[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Divergence in menu appearance between Emacs Info and standalone Info
From: |
Robert J. Chassell |
Subject: |
Re: Divergence in menu appearance between Emacs Info and standalone Info |
Date: |
Thu, 5 Jun 2003 12:27:50 +0000 (UTC) |
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
- Re: Divergence in menu appearance between Emacs Info and standalone Info, (continued)
- Re: Divergence in menu appearance between Emacs Info and standalone Info, Eli Zaretskii, 2003/06/05
- Re: Divergence in menu appearance between Emacs Info and standalone Info, Stefan Monnier, 2003/06/05
- Re: Divergence in menu appearance between Emacs Info and standalone Info, Eli Zaretskii, 2003/06/06
- Re: Divergence in menu appearance between Emacs Info and standalone Info, Andreas Schwab, 2003/06/06
- Re: Divergence in menu appearance between Emacs Info and standalone Info, Stefan Monnier, 2003/06/06
- Re: Divergence in menu appearance between Emacs Info and standalone Info, Eli Zaretskii, 2003/06/05
- Re: Divergence in menu appearance between Emacs Info and standalone Info, Richard Stallman, 2003/06/05
Re: Divergence in menu appearance between Emacs Info and standalone Info, Luc Teirlinck, 2003/06/04
Re: Divergence in menu appearance between Emacs Info and standalone Info, Eli Zaretskii, 2003/06/04
Re: Divergence in menu appearance between Emacs Info and standalone Info, Richard Stallman, 2003/06/05
Re: Divergence in menu appearance between Emacs Info and standalone Info,
Robert J. Chassell <=
- Re: Divergence in menu appearance between Emacs Info and standalone Info, Kim F. Storm, 2003/06/05
- Re: Divergence in menu appearance between Emacs Info and standalone Info, Miles Bader, 2003/06/05
- Re: Divergence in menu appearance between Emacs Info and standalone Info, Robert J. Chassell, 2003/06/05
- Re: Divergence in menu appearance between Emacs Info and standalone Info, Stefan Monnier, 2003/06/05
- Re: Divergence in menu appearance between Emacs Info and standalone Info, Robert J. Chassell, 2003/06/05
- Re: Divergence in menu appearance between Emacs Info and standalone Info, Miles Bader, 2003/06/05
- Re: Divergence in menu appearance between Emacs Info and standalone Info, Robert J. Chassell, 2003/06/06
- Re: Divergence in menu appearance between Emacs Info and standalone Info, Eli Zaretskii, 2003/06/06
- Re: Divergence in menu appearance between Emacs Info and standalone Info, David Kastrup, 2003/06/06
- Re: Divergence in menu appearance between Emacs Info and standalone Info, Richard Stallman, 2003/06/07