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: Divergence in menu appearance between Emacs Info and standalone Info Date: Thu, 5 Jun 2003 12:27:50 +0000 (UTC) Sender: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Message-ID: References: <200306041404.h54E4SO30552@f7.net> Reply-To: bob@rattlesnake.com NNTP-Posting-Host: main.gmane.org X-Trace: main.gmane.org 1054816657 29161 80.91.224.249 (5 Jun 2003 12:37:37 GMT) X-Complaints-To: usenet@main.gmane.org NNTP-Posting-Date: Thu, 5 Jun 2003 12:37:37 +0000 (UTC) Cc: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Thu Jun 05 14:37:33 2003 Return-path: Original-Received: from quimby.gnus.org ([80.91.224.244]) by main.gmane.org with esmtp (Exim 3.35 #1 (Debian)) id 19Ntzp-0007Zz-00 for ; Thu, 05 Jun 2003 14:37:33 +0200 Original-Received: from monty-python.gnu.org ([199.232.76.173]) by quimby.gnus.org with esmtp (Exim 3.12 #1 (Debian)) id 19NuHt-0000A1-00 for ; Thu, 05 Jun 2003 14:56:13 +0200 Original-Received: from localhost ([127.0.0.1] helo=monty-python.gnu.org) by monty-python.gnu.org with esmtp (Exim 4.20) id 19NtsP-00025D-Bi for emacs-devel@quimby.gnus.org; Thu, 05 Jun 2003 08:29:53 -0400 Original-Received: from list by monty-python.gnu.org with tmda-scanned (Exim 4.20) id 19NtrY-0001rU-6i for emacs-devel@gnu.org; Thu, 05 Jun 2003 08:29:00 -0400 Original-Received: from mail by monty-python.gnu.org with spam-scanned (Exim 4.20) id 19Ntqa-0001Zv-Or for emacs-devel@gnu.org; Thu, 05 Jun 2003 08:28:02 -0400 Original-Received: from megalith.rattlesnake.com ([140.186.114.245] helo=rattlesnake.com) by monty-python.gnu.org with esmtp (Exim 4.20) id 19NtqX-0001Z1-6u; Thu, 05 Jun 2003 08:27:57 -0400 Original-Received: by rattlesnake.com via sendmail from stdin id (Debian Smail3.2.0.114) Thu, 5 Jun 2003 12:27:50 +0000 (UTC) Original-To: karl@freefriends.org (Karl Berry) In-reply-to: <200306041404.h54E4SO30552@f7.net> (karl@freefriends.org) Original-cc: rms@gnu.org X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1b5 Precedence: list List-Id: Emacs development discussions. List-Help: List-Post: List-Subscribe: , List-Archive: List-Unsubscribe: , Errors-To: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Xref: main.gmane.org gmane.emacs.devel:14760 X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:14760 I gather the default is to hide the node names. Yes. This is and has been a mistake. It harms GNU documentation. Texinfo uses node names to structure an Info file, and section headers to structure a typeset file. Although the two may be the same, they should be different in every GNU manual. The Texinfo manual talks about this in a node called: (texinfo)Menu Location which does *not* have a section title. While the text of the node appears in a printed manual, the title does not. The text appears as part of the first section of the chapter on Menus. There is good reason for this: By convention, a menu is put at the end of a node since a reader who uses the menu may not see text that follows it. Furthermore, a node that has a menu should not contain much text. If you have a lot of text and a menu, move most of the text into a new subnode--all but a few lines. Otherwise, a reader with a terminal that displays only a few lines may miss the menu and its associated text. As a practical matter, you should locate a menu within 20 lines of the beginning of the node. The short text before a menu may look awkward in a printed manual. To avoid this, you can write a menu near the beginning of its node and follow the menu by an `@node' line, and then an `@heading' line located within `@ifinfo' and `@end ifinfo'. This way, the menu, `@node' line, and title appear only in the Info file, not the printed document. It does not matter to readers so much that the printed manual looks different from the online manual; after all, people expect a printed manual to be more limited in many ways -- for example, you cannot conveniently navigate through a printed manual using regular expression searches. (You cannot conveniently navigate through a multi-page HTML site either, which is why Web sites are still more backward than Info. Hiding node names in Info may lead some people to think falsely that Texinfo is as bad as HTML.) The surface expression of Info should reflect its deep representation more closely than a printed surface expression. Quite simply, it is dangerous to provide a online manual that does not tell users implicitly that node names are more important than section titles. Rather than hide node names, it would make more sense to modify Info to hide section titles than the reverse. Note that the first part of a menu entry is the menu entry name; that first part is *not* the section title. (I sometimes get the impression that poor writers think a menu entry is the name of a section.) A menu does not contain a obligatory section title slot. The `C-c C-c C-d' (`texinfo-start-menu-description') Texinfo mode command inserts a node's section or chapter title in the space for the description in a menu entry line in the far right hand part of the line -- in the `description' slot, not in the entry name or node name slots. This makes it easy to modify the section title text to provide a better description. Since we want good GNU documentation, and since node names are such an important part of good Texinfo writing, we should keep node names visible in Info. It is and has been a mistake to hide the node names in Info. -- Robert J. Chassell Rattlesnake Enterprises http://www.rattlesnake.com GnuPG Key ID: 004B4AC8 http://www.teak.cc bob@rattlesnake.com