Re: [naviserver-devel] Release/Docs
OTOH, have you ever looked at doctools? Not too much, but as I read here: http://wiki.tcl.tk/3054 the conversions should be easy: dtp doc html your_manpage your_manpage.html dtp doc nroff your_manpage your_manpage.n dtp doc text your_manpage your_manpage.txt And seems there's also latex (and therefor PDF) and wiki: http://aspn.activestate.com/ASPN/docs/ActiveTcl/tcllib/doctools/doctools.html So, if we use doctools, we only would need a) An autogenerated step to generate html,nroff (and wiki) b) (Auto)generate an index.html file to all generated single html pages (easy) I don't know the output of the doctool-wiki conversion, if it creates [Wiki-Links] automagically so that we have relations for free. But that does not matter. We know our commands so we can regsub and create those relations. If we start with Wiki, we can create a nice Documentation with easy relations/links between the commands and documents. But the wiki-nroff step does not exist, does it? There are these small little nroff-gadgets like .sp (Skip one line vertically) or markup for italics for function parameters. We can only produce really nice nroff/groff, if we have a really good Wiki template and always use it correctly. At least this is my impression. BTW: How do we fetch our documentation out of Wiki for autogeneration of documentation? Maybe we take a database dump and one of us accesses it local? Hm...not good. Or spidering it... No. So, somehow, seems the doctools approach would be easier right now. And no one will complain that documentation is not on Wiki, if documentation is available! :-) Bernd.
[naviserver-devel] Release/Docs
Hi! I want to ask you for your opinion on a few things: a) Documentation AFAIK the status was to ask Andreas Kupries for (small?) modification of the doctools to be able to make smart C-Function documentation. Zoran: Can you tell if your suggestions will be (or are) accepted? To me it would make sense to make the documentation effort now top priority, regardless of the format. Later we can copy and paste it from whatever source to our preferred target, but we should aim for the source now. Even the fresh NaviServer commands are not documented and only available for the skilled C developer (and see current discussion on AOLserver mailinglist). In the first step documentation must not be perfect and long, as long as it respects some formal template documentation style and presents things the way they work. Strategy? Two possible ways: (A) 1. Construct list of all current commands (C and TCL), mark the deprecated ones. 2. Categorize commands. 3. We distribute documentation work among each other (small bunch of commands for everyone; and we know who documents what command); and everyone on the mailing list is a volunteer per se and likes to contribute :-) (B) - Update the '/doc' dir in CVS using current templates OR - Update the '/doc' dir in CVS using doctools OR - use Wiki for easy peer review and parse the Wiki structure later to transform the docs to whatever format (would be very simple step) b) Intermediate-Release, Beta-Release This was also the intention for 4.99.0. There should be a release, downloadable!, so we have a visible result of the current status and efforts. It should be clearly marked or named as intermediate or beta release, open for testing and reviewing. Along with a statement or Roadmap that says: This release will become a default stable release - the next target is VFS, caching, etc. Do we want Version 5.0.0 to be the one with VFS, caching etc. or the first stable release? What do you think? Bernd.
Re: [naviserver-devel] Release/Docs
Am 04.07.2005 um 08:45 schrieb Bernd Eidenschink: Hi! I want to ask you for your opinion on a few things: a) Documentation AFAIK the status was to ask Andreas Kupries for (small?) modification of the doctools to be able to make smart C-Function documentation. Zoran: Can you tell if your suggestions will be (or are) accepted? This seems to lag behind (my fault) . Basically, the doctools is allright, the only limitation is that you can't make one man-page describing more than one C-API call. To get an idea, install Tcl and make: man Tcl_FSStat and you will see that the *entire* Tcl-VFS API is documented in one single man-page. Now, doctools can't make this. You'd need to supply a man-page per-api-call. But... Having worked with that in last couple of days. I find it *extremely* annoying. OOH, having conceptually related calls all fit on one page is appealing. OTOH, if you frequently need (man) access to a single call, then it is absolutely impractical and annoying to flip pages and pages of docs just to locate the call in question. I would really suggest we make a simple (and doctools supported) page-per-api-call approach. The doctools can already do that and it will be easier to read and (perhaps) maintain. The drawback is: number of files (will be quite large). I think I can live with that. To me it would make sense to make the documentation effort now top priority, regardless of the format. Later we can copy and paste it from whatever source to our preferred target, but we should aim for the source now. Even the fresh NaviServer commands are not documented and only available for the skilled C developer (and see current discussion on AOLserver mailinglist). Right. In the first step documentation must not be perfect and long, as long as it respects some formal template documentation style and presents things the way they work. Strategy? Two possible ways: (A) 1. Construct list of all current commands (C and TCL), mark the deprecated ones. 2. Categorize commands. 3. We distribute documentation work among each other (small bunch of commands for everyone; and we know who documents what command); and everyone on the mailing list is a volunteer per se and likes to contribute :-) This is not an option. This has to be done for the B. (below) as well! (B) - Update the '/doc' dir in CVS using current templates OR - Update the '/doc' dir in CVS using doctools OR - use Wiki for easy peer review and parse the Wiki structure later to transform the docs to whatever format (would be very simple step) Current templates are in plan nroff and thus complex to write. I would really use doctools for this purpose. doctools have a very short learning curve (very similar to POD and very Tcl-lish) so I believe everybody will be up and running after glancing on a doctools page for a few minutes. Wiki seems very nice for collaborative work but I do not know if there is a wiki-doctools converter (doctools-wiki there is). If we start hacking wiki, how would you convert this into some other format? The AS project started this and I do not see any moves there. The wiki-entered stuff is still there and nobody cares to get it into the CVS or get it translated to other off-line reading (man, html, pdf, etc) ? Bottom line: I think the best way would be to make a template for a C-API and Tcl-API call, then check-in this template for every C/Tcl API calls in CVS, then take one at a time and fill in the content. The CVS is a collaborative env, right? Who does which page? This is a simple matter of communication. I do not think that we need to divide this somehow. We are just a few people and it suffices to document as we go. I do not think that we will have much problems with that. A short email on the list telling: hey, I'j now do the ns_XZY or Ns_XZY() would do. b) Intermediate-Release, Beta-Release This was also the intention for 4.99.0. There should be a release, downloadable!, so we have a visible result of the current status and efforts. It should be clearly marked or named as intermediate or beta release, open for testing and reviewing. Along with a statement or Roadmap that says: This release will become a default stable release - the next target is VFS, caching, etc. Do we want Version 5.0.0 to be the one with VFS, caching etc. or the first stable release? I think that tagging the CVS now with 4.99.0 is perfectly OK as it would identify a body in CVS which is fixed and against which we can file bugs. I would do the 5.0 after we've done all those nice new things like VFS support (advancing well, btw), fancier upload caps, integration of ns_cache, full support for byte-ranges, finalized docs etc. I would target this towards the end of the year. Zoran
Re: [naviserver-devel] Release/Docs
This way or another, it seems that if we'd have a wiki-html and wiki-nroff converters at hand, we could trash doctools... But I do not know if any of those already exists. OK, the wiki-html should already be there, otherwise wiki would not work ;-) But, what about wiki-nroff ? Hm, the existing nroff docs could be transformed like here: http://naviserver.sourceforge.net/wiki/index.php/Template:Documentation_template I used the script that is found under the link hack at the end. (It's a hack. It's a hack.) The way back from wiki-nroff could be, depending on the nroff quality, more easy, if we use an easy and fresh Wiki document (and make use of standard HTML-Comments for better parsing). But it always would be unorthodox. :-)
Re: [naviserver-devel] Release/Docs
Am 04.07.2005 um 16:45 schrieb Bernd Eidenschink: This way or another, it seems that if we'd have a wiki-html and wiki-nroff converters at hand, we could trash doctools... But I do not know if any of those already exists. OK, the wiki-html should already be there, otherwise wiki would not work ;-) But, what about wiki-nroff ? Hm, the existing nroff docs could be transformed like here: http://naviserver.sourceforge.net/wiki/index.php/ Template:Documentation_template I used the script that is found under the link hack at the end. (It's a hack. It's a hack.) The way back from wiki-nroff could be, depending on the nroff quality, more easy, if we use an easy and fresh Wiki document (and make use of standard HTML-Comments for better parsing). But it always would be unorthodox. :-) I see this really pragmatic: *I* would not like to invent the wheel. If there is some good quality wiki-nroff, wiki-html, wiki-(whatever) this would be the way to go: write all in Wiki and get it converted to other stuff. This is very appealing. If not, but somebody (you?) could write working converters for at least html and nroff conversion, I'd be happy to use them and would also opt to write source docs in wiki. Ideal would be a tclsh app I could hit like wiki2html source.wiki (would produce source.html in the current dir) wiki2nroff source.wiki (would produce source.nroff in the current dir) If not, I'd use doctools for already given reasons. It can't be that bad considering that all of tcllib modules are documented with doctools (with some notable deficiencies in documenting C-code as I already mentioned). Zoran
Re: [naviserver-devel] Release/Docs
Don't know if this is useful: http://hula-project.org/Wiki_Conversion Our idea is that there be a script on the wiki server that autogenerates PDFs of the admin guide, the user guide, and any other large-scale documentation, suitable for printing and binding and admiring and cherishing forever and ever. -- Nat Friedman
