<?xml version="1.0" encoding="ISO-8859-1"?>
<chapter>
  <chapterinfo>

<!-- 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>cb</authorinitials>
      </revision>
      <revision>
        <revnumber>1.en.translate</revnumber>
        <date>YYYY-MM-DD</date>
        <authorinitials>tbn</authorinitials>
      </revision>
      <revision>
        <revnumber>1.en.write</revnumber>
        <date>YYYY-MM-DD</date>
        <authorinitials>tbn</authorinitials>
      </revision>
    </revhistory></chapterinfo>
  <title>Programer's Reference manual</title>

  <abstract>
    <para>We will get here into &prog-borges; internals. This may be
    of interest for the developer as well as for the user wishing to
    take advantage of the most advanced feaures of
    &prog-borges;.</para>
  </abstract>

  <para>If something is not clear enough below, or if you wish to know
  more, use the source luke. If there's something you definitely not
  understand, ask on &prog-borges; mailing list.</para>

  <sect1>
    <title>Makefiles</title> 

    <para>We will list here the different Makefiles available in
    &prog-borges; source repository and in the implemented
    repositories<footnote> <para>It is important to distinguish
    between the &prog-borges; source repository, which is the
    repository holding all the &prog-borges; code maintained by its
    developers; and a simple implementation of &prog-borges;, which is
    a documentation project repository, holding the documentaion
    source files managed by &prog-borges;.</para></footnote>. We will
    detail the way those Makefiles are generated, distributed,
    etc.</para>

    <sect2>
      <title>Borges source Makefile</title> <para>There's only one
      usable Makefile here. You'll find it at the root of the
      repository.</para>
      <para>This Makefile has two main targets:<variablelist>
	  <varlistentry>
	    <term>doc</term>
	    <listitem>
	      <para>compiles the &prog-borges; documentation and reports;</para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>install</term>
	    <listitem>
	      <para>installs &prog-borges; on a system so that users
	      of that system can start documentation projects on it,
	      using &prog-borges;. It installs all the scripts and
	      Makefile's and build a repository template so that users
	      can quickly start using &prog-borges;.</para>
	      <tip>
		<para>&prog-borges; gets instralled in
		<filename>/usr/share</filename> by default
		(<filename>/usr/share/Borges/</filename>). You can
		change that by passing the
		<parameter>TARGET</parameter> parameter to
		<command>make</command>. For example if you wish to
		relocate &prog-borges; to
		<filename>/home/joe/test/Borges/</filename> just run
		<command>make install
		TARGET=/home/joe/test</command></para>
	      </tip>
	    </listitem>
	  </varlistentry>
	</variablelist></para>

      <para>you may have noticed that &prog-borges; does not need
      compilation. Indeed all scripts are in perl or bash and do not
      need compilation.</para>
    </sect2>

    <sect2>
      <title>Documentatin Projects Makefiles</title>
      <sect3>
	<title>What Goes Where</title> <para>The diagram below shows
	how the different Makefiles provided by &prog-borges; are
	distributed in the implementation repository.</para>
      </sect3>
      <sect3>
	<title>Who Calls Who</title> <para>The following diagram shows
	how the Makefiles found in the &prog-borges; source repository
	(on the left) gets distributed into an imaginary project (on
	the right) with two books <literal>Book1</literal> and
	<literal>Book2</literal> in two languages
	<literal>en</literal> and <literal>fr</literal></para>
	<figure>
	  <title>Distributing Makefiles</title>
	  <mediaobject>
	    <imageobject>
	      <imagedata fileref="images/borges-makefiles-where.pdf" format="EPS" scale="80"/>
	    </imageobject>
	    <imageobject>
	      <imagedata fileref="images/borges-makefiles-where.png" format="PNG"/>
	    </imageobject>
	  </mediaobject>
	</figure>
      </sect3>
    </sect2>

    <sect2>
      <title>Makefiles in Action</title> <para>We will show here how
      Makefiles are linked together. <xref linkend="borges-makefiles"/> shows how Makefiles include each
      others. An arrow in the diagram means
      <quote>includes</quote>.</para>
	<figure id="borges-makefiles">
	  <title>Makefiles Relatiunships</title>
	  <mediaobject>
	    <imageobject>
	      <imagedata fileref="images/borges-makefiles.pdf" format="EPS" scale="80"/>
	    </imageobject>
	    <imageobject>
	      <imagedata fileref="images/borges-makefiles.png" format="PNG"/>
	    </imageobject>
	  </mediaobject>
	</figure>
      <para>All paths are relative to the project root dir unless
      otherwise stated.</para>
      <para>We can distinguish between four types:<variablelist>
	  <varlistentry>
	    <term>Production</term>
	    <listitem>
	      <para>The Makefiles on the left are the ones actually
      used to perform tasks on manuals, modules, images, etc.</para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>manuals/Book/Makefile.include</term>
	    <listitem>
	      <para>This Makefile is empty by default. It can be used
	      by advanced users to redefine default manual compilation
	      rules. See <xref linkend="custom-rules"/> for more
	      details.</para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>Makefile.DB</term>
	    <listitem>
	      <para>This Makefile contains the rules to actually
	      transform source XML DocBook files to any desired output
	      format (PDF, HTML, etc.). Advanced users may choose to
	      develop their own <filename>Makefile.XXX</filename> to
	      support another DTD. See <xref linkend="custom-dtd"/>
	      for more details on how to do that.</para> <para>To
	      determine which Makefile is used to generate output
	      formats, the system looks for the &lt;makefile&gt;
	      element(s) in <filename>conf/repository.xml</filename>
	      and sets the <parameter>OUTPUTS</parameter> variable
	      accordingly in the root
	      <filename>Makefile.include</filename> described
	      below.</para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>Makefile.include</term>
	    <listitem>
	      <para>This Makefile is automatically generated by the
	      root Makefile. It contains useful information for all
	      other Makefiles, extracted from the environment and
	      notably from the naim configuration file
	      <filename>conf/reposqitory.xml</filename>. It contains
	      also some generic functions and rules.</para>
	    </listitem>
	  </varlistentry>
	</variablelist></para>
    </sect2>
  </sect1>


  <sect1>
    <title>The Way a Manual is Generated</title>

    <para>To understand the process leading to the generation of a
    final document, we'll detail here the steps taken to generate an
    HTML file.</para>

    <para>In <xref linkend="borges-compilation-scheme"/> we represent the
    way from the <filename>master.top.xml</filename> skeleton
    guideleines to the final HTML book.</para>

    <figure id="borges-compilation-scheme">
      <title>Distributing Makefiles</title>
      <mediaobject>
	<imageobject>
	  <imagedata fileref="images/borges-compilation-scheme.pdf" format="EPS" scale="45"/>
	</imageobject>
	<imageobject>
	  <imagedata fileref="images/borges-compilation-scheme.png" format="PNG"/>
	</imageobject>
      </mediaobject>
    </figure>

    <para>We can distinguish two main steps:<orderedlist>
	<listitem>
	  <formalpara>
	    <title>Generation of the
	    <filename>&lt;book&gt;.flat.xml</filename> source
	    file</title> <para>This file contains all the XML source
	    code necessary to compile the document. It is
	    <quote>flat</quote> because all modules and entities have
	    been expanded into it. To do so it's been necessary to:<itemizedlist>
		<listitem>
		  <para>Compute a possible index,</para>
		</listitem>
		<listitem>
		  <para>Check all needed modules are available.</para>
		</listitem>
		<listitem>
		  <para>Catalog all entities.</para>
		</listitem>
	      </itemizedlist></para></formalpara>
	</listitem>
	<listitem>
	  <formalpara>
	    <title>Actual HTML Compilation</title> <para>This includes
	    the generation of all necessary images which names are
	    extracted from
	    <filename>&lt;book&gt;.flat.xml</filename>.</para>
	  </formalpara>
	</listitem>
      </orderedlist></para>


  </sect1>


  <sect1 id="custom-rules">
    <title>Adding/changing Manuals Rules</title> <para>It may happen
    that the rules provided to prepare the
    <filename>master.flat.xml</filename> are not suited for a
    particular need. Or the user may want to override some rules for
    generating output formats.</para> <para>&prog-borges; provides a
    mean to do that easily. One just need to write its custom or
    tweaked rule in
    <filename>manuals/&lt;Book&gt;/Makefile.include</filename>. That will
    add extra functionnality for generating output formats or
    overwrite default rules. </para>
  </sect1>


  <sect1 id="custom-dtd">
    <title>Supporting Another DTD than DocBook</title>
    <para>To Be Written</para>
  </sect1>

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