Martin, I am fine with this, I wrote a lot of documentation in XML-based docbook in the past. I am not sure what is the best way to add support for comments in documents rendered as HTML, but I would start asking google.
Regarding the sip-router.org site, you should have access to it so feel free to do necessary changes there. Jan. Martin Hoffmann wrote: > Heisann, > > as you may have noticed, I am playing around with documentation lately. > In the process I have tried many things: TeX, Docbook, various Wikis. > In the end, I am afraid that short of writing something new (which I > did, too, but that is a different matter), Docbook turns out to be the > best system. While editing XML is quite horrible, the advantage of the > tool base around it makes up for a lot. As prove, I have taken bits from > the existing docbook for the auth module and crafted a man page for > it:[0] > > http://www.partim.de/pub/misc/auth.7 > > I for one find having a manual page the perfect documentation. But of > course, you can turn this into HTML or PDF or whatever. > > So, since the Drupal approach and the Wiki approach didn't exactly > attract a horde of interested documenters, I think we are back to a > small core team. I browsed around a bit and it appears that the standard > way of doing documentation is providing a normal manual and having a > version online where users can put comments into pages (Blog style). > > So, unless anyone objects, I would like to start yet another attempt at > the SER User Manual. I would like to store the sources in the SER > repository, in doc/user_manual. For module documentation, I'd like to > keep a file reference.xml containing a single <refentry> for the module > in each module directory and ditch the old doc subdirectory. > > I have no idea what would be a good tool to allow the online version > with comments. I suppose Greger would suggest Drupal. Is that hard to > set up? Are there any other suggestions? As the place, I would like to > have http://docs.sip-router.org/user-manual/. > > I am all to aware, that I am arguing against my own earlier opinion. > But, it appears even I can learn ;) > > All earlier volunteers are invited to join. If you have any material, > that you would like to see included in the user manual, let me know > and/or send it to me. > > Best regards, > Martin > > [0] Should you care, here are the sources: > > http://www.partim.de/pub/misc/auth-reference.xml > _______________________________________________ > Serdev mailing list > [email protected] > http://lists.iptel.org/mailman/listinfo/serdev _______________________________________________ Serdev mailing list [email protected] http://lists.iptel.org/mailman/listinfo/serdev
