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

[Jan Janak]

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).

I certainly agree with the idea that all new stuff should be documented, but I
wonder whether we should revisit the system we write documentation in? I am
personaly fine with docbook.

But if our goal is to produce plain text READMEs, wouldn't it make more sense
to adopt something simpler, for example the dokuwiki format? It is easily
readable as plain-text and we can edit it in the wiki and synchornize with
READMEs in the repository.

It's just an idea...

  Jan.