Date: Wed, 2 Sep 2015 20:28:04 +0000 (UTC) From: Warren Block <wblock@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r47338 - head/en_US.ISO8859-1/books/fdp-primer/doc-build Message-ID: <201509022028.t82KS4ZY012015@repo.freebsd.org>
next in thread | raw e-mail | index | archive | help
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>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201509022028.t82KS4ZY012015>