Add some tips and remove some revision tag references from element glossary.
[working/Evergreen.git] / style_guide / glossary.xml
1 <?xml version="1.0" encoding="utf-8"?>\r
2 <chapter xml:id="style-glossary" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="EN"\r
3     xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink">\r
4     <info>\r
5         <title>DIG DocBook reference</title>\r
6     </info>\r
7     <section>\r
8         <info>\r
9             <title>Elements</title>\r
10         </info>\r
11         <para>Below is a non-exhaustive list of DocBook elements used in Evergreen documentation.\r
12             Authors may use other elements but are encouraged to draw from this list first. Each\r
13             term links to the authoritative DocBook 5 reference pages at <link\r
14                 xlink:href="http://www.docbook.org/tdg5/en/html/"\r
15                 >http://www.docbook.org/tdg5/en/html/part2.html</link>.</para>\r
16         <glossary>\r
17             <title/>\r
18             <glossentry xml:id="section">\r
19                 <glossterm>\r
20                     <link xlink:href="http://www.docbook.org/tdg5/en/html/section.html"\r
21                         >section</link>\r
22                 </glossterm>\r
23                 <glossdef>\r
24                     <para>A titled subdivision of a <markup linkend="chapter">chapter</markup>, only\r
25                         required if a chapter has two or more sections. Sections appear in TOC and\r
26                         have their own pages in HTML output (use <markup linkend="simplesect"\r
27                             >simplesect</markup> to exclude from TOC). The <markup linkend="xmlid"\r
28                             >xml:id</markup> attribute is optional and can be applied ad hoc when\r
29                         linking to a section.</para>\r
30                     <para>The section element can be nested to\r
31                         create subsections. Here are some examples used in <emphasis>The Book of Evergreen</emphasis>: </para>\r
32                     <itemizedlist>\r
33                         <listitem>\r
34                             <para><emphasis>section -> section</emphasis> (for a section and\r
35                                 subsection, both appearing in TOC)</para>\r
36                         </listitem>\r
37                         <listitem>\r
38                             <para><emphasis>section -> simplesect</emphasis> (for a section and\r
39                                 subsection, w/ only the top level in the TOC)</para>\r
40                         </listitem>\r
41                         <listitem>\r
42                             <para><emphasis>section -> section -> simplesect</emphasis> (for a\r
43                                 section, subsection, and sub-subsection, with the top 2 in the\r
44                                 TOC))</para>\r
45                         </listitem>\r
46                     </itemizedlist>\r
47                 </glossdef></glossentry>\r
48             <glossentry xml:id="xref">\r
49                 <glossterm>\r
50                     <link xlink:href="http://www.docbook.org/tdg5/en/html/xref.html">xref</link>\r
51                 </glossterm>\r
52                 <glossdef>\r
53                     <para>A cross reference to another part of the document (use <markup\r
54                             linkend="link">link</markup> for external links). The destination is set\r
55                         with the <markup linkend="linkend">linkend</markup> attribute, which matches\r
56                         the <markup linkend="xmlid">xml:id</markup> of the destination element. Link\r
57                         text is auto-generated.</para>\r
58                     <para><application>oXygen</application> returns a validation error if the link\r
59                         destination is in another xml file; this is resolved when the files are\r
60                         assembled for publication and can be ignored.</para>\r
61                 </glossdef></glossentry>\r
62             <glossentry xml:id="guimenu">\r
63                 <glossterm>\r
64                     <link xlink:href="http://www.docbook.org/tdg5/en/html/guimenu.html"\r
65                         >guimenu</link>\r
66                 </glossterm>\r
67                 <glossdef>\r
68                     <para>Use for the names of staff client menus; formatted in italics.</para>\r
69                 </glossdef></glossentry>\r
70             <glossentry xml:id="menuchoice">\r
71                 <glossterm>\r
72                     <link xlink:href="http://www.docbook.org/tdg5/en/html/menuchoice.html"\r
73                         >menuchoice</link>\r
74                 </glossterm>\r
75                 <glossdef>\r
76                     <para>Use to describe a menu selection. Usually contains <markup\r
77                             linkend="guimenu">guimenu</markup> and <markup linkend="guimenuitem"\r
78                             >guimenitiem</markup> elements (may also contain <markup\r
79                             linkend="guisubmenu">guisubmenu</markup>). Output displays an arrow\r
80                         between each child element. <programlisting><![CDATA[ \r
81     <para>To clear the staff client cache go to\r
82        <menuchoice>\r
83            <guimenu>Admin</guimenu>  \r
84            <guisubmenu>For developers</guisubmenu>\r
85            <guisubmenuitem>Clear Cache</guisubmenuitem>\r
86        </menuchoice>\r
87     </para>]]>\r
88     \r
89                             </programlisting> displays as <informalexample>\r
90                             <para>To clear the staff client cache go to <menuchoice>\r
91                                     <guimenu>Admin</guimenu>\r
92                                     <guisubmenu>For developers</guisubmenu>\r
93                                     <guimenuitem>Clear Cache</guimenuitem>\r
94                                 </menuchoice>\r
95                             </para>\r
96                         </informalexample></para>\r
97                 </glossdef></glossentry>\r
98             <glossentry xml:id="guimenuitem">\r
99                 <glossterm>\r
100                     <link xlink:href="http://www.docbook.org/tdg5/en/html/guimenuitem.html"\r
101                         >guimenuitem</link>\r
102                 </glossterm>\r
103                 <glossdef>\r
104                     <para>An option in a staff client menu or submenu; formatted in italics.</para>\r
105                 </glossdef></glossentry>\r
106             <glossentry xml:id="guibutton">\r
107                 <glossterm>\r
108                     <link xlink:href="http://www.docbook.org/tdg5/en/html/guibutton.html"\r
109                         >guibutton</link>\r
110                 </glossterm>\r
111                 <glossdef>\r
112                     <para>A button in the staff client. Currently formatted with italics, though this can be changed in the stylesheets.<programlisting><![CDATA[ \r
113 <para>Click <guibutton>Modify Copies</guibutton> to save your changes</para>]]>                       \r
114 \r
115                         </programlisting>\r
116                         displays as<informalexample>\r
117                             <para>Click <guibutton>Modify Copies</guibutton> to save your\r
118                                 changes</para>\r
119                         </informalexample></para>\r
120                 </glossdef></glossentry>\r
121             <glossentry xml:id="informalfigure">\r
122                 <glossterm>\r
123                     <link xlink:href="http://www.docbook.org/tdg5/en/html/informalfigure.html"\r
124                         >informalfigure</link>\r
125                 </glossterm>\r
126                 <glossdef>\r
127                     <para>A wrapper for a <markup>mediaobject</markup> and optional\r
128                         associated text. Stylesheet customizations ensure the contents of an informfigure are kept together during PDF pagination. The\r
129                             <markup linkend="step">step</markup> in the following example will not\r
130                         split across a page break: <programlisting>    <![CDATA[ \r
131 <step>\r
132     <informalfigure>\r
133         <para>STEP TEXT GOES HERE</para>  \r
134         <mediaobject>\r
135             <alt>OPTIONAL DESCRIPTION OF IMAGE</alt>\r
136             <imageobject>\r
137                 <imagedata  scalefit="0" fileref="media/FILENAME_HERE.png"/>\r
138             </imageobject>\r
139         </mediaobject>\r
140     </informalfigure>\r
141 </step>]]>\r
142         \r
143                         </programlisting></para>\r
144                 </glossdef></glossentry>\r
145             <glossentry xml:id="figure">\r
146                 <glossterm>\r
147                     <link xlink:href="http://www.docbook.org/tdg5/en/html/figure.html">figure</link>\r
148                 </glossterm>\r
149                 <glossdef>\r
150                     <para>Wrapper for a <markup linkend="mediaobject">mediaobject</markup> that has\r
151                         a title and appears in list of figures (in the book's front matter). Content in <markup\r
152                             linkend="figure">figure</markup> and <markup linkend="informalfigure"\r
153                             >informalfigure</markup> is not split across PDF page breaks.</para>\r
154                 </glossdef></glossentry>\r
155             <glossentry xml:id="example">\r
156                 <glossterm>\r
157                     <link xlink:href="http://www.docbook.org/tdg5/en/html/example.html"\r
158                         >example</link>\r
159                 </glossterm>\r
160                 <glossdef>\r
161                     <para>An example with a title.</para>\r
162                 </glossdef></glossentry>\r
163             <glossentry xml:id="informalexample">\r
164                 <glossterm>\r
165                     <link xlink:href="http://www.docbook.org/tdg5/en/html/informalexample.html"\r
166                         >informalexample</link>\r
167                 </glossterm>\r
168                 <glossdef>\r
169                     <para>An example with no title.</para>\r
170                 </glossdef></glossentry>\r
171             <glossentry xml:id="formalpara">\r
172                 <glossterm>\r
173                     <link xlink:href="http://www.docbook.org/tdg5/en/html/formalpara.html"\r
174                         >formalpara</link>\r
175                 </glossterm>\r
176                 <glossdef>\r
177                     <para>A titled paragraph. The following <programlisting><![CDATA[ \r
178 <formalpara>\r
179     <title>Paragraph title</title>\r
180     <para>Paragraph body...</para>  \r
181 </formalpara>]]>                       \r
182                         \r
183                     </programlisting>\r
184                         displays as<informalexample>\r
185                             <formalpara>\r
186                                 <title>Paragraph title</title>\r
187                                 <para>Paragraph body...</para>\r
188                             </formalpara>\r
189                         </informalexample></para>\r
190                 </glossdef></glossentry>\r
191             <glossentry xml:id="mediaobject">\r
192                 <glossterm>\r
193                     <link xlink:href="http://www.docbook.org/tdg5/en/html/mediaobject.html"\r
194                         >mediaobject</link>\r
195                 </glossterm>\r
196                 <glossdef>\r
197                     <para>A wrapper for <markup linkend="imageobject"\r
198                             >imageobjects</markup>. May be wrapped in an\r
199                             <markup linkend="informalfigure">informalfigure</markup> to keep image and text together across page breaks. See <xref linkend="style-image"/> for more\r
200                         on image formatting.</para>\r
201                 </glossdef></glossentry>\r
202             <glossentry xml:id="alt">\r
203                 <glossterm>\r
204                     <link xlink:href="http://www.docbook.org/tdg5/en/html/alt.html">alt</link>\r
205                 </glossterm>\r
206                 <glossdef>\r
207                     <para>Metadata describing an element, usually for accessibility. For example, each <markup linkend="mediaobject">mediaobject</markup> may contain an\r
208                             alt element with a generic description of the\r
209                         image content.</para>\r
210                 </glossdef></glossentry>\r
211             <glossentry xml:id="imageobject">\r
212                 <glossterm>\r
213                     <link xlink:href="http://www.docbook.org/tdg5/en/html/imageobject.html"\r
214                         >imageobject</link>\r
215                 </glossterm>\r
216                 <glossdef>\r
217                     <para>Contained by <markup linkend="mediaobject">mediaobject</markup> and a\r
218                         wrapper for <markup linkend="imagedata">imagedata</markup>.  See <xref linkend="style-image"/> for more on\r
219                         image formatting in <emphasis>The Book of Evergreen</emphasis>.</para>\r
220                 </glossdef></glossentry>\r
221             <glossentry xml:id="imagedata">\r
222                 <glossterm>\r
223                     <link xlink:href="http://www.docbook.org/tdg5/en/html/imagedata.html"\r
224                         >imagedata</link>\r
225                 </glossterm>\r
226                 <glossdef>\r
227                     <para>Contained by <markup linkend="imageobject">imageobject</markup>, its\r
228                         attributes determine sizing, scaling, alignment, and source file. See <xref\r
229                             linkend="style-image"/> for more on Sitka image formatting. </para>\r
230                 </glossdef></glossentry>\r
231             <glossentry xml:id="guilabel">\r
232                 <glossterm>\r
233                     <link xlink:href="http://www.docbook.org/tdg5/en/html/guilabel.html"\r
234                         >guilabel</link>\r
235                 </glossterm>\r
236                 <glossdef>\r
237                     <para>Use for labels and titles in the staff client. Where applicable <markup\r
238                             linkend="guimenu">guimenu</markup>, <markup linkend="guimenuitem"\r
239                             >guimenuitem</markup>, and <markup linkend="guibutton"\r
240                             >guibutton</markup> are preferred. HTML is formatted in italics, PDF is\r
241                         not formatted.</para>\r
242                 </glossdef></glossentry>\r
243             <glossentry xml:id="guisubmenu">\r
244                 <glossterm>\r
245                     <link xlink:href="http://www.docbook.org/tdg5/en/html/guisubmenu.html"\r
246                         >guisubmenu</link>\r
247                 </glossterm>\r
248                 <glossdef>\r
249                     <para>A staff client submenu. Used when a submenu is part of a <markup\r
250                             linkend="menuchoice">menuchoice</markup> sequence. Not italicized.\r
251                     </para>\r
252                 </glossdef></glossentry>\r
253             <glossentry xml:id="keycap">\r
254                 <glossterm>\r
255                     <link xlink:href="http://www.docbook.org/tdg5/en/html/keycap.html">keycap</link>\r
256                 </glossterm>\r
257                 <glossdef>\r
258                     <para>The label on a keyboard button; formatted in bold (eg Press\r
259                             <keycap>F5</keycap>).</para>\r
260                 </glossdef></glossentry>\r
261             <glossentry xml:id="keycombo">\r
262                 <glossterm>\r
263                     <link xlink:href="http://www.docbook.org/tdg5/en/html/keycap.html">keycap</link>\r
264                 </glossterm>\r
265                 <glossdef>\r
266                     <para>For a combination of two or more keystrokes, wrap <markup linkend="keycap"\r
267                             >keycap</markup> elements in a keycombo. Format is bold with a + between\r
268                         keystrokes. <programlisting><![CDATA[ \r
269 <para>Open a new tab with\r
270     <keycombo>\r
271         <keycap>Ctrl</keycap>\r
272         <keycap>T</keycap>\r
273     </keycombo>\r
274 </para> ]]>                       \r
275 \r
276                         </programlisting> displays as<informalexample>\r
277                             <para>Open a new tab with <keycombo>\r
278                                     <keycap>Ctrl</keycap>\r
279                                     <keycap>T</keycap>\r
280                                 </keycombo>\r
281                             </para>\r
282                         </informalexample></para>\r
283                 </glossdef></glossentry>\r
284             <glossentry xml:id="application">\r
285                 <glossterm>\r
286                     <link xlink:href="http://www.docbook.org/tdg5/en/html/application.html"\r
287                         >application</link>\r
288                 </glossterm>\r
289                 <glossdef>\r
290                     <para>The name of a software program or application such as\r
291                             <application>Evergreen</application>. Currently not formatted, but\r
292                         consistent use would allow for future batch formatting (e.g. italicize content of all application tags).</para>\r
293                 </glossdef></glossentry>\r
294             <glossentry xml:id="emphasis">\r
295                 <glossterm>\r
296                     <link xlink:href="http://www.docbook.org/tdg5/en/html/emphasis.html"\r
297                         >emphasis</link>\r
298                 </glossterm>\r
299                 <glossdef>\r
300                     <para>Use to <emphasis>italicize</emphasis> regular text.  Use with the ROLE attribute for <emphasis role="bold">bold</emphasis> text</para>\r
301                     <para><programlisting><![CDATA[ \r
302 <para>For <emphasis>italic</emphasis> and <emphasis role="bold">bold</emphasis> output.</para>\r
303 ]]>                       \r
304 \r
305                     </programlisting> displays as<informalexample>\r
306                         <para>For <emphasis>italic</emphasis> and <emphasis role="bold">bold</emphasis> output.</para>\r
307                         \r
308                     </informalexample> </para>\r
309                 </glossdef></glossentry>\r
310             <glossentry xml:id="tip">\r
311                 <glossterm>\r
312                     <link xlink:href="http://www.docbook.org/tdg5/en/html/tip.html">tip</link>\r
313                 </glossterm>\r
314                 <glossdef>\r
315                     <para>Enclose tip text and images in this element for consistent formatting.\r
316                         Display options are set with CSS and XSL stylesheets and include custom tip\r
317                         text, icons, formatting, etc.\r
318                     \r
319                     <programlisting><![CDATA[ \r
320 <tip>\r
321     <para>Tip text goes here</para>\r
322 </tip> ]]>                       \r
323 \r
324                     </programlisting> displays as<informalexample>\r
325                         <tip>\r
326                             <para>Tip text goes here       \r
327                             </para>\r
328                         </tip>\r
329                     </informalexample> </para>\r
330                     \r
331                 </glossdef></glossentry>\r
332             <glossentry xml:id="glossary">\r
333                 <glossterm>\r
334                     <link xlink:show="new" xlink:href="http://www.docbook.org/tdg5/en/html/glossary.html"\r
335                         >glossary</link>\r
336                 </glossterm>\r
337                 <glossdef>\r
338                     <para>Wrapper for a glossary.  Must contain <markup\r
339                             linkend="title">title</markup> element (to hide the title in published\r
340                         output use an empty <markup><![CDATA[<title/>]]></markup> tag).</para>\r
341                 </glossdef></glossentry>\r
342             <glossentry xml:id="glossentry">\r
343                 <glossterm>\r
344                     <link xlink:href="http://www.docbook.org/tdg5/en/html/glossentry.html"\r
345                         >glossentry</link>\r
346                 </glossterm>\r
347                 <glossdef>\r
348                     <para>Wrapper for each glossary entry. Should always have an <markup\r
349                             linkend="xmlid">xml:id</markup> for cross referencing. Entries are\r
350                         sorted alphabetically in published output, regardless of order in xml source\r
351                         document (this is optional and is set with stylesheet parameters). Full glossentry markup including child elements is shown below: <programlisting> <![CDATA[ \r
352 <glossentry xml:id="guisubmenu">\r
353     <glossterm>guisubmenu</glossterm>\r
354     <glossdef>\r
355         <para>A staff client submenu. Used primarily when a submenu is part\r
356         of a <markup>menuchoice</markup> sequence.  Not italicized.</para> \r
357         <glossseealso otherterm="guimenu"/>\r
358     </glossdef>\r
359 </glossentry>]]>                        \r
360                         \r
361                     </programlisting></para>\r
362                 </glossdef></glossentry>\r
363             <glossentry xml:id="glossterm">\r
364                 <glossterm>\r
365                     <link xlink:href="http://www.docbook.org/tdg5/en/html/glossterm.html"\r
366                         >glossterm</link>\r
367                 </glossterm>\r
368                 <glossdef>\r
369                     <para>Wrapper for the term in a <markup linkend="glossentry"\r
370                         >glossentry</markup>.</para>\r
371                 </glossdef></glossentry>\r
372             <glossentry xml:id="glosssee">\r
373                 <glossterm>\r
374                     <link xlink:href="http://www.docbook.org/tdg5/en/html/glosssee.html"\r
375                         >glosssee</link>\r
376                 </glossterm>\r
377                 <glossdef>\r
378                     <para>A "see" link that points from one <markup linkend="glossentry"\r
379                             >glossentry</markup> to another. Always has an <markup\r
380                             linkend="otherterm">otherterm</markup> attribute that corresponds to the\r
381                             <markup linkend="xmlid">xml:id</markup> of the referenced term.</para>\r
382                 </glossdef></glossentry>\r
383             <glossentry xml:id="glossseealso">\r
384                 <glossterm>\r
385                     <link xlink:href="http://www.docbook.org/tdg5/en/html/glossseealso.html"\r
386                         >glossseealso</link>\r
387                 </glossterm>\r
388                 <glossdef>\r
389                     <para>A "see also" link that points from one <markup linkend="glossentry"\r
390                             >glossentry</markup> to another. Always has an <markup\r
391                             linkend="otherterm">otherterm</markup> attribute corresponds to the\r
392                             <markup linkend="xmlid">xml:id</markup> of the referenced term.</para>\r
393                 </glossdef></glossentry>\r
394             <glossentry xml:id="itemizedlist">\r
395                 <glossterm>\r
396                     <link xlink:href="http://www.docbook.org/tdg5/en/html/itemizedlist.html"\r
397                         >itemizedlist</link>\r
398                 </glossterm>\r
399                 <glossdef>\r
400                     <para>A bulleted list with an optional title.</para>\r
401                 </glossdef></glossentry>\r
402             <glossentry xml:id="orderedlist">\r
403                 <glossterm>\r
404                     <link xlink:href="http://www.docbook.org/tdg5/en/html/orderedlist.html"\r
405                         >orderedlist</link>\r
406                 </glossterm>\r
407                 <glossdef>\r
408                     <para>A numbered list with an optional title.</para>\r
409                 </glossdef></glossentry>\r
410             <glossentry xml:id="listitem">\r
411                 <glossterm>\r
412                     <link xlink:href="http://www.docbook.org/tdg5/en/html/listitem.html"\r
413                         >listitem</link>\r
414                 </glossterm>\r
415                 <glossdef>\r
416                     <para>Wrapper for individual entries on an <markup linkend="itemizedlist"\r
417                             >itemizedlist</markup> or <markup linkend="orderedlist"\r
418                             >orderedlist</markup>.</para>\r
419                 </glossdef></glossentry>\r
420             <glossentry xml:id="programlisting">\r
421                 <glossterm>\r
422                     <link xlink:href="http://www.docbook.org/tdg5/en/html/programlisting.html"\r
423                         >programlisting</link>\r
424                 </glossterm>\r
425                 <glossdef>\r
426                     <para>When used with <markup><![CDATA[CDATA]]></markup>, text in a\r
427                         programlisting is published exactly as it appears in the xml file (including\r
428                         line breaks and white space). Formatted as a block with a shaded background,\r
429                         used only for coding examples (see\r
430                             <emphasis>/style/style_glossary.xml</emphasis> for syntax example).\r
431                     </para>\r
432                 </glossdef></glossentry>\r
433             <glossentry xml:id="link">\r
434                 <glossterm>\r
435                     <link xlink:href="http://www.docbook.org/tdg5/en/html/link.html">link</link>\r
436                 </glossterm>\r
437                 <glossdef>\r
438                     <para>For external links. Must have an <markup>xlink:href</markup> attribute with the destination URL. In PDF output\r
439                         the full URL is printed in brackts after the link text.</para>\r
440                 </glossdef></glossentry>\r
441             <glossentry xml:id="procedure">\r
442                 <glossterm>\r
443                     <link xlink:href="http://www.docbook.org/tdg5/en/html/procedure.html"\r
444                         >procedure</link>\r
445                 </glossterm>\r
446                 <glossdef>\r
447                     <para>A multi-step process consisting of two or more <markup linkend="step"\r
448                             >steps</markup>. Applies to most converted Sitka docs.</para>\r
449                     <glossseealso linkend="step">step</glossseealso>\r
450                 </glossdef></glossentry>\r
451             <glossentry xml:id="step">\r
452                 <glossterm>\r
453                     <link xlink:href="http://www.docbook.org/tdg5/en/html/step.html">step</link>\r
454                 </glossterm>\r
455                 <glossdef>\r
456                     <para>Component part of a <markup linkend="procedure">procedure</markup>. Steps\r
457                         are auto-numbered and may contain text, figures, examples, etc. The <markup\r
458                             linkend="xmlid">xml:id</markup> attribute is optional and only required\r
459                         if linking to a particular step. To keep step content together during\r
460                         pagination (eg text w/ associated image), use <markup\r
461                             linkend="informalfigure">informalfigure</markup>.</para>\r
462                 </glossdef></glossentry>\r
463             <glossentry xml:id="para">\r
464                 <glossterm>\r
465                     <link xlink:href="http://www.docbook.org/tdg5/en/html/para.html">para</link>\r
466                 </glossterm>\r
467                 <glossdef>\r
468                     <para>A paragraph; a required wrapper for text in most contexts.</para>\r
469                 </glossdef></glossentry>\r
470             <glossentry xml:id="info">\r
471                 <glossterm>\r
472                     <link xlink:href="http://www.docbook.org/tdg5/en/html/info.html">info</link>\r
473                 </glossterm>\r
474                 <glossdef>\r
475                     <para>A wrapper for metadata about an element, including title.</para>\r
476                 </glossdef></glossentry>\r
477             <glossentry xml:id="book">\r
478                 <glossterm>\r
479                     <link xlink:href="http://www.docbook.org/tdg5/en/html/book.html">book</link>\r
480                 </glossterm>\r
481                 <glossdef>\r
482                     <para>The top level element for Evergreen documentation, appears only in the file\r
483                             <emphasis>root.xml</emphasis></para>\r
484                 </glossdef></glossentry>\r
485             <glossentry xml:id="part">\r
486                 <glossterm>\r
487                     <link xlink:href="http://www.docbook.org/tdg5/en/html/part.html">part</link>\r
488                 </glossterm>\r
489                 <glossdef>\r
490                     <para>A subdivision of a book. Used only in\r
491                             <emphasis>root.xml</emphasis>; each part should have a <markup\r
492                             linkend="title">title</markup> and <markup linkend="xmlid"\r
493                             >xml:id</markup>.</para>\r
494                 </glossdef></glossentry>\r
495             <glossentry xml:id="chapter">\r
496                 <glossterm>\r
497                     <link xlink:href="http://www.docbook.org/tdg5/en/html/chapter.html">\r
498                         chapter</link>\r
499                 </glossterm>\r
500                 <glossdef>\r
501                     <para>A subdivision of a <markup linkend="part">part</markup>, further divided\r
502                         into <markup linkend="section">sections</markup>. In Evergreen documentation each chapter\r
503                         is a separate xml file referenced by <emphasis>root.xml</emphasis>.  Each chapter should\r
504                         have an <markup linkend="xmlid">xml:id</markup>.  The xml:id is required for cross-referencing and stable links to published html files.  If there is no xml:id the generated html files names may change as content is added or re-located.</para>\r
505                 </glossdef></glossentry>\r
506             <glossentry xml:id="title">\r
507                 <glossterm>\r
508                     <link xlink:href="http://www.docbook.org/tdg5/en/html/title.html">title</link>\r
509                 </glossterm>\r
510                 <glossdef>\r
511                     <para>Sets the title for the element which contains it. Required in \r
512                         chapters and sections.</para>\r
513                 </glossdef></glossentry>\r
514            \r
515             <glossentry xml:id="date">\r
516                 <glossterm>\r
517                     <link xlink:href="http://www.docbook.org/tdg5/en/html/date.html">date</link>\r
518                 </glossterm>\r
519                 <glossdef>\r
520                     <para>Wrapper for date info in any context. Format is YYYY-MM-DD</para>\r
521                     \r
522                 </glossdef></glossentry>\r
523             <glossentry xml:id="simplesect">\r
524                 <glossterm><link xlink:href="http://www.docbook.org/tdg5/en/html/simplesect.html"\r
525                         >simplesect</link></glossterm>\r
526                 <glossdef>\r
527                     <para>A subdivision of a <markup linkend="section">section</markup> that does\r
528                         not appear in the TOC. A simplesect is terminal, i.e. cannot be further\r
529                         subdivided with <markup linkend="section">section</markup> or <markup\r
530                             linkend="simplesect">simplesect</markup> elements.</para>\r
531                 </glossdef></glossentry>\r
532         </glossary>\r
533     </section>\r
534     <section>\r
535         <title>Attributes</title>\r
536         <para>DocBook elements can be modified by one or more attributes. The attibutes below are commonly used in <emphasis>The Book of Evergreen</emphasis>.  More info on DocBook 5 attributes is available at <link xlink:href="http://www.docbook.org/tdg5/en/html/ref-elements.html#common.attributes">http://www.docbook.org/tdg5/en/html/ref-elements.html#common.attributes</link></para>\r
537         <glossary>\r
538             <info>\r
539                 <title>Attributes</title>\r
540             </info>\r
541             <glossentry xml:id="xmlid">\r
542                 <glossterm>\r
543                     <link xlink:href="http://www.docbook.org/tdg5/en/html/ref-elements.html#db.cmn.xml:id">xml:id</link>\r
544                 </glossterm>\r
545                 <glossdef>\r
546                     <para>Optional xml identifier for an element, required for cross references and\r
547                         linking. Must be unique within the entire documentation set. Good practice is to make sure that, at minimum, all\r
548                         <markup linkend="book">book</markup>, <markup linkend="part">part</markup>, <markup linkend="chapter">chapter</markup>, and <markup linkend="glossentry">glossentry</markup> elements have an\r
549                         xml:id.  In html output, the xml:id becomes the name the html file and the URL for that segment of the documentation (if there is no xml:id, the html file is auto-numbered).</para>\r
550                     \r
551                 </glossdef></glossentry>\r
552             <glossentry xml:id="linkend">\r
553                 <glossterm>\r
554                     <link xlink:href="http://www.docbook.org/tdg5/en/html/ref-elements.html#db.cmn.linkend">linkend</link>\r
555                 </glossterm>\r
556                 <glossdef>\r
557                     <para>Attribute that sets the link destination. Any DocBook 5 inline\r
558                         element can become a link by adding a linkend attribute that corresponds to the\r
559                             <markup linkend="xmlid">xml:id</markup> of the destination. See\r
560                             <xref linkend="style-links"/> for more detailed info.</para>\r
561                 </glossdef></glossentry>\r
562             <glossentry xml:id="otherterm">\r
563                 <glossterm>\r
564                     <link xlink:href="http://www.docbook.org/tdg5/en/html/ref-elements.html#db.cmn.otherterm">otherterm</link>\r
565                 </glossterm>\r
566                 <glossdef>\r
567                     <para>Applied exclusively to <markup linkend="glosssee">glosssee</markup> and\r
568                             <markup linkend="glossseealso">glossseealso</markup> elements, it points\r
569                         to the referenced glossary term.  <programlisting><![CDATA[<glossseealso otherterm="date"/>]]></programlisting>displays as <informalexample><para>See also <link linkend="date">date</link>.</para></informalexample></para>\r
570                 </glossdef></glossentry>\r
571             <glossentry xml:id="role">\r
572                 <glossterm>\r
573                     <link xlink:href="http://www.docbook.org/tdg5/en/html/ref-elements.html#db.cmn.role">role</link>\r
574                 </glossterm>\r
575                 \r
576                     <glossdef><formalpara><title>Para</title><para>Applied to\r
577                             <markup linkend="para">para</markup> tags to track changes to draft\r
578                             docs for approval by other editors. Can have value of\r
579                             <emphasis>added</emphasis>, <emphasis>deleted</emphasis>, or\r
580                             <emphasis>changed</emphasis>; in html output will be highlighted in\r
581                             green, red, and yellow\r
582                             respectively.</para></formalpara></glossdef>\r
583                 </glossentry>\r
584             \r
585         </glossary>\r
586     </section>\r
587 </chapter>\r