[NTG-context] Occasional words sticking out from flush-right

James Fisher jameshfisher at gmail.com
Thu Mar 4 15:39:28 CET 2010


Hi Aditya,

On Thu, Mar 4, 2010 at 4:06 AM, Aditya Mahajan <adityam at 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 at 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
>
> ___________________________________________________________________________________
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.ntg.nl/pipermail/ntg-context/attachments/20100304/e0c0d2e4/attachment-0001.html>


More information about the ntg-context mailing list