[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] Changes to emacs/man/info.texi
From: |
Luc Teirlinck |
Subject: |
[Emacs-diffs] Changes to emacs/man/info.texi |
Date: |
Wed, 02 Jul 2003 21:59:40 -0400 |
Index: emacs/man/info.texi
diff -c emacs/man/info.texi:1.27 emacs/man/info.texi:1.28
*** emacs/man/info.texi:1.27 Tue Nov 5 19:45:03 2002
--- emacs/man/info.texi Wed Jul 2 21:59:39 2003
***************
*** 6,12 ****
@syncodeindex vr cp
@syncodeindex ky cp
@comment %**end of header
! @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
--- 6,12 ----
@syncodeindex vr cp
@syncodeindex ky cp
@comment %**end of header
! @comment $Id: info.texi,v 1.28 2003/07/03 01:59:39 teirllm Exp $
@copying
This file describes how to use Info, the on-line, menu-driven GNU
***************
*** 51,57 ****
@end titlepage
@ifnottex
! @node Top
@top Info: An Introduction
The GNU Project distributes most of its on-line manuals in the
--- 51,57 ----
@end titlepage
@ifnottex
! @node Top, Getting Started, (dir), (dir)
@top Info: An Introduction
The GNU Project distributes most of its on-line manuals in the
***************
*** 125,137 ****
* Help:: How to use Info
* Help-P:: Returning to the Previous node
* Help-^L:: The Space, DEL, B and ^L commands.
* Help-M:: Menus
* Help-Xref:: Following cross-references
* Help-Int:: Some intermediate Info commands
* Help-Q:: Quitting Info
@end menu
! @node Help-Small-Screen
@section Starting Info on a Small Screen
@ifnotinfo
--- 125,138 ----
* 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, Help, Getting Started, Getting Started
@section Starting Info on a Small Screen
@ifnotinfo
***************
*** 213,218 ****
--- 214,223 ----
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,291 ****
link, to get to the node @samp{Help-^L} and learn more.
@end format
! @node Help-^L, Help-M, Help-P, Getting Started
@comment node-name, next, previous, up
! @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
--- 288,296 ----
link, to get to the node @samp{Help-^L} and learn more.
@end format
! @node Help-^L, Help-Inv, Help-P, Getting Started
@comment node-name, next, previous, up
! @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,438 ****
@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.
@end format
! @node Help-M, Help-Xref, Help-^L, 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.
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
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:
--- 414,516 ----
@format
>> Now type @kbd{n}, or click the middle mouse button on the @samp{Next} link,
! to visit the next node.
@end format
! @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 @address@hidden, because, when you scroll to the
! bottom of a node and type another @address@hidden, 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, @address@hidden 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), @kbd{p} (previous), @address@hidden,
! @address@hidden, @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 @address@hidden 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{:}, 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,450 ****
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:}.]]
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
--- 522,532 ----
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 @address@hidden 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,469 ****
@noindent
This means that the subtopic name and node name are the same; they are
! both @samp{Foo}.
@format
>> Now use @key{SPC} to find the menu in this node, then come back to
--- 545,551 ----
@noindent
This means that the subtopic name and node name are the same; they are
! 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,503 ****
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.
@findex Info-menu
The command to go to a subnode via a menu is @kbd{m}. After you type
--- 570,587 ----
the @dfn{name of the subtopic}. Once you have typed @kbd{m}, Info
tries to read the subtopic name.
! 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,540 ****
--- 619,626 ----
* 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,623 ****
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
--- 696,701 ----
***************
*** 656,662 ****
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}.
@kindex f @r{(Info mode)}
@findex Info-follow-reference
--- 734,741 ----
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}. (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,704 ****
--- 778,824 ----
The @key{TAB} and @address@hidden 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,750 ****
@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.
@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}).
@kindex d @r{(Info mode)}
@findex Info-directory
--- 848,864 ----
@kbd{l} command revisits nodes in the history list; each successive
@kbd{l} command moves one step back through the history.
In Emacs, @kbd{l} runs the command @code{Info-last}.
@format
! >> 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-Xref}).
@kindex d @r{(Info mode)}
@findex Info-directory
***************
*** 796,805 ****
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}.)
@menu
! * Advanced:: Advanced Info commands: g, s, e, and 1 - 5.
* 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.
--- 910,919 ----
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}.
@menu
! * 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,1063 ****
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.
If the node name and topic name are the same, then rather than
giving the name twice, the abbreviation @samp{* @var{name}::} may be
--- 1163,1177 ----
reads from the terminal.
@cindex menu and menu entry format
! A menu begins with a line starting with @address@hidden 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,1283 ****
--- 1392,1405 ----
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 address@hidden value, @key{SPC} and @key{BACKSPACE} (or
@key{DEL}) keys in a menu visit subnodes of the current node before
***************
*** 1286,1292 ****
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}.
@item Info-enable-active-nodes
When set to a address@hidden value, allows Info to execute Lisp code
--- 1408,1414 ----
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{nil}.
@item Info-enable-active-nodes
When set to a address@hidden value, allows Info to execute Lisp code
- [Emacs-diffs] Changes to emacs/man/info.texi,
Luc Teirlinck <=
- [Emacs-diffs] Changes to emacs/man/info.texi, Luc Teirlinck, 2003/07/04
- [Emacs-diffs] Changes to emacs/man/info.texi, Luc Teirlinck, 2003/07/07
- [Emacs-diffs] Changes to emacs/man/info.texi, Luc Teirlinck, 2003/07/07
- [Emacs-diffs] Changes to emacs/man/info.texi, Luc Teirlinck, 2003/07/07
- [Emacs-diffs] Changes to emacs/man/info.texi, Karl Berry, 2003/07/16