Difficulty: ★☆☆ (easy)
Keywords: section, sectX, sect1, nesting sections

Problem

You need to know the differences and advantages of using a section vs. a sectn element.

Solution

The differences between section vs. sectn are shown in Table 1.2, “Comparison Between section and sectn Elements”:

Table 1.2. Comparison Between section and sectn Elements
Issuesectionsectn
Nesting Level?Undefined[a]Up to five levels (sect5)
Readability?WorseBetter
Easy Relocation?YesNo, needs to be renamed
Renaming after relocation?NoYes

[a] See discussion.

Discussion

Apart from technical issues, using section or sect1 is in most cases a matter of taste. However, knowing some of the differences in Table 1.2 can be helpful to decide which better suits your document.

Nesting Level. If you have documents that go further than level five, use the section element. This can be nested infinitely. On the other hand, if you want to restrict the levels to five, better use the sectn elements. You can, however, use DocBook's RELAX NG schema to customize it further (see next section).

Readability. This issue depends on how you edit your DocBook source code. If you edit it manually in your editor (in other words: without the aid of some kind of WYSIWYG), you can see and understand the level straight from the tag name when using sectn. Especially if you have lots of nested sections this makes it a lot easier than section. However, modern XML editors can show the XPath where you are, so it may be negligible.

Relocation. If you have to change the structure a lot, using section elements makes it a lot easier. If you use a sect2 element and this should become a sect1 element you have to rename it.

See Also

http://www.docbook.org/tdg51/en/html/ch05.html#ex.limitsdepth


Project@GitHubIssue#6