os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Add a skeletally brief overview of the FORMATS variable and actually show how

Browse source 
to build an output file.  Both of these are things might be of more than
academic value to someone working on the documentation.
This commit is contained in:
Warren Block 2015-09-02 20:28:03 +00:00
parent 9981bdebf1
commit 3062276fef
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=47338
1 changed files with 70 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

70
en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.xml
View file

@ -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>