27 Feb
2008
27 Feb
'08
2:15 p.m.
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