Re: Document formatting in Scheme

[Riku.Saikkonen@hut.fi (Riku Saikkonen)]

lisovsky@acm.org writes:
>TeX and HTML are examples of "presentation" markup which describe a
>layout of resulting document. Of course, TeX->HTML converters may be
>used, and so on, but (IMHO) "structural" markup is more useful in
>this context.

I think you need both. I think TeX is a pretty good solution for the
more low-level stuff (like tables or math formulas), but it still
needs a more high-level interface for specifying structure that is
specific to code. I think this is doable, because it's quite easy to
create new abstractions for structural markup in (La)TeX - I create
small ones in most of the LaTeX documents I write.

To produce good-quality output, it's not enough just to have a
converter to TeX from something else: The source language also needs
to have all the features of TeX - representations for all the
thousands of mathematical symbols and typographical features (no-break
space, different lengths of dashes, \@, hyphenation hints, etc.) and
so forth. Otherwise the output quality isn't as good as it would be
with a markup that uses a form of TeX as the source language.

(The TeXinfo language has yet another approach to this: you can
provide different versions of markup for different output formats. For
example, you can include TeX source for a mathematical formula and a
hand-made ASCII drawing of it in the same source document. The main
drawbacks of this, I think, are that you need to write some things
multiple times and to learn multiple languages, and it's difficult to
extend to new output formats.)

Perhaps it's possible to create a better documentation format than
(La)TeX that has all of TeX's features, including the pretty layout.
That would be a nice thing to have...

I guess the main thing I'm trying to say is that I wouldn't like to
have to learn a new language for documenting Scheme code, while
knowing that I can't use it to produce the good-quality output that
I'm used to... So it would be better to add new abstractions on top of
an existing markup language than to create a new one from scratch -
and (La)TeX is perhaps the only existing language that defines all the
details needed to produce really good-quality output.

>If the source code markup highlights its semantic structure when it
>is possible to use a number (relatively) independent stylesheets for
>generation of output documents, the situation here is the same as
>with HTML vs. XML.

Yes, and this applies to abstraced TeX source too. (A small example is
the various document classes that come with LaTeX - a \section can be
displayed in different ways.)

-- 
-=- Rjs -=- Riku.Saikkonen@hut.fi
"From cavern pale the moist moon eyes / the white mists that from earth arise /
to hide the morrow's sun and drip / all the grey day from each twig's tip."
    -- J. R. R. Tolkien