6. The Backmatter
This chapter deals with creating the backmatter of a document. The backmatter comprises the appendices, glossary and bibliography, as well as the keyword indexes.
6.1. The Appendices
An appendix is technically identical to a chapter, which also implies that you cannot have an appendix in an article. The only difference is that appendices are enumerated with latin letters. The appendices follow directly after the last chapter in a document. You can suppress an entry in the table of contents by setting the tocentry attribute to no.
6.2. Creating a Glossary
Creating a glossary can be as easy as pulling out your magic wand and saying make-glossary. If you are afraid, that spell might fire backwards, you can also create your glossary manually instead.
6.2.1. Making Definitions on the Spot
Whenever you come across a term or expression in your manuscript that you want to add to the glossary, use the defterm element to make the definition right there on the spot. The defterm element is a definition list (see also section 5.1.2) with only a single entry and it is used inline in the running paragraph as shown in this example:
<p> Users who are already familiar with HTML or document markup languages like DocBook <defterm> <dt>DocBook</dt> <dd> DocBook is a semantic markup language, originally developed by HAL Computer Systems and O'Reilly & Associates to enable document interchange between document publications systems of different vendors. DocBook has since grown into a comprehensive document authoring system. Modern versions of DocBook use XML for the markup and come with templates based on the Extensible Stylesheet Language for the transformation of documents to representational formats. </dd> </defterm> will find learning ECML particularly easy. </p>
There may be special cases, in which the collation rules of your locale have to be modified. This can be done indirectly by providing explicit sortkeys for glossary entries, using the defterm element's sortkey attribute. For example, in order to make “crocodile” sort as “krokodil”, you would write:
<defterm sortkey="krokodil"> <dt>crocodile</dt> <dd> ...
6.2.2. Automatic Generation of the Glossary
Putting instances of defterm in your document will not automatically trigger the generation of a glossary section. For this to happen, you have to insert a make-glossary element right after the appendices, or after the final chapter if the document does not have an appendix. A typical occurrence of this element in a document written in American English might look like this:
... </appendix> <make-glossary locale="en_US" tocentry="yes" alphabet="[Symbols],A,B,C,D,E,F,G,H,I,J,K,L,M,N,O,P,Q,R,S,T,U,V,W,X,Y,Z"/> <biblio number="no"> ...
The alphabet attribute holds a list of letters according to which your glossary will be sectioned. This has nothing to do with how the glossary will be sorted. In order to determine the collation, use the locale attribute instead. The alphabet attribute should contain a comma-separated list of characters. It may also contain a denominator of the form [name] – where name would typically be the word “symbols” – for entries that consist of only symbolic characters. The default alphabet is the basic latin alphabet.
The locale attribute indicates the language whose collation rules will be used to sort the glossary. Use one of the locale identifiers listed in section 3.3.1. Even though this attribute is optional, it is highly recommended that you always set it, or your glossary will be sorted according to the default locale of the system or account in which ecromedos is being run. If you select a locale, which is not supported on your system, ecromedos will fall back to standard C sorting.
The tocentry attribute, which can occur on any sectioning element, may be set to no to prevent the glossary from showing up in the table of contents (TOC), when generating printable output. In XHTML output, the glossary will always be listed in the TOC.
6.2.3. Creating the Glossary Manually
If you don't like the idea of having defterm elements all over your document, or for some other reason would prefer to set the glossary yourself, then here is how to do it:
<glossary> ... <glsection name="D"> <dl> <dt>DocBook</dt> <dd> DocBook is a semantic markup language, originally developed by ... </dd> <dt>Doxygen</dt> <dd> A tool for documenting C++ code. </dd> </dl> </glsection> <glsection name="E"> ... </glsection> ... </glossary>
As you can see, the glossary is split into glsections. Typically, there will be a separate section for each letter of your alphabet, and the name of a section would be the letter that it represents. Each section contains a single definition list with all the entries for the respective letter. Simply put your glossary in place of the make-glossary element.
6.3. Keeping a Bibliography
Bibliographies are entered with the biblio tag and individual entries with bibitem. The bibliography comes after the last section in your document or after the glossary, if one exists. ecromedos does not support bibliographies for individual sections. A typical bibliography might look like this:
<biblio number="yes"> <bibitem label="KOCH09" id="bib:KOCH09"> Tobias Koch. <i>ecromedos 2.0 - Users' Manual</i>. <tt>ecromedos.net</tt>, 2009. </bibitem> <bibitem label="WALSH03" id="bib:WALSH03"> Norman Walsh, Leonard Muellner. <i>DocBook: The Definitive Guide</i>. O‘Reilly, 2003. </bibitem> </biblio>
The biblio element encloses a series of bibitem elements, which represent the individual entries in the bibliography. Each bibitem carries a label and an id attribute. If the number attribute on the biblio element is set to no, then the user-supplied label will be shown next to the entry and in citations. If numbering is set to yes, which is the default, then the ordinal number of an item will be used as its label and the user-supplied identifier will be discarded.
Citing from the Bibliography
Use the cite element, when citing from a source listed in the bibliography, to point the reader to the corresponding entry like this:
... <p> For more information on DocBook, please refer to <cite idref="bib:WALSH03"/>. </p> ...
The document pre-processor will replace each occurence of the cite element with the label of the corresponding entry set in square brackets. For example, to refer to the first entry in the listing above, you would write <cite idref="bib:KOCH09"/>, which the document pre-processor would replace with [1] when numbering is turned on and with [KOCH09] when numbering is off.
6.4. Generating Keyword Indexes
ecromedos facilitates the generation of keyword indexes by allowing you to place index markers in the text as you are writing. These markers are collected, sorted and turned into corresponding index sections by the document pre-processor without requiring any additional effort from the writer. Just as for the glossary (see section 6.2.3), you can also set indexes manually, if required.
6.4.1. Placing Index Markers
Index markers are embedded inline into the runnning paragraph. However, in order to not cause too much visual disturbance in the source document, it is recommended to aggregate markers at the beginning or end of paragraphs. The listing below is an excerpt from the source code of this chapter:
<p> <idxterm group="ecml"> <item>biblio</item> <subitem>number</subitem> </idxterm> <idxterm group="ecml"> <item>bibitem</item> </idxterm> <idxterm group="ecml"> <item>bibitem</item> <subitem>label</subitem> </idxterm> <idxterm group="ecml"> <item>bibitem</item> <subitem>id</subitem> </idxterm> The <tt><b>biblio</b></tt> element encloses a series of <tt><b>bibitem</b></tt> elements, which represent the individual entries in the bibliography. Each <tt><b>bibitem</b></tt> carries a <tt><b>label</b></tt> and an <tt><b>id</b></tt> attribute. If the <tt><b>number</b></tt> ... </p>
As you can see, you can arrange keywords into a hierarchy. In the example above, a marker for bibitem is placed on the base level, using the idxterm and item elements. Then the markers for label and id are added as subitems. There is also a subsubitem element, in case you ever need a third hierarchy level.
There is one thing to note about this example: all entries are placed in a separate group called ecml. Effectively, a separate index listing all ECML language elements is created. Entries for which no group is specified will go into the default group.
Analogously to the defterm element (see section 6.2.1), you can set an explicit sortkey on the idxterm element, if you need to tweak the collation in a special way.
6.4.2. Automatic Index Generation
Use the make-index element to have the index markers in a particular group assembled into an actual keyword index. This document, for example, contains an index that links all ECML language elements and attributes to the sections in which they are discussed. The generation of this index is triggered with a make-index element like this:
...
</biblio>
<make-index group="default" locale="en_US" alphabet="[Symbols],A,B,C,
D,E,F,G,H,I,J,K,L,M,N,O,P,Q,R,S,T,U,V,W,X,Y,Z" tocentry="yes"
columns="2"/>
</report>
The make-index element goes logically after the biblio element.
The locale attribute indicates the language whose collation rules will be used to sort the index. Use one of the locale identifiers listed in section 3.3.1. Even though this attribute is optional, it is highly recommended that you always set it, or your index will be sorted according to the default locale of the system or account in which ecromedos is being run. If you select a locale, which is not supported on your system, ecromedos will fall back to standard C sorting.
The optional title attribute allows you to override the automatic title.
6.4.3. Manual Index Creation
Creating a full index single-handedly, can be a lot of work, but if you really must, here is how to do it: Instead of placing index markers in the document, you leave ordinary labels in places that you wish to reference from the index. Then in the index, simply use the idxref element, which behaves just like pageref (see section 4.3), to obtain the page number of a label. The following is an excerpt from the XML that the document pre-processor may have generated for the listing of ECML language elements that can be found at the end of this document.
<index title="Language Elements" columns="2" tocentry="yes"> <idxsection name="A"> <item>abstract <idxref idref="idx:label1"/></item> <item>appendix <idxref idref="idx:label2"/></item> <item>article <idxref idref="idx:label3"/></item> <subitem>bcor <idxref idref="idx:label4"/></subitem> <subitem>div <idxref idref="idx:label5"/></subitem> <subitem>lang <idxref idref="idx:label6"/></subitem> <subitem>papersize <idxref idref="idx:label7"/></subitem> <subitem>secnumdepth <idxref idref="idx:label8"/></subitem> <subitem>secsplitdepth <idxref idref="idx:label9"/>, <idxref idref="idx:label10"/></subitem> </idxsection> <idxsection name="B"> ... </idxsection> ... </index>
As you can see the structure of an index is somewhat similar to that of a glossary. The index is split into idxsections, each of which typically represents one letter of your alphabet. A section contains a series of items. Please note that subitems are not nested inside items. A subitem is considered as belonging to the item element immediately preceding it.