We recommend that you edit Document Holders using the Online DH Editor. See Editing a Document Holder online.
A Document Holder file is a plain text XML file with a specific format. You can edit the XML file in the following ways:
- Using a Notepad-type application or a dedicated XML editor.
- Using the Online DH Editor provided in Cognidox (v8.7.0 onwards). This is covered in Editing a Document Holder online.
This topic explains:
- Off-line editing of an XML file.
- The XML layout that is used for the DH type.
Basic Layout
Cognidox has a set of rules (or schema) for how XML is used for valid Document Holders.
A basic Document Holder consists of:
- An XML element named documentHolder containing an optional <introduction> element.
- A mandatory <sections> element.
The introduction element contains text used to describe the document and is displayed at the top of the Document Holder. The <sections> element is used to contain the document references.
In the example above, the Document Holder consists of a single documentHolder element containing an introduction element and a sections element. The text within the introduction element is formatted such that two newlines start a new paragraph. Notice that the sections element is empty – for real Document Holders, this would not be the case, as the sections element contains the document references.
Notice from the example that the XML elements are case-sensitive, so, when creating your own Document Holders, you must use documentHolder (rather than “DocumentHolder” or “documentholder”).
The sections element
The <sections> element of a Document Holder is used to contain zero or more <section> elements. Each <section> element must have a have a src attribute to link it with a section in another Document Holder (see below), or a title that is used as a heading for the section in the web page created by Cognidox. Here’s an incorrect and a correct example to illustrate this:
<section></section>[This is incorrect]
<section title="test"></section>[This is correct]
A section element may contain a <description> element and may have a <documents> element containing a list of <document> elements. Like the introduction element, the description is used to add some introductory text at the start of each section. You can use this text to describe the types of documents referenced in the section.
The documents element contains zero or more references to documents themselves. A basic document reference consists of a document element with partnum and issue attributes.
The example Document Holder above contains two sections, the first titled Introductory Documents and the second titled Manuals. The first section includes a single description paragraph, while the second section has no description.
Notice from the example that every section has a title attribute and every document has a partnum and issue attribute.
Section identifiers and section inclusion
Section elements can also have an optional id attribute used to uniquely identify the section within the document. For example:
Section ids must be unique within the document, i.e. two or more section elements within a Document Holder cannot use the same id attribute.
It is possible to use a section id to include the section content from another DH document. Including a section from another Document Holder requires use of the optional src attribute. For instance, to include a section with id software_docs in version 3 of AA-999999-DH, the following section element can be used:
When a section is included in a document holder, the title, description and list of documents in the section will be included. Both the title and description can be overridden later if desired.
The document element
The document element contains references to Cognidox documents and can appear multiple times within a Document Holder. A basic document reference has partnum and issue attributes. Because a basic document reference does not contain any text content, it should be written as a self-closed XML element (i.e. an element with a closing '/' character).
By default, Cognidox will display a basic document reference as a link to the document's master file in Cognidox, using the referenced document's title as the link text. If you want to use something other than the document's title as the link, use the title attribute of the document element to set your own title.
In the example above, the document will be linked with the text My Link Text.
When a document reference is displayed in Cognidox, it is shown with any Version Information string associated with the referenced version. However, it is possible to add an additional version string into the document reference and have that displayed too. To add an additional version string, use the version attribute of the document element.
In the example above, Cognidox would display the link to the document with the document's title followed by (My version string).
To include additional text after the document link is shown, it is possible to add text within the document element. This text will be shown as a paragraph directly after the document's link.
In the example above, the document reference contains additional text that is displayed after the document link. Notice that the document element has a closing tag and is not self-closed.
To link to the latest approved version of a document, a document element's issue attribute can be given the value APPROVED.
Formatting the introduction and description elements
By default, the introduction and description elements contain plain text. The only formatting that happens in these plain text blocks is as follows:
- Double newlines are converted to paragraph breaks.
- 20 or more '-' or '_' characters in a line on their own are converted to a horizontal rule.
If more complex formatting in these elements is required, the format attribute can be used, and given a value of textile.
Textile is a simple text formatting mark-up format providing text styling such as bold, strike-through, italic, superscript and subscript. Textile also allows for more complex text structures such as tables and lists. A full description of the Textile mark-up syntax is available at http://www.textism.com/tools/textile/.
When the example above is rendered into a web page, it will result in the following:
When using the '<' and '>' characters in textile formatting, they must be XML escaped to < and > respectively.
For example, the following textile markup:
<code>a = b;</code>
must be written like this in the Document Holder:
<code>a = b;</code>