Hello,
first, after reviewing a bit latest changes to module docs, I discovered
that we renamed module_user.xml to module_admin.xml, but we forgot about
chapter's title, it is still "User's guide". Should we replace it with
something more suggestive?
Second, coming to something was a bit touched in past discussions. It is
about adding ID attribute to sections and examples. That will help to
get persistent links inside a document. The issue is that we have
modules with same parameter name, also, perhaps modules with many
sections for same function (with different number of parameters), so we
should come up with some rules to avoid conflicts.
A pattern can be:
- for functions: modulename_f_functionname (plus 1 or 2 if there are
many sections for same function)
- for parameters: modulename_p_parametername
- for mi commands: modulename_mi_commandname
- for PVs: modulename_pv_pvname
- for the rest of sections: modulename_someuniqueid
In this way we ensure naming space within module. The bad might be that
modulename is quite long sometime, alternative will be to allocate an ID
per module, but we get to these IDs management, which, makes no sense,
in my opinion. In addition, having a clear pattern for ids, will help to
write the links by hart, although this is not something that important.
Updates will be done as we go, but we should enforce for new additions.
Any comments?
Cheers,
Daniel
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
Hi Bastian,
i just noticed that the benchmark module exported the 'BM_time_diff'
pseudo-variable. Was is the purpose of this PV, as this is not documented in
the readme?
Cheers,
Henning
Hi all,
the module docs conversion from SGML to docbook-xml is currently in the works,
and the devel module documentation looks already cleaner after the removal of
most of the FAQ and devel parts.
Perhaps we can now gather some ideas for a openser guide.
There a exists a few (probably well known) documents, that were created with a
somewhat similiar purpose, albeit they are really outdated now:
- the old SER getting started guide
http://siprouter.onsip.org/doc/gettingstarted/
- the IP telephony cookbook
http://www.informatik.uni-bremen.de/~prelle/terena/cookbook/main/index.html
Adam Linford started some time ago a new (more up to date) guide for the
project, available at: http://openser.oralnet.co.uk/ . Perhaps this can be
used (with his permission, as a starting point? Some parts of the SER getting
started guide can perhaps also used, after review and editing, however i
don't know what copyright this content has.
I think the target audience of the planned guide are newcomers without any
previous experience with the server. So it should be start with a description
of the basics, and then cover step by step more complex topics, like the
previous guides.
What do you think?
Henning
Hello,
The avp_aliases (string) parameter and the avp_write(value,name)
function has been removed in 1.3.
It is ok to keep them there for 1.3 (although I would prefer to have
them transfered to FAQ section: "what happened to avp_aliases" and
"what happened to avp_write"), but the reference to dead functionality
older then 2 releases should be removed from 1.4 documentation.
Regards,
Ovidiu Sas
I know that just now we are dealing with SGML to XML conversion, but it
seams that some point have to be registered:
1- clearer documentation/explanation of the functions internals.
Specifically what they do and what they changes (SIP messages, internal
counters/timers, PV, AVP, etc).
2- make very clear which functions break normal script execution (p.ex. see
the "noisy_ctimer" parameter in TM module" discussion).
And to close a question:
Should the DOC volume include the Doxigen documentation? Where? In a hole
dedicated and separete chapter, or should each module have in it's
documentation another chapter/section just for dealing with this internal
informations? I, particularly would like to see the generated graphs being
merged just after the function/parameter explanation (just for the
external/exported functions/parameters/variables).
Edson.
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";
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?
Edson
Hello,
thinking about migrating to xml from the sgml, I found a good tutorial:
http://www.sagehill.net/docbookxsl/index.html
Following some guidelines there, I was able to migrate the doc for
dispatcher in just few steps:
- renamed extension from sgml to xml
- changed the header of disptacher.xml to conform xml structure and link
to dtd
- fixed some bogus entities defined in doc/entities.sgml (I made a local
copy to entities.xml)
- fixed some unclosed <para> tags in disptacher_user.xml
- run this futuristic command (in modules/dispatcher/doc/):
xsltproc --stringparam html.stylesheet ../../../doc/docbook.css
--stringparam section.autolabel 1 --stringparam
section.label.includes.component.label 1 -o dispatcher.html
/usr/share/xml/docbook/stylesheet/nwalsh/html/docbook.xsl dispatcher.xml
- to get the readme txt format:
lynx -force_html -dump -nolist -width=72 dispatcher.html >dispatcher.txt
I downloaded http://www.openser.org/css/docbook.css in openser/doc/
folder, so I got the same look on my local generated html files as for
the ones on the openser.org. The extra option now is that each chapter
has its own table of content (can be removed via some option, but I
didn't dig in more).
It was not that painful, but will require some work, when coming to all
modules. I propose to add the docbook.css in the openser SVN under doc
folder, maybe renamed as "openser-docbook.css". Also, a copy of
entities.sgml as entities.xml with the required fixes (the sgml version
will be removed once migration is complete).
I believe makes no sense to add support for mixed doc sources -- meaning
here that some modules have sgml and some xml. If we can sync 3-4
people, and split the modules among, we can get the work done in few
days. In this case, we will go directly in replacing the generation of
html from sgml to xml. Will be useless work to add intermediary support
in Makefile and try to detect whether is sgml or xml.
Any comment?
Cheers,
Daniel
Hi, for now they are just a few modules that include real examples in their
doc. Usually, a module doc just shows examples of how to set each parameter
or use each function, but there is not a "global" example.
I don't know if would be good to include a section "Examples" in the module
doc template (it could saturate the info), or maybe a section "Examples"
containing links to the wiki or external references.
What do you think about it?
--
Iñaki Baz Castillo
ibc(a)in.ilimit.es
