On Thu, 4 Mar 2010, James Fisher wrote:
Right, to show I'm not just empty words, I've just spent ~90 minutes preparing the beginnings of some decent documentation. Presenting http://github.com/eegg/ConTeXt-doc : basically, I've:
Interesting.
(2) converted it all to reStructuredText using html2rest.py ( http://bitbucket.org/djerdo/musette/src/tip/musette/html/html2rest.py)
The values in texwebshow are generated from xml files http://source.contextgarden.net/tex/context/interface/cont-en.xml
- There's a hella lot of documentation to do here. Most of the pages in texshow are just placeholders. There's also massive capabilities in something like Sphinx to organize the code documentation with sensible commentaries.
Someone will still need to *write* the details. That has been the biggest bane of ConTeXt documentation. Almost all documentation is written by Hans and Taco and currently they want to focus on development and advanced documentation, and not converting all documentation to an organized html.
- In my humble opinion, TeXies need to get out of the habit of 'self-documenting' TeX using TeX itself. TeX is not some replacement for all markup, it's for producing beautiful books (OK, and some presentations); in any case, this habit smacks of introversion.
In this case it is not a question of markup, but of the output format, and whether the source and the documentation are in sync or not. Basically, context sources are documented as %D documentation ... \tex code %D documentation \tex code In principle, we can replace the markup in the documentation to xml or an ascii markup. It is easy enough to extract the %D lines and post-process them by any tool that you like. The biggest advantage of using a pdf output is that we can show the output of code snippets. For example, \startbuffer some tex code \stopbuffer \typebuffer gives \getbuffer thereby ensuring that the documentation is showing the correct behavior. To do this in html requires additional context run, converting the output to png, and displaying the png (this is how the wiki treats <context> ... </context> tags).
- Why on earth is there a git repository that is just slave storage? That uses about 1% of its capabilities; it seems a terrible waste.
Because ConTeXt has only 1 main developer :-) Aditya