ADA is a tool that provides support for “Agile and Distributed Authoring”. Authors usually use a combination of tools to produce documents. The actual variety of documents makes more appropriate to refer to this items as resources. A resource may be a regular text document, but it may also be a screen capture, video clip, audio clip, picture, etc. ADA is conceived to manipulate resources in this context.

The challenge appears when a large set of resources with a complex structure is created by a large number of authors working in a distributed environment.

The first problem is the variety of tools used by the authors. ADA facilitates the post-processing by automatically producing preliminary versions of the created resources. The following figure illustrates a generic authoring environment and the support provided by ADA.

Once created, the exported resources can be sent to a location where they are automatically combined to produce the final resource. The following figure illustrates a scenario combining these two aspects.

ADA offers support in two steps of this procedure.

The main element for ADA in the author working directory is the rule file. This file has the name Properties.txt (although it can be changed) and specifies which are the resource files and how they need to be processed to obtain the final resources. Each working directory needs a file with the rules applying to the files contained in it.

ADA is not a text editor, nor a graphic editor, nor an integrated creative environment. The author may use tools to create the resources, and ADA is used to automatically combine them into a global creation process.

To use an analogy, ADA offers a very efficient courier service that, if you comply with certain requirements when creating resources, it takes them very quickly to the assembling plant, combines them with other resources contributed by other authors and automatically creates a final resource.

ADA is oriented toward reducing the creation/modification cycle of a set of resources with a non-trivial organization. In the information era, the creation process is changing radically. Authors are no longer required to use a concrete tool, but instead, certain formats are used to easily publish content. But what really takes a multi-user distributed authoring scenario to a new dimension is a simple modification cycle. Think Wikipedia, its distributed authoring paradigm has consolidated beyond any doubt, but in order for those authors to contribute effectively, resources are extremely easy to modify.

A typical situation when a number of authors contribute toward a common resource is illustrated in the following figure. There is usually an entity that absorbs the complexity of providing a homogeneous view of the material usually through an expensive and time consuming production stage. This production requires then an additional step to bring all the material to the final web publishing platform.

The following picture illustrates the change in methodology that can be achieved with the help of ADA. By providing a fast two-way information channel between creation and production, the management of a set of resources can be truly improved. ADA provides the rules that automatically connect the source documents with the final published resources such that changes can be performed at a very low turnaround cost.

But aside from the turnaround time for changes, resources tend to be built hierarchically from the multiple sources. The internal organization of a resource can be often replicated in the process in which it is built. For example, to create the electronic version of a book, there is certain amount of work that can be done for each chapter individually accompanied by certain inter-chapter processing. The rules defined in ADA are prepared to be applied hierarchically at different points of the overall production procedure. The following picture illustrates a hypothetical scenario in which a resource is built by combining resources from four authors in three gradual stages.

ADA is prepared to supply rules to be used with several tools, but these tools need to be installed in the system. If they are not, the rules are never applied. However, to obtain the minimum functionality, ADA needs at least three applications to be installed (all of them Open Source, by the way.)

Aside from these three tools, ADA allows to process certain file types if some additional programs are installed. For example, translating figures from SVG to PNG can be done using Inkscape but it needs to be properly installed and available for execution.

Java is a free tool developed by Sun Microsystems and the instructions on how to install it in windows provided with the package. You may download the software from the official Free Java Download page. Once the download finishes, execute the installer that asks a few simple questions and installs Java in your system.

Once Java has been installed, the next step is to download the Cygwin tool, a Linux-like environment for Windows. Once downloaded, the initial page of the installer is shown in the following figure.

After starting the set-up program, you need to specify several parameters to establish a connection with a server. Keep advancing on the installation steps until the screen to select the packages like the one in the following figure is shown.

Click in the button with name View that appears above the package list until the word “Full” appears to its left. At that point, all packages suitable to be installed are shown alphabetically ordered. From the list, you need to select at least the following packages.

ADA is capable of using additional tools, but they are not essential for the installation. The set-up program takes a few minutes to download all the required packages through a reasonably fast net connection. Keep in mind that this installer application remains installed in your computer and therefore can be executed at any other time to add/remove applications to the Cygwin environment.

After all the required packages are installed, finish the execution of the set-up program and start a Cygwin shell. This is done by clicking on the icon that the set-up program has left on your desktop or browsing through the program menu and selecting the Cygwin executable. Once started, a window like the one shown in the following figure appears on the screen.

This window is a typical Linux command interpreter ready to process your commands. It is just a different way to give orders to your computer. Instead of clicking in different icons and menus, Cygwin allows you to type the orders at the prompt of this interpreter. The first check is to make sure the Java Run-time Environment (or JRE) is properly installed. Go ahead and type the command:

$ which java

If the answer is a single path to a file with name java similar to

/cygdrive/c/WINDOWS/system32/java

then the JRE is properly installed. If the message says something similar to “which: no java in (/usr/local/bin:/usr/bin:/....)” then you need to review your Java installation, because no JRE was found.

The next tool required by ADA is Ant, a Java based build tool. Ant is a multi-platform tool, and the installation simply amounts to downloading a zip file, deploying its files in a directory, and declaring a couple of environment variables.

When deploying Ant in a directory there are two choices: install Ant as a regular windows application, or install Ant inside Cygwin (remember that Cygwin is a simple Linux-like environment within your Windows system). The two choices are very similar because it only requires a JRE to be available. The important step is to set the environment variables ANT_HOME to point to the directory where Ant is installed and PATH to include the bin directory inside that directory.

To add a new variable or modify a current variable in the execution environment in Windows you need to first select the “Control Panel”, then select the “System” link. A new window opens with several panes. Select the pane with name “Advanced” and then click on the button with name “Environment Variables”. It is recommended to insert these definitions as part of the System Variables.

A new variable with name ANT_HOME (all uppercase) has to be declared and its value must be the directory where the Ant files where deployed from the zip archive. Additionally, the PATH variable (which is already defined) needs to be modified by adding the path to the bin directory within the Ant installation directory. That is, append to the string already in the variable a semicolon and then the path to the bin directory within Ant (something similar to C:\Applications\Ant\bin.)

Once the installation is finished, you may check the availability of the tool by opening a new Cygwin shell. Type the command

$ which ant

If the answer is a single path to a file with name ant such as

/cygdrive/c/Program Files/apache-ant-1.7.0/bin/ant

Ant is properly installed. If the message says “which: no ant in (/usr/local/bin:/usr/bin:/....)”, Ant is not being found and you need to review your installation steps.

Open a Cygwin shell and go to the directory where you want ADA installed (a directory with name ADA will be created. The computer needs to be connected to the net. Execute the command:

$ git clone http://flautin.it.uc3m.es/abel/ADA

A list of messages appear on the screen. After a while (depending on the speed of your net connection), the command terminates and a new directory with name ADA has been created containing all the required files.

In order to make ADA available, the PATH environment variable needs to be modified by adding the path to the bin directory. You may follow the same procedure described in the Ant installation.

Once the environment variable PATH has been modified to include the bin directory within ADA, open a brand new Cygwin shell and type the following command

$ which adado

As in the case of the Ant installation, if the answer is a single path to the adado file similar to

/home/.../.../ADA/bin/adado

ADA is properly installed. If the message says “which: no adado in (/usr/local/bin:/usr/bin:/....)”, ADA is not available for execution and you need to review your installation.

The final step to make sure that the commands provided by ADA are available is to Which resources are processed by ADA.

The symptoms for this problem is an unusually large amount of time for the toolkit to process a Docbook file. The process eventually finishes, but it takes for ever (in the order of minutes to process one or two files).

The stylesheets in ADA import a set of default stylesheets to process most of the Docbook constructs. The location of these styleheets may vary from machine to machine. The way to solve this problem is using XML Catalogs. A catalog is a file specific for a single machine that specifies the location where certain files are installed. If this catalog is not properly deployed, xsltproc (the XSLT processor used by ADA) obtaines them all from the web. The number of stylesheets is high and therefore, processing time goes through the roof.

Te solution for this problem is to make sure the packages specified in How to install Cygwin are properly installed.

ADA is distributed using the tool git which keeps track of the files you already have and the changes that need to be applied to upgrade to the latest version. The upgrade process requires simply to open a shell window, go to the directory where ADA is installed and execute the command:

$ git pull

The command will inform in some fairly cryptic way of the changes that are taking place. In principle, if the source files have not been modified, the change will go smoothly. If you have some personal modifications in the source files, you need first to tell git to store those changes. You need to execute the command:

$ git commit -a -m "Your message here"

Try again to execute git pull. This time, the update process should go smoothly. There could be some conflicts when git tries to merge these changes with the ones you introduced. If such situation happens, it is called a “merge conflict” and it needs to be solved manually by the user. If you touched the source code of ADA, then we assume that you know how to solve merge conflicts.

ADA uses primarily Ant, and it is distributed using git. The bare minimum required packages are: Ant (including the ant-optional package), a Java run-time environment (JRE) and git.

Additionally to these packages, the following list are highly recommended:

But to fully exploit ADA functionality, there are additional tools that need to be installed. See Which resources are processed by ADA for more details.

ADA is distributed using the git version control tool. Open a terminal and type the command:

          $ git clone http://flautin.it.uc3m.es/abel/ADA
        

A new directory with name ADA will be created. In order to make ADA available, you need to include the path to its bin directory as part of your PATH environment variable.

The symptoms for this problem is an unusually large amount of time for the toolkit to process a Docbook file. The process eventually finishes, but it takes for ever (in the order of minutes to process one or two files).

The stylesheets in ADA import a set of default stylesheets to process most of the Docbook constructs. The location of these styleheets may vary from machine to machine. The way to solve this problem is using XML Catalogs. A catalog is a file specific for a single machine that specifies the location where certain files are installed. If this catalog is not properly deployed, xsltproc (the XSLT processor used by ADA) obtaines them all from the web. The number of stylesheets is high and therefore, processing time goes through the roof.

Te solution for this problem is to make sure the packages specified in How to install Cygwin are properly installed.

ADA is distributed using the tool git which keeps track of the files you already have and the changes that need to be applied to upgrade to the latest version. The upgrade process requires simply to open a shell window, go to the directory where ADA is installed and execute the command:

$ git pull

The command will inform in some fairly cryptic way of the changes that are taking place. In principle, if the source files have not been modified, the change will go smoothly. If you have some personal modifications in the source files, you need first to tell git to store those changes. You need to execute the command:

$ git commit -a -m "Your message here"

Try again to execute git pull. This time, the update process should go smoothly. There could be some conflicts when git tries to merge these changes with the ones you introduced. If such situation happens, it is called a “merge conflict” and it needs to be solved manually by the user. If you touched the source code of ADA, then we assume that you know how to solve merge conflicts.

ADA is a building tool, and to “build” a resource it needs some applications to be properly installed in your computer. To see what tools are managed by ADA and available, open a shell (a regular shell in Linux or a Cygwin shell in Windows) and type the command:

$ adacheck

ADA prints the value of some relevant variables followed by the list of the tools that are available. For example:

     [echo] 
     [echo] Tool               | Installed |  Missing
     [echo] -------------------+-----------+-----------------------------
     [echo] Xfig               |     *     |
     [echo] -------------------+-----------+-----------------------------
     [echo] Inkscape           |     *     |
     [echo] -------------------+-----------+-----------------------------
     [echo] Gimp               |     *     |
     [echo] -------------------+-----------+-----------------------------
     [echo] Convert            |     *     |
     [echo] -------------------+-----------+-----------------------------
     [echo] Xsltproc           |     *     |
     [echo] -------------------+-----------+-----------------------------
     [echo] Latex              |     *     |
     [echo] -------------------+-----------+-----------------------------
     [echo] Dvips              |     *     |
     [echo] -------------------+-----------+-----------------------------
     [echo] Ps2pdf             |     *     |
     [echo] -------------------+-----------+-----------------------------
     [echo] Pdflatex           |     *     |
     [echo] -------------------+-----------+-----------------------------
     [echo] Dblatex            |     *     |
     [echo] -------------------+-----------+-----------------------------
     [echo]                    | * Only If |
     [echo] ppt2pdf            |OpenOffice |
     [echo]                    |2.4 or latr|
     [echo] -------------------+-----------+-----------------------------
     [echo] Pdfnup             |     *     |
     [echo] -------------------+-----------+-----------------------------

BUILD SUCCESSFUL
Total time: 1 second

This listing shows the tools that ADA is capable of using. If you don't have all of them available, don't worry, ADA is capable of working with a subset of these tools (although your functionality will be reduced).

ADA needs from the user the set of files to apply a set of pre-defined production rules. This information should all be contained in a regular text file with name Properties.txt in the same directory where your files are located. The format of this file is very simple: any line starting with the symbol “#” or empty is ignored. The rest of lines should have the structure name=value. The names that can be used are pre-defined by ADA. The following sections of this document describe the available variables and explain the values that can be assigned.

The following figure illustrates at a certain level of abstraction how ADA uses this file to process your files and produce the resources.

An example of a Properties.txt file content is shown in the following figure:

# Definition to process the SVG files with inkscape
inkscape.files=*.svg

# Definition of the XML files to be processed by Xsltproc
xsltproc.files=index.xml

# Files to copy to another location when requested
export.files=*.png

The first definition simply states that all files with the *.svg extension should be processed by inkscape. The default behavior of this rule is to produce a file in PNG format. The second variable assignment states that the index.xml file should be processed with the xsltproc rule, which means that a default stylesheet is applied. Finally, the last assignment states that if this directory is required to “produce” resources from a different location, only the files with extension *.png are to be copied to such remote location.

All rules present in ADA have default values assigned with the most common behavior. This means that in most cases, by including a small set of definitions in the Properties.txt file, ADA will perform the appropriate operations.

Once the Properties.txt file with the required assignments has been created, to apply these rules simply open a shell (regular shell in Unix or a Cygwin shell in Windows) and, in the correct directory type the following command:

$ adado

A few lines will then appear on the screen. ADA is writing the rules that is applying as well as the directories in which the processing is taking place. For example:

     [echo] BEGIN [path to your current dir]
     [echo] inkscape.processing         RUN
     [echo] xsltproc.processing.nopre   RUN
     [echo] END [path to your current dir]

BUILD SUCCESSFUL
Total time: 4 seconds

The previous execution shows the result of applying the Properties.txt file shown in the question on Which resources are processed by ADA. Two rules are executed within the current directory.

If an error appears while ADA executes the rules, the information about the anomaly is stored in the file build.out and the first lines are shown on the screen:

     [echo] BEGIN /path to current dir]/SimpleDoc
     [echo] inkscape.processing         RUN
     [echo] xsltproc.processing.nopre   RUN

---------------------------------- ADA ERROR ----------------------------------

-- Full error information in file:
   ./build.out

                            ==== Error excerpt ====
/[path to a file]/index.xml:45: parser error : expected '>'

^
unable to parse /[path to a file]/index.xml
                            =======================

-------------------------------------------------------------------------------

The complete collection of variables that can be included in a Properties.txt file are contained in the sample of Properties.txt file. Remember, however, that only those variables that include a definition different from the default need to be included in that file.

Yes. ADA allows two regular expression patterns.

For example, if you have several figures and each of them with a version with a suffix _en.svg and a suffix _es.svg), you may select all of them with the expression *_e?.xml. These patterns may be used anywhere file lists are required unless otherwise noted. Regular expressions are not allowed when specifying sets of files to delete for security reasons.

If you want this type of rule to be applied, not only to all the files matching this pattern in this directory, but to all directories, see How to make a variable declaration valid for all projects.

Yes. In fact, you may include as many variable definitions in the command line as you see fit. They need to be provided with the following format:

-Dpropertyname=propertyvalue

If tye property value contains spaces, then the parameter needs to be given with the following syntax:

'-Dpropertyname="propertyvalue with spaces"'

Any argument written beyond adado is directly passed to an invocation of Ant (the rule processing engine used by ADA). See the Ant manual for a detailed discussion of the available options.

Yes. Although there is no formal definition of “project” within ADA, it is very common to have files or definitions that apply to all files included in a set of directories. The way this is solved in ADA is by detecting a special directory in the hierarchy called the course home directory. The idea is for users to have multiple of these directories one for each large project of shared resources.

ADA tries to provide the least invasive solution, so rather than requiring an extra definition with the location of this course home directory, it detects it automatically by searching for the file with name AdaCourseParams.xml in up to ten levels of directories above the current one. If a file with this name is found, the variable ada.course.home is then assinged the directory where the file is located.

For example, let us assume that your project contains some stylesheet to be used in multiple locations. You may give this file the name AdaCourseParams.xml and place it at the highest level in your hierarchy of directories. From any directory you may refer to such file in the Properties.txt file as shown in the following example.

mergestyles.master.style=${ada.course.home}AdaCourseParams.xml
export.dst.dir=${ada.course.home}scratch

The variable ada.course.home is used to access the common stylesheet as well as a prefix to a directory where to export resources.

Variable ada.course.home is one of the global variables that ADA defines. The entire list is:

If what you want is not a variable definition valid for an entire project, but a variable for all the projects, check How to make a variable declaration valid for all projects.

Yes. You may have this type of assignments in two additional files that are read by ADA:

The order in which these files are processed is: Ada.properties, Properties.txt, and .ant.properties. If a variable is defined in more than one file, only the first definition is taken into account. As a consequence, you may have general definitions in the .ant.properties of your home directory that may be overwritten by definitions in the Properties.txt file in the local directory, and these can be overwritten by the Ada.properties file in the project home. The following figure shows the effect of reading these files in this order:

The value of Var1 is taken from the Ada.properties file, Var2 is taken from the Properties.txt file, and Var3 is taken from the .ant.properties file in the user home directory.

The rule to apply a stylesheel to a XML file requires only to define the source file. ADA has a default stylesheet that is applied to a XML file if none is defined and is based in Docbook (see How to translate Docbook to HTML for more details).

The following variables can be defined to apply a XSL stylesheet to one or several XML files:

The variables that need to be defined to activate this rule are either xsltproc.files or xsltproc.multilingual.files. The variable mergestyles.master.style is used primarily to merge an external stylesheet with the given one and apply both of them (see How to use a slightly modified stylesheet).

For example, let us consider a simple XML file that needs to be processed by the stylesheet Dump.xsl (included in the styles directory in ADA). The output of this processing should be left in a files with the same name but with the suffix _Cump.xml. The variable definitions required in the Properties.txt file are:

# Definition of the XML files to be processed by Xsltproc
xsltproc.files=index.xml
xsltproc.style.file=${ada.home}/ADA_Styles/Dump.xsl
xsltproc.output.format=_Dump.xml

Note the use of the global variable ada.home to refer to a style included with ADA (see How to re-use definitions across an entire project for more details).

Open your favorite XML editor, create a Docbook file and save it. If you want to apply the Docbook XSL Stylesheet to translate the file to HTML you just need to define the variable xsltproc.files, because the default style applied by this rule translates the file to HTML.

For example, consider the Docbook document with name TectBookSelect.xml. To obtain the corresponding HTML file, the content of the Properties.txt is:

xsltproc.files=TextBookSelect.xml

Although in theory there is a workflow to translate Dobook files to PDF using the FO format, the approach used in ADA relies on the dblatex program. This tool takes a Docbook file, translates it to LaTeX and generates a PDF file from it. The rule needs this executable to be properly installed in the system. The variables to use in the Properties.txt file are:

For example, given a Docbook file, a PDF file is obtained with the following definitions in the Properties.txt file:

dblatex.files=TextBookSelect.xml
dblatex.compliant.mode=false

ADA offers this possibility by taking all your personal definitions in an extra XML file and merging it with a conventional style. This file is defined in the variable mergestyles.master.style.

Suppose you want to use the style file in ${ada.home}/ADA_Styles/HeadTail.xsl to generate an HTML page. To reuse those definitions and override some of them, create a local stylesheet (for example, a file with name MyPersonalValues.xml) containing only the definitions you want to override. Assign in Properties.txt the value MyPersonalValues.xml to the variable mergestyles.master.style and use the style sheet ${ada.home}/ADA_Styles/HeadTail.xsl by assigning its value to xsltproc.style.file as shown in the following example:

mergestyles.master.style=MyPersonalValues.xml

xsltproc.style.file=${ada.home}/ADA_Styles/HeadTail.xsl
xsltproc.files=index.xml

The previous definitions instruct ADA to apply to the file index.xml the style sheet resulting from combining ${ada.home}/ADA_Styles/HeadTail.xsl with the file MyPersonalValues.xml containing your modifications.

The resulting applied style sheet is a file left in the current directory with name MyPersonalValues_HeadTail.xsl.

Ada keeps some definitions that are used in multiple locations in the built-in style sheets. The purpose of these definitions are to be overwritten by definitions that apply to each project in particular (see How to use a slightly modified stylesheet for details.

The recommendation is to include these and other style parameters with the appropriate values in a common file, name it AdaCourseParams.xml and place it at the top of your project to notify ADA the location of the ada.course.home (see How to re-use definitions across an entire project). The stylesheets include the default values of these parameters, therefore, only those with values different from the default need to be included in the file.

The stylesheel with name HeadTail.xsl allows the customazation of a HTML document by defining the following parameters:

Through the definition of some or all of these variables, the obtained HTML document has the structure shown in the following figure:

ADA allows to include a set of links at the header of a document. There are two ways to define these links:

For example, by creating a simple style sheet including HeaderLinks.xsl and a Docbook file with the element <note condition="AdminInfo">, and the Properties.txt file with the proper definitions, the resulting document has in its header the given link.

Open Xfig and create a figure. Save it in Xfig format. Suppose that the figure needs to be translated to PNG format. Open the file Properties.txt (if not created, see How to define which files to process) and set the following variables to suit your needs:

For example. If the figures with names modules.fig and structure.fig are stored in the current directory and versions in PNG format are needed, the following assignment is required in the file Properties.txt.

xfig.files=module.fig structure.fig

Execute ADA to obtain the processed figures (see How to execute ADA).

Open Inkscape and create a figure. Save it in SVG format. Suppose that this figure needs to be translated to PNG format. Open the file Properties.txt (if not created, see How to define which files to process) and set the approriate value for some of the following variables:

For example. If the figures with names chart.svg and kanjidic.svg are stored in the current directory and versions in png format are needed, the following assignment is required in the file Properties.txt.

inkscape.files=chart.svg kanjidic.svg

With such values defined, execute ADA to obtain the processed figures (see How to execute ADA).

Vector graphics (like SVG, Postscript, PDF, etc.) are usually preferred for graphics drawn with computer programs, because they maintain quality when they have to be scaled. Fonts and lines are smooth even when they are scaled to high resolutions, e.g. for printing.

However, the only image formats that are guaranteed to be shown on any browser are bitmap-based (JPEG, GIF and PNG). HTML documents should include only images in those formats to maintain compatibility.

Because sometimes it is interesting to generate both an HTML and a PDF version of a document, produced from the same Docbook sources, Docbook allows the author to select different image formats for HTML and PDF. For computer-drawn illustrations, the PNG format is preferred for HTML documents, whereas PDF format is preferred for PDF output (because Ada uses internally dblatex and pdflatex for producing PDF documents from Docbook sources).

The following example shows how an author can specify alternative image formats:

<mediaobject>
  <imageobject role="html">
    <imagedata fileref="drawing.png" format="PNG"/>
  </imageobject>
  <imageobject role="dblatex">
    <imagedata fileref="drawing.pdf" format="PDF"/>
  </imageobject>
  <textobject>
    <phrase>Example drawing</phrase>
  </textobject>
</mediaobject>

If the drawing is in SVG format, both the PNG and PDF versions can be obtained with the Inkscape rule (see How to process a figure with Inkscape). The following lines in Properties.txt do that:

inkscape.files=*.svg
inkscape.output.format= pdf,png

Back to Top of the Section.

Embedding a flash video in an HTML page can be done with flash players that are downloaded by the browser and offer functionality such as a start, stop and pause buttons, volume control, etc. ADA uses the player available in www.jeroenwijering.com.

From the point of view of the author, these details should be hidden, and worry only about the basic data such as the video file, height and width of the screen and that's it.

The stylesheets included in ADA to process Docbook allow you to include a video player embedded in your page simply by providing a special markup using the <para> element. The following example shows the structure of this element:

<para id="video_1" condition="ada.flv.player">
  <phrase condition="width">320</phrase>
  <phrase condition="height">200</phrase>
  <phrase condition="file">player.flv</phrase>
  <phrase condition="image">playerthumb.jpg</phrase>
  <phrase condition="showstop">true</phrase>
</para>

In order to maintain the Docbook file valid, the parameters are passed as nested <code> elements with the attribute condition equal to the name of the parameter. The available names are:

Embedding a Shockwave file in an HTML page can be done by including a special paragraph in Docbook with the values for certain parameters. A special stylesheet in ADA will then produce the proper element in HTML to view the Shockwave file. The idea is similar to How to include Flash Video in Docbook but requires less information.

The special markup in docbook to include a a showkwave is shown in the following example:

<para condition="ada.swf.player">
  <phrase condition="width">425</phrase>
  <phrase condition="height">355</phrase>
  <phrase condition="file">File.swf</phrase>
  Additonal text and <ulink url="link.html">links</ulink> you might include.
</para>

In order to maintain the Docbook file valid, the parameters are passed as nested <phrase> elements with the attribute condition equal to the name of the parameter. The available names are:

The Docbook tool chain offers a powerful functionality called profiling or conditional text (search for “Docbook profiling” for more detailed information). Each Docbook element may include a fixed set of attributes that are used to select or ignore portions of a document. The exact definition of profiling with a generic attribute attr is:

The list of attributes which can be used for profiling is fixed by the Docbook stylesheets (there are actually more than 10). One of these attributes is lang and therefore, it may be used to handle documents written in more than one langugage. Each element containing text in a language is marked with the appropritate value of the lang attribute. If an element is common to both languages, it should contain no lang attribute. A possible strategy is then to label each paragraph with the attribute lang and the appropriate language. Currently, the supported languages are English (lang attribute with value “en”) and Spanish (lang attribute with value “es”).

For each language supported by ADA, the produced file names are created by appending a suffix with an underscore followed by the abbreviated language name in lower case (i.e. “_en” for the English version and “_es” for the Spanish version.

The placement of the lang attribute can be chosen as to minimize the number of duplicated elements and maintain the document valid. The following example shows a snippet of bilingual (English/Spanish) Docbook with a figure that needs also to be distinguished.

    <para lang="es">
    La estructura de esta tabla se puede ver en la siguiente figura:</para>

  <para lang="en">
    The structure of this table can be seen in the following figure:</para>

  <informalfigure id="reversetable_fig_pagetable">
    <mediaobject>
      <imageobject lang="es">
        <imagedata align="center" fileref="tablestruct_es.png" format="PNG" />
      </imageobject>
      <imageobject lang="en">
        <imagedata align="center" fileref="tablestruct_en.png" format="PNG" />
      </imageobject>
    </mediaobject>
  </informalfigure>

Note that the location of the lang attribute is as deep in the document structure as possible to increase the number of common elements and at the same time maintaining the validity of the document. More precisely, checking the Docbook manual, a mediaobject element accepts multiple imageobject elements inside. But this one does not accept multiple imagedata elements. As a conclusion, the multiple language versions can be easily accomodated by including an imagobject element per language.

ADA contains rules to do process a Docbook file containing elements in various languages (currently English and Spanish), and generate two separated files.

The variable xsltproc.multilingual.files of the rule to apply a XSL stylesheet must contain the file names to be process in multilingual mode (see How to apply a XSL stylesheet for more details).

For example, the following Docbook file uses the lang attribute:

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">

<section>
  <title>
    <phrase lang="es">Título de este documento</phrase>
    <phrase lang="en">Title for this document</phrase>
  </title>

  <para lang="es">El título de este documento debe incluir dos elementos
  <code>phrase</code> uno con cada valor del atributo <code>lang</code> porque
  un documento no admite dos títulos. La multiplicidad de lenguajes, por tanto,
  se acomoda dentro de <code>title</code> mediante el uso del elemento
  <code>phrase</code> que no tiene efecto en como se visualiza el texto.</para>

  <para lang="en">The document title must include two <code>phrase</code>
  elements with the title in each language and the appropriate value of the
  <code>lang</code> attribute because a Docbook section does not admit two
  <code>title</code> elements. Multilingual elements, then needs to be
  accomodated within <code>title</code> with the use of the <code>phrase</code>
  element which has no effect on how the document is rendered.</para>

  <para lang="es">A continuación se muestra una figura en versión multilingüe:</para>

  <para lang="en">The following figure has also a multilingual structure:</para>

  <informalfigure id="">
    <mediaobject>
      <imageobject lang="es">
	<imagedata align="center" fileref="tablestruct_es.png" format="PNG" />
      </imageobject>
      <imageobject lang="en">
	<imagedata align="center" fileref="tablestruct_en.png" format="PNG" />
      </imageobject>
    </mediaobject>
  </informalfigure>

  <para lang="es">La figura se incluye mediante el siguiente Docbook:</para>
  <para lang="en">The figure is included with the following Docbook:</para>

  <programlisting><![CDATA[<informalfigure id="">
  <mediaobject>
    <imageobject lang="es">
	<imagedata align="center" fileref="tablestruct_es.png" format="PNG" />
    </imageobject>
    <imageobject lang="en">
	<imagedata align="center" fileref="tablestruct_en.png" format="PNG" />
    </imageobject>
  </mediaobject>
</informalfigure>]]></programlisting>
</section>

By including the following definitions in the Properties.txt file:

inkscape.files=*.svg

xsltproc.multilingual.files=index.xml

Two files index_en.html and index_es.html are produced.

The rules used by ADA to create resources are prepared to be invoked to clear the produced files. This step is useful to start from scratch in the production of resources, or simply to reduce the content of a directory only to the source files.

Each rule used in ADA to produce a resource has its equivalent to remove it. Thus, with no additional information in the Properties.txt file, by simply executing the command adado clean, all the production rules are invoked again, although this time to remove the produced resources.

ADA performs this cleaning procedure by “deducing” the file names of the produced resources through the given definitions. If you plan to change these definitions, the recommended procedure is first to “clean” the directory, change the file names and then apply again the rules. If the names of the produced files are changed and there are some of these old files in the directory, the execution of the cleaning procedure with the new properties will not remove them, the author will have to do it by hand.

Although ADA knows exactly the files that creates, there are some special cases in which the cleaning rule does not remove everything that was created. The exception are the empty directories. If a production rule creates new files in a directory, and eventually the directory itself, when cleaning, the rule will only remove the files in that directory, but not the directory. The consequence of this policy is that there might be some remaining empty directories after cleaning all the content produced by ADA.

To solve this issue, ADA offers one additional variable to be used in the Properties.txt file and is described, along with the rest of variables available, in the following table:

The variable clean.files is used to specify those files or directories that are not properly removed by the implicit cleaning rules. Due to the danger of inadvertently deleting important files, this variable does not expand characters such as “*” or “?”. If you want to use it to delete multiple files that are not removed by the regular cleaning rules, you need to write all of their complete file names in the variable.

ADA consider the following scenarios to copy files from one location to another.

ADA allows to specify the source directory and a collection of files and copy them to a destination directory. The variables to include in the Properties.txt to control this procedure are:

For example, let us assume that you need the auxiliary file styles.css from the directory above the one you are currently working. The following definitions in the Properties.txt are required:

copyfiles.src.dir=..
copyfiles.files=style.css

This rule is executed at the very begining of the directory processing and therefore is specially suited to manipulate files that are always present. If you need to copy files from/to a location that are the result of applying a production rule, then you need to use either the Export (copy files that have been produced, see How to declare which resources are exported) or the Subrecursive (produce files before the local production, see How to process other directories before the current one) rules.

Yes. And this is one of the key features that ADA uses to allow hierarchical resource building. The generic scenario considered is such that to produce a set of resources, some other resources need to be created in different locations and exported to obtain the final product.

Let us assume that all the remote directories contain the Properties.txt file in which the export variables containing the list of files to export have been defined (see How to declare which resources are exported for the details). Two scenarios are considered by this functionality depending on the location where to export the resource is decided.

ADA allows the definition of two sets of directories each of them processed in each of the scenarios previously described. The following variables control the execution of the production process in a set of directories:

The values stored in these variables have a special effect when combined with the variables used for exporting resources in the remote repository (see How to declare which resources are exported.) The following figure shows the possible scenarios when combining the definitions of the destination where the files are copied:

The following figure shows the effect of the two types of subrecursive processing with and without a destination for the exported resources.

When creating resources in a directory, typically, only a subset of files are supposed to be used in the outside. These files are what we call the exported resources. The variables inside the Properties.txt used to capture this functionality are:

There are two typical scenarios when it comes to using these variables.

This functionality is considered in ADA and provided through a combination of multiple mechanisms. The presence or not of a set of resources in the final version of a site is achieved by either executing or not the exporting rules (see How to declare which resources are exported for the details). The following variables are provided to create a condition such that if satisfied, resource export is executed, but if not satisfied, no resource is exported:

Given these variables, the export rule is executed if all the following conditions are satisfied:

Clear uh? The condition is so complicated because it combines several control mechanisms. The most common situation is to use only one of them. The condition is easily understood if broken into the following possible scenarios of use (in increasing level of complexity):

ADA allows you use more than one of these conditions together. The export is actually execute if all of them are satisfied.

ADA provides a rule to specify a set of LaTeX files to be processed. The variables to define in the Properties.tex file are:

For example, if the source file is a LaTeX file, the required definitions in the Properties.txt file are:

latex.files=input.tex

Note that the rule does not execute LaTeX multiple times to remove potentially undefined references. A more complex rule is required for that task (and it has not been developed yet).

ADA provides a rule such that given a set of *.dvi files, it translates them to Postscript. The variables used in the Properties.txt file are:

For example, if in a directory we want to process a LaTeX file to obtain a DVI file, and then translate this last file to Postscript, the Properties.txt file should include the following definitions:

latex.files=input.tex

dvips.files=*.dvi

Yet to be written.

ADA provides a rule that given a set of PDF files produces n-up files, where “n” is a parameter. The availability of this rule depends on the executable pdfnup being properly installed in the system. The set of variables to include in the Properties.txt file are:

For example, to produce a 2-up version of a a PDF file, the required definitions in the Properties.txt file are:

pdfnup.files=Document.pdf
pdfnup.nup.option=2x1

Note that the PDF file to process may be produced by another ADA rule.

WARNING: This functionality is still in Beta. ADA has a rule to invoke OpenOffice directly and produce a PDF file from either a PowerPoint or a Word file. The functionality relies on a specific macro being available in a properly installed OpenOffice instance. The variables to control this rule are:

Note that this rule does not allow to control where the newly produced PDF are stored. It is assumed that the same directory of the source file is considered.

ADA includes a rule to translate a set of given Postscript files to PDF. The variables to include in the Properties.txt file are:

For example, given a PostScript file, the content of the Properties.txt file should include the definitions:

ps2pdf.files=Document.ps

Note that the rule can only be applied if the proper translation tool is installed in the system.

A Version Control System (VCS) is a tool that allows the manipulation of different versions of information units (typically files) by multiple users.

Files change over time, and current file systems store only the last version. Version control systems, on the other hand store (almost) all the different versions that files have over time. The location where these versions are stored is commonly known as a repository. But on top of storing versions, these tools also offer multiple operations to manipulate them. The two most common operations amount to send a new version of the files to the repository and get the latest version of the repository.

But when a set of users is sharing files, version management may become specially complicated. What happens if two users have the same file and both modify it? Who has the latest version? How is this situation managed? Actual VCS tools have very sophisticated techniques to solve these situations and offer users a comfortable environment to manipulate complicated multiple versions of large sets of files.

As with almost any application, there are multiple VCS, both open source and commercial. ADA is itself managed using GIT, an open source VCS, and the authoring environment proposed relies also in the use of the same tool. The problem of version control is orthogonal to authoring. In other words, any distributed authoring environment probably has some degree of file sharing and version management. If you solve this problem with git or any other tool is independent of the problem of creating and assembling resources as supported by ADA.

Git is a modern, fast, open-source distributed version control system, originally developed by Linus Torvalds. It is being used in large-scale open-source projects like, for example, the Linux Kernel and the X Window System X.org, although it is suitable also for small projects.

Unlike other well-known version control systems like CVS and Subversion (which rely on a central repository), Git uses a distributed repository. A central repository is not necessary because each developer can have her own repository with the full history of the project. Changes done by a developer in her repository can be easily copied to other repositories.

GIT approaches the problem of managing versions of a set of files from the point of view of four locations as shown in the following figure (derived from an excellent post by Oliver Steel's Blog).

The user works with her files normally. The “index” is similar to a container in which the changes to the files can be deposited gradually to later be packed and sent to the local repository. As it can be seen in the figure, there are commands to send changes from the files to the index, from the index to the local repository or even directly from the files to the repository.

This workflow can be done entirely in a local machine with no information exchange with any other repository. However, if the different versions need to be shared through an external repository, git offers commands to send these changes or update the local files with the latest revision respect to the remote repository. These commands are explained in the following questions.

But aside from this four-location scenario, Git, as all VCS tools, offers a very powerful functionality to group and manage versions into what are called branches. Branches are different views of the local repository that contain different versions of the files in the repository. At any point in time, the work directory and the index are pointing to one and only one branch of the repository. It then appears the notion of “being placed in a branch” (or should we say “perched”) while working with our local files managed by git.

The most commonly used operations with branches are: create a branch with a name (simply duplicate the content of the current branch), change the current branch, and merge the content of one branch with the current branch. Branches might be a bit counterintiutive at first, but together with an extremely powerful merge capability, offer an effective way to organize multiple versions in a complex set of files.

For further information about Git, go to the official Git Web site.

Git is multi-platform. It can be installed on Windows, Linux and Mac systems.

The distributed model offered by Git allows several workflows. One possible workflow is presented here, but different alternatives are also possible. It is assumed that a set of authors create content for a course that is ultimately combined in a common location by a person called the coordinator to produce the final version to be published in the Web.

Also, a repository for the course material (and optionally course administration files) must be installed in an location associated to the course and such that all the authors must be able to exchange files (for example through SSH). This repository will be referred to as the shared repository in some parts of this FAQ.

The course coordinator sets up an initial version of the shared repository. Git repositories allow for versions to be grouped in what is called a branch. Branches are copies of the repository such that versions can be selected from any of them to manipulate. There is always a branch called master and the coordinator should use it as the official one containing the course material (if you are a course coordinator, see How to set-up the shared repository). Published material is intended to be built from the contents of this branch. The course coordinator is the person in charge of combining the changes from all the authors into this branch. In order to maintain the new versions produced by the authors properly contained, a branch should be created for each author that is going to use the repository. Authors will modify files in their respective local repositories and eventually upload a new version of their files to the proper branch of the shared repository. The coordinator takes authors' contributions from their branches and merges them into this repository (if you are a course coordinator, see How to merge contributions from authors). The following figure illustrates the interaction between authors and course coordinator through the shared repository.

As it can be seen, in addition to the course shared repository, authors have their own local repository in their workspace (their laptop, corporate user account, etc.) These repositories can be easily set up by cloning the course repository (see How to clone a repository). Authors then edit and store their versions in their local repositories, and when the new version is ready to be shared with the rest of authors, they push the changes to the proper author branch in the shared repository (see How to send changes to the shared repository).

A repository containing a copy of another repository is obtained using the clone command. Let us suppose that the shared repository is available through SSH with the following parameters:

Open a Git Shell window (see How to install Git). Go to the directory where you want to store your repository (take into account that git will create a new folder with the name material). Execute the following command:

$ git clone ssh://mycourse@accounts.example.com/home/mycourse/repository/material

You will be asked to authenticate with mycourse's password. The program will then print several messages and after a while a clone of the shared repository should appear now in a new sub-directory called material inside your current directory. The following figure illustrates this process.

With the previous command you may have downloaded a self-contained directory, in which case, all the files are already available for regular use, or a directory with references to some complementary material. These directories are called “submodules” and need a special treatment. A directory contains these modules if the file .gitmodules is present in the top directory.

In the presence of modules, there are two additional commands that need to be executed in order to obtain the entire repository.

$ git submodule init
$ git submodule update

The first command simply inserts the submodule declaration as part of the repository (a simple declaration is downloaded with the first clone command). The second effectively clones the additional modules.

You may now enter in the top directory of the cloned copy and type git status:

$ git status
# On branch master
nothing to commit (working directory clean)

As you can see, the repository has been successfully downloaded, you are in the master branch and the working directory is clean of any changes. If the command says that you are placed on a branch different from master, then you just must change to that branch with the command:

$ git checkout master

If you are not placed on the master branch and the previous command failed, it means that the master branch was not cloned. To create it you must type:

$ git checkout -b master origin/master

Your repository should now be placed on branch master as illustrated in the following figure.

Before beginning to work, you need to edit the configuration file of your repository to simplify the exchange of information with your author branch in the shared repository. Open the file .git/config in your repository directory with a plain text editor and add the line push = master:john at the end of the remote "origin" section. Remember that john is the name of your branch in the shared repository in this example. The file should now look something like this:

$ cat .git/config
[core]
        repositoryformatversion = 0
        filemode = true
        bare = false
        logallrefupdates = true
[remote "origin"]
        url = ssh://john@accounts.example.com/home/mycourse/repository/material
        fetch = +refs/heads/*:refs/remotes/origin/*
        push = master:john
[branch "master"]
        remote = origin
        merge = refs/heads/master

Now your local repository is ready to work. Go ahead and modify your files in this repository, and eventually send the changes first to the index (if you need to do so) and then to your local repository (see How to commit changes). Whenever you think appropriate push your changes to your branch in the shared repository (see How to send changes to the shared repository), and to obtain the latest version from the repository, update from time to time your local repository(see How to update your local repository with others' changes).

“Commits” are the basic unit used by Git to keep track of the different versions of the contents it manages. Only the versions committed into the repository are available later for reverting changes, examining history, computing differences between versions, etc. In other words, if you never commit files, it is like working with no VCS at all. So, commit often, in an orderly fashion (this takes some experience) and trying to separate changes in logical units (this takes even more experience).

Authors make continuous changes to their content. After changing some files, typically when they finish a logical unit of work (e.g. finish writing or reviewing a document section, including a figure in a document, finish a draft they want to share with others, etc.), authors send the new version to the local repository. The action of sending a new version into the local repository is called a commit. For each commit, Git stores the differences between the files now and the files in the previous commit.

When you have a new version of the files you want to commit, it helps sometimes to take a look at those changes before sending them to the repository. This is achieved with the git status command:

$ git status
# On branch master
# Changes to be committed:
#   (use "git reset HEAD <file>..." to unstage)
#
#       new file:   images/ReallyCoolImage.svg
#
# Changed but not updated:
#   (use "git add <file>..." to update what will be committed)
#
#       modified:   MyCoolResource.xml
#
# Untracked files:
#   (use "git add <file>..." to include in what will be committed)
#
#       MyCoolResource.html
#       MyCoolReource.pdf
#       build.out

The text dumped on the screen is the way Git has to tell us what is the situation between your files, the index and the local repository (refresh your memory with What is git). It first shows those files that are already inside the index and ready to be committed (in the example images/ReallyCoolImage.svg). It then shows the files that have changed but are not inside the index (in this case MyCoolResource.xml). And it finally shows those files that Git knows nothing about them, or in other words, are ignored by git or untracked. If you need a much more detailed report on the changes made, use the command git diff, which shows the lines that changed (were added, removed or modified) in all the modified files.

There are two typical ways to send changes to the local repository. If you want to send only the files in the index, then the command is git commit. In order to be considered as changes, files need to be explicitly placed in the index with the command git add file. If this concept of the index is too confusing, forget about it for the time being and use it only once you feed the need for it.

The alternative way of doing a commit is to ignore the index and simply send the changes in all the files (the second section on the report shown by git status). To achieve this, just type git commit -a. This command commits all the files that have been modified since the last commit (independently of being in the index or not).

The commit command always asks for a message describing the changes that are being sent to the repository. There is this unwritten convention that says that comments should include a summary (similar to an email subject) in the first line, then an empty line and then a longer description of the changes if needed.

Redesigned completely the figure on this section

The figure was actually very confusing, so I modified the arrows (which were
backwards and added some colors so make it more intuitive.
       modified:   MyCoolResource.xml

Git places several lines in the editor as part of the message. But all of them start with the “#” symbol that says that it will be ignored. Git places them there just in case you want to include any of them, and saves you the time to type it (as the last line in the example)

If you create a new file, Git ignores its presence and is listed as untracked. If you want that file to be part of the versions managed by Git you must include it explicitly with the command git add <filename>. This command also includes the new file in the index. The next time you commit your changes, the file will be considered by Git. After adding a file you may check the status of your working files with the command git status.

Sometimes, but only sometimes, you've modified lots of files, and instead of creating a new version with all the changes, you would like to document the changes separately by grouping some files. For example, you made two clearly identified changes. One in files f1 and f2, and the second in files f3 and f4. The command git commit -a will send the new versions of all four files to the repository, but you would like to send the first two with a message and the second two with another message in separated commits.

This is precisely the purpose of the index! The index is this fictitious box in which files are prepared and packed to be sent to the local repository. By using the command git add <filenames>, you can place the files you want in the index. Once you have the right files, run the command git commit (without the -a option!) and the files in the index, and only them, are sent to the repository. No other changes in your local files are considered and the index appears now as empty. You can then proceed to place in the index the second set of files and execute the second commit.

Source code management tools, like Git, are designed to track source files. Files produced automatically by compilers, stylesheets, image transformation programs, etc. should not be tracked.

This does not mean that untracked files cannot be inside your working directory, they can, but just that they should not be added into the Git repository. Do not worry about having them in your working directory, because only files that are added explicitly with the git add <filename> command are tracked by Git. Be careful when you add a directory with git add, because it adds all the files inside it into the repository. If there are files in that directory that should not be added, it is better to list the files to be added explicitly.

In the case of ADA, add into the Git repository your Docbook source files, your figures in the vector format produced by your favorite drawing program (normally SVG files), configuration files like Properties.txt and Params.xml and, in general, any other resources that are not generated automatically by ADA.

In general, do not include into the Git repository files like PDFs and HTMLs produced from Docbook or LaTex sources, PNG images produced from SVG figures, the backup files that are saved by some editors, etc.

When you commit changes, they are only stored in your local repository. Remember, you own your repository. If you want those changes to be stored also in the shared repository, you have to explicitly send them (or push them!) to that repository after committing. See How to send changes to the shared repository for further explanation.

Make sure your are placed in your master branch and type the command:

$ git pull

If there have been any changes in the course repository (ore more precisely in its master branch) they are now included in your repository.

The pull can only be executed if your index is empty. Remember that empty box in What is git? To make sure you have no pending changes, commit them before executing git pull.

If your changes have been committed into your the master branch and you have set-up your local repository following the instructions in How to clone a repository, you just have to execute:

$ git push

Your changes should be now on your branch in the shared repository. If your modifications are ready to be reviewed by the course coordinator, you may tell her that there are new contents there. The course coordinator will review them and, if they are all right, put them into the official branch.

The proposed workflow (there are many others possible) is illustrated in the following figure.

You initiated the process by cloning the shared repository (see How to clone a repository), then modified your own files and first committed those new versions to your local repository (see How to clone a repository), once these changes were ready to be shared you pushed them to the shared repository (see How to send changes to the shared repository) and where stored in a different branch specially reserved for your changes. Somebody else, after inspecting (or not) your changes, took them and promoted them to the master branch by a “merge” operation. If any other file has changed in the shared repository, you may pull them (see How to update your local repository with others' changes.

So, a hypothetical sequence of commands in your regular day to day work as an author would be:

$ git pull # (Get the latest files)
... Work on your material and produce really cool stuff ...
$ git add <new files> # (Some new files need to be added)
$ git commit (-a) # (I'm done, store the changes locally)
... Go home/coffee up/take a nap/Lunch/Phone/ whatever
... Work on your material and modify it again ...
$ git commit (-a) # (I'm done with this other set of changes)
$ git push # (Ready for prime time. Send it to the shared repository)
... Notify the coordinator that there is new stuff ready ...
... Wait for any comments ...
$ git pull # (Get the latest files again)
...

You need first some account or location which is accessible to the rest of authors. It will be assumed that you have such account. Enter in the course account and decide where you want to put the shared repository. It can be anywhere, but remember not to put it in a place served by a Web server if you want your repository not to be public. Once you have created a directory for the repository (named, for example, material), enter into this directory and type:

$ git init

The material directory is now a Git repository placed on branch master, with no content. This will be the official branch of the shared course repository. It means that whatever files are on that branch, they are taken as the official versions.

Create the initial layout for your course (directories, common files, etc.) and commit your changes. The command git add will be useful to include files in the version control mechanism (see How to commit changes). Remember that Git does not handle empty directories. Therefore, if you create directories with no material , you may want to create an initial version of Properties.txt inside that directory and add it at the set of files controlled by Git.

After you have finished your initial layout and committed it, create a new branch for each contributing author:

$ git branch john
$ git branch mary
$ git branch laura
$ git branch peter

There is no need to create all the required branches in advance. You may create additional branches whenever new authors are considered.

The shared repository is now ready. Tell the authors the basic parameters to access it (remote machine they should connect to, name of the course account, location of the repository in the course account, and their author branch name).

There are several ways you may interact with this repository. One of them could be to keep a clone of this repository in your local workspace. Follow the instructions in How to clone a repository and obtain such clone. One possible workflow produces all the changes in the master branch in your local repository and push the changes into the master branch of the shared repository when it is ready to be made public. For more detailed instructions on how to manage all the changes, follow the instructions in How the coordinator clones the shared repository.

We recommend you to create a clone of the shared repository in your own workspace (probably your laptop or desktop computer). Follow the instructions in How to clone a repository to create your repository and set-up your branch master, with the exception that the line you should add to your .git/config file which in your case is push = master:master:

$ cat .git/config
[core]
        repositoryformatversion = 0
        filemode = true
        bare = false
        logallrefupdates = true
[remote "origin"]
        url = ssh://YourLogin@accounts.example.com/home/mycourse/repository/material
        fetch = +refs/heads/*:refs/remotes/origin/*
        push = master:master
[branch "master"]
        remote = origin
        merge = refs/heads/master

This change is because your master branch in your local repository will be the branch where you prepare the official material that other authors will see after you push the changes into the master branch of the shared repository.

Your main role as the course coordinator is to supervise the changes proposed by your team of authors and incorporate them to the official master branch of the shared repository. But in order to do that, you have to access to the contributions of all the authors. To perform such task replicate in your local repository the author branches in the shared repository. For example:

$ git branch --track john origin/john
$ git branch --track mary origin/mary
$ git branch --track laura origin/laura
$ git branch --track peter origin/peter

Your local repository is now prepared for merging contributions from other authors. Don't worry, the merging will be done with the help of Git which is really good at it. If you happen to be not only the course coordinator but also an author, then it is recommended to have your own local branch to do such changes and then merge them into the master branch. A typical sequence when you have changes and you want them to be included in the master branch is:

$ git checkout master
$ git checkout -b new-calendar
... edit ... commit ... edit ... commit ...
$ git checkout master
$ git merge new-calendar
$ git branch -d new-calendar

The command git checkout -b creates a new branch starting from the current branch (master in this case). After you have edited and committed (probably several commits), you can merge those changes into the official branch with git merge. Finally, you can safely remove the temporary branch with git branch -d. If you plan to do further changes in the short-term about the same topic, you can skip the last step, and reuse the branch.

Merging is probably the most delicate of the steps, but Git gives you a lot of flexibility to perform this operation. As with the rest of the proposed workflow, there are multiple alterntives for merging contributions from a set of authors, but a concrete one is explained here.

You should have created a local repository and you have your master branch as well as one branch per author. If you are not at this point, stop right here and go back to How the coordinator clones the shared repository.

Suppose you want to merge some changes introduced by Mary. She should have pushed her changes into the mary branch in the shared repository. Go to your mary local branch and update it (that is, fetch those changes from the shared repository):

$ git checkout mary
$ git pull

The first command places you in the branch assigned to Mary, the second, as the name says, “pulls” those changes to your local copy of such branch. You may review them and take a look at the history of commits performed by Mary with git log. If you see no problems and the changes are good to be incorporated to the official branch, it is time then to merge her changes into the master branch (if you are not happy with the changes ask Mary to fix the problems). In order to merge into the master branch, you need to change to such branch:

$ git checkout master
$ git merge mary

The changes of Mary should now be available in your local master branch. Since this is the official source of material for the entire course, make sure the material is built correctly with adado. If you need to fix details, you may do so and commit the changes normally to your local repository. So far, no change has left your local repository to the shared one. Once you are finished with the modifications and see the material perfectly stable again, you want them to be in the official branch of the shared repository, available for all the authors. It is time then to push these changes:

$ git push

Authors will now be able to obtain these changes the next time they execute git pull from their local repository.

If you made it to this point, and you went several times around this loop of pulling changes, review them and pushing them to the shared repository, you are ready to explore a bit deeper what Git is capable of doing. The commands in this FAQ are just a small subset of the real functionality.

Creating a HTML document with one or several exercises can be easily done with the rules presented in the previous sections (see How to translate Docbook to HTML, for example). But in some cases, certain activities require more than one document and more importantly, the possibility of interfacing the documents with other platforms to submit answers, automatic grading, etc.

ADA offers the possibility of preparing a set of files around the concept of “exercise”. The scenario that is assumed is the following:

The variables used in the previously described scenario suitable to be defined in the Properties.txt are:

When used, this rule creates the previously described documents: hand-out, solutions, professor guide and submission page. Two stylesheet files are specified. The variable exercisesubmit.style.file is used to produce the hand out, solutions and professor guide document. The variable exercisesubmit.submit.style.file is used to obtain the submission page. Multilingual versions of all these documents can be produced using the exercisesubmit.multilingual.files.

The structure of the hand-out document is similar to the one obtained when using the stylesheet HeadTail.xsl (see How to inserta Header and Tail in a HTML File for more details). The additional variables to control the the style are:

For example, let us consider a XML file that contains two exercises. With the following definitions in the Properties.txt file:

mergestyles.master.style=Params.xml

exercisesubmit.files=index.xml

and some customization definitions in the Params.xml file, the resulting handout document has the appearance shown in the following figure:

The solution document is conceived as a document that has entirely the same text as the hand out but extended with annotations containing the solution to the posed questions. These annotations can be placed at only three levels of the document: section, note and phrase.

To include the solution information inside a section, the attribute condition must be present in this element with the value solution. The section with this attribute is ignored when processing the hand out document and considered when processing the solution document.

The inclusion of the solution information in a note element is similar to the previous one but this element is intended to be included at a lower level within the document (for example, inside an entry in a table, between two paragraphs, in a list, etc.) The presence of the condition attribute with value solution has the same effect than in the case of the section element previously described.

The third method to include the solution information is to place it in the middle of regular text. By using the phrase element with the attribute condition equal to the value solution, small text strings can be interspersed through in the middle of a paragraph.

For example, let us consider a XML file that contains two exercises with the information about the solutions. With the following definitions in the Properties.txt file:

mergestyles.master.style=Params.xml

exercisesubmit.files=index.xml

and some customization definitions in the Params.xml file, the resulting solution document has the appearance shown in the following figure:

The presence or absence of the solution information is controlled by the following style parameter:

The rule to generate the solution document invokes the proper style sheet changing the value of this variable to “yes”.

The document called the “professor guide” is intended for the use of the teaching staff. It includes the solution information and special annotations and remarks not to be seen by the students. Two elements are prepared to encapsulate these comments: note and section. In both cases, the condition attribute must have the value professorguide.

For example, let us consider a XML file that contains two exercises with the information to include in the professor guide. With the following definitions in the Properties.txt file:

mergestyles.master.style=Params.xml

exercisesubmit.files=index.xml

and some customization definitions in the Params.xml file, the resulting solution document has the appearance shown in the following figure:

The presence or absence of the professor guide information is controlled by the following style parameter:

The rule to generate the professor guide document invokes the proper style sheet changing the value of this variable to “yes”.

Yet to be written.

ADA includes a set of stylesheets to transform a Docbook document with certain special elements into an HTML document with the appearance of an exam. As with the rest of styles in ADA, some elements are parameters and therefore can be easily customized. Alternatively, you may use this style as the basis for your own customized style.

There are two sets of variables and rules depending on the type of exam. If an exam contains a set of questions that need to be shuffled and two versions be produced, then the variables with the prefix testexam are used. If the exam is simply a set of exercises and no shuffle is required, then the varaiables with the prefix exam are required. In the same directory, two exams, one of each type may coexist.

The variables that can be included in the Properties.txt file are:

You main check the content of the following samples of the Properties.txt file to:

The stylesheet needs certain special elements and parameters to generate the exam heading. Furthermore, certain special elements may be included in the Docbook source document to produce additional elements in the HTML version. The customization then is achieved by using both mechanisms: parameters and elements in the document. The following figure shows an exam in which all the customizable parts have been substituted by the parameter names or the element to include in the source document.

The docbook source document to create an exam like the one shown in the previous figure must have a <section> element as root. The content of this section together with the values of the parameters are used to produce the HTML file.

Additional parameters available for customization but not shown in the figure are:

The generic structure of a Docbook file to render with the exam heading would be something similar to (see also the Docbook source file used to create the exam in the previous figure):

<section lang="en" id="ExamID">

  <title>Title to insert in the HTML head</title>
  <para condition="part">Problems</para>
  
  <para condition="duration">1 hour and 15 minutes</para>
  <para condition="scoring">50 points over 100</para>
  <para condition="date">May 16th, 2008 at 16:30</para>

  <para condition="note">
    The rules for the exam are...
  </para>

  <para condition="name"/> <!-- To include the name box -->

  <section>
    <title>Section with the exercises (this title is ignored)</title>
    <section>
      <title>This is the first exercise (this title is ignored)</title>
      <para>
        Exam content. Either regular docbook describing a problem or a 
        qandaset element with several qandaentry elements each of them
        containing one or several questions
      </para>
    </section>
    ...
  </section>
</section>

If the exam contains only true/false questions, the style includes a table with scoring data (number of correct, incorrect and empty answers as well as the final score) if the element <para condition="score"/> is included in the root section element. The following figure shows the resulting box if the element is included.

The file containing the parameter values would have a structure similar to:

<xsl:stylesheet
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform" 
  xmlns="http://www.w3.org/1999/xhtml" version="1.0">

  <xsl:param name="ada.exam.include.id" select="'no'"/>
  <xsl:param name="ada.exam.render.separate.cover" select="'yes'"/>
  <xsl:param name="ada.exam.author">Author that created the exam</xsl:param>
  <xsl:param name="ada.exam.topleft.image">Logo.png</xsl:param>
  <xsl:param name="ada.exam.topleft.image.alt">My Logo</xsl:param>
  <xsl:param name="ada.exam.topleft.toptext">The degree name</xsl:param>
  <xsl:param name="ada.exam.topleft.centertext">Course name</xsl:param>
  <xsl:param name="ada.exam.topleft.centertext.en">Date</xsl:param>
  <xsl:param name="ada.exam.topleft.bottomtext">Some other message</xsl:param>
  ...
</xsl:stylesheet>

See How to use a slightly modified stylesheet to see how the file containing these definitions is included in the Properties.txt file

Additionaly to producing an exam heading (see How to produce the exam heading) the ADA stylesheet is capable of detecting true/false questions with certain structure and produce two HTML documents with these questions shuffled.

The questions must be described using the qandaentry docbook element which is provided preciselly to mark the content of questions and answers.

The following listing shows the content of a Docbook file with the definition of a multiple choice question:

<qandadiv condition="TestQuestion" id="Question ID">
  <blockinfo>
    <author>
      <personname>
        <firstname>AuthorFirst</firstname><surname>AuthorLast</surname>
      </personname>
    </author>
  </blockinfo>
  <para>Any text preceding the (possible) multiple questions.</para>
  <qandaentry>
    <!-- Any text to precede the question -->
    <para>
        Include here any Docbook subset introducing the first question.
    </para>
    <question>
      <para>First Question text</para>
    </question>
    <!-- Answer value as attribute -->
    <answer condition="False" />
  </qandaentry>
  <qandaentry>
    <!-- Any text to precede the question -->
    <para>
        Include here any Docbook subset introducing the second question.
    </para>
    <question>
      <para>Second question text</para>
    </question>
    <!-- Answer value as attribute -->
    <answer condition="True" />
  </qandaentry>
</qandadiv>

The condition attribute in the qandadiv element with the value TestQuestion is used to state the type of rendering to be used, in this case, two possible answers, “True” or “False”. The id attribute can be used to uniquely identify questions in a catalog.

The blockinfo element is used to store some basic information about the question. Some additional elements can be included within this block as explained in How to select a subset of questions from a catalog. Following this element, an arbitrary Docbook fragment can be included. This is useful if, for example, a problem statement is followed by several related true/false questions. These questions need to be included in the same qandadiv element. When shuffling questions, ADA shuffles independently the questions within this unit.

After this optional portion, questions are each included inside a qandaentry. This element may include again an arbitrary Docbook fragment to introduce the question, the question itself surrounded by the question element and a signe answer element with the condition attribute equal to the correct answer. Acceptable true values are “Correct”, “Correcto”, “True”, and “Cierto”. Acceptable false values are “Incorrect”, “Incorrecto”, “False”, and “Falso”.

The HTML obtained with the previously included Docbook structure is shown in the following figure.

Additionaly to producing an exam heading (see How to produce the exam heading) the ADA stylesheet is capable of detecting true/false and multiple choice questions with certain structure and produce two versions with these questions shuffled.

The questions must be described using the qandaentry docbook element which is provided preciselly to mark the content of questions and answers.

The following listing shows the content of a Docbook file with the definition of a multiple choice question:

<qandadiv condition="TestMCQuestion" id="Your own unique id">
  <blockinfo>   <!-- Basic meta info for this question -->
    <author>
      <personname>
        <firstname>AuthorName</firstname><surname>AuthorSurname</surname>
      </personname>
    </author>
  </blockinfo>
  <para>Any text preceding the (possible) multiple questions.</para>
  <qandaentry>
    <para> <!-- Any text to precede the question -->
        Include here any Docbook subset introducing the questions
    </para>
    <question>
      <para>Question text.</para>
    </question>
    <!-- 
         Answer list. The correct one needs to include the condition attribute
         with value "Correct, True, Correcto or Cierto". 
    -->
    <answer condition="Correct"><para>First answer</para></answer>
    <answer><para>Second answer</para></answer>
    <answer><para>Third answer</para></answer>
    <answer><para>Fourth answer</para></answer>
  </qandaentry>
</qandadiv>

The condition attribute with the value TestMCQuestion attribute is used to state the type of rendering to be used, in this case, a set of possible answer with a white square on their left. The id attribute can be used to uniquely identify questions in a wider catalog.

The blockinfo element is used to store some basic information about the question. Some additional elements can be included within this block as explained in How to select a subset of questions from a catalog. Following this element, an arbitrary Docbook fragment can be included. This is useful if, for example, a problem statement is followed by several related questions (see How to typeset a true/false question exam for an example). These questions need to be included in the same qandadiv element. When shuffling questions, ADA shuffles independently the questions within this unit.

After this optional portion, questions are each included inside a qandaentry. This element may include again an arbitrary Docbook fragment to introduce the question, the question itself surrounded by the question element and the multiple answers surrounded by the answer element. Correct answers are distinguished by the condition attribute in the answer element with one of the values “Correct”, “Correcto”, “True” or “Cierto”.

The HTML obtained with the previously included Docbook structure is shown in the following figure.

That depends on the type of exam being manipulated. If the exam contains a test (either variable testexam.file or testexam.bilingual.file are defined) then there are numerous extra files produced because of the shuffling mechanism. The following table summarizes the four possible scenarios when combined with single language file or bilingual file when processing an exam file with name examfile.xml (the expression foo_[a,b] means that two files are produced, foo_a and foo_b).

Although not a functionality provided by ADA, by combining questions encoded in Docbook with the possibility of including a fragment of a XML file into another (using xinclude), questions can be managed in large catalogs and select only a subset for a given exam.

The idea is to centralize all the test questions created over the years into a single large Docbook file with the format explaned in How to typeset a true/false question exam and How to typeset a multiple choice question exam. When creating a new exam, a special set of questions can be selected by providing a set of identifiers. Two conditions are required to perform such operation: question sets need to have identifiers (aside from the unique question identifier stored in the id attribute) and a mechanism to select from the file only those questions with a given identifier.

ADA proposes to identify sets of questions by means of three identifiers to facilitate stratified searches. An example of the Docbook element chosen to include this information is as follows:

<qandadiv condition="TestQuestion" id="Q Id">
  <blockinfo>
    <author>
      <personname>
        <firstname>Author First</firstname><surname>Author Last</surname>
      </personname>
    </author>
    <printhistory>
      <para arch="ID_1" revision="ID_2" vendor="ID_3" />
    </printhistory>
  </blockinfo>
  <qandaentry>
    <question>Question Text</question>
    </question>
    <answer condition="True" />
  </qandaentry>
</qandadiv>

The printhistory element may contain an arbitrary number of para elements each of them with three identifiers. With this scheme, a question may belong to more than one set of questions (for example when re-used in more than one exam) and have one of these identifiers for each set.

For example, given the file QuestionCatalog.xml with a large number of questions, selecting those questions that belong to a set is achieved by using the “Xinclude” notation. The usage of such element within a XML file is shown in the following listing:

<qandaset defaultlabel="number">
  <xi:include href="QuestionCatalog.xml"
    xpointer="xpointer(//*/qandadiv/blockinfo/printhistory/para[@arch =
              'ID_1'][@revision = 'ID_2'][@vendor = 'ID_3']/ancestor::qandadiv)"
              xmlns:xi="http://www.w3.org/2001/XInclude">
    <xi:fallback>
      <para>No questions found in catalog with id="ID_1/ID_2/ID_3"</para>
    </xi:fallback>
  </xi:include>
</qandaset>

The resulting qandaset element contains only those questions that match the three given identifiers. With this technique, a possible usage scenario would be to keep all questions for a course, or set of courses, all encoded in a single file and then preparing an exam would be simply to label the questions with the proper identifiers and them pull all of them in the source document with the xinclude construction as shown above.

ADA offers some support to implement this scenario. It assumes that the information attached to a question after it has been used in a test (generically referred as “stats”) is also stored in the Docbook source structure.

The idea is to extend the mechanism of question group identifier (see How to select a subset of questions from a catalog) and include certain typical measurements. The proposed structure is shown in the following listing:

<qandaentry>
  <blockinfo>
    <printhistory>
      <para arch="ID_1" revision="ID_2" vendor="ID_3">
        <phrase condition="correct">20</phrase>
        <phrase condition="incorrect">0</phrase>
        <phrase condition="blank">2</phrase>
        <phrase condition="total">22</phrase>
        <phrase condition="remarks" />
      </para>
    </printhistory>
  </blockinfo>
  <question>
    <para>Question text</para>
  </question>
  <answer condition="False" />
</qandaentry>

Each qandaentry element may include a blockinfo with several printhistory blocks. Each of them contains a paragraph with a group identifier made of the same three attributes as described in How to select a subset of questions from a catalog and five phrase elements with the numbers derived from the use of the question in that set. In the example the question was answered by 22 perons, 20 of them answered correctly, nobody answered incorrectly and only two persons left it blank.

ADA does not provide any support on how to collect and insert that information within each question. Since the files have a XML structure, it would be feasible to design some application that given a set of question identifiers and the proper data, it inserts them with the proper markup, but at this time, ADA does not offer such functionality.

However, the rules to produce test exams (see How to typeset a true/false question exam and How to typeset a multiple choice question exam) produce an additional files with extension _stats in which all the data include for the questions are shown in tables. The following figure shows the table resulting from processing the data in the previous example: