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

Thu Mar 4 18:11:45 CET 2010

```On Thu, 4 Mar 2010, James Fisher wrote:

> On Thu, Mar 4, 2010 at 4:06 AM, Aditya Mahajan <adityam at umich.edu> wrote:
>
>> On Thu, 4 Mar 2010, James Fisher wrote:
>>
>>  (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?

It is hand maintained. Ideally, whenever someone suggests an enhancement,
they should also send an update for the interface files.

>>  - 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.

I personally prefer a massive PDF to a massive HTML with lots of images.
With pdf you can also *search* the output. A perfect solution will be to
generate both outputs from a single source, but that means a custom made
solution.

> 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.)

This is what wiki does. <context source="yes"> shows both the source and
the output side by side. This was a later edition, so there is still code
that duplicates the source in  <texcode> and <context>