Re: Emacs documentation.

[Dave Pawson]

On 29/09/2007, Alan Mackenzie <acm@muc.de> wrote:
>
> > 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?".

Yes. Look around.


>
> 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:

Rubbish.


>
> (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.

Go play catchup Alan. You're years behind. About ten.


>
> (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.  ;-)

It's called semantic markup.

>
> (iii) You can't just comment out a block of XML.
Wrong.
> 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.

Where have you been?

>
> (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).

It's just you.

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

Let's agree to differ on 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.

Go ask around the OSS world what's being used for documentation.

>  I suspect most Docbook writers actually use special purpose
> editors to create their source code, rather than Emacs or vi.

Emacs has done for me for the last ten years.

> I'm not saying that Texinfo is ideal,


Oh good.



-- 
Dave Pawson
XSLT XSL-FO FAQ.
http://www.dpawson.co.uk