From: Bernd E. <eid...@we...> - 2005-07-04 06:43:26
|
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. |
From: Zoran V. <zv...@ar...> - 2005-07-04 07:22:12
|
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 |
From: Bernd E. <eid...@we...> - 2005-07-04 08:13:02
|
> 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. ok, see. would be handy. > 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? Depends on what we need for doctools, or generally for documentation. Example: All Headings like NAME,SYNOPSIS,DESCRIPTION,EXAMPLES,SEE ALSO,KEYWORDS are representated the same in the wiki, e.g. a third-level-heading: === SEE ALSO === Other "markup" like bold or underline is also easy parseable ('''bold'''). "Examples" start with one or more whitespace on a line. So I think it should be very easy to hack a convert, as the structure is always the same. Like this stupid hack: http://naviserver.sourceforge.net/wiki/index.php/News2wiki.tcl But, as the devil is in the details, maybe you send me a doctool-document in the form that you can imagine as a template for NaviServer, and I take a look at how complex it is to write a small converter script. > 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) ? Thats true. I think the effort stopped at the very beginning or halfway. But if only we had it in the Wiki! The problem is that writing documentation sucks, not writing the converter :-))) > 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. Ok. But we should have a complete list for C and TCL to know whats missing or when we are finished. I started with TCL, but the list is not perfect: http://naviserver.sourceforge.net/wiki/index.php/Examples:Commands > 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. Ok, so we tag it after the macro insertion (or whatever solution) for the range headers? > 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. ok. |
From: Zoran V. <zv...@ar...> - 2005-07-04 08:38:27
|
Am 04.07.2005 um 10:14 schrieb Bernd Eidenschink: >> 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. >> > ok, see. would be handy. Watch! Although handy, it is pretty inflexible. As an exercise, imagine you'd like to use Tcl_AllocStatBuf call. Now, you naively go and "man Tcl_AllocStatBuf". You'd like to get call signature and parameter description, but you also want to look at what the call is really doing. Given the current state, this is all but user-friendly and effective. In order to understand what I mean, please do try "man Tcl_AllocStatBuf" and judge by yourself... Personally, I find it very annoying and ineffective. > > >> 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? >> > Depends on what we need for doctools, or generally for documentation. > Example: > All Headings like NAME,SYNOPSIS,DESCRIPTION,EXAMPLES,SEE > ALSO,KEYWORDS are > representated the same in the wiki, e.g. a third-level-heading: > === SEE ALSO === > Other "markup" like bold or underline is also easy parseable > ('''bold'''). > "Examples" start with one or more whitespace on a line. > > So I think it should be very easy to hack a convert, as the > structure is > always the same. Like this stupid hack: > http://naviserver.sourceforge.net/wiki/index.php/News2wiki.tcl > > But, as the devil is in the details, maybe you send me a doctool- > document in > the form that you can imagine as a template for NaviServer, and I > take a look > at how complex it is to write a small converter script. OK. I will prepare a doctool for a one ns_xyz and Ns_XYZ() (both Tcl and C api). You must install tcllib and there you will have a dtp utility which will translate this in wiki or html or nroff for you. If it turns out to be simple to write a wiki->doctools converter then I'm all for it. Then we'd use wiki to fill-in the content, use the translator to generate doctools pages, then cvs-import those, then generate html/nroff offline docs during installation. Ideally, the wiki->doctools should be somehow automated. Hm.... and what if we'd have a wiki->nroff and wiki->html off-line converters? Than we'd have the sources of docs in native wiki format and check-in those in CVS. During the "make install" we'd hit the apropriate converter and generate html/nroff on the fly? Or we can pre-format nroff/html and check-in those... ?? 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 ? > > >> 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) ? >> > > Thats true. I think the effort stopped at the very beginning or > halfway. But > if only we had it in the Wiki! The problem is that writing > documentation > sucks, not writing the converter :-))) But yet, having a good framework in place would actually lower the barrier of having to start to write actually. > > Ok. But we should have a complete list for C and TCL to know whats > missing or > when we are finished. If we manage to get Wiki-based thing, than all is already in-place, right? > I started with TCL, but the list is not perfect: > http://naviserver.sourceforge.net/wiki/index.php/Examples:Commands > The problems with the list is that you need to update yet-another-thing. > >> 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. >> > > Ok, so we tag it after the macro insertion (or whatever solution) > for the > range headers? > I would suggest so. Zoran |
From: Bernd E. <eid...@we...> - 2005-07-04 14:44:09
|
> 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. :-) |
From: Zoran V. <zv...@ar...> - 2005-07-04 14:59:29
|
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 |
From: Stephen D. <sd...@gm...> - 2005-07-04 23:44:12
|
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 autogenerate= s 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 |
From: Stephen D. <sd...@gm...> - 2005-07-05 00:36:06
|
http://naviserver.sf.net/wiki/index.php/User:Sdeasey Neato: templates! The wiki =3D=3D nroff :-) Categories look useful too. Unfortunately all page names have their initial letter bashed to upper case, and underscores are converted to spaces... :-( |
From: Zoran V. <zv...@ar...> - 2005-07-05 06:19:36
|
Am 05.07.2005 um 02:36 schrieb Stephen Deasey: > http://naviserver.sf.net/wiki/index.php/User:Sdeasey > > Neato: templates! The wiki == nroff :-) Excuse my ignorance, but: where is nroff? |
From: Stephen D. <sd...@gm...> - 2005-07-05 06:43:42
|
On 7/5/05, Zoran Vasiljevic <zv...@ar...> wrote: >=20 > Am 05.07.2005 um 02:36 schrieb Stephen Deasey: >=20 > > http://naviserver.sf.net/wiki/index.php/User:Sdeasey > > > > Neato: templates! The wiki =3D=3D nroff :-) >=20 > Excuse my ignorance, but: where is nroff? I was exagerating, sorry. Templates... with args... macros... nroff... Still, where man.macros (oh, my, God) has: .OP cmdName dbName dbClass The wiki would have Template:OP, called as: {{OP:cmdName=3DX|dbName=3DY|dbClass=3DZ}} Which could expand to whatever you like, including HTML comments to aid converting back to nroff etc... |
From: Zoran V. <zv...@ar...> - 2005-07-05 06:55:13
|
Am 05.07.2005 um 08:43 schrieb Stephen Deasey: > On 7/5/05, Zoran Vasiljevic <zv...@ar...> wrote: > >> >> Am 05.07.2005 um 02:36 schrieb Stephen Deasey: >> >> >>> http://naviserver.sf.net/wiki/index.php/User:Sdeasey >>> >>> Neato: templates! The wiki == nroff :-) >>> >> >> Excuse my ignorance, but: where is nroff? >> > > > I was exagerating, sorry. Templates... with args... macros... > nroff... > > > Still, where man.macros (oh, my, God) has: > > .OP cmdName dbName dbClass > > The wiki would have Template:OP, called as: > > {{OP:cmdName=X|dbName=Y|dbClass=Z}} > > Which could expand to whatever you like, including HTML comments to > aid converting back to nroff etc... Does this mean that converting from wiki format to nroff would be relatively trivial? IOW, I can invent just about any Tempate:OP were OP is whatever nroff will support, like .CE, .CS, .PP, .SH ? I do not know wiki enough to be able to make any decision, but if there is a way of writing it all in wiki and getting it converted to decent nroff (and html) without much fuss, then I'm all for it. OTOH, have you ever looked at doctools? Zoran |
From: Stephen D. <sd...@gm...> - 2005-07-05 07:25:28
|
On 7/5/05, Zoran Vasiljevic <zv...@ar...> wrote: >=20 > Am 05.07.2005 um 08:43 schrieb Stephen Deasey: >=20 > > On 7/5/05, Zoran Vasiljevic <zv...@ar...> wrote: > > > >> > >> Am 05.07.2005 um 02:36 schrieb Stephen Deasey: > >> > >> > >>> http://naviserver.sf.net/wiki/index.php/User:Sdeasey > >>> > >>> Neato: templates! The wiki =3D=3D nroff :-) > >>> > >> > >> Excuse my ignorance, but: where is nroff? > >> > > > > > > I was exagerating, sorry. Templates... with args... macros... > > nroff... > > > > > > Still, where man.macros (oh, my, God) has: > > > > .OP cmdName dbName dbClass > > > > The wiki would have Template:OP, called as: > > > > {{OP:cmdName=3DX|dbName=3DY|dbClass=3DZ}} > > > > Which could expand to whatever you like, including HTML comments to > > aid converting back to nroff etc... >=20 >=20 > Does this mean that converting from wiki format to nroff > would be relatively trivial? IOW, I can invent just about > any Tempate:OP were OP is whatever nroff will support, like > .CE, .CS, .PP, .SH ? >=20 > I do not know wiki enough to be able to make any decision, > but if there is a way of writing it all in wiki and getting > it converted to decent nroff (and html) without much fuss, > then I'm all for it. >=20 > OTOH, have you ever looked at doctools? >=20 > Zoran I really don't know what the best thing to do is. I can see plusses and minuses either way. I personally I don't have a lot of use for paper docs, but I know it's important to some people. You can already get an XML page dump: http://naviserver.sourceforge.net/wiki/index.php/Special:Export/User:Sdea= sey Kind of dissapointing, just a big blob of wiki-source. However, the macros are preserved. So the problem basically becomes, can you write a program which spiders the website and converts {{X:1|2|3}} into .X 1 2 3. Maybe we should pick one C function and one Tcl command to document fully on the wiki, write some wiki macros to make it easy, then try converting it into whatever? |
From: Zoran V. <zv...@ar...> - 2005-07-05 07:51:44
|
Am 05.07.2005 um 09:25 schrieb Stephen Deasey: > Maybe we should pick one C function and one Tcl command to document > fully on the wiki, write some wiki macros to make it easy, then try > converting it into whatever? > Eh... It seems that this task is a real PITA! I think somebody could make a fortune by inventing easy to use collaborative doc system able to generate just a handful of formats: pdf, nroff, html. If I understand this correctly, writing wiki pages is also a task you have to learn (wiki markup). This is the same as with doctools. Difference: in wiki everybody can do this from the browser, whereas in doctools you'd have to do it off-line and in a text editor. Apart that it is appealing to be able to write it on-line and it seems trivial for bunch of people to do it "at the same time" I see no other pros for Wiki. Cons are important: no simple interface to cvs (docs are vital part of the server), lack of usable converters... It seems like a lot of hacking for me and a great time eater. OTOH, doctools are already supporting (almost) everything we need. The cons are: you must edit sources off-line. Just to be clear: I'm not trying to push doctools vs. wiki. I'm just not convinced that wiki will save us any time and trouble. I have a notion that doctools are less problematic and would bring us to the goal (of having decent html/nroff docs distributed with the server) faster. I can imagine the following: We divide and conquer... Since I have more experience with doctools than wiki, I will take a C-API and a Tcl-API call and write source of the doc in doctools. Then I will convert this to nroff, html and wiki format by means of the "dtp" processor from the tcllib. You or Bernd can take the Wiki part and examine what would it mean to write a converter that would emit something like people are accustomed to when hitting "man fcopy" or "man lindex" or "man Tcl_NewObj". Then we can share experience (and source-files). How does this sound? |
From: Bernd E. <eid...@we...> - 2005-07-05 08:00:52
|
> 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. |