Chapter 2. Red Hat Documentation Guidelines

2.1. ID Naming Conventions
2.2. File Header
2.3. Admonitions
2.3.1. Creating Notes, Tips, Cautions, Importants, and Warnings
2.4. Screenshots
2.5. Diagrams and Images

Please read this chapter carefully. This chapter describes the guidelines that must be followed such as naming conventions.

2.1. ID Naming Conventions

You will see certain ID names referred to below and this will help to explain how we come up with those names. For example:


<chapter id="ch-uniquename">

<sect3="s3-install-make-disks">

<figure id="fig-redhat-config-kickstart-basic">

IDs are unique identifiers, allowing DocBook XML to know where to cross-reference a section or chapter or the like.

The general rules for defining an ID are:

  • Keep it 32 characters or under (this is counted as everything between the quotation marks)

  • Keep it as short and simple as possible

  • Make sure the name is relevant to the information (make it recognizable)

Some examples are "ch-uniquename" (with 13 characters) and "s3-install-make-disks" (with 21 characters).

A section within a particular chapter always uses the chapter name (minus the "ch-") in its ID. For example, you are working with the "ch-intro" chapter and need to create your first section on disk partitions. That section ID would look similar to "s1-intro-partition" which contains the section number, the main chapter ID, and a unique ID for that section.

TagPrefix
prefacepr-
chapterch-
sectionsn-
sect1s1-
sect2s2-
sect3s3-
sect4s4-
figurefig-
tabletb-
appendixap-
partpt-
exampleex-

Table 2.1. Naming Conventions