Changeset 3301 for trunk/doc/src/docbook/developerdoc/write_docbook_doc.xml

Timestamp:

May 8, 2007, 8:57:48 AM (16 years ago)

Author:

Nicklas Nordborg

Message:

Added option to stop the chunking of each sect1 in chapters and to chunk each sect2 inside sect1.

File:

• trunk/doc/src/docbook/developerdoc/write_docbook_doc.xml (modified) (1 diff)

trunk/doc/src/docbook/developerdoc/write_docbook_doc.xml

@@ -242 +242 @@
       </sect3>
     </sect2>
+    
+    <sect2 id="write_docbook_doc.begin.chunking">
+      <title>Controlling chunking</title>
+      <para>
+        We have configured docbook to create a new output file for
+        each new <sgmltag class="starttag">chapter</sgmltag>
+        and <sgmltag class="starttag">sect1</sgmltag>. In most cases this 
+        gives each page a relatively good size. Not too long and not too short.
+        However, if a chapter contains many small <sgmltag class="starttag">sect1</sgmltag>
+        sections (for example, <xref linkend="resources"/>), you end up with many 
+        pages with just a few lines of text on each page. This is not so 
+        good and can be avoided by adding a <sgmltag class="attribute">chunked = "0"</sgmltag>
+        attribute to the chapter, for example:
+      </para>
+      <programlisting>
+&lt;chapter id="resources" chunked="0"&gt;
+</programlisting>
+      <para>
+        This will stop the chunking of <sgmltag class="starttag">sect1</sgmltag>
+        sections in this chapter. On the other
+        hand, if you have a <sgmltag class="starttag">sect1</sgmltag>
+        that contains many long <sgmltag class="starttag">sect2</sgmltag>
+        sections you might want to put each <sgmltag class="starttag">sect2</sgmltag>
+        section in a separate chunk. If you want to do this:
+      </para>
+      <programlisting>
+&lt;sect1 id="sect.with.large.sect2" chunked="1"&gt;
+</programlisting>
+    
+    </sect2>
+    
     <sect2 id="write_docbook_doc.begin.id">
       <title>