[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>
+ —
+ </entry>
+ <entry>
+ Contains the default preface. Articles do not use this file.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <filename>Chapter.xml</filename>
+ </entry>
+ <entry>
+ —
+ </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