crowd Tecnical Report
1 Sections
This technical report is divided in these sections:
- Client
- Explains the client part design and implementation.
- Server
- Explains the server-side design and implementation.
- Visual queries
- Explains the visual querie version of crowd.
2 About this Technical Report
This technical report is created using org-mode and Emacs. This allows us to export the same document into various formats, including HTML, ODT and (PDF, DVI, PS, etc).
Viewing org documents in Emacs follows a "only text" phylosophie and is different than programming. Table tab:keybindings list some useful key-bindings for reading and writing. Also, in the following subsections we present some snippets that can help the user.
Keys | Description |
---|---|
C-h b | Help: list key-bindings. |
C-h m | Help: Describe mode |
Tab | Opens and closes titles |
C-c C-x C-v | Toggle display inline images |
C-c C-x C-l | Toggle LaTeX fragment preview |
In some cases emojify-mode is used for personal comments and little images.
2.1 Emacs Lisp Snippets
These are snippets that create a more suitable environments for reading this Org files. We recommend using the packages helm, which-keys, a darker theme like "afternoon" and org-ref. This packages can be searched and installed by calling M-x packages-list-packages
.
All these snippets can be added in the ~/.emacs
file.
2.1.1 White Background in Inline Images
The following snippets creates a white background for inline images. The color can be "customized" using M-x customize-variable org-inline-image-background
.
;; Background color in inlines images (defcustom org-inline-image-background "white" "The color used as the default background for inline images. When nil, use the default face background." :group 'org :type '(choice color (const nil))) (defun org-display-inline-images--with-color-theme-background-color (args) "Specify background color of Org-mode inline image through modify `ARGS'." (let* ((file (car args)) (type (cadr args)) (data-p (caddr args)) (props (cdddr args))) ;; get this return result style from `create-image' (append (list file type data-p) (list :background org-inline-image-background) props))) (advice-add 'create-image :filter-args #'org-display-inline-images--with-color-theme-background-color)
2.1.2 Enable Org-ref
Sometimes Org-ref doesn't work properly if not loaded explicity. This creates issues when exporting to LaTeX and HTML. This line of code ensure that the library is loaded.
(require 'org-ref)
2.1.3 Enable LaTeX Source Block Execution
Org-mode won't execute LaTeX or any other language source block code by default. Then, if not enabled, all results cannot be exported nor displayed in the buffer.
This snippet enable R, Python, Prolog, Ruby and LaTeX languages for executing and retrieving its results. However Org-mode asks for confirmation when org-confirm-babel-evaluate
variable is true (t
).
;; Enable org-babel languages (setq org-confirm-babel-evaluate t) (org-babel-do-load-languages 'org-babel-load-languages '((emacs-lisp . t) (R . t) (python . t) (prolog . t) (ruby . t) (latex . t)) )
It is possible to avoid confirmation for specific languages. For example, the following snippet only evaluates ditaa source blocks without confirmation.
(defun my-org-confirm-babel-evaluate (lang body) (not (string= lang "ditaa"))) ; don't ask for ditaa (setq org-confirm-babel-evaluate 'my-org-confirm-babel-evaluate) (org-babel-do-load-languages 'org-babel-load-languages '((emacs-lisp . t) (ditaa . t) (R . t) (python . t) (prolog . t) (ruby . t) (latex . t)) )
More information is available at the Org-mode info, section "Code evaluation and security issues". If you're using org-mode, you can access directly the info through this link.
2.1.4 Enable Bootstrap for Exporting in a Responsive HTML
Using the ox-twbs package created by marsmining, Org-mode can export the content into an HTML page with bootstrap JS support.
The package can be installed by browsing with M-x package-list-package
or by following the instructions in its README.org file.
Downloads and more information are available at its repository at the following URL: https://github.com/marsmining/ox-twbs
2.2 Different Output Formats
This technical report can be downloaded in PDF format or readed in org-mode formatted text, plain text and HTML. These files can be obtained modifying the extension of the file in the URL by ".pdf", ".org", ".txt", ".html" respectively.
For example, suppose we want the client.org file in PDF, and you are reading it in your Web browser in the http://crowd.fi.uncoma.edu.ar/tech-report/client.html URL, if you visit the following URLs you'll find the other formats:
- http://crowd.fi.uncoma.edu.ar/tech-report/client.pdf URL for the PDF format.
- http://crowd.fi.uncoma.edu.ar/tech-report/client.org URL for the org-mode format.
- http://crowd.fi.uncoma.edu.ar/tech-report/client.txt URL for the plain text format.
3 About the Main crowd Web Page
3.1 TODO Main Page
3.2 TODO Wiki
3.3 TODO This Technical Report
3.4 Available Pre-Compiled Reasoners
On the "Reasoners" Wiki page, there's a list of available Reasoners already compiled and ready to use. This is needed for crowd installations, as for the new versions theese programs will not be packaged along the code, instead they will be downloaded through an installation script.
Refer to this Wiki page at http://crowd.fi.uncoma.edu.ar/wiki/doku.php/reasoners for information about the reasoners and their home page and authors.
4 About the Repositories
We use Bitbucket repositories for storing the code, collaborating development and managing our projects versioning through tools such as Git and Mercurial. Refer to their respective Web pages for more information:
- Bitbucket
- https://bitbucket.com
- Git
- https://git-scm.com/
- Mercurial
- http://mercurial-scm.org/
4.1 Repositories branches
These are the branches and their purposes at my personal repository. These name should be the same along repositories.
- sparqldl
- SPARQL-DL and Visual Queries implementation.
- uml-base
- UML only implementation with consistency check.
- verbalization
- UML verbalization by logic representation.
- metamodel
- Metamodel implementation with EER and UML. ORM will be added when
orm
branch is available and ready. - orm
- ORM implementation. Consisteny check and UML may not be available.
5 About the Development
We follow some conventions for developing. Here we explain the most important guidelines.
5.1 Test Oriented Development
The development of crowd follows a cycle that involves the creation of unit tests for two purposes: documenting the unit usage and ensuring that other unit's features works after modifications.
In this section we explain the cycle the developers should follow and how to run the tests if needed.
5.1.1 Explain the Test Oriented Development Cycle
The test development cycle we use is depicted in Figure fig:test-cycle and consist in the following steps:
- We propose a new feature idea to be included in crowd.
- First, we write tests about the feature we want to implement. The tests represents the expected results and usage of the module or modules should have.
- We implement the feature trying to follow the tests.
- Then, we run the units tests for that feature. If every tests are green, we ignore the next step.
- If some tests don't pass, a fix is needed in the code recently implemented. It can happen that the tests we designed needs fixing too, because the goal or usage of the implemented feature changed.
- Run other tests ensuring that nothing else in the system has been broken. If all tests are green, we ignore the next step.
- Fix the broken code. This happens when the module needs to modify or add code in already developed modules. If that happens, tests may also needs to be fixed.
For more information about Test Driven Development (TDD) consult TDD2012.