[OpenSER-Docs] module documentation sgml to xml migration
miconda at gmail.com
Tue Mar 11 00:32:10 CET 2008
On 03/10/08 20:09, Henning Westerholt wrote:
> 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.
At this time, there are revision numbers for each chapter (admin, devel,
faq, ...) and they reflect svn commit revision for that specif file.
Having up to 3 or 4 such numbers in same readme might be confusing.
keeping one in the master, will not reflect changes, as module.xml is
the less updated. Good alternative will be to find a way to add the svn
revision at generation time (as we get it now with compilation of
openser and it is reflected in openser -v). I think it is possible with
xml, to give a parameter value in the command line (needs investigation).
>> 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.
It is what I think as well.
More information about the sr-docs