On Thu, Mar 4, 2010 at 4:06 AM, Aditya Mahajan
<adityam@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:
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?
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