Use chapters to break up the document into smaller chunks. A chapter break should occur when a major subject change happens. Use sections within the chapter when the subject changes, but you are still discussing a particular aspect of a larger subject.
For example, going from discussing how to use the application, to how to configure the application would be worthy of a new chapter. Moving from discussing how to specifically configure the application on SuSE, to how to specifically configure the application on Red Hat®, would be a new section in a larger “Configuration” chapter.
Chapters must have an
id. This is the only attribute used in KDE documentation. For KDE Documents, this id must be in lower case, and with a hyphen (-) to separate words. Please don't use spaces, underscores, or run the words together. For HTML generation, the chapter id and most
<sect1>id's are used to name the separate HTML pages, so take care to make them sensible and descriptive. For translators, these id's should be translated, but you will need to take care to also translate references to the id's in
<xref>elements in other parts of the document.
Titles are used in many places, but the most common is the Chapter and Section headings. Make sure to use sensible titles, as these will also be that chapter's (or section's) entry in the table of contents, so people will rely on these to find the part of the document they are interested in.
Use sections to break chapters up into smaller pieces. Use similar criteria on where to divide them as you would for chapters.
Sections require a
<title>. Sections are nested according to the number - a
<sect2>can contain any number of
<sect3>, which can contain
<sect4>, but a
<sect2>can't directly contain a