Re: My emacs was upgraded and I am a novice again

[David Kastrup <dak@gnu.org>]

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

> On 23/09/2007, David Kastrup <dak@gnu.org> wrote:
>
>> Then perhaps it would be time to get acquainted with the
>> documentation system of Emacs.
>
> I agree David. I am. From the .texi files as my starting point.

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.

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.

>> A working fast and efficient tool that is easy to use is not
>> lightly replaced.  Hammers might be archaic tools, but they still
>> do the job of driving nails.
>
> Not sure of the analogy, but I'd suggest the comparator might be a
> branch of a tree rather than a modern hammer.  The only part I find
> objectionable is having to bend the way I work to an archaic tool.

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

>> > http://savannah.gnu.org/search/index.php?type_of_search=soft&words=%%%
>> > there isn't even a general gnu documentation list, seems that
>> > texinfo is a given and not open to a challenge.
>>
>> There is no working challenge around.  HTML does not contain useful
>> indexing and structuring information.
>
> I believe there is. XML, not html.

XML is not an end user format.

> utf-8/16 encoding. Semantic markup way beyond what .texi can do,
> structured, encoding, fully supported by transforms etc. Eli points
> out the low likelihood of gnu adopting XML as a documentation
> system, which I can see.
>
> http://docbook2x.sourceforge.net/ even provides the transform so
> that Tim and others can continue to use the texi system.

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 also tried getting the manual pages of git into an appendix in the
user manual and failed abysmally.

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.

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.

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.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum