From 3062276fefb1fc913abfe5405e7e7fe30674fc51 Mon Sep 17 00:00:00 2001
From: Warren Block <wblock@FreeBSD.org>
Date: Wed, 2 Sep 2015 20:28:03 +0000
Subject: [PATCH] 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.

---
 .../books/fdp-primer/doc-build/chapter.xml    | 70 +++++++++++++++++++
 1 file changed, 70 insertions(+)

diff --git a/en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.xml
index 26efed2eb4..d2ef3545dd 100644
--- a/en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.xml
+++ b/en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.xml
@@ -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>