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

[Dave Pawson]

On 23/09/2007, David Kastrup <dak@gnu.org> wrote:
> "Dave Pawson" <dave.pawson@gmail.com> writes:

> One does not get acquainted with Emacs' editing by reading its C and
> Lisp source code either.  The documentation system of Emacs is _info_
> as far as online access is concerned.  The .texi files are not
> intended for reading, but for writing.  It is source code.

One does if one believes they can be improved.


>
> So I really repeat the recommendation to get acquanted with the info
> reader in Emacs.  It puts the information at your fingertip, and the
> .texi files don't do that.

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?

 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.



> XML is not an end user format.

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



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




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


>
> While the toolchain may be in better shape (I found it to produce
> pretty much perfect Texinfo from the get-go while Texinfo's Docbook
> output was ill-formed), it is just not usable without months of study
> and fishing for information in distributed places.



>
> Coming back to the manual page problem: in Texinfo, this could be
> solved easily using @include and @raisesections, consulting just a
> single manual about a single format, a well-structured and indexed
> manual that can be browsed efficiently in Emacs even on slow machines.

Which is a solution to the last issue.
>From an XML source I could identify and write out small files needed
by the elisp for inclusion where needed (even language specific if
needs be).





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

I've sent a demo chapter to Eli for comment.

No point if the actual documenters are unwilling to move to XML though.

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!

regards

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