On Thu, Mar 4, 2010 at 5:11 PM, Aditya Mahajan
<adityam@umich.edu> wrote:
On Thu, 4 Mar 2010, James Fisher wrote:
On Thu, 4 Mar 2010, James Fisher wrote:
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.
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