OrgaDoc 0.8

1. 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 section 4. How to use it) for details.

2. 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

make install

3. 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

4. How to use it

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>

5. 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.

6. 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

7. Usage of OrgaDoc with CVS

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.

8. CGI binary

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>

Table of Contents

1. Goals of orgadoc
2. Installation
3. OrgaDoc features
4. How to use it
5. Templates
6. Configuration file
7. Usage of OrgaDoc with CVS
8. CGI binary

Short Table of Contents

1. Goals of orgadoc
2. Installation
3. OrgaDoc features
4. How to use it
5. Templates
6. Configuration file
7. Usage of OrgaDoc with CVS
8. CGI binary

About this document

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:

• 1. Section One
  • 1.1 Subsection One-One
    • ...
  • 1.2 Subsection One-Two
    • 1.2.1 Subsubsection One-Two-One
    • 1.2.2 Subsubsection One-Two-Two
    • 1.2.3 Subsubsection One-Two-Three     <== Current Position
    • 1.2.4 Subsubsection One-Two-Four
  • 1.3 Subsection One-Three
    • ...
  • 1.4 Subsection One-Four