On Fri, 25 Jul 2008, Gerben Wierda wrote: > On Jul 22, 2008, at 2:37 AM, John Culleton wrote: > >> There are days when I feel like collecting all the bits and pieces and >> writing somthing myself. But then I lie down until the fit passes. > > The lack of proper end user documentation is one of the main problems > with ConTeXt. There was talk of a book about ConTeXt but I haven't > heard about that one for a while. Probably impossible given the lack > of stability (aka ongoing development) of ConTeXt.
I believe a ConTeXt book is possible even with the problem of chasing a moving target. The user interface has not changed in quite some time. Moreover, we do not need an exhaustive manual listing all the features of ConTeXt; we need a user manual that explains the most commonly used features. Currently, the trouble with writing a book is that there is no one way of installing ConTeXt. Hopefully that will change once the minimal become more stable. The other thing is font handling, which is becoming considerably simpler with mkiv. Another thing is math support, which still lacks certain features that are critical. The right to left typsetting support is just beginning, and I imagine it will take some time before we settle on a stable interface. However, if we look at typsetting text in European languages with figures, tables, and footnotes, the interface has been more of less stable for more than 5 years. So, we can have a book that talks about the most common issues of these features and does not try to be exhaustive. I believe that it will be very useful to a lot of new users. The trouble is that writing such a book is a considerable effort. I don't know how much incentive and motivation there is for the authors. > ConTeXt could become very popular in teh TeX world if it had: > - A decent versioning support (where you can get documentation and > code that match and not code from 2008 with documentation from 2001) If you really want, you can get code from 2001 and then the code and documentation will watch (Just kidding). > - Side-by-side development of manuals and code That is done partly. The sources are very well documented in the most part. But then, that is not user interface documentation, it is code documentation. > As it is now, the developing community is restricted to the few gurus > who can hack the ConTeXt source code. No other sane person will try to > release and support something on such a volatile foundation. What > ConTeXt looks to me currently, is a personal swiss army knife of a few > people who have no need for end user documentation (so it never > arrives). I moved to ConTeXt years ago for a project expecting ConTeXt > to stabilize and come with better documentation. It never happened. Unfortunately, when it comes to choosing TeX based markup alternatives, you have two options: latex and context. Latex has been dorment for 15 years, and the developers are discussing the best way of solving complex typesetting problems and the best way to design a user interface. It is fairly well documented, because it is not evolving. (I don't know if LaTeX takes advantage of etex primitives or not). Context is adding new features constantly, there is not too much discussion on what is the best way to do things, Hans adds features that work, and not many people mind the not optimal speed or placements. The documentation is old, and at places woefully inadequate. So as a user, you have to choose between the less of the two evils :-(. One way for ConTeXt to develop is to become modular (i.e. follow the LaTeX model of development). Write a set of core macros, that are fixed and stable. Document them well. Write a regression suite. And do not change them. If you want new features, write a separate module with these features. Every few years, move some of the functionality of the modules into the core. This will help in solving the documentation problem. But what about package clashes? Should I load the module on math after the module on fonts but before the module for references? What about documentation of modules? I don't know if this is a better scenario. Another option is to have a editable book on wikibooks or some other similar site, with a pdf export. Then the users can correct the mistakes of the original book and the documentation will be up to date. There will be difference in styles, although I am not sure how much this will matter. The trouble with this model is that one will need to check the documentation. Will the "many eyes will avoid mistakes" model work? Aditya ___________________________________________________________________________________ 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 ___________________________________________________________________________________
