\input texinfo @c -*-texinfo-*-
@comment %**start of header
@setfilename orgadoc.info
@include version.texi
@settitle GNU OrgaDoc @value{VERSION}
@setchapternewpage off 

@finalout

@synindex fn cp
@synindex vr cp
@synindex tp cp

@copying

This manual is for @acronym{GNU} OrgaDoc (version @value{VERSION},
@value{UPDATED})

Copyright @copyright{} 2003-2018 Free Software Foundation, Inc.

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the @acronym{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 @acronym{GNU} Manual,'' and with the Back-Cover Texts as in
(a) below.  A copy of the license is included in the section entitled
``@acronym{GNU} Free Documentation License.''

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

@dircategory GNU programming tools
@direntry
* orgadoc: (orgadoc).       Organizes documents from XML descriptions
@end direntry

@ifset shorttitlepage-enabled
@shorttitlepage GNU OrgaDoc
@end ifset
@titlepage
@title GNU OrgaDoc User Manual
@author original program by Julien Lemoine.  C Rewrite by Adam Bilbrough.

@page
@vskip 0pt plus 1filll
@insertcopying
@sp 1
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.@*
@acronym{ISBN} 1-882114-44-2
@sp 1
Cover art by Etienne Suvasa.
@end titlepage

@contents

@node Top
@top Copyright
@insertcopying

@menu
* Goals of orgadoc:: 
* Installation:: 
* GNU OrgaDoc features:: 
* How to use it:: 
@end menu

@node Goals of orgadoc
@chapter Goals of orgadoc
@cindex goals

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

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 (@pxref{How to use it}) for details.

@node Installation
@chapter Installation
@cindex installation

Required software to use GNU OrgaDoc:
@itemize @bullet
@item libxml2
@item texi2html
@end itemize

Required software to run orgadoc_init_readmes:
@itemize @bullet
@item pdfinfo which is a part of xpdf (pdfinfo is in the xpdf-utils
package on GNU/Linux distributions such as Trisquel GNU/Linux).
@end itemize

GNU OrgaDoc uses the ./configure approach

To use GNU OrgaDoc, run these commands in user mode:
@verbatim
tar xzvf orgadoc-1.0.tar.gz
cd orgadoc-1.0
./configure <optionally add a --prefix= for a local installation>
make && make install (as sudo/superuser)
@end verbatim

@node GNU OrgaDoc features
@chapter OrgaDoc features

GNU Orgadoc uses XML files to describe your document(s) and convert them to
another format using one of the available backends:
@itemize @bullet
@item HTML: generates a HTML file which you can easily browse into your
  documentation;
@item Bibtex: convert your documents pool into a Bibtex file for reference
  into LaTex documents;
@item Latex: generates a Latex document with the details of your
 documents, you can compile this into a pdf or ps file;
@item Json: generates a JSON document with the details of your
 documents;
@item PlainText: generates a Plain Text document with the details of your
 documents;
@item Ast : dump the documents pool into ascii
@end itemize
GNU Orgadoc also works well with other programs such as grep.

@node How to use it
@chapter How to use it
@cindex howto
A directory hierarchy of documentation is needed, for example:

@verbatim
artificial_intelligence
artificial_intelligence/neural_networks
artificial_intelligence/pattern_recognition
graphics
graphics/rendering
graphics/nurbs
...
@end verbatim

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:

@itemize @bullet
@item title: the title of the document;
@item file: the filename or the directory of the document
@item date: the timestamp of the document
@item type: the kind of document (public/private)
@item author: the author of the document
@item nbpages: the number of pages;
@item language: language the document was written in;
@item summary : short resume of the document (useful for searching on
  your document pool);
@item part : you can give the principal chapter or section of your
  document
@item notes : this node is designed to add some notes about your document.
@end itemize

Here is an example of an xml file describing a directory:
@verbatim
<?xml version="1.0" ?>
<readme>
<document>
<title></title>
<file>test.pdf</file>
<date>Tue Feb  6 13:59:34 2018</date>
<type>public</type>
<author>Adam</author>
<nbpages>1</nbpages>
<language>FIXME LANGUAGE</language>
<summary>FIXME SUMMARY</summary>
<part>FIXME PART</part>
<part>FIXME PART2</part>
<notes>FIXME NOTES</notes>
</document>
<document>
<title></title>
<file>test2.pdf</file>
<date>Tue Feb  7 13:59:34 2018</date>
<type>private</type>
<author>Adam</author>
<nbpages>1</nbpages>
<language>FIXME LANGUAGE2</language>
<summary>FIXME SUMMARY2</summary>
<part>FIXME PART2</part>
<notes>FIXME NOTES2</notes>
</document>
</readme>
@end verbatim

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:
@verbatim
$ 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

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

There is also a new option of '-m' or '--merge' which will
locate the readme.xml directory from the script and merge
all readme.xml files into a single directory for
easy usage with orgadoc.
Default path is the user's home directory in '.orgadoc'.
@end verbatim
@bye
