Documentation Primer/Manual/DocBook Reference/Chapters and Sections - Revision history

Claus chr: typo

2012-09-11T08:29:47Z

typo

Claus chr: typo

2012-09-11T08:27:15Z

typo

Claus chr: Corrected links

2012-09-09T10:25:25Z

Corrected links

Claus chr at 08:28, 2 September 2012

2012-09-02T08:28:53Z

Claus chr at 09:06, 1 September 2012

2012-09-01T09:06:22Z

Claus chr: 1 revision: Moving Docbook Primer from UserBase to TechBase

2012-09-01T08:47:32Z

1 revision: Moving Docbook Primer from UserBase to TechBase

Annew: Marked this version for translation

2011-11-30T14:29:18Z

Marked this version for translation

New page

<translate>

=== Chapters and Sections === 


{{Tag|1=chapter id=""}}
</translate><translate>


: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 RedHat®, would be a new section in a larger "Configuration" chapter.


:Chapters must have an <tt>id</tt>. 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 {{Tag|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 {{Tag|link}} and {{Tag|xref}} elements in other parts of the document.


{{Tag|title}}
</translate><translate>


: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.


{{Tag|1=sect1 id=""}}, {{Tag|sect2}}, {{Tag|sect3}}, {{Tag|sect4}}, {{Tag|sect5}}
</translate><translate>


: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 {{Tag|title}}. Sections
are nested according to the number - a {{Tag|sect2}} can contain any number of {{Tag|sect3}}, which can contain {{Tag|sect4}}, but a {{Tag|sect2}} cannot directly contain a {{Tag|sect4}}.


:{{Tag|sect1}} requires an id attribute, and you can use id's on the other section tags if you want to later link directly to them from other parts of the document. <tt>id</tt> is the only attribute used in KDE Documentation.


{{Tag|sect1info}}, {{Tag|sect2info}}, {{Tag|sect3info}}, {{Tag|sect4info}}, {{Tag|sect5info}}
</translate><translate>


:The section info elements are rarely used in KDE Documentation. They are appropriate for documents where some smaller sections arecontributed by third parties, or where the document covers multiple applications. The contents are more or less the same as those of the {{Tag|bookinfo}} section, although they tend to be briefer.


:Please ensure if you use these elements that you add the translation placeholder comments as you do in the prolog.


{{Tag|appendix}}
</translate><translate>


:The standard installation instructions for all applications are contained in an {{Tag|appendix}}, and are normally required for KDE documents. Although the installation instructions as found in the template are reasonably complete, and need no customization for most applications, authors are very strongly encouraged to expand on them. For example, links to web pages, where to find libraries, plugins, screenshots of the application in a particular configuration, or any other information you can think of.


:If the application is only distributed with KDE, there is little use in repeating the same installation instructions for every manual. You may leave it out entirely, unless you have further information to add.


:For other purposes, appendices are used infrequently in KDE Documentation. An appendix can be found, for example, in the '''KPPP''' document, containing such things as Hayes Modem commands. Only use an appendix if you think it's very necessary. In most cases, the information it would contain would be better moved to the main document. In the example of '''KPPP''', this information is vital to a few people, but extremely uninteresting to the majority, so it was placed in an appendix.


{{Prevnext2
| prevpage=Documentation Primer/Manual/DocBook Reference/Book and Bookinfo
| prevtext=The book and the bookinfo section
| nextpage=Documentation Primer/Manual/DocBook Reference/Linking
| nexttext=The linking elements
| index=Documentation Primer/Manual
| indextext=Back to Menu
}}

</translate>

← Older revision		Revision as of 08:28, 2 September 2012
Line 1:		Line 1:
	<languages />		<languages />
−	~~{{Transferring}}~~
	<translate>		<translate>

← Older revision		Revision as of 09:06, 1 September 2012
Line 1:		Line 1:
		+	<languages />
		+	{{Transferring}}
	<translate>		<translate>

@@ Line 42: / Line 42: @@
 <!--T:13-->
-:The section info elements are rarely used in KDE Documentation. They are appropriate for documents where some smaller sections arecontributed by third parties, or where the document covers multiple applications.  The contents are more or less the same as those of the {{Tag|bookinfo}} section, although they tend to be briefer.
+:The section info elements are rarely used in KDE Documentation. They are appropriate for documents where some smaller sections are contributed by third parties, or where the document covers multiple applications.  The contents are more or less the same as those of the {{Tag|bookinfo}} section, although they tend to be briefer.
 <!--T:14-->

@@ Line 32: / Line 32: @@
 <!--T:10-->
-:Sections require a {{Tag|title}}.  Sections
+:Sections require a {{Tag|title}}.  Sections are nested according to the number - a {{Tag|sect2}} can contain any number of {{Tag|sect3}}, which can contain {{Tag|sect4}}, but a {{Tag|sect2}} cannot directly contain a {{Tag|sect4}}.
 are nested according to the number - a {{Tag|sect2}} can contain any number of {{Tag|sect3}}, which can contain {{Tag|sect4}}, but a {{Tag|sect2}} cannot directly contain a {{Tag|sect4}}.
 <!--T:11-->

@@ Line 63: / Line 63: @@
 <!--T:19-->
 {{Prevnext2
-| prevpage=Documentation Primer/Manual/DocBook Reference/Book and Bookinfo
+| prevpage=Special:myLanguage/Documentation Primer/Manual/DocBook Reference/Book and Bookinfo
 | prevtext=The book and the bookinfo section
-| nextpage=Documentation Primer/Manual/DocBook Reference/Linking
+| nextpage=Special:myLanguage/Documentation Primer/Manual/DocBook Reference/Linking
 | nexttext=The linking elements
-| index=Documentation Primer/Manual
+| index=Special:myLanguage/Documentation Primer/Manual
 | indextext=Back to Menu
 }}
 </translate>