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

4 Mar 2010

      On Thu, Mar 4, 2010 at 5:11 PM, Aditya Mahajan  wrote:
...
On Thu, 4 Mar 2010, James Fisher wrote:
On Thu, Mar 4, 2010 at 4:06 AM, Aditya Mahajan  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.
Ouch.
...
- 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.
I'll put the PDF vs. HTML argument to rest :) ... suffice to say that I
thoroughly agree a semantic single-source solution with multiple outputs is
highly desirable.  I've just two pieces of guidance on the roads not to go
down:

(1) XML isn't a great solution because, while it's purely semantic,
extensible, easily parseable, and all the rest of it, it is *horrible* to
look at and maintain
(2) TeX isn't a great solution because of its curious property that it is
only really parseable by TeX itself ... none of the "tex-to-<whatever>"
attempts that I've seen are a viable option IMO.
...
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>
Duly noted.  I guess I've just happened to only see the latter.
...
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
___________________________________________________________________________________