Copyright
*********

   This manual is for GNU OrgaDoc (version 0.8, 28 March 2004)

   Copyright (C) 2003, 2004 Free Software Foundation, Inc.

     Permission is granted to copy, distribute and/or modify this
     document under the terms of the GNU Free Documentation License,
     Version 1.1 or any later version published by the Free Software
     Foundation; with no Invariant Sections, with the Front-Cover texts
     being "A GNU Manual," and with the Back-Cover Texts as in (a)
     below.  A copy of the license is included in the section entitled
     "GNU Free Documentation License."

     (a) The FSF's Back-Cover Text is: "You have freedom to copy and
     modify this GNU Manual, like GNU software.  Copies published by
     the Free Software Foundation raise funds for GNU development."

Goals of orgadoc
****************

OrgaDoc has been designed to easily copy and maitain a pool of
documents between computers. You can synchronise your documents pool
with rsync or unison. You don't need to install a database server (like
MySql or PostgreSql), a HTTP server, a script language (like php, perl,
...). You only need orgadoc to generate html pages and to perform
queries.

   OrgaDoc is easy to use : only the creation of some xml files
describing your documents is needed. These files can be generated. Read
the section (see How to use it) for details.

Installation
************

Needed software to compile orgadoc:
   * An eiffel compiler : SmartEiffel for example;

   * Gobo library (http://www.gobosoft.com).

   Needed software to run orgadoc_init_readmes:
   * pdfinfo which is a part of xpdf (pdfinfo is into the xpdf-utils
     package on Debian GNU/Linux).

   OrgaDoc uses the autoconf/automake facilities, therefore the end user
should use the provided configure script (some options are available)
to generate architecture specific.

   First of all, some environment variables have to be defined if your
compiler and libraries are not located in the standard path. Here is a
list of variables:

GOBO_EIFFEL: specify the eiffel vendor (se, ise or ve), default value
is se (for Smart Eiffel)
GOBO: specify the location of the gobo library, default path is
/usr/lib/gobo
SmartEiffel: give the location of SmartEiffel cluster, for exemple :
/usr/lib/smarteiffel/sys/system.se

   To compile OrgaDoc, run these commands in user mode:

tar xzvf orgadoc-0.8.0.tar.gz
cd orgadoc-0.8.0
./configure
make
 and to install OrgaDoc, run in super user mode:

make install

OrgaDoc features
****************

Orgadoc uses XML files to describe your documents and convert them to
another format using one of the available backend:
   * HTML: generates a tree of HTML files, you can easily browse into
     your   documentation;

   * Bibtex: convert your documents pool into a bibtex file for
     reference   into LaTex documents;

   * Latex: generates a latex document with the details of your
     documents base, you can compile this into a pdf or ps file.

   * Ast : dump the documents pool into ascii
   Orgadoc also includes a search tool to perform regexp queries on the
documents pool and a CGI mode to enable queries via html.

How to use it
*************

A directory hierarchy of documentation is needed, for example:

artificial_intelligence
artificial_intelligence/neural_networks
artificial_intelligence/pattern_recognition
graphics
graphics/rendering
graphics/nurbs
...

   To describes documents which are in these directories, you need to
have an xml file per directory which describes them. This file contains
a <document> node for each document of this directory.  A document node
contains a number of subnodes:

   * title: the title of the document;

   * file: the filename or the directory of the document

   * nbpages: the number of pages;

   * type: you can flag the document public or private, this option
     is usefull if you want to create a public documentation server and
      you do not have the correct permission to diffuse all documents;

   * date: creation date of the document;

   * language: language the document was written in;

   * summary : short resume of the document (useful for search on
     your documents pool);

   * url : the url where you downloaded the document;

   * part : you can give the principal chapter or section of your
     document;

   * author : authors of the document;

   * comment : this node is designed to add some comments about your
     documents. Comments are splitted in two  subnodes "author_name" and
      "content" (see the example below).

   Here is an example of an xml file describing a directory:

<?xml version="1.0" encoding="ISO-8859-1"?>
<readme>
  <document>
    <title>An Introduction To Neural Networks</title>
    <file>neuro-intro.ps</file>
    <nbpages>135</nbpages>
    <type>public</type>
    <author>Ben Krose, Patrick van der Smagt</author>
    <date>November 1996</date>
    <language>English</language>
    <summary>Neural networks, terminology, theory, topoloy,
    applications, implementations</summary>
    <part>Introduction and terminology</part>
    <part>Perceptron and Adaline</part>
    <part>Back-propagation</part>
    <part>Recurrent Networks</part>
    <part>Self-Organising Networks</part>
    <part>Reinforcement learning</part>
    <part>Applications (vision, robotics, etc...)</part>
    <url>http://www.domain.com/document/file.ps</url>
    <part>Implementations (software, hardware, etc...)</part>
    <comment>
      <author_name>Julien Lemoine</author_name>
      <content>This is a comment</content>
    </comment>
  </document>
 <document>
    <title>Neural Network and Its Application in IR</title>
    <file>uiuclis--1999-5+irg.pdf</file>
    <nbpages>31</nbpages>
    <type>public</type>
    <author>Qin He</author>
    <date>1999</date>
    <language>English</language>
    <summary>neural networks and applications in information retrieval
    systems.</summary>
  </document>
</readme>

   Some documentation can contain a piece of this information, for
example pdf documents contains the author, the number of pages...  This
information can be extracted using the orgadoc_init_readmes script.
This script takes a directory in argument, explores it recursively and
generates a readme.xml file per directory containing extractable
informations. XML section that can not be extracted are filled with a
FIXME.

   Exemple of orgadoc_init_readmes usage:

$ orgadoc_init_readmes docs
Entering directory [docs]
Leaving directory [docs]
Entering directory [docs/artifical_intelligence]
Leaving directory [docs/artifical_intelligence]
Entering directory [docs/artifical_intelligence/neural_networks]
Leaving directory [docs/artifical_intelligence/neural_networks]
Entering directory [docs/artifical_intelligence/pattern_recognition]
Leaving directory [docs/artifical_intelligence/pattern_recognition]
Entering directory [docs/graphics]
Leaving directory [docs/graphics]
Entering directory [docs/graphics/nurbs]
Leaving directory [docs/graphics/nurbs]
Entering directory [docs/graphics/rendering]
Leaving directory [docs/graphics/rendering]

readme.xml files are now created, please edit the FIXME lines
$
 Exemple of generated readme.xml file:

<?xml version="1.0" encoding="ISO-8859-1"?>
<readme>
<document>
<title>Neural Nets Report.PDF</title>
<file>uiuclis--1999-5+irg.pdf</file>
<date>Tue Aug 17 17:19:35 1999</date>
<type>public</public>
<author>Qin He</author>
<nbpages>31</nbpages>
<language>FIXME: LANGUAGE</language>
<summary>FIXME: SUMMARY</summary>
<part>FIXME: PART</part>
</document>
</readme>

Templates
*********

Orgadoc supports many backends. For each backend it use a template to
output data in a particular way. Templates are located into
/etc/orgadoc/templates, you can edit them to personalize your backend
output. A template is constitued of four files (orgadoc replaces
specific tokens by data in these files, for example %%TITLE%% is
remplaced by the title of the document)
   * global.tpl: gives the global aspect of the output;

   * document.tpl: gives the output aspect for a document;

   * comment.tpl: gives the output aspect for a comment;

   * link.tpl: gives the output aspect for link between documents
     (for html documents).

   There is currently five orgadoc backends:
   * ast : this template is used when you perform a query using the
     orgadoc command   line binary;

   * bibtex : this template is used to convert the orgadoc format
     into a bibtex file to use your documents pool in a LaTex document;

   * cgi: this template is used to generate a suitable output for cgi
     binary, it generates an html output;

   * html: used for html tree creation;

   * latex: this template is used to generate a LaTex document with   a
     small description for each document.

   Once all the xml files have been written, the orgadoc binary can be
used to generate a html tree decribing these documents (or an other
kind of backend) and perform queries on your documents pool using the
orgadoc binary (orgadoc -s) or the cgi binary.  For details on orgadoc
binary, please consult the man page.

Configuration file
******************

The orgadoc configuration file use the standard unix format for
configuration files, you can comment a line with the caracter #.

   Here is a list of configuration variable and there utility:
   * XmlFile: name of xml file to read (default: readme.xml);

   * HtmlFile: name of html file to generate (default: index.html);

   * BibTexFile: name of bibtex file to generate (default: orgadoc.bib);

   * LaTexFile: name of latex file to generate (default: orgadoc.tex);

   * InputPath: path where xml files are stored;

   * OutputPath: path to store html files;

   * EnablePrivateDoc: Boolean (True or False), if false orgadoc will
     restrict generation to public document;

   * Mode: HTML, DISPLAY, BIBTEX or LATEX. Choose the default mode
     for orgadoc output;

   * Recursive: Boolean (True of False), if True, orgadoc will
     explore ImputPath recursivelly;

   * TemplatePath: Path where orgadoc will read templates documents
     (defaults: /etc/orgadoc/templates);

   * HttpdDocPath: Httpd prefix (prefix added when orgadoc generates
     href).

   Example of orgadoc.conf file:

XmlFile                 = readme.xml
HtmlFile                = index.html
BibTexFile              = orgadoc.bib
LaTexFile               = orgadoc.tex
InputPath               = /var/www/docs/xml/orgadoc
OutputPath              = /var/www/docs/html
HttpdDocPath            = http://docs.happycoders.org
Mode                    = HTML
EnablePrivateDoc        = True
Recursive               = True
TemplatePath            = /etc/orgadoc/templates

Usage of OrgaDoc with CVS
*************************

When more than one person use orgadoc to manage a pool of documents,
there is some synchronisation problems with xml files. To solve this
problem, the suggested solution is to store xml files into a cvs
server. Keeping xml files in a different directory than documentation
is not a problem for orgadoc, therefore storing xml files in cvs works
fine.  You simply need to to a "cvs update" before running orgadoc.

   To simplify the upload of documentation on a main server, a script is
provided with orgadoc. It commits a readme.xml file and uploads
document on server with scp. A readme.xml file and a section have to be
supplied and the script do  the remaining part of the work.

   For example:

./orgadoc_add_docs /tmp/readme.xml artificial_intelligence/neural_networks
 will commit changes into readme.xml file of
artificial_intelligence/neural_networks section and scp new
documentation files.

CGI binary
**********

You can use the orgadoc cgi binary to perform regexp search on your
document pool, you simply need to send the query variable to cgi.

   Here is a example of HTML form to use with this cgi :

<FORM ACTION="cgi-bin/orgadoc_cgi" xmethod="PRE">
<P>Regexp search :
<INPUT NAME="query" SIZE="10">
<INPUT TYPE="SUBMIT" VALUE="Search">
</FORM>