<?xml version="1.0" encoding='ISO-8859-1'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
 "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
 <!ENTITY % cartoweb SYSTEM "../cartoweb.ent">
 %cartoweb;
]>
<!-- $Id: make_doc.xml,v 1.8 2007-07-26 13:53:23 olivier Exp $ -->
<appendix id="appendix.make_doc">
 <title>
  DocBook Documentation Generation
 </title>
 <para>
  &cartoweb; documentation source are in <ulink url=
  "http://www.docbook.org">DocBook XML</ulink> format and located in
  <filename>documentation/user_manual/source</filename> in &cartoweb;
  archive.
 </para>
 <para>
  You may want to generate it by yourself in order to produce <acronym>XHTML
  </acronym> or <acronym>PDF</acronym> output.
 </para>
 <sect1 id="appendix.make_doc.unix">
  <title>
   Documentation Generation on UNIX-like System
  </title>
  <sect2 id="appendix.make_doc.unix.tiny_docbook">
   <title>
    Tiny DocBook Install
   </title>
   <para>
    Uncompress the <ulink url=
     "http://www.cartoweb.org/downloads/docbook/tiny-docbook-1-6-16.tar.bz2">
    tiny-docbook-1-6-17.tar.bz2</ulink> archive somewhere in your filesystem.
   </para>
   <para>
    Execute:
    <screen><![CDATA[
$ ./configure --enable-install
$ make install]]></screen>
    to install and configure Tiny DocBook environment.
   </para>
  </sect2>
  <sect2 id="appendix.make_doc.unix.link">
   <title>
    Create a Symbolic Link to Documentation Source
   </title>
   <para>
    Create a symbolic link in the Tiny DocBook install directory pointing to
    the CartoWeb documentation sources <filename>
    &lt;cartoweb_home&gt;/documentation/user_manual/source</filename> , like
    that:
    <screen><![CDATA[$ ln -s CARTOWEB_HOME/documentation/user_manual/source]]></screen>
   </para>
  </sect2>
  <sect2 id="appendix.make_doc.unix.xhtml">
   <title>
    XHTML Generation
   </title>
   <para>
    Then, to generate an <acronym>XHTML</acronym> version of the
    documentation, execute as follow:
    <screen><![CDATA[
$ ./configure
$ make xhtml]]></screen>
    Output result will be generated in <filename>xhtml/</filename> directory.
   </para>
  </sect2>
  <sect2 id="appendix.make_doc.unix.pdf">
   <title>
    PDF Generation
   </title>
   <para>
    To generate a pdf version of the documentation, execute instead:
    <screen><![CDATA[
$ ./configure
$ make pdf]]></screen>
    Resulting pdf will be generated in <filename>book.pdf</filename> file.
    <note>
     <para>
      You need to have at least a <acronym>JRE</acronym> (or <acronym>JDK
      </acronym>) installed on your system in order to generate <acronym>PDF
      </acronym>. The environment variable <literal>JAVA_HOME</literal> must
      also be rightly set, e.g
      <screen><![CDATA[
$ export JAVA_HOME=dir_path_where_jre_is_put_on_your_system]]></screen>
     </para>
    </note>
   </para>
  </sect2>
 </sect1>
 <sect1 id="appendix.make_doc.cygwin">
  <title>
   Documentation Generation on Windows using Cygwin
  </title>
  <para>
   At this time, the only known way to generate xhml or pdf version of the
   documentation on Windows is by using Cygwin.
  </para>
  <para>
   You will need to install the following Cygwin packages:
   <emphasis>
    libxml2, libxslt, make
   </emphasis>
   .
  </para>
  <para>
   Then follow the same instructions as for UNIX-like system <xref linkend=
   "appendix.make_doc.unix"/>.
  </para>
 </sect1>
</appendix>
