Re: INFO on add-ons

["Stephen J. Turnbull" <stephen@xemacs.org>]

>>>>> "Stefan" == Stefan Monnier <monnier+gnu/emacs@rum.cs.yale.edu> writes:

    Stefan> Huh?!?  What kind of wacky Emacs macros did you have to
    Stefan> maintain indices and to ensure a consistent style when
    Stefan> editing Info files ?

I didn't do indicies (at the time writing Info was a lot easier for me
than the mechanics of contributing, so I knew what was in there), mea
maxima culpa, although I doubt it would be that hard to write a macro
to do it.

As for style, Info has basically three forms of physical presentation,
*emphasis*, `literals' and META VARIABLES.  Very mnemonic.  (I find
modern Texinfo bewildering in its variety of useful-only-in-the-
hardcopy markup, @url and @htmlurl and @file and @dir and @subdir
and @lionsandtigersandbearsohmy and so on.)

    Stefan> What's so great about <kindex key="C-x k"/> compared to
    Stefan> @kindex C-x k ?

I wouldn't have a kindex element.  It would be an attribute of the key
element:

<key index="def" xindex="kill-buffer">C-x k</key> runs the command
<cmd index="ref">kill-buffer</cmd>. ... An alternative to
<key index="ref">C-x k</key> <key>RET C-x b UP RET</key> is
<key>M-x <cmd index="ref">erase-buffer</cmd> RET</key>.

This means that it would be easy to make an XML-based indexing helper.
If you just index all references, it could be automatic.  If you want
intelligent indexing, as above, it would be interactive.  This would
mean that it's hardly a crime to be lazy about indexing, as I was with
the third key element above.  I'm sure you could do it with regexps
and Lisp for texinfo, too, but with XML these possibilities just walk
up and bite you on the ankle.

Furthermore, XML allows you to take natural advantage of commonality,
as I did in the example above by endowing the cmd element with an
index attribute.  Now, any time I want to index something, I just add
an index attribute.  I don't need to remember @kindex and @cindex and
@whateverindexthetexinfomaintainerdeemsnecessarytoday.  If we add an
"eg" (to be distinguished from "ref") value for index attributes, then
it's easy to ensure all indexables share that new distinction.

And the validating parser will barf if index isn't an attribute of
key, while Texinfo doesn't care if I @kindex{Stefan Monnier}.  (Tell
me about how easy it would be to fix _that_ bug.)  If I really want to
index keys, I report it to the XML/Info maintainer as an RFE.  If
approved, implementation is trivial.  You change the definition in two
places in the DTD.  You add the index attribute to key, and key to the
list of indexables for an appropriate index.

It's also easy to add features like xindex, which would automatically
put "see also" entries in the indicies.

    Stefan> What's so great about <sample>foobar</sample> compared to
    Stefan> @sample{foobar} ?

Nothing.  Once again, I want the Document Object Model, so I can use
the many tools that are being developed for structure manipulation.  I
want locality (index an attribute of key, rather than a separate
markup).  I want orthogonality, so that once a new contributor learns
a concept, she can employ it correctly everywhere.  Documentation
should be do-able by users who aren't specialists in Emacs or in
documentation.  (See the Thi-Thien Nguyen thread.)

    Stefan> XML has its advantages, but for a *source* format, it's just
    Stefan> way too cumbersome/verbose,

That is clearly a deficiency of XML in this application, although I
hardly think it's crippling.  In "suppress-attribute" mode, the
example above appears as

<key>C-x k</key> runs the command <cmd>kill-buffer</cmd>. ... An
alternative to <key>C-x k</key> <key>RET C-x b UP RET</key> is
<key>M-x <cmd>erase-buffer</cmd> RET</key>.

Perhaps with fontification to indicate that some of the elements have
hidden attributes.  Still more verbose, but I'm willing to sacrifice
terseness for the power and orthogonality I've described above, power
that Somebody Else Somewhere is already implementing and maintaining
for me.  YMMV.

    Stefan> unless you use an editor that hides the markup, but then
    Stefan> what would such an editor look like ?

PSGML?  outline-mode (for structure editing)?  It would even be
possible to use TeX-like <elt>{element contents} notation to decrease
verbosity.

    Stefan> If you say WYSIWYG

Please, I have asthma.  Take your strawman outside.  ;-)


-- 
Institute of Policy and Planning Sciences     http://turnbull.sk.tsukuba.ac.jp
University of Tsukuba                    Tennodai 1-1-1 Tsukuba 305-8573 JAPAN
 My nostalgia for Icon makes me forget about any of the bad things.  I don't
have much nostalgia for Perl, so its faults I remember.  Scott Gilbert c.l.py