[SR-Dev] Module Documentaiton (was: what to do if function names differ?)

[Jan Janak]

Martin,

On 21-04 09:09, Martin Hoffmann wrote:
> Juha Heinanen wrote:
> > Klaus Darilion writes:
> > 
> >  > 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 at 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 at taimen:/usr/src/orig/sip-router$ ls modules/auth_radius/doc
> > auth_radius_admin.xml  auth_radius.xml
> 
> Before sip-router started, I started an effort for SER to have all
> module documentation standardized into a manual page based on docbook
> sources.[0] The result is certainly optimal, for a user on a *nix system,
> doing "man tm" should be natural.
> 
> The source format is dubious, though. I eventually ended up with docbook
> since it is a standard of sorts and there are tools to make manpages out
> of the sources (although they need some tweaking). However, editing is
> as painful as it gets. For documentation, painful editing usually means
> it is not being done. So, if someone has a better suggestion for the
> source format, they are most welcome. Some lightweight markup like RST
> is probably a good idea, but then someone needs to write a
> RST-to-docbook converter (shouldn't be that hard) and we need some
> formating rules (not very hard either, pretty much everyone knows how
> manpages look).

So did you generate the manpages from docbook after all? Or does it use some
special syntax/markings? Would it be possible to generate man pages from the
docbook documentation in modules?

   Jan.