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:
(1) wget'ed all the English HTML from the texshow documentation
(2) converted it all to reStructuredText using html2rest.py (
http://bitbucket.org/djerdo/musette/src/tip/musette/html/html2rest.py)
(3) plugged the result into a fresh installation of the Sphinx documentation
system
(4) Pushed the whole thing to a new github repo (including generated HTML so
you can take a look without bothering to install Sphinx)
To note:
- Sphinx really is state-of-the-art. I suggest you spend a few minutes
browsing http://docs.python.org/ to see what I think is 'good
documentation.' It runs on reStructuredText, a powerful, purely semantic
and readable (almost invisible) markup.
- Revision control, people! I strongly encourage everyone to fork and push
this repository.
- 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.
- 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.
To address previous points in this thread:
- Maybe I exaggerated a tad on how little documentation there is.
- 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.
So, thoughts?
James
On Thu, Mar 4, 2010 at 12:08 AM, Aditya Mahajan
On Wed, 3 Mar 2010, James Fisher wrote:
Also, re "there is only one ConTeXt developer --- Hans Hagen":
I'd suggest a few reasons for this are: (1) in order to develop on a project, you first need a the high-level appreciation of the system that comes from documentation
MkII is fairly well documented. See http://wiki.contextgarden.net/Official_ConTeXt_Documentation
MkIV is only documented at http://www.pragma-ade.com/general/manuals/mk.pdf. Part of the reason is that it is still changing.
The documentation is not perfect, but is huge (more than 1000 pages last time I checked). Saying that ConTeXt is undocumented in not fair, IMO.
(2) ConTeXt does not have any revision control system that I can see (the
only source code browser seem to be http://source.contextgarden.net/which looks entirely custom); all I can find is the SVN of the in-progress manual
git clone http://dl.contextgarden.net/distribution/git/
Hans does not use a public version control system. The above repository is a daily snapshot of ConTeXt files.
(3) The low-level macro documentation at
http://texshow.contextgarden.net/is a start, but: (i) instead of a custom system with basic editing, a modern documentation system (I'm thinking of http://sphinx.pocoo.org/ used for the *fantastic* documentation of the Python library) would be more productive, and (ii) this documentation is completely non-structured, being just an alphabetical list.
(This from the community that came up with "literate programming"?)
The sources are fairly well documented. Just read the source files, or see http://foundry.supelec.fr/gf/project/modules/ for PDF output.
The question of documentation has come up many times in the past. Everytime we conclude that we need a volunteer to do maintain the documentation, but so far no one has stepped forward (hint, hint).
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 : http://foundry.supelec.fr/projects/contextrev/ wiki : http://contextgarden.net
___________________________________________________________________________________