Re: Emacs documentation.

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

Re: Emacs documentation.

[Dave Pawson]

[-- Attachment #1: Type: text/plain, Size: 2718 bytes --]

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

[-- Attachment #2: Type: text/plain, Size: 152 bytes --]

_______________________________________________
help-gnu-emacs mailing list
help-gnu-emacs@gnu.org
http://lists.gnu.org/mailman/listinfo/help-gnu-emacs

Re: Emacs documentation.

[Peter Dyballa]

Am 29.09.2007 um 17:47 schrieb Dave Pawson:

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

Can't you sleep just one night over it? This is what I learned from  
military service.

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

How about usable markup?


--
Mit friedvollen Grüßen

   Pete

"Give a man a fish, and you've fed him for a day. Teach him to fish,  
and you've depleted the lake."

Re: Emacs documentation.

[Eli Zaretskii]

> Date: Sat, 29 Sep 2007 15:46:01 +0000
> From: Alan Mackenzie <acm@muc.de>
> Cc: help-gnu-emacs@gnu.org
> 
> I suspect most Docbook writers actually use special purpose editors
> to create their source code, rather than Emacs or vi.

I think the real reason is that, in professional book publishing
business, many editorial and other auxiliary tools speak Docbook.  I'm
quite sure I've heard this in the past from someone who published
several books (and needed makeinfo's Docbook output feature for that
very reason).

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

Re: Emacs documentation.

[David Kastrup]

Alan Mackenzie <acm@muc.de> writes:

> Hi again, Dave!
>
>>Go ask around the OSS world what's being used for documentation.
>
> Why?

Because you'll find that any XML-based process would be rather unusual
(at least ouside of the Java world).  Man-pages, hand-written HTML,
plain text files, Texinfo, LaTeX and other stuff are more prevalent.

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

The long dampeners on Trabant were actually a good complement to the
lousy road quality in the GDR.  Imported cars suffered from a higher
probability of breakdowns because they were less well suited to the
potholes there.

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

Well, he did personally inform me that he put me in his killfile when
I made a list of detailed problems and tried to elicit comments.  So
that is one way of addressing such points.

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

To be fair: people using Emacs _are_ generally using a special purpose
editor (in the form of a good major mode).  Even LaTeX is not
uncommonly written with special purpose editors and modes.

So if you want to get more relevant numbers, you probably should ask
on some vi user group, as that sort of editor can't be tailored as
well to the task.  How many of those would write Texinfo and LaTeX
with their favorite general purpose editor, but revert to special
systems for XML writing?

I suppose still some, but have no hard numbers.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Emacs documentation.

[martin rudalics]

 > ... or Trabant cars ...

Alan, you're exaggerating.  Trabis were not that bad.

Re: Emacs documentation.

[Alan Mackenzie]

'nAbend, David!

On Sat, Sep 29, 2007 at 10:01:40PM +0200, David Kastrup wrote:
>looked at Alan Mackenzie <acm@muc.de> writes:

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

> > Why?

> Because you'll find that any XML-based process would be rather unusual
> (at least ouside of the Java world).  Man-pages, hand-written HTML,
> plain text files, Texinfo, LaTeX and other stuff are more prevalent.

That's what I would've thought.  Given the existence of, in particular,
TeX and LaTeX, I really don't understand what the point of Docbook is.
(That's NOT a rhetorical comment.)

What has irritated me about David P.'s posts is he seems to assume that
Docbook doesn't need justification - it is the Right Thing for any
documentation application, and it is somehow not done to ask questions
about it.  I'm still hoping he'll come back with some answers.

[ .... ]

> The long dampeners on Trabant were actually a good complement to the
> lousy road quality in the GDR.  Imported cars suffered from a higher
> probability of breakdowns because they were less well suited to the
> potholes there.

How things have changed since 1989!

[ .... ]

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

> To be fair: people using Emacs _are_ generally using a special purpose
> editor (in the form of a good major mode).  Even LaTeX is not
> uncommonly written with special purpose editors and modes.

I didn't express myself very well.  I think what I meant by "special
purpose editor" was one that interprets the XML data structure and hides
it from the user, much like Open Office does with ODF.  I contrast this
with an editor where you actually see and edit the raw XML file, possibly
with the help of a good major mode.  I suppose it's analogous to the
difference between editing Elisp source files and hacking through the
internal form created by the Lisp reader.

I don't think that Emacs developers would be willing to learn such a
special purpose editor, just to write Info-MkII documents with.

> So if you want to get more relevant numbers, you probably should ask
> on some vi user group, as that sort of editor can't be tailored as
> well to the task.  How many of those would write Texinfo and LaTeX
> with their favorite general purpose editor, but revert to special
> systems for XML writing?

> I suppose still some, but have no hard numbers.

Nor me.

> David Kastrup, Kriemhildstr. 15, 44793 Bochum

-- 
Alan Mackenzie (Ittersbach, Germany).

Re: Emacs documentation.

[Tom Tromey]

>>>>> "Alan" == Alan Mackenzie <acm@muc.de> writes:

Alan> I didn't express myself very well.  I think what I meant by
Alan> "special purpose editor" was one that interprets the XML data
Alan> structure and hides it from the user, much like Open Office does
Alan> with ODF.

This is sort of a diversion, but I've heard talk from time to time
about writing such an editor as an Emacs mode.  As an existing
example, there's `enriched.el'.  (Open etc/enriched.doc for an
example, or look at it with find-file-literally to see the contents as
they appear on disk.)

A full ODF editor would be a major undertaking.

Tom

RE: Emacs documentation.

[Drew Adams]

> Alan> I didn't express myself very well.  I think what I meant by
> Alan> "special purpose editor" was one that interprets the XML data
> Alan> structure and hides it from the user, much like Open Office does
> Alan> with ODF.
>
> This is sort of a diversion, but I've heard talk from time to time
> about writing such an editor as an Emacs mode.  As an existing
> example, there's `enriched.el'.  (Open etc/enriched.doc for an
> example, or look at it with find-file-literally to see the contents as
> they appear on disk.)
>
> A full ODF editor would be a major undertaking.

FWIW, and not terribly relevant to Emacs:

I didn't follow everything in this thread, but Adobe Framemaker does what
you describe: it is XML underneath (DTD or XML Schema), and users manipulate
things in WYSIWYG fashion. However, they can still see and manipulate the
document structure, without having to look at the XML code. It is in fact
quite a good XML round-trip editor for document-centric XML use cases.

Re: Emacs documentation.

[David Kastrup]

Alan Mackenzie <acm@muc.de> writes:

> On Sat, Sep 29, 2007 at 10:01:40PM +0200, David Kastrup wrote:
>>looked at Alan Mackenzie <acm@muc.de> writes:
>
>> >>Go ask around the OSS world what's being used for documentation.
>
>> > Why?
>
>> Because you'll find that any XML-based process would be rather
>> unusual (at least ouside of the Java world).  Man-pages,
>> hand-written HTML, plain text files, Texinfo, LaTeX and other stuff
>> are more prevalent.
>
> That's what I would've thought.  Given the existence of, in
> particular, TeX and LaTeX, I really don't understand what the point
> of Docbook is.  (That's NOT a rhetorical comment.)

Well-formed Docbook-XML can be transformed in a number of ways without
further hassles.  As an example, I have been able to transform the git
user manual into a valid Texinfo document just by calling some
converters.

That's impressive.  In contrast, Texinfo is something that basically
happens to compile or not, given a particular version of texinfo.tex
and/or makeinfo.

You can also say "I don't like the look of this HTML/PDF/groff, let's
try a different converter/style", something which you can't do with
Texinfo.

If you take a look at, say,
<URL:http://www.kernel.org/pub/software/scm/git/docs/user-manual.html>,
you'll find that the look is quite more pleasant than the HTML
renditions of makeinfo.  With Docbook/XML, playing with different end
formats and forms might be easier: the format can be translated
mechanically rather well _iff_ you are familiar with the toolchain and
how to program it.

> What has irritated me about David P.'s posts is he seems to assume
> that Docbook doesn't need justification - it is the Right Thing for
> any documentation application, and it is somehow not done to ask
> questions about it.  I'm still hoping he'll come back with some
> answers.

Yes.

>> To be fair: people using Emacs _are_ generally using a special
>> purpose editor (in the form of a good major mode).  Even LaTeX is
>> not uncommonly written with special purpose editors and modes.
>
> I didn't express myself very well.  I think what I meant by "special
> purpose editor" was one that interprets the XML data structure and
> hides it from the user, much like Open Office does with ODF.  I
> contrast this with an editor where you actually see and edit the raw
> XML file, possibly with the help of a good major mode.  I suppose
> it's analogous to the difference between editing Elisp source files
> and hacking through the internal form created by the Lisp reader.

Hm, I think I draw the line differently.  For me, Oxygen/XML is a
special-purpose XML editor, even though it will show the source text,
and Bluefish is a special-purpose HTML editor.  Both can fold stuff
and validate it, but so can Emacs with nxml-mode.  Kile
<URL:http://kile.sourceforge.net> is certainly a special-purpose LaTeX
editor even though it shows everything.  Calling AUCTeX
<URL:http://www.gnu.org/software/auctex> non-special-purpose even
though it does dynamic folding of LaTeX structures, WYSIWYG rendition
in the source buffer
<URL:http://www.gnu.org/software/auctex/preview-latex.html>, source
special support and other stuff seems sort of disingenuous.  In that
context, Emacs is not as much a general-purpose editor, but rather a
general-purpose editing platform on top of which special-purpose
editors are implemented in the form of major modes.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

emacs documentation

[Sean Sieger]

I've been reading `An Introduction to Programming in Emacs Lisp' closely
and sometimes I come upon typos---or what look like typos, grammatical
or otherwise.  To whom should I, or how should I report them?  And more
generally, where is the information on how to contribute to
documentation?

Thank you.

Re: emacs documentation

[Lennart Borgman (gmail)]

Sean Sieger wrote:
> I've been reading `An Introduction to Programming in Emacs Lisp' closely
> and sometimes I come upon typos---or what look like typos, grammatical
> or otherwise.  To whom should I, or how should I report them?  And more
> generally, where is the information on how to contribute to
> documentation?


http://lists.gnu.org/archive/html/emacs-devel/2008-10/msg00184.html

RE: emacs documentation

[Drew Adams]

> I've been reading `An Introduction to Programming in Emacs 
> Lisp' closely and sometimes I come upon typos---or what look like
> typos, grammatical or otherwise.  To whom should I, or how should
> I report them? And more generally, where is the information on how
> to contribute to documentation?

`M-x report-emacs-bug'
See the Emacs manual, node Bugs.

Re: emacs documentation

[Sean Sieger]

"Lennart Borgman (gmail)" <lennart.borgman@gmail.com> writes:

    Sean Sieger wrote:
    > I've been reading `An Introduction to Programming in Emacs Lisp' closely
    > and sometimes I come upon typos---or what look like typos, grammatical
    > or otherwise.  To whom should I, or how should I report them?  And more
    > generally, where is the information on how to contribute to
    > documentation?


    http://lists.gnu.org/archive/html/emacs-devel/2008-10/msg00184.html

Right?  This is the article that got me thinking about improving
GNU/Emacs and improving my use of it.  Thanks, Lennart.

Re: emacs documentation

[Sean Sieger]

"Drew Adams" <drew.adams@oracle.com> writes:

    > I've been reading `An Introduction to Programming in Emacs 
    > Lisp' closely and sometimes I come upon typos---or what look like
    > typos, grammatical or otherwise.  To whom should I, or how should
    > I report them? And more generally, where is the information on how
    > to contribute to documentation?

    `M-x report-emacs-bug'
    See the Emacs manual, node Bugs.

Done.

Thank you, Drew.