procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

(Help): Mention existence of Emacs and stand-alone Info at the very

Browse source 
beginning of the tutorial.
(Help-Inv): New node.
(Help-]): New node.
(Help-M): Systematically point out the differences between default
Emacs and stand-alone versions.  Delete second menu.
(Help-Xref): Systematically point out the differences between default
Emacs and stand-alone versions.
(Help-Int): Change `l' example.
(Expert Info): Fix typos.
(Emacs Info Variables): Mention `Info-hide-note-references' and new
default for `Info-scroll-prefer-subnodes'.
This commit is contained in:
Luc Teirlinck 2003-07-03 01:59:39 +00:00
parent 9e2497ccaf
commit bac598bbf5
1 changed files with 184 additions and 62 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

246
man/info.texi
View file

@ -6,7 +6,7 @@
@syncodeindex vr cp
@syncodeindex ky cp
@comment %**end of header
@comment $Id: info.texi,v 1.26 2002/10/02 23:24:31 karl Exp $
@comment $Id: info.texi,v 1.27 2002/11/06 00:45:03 karl Exp $
@copying
This file describes how to use Info, the on-line, menu-driven GNU
@ -51,7 +51,7 @@ license to the document, as described in section 6 of the license.
@end titlepage
@ifnottex
@node Top
@node Top, Getting Started, (dir), (dir)
@top Info: An Introduction
The GNU Project distributes most of its on-line manuals in the
@ -125,13 +125,14 @@ the screen.
* Help:: How to use Info
* Help-P:: Returning to the Previous node
* Help-^L:: The Space, DEL, B and ^L commands.
* Help-Inv:: Invisible text in Emacs Info.
* Help-M:: Menus
* Help-Xref:: Following cross-references
* Help-Int:: Some intermediate Info commands
* Help-Q:: Quitting Info
@end menu
@node Help-Small-Screen
@node Help-Small-Screen, Help, Getting Started, Getting Started
@section Starting Info on a Small Screen
@ifnotinfo
@ -213,6 +214,10 @@ the course.
You are talking to the program Info, for reading documentation.
There are two ways to use Info: from within Emacs or as a
stand-alone reader that you can invoke from a shell using the command
@command{info}.
@cindex node, in Info documents
Right now you are looking at one @dfn{Node} of Information.
A node contains text describing a specific topic at a specific
@ -283,9 +288,9 @@ coming up.
link, to get to the node @samp{Help-^L} and learn more.
@end format
@node Help-^L, Help-M, Help-P, Getting Started
@node Help-^L, Help-Inv, Help-P, Getting Started
@comment node-name, next, previous, up
@section The Space, DEL, B and ^L commands.
@section The Space, DEL, B and ^L commands
This node's mode line tells you that you are now at node
@samp{Help-^L}, and the header line tells you that @kbd{p} would get
@ -409,30 +414,103 @@ the same size screen, it would be impossible to warn you anyway.
@format
>> Now type @kbd{n}, or click the middle mouse button on the @samp{Next} link,
to see the description of the @kbd{m} command.
to visit the next node.
@end format
@node Help-M, Help-Xref, Help-^L, Getting Started
@node Help-Inv, Help-M, Help-^L, Getting Started
@comment node-name, next, previous, up
@section Invisible text in Emacs Info
Before discussing menus, we need to make some remarks that are only
relevant to users reading Info using Emacs. Users of the stand-alone
version can skip this node by typing @kbd{]} now.
@cindex invisible text in Emacs
In Emacs, certain text that appears in the stand-alone version is
normally hidden, technically because it has the @samp{invisibility}
property. Invisible text is really a part of the text. It becomes
visible (by default) after killing and yanking, it appears in printed
output, it gets saved to file just like any other text, and so on.
Thus it is useful to know it is there.
@findex vis-mode
You can make invisible text visible by using the command @kbd{M-x
vis-mode}. @code{vis-mode} is a minor mode, so using it a second time
will make the text invisible again. Use this command and watch its
effect on the ``menu'' below and the top line of this node.
If you prefer to @emph{always} see the invisible text, you can set
@code{Info-hide-note-references} to @code{nil}. Enabling
@code{vis-mode} permanently is not a real alternative, because Emacs
Info also uses (although less extensively) another text property that
can change the text being displayed, the @samp{display} property.
Only the invisibility property is affected by @code{vis-mode}. When,
in this tutorial, we refer to the @samp{Emacs} behavior, we mean the
@emph{default} Emacs behavior.
Now type @kbd{]}, to learn about the @kbd{]} and @kbd{[} commands.
@menu
* ]: Help-]. Node telling about ].
* stuff: Help-]. Same node.
* Help-]:: Yet again, same node.
@end menu
@node Help-], , , Help-Inv
@subsection The @kbd{]} and @kbd{[} commands.
If you type @kbd{n} now, you get an error message saying that this
node has no next node. Similarly, if you type @kbd{p}, the error
message tells you that there is no previous node. (The exact message
depends on the Info reader you use.) This is because @kbd{n} and
@kbd{p} carry you to the next and previous node @emph{at the same
level}. The present node is contained in a menu (see next) of the
node you came from, and hence is considered to be at a lower level.
It is the only node in the previous node's menu (even though it was
listed three times). Hence it has no next or previous node that
@kbd{n} or @kbd{p} could move to.
If you systematically move through a manual by typing @kbd{n}, you run
the risk of skipping many nodes. You do not run this risk if you
systematically use @kbd{@key{SPC}}, because, when you scroll to the
bottom of a node and type another @kbd{@key{SPC}}, then this carries
you to the following node in the manual @emph{regardless of level}.
If you immediately want to go to that node, without having to scroll
to the bottom of the screen first, you can type @kbd{]}.
Similarly, @kbd{@key{BACKSPACE}} carries you to the preceding node
regardless of level, after you scrolled to the beginning of the
present node. If you want to go to the preceding node immediately,
you can type @kbd{[}.
For instance, typing this sequence will come back here in three steps:
@kbd{[ n [}. To do the same backward, type @kbd{] p ]}.
Now type @kbd{]} to go to the next node and learn about menus.
@node Help-M, Help-Xref, Help-Inv, Getting Started
@comment node-name, next, previous, up
@section Menus and the @kbd{m} command
@cindex menus in an Info document
@cindex Info menus
With only the @kbd{n} (next) and @kbd{p} (previous) commands for
moving between nodes, nodes are restricted to a linear sequence.
Menus allow a branching structure. A menu is a list of other nodes
you can move to. It is actually just part of the text of the node
formatted specially so that Info can interpret it. The beginning of a
menu is always identified by a line which starts with @samp{* Menu:}.
A node contains a menu if and only if it has a line in it which starts
that way. The only menu you can use at any moment is the one in the
node you are in. To use a menu in any other node, you must move to
that node first.
With only the @kbd{n} (next), @kbd{p} (previous), @kbd{@key{SPC}},
@kbd{@key{BACKSPACE}}, @kbd{]} and @kbd{[} commands for moving between
nodes, nodes are restricted to a linear sequence. Menus allow a
branching structure. A menu is a list of other nodes you can move to.
It is actually just part of the text of the node formatted specially
so that Info can interpret it. The beginning of a menu is always
identified by a line which starts with @w{@samp{* Menu:}}. A node
contains a menu if and only if it has a line in it which starts that
way. The only menu you can use at any moment is the one in the node
you are in. To use a menu in any other node, you must move to that
node first.
After the start of the menu, each line that starts with a @samp{*}
identifies one subtopic. The line usually contains a brief name
for the subtopic (followed by a @samp{:}), the name of the node that talks
about that subtopic, and optionally some further description of the
identifies one subtopic. The line usually contains a brief name for
the subtopic (followed by a @samp{:}, normally hidden in Emacs), the
name of the node that talks about that subtopic (again, normally
hidden in Emacs), and optionally some further description of the
subtopic. Lines in the menu that do not start with a @samp{*} have no
special meaning---they are only for the human reader's benefit and do
not define additional subtopics. Here is an example:
@ -444,7 +522,11 @@ not define additional subtopics. Here is an example:
The subtopic name is Foo, and the node describing it is @samp{Node
about FOO}. The rest of the line is just for the reader's
Information. [[ But this line is not a real menu item, simply because
there is no line above it which starts with @samp{* Menu:}.]]
there is no line above it which starts with @w{@samp{* Menu:}}. Also,
in a real menu item, the @samp{*} would appear at the very start of
the line. This is why the ``normally hidden'' text in Emacs, namely
@samp{: Node about FOO.}, is actually visible in this example, even
when @code{vis-mode} is off.]]
When you use a menu to go to another node (in a way that will be
described soon), what you specify is the subtopic name, the first
@ -463,7 +545,7 @@ abbreviation for this:
@noindent
This means that the subtopic name and node name are the same; they are
both @samp{Foo}.
both @samp{Foo}. (The @samp{::} is normally hidden in Emacs.)
@format
>> Now use @key{SPC} to find the menu in this node, then come back to
@ -488,16 +570,18 @@ another command. The @kbd{m} command is different: it needs to know
the @dfn{name of the subtopic}. Once you have typed @kbd{m}, Info
tries to read the subtopic name.
Now look for the line containing many dashes near the bottom of the
screen. There is one more line beneath that one, but usually it is
blank. When it is blank, Info is ready for a command, such as @kbd{n}
or @kbd{b} or @key{SPC} or @kbd{m}. If that line contains text ending
in a colon, it means Info is reading more input for the last command.
You can't type an Info command then, because Info is trying to read
input, not commands. You must either give the input and finish the
command you started, or type @kbd{Control-g} to cancel the command.
When you have done one of those things, the input entry line becomes
blank again. Then you can type Info commands again.
Now, in the stand-alone Info, look for the line containing many
dashes near the bottom of the screen. (This is the stand-alone
equivalent for the mode line in Emacs.) There is one more line
beneath that one, but usually it is blank. (In Emacs, this is the
echo area.) When it is blank, Info is ready for a command, such as
@kbd{n} or @kbd{b} or @key{SPC} or @kbd{m}. If that line contains
text ending in a colon, it means Info is reading more input for the
last command. You can't type an Info command then, because Info is
trying to read input, not commands. You must either give the input
and finish the command you started, or type @kbd{Control-g} to cancel
the command. When you have done one of those things, the input entry
line becomes blank again. Then you can type Info commands again.
@findex Info-menu
The command to go to a subnode via a menu is @kbd{m}. After you type
@ -535,6 +619,8 @@ three ways of going to one place, Help-FOO:
* Help-FOO:: And yet another!
@end menu
(Turn @code{vis-mode} on if you are using Emacs.)
@format
>> Now type just an @kbd{m} and see what happens:
@end format
@ -610,14 +696,6 @@ node's header line it acts like @kbd{n}, @kbd{p}, or @kbd{u}, etc. At
end of the node's text @kbd{Mouse-2} moves to the next node, or up if
there's no next node.
Here is another way to get to Help-FOO, a menu. You can ignore this
if you want, or else try it by typing @key{TAB} and then @key{RET}, or
clicking @kbd{Mouse-2} on it (but then please come back to here).
@menu
* Help-FOO::
@end menu
@format
>> Type @kbd{n} to see more commands.
@end format
@ -656,7 +734,8 @@ pointer shown in the header line (provided that you have a mouse).
In Info documentation, you will see many @dfn{cross references}.
Cross references look like this: @xref{Help-Cross, Cross}. That text
is a real, live cross reference, whose name is @samp{Cross} and which
points to the node named @samp{Help-Cross}.
points to the node named @samp{Help-Cross}. (The node name is hidden
in Emacs. Do @kbd{M-x vis-mode} to show or hide it.)
@kindex f @r{(Info mode)}
@findex Info-follow-reference
@ -699,6 +778,47 @@ to cancel the @kbd{f}.
The @key{TAB} and @kbd{M-@key{TAB}} key, which move between menu
items in a menu, also move between cross references outside of menus.
Sometimes a cross reference (or a node) can lead to another file (in
other words another ``manual''), or, on occasion, even a file on a
remote machine (although Info files distributed with Emacs or the
stand-alone Info avoid using remote links). Such a cross reference
looks like this: @xref{Overview,,,texinfo}. (After following this
link, type @kbd{l} to get back to this node.) Here the name
@samp{texinfo} between parentheses (shown in the stand-alone version)
refers to the file name. This file name appears in cross references
and node names if it differs from the current file. In Emacs, the
file name is hidden (along with other text). (Use @kbd{M-x vis-mode}
to show or hide it.)
The remainder of this node applies only to the Emacs version. If
you use the stand-alone version, you can type @kbd{n} immediately.
To some users, switching manuals is a much bigger switch than
switching sections. These users like to know that they are going to
be switching to another manual (and which one) before actually doing
so, especially given that, if one does not notice, Info commands like
@kbd{t} (see the next node) can have confusing results.
If you put your mouse over the cross reference and if the cross
reference leads to a different manual, then the information appearing
in a separate box (tool tip) or in the echo area, will mention the
file the cross reference will carry you to (between parentheses).
This is also true for menu subtopic names. If you have a mouse, just
leave it over the @samp{Overview} cross reference above and watch what
happens.
If you always like to have that information available without having
to move your mouse over the cross reference, set
@code{Info-hide-note-references} to a value other than t (@pxref{Emacs
Info Variables}). You might also want to do that if you have a lot of
cross references to files on remote machines and have non-permanent or
slow access, since otherwise you might not be able to distinguish
between local and remote links.
@format
>> Now type @kbd{n} to learn more commands.
@end format
@node Help-Int, Help-Q, Help-Xref, Getting Started
@comment node-name, next, previous, up
@section Some intermediate Info commands
@ -728,23 +848,17 @@ records the nodes where you have been in a special history list. The
@kbd{l} command revisits nodes in the history list; each successive
@kbd{l} command moves one step back through the history.
If you have been following directions, an @kbd{l} command now will get
you back to @samp{Help-M}. Another @kbd{l} command would undo the
@kbd{u} and get you back to @samp{Help-FOO}. Another @kbd{l} would undo
the @kbd{m} and get you back to @samp{Help-M}.
In Emacs, @kbd{l} runs the command @code{Info-last}.
@format
>> Try typing three @kbd{l}'s, pausing in between to see what each
@kbd{l} does. Then follow directions again and you will end up
back here.
>> Try typing @kbd{p p n} and then three @kbd{l}'s, pausing in between
to see what each @kbd{l} does. You should wind up right back here.
@end format
Note the difference between @kbd{l} and @kbd{p}: @kbd{l} moves to
where @emph{you} last were, whereas @kbd{p} always moves to the node
which the header says is the @samp{Previous} node (from this node, the
@samp{Prev} link leads to @samp{Help-M}).
@samp{Prev} link leads to @samp{Help-Xref}).
@kindex d @r{(Info mode)}
@findex Info-directory
@ -796,10 +910,10 @@ Texinfo file. (However, in most cases, writing a Texinfo file is
better, since you can use it to make a printed manual or produce other
formats, such as HTML and DocBook, as well as for generating Info
files.) @xref{Top,, Overview of Texinfo, texinfo, Texinfo: The GNU
Documentation Format}.)
Documentation Format}.
@menu
* Advanced:: Advanced Info commands: g, s, e, and 1 - 5.
* Advanced:: Advanced Info commands: g, e, and 1 - 9.
* Info Search:: How to search Info documents for specific subjects.
* Add:: Describes how to add new nodes to the hierarchy.
Also tells what nodes look like.
@ -1049,15 +1163,15 @@ The @kbd{m} command searches the current node's menu for the topic which it
reads from the terminal.
@cindex menu and menu entry format
A menu begins with a line starting with @samp{* Menu:}. The rest of the
line is a comment. After the starting line, every line that begins
with a @samp{* } lists a single topic. The name of the topic--what
the user must type at the @kbd{m}'s command prompt to select this
topic---comes right after the star and space, and is followed by a
colon, spaces and tabs, and the name of the node which discusses that
topic. The node name, like node names following @samp{Next}, @samp{Previous}
and @samp{Up}, may be terminated with a tab, comma, or newline; it may also
be terminated with a period.
A menu begins with a line starting with @w{@samp{* Menu:}}. The
rest of the line is a comment. After the starting line, every line
that begins with a @samp{* } lists a single topic. The name of the
topic--what the user must type at the @kbd{m}'s command prompt to
select this topic---comes right after the star and space, and is
followed by a colon, spaces and tabs, and the name of the node which
discusses that topic. The node name, like node names following
@samp{Next}, @samp{Previous} and @samp{Up}, may be terminated with a
tab, comma, or newline; it may also be terminated with a period.
If the node name and topic name are the same, then rather than
giving the name twice, the abbreviation @samp{* @var{name}::} may be
@ -1278,6 +1392,14 @@ the @samp{Next}, @samp{Prev}, and @samp{Up} links. A header line does
not scroll with the rest of the buffer, making these links always
visible.
@item Info-hide-note-references
As explained in earlier nodes, the Emacs version of Info normally
hides some text in menus and cross-references. You can completely
disable this feature, by setting this option to @code{nil}. Setting
it to a value that is neither @code{nil} nor @code{t} produces an
intermediate behavior, hiding a limited amount of text, but showing
all text that could potentially be useful.
@item Info-scroll-prefer-subnodes
If set to a non-@code{nil} value, @key{SPC} and @key{BACKSPACE} (or
@key{DEL}) keys in a menu visit subnodes of the current node before
@ -1286,7 +1408,7 @@ node's menu appears on the screen, the next @key{SPC} moves to a
subnode indicated by the following menu item. Setting this option to
@code{nil} results in behavior similar to the stand-alone Info reader
program, which visits the first subnode from the menu only when you
hit the end of the current node. The default is @code{t}.
hit the end of the current node. The default is @code{nil}.
@item Info-enable-active-nodes
When set to a non-@code{nil} value, allows Info to execute Lisp code