<?xml version="1.0" encoding="ISO-8859-1"?>
<sect1 id="borges-compile-features-sect1">
  <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>YYYY-MM-DD</date>
        <authorinitials>tbn</authorinitials>
      </revision>
      <revision>
        <revnumber>1.en.tproof</revnumber>
        <date>YYYY-MM-DD</date>
        <authorinitials>tbn</authorinitials>
      </revision>
      <revision>
        <revnumber>1.en.write</revnumber>
        <date>2002-12-10</date>
        <authorinitials>cb</authorinitials>
      </revision>
    </revhistory></sect1info>
  <title id="borges-compile-features-sect1-ti1">Generating Final Documents</title>
  <abstract>
    <para id="borges-compile-features-sect1-pa1">Beyond the simple document generation, many advanced
    features are available to allow the user easily customizing the
    output formats or generate a set of manuals in a single
    command. We will detail all that here.</para>
  </abstract>

  <sect2>
    <title id="borges-compile-features-sect1-ti2">Single Manual Generation</title> <para id="borges-compile-features-sect1-pa2">A final manual (in a
    user readable format) is simply identified by its name followed by
    a format extension. Four formats with four extensions are
    available for &docbook; document sin &prog-borges;:<table>
	<title id="borges-compile-features-sect1-ti3">Borges Output Formats</title>
	<tgroup cols="3">
	  <colspec colwidth="1*"/>
	  <colspec colwidth="1*"/>
	  <colspec colwidth="3*"/>
	  <thead>
	    <row>
	      <entry id="borges-compile-features-sect1-en1">Format</entry>
	      <entry id="borges-compile-features-sect1-en2">Extension</entry>
	      <entry id="borges-compile-features-sect1-en3">Description</entry>
	    </row>
	  </thead>
	  <tbody>
	    <row>
	      <entry id="borges-compile-features-sect1-en4">PDF</entry> <entry id="borges-compile-features-sect1-en5">.pdf</entry> <entry id="borges-compile-features-sect1-en6"><para id="borges-compile-features-sect1-pa3">The
	      famous Adobe PDF format for printable documents with
	      readers available for all platforms.</para></entry>
	    </row>
	    <row>
	      <entry id="borges-compile-features-sect1-en7">HTML</entry> <entry id="borges-compile-features-sect1-en8">.html</entry> <entry id="borges-compile-features-sect1-en9">Standard
	      HTML format for online publishing, with chunked output:
	      the document is chunked in many different HTML files. In
	      this case <filename>My_Book.html</filename> designates a
	      directory, not a file, holding all the &html; files
	      composing the document. The entry page is
	      <filename>My_Book.html/index.html</filename></entry>
	    </row>
	    <row>
	      <entry id="borges-compile-features-sect1-en10">Flat HTML</entry> <entry id="borges-compile-features-sect1-en11">.flat.html</entry>
	      <entry id="borges-compile-features-sect1-en12">One single &html; file for the whole
	      document. Can result very big.</entry>
	    </row>
	    <row>
	      <entry id="borges-compile-features-sect1-en13">PostScript</entry>
	      <entry id="borges-compile-features-sect1-en14">.ps</entry>
	      <entry id="borges-compile-features-sect1-en15">for printable documents.</entry>
	    </row>
	  </tbody>
	</tgroup>
      </table></para>

    <para id="borges-compile-features-sect1-pa4">Knowing that all you need to do is to
    <command>make</command> the desired output. For example if you
    want to get the document <filename>Install-guide-RPM</filename>
    from the super-document <filename>Install-guide</filename> in
    English in &pdf; format, just run:</para>

    <screen id="borges-compile-features-sect1-sc1">make -C manuals/Install-guide/ Install-guide-RPM.pdf LANG=en</screen>

  </sect2>

  <sect2 id="compile-multiple">
    <title id="borges-compile-features-sect1-ti4">Generating Multiple
    Documents at Once</title> <para id="borges-compile-features-sect1-pa5">When one needs to publish
    all the manuals available in all language for his project,
    compiling them one after the other in all formats can result
    harassing. For this reason &prog-borges; provides a target to
    automatically compile any combination of
    manual-language-format.</para> <para id="borges-compile-features-sect1-pa6">The synopsis of this
    command is:

<synopsis id="borges-compile-features-sect1-sy1">make all SUBDOCS=&quot;&lt;docs list&gt;&quot; LANGS=&quot;&quot;&lt;languages list&gt;&quot; FORMATS=&quot;&quot;&lt;formats list&gt;&quot;</synopsis>

where:<variablelist>
	<varlistentry>
	  <term id="borges-compile-features-sect1-te1">docs list</term>
	  <listitem>
	    <para id="borges-compile-features-sect1-pa7">is the list of super-document/document pairs you
	    wish to generate. If you wish to get the manuals
	    <filename>Install-guide-RPM</filename> and
	    <filename>Install-guide-tar</filename> from super-document
	    <filename>Install-guide</filename>, you'll have to use
	    <option>SUBDOCS=&quot;Install-guide/Install-guide-RPM
	    Install-guide/Install-guide-tar&quot;</option></para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term id="borges-compile-features-sect1-te2">languages list</term>
	  <listitem>
	    <para id="borges-compile-features-sect1-pa8">the list of languages to get the manuals in. use
	    <option>LANGS=&quot;en fr es&quot;</option> to get all manuals in
	    English, French and Spanish.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term id="borges-compile-features-sect1-te3">formats list</term>
	  <listitem>
	    <para id="borges-compile-features-sect1-pa9">the list of extensions to compiles the manuals
	    in. If you are interested in &pdf; and flat &html; output,
	    use <option>FORMATS=&quot;pdf flat.html&quot;</option></para>
	  </listitem>
	</varlistentry>
      </variablelist>With this example we would end up with the following command line:

<programlisting id="borges-compile-features-sect1-pl1">make all SUBDOCS=&quot;Install-guide/Install-guide-RPM Install-guide/Install-guide-tar&quot; \
LANGS=&quot;en fr es&quot; FORMATS=&quot;pdf flat.html&quot;</programlisting>

Which will result in 2*3*2=12 manuals in
<filename>Outputs/</filename>.</para>
  </sect2>

 <sect2 id="compile-single-module">
  <title id="borges-compile-features-sect1-ti5">Generating a Single
   Module</title>

  <para id="borges-compile-features-sect1-pa10">When you are working
   on writing and/or translating a module, you often want to have a
   look at it in one of the supported output formats. &prog-borges;'
   single module compilation feature allows you to do so
   <emphasis>without</emphasis> the need to compile the whole document
   containing the module in question, thus leaving you more time to do
   your work instead of waiting long book compilation times.</para>

  <para id="borges-compile-features-sect1-pa11">The command synopsis
  for compiling a single module is:
   <synopsis id="borges-compile-features-sect1-sy2">
    make -C manuals/module &lt;module_name&gt;.&lt;output_format&gt; [LANG=ll]
   </synopsis>
   Note that the directory for single module compilation is always
   <literal>manuals/module</literal> regardless of which document the
   module belongs to. This directory is automatically created when
   &prog-borges; is initialized. All single module compilation output
   goes into it.</para>

  <para id="borges-compile-features-sect1-pa12">The
   <literal>LANG=ll</literal> parameter is optional and it is used to
   force compilation to occur in a language other than the default
   one. <literal>ll</literal> is the two letter lowercase &iso; code
   of the language.</para>

  <para id="borges-compile-features-sect1-pa13">For example, after issuing:
   <screen id="borges-compile-features-sect1-sc2">
    make -C manuals/module borges-compile-features-sect1.pdf LANG=es
   </screen>
   you will end up with the &pdf; file
   <filename>manuals/module/borges-compile-features-sect1.pdf</filename>
   with the contents of the
   <literal>borges-compile-features-sect1</literal> module in
   Spanish.</para>

 </sect2>
</sect1>
<!-- Keep this comment at the end of the file
Local variables:
mode: xml
sgml-parent-document: ("../../manuals/module/psgml-top.xml" "sect1")
End:
-->