10 Mar
2008
10 Mar
'08
11:51 a.m.
Hello,
many thanks to Edson for scripts and Henning for help and testing, the
first phase of migrating the sgml to xml is done. You can now add
changes to any module documentation you wish.
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)
- 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)
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.
Cheers,
Daniel
10 Mar
10 Mar
7:09 p.m.
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
7:52 p.m.
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...
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>"?
Edson
-----Original Message-----
From: openser-docs-bounces(a)lists.openser.org [mailto:openser-docs-
bounces(a)lists.openser.org] On Behalf Of Henning Westerholt
Sent: segunda-feira, 10 de março de 2008 15:10
To: openser-docs(a)lists.openser.org; miconda(a)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(a)lists.openser.org
http://lists.openser.org/cgi-bin/mailman/listinfo/openser-docs
11 Mar
11 Mar
12:44 a.m.
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(a)lists.openser.org [mailto:openser-docs-
bounces(a)lists.openser.org] On Behalf Of Henning Westerholt
Sent: segunda-feira, 10 de março de 2008 15:10
To: openser-docs(a)lists.openser.org; miconda(a)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(a)lists.openser.org
http://lists.openser.org/cgi-bin/mailman/listinfo/openser-docs
5:32 a.m.
Hi...
-----Original Message-----
From: Daniel-Constantin Mierla [mailto:miconda@gmail.com]
Sent: segunda-feira, 10 de março de 2008 20:45
To: Edson
Cc: 'Henning Westerholt'; openser-docs(a)lists.openser.org
Subject: Re: [OpenSER-Docs] module documentation sgml to xml migration
Hello,
On 03/10/08 20:52, Edson wrote:
That's Ok for me.
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.
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
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(a)lists.openser.org [mailto:openser-docs-
> bounces(a)lists.openser.org] On Behalf Of Henning Westerholt
> Sent: segunda-feira, 10 de março de 2008 15:10
> To: openser-docs(a)lists.openser.org; miconda(a)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(a)lists.openser.org
>> http://lists.openser.org/cgi-bin/mailman/listinfo/openser-docs
>>
>
>
12:32 a.m.
Hello Henning,
On 03/10/08 20:09, Henning Westerholt wrote:
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).
It is what I think as well.
Cheers,
Daniel
On Monday 10 March 2008, Daniel-Constantin Mierla
wrote:
ok.
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
7:15 p.m.
On Tuesday 11 March 2008, Daniel-Constantin Mierla wrote:
Hi Daniel,
there is only one revision per module documentation, this was removed during
the cleanups that Edson did. But to keep this in the master document is only
not that useful, you're right. I think that your suggestion to use the same
revision like in the 'openser -V' output is reasonable. This way its easily
checkable that the documentation matches installed binaries.
Cheers,
Henning
[..]
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).
5890
days inactive
5891
days old
6 comments
3 participants
participants (3)
-
Daniel-Constantin Mierla -
Edson -
Henning Westerholt