DocBook documentation templates

Introduction to DocBook documentation templates

DocBook documentation templates are used to develop document models, which can be applied to UML models. Each DocBook documentation template concentrates on a specific metaclass belonging to the metamodel referenced by the MDA component.

DocBook Documentation templates are based on the simplified version of the Docbook documentary metamodel. This documentary metamodel is a standard, recognized model, which is over ten years old, is maintained by an OASIS Open consortium technical committee. Originally destined for the industrial world, the simplified version of Docbook was developed in the objective of broadening the scope of the standard to other domains. For further information on Docbook, please refer to “Docbook, the definitive guide” on www.docbook.org.

DocBook Documentation templates are structured using production nodes and navigation nodes. Production nodes correspond to elements belonging to the “Simplified Docbook” metamodel, and are used to browse this metamodel. An example of a production node would be the “section” element, which is a chapter in Docbook vocabulary.

Customizing DocBook documentation generation

Before generating MDA Modeler documentation, a certain number of parameters must be positioned. XSL files can also be used to customize documentation generation. For details on MDA Modeler documentation generation parameters and XSL file customization, please see “Parameterizing MDA Modeler documentation generation”.

Example of a DocBook documentation template

For a complete example of the construction of a DocBook documentation template, please see “Quick tour of MDA Modeler - Building a documentation template”.

Creating a DocBook documentation template

To create a new DocBook documentation template, click on the icon from a profile implementation. The “DocBook documentation template” window then appears (for details on this window, see “General principles of template design”).

Figure 157. The DocBook documentation template editor

Toolbar

On the top-right of the template design window, the icons (which are presented on the top-right of the template design window as shown in Figure 157) available on a documentation template to create nodes are detailed below.

Icon	Description
	This icon is used to create a navigation node. It is available on the template root, on a navigation node or on a production node.
	This icon is used to create a production node. It is available on the template root, on a navigation node or on a production node.
	This icon is used to reference an internal node in order to execute an existing node. It is available on the template root, on a navigation node or on a production node.

Adding a production node

To add a new production node to your documentation template, simply click on the icon and then select the type of production node you wish to create.

Depending on the type of production node which is selected, different types of production node can be added. The paragraphs which follow are intended to illustrate the most commonly used operations.

For details on other docbook elements, please refer to the end of this section.

Modifying the properties of a production node

Production node properties differ according to the document item selected.

As a general rule, there are two types of property:

· properties for which the value can be directly parameterized and which can contain, for example, a J function. Examples of this type of property are “Title”, “Caption” and “Value”.

· properties which have predefined values.

The contents of a property must appear between inverted commas, if they are not J code. For example, to display the name of a navigation node preceded by the “Name” string, the following should be entered: "Name: " + Name.

For more information on entering J code, please see “Inserting J code”.

Creating a chapter and a paragraph

To create a chapter, a “section” production node must be created. To enter the title of a section, the “Title” property must be defined.

To create a paragraph, a “paragraph” production node must be created, and the value of the paragraph defined.

Let's imagine we want to create a chapter for the class on which the template is to be run, with “Class:” followed by the name of the class in question as its title, before continuing by creating a paragraph within this chapter. Figures 158 and 159 illustrate these operations.

Figure 158. Creating a chapter

Steps:

1. Create a navigation node to retrieve the classes of the current package. For more information on creating navigation nodes, please see “Creating navigation nodes”. Click on the icon on the top-left of the window and select "Classes" from the possible navigation nodes.

2. Select the “Classes” navigation node.

3. Click on the icon.

4. Select “Section” from the list of possible production nodes.

5. Click on “OK” to confirm.

Continue by defining the “Title” property for the newly created section production node, as shown in Figure 158.

On the right-hand side of the window, in the “Value” field associated with the “Title” property, enter: "Class: " + Name.

The next step is to create a paragraph (Figure 159).

Figure 159. Creating a paragraph

Steps:

1. Select the newly-created “Section” production node.

2. Click on the icon.

3. Select “Paragraph” from the list of possible production nodes and click on “OK” to confirm.

4. The new paragraph production node immediately appears. On the right-hand side of the window, in the “Value” field associated with the “Value” property, enter getNoteFormatedContent("description") or double-click on this property and select (by double-clicking) “description” from the “Note content” list.

The resulting documentation template will produce the following result when run on a model (Figure 160).

Figure 160. Example of documentation generated using the documentation template built in Figures 158 and 159

Creating a table

To create a table, a “table” production node must be created. After creation, the table must then be defined.

Let us imagine that we want to display a table for each class containing the name and description of each of its operations. Let's also imagine that we want to include a header line indicating “Operation” and “Description” for each column.

Figures 161 to 164 illustrate these operations.

Figure 161. Creating a table

Steps:

1. Click on the “Section” navigation node.

2. Click on the icon on the top-left of the window.

3. Select “Table” from the list and confirm by clicking on “OK”.

4. Change the name of the production node (by simply clicking on the node or by pressing F2) to “OperationTable”.

5. Define a value for the “Title” property, for example: "Table of the class " + Name.

Continue by carrying out the operations shown in Figure 162.

Figure 162. Creating a group

Steps:

1. Click on the table.

2. Click on the icon on the top-left of the window. Select “Group” from the list and confirm by clicking on “OK”.

3. At this stage, it is IMPERATIVE that you define a value for the “Number of columns” property (in our example, "2" ). This value MUST appear between inverted commas.

Continue by carrying out the following steps:

1. Click on the new group and then click on the icon on the top-left of the window.

Note: At this stage, you can choose to add “Column specification” elements. These elements allow an “internal” name to be attributed to each column according to its number. It is then possible to specify for a line entry the column in which it will appear, according to the name of the column. Otherwise, entries appear in their order of entry.

2. Select “Table body” from the list and confirm by clicking on “OK”.

3. Click on the new table body and then click once again on the icon on the top-left of the window.

4. Select “Row” from the list and confirm by clicking on “OK”. This will create the header line. This hearder line must be composed of two cells.

5. Click on the new “Row” and then click once again on the icon on the top-left of the window.

6. Select “Cell”, confirm by clicking on “OK” and define the value of the “Value” property by entering "Operation" (remember to enter this value between inverted commas!).

7. Create another “Cell” by repeating step 6 and defining the value of the “Value” property by entering "Description" (between inverted commas).

The result of these operations is shown in Figure 163.

Figure 163. The result of the operations you have carried out so far

Next, carry out the following operations:

1. Create a navigation node to retrieve the operations of the current class. For more information on creating navigation nodes, please see “Creating navigation nodes”. Click on the icon on the top-left of the window and select “Operations” from the possible navigation nodes.

2. Click on the icon on the top-left of the window.

3. Select the “Row” element. A row will be generated for each operation. This row must be composed of two cells.

4. Click once again on the icon. Select the “Cell” element, define the property value by entering “Name” (remember to enter this value without inverted commas!).

5. Click once again on the icon.

6. Select the “Cell” element, define the property value by entering getNoteFormatedContent("description") or double-click on this property and select (by double-clicking) “description” from the “Note content” list.

The result of these operations is shown in Figure 164 below.

Figure 164. The newly created table in the documentation template

The documentation template shown in Figure 164 will produce the following result when run on a model (Figure 165).

Figure 165. Example of documentation generated using the documentation template built in Figures 161 to 164

Adding a list

The simplified docbook documentary metamodel provides three types of list:

· Itemized lists, which are lists containing items which can be of different types (paragraphs, images, etc.), where each item in the list is preceded by a symbol.

· Ordered lists, which are lists containing items which can be of different types (paragraphs, images, etc.), where each item in the list is preceded by a number.

· Variable lists, which are lists containing items which can be of different types (paragraphs, images, etc.), but also “terms” (simple text). Each item in the list is preceded by a symbol.

Let us imagine that we want to display a list of classes belonging to a package (the package on which the documentation template is focused), with, for each class, its name following by a summary of its description (“summary” notes).

Figures 166 to 167 illustrate these operations.

Figure 166. Creating an itemized list

Steps:

1. Click on the template root.

2. Click on the icon on the top-left of the window.

3. Select the “Itemized list” element and confirm by clicking on “OK”.

4. The new itemized list production node immediately appears. In the “Value” field associated with the “Title” property, enter "Classes of " + Name.

Continue by carrying out the following steps:

2. Click on the icon on the top-left of the window.

3. Select the “List item” element. We have a general title for all the elements in the list, and a list item for each class.

Finally, carry out the steps shown in Figure 167.

Figure 167. Creating a paragraph within an itemized list

Steps:

1. Select the new “List item” production node.

2. Click on the icon on the top-left of the window.

3. Select the “Paragraph” element and confirm by clicking on “OK” (please note that a list item can contains different types of production node).

4. The new paragraph production node immediately appears. In the “Value” field associated with the “Value” property, enter Name + ": " + getNoteFormatedContent ("summary").

The resulting documentation template will produce the following result when run on a model (Figure 168).

Figure 168. Example of documentation generated using the documentation template built in Figures 166 to 167

Inserting an image

The “Media object” document item is used to insert images into your document.

To insert an “external” image (corresponding to an external file), carry out the following steps:

1. Click on the icon.

2. Select “Media object” in the “Selection of a production node” window and confirm by clicking on “OK”.

3. Select the new media object. By default, it is selected after creation.

4. Click once again on the icon.

5. Select “Image object” in the “Selection of a production node” window and click on “OK” to confirm.

6. Select the new image object. By default, it is selected after creation.

7. Click a third time on the icon.

8. Select “Image data” in the “Selection of a production node” window and click on “OK” to confirm.

9. Define the value of the “File path” property by indicating the path of the image file you wish to insert.

Figure 169. Inserting an image

Inserting a diagram

Despite the fact that they resemble a navigation node, diagrams are primarily used as images. This means that in order to insert the image of a diagram, both these nodes must be used.

Let us imagine that we want to insert into our documentation the class diagrams belonging to the current package.

Figure 170. Inserting a diagram

Steps:

1. Select the documentation template.

2. Create a navigation node to retrieve the diagrams of the current package. For more information on creating navigation nodes, please see “Creating navigation nodes”. Click on the icon on the top-left of the window and select “Class diagrams” from the possible navigation nodes.

3. Click on the icon.

4. Select “Media object” in the “Selection of a production node” window and confirm by clicking on “OK”.

5. Select the new media object production node. By default, it is selected after creation.

6. Click on the icon.

7. Select "Image object" in the “Selection of a production node” window and confirm by clicking on “OK”.

8. Select the new image object production node. By default, it is selected after creation.

9. Click on the icon.

10. Select “Image data” in the “Selection of a production node” window and confirm by clicking on “OK”.

Note 1: No image data production node attributes should be defined.

Note 2: In order for links within diagrams to function properly, it is imperative that a section be created for each of the diagram's elements.

Inserting external files

To insert an external file, a paragraph must be created before.

1. Click on the icon.

2. Select “Include file” from the list of possible production nodes.

In RTF format, included files are generated as fields. In HTML and PDF formats, included files are generated in the form of hypertext links.

The properties of an include file are as follows.

The … property	specifies…
Value	in RTF format, the text displayed before the insertion of the file carried out by the update of the field. By default, if this property is not defined, the message displayed indicates that file inclusion is carried out using the F9 key. in HTML and PDF formats, the text displayed in the form of a hypertext link. By default, if this property is not defined, the name of the file is displayed as a hypertext link.
Merge format	Whether or not the layout should be retained every time an update is carried out. This property is only used for RTF generation. By default, the layout is not retained at every update.
File name	The name of the file in the form of an absolute path or a relative path to the generation directory.

Attaching an external file to a model element

To attach one or several files to a modeling element, create as many {includeFile} tagged values as there as files to be attached. The name of the file must be stored in the first parameter of the tagged value.

The name of the file can be entered as an absolute path or a relative path, since the resolution of the name is carried out by the editor of the generated document.

Note : The {includeFile} tagged value is available after deployment of the “MDARuntime” MDA component.

Inserting an external file

In J, the “string getIncludeFile()” service is used to retrieve the file attached to a modeling element.

If several {includeFile} tagged values have been set, this service only returns the file corresponding to the first {includeFile} tagged value found on the modeling element.

Figure 170-a. Example of inserting an external file attached to a modeling element

Inserting several external files

To insert several external files attached to a single modeling element, a navigation node must be created, in order to allow all the {includeFile} tagged values to be browsed and the content of the first parameter to be retrieved in the “File name” property.

Figure 170-b. Example of inserting several external files attached to a modeling element

Other docbook elements

The following table gives details on the different production nodes which have not already been illustrated in this section.

Name	Description
Node (or complex elements)
Appendix	Like a section, an appendix element can contain sections and is referenced by an identifier.
Bibliography	This element is used to make a bibliography of the articles with links to the concerned documents
Article information	This part of an article provides extensive information about it. This node element can contain an abstract, legal notice or revision information … There is a similar kind of node for sections.
Abstract	This node is placed in information nodes. It can be made up of a title and a set of paragraphs.
Legal notice	A set of notes about legal information.
Author group	This node is placed in information nodes, and provides data about authors and editors.
Copyright	This node is placed in information nodes. It contains data about the copyright of the document.
Note	Note elements are similar to sections or appendices in terms of content. However, they are not structural elements of the document even if they can be used outside of a section.
Leaf (or simple) elements
E-mail	An email element is used to insert email addresses. As a consequence, when generating HTML, a link is made for the email address.
Abbreviation	This element is used by other elements to provide abbreviations.
Program listing	This element is used to put code in the document, special processing will be carried out when documentation generation to format it.
Inline quotation	This element is used to put text in quotes.
Subtitle	When you define the “value” property of this element, a subtitle will be generated. This element is available under the root and sections.
Release information	Information about the document release.
Product name	The value property of this element contains the name of the product the document deals with.
Publication date	The value property of this element contains the publication date of the document.
Product number	The value property of this element contains the product number of the document.