crowd Tecnical Report

1. About this Technical Report
- 1.1. Emacs Lisp Snippets
2. Repositories branches
3. Test Oriented Development
- 3.1. TODO Explain the Test Oriented Development Cycle
4. Open Issues
5. Conclusions and Future Work

Sections:

1. 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

1.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.

1.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)

1.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)

1.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. 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.

3. 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.

3.1. TODO Explain the Test Oriented Development Cycle

Nice figure about the cycle here.

Write tests about the feature we want to implement.
Implement the feature.
Run the unit test for that feature.
Fix tests if other unit's features has been updated or has been changed.
Run other tests for ensuring that nothing has broken.