From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: David Kastrup Newsgroups: gmane.emacs.help Subject: Re: My emacs was upgraded and I am a novice again Date: Sun, 23 Sep 2007 11:25:24 +0200 Organization: Organization?!? Message-ID: <85ejgprawr.fsf@lola.goethe.zz> References: <46F2BA57.3060604@gmail.com> <87fy16q8kq.fsf@lion.rapttech.com.au> <85myvdre11.fsf@lola.goethe.zz> NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: sea.gmane.org 1190540439 5893 80.91.229.12 (23 Sep 2007 09:40:39 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Sun, 23 Sep 2007 09:40:39 +0000 (UTC) To: help-gnu-emacs@gnu.org Original-X-From: help-gnu-emacs-bounces+geh-help-gnu-emacs=m.gmane.org@gnu.org Sun Sep 23 11:40:33 2007 Return-path: Envelope-to: geh-help-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by lo.gmane.org with esmtp (Exim 4.50) id 1IZNwz-0006FZ-Iv for geh-help-gnu-emacs@m.gmane.org; Sun, 23 Sep 2007 11:40:29 +0200 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1IZNww-0000vt-Vu for geh-help-gnu-emacs@m.gmane.org; Sun, 23 Sep 2007 05:40:27 -0400 Original-Path: shelby.stanford.edu!headwall.stanford.edu!newshub.sdsu.edu!nx02.iad01.newshosting.com!newshosting.com!newsfeed.icl.net!newsfeed.fjserv.net!newsfeed.arcor.de!newsspool4.arcor-online.net!news.arcor.de.POSTED!not-for-mail Original-Newsgroups: gnu.emacs.help X-Face: 2FEFf>]>q>2iw=B6, xrUubRI>pR&Ml9=ao@P@i)L:\urd*t9M~y1^:+Y]'C0~{mAl`oQuAl \!3KEIp?*w`|bL5qr,H)LFO6Q=qx~iH4DN; i"; /yuIsqbLLCh/!U#X[S~(5eZ41to5f%E@'ELIi$t^ Vc\LWP@J5p^rst0+('>Er0=^1{]M9!p?&:\z]|;&=NP3AhB!B_bi^]Pfkw User-Agent: Gnus/5.11 (Gnus v5.11) Emacs/22.1.50 (gnu/linux) Cancel-Lock: sha1:gB7dycDcs7TV0Syr+8+QCPjcuFU= Original-Lines: 86 Original-NNTP-Posting-Date: 23 Sep 2007 11:25:27 CEST Original-NNTP-Posting-Host: 671373c4.newsspool4.arcor-online.net Original-X-Trace: DXC=gdA?QRfh_Dmg`45cDR8l?o4IUK List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: help-gnu-emacs-bounces+geh-help-gnu-emacs=m.gmane.org@gnu.org Errors-To: help-gnu-emacs-bounces+geh-help-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.help:47758 Archived-At: "Dave Pawson" writes: > On 23/09/2007, David Kastrup 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