[OpenSER-Docs] module documentation sgml to xml migration

[Edson]

Hi...

>-----Original Message-----
>From: Daniel-Constantin Mierla [mailto:miconda at gmail.com]
>Sent: segunda-feira, 10 de março de 2008 20:45
>To: Edson
>Cc: 'Henning Westerholt'; openser-docs at lists.openser.org
>Subject: Re: [OpenSER-Docs] module documentation sgml to xml migration
>
>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.
That's Ok for me.

>
>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.
Yep... my fault... I wasn't clear enough... I also agrre with You about use
the global revision number, but what do You think about include the
generation time _inside_ the generated files?

Cheers,
Edson

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