[documentation-guide] Extended the "Creating a New Document" section.

Jaromir Hradilek jhradile at fedoraproject.org
Sun Oct 2 21:32:24 UTC 2011


commit e8606d3b0ebe1ffe8661e483a8701bd32decc8c1
Author: Jaromir Hradilek <jhradile at redhat.com>
Date:   Sun Oct 2 22:35:46 2011 +0200

    Extended the "Creating a New Document" section.

 en-US/publican.xml |  116 ++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 files changed, 112 insertions(+), 4 deletions(-)
---
diff --git a/en-US/publican.xml b/en-US/publican.xml
index dd61e89..cc676e6 100644
--- a/en-US/publican.xml
+++ b/en-US/publican.xml
@@ -26,14 +26,122 @@
     <para>
       <application>Publican</application> is a command line interface (CLI) program that uses several commands for creating user files from DocBook XML source code.  <application>Publican</application> will take care of several tasks for you including building a new book or article, build the book in several formats, and create an RPM package that can be used to install the document locally onto a computer.
     </para>
-    <section id="chap-documentation_guide-publican-workflow-blank_document">
-      <title>Creating a Blank Document</title>
+    <section id="sect-publican-workflow-creating">
+      <title>Creating a New Document</title>
       <para>
-        Creating a new book or article is easy using this command: <command>publican create --name=<replaceable>Book_Name</replaceable> --brand=fedora --lang=<replaceable>language identifier</replaceable> --type=book <replaceable>or</replaceable> article.</command>  This string will create a new directory with the same name as <literal>Book_Name</literal>, with a directory of the language identifier inside the <literal>Book_Name</literal> directory.  Also created is a publican.cfg configuration file that handles some <application>Publican</application> configuration switches.
+        When creating a new document, <application>Publican</application> allows you to choose between a book and an article. Compared to books, articles have a simpler structure, do not have a preface or a separate title page, and generally tend to be much shorter. Use an article if you intend to write a text with only few pages. For a larger documents, it is usally better to use a book.
       </para>
       <para>
-        The type of document can be a bit confusing.  The type <literal>article</literal> is best used for documents that will be five pages or less.  <literal>Book</literal> on the other hand is best for documents that are longer than five pages and includes a title page, preface, and an index, among other differences.
+        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>
+      <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-workflow-creating" />.
+      </para>
+      <table id="tabl-publican-workflow-creating">
+        <title>Files created by Publican</title>
+        <tgroup cols="3">
+          <colspec colname="Book" colnum="1" colwidth="25*" />
+          <colspec colname="Article" colnum="2" colwidth="25*" />
+          <colspec colname="Description" colnum="3" colwidth="50*" />
+          <thead>
+            <row>
+              <entry>
+                Book
+              </entry>
+              <entry>
+                Article
+              </entry>
+              <entry>
+                Description
+              </entry>
+            </row>
+          </thead>
+          <tbody>
+            <row>
+              <entry>
+                <filename><replaceable>Document_Name</replaceable>.ent</filename>
+              </entry>
+              <entry>
+                <filename><replaceable>Document_Name</replaceable>.ent</filename>
+              </entry>
+              <entry>
+                Contains local entities such as <literal>YEAR</literal> and <literal>HOLDER</literal> that are used in the copyright notice.
+              </entry>
+            </row>
+            <row>
+              <entry>
+                <filename><replaceable>Document_Name</replaceable>.xml</filename>
+              </entry>
+              <entry>
+                <filename><replaceable>Document_Name</replaceable>.xml</filename>
+              </entry>
+              <entry>
+                The main XML file that includes other files. Articles are usually written in this file.
+              </entry>
+            </row>
+            <row>
+              <entry>
+                <filename>Book_Info.xml</filename>
+              </entry>
+              <entry>
+                <filename>Article_Info.xml</filename>
+              </entry>
+              <entry>
+                Contains the document metadata, such as the title, subtitle, product name, or abstract.
+              </entry>
+            </row>
+            <row>
+              <entry>
+                <filename>Author_Group.xml</filename>
+              </entry>
+              <entry>
+                <filename>Author_Group.xml</filename>
+              </entry>
+              <entry>
+                Contains information about the document authors, editors, and other contributors.
+              </entry>
+            </row>
+            <row>
+              <entry>
+                <filename>Revision_History.xml</filename>
+              </entry>
+              <entry>
+                <filename>Revision_History.xml</filename>
+              </entry>
+              <entry>
+                Contains the revision history. <application>Publican</application> uses this file when it creates an RPM package.
+              </entry>
+            </row>
+            <row>
+              <entry>
+                <filename>Preface.xml</filename>
+              </entry>
+              <entry>
+                &mdash;
+              </entry>
+              <entry>
+                Contains the default preface. Articles do not use this file.
+              </entry>
+            </row>
+            <row>
+              <entry>
+                <filename>Chapter.xml</filename>
+              </entry>
+              <entry>
+                &mdash;
+              </entry>
+              <entry>
+                Contains a template of the first chapter. Articles do not use this file and a similar template is included in the main XML file instead.
+              </entry>
+            </row>
+          </tbody>
+        </tgroup>
+      </table>
     </section>
     <section id="chap-documentation_guide-publican-workflow-validating_XML">
       <title>Validating XML Code</title>


More information about the docs-commits mailing list