[documentation-guide] Changed the order of sections a bit.
Jaromir Hradilek
jhradile at fedoraproject.org
Wed Oct 19 22:11:05 UTC 2011
commit 0771fb36e116a6a37e930685c89d4dee1cb3b493
Author: Jaromir Hradilek <jhradile at redhat.com>
Date: Wed Oct 19 22:48:56 2011 +0200
Changed the order of sections a bit.
A.k.a. refactoring.
en-US/publican.xml | 769 +++++++++++++++++++++++++---------------------------
en-US/workflow.xml | 10 +-
2 files changed, 375 insertions(+), 404 deletions(-)
---
diff --git a/en-US/publican.xml b/en-US/publican.xml
index d447950..5295d03 100644
--- a/en-US/publican.xml
+++ b/en-US/publican.xml
@@ -5,9 +5,16 @@
]>
<chapter id="chap-publican">
<title>Publican</title>
+ <!-- jhradilek: The following text is not a final; don't worry, I'll fix it. -->
<para>
<application>Publican</application> is a program that creates the end product that our customers see. The program creates html, html-single, PDF, and ePub formatted files from DocBook XML source code. The files that Publican builds can then be uploaded to a website or packaged in an RPM.
</para>
+ <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>
+ <para>
+ <application>Publican</application> uses modules called <firstterm>brands</firstterm> to add logos and color schemes to documents produced for a specific project, and thus ensures that the look of these documents is consistent. At the top right of every HTML page, the Fedora brand includes a link back to the Fedora documentation site, from a graphic containing the English word "Documentation". We can localise this graphic so that the word "Documentation appears in the same language into which the document itself is translated.
+ </para>
<section id="sect-publican-installing">
<title>Installing Publican</title>
<para>
@@ -15,436 +22,400 @@
</para>
<synopsis><command>yum</command> <option>install</option> <option>publican</option> <option>publican-fedora</option></synopsis>
<para>
- <application>Publican</application> uses modules called <firstterm>brands</firstterm> to add logos and color schemes to documents produced for a specific project, and thus ensures that the look of these documents is consistent. By default, only the <systemitem>common</systemitem> brand is installed with the <package>publican</package> package.
+ 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>.
+ </para>
+ </section>
+ <section id="sect-publican-creating">
+ <title>Creating a New Document</title>
+ <para>
+ 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 usually better to use a book.
+ </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>
<para>
- There are many brands in the 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>.
+ 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>
+ <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">
- <title>Publican Workflow</title>
+ <section id="sect-publican-validating">
+ <title>Validating XML Code</title>
<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.
+ <remark>Hic sunt leones.</remark>
</para>
- <section id="sect-publican-workflow-creating">
- <title>Creating a New Document</title>
- <para>
- 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 usually better to use a book.
- </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>
- <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>
- <para>
- <remark>Hic sunt leones.</remark>
- </para>
- </section>
- <section id="sect-publican-workflow-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-workflow-building" />.
- </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>
+ <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="sect-publican-publishing" />.
+ </para>
+ <table id="tabl-publican-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="sect-publican-publishing">
+ <title>Publishing a Document</title>
+ <para>
+ Publishing a document to the Fedora Documentation website isn't that difficult when <application>Publican</application> is doing the heavy lifting. It is assumed that you already have the repository cloned on the computer that <application>Publican</application> will be working from and that your configuration is complete.
+ </para>
+ <warning>
<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:
+ Documents produced with versions of Publican prior to 2.5 are not compatible with the current website structure. Always make sure that you have the latest version of Publican installed before you publish documents.
</para>
- <synopsis><command>publican</command> <option>build</option> <option>--publish</option> <option>--langs</option> <replaceable>languages</replaceable> <option>--formats</option> <replaceable>formats</replaceable></synopsis>
+ </warning>
+ <section id="sect-publican-publishing-preparing">
+ <title>Preparing Your System</title>
<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" />.
+ Before we start building your documents into the proper formats for user consumption we need to pull down the webpage source which you'll later add your document into and commit. The following procedure will instruct you on how to do this.
</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>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Create a local copy of the git repository of the docs.fedoraproject.org website: <command>git clone ssh://USERNAME@git.fedorahosted.org/git/docs/web.git</command> where <literal>USERNAME</literal> is your FAS username.
+ </para>
+ <note>
+ <para>
+ This download will take some time, even on fast connections.
+ </para>
+ </note>
+ </listitem>
+ <listitem>
+ <para>
+ Change into the directory into which you downloaded the <literal>web.git</literal> repo, and make a copy of <literal>homepage.tmp</literal> named <literal>homepage.cfg</literal>:<command>cp homepage.tmp homepage.cfg</command>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Edit the <literal>homepage.cfg</literal> file to provide the absolute paths to the <literal>fedoradocs.db</literal> file and the <literal>public_html</literal> directory. For example, if you downloaded the <literal>web.git</literal> repo to the <literal>fedoradocs</literal> subdirectory of your home directory, your homepage.cfg file might look like:
+ </para>
+ <programlisting>db_file: /home/jsmith/fedoradocs/web/fedoradocs.db
+toc_path: /home/jsmith/fedoradocs/web/public_html
+host: http://docs.fedoraproject.org
+title: "Fedora Documentation"
+search:</programlisting>
+ </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>
+ </para>
+ </listitem>
+ </itemizedlist>
</section>
- <section id="chap-documentation_guide-publican-workflow-Publishing_to_web">
- <title>Publishing a Document to the Web</title>
- <para>
- Publishing a document to the Fedora Documentation website isn't that difficult when <application>Publican</application> is doing the heavy lifting. It is assumed that you already have the repository cloned on the computer that <application>Publican</application> will be working from and that your configuration is complete.
- </para>
+ <section id="sect-publican-publishing-publishing">
+ <title>Publishing a Document on the Web</title>
<warning>
<para>
- Documents produced with versions of Publican prior to 2.5 are not compatible with the current website structure. Always make sure that you have the latest version of Publican installed before you publish documents.
+ Publican now controls the directory structure and the SQLite database that manages the site and its tables of contents. Do not add or remove directories from the directory tree manually as we did in the past.
</para>
</warning>
- <section id="chap-documentation_guide-publican-workflow-Publishing_to_web-Getting_setup">
- <title>Preparing Your System</title>
+ <warning>
<para>
- Before we start building your documents into the proper formats for user consumption we need to pull down the webpage source which you'll later add your document into and commit. The following procedure will instruct you on how to do this.
+ If you are publishing draft documentation, be sure to follow the instructions described at Publishing draft documentation first.
</para>
- <itemizedlist>
- <listitem>
- <para>
- Create a local copy of the git repository of the docs.fedoraproject.org website: <command>git clone ssh://USERNAME@git.fedorahosted.org/git/docs/web.git</command> where <literal>USERNAME</literal> is your FAS username.
- </para>
- <note>
- <para>
- This download will take some time, even on fast connections.
- </para>
- </note>
- </listitem>
- <listitem>
- <para>
- Change into the directory into which you downloaded the <literal>web.git</literal> repo, and make a copy of <literal>homepage.tmp</literal> named <literal>homepage.cfg</literal>:<command>cp homepage.tmp homepage.cfg</command>
- </para>
- </listitem>
- <listitem>
- <para>
- Edit the <literal>homepage.cfg</literal> file to provide the absolute paths to the <literal>fedoradocs.db</literal> file and the <literal>public_html</literal> directory. For example, if you downloaded the <literal>web.git</literal> repo to the <literal>fedoradocs</literal> subdirectory of your home directory, your homepage.cfg file might look like:
- </para>
- <programlisting>db_file: /home/jsmith/fedoradocs/web/fedoradocs.db
- toc_path: /home/jsmith/fedoradocs/web/public_html
- host: http://docs.fedoraproject.org
- title: "Fedora Documentation"
- search:</programlisting>
- </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>
- </para>
- </listitem>
- </itemizedlist>
- </section>
- <section id="chap-documentation_guide-publican-workflow-Publishing_a_Document">
- <title>Publishing a Document</title>
- <warning>
+ </warning>
+ <warning>
+ <para>
+ If you are publishing the final version of documentation that was first published in the "Draft Documentation" category, be sure to follow the instructions described at Unpublishing draft documentation first.
+ </para>
+ </warning>
+ <itemizedlist>
+ <listitem>
<para>
- Publican now controls the directory structure and the SQLite database that manages the site and its tables of contents. Do not add or remove directories from the directory tree manually as we did in the past.
+ Update your copy of the docs.fedoraproject.org website. In the directory where you keep your local copy of the site, run: <command>git pull</command>
</para>
- </warning>
- <warning>
+ </listitem>
+ <listitem>
<para>
- If you are publishing draft documentation, be sure to follow the instructions described at Publishing draft documentation first.
+ Change to the directory where you keep a checked-out copy of the document that you want to publish, then run: <command>publican build -- embedtoc -- publish -- formats epub,html,html-single,pdf -- langs LANGUAGE_CODES</command> where <literal>LANGUAGE_CODES</literal> is a comma-separated list of the languages in which you want to publish this document.
</para>
- </warning>
- <warning>
+ </listitem>
+ <listitem>
<para>
- If you are publishing the final version of documentation that was first published in the "Draft Documentation" category, be sure to follow the instructions described at Unpublishing draft documentation first.
+ Browse to the publish subdirectory and to the documents themselves inside it to ensure that the documents have built as you expected. In particular, verify the product name is <literal>Fedora</literal> (note capitalization), the version number is correct, the document title is properly capitalized and spaced: for example, <literal>Foo Guide</literal>, not <literal>foo-guide</literal>
</para>
- </warning>
- <itemizedlist>
- <listitem>
- <para>
- Update your copy of the docs.fedoraproject.org website. In the directory where you keep your local copy of the site, run: <command>git pull</command>
- </para>
- </listitem>
- <listitem>
- <para>
- Change to the directory where you keep a checked-out copy of the document that you want to publish, then run: <command>publican build -- embedtoc -- publish -- formats epub,html,html-single,pdf -- langs LANGUAGE_CODES</command> where <literal>LANGUAGE_CODES</literal> is a comma-separated list of the languages in which you want to publish this document.
- </para>
- </listitem>
- <listitem>
- <para>
- Browse to the publish subdirectory and to the documents themselves inside it to ensure that the documents have built as you expected. In particular, verify the product name is <literal>Fedora</literal> (note capitalization), the version number is correct, the document title is properly capitalized and spaced: for example, <literal>Foo Guide</literal>, not <literal>foo-guide</literal>
- </para>
- </listitem>
- <listitem>
- <para>
- Install the book to the Fedora website: <command>publican install_book --site_config PATH_TO_SITE_CONFIG_FILE --lang LANGUAGE_CODE</command> where <literal>PATH_TO_SITE_CONFIG_FILE</literal> is the path to the <literal>homepage.cfg</literal> file in your local copy of the docs.fedoraproject.org website, and <literal>LANGUAGE_CODE</literal> is the language in which you are publishing the document. Note that you can only run <command>publican install_book</command> for one language at a time.
- </para>
- </listitem>
- <listitem>
- <para>
- Change to the directory in which you keep your local copy of the site and run:
- </para>
- <screen><command>git add .</command>
+ </listitem>
+ <listitem>
+ <para>
+ Install the book to the Fedora website: <command>publican install_book --site_config PATH_TO_SITE_CONFIG_FILE --lang LANGUAGE_CODE</command> where <literal>PATH_TO_SITE_CONFIG_FILE</literal> is the path to the <literal>homepage.cfg</literal> file in your local copy of the docs.fedoraproject.org website, and <literal>LANGUAGE_CODE</literal> is the language in which you are publishing the document. Note that you can only run <command>publican install_book</command> for one language at a time.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Change to the directory in which you keep your local copy of the site and run:
+ </para>
+ <screen><command>git add .</command>
<command>git commit -m "DESCRIPTION_OF_YOUR_CHANGES"</command>
<command>git push</command></screen>
- </listitem>
- </itemizedlist>
- </section>
- <section id="chap-documentation_guide-publican-workflow-Removing_a_document">
- <title>Removing a Document from the Web</title>
- <para>
- To remove a document for a particular version of Fedora in a particular language:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- Update your copy of the docs.fedoraproject.org website. In the directory where you keep your local copy of the site, run: <command>git pull</command>
- </para>
- </listitem>
- <listitem>
- <para>
- Change to the directory where you keep a checked-out copy of the document that you want to remove, then run: <command>publican remove_book --site_config PATH_TO_SITE_CONFIG_FILE --lang LANGUAGE_CODE</command> where <literal>PATH_TO_SITE_CONFIG_FILE</literal> is the path to the <literal>homepage.cfg</literal> file in your local copy of the docs.fedoraproject.org website, and <literal>LANGUAGE_CODE</literal> is the language in which you are removing the document. Note that you can only run <command>publican remove_book</command> for one language at a time.
- </para>
- </listitem>
- <listitem>
- <para>
- Change to the directory in which you keep your local copy of the site and run:
- </para>
- <screen><command>git add .</command>
+ </listitem>
+ </itemizedlist>
+ </section>
+ <section id="sect-publican-publishing-removing">
+ <title>Removing a Document from the Web</title>
+ <para>
+ To remove a document for a particular version of Fedora in a particular language:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Update your copy of the docs.fedoraproject.org website. In the directory where you keep your local copy of the site, run: <command>git pull</command>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Change to the directory where you keep a checked-out copy of the document that you want to remove, then run: <command>publican remove_book --site_config PATH_TO_SITE_CONFIG_FILE --lang LANGUAGE_CODE</command> where <literal>PATH_TO_SITE_CONFIG_FILE</literal> is the path to the <literal>homepage.cfg</literal> file in your local copy of the docs.fedoraproject.org website, and <literal>LANGUAGE_CODE</literal> is the language in which you are removing the document. Note that you can only run <command>publican remove_book</command> for one language at a time.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Change to the directory in which you keep your local copy of the site and run:
+ </para>
+ <screen><command>git add .</command>
<command>git commit -m "DESCRIPTION_OF_YOUR_CHANGES"</command>
<command>git push</command></screen>
- </listitem>
- <listitem>
+ </listitem>
+ <listitem>
+ <para>
+ Publican can only remove the local files and directories on your system, not their record in Git. To remove the deleted files from your local Git repo, run: <command>for f in $(git ls-files --deleted); do git rm $f; done </command>. Then push these changes to the remote repo: <command>git commit -m "rm unused files" git push</command>
+ </para>
+ <warning>
<para>
- Publican can only remove the local files and directories on your system, not their record in Git. To remove the deleted files from your local Git repo, run: <command>for f in $(git ls-files --deleted); do git rm $f; done </command>. Then push these changes to the remote repo: <command>git commit -m "rm unused files" git push</command>
+ A <command>git rm</command> command gone wrong can cause widespread damage to the documentation site. If you are not absolutely sure of what you are doing, ask for help.
</para>
- <warning>
- <para>
- A <command>git rm</command> command gone wrong can cause widespread damage to the documentation site. If you are not absolutely sure of what you are doing, ask for help.
- </para>
- </warning>
- </listitem>
- </itemizedlist>
- </section>
- <section id="chap-documentation_guide-publican-workflow-Updating_a_Document">
- <title>Updating a Document</title>
- <para>
- To update a document previously published in a particular language for a particular version of Fedora, change into the directory in which you keep a checked-out copy of the document, then run <command>publican install_book</command>, as if you were installing it for the first time. Publican automatically replaces the old version with the new one.
- </para>
- </section>
+ </warning>
+ </listitem>
+ </itemizedlist>
+ </section>
+ <section id="sect-publican-publishing-updating">
+ <title>Updating a Document on the Web</title>
+ <para>
+ To update a document previously published in a particular language for a particular version of Fedora, change into the directory in which you keep a checked-out copy of the document, then run <command>publican install_book</command>, as if you were installing it for the first time. Publican automatically replaces the old version with the new one.
+ </para>
+ </section>
+ <section id="sect-publican-publishing-draft">
+ <title>Marking a Documentation as Draft</title>
+ <para>
+ Release early, release often.
+ </para>
+ <para>
+ Documents can be released before they are completely ready for the users. When this happens it's important to mark and publish the document as a draft. To do this there are three things that need to be done so that everyone knows that the guide isn't complete and ready for public consumption.
+ </para>
+ <para>
+ The first is setting the draft switch in the document itself. To do this you need to add <command>status="draft"</command> to your <literal>Doc_Name.xml</literal> file in the <literal>book</literal> or <literal>article</literal> heading so it looks like <command>book status="draft"</command>. This provides a draft watermark on all pages of the text.
+ </para>
+ <para>
+ The next task is to modify your <literal>Book_Info.xml</literal> or <literal>Article_Info.xml</literal> file. Change the <literal>productname</literal>tag to Fedora Draft Documentation and remove the contents of <literal>productnumber</literal>. Optionally, if you plan to release the document for a particular Fedora release, include the Fedora release number in the <literal>edition</literal> tag. For example, if you plan to release the book for Fedora 14, you would set edition to: <command>14.0.1</command>. Here 14.0.1 signifies Fedora 14, edition 0.1.
+ </para>
+ <para>
+ Lastly, in the <literal>Publican.cfg</literal> add the following lines: <command>version: 0.1</command> and <command>web_version_label: UNUSED</command>.
+ </para>
+ <para>
+ After completing the above tasks your guide will be sufficiently marked as draft and can safely be published to the Docs website.
+ </para>
</section>
</section>
- <section id="chap-documentation_guide-publican-Formats">
- <title>Documentation Formats</title>
- <para>
- <application>Publican</application> creates documents in four formats for users to select from: PDF, HTML, HTML-Single, and ePub.
- </para>
- </section>
- <section id="chap-documentation_guide-publican-Branding">
- <title>Publican Branding</title>
- <para>
- <application>Publican</application> uses modules called "brands" to add logos and colour schemes to documents produced for a specific project. For example, the <package>publican-fedora</package> package adds the Fedora logos and colour scheme to documents produced for the Fedora Project.
- </para>
- <para>
- At the top right of every HTML page, the Fedora brand includes a link back to the Fedora documentation site, from a graphic containing the English word "Documentation". We can localise this graphic so that the word "Documentation appears in the same language into which the document itself is translated.
- </para>
- </section>
- <section id="chap-documentation_guide-publican-draft">
- <title>Marking a Documentation as Draft</title>
- <para>
- Release early, release often.
- </para>
- <para>
- Documents can be released before they are completely ready for the users. When this happens it's important to mark and publish the document as a draft. To do this there are three things that need to be done so that everyone knows that the guide isn't complete and ready for public consumption.
- </para>
- <para>
- The first is setting the draft switch in the document itself. To do this you need to add <command>status="draft"</command> to your <literal>Doc_Name.xml</literal> file in the <literal>book</literal> or <literal>article</literal> heading so it looks like <command>book status="draft"</command>. This provides a draft watermark on all pages of the text.
- </para>
- <para>
- The next task is to modify your <literal>Book_Info.xml</literal> or <literal>Article_Info.xml</literal> file. Change the <literal>productname</literal>tag to Fedora Draft Documentation and remove the contents of <literal>productnumber</literal>. Optionally, if you plan to release the document for a particular Fedora release, include the Fedora release number in the <literal>edition</literal> tag. For example, if you plan to release the book for Fedora 14, you would set edition to: <command>14.0.1</command>. Here 14.0.1 signifies Fedora 14, edition 0.1.
- </para>
- <para>
- Lastly, in the <literal>Publican.cfg</literal> add the following lines: <command>version: 0.1</command> and <command>web_version_label: UNUSED</command>.
- </para>
- <para>
- After completing the above tasks your guide will be sufficiently marked as draft and can safely be published to the Docs website.
- </para>
- </section>
- <section id="chap-documentation_guide-publican-Building_RPMs">
- <title>Building RPMs</title>
- <para>
- <remark>Hic sunt leones.</remark>
- </para>
- </section>
- <section id="chap-documentation_guide-publican-Translations">
- <title>Translating Documentation</title>
- <para>
- Documentation translation is discussed in a separate <xref linkend="chap-documentation_guide-translations"/>.
- </para>
- </section>
- <section id="chap-documentation_guide-publican-TipsAndTricks">
- <title>Tips and Tricks</title>
+ <section id="sect-publican-packaging">
+ <title>Building RPM Packages</title>
<para>
<remark>Hic sunt leones.</remark>
</para>
diff --git a/en-US/workflow.xml b/en-US/workflow.xml
index 8b66a8d..0624dac 100644
--- a/en-US/workflow.xml
+++ b/en-US/workflow.xml
@@ -18,23 +18,23 @@
</section>
<section>
<title>Pushing Strings to Translation</title>
- <para>Pushing strings to translation is discussed in <xref linkend="chap-documentation_guide-translations"/>.</para>
+ <para>Pushing strings to translation is discussed in <xref linkend="chap-documentation_guide-translations" />.</para>
</section>
<section>
<title>Pulling Strings from Translation</title>
- <para>Pulling strings from translation is discussed in <xref linkend="chap-documentation_guide-translations"/>.</para>
+ <para>Pulling strings from translation is discussed in <xref linkend="chap-documentation_guide-translations" />.</para>
</section>
<section>
<title>Building Documents</title>
- <para>Building documents is discussed in <xref linkend="sect-publican-workflow-building"/>.</para>
+ <para>Building documents is discussed in <xref linkend="sect-publican-building" />.</para>
</section>
<section>
<title>Publishing Documents to the Web</title>
- <para>Publishing documents to the web is discussed in <xref linkend="chap-documentation_guide-publican-workflow-Publishing_to_web"/>.</para>
+ <para>Publishing documents to the web is discussed in <xref linkend="sect-publican-publishing" />.</para>
</section>
<section>
<title>Building Packages from Documents</title>
- <para>Building packages from documents is discussed in <xref linkend="chap-documentation_guide-publican-Building_RPMs"/>.</para>
+ <para>Building packages from documents is discussed in <xref linkend="sect-publican-packaging" />.</para>
</section>
</chapter>
<!--
More information about the docs-commits
mailing list