/[emacs]/emacs/man/info.texi
ViewVC logotype

Diff of /emacs/man/info.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.23.2.1 by miles, Fri Apr 4 06:20:48 2003 UTC revision 1.23.2.2 by miles, Tue Oct 14 22:56:23 2003 UTC
# Line 12  Line 12 
12  This file describes how to use Info, the on-line, menu-driven GNU  This file describes how to use Info, the on-line, menu-driven GNU
13  documentation system.  documentation system.
14    
15  Copyright (C) 1989, 1992, 1996, 1997, 1998, 1999, 2000, 2001, 2002  Copyright (C) 1989, 1992, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003
16  Free Software Foundation, Inc.  Free Software Foundation, Inc.
17    
18  @quotation  @quotation
# Line 50  license to the document, as described in Line 50  license to the document, as described in
50  @insertcopying  @insertcopying
51  @end titlepage  @end titlepage
52    
53    @contents
54    
55  @ifnottex  @ifnottex
56  @node Top  @node Top
57  @top Info: An Introduction  @top Info: An Introduction
# Line 125  the screen. Line 127  the screen.
127  * Help::                How to use Info  * Help::                How to use Info
128  * Help-P::              Returning to the Previous node  * Help-P::              Returning to the Previous node
129  * Help-^L::             The Space, DEL, B and ^L commands.  * Help-^L::             The Space, DEL, B and ^L commands.
130    * Help-Inv::            Invisible text in Emacs Info.
131  * Help-M::              Menus  * Help-M::              Menus
132  * Help-Xref::           Following cross-references  * Help-Xref::           Following cross-references
133  * Help-Int::            Some intermediate Info commands  * Help-Int::            Some intermediate Info commands
# Line 213  the course. Line 216  the course.
216    
217  You are talking to the program Info, for reading documentation.  You are talking to the program Info, for reading documentation.
218    
219      There are two ways to use Info: from within Emacs or as a
220    stand-alone reader that you can invoke from a shell using the command
221    @command{info}.
222    
223  @cindex node, in Info documents  @cindex node, in Info documents
224    Right now you are looking at one @dfn{Node} of Information.    Right now you are looking at one @dfn{Node} of Information.
225  A node contains text describing a specific topic at a specific  A node contains text describing a specific topic at a specific
# Line 283  coming up. Line 290  coming up.
290     link, to get to the node @samp{Help-^L} and learn more.     link, to get to the node @samp{Help-^L} and learn more.
291  @end format  @end format
292    
293  @node Help-^L, Help-M, Help-P, Getting Started  @node Help-^L, Help-Inv, Help-P, Getting Started
294  @comment  node-name,  next,  previous,  up  @comment  node-name,  next,  previous,  up
295  @section The Space, DEL, B and ^L commands.  @section The Space, DEL, B and ^L commands
296    
297    This node's mode line tells you that you are now at node    This node's mode line tells you that you are now at node
298  @samp{Help-^L}, and the header line tells you that @kbd{p} would get  @samp{Help-^L}, and the header line tells you that @kbd{p} would get
# Line 409  the same size screen, it would be imposs Line 416  the same size screen, it would be imposs
416    
417  @format  @format
418  >> Now type @kbd{n}, or click the middle mouse button on the @samp{Next} link,  >> Now type @kbd{n}, or click the middle mouse button on the @samp{Next} link,
419     to see the description of the @kbd{m} command.     to visit the next node.
420  @end format  @end format
421    
422  @node Help-M, Help-Xref, Help-^L, Getting Started  @node Help-Inv, Help-M, Help-^L, Getting Started
423    @comment  node-name,  next,  previous,  up
424    @section Invisible text in Emacs Info
425    
426      Before discussing menus, we need to make some remarks that are only
427    relevant to users reading Info using Emacs.  Users of the stand-alone
428    version can skip this node by typing @kbd{]} now.
429    
430    @cindex invisible text in Emacs
431      In Emacs, certain text that appears in the stand-alone version is
432    normally hidden, technically because it has the @samp{invisibility}
433    property.  Invisible text is really a part of the text.  It becomes
434    visible (by default) after killing and yanking, it appears in printed
435    output, it gets saved to file just like any other text, and so on.
436    Thus it is useful to know it is there.
437    
438    @findex visible-mode
439    You can make invisible text visible by using the command @kbd{M-x
440    visible-mode}.  Visible mode is a minor mode, so using the command a
441    second time will make the text invisible again.  Watch the effects of
442    the command on the ``menu'' below and the top line of this node.
443    
444    If you prefer to @emph{always} see the invisible text, you can set
445    @code{Info-hide-note-references} to @code{nil}.  Enabling Visible mode
446    permanently is not a real alternative, because Emacs Info also uses
447    (although less extensively) another text property that can change the
448    text being displayed, the @samp{display} property.  Only the
449    invisibility property is affected by Visible mode.  When, in this
450    tutorial, we refer to the @samp{Emacs} behavior, we mean the
451    @emph{default} Emacs behavior.
452    
453    Now type @kbd{]}, to learn about the @kbd{]} and @kbd{[} commands.
454    
455    @menu
456    * ]:         Help-].               Node telling about ].
457    * stuff:     Help-].               Same node.
458    * Help-]::                         Yet again, same node.
459    @end menu
460    
461    @node Help-], , , Help-Inv
462    @subsection The @kbd{]} and @kbd{[} commands
463    
464    If you type @kbd{n} now, you get an error message saying that this
465    node has no next node.  Similarly, if you type @kbd{p}, the error
466    message tells you that there is no previous node.  (The exact message
467    depends on the Info reader you use.)  This is because @kbd{n} and
468    @kbd{p} carry you to the next and previous node @emph{at the same
469    level}.  The present node is contained in a menu (see next) of the
470    node you came from, and hence is considered to be at a lower level.
471    It is the only node in the previous node's menu (even though it was
472    listed three times). Hence it has no next or previous node that
473    @kbd{n} or @kbd{p} could move to.
474    
475    If you systematically move through a manual by typing @kbd{n}, you run
476    the risk of skipping many nodes.  You do not run this risk if you
477    systematically use @kbd{@key{SPC}}, because, when you scroll to the
478    bottom of a node and type another @kbd{@key{SPC}}, then this carries
479    you to the following node in the manual @emph{regardless of level}.
480    If you immediately want to go to that node, without having to scroll
481    to the bottom of the screen first, you can type @kbd{]}.
482    
483    Similarly, @kbd{@key{BACKSPACE}} carries you to the preceding node
484    regardless of level, after you scrolled to the beginning of the
485    present node.  If you want to go to the preceding node immediately,
486    you can type @kbd{[}.
487    
488    For instance, typing this sequence will come back here in three steps:
489    @kbd{[ n [}.  To do the same backward, type @kbd{] p ]}.
490    
491    Now type @kbd{]} to go to the next node and learn about menus.
492    
493    @node Help-M, Help-Xref, Help-Inv, Getting Started
494  @comment  node-name,  next,  previous,  up  @comment  node-name,  next,  previous,  up
495  @section Menus and the @kbd{m} command  @section Menus and the @kbd{m} command
496    
497  @cindex menus in an Info document  @cindex menus in an Info document
498  @cindex Info menus  @cindex Info menus
499    With only the @kbd{n} (next) and @kbd{p} (previous) commands for    With only the @kbd{n} (next), @kbd{p} (previous), @kbd{@key{SPC}},
500  moving between nodes, nodes are restricted to a linear sequence.  @kbd{@key{BACKSPACE}}, @kbd{]} and @kbd{[} commands for moving between
501  Menus allow a branching structure.  A menu is a list of other nodes  nodes, nodes are restricted to a linear sequence.  Menus allow a
502  you can move to.  It is actually just part of the text of the node  branching structure.  A menu is a list of other nodes you can move to.
503  formatted specially so that Info can interpret it.  The beginning of a  It is actually just part of the text of the node formatted specially
504  menu is always identified by a line which starts with @samp{* Menu:}.  so that Info can interpret it.  The beginning of a menu is always
505  A node contains a menu if and only if it has a line in it which starts  identified by a line which starts with @w{@samp{* Menu:}}.  A node
506  that way.  The only menu you can use at any moment is the one in the  contains a menu if and only if it has a line in it which starts that
507  node you are in.  To use a menu in any other node, you must move to  way.  The only menu you can use at any moment is the one in the node
508  that node first.  you are in.  To use a menu in any other node, you must move to that
509    node first.
510    
511    After the start of the menu, each line that starts with a @samp{*}    After the start of the menu, each line that starts with a @samp{*}
512  identifies one subtopic.  The line usually contains a brief name  identifies one subtopic.  The line usually contains a brief name for
513  for the subtopic (followed by a @samp{:}), the name of the node that talks  the subtopic (followed by a @samp{:}, normally hidden in Emacs), the
514  about that subtopic, and optionally some further description of the  name of the node that talks about that subtopic (again, normally
515    hidden in Emacs), and optionally some further description of the
516  subtopic.  Lines in the menu that do not start with a @samp{*} have no  subtopic.  Lines in the menu that do not start with a @samp{*} have no
517  special meaning---they are only for the human reader's benefit and do  special meaning---they are only for the human reader's benefit and do
518  not define additional subtopics.  Here is an example:  not define additional subtopics.  Here is an example:
# Line 444  not define additional subtopics.  Here i Line 524  not define additional subtopics.  Here i
524  The subtopic name is Foo, and the node describing it is @samp{Node  The subtopic name is Foo, and the node describing it is @samp{Node
525  about FOO}.  The rest of the line is just for the reader's  about FOO}.  The rest of the line is just for the reader's
526  Information.  [[ But this line is not a real menu item, simply because  Information.  [[ But this line is not a real menu item, simply because
527  there is no line above it which starts with @samp{* Menu:}.]]  there is no line above it which starts with @w{@samp{* Menu:}}.  Also,
528    in a real menu item, the @samp{*} would appear at the very start of
529    the line.  This is why the ``normally hidden'' text in Emacs, namely
530    @samp{: Node about FOO.}, is actually visible in this example, even
531    when Visible mode is off.]]
532    
533    When you use a menu to go to another node (in a way that will be    When you use a menu to go to another node (in a way that will be
534  described soon), what you specify is the subtopic name, the first  described soon), what you specify is the subtopic name, the first
# Line 463  abbreviation for this: Line 547  abbreviation for this:
547    
548  @noindent  @noindent
549  This means that the subtopic name and node name are the same; they are  This means that the subtopic name and node name are the same; they are
550  both @samp{Foo}.  both @samp{Foo}.  (The @samp{::} is normally hidden in Emacs.)
551    
552  @format  @format
553  >> Now use @key{SPC} to find the menu in this node, then come back to  >> Now use @key{SPC} to find the menu in this node, then come back to
# Line 488  another command.  The @kbd{m} command is Line 572  another command.  The @kbd{m} command is
572  the @dfn{name of the subtopic}.  Once you have typed @kbd{m}, Info  the @dfn{name of the subtopic}.  Once you have typed @kbd{m}, Info
573  tries to read the subtopic name.  tries to read the subtopic name.
574    
575    Now look for the line containing many dashes near the bottom of the    Now, in the stand-alone Info, look for the line containing many
576  screen.  There is one more line beneath that one, but usually it is  dashes near the bottom of the screen.  (This is the stand-alone
577  blank.  When it is blank, Info is ready for a command, such as @kbd{n}  equivalent for the mode line in Emacs.)  There is one more line
578  or @kbd{b} or @key{SPC} or @kbd{m}.  If that line contains text ending  beneath that one, but usually it is blank.  (In Emacs, this is the
579  in a colon, it means Info is reading more input for the last command.  echo area.)  When it is blank, Info is ready for a command, such as
580  You can't type an Info command then, because Info is trying to read  @kbd{n} or @kbd{b} or @key{SPC} or @kbd{m}.  If that line contains
581  input, not commands.  You must either give the input and finish the  text ending in a colon, it means Info is reading more input for the
582  command you started, or type @kbd{Control-g} to cancel the command.  last command.  You can't type an Info command then, because Info is
583  When you have done one of those things, the input entry line becomes  trying to read input, not commands.  You must either give the input
584  blank again.  Then you can type Info commands again.  and finish the command you started, or type @kbd{Control-g} to cancel
585    the command.  When you have done one of those things, the input entry
586    line becomes blank again.  Then you can type Info commands again.
587    
588  @findex Info-menu  @findex Info-menu
589    The command to go to a subnode via a menu is @kbd{m}.  After you type    The command to go to a subnode via a menu is @kbd{m}.  After you type
# Line 535  three ways of going to one place, Help-F Line 621  three ways of going to one place, Help-F
621  * Help-FOO::            And yet another!  * Help-FOO::            And yet another!
622  @end menu  @end menu
623    
624    (Turn Visible mode on if you are using Emacs.)
625    
626  @format  @format
627  >>  Now type just an @kbd{m} and see what happens:  >>  Now type just an @kbd{m} and see what happens:
628  @end format  @end format
# Line 610  node's header line it acts like @kbd{n}, Line 698  node's header line it acts like @kbd{n},
698  end of the node's text @kbd{Mouse-2} moves to the next node, or up if  end of the node's text @kbd{Mouse-2} moves to the next node, or up if
699  there's no next node.  there's no next node.
700    
   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  
   
701  @format  @format
702  >> Type @kbd{n} to see more commands.  >> Type @kbd{n} to see more commands.
703  @end format  @end format
# Line 656  pointer shown in the header line (provid Line 736  pointer shown in the header line (provid
736    In Info documentation, you will see many @dfn{cross references}.    In Info documentation, you will see many @dfn{cross references}.
737  Cross references look like this: @xref{Help-Cross, Cross}.  That text  Cross references look like this: @xref{Help-Cross, Cross}.  That text
738  is a real, live cross reference, whose name is @samp{Cross} and which  is a real, live cross reference, whose name is @samp{Cross} and which
739  points to the node named @samp{Help-Cross}.  points to the node named @samp{Help-Cross}.  (The node name is hidden
740    in Emacs.  Do @kbd{M-x visible-mode} to show or hide it.)
741    
742  @kindex f @r{(Info mode)}  @kindex f @r{(Info mode)}
743  @findex Info-follow-reference  @findex Info-follow-reference
# Line 699  to cancel the @kbd{f}. Line 780  to cancel the @kbd{f}.
780    The @key{TAB} and @kbd{M-@key{TAB}} key, which move between menu    The @key{TAB} and @kbd{M-@key{TAB}} key, which move between menu
781  items in a menu, also move between cross references outside of menus.  items in a menu, also move between cross references outside of menus.
782    
783      Sometimes a cross reference (or a node) can lead to another file (in
784    other words another ``manual''), or, on occasion, even a file on a
785    remote machine (although Info files distributed with Emacs or the
786    stand-alone Info avoid using remote links).  Such a cross reference
787    looks like this: @xref{Top,, Overview of Texinfo, texinfo, Texinfo:
788    The GNU Documentation Format}.  (After following this link, type
789    @kbd{l} to get back to this node.)  Here the name @samp{texinfo}
790    between parentheses (shown in the stand-alone version) refers to the
791    file name.  This file name appears in cross references and node names
792    if it differs from the current file.  In Emacs, the file name is
793    hidden (along with other text).  (Use @kbd{M-x visible-mode} to show
794    or hide it.)
795    
796      The remainder of this node applies only to the Emacs version.  If
797    you use the stand-alone version, you can type @kbd{n} immediately.
798    
799      To some users, switching manuals is a much bigger switch than
800    switching sections.  These users like to know that they are going to
801    be switching to another manual (and which one) before actually doing
802    so, especially given that, if one does not notice, Info commands like
803    @kbd{t} (see the next node) can have confusing results.
804    
805      If you put your mouse over the cross reference and if the cross
806    reference leads to a different manual, then the information appearing
807    in a separate box (tool tip) or in the echo area, will mention the
808    file the cross reference will carry you to (between parentheses).
809    This is also true for menu subtopic names.  If you have a mouse, just
810    leave it over the @samp{Overview} cross reference above and watch what
811    happens.
812    
813      If you always like to have that information available without having
814    to move your mouse over the cross reference, set
815    @code{Info-hide-note-references} to a value other than t (@pxref{Emacs
816    Info Variables}).  You might also want to do that if you have a lot of
817    cross references to files on remote machines and have non-permanent or
818    slow access, since otherwise you might not be able to distinguish
819    between local and remote links.
820    
821    @format
822    >> Now type @kbd{n} to learn more commands.
823    @end format
824    
825  @node Help-Int, Help-Q, Help-Xref, Getting Started  @node Help-Int, Help-Q, Help-Xref, Getting Started
826  @comment  node-name,  next,  previous,  up  @comment  node-name,  next,  previous,  up
827  @section Some intermediate Info commands  @section Some intermediate Info commands
# Line 728  records the nodes where you have been in Line 851  records the nodes where you have been in
851  @kbd{l} command revisits nodes in the history list; each successive  @kbd{l} command revisits nodes in the history list; each successive
852  @kbd{l} command moves one step back through the history.  @kbd{l} command moves one step back through the history.
853    
   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}.  
   
854    In Emacs, @kbd{l} runs the command @code{Info-last}.    In Emacs, @kbd{l} runs the command @code{Info-last}.
855    
856  @format  @format
857  >> Try typing three @kbd{l}'s, pausing in between to see what each  >> Try typing @kbd{p p n} and then three @kbd{l}'s, pausing in between
858     @kbd{l} does.  Then follow directions again and you will end up  to see what each @kbd{l} does.  You should wind up right back here.
    back here.  
859  @end format  @end format
860    
861    Note the difference between @kbd{l} and @kbd{p}: @kbd{l} moves to    Note the difference between @kbd{l} and @kbd{p}: @kbd{l} moves to
862  where @emph{you} last were, whereas @kbd{p} always moves to the node  where @emph{you} last were, whereas @kbd{p} always moves to the node
863  which the header says is the @samp{Previous} node (from this node, the  which the header says is the @samp{Previous} node (from this node, the
864  @samp{Prev} link leads to @samp{Help-M}).  @samp{Prev} link leads to @samp{Help-Xref}).
865    
866  @kindex d @r{(Info mode)}  @kindex d @r{(Info mode)}
867  @findex Info-directory  @findex Info-directory
# Line 796  Texinfo file.  (However, in most cases, Line 913  Texinfo file.  (However, in most cases,
913  better, since you can use it to make a printed manual or produce other  better, since you can use it to make a printed manual or produce other
914  formats, such as HTML and DocBook, as well as for generating Info  formats, such as HTML and DocBook, as well as for generating Info
915  files.)  @xref{Top,, Overview of Texinfo, texinfo, Texinfo: The GNU  files.)  @xref{Top,, Overview of Texinfo, texinfo, Texinfo: The GNU
916  Documentation Format}.)  Documentation Format}.
917    
918  @menu  @menu
919  * Advanced::             Advanced Info commands: g, s, e, and 1 - 5.  * Advanced::             Advanced Info commands: g, e, and 1 - 9.
920  * Info Search::          How to search Info documents for specific subjects.  * Info Search::          How to search Info documents for specific subjects.
921  * Add::                  Describes how to add new nodes to the hierarchy.  * Add::                  Describes how to add new nodes to the hierarchy.
922                             Also tells what nodes look like.                             Also tells what nodes look like.
# Line 1049  The @kbd{m} command searches the current Line 1166  The @kbd{m} command searches the current
1166  reads from the terminal.  reads from the terminal.
1167    
1168  @cindex menu and menu entry format  @cindex menu and menu entry format
1169    A menu begins with a line starting with @samp{* Menu:}.  The rest of the    A menu begins with a line starting with @w{@samp{* Menu:}}.  The
1170  line is a comment.  After the starting line, every line that begins  rest of the line is a comment.  After the starting line, every line
1171  with a @samp{* } lists a single topic.  The name of the topic--what  that begins with a @samp{* } lists a single topic.  The name of the
1172  the user must type at the @kbd{m}'s command prompt to select this  topic--what the user must type at the @kbd{m}'s command prompt to
1173  topic---comes right after the star and space, and is followed by a  select this topic---comes right after the star and space, and is
1174  colon, spaces and tabs, and the name of the node which discusses that  followed by a colon, spaces and tabs, and the name of the node which
1175  topic.  The node name, like node names following @samp{Next}, @samp{Previous}  discusses that topic.  The node name, like node names following
1176  and @samp{Up}, may be terminated with a tab, comma, or newline; it may also  @samp{Next}, @samp{Previous} and @samp{Up}, may be terminated with a
1177  be terminated with a period.  tab, comma, or newline; it may also be terminated with a period.
1178    
1179    If the node name and topic name are the same, then rather than    If the node name and topic name are the same, then rather than
1180  giving the name twice, the abbreviation @samp{* @var{name}::} may be  giving the name twice, the abbreviation @samp{* @var{name}::} may be
# Line 1278  the @samp{Next}, @samp{Prev}, and @samp{ Line 1395  the @samp{Next}, @samp{Prev}, and @samp{
1395  not scroll with the rest of the buffer, making these links always  not scroll with the rest of the buffer, making these links always
1396  visible.  visible.
1397    
1398    @item Info-hide-note-references
1399    As explained in earlier nodes, the Emacs version of Info normally
1400    hides some text in menus and cross-references.  You can completely
1401    disable this feature, by setting this option to @code{nil}.  Setting
1402    it to a value that is neither @code{nil} nor @code{t} produces an
1403    intermediate behavior, hiding a limited amount of text, but showing
1404    all text that could potentially be useful.
1405    
1406  @item Info-scroll-prefer-subnodes  @item Info-scroll-prefer-subnodes
1407  If set to a non-@code{nil} value, @key{SPC} and @key{BACKSPACE} (or  If set to a non-@code{nil} value, @key{SPC} and @key{BACKSPACE} (or
1408  @key{DEL}) keys in a menu visit subnodes of the current node before  @key{DEL}) keys in a menu visit subnodes of the current node before
# Line 1286  node's menu appears on the screen, the n Line 1411  node's menu appears on the screen, the n
1411  subnode indicated by the following menu item.  Setting this option to  subnode indicated by the following menu item.  Setting this option to
1412  @code{nil} results in behavior similar to the stand-alone Info reader  @code{nil} results in behavior similar to the stand-alone Info reader
1413  program, which visits the first subnode from the menu only when you  program, which visits the first subnode from the menu only when you
1414  hit the end of the current node.  The default is @code{t}.  hit the end of the current node.  The default is @code{nil}.
1415    
1416  @item Info-enable-active-nodes  @item Info-enable-active-nodes
1417  When set to a non-@code{nil} value, allows Info to execute Lisp code  When set to a non-@code{nil} value, allows Info to execute Lisp code
# Line 1331  topics discussed in this document. Line 1456  topics discussed in this document.
1456  @printindex cp  @printindex cp
1457    
1458  @bye  @bye
1459    
1460    @ignore
1461       arch-tag: 965c1638-01d6-4156-9227-b10418b9d8e8
1462    @end ignore

Legend:
Removed from v.1.23.2.1  
changed lines
  Added in v.1.23.2.2

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26