Re: Emacs documentation.

[Alan Mackenzie]

Hi, Dave!

On Sun, Sep 23, 2007 at 12:35:05PM +0100, Dave Pawson wrote:
> On 23/09/2007, Bastien <bzg@altern.org> wrote:
> > "Dave Pawson" <dave.pawson@gmail.com> writes:

> > > My offer is to convert the emacs documentation into docbook, version 5
> > > and work with those interested to improve it/bring it up to scratch.

> > It would be like trying to convert man pages into docbook. Why?

> Because XML is more flexible and a more modern standard for
> documentation IMHO.

Assembler is more flexible than C, but nobody nowadays uses assembler
very much.  Being "more modern" has never been a compelling argument for
anything in Emacs.  The question to ask is "is it any good?".

XML isn't any good as a source format; it's designed to be parseable by
programs with minimum effort, and places no value on being readable or
writeable.  Using XML/Docbook as a source language would be taking a
step back to 1960s technology:

(i) There is nothing like Texinfo's "@" or Lisp's/C's "\" for escape
purposes; you've got to write "<" as "&lt;", much like you had to write
".lt." in Fortran.  "ü" (German "u umlaut") appears as "&uuml;".  And so
on.  Yuck!  That stuff isn't unreadable, but it's uncomfortably close,
and it's clumsy enough to condemn XML.

(ii) Instead of using single character block delimiters like "{}" in C
or "()" in Lisp, XML uses long, long keywords, e.g.
"<VeryLongUnreadableDelimiter>" to open a block and
"</VeryLongUnreadableDelimiter>" to close it.  This harks back to
Algol's and Pascal's "BEGIN" and "END".  It also reduces the readability
and signal to noise ratio horribly.  Hackers detest prolixity.  ;-)

(iii) You can't just comment out a block of XML.  Doing so make the
source syntactically incorrect.  In fact, XML comments have a rigid
syntactic structure which stops you describing XML constructs in them.
I think this snag, in itself, rules out XML/Docbook as a sensible source
format.

(iv) This one might just be me, but I find "<" and ">" as delimiters far
too jaggy and violent (except for occasional use, as in C's "#include
<stdio.h>" or a C++/Java template).

> > I guess too many developpers actually use Texinfo to document their
> > code, and both users and developpers seem to be happy with that.

> You may be right. I think it is worth challenging though, otherwise
> we'll never progress?

XML as a source language isn't progress; it's like regressing into the
dark ages.  I suspect most Docbook writers actually use special purpose
editors to create their source code, rather than Emacs or vi.  This is
anathema to Emacs developers.  If we changed our default format from
.texi to .xml, I'd probably just give up hacking documentation - it'd be
too painful.

I'm not saying that Texinfo is ideal, and maybe we could use a better
format.  But XML isn't it.

> -- 
> Dave Pawson

-- 
Alan Mackenzie (Ittersbach, Germany).