<?xml version="1.0" encoding="ISO-8859-1"?>
<sect1 id="borges-writing-features" lang="⟨">
<sect1info>
<!-- Please, do NOT edit the following revision history by hand. Use the
"make <module_name>.revision" target instead. -->
<revhistory><revision><revnumber>0.8</revnumber><date>YYYY-MM-DD</date><authorinitials>tbn</authorinitials><revremark>write</revremark> </revision><revision><revnumber>0.8</revnumber><date>YYYY-MM-DD</date><authorinitials>tbn</authorinitials><revremark>translate</revremark> </revision><revision><revnumber>0.8</revnumber><date>YYYY-MM-DD</date><authorinitials>tbn</authorinitials><revremark>tproof</revremark> </revision><revision><revnumber>0.8</revnumber><date>YYYY-MM-DD</date><authorinitials>tbn</authorinitials><revremark>pproof</revremark> </revision><revision><revnumber>0.8</revnumber><date>YYYY-MM-DD</date><authorinitials>tbn</authorinitials><revremark>ispell</revremark> </revision><revision><revnumber>0.8</revnumber><date>YYYY-MM-DD</date><authorinitials>tbn</authorinitials><revremark>lproof</revremark> </revision>
<revision>
<revnumber>1.en.lproof</revnumber>
<date>YYYY-MM-DD</date>
<authorinitials>tbn</authorinitials>
</revision>
<revision>
<revnumber>1.en.ispell</revnumber>
<date>YYYY-MM-DD</date>
<authorinitials>tbn</authorinitials>
</revision>
<revision>
<revnumber>1.en.pproof</revnumber>
<date>2002-07-22</date>
<authorinitials>jp</authorinitials>
</revision>
<revision>
<revnumber>1.en.tproof</revnumber>
<date>2002-07-03</date>
<authorinitials>cb</authorinitials>
</revision>
<revision>
<revnumber>1.en.write</revnumber>
<date>2002-06-18</date>
<authorinitials>fm</authorinitials>
</revision>
</revhistory>
</sect1info>
<title id="borges-writing-features-ti1">Documents Writing</title>
<abstract>
<para id="borges-writing-features-pa1">Following is a review of the
configuration files' format and the required elements on
<filename>master.top.xml</filename> for the revision system to
work. All the necessary elements to create your documents for your
projects, from global entities to documents compilation, are
detailed in this section also.</para>
</abstract>
<sect2>
<title id="borges-writing-features-ti2">Configuration Files</title>
<para id="borges-writing-features-pa2">Following is an in-depth
review of &prog-borges;' configuration files and their
format.</para>
<sect3 id="borges-writing-features-conf-author">
<title id="borges-writing-features-ti3">conf/author.xml</title>
<para id="borges-writing-features-pa3">This file holds information
related to the author (writer, translator, etc.) who will use the
system. Each author <emphasis>must</emphasis> define it in order
to use the revision system and to be able to compile
documents.</para>
<programlisting id="borges-writing-features-pl1"><![CDATA[
<?xml version='1.0' encoding='ISO-8859-1'?>
<author>
<initials>pp</initials>
<firstname>Peter</firstname>
<lastname>Pingus</lastname>
<mail>peter.pingus@mandrakesoft.com</mail>
<lang>en</lang>
</author>
]]></programlisting>
<itemizedlist>
<listitem>
<para id="borges-writing-features-pa4"><literal><initials></literal>
holds the author's initials. Most likely two lowercase letters,
the initials are used as a <emphasis>unique</emphasis>
identifier to distinguish among different
authors. Mandatory.</para>
</listitem>
<listitem>
<para id="borges-writing-features-pa5"><literal><firstname></literal>
holds the author's name and <literal><lastname></literal>
holds the author's lastname. Optional.</para>
</listitem>
<listitem>
<para id="borges-writing-features-pa6"><literal><mail></literal>
holds the author's e-mail address. Optional, but necessary for
email alerts</para>
</listitem>
<listitem>
<para id="borges-writing-features-pa7"><literal><lang></literal>
holds the author's preferred language. Note that we use the word
<quote>preferred</quote> because the language can be overridden
with the <literal>LANG=</literal> parameter when doing
compilations. However, for revision control the language cannot
be forced with the <literal>LANG=</literal> parameter and the
one defined in <literal><lang></literal> is used.
Mandatory.</para>
</listitem>
</itemizedlist>
</sect3>
<sect3 id="borges-writing-features-conf-default">
<title id="borges-writing-features-ti4">conf/manual-default.xml</title>
<para id="borges-writing-features-pa8">This file holds the
configuration parameters of the style-sheets to use <emphasis>by
default</emphasis> when producing &pdf; and &html; output. <!--
Please refer to XREF_TO_SSHEET_CUSTOMIZATION_HERE for details on
how to customize the default style-sheets to fit your particular
needs. --></para>
<programlisting id="borges-writing-features-pl2"><![CDATA[
<?xml version='1.0' encoding='ISO-8859-1'?>
<configuration>
<stylesheet>
<dssslprint>../drivers/docbook-jadetex.dsssl</dssslprint>
<xslxhtmlchunk>../drivers/docbook-xhtml-chunk.xsl</xslxhtmlchunk>
<xslxhtmlflat>../drivers/docbook-xhtml.xsl</xslxhtmlflat>
</stylesheet>
</configuration>
]]></programlisting>
<itemizedlist>
<listitem>
<para id="borges-writing-features-pa9"><literal><dssslprint></literal>
holds the &dsssl; style-sheet used for &tex; transformation of
the document to prepare it for printing. Mandatory.</para>
</listitem>
<listitem>
<para id="borges-writing-features-pa10"><literal><xslxhtmlchunk></literal>
holds the &xsl; style-sheet used for &xhtml; transformation of
the document into <emphasis>different</emphasis> &xhtml; files
for online publication. Mandatory.</para>
</listitem>
<listitem>
<para id="borges-writing-features-pa11"><literal><xslxhtmlflat></literal>
holds the &xsl; style-sheet used for &xhtml; transformation of
the document into <emphasis>a single</emphasis> &xhtml; file for
online publication. Mandatory.</para>
</listitem>
</itemizedlist>
<!--
<note>
<para>The <literal>ROOTDIR</literal> variable is defined in the
<filename>Makefile</filename> file placed in the
<quote>top</quote> or <quote>root</quote> directory of your
project. (<filename>~/My_Project</filename> in the examples given
in <xref linkend="first-project-borges"/>)</para>
</note>
-->
</sect3>
<sect3 id="borges-writing-features-conf-perdocument">
<title id="borges-writing-features-ti5">manuals/My_Book/conf.xml</title>
<para id="borges-writing-features-pa12">This file holds the
configuration parameters of the style-sheets to use when producing
&pdf; and &html; output, as well as <quote>aliases</quote> and
exclusion information for deriving various documents from a single
super-document. By default this file is the copy of the
<filename>conf/manual-default.xml</filename> file above.</para>
<programlisting id="borges-writing-features-pl3"><![CDATA[
<?xml version='1.0' encoding='ISO-8859-1'?>
<configuration>
<stylesheet>
<dssslprint>../drivers/docbook-jadetex.dsssl</dssslprint>
<xslxhtmlchunk>../drivers/docbook-xhtml-chunk.xsl</xslxhtmlchunk>
<xslxhtmlflat>../drivers/docbook-xhtml.xsl</xslxhtmlflat>
</stylesheet>
<manuals>
<manual id="Some_Book">
<lang>en</lang>
<format>pdf</format>
<exclude>VPN</exclude>
</manual>
<manual id="Another_Book">
<lang>en</lang>
<format>pdf</format>
<exclude>VPN</exclude>
<exclude>booklet</exclude>
</manual>
</manuals>
</configuration>
]]></programlisting>
<note>
<para id="borges-writing-features-pa13"><literal><stylesheet></literal>
contains the same parameters as before. Please, refer to <xref linkend="borges-writing-features-conf-default"/> for more
information on it.</para>
</note>
<itemizedlist>
<listitem>
<para id="borges-writing-features-pa14"><literal><manual></literal>
holds configuration information of exclusions for one
document. The <literal>id</literal> attribute <emphasis>must be
unique among all projects</emphasis>. Optional.</para>
</listitem>
<listitem>
<para id="borges-writing-features-pa15"><literal><exclude></literal>
holds the name of the <quote>flags</quote> to exclude in
conditional-compilation of the document. Mandatory.</para>
</listitem>
</itemizedlist>
<para id="borges-writing-features-pa16">With the sample
<filename>manuals/My_Book/conf.xml</filename> above, issuing
<screen id="borges-writing-features-sc1">
make -C manuals/My_Book Some_Book.pdf
</screen>
will compile a &pdf; file named
<filename>manuals/My_Book/Some_Book.pdf</filename> excluding all
elements marked with <literal>condition="VPN"</literal>; issuing
<screen id="borges-writing-features-sc2">
make -C manuals/My_Book Another_Book.pdf
</screen>
will compile a &pdf; file named
<filename>manuals/My_Book/Another_Book.pdf</filename> excluding
all elements marked with <literal>condition="VPN"</literal> and
also all elements marked with
<literal>condition="booklet"</literal>.</para>
<para id="borges-writing-features-pa17">Please refer to <xref linkend="borges-writing-features-subcompilation"/> for more
information on conditional-compilation.</para>
</sect3>
<sect3 id="borges-writing-features-conf-repository">
<title id="borges-writing-features-ti6">conf/repository.xml</title>
<para id="borges-writing-features-pa18">This file is the most
important configuration files because it's the top configuration
file for the whole &prog-borges; project.</para>
<programlisting id="borges-writing-features-pl4"><![CDATA[
<?xml version='1.0' encoding='iso-8859-1'?>
<configuration>
<repository>
<title>My Book Project</title>
<paths>
<modules>modules</modules>
<manuals>manuals</manuals>
</paths>
<outputs>
<makefile>/usr/share/Borges/backend/Makefile.DB</makefile>
</outputs>
<manuals>
<manual>My_Book</manual>
</manuals>
<languages>
<lang>en</lang>
<lang>fr</lang>
<lang>es</lang>
</languages>
<revisions>
<type>
<name>lproof</name>
<author>tbn</author>
</type>
<type>
<name>ispell</name>
<author>tbn</author>
</type>
<type>
<name>pproof</name>
<author>tbn</author>
</type>
<type>
<name>tproof</name>
<author>tbn</author>
</type>
<type>
<name>translate</name>
<author>tbn</author>
</type>
<type>
<name>write</name>
<author>tbn</author>
</type>
</revisions>
</repository>
</configuration>
]]></programlisting>
<itemizedlist>
<listitem>
<para id="borges-writing-features-pa19"><literal><title></literal>
holds the project's name. This is used as the title in the
reports generated by &prog-borges; report
facilities. Mandatory.</para>
</listitem>
<listitem>
<para id="borges-writing-features-pa20"><literal><paths></literal>
holds the paths where the different documents and their modules
are located. The defaults are a safe bet, so it is recommended
not to change them. Mandatory.
<itemizedlist>
<listitem>
<para id="borges-writing-features-pa21"><literal><modules></literal> holds the modules'
<quote>top</quote> directory. Mandatory.</para>
</listitem>
<listitem>
<para id="borges-writing-features-pa22"><literal><manuals></literal> holds the documents'
<quote>top</quote> directory. Mandatory.</para>
</listitem>
</itemizedlist>
</para>
</listitem>
<listitem>
<para id="borges-writing-features-pa23"><literal><outputs></literal>
holds the location of the template output
<filename>Makefile</filename> files. Template output make files
are used for the different &dtd;s &prog-borges; supports. At the
moment of this writing, only the DocBook &dtd; was supported
(hence, the <literal>.DB</literal> file name extension). You can
put as many <literal><makefile></literal> entries as you
like. Mandatory.</para>
</listitem>
<listitem>
<para id="borges-writing-features-pa24"><literal><manuals></literal>
holds the directory name of the different documents, with one
<literal><manual></literal> entry per document. There
<emphasis>must</emphasis> be at least one entry.
Mandatory.</para>
<caution>
<para id="borges-writing-features-pa25">It is highly recommended not to add here any manual
by hand. Use the <command>make adddoc</command> command
instead. See <xref linkend="first-project-borges-document-adddoc"/>.</para>
</caution>
<tip>
<para id="borges-writing-features-pa26">Even if &os-linux;
supports the space character in path names, it is
<emphasis>recommended</emphasis> not to use them here. You can
use the hyphen (<literal>-</literal>) or the underscore
(<literal>_</literal>) as word separators for path
names.</para>
</tip>
</listitem>
<listitem>
<para id="borges-writing-features-pa27"><literal><languages></literal>
holds the languages supported by all documents, one
<literal><lang></literal> entry per language containing
the two letter &iso; code (in lowercase) for that language. At
least one language <emphasis>must</emphasis> be
defined. Mandatory.</para>
<caution>
<para id="borges-writing-features-pa28">It is highly recommended not to add here any
language by hand but the first one. Use the <command>make
addlang</command> command instead. See <xref linkend="borges-addlang"/>.</para>
</caution>
<!-- FABITOREM: tproof reader, please check if the order in which
lang entries are defined IS important or not. If it is
important, then please explain its importance. Once that is
done, please wipe this comment out. Thx. -->
</listitem>
<listitem>
<para id="borges-writing-features-pa29"><literal><revisions></literal>
holds the revision types managed by the revision system. The
order in which they appear define the work-flow of the
document's modules. At the moment of this writing, neither the
names of the revision types nor their order can be changed,
however the initials of the <quote>default</quote> author
responsible for a specific revision can be set. Mandatory.
<itemizedlist>
<listitem>
<para id="borges-writing-features-pa30"><literal><name></literal>
holds the name of the revision: <literal>write</literal>, for
module's writing; <literal>translate</literal> for module's
translation; <literal>tproof</literal> for module's technical
proofreading; <literal>pproof</literal> for module's
pedagogical proofreading, <literal>ispell</literal> for
module's spell-checking and <literal>lproof</literal> for
module's idiomatic proofreading. Mandatory.</para>
<note>
<para id="borges-writing-features-pa31">Translations of the
modules will <emphasis>only</emphasis> have
<literal>translate</literal>, <literal>ispell</literal> and
<literal>lproof</literal> revision types.</para>
</note>
</listitem>
<listitem>
<para id="borges-writing-features-pa32"><literal><author></literal>
holds the <quote>default</quote> author initials for a
revision type. If no author is assigned to a revision type
yet, <literal>tbn</literal> (To Be Named)
<emphasis>must</emphasis> be used. Mandatory.</para>
</listitem>
</itemizedlist>
</para>
</listitem>
<listitem>
<para id="borges-writing-features-pa33"><literal><server></literal>
holds the parameters related to remote compilation and/or
validation of &xml; files. This is not yet implemented in
&prog-borges;.
<!--
<itemizedlist>
<listitem>
<para><literal><name></literal> holds the remote server
name. A fully qualified domain name <emphasis>must</emphasis>
be used here. Mandatory.</para>
</listitem>
<listitem>
<para><literal><localip></literal> holds the &ip;
address of the remote server for the scenarios where such
server resides in your &lan; network. Optional(?).</para>
</listitem>
<listitem>
<para><literal><ip></literal> holds the &ip; address of
the remote server for accessing it through the
Internet. Mandatory(?).</para>
</listitem>
<listitem>
<para><literal><robot></literal> holds the name of the
robot script to execute for reports updating and confirmation
mails sent to authors with their <quote>still to be
done</quote> work. Mandatory.</para>
</listitem>
</itemizedlist>
-->
</para>
</listitem>
</itemizedlist>
</sect3>
<sect3 id="borges-writing-features-revisions">
<title id="borges-writing-features-ti7">master.top.xml and the Revision System</title>
<para id="borges-writing-features-pa34">The <literal><revhistory></literal> part of the
<filename>master.top.xml</filename> file plays an important role
in the revision system of &prog-borges; <!-- for documents that
are going to be translated into multiple languages -->.</para>
<para id="borges-writing-features-pa35">Below you have a sample <literal><revhistory></literal>
part:
<programlisting id="borges-writing-features-pl5"><![CDATA[
<revhistory>
<revision lang="en">
<revnumber>1</revnumber>
<date>2002-06-04</date>
<authorinitials>pp</authorinitials>
<revremark>First Draft</revremark>
</revision>
<revision lang="fr">
<revnumber>1</revnumber>
<date>2002-06-14</date>
<authorinitials>pt</authorinitials>
<revremark>Begin French Translation</revremark>
</revision>
<revision lang="es">
<revnumber>1</revnumber>
<date>2002-06-10</date>
<authorinitials>rp</authorinitials>
<revremark>Begin Spanish Translation</revremark>
</revision>
</revhistory>
]]></programlisting>
</para>
<para id="borges-writing-features-pa36">Each
<literal><revision></literal> entry contains data related to
one of the translations of the document. It has a
<literal>lang</literal> attribute with the two letter &iso; code
(in lowercase) of the language. There <emphasis>must</emphasis> be
at least one such entry which also has the following:
<itemizedlist>
<listitem>
<para id="borges-writing-features-pa37"><literal><revnumber></literal>
contains the revision number (or edition number) of the
document. Generally, it is an integer value starting at
<literal>1</literal> and incrementing for each major revision
(or edition) of the document. Optional<footnote> <para id="borges-writing-features-pa38">This will be used in future
versions of &prog-borges; for major documents
revisions.</para></footnote>.</para>
</listitem>
<listitem>
<para id="borges-writing-features-pa39"><literal><date></literal>
contains the date at which work on the corresponding language
started. This is used by the report facility of &prog-borges;
to estimate finishing dates for the revisions; in the sample
above, work has begun on the French revision on June, the
10<superscript>th</superscript>, 2002. The format is
<literal>YYYY-MM-DD</literal>. Mandatory.</para>
</listitem>
<listitem>
<para id="borges-writing-features-pa40"><literal><authorinitials></literal>
contains the initials (unique identifier) of the author
responsible for that revision. Optional.</para>
</listitem>
<listitem>
<para id="borges-writing-features-pa41"><literal><revremark></literal>
contains remarks on the revision itself. This remark is
<emphasis>not</emphasis> rendered with the default &dsssl;
style-sheet provided by &prog-borges; for printed documents, so
you'll need to customize the style-sheet if you want the
remarks to be printed. Optional.</para>
</listitem>
</itemizedlist>
</para>
</sect3>
</sect2>
<sect2>
<title id="borges-writing-features-ti8">Document Creation Features</title>
<para id="borges-writing-features-pa42">In the following sections
the document creation features of &prog-borges; will be
detailed. The sections are not presented in any particular
order.</para>
<sect3 id="borges-writing-features-global-entities">
<title id="borges-writing-features-ti9">Global Entities</title>
<para id="borges-writing-features-pa43">Global entities are those
entities that you intend to use <emphasis>without any change at
all</emphasis> among all versions of a project and/or among all
your projects. They reside under the
<filename>entities/</filename> directory and are &xml; files with
file names ending in <literal>.ent</literal></para>
<para id="borges-writing-features-pa44">Put all entities which
<emphasis>neither</emphasis> change from one language to another
<emphasis>nor</emphasis> from one document to another under
<filename>entities/</filename>.</para>
<para id="borges-writing-features-pa45">Put all entities which
<emphasis>do</emphasis> change from one language to another,
<emphasis>but do not</emphasis> change from one document to
another under <filename>entities/ll/</filename>, where
<literal>ll</literal> is the &iso; two letter code (in lowercase)
for the language in question.</para>
<para id="borges-writing-features-pa46">Good candidates for global entities are:
<itemizedlist>
<listitem>
<para id="borges-writing-features-pa47">Company names;</para>
</listitem>
<listitem>
<para id="borges-writing-features-pa48">Program (software) names;</para>
</listitem>
<listitem>
<para id="borges-writing-features-pa49">Operating Systems names.</para>
</listitem>
<listitem>
<para id="borges-writing-features-pa50">Most acronyms<footnote><para id="borges-writing-features-pa51">Acronyms are used
<quote>almost</quote> without change among all
languages/projects. One that does change, for example, is
&isdn; which is <acronym>RDSI</acronym> in
Spanish.</para></footnote>.</para>
</listitem>
</itemizedlist>
</para>
</sect3>
<sect3 id="borges-writing-features-images">
<title id="borges-writing-features-ti10">Images</title>
<para id="borges-writing-features-pa52">Including images in your
work is as easy as inserting a <literal><figure></literal>
element in your modules. For example:
<programlisting id="borges-writing-features-pl6"><![CDATA[
<figure>
<title>An Amazing Figure</title>
<mediaobject>
<imageobject>
<imagedata align="center" fileref="images/image_file_name.png"
format="PNG"/>
</imageobject>
</mediaobject>
</figure>
]]></programlisting>
will insert a &png; image contained in the file named
<filename>image_file_name.png</filename>, aligned in the center of
the page with <quote>An Amazing Figure</quote> (without the
quotes) as its title.</para>
<para id="borges-writing-features-pa53">Needless to say,
&prog-borges; will take care of finding the
<filename>image_file_name.png</filename> file for you in the
corresponding <filename>images/ll/</filename> directory, where
<literal>ll</literal> is the two letter &iso; code (in lowercase)
of the language the module will be compiled into.</para>
<para id="borges-writing-features-pa54">You can also put
language-neutral images under the <filename>images/</filename>
directory and &prog-borges; will get them from there.</para>
<para id="borges-writing-features-pa55">Images formats available in
your documents are &png; (<literal>format="PNG"</literal>), &pdf;
(<literal>format="PDF"</literal>) and &eps;
(<literal>format="EPS"</literal>). &prog-borges; will
automatically make them available at the right place for
you.</para>
<bridgehead id="borges-writing-features-bh1">Missing Images</bridgehead>
<para id="borges-writing-features-pa56">In case that you insert an image in a module and you
forget to make the image itself, the system will replace it by a
default image, so that the compilation is not broken. The image
used by default is <filename>images/missing.jpg</filename> and you can
replace it by whatever you want.</para>
<mediaobject>
<imageobject>
<imagedata fileref="images/missing.png" width="6cm" align="center"/>
</imageobject>
</mediaobject>
<para id="borges-writing-features-pa57">Additionally, whenever
&prog-borges; finds a missing image, it will report it in the
<filename><manual>.missing.xx.img</filename> text file. So if
you just compiled a document (say <literal>UserGuide</literal>)
in French and you note some images are missing (showing the
default missing image) you can get the list of missing images by
printing
<filename>manuals/UserGuide/UserGuide.missing.fr.img</filename>. You
can also generate directly that file to check no more images are
missing by simply running <command>make -C manuals/UserGuide/
UserGuide.missing.fr.img</command></para>
</sect3>
<sect3>
<title id="borges-writing-features-ti11">Index Support</title>
<para id="borges-writing-features-pa58">&docbook; is able to
generate an automatic index by collecting all index terms found
in the source document. &prog-borges; will automatically
generate such index provided you request it in the master
document. If you want an index to be added at the end of your
book, simply end your <filename>master.top.xml</filename> in:
<programlisting id="borges-writing-features-pl7"><![CDATA[
<index id="index">
<title>Index </title>
<para>Automatic Index Here.</para>
</index>
</book>
]]></programlisting></para>
</sect3>
<sect3 id="borges-writing-features-subcompilation">
<title id="borges-writing-features-ti12">Specialized Books for
Different Needs</title>
<para id="borges-writing-features-pa59">Often you need to make
small variations on your book to fit different audiences, for
example a technical manual for a family of products with only
small differences among each other.</para>
<para id="borges-writing-features-pa60">So, instead of writing
different books for the different audiences, it would be desirable
to have the possibility to write <emphasis>one</emphasis> set of
modules for all audiences and have different parts excluded from
the different documentation for each audience.</para>
<para id="borges-writing-features-pa61">&prog-borges; makes this
possible thanks to <quote>conditional
compilation</quote>. Conditional compilation allows you to
<quote>mark</quote> some parts of your modules or entire modules
in order to exclude them in certain compilations, but not in
others.</para>
<para id="borges-writing-features-pa62">Let's take an
example. You are writing a user manual for the
<literal>Tortoise</literal> operating system running on both
<literal>Intel</literal> and <literal>Sparc</literal>
architectures. There are only minor differences between both
guides.</para>
<para id="borges-writing-features-pa63">You just need to add the
<literal>condition="i386"</literal> attribute to mark an element
(section, paragraph, phrase, note, warning, tip, etc.) as being
only valid for the <literal>Intel</literal> version. Likewise mark
elements specific to the <literal>Sparc</literal> version with
<literal>condition="sparc"</literal>. If the element appears to be
an entire module, add the attribute in the
<literal>master</literal> file:
<programlisting id="borges-writing-features-pl8"><![CDATA[
<sect1 condition="i386">
<title>Some Title</title>
<para role="module">some_sect-sect1</para>
<para>Introduce here the Tortoise OS, highlighting Intel specifications.</para>
</sect1>
]]></programlisting>
You then need to tell &prog-borges; how to derive both userguides
from the <literal>Tortoise-UserGuide</literal>
super-document. This is done in the super document configuration
file <xref linkend="borges-writing-features-conf-perdocument"/>. For our
example, this file could be:
<programlisting id="borges-writing-features-pl9" revision="1"><![CDATA[
<?xml version='1.0' encoding='ISO-8859-1'?>
<configuration>
<stylesheet>
<dssslprint>../drivers/docbook-jadetex.dsssl</dssslprint>
<xslxhtmlchunk>../drivers/docbook-xhtml-chunk.xsl</xslxhtmlchunk>
<xslxhtmlflat>../drivers/docbook-xhtml.xsl</xslxhtmlflat>
</stylesheet>
<manuals>
<manual>
<exclude>sparc</exclude>
</manual>
<manual id="Tortoise-Sparc">
<exclude>i386</exclude>
</manual>
</manuals>
</configuration>
]]></programlisting>
That done, issuing
<screen id="borges-writing-features-sc3">
make -C manuals/My_Book Tortoise-i386.pdf
</screen>
will compile the whole book into &pdf; discarding the elements
with <literal>condition="sparc"</literal>.</para>
</sect3>
<sect3 id="borges-writing-features-validation">
<title id="borges-writing-features-ti13">Document Validation</title>
<para id="borges-writing-features-pa64">From time to time, it is
<emphasis>recommended</emphasis> to check your modules are valid
&xml;. Issue
<screen id="borges-writing-features-sc4">
make -C manuals/My_Book master.validate
</screen>
to validate your whole super-document for your preferred (working)
language.</para>
<tip>
<para id="borges-writing-features-pa65">Use the
<literal>LANG=ll</literal> parameter to validate in a language
other than your preferred language. <literal>ll</literal> is the
&iso; two letter code (in lowercase) for the language you want to
validate the document into.</para>
</tip>
<para id="borges-writing-features-pa66">At the moment of this
writing the validation process is a parsing of the whole &xml;
code of the document, there are no other validation constraints
checked yet.</para>
</sect3>
<sect3 id="borges-writing-features-transparentparas">
<title id="borges-writing-features-ti14">Making Translated
Paragraphs Transparent to the Revision System</title>
<para id="borges-writing-features-pa67">When translating a module
into a foreign language it often happens that the translator wants
to add a footnote with translator notes or a few clarification
words in a separate paragraph. Also, some licenses (for example
the &gpl; and the &gfdl;) <emphasis>require</emphasis> that you
include some portion of it in the original language.</para>
<para id="borges-writing-features-pa68">&prog-borges;' automated
revisions management system will report differences among the
translated module and the original module only because of those
added footnotes/paragraphs, even if they are
<emphasis>correct</emphasis> or <emphasis>necessary</emphasis> in
some cases; so, how can you make those paragraphs
<quote>invisible</quote> to the revision system?</para>
<para id="borges-writing-features-pa69">&prog-borges; solves this
<quote>problem</quote> in an elegant way which does not break
DocBook compatibility by using the
<literal>revision="-1"</literal> attribute. For example:
<screen id="borges-writing-features-sc5">
<para revision="-1">En otro idioma</para>
</screen>
will exclude that paragraph (in Spanish, in the example) when
comparing against the original looking for differences in
revisions.</para>
<para id="borges-writing-features-pa70">This way, you can have those <quote>extra</quote> paragraphs
in your translation without worrying about the revisions report
being wrong all the time just because of them.</para>
<!-- Is this really a planned needed feature ? (Camille)
<note>
<para>At the moment of this writing, it is not possible to have
revision management work with such paragraphs. However this is a
planned feature (using <literal>revision="-2"</literal>,
<literal>revision="-3"</literal>, etc.)</para>
</note>
-->
</sect3>
</sect2>
<sect2>
<title id="borges-writing-features-ti15">Document modification features</title>
<para id="borges-writing-features-pa71">Whenever you modify the structure of a super-document it is
necessary to inform the system of such modifications. That will
particularly build the module templates for the added
modules.</para>
<para id="borges-writing-features-pa72">Simply run the <command>make alltemplates</command> command.</para>
<para id="borges-writing-features-pa73">When this is done, to not forget to add the generated
templates to your &cvs; repository, if any.</para>
</sect2>
<sect2 id="borges-addlang">
<title id="borges-writing-features-ti16">Adding new languages to the system</title>
<para id="borges-writing-features-pa74">When one of your documents needs to
be translated, or simply when you decide that one of the
documents will need to be translated, it is time to make the
system aware of this new language. This is done in one
single command:
<programlisting id="borges-writing-features-pl10">make addlang LANG=ll</programlisting>
that will declare the new <literal>ll</literal><footnote>
<para id="borges-writing-features-pa75"><literal>ll</literal> being the two letters
<acronym>ISO</acronym> code for that lanaguage. See <ulink url="http://ftp.ics.uci.edu/pub/ietf/http/related/iso639.txt">ISO
639</ulink>.</para> </footnote> language document for the
whole project. It will actually perform the following
tasks:<itemizedlist>
<listitem>
<para id="borges-writing-features-pa76">Update
<filename>conf/repository.xml</filename>;</para>
</listitem>
<listitem>
<para id="borges-writing-features-pa77">create all
language specific directories for modules, images,
entities, etc.;</para>
</listitem>
<listitem>
<para id="borges-writing-features-pa78">copy entities files from the
default one (first in the list of languages in the main
configuration file) to the new language
directories;</para>
</listitem>
<listitem>
<para id="borges-writing-features-pa79">Make all module
templates for this new language for all defined
documents;</para>
</listitem>
<listitem>
<para id="borges-writing-features-pa80">Add all new
files to the <acronym>CVS</acronym> repository, if
available. Note that you'll still need to commit those
files by hand;</para>
</listitem>
</itemizedlist> Once this is done translators will have to<orderedlist>
<listitem>
<para id="borges-writing-features-pa81">Translate entities in
<filename>manuals/My_Doc/ll/*.ent</filename>;</para>
</listitem>
<listitem>
<para id="borges-writing-features-pa82">Translate entities in
<filename>entities/*.ent</filename>;</para>
</listitem>
<listitem>
<para id="borges-writing-features-pa83">Translate modules in
<filename>modules/ll/*.xml</filename>;</para>
</listitem>
<listitem>
<para id="borges-writing-features-pa84">Take snapshots and translate
diagrams from <filename>images/xx/</filename> to
<filename>images/ll/</filename>, <literal>xx</literal> being
another language for which images have already been
created.i</para>
</listitem>
</orderedlist></para>
</sect2>
</sect1>
<!-- Keep this comment at the end of the file
Local variables:
mode: xml
sgml-parent-document: ("../../manuals/Borges-doc/master.top.xml" "sect1")
End:
-->
distrib
>
Mandriva
>
9.1
>
ppc
>
media
>
main
>
by-pkgid
>
6c1629ca18f6adf273e73d0f5069fa8c
>
files
>
340
