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

[Daniel-Constantin Mierla]

Hello Edson,

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

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

Cheers,
Daniel


On 02/27/08 01:26, Edson wrote:
> Hi, Daniel... Guys...
>
> So let's try to draw a first to-do list, so that the work can begin...
>
> 1- Migrate the existing DOCs from SGML to XML format:
>    I'm not a DocBook expert but Henning and I already changed some thoughts
>    on this. What's not clear to me is if this is just a translation matter
>    or also a diagramatic problem? Translation is some kind of direct work,
>    while diagramatic requires a previous discussion.
>
> 2- Suppress and/or Agregate new DOCs:
>    Clean-up empty files (with a sort of "no content") is require, since
>    there information can be gatered elsewhere, but agregate new DOCs is
>    a sort of "asking for problems" approach, so I would say that some
>    skeleton/template has to be defined. This has to become before this
>    agregation issue. But this arises a problem: wich is the best 'skeleton'?
>    Which kind of documentation will be present? How to automate it?
>
> So this two points brings:
> 1- Documentation structure Skeleton/Template;
> 2- Documents Skeleton/Template defining chapter and, maybe, minimum section
>    contents, definition of origin (directly from code? From Doxygen?) and,
>    most important, responsibilities;
> 3- XML Style that translate/implement this skeleton/templates;
> 4- Conversion of actual SGML format to some DocBook-XML format;
>
> Each of this points should define a milestone by itself and its end it could
> be marked with IRC meeting where the results could be presented and
> discussed.
>
> Please these are only thoughs... so fell free to add more points and/or
> point me wrongs approaches.
>
> Edson
>
>   
>> -----Original Message-----
>> From: Daniel-Constantin Mierla [mailto:miconda at gmail.com]
>> Sent: terça-feira, 26 de fevereiro de 2008 18:37
>> To: Edson
>> Cc: openser-docs at lists.openser.org
>> Subject: Re: [OpenSER-Docs] First Clean-up Patch for Documentation
>>
>> Hello,
>>
>> On 02/26/08 22:27, Edson wrote:
>>     
>>> Hi, Guys...
>>>
>>> I finish the first clean-up of the documentation. It consisted by:
>>> 1) remove all FAQ and DEVEL files considered empty in content (no content
>>>    at all or just the default lines);
>>> 2) remove of the <RevHistory>/</RevHistory> tag (and of course anything
>>>    Between them);
>>> 3) remove the comments at the EOF that beginned with
>>>    "<!-- Keep this element at the end of the file";
>>>
>>>       
>> Thanks, I believe we should think also the context of migrating to xml
>> format. Anybody with some docbook xml experience? Hints, tips? I am
>> investigating now the best way to migrate from sgml to xml.
>>
>> If we are going to remove some file, add new ones, we need to have in
>> mind the near future as well.
>>     
>>> The attached file (in ZIP format) is the resulting SVN DIFF file. It was
>>> applied over trunk version, revision 3761.
>>>
>>> I would like to ask the developers how much is a good time to wait for
>>> comments and revisions before commiting the changes? 1 week? 10 days?
>>> Sugestions?
>>>
>>>       
>> Let's plan kind of to-do list/roadmap, to sync the work and check the
>> milestones. Otherwise many will work on same task, or go totally
>> different direction.
>>
>> Cheers,
>> Daniel
>>
>>     
>>> Edson
>>>
>>> ------------------------------------------------------------------------
>>>
>>> _______________________________________________
>>> Openser-docs mailing list
>>> Openser-docs at lists.openser.org
>>> http://lists.openser.org/cgi-bin/mailman/listinfo/openser-docs
>>>
>>>       
>
>