[documentation-guide] Wrote the "Building a Document" section.

[Jaromir Hradilek]

commit 52e9c413b8365a923c3ccaf462f7c4c9ef469491
Author: Jaromir Hradilek <jhradile at redhat.com>
Date:   Sun Oct 2 23:28:11 2011 +0200

    Wrote the "Building a Document" section.

 en-US/publican.xml |  106 ++++++++++++++++++++++++++++++++++++++++++++++++++-
 en-US/workflow.xml |    2 +-
 2 files changed, 104 insertions(+), 4 deletions(-)
---
diff --git a/en-US/publican.xml b/en-US/publican.xml
index cc676e6..a4d59c8 100644
--- a/en-US/publican.xml
+++ b/en-US/publican.xml
@@ -149,11 +149,111 @@
         <remark>Hic sunt leones.</remark>
       </para>
     </section>
-    <section id="chap-documentation_guide-publican-workflow-building">
+    <section id="sect-publican-workflow-building">
       <title>Building a Document</title>
       <para>
-        <remark>Hic sunt leones.</remark>
+        To build a document in order to review it, use the following command:
+        <synopsis><command>publican</command> <option>build</option> <option>--langs</option> <replaceable>languages</replaceable> <option>--formats</option> <replaceable>formats</replaceable></synopsis>
+        where <replaceable>languages</replaceable> is a comma-separated list of language codes and <replaceable>formats</replaceable> is a comma-separated list of file formats you want to build as described in <xref linkend="tabl-publican-workflow-building" />.
+      </para>
+      <para>
+        By default, the <command>publican build</command> command stores created files in the <filename class="directory">tmp/</filename> directory where you can review the output. To build a final version of the document, add the <option>--publish</option> option as follows:
+      </para>
+      <synopsis><command>publican</command> <option>build</option> <option>--publish</option> <option>--langs</option> <replaceable>languages</replaceable> <option>--formats</option> <replaceable>formats</replaceable></synopsis>
+      <para>
+        This places the generated files in the <filename class="directory">publish/</filename> directory. If you intend to publish the document at the <ulink url="http://docs.fedoraproject.org" /> website, use also the <option>--embedtoc</option> option. For detailed information on how to publish a document on the Fedora Documentation Project website, refer to <xref linkend="chap-documentation_guide-publican-workflow-Publishing_to_web" />.
       </para>
+      <table id="tabl-publican-workflow-building">
+        <title>Available target formats</title>
+        <tgroup cols="2">
+          <colspec colname="Format" colnum="1" colwidth="25*" />
+          <colspec colname="Description" colnum="2" colwidth="75*" />
+          <thead>
+            <row>
+              <entry>
+                Format
+              </entry>
+              <entry>
+                Description
+              </entry>
+            </row>
+          </thead>
+          <tbody>
+            <row>
+              <entry>
+                <literal>html</literal>
+              </entry>
+              <entry>
+                Generates multiple HTML pages.
+              </entry>
+            </row>
+            <row>
+              <entry>
+                <literal>html-single</literal>
+              </entry>
+              <entry>
+                Generates a single HTML page.
+              </entry>
+            </row>
+            <row>
+              <entry>
+                <literal>html-desktop</literal>
+              </entry>
+              <entry>
+                Generates a single HTML page with a table of contents in a sidebar.
+              </entry>
+            </row>
+            <row>
+              <entry>
+                <literal>pdf</literal>
+              </entry>
+              <entry>
+                Generates a PDF file.
+              </entry>
+            </row>
+            <row>
+              <entry>
+                <literal>epub</literal>
+              </entry>
+              <entry>
+                Generates an EPUB file.
+              </entry>
+            </row>
+            <row>
+              <entry>
+                <literal>txt</literal>
+              </entry>
+              <entry>
+                Generates a plain text file.
+              </entry>
+            </row>
+            <row>
+              <entry>
+                <literal>man</literal>
+              </entry>
+              <entry>
+                Generates a manual page.
+              </entry>
+            </row>
+            <row>
+              <entry>
+                <literal>eclipse</literal>
+              </entry>
+              <entry>
+                Generates an Eclipse help plug-in.
+              </entry>
+            </row>
+            <row>
+              <entry>
+                <literal>test</literal>
+              </entry>
+              <entry>
+                Does not generate any files, only validates the XML files.
+              </entry>
+            </row>
+          </tbody>
+        </tgroup>
+      </table>
     </section>
     <section id="chap-documentation_guide-publican-workflow-Publishing_to_web">
       <title>Publishing a Document to the Web</title>
@@ -195,7 +295,7 @@
   host: http://docs.fedoraproject.org
   title: "Fedora Documentation"
   search:</programlisting>
-          </listitem> 
+          </listitem>
           <listitem>
             <para>
               Make sure you have the latest version of Publican and the Fedora brand package. As root, run: <command>yum update publican publican-fedora</command>
diff --git a/en-US/workflow.xml b/en-US/workflow.xml
index 807d38f..8b66a8d 100644
--- a/en-US/workflow.xml
+++ b/en-US/workflow.xml
@@ -26,7 +26,7 @@
 	</section>
 	<section>
 		<title>Building Documents</title>
-		<para>Building documents is discussed in <xref linkend="chap-documentation_guide-publican-workflow-building"/>.</para>
+		<para>Building documents is discussed in <xref linkend="sect-publican-workflow-building"/>.</para>
 	</section>
 	<section>
 		<title>Publishing Documents to the Web</title>