[OpenSER-Docs] First Clean-up Patch for Documentation

[Henning Westerholt]

On Wednesday 27 February 2008, Daniel-Constantin Mierla wrote:
> your points are very good. It is the skeleton/template we have to define
> primary. Here I see couple of items you should take in consideration:
> - ability to generate standalone readme per module and aggregate all in
> single document. Perhaps here we can have two documets in each module,
> one that will have the head/tag of a book, and the other, head/tag of a
> chapter -- they will be very small, just including the other documents.

Hi Daniel, hi Edson,

your suggestions sounds good. Yes, it would be nice to generate a document 
containing all the module documentation. For this the existing 'set' 
docbook-xml tag could be used. This allows the combination of several books 
to one bigger compilation.

> - module names, parameters name, function names, PV names, ..., must be
> clearly marked so we can extract very easy the index. You did the
> previous indexes in dokuwiki, and you know better how hard is to do it
> with the current structure.
> - the generated html formats should have all the time same anchor for
> parameters, functions, a.s.o, so that the reference will stay the same,
> even new elements are introduced. If I am not wrong, that is possible by
> setting an unique 'id'. In this way, links sent to mailing list, in the
> indexes, will be persistent over the years.

If we have a unique id per chapter/ section, then this could be easily done. 
The whole id stuff is for example documented at:
http://opensource.bureau-cornavin.com/crash-course/en/doc-structure.html

> To my first point, a proposal of files will be
> - name_book.xml - will have structure of a book and include name.xml
> - name_chapter.xml - will have structure of a chapter and include
> name.xml (to investigate whether won't be same as name.xml)
> - name.xml - similar to what is now name.sgml -- details about author,
> editor, etc... and include the other files
> - name_admin.xml - will contain the documentation for administrators --
> same as name_users.sgml, just the 'users' is a bit unclear and thought
> 'admin' might be better
> - name_devel.xml. and others will be added as needed

Each file we add here increases the overhead for processing. And both 
of 'name_admin.xml' and 'name_devel.xml' are separate chapters anyway, so i 
don't think that we need the 'name_chapter.xml' file. And the "structure of a 
book" is not so complex, so i also think that we don't need a own file for 
this too. What do you think are the advantages in splitting this to discrete 
files?

Perhaps we can just stay with the actual structure? Then name.xml will contain 
the book definition, author and include the other files. The name_admin.xml 
file contains the user/ admin documentation, a name_devel.xml and other will 
be added over time. This would also ease the conversion process.

Cheers,

Henning