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

Daniel-Constantin Mierla miconda at gmail.com
Wed Feb 27 18:11:50 CET 2008


Hello,

On 02/27/08 14:15, Henning Westerholt wrote:
> 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.
>   
great! Didn't know about.
>   
>> - 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
>   
section would be the hard one, as there are parameters with same name. 
Perhaps some patterns have to be defined here, like modulename_id. It is 
easier in this way to avoid conflicts with other modules.

>   
>> 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?
>   
name_chapter.xml was just the main file for the case when the aggregated 
book was generated. I had no real expertise to know whether we can 
combine docbooks in another docbook. My idea was, when generating stand 
alone readme, use name_book.xml. For the aggregated readme, there should 
be some master file that will include all "name_chapter.xml" files. Once 
again, it may not be required, as you said.

As I had it in mind, a name_book.xml would be (pseudocode)
<book>
include here name_chapter.xml
</book>

The name_chapter would be
<chapter>
include here name_admin.xml
</chapter>

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

yes, all ok for me.

Cheers,
Daniel

> Cheers,
>
> Henning
>   




More information about the sr-docs mailing list