crowd Tecnical Report

Sitemap | Index

1 Sections

This technical report is divided in these sections:

Explains the client part design and implementation.
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.

Table 1: Key-bindings for Org-mode in Emacs. tab:keybindings
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)

(advice-add 'create-image :filter-args

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)

 '((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)

 '((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:

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:


4.1 Repositories branches

These are the branches and their purposes at my personal repository. These name should be the same along repositories.

SPARQL-DL and Visual Queries implementation.
UML only implementation with consistency check.
UML verbalization by logic representation.
Metamodel implementation with EER and UML. ORM will be added when orm branch is available and ready.
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:

  1. We propose a new feature idea to be included in crowd.
  2. 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.
  3. We implement the feature trying to follow the tests.
  4. Then, we run the units tests for that feature. If every tests are green, we ignore the next step.
  5. 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.
  6. Run other tests ensuring that nothing else in the system has been broken. If all tests are green, we ignore the next step.
  7. 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.

6 Open Issues

7 Conclusions and Future Work

8 References