svn commit: r47338 - head/en_US.ISO8859-1/books/fdp-primer/doc-build

[Warren Block]

Author: wblock
Date: Wed Sep  2 20:28:03 2015
New Revision: 47338
URL: https://svnweb.freebsd.org/changeset/doc/47338

Log:
  Add a skeletally brief overview of the FORMATS variable and actually show how
  to build an output file.  Both of these are things might be of more than
  academic value to someone working on the documentation.

Modified:
  head/en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.xml

Modified: head/en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.xml	Wed Sep  2 15:20:47 2015	(r47337)
+++ head/en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.xml	Wed Sep  2 20:28:03 2015	(r47338)
@@ -36,6 +36,76 @@
   <para>This chapter covers organization of the documentation build
     process and how &man.make.1; is used to control it.</para>
 
+  <sect1 xml:id="doc-build-rendering">
+    <title>Rendering DocBook into Output</title>
+
+    <para>Different types of output can be produced from a single
+      DocBook source file.  The type of output desired is set with the
+      <varname>FORMATS</varname> variable.  A list of known formats is
+      stored in <varname>KNOWN_FORMATS</varname>:</para>
+
+    <screen xml:id="doc-build-rendering-known-formats">&prompt.user; <userinput>cd ~/doc/en_US.ISO8859-1/books/handbook</userinput>
+&prompt.user; <userinput>make -V KNOWN_FORMATS</userinput></screen>
+
+    <table xml:id="doc-build-rendering-common-formats" frame="none">
+      <title>Common Output Formats</title>
+
+      <tgroup cols="3">
+	<thead>
+	  <row>
+	    <entry><varname>FORMATS</varname> Value</entry>
+	    <entry>File Type</entry>
+	    <entry>Description</entry>
+	  </row>
+	</thead>
+
+	<tbody>
+	  <row>
+	    <entry><literal>html</literal></entry>
+	    <entry><acronym>HTML</acronym>, one file</entry>
+	    <entry>A single <filename>book.html</filename> or
+	      <filename>article.html</filename>.</entry>
+	  </row>
+
+	  <row>
+	    <entry><literal>html-split</literal></entry>
+	    <entry><acronym>HTML</acronym>, multiple files</entry>
+	    <entry>Multiple <acronym>HTML</acronym> files, one for
+	      each chapter or section, for use on a typical web
+	      site.</entry>
+	  </row>
+
+	  <row>
+	    <entry><literal>pdf</literal></entry>
+	    <entry><acronym>PDF</acronym></entry>
+	    <entry>Portable Document Format</entry>
+	  </row>
+	</tbody>
+      </tgroup>
+    </table>
+
+    <para>The default output format can vary by document, but is
+      usually <literal>html-split</literal>.  Other formats are chosen
+      by setting <varname>FORMATS</varname> to a specific value.
+      Multiple output formats can be created at a single time by
+      setting <varname>FORMATS</varname> to a list of formats.</para>
+
+    <example xml:id="doc-build-formats-example-html">
+      <title>Build a Single HTML Output File</title>
+
+      <screen>&prompt.user; <userinput>cd ~/doc/en_US.ISO8859-1/books/handbook</userinput>
+&prompt.user; <userinput>make FORMATS=html</userinput></screen>
+    </example>
+
+    <example xml:id="doc-build-formats-example-html-split-pdf">
+      <title>Build HTML-Split and <acronym>PDF</acronym> Output
+	Files</title>
+
+      <screen>&prompt.user; <userinput>cd ~/doc/en_US.ISO8859-1/books/handbook</userinput>
+&prompt.user; <userinput>make FORMATS="html-split pdf"</userinput></screen>
+    </example>
+  </sect1>
+
   <sect1 xml:id="doc-build-toolset">
     <title>The &os; Documentation Build Toolset</title>