Re: Divergence in menu appearance between Emacs Info and standalone Info

[Robert J. Chassell]

   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 address@hidden' line, and then an
    address@hidden' line located within address@hidden' and address@hidden 
ifinfo'.  This
    way, the menu, address@hidden' 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                             address@hidden