incubator-cloudstack-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From seb...@apache.org
Subject git commit: refs/heads/4.1 - Docs: Adding documentation and translation chapter in dev guide
Date Thu, 07 Feb 2013 14:43:11 GMT
Updated Branches:
  refs/heads/4.1 b513448ec -> 7dd2ed12f


Docs: Adding documentation and translation chapter in dev guide


Project: http://git-wip-us.apache.org/repos/asf/incubator-cloudstack/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-cloudstack/commit/7dd2ed12
Tree: http://git-wip-us.apache.org/repos/asf/incubator-cloudstack/tree/7dd2ed12
Diff: http://git-wip-us.apache.org/repos/asf/incubator-cloudstack/diff/7dd2ed12

Branch: refs/heads/4.1
Commit: 7dd2ed12f99d6d6a560482d206039ca2330d6d4c
Parents: b513448
Author: Sebastien Goasguen <runseb@gmail.com>
Authored: Thu Feb 7 15:35:51 2013 +0100
Committer: Sebastien Goasguen <runseb@gmail.com>
Committed: Thu Feb 7 15:43:05 2013 +0100

----------------------------------------------------------------------
 docs/en-US/Developers_Guide.xml           |    1 +
 docs/en-US/building-documentation.xml     |   40 ++++++++++
 docs/en-US/building-translation.xml       |   75 ++++++++++++++++++
 docs/en-US/installing-publican.xml        |   46 +++++++++++
 docs/en-US/translating-documentation.xml  |   38 +++++++++
 docs/en-US/working-with-documentation.xml |   32 ++++++++
 docs/en-US/writing-new-documentation.xml  |  100 ++++++++++++++++++++++++
 7 files changed, 332 insertions(+), 0 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-cloudstack/blob/7dd2ed12/docs/en-US/Developers_Guide.xml
----------------------------------------------------------------------
diff --git a/docs/en-US/Developers_Guide.xml b/docs/en-US/Developers_Guide.xml
index 6299ad6..c86208b 100644
--- a/docs/en-US/Developers_Guide.xml
+++ b/docs/en-US/Developers_Guide.xml
@@ -50,6 +50,7 @@
     <xi:include href="whats-new.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
     <xi:include href="api-calls.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
     <xi:include href="working-with-usage-data.xml" xmlns:xi="http://www.w3.org/2001/XInclude"
/>
+    <xi:include href="working-with-documentation.xml" xmlns:xi="http://www.w3.org/2001/XInclude"
/>
     <xi:include href="tools.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
     <xi:include href="event-types.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
     <xi:include href="alerts.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />

http://git-wip-us.apache.org/repos/asf/incubator-cloudstack/blob/7dd2ed12/docs/en-US/building-documentation.xml
----------------------------------------------------------------------
diff --git a/docs/en-US/building-documentation.xml b/docs/en-US/building-documentation.xml
new file mode 100644
index 0000000..4848266
--- /dev/null
+++ b/docs/en-US/building-documentation.xml
@@ -0,0 +1,40 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
[
+<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
+%BOOK_ENTITIES;
+]>
+
+<!-- Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements.  See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership.  The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License.  You may obtain a copy of the License at
+ 
+   http://www.apache.org/licenses/LICENSE-2.0
+ 
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied.  See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+<section id="building-documentation">
+    <title>Building &PRODUCT; Documentation</title>
+    <para>To build a specific guide, go to the source tree of the documentation in
/docs and identify the guide you want to build.</para>
+    <para>Currenlty there are four guides plus the release notes, all defined in publican
configuration files:</para>
+    <programlisting>
+        publican-adminguide.cfg
+        publican-devguide.cfg
+        publican-installation.cfg
+        publican-plugin-niciranvp.cfg
+        publican-release-notes.cfg
+    </programlisting>
+    <para>To build the Developer guide for example, do the following:</para>
+    <programlisting>publican build --config=publican-devguide.cfg --formats=pdf --langs=en-US</programlisting>
+    <para>A pdf file will be created in tmp/en-US/pdf, you may choose to build the
guide in a different format like html. In that case just replace the format value.</para>
+    
+</section>

http://git-wip-us.apache.org/repos/asf/incubator-cloudstack/blob/7dd2ed12/docs/en-US/building-translation.xml
----------------------------------------------------------------------
diff --git a/docs/en-US/building-translation.xml b/docs/en-US/building-translation.xml
new file mode 100644
index 0000000..659c55f
--- /dev/null
+++ b/docs/en-US/building-translation.xml
@@ -0,0 +1,75 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
[
+<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
+%BOOK_ENTITIES;
+]>
+
+<!-- Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements.  See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership.  The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License.  You may obtain a copy of the License at
+ 
+   http://www.apache.org/licenses/LICENSE-2.0
+ 
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied.  See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+<section id="building-translation">
+    <title>Translating &PRODUCT; Documentation</title>
+    <para>Now that you know how to build the documentation with Publican, let's move
on to building it in different languages. Publican helps us
+          build the documentation in various languages by using Portable Object Template
(POT) files and Portable Objects (PO) files for each language.
+    </para>
+    <para>The POT files are generated by parsing all the DocBook files in the language
of origin, en-US for us, and creating a long list of strings 
+          for each file that needs to be translated. The translation can be done by hand
directly in the PO files of each target language or via the 
+          transifex service.
+     </para>
+    <note>
+        <para><ulink url="http://www.transifex.com">Transifex</ulink> is
a free service to help translate documents and organize distributed teams
+              of translators. Anyone interested in helping with the translation should get
an account on Transifex
+        </para>
+        <para>
+              Three &PRODUCT; projects exist on Transifex. It is recommended to tour
those projects to become familiar with Transifex:
+              <itemizedlist>
+                  <listitem><para><ulink url="https://www.transifex.com/projects/p/ACS_DOCS/">https://www.transifex.com/projects/p/ACS_DOCS/</ulink></para></listitem>
+                  <listitem><para><ulink url="https://www.transifex.com/projects/p/ACS_Runbook/">https://www.transifex.com/projects/p/ACS_Runbook/</ulink></para></listitem>
+                  <listitem><para><ulink url="https://www.transifex.com/projects/p/CloudStack_UI/">https://www.transifex.com/projects/p/CloudStackUI/</ulink></para></listitem>
+              </itemizedlist> 
+        </para>
+    </note>
+    <warning>
+        <para>The pot directory should already exist in the source tree. If you want
to build an up to date translation, you might have to update it to include any pot file that
was not previously generated.</para>
+        <para>To register new resources on transifex, you will need to be an admin
of the transifex &PRODUCT; site. Send an email to the developer list if you want access.</para>
+    </warning>
+    <para>First we need to generate the .pot files for all the DocBook xml files needed
for a particular guide. This is well explained at the publican website in a section on 
+    how to <ulink url="http://rlandmann.fedorapeople.org/pug/sect-Users_Guide-Preparing_a_document_for_translation.html">prepare</ulink>
a document for translation.</para>
+    <para>The basic command to execute to build the pot files for the developer guide
is:</para>
+    <programlisting>publican update_pot --config=publican-devguide.cfg</programlisting>
+    <para>This will create a pot directory with pot files in it, one for each corresponding
xml files needed to build the guide. Once genereated, all pots files need to be configured
for translation using transifex this is best done by using the transifex client that you can
install with the following command (For RHEL and its derivatives):</para>
+    <programlisting>yum install transifex-client</programlisting>
+    <para>The transifex client is also available via PyPi and you can install it like
this:</para>
+    <programlisting>easy_install transifex-client</programlisting>
+    <para>Once you have installed the transifex client you can run the <emphasis>settx.sh</emphasis>
script in the <emphasis>docs</emphasis> directory. This will create the <emphasis>.tx/config</emphasis>
file used by transifex to push and pull all translation strings.</para>
+    <para>All the resource files need to be uploaded to transifex, this is done with
the transifex client like so:</para>
+    <programlisting>tx push -s</programlisting>
+    <para>Once the translators have completed translation of the documentation, the
translated strings can be pulled from transifex like so:</para>
+    <programlisting>tx pull -a</programlisting>
+    <para>If you wish to push specific resource files or pull specific languages translation
strings, you can do so with the transifex client. A complete documentation of
+    the client is available on the <ulink url="http://help.transifex.com/features/client/">client</ulink>
website</para>
+    <para>When you pull new translation strings a directory will be created corresponding
to the language of the translation. This directory will contain PO files that will be used
by Publican to create the documentation in that specific language. For example assuming that
you pull the French translation whose language code is fr-FR, you will build the documentation
with publican:</para>
+    <programlisting>publican build --config=publican-devguide.cfg --formats=html --langs=fr-FR</programlisting>
+    <warning>
+       <para>
+            Some languages like Chinese or Japanese will not render well in pdf format and
html should be used.
+       </para>
+    </warning>
+    <xi:include href="translating-documentation.xml" xmlns:xi="http://www.w3.org/2001/XInclude"
/>
+
+</section>

http://git-wip-us.apache.org/repos/asf/incubator-cloudstack/blob/7dd2ed12/docs/en-US/installing-publican.xml
----------------------------------------------------------------------
diff --git a/docs/en-US/installing-publican.xml b/docs/en-US/installing-publican.xml
new file mode 100644
index 0000000..9f180aa
--- /dev/null
+++ b/docs/en-US/installing-publican.xml
@@ -0,0 +1,46 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
[
+<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
+%BOOK_ENTITIES;
+]>
+
+<!-- Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements.  See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership.  The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License.  You may obtain a copy of the License at
+ 
+   http://www.apache.org/licenses/LICENSE-2.0
+ 
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied.  See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+<section id="installing-publican">
+    <title>Installing Publican</title>
+    <para>&PRODUCT; documentation is built using publican. This section describes
how to install publican on your own machine so that you can build the documentation guides.</para>
+    <note>
+        <para>The &PRODUCT; documentation source code is located under <emphasis>/docs</emphasis></para>
+        <para>Publican documentation itself is also very <ulink url="http://docs.fedoraproject.org/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/chap-Users_Guide-Installing_Publican.html">useful</ulink>.</para>
+    </note>
+    <para>On RHEL and RHEL derivatives, install publican with the following command:</para>
+    <programlisting>yum install publican publican-doc</programlisting>
+    <para>On Ubuntu, install publican with the following command:</para>
+    <programlisting>apt-get install publican publican-doc</programlisting>
+    <para>For other distribution refer to the publican documentation listed above.
For latest versions of OSX you may have to install from <ulink url="https://fedorahosted.org/publican/wiki/Installing_OSX">source</ulink>
and tweak it to your own setup.</para>
+    <para>Once publican is installed, you need to setup the so-called &PRODUCT;
brand defined in the <emphasis>docs/publican-&PRODUCT;</emphasis> directory.</para>
+    <para>To do so, enter the following commands:</para>
+    <programlisting>
+        sudo cp -R publican-cloudstack /usr/share/publican/Common_Content/cloudstack
+    </programlisting>
+    <para>If this fails or you later face errors related to the brand files, see the
publican <ulink url="http://docs.fedoraproject.org/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/chap-Users_Guide-Branding.html#sect-Users_Guide-Installing_a_brand">documentation</ulink>.</para>
+    <para>With publican installed and the &PRODUCT; brand files in place, you should
be able to build any documentation guide.</para>
+
+
+</section>

http://git-wip-us.apache.org/repos/asf/incubator-cloudstack/blob/7dd2ed12/docs/en-US/translating-documentation.xml
----------------------------------------------------------------------
diff --git a/docs/en-US/translating-documentation.xml b/docs/en-US/translating-documentation.xml
new file mode 100644
index 0000000..afe2765
--- /dev/null
+++ b/docs/en-US/translating-documentation.xml
@@ -0,0 +1,38 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
[
+<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
+%BOOK_ENTITIES;
+]>
+
+<!-- Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements.  See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership.  The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License.  You may obtain a copy of the License at
+ 
+   http://www.apache.org/licenses/LICENSE-2.0
+ 
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied.  See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+<section id="translating-documentation">
+    <title>Translating &PRODUCT; Documentation</title>
+
+    <para>There are two ways to translate the documentation:</para>
+    <para>
+        <itemizedlist>
+            <listitem><para>Directly using the Transifex website and using their
user interface.</para></listitem>
+            <listitem><para>Using the Transifex client and pushing your translated
strings to the website.</para></listitem>
+        </itemizedlist>
+    </para>
+    <para>Once a translation is complete, a site admin will pull the translated strings
within the &PRODUCT; repository, build the documenation and publish it.</para>
+    <para>For instructions on how to use the Transifex website see <ulink url="http://sebgoa.blogspot.ch/2012/11/translating-apache-cloudstack-docs-with.html">http://sebgoa.blogspot.ch/2012/11/translating-apache-cloudstack-docs-with.html</ulink></para>
+    <para>For instructions on how to use the Transifex client to translate from the
command line see <ulink url="http://sebgoa.blogspot.ch/2012/12/using-transifex-client-to-translate.html">http://sebgoa.blogspot.ch/2012/12/using-transifex-client-to-translate.html</ulink></para>
+</section>

http://git-wip-us.apache.org/repos/asf/incubator-cloudstack/blob/7dd2ed12/docs/en-US/working-with-documentation.xml
----------------------------------------------------------------------
diff --git a/docs/en-US/working-with-documentation.xml b/docs/en-US/working-with-documentation.xml
new file mode 100644
index 0000000..6774842
--- /dev/null
+++ b/docs/en-US/working-with-documentation.xml
@@ -0,0 +1,32 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
[
+<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
+%BOOK_ENTITIES;
+]>
+
+<!-- Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements.  See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership.  The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License.  You may obtain a copy of the License at
+ 
+   http://www.apache.org/licenses/LICENSE-2.0
+ 
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied.  See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+<chapter id="working-with-documentation">
+  <title>Preparing and Building &PRODUCT; Documentation</title>
+  <para>This chapter describes how to install publican, how to write new documentation
and build a guide as well as how to build a translated version of the documentation using
transifex</para>
+  <xi:include href="installing-publican.xml" xmlns:xi="http://www.w3.org/2001/XInclude"
/>
+  <xi:include href="building-documentation.xml" xmlns:xi="http://www.w3.org/2001/XInclude"
/>
+  <xi:include href="writing-new-documentation.xml" xmlns:xi="http://www.w3.org/2001/XInclude"
/>
+  <xi:include href="building-translation.xml" xmlns:xi="http://www.w3.org/2001/XInclude"
/>
+</chapter>

http://git-wip-us.apache.org/repos/asf/incubator-cloudstack/blob/7dd2ed12/docs/en-US/writing-new-documentation.xml
----------------------------------------------------------------------
diff --git a/docs/en-US/writing-new-documentation.xml b/docs/en-US/writing-new-documentation.xml
new file mode 100644
index 0000000..340900e
--- /dev/null
+++ b/docs/en-US/writing-new-documentation.xml
@@ -0,0 +1,100 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
[
+<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
+%BOOK_ENTITIES;
+]>
+
+<!-- Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements.  See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership.  The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License.  You may obtain a copy of the License at
+ 
+   http://www.apache.org/licenses/LICENSE-2.0
+ 
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied.  See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+<section id="writing-new-documentation">
+    <title>Writing &PRODUCT; Documentation</title>
+    <para>&PRODUCT; documentation is written in DocBook xml format. Each guide
defined with a publican configuration file refers to a DocBook <emphasis>book</emphasis>.</para>

+    <para>These books are defined in xml files in docs/en-US, for instance if we look
at the Developers guide, its configuration file contains:</para>
+    <programlisting>
+        xml_lang: en-US
+        type: Book
+        docname: Developers_Guide
+        brand: cloudstack
+        chunk_first: 1
+        chunk_section_depth: 1
+    </programlisting>
+    <para>The <emphasis>docname</emphasis> key gives you the basename of
the DocBook file located in the en-US directory that contains the description of the book.</para>
+    <para>Looking closely at Developers_Guide.xml we see that it contains <emphasis>book</emphasis>
tags and several references to other xml files. These are the chapters of the book, currently
they are:</para>
+    <programlisting>
+    <![CDATA[
+        <xi:include href="concepts.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+        <xi:include href="building-with-maven.xml" xmlns:xi="http://www.w3.org/2001/XInclude"
/>
+        <xi:include href="developer-introduction.xml" xmlns:xi="http://www.w3.org/2001/XInclude"
/>
+        <xi:include href="whats-new.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+        <xi:include href="api-calls.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+        <xi:include href="working-with-usage-data.xml" xmlns:xi="http://www.w3.org/2001/XInclude"
/>
+        <xi:include href="working-with-documentation.xml" xmlns:xi="http://www.w3.org/2001/XInclude"
/>
+        <xi:include href="tools.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+        <xi:include href="event-types.xml" xmlns:xi="http://www.w3.org/2001/XInclude"
/>
+        <xi:include href="alerts.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+        <xi:include href="time-zones.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+        <xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude"
/>
+    ]]>
+    </programlisting>
+    <para>All these xml files are written in DocBook format.</para>
+    <note>
+        <para>DocBook format is well <ulink url="http://www.docbook.org/tdg5/en/html/docbook.html">documented</ulink>,
refer to the documentation for any questions about DocBook tags</para>
+    </note>
+    <para>When writing documentation, you therefore need to located the book,chapter
and section of the content you want to write/correct.
+    Or create a new book,chapter,section.</para>
+    <para>You will then learn much more about DocBook tagging. In order to write this
chapter about documentation, I added the <emphasis>working-with-documentation.xml</emphasis>file
describing a chapter in the Developer book and I created several sections within that chapter
like so:</para>
+    <programlisting>
+    <![CDATA[
+        <chapter id="working-with-documentation">
+            <title>Preparing and Building &PRODUCT; Documentation</title>
+            <para>This chapter describes how to install publican, how to write new
documentation and build a guide as well as how to build a translated version of the documentation
using transifex</para>
+            <xi:include href="installing-publican.xml" xmlns:xi="http://www.w3.org/2001/XInclude"
/>
+            <xi:include href="building-documentation.xml" xmlns:xi="http://www.w3.org/2001/XInclude"
/>
+            <xi:include href="writing-new-documentation.xml" xmlns:xi="http://www.w3.org/2001/XInclude"
/>
+            <xi:include href="building-translation.xml" xmlns:xi="http://www.w3.org/2001/XInclude"
/>
+        </chapter>
+    ]]>
+    </programlisting>
+
+    <para>Note the id witin the chapter tag, it represents the basename of the xml
file describing the chapter.</para>
+    <para>For translation purposes it is important that this basename be less than
50 characters long.</para>
+
+    <para>This chapter also refers to xml files which contains each section. While
you could embed the sections directly in the chapter file and as a matter of fact also write
the chapters within a single book file. Breaking things up in smaller files at the granularity
of the section, allows us to re-use any section to build different books.</para>
+    <para>For completeness here is an example of a section:</para>
+    <programlisting>
+    <![CDATA[
+        <section id="building-documentation">
+            <title>Building &PRODUCT; Documentation</title>
+            <para>To build a specific guide, go to the source tree of the documentation
in /docs and identify the guide you want to build.</para>
+            <para>Currenlty there are four guides plus the release notes, all defined
in publican configuration files:</para>
+            <programlisting>
+               publican-adminguide.cfg
+               publican-devguide.cfg
+               publican-installation.cfg
+               publican-plugin-niciranvp.cfg
+               publican-release-notes.cfg
+            </programlisting>
+            <para>To build the Developer guide for example, do the following:</para>
+            <programlisting>publican build --config=publican-devguide.cfg --formats=pdf
--langs=en-US</programlisting>
+            <para>A pdf file will be created in tmp/en-US/pdf, you may choose to build
the guide in a different format like html. In that case just replace the format value.</para>
+        </section>
+    ]]>
+    </programlisting>
+    <para>Happy Publicaning and DocBooking.</para>
+</section>


Mime
View raw message