Re: Emacs documentation.

[David Kastrup <dak@gnu.org>]

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