Andrei Pelinescu-Onciul writes: i didn't understand how you merge names. will the resulting module have two names for the same function? i didn't find that in module readme. the policy should be that whatever is not documented, does not exist. -- juha

Jan Janak writes: yes, i need to soften my position. undocumented features just makes merge much harder, because it is not enough to compare readme files. also, it more or less means that the party who has not documented its features needs to make the merge, because that party understands what the undocumented features are doing. -- juha

Jan Janak schrieb: 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) regards klaus

Juha Heinanen wrote: 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). Regards, Martin [0] The git Web frontend's URL scheme sucks big time, but here is an example: http://git.sip-router.org/cgi-bin/gitweb.cgi?p=ser_modules;a=blob;f=modules… We didn't check in the results, but here is how it looks like: http://partim.de/pub/misc/auth.7

Jan Janak wrote: This sort of leads to the lightweight markup approach. Basically, add a small amount of markup and formatting rules to the README so that you can turn them into a man page, PDF, Wiki pages, you name it. The Python people use RST everywhere -- the entire documentation basically is RST files (on docs.python.org you can even check the raw files). While I am personally not too fond of RST, it would be a good choice since obviously processing the stuff in Python is easy. If we then define the required sections in the README file, we can write a little script for turning it into nroff or docbook or whatever. Regards, Martin

Juha Heinanen wrote: Manually and over time. Regards, Martin

Juha Heinanen wrote: Point taken. From where I stand, the documentation for many of the SER modules needs to be redone anyhow (hence me starting on that). So, if the K conventions are good enough, then you have the common format and the matter can be settled. Although I still love the idea of having manpages. Regards, Martin

On Tuesday 21 April 2009, Martin Hoffmann wrote: Hi Martin, i thought you already wrote this script to convert the XML to man. We also did not check the man pages in (they can be easily generated from the XML source), so is there anything else missing in the SER for this? Cheers, Henning

On Tuesday 21 April 2009, Martin Hoffmann wrote: Hi Martin, not sure if its really compatible, it seems that SER uses a bit different dialect of docbook in its sources, but here is the converter XSL we use: http://devel.kamailio.org/svn/trunk/doc/module-man.xsl Cheers, Henning

On 21-04 11:11, Juha Heinanen wrote: 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.

On 21-04 11:24, Juha Heinanen wrote: Of course, that will be possible. I don't know what were the steps to generate READMEs in kamailio, in ser modules we added a Makefile in each documentation directory and you can just type make txt to generate the README or make html to generat HTML based documentation. We can either add Makefiles to modules in modules_k or import the kamailio system. But in any case we will be using the same tools and templates to generate READMEs. Jan.

On Tuesday 21 April 2009, Martin Hoffmann wrote: Hi Martin, i also provided man pages for all kamailio modules with a similar approach like you did, by writing a XSL. But we don't used the docbook to man infrastructure like you did, instead we wrote a own small converter script. Man pages in kamailio trunk and 1.5.0 release can be generated with make modules-docbook-man, and are also included in the debian packages, if you want to take a look. I don't think that docbook is really that painful. If you look at a typical README source, e.g. for tm [1] then one needs to only master a few tags. This is not too hard, IMHO. The docbook stuff has also some advantages, it can be checked against a stylesheet to see if the document is well formed, it really easy be convert into different outputs, like HTML, PDF, man-pages and so on.. Cheers, Henning

Henning Westerholt wrote: Didn't know that (Yes, I am rather lazy). I will have a look into it. If you already have a lot of documentation in a certain format, we should probably reuse it, if it fullfills all requirements (which are not actually defined, of course). This may turn into an endless and rather pointless discussion, so I just shut up. I did choose docbook for my stuff, too, after all. Regards, Martin

Jan Janak wrote: Docbook has some markup for manpages already. I used that: http://www.oasis-open.org/docbook/documentation/reference/html/reference.ht… On top of that I defined a bunch of elements and a stylesheet to get the manpages I want when I run them through http://docbook2x.sourceforge.net/ They are still not perfect, but a lot better then the vanilla stuff. Regards, Martin

Daniel-Constantin Mierla writes: s-r cannot be worse that k k from doc point of view. it is totally unacceptable to me if we start to accept modules or functions w/o documentation. community is not able to write docs for common modules, e.g., tm. i don't remember that user would have written many (or any) module docs. each developer, who is responsible of a module, has to take care of it. wiki is easier to get help with. -- juha

Juha Heinanen wrote: Why not? Everyone who can read code can write documentation. Granted, tm is tricky, but the developers can read over it and point out mistakes. Regards, Martin

Henning Westerholt wrote: True. But this is somewhat different from "community is not able to write docs". For the modules that are there just now and pretty old, I am happy to write the docs, even though I am not planning on maintaining them. But I think this topic is somewhat exhausted: Seems to me we can agree on requiring documentation for modules and using K's formats for now since K has a gigantic advance there. Regards, Martin

Jan Janak wrote: I am quite aware of that. But the amount of familiarity with the code necessary to write useful documentation differs. Modules like xlog or acc are easy and even someone new to SER code can extract the necessary information. tm is the other extreme. Figuring out what the module will do with ACKs and CANCELs is a task for several hours. But interstingly enough, this latter point also shows that documentation written by developers is necessarily good either. Neither K nor SER document the very subtle and occassionally unexpected behaviour. The main skill of a good technical writer is to ask the right questions. Sure, they are a very rare breed, but if you happen to run across one, you will afterwards understand your own code better. Regards, Martin

On Tuesday 21 April 2009, Daniel-Constantin Mierla wrote: Hi Daniel, i agree. But then we should communicate this correctly. Instead of announcing something that is almost done, we need to point out clearly the areas where issues exists, and also providing pointers where help is really appreciated. Well, my employee also pays me to do work at the documentation (in kamailio so far). So it seems that some people did care in this areas too. If this is a capacity or resource problem with regards to some developing efforts, perhaps one of the (bigger) companies involved here can think about hiring a technical writer? Just an idea. :-) The basic foundation were not done from the community IMHO, but i agree, we could really use more help here. Cheers, Henning

Hello, On 04/21/2009 11:39 AM, Henning Westerholt wrote: I am not sure what you think the announcement would be, so I cannot comment. What is almost done? I want to tell people that they can start playing with sip-router and K modules are there. In this way we learn what are the most used parts and make them work quicker. There is still lot of work to do, in regard to MI, statistics, additional processes. I prefer to work on something people use, rather than doing blind coding. I am not using most of the modules out there, therefore I am not able to test them properly. Somehow I feel you think about a release -- we are far from there. Are you happy with K documentation? Well, main page of kamailio.org has in bottom right corner a poll, it is there for quire some time. Guess what community think needs to be improved. Documentation will never be satisfactory for everybody, but it grows with the number of people using the application. I think there are companies that paid full time developers in the last months for the integration work. If there are other companies willing to fund, they are more than welcome. I think all modules have docs, but not all up to date. The foundation is there, take a module, digg the sources and add what is missing in the readme. Even simply listing the functions and parameters to docbook with the note: "Needs content" is a step forward and great help. It is pretty simple to get out of mod interface: - parameter name and type - function name, number of parameters, where it can be used - name for exported PV, MI/RPC commands, ... Others can come latter and complete. Cheers, Daniel -- Daniel-Constantin Mierla http://www.asipto.com/

Henning Westerholt writes: k docs are MUCH better than in an average open source project and we should keep it that way also in sip-router. it just affects those modules that in sip-router replace k modules. -- juha

Jan Janak writes: yes, that is reasonable. so did we decide that common modules will use k readme style and generation script? -- juha

On 21-04 08:36, Juha Heinanen wrote: 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.