Re: Emacs documentation.

[Alan Mackenzie]

Hi again, Dave!

>On 29/09/2007, Alan Mackenzie <address@hidden> 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.

I have.  I once had to hack an XML config file and I've amended some
Docbook source code, though it was some while ago.  They were both
horrible.

What's so good about XML/Docbook as a source format?

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

Oh good!  So please correct my misapprehension and tell me what the
Docbook escape character is.  Next, please tell me how to write a "<"
and a "ü" in a modern Docbook source.  At any stage, you're more than
welcome to attempt to persuade me that writing Docbook source is easy,
pleasant and productive.  Thanks in advance!

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

It doesn't matter what it's called.  The important point is that it's
difficult to read and likely difficult to write - much more so than the
Texinfo equivalents.

>> (iii) You can't just comment out a block of XML.

>Wrong.

Oh good!  Please tell me how "just" to comment out a block of XML, with
emphasis on the word "just".  I seem to remember Emacs in SGML mode
going through the region being commented, replacing all the "--"s with
"-/-", and not being able to reverse that transformation.  That's unjust
indeed.

>> Doing so makes 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?

In XM hell.

[ .... ]

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

Why?  The fact that vast numbers of people use or have used Microsoft
Windows or XML or Cobol or Emacs or VHS videotape or Trabant cars or
variable length character encodings or Docbook or Fortran has no bearing
on whether these things are any good, or what they are good for.

I'm not sure you've thought this issue through.  Popularity doesn't imply
quality.  XML-based thingies and Microsoft Word (*.doc) are both widely
used formats, yet at least half of them are bad formats.  As a Docbook
enthusiast, you should be able to counter my posts by arguing the
intrinsic merits of Docbook/XML, and why it would be superior to Texinfo
in the Emacs project.  I haven't seen you doing this.

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

Do most Docbook writers use special purpose editors or don't they?

>-- 
>Dave Pawson

-- 
Alan Mackenzie (Ittersbach, Germany).