[documentation-guide] Minor edits for the sake of consistency.

Sat Mar 22 03:56:47 UTC 2014

commit 8b97717e2c1e12a0edb56b04a49f663d3a259b4d
Author: Jaromir Hradilek <jhradile at redhat.com>
Date:   Sat Mar 22 04:55:01 2014 +0100

    Minor edits for the sake of consistency.

 en-US/publican.xml |   43 ++++++++++++++++++++++++-------------------
 1 files changed, 24 insertions(+), 19 deletions(-)
---

diff --git a/en-US/publican.xml b/en-US/publican.xml
index 1469b33..15e6cc5 100644
--- a/en-US/publican.xml
+++ b/en-US/publican.xml
@@ -21,7 +21,7 @@
     </para>
     <synopsis><command>yum</command> <option>install</option> <option>publican</option> <option>publican-fedora</option></synopsis>
     <para>
-       By default, only the <systemitem>common</systemitem> brand is installed with the <package>publican</package> package. There are many brands in Fedora repositories, such as <systemitem>oVirt</systemitem> (<package>publican-ovirt</package>), <systemitem>JBoss</systemitem> (<package>publican-jboss</package>), or <systemitem>genome</systemitem> (<package>publican-genome</package>). For a full list of available brands, refer to the <citetitle pubwork="book">Publican Users' Guide</citetitle>.
+       By default, only the <systemitem>common</systemitem> brand is installed with the <package>publican</package> package. There are many brands in Fedora repositories, such as <systemitem>oVirt</systemitem> (<package>publican-ovirt</package>), <systemitem>JBoss</systemitem> (<package>publican-jboss</package>), or <systemitem>genome</systemitem> (<package>publican-genome</package>).
     </para>
   </section>
   <section id="sect-publican-creating">
@@ -31,17 +31,20 @@
     </para>
     <para>
       To create a new book, type the following at a shell prompt:
-      <synopsis><command>publican</command> <option>create</option> <option>--type</option> <option>book</option> <option>--name</option> "<replaceable>Document Name</replaceable>" <option>--brand</option> <replaceable>brand</replaceable></synopsis>
-
-      where <replaceable>Document Name</replaceable> is the document title and <replaceable>brand</replaceable> is the brand you want to use (this is typically <literal>fedora</literal>). Similarly, run the following command to create an article:
-      <synopsis><command>publican</command> <option>create</option> <option>--type</option> <option>article</option> <option>--name</option> "<replaceable>Document Name</replaceable>" <option>--brand</option> <replaceable>brand</replaceable></synopsis>
-      Additionally, you can specify the <option>--lang</option> option followed by a language code (such as <literal>pt-BR</literal> or <literal>cs-CZ</literal>) to write the book in a different language than English.
+    </para>
+    <synopsis><command>publican</command> <option>create</option> <option>--type</option> <option>book</option> <option>--name</option> "<replaceable>Document Name</replaceable>" <option>--brand</option> <replaceable>brand</replaceable></synopsis>
+    <para>
+      Replace <replaceable>Document Name</replaceable> with the document title and <replaceable>brand</replaceable> with the brand you want to use (typically <literal>fedora</literal>). Similarly, to create a new article, run the following command:
+    </para>
+    <synopsis><command>publican</command> <option>create</option> <option>--type</option> <option>article</option> <option>--name</option> "<replaceable>Document Name</replaceable>" <option>--brand</option> <replaceable>brand</replaceable></synopsis>
+    <para>
+      Additionally, you can specify the <option>--lang</option> option followed by a language code (such as <literal>pt-BR</literal> or <literal>cs-CZ</literal>) to write the book in a language different than English.
     </para>
     <para>
       The <command>publican create</command> command creates a new directory named <replaceable>Document_Name</replaceable>. This directory contains the <filename>publican.cfg</filename> configuration file and another directory named after the language code (that is, <filename class="directory">en-US/</filename> by default), which contains boilerplate files as described in <xref linkend="tabl-publican-creating" />.
     </para>
     <table id="tabl-publican-creating">
-      <title>Files created by Publican</title>
+      <title>Files Created By Publican</title>
       <tgroup cols="3">
         <colspec colname="Book" colnum="1" colwidth="25*" />
         <colspec colname="Article" colnum="2" colwidth="25*" />
@@ -148,25 +151,27 @@
     </para>
     <synopsis><command>publican build --langs <replaceable>languages</replaceable> --formats test</command></synopsis>
     <para>
-      Replace <replaceable>languages</replaceable> with a comma-separated list of language codes. Note that when you build a document as described in <xref linkend="sect-publican-building" />, Publican automatically validates it for you.
+      Replace <replaceable>languages</replaceable> with a comma-separated list of language codes (such as <literal>en-US</literal> or <literal>cs-CZ</literal>). Note that when you build a document as described in <xref linkend="sect-publican-building" />, Publican automatically validates it for you.
     </para>
   </section>
   <section id="sect-publican-building">
     <title>Building a Document</title>
     <para>
       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-building" />.
+    </para>
+    <synopsis><command>publican</command> <option>build</option> <option>--langs</option> <replaceable>languages</replaceable> <option>--formats</option> <replaceable>formats</replaceable></synopsis>
+    <para>
+      Replace <replaceable>languages</replaceable> with a comma-separated list of language codes (such as <literal>en-US</literal> or <literal>cs-CZ</literal>) and <replaceable>formats</replaceable> with a comma-separated list of file formats as described in <xref linkend="tabl-publican-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:
+      By default, the <command>publican build</command> command stores the 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="sect-publican-publishing" />.
+      This places the generated files in the <filename class="directory">publish/</filename> directory. For information on how to publish your document on the Fedora Documentation website, see <xref linkend="sect-publican-publishing" />.
     </para>
     <table id="tabl-publican-building">
-      <title>Available target formats</title>
+      <title>Available Target Formats</title>
       <tgroup cols="2">
         <colspec colname="Format" colnum="1" colwidth="25*" />
         <colspec colname="Description" colnum="2" colwidth="75*" />
@@ -262,15 +267,15 @@
     <section id="sect-publican-publishing-adding">
       <title>Adding a New Document</title>
       <para>
-        In order to publish an entirely new document or a new major version of an already published document on the <ulink url="http://docs.fedoraproject.org/">Fedora Documentation</ulink> website, <ulink url="https://fedorahosted.org/rel-eng/newticket">open a support ticket with Fedora Release Engineering</ulink> and request addition of the relevant RPM package name to the <systemitem>el6-docs</systemitem> repository. RPM package names of document created by Publican have the following format:
+        In order to publish an entirely new document or a new major version of an already published document on the <ulink url="http://docs.fedoraproject.org/">Fedora Documentation</ulink> website, <ulink url="https://fedorahosted.org/rel-eng/newticket">open a support ticket with Fedora Release Engineering</ulink> and request addition of the relevant RPM package name (for example <literal>Fedora-Security_Guide-19-web-en-US</literal>) to the <systemitem>el6-docs</systemitem> repository. Package names of documents created by Publican have the following format:
       </para>
       <synopsis><replaceable>product_name</replaceable>-<replaceable>document_title</replaceable>-<replaceable>product_number</replaceable>-web-<replaceable>language</replaceable></synopsis>
       <para>
-        To determine the exact package name, you can run the following command in the main directory of your document:
+        To help you determine the correct package name for your document, you can run the following command in the main directory of your document:
       </para>
       <synopsis><command>publican package --lang <replaceable>language</replaceable></command></synopsis>
       <para>
-        Replace <replaceable>language</replaceable> with a selected language code. This command packages your document as a source RPM (SRPM) and prints the absolute path to this package to standard output.
+        Replace <replaceable>language</replaceable> with a selected language code (such as <literal>en-US</literal> or <literal>cs-CZ</literal>). This command packages your document as a source RPM (SRPM) and prints the absolute path to this package to standard output.
       </para>
     </section>
     <section id="sect-publican-publishing-updating">
@@ -293,7 +298,7 @@
   <command>--firstname <replaceable>first_name</replaceable> --surname <replaceable>surname</replaceable> --email <replaceable>email</replaceable> \</command>
   <command>--member "<replaceable>description</replaceable>"</command></screen>
           <para>
-            Replace <replaceable>language</replaceable> with a selected language code, <replaceable>first_name</replaceable> with your given name, <replaceable>surname</replaceable> with your surname, <replaceable>email</replaceable> with your email address, and <replaceable>description</replaceable> with a brief description of your changes.
+            Replace <replaceable>language</replaceable> with a selected language code (such as <literal>en-US</literal> or <literal>cs-CZ</literal>), <replaceable>first_name</replaceable> with your given name, <replaceable>surname</replaceable> with your surname, <replaceable>email</replaceable> with your email address, and <replaceable>description</replaceable> with a brief description of your changes.
           </para>
         </step>
         <step>
@@ -302,7 +307,7 @@
           </para>
           <synopsis><command>publican package --lang <replaceable>language</replaceable></command></synopsis>
           <para>
-            Replace <replaceable>language</replaceable> with a selected language code. This command stores the newly created SRPM package in the <filename class="directory">tmp/rpm/</filename> directory and prints the absolute path to this file to standard output. If you intend to publish your document in more than one language, repeat this step with a different language code.
+            Replace <replaceable>language</replaceable> with a selected language code (such as <literal>en-US</literal> or <literal>cs-CZ</literal>). This command stores the newly created SRPM package in the <filename class="directory">tmp/rpm/</filename> directory and prints the absolute path to this file to standard output. If you intend to publish your document in more than one language, repeat this step with a different language code.
           </para>
         </step>
         <step>
@@ -311,7 +316,7 @@
           </para>
           <synopsis><command>koji build el6-docs <replaceable>package_name</replaceable></command></synopsis>
           <para>
-            Replace <replaceable>package_name</replaceable> with a path to the SRPM package.
+            Replace <replaceable>package_name</replaceable> with a path to the SRPM package (for example, <literal>tmp/rpm/Fedora-Security_Guide-19-web-en-US-19.1-1.el6.src.rpm</literal>).
           </para>
         </step>
       </procedure>
