diff options
Diffstat (limited to 'doc/info-stnd.texi')
| -rw-r--r-- | doc/info-stnd.texi | 2270 |
1 files changed, 2270 insertions, 0 deletions
diff --git a/doc/info-stnd.texi b/doc/info-stnd.texi new file mode 100644 index 0000000..0fde962 --- /dev/null +++ b/doc/info-stnd.texi @@ -0,0 +1,2270 @@ +vb\input texinfo.tex @c -*-texinfo-*- +@comment $Id: info-stnd.texi,v 1.24 2008/08/29 17:27:18 karl Exp $ +@c We must \input texinfo.tex instead of texinfo, otherwise make +@c distcheck in the Texinfo distribution fails, because the texinfo Info +@c file is made first, and texi2dvi must include . first in the path. +@comment %**start of header +@setfilename info-stnd.info +@include version-stnd.texi +@settitle GNU Info @value{VERSION} +@syncodeindex vr cp +@syncodeindex fn cp +@syncodeindex ky cp +@comment %**end of header + +@copying +This manual is for GNU Info (version @value{VERSION}, @value{UPDATED}), +a program for viewing documents in Info format (usually created from +Texinfo source files). + +Copyright @copyright{} 1992, 1993, 1996, 1997, 1998, 1999, 2001, 2002, +2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc. + +@quotation +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.2 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', +and with the Back-Cover Texts as in (a) below. A copy of the +license is included in the section entitled ``GNU Free Documentation +License' in the Texinfo manual. + +(a) The FSF's Back-Cover Text is: ``You have the freedom to +copy and modify this GNU manual. Buying copies from the FSF +supports it in developing GNU and promoting software freedom.'' +@end quotation + +This document is part of a collection distributed under the GNU Free +Documentation License. If you want to distribute this document +separately from the collection, you can do so by adding a copy of the +license to the document, as described in section 6 of the license. +@end copying + +@dircategory Texinfo documentation system +@direntry +* info standalone: (info-stnd). Read Info documents without Emacs. +* infokey: (info-stnd)Invoking infokey. Compile Info customizations. +@end direntry + +@titlepage +@title GNU Info +@subtitle for version @value{VERSION}, @value{UPDATED} +@author Brian J. Fox +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@contents + +@ifnottex +@node Top +@top GNU Info + +If you do not know how to use Info, but have a working Info reader, +you should read the Info manual before this one (@pxref{Top, Getting +Started,,info, Info}), as it includes more background information and +a thorough tutorial. This documentation describes the stand-alone Info +reader that is part of the Texinfo distribution, not the Info reader +that is part of GNU Emacs. +@end ifnottex + +@menu +* Stand-alone Info:: What is Info? +* Invoking Info:: Options you can pass on the command line. +* Cursor Commands:: Commands which move the cursor within a node. +* Scrolling Commands:: Commands for reading the text within a node. +* Node Commands:: Commands for selecting a new node. +* Searching Commands:: Commands for searching an Info file. +* Xref Commands:: Commands for selecting cross references. +* Window Commands:: Commands which manipulate multiple windows. +* Printing Nodes:: How to print out the contents of a node. +* Miscellaneous Commands:: A few commands that defy categories. +* Variables:: How to change the default behavior of Info. +* Custom Key Bindings:: How to define your own key-to-command bindings. +* Index:: Global index with keystrokes, command names, + variable names, and general concepts. +@end menu + + +@node Stand-alone Info +@chapter Stand-alone Info + +The @dfn{Info} program is a stand-alone program, part of the Texinfo +distribution, which is used to view Info files on an ASCII terminal. +@dfn{Info files} are typically the result of processing Texinfo files +with the program @code{makeinfo} (also in the Texinfo distribution) + +Texinfo itself is a documentation system that uses a single source +file to produce both on-line information and printed output. You can +typeset and print the files that you read in Info. + +GNU Emacs also provides an Info reader (just type @kbd{M-x info} in +Emacs). Emacs Info and stand-alone Info have nearly identical user +interfaces, although customization and other details are different +(this manual explains the stand-alone Info reader). The Emacs Info +reader supports the X Window System and other such bitmapped +interfaces, not just plain ASCII, so if you want the prettiest +display for Info files, you should try it. You can use Emacs Info +without using Emacs for anything else. (Type @kbd{C-x C-c} to exit; +this also works in the stand-alone Info reader.) + + +@node Invoking Info +@chapter Invoking Info + +@cindex Info, invoking +@cindex invoking Info +@cindex command line options +@cindex options, command line +@cindex arguments, command line + +GNU Info accepts several options to control the initial node being +viewed, and to specify which directories to search for Info files. Here +is a template showing an invocation of GNU Info from the shell: + +@example +info [@var{option}]@dots{} [@var{menu-item}@dots{}] +@end example + +The program accepts the following options: + +@table @code +@anchor{--apropos} +@item --apropos=@var{string} +@itemx -k @var{string} +@cindex Searching all indices +@cindex Info files@r{, searching all indices} +@cindex Apropos@r{, in Info files} +Specify a string to search in every index of every Info file installed +on your system. Info looks up the named @var{string} in all the +indices it can find, prints the results to standard output, and then +exits. If you are not sure which Info file explains certain issues, +this option is your friend. (If your system has a lot of Info files +installed, searching all of them might take some time!) + +You can invoke the apropos command from inside Info; see +@ref{Searching Commands}. + +@cindex directory path +@item --directory @var{directory-path} +@itemx -d @var{directory-path} +Prepend @var{directory-path} to the list of directory paths searched +when Info needs to find a file. You may issue @code{--directory} +multiple times; once for each directory which contains Info files. The +list of directories searched by Info is constructed from the value of +the environment variable @code{INFOPATH}; @code{--directory} causes the +named @var{directory-path} to be prepended to that list. The value of +@code{INFOPATH} is a list of directories usually separated by a colon; +on MS-DOS/MS-Windows systems, the semicolon is used. If you do not +define @code{INFOPATH}, Info uses a default path defined when Info was +built as the initial list of directories. If the value of +@code{INFOPATH} ends with a colon (or semicolon on MS-DOS/MS-Windows), +the initial list of directories is constructed by appending the +build-time default to the value of @code{INFOPATH}. + +@cindex keystrokes, recording +@cindex remembering user keystrokes +@item --dribble=@var{dribble-file} +Specify a file where all user keystrokes will be recorded. This file +can be used later to replay the same sequence of commands, see the +@samp{--restore} option below. + +@item --file @var{filename} +@itemx -f @var{filename} +@cindex Info file, selecting +Specify a particular Info file to visit. By default, Info visits +the file @code{dir}; if you use this option, Info will start with +@code{(@var{filename})Top} as the first file and node. + +@cindex relative Info file names +@cindex file names, relative +@cindex Info files, relative +If @var{filename} is an absolute file name, or begins with @file{./} or +@file{../}, Info looks for @var{filename} only in the directory of the +specified @var{filename}, and adds the directory of @var{filename} to +the value of @code{INFOPATH}. In contrast, if @var{filename} is in the +form of a relative file name, but without the @file{./} or @file{../} +prefix, Info will only look for it in the directories specified in +@code{INFOPATH}. In other words, Info does @emph{not} treat file names +which lack @file{./} and @file{../} prefix as relative to the current +directory. + +@cindex compressed Info files +@cindex files, compressed +@cindex Info files, compressed +In every directory Info tries, if @var{filename} is not found, Info +looks for it with a number of known extensions of Info files@footnote{ +@file{.info}, @file{-info}, @file{/index}, and @file{.inf}.}. For every +known extension, Info looks for a compressed file, if a regular file +isn't found. Info supports files compressed with @code{gzip}, +@code{bzip2}, @code{compress} and @code{yabba} programs; it calls +@code{gunzip}, @code{bunzip2}, @code{uncompress} and @code{unyabba}, +accordingly, to decompress such files. Compressed Info files are +assumed to have @file{.z}, @file{.gz}, @file{.bz2}, @file{.Z}, or +@file{.Y} extensions, possibly in addition to one of the known Info +files extensions@footnote{The MS-DOS version allows for the Info +extension, such as @code{.inf}, and the short compressed file +extensions, such as @file{.z} and @file{.gz}, to be merged into a single +extension, since DOS doesn't allow more than a single dot in the +basename of a file. Thus, on MS-DOS, if Info looks for @file{bison}, +file names like @file{bison.igz} and @file{bison.inz} will be found and +decompressed by @code{gunzip}.}. + +@item --help +@itemx -h +Produces a relatively brief description of the available Info options. + +@item --index-search @var{string} +@cindex index search, selecting from the command line +@cindex online help, using Info as +After processing all command-line arguments, go to the index in the Info +file and search for index entries which match @var{string}. If such an +entry is found, the Info session begins with displaying the node pointed +to by the first matching index entry; press @kbd{,} to step through the +rest of the matching entries. If no such entry exists, print @samp{no +entries found} and exit with nonzero status. This can be used from +another program as a way to provide online help, or as a quick way of +starting to read an Info file at a certain node when you don't know the +exact name of that node. + +This command can also be invoked from inside Info; see @ref{Searching +Commands}. + +@item --node @var{nodename} +@itemx -n @var{nodename} +@cindex node, selecting from the command line +Specify a particular node to visit in the initial file that Info +loads. This is especially useful in conjunction with +@code{--file}@footnote{Of course, you can specify both the file and node +in a @code{--node} command; but don't forget to escape the open and +close parentheses and whitespace from the shell as in: @code{info --node +"(emacs)Buffers"}.}. You may specify @code{--node} multiple times; for +an interactive Info, each @var{nodename} is visited in its own window, +for a non-interactive Info (such as when @code{--output} is given) each +@var{nodename} is processed sequentially. + +@item --output @var{filename} +@itemx -o @var{filename} +@cindex file, outputting to +@cindex outputting to a file +Specify @var{filename} as the name of a file to which to direct output. +Each node that Info visits will be output to @var{filename} instead of +interactively viewed. A value of @code{-} for @var{filename} specifies +the standard output. + +@cindex colors in documents +@cindex ANSI escape sequences in documents +@item --raw-escapes +@itemx --no-raw-escapes +@itemx -R +Do not remove ANSI escape sequences from documents. Some versions of +Groff, the GNU document formatter, produce man pages with ANSI escape +sequences for bold, italics, and underlined characters, and for +colorized text. By default, Info lets those escape sequences pass +through directly to the terminal. If your terminal does not support +these escapes, use @code{--no-raw-escapes} to make Info remove them. + +@cindex replaying recorded keystrokes +@item --restore=@var{dribble-file} +Read keystrokes from @var{dribble-file}, presumably recorded during +previous Info session (see the description of the @samp{--dribble} +option above). When the keystrokes in the files are all read, Info +reverts its input to the usual interactive operation. + +@item --show-malformed-multibytes +@itemx --no-show-malformed-multibytes + Show malformed multibyte sequences in the output. By default, such +sequences are dropped. + +@anchor{--show-options} +@cindex command-line options, how to find +@cindex invocation description, how to find +@item --show-options +@itemx --usage +@itemx -O +This option causes Info to look for the node that describes how to +invoke the program and its command-line options, and begin the session +by displaying that node. It is provided to make it easier to find the +most important usage information in a manual without the need to wade +through complex menu hierarchies. The effect is similar to the +@code{M-x goto-invocation} command (@pxref{goto-invocation}) from inside +Info. + +@cindex speech synthesizers +@item --speech-friendly +@itemx -b +On MS-DOS/MS-Windows only, this option causes Info to use standard file +I/O functions for screen writes. (By default, Info uses direct writes +to the video memory on these systems, for faster operation and colored +display support.) This allows the speech synthesizers used by blind +persons to catch the output and convert it to audible speech. + +@item --subnodes +@cindex @code{--subnodes}, command line option +This option only has meaning when given in conjunction with +@code{--output}. It means to recursively output the nodes appearing in +the menus of each node being output. Menu items which resolve to +external Info files are not output, and neither are menu items which are +members of an index. Each node is only output once. + +@item --version +@cindex version information +Prints the version information of Info and exits. + +@anchor{--vi-keys} +@cindex vi-like key bindings +@cindex Less-like key bindings +@item --vi-keys +This option binds functions to keys differently, to emulate the key +bindings of @code{vi} and Less. The default key bindings are generally +modeled after Emacs. +(@xref{Custom Key Bindings}, +for a more general way of altering GNU Info's key bindings.) + +@cindex Info manual location +@cindex Where is an Info manual? +@item --where +@itemx --location +@itemx -w +Show the filename that would be read and exit, instead of actually +reading it and starting Info. + +@item @var{menu-item} +@cindex menu, following +@anchor{command-line menu items} +Info treats its remaining arguments as the names of menu items. The +first argument is a menu item in the initial node visited (generally +@code{dir}), the second argument is a menu item in the first argument's +node, etc. You can easily move to the node of your choice by specifying +the menu names which describe the path to that node. For example, + +@example +info emacs buffers +@end example + +@noindent +first selects the menu item @samp{Emacs} in the node @samp{(dir)Top}, +and then selects the menu item @samp{Buffers} in the node +@samp{(emacs)Top}. +@end table + +To avoid searching the @file{dir} files and just show some arbitrary +file, use @samp{-f} and the filename, as in @samp{info -f ./foo.info}. + +The index search and the search for the node which describes program +invocation and command-line options begins @emph{after} processing all +the command-line menu items. Therefore, the Info file searched for the +index or the invocation node is the file where Info finds itself after +following all the menu items given on the command line. This is so +@samp{info emacs --show-options} does what you'd expect. + +Finally, Info defines many default key bindings and variables. +@xref{Custom Key Bindings}, for information on how to customize these +settings. + +@c FIXME: the feature with lowercasing the file name isn't documented + + +@node Cursor Commands +@chapter Moving the Cursor +@cindex cursor, moving +@cindex moving the cursor + +Many people find that reading screens of text page by page is made +easier when one is able to indicate particular pieces of text with +some kind of pointing device. Since this is the case, GNU Info (both +the Emacs and stand-alone versions) have several commands which allow +you to move the cursor about the screen. The notation used in this +manual to describe keystrokes is identical to the notation used within +the Emacs manual, and the GNU Readline manual. @xref{User Input,,, +emacs, The GNU Emacs Manual}, if you are unfamiliar with the +notation.@footnote{Here's a short summary. @kbd{C-@var{x}} means +press the @kbd{CTRL} key and the key @var{x}. @kbd{M-@var{x}} means +press the @kbd{META} key and the key @var{x}. On many terminals th +@kbd{META} key is known as the @kbd{ALT} key. @kbd{SPC} is the space +bar. The other keys are usually called by the names imprinted on +them.} + +The following table lists the basic cursor movement commands in Info. +Each entry consists of the key sequence you should type to execute the +cursor movement, the @code{M-x}@footnote{@code{M-x} is also a command; it +invokes @code{execute-extended-command}. @xref{M-x, , Executing an +extended command, emacs, The GNU Emacs Manual}, for more detailed +information.} command name (displayed in parentheses), and a short +description of what the command does. All of the cursor motion commands +can take a @dfn{numeric} argument (see @ref{Miscellaneous Commands, +@code{universal-argument}, to find out how to supply them}. With a +numeric argument, the motion commands are simply executed that +many times; for example, a numeric argument of 4 given to +@code{next-line} causes the cursor to move down 4 lines. With a +negative numeric argument, the motion is reversed; an argument of -4 +given to the @code{next-line} command would cause the cursor to move +@emph{up} 4 lines. + +@table @asis +@item @kbd{C-n} (@code{next-line}) +@itemx @key{DOWN} (an arrow key) +@kindex C-n +@kindex DOWN (an arrow key) +@findex next-line +Move the cursor down to the next line. + +@item @kbd{C-p} (@code{prev-line}) +@itemx @key{UP} (an arrow key) +@kindex C-p +@kindex UP (an arrow key) +@findex prev-line +Move the cursor up to the previous line. + +@item @kbd{C-a} (@code{beginning-of-line}) +@itemx @key{Home} (on DOS/Windows only) +@kindex C-a, in Info windows +@kindex Home +@findex beginning-of-line +Move the cursor to the start of the current line. + +@item @kbd{C-e} (@code{end-of-line}) +@itemx @key{End} (on DOS/Windows only) +@kindex C-e, in Info windows +@kindex End +@findex end-of-line +Move the cursor to the end of the current line. + +@item @kbd{C-f} (@code{forward-char}) +@itemx @key{RIGHT} (an arrow key) +@kindex C-f, in Info windows +@kindex RIGHT (an arrow key) +@findex forward-char +Move the cursor forward a character. + +@item @kbd{C-b} (@code{backward-char}) +@itemx @key{LEFT} (an arrow key) +@kindex C-b, in Info windows +@kindex LEFT (an arrow key) +@findex backward-char +Move the cursor backward a character. + +@item @kbd{M-f} (@code{forward-word}) +@itemx @kbd{C-@key{RIGHT}} (on DOS/Windows only) +@kindex M-f, in Info windows +@kindex C-RIGHT +@findex forward-word +Move the cursor forward a word. + +@item @kbd{M-b} (@code{backward-word}) +@itemx @kbd{C-@key{LEFT}} (on DOS/Windows only) +@kindex M-b, in Info windows +@kindex C-LEFT +@findex backward-word +Move the cursor backward a word. + +@item @kbd{M-<} (@code{beginning-of-node}) +@itemx @kbd{C-@key{Home}} (on DOS/Windows only) +@itemx @kbd{b} +@itemx @kbd{M-b}, vi-like operation +@kindex b, in Info windows +@kindex M-< +@kindex C-Home +@kindex M-b, vi-like operation +@findex beginning-of-node +Move the cursor to the start of the current node. + +@item @kbd{M->} (@code{end-of-node}) +@itemx @kbd{C-@key{End}} (on DOS/Windows only) +@itemx @kbd{e} +@kindex M-> +@kindex e, in Info windows +@kindex C-End +@findex end-of-node +Move the cursor to the end of the current node. + +@item @kbd{M-r} (@code{move-to-window-line}) +@kindex M-r +@findex move-to-window-line +Move the cursor to a specific line of the window. Without a numeric +argument, @code{M-r} moves the cursor to the start of the line in the +center of the window. With a numeric argument of @var{n}, @code{M-r} +moves the cursor to the start of the @var{n}th line in the window. +@end table + + +@node Scrolling Commands +@chapter Moving Text Within a Window +@cindex scrolling + +Sometimes you are looking at a screenful of text, and only part of the +current paragraph you are reading is visible on the screen. The +commands detailed in this section are used to shift which part of the +current node is visible on the screen. + +Scrolling commands are bound differently when @samp{--vi-keys} +operation is in effect (@pxref{--vi-keys}). These key bindings are +designated with ``vi-like operation''. @xref{Custom Key Bindings}, +for information on arbitrarily customizing key bindings and variable +settings. + +@table @asis +@item @key{SPC} (@code{scroll-forward}) +@kindex SPC, in Info windows +@findex scroll-forward +Shift the text in this window up. That is, show more of the node which +is currently below the bottom of the window. With a numeric argument, +show that many more lines at the bottom of the window; a numeric +argument of 4 would shift all of the text in the window up 4 lines +(discarding the top 4 lines), and show you four new lines at the bottom +of the window. Without a numeric argument, @key{SPC} takes the bottom +two lines of the window and places them at the top of the window, +redisplaying almost a completely new screenful of lines. If you are at +the end of a node, @key{SPC} takes you to the ``next'' node, so that you can +read an entire manual from start to finish by repeating @key{SPC}. + +The default scroll size is one screen-full, but it can be changed by +invoking the (@code{scroll-forward-page-only-set-window}) command, +@samp{z} under @samp{--vi-keys}, with a numeric argument. + +@item @key{NEXT} (an arrow key) (@code{scroll-forward-page-only}) +@itemx @kbd{C-v} +@itemx @kbd{C-f}, vi-like operation +@itemx @kbd{f}, vi-like operation +@itemx @kbd{M-SPC}, vi-like operation +@kindex NEXT +@kindex C-v +@kindex C-f, vi-like operation +@kindex f, vi-like operation +@kindex M-SPC, vi-like operation +@findex scroll-forward-page-only +Shift the text in this window up. This is identical to the @key{SPC} +operation above, except that it never scrolls beyond the end of the +current node. + +@kindex PageDown +The @key{NEXT} key is known as the @key{PageDown} key on some +keyboards. + +@item @kbd{z} (@code{scroll-forward-page-only-set-window}, vi-like operation) +@kindex z, vi-like operation +@findex scroll-forward-page-only-set-window +Scroll forward, like with @key{NEXT}, but if a numeric argument is +specified, it becomes the default scroll size for subsequent +@code{scroll-forward} and @code{scroll-backward} commands and their +ilk. + +@item @key{DEL} (@code{scroll-backward}) +@kindex DEL, in Info windows +@findex scroll-backward +Shift the text in this window down. The inverse of +@code{scroll-forward}. +If you are at the start of a node, @key{DEL} takes you to the +``previous'' node, so that you can read an entire manual from finish to +start by repeating @key{DEL}. The default scroll size can be changed by +invoking the (@code{scroll-backward-page-only-set-window}) command, +@samp{w} under @samp{--vi-keys}, with a numeric argument. + +@itemx @key{PREVIOUS} (arrow key) (@code{scroll-backward-page-only}) +@itemx @key{PRIOR} (arrow key) +@itemx @kbd{M-v} +@itemx @kbd{b}, vi-like operation +@itemx @kbd{C-b}, vi-like operation +@kindex PREVIOUS +@kindex M-v +@kindex b, vi-like operation +@kindex C-b, vi-like operation +@findex scroll-backward-page-only +Shift the text in this window down. The inverse of +@code{scroll-forward-page-only}. Does not scroll beyond the start of +the current node. The default scroll size can be changed by invoking +the(@code{scroll-backward-page-only-set-window}) command, @samp{w} under +@samp{--vi-keys}, with a numeric argument. + +@item @kbd{w} (@code{scroll-backward-page-only-set-window}, vi-like operation) +@kindex w, vi-like operation +@findex scroll-backward-page-only-set-window +Scroll backward, like with @key{PREVIOUS}, but if a numeric argument is +specified, it becomes the default scroll size for subsequent +@code{scroll-forward} and @code{scroll-backward} commands. + +@item @kbd{C-n} (@code{down-line}, vi-like operation) +@itemx @kbd{C-e}, vi-like operation +@itemx @key{RET}, vi-like operation +@itemx @key{LFD}, vi-like operation +@itemx @key{DOWN}, vi-like operation +@kindex C-n, vi-like operation +@kindex C-e, vi-like operation +@kindex RET, vi-like operation +@kindex LFD, vi-like operation +@kindex DOWN, vi-like operation +@findex down-line +Scroll forward by one line. With a numeric argument, scroll forward +that many lines. + +@item @kbd{C-p} (@code{up-line}, vi-like operation) +@itemx @key{UP}, vi-like operation +@itemx @kbd{y}, vi-like operation +@itemx @kbd{k}, vi-like operation +@itemx @kbd{C-k}, vi-like operation +@itemx @kbd{C-y}, vi-like operation +@kindex C-p, vi-like operation +@kindex UP, vi-like operation +@kindex y, vi-like operation +@kindex k, vi-like operation +@kindex C-k, vi-like operation +@kindex C-y, vi-like operation +@findex up-line +Scroll backward one line. With a numeric argument, scroll backward that +many lines. + +@item @kbd{d} (@code{scroll-half-screen-down}, vi-like operation) +@itemx @kbd{C-d}, vi-like operation +@kindex d, vi-like operation +@kindex C-d, vi-like operation +@findex scroll-half-screen-down +Scroll forward by half of the screen size. With a numeric argument, +scroll that many lines. If an argument is specified, it becomes the new +default number of lines to scroll for subsequent @samp{d} and @samp{u} +commands. + +@item @kbd{u} (@code{scroll-half-screen-up}, vi-like operation) +@itemx @kbd{C-u}, vi-like operation +@kindex u, vi-like operation +@kindex C-u, vi-like operation +@findex scroll-half-screen-up +Scroll back by half of the screen size. With a numeric argument, +scroll that many lines. If an argument is specified, it becomes the new +default number of lines to scroll for subsequent @samp{u} and @samp{d} +commands. +@end table + +@cindex scrolling through node structure +The @code{scroll-forward} and @code{scroll-backward} commands can also +move forward and backward through the node structure of the file. If +you press @key{SPC} while viewing the end of a node, or @key{DEL} while +viewing the beginning of a node, what happens is controlled by the +variable @code{scroll-behavior} (@pxref{scroll-behavior}). + +The @code{scroll-forward-page-only} and @code{scroll-backward-page-only} +commands never scroll beyond the current node. + +@kindex PageUp +The @key{PREVIOUS} key is the @key{PageUp} key on many keyboards. Emacs +refers to it by the name @key{PRIOR}. When you use @key{PRIOR} or +@key{PageUp} to scroll, Info never scrolls beyond the beginning of the +current node. + +@kindex BS (backspace) +If your keyboard lacks the @key{DEL} key, look for a key called +@key{BS}, or @samp{Backspace}, sometimes designated with an arrow which +points to the left, which should perform the same function. + +@table @asis +@item @kbd{C-l} (@code{redraw-display}) +@kindex C-l +@findex redraw-display +Redraw the display from scratch, or shift the line containing the cursor +to a specified location. With no numeric argument, @samp{C-l} clears +the screen, and then redraws its entire contents. Given a numeric +argument of @var{n}, the line containing the cursor is shifted so that +it is on the @var{n}th line of the window. + +@item @kbd{C-x @kbd{w}} (@code{toggle-wrap}) +@kindex C-w +@findex toggle-wrap +Toggles the state of line wrapping in the current window. Normally, +lines which are longer than the screen width @dfn{wrap}, i.e., they are +continued on the next line. Lines which wrap have a @samp{\} appearing +in the rightmost column of the screen. You can cause such lines to be +terminated at the rightmost column by changing the state of line +wrapping in the window with @code{C-x w}. When a line which needs more +space than one screen width to display is displayed, a @samp{$} appears +in the rightmost column of the screen, and the remainder of the line is +invisible. When long lines are truncated, the modeline displays the +@samp{$} character near its left edge. +@end table + + +@node Node Commands +@chapter Selecting a Node +@cindex nodes, selection of + +This section details the numerous Info commands which select a new node +to view in the current window. + +The most basic node commands are @samp{n}, @samp{p}, @samp{u}, and +@samp{l}. Note that the commands to select nodes are mapped differently +when @samp{--vi-keys} is in effect; these keybindings are designated +below as ``vi-like operation''. + +When you are viewing a node, the top line of the node contains some Info +@dfn{pointers} which describe where the next, previous, and up nodes +are. Info uses this line to move about the node structure of the file +when you use the following commands: + +@table @asis +@item @kbd{n} (@code{next-node}) +@itemx @kbd{C-@key{NEXT}} (on DOS/Windows only) +@itemx @kbd{C-x @kbd{n}}, vi-like operation +@kindex n +@kindex C-NEXT +@kindex C-x n, vi-like operation +@findex next-node +Select the `Next' node. + +@kindex C-PgDn +The @key{NEXT} key is known as the @key{PgDn} key on some +keyboards. + +@item @kbd{p} (@code{prev-node}) +@itemx @kbd{C-@key{PREVIOUS}} (on DOS/Windows only) +@kindex p +@kindex C-PREVIOUS +@findex prev-node +Select the `Prev' node. + +@kindex C-PgUp +The @key{PREVIOUS} key is known as the @key{PgUp} key on some +keyboards. + +@item @kbd{u} (@code{up-node}) +@itemx @kbd{C-@key{UP}} (an arrow key on DOS/Windows only) +@itemx @kbd{C-x @kbd{u}}, vi-like operation +@kindex u +@kindex C-UP +@kindex C-x u, vi-like operation +@findex up-node +Select the `Up' node. +@end table + +You can easily select a node that you have already viewed in this window +by using the @samp{l} command---this name stands for ``last'', and +actually moves backwards through the history of visited nodes for this +window. This is handy when you followed a reference to another node, +possibly to read about a related issue, and would like then to resume +reading at the same place where you started the excursion. + +Each node where you press @samp{l} is discarded from the history. Thus, +by the time you get to the first node you visited in a window, the +entire history of that window is discarded. + +@table @asis +@item @kbd{l} (@code{history-node}) +@itemx @kbd{C-@key{CENTER}} (on DOS/Windows only) +@itemx @kbd{'}, vi-like operation +@kindex l +@kindex C-CENTER +@kindex ', vi-like operation +@findex history-node +Pop the most recently selected node in this window from the node +history. +@end table + +Two additional commands make it easy to select the most commonly +selected nodes; they are @samp{t} and @samp{d}. + +@table @asis +@item @kbd{t} (@code{top-node}) +@itemx @kbd{M-t}, vi-like operation +@kindex t +@kindex M-t, vi-like operation +@findex top-node +Select the node @samp{Top} in the current Info file. + +@item @kbd{d} (@code{dir-node}) +@itemx @kbd{M-d}, vi-like operation +@kindex d +@kindex M-d, vi-like operation +@findex dir-node +Select the directory node (i.e., the node @samp{(dir)}). +@end table + +Here are some other commands which immediately result in the selection +of a different node in the current window: + +@table @asis +@item @kbd{<} (@code{first-node}) +@itemx @kbd{g}, vi-like operation +@kindex < +@kindex g, vi-like operation +@findex first-node +Selects the first node which appears in this file. This node is most +often @samp{Top}, but it does not have to be. With a numeric argument +@var{N}, select the @var{N}th node (the first node is node 1). An +argument of zero is the same as the argument of 1. + +@item @kbd{>} (@code{last-node}) +@itemx @kbd{G}, vi-like operation +@kindex > +@kindex G, vi-like operation +@findex last-node +Select the last node which appears in this file. With a numeric argument +@var{N}, select the @var{N}th node (the first node is node 1). An +argument of zero is the same as no argument, i.e., it selects the last +node. + +@item @kbd{]} (@code{global-next-node}) +@kindex ] +@findex global-next-node +Move forward or down through node structure. If the node that you are +currently viewing has a @samp{Next} pointer, that node is selected. +Otherwise, if this node has a menu, the first menu item is selected. If +there is no @samp{Next} and no menu, the same process is tried with the +@samp{Up} node of this node. + +@item @kbd{[} (@code{global-prev-node}) +@kindex [ +@findex global-prev-node +Move backward or up through node structure. If the node that you are +currently viewing has a @samp{Prev} pointer, that node is selected. +Otherwise, if the node has an @samp{Up} pointer, that node is selected, +and if it has a menu, the last item in the menu is selected. +@end table + +You can get the same behavior as @code{global-next-node} and +@code{global-prev-node} while simply scrolling through the file with +@key{SPC} and @key{DEL} (@pxref{scroll-behavior}). + +@table @asis +@anchor{goto-node} +@item @kbd{g} (@code{goto-node}) +@itemx @kbd{C-x @kbd{g}}, vi-like operation +@kindex g +@kindex C-x g, vi-like operation +@findex goto-node +Read the name of a node and select it. While reading the node name, +completion (@pxref{The Echo Area, completion}) is only done for the +nodes which reside in one of the Info files that were loaded in the +current Info session; if the desired node resides in some other file, +you must type the node exactly as it appears in that Info file, and you +must include the Info file of the other file. For example, + +@example +@code{g(emacs)Buffers} +@end example + +finds the node @samp{Buffers} in the Info file @file{emacs}. + +@anchor{goto-invocation} +@item @kbd{O} (@code{goto-invocation} +@itemx @kbd{I} +@kindex O +@kindex I +@findex goto-invocation +@cindex finding the Invocation node +Read the name of a program and look for a node in the current Info file +which describes the invocation and the command-line options for that +program. The default program name is derived from the name of the +current Info file. This command does the same as the +@samp{--show-options} command-line option (@pxref{--show-options}), but +it also allows to specify the program name; this is important for those +manuals which describe several programs. + +If you need to find the Invocation node of a program that is documented +in another Info file, you need to visit that file before invoking +@samp{I}. For example, if you are reading the Emacs manual and want to +see the command-line options of the @code{makeinfo} program, type @kbd{g +(texinfo) @key{RET}} and then @kbd{I makeinfo @key{RET}}. If you don't +know what Info file documents the command, or if invoking @samp{I} +doesn't display the right node, go to the @samp{(dir)} node (using the +@samp{d} command) and invoke @samp{I} from there. + +@item @kbd{G} (@code{menu-sequence}) +@kindex G +@findex menu-sequence +@cindex menu, following, from inside Info +Read a sequence of menu entries and follow it. Info prompts for a +sequence of menu items separated by commas. (Since commas are not +allowed in a node name, they are a natural choice for a delimiter in a +list of menu items.) Info then looks up the first item in the menu of +the node @samp{(dir)} (if the @samp{(dir)} node cannot be found, Info +uses @samp{Top}). If such an entry is found, Info goes to the node it +points to and looks up the second item in the menu of that node, etc. +In other words, you can specify a complete path which descends through +the menu hierarchy of a particular Info file starting at the +@samp{(dir)} node. This has the same effect as if you typed the menu +item sequence on Info's command line, see @ref{command-line menu items,, +Info command-line arguments processing}. For example, + +@example + @kbd{G Texinfo,Overview,Reporting Bugs @key{RET}} +@end example + +@noindent +displays the node @samp{Reporting Bugs} in the Texinfo manual. (You +don't actually need to type the menu items in their full length, or in +their exact letter-case. However, if you do type the menu items +exactly, Info will find it faster.) + +If any of the menu items you type are not found, Info stops at the last +entry it did find and reports an error. + +@item @kbd{C-x @kbd{k}} (@code{kill-node}) +@kindex C-x k +@findex kill-node +Kill a node. The node name is prompted for in the echo area, with a +default of the current node. @dfn{Killing} a node means that Info tries +hard to forget about it, removing it from the list of history nodes kept +for the window where that node is found. Another node is selected in +the window which contained the killed node. + +@item @kbd{C-x C-f} (@code{view-file}) +@kindex C-x C-f +@findex view-file +Read the name of a file and selects the entire file. The command +@example +@code{C-x C-f @var{filename}} +@end example +is equivalent to typing +@example +@code{g(@var{filename})*} +@end example + +@item @kbd{C-x C-b} (@code{list-visited-nodes}) +@kindex C-x C-b +@findex list-visited-nodes +Make a window containing a menu of all of the currently visited nodes. +This window becomes the selected window, and you may use the standard +Info commands within it. + +@item @kbd{C-x @kbd{b}} (@code{select-visited-node}) +@kindex C-x b +@findex select-visited-node +Select a node which has been previously visited in a visible window. +This is similar to @samp{C-x C-b} followed by @samp{m}, but no window is +created. +@end table + + +@node Searching Commands +@chapter Searching an Info File +@cindex searching + +GNU Info allows you to search for a sequence of characters throughout an +entire Info file, search through the indices of an Info file, or find +areas within an Info file which discuss a particular topic. + +@table @asis +@item @kbd{s} (@code{search}) +@itemx @kbd{/} +@kindex s +@kindex / +@findex search +@cindex regular expression search +Read a string in the echo area and search for it, either as a regular +expression (by default) or a literal string. If the string includes +upper-case characters, the Info file is searched case-sensitively; +otherwise Info ignores the letter case. With a numeric argument of +@var{N}, search for @var{N}th occurrence of the string. Negative +arguments search backwards. + +@item @kbd{?} (@code{search-backward}, vi-like operation) +@kindex ?, vi-like operation +@findex search-backward +Read a string in the echo area and search backward through the Info file +for that string. If the string includes upper-case characters, the Info +file is searched case-sensitively; otherwise Info ignores the letter +case. With a numeric argument of @var{N}, search for @var{N}th +occurrence of the string. Negative arguments search forward. + +@item @kbd{R} (@code{toggle-regexp}) +@kindex R +@findex toggle-regexp +Toggle between using regular expressions and literal strings for +searching. Info uses so-called `extended' regular expression syntax, +similar to Emacs (@pxref{Regexps, , Using Regular Expressions, emacs, +The GNU Emacs Manual}). + +@item @kbd{S} (@code{search-case-sensitively} +@kindex S +@findex search-case-sensitively +@cindex search, case-sensitive +@cindex case-sensitive search +Read a string in the echo area and search for it case-sensitively, even +if the string includes only lower-case letters. With a numeric argument +of @var{N}, search for @var{N}th occurrence of the string. Negative +arguments search backwards. + +@item @kbd{C-x @kbd{n}} (@code{search-next}) +@itemx @kbd{n}, vi-like operation +@kindex C-x n +@kindex n, vi-like operation +@findex search-next +@cindex repeated search +Search for the same string used in the last search command, in the same +direction, and with the same case-sensitivity option. With a numeric +argument of @var{N}, search for @var{N}th next occurrence. + +@item @kbd{C-x @kbd{N}} (@code{search-previous}) +@itemx @kbd{N}, vi-like operation +@kindex C-x N +@kindex n, vi-like operation +@findex search-previous +Search for the same string used in the last search command, and with the +same case-sensitivity option, but in the reverse direction. With a +numeric argument of @var{N}, search for @var{N}th previous occurrence. + +@item @kbd{C-s} (@code{isearch-forward}) +@kindex C-s +@findex isearch-forward +@cindex incremental search +Interactively search forward through the Info file for a string as you +type it. If the string includes upper-case characters, the search is +case-sensitive; otherwise Info ignores the letter case. + +@item @kbd{C-r} (@code{isearch-backward}) +@kindex C-r +@findex isearch-backward +Interactively search backward through the Info file for a string as +you type it. If the string includes upper-case characters, the search +is case-sensitive; otherwise Info ignores the letter case. + +@item @kbd{i} (@code{index-search}) +@kindex i +@findex index-search +@cindex index, searching +@cindex searching, in the indices +Look up a string in the indices for this Info file, and select a node +to which the found index entry points. + +@item @kbd{,} (@code{next-index-match}) +@kindex , +@findex next-index-match +Move to the node containing the next matching index item from the last +@samp{i} command. + +@item @kbd{M-x index-apropos} +@findex index-apropos +Grovel the indices of all the known Info files on your system for a +string, and build a menu of the possible matches. +@end table + +The most basic searching command is @samp{s} or @samp{/} +(@code{search}). The @samp{s} command prompts you for a string in the +echo area, and then searches the remainder of the Info file for an +occurrence of that string. If the string is found, the node containing +it is selected, and the cursor is left positioned at the start of the +found string. Subsequent @samp{s} commands show you the default search +string within @samp{[} and @samp{]}; pressing @key{RET} instead of +typing a new string will use the default search string. Under +@samp{--vi-keys} (@pxref{--vi-keys}), using the @samp{n} or @samp{N} +commands is a faster way of searching for the same string. + +@dfn{Incremental searching} is similar to basic searching, but the +string is looked up while you are typing it, instead of waiting until +the entire search string has been specified. + +@cindex search, and case-sensitivity +@cindex case-sensitivity, and search +Both incremental and non-incremental search by default ignore the case +of letters when comparing the Info file text with the search string. +However, an uppercase letter in the search string makes the search +case-sensitive. You can force a case-sensitive non-incremental search, +even for a string that includes only lower-case letters, by using the +@samp{S} command (@code{search-case-sensitively}). The @samp{n} and +@samp{N} commands operate case-sensitively if the last search command +was @samp{S}. + +The most efficient means of finding something quickly in a manual is +the @samp{i} command (@code{index-search}). This command prompts for +a string, and then looks for that string in all the indices of the +current Info manual. If it finds a matching index entry, it displays +the node to which that entry refers and prints the full text of the +entry in the echo area. You can press @samp{,} +(@code{next-index-match}) to find more matches. A good Info manual +has all of its important concepts indexed, so the @samp{i} command +lets you use a manual as a reference. + +If you don't know what manual documents something, try the @kbd{M-x +index-apropos} command. It prompts for a string and then looks up +that string in all the indices of all the Info documents installed on +your system. It can also be invoked from the command line; see +@ref{--apropos}. + + +@node Xref Commands +@chapter Selecting Cross References + +We have already discussed the @samp{Next}, @samp{Prev}, and @samp{Up} +pointers which appear at the top of a node. In addition to these +pointers, a node may contain other pointers which refer you to a +different node, perhaps in another Info file. Such pointers are called +@dfn{cross references}, or @dfn{xrefs} for short. + +@menu +* Parts of an Xref:: What a cross reference is made of. +* Selecting Xrefs:: Commands for selecting menu or note items. +@end menu + +@node Parts of an Xref +@section Parts of an Xref + +Cross references have two major parts: the first part is called the +@dfn{label}; it is the name that you can use to refer to the cross +reference, and the second is the @dfn{target}; it is the full name of +the node that the cross reference points to. + +The target is separated from the label by a colon @samp{:}; first the +label appears, and then the target. For example, in the sample menu +cross reference below, the single colon separates the label from the +target. + +@example +* Foo Label: Foo Target. More information about Foo. +@end example + +Note the @samp{.} which ends the name of the target. The @samp{.} is +not part of the target; it serves only to let Info know where the target +name ends. + +A shorthand way of specifying references allows two adjacent colons to +stand for a target name which is the same as the label name: + +@example +* Foo Commands:: Commands pertaining to Foo. +@end example + +In the above example, the name of the target is the same as the name of +the label, in this case @code{Foo Commands}. + +You will normally see two types of cross reference while viewing nodes: +@dfn{menu} references, and @dfn{note} references. Menu references +appear within a node's menu; they begin with a @samp{*} at the beginning +of a line, and continue with a label, a target, and a comment which +describes what the contents of the node pointed to contains. + +Note references appear within the body of the node text; they begin with +@code{*Note}, and continue with a label and a target. + +Like @samp{Next}, @samp{Prev}, and @samp{Up} pointers, cross references +can point to any valid node. They are used to refer you to a place +where more detailed information can be found on a particular subject. +Here is a cross reference which points to a node within the Texinfo +documentation: @xref{xref, , Writing an Xref, texinfo, the Texinfo +Manual}, for more information on creating your own texinfo cross +references. + +@node Selecting Xrefs +@section Selecting Xrefs + +The following table lists the Info commands which operate on menu items. + +@table @asis +@item @kbd{1} (@code{menu-digit}) +@itemx @kbd{2} @dots{} @kbd{9} +@itemx @kbd{M-1}, vi-like operation +@itemx @kbd{M-2} @dots{} @kbd{M-9}, vi-like operation +@cindex 1 @dots{} 9, in Info windows +@cindex M-1 @dots{} M-9, vi-like operation +@kindex 1 @dots{} 9, in Info windows +@kindex M-1 @dots{} M-9, vi-like operation +@findex menu-digit +Within an Info window, pressing a single digit, (such as @samp{1}), +selects that menu item, and places its node in the current window. +For convenience, there is one exception; pressing @samp{0} selects the +@emph{last} item in the node's menu. When @samp{--vi-keys} is in +effect, digits set the numeric argument, so these commands are remapped +to their @samp{M-} varieties. For example, to select the last menu +item, press @kbd{M-0}. + +@item @kbd{0} (@code{last-menu-item}) +@itemx @kbd{M-0}, vi-like operation +@kindex 0, in Info windows +@kindex M-0, vi-like operation +@findex last-menu-item +Select the last item in the current node's menu. + +@item @kbd{m} (@code{menu-item}) +@kindex m +@findex menu-item +Reads the name of a menu item in the echo area and selects its node. +Completion is available while reading the menu label. @xref{The Echo +Area, completion}. + +@item @kbd{M-x find-menu} +@findex find-menu +Move the cursor to the start of this node's menu. +@end table + +This table lists the Info commands which operate on cross references. + +@table @asis +@item @kbd{f} (@code{xref-item}) +@itemx @kbd{r} +@item @kbd{M-f}, vi-like operation +@itemx @kbd{C-x @kbd{r}}, vi-like operation +@kindex f +@kindex r +@kindex M-f, vi-like operation +@kindex C-x r, vi-like operation +@findex xref-item +Reads the name of a note cross reference in the echo area and selects +its node. Completion is available while reading the cross reference +label. @xref{The Echo Area, completion}. +@end table + +Finally, the next few commands operate on menu or note references alike: + +@table @asis +@item @key{TAB} (@code{move-to-next-xref}) +@kindex TAB, in Info windows +@findex move-to-next-xref +Move the cursor to the start of the next nearest menu item or note +reference in this node. You can then use @key{RET} +(@code{select-reference-this-line}) to select the menu or note reference. + +@item @kbd{M-TAB} (@code{move-to-prev-xref}) +@itemx @kbd{Shift-@key{TAB}} (on DOS/Windows only) +@kindex M-TAB, in Info windows +@findex move-to-prev-xref +Move the cursor the start of the nearest previous menu item or note +reference in this node. + +@kindex Shift-TAB, in Info windows +@kindex BackTab, in Info windows +On DOS/Windows only, the @kbd{Shift-@key{TAB}} key is an alias for +@kbd{M-@key{TAB}}. This key is sometimes called @samp{BackTab}. + +@item @key{RET} (@code{select-reference-this-line}) +@itemx @kbd{M-g}, vi-like operation +@kindex RET, in Info windows +@kindex M-g, vi-like operation +@findex select-reference-this-line +Select the menu item or note reference appearing on this line. +@end table + + +@node Window Commands +@chapter Manipulating Multiple Windows +@cindex windows, manipulating + +A @dfn{window} is a place to show the text of a node. Windows have a +view area where the text of the node is displayed, and an associated +@dfn{mode line}, which briefly describes the node being viewed. + +GNU Info supports multiple windows appearing in a single screen; each +window is separated from the next by its modeline. At any time, there +is only one @dfn{active} window, that is, the window in which the cursor +appears. There are commands available for creating windows, changing +the size of windows, selecting which window is active, and for deleting +windows. + +@menu +* The Mode Line:: What appears in the mode line? +* Basic Windows:: Manipulating windows in Info. +* The Echo Area:: Used for displaying errors and reading input. +@end menu + +@node The Mode Line +@section The Mode Line + +A @dfn{mode line} is a line of inverse video which appears at the bottom +of an Info window. It describes the contents of the window just above +it; this information includes the name of the file and node appearing in +that window, the number of screen lines it takes to display the node, +and the percentage of text that is above the top of the window. It can +also tell you if the indirect tags table for this Info file needs to be +updated, and whether or not the Info file was compressed when stored on +disk. + +Here is a sample mode line for a window containing an uncompressed file +named @file{dir}, showing the node @samp{Top}. + +@example +@group +-----Info: (dir)Top, 40 lines --Top------------------------------------- + ^^ ^ ^^^ ^^ + (file)Node #lines where +@end group +@end example + +When a node comes from a file which is compressed on disk, this is +indicated in the mode line with two small @samp{z}'s. In addition, if +the Info file containing the node has been split into subfiles, the name +of the subfile containing the node appears in the modeline as well: + +@example +--zz-Info: (emacs)Top, 291 lines --Top-- Subfile: emacs-1.Z------------- +@end example + +Truncation of long lines (as opposed to wrapping them to the next +display line, @pxref{Scrolling Commands, toggle-wrap}) is indicated by a +@samp{$} at the left edge of the mode line: + +@example +--$--Info: (texinfo)Top, 480 lines --Top-- Subfile: texinfo-1----------- +@end example + +When Info makes a node internally, such that there is no corresponding +info file on disk, the name of the node is surrounded by asterisks +(@samp{*}). The name itself tells you what the contents of the window +are; the sample mode line below shows an internally constructed node +showing possible completions: + +@example +-----Info: *Completions*, 7 lines --All--------------------------------- +@end example + +@node Basic Windows +@section Window Commands + +It can be convenient to view more than one node at a time. To allow +this, Info can display more than one @dfn{window}. Each window has its +own mode line (@pxref{The Mode Line}) and history of nodes viewed in that +window (@pxref{Node Commands, , @code{history-node}}). + +@table @asis +@item @kbd{C-x @kbd{o}} (@code{next-window}) +@cindex windows, selecting +@kindex C-x o +@findex next-window +Select the next window on the screen. Note that the echo area can only be +selected if it is already in use, and you have left it temporarily. +Normally, @samp{C-x o} simply moves the cursor into the next window on +the screen, or if you are already within the last window, into the first +window on the screen. Given a numeric argument, @samp{C-x o} moves over +that many windows. A negative argument causes @samp{C-x o} to select +the previous window on the screen. + +@item @kbd{M-x prev-window} +@findex prev-window +Select the previous window on the screen. This is identical to +@samp{C-x o} with a negative argument. + +@item @kbd{C-x @kbd{2}} (@code{split-window}) +@cindex windows, creating +@kindex C-x 2 +@findex split-window +Split the current window into two windows, both showing the same node. +Each window is one half the size of the original window, and the cursor +remains in the original window. The variable @code{automatic-tiling} +can cause all of the windows on the screen to be resized for you +automatically (@pxref{Variables, , automatic-tiling}). + +@item @kbd{C-x @kbd{0}} (@code{delete-window}) +@cindex windows, deleting +@kindex C-x 0 +@findex delete-window +Delete the current window from the screen. If you have made too many +windows and your screen appears cluttered, this is the way to get rid of +some of them. + +@item @kbd{C-x @kbd{1}} (@code{keep-one-window}) +@kindex C-x 1 +@findex keep-one-window +Delete all of the windows excepting the current one. + +@item @kbd{ESC @kbd{C-v}} (@code{scroll-other-window}) +@kindex ESC C-v, in Info windows +@findex scroll-other-window +Scroll the other window, in the same fashion that @samp{C-v} might +scroll the current window. Given a negative argument, scroll the +``other'' window backward. + +@item @kbd{C-x @kbd{^}} (@code{grow-window}) +@kindex C-x ^ +@findex grow-window +Grow (or shrink) the current window. Given a numeric argument, grow +the current window that many lines; with a negative numeric argument, +shrink the window instead. + +@item @kbd{C-x @kbd{t}} (@code{tile-windows}) +@cindex tiling +@kindex C-x t +@findex tile-windows +Divide the available screen space among all of the visible windows. +Each window is given an equal portion of the screen in which to display +its contents. The variable @code{automatic-tiling} can cause +@code{tile-windows} to be called when a window is created or deleted. +@xref{Variables, , @code{automatic-tiling}}. +@end table + +@node The Echo Area +@section The Echo Area +@cindex echo area + +The @dfn{echo area} is a one line window which appears at the bottom of +the screen. It is used to display informative or error messages, and to +read lines of input from you when that is necessary. Almost all of the +commands available in the echo area are identical to their Emacs +counterparts, so please refer to that documentation for greater depth of +discussion on the concepts of editing a line of text. The following +table briefly lists the commands that are available while input is being +read in the echo area: + +@table @asis +@item @kbd{C-f} (@code{echo-area-forward}) +@itemx @key{RIGHT} (an arrow key) +@itemx @kbd{M-h}, vi-like operation +@kindex C-f, in the echo area +@kindex RIGHT, in the echo area +@kindex M-h, in the echo area, vi-like operation +@findex echo-area-forward +Move forward a character. + +@item @kbd{C-b} (@code{echo-area-backward}) +@itemx @key{LEFT} (an arrow key) +@itemx @kbd{M-l}, vi-like operation +@kindex LEFT, in the echo area +@kindex C-b, in the echo area +@kindex M-l, in the echo area, vi-like operation +@findex echo-area-backward +Move backward a character. + +@item @kbd{C-a} (@code{echo-area-beg-of-line}) +@itemx @kbd{M-0}, vi-like operation +@kindex C-a, in the echo area +@kindex M-0, in the echo area, vi-like operation +@findex echo-area-beg-of-line +Move to the start of the input line. + +@item @kbd{C-e} (@code{echo-area-end-of-line}) +@itemx @kbd{M-$}, vi-like operation +@kindex C-e, in the echo area +@kindex M-$, vi-like operation +@findex echo-area-end-of-line +Move to the end of the input line. + +@item @kbd{M-f} (@code{echo-area-forward-word}) +@itemx @kbd{C-@key{RIGHT}} (DOS/Windows only) +@itemx @kbd{M-w}, vi-like operation +@kindex M-f, in the echo area +@kindex M-w, in the echo area, vi-like operation +@findex echo-area-forward-word +Move forward a word. + +@kindex C-RIGHT, in the echo area +On DOS/Windows, @kbd{C-@key{RIGHT}} moves forward by words. + +@item @kbd{M-b} (@code{echo-area-backward-word}) +@itemx @kbd{C-@key{LEFT}} (DOS/Windows only) +@kindex M-b, in the echo area +@findex echo-area-backward-word +Move backward a word. + +@kindex C-LEFT, in the echo area +On DOS/Windows, @kbd{C-@key{LEFT}} moves backward by words. + +@item @kbd{C-d} (@code{echo-area-delete}) +@itemx @kbd{M-x}, vi-like operation +@kindex C-d, in the echo area +@kindex M-x, in the echo area, vi-like operation +@findex echo-area-delete +Delete the character under the cursor. + +@item @key{DEL} (@code{echo-area-rubout}) +@kindex DEL, in the echo area +@findex echo-area-rubout +Delete the character behind the cursor. + +On some keyboards, this key is designated @key{BS}, for +@samp{Backspace}. Those keyboards will usually bind @key{DEL} in the +echo area to @code{echo-area-delete}. + +@item @kbd{C-g} (@code{echo-area-abort}) +@itemx @kbd{C-u}, vi-like operation +@kindex C-g, in the echo area +@kindex C-u, in the echo area, vi-like operation +@findex echo-area-abort +Cancel or quit the current operation. If completion is being read, this +command discards the text of the input line which does not match any +completion. If the input line is empty, it aborts the calling function. + +@item @key{RET} (@code{echo-area-newline}) +@kindex RET, in the echo area +@findex echo-area-newline +Accept (or forces completion of) the current input line. + +@item @kbd{C-q} (@code{echo-area-quoted-insert}) +@itemx @kbd{C-v}, vi-like operation +@kindex C-q, in the echo area +@kindex C-v, in the echo area, vi-like operation +@findex echo-area-quoted-insert +Insert the next character verbatim. This is how you can insert control +characters into a search string, for example, or the @samp{?} character +when Info prompts with completion. + +@item @var{printing character} (@code{echo-area-insert}) +@kindex printing characters, in the echo area +@findex echo-area-insert +Insert the character. Characters that have their 8th bit set, and not +bound to @samp{M-} commands, are also inserted verbatim; this is useful +for terminals which support Latin scripts. + +@item @kbd{M-TAB} (@code{echo-area-tab-insert}) +@itemx @kbd{Shift-@key{TAB}} (on DOS/Windows only) +@kindex M-TAB, in the echo area +@kindex Shift-TAB, in the echo area +@findex echo-area-tab-insert +Insert a TAB character. + +@kindex Shift-TAB, in the echo area +@kindex BackTab, in the echo area +On DOS/Windows only, the @kbd{Shift-@key{TAB}} key is an alias for +@kbd{M-@key{TAB}}. This key is sometimes called @samp{BackTab}. + +@item @kbd{C-t} (@code{echo-area-transpose-chars}) +@kindex C-t, in the echo area +@findex echo-area-transpose-chars +Transpose the characters at the cursor. +@end table + +The next group of commands deal with @dfn{killing}, and @dfn{yanking} +text@footnote{ +Some people are used to calling these operations @dfn{cut} and +@dfn{paste}, respectively.}. For an in-depth discussion of killing and +yanking, see @ref{Killing, , Killing and Deleting, emacs, the GNU Emacs +Manual}. + +@table @asis +@item @kbd{M-d} (@code{echo-area-kill-word}) +@itemx @kbd{M-X}, vi-like operation +@kindex M-d, in the echo area +@kindex M-X, in the echo area, vi-like operation +@findex echo-area-kill-word +Kill the word following the cursor. + +@item @kbd{M-@key{DEL}} (@code{echo-area-backward-kill-word}) +@itemx @kbd{M-@key{BS}} +@kindex M-DEL, in the echo area +@findex echo-area-backward-kill-word +Kill the word preceding the cursor. + +@kindex M-BS, in the echo area +On some keyboards, the @samp{Backspace} key is used instead of +@code{DEL}, so @code{M-@key{Backspace}} has the same effect as +@code{M-@key{DEL}}. + +@item @kbd{C-k} (@code{echo-area-kill-line}) +@kindex C-k, in the echo area +@findex echo-area-kill-line +Kill the text from the cursor to the end of the line. + +@item @kbd{C-x @key{DEL}} (@code{echo-area-backward-kill-line}) +@kindex C-x DEL, in the echo area +@findex echo-area-backward-kill-line +Kill the text from the cursor to the beginning of the line. + +@item @kbd{C-y} (@code{echo-area-yank}) +@kindex C-y, in the echo area +@findex echo-area-yank +Yank back the contents of the last kill. + +@item @kbd{M-y} (@code{echo-area-yank-pop}) +@kindex M-y, in the echo area +@findex echo-area-yank-pop +Yank back a previous kill, removing the last yanked text first. +@end table + +@cindex completion +Sometimes when reading input in the echo area, the command that needed +input will only accept one of a list of several choices. The choices +represent the @dfn{possible completions}, and you must respond with one +of them. Since there are a limited number of responses you can make, +Info allows you to abbreviate what you type, only typing as much of the +response as is necessary to uniquely identify it. In addition, you can +request Info to fill in as much of the response as is possible; this +is called @dfn{completion}. + +The following commands are available when completing in the echo area: + +@table @asis +@item @key{TAB} (@code{echo-area-complete}) +@itemx @key{SPC} +@kindex TAB, in the echo area +@kindex SPC, in the echo area +@findex echo-area-complete +Insert as much of a completion as is possible. + +@item @kbd{?} (@code{echo-area-possible-completions}) +@kindex ?, in the echo area +@findex echo-area-possible-completions +Display a window containing a list of the possible completions of what +you have typed so far. For example, if the available choices are: + +@example +@group +bar +foliate +food +forget +@end group +@end example + +@noindent +and you have typed an @samp{f}, followed by @samp{?}, Info will pop up a +window showing a node called @samp{*Completions*} which lists the +possible completions like this: + +@example +@group +3 completions: +foliate food +forget +@end group +@end example + +@noindent +i.e., all of the choices which begin with @samp{f}. Pressing @key{SPC} +or @key{TAB} would result in @samp{fo} appearing in the echo area, since +all of the choices which begin with @samp{f} continue with @samp{o}. +Now, typing @samp{l} followed by @samp{TAB} results in @samp{foliate} +appearing in the echo area, since that is the only choice which begins +with @samp{fol}. + +@item @key{ESC C-v} (@code{echo-area-scroll-completions-window}) +@kindex ESC C-v, in the echo area +@findex echo-area-scroll-completions-window +Scroll the completions window, if that is visible, or the ``other'' +window if not. +@end table + + +@node Printing Nodes +@chapter Printing Nodes +@cindex printing + +In general, we recommend that you use @TeX{} to format the document and +print sections of it, by running @code{tex} on the Texinfo source file. +However, you may wish to print out the contents of a node as a quick +reference document for later use, or if you don't have @TeX{} installed. +Info provides you with a command for doing this. + +@table @asis +@item @kbd{M-x print-node} +@findex print-node +@cindex INFO_PRINT_COMMAND, environment variable +Pipe the contents of the current node through the command in the +environment variable @code{INFO_PRINT_COMMAND}. If the variable does not +exist, the node is simply piped to @code{lpr} (on DOS/Windows, the +default is to print the node to the local printer device, @file{PRN}). + +@cindex printing nodes to the local printer +@cindex local printer device +The value of @code{INFO_PRINT_COMMAND} may begin with the @samp{>} +character, as in @samp{>/dev/printer}, in which case Info treats the +rest as the name of a file or a device. Instead of piping to a command, +Info opens the file, writes the node contents, and closes the file, +under the assumption that text written to that file will be printed by +the underlying OS. +@end table + + +@node Miscellaneous Commands +@chapter Miscellaneous Commands + +GNU Info contains several commands which self-document GNU Info: + +@table @asis +@item @kbd{M-x describe-command} +@cindex functions, describing +@cindex commands, describing +@findex describe-command +Read the name of an Info command in the echo area and then display a +brief description of what that command does. + +@item @kbd{M-x describe-key} +@cindex keys, describing +@findex describe-key +Read a key sequence in the echo area, and then display the name and +documentation of the Info command that the key sequence invokes. + +@item @kbd{M-x describe-variable} +Read the name of a variable in the echo area and then display a brief +description of what the variable affects. + +@item @kbd{M-x where-is} +@findex where-is +Read the name of an Info command in the echo area, and then display +a key sequence which can be typed in order to invoke that command. + +@item @kbd{C-h} (@code{get-help-window}) +@itemx @kbd{?} +@itemx @key{F1} (on DOS/Windows only) +@itemx h, vi-like operation +@kindex C-h +@kindex ?, in Info windows +@kindex F1 +@kindex h, vi-like operation +@findex get-help-window +Create (or Move into) the window displaying @code{*Help*}, and place +a node containing a quick reference card into it. This window displays +the most concise information about GNU Info available. + +@item @kbd{h} (@code{get-info-help-node}) +@itemx @kbd{M-h}, vi-like operation +@kindex h +@kindex M-h, vi-like operation +@findex get-info-help-node +Try hard to visit the node @code{(info)Help}. The Info file +@file{info.texi} distributed with GNU Info contains this node. Of +course, the file must first be processed with @code{makeinfo}, and then +placed into the location of your Info directory. +@end table + +Here are the commands for creating a numeric argument: + +@table @asis +@item @kbd{C-u} (@code{universal-argument}) +@cindex numeric arguments +@kindex C-u +@findex universal-argument +Start (or multiply by 4) the current numeric argument. @samp{C-u} is +a good way to give a small numeric argument to cursor movement or +scrolling commands; @samp{C-u C-v} scrolls the screen 4 lines, while +@samp{C-u C-u C-n} moves the cursor down 16 lines. @samp{C-u} followed +by digit keys sets the numeric argument to the number thus typed: +@kbd{C-u 1 2 0} sets the argument to 120. + +@item @kbd{M-1} (@code{add-digit-to-numeric-arg}) +@itemx @kbd{1}, vi-like operation +@itemx @kbd{M-2} @dots{} @kbd{M-9} +@itemx @kbd{2} @dots{} @kbd{9}, vi-like operation +@itemx @kbd{M-0} +@itemx @kbd{0}, vi-like operation +@kindex M-0 @dots{} M-9 +@kindex 0 @dots{} 9, vi-like operation +@findex add-digit-to-numeric-arg +Add the digit value of the invoking key to the current numeric +argument. Once Info is reading a numeric argument, you may just type +the digits of the argument, without the Meta prefix. For example, you +might give @samp{C-l} a numeric argument of 32 by typing: + +@example +@kbd{C-u 3 2 C-l} +@end example + +@noindent +or + +@example +@kbd{M-3 2 C-l} +@end example + +@item @kbd{M--} (@code{add-digit-to-numeric-arg} +@itemx @kbd{-} +@kindex M-- +@kindex - +@cindex negative arguments +@cindex arguments, negative +@cindex numeric arguments, negative +To make a negative argument, type @kbd{-}. Typing @kbd{-} alone makes a +negative argument with a value of -1. If you continue to type digit or +Meta-digit keys after @kbd{-}, the result is a negative number produced +by those digits. + +@kbd{-} doesn't work when you type in the echo area, because you need to +be able to insert the @samp{-} character itself; use @kbd{M--} instead, +if you need to specify negative arguments in the echo area. +@end table + +@samp{C-g} is used to abort the reading of a multi-character key +sequence, to cancel lengthy operations (such as multi-file searches) and +to cancel reading input in the echo area. + +@table @asis +@item @kbd{C-g} (@code{abort-key}) +@itemx @kbd{C-u}, vi-like operation +@cindex cancelling typeahead +@cindex cancelling the current operation +@kindex C-g, in Info windows +@kindex C-u cancels typeahead, vi-like operation +@findex abort-key +Cancel current operation. +@end table + +The @samp{q} command of Info simply quits running Info. Under +@samp{--vi-keys} (@pxref{--vi-keys}), you can also exit with @samp{:q} +or @samp{ZZ}. + +@table @asis +@item @kbd{q} (@code{quit}) +@itemx @kbd{C-x C-c} +@itemx @kbd{:q}, vi-like operation +@itemx @kbd{ZZ}, vi-like operation +@cindex quitting +@kindex q +@kindex C-x C-c +@kindex ZZ, vi-like operation +@findex quit +Exit GNU Info. +@end table + +If the operating system tells GNU Info that the screen is 60 lines tall, +and it is actually only 40 lines tall, here is a way to tell Info that +the operating system is correct. + +@table @asis +@item @kbd{M-x set-screen-height} +@findex set-screen-height +@cindex screen, changing the height of +Read a height value in the echo area and set the height of the +displayed screen to that value. +@end table + +On MS-DOS/MS-Windows, this command actually tries to change the +dimensions of the visible screen to the value you type in the echo +area. + +Finally, Info provides a convenient way to display footnotes which might +be associated with the current node that you are viewing: + +@table @asis +@item @kbd{ESC C-f} (@code{show-footnotes}) +@kindex ESC C-f +@findex show-footnotes +@cindex footnotes, displaying +Show the footnotes (if any) associated with the current node in another +window. You can have Info automatically display the footnotes +associated with a node when the node is selected by setting the variable +@code{automatic-footnotes}. @xref{Variables, , @code{automatic-footnotes}}. +@end table + + +@node Variables +@chapter Manipulating Variables + +GNU Info contains several @dfn{variables} whose values are looked at by +various Info commands. You can change the values of these variables, +and thus change the behavior of Info to more closely match your +environment and Info file reading manner. + +There are two ways to set the value of a variable: interactively, using +the @code{set-variable} command described below, or in the @code{#var} +section of the @code{.infokey} file. @xref{Custom Key Bindings}. + +@table @asis +@item @kbd{M-x set-variable} +@cindex variables, setting +@findex set-variable +Read the name of a variable, and the value for it, in the echo area and +then set the variable to that value. Completion is available when +reading the variable name (@pxref{The Echo Area, completion}); often, +completion is available when reading the value to give to the variable, +but that depends on the variable itself. If a variable does @emph{not} +supply multiple choices to complete over, it expects a numeric value. + +@item @kbd{M-x describe-variable} +@cindex variables, describing +@findex describe-variable +Read the name of a variable in the echo area and then display a brief +description of what the variable affects. +@end table + +Here is a list of the variables that you can set in Info. + +@table @code +@item automatic-footnotes +@vindex automatic-footnotes +When set to @code{On}, footnotes appear and disappear automatically; +else, they appear at the bottom of the node text. This variable is +@code{Off} by default. When a node is selected, a window containing +the footnotes which appear in that node is created, and the footnotes +are displayed within the new window. The window that Info creates to +contain the footnotes is called @samp{*Footnotes*}. If a node is +selected which contains no footnotes, and a @samp{*Footnotes*} window +is on the screen, the @samp{*Footnotes*} window is deleted. Footnote +windows created in this fashion are not automatically tiled so that +they can use as little of the display as is possible. + +@item automatic-tiling +@vindex automatic-tiling +When set to @code{On}, creating or deleting a window resizes other +windows. This variable is @code{Off} by default. Normally, typing +@samp{C-x 2} divides the current window into two equal parts. When +@code{automatic-tiling} is set to @code{On}, all of the windows are +resized automatically, keeping an equal number of lines visible in each +window. There are exceptions to the automatic tiling; specifically, the +windows @samp{*Completions*} and @samp{*Footnotes*} are @emph{not} +resized through automatic tiling; they remain their original size. + +@anchor{cursor-movement-scrolls} +@item cursor-movement-scrolls +Normally, cursor movement commands (@pxref{Cursor Commands}) stop when +top or bottom of a node is reached. When this variable is set to +@code{On}, cursor movement commands act as scrolling ones and their +behavior is controlled by the @code{scroll-behavior} variable (see below). + +@item errors-ring-bell +@vindex errors-ring-bell +When set to @code{On}, errors cause the bell to ring. The default +setting of this variable is @code{On}. + +@item gc-compressed-files +@vindex gc-compressed-files +When set to @code{On}, Info garbage collects files which had to be +uncompressed. The default value of this variable is @code{Off}. +Whenever a node is visited in Info, the Info file containing that node +is read into core, and Info reads information about the tags and nodes +contained in that file. Once the tags information is read by Info, it +is never forgotten. However, the actual text of the nodes does not need +to remain in core unless a particular Info window needs it. For +non-compressed files, the text of the nodes does not remain in core when +it is no longer in use. But de-compressing a file can be a time +consuming operation, and so Info tries hard not to do it twice. +@code{gc-compressed-files} tells Info it is okay to garbage collect the +text of the nodes of a file which was compressed on disk. + +@item ISO-Latin +@cindex ISO Latin characters +@vindex ISO-Latin +When set to @code{On}, Info accepts and displays ISO Latin characters. +By default, Info assumes an ASCII character set. @code{ISO-Latin} tells +Info that it is running in an environment where the European standard +character set is in use, and allows you to input such characters to +Info, as well as display them. + +@anchor{scroll-behavior} +@item scroll-behavior +@itemx scroll-behaviour +@vindex scroll-behavior +@vindex scroll-behaviour +Control what happens when forward scrolling is requested at the end of +a node, or when backward scrolling is requested at the beginning of a +node. The default value for this variable is @code{Continuous}. +There are three possible values for this variable: + +@table @code +@item Continuous +Try to get the first item in this node's menu, or failing that, the +@samp{Next} node, or failing that, the @samp{Next} of the @samp{Up}. +This behavior is identical to using the @samp{]} +(@code{global-next-node}) and @samp{[} (@code{global-prev-node}) +commands. + +@item scroll-last-node +@vindex scroll-last-node +Control what happens when a scrolling command is issued at the end of +the last node. Possible values are: + +@table @code +@item Stop +Do not scroll. Display the @samp{No more nodes within this document.} +message. This is the default. + +@item Scroll +Scroll as usual. Since the last node is usually an index, this means +that the very first node from the menu will be selected. + +@item Top +Go to the top node of this document. +@end table + +This variable is in effect only if @code{scroll-behaviour} is set to +@code{Continuous}. + +Notice that the default behavior has changed in version 4.12. Previous +versions behaved as if @code{scroll-last-node=Scroll} was set. This +behavior was counter-intuitive, therefore since version 4.12 the +default is to stop at the last node. + +@item Next Only +Only try to get the @samp{Next} node. + +@item Page Only +Simply give up, changing nothing. If @code{scroll-behavior} is +@code{Page Only}, no scrolling command can change the node that is being +viewed. +@end table + +This variable normally affects only scrolling commands. +@xref{cursor-movement-scrolls}, for information on how to widen its +scope. + +The two names, @code{scroll-behavior} and @code{scroll-behaviour}, are +a historical accident. They are merely synonyms. + +@item scroll-step +@vindex scroll-step +The number of lines to scroll when the cursor moves out of the window. +Scrolling happens automatically if the cursor has moved out of the +visible portion of the node text when it is time to display. Usually +the scrolling is done so as to put the cursor on the center line of the +current window. However, if the variable @code{scroll-step} has a +nonzero value, Info attempts to scroll the node text by that many lines; +if that is enough to bring the cursor back into the window, that is what +is done. The default value of this variable is 0, thus placing the +cursor (and the text it is attached to) in the center of the window. +Setting this variable to 1 causes a kind of ``smooth scrolling'' which +some people prefer. + +@item show-index-match +@vindex show-index-match +When set to @code{On}, the portion of the matched search string is +highlighted in the message which explains where the matched search +string was found. The default value of this variable is @code{On}. +When Info displays the location where an index match was found, +(@pxref{Searching Commands, , @code{next-index-match}}), the portion of the +string that you had typed is highlighted by displaying it in the inverse +case from its surrounding characters. + +@item visible-bell +@vindex visible-bell +When set to @code{On}, GNU Info attempts to flash the screen instead of +ringing the bell. This variable is @code{Off} by default. Of course, +Info can only flash the screen if the terminal allows it; in the case +that the terminal does not allow it, the setting of this variable has no +effect. However, you can make Info perform quietly by setting the +@code{errors-ring-bell} variable to @code{Off}. + +@end table + + +@node Custom Key Bindings +@chapter Customizing Key Bindings and Variables + +@cindex default key bindings, overriding +@cindex overriding default key bindings +@cindex customizing key bindings +@cindex key bindings, customizing +@cindex infokey +@cindex .info +@cindex .infokey +@cindex _info file (MS-DOS) + +GNU Info provides a way to define arbitrary key-to-command bindings +and variable settings, overriding the defaults described in this +document. (The @option{--vi-keys} option rebinds many keys at once; +@pxref{--vi-keys}.) + +On startup, GNU Info looks for a configuration file in the invoker's +HOME directory called @file{.info}@footnote{Due to the limitations of +DOS filesystems, the MS-DOS version of Info looks for a file +@file{_info} instead. If the @env{HOME} variable is not defined, Info +additionally looks in the current directory.}. If it is present, and +appears to contain Info configuration data, and was created with the +current version of the @code{infokey} command, then Info adopts the +key bindings and variable settings contained therein. + +The @file{.info} file contains compact, non-textual data for reasons of +efficiency and because its design was lifted wholesale from the GNU Less +program, which also does it that way. It must be created by compiling a +textual source file using the @code{infokey} command. + +@menu +* Invoking infokey:: +* infokey source format:: +@end menu + + +@node Invoking infokey +@section Invoking @command{infokey} + +@cindex invoking infokey +@cindex infokey, invoking +@cindex _infokey file (MS-DOS) + +@command{infokey} compiles a source file +(@file{$HOME/.infokey}@footnote{This file is named @file{_infokey} in +the MS-DOS version, and is looked for in the current directory if +@env{HOME} is undefined.} by default) containing Info customizations +into a binary format (@file{$HOME/.info} by default). GNU Info reads +the binary file at startup to override the default key bindings and +variable definitions. Synopsis: + +@example +infokey [@var{option}@dots{}] [@var{input-file}] +@end example + +Besides the standard @option{--help} and @option{--version}, the only +option is @option{--output @var{file}}. This tells @command{infokey} to +write the binary data to @var{file} instead of @file{$HOME/.info}. + + +@node infokey source format +@section @command{infokey} source format + +@cindex infokey source format +@cindex .infokey source format +@cindex format of .infokey source + +The format of the source file read by @command{infokey} is most easily +illustrated by example. For instance, here is a sample @file{.infokey} +source file suitable for aficionados of @command{vi} or @command{less}: + +@example +#info +j next-line +k prev-line +l forward-char +h backward-char +\kd next-line +\ku prev-line +\kr forward-char +\kl backward-char +\ scroll-forward +\kD scroll-forward-page-only +b scroll-backward +\kU scroll-backward-page-only +g beginning-of-node +\kh beginning-of-node +G end-of-node +\ke end-of-node +\t select-reference-this-line +- history-node +n next-node +p prev-node +u up-node +t top-node +d dir-node +#var +scroll-step=1 +@end example + +The source file consists of one or more @dfn{sections}. +Each section starts with a line that identifies the type of section. +Possible sections are: + +@table @code +@item #info +Key bindings for Info windows. +The start of this section is indicated by a line containing just +@code{#info} by itself. If this is the first section in the source +file, the @code{#info} line can be omitted. The rest of this section +consists of lines of the form: + +@example +@var{string} whitespace @var{action} [ whitespace [ # comment ] ] newline +@end example + +Whitespace is any sequence of one or more spaces and/or tabs. Comment +is any sequence of any characters, excluding newline. @var{string} is +the key sequence which invokes the action. @var{action} is the name of +an Info command. The characters in @var{string} are interpreted +literally or prefixed by a caret (@code{^}) to indicate a control +character. A backslash followed by certain characters specifies input +keystrokes as follows: + +@table @code +@item \b +Backspace +@item \e +Escape (ESC) +@item \n +Newline +@item \r +Return +@item \t +Tab +@item \ku +Up arrow +@item \kd +Down arrow +@item \kl +Left arrow +@item \kr +Right arrow +@item \kU +Page Up +@item \kD +Page Down +@item \kh +HOME +@item \ke +END +@item \kx +Delete (DEL) +@item \m@var{x} +Meta-@var{x} where @var{x} is any character as described above. +@end table + +Backslash followed by any other character indicates that character is to +be taken literally. Characters which must be preceded by a backslash +include caret, space, tab, and backslash itself. + +@item #echo-area +Key bindings for the echo area. +The start of this section is indicated by a line containing just +@code{#echo-area} by itself. The rest of this section has a syntax +identical to that for the key definitions for the Info area, described +above. + +@item #var +Variable initializations. +The start of this section is indicated by a line containing just +@code{#var} by itself. Following this line is a list of variable +assignments, one per line. Each line consists of a variable name +(@xref{Variables},) followed by @code{=} followed by a value. +There may be no white space between the variable name and the @code{=}, +and all characters following the @code{=}, including white space, +are included in the value. +@end table + +Blank lines and lines starting with @code{#} are ignored, except for +the special section header lines. + +Key bindings defined in the @file{.info} file take precedence over GNU +Info's default key bindings, whether or not @samp{--vi-keys} is used. A +default key binding may be disabled by overriding it in the @file{.info} +file with the action @code{invalid}. In addition, @emph{all} default +key bindings can be disabled by adding this line @emph{anywhere} in the +relevant section: + +@example +#stop +@end example + +This will cause GNU Info to ignore all the default key commands for that +section. + +Beware: @code{#stop} can be dangerous. Since it disables all default +key bindings, you must supply enough new key bindings to enable all +necessary actions. Failure to bind any key to the @code{quit} command, +for example, can lead to frustration. + +The order in which key bindings are defined in the @file{.info} file is +not important, except that the command summary produced by the +@code{get-help-window} command only displays the @emph{first} key that +is bound to each command. + + +@c the following is incomplete +@ignore +@c node Info for Sys Admins +@c chapter Info for System Administrators + +This text describes some common ways of setting up an Info hierarchy +from scratch, and details the various options that are available when +installing Info. This text is designed for the person who is installing +GNU Info on the system; although users may find the information present +in this section interesting, none of it is vital to understanding how to +use GNU Info. + +@menu +* Setting the INFOPATH:: Where are my Info files kept? +* Editing the DIR node:: What goes in `DIR', and why? +* Storing Info files:: Alternate formats allow flexibility in setups. +* Using `localdir':: Building DIR on the fly. +* Example setups:: Some common ways to organize Info files. +@end menu + +@c node Setting the INFOPATH +@c section Setting the INFOPATH + +Where are my Info files kept? + +@c node Editing the DIR node +@c section Editing the DIR node + +What goes in `DIR', and why? + +@c node Storing Info files +@c section Storing Info files + +Alternate formats allow flexibility in setups. + +@c node Using `localdir' +@c section Using `localdir' + +Building DIR on the fly. + +@c node Example setups +@c section Example setups + +Some common ways to organize Info files. +@end ignore + + +@node Index +@appendix Index + +@printindex cp + +@bye |