On Jul 28, 2008, at 4:20 PM, Hans Hagen wrote:
there's the matter of what a user expects ... the core of context is rather stable and in that respect the 'old documentation' is still valid i.e. apart from 'new features, which may of interest to only a small group', the date on a manual does not tell much (i run quite some software which rather ancient manuals); for instance ... how many users are really interested in tricky xml support?
Only a few. But if I want to use ConTeXt to write a book I am definitely interested in something as mundane as endnotes. And stuff having to do with chapter beginnings, the way paragraphs should look (e.g. indentation, whitespace, line distance) for various types (e.g. a normal text paragraph, a long quote from another book, etc.). And with producing draft products (e.g. a B5 sized book that in draft is printed two-up with the even pages on the right). Or everything that has to do with ConTeXt's power in organizing projects and producing mltiple outputs from single sources. All stuff I have fought with in the past, some I find not intuitive, some of which to date I have not been able to solve in a satisfying way. Oh, and though the documentation may still be valid, I recall that I was trying to do cerrtain table stuff with what was available in the manual or excursion (the two documents that together make up the current ConTeXt documentation) and I was pointed to another way of doing tables in a MAPS article. Those are very, very mundane things you want when writing a book that are underdocumented, documented in locations that are outside the manual or not documented at all. I do not care if the manual is old. But the onging development of ConTeXt has been offered as a reason why the documentation is lacking. If this is nonsense, good. In that case there is no reason to improve the docs so they actualy give a good overview of how to do things in ConTeXt and understandable by non-ConTeXt-developers. G knuth.tex from the ConTeXt distribution says: Thus, I came to the conclusion that the designer of a new system must not only be the implementer and first large||scale user; the designer should also write the first user manual. The separation of any of these four components would have hurt \TeX\ significantly. If I had not participated fully in all these activities, literally hundreds of improvements would never have been made, because I would never have thought of them or perceived why they were important. But a system cannot be successful if it is too strongly influenced by a single person. Once the initial design is complete and fairly robust, the real test begins as people with many different viewpoints undertake their own experiments. Somehow, this might be applied to ConTeXt I think ;-). Three out of four afaic...