March 2008 - sr-docs - kamailio.org

[OpenSER-Docs] module docs: internal anchors
by Daniel-Constantin Mierla 12 Mar '08

12 Mar '08

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

3 2

[OpenSER-Docs] module documentation sgml to xml migration
by Daniel-Constantin Mierla 11 Mar '08

11 Mar '08

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

3 6

[OpenSER-Docs] benchmark, $BM_time_diff
by Henning Westerholt 10 Mar '08

10 Mar '08

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

2 2

[OpenSER-Docs] towards a openser guide
by Henning Westerholt 10 Mar '08

10 Mar '08

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

2 1

[OpenSER-Docs] AVPops Module: README
by Ovidiu Sas 07 Mar '08

07 Mar '08

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

3 2

[OpenSER-Docs] Doc Improvements
by Edson 05 Mar '08

05 Mar '08

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.

3 5

[OpenSER-Docs] First Clean-up Patch for Documentation
by Edson 04 Mar '08

04 Mar '08

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

3 19

[OpenSER-Docs] migrating sgml to xml
by Daniel-Constantin Mierla 04 Mar '08

04 Mar '08

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

3 7

[OpenSER-Docs] Add examples in module documentation
by Iñaki Baz Castillo 03 Mar '08

03 Mar '08

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

4 7