(Fx_create_frame): Don't call Qface_set_after_frame_default.
[emacs.git] / man / info.texi
blob3d8c0f5224b420c13f8ef50667abd907560c52a2
1 \input texinfo    @c -*-texinfo-*-
2 @comment %**start of header
3 @setfilename info.info
4 @settitle Info
5 @syncodeindex fn cp
6 @syncodeindex vr cp
7 @syncodeindex ky cp
8 @comment %**end of header
9 @comment $Id: info.texi,v 1.26 2002/10/02 23:24:31 karl Exp $
11 @copying
12 This file describes how to use Info, the on-line, menu-driven GNU
13 documentation system.
15 Copyright (C) 1989, 1992, 1996, 1997, 1998, 1999, 2000, 2001, 2002
16 Free Software Foundation, Inc.
18 @quotation
19 Permission is granted to copy, distribute and/or modify this document
20 under the terms of the GNU Free Documentation License, Version 1.1 or
21 any later version published by the Free Software Foundation; with no
22 Invariant Sections, with the Front-Cover texts being ``A GNU
23 Manual'', and with the Back-Cover Texts as in (a) below.  A copy of the
24 license is included in the section entitled ``GNU Free Documentation
25 License'' in the Emacs manual.
27 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
28 this GNU Manual, like GNU software.  Copies published by the Free
29 Software Foundation raise funds for GNU development.''
31 This document is part of a collection distributed under the GNU Free
32 Documentation License.  If you want to distribute this document
33 separately from the collection, you can do so by adding a copy of the
34 license to the document, as described in section 6 of the license.
35 @end quotation
36 @end copying
38 @dircategory Texinfo documentation system
39 @direntry
40 * Info: (info).         How to use the documentation browsing system.
41 @end direntry
43 @titlepage
44 @title Info
45 @subtitle The online, hyper-text GNU documentation system
46 @author Brian Fox
47 @author and the GNU Texinfo community
48 @page
49 @vskip 0pt plus 1filll
50 @insertcopying
51 @end titlepage
53 @ifnottex
54 @node Top
55 @top Info: An Introduction
57 The GNU Project distributes most of its on-line manuals in the
58 @dfn{Info format}, which you read using an @dfn{Info reader}.  You are
59 probably using an Info reader to read this now.
61 @ifinfo
62 If you are new to the Info reader and want to learn how to use it,
63 type the command @kbd{h} now.  It brings you to a programmed
64 instruction sequence.
66 To read about expert-level Info commands, type @kbd{n} twice.  This
67 brings you to @cite{Info for Experts}, skipping over the `Getting
68 Started' chapter.
69 @end ifinfo
70 @end ifnottex
72 @menu
73 * Getting Started::             Getting started using an Info reader.
74 * Expert Info::                 Info commands for experts.
75 * Creating an Info File::       How to make your own Info file.
76 * Index::                       An index of topics, commands, and variables.
77 @end menu
79 @node Getting Started, Expert Info, Top, Top
80 @comment  node-name,  next,  previous,  up
81 @chapter Getting Started
83 This first part of the Info manual describes how to get around inside
84 of Info.  The second part of the manual describes various advanced
85 Info commands, and how to write an Info as distinct from a Texinfo
86 file.  The third part briefly explains how to generate Info files from
87 Texinfo files.
89 @ifnotinfo
90 This manual is primarily designed for browsing with an Info reader
91 program on a computer, so that you can try Info commands while reading
92 about them.  Reading it on paper or with an HTML browser is less
93 effective, since you must take it on faith that the commands described
94 really do what the manual says.  By all means go through this manual
95 now that you have it; but please try going through the on-line version
96 as well.
98 @cindex Info reader, how to invoke
99 @cindex entering Info
100 There are two ways of looking at the online version of this manual:
102 @enumerate
103 @item
104 Type @code{info} at your shell's command line.  This approach uses a
105 stand-alone program designed just to read Info files.
107 @item
108 Type @code{emacs} at the command line; then type @kbd{C-h i}
109 (@kbd{Control-h}, followed by @kbd{i}).  This approach uses the Info
110 mode of the Emacs program, an editor with many other capabilities.
111 @end enumerate
113 In either case, then type @kbd{mInfo} (just the letters), followed by
114 @key{RET}---the ``Return'' or ``Enter'' key.  At this point, you should
115 be ready to follow the instructions in this manual as you read them on
116 the screen.
117 @c FIXME! (pesch@cygnus.com, 14 dec 1992)
118 @c Is it worth worrying about what-if the beginner goes to somebody
119 @c else's Emacs session, which already has an Info running in the middle
120 @c of something---in which case these simple instructions won't work?
121 @end ifnotinfo
123 @menu
124 * Help-Small-Screen::   Starting Info on a Small Screen
125 * Help::                How to use Info
126 * Help-P::              Returning to the Previous node
127 * Help-^L::             The Space, DEL, B and ^L commands.
128 * Help-M::              Menus
129 * Help-Xref::           Following cross-references
130 * Help-Int::            Some intermediate Info commands
131 * Help-Q::              Quitting Info
132 @end menu
134 @node Help-Small-Screen
135 @section Starting Info on a Small Screen
137 @ifnotinfo
138 (In Info, you only see this section if your terminal has a small
139 number of lines; most readers pass by it without seeing it.)
140 @end ifnotinfo
142 @cindex small screen, moving around
143 Since your terminal has a relatively small number of lines on its
144 screen, it is necessary to give you special advice at the beginning.
146 If you see the text @samp{--All----} near the bottom right corner
147 of the screen, it means the entire text you are looking at fits on the
148 screen.  If you see @samp{--Top----} instead, it means that there is
149 more text below that does not fit.  To move forward through the text
150 and see another screen full, press @key{SPC}, the Space bar.  To move
151 back up, press the key labeled @samp{Backspace} or @samp{DEL} (on some
152 keyboards, this key might be labeled @samp{Delete}).
154 @ifinfo
155 Here are 40 lines of junk, so you can try @key{SPC} and @key{DEL} and
156 see what they do.  At the end are instructions of what you should do
157 next.
159 @format
160 This is line 20
161 This is line 21
162 This is line 22
163 This is line 23
164 This is line 24
165 This is line 25
166 This is line 26
167 This is line 27
168 This is line 28
169 This is line 29
170 This is line 30
171 This is line 31
172 This is line 32
173 This is line 33
174 This is line 34
175 This is line 35
176 This is line 36
177 This is line 37
178 This is line 38
179 This is line 39
180 This is line 40
181 This is line 41
182 This is line 42
183 This is line 43
184 This is line 44
185 This is line 45
186 This is line 46
187 This is line 47
188 This is line 48
189 This is line 49
190 This is line 50
191 This is line 51
192 This is line 52
193 This is line 53
194 This is line 54
195 This is line 55
196 This is line 56
197 This is line 57
198 This is line 58
199 This is line 59
200 @end format
202 If you have managed to get here, go back to the beginning with
203 @kbd{DEL} (or @key{BACKSPACE}), and come back here again, then you
204 understand the about the @samp{Space} and @samp{Backspace} keys.  So
205 now type an @kbd{n} ---just one character; don't type the quotes and
206 don't type the Return key afterward--- to get to the normal start of
207 the course.
208 @end ifinfo
210 @node Help, Help-P, Help-Small-Screen, Getting Started
211 @comment  node-name,  next,  previous,  up
212 @section How to use Info
214 You are talking to the program Info, for reading documentation.
216 @cindex node, in Info documents
217   Right now you are looking at one @dfn{Node} of Information.
218 A node contains text describing a specific topic at a specific
219 level of detail.  This node's topic is ``how to use Info''.  The mode
220 line says that this is node @samp{Help} in the file @file{info}.
222 @cindex header of Info node
223   The top line of a node is its @dfn{header}.  This node's header
224 (look at it now) says that the @samp{Next} node after this one is the
225 node called @samp{Help-P}.  An advanced Info command lets you go to
226 any node whose name you know.  In the stand-alone Info reader program,
227 the header line shows the names of this node and the info file as
228 well.  In Emacs, the header line is duplicated in a special typeface,
229 and the duplicate remains at the top of the window all the time even
230 if you scroll through the node.
232   Besides a @samp{Next}, a node can have a @samp{Previous} or an
233 @samp{Up} links, or both.  As you can see, this node has all of these
234 links.
236 @kindex n @r{(Info mode)}
237   Now it is time to move on to the @samp{Next} node, named @samp{Help-P}.
239 @format
240 >> Type @kbd{n} to move there.  Type just one character;
241    do not type the quotes and do not type a @key{RET} afterward.
242 @end format
244 @noindent
245 @samp{>>} in the margin means it is really time to try a command.
247 @format
248 >> If you are in Emacs and have a mouse, and if you already practiced
249    typing @kbd{n} to get to the next node, click now with the middle
250    mouse button on the @samp{Next} link to do the same ``the mouse way''.
251 @end format
253 @node Help-P, Help-^L, Help, Getting Started
254 @comment  node-name,  next,  previous,  up
255 @section Returning to the Previous node
257 @kindex p @r{(Info mode)}
258 This node is called @samp{Help-P}.  The @samp{Previous} node, as you see,
259 is @samp{Help}, which is the one you just came from using the @kbd{n}
260 command.  Another @kbd{n} command now would take you to the next
261 node, @samp{Help-^L}.
263 @format
264 >> But do not type @kbd{n} yet.  First, try the @kbd{p} command,
265    or click the middle mouse button on the @samp{Prev} link.  That
266    takes you to the @samp{Previous} node.  Then use @kbd{n} to return here.
267 @end format
269   If you read this in Emacs, you will see an @samp{Info} item in the
270 menu bar, close to its right edge.  Clicking the mouse on the
271 @samp{Info} menu-bar item opens a menu of commands which include
272 @samp{Next} and @samp{Prev} (and also some others which you didn't yet
273 learn about).
275   This all probably seems insultingly simple so far, but @emph{please
276 don't} start skimming.  Things will get complicated soon enough!
277 Also, please do not try a new command until you are told it is time
278 to.  You could make Info skip past an important warning that was
279 coming up.
281 @format
282 >> Now do an @kbd{n}, or click the middle mouse button on the @samp{Next}
283    link, to get to the node @samp{Help-^L} and learn more.
284 @end format
286 @node Help-^L, Help-M, Help-P, Getting Started
287 @comment  node-name,  next,  previous,  up
288 @section The Space, DEL, B and ^L commands.
290   This node's mode line tells you that you are now at node
291 @samp{Help-^L}, and the header line tells you that @kbd{p} would get
292 you back to @samp{Help-P}.  The node's title is highlighted and may be
293 underlined as well; it says what the node is about.
295   This is a big node and it does not all fit on your display screen.
296 You can tell that there is more that is not visible because you
297 can see the string @samp{--Top-----} rather than @samp{--All----} near
298 the bottom right corner of the screen.
300 @kindex SPC @r{(Info mode)}
301 @kindex DEL @r{(Info mode)}
302 @kindex BACKSPACE @r{(Info mode)}
303 @findex Info-scroll-up
304 @findex Info-scroll-down
305   The @key{SPC}, @key{BACKSPACE} (or @key{DEL})@footnote{The key which
306 we call ``Backspace or DEL'' in this manual is labeled differently on
307 different keyboards.  Look for a key which is a little ways above the
308 @key{ENTER} or @key{RET} key and which you normally use outside Emacs
309 to erase the character before the cursor, i.e.@: the character you
310 typed last.  It might be labeled @samp{Backspace} or @samp{<-} or
311 @samp{DEL}, or sometimes @samp{Delete}.} and @kbd{b} commands exist to
312 allow you to ``move around'' in a node that does not all fit on the
313 screen at once.  @key{SPC} moves forward, to show what was below the
314 bottom of the screen.  @key{DEL} or @key{BACKSPACE} moves backward, to
315 show what was above the top of the screen (there is not anything above
316 the top until you have typed some spaces).
318 @format
319 >> Now try typing a @key{SPC} (afterward, type a @key{BACKSPACE} to
320    return here).
321 @end format
323   When you type the @key{SPC}, the two lines that were at the bottom of
324 the screen appear at the top, followed by more lines.  @key{DEL} or
325 @key{BACKSPACE} takes the two lines from the top and moves them to the
326 bottom, @emph{usually}, but if there are not a full screen's worth of
327 lines above them they may not make it all the way to the bottom.
329   If you are reading this in Emacs, note that the header line is
330 always visible, never scrolling off the display.  That way, you can
331 always see the @samp{Next}, @samp{Prev}, and @samp{Up} links, and you
332 can conveniently go to one of these links at any time by
333 clicking the middle mouse button on the link.
335 @cindex reading Info documents top to bottom
336 @cindex Info documents as tutorials
337   @key{SPC} and @key{DEL} not only move forward and backward through
338 the current node.  They also move between nodes.  @key{SPC} at the end
339 of a node moves to the next node; @key{DEL} (or @key{BACKSPACE}) at
340 the beginning of a node moves to the previous node.  In effect, these
341 commands scroll through all the nodes in an Info file as a single
342 logical sequence.  You can read an entire manual top to bottom by just
343 typing @key{SPC}, and move backward through the entire manual from
344 bottom to top by typing @key{DEL} (or @key{BACKSPACE}).
346   In this sequence, a node's subnodes appear following their parent.
347 If a node has a menu, @key{SPC} takes you into the subnodes listed in
348 the menu, one by one.  Once you reach the end of a node, and have seen
349 all of its subnodes, @key{SPC} takes you to the next node or to the
350 parent's next node.
352 @kindex PAGEUP @r{(Info mode)}
353 @kindex PAGEDOWN @r{(Info mode)}
354   Many keyboards nowadays have two scroll keys labeled @samp{PageUp}
355 and @samp{PageDown} (or maybe @samp{Prior} and @samp{Next}).  If your
356 keyboard has these keys, you can use them to move forward and backward
357 through the text of one node, like @key{SPC} and @key{BACKSPACE} (or
358 @key{DEL}).  However, @key{PAGEUP} and @key{PAGEDOWN} keys never
359 scroll beyond the beginning or the end of the current node.
361 @kindex C-l @r{(Info mode)}
362   If your screen is ever garbaged, you can tell Info to display it
363 again by typing @kbd{C-l} (@kbd{Control-L}, that is---hold down
364 @key{CTRL} and type @kbd{L} or @kbd{l}).
366 @format
367 >> Type @kbd{C-l} now.
368 @end format
370 @kindex b @r{(Info mode)}
371   To move back to the beginning of the node you are on, you can type
372 the @key{BACKSPACE} key (or @key{DEL}) many times.  You can also type
373 @kbd{b} just once.  @kbd{b} stands for ``beginning.''
375 @format
376 >> Try that now.  (We have put in enough verbiage to push this past
377    the first screenful, but screens are so big nowadays that perhaps it
378    isn't enough.  You may need to shrink your Emacs or Info window.)
379    Then come back, by typing @key{SPC} one or more times.
380 @end format
382   If your screen is very tall, all of this node might fit at once.  In
383 that case, @kbd{b} won't do anything.  But you could observe the
384 effect of the @kbd{b} key if you use a smaller window.
386 @kindex ? @r{(Info mode)}
387 @findex Info-summary
388   You have just learned a considerable number of commands.  If you
389 want to use one but have trouble remembering which, you should type
390 a @kbd{?} (in Emacs it runs the @code{Info-summary} command) which
391 displays a brief list of commands.  When you are finished looking at
392 the list, make it go away by typing a @key{SPC} repeatedly.
394 @format
395 >> Type a @key{?} now.  Press @key{SPC} to see consecutive screenfuls of
396    the list until finished.  Then type @key{SPC} several times.  If
397    you are using Emacs, the help will then go away automatically.
398 @end format
400   (If you are using the stand-alone Info reader, type @kbd{C-x 0} to
401 return here, that is---press and hold @key{CTRL}, type an @kbd{x},
402 then release @key{CTRL} and @kbd{x}, and press @kbd{0}---a zero, not
403 the letter ``o''.)
405   From now on, you will encounter large nodes without warning, and
406 will be expected to know how to use @key{SPC} and @key{BACKSPACE} to
407 move around in them without being told.  Since not all terminals have
408 the same size screen, it would be impossible to warn you anyway.
410 @format
411 >> Now type @kbd{n}, or click the middle mouse button on the @samp{Next} link,
412    to see the description of the @kbd{m} command.
413 @end format
415 @node Help-M, Help-Xref, Help-^L, Getting Started
416 @comment  node-name,  next,  previous,  up
417 @section Menus and the @kbd{m} command
419 @cindex menus in an Info document
420 @cindex Info menus
421   With only the @kbd{n} (next) and @kbd{p} (previous) commands for
422 moving between nodes, nodes are restricted to a linear sequence.
423 Menus allow a branching structure.  A menu is a list of other nodes
424 you can move to.  It is actually just part of the text of the node
425 formatted specially so that Info can interpret it.  The beginning of a
426 menu is always identified by a line which starts with @samp{* Menu:}.
427 A node contains a menu if and only if it has a line in it which starts
428 that way.  The only menu you can use at any moment is the one in the
429 node you are in.  To use a menu in any other node, you must move to
430 that node first.
432   After the start of the menu, each line that starts with a @samp{*}
433 identifies one subtopic.  The line usually contains a brief name
434 for the subtopic (followed by a @samp{:}), the name of the node that talks
435 about that subtopic, and optionally some further description of the
436 subtopic.  Lines in the menu that do not start with a @samp{*} have no
437 special meaning---they are only for the human reader's benefit and do
438 not define additional subtopics.  Here is an example:
440 @example
441 * Foo:  Node about FOO.      This tells about FOO.
442 @end example
444 The subtopic name is Foo, and the node describing it is @samp{Node
445 about FOO}.  The rest of the line is just for the reader's
446 Information.  [[ But this line is not a real menu item, simply because
447 there is no line above it which starts with @samp{* Menu:}.]]
449   When you use a menu to go to another node (in a way that will be
450 described soon), what you specify is the subtopic name, the first
451 thing in the menu line.  Info uses it to find the menu line, extracts
452 the node name from it, and goes to that node.  The reason that there
453 is both a subtopic name and a node name is that the node name must be
454 meaningful to the computer and may therefore have to be ugly looking.
455 The subtopic name can be chosen just to be convenient for the user to
456 specify.  Often the node name is convenient for the user to specify
457 and so both it and the subtopic name are the same.  There is an
458 abbreviation for this:
460 @example
461 * Foo::   This tells about FOO.
462 @end example
464 @noindent
465 This means that the subtopic name and node name are the same; they are
466 both @samp{Foo}.
468 @format
469 >> Now use @key{SPC} to find the menu in this node, then come back to
470    the front with a @kbd{b} and some @key{SPC}s.  As you see, a menu is
471    actually visible in its node.  If you cannot find a menu in a node
472    by looking at it, then the node does not have a menu and the
473    @kbd{m} command is not available.
474 @end format
476 If you keep typing @key{SPC} once the menu appears on the screen, it
477 will move to another node (the first one in the menu).  If that
478 happens, type @key{BACKSPACE} to come back.
480 @kindex m @r{(Info mode)}
481   The command to go to one of the subnodes is @kbd{m}.  This is very
482 different from the commands you have used: it is a command that
483 prompts you for more input.
485   The Info commands you know do not need additional input; when you
486 type one of them, Info processes it instantly and then is ready for
487 another command.  The @kbd{m} command is different: it needs to know
488 the @dfn{name of the subtopic}.  Once you have typed @kbd{m}, Info
489 tries to read the subtopic name.
491   Now look for the line containing many dashes near the bottom of the
492 screen.  There is one more line beneath that one, but usually it is
493 blank.  When it is blank, Info is ready for a command, such as @kbd{n}
494 or @kbd{b} or @key{SPC} or @kbd{m}.  If that line contains text ending
495 in a colon, it means Info is reading more input for the last command.
496 You can't type an Info command then, because Info is trying to read
497 input, not commands.  You must either give the input and finish the
498 command you started, or type @kbd{Control-g} to cancel the command.
499 When you have done one of those things, the input entry line becomes
500 blank again.  Then you can type Info commands again.
502 @findex Info-menu
503   The command to go to a subnode via a menu is @kbd{m}.  After you type
504 the @kbd{m}, the line at the bottom of the screen says @samp{Menu item: }.
505 You must then type the name of the subtopic you want, and end it with
506 a @key{RET}.  In Emacs, @kbd{m} runs the command @code{Info-menu}.
508 @cindex abbreviating Info subnodes
509   You can abbreviate the subtopic name.  If the abbreviation is not
510 unique, the first matching subtopic is chosen.  Some menus put
511 the shortest possible abbreviation for each subtopic name in capital
512 letters, so you can see how much you need to type.  It does not
513 matter whether you use upper case or lower case when you type the
514 subtopic.  You should not put any spaces at the end, or inside of the
515 item name, except for one space where a space appears in the item in
516 the menu.
518 @cindex completion of Info node names
519   You can also use the @dfn{completion} feature to help enter the
520 subtopic name.  If you type the @key{TAB} key after entering part of a
521 name, it will fill in more of the name---as much as Info can deduce
522 from the part you have entered.
524   If you move the cursor to one of the menu subtopic lines, then you do
525 not need to type the argument: you just type a @key{RET}, and it
526 stands for the subtopic of the line you are on.  You can also click
527 the middle mouse button directly on the subtopic line to go there.
529 Here is a menu to give you a chance to practice.  This menu gives you
530 three ways of going to one place, Help-FOO:
532 @menu
533 * Foo:  Help-FOO.       A node you can visit for fun.
534 * Bar:  Help-FOO.       We have made two ways to get to the same place.
535 * Help-FOO::            And yet another!
536 @end menu
538 @format
539 >>  Now type just an @kbd{m} and see what happens:
540 @end format
542   Now you are ``inside'' an @kbd{m} command.  Commands cannot be used
543 now; the next thing you will type must be the name of a subtopic.
545   You can change your mind about doing the @kbd{m} by typing
546 @kbd{Control-g}.
548 @format
549 >> Try that now;  notice the bottom line clear.
550 @end format
552 @format
553 >> Then type another @kbd{m}.
554 @end format
556 @format
557 >> Now type @kbd{BAR}, the item name.  Do not type @key{RET} yet.
558 @end format
560   While you are typing the item name, you can use the @key{DEL} (or
561 @key{BACKSPACE}) key to cancel one character at a time if you make a
562 mistake.
564 @format
565 >> Press @key{DEL} to cancel the @samp{R}.  You could type another @kbd{R}
566    to replace it.  But you do not have to, since @samp{BA} is a valid
567    abbreviation.
568 @end format
570 @format
571 >> Now you are ready to go.  Type a @key{RET}.
572 @end format
574   After visiting @samp{Help-FOO}, you should return here.
576   Another way to move to the menu subtopic lines and between them is
577 to type @key{TAB}.  Each time you type a @key{TAB}, you move to the
578 next subtopic line.  To move to a previous subtopic line, type
579 @kbd{M-@key{TAB}}---that is, press and hold the @key{META} key and then
580 press @key{TAB}.  (On some keyboards, the @key{META} key might be labeled
581 @samp{Alt}.)
583   Once you move cursor to a subtopic line, press @key{RET} to go to
584 that subtopic's node.
586 @cindex mouse support in Info mode
587 @kindex Mouse-2 @r{(Info mode)}
588   If your terminal supports a mouse, you have yet another way of going
589 to a subtopic.  Move your mouse pointer to the subtopic line,
590 somewhere between the beginning @samp{*} and the colon @samp{:} which
591 ends the subtopic's brief name.  You will see the subtopic's name
592 change its appearance (usually, its background color will change), and
593 the shape of the mouse pointer will change if your platform supports
594 that.  After a while, if you leave the mouse on that spot, a small
595 window will pop up, saying ``Mouse-2: go to that node'', or the same
596 message may appear at the bottom of the screen.
598   @kbd{Mouse-2} is the second button of your mouse counting from the
599 left---the middle button on a 3-button mouse.  (On a 2-button mouse,
600 you may have to press both buttons together to ``press the middle
601 button''.)  The message tells you pressing @kbd{Mouse-2} with the
602 current position of the mouse pointer (on subtopic in the menu) will
603 go to that subtopic.
605 @findex Info-mouse-follow-nearest-node
606   More generally, @kbd{Mouse-2} in an Info buffer finds the nearest
607 link to another node and goes there.  For example, near a cross
608 reference it acts like @kbd{f}, in a menu it acts like @kbd{m}, on the
609 node's header line it acts like @kbd{n}, @kbd{p}, or @kbd{u}, etc.  At
610 end of the node's text @kbd{Mouse-2} moves to the next node, or up if
611 there's no next node.
613   Here is another way to get to Help-FOO, a menu.  You can ignore this
614 if you want, or else try it by typing @key{TAB} and then @key{RET}, or
615 clicking @kbd{Mouse-2} on it (but then please come back to here).
617 @menu
618 * Help-FOO::
619 @end menu
621 @format
622 >> Type @kbd{n} to see more commands.
623 @end format
625 @node Help-FOO,  ,  , Help-M
626 @subsection The @kbd{u} command
628   Congratulations!  This is the node @samp{Help-FOO}.  It has an @samp{Up}
629 pointer @samp{Help-M}, the node you just came from via the @kbd{m}
630 command.  This is the usual convention---the nodes you reach from a menu
631 have @samp{Up} nodes that lead back to the menu.  Menus move Down in the
632 tree, and @samp{Up} moves Up.  @samp{Previous}, on the other hand, is
633 usually used to ``stay on the same level but go backwards''.
635 @kindex u @r{(Info mode)}
636 @findex Info-up
637   You can go back to the node @samp{Help-M} by typing the command
638 @kbd{u} for ``Up'' (the Emacs command run by @kbd{u} is
639 @code{Info-up}).  That puts you at the @emph{front} of the node---to
640 get back to where you were reading you have to type some @key{SPC}s.
641 (Some Info readers, such as the one built into Emacs, put you at the
642 same place where you were reading in @samp{Help-M}.)
644   Another way to go Up is to click @kbd{Mouse-2} on the @samp{Up}
645 pointer shown in the header line (provided that you have a mouse).
647 @format
648 >> Now type @kbd{u} to move back up to @samp{Help-M}.
649 @end format
651 @node Help-Xref, Help-Int, Help-M, Getting Started
652 @comment  node-name,  next,  previous,  up
653 @section Following Cross-References
655 @cindex cross references in Info documents
656   In Info documentation, you will see many @dfn{cross references}.
657 Cross references look like this: @xref{Help-Cross, Cross}.  That text
658 is a real, live cross reference, whose name is @samp{Cross} and which
659 points to the node named @samp{Help-Cross}.
661 @kindex f @r{(Info mode)}
662 @findex Info-follow-reference
663   There are two ways to follow a cross reference.  You can move the
664 cursor to it and press @key{RET}, just as in a menu.  @key{RET}
665 follows the cross reference that the cursor is on.  Or you can type
666 @kbd{f} and then specify the name of the cross reference (in this
667 case, @samp{Cross}) as an argument.  In Emacs Info, @kbd{f} runs
668 @code{Info-follow-reference},
670   In the @kbd{f} command, you select the cross reference with its
671 name, so it does not matter where the cursor was.  If the cursor is on
672 or near a cross reference, @kbd{f} suggests that reference name in
673 parentheses as the default; typing @key{RET} will follow that
674 reference.  However, if you type a different reference name, @kbd{f}
675 will follow the other reference which has that name.
677 @format
678 >> Type @kbd{f}, followed by @kbd{Cross}, and then @key{RET}.
679 @end format
681   As you enter the reference name, you can use the @key{DEL} (or
682 @key{BACKSPACE}) key to edit your input.  If you change your mind
683 about following any reference, you can use @kbd{Control-g} to cancel
684 the command.  Completion is available in the @kbd{f} command; you can
685 complete among all the cross reference names in the current node by
686 typing a @key{TAB}.
688   To get a list of all the cross references in the current node, you
689 can type @kbd{?} after an @kbd{f}.  The @kbd{f} continues to await a
690 cross reference name even after displaying the list, so if you don't
691 actually want to follow a reference, you should type a @kbd{Control-g}
692 to cancel the @kbd{f}.
694 @format
695 >> Type @kbd{f?} to get a list of the cross references in this node.  Then
696    type a @kbd{Control-g} and see how the @samp{f} gives up.
697 @end format
699   The @key{TAB} and @kbd{M-@key{TAB}} key, which move between menu
700 items in a menu, also move between cross references outside of menus.
702 @node Help-Int, Help-Q, Help-Xref, Getting Started
703 @comment  node-name,  next,  previous,  up
704 @section Some intermediate Info commands
706   The introductory course is almost over; please continue
707 a little longer to learn some intermediate-level commands.
709   Most Info files have an index, which is actually a large node that
710 contains nothing but a menu.  The menu has one menu item for each
711 topic listed in the index.  You can find the index node from the main
712 menu of the file, with the @kbd{m} command; then you can use the
713 @kbd{m} command again in the index node to go to the node that
714 describes the topic.
716   There is also a short-cut Info command, @kbd{i}, which does all of
717 that for you.  It searches the index for a given topic (a string) and
718 goes to the node which is listed in the index for that topic.
719 @xref{Info Search}, for a full explanation.
721 @kindex l @r{(Info mode)}
722 @findex Info-last
723 @cindex going back in Info mode
724   If you have been moving around to different nodes and wish to
725 retrace your steps, the @kbd{l} command (@kbd{l} for @dfn{last}) will
726 do that, one node-step at a time.  As you move from node to node, Info
727 records the nodes where you have been in a special history list.  The
728 @kbd{l} command revisits nodes in the history list; each successive
729 @kbd{l} command moves one step back through the history.
731   If you have been following directions, an @kbd{l} command now will get
732 you back to @samp{Help-M}.  Another @kbd{l} command would undo the
733 @kbd{u} and get you back to @samp{Help-FOO}.  Another @kbd{l} would undo
734 the @kbd{m} and get you back to @samp{Help-M}.
736   In Emacs, @kbd{l} runs the command @code{Info-last}.
738 @format
739 >> Try typing three @kbd{l}'s, pausing in between to see what each
740    @kbd{l} does.  Then follow directions again and you will end up
741    back here.
742 @end format
744   Note the difference between @kbd{l} and @kbd{p}: @kbd{l} moves to
745 where @emph{you} last were, whereas @kbd{p} always moves to the node
746 which the header says is the @samp{Previous} node (from this node, the
747 @samp{Prev} link leads to @samp{Help-M}).
749 @kindex d @r{(Info mode)}
750 @findex Info-directory
751 @cindex go to Directory node
752   The @kbd{d} command (@code{Info-directory} in Emacs) gets you
753 instantly to the Directory node.  This node, which is the first one
754 you saw when you entered Info, has a menu which leads (directly or
755 indirectly, through other menus), to all the nodes that exist.  The
756 Directory node lists all the manuals and other Info documents that
757 are, or could be, installed on your system.
759 @format
760 >> Try doing a @kbd{d}, then do an @kbd{l} to return here (yes,
761    @emph{do} return).
762 @end format
764 @kindex t @r{(Info mode)}
765 @findex Info-top-node
766 @cindex go to Top node
767   The @kbd{t} command moves to the @samp{Top} node of the manual.
768 This is useful if you want to browse the manual's main menu, or select
769 some specific top-level menu item.  The Emacs command run by @kbd{t}
770 is @code{Info-top-node}.
772   Clicking @kbd{Mouse-2} on or near a cross reference also follows the
773 reference.  You can see that the cross reference is mouse-sensitive by
774 moving the mouse pointer to the reference and watching how the
775 underlying text and the mouse pointer change in response.
777 @format
778 >> Now type @kbd{n} to see the last node of the course.
779 @end format
781   @xref{Expert Info}, for more advanced Info features.
783 @c If a menu appears at the end of this node, remove it.
784 @c It is an accident of the menu updating command.
786 @node Expert Info
787 @chapter Info for Experts
789   This chapter describes various Info commands for experts.  (If you
790 are using a stand-alone Info reader, there are additional commands
791 specific to it, which are documented in several chapters of @ref{Top,,
792 GNU Info, info-stnd, GNU Info}.)
794   This chapter also explains how to write an Info as distinct from a
795 Texinfo file.  (However, in most cases, writing a Texinfo file is
796 better, since you can use it to make a printed manual or produce other
797 formats, such as HTML and DocBook, as well as for generating Info
798 files.)  @xref{Top,, Overview of Texinfo, texinfo, Texinfo: The GNU
799 Documentation Format}.)
801 @menu
802 * Advanced::             Advanced Info commands: g, s, e, and 1 - 5.
803 * Info Search::          How to search Info documents for specific subjects.
804 * Add::                  Describes how to add new nodes to the hierarchy.
805                            Also tells what nodes look like.
806 * Menus::                How to add to or create menus in Info nodes.
807 * Cross-refs::           How to add cross-references to Info nodes.
808 * Tags::                 How to make tags tables for Info files.
809 * Checking::             Checking an Info File
810 * Emacs Info Variables:: Variables modifying the behavior of Emacs Info.
811 @end menu
813 @node Advanced, Info Search,  , Expert Info
814 @comment  node-name,  next,  previous,  up
815 @section Advanced Info Commands
817 Here are some more Info commands that make it easier to move around.
819 @unnumberedsubsec @kbd{g} goes to a node by name
821 @kindex g @r{(Info mode)}
822 @findex Info-goto-node
823 @cindex go to a node by name
824   If you know a node's name, you can go there by typing @kbd{g}, the
825 name, and @key{RET}.  Thus, @kbd{gTop@key{RET}} would go to the node
826 called @samp{Top} in this file.  (This is equivalent to @kbd{t}, see
827 @ref{Help-Int}.)  @kbd{gAdvanced@key{RET}} would come back here.
828 @kbd{g} in Emacs runs the command @code{Info-goto-node}.
830   Unlike @kbd{m}, @kbd{g} does not allow the use of abbreviations.
831 But it does allow completion, so you can type @key{TAB} to complete a
832 partial node name.
834 @cindex go to another Info file
835   To go to a node in another file, you can include the file name in the
836 node name by putting it at the front, in parentheses.  Thus,
837 @kbd{g(dir)Top@key{RET}} would go to the Info Directory node, which is
838 the node @samp{Top} in the Info file @file{dir}.  Likewise,
839 @kbd{g(emacs)Top@key{RET}} goes to the top node of the Emacs manual.
841   The node name @samp{*} specifies the whole file.  So you can look at
842 all of the current file by typing @kbd{g*@key{RET}} or all of any
843 other file with @kbd{g(@var{filename})@key{RET}}.
845 @unnumberedsubsec @kbd{1} -- @kbd{9} choose a menu subtopic by its number
847 @kindex 1 @r{through} 9 @r{(Info mode)}
848 @findex Info-nth-menu-item
849 @cindex select @var{n}'th menu item
850   If you begrudge each character of type-in which your system requires,
851 you might like to use the commands @kbd{1}, @kbd{2}, @kbd{3}, @kbd{4},
852 @dots{}, @kbd{9}.  They are short for the @kbd{m} command together
853 with a name of a menu subtopic.  @kbd{1} goes through the first item
854 in the current node's menu; @kbd{2} goes through the second item, etc.
855 In the stand-alone reader, @kbd{0} goes through the last menu item;
856 this is so you need not count how many entries are there.  In Emacs,
857 the digit keys run the command @code{Info-nth-menu-item}.
859   If your display supports multiple fonts, and you are using Emacs'
860 Info mode to read Info files, the @samp{*} for the fifth menu item
861 stands out, either in color or in some other attribute, such as
862 underline, and so is the @samp{*} for the ninth item; this makes it
863 easy to see at a glance which number to use for an item.
865   Some terminals don't support colors or underlining.  If you need to
866 actually count items, it is better to use @kbd{m} instead, and specify
867 the name, or use @key{TAB} to quickly move between menu items.
869 @unnumberedsubsec @kbd{e} makes Info document editable
871 @kindex e @r{(Info mode)}
872 @findex Info-edit
873 @cindex edit Info document
874   The Info command @kbd{e} changes from Info mode to an ordinary
875 Emacs editing mode, so that you can edit the text of the current node.
876 Type @kbd{C-c C-c} to switch back to Info.  The @kbd{e} command is allowed
877 only if the variable @code{Info-enable-edit} is non-@code{nil}.
879   The @kbd{e} command only works in Emacs, where it runs the command
880 @code{Info-edit}.  The stand-alone Info reader doesn't allow you to
881 edit the Info file, so typing @kbd{e} there goes to the end of the
882 current node.
884 @node Info Search, Add, Advanced, Expert Info
885 @comment  node-name,  next,  previous,  up
886 @section How to search Info documents for specific subjects
888 @cindex searching Info documents
889 @cindex Info document as a reference
890   The commands which move between and inside nodes allow you to read
891 the entire manual or its large portions.  But what if you need to find
892 some information in the manual as fast as you can, and you don't know
893 or don't remember in what node to look for it?  This need arises when
894 you use a manual as a @dfn{reference}, or when it is impractical to
895 read the entire manual before you start using the programs it
896 describes.
898   Info has powerful searching facilities that let you find things
899 quickly.  You can search either the manual indices or its text.
901 @kindex i @r{(Info mode)}
902 @findex Info-index
903   Since most subjects related to what the manual describes should be
904 indexed, you should try the index search first.  The @kbd{i} command
905 prompts you for a subject and then looks up that subject in the
906 indices.  If it finds an index entry with the subject you typed, it
907 goes to the node to which that index entry points.  You should browse
908 through that node to see whether the issue you are looking for is
909 described there.  If it isn't, type @kbd{,} one or more times to go
910 through additional index entries which match your subject.
912   The @kbd{i} command finds all index entries which include the string
913 you typed @emph{as a substring}.  For each match, Info shows in the
914 echo area the full index entry it found.  Often, the text of the full
915 index entry already gives you enough information to decide whether it
916 is relevant to what you are looking for, so we recommend that you read
917 what Emacs shows in the echo are before looking at the node it
918 displays.
920   Since @kbd{i} looks for a substring, you can search for subjects even
921 if you are not sure how they are spelled in the index.  For example,
922 suppose you want to find something that is pertinent to commands which
923 complete partial input (e.g., when you type @key{TAB}).  If you want
924 to catch index entries that refer to ``complete'', ``completion'', and
925 ``completing'', you could type @kbd{icomplet@key{RET}}.
927   Info documents which describe programs should index the commands,
928 options, and key sequences that the program provides.  If you are
929 looking for a description of a command, an option, or a key, just type
930 their names when @kbd{i} prompts you for a topic.  For example, if you
931 want to read the description of what the @kbd{C-f} key does, type
932 @kbd{iC-f@key{RET}}.  Here @kbd{C-f} are 3 literal characters
933 @samp{C}, @samp{-}, and @samp{f}, not the ``Control-f'' command key
934 you type inside Emacs to run the command bound to @kbd{C-f}.
936   In Emacs, @kbd{i} runs the command @code{Info-index}.
938 @kindex s @r{(Info mode)}
939 @findex Info-search
940   The @kbd{s} command allows you to search a whole file for a string.
941 It switches to the next node if and when that is necessary.  You
942 type @kbd{s} followed by the string to search for, terminated by
943 @key{RET}.  To search for the same string again, just @kbd{s} followed
944 by @key{RET} will do.  The file's nodes are scanned in the order
945 they are in in the file, which has no necessary relationship to the
946 order that they may be in the tree structure of menus and @samp{next}
947 pointers.  But normally the two orders are not very different.  In any
948 case, you can always do a @kbd{b} to find out what node you have
949 reached, if the header is not visible (this can happen, because @kbd{s}
950 puts your cursor at the occurrence of the string, not at the beginning
951 of the node).
953 @kindex M-s @r{(Info mode)}
954   In Emacs, @kbd{Meta-s} is equivalent to @kbd{s}.  That is for
955 compatibility with other GNU packages that use @kbd{M-s} for a similar
956 kind of search command.  Both @kbd{s} and @kbd{M-s} run in Emacs the
957 command @code{Info-search}.
960 @node Add, Menus, Info Search, Expert Info
961 @comment  node-name,  next,  previous,  up
962 @section Adding a new node to Info
964 To add a new topic to the list in the Info directory, you must:
966 @enumerate
967 @item
968 Create some nodes, in some file, to document that topic.
969 @item
970 Put that topic in the menu in the directory.  @xref{Menus, Menu}.
971 @end enumerate
973   Usually, the way to create the nodes is with Texinfo (@pxref{Top,,
974 Overview of Texinfo, texinfo, Texinfo: The GNU Documentation Format});
975 this has the advantage that you can also make a printed manual or HTML
976 from them.  You would use the @samp{@@dircategory} and
977 @samp{@@direntry} commands to put the manual into the Info directory.
978 However, if you want to edit an Info file manually and install it
979 manually, here is how.
981 @cindex node delimiters
982   The new node can live in an existing documentation file, or in a new
983 one.  It must have a @samp{^_} character before it (invisible to the
984 user; this node has one but you cannot see it), and it ends with either
985 a @samp{^_}, a @samp{^L} (``formfeed''), or the end of file.@footnote{If
986 you put in a @samp{^L} to end a new node, be sure that there is a
987 @samp{^_} after it to start the next one, since @samp{^L} cannot
988 @emph{start} a node.  Also, a nicer way to make a node boundary be a
989 page boundary as well is to put a @samp{^L} @emph{right after} the
990 @samp{^_}.}
992   The @samp{^_} starting a node must be followed by a newline or a
993 @samp{^L} newline, after which comes the node's header line.  The
994 header line must give the node's name (by which Info finds it), and
995 state the names of the @samp{Next}, @samp{Previous}, and @samp{Up}
996 nodes (if there are any).  As you can see, this node's @samp{Up} node
997 is the node @samp{Expert Info}.  The @samp{Next} node is @samp{Menus}.
999 @cindex node header line format
1000 @cindex format of node headers
1001   The keywords @dfn{Node}, @dfn{Next}, @dfn{Previous}, and @dfn{Up}
1002 may appear in any order, anywhere in the header line, but the
1003 recommended order is the one in this sentence.  Each keyword must be
1004 followed by a colon, spaces and tabs, and then the appropriate name.
1005 The name may be terminated with a tab, a comma, or a newline.  A space
1006 does not end it; node names may contain spaces.  The case of letters
1007 in the names is insignificant.
1009 @cindex node name format
1010 @cindex Directory node
1011   A node name has two forms.  A node in the current file is named by
1012 what appears after the @samp{Node: } in that node's first line.  For
1013 example, this node's name is @samp{Add}.  A node in another file is
1014 named by @samp{(@var{filename})@var{node-within-file}}, as in
1015 @samp{(info)Add} for this node.  If the file name starts with ``./'',
1016 then it is relative to the current directory; otherwise, it is
1017 relative starting from the standard directory for Info files of your
1018 site.  The name @samp{(@var{filename})Top} can be abbreviated to just
1019 @samp{(@var{filename})}.  By convention, the name @samp{Top} is used
1020 for the ``highest'' node in any single file---the node whose @samp{Up}
1021 points out of the file.  The @samp{Directory} node is @file{(dir)}, it
1022 points to a file @file{dir} which holds a large menu listing all the
1023 Info documents installed on your site.  The @samp{Top} node of a
1024 document file listed in the @samp{Directory} should have an @samp{Up:
1025 (dir)} in it.
1027 @cindex unstructured documents
1028   The node name @kbd{*} is special: it refers to the entire file.
1029 Thus, @kbd{g*} shows you the whole current file.  The use of the
1030 node @kbd{*} is to make it possible to make old-fashioned,
1031 unstructured files into nodes of the tree.
1033   The @samp{Node:} name, in which a node states its own name, must not
1034 contain a file name, since when Info searches for a node, it does not
1035 expect a file name to be there.  The @samp{Next}, @samp{Previous} and
1036 @samp{Up} names may contain them.  In this node, since the @samp{Up}
1037 node is in the same file, it was not necessary to use one.
1039   Note that the nodes in this file have a file name in the header
1040 line.  The file names are ignored by Info, but they serve as comments
1041 to help identify the node for the user.
1043 @node Menus, Cross-refs, Add, Expert Info
1044 @comment  node-name,  next,  previous,  up
1045 @section How to Create Menus
1047   Any node in the Info hierarchy may have a @dfn{menu}---a list of subnodes.
1048 The @kbd{m} command searches the current node's menu for the topic which it
1049 reads from the terminal.
1051 @cindex menu and menu entry format
1052   A menu begins with a line starting with @samp{* Menu:}.  The rest of the
1053 line is a comment.  After the starting line, every line that begins
1054 with a @samp{* } lists a single topic.  The name of the topic--what
1055 the user must type at the @kbd{m}'s command prompt to select this
1056 topic---comes right after the star and space, and is followed by a
1057 colon, spaces and tabs, and the name of the node which discusses that
1058 topic.  The node name, like node names following @samp{Next}, @samp{Previous}
1059 and @samp{Up}, may be terminated with a tab, comma, or newline; it may also
1060 be terminated with a period.
1062   If the node name and topic name are the same, then rather than
1063 giving the name twice, the abbreviation @samp{* @var{name}::} may be
1064 used (and should be used, whenever possible, as it reduces the visual
1065 clutter in the menu).
1067   It is considerate to choose the topic names so that they differ
1068 from each other very near the beginning---this allows the user to type
1069 short abbreviations.  In a long menu, it is a good idea to capitalize
1070 the beginning of each item name which is the minimum acceptable
1071 abbreviation for it (a long menu is more than 5 or so entries).
1073   The nodes listed in a node's menu are called its ``subnodes'', and it
1074 is their ``superior''.  They should each have an @samp{Up:} pointing at
1075 the superior.  It is often useful to arrange all or most of the subnodes
1076 in a sequence of @samp{Next} and @samp{Previous} pointers so that
1077 someone who wants to see them all need not keep revisiting the Menu.
1079   The Info Directory is simply the menu of the node @samp{(dir)Top}---that
1080 is, node @samp{Top} in file @file{.../info/dir}.  You can put new entries
1081 in that menu just like any other menu.  The Info Directory is @emph{not} the
1082 same as the file directory called @file{info}.  It happens that many of
1083 Info's files live in that file directory, but they do not have to; and
1084 files in that directory are not automatically listed in the Info
1085 Directory node.
1087   Also, although the Info node graph is claimed to be a ``hierarchy'',
1088 in fact it can be @emph{any} directed graph.  Shared structures and
1089 pointer cycles are perfectly possible, and can be used if they are
1090 appropriate to the meaning to be expressed.  There is no need for all
1091 the nodes in a file to form a connected structure.  In fact, this file
1092 has two connected components.  You are in one of them, which is under
1093 the node @samp{Top}; the other contains the node @samp{Help} which the
1094 @kbd{h} command goes to.  In fact, since there is no garbage
1095 collector, nothing terrible happens if a substructure is not pointed
1096 to, but such a substructure is rather useless since nobody can
1097 ever find out that it exists.
1099 @node Cross-refs, Tags, Menus, Expert Info
1100 @comment  node-name,  next,  previous,  up
1101 @section Creating Cross References
1103 @cindex cross reference format
1104   A cross reference can be placed anywhere in the text, unlike a menu
1105 item which must go at the front of a line.  A cross reference looks
1106 like a menu item except that it has @samp{*note} instead of @samp{*}.
1107 It @emph{cannot} be terminated by a @samp{)}, because @samp{)}'s are
1108 so often part of node names.  If you wish to enclose a cross reference
1109 in parentheses, terminate it with a period first.  Here are two
1110 examples of cross references pointers:
1112 @example
1113 *Note details: commands.  (See *note 3: Full Proof.)
1114 @end example
1116 @noindent
1117 @emph{These are just examples.}  The places they ``lead to'' do not
1118 really exist!
1120 @menu
1121 * Help-Cross::                  Target of a cross-reference.
1122 @end menu
1125 @node Help-Cross,  ,  , Cross-refs
1126 @subsection The node reached by the cross reference in Info
1128   This is the node reached by the cross reference named @samp{Cross}.
1130   While this node is specifically intended to be reached by a cross
1131 reference, most cross references lead to nodes that ``belong''
1132 someplace else far away in the structure of an Info document.  So you
1133 cannot expect this node to have a @samp{Next}, @samp{Previous} or
1134 @samp{Up} links pointing back to where you came from.  In general, the
1135 @kbd{l} (el) command is the only way to get back there.
1137 @format
1138 >> Type @kbd{l} to return to the node where the cross reference was.
1139 @end format
1141 @node Help-Q,  , Help-Int, Getting Started
1142 @comment  node-name,  next,  previous,  up
1143 @section Quitting Info
1145 @kindex q @r{(Info mode)}
1146 @findex Info-exit
1147 @cindex quitting Info mode
1148   To get out of Info, back to what you were doing before, type @kbd{q}
1149 for @dfn{Quit}.  This runs @code{Info-exit} in Emacs.
1151   This is the end of the basic course on using Info.  You have learned
1152 how to move in an Info document, and how to follow menus and cross
1153 references.  This makes you ready for reading manuals top to bottom,
1154 as new users should do when they learn a new package.
1156   Another set of Info commands is useful when you need to find
1157 something quickly in a manual---that is, when you need to use a manual
1158 as a reference rather than as a tutorial.  We urge you to learn
1159 these search commands as well.  If you want to do that now, follow this
1160 cross reference to @ref{Info Search}.
1162 Yet another set of commands are meant for experienced users; you can
1163 find them by looking in the Directory node for documentation on Info.
1164 Finding them will be a good exercise in using Info in the usual
1165 manner.
1167 @format
1168 >> Type @kbd{d} to go to the Info directory node; then type
1169    @kbd{mInfo} and Return, to get to the node about Info and
1170    see what other help is available.
1171 @end format
1174 @node Tags, Checking, Cross-refs, Expert Info
1175 @comment  node-name,  next,  previous,  up
1176 @section Tags Tables for Info Files
1178 @cindex tags tables in info files
1179   You can speed up the access to nodes of a large Info file by giving
1180 it a tags table.  Unlike the tags table for a program, the tags table for
1181 an Info file lives inside the file itself and is used
1182 automatically whenever Info reads in the file.
1184 @findex Info-tagify
1185   To make a tags table, go to a node in the file using Emacs Info mode and type
1186 @kbd{M-x Info-tagify}.  Then you must use @kbd{C-x C-s} to save the
1187 file.  Info files produced by the @code{makeinfo} command that is part
1188 of the Texinfo package always have tags tables to begin with.
1190 @cindex stale tags tables
1191 @cindex update Info tags table
1192   Once the Info file has a tags table, you must make certain it is up
1193 to date.  If you edit an Info file directly (as opposed to editing its
1194 Texinfo source), and, as a result of deletion of text, any node moves back
1195 more than a thousand characters in the file from the position
1196 recorded in the tags table, Info will no longer be able to find that
1197 node.  To update the tags table, use the @code{Info-tagify} command
1198 again.
1200   An Info file tags table appears at the end of the file and looks like
1201 this:
1203 @example
1204 ^_^L
1205 Tag Table:
1206 File: info, Node: Cross-refs^?21419
1207 File: info,  Node: Tags^?22145
1209 End Tag Table
1210 @end example
1212 @noindent
1213 Note that it contains one line per node, and this line contains
1214 the beginning of the node's header (ending just after the node name),
1215 a @samp{DEL} character, and the character position in the file of the
1216 beginning of the node.
1219 @node Checking, Emacs Info Variables, Tags, Expert Info
1220 @section Checking an Info File
1222 When creating an Info file, it is easy to forget the name of a node when
1223 you are making a pointer to it from another node.  If you put in the
1224 wrong name for a node, this is not detected until someone tries to go
1225 through the pointer using Info.  Verification of the Info file is an
1226 automatic process which checks all pointers to nodes and reports any
1227 pointers which are invalid.  Every @samp{Next}, @samp{Previous}, and
1228 @samp{Up} is checked, as is every menu item and every cross reference.  In
1229 addition, any @samp{Next} which does not have a @samp{Previous} pointing
1230 back is reported.  Only pointers within the file are checked, because
1231 checking pointers to other files would be terribly slow.  But those are
1232 usually few.
1234 @findex Info-validate
1235 To check an Info file, do @kbd{M-x Info-validate} while looking at any
1236 node of the file with Emacs Info mode.
1238 @node Emacs Info Variables, , Checking, Expert Info
1239 @section Emacs Info-mode Variables
1241 The following variables may modify the behavior of Info-mode in Emacs;
1242 you may wish to set one or several of these variables interactively, or
1243 in your @file{~/.emacs} init file.  @xref{Examining, Examining and Setting
1244 Variables, Examining and Setting Variables, emacs, The GNU Emacs
1245 Manual}.  The stand-alone Info reader program has its own set of
1246 variables, described in @ref{Variables,, Manipulating Variables,
1247 info-stnd, GNU Info}.
1249 @vtable @code
1250 @item Info-directory-list
1251 The list of directories to search for Info files.  Each element is a
1252 string (directory name) or @code{nil} (try default directory).  If not
1253 initialized Info uses the environment variable @env{INFOPATH} to
1254 initialize it, or @code{Info-default-directory-list} if there is no
1255 @env{INFOPATH} variable in the environment.
1257 If you wish to customize the Info directory search list for both Emacs
1258 info and stand-alone Info, it is best to set the @env{INFOPATH}
1259 environment variable, since that applies to both programs.
1261 @item Info-additional-directory-list
1262 A list of additional directories to search for Info documentation files.
1263 These directories are not searched for merging the @file{dir} file.
1265 @item Info-fontify
1266 When set to a non-@code{nil} value, enables highlighting of Info
1267 files.  The default is @code{t}.  You can change how the highlighting
1268 looks by customizing the faces @code{info-node}, @code{info-xref},
1269 @code{info-header-xref}, @code{info-header-node}, @code{info-menu-5},
1270 @code{info-menu-header}, and @code{info-title-@var{n}-face} (where
1271 @var{n} is the level of the section, a number between 1 and 4).  To
1272 customize a face, type @kbd{M-x customize-face @key{RET} @var{face}
1273 @key{RET}}, where @var{face} is one of the face names listed here.
1275 @item Info-use-header-line
1276 If non-@code{nil}, Emacs puts in the Info buffer a header line showing
1277 the @samp{Next}, @samp{Prev}, and @samp{Up} links.  A header line does
1278 not scroll with the rest of the buffer, making these links always
1279 visible.
1281 @item Info-scroll-prefer-subnodes
1282 If set to a non-@code{nil} value, @key{SPC} and @key{BACKSPACE} (or
1283 @key{DEL}) keys in a menu visit subnodes of the current node before
1284 scrolling to its end or beginning, respectively.  For example, if the
1285 node's menu appears on the screen, the next @key{SPC} moves to a
1286 subnode indicated by the following menu item.  Setting this option to
1287 @code{nil} results in behavior similar to the stand-alone Info reader
1288 program, which visits the first subnode from the menu only when you
1289 hit the end of the current node.  The default is @code{t}.
1291 @item Info-enable-active-nodes
1292 When set to a non-@code{nil} value, allows Info to execute Lisp code
1293 associated with nodes.  The Lisp code is executed when the node is
1294 selected.  The Lisp code to be executed should follow the node
1295 delimiter (the @samp{DEL} character) and an @samp{execute: } tag, like
1296 this:
1298 @example
1299 ^_execute: (message "This is an active node!")
1300 @end example
1302 @item Info-enable-edit
1303 Set to @code{nil}, disables the @samp{e} (@code{Info-edit}) command.  A
1304 non-@code{nil} value enables it.  @xref{Add, Edit}.
1305 @end vtable
1308 @node Creating an Info File
1309 @chapter Creating an Info File from a Texinfo File
1311 @code{makeinfo} is a utility that converts a Texinfo file into an Info
1312 file; @code{texinfo-format-region} and @code{texinfo-format-buffer} are
1313 GNU Emacs functions that do the same.
1315 @xref{Top,, Overview of Texinfo, texinfo, Texinfo: The GNU
1316 Documentation Format}, to learn how to write a Texinfo file.
1318 @xref{Creating an Info File,,, texinfo, Texinfo: The GNU Documentation
1319 Format}, to learn how to create an Info file from a Texinfo file.
1321 @xref{Installing an Info File,,, texinfo, Texinfo: The GNU
1322 Documentation Format}, to learn how to install an Info file after you
1323 have created one.
1325 @node Index
1326 @unnumbered Index
1328 This is an alphabetical listing of all the commands, variables, and
1329 topics discussed in this document.
1331 @printindex cp
1333 @bye