From mboxrd@z Thu Jan 1 00:00:00 1970 Path: main.gmane.org!not-for-mail From: "Robert J. Chassell" Newsgroups: gmane.emacs.devel Subject: Re: Texinfo Mode: node-based movement functions. Date: Sun, 7 Nov 2004 23:52:12 +0000 (UTC) Message-ID: References: Reply-To: bob@rattlesnake.com NNTP-Posting-Host: deer.gmane.org X-Trace: sea.gmane.org 1099871591 28114 80.91.229.6 (7 Nov 2004 23:53:11 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Sun, 7 Nov 2004 23:53:11 +0000 (UTC) Cc: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Mon Nov 08 00:53:02 2004 Return-path: Original-Received: from lists.gnu.org ([199.232.76.165]) by deer.gmane.org with esmtp (Exim 3.35 #1 (Debian)) id 1CQwqD-0000ll-00 for ; Mon, 08 Nov 2004 00:53:01 +0100 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.33) id 1CQwyX-0001gP-MU for ged-emacs-devel@m.gmane.org; Sun, 07 Nov 2004 19:01:37 -0500 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.33) id 1CQwy2-0001gI-9n for emacs-devel@gnu.org; Sun, 07 Nov 2004 19:01:06 -0500 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.33) id 1CQwy1-0001g6-FK for emacs-devel@gnu.org; Sun, 07 Nov 2004 19:01:05 -0500 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.33) id 1CQwy0-0001g3-Ss for emacs-devel@gnu.org; Sun, 07 Nov 2004 19:01:05 -0500 Original-Received: from [69.168.110.189] (helo=rattlesnake.com) by monty-python.gnu.org with esmtp (Exim 4.34) id 1CQwpX-0005cn-7i for emacs-devel@gnu.org; Sun, 07 Nov 2004 18:52:19 -0500 Original-Received: by rattlesnake.com via sendmail from stdin id (Debian Smail3.2.0.115) Sun, 7 Nov 2004 23:52:12 +0000 (UTC) Original-To: Alan Mackenzie In-reply-to: (message from Alan Mackenzie on Sun, 7 Nov 2004 13:55:04 +0000 (GMT)) X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: main.gmane.org gmane.emacs.devel:29545 X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:29545 Why do I focus so much on nodes? What do you think of `C-c C-s' (texinfo-show-structure), especially when called with a prefix arg, so it lists the @node lines, too? I've never seen a printed form of a Texinfo manual. Ah... Even if you do not print it out, please run texi2dvi cc-mode.texi to create a DVI version of the CC Mode manual, and look at it using xdvi cc-mode.dvi & Indeed, please put the following at the beginning of cc-mode.texi: @end ignore ## Info output makeinfo --no-split --paragraph-indent=0 --verbose cc-mode.texi ## DVI output texi2dvi cc-mode.texi ## HTML output makeinfo --html --no-split --verbose cc-mode.texi ## Plain text output makeinfo --fill-column=70 --no-split --paragraph-indent=0 \ --verbose --no-headers --output=cc-mode.txt cc-mode.texi ## DocBook output makeinfo --docbook --no-split --paragraph-indent=0 \ --verbose cc-mode.texi ## XML output makeinfo --xml --no-split --paragraph-indent=0 \ --verbose cc-mode.texi #### (You must be in the same directory as the viewed file.) ## View DVI output xdvi cc-mode.dvi & ## View HTML output mozilla cc-mode.html @end ignore For an example, see emacs/lispintro/emacs-lisp-intro.texi in the Emacs distribution. It is a good idea to run the commands to create the Info, HTML, and DVI outputs frequently and to look at them. That way, you can catch errors early on. (It is also a good idea to listen to the Info using Emacspeak, as if you were driving a car or permanently blind. If the document makes sense when you listen to it, it is well written. Now that Emacspeak has good-enough, free software text-to-speech synthesizers, anyone can do this.) What do you mean by "too close" here? Woops! I was being old fashioned. I had forgot about XML. I had meant to push you towards @heading but should direct you instead to the less good @unnumberedsec. As for being "too close" -- it is best to start a section within 24 or so lines of the beginning of a chapter so that the section menu is visible in Info. However, in a printed book, that looks bad. So, in the old days, we hid that first section line by putting it in `@ifinfo'. But XML has come along, so instead the Texinfo manual says: (texinfo)Menu Location In the past, we recommended using a `@heading' command within an `@ifinfo' conditional instead of the normal sectioning commands after a very short node with a menu. This had the advantage of making the printed output look better, because there was no very short text between two headings on the page. But aside from not working with `makeinfo''s implicit pointer creation, it also makes the XML output incorrect, since it does not reflect the true document structure. So, unfortunately we can no longer recommend this. One modern way to do the job is to use @unnumberedsec in place of @section for the first subnode of a chapter (or lower level construct). This does not always produce the right output, but .... For example, emacs/lispintro/emacs-lisp-intro.texi has this format (leaving out the @node lines that a prefix arg to texinfo-show-structure provides): 1053:@chapter List Processing 1083: @section Lisp Lists 1115: @unnumberedsubsec Numbers, Lists inside of Lists 1144: @subsection Lisp Atoms 1225: @subsection Whitespace in Lists Please compare the Info output with the DVI output. That works out well. The table of contents for the HTML output, which is in emacs/info/eintr.html looks like this, which is a problem with this format, but not a big one: 1.1 Lisp Lists * Numbers, Lists inside of Lists * 1.1.1 Lisp Atoms * 1.1.2 Whitespace in Lists Since Info and printed copies are the most efficient forms in which a Texinfo document appears (and probably the most common, although many people use the less efficient HTML format), the lack of a number for the `unnumbered' HTML node is OK. Someday, I must look at the XML but since I fear the worst, I have not.... -- Robert J. Chassell bob@rattlesnake.com GnuPG Key ID: 004B4AC8 http://www.rattlesnake.com http://www.teak.cc