21 Apr
2009
21 Apr
'09
11:33 a.m.
On 21-04 08:36, Juha Heinanen wrote:
Klaus Darilion writes:
It does not really matter how many files there are. In both cases it is xml
based docbook that is used to produce a single document.
The only structure difference I can see is that we start our docbook tree with
a <section> element, while kamailio modules start with <book>. This only
makes
a difference if you process the sources within a larger collection, i.e. we
wanted to be able to insert module documentation within a larger document and
starting with <section> is more flexible there because you can insert it
anywhere in the documentation tree.
But in most cases the documentation in each module is processed separatetely
and most often it is used to generate README files, and there it does not
matter if the document starts with <section> or <book>.
The fact that ser modules sometimes lack up-to-date documentation is another
issue.
Jan.
I prefer README as authoritative source - every
feature commit should
also add a feature descrption (e.g. do not write long commit messages
but write the text into the README and then copy paste it into the
commit message)
i agree and also, there should be a common format for readme file source
files. if i look at modules/tm, it contains:
jh@taimen:/usr/src/orig/sip-router$ ls modules/tm/doc
api.xml functions.xml Makefile params.xml tm.xml
and if i look at a k derived module, it has:
jh@taimen:/usr/src/orig/sip-router$ ls modules/auth_radius/doc
auth_radius_admin.xml auth_radius.xml
there is thus need to standardize doc format and have documentation of
all common modules up to data, before we can even dream to announce this
project to users.