GNU OrgaDoc 0.9 User Manual

by Julien Lemoine. Maintained by Adam Bilbrough.

This manual is for GNU OrgaDoc (version 0.9, 24 April 2017)

Copyright © 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.”



Published by the Free Software Foundation
59 Temple Place, Suite 330
Boston, MA 02111-1307 USA
Printed copies are available from the Free Software Foundation.
ISBN 1-882114-44-2



Cover art by Etienne Suvasa.


[ < ] [ > ]   [Contents] [Index] [ ? ]

Copyright

This manual is for GNU OrgaDoc (version 0.9, 24 April 2017)

Copyright © 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.”


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1 Goals of orgadoc

GNU OrgaDoc has been designed to easily copy and maintain a pool of documents between computers. You can synchronize your document(s) 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.

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


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2 Installation

Required software to compile GNU OrgaDoc:

Required software to run orgadoc_init_readmes:

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

First of all, 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 GNU 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 GNU OrgaDoc, run in super user mode:

make install

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3 OrgaDoc features

GNU Orgadoc uses XML files to describe your document(s) and convert them to another format using one of the available backends:

GNU Orgadoc also includes a search tool to perform regex queries on the document pool and a CGI mode to enable queries via html.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4 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 describe documents which are in these directories, you need to have an xml file for each directory which describes them. This file contains a <document> node for each document of this directory. A document node contains a number of subnodes:

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 as an argument, explores it recursively and generates a readme.xml file for each directory containing extractable information. XML sections that can not be extracted are filled with a FIXME.

Example 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
$

Example of the 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>

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5 Templates

GNU Orgadoc supports many backends. For each backend it uses a template to output data in a particular way. Templates are located in /usr/local/etc/orgadoc/templates, you can edit them to personalize your backend output. A template consists of four files (orgadoc replaces specific tokens by data in these files, for example %%TITLE%% is replaced by the title of the document)

There are currently five GNU OrgaDoc backends:

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


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6 Configuration file

The OrgaDoc configuration file uses the standard UNIX format for configuration files, you can comment a line with the character #.

Here is a list of configuration variables and their use:

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            = /usr/local/etc/orgadoc/templates

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7 Usage of OrgaDoc with CVS

When more than one person uses OrgaDoc to manage a pool of documents, there is some synchronization problems with xml files. To solve this problem, the suggested solution is to store xml files in 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 do “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 the document onto a server with SCP. A readme.xml file and a section have to be supplied and the script will do the rest.

For example:

./orgadoc_add_docs /tmp/readme.xml artificial_intelligence/neural_networks

will commit changes into the readme.xml file of artificial_intelligence/neural_networks section and SCP new documentation files.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8 CGI binary

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

Here is an example of a 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>

[Top] [Contents] [Index] [ ? ]

Table of Contents


[Top] [Contents] [Index] [ ? ]

About This Document

This document was generated on May 12, 2017 using texi2html 5.0.

The buttons in the navigation panels have the following meaning:

Button Name Go to From 1.2.3 go to
[ << ] FastBack Beginning of this chapter or previous chapter 1
[ < ] Back Previous section in reading order 1.2.2
[ Up ] Up Up section 1.2
[ > ] Forward Next section in reading order 1.2.4
[ >> ] FastForward Next chapter 2
[Top] Top Cover (top) of document  
[Contents] Contents Table of contents  
[Index] Index Index  
[ ? ] About About (help)  

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


This document was generated on May 12, 2017 using texi2html 5.0.