On Jul 28, 2008, at 12:46 PM, Taco Hoekwater wrote: > > Hi, > > While most of what Gerben states is close enough to the truth to > be a matter of opinion, I really object to the tone of 'there is no > documentation'. There is, in fact, a whole lot of documentation. > It may be incomplete (especially when it comes to recent > developments), > but that is quite different from not having documentation at all. > > There are thousands of pages of documentation on pragma-ade.com, > and pretending they are totally inadequate by not even asserting > their assistance is unfair.
OK Taco, that is a fair point concerning my pov. To answer it: I have made my comments knowing quite well what documentation there is and my *personal* (your mileage may vary) experience is that it hardly helps me. My personal experience has been with a result of close to 100% that if I want to do something / find out something I am unable to find it in the docs. Also, depending on what doc you take, I recall getting different solutions (I am reminded of the various incompatible ways to do tables) and if I recall correctly some of it had to be hunted down in MAPS articles and such. Maybe the answers of my questions are there. But in that case the documentation is such that I consider myself in the situation that I am unable to get my help from it. And the documentation is not just incomplete for recent developments. I have an idea. Why not have a live ConTeXt manual.pdf where you add something in the proper location and compile the document every time you answer a question from a user? As you are the person answering anyway, it should be little extra work. For instance: I have put out a question about the (afaik completely undocumented, incomplete and certainly not recent) endnotes feature. Why not take the manual now, add the info in and recompile and do that every time a question arrives that is not in the manual or that is maybe unclear in the manual? I would suggest looking at ways to make it as easy as possible (that is, as little work as possible) for yourself to keep a user&reference manual up to date. Something simple and fundamental as endnotes should not be undocumented. And limitations (like what to do if you want images in endnotes) should be available in documentation. In fact, you need only maintain one single integrated document en keep it up to date with the current ConTeXt version. Then, when you make MkIV the current ConTeXt version (and not a beta using a beta of a new compiler) you freeze the old and move to the new. Is it perhaps the case that the source of the manual is so old that it will not compile with a current ConTeXt anymore? If not, why not update it so it is less than 7 or 9 years out of date? If so, what does that possibly tell you about how valid the contents itself still are? Yours, G PS. To my own surprise (as I am a TeX fan) I have recently started to think about researching non-TeX alternatives. PPS. Before pressing send I just had a look at what is there on the pragma-ade site: http://www.pragma-ade.com/document-1.htm. I do not see any documentation other than the 1999 excursion and the 2001 'all of ConTeXt' manual. Maybe I am looking in the wrong place for documentation? ___________________________________________________________________________________ If your question is of interest to others as well, please add an entry to the Wiki! maillist : ntg-context@ntg.nl / http://www.ntg.nl/mailman/listinfo/ntg-context webpage : http://www.pragma-ade.nl / http://tex.aanhet.net archive : https://foundry.supelec.fr/projects/contextrev/ wiki : http://contextgarden.net ___________________________________________________________________________________
