Kamailio SIP Server Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Writing Docbook Files for Module Readme ======

README file for each module is generated from xml docbook files residing in **doc/** sub folder. The README file must not be changed directly, the editing has to be done to the xml docbook files.

When one adds a new module it has to write these xml docbook files and then generate the first version of README using:

<code>
make modules-readme modules=modules/modname
</code>

For old modules (or after the new module has been published to the public git repository) do not generate anymore the README for pushing it to git. Push only the changes to the xml files, because the README will be automatically generated by a cron service running on server to ensure coherent formatting and avoid conflicts when having to backport to older branches.

Of course, you can generate the README locally to check if the result is the expected one, but then restore the old README without changes -- it can be done with:

<code>
rm src/modules/modname/README
git checkout src/modules/modname/README
</code>


===== Naming Files =====

==== Kamailio Style ====

The docbook file are:

  * modname.xml (e.g., acc.xml) - the main docbook file, including other files that have content
  * modname_admin.xml (e.g., acc_admin.xml) - the docbook file that includes content targeting administrators (e.g., short description, dependencies, parameters and functions for the config file, a.s.o.)
  * modname_devel.xml - the docbook file that includes content targeting developers (e.g., inter module APIs)

==== SER Style ====

The docbook file are:

  * modname.xml - the main docbook file, including other files that have content
  * params.xml - the docbook file that includes module config parameters
  * funcs.xml - the docbook file that includes module config functions
  * ... 


===== Section IDs =====

To generate IDs that make html version of README easier to refer to, each section tag for parameters, functions, etc. has to contain an **id** attribute. To avoid conflicts when merging some readme file, the value of ID attributes should use following pattern:

<code>
[module name] [dot] [type] [dot] [title]
</code>

The [type] should be:
  * p - parameters
  * f - functions
  * m - mi commands
  * r - rpc commands
  * s - statistics
  * e - event routes
  * v - pseudovariable

Next is an example showing the id for the section corresponding to parameter **workers** from module **async**:

<code>
<section id="async.p.workers">
        <title><varname>workers</varname> (int)</title> 
</code>