Chapter 6. DocBook XML Tags

6.1. Tags and Entities Caveats
6.2. application
6.3. chapter
6.4. citetitle
6.5. command
6.6. computeroutput
6.7. emphasis
6.8. example
6.9. filename
6.10. firstterm
6.11. footnote
6.12. figure
6.13. GUI Tags
6.13.1. guilabel
6.13.2. guibutton
6.13.3. guiicon
6.13.4. guimenu and guimenuitem
6.14. keycap
6.14.1. menuchoice
6.14.2. keycombo
6.15. Lists
6.15.1. itemizedlist
6.15.2. OrderedList
6.15.3. Variablelist
6.15.4. Creating a List Within a Table Using Simplelist
6.15.5. glosslist
6.16. option
6.17. Index Entries
6.18. para
6.19. part
6.20. prompt
6.21. replaceable
6.22. screen
6.22.1. Using Inline Tags with screen
6.23. Sections
6.24. table
6.24.1. Creating a List Within a Table
6.25. trademark
6.26. userinput
6.27. ulink
6.28. wordasword
6.29. xref

Please read this chapter carefully. This chapter describes the tags used by the Docs Project. Some of the rules described are specific to the project.

If these tags are used appropriately, document searches will provide meaningful results. These tags help search engines identify the information relevant to the search request. Another benefit is that all Fedora Project documents will have a similar look and feel (however, they will have some differences depending upon the output format).

All tags in XML must have an opening and closing tag Additionally, proper XML conventions say that there must be a unique identifier for sections, chapters, figures, tables, and so on, so that they may be correctly identified, and cross referenced if needed.

Although XML is capable of handling many document types, the format discussed here is the article format.

This chapter only discusses tags used for documentation for the Fedora Project, not all available DocBook XML tags. For the complete list, refer to:


http://www.docbook.org/tdg/en/html/docbook.html

6.1. Tags and Entities Caveats

It is very important that you remember the caveats in this section. Even though they are more strict than valid DocBook XML, these rules exist so that both the HTML and PDF outputs look proper.

Do Not Use Trademark Entities

Do not use the trademark entities ™, ©, or ® because the do not produce HTML output that works for all charsets. The HTML output produces by these entities are declared in the DTD and cannot be changed via the stylesheet.

Instead, use the trademark tag and its associates classes as follows:

  • <trademark>trademark symbol after me</trademark>

  • <trademark class="registered">registered trademark symbol after me</trademark>

  • <trademark class="copyright">copyright symbol after me</trademark>

Content inside para tags

Do not use para tags around anything other than a simple paragraph. Doing so will create additional white space within the text itself in the PDF version.

Specifically, do not use para tags around the following (or, to put this another way, do not embed the following within para tags):

  • <screen>

  • <itemizedlist>

  • <orderedlist>

  • <variablelist>

  • <table>

Content inside para tags within listitem tags

Content inside para tags within listitem tags must start immediately after the beginning <para> tag to avoid extra white space in the PDF version.

Content inside screen tags

The screen tags (<screen> and </screen>) must be flush left in the XML file, and all the content inside the screen tags must be flush left as well unless the white space in intentional; otherwise, the extraneous whitespace will appear in the HTML version.