[OpenSER-Docs] module documentation sgml to xml migration

[Daniel-Constantin Mierla]

Hello,

On 03/10/08 20:52, Edson wrote:
> Hi, Guys...
>
> Just to put another point of view... removing the template is fine to those
> that will write a new module documentation, since, as Henning said, they
> usually use another one already wirted as starting point.
>
> But... where to put the documentation templates? The documentation
> definitions? The structure definitions... I would say that the template
> files (as examples on how to write) can be easily removed, not the
> directory... it (for me, sure) seems the right place to put the structure
> definitions files...
>   
I think we should remove all things that are not actually in use. The 
templates were not updated since long time, that's a clear sign of useless.

We will add new files as we get them, from the ones mentioned by you.
> At last, I would say that SNV revision or date, both have there advantage an
> disadvantage... Than, why not keeping both? Something like: "Revision X,
> valid on <compilation date> at <compilation time>"?
>   
As expressed in my previous email, I think we should use the global svn 
revision at generation time (for readme, html) -- this way one can 
control better validity of the document for a certain feature and 
content. The documents are generated from many files (admin, devel, 
etc), having several revision numbers in same document is confusing.

Cheers,
Daniel

> Edson
>
>   
>> -----Original Message-----
>> From: openser-docs-bounces at lists.openser.org [mailto:openser-docs-
>> bounces at lists.openser.org] On Behalf Of Henning Westerholt
>> Sent: segunda-feira, 10 de março de 2008 15:10
>> To: openser-docs at lists.openser.org; miconda at gmail.com
>> Subject: Re: [OpenSER-Docs] module documentation sgml to xml migration
>>
>> On Monday 10 March 2008, Daniel-Constantin Mierla wrote:
>>     
>>> Remaining steps, that should not affect the content:
>>> - migration from entities to xinclude (Henning perhaps we can talk a bit
>>> on IRC as I get some strange errors, if you have a bit of time)
>>>       
>> Hello Daniel,
>>
>> thank you for the migration. Sure, we can talk tomorow about this.
>>
>>     
>>> - decide about some parts of the documentation if we keep it or not.
>>> docbook xml tools are more advanced than sgml ones, more information is
>>> displayed now: e.g., svn revision info appears in each document now,
>>> should we keep it? It is not really what one will expect from revision
>>> part of a document (should show changes done in the document)
>>>       
>> This big revision string is probably a little bit overkill. Perhaps we can
>> use
>> either: only the svn revision, or the date of the last change? The former
>> has
>> more advantages for the developer/ writer, the last one is probably better
>> understandable for the reader.
>>
>>     
>>> As now, there are few other sgml documents. The templates for module
>>> documentation. Should we keep them (doc/templates/module)? I think they
>>> were not in use for quite some time, nor updated. The tls doc will be
>>> migrated xml (tls/doc). The rest should be now all over xml.
>>>       
>> Perhaps we can remove the template, i think most people uses a small module
>> as
>> their starting point now.
>>
>> Cheers,
>>
>> Henning
>>
>> _______________________________________________
>> Openser-docs mailing list
>> Openser-docs at lists.openser.org
>> http://lists.openser.org/cgi-bin/mailman/listinfo/openser-docs
>>     
>
>