aboutsummaryrefslogtreecommitdiff
path: root/en_US.ISO8859-1/books/fdp-primer/doc-build
diff options
context:
space:
mode:
authorWarren Block <wblock@FreeBSD.org>2015-09-02 20:28:03 +0000
committerWarren Block <wblock@FreeBSD.org>2015-09-02 20:28:03 +0000
commit3062276fefb1fc913abfe5405e7e7fe30674fc51 (patch)
treeb3bfe5620bd489c18e35a38340f216f454a713af /en_US.ISO8859-1/books/fdp-primer/doc-build
parent9981bdebf1a82e3f8b2a73634fadce5be184710a (diff)
downloaddoc-3062276fefb1fc913abfe5405e7e7fe30674fc51.tar.gz
doc-3062276fefb1fc913abfe5405e7e7fe30674fc51.zip
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.
Notes
Notes: svn path=/head/; revision=47338
Diffstat (limited to 'en_US.ISO8859-1/books/fdp-primer/doc-build')
-rw-r--r--en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.xml70
1 files changed, 70 insertions, 0 deletions
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>