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

[Jan Janak]

On 21-04 11:11, Juha Heinanen wrote:
> Jan Janak writes:
> 
>  > 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.
> 
> in k we want to keep the tradition that ALL modules are fully
> documented.  we don't accept a module or a new function in a module,
> unless it is fully documented.  the system that is used to write the
> docs must be such that we can generate the doc at least as as txt and
> html.  we have made a huge effort to write the readmes as they currently
> are.  unless there is an automatic means to change their format, the
> format cannot be changed, i.e., manual change is out of question.
> 
> regarding common modules, before this project is announced to public,
> there thus needs to be k style documentation of all of them.
> 
> perhaps it was not a good idea to try to merge the modules after all if
> also documentation style is different in k and s, because we need to
> have two doc subdirs in all of them (one for k and another for s).

I don't understand this. In both cases it is xml based docbook. The structure
of a docbook document is given. The fact that there are more files with
boilerplate in modules coming from ser does not make it that much different.

   Jan.