Hi Aditya, On Thu, Mar 4, 2010 at 4:06 AM, Aditya Mahajan <adit...@umich.edu> wrote:
> 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 > > Well now, that's interesting. May I ask where that XML itself comes from? Is it hand-maintained by Hans/Taco/Patrick? > > - 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. > > Of course. So before people offer to write documentation, the barriers to it being written have to be lowered. No sane person wants to (read: *I* don't want to) hand-maintain one massive XML file. > > - 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). > > That is also something to think about. But I don't think it's really a serious problem -- the Mediawiki <context> works well enough. In terms of user-friendliness I would say it works better than in a massive PDF -- I would rather consult an image on the web. It wouldn't be too hard to alter Sphinx (as a for example; I suggest Sphinx so we can talk concretely) so that all TeX-markupped code is shown side-by-side as [ syntax-highlighted code | ConTeXt output as PNG ]. (This would be an improvement on the wiki implementation where the TeX code is duplicated in the source.) > > - 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 :-) > > Again I smell circular reasoning :) ... I suppose at this point I want to ask Hans personally: is cutting everyone else out from the workflow a design decision? > > Aditya > p.s.; I've been updating documentation of 'Enumerations' in the git repo -- I've chosen to develop a little patch of code as an example of what documentation code be across the board. Best, James > > ___________________________________________________________________________________ > 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 > > ___________________________________________________________________________________ >
___________________________________________________________________________________ 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 ___________________________________________________________________________________
