aboutsummaryrefslogtreecommitdiffstats
path: root/man
diff options
context:
space:
mode:
authorDave Love1999-09-30 14:13:07 +0000
committerDave Love1999-09-30 14:13:07 +0000
commit2690179258ed0d92646261447bbd4fcd59ef31aa (patch)
tree8df39f73c7accac318317f85a59e3c3f31329375 /man
parent1791e2e537d1d3f6b865941030a4809ca9e84ccf (diff)
downloademacs-2690179258ed0d92646261447bbd4fcd59ef31aa.tar.gz
emacs-2690179258ed0d92646261447bbd4fcd59ef31aa.zip
#
Diffstat (limited to 'man')
-rw-r--r--man/.gitignore15
-rw-r--r--man/ChangeLog4
-rw-r--r--man/info-stnd.texi1268
-rw-r--r--man/info.texi969
4 files changed, 2251 insertions, 5 deletions
diff --git a/man/.gitignore b/man/.gitignore
index 56272ef85f5..c39e88496c5 100644
--- a/man/.gitignore
+++ b/man/.gitignore
@@ -1,9 +1,14 @@
1*.aux 1*.aux
2*.fns? 2*.fn
3*.cps? 3*.fns
4*.kys? 4*.cps
5*.cp
6*.kys
7*.ky
5*.toc 8*.toc
6*.pgs? 9*.pgs
10*.pg
7*.log 11*.log
8*.vrs? 12*.vrs
13*.vr
9*.dvi 14*.dvi
diff --git a/man/ChangeLog b/man/ChangeLog
index 490c6e06cc5..8d5680f38ee 100644
--- a/man/ChangeLog
+++ b/man/ChangeLog
@@ -1,3 +1,7 @@
11999-09-01 Dave Love <fx@gnu.org>
2
3 * Makefile.in: Add faq.
4
11999-07-12 Richard Stallman <rms@gnu.org> 51999-07-12 Richard Stallman <rms@gnu.org>
2 6
3 * Version 20.4 released. 7 * Version 20.4 released.
diff --git a/man/info-stnd.texi b/man/info-stnd.texi
new file mode 100644
index 00000000000..124af301fa9
--- /dev/null
+++ b/man/info-stnd.texi
@@ -0,0 +1,1268 @@
1@c This file is meant to be included in any arbitrary piece of
2@c documentation that wishes to describe the info program.
3@c
4@c This file documents the use of the standalone GNU Info program,
5@c versions 2.7 and later. It was authored by Brian Fox (bfox@gnu.org).
6
7@ifclear InfoProgVer
8@set InfoProgVer 2.10
9@end ifclear
10@synindex vr cp
11@synindex fn cp
12@synindex ky cp
13
14@heading What is Info?
15
16This text documents the use of the GNU Info program, version
17@value{InfoProgVer}.
18
19@dfn{Info} is a program which is used to view info files on an ASCII
20terminal. @dfn{info files} are the result of processing texinfo files
21with the program @code{makeinfo} or with the Emacs command @code{M-x
22texinfo-format-buffer}. Finally, @dfn{texinfo} is a documentation
23language which allows a printed manual and online documentation (an info
24file) to be produced from a single source file.
25
26@menu
27* Options:: Options you can pass on the command line.
28* Cursor Commands:: Commands which move the cursor within a node.
29* Scrolling Commands:: Commands for moving the node around in a window.
30* Node Commands:: Commands for selecting a new node.
31* Searching Commands:: Commands for searching an info file.
32* Xref Commands:: Commands for selecting cross references.
33* Window Commands:: Commands which manipulate multiple windows.
34* Printing Nodes:: How to print out the contents of a node.
35* Miscellaneous Commands:: A few commands that defy categories.
36* Variables:: How to change the default behaviour of Info.
37@ifset NOTSET
38* Info for Sys Admins:: How to setup Info. Using special options.
39@end ifset
40@ifset STANDALONE
41* GNU Info Global Index:: Global index containing keystrokes, command names,
42 variable names, and general concepts.
43@end ifset
44@end menu
45
46@node Options
47@chapter Command Line Options
48@cindex command line options
49@cindex arguments, command line
50
51GNU Info accepts several options to control the initial node being
52viewed, and to specify which directories to search for info files. Here
53is a template showing an invocation of GNU Info from the shell:
54
55@example
56info [--@var{option-name} @var{option-value}] @var{menu-item}@dots{}
57@end example
58
59The following @var{option-names} are available when invoking Info from
60the shell:
61
62@table @code
63@cindex directory path
64@item --directory @var{directory-path}
65@itemx -d @var{directory-path}
66Adds @var{directory-path} to the list of directory paths searched when
67Info needs to find a file. You may issue @code{--directory} multiple
68times; once for each directory which contains info files.
69Alternatively, you may specify a value for the environment variable
70@code{INFOPATH}; if @code{--directory} is not given, the value of
71@code{INFOPATH} is used. The value of @code{INFOPATH} is a colon
72separated list of directory names. If you do not supply
73@code{INFOPATH} or @code{--directory-path} a default path is used.
74
75@item --file @var{filename}
76@itemx -f @var{filename}
77@cindex info file, selecting
78Specifies a particular info file to visit. Instead of visiting the file
79@code{dir}, Info will start with @code{(@var{filename})Top} as the first
80file and node.
81
82@item --node @var{nodename}
83@itemx -n @var{nodename}
84@cindex node, selecting
85Specifies a particular node to visit in the initial file loaded. This
86is especially useful in conjunction with @code{--file}@footnote{Of
87course, you can specify both the file and node in a @code{--node}
88command; but don't forget to escape the open and close parentheses from
89the shell as in: @code{info --node '(emacs)Buffers'}}. You may specify
90@code{--node} multiple times; for an interactive Info, each
91@var{nodename} is visited in its own window, for a non-interactive Info
92(such as when @code{--output} is given) each @var{nodename} is processed
93sequentially.
94
95@item --output @var{filename}
96@itemx -o @var{filename}
97@cindex file, outputting to
98@cindex outputting to a file
99Specify @var{filename} as the name of a file to output to. Each node
100that Info visits will be output to @var{filename} instead of
101interactively viewed. A value of @code{-} for @var{filename} specifies
102the standard output.
103
104@item --subnodes
105@cindex @code{--subnodes}, command line option
106This option only has meaning when given in conjunction with
107@code{--output}. It means to recursively output the nodes appearing in
108the menus of each node being output. Menu items which resolve to
109external info files are not output, and neither are menu items which are
110members of an index. Each node is only output once.
111
112@item --help
113@itemx -h
114Produces a relatively brief description of the available Info options.
115
116@item --version
117@cindex version information
118Prints the version information of Info and exits.
119
120@item @var{menu-item}
121@cindex menu, following
122Remaining arguments to Info are treated as the names of menu items. The
123first argument would be a menu item in the initial node visited, while
124the second argument would be a menu item in the first argument's node.
125You can easily move to the node of your choice by specifying the menu
126names which describe the path to that node. For example,
127
128@example
129info emacs buffers
130@end example
131
132first selects the menu item @samp{Emacs} in the node @samp{(dir)Top},
133and then selects the menu item @samp{Buffers} in the node
134@samp{(emacs)Top}.
135
136@end table
137
138@node Cursor Commands
139@chapter Moving the Cursor
140@cindex cursor, moving
141Many people find that reading screens of text page by page is made
142easier when one is able to indicate particular pieces of text with some
143kind of pointing device. Since this is the case, GNU Info (both the
144Emacs and standalone versions) have several commands which allow you to
145move the cursor about the screen. The notation used in this manual to
146describe keystrokes is identical to the notation used within the Emacs
147manual, and the GNU Readline manual. @xref{Characters, , Character
148Conventions, emacs, the GNU Emacs Manual}, if you are unfamiliar with the
149notation.
150
151The following table lists the basic cursor movement commands in Info.
152Each entry consists of the key sequence you should type to execute the
153cursor movement, the @code{M-x}@footnote{@code{M-x} is also a command; it
154invokes @code{execute-extended-command}. @xref{M-x, , Executing an
155extended command, emacs, the GNU Emacs Manual}, for more detailed
156information.} command name (displayed in parentheses), and a short
157description of what the command does. All of the cursor motion commands
158can take an @dfn{numeric} argument (@pxref{Miscellaneous Commands,
159@code{universal-argument}}), to find out how to supply them. With a
160numeric argument, the motion commands are simply executed that
161many times; for example, a numeric argument of 4 given to
162@code{next-line} causes the cursor to move down 4 lines. With a
163negative numeric argument, the motion is reversed; an argument of -4
164given to the @code{next-line} command would cause the cursor to move
165@emph{up} 4 lines.
166
167@table @asis
168@item @code{C-n} (@code{next-line})
169@kindex C-n
170@findex next-line
171Moves the cursor down to the next line.
172
173@item @code{C-p} (@code{prev-line})
174@kindex C-p
175@findex prev-line
176Move the cursor up to the previous line.
177
178@item @code{C-a} (@code{beginning-of-line})
179@kindex C-a, in Info windows
180@findex beginning-of-line
181Move the cursor to the start of the current line.
182
183@item @code{C-e} (@code{end-of-line})
184@kindex C-e, in Info windows
185@findex end-of-line
186Moves the cursor to the end of the current line.
187
188@item @code{C-f} (@code{forward-char})
189@kindex C-f, in Info windows
190@findex forward-char
191Move the cursor forward a character.
192
193@item @code{C-b} (@code{backward-char})
194@kindex C-b, in Info windows
195@findex backward-char
196Move the cursor backward a character.
197
198@item @code{M-f} (@code{forward-word})
199@kindex M-f, in Info windows
200@findex forward-word
201Moves the cursor forward a word.
202
203@item @code{M-b} (@code{backward-word})
204@kindex M-b, in Info winows
205@findex backward-word
206Moves the cursor backward a word.
207
208@item @code{M-<} (@code{beginning-of-node})
209@itemx @code{b}
210@kindex b, in Info winows
211@kindex M-<
212@findex beginning-of-node
213Moves the cursor to the start of the current node.
214
215@item @code{M->} (@code{end-of-node})
216@kindex M->
217@findex end-of-node
218Moves the cursor to the end of the current node.
219
220@item @code{M-r} (@code{move-to-window-line})
221@kindex M-r
222@findex move-to-window-line
223Moves the cursor to a specific line of the window. Without a numeric
224argument, @code{M-r} moves the cursor to the start of the line in the
225center of the window. With a numeric argument of @var{n}, @code{M-r}
226moves the cursor to the start of the @var{n}th line in the window.
227@end table
228
229@node Scrolling Commands
230@chapter Moving Text Within a Window
231@cindex scrolling
232
233Sometimes you are looking at a screenful of text, and only part of the
234current paragraph you are reading is visible on the screen. The
235commands detailed in this section are used to shift which part of the
236current node is visible on the screen.
237
238@table @asis
239@item @code{SPC} (@code{scroll-forward})
240@itemx @code{C-v}
241@kindex SPC, in Info windows
242@kindex C-v
243@findex scroll-forward
244Shift the text in this window up. That is, show more of the node which
245is currently below the bottom of the window. With a numeric argument,
246show that many more lines at the bottom of the window; a numeric
247argument of 4 would shift all of the text in the window up 4 lines
248(discarding the top 4 lines), and show you four new lines at the bottom
249of the window. Without a numeric argument, @key{SPC} takes the bottom
250two lines of the window and places them at the top of the window,
251redisplaying almost a completely new screenful of lines.
252
253@item @code{DEL} (@code{scroll-backward})
254@itemx @code{M-v}
255@kindex DEL, in Info windows
256@kindex M-v
257@findex scroll-backward
258Shift the text in this window down. The inverse of
259@code{scroll-forward}.
260
261@end table
262
263@cindex scrolling through node structure
264The @code{scroll-forward} and @code{scroll-backward} commands can also
265move forward and backward through the node structure of the file. If
266you press @key{SPC} while viewing the end of a node, or @key{DEL} while
267viewing the beginning of a node, what happens is controlled by the
268variable @code{scroll-behaviour}. @xref{Variables,
269@code{scroll-behaviour}}, for more information.
270
271@table @asis
272@item @code{C-l} (@code{redraw-display})
273@kindex C-l
274@findex redraw-display
275Redraw the display from scratch, or shift the line containing the cursor
276to a specified location. With no numeric argument, @samp{C-l} clears
277the screen, and then redraws its entire contents. Given a numeric
278argument of @var{n}, the line containing the cursor is shifted so that
279it is on the @var{n}th line of the window.
280
281@item @code{C-x w} (@code{toggle-wrap})
282@kindex C-w
283@findex toggle-wrap
284Toggles the state of line wrapping in the current window. Normally,
285lines which are longer than the screen width @dfn{wrap}, i.e., they are
286continued on the next line. Lines which wrap have a @samp{\} appearing
287in the rightmost column of the screen. You can cause such lines to be
288terminated at the rightmost column by changing the state of line
289wrapping in the window with @code{C-x w}. When a line which needs more
290space than one screen width to display is displayed, a @samp{$} appears
291in the rightmost column of the screen, and the remainder of the line is
292invisible.
293@end table
294
295@node Node Commands
296@chapter Selecting a New Node
297@cindex nodes, selection of
298
299This section details the numerous Info commands which select a new node
300to view in the current window.
301
302The most basic node commands are @samp{n}, @samp{p}, @samp{u}, and
303@samp{l}.
304
305When you are viewing a node, the top line of the node contains some Info
306@dfn{pointers} which describe where the next, previous, and up nodes
307are. Info uses this line to move about the node structure of the file
308when you use the following commands:
309
310@table @asis
311@item @code{n} (@code{next-node})
312@kindex n
313@findex next-node
314Selects the `Next' node.
315
316@item @code{p} (@code{prev-node})
317@kindex p
318@findex prev-node
319Selects the `Prev' node.
320
321@item @code{u} (@code{up-node})
322@kindex u
323@findex up-node
324Selects the `Up' node.
325@end table
326
327You can easily select a node that you have already viewed in this window
328by using the @samp{l} command -- this name stands for "last", and
329actually moves through the list of already visited nodes for this
330window. @samp{l} with a negative numeric argument moves forward through
331the history of nodes for this window, so you can quickly step between
332two adjacent (in viewing history) nodes.
333
334@table @asis
335@item @code{l} (@code{history-node})
336@kindex l
337@findex history-node
338Selects the most recently selected node in this window.
339@end table
340
341Two additional commands make it easy to select the most commonly
342selected nodes; they are @samp{t} and @samp{d}.
343
344@table @asis
345@item @code{t} (@code{top-node})
346@kindex t
347@findex top-node
348Selects the node @samp{Top} in the current info file.
349
350@item @code{d} (@code{dir-node})
351@kindex d
352@findex dir-node
353Selects the directory node (i.e., the node @samp{(dir)}).
354@end table
355
356Here are some other commands which immediately result in the selection
357of a different node in the current window:
358
359@table @asis
360@item @code{<} (@code{first-node})
361@kindex <
362@findex first-node
363Selects the first node which appears in this file. This node is most
364often @samp{Top}, but it doesn't have to be.
365
366@item @code{>} (@code{last-node})
367@kindex >
368@findex last-node
369Selects the last node which appears in this file.
370
371@item @code{]} (@code{global-next-node})
372@kindex ]
373@findex global-next-node
374Moves forward or down through node structure. If the node that you are
375currently viewing has a @samp{Next} pointer, that node is selected.
376Otherwise, if this node has a menu, the first menu item is selected. If
377there is no @samp{Next} and no menu, the same process is tried with the
378@samp{Up} node of this node.
379
380@item @code{[} (@code{global-prev-node})
381@kindex [
382@findex global-prev-node
383Moves backward or up through node structure. If the node that you are
384currently viewing has a @samp{Prev} pointer, that node is selected.
385Otherwise, if the node has an @samp{Up} pointer, that node is selected,
386and if it has a menu, the last item in the menu is selected.
387@end table
388
389You can get the same behaviour as @code{global-next-node} and
390@code{global-prev-node} while simply scrolling through the file with
391@key{SPC} and @key{DEL}; @xref{Variables, @code{scroll-behaviour}}, for
392more information.
393
394@table @asis
395@item @code{g} (@code{goto-node})
396@kindex g
397@findex goto-node
398Reads the name of a node and selects it. No completion is done while
399reading the node name, since the desired node may reside in a separate
400file. The node must be typed exactly as it appears in the info file. A
401file name may be included as with any node specification, for example
402
403@example
404@code{g(emacs)Buffers}
405@end example
406
407finds the node @samp{Buffers} in the info file @file{emacs}.
408
409@item @code{C-x k} (@code{kill-node})
410@kindex C-x k
411@findex kill-node
412Kills a node. The node name is prompted for in the echo area, with a
413default of the current node. @dfn{Killing} a node means that Info tries
414hard to forget about it, removing it from the list of history nodes kept
415for the window where that node is found. Another node is selected in
416the window which contained the killed node.
417
418@item @code{C-x C-f} (@code{view-file})
419@kindex C-x C-f
420@findex view-file
421Reads the name of a file and selects the entire file. The command
422@example
423@code{C-x C-f @var{filename}}
424@end example
425is equivalent to typing
426@example
427@code{g(@var{filename})*}
428@end example
429
430@item @code{C-x C-b} (@code{list-visited-nodes})
431@kindex C-x C-b
432@findex list-visited-nodes
433Makes a window containing a menu of all of the currently visited nodes.
434This window becomes the selected window, and you may use the standard
435Info commands within it.
436
437@item @code{C-x b} (@code{select-visited-node})
438@kindex C-x b
439@findex select-visited-node
440Selects a node which has been previously visited in a visible window.
441This is similar to @samp{C-x C-b} followed by @samp{m}, but no window is
442created.
443@end table
444
445@node Searching Commands
446@chapter Searching an Info File
447@cindex searching
448
449GNU Info allows you to search for a sequence of characters throughout an
450entire info file, search through the indices of an info file, or find
451areas within an info file which discuss a particular topic.
452
453@table @asis
454@item @code{s} (@code{search})
455@kindex s
456@findex search
457Reads a string in the echo area and searches for it.
458
459@item @code{C-s} (@code{isearch-forward})
460@kindex C-s
461@findex isearch-forward
462Interactively searches forward through the info file for a string as you
463type it.
464
465@item @code{C-r} (@code{isearch-backward})
466@kindex C-r
467@findex isearch-backward
468Interactively searches backward through the info file for a string as
469you type it.
470
471@item @code{i} (@code{index-search})
472@kindex i
473@findex index-search
474Looks up a string in the indices for this info file, and selects a node
475where the found index entry points to.
476
477@item @code{,} (@code{next-index-match})
478@kindex ,
479@findex next-index-match
480Moves to the node containing the next matching index item from the last
481@samp{i} command.
482@end table
483
484The most basic searching command is @samp{s} (@code{search}). The
485@samp{s} command prompts you for a string in the echo area, and then
486searches the remainder of the info file for an occurrence of that string.
487If the string is found, the node containing it is selected, and the
488cursor is left positioned at the start of the found string. Subsequent
489@samp{s} commands show you the default search string within @samp{[} and
490@samp{]}; pressing @key{RET} instead of typing a new string will use the
491default search string.
492
493@dfn{Incremental searching} is similar to basic searching, but the
494string is looked up while you are typing it, instead of waiting until
495the entire search string has been specified.
496
497@node Xref Commands
498@chapter Selecting Cross References
499
500We have already discussed the @samp{Next}, @samp{Prev}, and @samp{Up}
501pointers which appear at the top of a node. In addition to these
502pointers, a node may contain other pointers which refer you to a
503different node, perhaps in another info file. Such pointers are called
504@dfn{cross references}, or @dfn{xrefs} for short.
505
506@menu
507* Parts of an Xref:: What a cross reference is made of.
508* Selecting Xrefs:: Commands for selecting menu or note items.
509@end menu
510
511@node Parts of an Xref
512@section Parts of an Xref
513
514Cross references have two major parts: the first part is called the
515@dfn{label}; it is the name that you can use to refer to the cross
516reference, and the second is the @dfn{target}; it is the full name of
517the node that the cross reference points to.
518
519The target is separated from the label by a colon @samp{:}; first the
520label appears, and then the target. For example, in the sample menu
521cross reference below, the single colon separates the label from the
522target.
523
524@example
525* Foo Label: Foo Target. More information about Foo.
526@end example
527
528Note the @samp{.} which ends the name of the target. The @samp{.} is
529not part of the target; it serves only to let Info know where the target
530name ends.
531
532A shorthand way of specifying references allows two adjacent colons to
533stand for a target name which is the same as the label name:
534
535@example
536* Foo Commands:: Commands pertaining to Foo.
537@end example
538
539In the above example, the name of the target is the same as the name of
540the label, in this case @code{Foo Commands}.
541
542You will normally see two types of cross references while viewing nodes:
543@dfn{menu} references, and @dfn{note} references. Menu references
544appear within a node's menu; they begin with a @samp{*} at the beginning
545of a line, and continue with a label, a target, and a comment which
546describes what the contents of the node pointed to contains.
547
548Note references appear within the body of the node text; they begin with
549@code{*Note}, and continue with a label and a target.
550
551Like @samp{Next}, @samp{Prev} and @samp{Up} pointers, cross references
552can point to any valid node. They are used to refer you to a place
553where more detailed information can be found on a particular subject.
554Here is a cross reference which points to a node within the Texinfo
555documentation: @xref{xref, , Writing an Xref, texinfo, the Texinfo
556Manual}, for more information on creating your own texinfo cross
557references.
558
559@node Selecting Xrefs
560@section Selecting Xrefs
561
562The following table lists the Info commands which operate on menu items.
563
564@table @asis
565@item @code{1} (@code{menu-digit})
566@itemx @code{2} @dots{} @code{9}
567@cindex 1 @dots{} 9, in Info windows
568@kindex 1 @dots{} 9, in Info windows
569@findex menu-digit
570Within an Info window, pressing a single digit, (such as @samp{1}),
571selects that menu item, and places its node in the current window.
572For convenience, there is one exception; pressing @samp{0} selects the
573@emph{last} item in the node's menu.
574
575@item @code{0} (@code{last-menu-item})
576@kindex 0, in Info windows
577@findex last-menu-item
578Select the last item in the current node's menu.
579
580@item @code{m} (@code{menu-item})
581@kindex m
582@findex menu-item
583Reads the name of a menu item in the echo area and selects its node.
584Completion is available while reading the menu label.
585
586@item @code{M-x find-menu}
587@findex find-menu
588Moves the cursor to the start of this node's menu.
589@end table
590
591This table lists the Info commands which operate on note cross references.
592
593@table @asis
594@item @code{f} (@code{xref-item})
595@itemx @code{r}
596@kindex f
597@kindex r
598@findex xref-item
599Reads the name of a note cross reference in the echo area and selects
600its node. Completion is available while reading the cross reference
601label.
602@end table
603
604Finally, the next few commands operate on menu or note references alike:
605
606@table @asis
607@item @code{TAB} (@code{move-to-next-xref})
608@kindex TAB, in Info windows
609@findex move-to-next-xref
610Moves the cursor to the start of the next nearest menu item or note
611reference in this node. You can then use @key{RET}
612(@code{select-reference-this-line} to select the menu or note reference.
613
614@item @code{M-TAB} (@code{move-to-prev-xref})
615@kindex M-TAB, in Info windows
616@findex move-to-prev-xref
617Moves the cursor the start of the nearest previous menu item or note
618reference in this node.
619
620@item @code{RET} (@code{select-reference-this-line})
621@kindex RET, in Info windows
622@findex select-reference-this-line
623Selects the menu item or note reference appearing on this line.
624@end table
625
626@node Window Commands
627@chapter Manipulating Multiple Windows
628@cindex windows, manipulating
629
630A @dfn{window} is a place to show the text of a node. Windows have a
631view area where the text of the node is displayed, and an associated
632@dfn{mode line}, which briefly describes the node being viewed.
633
634GNU Info supports multiple windows appearing in a single screen; each
635window is separated from the next by its modeline. At any time, there
636is only one @dfn{active} window, that is, the window in which the cursor
637appears. There are commands available for creating windows, changing
638the size of windows, selecting which window is active, and for deleting
639windows.
640
641@menu
642* The Mode Line:: What appears in the mode line?
643* Basic Windows:: Manipulating windows in Info.
644* The Echo Area:: Used for displaying errors and reading input.
645@end menu
646
647@node The Mode Line
648@section The Mode Line
649
650A @dfn{mode line} is a line of inverse video which appears at the bottom
651of an info window. It describes the contents of the window just above
652it; this information includes the name of the file and node appearing in
653that window, the number of screen lines it takes to display the node,
654and the percentage of text that is above the top of the window. It can
655also tell you if the indirect tags table for this info file needs to be
656updated, and whether or not the info file was compressed when stored on
657disk.
658
659Here is a sample mode line for a window containing an uncompressed file
660named @file{dir}, showing the node @samp{Top}.
661
662@example
663-----Info: (dir)Top, 40 lines --Top---------------------------------------
664 ^^ ^ ^^^ ^^
665 (file)Node #lines where
666@end example
667
668When a node comes from a file which is compressed on disk, this is
669indicated in the mode line with two small @samp{z}'s. In addition, if
670the info file containing the node has been split into subfiles, the name
671of the subfile containing the node appears in the modeline as well:
672
673@example
674--zz-Info: (emacs)Top, 291 lines --Top-- Subfile: emacs-1.Z---------------
675@end example
676
677When Info makes a node internally, such that there is no corresponding
678info file on disk, the name of the node is surrounded by asterisks
679(@samp{*}). The name itself tells you what the contents of the window
680are; the sample mode line below shows an internally constructed node
681showing possible completions:
682
683@example
684-----Info: *Completions*, 7 lines --All-----------------------------------
685@end example
686
687@node Basic Windows
688@section Window Commands
689
690It can be convenient to view more than one node at a time. To allow
691this, Info can display more than one @dfn{window}. Each window has its
692own mode line (@pxref{The Mode Line}) and history of nodes viewed in that
693window (@pxref{Node Commands, , @code{history-node}}).
694
695@table @asis
696@item @code{C-x o} (@code{next-window})
697@cindex windows, selecting
698@kindex C-x o
699@findex next-window
700Selects the next window on the screen. Note that the echo area can only be
701selected if it is already in use, and you have left it temporarily.
702Normally, @samp{C-x o} simply moves the cursor into the next window on
703the screen, or if you are already within the last window, into the first
704window on the screen. Given a numeric argument, @samp{C-x o} moves over
705that many windows. A negative argument causes @samp{C-x o} to select
706the previous window on the screen.
707
708@item @code{M-x prev-window}
709@findex prev-window
710Selects the previous window on the screen. This is identical to
711@samp{C-x o} with a negative argument.
712
713@item @code{C-x 2} (@code{split-window})
714@cindex windows, creating
715@kindex C-x 2
716@findex split-window
717Splits the current window into two windows, both showing the same node.
718Each window is one half the size of the original window, and the cursor
719remains in the original window. The variable @code{automatic-tiling}
720can cause all of the windows on the screen to be resized for you
721automatically, please @pxref{Variables, , automatic-tiling} for more
722information.
723
724@item @code{C-x 0} (@code{delete-window})
725@cindex windows, deleting
726@kindex C-x 0
727@findex delete-window
728Deletes the current window from the screen. If you have made too many
729windows and your screen appears cluttered, this is the way to get rid of
730some of them.
731
732@item @code{C-x 1} (@code{keep-one-window})
733@kindex C-x 1
734@findex keep-one-window
735Deletes all of the windows excepting the current one.
736
737@item @code{ESC C-v} (@code{scroll-other-window})
738@kindex ESC C-v, in Info windows
739@findex scroll-other-window
740Scrolls the other window, in the same fashion that @samp{C-v} might
741scroll the current window. Given a negative argument, the "other"
742window is scrolled backward.
743
744@item @code{C-x ^} (@code{grow-window})
745@kindex C-x ^
746@findex grow-window
747Grows (or shrinks) the current window. Given a numeric argument, grows
748the current window that many lines; with a negative numeric argument,
749the window is shrunk instead.
750
751@item @code{C-x t} (@code{tile-windows})
752@cindex tiling
753@kindex C-x t
754@findex tile-windows
755Divides the available screen space among all of the visible windows.
756Each window is given an equal portion of the screen in which to display
757its contents. The variable @code{automatic-tiling} can cause
758@code{tile-windows} to be called when a window is created or deleted.
759@xref{Variables, , @code{automatic-tiling}}.
760@end table
761
762@node The Echo Area
763@section The Echo Area
764@cindex echo area
765
766The @dfn{echo area} is a one line window which appears at the bottom of
767the screen. It is used to display informative or error messages, and to
768read lines of input from you when that is necessary. Almost all of the
769commands available in the echo area are identical to their Emacs
770counterparts, so please refer to that documentation for greater depth of
771discussion on the concepts of editing a line of text. The following
772table briefly lists the commands that are available while input is being
773read in the echo area:
774
775@table @asis
776@item @code{C-f} (@code{echo-area-forward})
777@kindex C-f, in the echo area
778@findex echo-area-forward
779Moves forward a character.
780
781@item @code{C-b} (@code{echo-area-backward})
782@kindex C-b, in the echo area
783@findex echo-area-backward
784Moves backward a character.
785
786@item @code{C-a} (@code{echo-area-beg-of-line})
787@kindex C-a, in the echo area
788@findex echo-area-beg-of-line
789Moves to the start of the input line.
790
791@item @code{C-e} (@code{echo-area-end-of-line})
792@kindex C-e, in the echo area
793@findex echo-area-end-of-line
794Moves to the end of the input line.
795
796@item @code{M-f} (@code{echo-area-forward-word})
797@kindex M-f, in the echo area
798@findex echo-area-forward-word
799Moves forward a word.
800
801@item @code{M-b} (@code{echo-area-backward-word})
802@kindex M-b, in the echo area
803@findex echo-area-backward-word
804Moves backward a word.
805
806@item @code{C-d} (@code{echo-area-delete})
807@kindex C-d, in the echo area
808@findex echo-area-delete
809Deletes the character under the cursor.
810
811@item @code{DEL} (@code{echo-area-rubout})
812@kindex DEL, in the echo area
813@findex echo-area-rubout
814Deletes the character behind the cursor.
815
816@item @code{C-g} (@code{echo-area-abort})
817@kindex C-g, in the echo area
818@findex echo-area-abort
819Cancels or quits the current operation. If completion is being read,
820@samp{C-g} discards the text of the input line which does not match any
821completion. If the input line is empty, @samp{C-g} aborts the calling
822function.
823
824@item @code{RET} (@code{echo-area-newline})
825@kindex RET, in the echo area
826@findex echo-area-newline
827Accepts (or forces completion of) the current input line.
828
829@item @code{C-q} (@code{echo-area-quoted-insert})
830@kindex C-q, in the echo area
831@findex echo-area-quoted-insert
832Inserts the next character verbatim. This is how you can insert control
833characters into a search string, for example.
834
835@item @var{printing character} (@code{echo-area-insert})
836@kindex printing characters, in the echo area
837@findex echo-area-insert
838Inserts the character.
839
840@item @code{M-TAB} (@code{echo-area-tab-insert})
841@kindex M-TAB, in the echo area
842@findex echo-area-tab-insert
843Inserts a TAB character.
844
845@item @code{C-t} (@code{echo-area-transpose-chars})
846@kindex C-t, in the echo area
847@findex echo-area-transpose-chars
848Transposes the characters at the cursor.
849@end table
850
851The next group of commands deal with @dfn{killing}, and @dfn{yanking}
852text. For an in depth discussion of killing and yanking,
853@pxref{Killing, , Killing and Deleting, emacs, the GNU Emacs Manual}
854
855@table @asis
856@item @code{M-d} (@code{echo-area-kill-word})
857@kindex M-d, in the echo area
858@findex echo-area-kill-word
859Kills the word following the cursor.
860
861@item @code{M-DEL} (@code{echo-area-backward-kill-word})
862@kindex M-DEL, in the echo area
863@findex echo-area-backward-kill-word
864Kills the word preceding the cursor.
865
866@item @code{C-k} (@code{echo-area-kill-line})
867@kindex C-k, in the echo area
868@findex echo-area-kill-line
869Kills the text from the cursor to the end of the line.
870
871@item @code{C-x DEL} (@code{echo-area-backward-kill-line})
872@kindex C-x DEL, in the echo area
873@findex echo-area-backward-kill-line
874Kills the text from the cursor to the beginning of the line.
875
876@item @code{C-y} (@code{echo-area-yank})
877@kindex C-y, in the echo area
878@findex echo-area-yank
879Yanks back the contents of the last kill.
880
881@item @code{M-y} (@code{echo-area-yank-pop})
882@kindex M-y, in the echo area
883@findex echo-area-yank-pop
884Yanks back a previous kill, removing the last yanked text first.
885@end table
886
887Sometimes when reading input in the echo area, the command that needed
888input will only accept one of a list of several choices. The choices
889represent the @dfn{possible completions}, and you must respond with one
890of them. Since there are a limited number of responses you can make,
891Info allows you to abbreviate what you type, only typing as much of the
892response as is necessary to uniquely identify it. In addition, you can
893request Info to fill in as much of the response as is possible; this
894is called @dfn{completion}.
895
896The following commands are available when completing in the echo area:
897
898@table @asis
899@item @code{TAB} (@code{echo-area-complete})
900@itemx @code{SPC}
901@kindex TAB, in the echo area
902@kindex SPC, in the echo area
903@findex echo-area-complete
904Inserts as much of a completion as is possible.
905
906@item @code{?} (@code{echo-area-possible-completions})
907@kindex ?, in the echo area
908@findex echo-area-possible-completions
909Displays a window containing a list of the possible completions of what
910you have typed so far. For example, if the available choices are:
911@example
912bar
913foliate
914food
915forget
916@end example
917and you have typed an @samp{f}, followed by @samp{?}, the possible
918completions would contain:
919@example
920foliate
921food
922forget
923@end example
924i.e., all of the choices which begin with @samp{f}. Pressing @key{SPC}
925or @key{TAB} would result in @samp{fo} appearing in the echo area, since
926all of the choices which begin with @samp{f} continue with @samp{o}.
927Now, typing @samp{l} followed by @samp{TAB} results in @samp{foliate}
928appearing in the echo area, since that is the only choice which begins
929with @samp{fol}.
930
931@item @code{ESC C-v} (@code{echo-area-scroll-completions-window})
932@kindex ESC C-v, in the echo area
933@findex echo-area-scroll-completions-window
934Scrolls the completions window, if that is visible, or the "other"
935window if not.
936@end table
937
938@node Printing Nodes
939@chapter Printing Out Nodes
940@cindex printing
941
942You may wish to print out the contents of a node as a quick reference
943document for later use. Info provides you with a command for doing
944this. In general, we recommend that you use @TeX{} to format the
945document and print sections of it, by running @code{tex} on the texinfo
946source file.
947
948@table @asis
949@item @code{M-x print-node}
950@findex print-node
951@cindex INFO_PRINT_COMMAND, environment variable
952Pipes the contents of the current node through the command in the
953environment variable @code{INFO_PRINT_COMMAND}. If the variable doesn't
954exist, the node is simply piped to @code{lpr}.
955@end table
956
957@node Miscellaneous Commands
958@chapter Miscellaneous Commands
959
960GNU Info contains several commands which self-document GNU Info:
961
962@table @asis
963@item @code{M-x describe-command}
964@cindex functions, describing
965@cindex commands, describing
966@findex describe-command
967Reads the name of an Info command in the echo area and then displays a
968brief description of what that command does.
969
970@item @code{M-x describe-key}
971@cindex keys, describing
972@findex describe-key
973Reads a key sequence in the echo area, and then displays the name and
974documentation of the Info command that the key sequence invokes.
975
976@item @code{M-x describe-variable}
977Reads the name of a variable in the echo area and then displays a brief
978description of what the variable affects.
979
980@item @code{M-x where-is}
981@findex where-is
982Reads the name of an Info command in the echo area, and then displays
983a key sequence which can be typed in order to invoke that command.
984
985@item @code{C-h} (@code{get-help-window})
986@itemx @code{?}
987@kindex C-h
988@kindex ?, in Info windows
989@findex get-help-window
990Creates (or moves into) the window displaying @code{*Help*}, and places
991a node containing a quick reference card into it. This window displays
992the most concise information about GNU Info available.
993
994@item @code{h} (@code{get-info-help-node})
995@kindex h
996@findex get-info-help-node
997Tries hard to visit the node @code{(info)Help}. The info file
998@file{info.texi} distributed with GNU Info contains this node. Of
999course, the file must first be processed with @code{makeinfo}, and then
1000placed into the location of your info directory.
1001@end table
1002
1003Here are the commands for creating a numeric argument:
1004
1005@table @asis
1006@item @code{C-u} (@code{universal-argument})
1007@cindex numeric arguments
1008@kindex C-u
1009@findex universal-argument
1010Starts (or multiplies by 4) the current numeric argument. @samp{C-u} is
1011a good way to give a small numeric argument to cursor movement or
1012scrolling commands; @samp{C-u C-v} scrolls the screen 4 lines, while
1013@samp{C-u C-u C-n} moves the cursor down 16 lines.
1014
1015@item @code{M-1} (@code{add-digit-to-numeric-arg})
1016@itemx @code{M-2} @dots{} @code{M-9}
1017@kindex M-1 @dots{} M-9
1018@findex add-digit-to-numeric-arg
1019Adds the digit value of the invoking key to the current numeric
1020argument. Once Info is reading a numeric argument, you may just type
1021the digits of the argument, without the Meta prefix. For example, you
1022might give @samp{C-l} a numeric argument of 32 by typing:
1023
1024@example
1025@kbd{C-u 3 2 C-l}
1026@end example
1027or
1028@example
1029@kbd{M-3 2 C-l}
1030@end example
1031@end table
1032
1033@samp{C-g} is used to abort the reading of a multi-character key
1034sequence, to cancel lengthy operations (such as multi-file searches) and
1035to cancel reading input in the echo area.
1036
1037@table @asis
1038@item @code{C-g} (@code{abort-key})
1039@cindex cancelling typeahead
1040@cindex cancelling the current operation
1041@kindex C-g, in Info windows
1042@findex abort-key
1043Cancels current operation.
1044@end table
1045
1046The @samp{q} command of Info simply quits running Info.
1047
1048@table @asis
1049@item @code{q} (@code{quit})
1050@cindex quitting
1051@kindex q
1052@findex quit
1053Exits GNU Info.
1054@end table
1055
1056If the operating system tells GNU Info that the screen is 60 lines tall,
1057and it is actually only 40 lines tall, here is a way to tell Info that
1058the operating system is correct.
1059
1060@table @asis
1061@item @code{M-x set-screen-height}
1062@findex set-screen-height
1063@cindex screen, changing the height of
1064Reads a height value in the echo area and sets the height of the
1065displayed screen to that value.
1066@end table
1067
1068Finally, Info provides a convenient way to display footnotes which might
1069be associated with the current node that you are viewing:
1070
1071@table @asis
1072@item @code{ESC C-f} (@code{show-footnotes})
1073@kindex ESC C-f
1074@findex show-footnotes
1075@cindex footnotes, displaying
1076Shows the footnotes (if any) associated with the current node in another
1077window. You can have Info automatically display the footnotes
1078associated with a node when the node is selected by setting the variable
1079@code{automatic-footnotes}. @xref{Variables, , @code{automatic-footnotes}}.
1080@end table
1081
1082@node Variables
1083@chapter Manipulating Variables
1084
1085GNU Info contains several @dfn{variables} whose values are looked at by various
1086Info commands. You can change the values of these variables, and thus
1087change the behaviour of Info to more closely match your environment and
1088info file reading manner.
1089
1090@table @asis
1091@item @code{M-x set-variable}
1092@cindex variables, setting
1093@findex set-variable
1094Reads the name of a variable, and the value for it, in the echo area and
1095then sets the variable to that value. Completion is available when
1096reading the variable name; often, completion is available when reading
1097the value to give to the variable, but that depends on the variable
1098itself. If a variable does @emph{not} supply multiple choices to
1099complete over, it expects a numeric value.
1100
1101@item @code{M-x describe-variable}
1102@cindex variables, describing
1103@findex describe-variable
1104Reads the name of a variable in the echo area and then displays a brief
1105description of what the variable affects.
1106@end table
1107
1108Here is a list of the variables that you can set in Info.
1109
1110@table @code
1111@item automatic-footnotes
1112@vindex automatic-footnotes
1113When set to @code{On}, footnotes appear and disappear automatically.
1114This variable is @code{On} by default. When a node is selected, a
1115window containing the footnotes which appear in that node is created,
1116and the footnotes are displayed within the new window. The window that
1117Info creates to contain the footnotes is called @samp{*Footnotes*}. If
1118a node is selected which contains no footnotes, and a @samp{*Footnotes*}
1119window is on the screen, the @samp{*Footnotes*} window is deleted.
1120Footnote windows created in this fashion are not automatically tiled so
1121that they can use as little of the display as is possible.
1122
1123@item automatic-tiling
1124@vindex automatic-tiling
1125When set to @code{On}, creating or deleting a window resizes other
1126windows. This variable is @code{Off} by default. Normally, typing
1127@samp{C-x 2} divides the current window into two equal parts. When
1128@code{automatic-tiling} is set to @code{On}, all of the windows are
1129resized automatically, keeping an equal number of lines visible in each
1130window. There are exceptions to the automatic tiling; specifically, the
1131windows @samp{*Completions*} and @samp{*Footnotes*} are @emph{not}
1132resized through automatic tiling; they remain their original size.
1133
1134@item visible-bell
1135@vindex visible-bell
1136When set to @code{On}, GNU Info attempts to flash the screen instead of
1137ringing the bell. This variable is @code{Off} by default. Of course,
1138Info can only flash the screen if the terminal allows it; in the case
1139that the terminal does not allow it, the setting of this variable has no
1140effect. However, you can make Info perform quietly by setting the
1141@code{errors-ring-bell} variable to @code{Off}.
1142
1143@item errors-ring-bell
1144@vindex errors-ring-bell
1145When set to @code{On}, errors cause the bell to ring. The default
1146setting of this variable is @code{On}.
1147
1148@item gc-compressed-files
1149@vindex gc-compressed-files
1150When set to @code{On}, Info garbage collects files which had to be
1151uncompressed. The default value of this variable is @code{Off}.
1152Whenever a node is visited in Info, the info file containing that node
1153is read into core, and Info reads information about the tags and nodes
1154contained in that file. Once the tags information is read by Info, it
1155is never forgotten. However, the actual text of the nodes does not need
1156to remain in core unless a particular info window needs it. For
1157non-compressed files, the text of the nodes does not remain in core when
1158it is no longer in use. But de-compressing a file can be a time
1159consuming operation, and so Info tries hard not to do it twice.
1160@code{gc-compressed-files} tells Info it is okay to garbage collect the
1161text of the nodes of a file which was compressed on disk.
1162
1163@item show-index-match
1164@vindex show-index-match
1165When set to @code{On}, the portion of the matched search string is
1166highlighted in the message which explains where the matched search
1167string was found. The default value of this variable is @code{On}.
1168When Info displays the location where an index match was found,
1169(@pxref{Searching Commands, , @code{next-index-match}}), the portion of the
1170string that you had typed is highlighted by displaying it in the inverse
1171case from its surrounding characters.
1172
1173@item scroll-behaviour
1174@vindex scroll-behaviour
1175Controls what happens when forward scrolling is requested at the end of
1176a node, or when backward scrolling is requested at the beginning of a
1177node. The default value for this variable is @code{Continuous}. There
1178are three possible values for this variable:
1179
1180@table @code
1181@item Continuous
1182Tries to get the first item in this node's menu, or failing that, the
1183@samp{Next} node, or failing that, the @samp{Next} of the @samp{Up}.
1184This behaviour is identical to using the @samp{]}
1185(@code{global-next-node}) and @samp{[} (@code{global-prev-node})
1186commands.
1187
1188@item Next Only
1189Only tries to get the @samp{Next} node.
1190
1191@item Page Only
1192Simply gives up, changing nothing. If @code{scroll-behaviour} is
1193@code{Page Only}, no scrolling command can change the node that is being
1194viewed.
1195@end table
1196
1197@item scroll-step
1198@vindex scroll-step
1199The number of lines to scroll when the cursor moves out of the window.
1200Scrolling happens automatically if the cursor has moved out of the
1201visible portion of the node text when it is time to display. Usually
1202the scrolling is done so as to put the cursor on the center line of the
1203current window. However, if the variable @code{scroll-step} has a
1204nonzero value, Info attempts to scroll the node text by that many lines;
1205if that is enough to bring the cursor back into the window, that is what
1206is done. The default value of this variable is 0, thus placing the
1207cursor (and the text it is attached to) in the center of the window.
1208Setting this variable to 1 causes a kind of "smooth scrolling" which
1209some people prefer.
1210
1211@item ISO-Latin
1212@cindex ISO Latin-1 characters
1213@vindex ISO-Latin
1214When set to @code{On}, Info accepts and displays ISO Latin-1 characters.
1215By default, Info assumes an ASCII character set. @code{ISO-Latin} tells
1216Info that it is running in an environment where the European standard
1217character set is in use, and allows you to input such characters to
1218Info, as well as display them.
1219@end table
1220
1221@c The following node and its children are currently unfinished. Please feel
1222@c free to finish it!
1223
1224@ifset NOTSET
1225@node Info for Sys Admins
1226@chapter Info for System Administrators
1227
1228This text describes some common ways of setting up an Info hierarchy
1229from scratch, and details the various options that are available when
1230installing Info. This text is designed for the person who is installing
1231GNU Info on the system; although users may find the information present
1232in this section interesting, none of it is vital to understanding how to
1233use GNU Info.
1234
1235@menu
1236* Setting the INFOPATH:: Where are my Info files kept?
1237* Editing the DIR node:: What goes in `DIR', and why?
1238* Storing Info files:: Alternate formats allow flexibility in setups.
1239* Using `localdir':: Building DIR on the fly.
1240* Example setups:: Some common ways to organize Info files.
1241@end menu
1242
1243@node Setting the INFOPATH
1244@section Setting the INFOPATH
1245Where are my Info files kept?
1246
1247@node Editing the DIR node
1248@section Editing the DIR node
1249What goes in `DIR', and why?
1250
1251@node Storing Info files
1252@section Storing Info files
1253Alternate formats allow flexibility in setups.
1254
1255@node Using `localdir'
1256@section Using `localdir'
1257Building DIR on the fly.
1258
1259@node Example setups
1260@section Example setups
1261Some common ways to organize Info files.
1262@end ifset
1263
1264@ifset STANDALONE
1265@node GNU Info Global Index
1266@appendix Global Index
1267@printindex cp
1268@end ifset
diff --git a/man/info.texi b/man/info.texi
new file mode 100644
index 00000000000..30997676f1a
--- /dev/null
+++ b/man/info.texi
@@ -0,0 +1,969 @@
1\input texinfo @c -*-texinfo-*-
2@comment %**start of header
3@setfilename ../info/info
4@settitle Info 1.0
5@comment %**end of header
6
7@direntry
8* Info: (info). Documentation browsing system.
9@end direntry
10
11@iftex
12@finalout
13@end iftex
14
15@ifinfo
16This file describes how to use Info,
17the on-line, menu-driven GNU documentation system.
18
19Copyright (C) 1989, 1992 Free Software Foundation, Inc.
20
21Permission is granted to make and distribute verbatim copies of
22this manual provided the copyright notice and this permission notice
23are preserved on all copies.
24
25@ignore
26Permission is granted to process this file through TeX and print the
27results, provided the printed document carries copying permission
28notice identical to this one except for the removal of this paragraph
29(this paragraph not being relevant to the printed manual).
30
31@end ignore
32Permission is granted to copy and distribute modified versions of this
33manual under the conditions for verbatim copying, provided that the entire
34resulting derived work is distributed under the terms of a permission
35notice identical to this one.
36
37Permission is granted to copy and distribute translations of this manual
38into another language, under the above conditions for modified versions,
39except that this permission notice may be stated in a translation approved
40by the Free Software Foundation.
41@end ifinfo
42
43@setchapternewpage odd
44@titlepage
45@sp 11
46@center @titlefont{Info}
47@sp 2
48@center The
49@sp 2
50@center On-line, Menu-driven
51@sp 2
52@center GNU Documentation System
53
54@page
55@vskip 0pt plus 1filll
56Copyright @copyright{} 1989, 1992, 1993 Free Software Foundation, Inc.
57@sp 2
58
59Published by the Free Software Foundation @*
6059 Temple Place, Suite 330 @*
61Boston, MA 02111-1307 USA @*
62
63Permission is granted to make and distribute verbatim copies of
64this manual provided the copyright notice and this permission notice
65are preserved on all copies.
66
67Permission is granted to copy and distribute modified versions of this
68manual under the conditions for verbatim copying, provided that the entire
69resulting derived work is distributed under the terms of a permission
70notice identical to this one.
71
72Permission is granted to copy and distribute translations of this manual
73into another language, under the above conditions for modified versions,
74except that this permission notice may be stated in a translation approved
75by the Free Software Foundation.
76@end titlepage
77
78@paragraphindent 3
79@ifinfo
80@node Top, Getting Started, (dir), (dir)
81@top Info: An Introduction
82
83Info is a program for reading documentation, which you are using now.
84
85To learn how to use Info, type the command @kbd{h}. It brings you
86to a programmed instruction sequence. If at any time you are ready to
87stop using Info, type @samp{q}.
88
89@c Need to make sure that `Info-help' goes to the right node,
90@c which is the first node of the first chapter. (It should.)
91@c (Info-find-node "info"
92@c (if (< (window-height) 23)
93@c "Help-Small-Screen"
94@c "Help")))
95
96To learn advanced Info commands, type @kbd{n} twice. This brings you to
97@cite{Info for Experts}, skipping over the `Getting Started' chapter.
98@end ifinfo
99
100@menu
101* Getting Started:: Getting started using an Info reader.
102* Advanced Info:: Advanced commands within Info.
103* Create an Info File:: How to make your own Info file.
104@end menu
105
106@node Getting Started, Advanced Info, Top, Top
107@comment node-name, next, previous, up
108@chapter Getting Started
109
110This first part of the Info manual describes how to get around inside
111of Info. The second part of the manual describes various advanced
112Info commands, and how to write an Info as distinct from a Texinfo
113file. The third part is about how to generate Info files from
114Texinfo files.
115
116@iftex
117This manual is primarily designed for use on a computer, so that you can
118try Info commands while reading about them. Reading it on paper is less
119effective, since you must take it on faith that the commands described
120really do what the manual says. By all means go through this manual now
121that you have it; but please try going through the on-line version as
122well.
123
124There are two ways of looking at the online version of this manual:
125
126@enumerate
127@item
128Type @code{info} at your shell's command line. This approach uses a
129stand-alone program designed just to read Info files.
130
131@item
132Type @code{emacs} at the command line; then type @kbd{C-h i} (Control
133@kbd{h}, followed by @kbd{i}). This approach uses the Info mode of the
134Emacs program, an editor with many other capabilities.
135@end enumerate
136
137In either case, then type @kbd{mInfo} (just the letters), followed by
138@key{RET}---the ``Return'' or ``Enter'' key. At this point, you should
139be ready to follow the instructions in this manual as you read them on
140the screen.
141@c FIXME! (pesch@cygnus.com, 14 dec 1992)
142@c Is it worth worrying about what-if the beginner goes to somebody
143@c else's Emacs session, which already has an Info running in the middle
144@c of something---in which case these simple instructions won't work?
145@end iftex
146
147@menu
148* Help-Small-Screen:: Starting Info on a Small Screen
149* Help:: How to use Info
150* Help-P:: Returning to the Previous node
151* Help-^L:: The Space, Rubout, B and ^L commands.
152* Help-M:: Menus
153* Help-Adv:: Some advanced Info commands
154* Help-Q:: Quitting Info
155* Using Stand-alone Info:: How to use the stand-alone Info reader.
156@end menu
157
158@node Help-Small-Screen, Help, , Getting Started
159@comment node-name, next, previous, up
160@section Starting Info on a Small Screen
161
162@iftex
163(In Info, you only see this section if your terminal has a small
164number of lines; most readers pass by it without seeing it.)
165@end iftex
166
167Since your terminal has an unusually small number of lines on its
168screen, it is necessary to give you special advice at the beginning.
169
170If you see the text @samp{--All----} at near the bottom right corner
171of the screen, it means the entire text you are looking at fits on the
172screen. If you see @samp{--Top----} instead, it means that there is
173more text below that does not fit. To move forward through the text
174and see another screen full, press the Space bar, @key{SPC}. To move
175back up, press the key labeled @samp{Delete} or @key{DEL}.
176
177@ifinfo
178Here are 40 lines of junk, so you can try Spaces and Deletes and
179see what they do. At the end are instructions of what you should do
180next.
181@format
182This is line 17
183This is line 18
184This is line 19
185This is line 20
186This is line 21
187This is line 22
188This is line 23
189This is line 24
190This is line 25
191This is line 26
192This is line 27
193This is line 28
194This is line 29
195This is line 30
196This is line 31
197This is line 32
198This is line 33
199This is line 34
200This is line 35
201This is line 36
202This is line 37
203This is line 38
204This is line 39
205This is line 40
206This is line 41
207This is line 42
208This is line 43
209This is line 44
210This is line 45
211This is line 46
212This is line 47
213This is line 48
214This is line 49
215This is line 50
216This is line 51
217This is line 52
218This is line 53
219This is line 54
220This is line 55
221This is line 56
222@end format
223If you have managed to get here, go back to the beginning with
224Delete, and come back here again, then you understand Space and
225Delete. So now type an @kbd{n} ---just one character; don't type
226the quotes and don't type the Return key afterward--- to
227get to the normal start of the course.
228@end ifinfo
229
230@node Help, Help-P, Help-Small-Screen, Getting Started
231@comment node-name, next, previous, up
232@section How to use Info
233
234You are talking to the program Info, for reading documentation.
235
236 Right now you are looking at one @dfn{Node} of Information.
237A node contains text describing a specific topic at a specific
238level of detail. This node's topic is ``how to use Info''.
239
240 The top line of a node is its @dfn{header}. This node's header (look at
241it now) says that it is the node named @samp{Help} in the file
242@file{info}. It says that the @samp{Next} node after this one is the node
243called @samp{Help-P}. An advanced Info command lets you go to any node
244whose name you know.
245
246 Besides a @samp{Next}, a node can have a @samp{Previous} or an
247@samp{Up}. This node has a @samp{Previous} which is
248@samp{Help-Small-Screen}, and an @samp{Up} which is @samp{Getting
249Started}. Some nodes have no @samp{Previous} and some have no
250@samp{Up}.
251
252 Now it is time to move on to the @samp{Next} node, named @samp{Help-P}.
253
254@format
255>> Type @samp{n} to move there. Type just one character;
256 do not type the quotes and do not type a @key{RET} afterward.
257@end format
258
259@samp{>>} in the margin means it is really time to try a command.
260
261@node Help-P, Help-^L, Help, Getting Started
262@comment node-name, next, previous, up
263@section Returning to the Previous node
264
265This node is called @samp{Help-P}. The @samp{Previous} node, as you see,
266is @samp{Help}, which is the one you just came from using the @kbd{n}
267command. Another @kbd{n} command now would take you to the next
268node, @samp{Help-^L}.
269
270@format
271>> But do not do that yet. First, try the @kbd{p} command, which takes
272 you to the @samp{Previous} node. When you get there, you can do an
273 @kbd{n} again to return here.
274@end format
275
276 This all probably seems insultingly simple so far, but @emph{do not} be
277led into skimming. Things will get more complicated soon. Also,
278do not try a new command until you are told it is time to. Otherwise,
279you may make Info skip past an important warning that was coming up.
280
281@format
282>> Now do an @kbd{n} to get to the node @samp{Help-^L} and learn more.
283@end format
284
285@node Help-^L, Help-M, Help-P, Getting Started
286@comment node-name, next, previous, up
287@section The Space, Delete, B and ^L commands.
288
289 This node's header tells you that you are now at node @samp{Help-^L}, and
290that @kbd{p} would get you back to @samp{Help-P}. The node's title is
291underlined; it says what the node is about (most nodes have titles).
292
293 This is a big node and it does not all fit on your display screen.
294You can tell that there is more that is not visible because you
295can see the string @samp{--Top-----} rather than @samp{--All----} near
296the bottom right corner of the screen.
297
298 The Space, Delete and @kbd{B} commands exist to allow you to ``move
299around'' in a node that does not all fit on the screen at once.
300Space moves forward, to show what was below the bottom of the screen.
301Delete moves backward, to show what was above the top of the screen
302(there is not anything above the top until you have typed some spaces).
303
304@format
305>> Now try typing a Space (afterward, type a Delete to return here).
306@end format
307
308 When you type the space, the two lines that were at the bottom of
309the screen appear at the top, followed by more lines. Delete takes
310the two lines from the top and moves them to the bottom,
311@emph{usually}, but if there are not a full screen's worth of lines
312above them they may not make it all the way to the bottom.
313
314 Space and Delete scroll through all the nodes in an Info file as a
315single logical sequence. In this sequence, a node's subnodes appear
316following their parent. If a node's menu is on the screen, Space takes
317you into the subnodes listed in the menu, one by one. Once you reach
318the end of a node, Space takes you to the next node or back to the
319parent node.
320
321 If your screen is ever garbaged, you can tell Info to print it out
322again by typing @kbd{C-l} (@kbd{Control-L}, that is---hold down ``Control'' and
323type an @key{L} or @kbd{l}).
324
325@format
326>> Type @kbd{C-l} now.
327@end format
328
329 To move back to the beginning of the node you are on, you can type
330a lot of Deletes. You can also type simply @kbd{b} for beginning.
331@format
332>> Try that now. (We have put in enough verbiage to push this past
333the first screenful, but screens are so big nowadays that perhaps it
334isn't enough. You may need to shrink your Emacs or Info window.)
335Then come back, with Spaces.
336@end format
337
338If your screen is very tall, all of this node might fit at once.
339In that case, "b" won't do anything. Sorry; what can we do?
340
341 You have just learned a considerable number of commands. If you
342want to use one but have trouble remembering which, you should type
343a @key{?} which prints out a brief list of commands. When you are
344finished looking at the list, make it go away by typing a @key{SPC}.
345
346@format
347>> Type a @key{?} now. After it finishes, type a @key{SPC}.
348@end format
349
350 (If you are using the standalone Info reader, type `l' to return here.)
351
352 From now on, you will encounter large nodes without warning, and
353will be expected to know how to use Space and Delete to move
354around in them without being told. Since not all terminals have
355the same size screen, it would be impossible to warn you anyway.
356
357@format
358>> Now type @kbd{n} to see the description of the @kbd{m} command.
359@end format
360
361@node Help-M, Help-Adv, Help-^L, Getting Started
362@comment node-name, next, previous, up
363@section Menus
364
365Menus and the @kbd{m} command
366
367 With only the @kbd{n} and @kbd{p} commands for moving between nodes, nodes
368are restricted to a linear sequence. Menus allow a branching
369structure. A menu is a list of other nodes you can move to. It is
370actually just part of the text of the node formatted specially so that
371Info can interpret it. The beginning of a menu is always identified
372by a line which starts with @samp{* Menu:}. A node contains a menu if and
373only if it has a line in it which starts that way. The only menu you
374can use at any moment is the one in the node you are in. To use a
375menu in any other node, you must move to that node first.
376
377 After the start of the menu, each line that starts with a @samp{*}
378identifies one subtopic. The line usually contains a brief name
379for the subtopic (followed by a @samp{:}), the name of the node that talks
380about that subtopic, and optionally some further description of the
381subtopic. Lines in the menu that do not start with a @samp{*} have no
382special meaning---they are only for the human reader's benefit and do
383not define additional subtopics. Here is an example:
384
385@example
386* Foo: FOO's Node This tells about FOO
387@end example
388
389The subtopic name is Foo, and the node describing it is @samp{FOO's Node}.
390The rest of the line is just for the reader's Information.
391[[ But this line is not a real menu item, simply because there is
392no line above it which starts with @samp{* Menu:}.]]
393
394 When you use a menu to go to another node (in a way that will be
395described soon), what you specify is the subtopic name, the first
396thing in the menu line. Info uses it to find the menu line, extracts
397the node name from it, and goes to that node. The reason that there
398is both a subtopic name and a node name is that the node name must be
399meaningful to the computer and may therefore have to be ugly looking.
400The subtopic name can be chosen just to be convenient for the user to
401specify. Often the node name is convenient for the user to specify
402and so both it and the subtopic name are the same. There is an
403abbreviation for this:
404
405@example
406* Foo:: This tells about FOO
407@end example
408
409@noindent
410This means that the subtopic name and node name are the same; they are
411both @samp{Foo}.
412
413@format
414>> Now use Spaces to find the menu in this node, then come back to
415 the front with a @kbd{b} and some Spaces. As you see, a menu is
416 actually visible in its node. If you cannot find a menu in a node
417 by looking at it, then the node does not have a menu and the
418 @kbd{m} command is not available.
419@end format
420
421 The command to go to one of the subnodes is @kbd{m}---but @emph{do
422not do it yet!} Before you use @kbd{m}, you must understand the
423difference between commands and arguments. So far, you have learned
424several commands that do not need arguments. When you type one, Info
425processes it and is instantly ready for another command. The @kbd{m}
426command is different: it is incomplete without the @dfn{name of the
427subtopic}. Once you have typed @kbd{m}, Info tries to read the
428subtopic name.
429
430 Now look for the line containing many dashes near the bottom of the
431screen. There is one more line beneath that one, but usually it is
432blank. If it is empty, Info is ready for a command, such as @kbd{n}
433or @kbd{b} or Space or @kbd{m}. If that line contains text ending
434in a colon, it mean Info is trying to read the @dfn{argument} to a
435command. At such times, commands do not work, because Info tries to
436use them as the argument. You must either type the argument and
437finish the command you started, or type @kbd{Control-g} to cancel the
438command. When you have done one of those things, the line becomes
439blank again.
440
441 The command to go to a subnode via a menu is @kbd{m}. After you type
442the @kbd{m}, the line at the bottom of the screen says @samp{Menu item: }.
443You must then type the name of the subtopic you want, and end it with
444a @key{RET}.
445
446 You can abbreviate the subtopic name. If the abbreviation is not
447unique, the first matching subtopic is chosen. Some menus put the
448shortest possible abbreviation for each subtopic name in capital
449letters, so you can see how much you need to type. It does not matter
450whether you use upper case or lower case when you type the subtopic. Do
451not put spaces at the end of the subtopic name; in the middle of the
452subtopic name, use one space (no more!) wherever the menu item name has
453a space.
454
455 You can also use the @dfn{completion} feature to help enter the subtopic
456name. If you type the Tab key after entering part of a name, it will
457magically fill in more of the name---as much as follows uniquely from
458what you have entered.
459
460 If you move the cursor to one of the menu subtopic lines, then you do
461not need to type the argument: you just type a Return, and it stands for
462the subtopic of the line you are on.
463
464Here is a menu to give you a chance to practice.
465
466@menu
467This menu gives you three ways of going to one place, Help-FOO.
468
469* Foo: Help-FOO. A node you can visit for fun.
470* Bar: Help-FOO. Strange! two ways to get to the same place.
471* Help-FOO:: And yet another!
472@end menu
473
474@format
475>> Now type just an @kbd{m} and see what happens:
476@end format
477
478 Now you are ``inside'' an @kbd{m} command. Commands cannot be used
479now; the next thing you will type must be the name of a subtopic.
480
481 You can change your mind about doing the @kbd{m} by typing Control-g.
482
483@format
484>> Try that now; notice the bottom line clear.
485
486>> Then type another @kbd{m}.
487
488>> Now type @samp{BAR} item name. Do not type Return yet.
489@end format
490
491 While you are typing the item name, you can use the Delete key to
492cancel one character at a time if you make a mistake.
493
494@format
495>> Type one to cancel the @samp{R}. You could type another @samp{R} to
496 replace it. You do not have to, since @samp{BA} is a valid abbreviation.
497
498>> Now you are ready to go. Type a @key{RET}.
499@end format
500
501 After visiting Help-FOO, you should return here.
502
503@format
504>> Type @kbd{n} to see more commands.
505@end format
506
507@c If a menu appears at the end of this node, remove it.
508@c It is an accident of the menu updating command.
509
510@node Help-FOO, , , Help-M
511@comment node-name, next, previous, up
512@subsection The @kbd{u} command
513
514 Congratulations! This is the node @samp{Help-FOO}. Unlike the other
515nodes you have seen, this one has an @samp{Up}: @samp{Help-M}, the node you
516just came from via the @kbd{m} command. This is the usual
517convention---the nodes you reach from a menu have @samp{Up} nodes that lead
518back to the menu. Menus move Down in the tree, and @samp{Up} moves Up.
519@samp{Previous}, on the other hand, is usually used to ``stay on the same
520level but go backwards''
521
522 You can go back to the node @samp{Help-M} by typing the command
523@kbd{u} for ``Up''. That puts you at the @emph{front} of the
524node---to get back to where you were reading you have to type
525some @key{SPC}s.
526
527@format
528>> Now type @kbd{u} to move back up to @samp{Help-M}.
529@end format
530
531@node Help-Adv, Help-Q, Help-M, Getting Started
532@comment node-name, next, previous, up
533@section Some advanced Info commands
534
535 The course is almost over, so please stick with it to the end.
536
537 If you have been moving around to different nodes and wish to
538retrace your steps, the @kbd{l} command (@kbd{l} for @dfn{last}) will
539do that, one node-step at a time. As you move from node to node, Info
540records the nodes where you have been in a special history list. The
541@kbd{l} command revisits nodes in the history list; each successive
542@kbd{l} command moves one step back through the history.
543
544 If you have been following directions, an @kbd{l} command now will get
545you back to @samp{Help-M}. Another @kbd{l} command would undo the
546@kbd{u} and get you back to @samp{Help-FOO}. Another @kbd{l} would undo
547the @kbd{m} and get you back to @samp{Help-M}.
548
549@format
550>> Try typing three @kbd{l}'s, pausing in between to see what each
551 @kbd{l} does.
552@end format
553
554Then follow directions again and you will end up back here.
555
556 Note the difference between @kbd{l} and @kbd{p}: @kbd{l} moves to
557where @emph{you} last were, whereas @kbd{p} always moves to the node
558which the header says is the @samp{Previous} node (from this node, to
559@samp{Help-M}).
560
561 The @samp{d} command gets you instantly to the Directory node.
562This node, which is the first one you saw when you entered Info,
563has a menu which leads (directly, or indirectly through other menus),
564to all the nodes that exist.
565
566@format
567>> Try doing a @samp{d}, then do an @kbd{l} to return here (yes,
568 @emph{do} return).
569@end format
570
571 Sometimes, in Info documentation, you will see a cross reference.
572Cross references look like this: @xref{Help-Cross, Cross}. That is a
573real, live cross reference which is named @samp{Cross} and points at
574the node named @samp{Help-Cross}.
575
576 If you wish to follow a cross reference, you must use the @samp{f}
577command. The @samp{f} must be followed by the cross reference name
578(in this case, @samp{Cross}). While you enter the name, you can use the
579Delete key to edit your input. If you change your mind about following
580any reference, you can use @kbd{Control-g} to cancel the command.
581
582 Completion is available in the @samp{f} command; you can complete among
583all the cross reference names in the current node by typing a Tab.
584
585@format
586>> Type @samp{f}, followed by @samp{Cross}, and a @key{RET}.
587@end format
588
589 To get a list of all the cross references in the current node, you can
590type @kbd{?} after an @samp{f}. The @samp{f} continues to await a
591cross reference name even after printing the list, so if you don't
592actually want to follow a reference, you should type a @kbd{Control-g}
593to cancel the @samp{f}.
594
595@format
596>> Type "f?" to get a list of the cross references in this node. Then
597 type a @kbd{Control-g} and see how the @samp{f} gives up.
598
599>> Now type @kbd{n} to see the last node of the course.
600@end format
601
602@c If a menu appears at the end of this node, remove it.
603@c It is an accident of the menu updating command.
604
605@node Help-Cross, , , Help-Adv
606@comment node-name, next, previous, up
607@unnumberedsubsec The node reached by the cross reference in Info
608
609 This is the node reached by the cross reference named @samp{Cross}.
610
611 While this node is specifically intended to be reached by a cross
612reference, most cross references lead to nodes that ``belong''
613someplace else far away in the structure of Info. So you cannot expect
614the footnote to have a @samp{Next}, @samp{Previous} or @samp{Up} pointing back to
615where you came from. In general, the @kbd{l} (el) command is the only
616way to get back there.
617
618@format
619>> Type @kbd{l} to return to the node where the cross reference was.
620@end format
621
622@node Help-Q, , Help-Adv, Getting Started
623@comment node-name, next, previous, up
624@section Quitting Info
625
626 To get out of Info, back to what you were doing before, type @kbd{q}
627for @dfn{Quit}.
628
629 This is the end of the course on using Info. There are some other
630commands that are meant for experienced users; they are useful, and you
631can find them by looking in the directory node for documentation on
632Info. Finding them will be a good exercise in using Info in the usual
633manner.
634
635@format
636>> Type @samp{d} to go to the Info directory node; then type
637 @samp{mInfo} and Return, to get to the node about Info and
638 see what other help is available.
639@end format
640
641@node Advanced Info, Create an Info File, Getting Started, Top
642@comment node-name, next, previous, up
643@chapter Info for Experts
644
645This chapter describes various advanced Info commands, and how to write
646an Info as distinct from a Texinfo file. (However, in most cases, writing a
647Texinfo file is better, since you can use it @emph{both} to generate an
648Info file and to make a printed manual. @xref{Top,, Overview of
649Texinfo, texinfo, Texinfo: The GNU Documentation Format}.)
650
651@menu
652* Expert:: Advanced Info commands: g, s, e, and 1 - 5.
653* Add:: Describes how to add new nodes to the hierarchy.
654 Also tells what nodes look like.
655* Menus:: How to add to or create menus in Info nodes.
656* Cross-refs:: How to add cross-references to Info nodes.
657* Tags:: How to make tags tables for Info files.
658* Checking:: Checking an Info File
659* Emacs Info Variables:: Variables modifying the behavior of Emacs Info.
660@end menu
661
662@node Expert, Add, , Advanced Info
663@comment node-name, next, previous, up
664@section Advanced Info Commands
665
666@kbd{g}, @kbd{s}, @kbd{1}, -- @kbd{9}, and @kbd{e}
667
668If you know a node's name, you can go there by typing @kbd{g}, the
669name, and @key{RET}. Thus, @kbd{gTop@key{RET}} would go to the node
670called @samp{Top} in this file (its directory node).
671@kbd{gExpert@key{RET}} would come back here.
672
673Unlike @kbd{m}, @kbd{g} does not allow the use of abbreviations.
674
675To go to a node in another file, you can include the filename in the
676node name by putting it at the front, in parentheses. Thus,
677@kbd{g(dir)Top@key{RET}} would go to the Info Directory node, which is
678node @samp{Top} in the file @file{dir}.
679
680The node name @samp{*} specifies the whole file. So you can look at
681all of the current file by typing @kbd{g*@key{RET}} or all of any
682other file with @kbd{g(FILENAME)@key{RET}}.
683
684The @kbd{s} command allows you to search a whole file for a string. It
685switches to the next node if and when that is necessary. You type
686@kbd{s} followed by the string to search for, terminated by @key{RET}.
687To search for the same string again, just @kbd{s} followed by @key{RET}
688will do. The file's nodes are scanned in the order they are in in the
689file, which has no necessary relationship to the order that they may be
690in in the tree structure of menus and @samp{next} pointers. But
691normally the two orders are not very different. In any case, you can
692always do a @kbd{b} to find out what node you have reached, if the
693header is not visible (this can happen, because @kbd{s} puts your cursor
694at the occurrence of the string, not at the beginning of the node).
695
696@kbd{Meta-s} is equivalent to @kbd{s}. That is for compatibility with
697other GNU packages that use @kbd{M-s} for a similar kind of search
698command.
699
700If you grudge the system each character of type-in it requires, you
701might like to use the commands @kbd{1}, @kbd{2}, @kbd{3}, @kbd{4}, ...
702@kbd{9}. They are short for the @kbd{m} command together with an
703argument. @kbd{1} goes through the first item in the current node's
704menu; @kbd{2} goes through the second item, etc.
705
706If your display supports multiple fonts, and you are using Emacs' Info
707mode to read Info files, the @samp{*} for the fifth menu item is
708underlined, and so is the @samp{*} for the ninth item; these underlines
709make it easy to see at a glance which number to use for an item.
710
711On ordinary terminals, you won't have underlining. If you need to
712actually count items, it is better to use @kbd{m} instead, and specify
713the name.
714
715The Info command @kbd{e} changes from Info mode to an ordinary
716Emacs editing mode, so that you can edit the text of the current node.
717Type @kbd{C-c C-c} to switch back to Info. The @kbd{e} command is allowed
718only if the variable @code{Info-enable-edit} is non-@code{nil}.
719
720@node Add, Menus, Expert, Advanced Info
721@comment node-name, next, previous, up
722@section Adding a new node to Info
723
724To add a new topic to the list in the Info directory, you must:
725@enumerate
726@item
727Create some nodes, in some file, to document that topic.
728@item
729Put that topic in the menu in the directory. @xref{Menus, Menu}.
730@end enumerate
731
732Usually, the way to create the nodes is with Texinfo @pxref{Top,, Overview of
733Texinfo, texinfo, Texinfo: The GNU Documentation Format}); this has the
734advantage that you can also make a printed manual from them. However,
735if you want to edit an Info file, here is how.
736
737 The new node can live in an existing documentation file, or in a new
738one. It must have a @key{^_} character before it (invisible to the
739user; this node has one but you cannot see it), and it ends with either
740a @key{^_}, a @key{^L}, or the end of file. Note: If you put in a
741@key{^L} to end a new node, be sure that there is a @key{^_} after it
742to start the next one, since @key{^L} cannot @emph{start} a node.
743Also, a nicer way to make a node boundary be a page boundary as well
744is to put a @key{^L} @emph{right after} the @key{^_}.
745
746 The @key{^_} starting a node must be followed by a newline or a
747@key{^L} newline, after which comes the node's header line. The
748header line must give the node's name (by which Info finds it),
749and state the names of the @samp{Next}, @samp{Previous}, and @samp{Up} nodes (if
750there are any). As you can see, this node's @samp{Up} node is the node
751@samp{Top}, which points at all the documentation for Info. The @samp{Next}
752node is @samp{Menus}.
753
754 The keywords @dfn{Node}, @dfn{Previous}, @dfn{Up}, and @dfn{Next},
755may appear in any order, anywhere in the header line, but the
756recommended order is the one in this sentence. Each keyword must be
757followed by a colon, spaces and tabs, and then the appropriate name.
758The name may be terminated with a tab, a comma, or a newline. A space
759does not end it; node names may contain spaces. The case of letters
760in the names is insignificant.
761
762 A node name has two forms. A node in the current file is named by
763what appears after the @samp{Node: } in that node's first line. For
764example, this node's name is @samp{Add}. A node in another file is
765named by @samp{(@var{filename})@var{node-within-file}}, as in
766@samp{(info)Add} for this node. If the file name starts with ``./'',
767then it is relative to the current directory; otherwise, it is relative
768starting from the standard Info file directory of your site.
769The name @samp{(@var{filename})Top} can be abbreviated to just
770@samp{(@var{filename})}. By convention, the name @samp{Top} is used for
771the ``highest'' node in any single file---the node whose @samp{Up} points
772out of the file. The Directory node is @file{(dir)}. The @samp{Top} node
773of a document file listed in the Directory should have an @samp{Up:
774(dir)} in it.
775
776 The node name @kbd{*} is special: it refers to the entire file.
777Thus, @kbd{g*} shows you the whole current file. The use of the
778node @kbd{*} is to make it possible to make old-fashioned,
779unstructured files into nodes of the tree.
780
781 The @samp{Node:} name, in which a node states its own name, must not
782contain a filename, since Info when searching for a node does not
783expect one to be there. The @samp{Next}, @samp{Previous} and @samp{Up} names may
784contain them. In this node, since the @samp{Up} node is in the same file,
785it was not necessary to use one.
786
787 Note that the nodes in this file have a file name in the header
788line. The file names are ignored by Info, but they serve as comments
789to help identify the node for the user.
790
791@node Menus, Cross-refs, Add, Advanced Info
792@comment node-name, next, previous, up
793@section How to Create Menus
794
795 Any node in the Info hierarchy may have a @dfn{menu}---a list of subnodes.
796The @kbd{m} command searches the current node's menu for the topic which it
797reads from the terminal.
798
799 A menu begins with a line starting with @samp{* Menu:}. The rest of the
800line is a comment. After the starting line, every line that begins
801with a @samp{* } lists a single topic. The name of the topic--the
802argument that the user must give to the @kbd{m} command to select this
803topic---comes right after the star and space, and is followed by a
804colon, spaces and tabs, and the name of the node which discusses that
805topic. The node name, like node names following @samp{Next}, @samp{Previous}
806and @samp{Up}, may be terminated with a tab, comma, or newline; it may also
807be terminated with a period.
808
809 If the node name and topic name are the same, then rather than
810giving the name twice, the abbreviation @samp{* NAME::} may be used
811(and should be used, whenever possible, as it reduces the visual
812clutter in the menu).
813
814 It is considerate to choose the topic names so that they differ
815from each other very near the beginning---this allows the user to type
816short abbreviations. In a long menu, it is a good idea to capitalize
817the beginning of each item name which is the minimum acceptable
818abbreviation for it (a long menu is more than 5 or so entries).
819
820 The nodes listed in a node's menu are called its ``subnodes'', and
821it is their ``superior''. They should each have an @samp{Up:} pointing at
822the superior. It is often useful to arrange all or most of the
823subnodes in a sequence of @samp{Next} and @samp{Previous} pointers so that someone who
824wants to see them all need not keep revisiting the Menu.
825
826 The Info Directory is simply the menu of the node @samp{(dir)Top}---that
827is, node @samp{Top} in file @file{.../info/dir}. You can put new entries
828in that menu just like any other menu. The Info Directory is @emph{not} the
829same as the file directory called @file{info}. It happens that many of
830Info's files live on that file directory, but they do not have to; and
831files on that directory are not automatically listed in the Info
832Directory node.
833
834 Also, although the Info node graph is claimed to be a ``hierarchy'',
835in fact it can be @emph{any} directed graph. Shared structures and
836pointer cycles are perfectly possible, and can be used if they are
837appropriate to the meaning to be expressed. There is no need for all
838the nodes in a file to form a connected structure. In fact, this file
839has two connected components. You are in one of them, which is under
840the node @samp{Top}; the other contains the node @samp{Help} which the
841@kbd{h} command goes to. In fact, since there is no garbage
842collector, nothing terrible happens if a substructure is not pointed
843to, but such a substructure is rather useless since nobody can
844ever find out that it exists.
845
846@node Cross-refs, Tags, Menus, Advanced Info
847@comment node-name, next, previous, up
848@section Creating Cross References
849
850 A cross reference can be placed anywhere in the text, unlike a menu
851item which must go at the front of a line. A cross reference looks
852like a menu item except that it has @samp{*note} instead of @kbd{*}.
853It @emph{cannot} be terminated by a @samp{)}, because @samp{)}'s are
854so often part of node names. If you wish to enclose a cross reference
855in parentheses, terminate it with a period first. Here are two
856examples of cross references pointers:
857
858@example
859*Note details: commands. (See *note 3: Full Proof.)
860@end example
861
862They are just examples. The places they ``lead to'' do not really exist!
863
864@node Tags, Checking, Cross-refs, Advanced Info
865@comment node-name, next, previous, up
866@section Tags Tables for Info Files
867
868 You can speed up the access to nodes of a large Info file by giving
869it a tags table. Unlike the tags table for a program, the tags table for
870an Info file lives inside the file itself and is used
871automatically whenever Info reads in the file.
872
873 To make a tags table, go to a node in the file using Emacs Info mode and type
874@kbd{M-x Info-tagify}. Then you must use @kbd{C-x C-s} to save the
875file.
876
877 Once the Info file has a tags table, you must make certain it is up
878to date. If, as a result of deletion of text, any node moves back
879more than a thousand characters in the file from the position
880recorded in the tags table, Info will no longer be able to find that
881node. To update the tags table, use the @code{Info-tagify} command again.
882
883 An Info file tags table appears at the end of the file and looks like
884this:
885
886@example
887^_
888Tag Table:
889File: info, Node: Cross-refs^?21419
890File: info, Node: Tags^?22145
891^_
892End Tag Table
893@end example
894
895@noindent
896Note that it contains one line per node, and this line contains
897the beginning of the node's header (ending just after the node name),
898a Delete character, and the character position in the file of the
899beginning of the node.
900
901@node Checking, Emacs Info Variables, Tags, Advanced Info
902@comment node-name, next, previous, up
903@section Checking an Info File
904
905 When creating an Info file, it is easy to forget the name of a node
906when you are making a pointer to it from another node. If you put in
907the wrong name for a node, this is not detected until someone
908tries to go through the pointer using Info. Verification of the Info
909file is an automatic process which checks all pointers to nodes and
910reports any pointers which are invalid. Every @samp{Next}, @samp{Previous}, and
911@samp{Up} is checked, as is every menu item and every cross reference. In
912addition, any @samp{Next} which does not have a @samp{Previous} pointing back is
913reported. Only pointers within the file are checked, because checking
914pointers to other files would be terribly slow. But those are usually
915few.
916
917 To check an Info file, do @kbd{M-x Info-validate} while looking at
918any node of the file with Emacs Info mode.
919
920@node Emacs Info Variables, , Checking, Advanced Info
921@section Emacs Info-mode Variables
922
923The following variables may modify the behaviour of Info-mode in Emacs;
924you may wish to set one or several of these variables interactively, or
925in your @file{~/.emacs} init file. @xref{Examining, Examining and Setting
926Variables, Examining and Setting Variables, emacs, The GNU Emacs
927Manual}.
928
929@table @code
930@item Info-enable-edit
931Set to @code{nil}, disables the @samp{e} (@code{Info-edit}) command. A
932non-@code{nil} value enables it. @xref{Add, Edit}.
933
934@item Info-enable-active-nodes
935When set to a non-@code{nil} value, allows Info to execute Lisp code
936associated with nodes. The Lisp code is executed when the node is
937selected.
938
939@item Info-directory-list
940The list of directories to search for Info files. Each element is a
941string (directory name) or @code{nil} (try default directory).
942
943@item Info-directory
944The standard directory for Info documentation files. Only used when the
945function @code{Info-directory} is called.
946@end table
947
948@node Create an Info File, , Advanced Info, Top
949@comment node-name, next, previous, up
950@chapter Creating an Info File from a Makeinfo file
951
952@code{makeinfo} is a utility that converts a Texinfo file into an Info
953file; @code{texinfo-format-region} and @code{texinfo-format-buffer} are
954GNU Emacs functions that do the same.
955
956@xref{Create an Info File, , Creating an Info File, texinfo, the Texinfo
957Manual}, to learn how to create an Info file from a Texinfo file.
958
959@xref{Top,, Overview of Texinfo, texinfo, Texinfo: The GNU Documentation
960Format}, to learn how to write a Texinfo file.
961
962@nwnode Using Stand-alone Info, Options, , Top
963@chapter Using the Stand-alone Info Reader
964@lowersections
965@c Make the paragraph indentation match the rest of this file.
966@paragraphindent 2
967@include info-stnd.texi
968@raisesections
969@bye