Re: Emacs documentation. Was My emacs was upgraded and I am a novice again

[David Kastrup]

"Dave Pawson" <dave.pawson@gmail.com> writes:

> On 23/09/2007, David Kastrup <dak@gnu.org> wrote:
>> "Dave Pawson" <dave.pawson@gmail.com> writes:
>
> Point taken.
>
>> Again, you are confusing format and reader.  The Texinfo format is
>> archaic (but nevertheless quite alive).  The reader is what Emacs
>> offers you.  Nobody has ever proposed a user interface that would be
>> more efficient or convenient than Emacs' current info reader.
>
> Caveat. When used to it?

No caveat.  When you are not used to it, you start by clicking either
the links in the text or headers (which gives you all that HTML has to
offer with regard to navigation) or the Info menu (which gives you
more).

>> So the source of contention is the source file format (and the
>> compiled _fast_ info format), but that is nothing that would affect
>> the _usage_ of the files: changing the format would probably
>> achieve no user-visible change inside of Emacs apart from slowing
>> it down.  At the current point of time, info access is near
>> instantaneous.
>
> Can't disagree with that.
>
> But yes. the contention is that the source file format and end user
> access can be improved.

Both are different things.  So far, I have yet to see a proposal for
improving the end user access that would benefit from a source file
format change.

>> XML is not an end user format.
>
> It's the best starting point for an end user format that I've ever
> found.

Correction.  "best general purpose starting point".  It is not the
best starting point for info, for example...

>> docbook2x is undocumented software.  I used it to provide a user
>> manual in info format for git.  It was reasonably easy to do this,
>> except that it was near impossible to put the respective directory
>> entries at the top.  After working on this a few days, I punted and
>> used a Perl script for post-processing the Texinfo file.  It seems
>> from the few uses one sees on the Web that nobody else fared
>> better.
>
> I've not used it so I can't comment.

You better do so.  See below.

>> The combined largely under- or undocumented and inscrutable
>> layerism of XML, Docbook, Ascii2doc and Docbook2x makes it
>> impossible to achieve a particular effect at the end of the
>> toolchain without weeks of previous study.
>
> Yes. I agree. The combination is nearly as bad as sgml+dsssl+emacs
> :)
>
> I've spent that time and am fairly happy with docbook, xml, xslt,
> xsl-fo.  (I host the docbook and xslt faq )

Here is the problem: Richard Stallman has been quite sympathetic to
replacing Texinfo if a suitable alternative comes up.  It hasn't up to
now.  Here are the requirements for it as far as I am concerned (I
don't think you have a reasonable chance to get this past Richard if
the following points aren't addressed satisfactorily):

a) the essential parts of the toolchain must be well-documented from a
documentation writer's as well as a programmer's point of view and
most likely copyright-assigned to the Free Software Foundation.  That
is the state of affairs with Texinfo.  Documentation is an essential
part of the GNU system.  Relying on the continued goodwill of
independent third parties would be a step backwards from the current
state of affairs.  This would seem to particularly apply to Docbook2X:
it apparently does a good job, but it is not clear what input it will
accept, and how a typical user could influence or extend its
operation, and it is written (and copyrighted) by someone who does not
as a rule answer Email with questions (at least I have tried and
failed to get a response).

b) the expressivity of Texinfo must be preserved.  This concerns most
of the options for detailed and coarse tables of contents and indices.

c) end user access must be fast and convenient from within Emacs.  At
the current point of time, using Docbook2x for going via Texinfo would
mostly do the trick as a transition strategy.  But there would likely
need to be some translation process (similar to producing cattable
manpages from *roff sources) with fewer external dependencies that one
could rely on.

>> In contrast, the information for the XML toolchains is scattered
>> all over the place and rarely in a format that can be readily
>> browsed by humans without starting to convert and manipulate stuff
>> first.
>
> Yep.
>
> 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.

But that's the wrong way round.  At the current point of time, it is
not the Emacs documentation that needs to be brought up to scratch,
but rather the Docbook documentation, toolchain and general situation.
Before that is the case, any change in the source file format would be
a waste of time.

Experimenting with other toolchains might be easier if the Docbook
output of makeinfo was improved to a point where it would in most
cases deliver actually valid output.  Being close to "roundtripping"
would be a strong argument.

> I've sent a demo chapter to Eli for comment.
>
> No point if the actual documenters are unwilling to move to XML
> though.

As long as there is nothing in it for them, why should they?

> I've also mailed the makeinfo guy at gnu, see if the .texi to
> docbook can be revived. I've a nasty feeling its written in tex
> macros!

As an additional note: the output of the Docbook toolchain appears to
be quite better than that of the Texinfo toolchain _except_ where the
info format is concerned: the HTML pages look nicer, the printed pages
possibly too (though Texinfo does a splendid job at PDF indexing).
And Texinfo does not really cut it with regard to utf-8 character
sets.  I would still like to see evidence, though, that the available
Docbook toolchains do a better job where PDF, PostScript or
preformatted plain text are concerned (pure HTML likely should work).

So that is a definite selling point once the _primary_ purpose of
Texinfo, a fast user-accessible rich structured hypertext format with
a reasonably accessible and documented source code format to people
not specializing in XML, is secured.

That is by no means a small job.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum