emacs manual

emacs manual

[Sean Sieger]

I was just navigating my way back to a point in the Emacs Manual, the
section, `22 File Handling'.  I did `t', `m' and then typed

file h <TAB>

``[No Match]'' was the message that I got.

From the top level of the manual, ``Files'' is the name of the section.
I remembered the last chapter name or section name I'd come across
(again, `22 File Handling') as I do when I close a book and put it down.

Isn't this a disjunction?

My post may be interpreted as a complaint, but this looked like an
example of the opacity that I sometimes perceive in the documentation of
Emacs but don't know how to verbalize.

Just looking for an explanation.

Re: emacs manual

[Eli Zaretskii]

> From: Sean Sieger <sean.sieger@gmail.com>
> Date: Wed, 08 Apr 2009 09:36:13 -0400
> 
> I was just navigating my way back to a point in the Emacs Manual, the
> section, `22 File Handling'.  I did `t', `m' and then typed
> 
> file h <TAB>
> 
> ``[No Match]'' was the message that I got.
> 
> From the top level of the manual, ``Files'' is the name of the section.
> I remembered the last chapter name or section name I'd come across
> (again, `22 File Handling') as I do when I close a book and put it down.

In an Info manual, there are node names and there are section names.
A section name is what you see at the beginning of the section;
"22 File Handling" is an example.  The corresponding node name appears
in the mode line, where you should see "(emacs) Files", which tells
you that you are in the node "Files" of the "emacs" manual.

The `m' command wants a node name, not the name of a section.  More
accurately, it wants the name of a menu item.  Normally, menu items
are just node names, but sometimes they also have an additional menu
entry name.  Here are two examples:

     * Files::                       All about handling files.
     * Multiples: Buffers.           Multiple buffers; editing
                                      several files at once.

The reason the `m' command does not work on section names is because
it looks at the menu entries, not at the list of all the sections in
the manual.  And section names do not appear in the menu entries.

Re: emacs manual

[Sean Sieger]

Eli Zaretskii <eliz@gnu.org> writes:

    In an Info manual, there are node names and there are section names.
    A section name is what you see at the beginning of the section;
    "22 File Handling" is an example.  The corresponding node name appears
    in the mode line, where you should see "(emacs) Files", which tells
    you that you are in the node "Files" of the "emacs" manual.

    The `m' command wants a node name, not the name of a section.  More
    accurately, it wants the name of a menu item.  Normally, menu items
    are just node names, but sometimes they also have an additional menu
    entry name.  Here are two examples:

         * Files::                       All about handling files.
         * Multiples: Buffers.           Multiple buffers; editing
                                          several files at once.

    The reason the `m' command does not work on section names is because
    it looks at the menu entries, not at the list of all the sections in
    the manual.  And section names do not appear in the menu entries.

Thank you for explaining this Eli.  I'll start noting the mode line of
*info* buffers.  Right, and now to go and understand the syntax of,
(info "(emacs)Files")---I can never remember it!

Re: emacs manual

[tyler]

Sean Sieger <sean.sieger@gmail.com> writes:

> I was just navigating my way back to a point in the Emacs Manual, the
> section, `22 File Handling'.  I did `t', `m' and then typed
>
> file h <TAB>
>
> ``[No Match]'' was the message that I got.
>
> From the top level of the manual, ``Files'' is the name of the section.
> I remembered the last chapter name or section name I'd come across
> (again, `22 File Handling') as I do when I close a book and put it down.
>
> Isn't this a disjunction?
>
> My post may be interpreted as a complaint, but this looked like an
> example of the opacity that I sometimes perceive in the documentation of
> Emacs but don't know how to verbalize.
>
> Just looking for an explanation.
>

In Texinfo, the commands for naming a chapter are different from the
commands used to define a node. So in your case, the chapter is defined
as `File Handling', which applies that title to the top of the page, but
the node is defined as `Files', which is what gets inserted into the
menu, and is what you need to target when you use `m' to pick the page.

At least, that's how I understand it. I don't know why this should be,
because it seems like it would be more intuitive if the chapter and node
names were the same, as you've pointed out. If no-one else has a better
explanation, I'd be tempted to submit this as a documentation bug. It's
not really a bug though, as much as an inconsistency in the way
documents are laid out. I notice that the texinfo manual itself contains
similar problems, with the node `Ending a File' having the chapter title
`Ending a Texinfo File'.

Cheers,

Tyler

-- 
I have no "intellectual property," and I think that all claimants to 
such property are thieves.             --Wendell Berry

http://home.btconnect.com/tipiglen/resist.html