(===hng-kbk): New coded-charset for XEmacs CHISE.
[chise/xemacs-chise.git.1] / man / info.texi
1 \input texinfo    @c -*-texinfo-*-
2 @comment %**start of header
3 @setfilename ../info/info.info
4 @settitle Info
5 @comment %**end of header
6 @comment $Id: info.texi,v 1.4.2.6 2000/11/29 08:27:28 stephent Exp $
7
8 @dircategory Texinfo documentation system
9 @direntry
10 * Info: (info).                 Documentation browsing system.
11 @end direntry
12
13 @ifinfo
14 This file describes how to use Info, the on-line, menu-driven GNU
15 documentation system.
16
17 Copyright (C) 1989, 92, 96, 97, 98, 99 Free Software Foundation, Inc.
18
19 Permission is granted to make and distribute verbatim copies of
20 this manual provided the copyright notice and this permission notice
21 are preserved on all copies.
22
23 @ignore
24 Permission is granted to process this file through TeX and print the
25 results, provided the printed document carries copying permission
26 notice identical to this one except for the removal of this paragraph
27 (this paragraph not being relevant to the printed manual).
28
29 @end ignore
30 Permission is granted to copy and distribute modified versions of this
31 manual under the conditions for verbatim copying, provided that the entire
32 resulting derived work is distributed under the terms of a permission
33 notice identical to this one.
34
35 Permission is granted to copy and distribute translations of this manual
36 into another language, under the above conditions for modified versions,
37 except that this permission notice may be stated in a translation approved
38 by the Free Software Foundation.
39 @end ifinfo
40
41 @titlepage
42 @title Info
43 @subtitle The online, menu-driven GNU documentation system
44 @author Brian Fox
45 @page
46 @vskip 0pt plus 1filll
47 Copyright @copyright{} 1989, 92, 93, 96, 97, 98, 99 Free Software
48 Foundation, Inc.
49 @sp 2
50 Published by the Free Software Foundation @*
51 59 Temple Place - Suite 330 @*
52 Boston, MA 02111-1307, USA.
53
54 Permission is granted to make and distribute verbatim copies of
55 this manual provided the copyright notice and this permission notice
56 are preserved on all copies.
57
58 Permission is granted to copy and distribute modified versions of this
59 manual under the conditions for verbatim copying, provided that the entire
60 resulting derived work is distributed under the terms of a permission
61 notice identical to this one.
62
63 Permission is granted to copy and distribute translations of this manual
64 into another language, under the above conditions for modified versions,
65 except that this permission notice may be stated in a translation approved
66 by the Free Software Foundation.
67 @end titlepage
68
69 @node Top
70 @top Info: An Introduction
71
72 Info is a program for reading documentation, which you might be using
73 now to read this.
74
75 To learn how to use Info, type the command @kbd{h} while using the Info
76 program.  It brings you to a programmed instruction sequence.
77
78 @menu
79 * Getting Started::             Getting started using an Info reader.
80 * Advanced Info::               Advanced commands within Info.
81 * Creating an Info File::       How to make your own Info file.
82 @end menu
83
84 @node Getting Started, Advanced Info, Top, Top
85 @comment  node-name,  next,  previous,  up
86 @chapter Getting Started
87
88 This first part of the Info manual describes how to get around inside
89 of Info.  The second part of the manual describes various advanced
90 Info commands, and how to write an Info as distinct from a Texinfo
91 file.  The third part is about how to generate Info files from
92 Texinfo files.
93
94 @iftex
95 This manual is primarily designed for use on a computer, so that you can
96 try Info commands while reading about them.  Reading it on paper is less
97 effective, since you must take it on faith that the commands described
98 really do what the manual says.  By all means go through this manual now
99 that you have it; but please try going through the on-line version as
100 well.
101
102 There are two ways of looking at the online version of this manual:
103
104 @enumerate
105 @item
106 Type @code{info} at your shell's command line.  This approach uses a
107 small stand-alone program designed just to read Info files.
108
109 @item
110 Type @code{emacs} at the command line; then type @kbd{C-h i} (Control
111 @kbd{h}, followed by @kbd{i}).  This approach uses the Info mode of the
112 Emacs program, an editor with many other capabilities.
113 @end enumerate
114
115 In either case, then type @kbd{mInfo} (just the letters), followed by
116 @key{RET}---the ``Return'' or ``Enter'' key.  At this point, you should
117 be ready to follow the instructions in this manual as you read them on
118 the screen.
119 @c FIXME! (pesch@cygnus.com, 14 dec 1992)
120 @c Is it worth worrying about what-if the beginner goes to somebody
121 @c else's Emacs session, which already has an Info running in the middle
122 @c of something---in which case these simple instructions won't work?
123 @end iftex
124
125 @menu
126 * Help-Small-Screen::   Starting Info on a Small Screen
127 * Help::                How to use Info
128 * Help-P::              Returning to the Previous node
129 * Help-^L::             The Space, Rubout, B and ^L commands.
130 * Help-M::              Menus
131 * Help-Adv::            Some advanced Info commands
132 * Help-Q::              Quitting Info
133 @end menu
134
135 @node Help-Small-Screen, Help,  , Getting Started
136 @comment  node-name,  next,  previous,  up
137 @section Starting Info on a Small Screen
138
139 @iftex
140 (In Info, you only see this section if your terminal has a small
141 number of lines; most readers pass by it without seeing it.)
142 @end iftex
143
144 Since your terminal has an unusually small number of lines on its
145 screen, it is necessary to give you special advice at the beginning.
146
147 If you see the text @samp{--All----} at near the bottom right corner
148 of the screen, it means the entire text you are looking at fits on the
149 screen.  If you see @samp{--Top----} instead, it means that there is
150 more text below that does not fit.  To move forward through the text
151 and see another screen full, press the Space bar, @key{SPC}.  To move
152 back up, press the key labeled @samp{Backspace} or @key{Delete}.
153
154 @ifinfo
155 Here are 40 lines of junk, so you can try Spaces and Deletes and
156 see what they do.  At the end are instructions of what you should do
157 next.
158
159 This is line 17 @*
160 This is line 18 @*
161 This is line 19 @*
162 This is line 20 @*
163 This is line 21 @*
164 This is line 22 @*
165 This is line 23 @*
166 This is line 24 @*
167 This is line 25 @*
168 This is line 26 @*
169 This is line 27 @*
170 This is line 28 @*
171 This is line 29 @*
172 This is line 30 @*
173 This is line 31 @*
174 This is line 32 @*
175 This is line 33 @*
176 This is line 34 @*
177 This is line 35 @*
178 This is line 36 @*
179 This is line 37 @*
180 This is line 38 @*
181 This is line 39 @*
182 This is line 40 @*
183 This is line 41 @*
184 This is line 42 @*
185 This is line 43 @*
186 This is line 44 @*
187 This is line 45 @*
188 This is line 46 @*
189 This is line 47 @*
190 This is line 48 @*
191 This is line 49 @*
192 This is line 50 @*
193 This is line 51 @*
194 This is line 52 @*
195 This is line 53 @*
196 This is line 54 @*
197 This is line 55 @*
198 This is line 56 @*
199
200 If you have managed to get here, go back to the beginning with
201 Delete, and come back here again, then you understand Space and
202 Delete.  So now type an @kbd{n} ---just one character; don't type
203 the quotes and don't type the Return key afterward--- to
204 get to the normal start of the course.
205 @end ifinfo
206
207 @node Help, Help-P, Help-Small-Screen, Getting Started
208 @comment  node-name,  next,  previous,  up
209 @section How to use Info
210
211 You are talking to the program Info, for reading documentation.
212
213   Right now you are looking at one @dfn{Node} of Information.
214 A node contains text describing a specific topic at a specific
215 level of detail.  This node's topic is ``how to use Info''.
216
217   The top line of a node is its @dfn{header}.  This node's header (look at
218 it now) says that it is the node named @samp{Help} in the file
219 @file{info}.  It says that the @samp{Next} node after this one is the node
220 called @samp{Help-P}.  An advanced Info command lets you go to any node
221 whose name you know.
222
223   Besides a @samp{Next}, a node can have a @samp{Previous} or an @samp{Up}.
224 This node has a @samp{Previous} but no @samp{Up}, as you can see.
225
226   Now it is time to move on to the @samp{Next} node, named @samp{Help-P}.
227
228 >> Type @samp{n} to move there.  Type just one character;
229    do not type the quotes and do not type a @key{RET} afterward.
230
231 @samp{>>} in the margin means it is really time to try a command.
232
233 @node Help-P, Help-^L, Help, Getting Started
234 @comment  node-name,  next,  previous,  up
235 @section Returning to the Previous node
236
237 This node is called @samp{Help-P}.  The @samp{Previous} node, as you see,
238 is @samp{Help}, which is the one you just came from using the @kbd{n}
239 command.  Another @kbd{n} command now would take you to the next
240 node, @samp{Help-^L}.
241
242 >> But do not do that yet.  First, try the @kbd{p} command, which takes
243    you to the @samp{Previous} node.  When you get there, you can do an
244    @kbd{n} again to return here.
245
246   This all probably seems insultingly simple so far, but @emph{do not} be
247 led into skimming.  Things will get more complicated soon.  Also,
248 do not try a new command until you are told it is time to.  Otherwise,
249 you may make Info skip past an important warning that was coming up.
250
251 >> Now do an @kbd{n} to get to the node @samp{Help-^L} and learn more.
252
253 @node Help-^L, Help-M, Help-P, Getting Started
254 @comment  node-name,  next,  previous,  up
255 @section The Space, Delete, B and ^L commands.
256
257   This node's header tells you that you are now at node @samp{Help-^L}, and
258 that @kbd{p} would get you back to @samp{Help-P}.  The node's title is
259 underlined; it says what the node is about (most nodes have titles).
260
261   This is a big node and it does not all fit on your display screen.
262 You can tell that there is more that is not visible because you
263 can see the string @samp{--Top-----} rather than @samp{--All----} near
264 the bottom right corner of the screen.
265
266   The Space, Delete and @kbd{B} commands exist to allow you to ``move
267 around'' in a node that does not all fit on the screen at once.
268 Space moves forward, to show what was below the bottom of the screen.
269 Delete moves backward, to show what was above the top of the screen
270 (there is not anything above the top until you have typed some spaces).
271
272 >> Now try typing a Space (afterward, type a Delete to return here).
273
274   When you type the space, the two lines that were at the bottom of
275 the screen appear at the top, followed by more lines.  Delete takes
276 the two lines from the top and moves them to the bottom,
277 @emph{usually}, but if there are not a full screen's worth of lines
278 above them they may not make it all the way to the bottom.
279
280   If you type Space when there is no more to see, it rings the
281 bell and otherwise does nothing.  The same goes for Delete when
282 the header of the node is visible.
283
284   If your screen is ever garbaged, you can tell Info to print it out
285 again by typing @kbd{C-l} (@kbd{Control-L}, that is---hold down ``Control'' and
286 type an @key{L} or @kbd{l}).
287
288 >> Type @kbd{C-l} now.
289
290   To move back to the beginning of the node you are on, you can type
291 a lot of Deletes.  You can also type simply @kbd{b} for beginning.
292 >> Try that now.  (We have put in enough verbiage to push this past
293 the first screenful, but screens are so big nowadays that perhaps it
294 isn't enough.  You may need to shrink your Emacs or Info window.)
295 Then come back, with Spaces.
296
297   If your screen is very tall, all of this node might fit at once.
298 In that case, "b" won't do anything.  Sorry; what can we do?
299
300   You have just learned a considerable number of commands.  If you
301 want to use one but have trouble remembering which, you should type
302 a @key{?} which prints out a brief list of commands.  When you are
303 finished looking at the list, make it go away by pressing @key{SPC}
304 repeatedly.
305
306 >> Type a @key{?} now.  Press @key{SPC} to see consecutive screenfuls of
307 >> the list until finished.
308
309   From now on, you will encounter large nodes without warning, and
310 will be expected to know how to use Space and Delete to move
311 around in them without being told.  Since not all terminals have
312 the same size screen, it would be impossible to warn you anyway.
313
314 >> Now type @kbd{n} to see the description of the @kbd{m} command.
315
316 @node Help-M, Help-Adv, Help-^L, Getting Started
317 @comment  node-name,  next,  previous,  up
318 @section Menus
319
320 Menus and the @kbd{m} command
321
322   With only the @kbd{n} and @kbd{p} commands for moving between nodes, nodes
323 are restricted to a linear sequence.  Menus allow a branching
324 structure.  A menu is a list of other nodes you can move to.  It is
325 actually just part of the text of the node formatted specially so that
326 Info can interpret it.  The beginning of a menu is always identified
327 by a line which starts with @samp{* Menu:}.  A node contains a menu if and
328 only if it has a line in it which starts that way.  The only menu you
329 can use at any moment is the one in the node you are in.  To use a
330 menu in any other node, you must move to that node first.
331
332   After the start of the menu, each line that starts with a @samp{*}
333 identifies one subtopic.  The line usually contains a brief name
334 for the subtopic (followed by a @samp{:}), the name of the node that talks
335 about that subtopic, and optionally some further description of the
336 subtopic.  Lines in the menu that do not start with a @samp{*} have no
337 special meaning---they are only for the human reader's benefit and do
338 not define additional subtopics.  Here is an example:
339
340 @example
341 * Foo:  FOO's Node      This tells about FOO
342 @end example
343
344 The subtopic name is Foo, and the node describing it is @samp{FOO's Node}.
345 The rest of the line is just for the reader's Information.
346 [[ But this line is not a real menu item, simply because there is
347 no line above it which starts with @samp{* Menu:}.]]
348
349   When you use a menu to go to another node (in a way that will be
350 described soon), what you specify is the subtopic name, the first
351 thing in the menu line.  Info uses it to find the menu line, extracts
352 the node name from it, and goes to that node.  The reason that there
353 is both a subtopic name and a node name is that the node name must be
354 meaningful to the computer and may therefore have to be ugly looking.
355 The subtopic name can be chosen just to be convenient for the user to
356 specify.  Often the node name is convenient for the user to specify
357 and so both it and the subtopic name are the same.  There is an
358 abbreviation for this:
359
360 @example
361 * Foo::   This tells about FOO
362 @end example
363
364 @noindent
365 This means that the subtopic name and node name are the same; they are
366 both @samp{Foo}.
367
368 >> Now use Spaces to find the menu in this node, then come back to
369    the front with a @kbd{b} and some Spaces.  As you see, a menu is
370    actually visible in its node.  If you cannot find a menu in a node
371    by looking at it, then the node does not have a menu and the
372    @kbd{m} command is not available.
373
374   The command to go to one of the subnodes is @kbd{m}---but @emph{do
375 not do it yet!}  Before you use @kbd{m}, you must understand the
376 difference between commands and arguments.  So far, you have learned
377 several commands that do not need arguments.  When you type one, Info
378 processes it and is instantly ready for another command.  The @kbd{m}
379 command is different: it is incomplete without the @dfn{name of the
380 subtopic}.  Once you have typed @kbd{m}, Info tries to read the
381 subtopic name.
382
383   Now look for the line containing many dashes near the bottom of the
384 screen.  There is one more line beneath that one, but usually it is
385 blank.  If it is empty, Info is ready for a command, such as @kbd{n}
386 or @kbd{b} or Space or @kbd{m}.  If that line contains text ending
387 in a colon, it means Info is trying to read the @dfn{argument} to a
388 command.  At such times, commands do not work, because Info tries to
389 use them as the argument.  You must either type the argument and
390 finish the command you started, or type @kbd{Control-g} to cancel the
391 command.  When you have done one of those things, the line becomes
392 blank again.
393
394   The command to go to a subnode via a menu is @kbd{m}.  After you type
395 the @kbd{m}, the line at the bottom of the screen says @samp{Menu item: }.
396 You must then type the name of the subtopic you want, and end it with
397 a @key{RET}.
398
399   You can abbreviate the subtopic name.  If the abbreviation is not
400 unique, the first matching subtopic is chosen.  Some menus put
401 the shortest possible abbreviation for each subtopic name in capital
402 letters, so you can see how much you need to type.  It does not
403 matter whether you use upper case or lower case when you type the
404 subtopic.  You should not put any spaces at the end, or inside of the
405 item name, except for one space where a space appears in the item in
406 the menu.
407
408   You can also use the @dfn{completion} feature to help enter the subtopic
409 name.  If you type the Tab key after entering part of a name, it will
410 magically fill in more of the name---as much as follows uniquely from
411 what you have entered.
412
413   If you move the cursor to one of the menu subtopic lines, then you do
414 not need to type the argument: you just type a Return, and it stands for
415 the subtopic of the line you are on.
416
417 Here is a menu to give you a chance to practice.  This menu gives you
418 three ways of going to one place, Help-FOO:
419
420 @menu
421 * Foo:  Help-FOO.       A node you can visit for fun.
422 * Bar:  Help-FOO.       Strange!  two ways to get to the same place.
423 * Help-FOO::            And yet another!
424 @end menu
425
426 >>  Now type just an @kbd{m} and see what happens:
427
428   Now you are ``inside'' an @kbd{m} command.  Commands cannot be used
429 now; the next thing you will type must be the name of a subtopic.
430
431   You can change your mind about doing the @kbd{m} by typing Control-g.
432
433 >> Try that now;  notice the bottom line clear.
434
435 >> Then type another @kbd{m}.
436
437 >> Now type @samp{BAR} item name.  Do not type Return yet.
438
439   While you are typing the item name, you can use the Delete key to
440 cancel one character at a time if you make a mistake.
441
442 >> Type one to cancel the @samp{R}.  You could type another @samp{R} to
443    replace it.  You do not have to, since @samp{BA} is a valid abbreviation.
444
445 >> Now you are ready to go.  Type a @key{RET}.
446
447   After visiting Help-FOO, you should return here.
448
449 >> Type @kbd{n} to see more commands.
450
451 @c If a menu appears at the end of this node, remove it.
452 @c It is an accident of the menu updating command.
453
454 Here is another way to get to  Help-FOO, a menu.  You can ignore this
455 if you want, or else try it (but then please come back to here).
456
457 @menu
458 * Help-FOO::
459 @end menu
460
461 @node Help-FOO,  ,  , Help-M
462 @comment  node-name,  next,  previous,  up
463 @subsection The @kbd{u} command
464
465   Congratulations!  This is the node @samp{Help-FOO}.  Unlike the other
466 nodes you have seen, this one has an @samp{Up}: @samp{Help-M}, the node you
467 just came from via the @kbd{m} command.  This is the usual
468 convention---the nodes you reach from a menu have @samp{Up} nodes that lead
469 back to the menu.  Menus move Down in the tree, and @samp{Up} moves Up.
470 @samp{Previous}, on the other hand, is usually used to ``stay on the same
471 level but go backwards''
472
473   You can go back to the node @samp{Help-M} by typing the command
474 @kbd{u} for ``Up''.  That puts you at the @emph{front} of the
475 node---to get back to where you were reading you have to type
476 some @key{SPC}s.
477
478 >> Now type @kbd{u} to move back up to @samp{Help-M}.
479
480 @node Help-Adv, Help-Q, Help-M, Getting Started
481 @comment  node-name,  next,  previous,  up
482 @section Some advanced Info commands
483
484   The course is almost over, so please stick with it to the end.
485
486   If you have been moving around to different nodes and wish to
487 retrace your steps, the @kbd{l} command (@kbd{l} for @dfn{last}) will
488 do that, one node-step at a time.  As you move from node to node, Info
489 records the nodes where you have been in a special history list.  The
490 @kbd{l} command revisits nodes in the history list; each successive
491 @kbd{l} command moves one step back through the history.
492
493   If you have been following directions, ad @kbd{l} command now will get
494 you back to @samp{Help-M}.  Another @kbd{l} command would undo the
495 @kbd{u} and get you back to @samp{Help-FOO}.  Another @kbd{l} would undo
496 the @kbd{m} and get you back to @samp{Help-M}.
497
498 >> Try typing three @kbd{l}'s, pausing in between to see what each
499     @kbd{l} does.
500
501 Then follow directions again and you will end up back here.
502
503   Note the difference between @kbd{l} and @kbd{p}: @kbd{l} moves to
504 where @emph{you} last were, whereas @kbd{p} always moves to the node
505 which the header says is the @samp{Previous} node (from this node, to
506 @samp{Help-M}).
507
508   The @samp{d} command gets you instantly to the Directory node.
509 This node, which is the first one you saw when you entered Info,
510 has a menu which leads (directly, or indirectly through other menus),
511 to all the nodes that exist.
512
513 >> Try doing a @samp{d}, then do an @kbd{l} to return here (yes,
514    @emph{do} return).
515
516   Sometimes, in Info documentation, you will see a cross reference.
517 Cross references look like this: @xref{Help-Cross, Cross}.  That is a
518 real, live cross reference which is named @samp{Cross} and points at
519 the node named @samp{Help-Cross}.
520
521   If you wish to follow a cross reference, you must use the @samp{f}
522 command.  The @samp{f} must be followed by the cross reference name
523 (in this case, @samp{Cross}).  While you enter the name, you can use the
524 Delete key to edit your input.  If you change your mind about following
525 any reference, you can use @kbd{Control-g} to cancel the command.
526
527   Completion is available in the @samp{f} command; you can complete among
528 all the cross reference names in the current node by typing a Tab.
529
530 >> Type @samp{f}, followed by @samp{Cross}, and a @key{RET}.
531
532   To get a list of all the cross references in the current node, you can
533 type @kbd{?} after an @samp{f}.  The @samp{f} continues to await a
534 cross reference name even after printing the list, so if you don't
535 actually want to follow a reference, you should type a @kbd{Control-g}
536 to cancel the @samp{f}.
537
538 >> Type "f?" to get a list of the cross references in this node.  Then
539    type a @kbd{Control-g} and see how the @samp{f} gives up.
540
541 >> Now type @kbd{n} to see the last node of the course.
542
543 @c If a menu appears at the end of this node, remove it.
544 @c It is an accident of the menu updating command.
545
546 @node Help-Cross,  ,  , Help-Adv
547 @subsection The node reached by the cross reference in Info
548
549   This is the node reached by the cross reference named @samp{Cross}.
550
551   While this node is specifically intended to be reached by a cross
552 reference, most cross references lead to nodes that ``belong'' someplace
553 else far away in the structure of Info.  So you cannot expect the
554 footnote to have a @samp{Next}, @samp{Previous} or @samp{Up} pointing
555 back to where you came from.  In general, the @kbd{l} (el) command is
556 the only way to get back there.
557
558 >> Type @kbd{l} to return to the node where the cross reference was.
559
560 @node Help-Q,  , Help-Adv, Getting Started
561 @comment  node-name,  next,  previous,  up
562 @section Quitting Info
563
564   To get out of Info, back to what you were doing before, type @kbd{q}
565 for @dfn{Quit}.
566
567   This is the end of the course on using Info.  There are some other
568 commands that are meant for experienced users; they are useful, and you
569 can find them by looking in the directory node for documentation on
570 Info.  Finding them will be a good exercise in using Info in the usual
571 manner.
572
573 >> Type @samp{d} to go to the Info directory node; then type
574    @samp{mInfo} and Return, to get to the node about Info and
575    see what other help is available.
576
577
578 @node Advanced Info
579 @chapter Info for Experts
580
581 This chapter describes various advanced Info commands, and how to write
582 an Info as distinct from a Texinfo file.  (However, in most cases, writing a
583 Texinfo file is better, since you can use it @emph{both} to generate an
584 Info file and to make a printed manual.  @xref{Top,, Overview of
585 Texinfo, texinfo, Texinfo}.)
586
587 @menu
588 * Expert::               Advanced Info commands: g, s, e, and 1 - 5.
589 * Add::                  Describes how to add new nodes to the hierarchy.
590                            Also tells what nodes look like.
591 * Menus::                How to add to or create menus in Info nodes.
592 * Cross-refs::           How to add cross-references to Info nodes.
593 * Tags::                 How to make tag tables for Info files.
594 * Checking::             Checking an Info File
595 * Emacs Info Variables:: Variables modifying the behavior of Emacs Info.
596 @end menu
597
598 @node Expert, Add,  , Advanced Info
599 @comment  node-name,  next,  previous,  up
600 @section Advanced Info Commands
601
602 @kbd{g}, @kbd{s}, @kbd{1}, -- @kbd{9}, and @kbd{e}
603
604 If you know a node's name, you can go there by typing @kbd{g}, the
605 name, and @key{RET}.  Thus, @kbd{gTop@key{RET}} would go to the node
606 called @samp{Top} in this file (its directory node).
607 @kbd{gExpert@key{RET}} would come back here.
608
609 Unlike @kbd{m}, @kbd{g} does not allow the use of abbreviations.
610
611 To go to a node in another file, you can include the filename in the
612 node name by putting it at the front, in parentheses.  Thus,
613 @kbd{g(dir)Top@key{RET}} would go to the Info Directory node, which is
614 node @samp{Top} in the file @file{dir}.
615
616 The node name @samp{*} specifies the whole file.  So you can look at
617 all of the current file by typing @kbd{g*@key{RET}} or all of any
618 other file with @kbd{g(FILENAME)@key{RET}}.
619
620 The @kbd{s} command allows you to search a whole file for a string.
621 It switches to the next node if and when that is necessary.  You
622 type @kbd{s} followed by the string to search for, terminated by
623 @key{RET}.  To search for the same string again, just @kbd{s} followed
624 by @key{RET} will do.  The file's nodes are scanned in the order
625 they are in in the file, which has no necessary relationship to the
626 order that they may be in in the tree structure of menus and @samp{next}
627 pointers.  But normally the two orders are not very different.  In any
628 case, you can always do a @kbd{b} to find out what node you have
629 reached, if the header is not visible (this can happen, because @kbd{s}
630 puts your cursor at the occurrence of the string, not at the beginning
631 of the node).
632
633 If you grudge the system each character of type-in it requires, you
634 might like to use the commands @kbd{1}, @kbd{2}, @kbd{3}, @kbd{4}, ...
635 @kbd{9}.  They are short for the @kbd{m} command together with an
636 argument.  @kbd{1} goes through the first item in the current node's
637 menu; @kbd{2} goes through the second item, etc.
638
639 If your display supports multiple fonts, and you are using Emacs' Info
640 mode to read Info files, the @samp{*} for the fifth menu item is
641 underlined, and so is the @samp{*} for the ninth item; these underlines
642 make it easy to see at a glance which number to use for an item.
643
644 On ordinary terminals, you won't have underlining.  If you need to
645 actually count items, it is better to use @kbd{m} instead, and specify
646 the name.
647
648 The Info command @kbd{e} changes from Info mode to an ordinary
649 Emacs editing mode, so that you can edit the text of the current node.
650 Type @kbd{C-c C-c} to switch back to Info.  The @kbd{e} command is allowed
651 only if the variable @code{Info-enable-edit} is non-@code{nil}.
652
653 @node Add, Menus, Expert, Advanced Info
654 @comment  node-name,  next,  previous,  up
655 @section Adding a new node to Info
656
657 To add a new topic to the list in the Info directory, you must:
658 @enumerate
659 @item
660 Create some nodes, in some file, to document that topic.
661 @item
662 Put that topic in the menu in the directory.  @xref{Menus, Menu}.
663 @end enumerate
664
665 Usually, the way to create the nodes is with Texinfo (@pxref{Top,,
666 Overview of Texinfo, texinfo, Texinfo}); this has the advantage that you
667 can also make a printed manual from them.  However, if you want to edit
668 an Info file, here is how.
669
670 The new node can live in an existing documentation file, or in a new
671 one.  It must have a @key{^_} character before it (invisible to the
672 user; this node has one but you cannot see it), and it ends with either
673 a @key{^_}, a @key{^L}, or the end of file.  Note: If you put in a
674 @key{^L} to end a new node, be sure that there is a @key{^_} after it
675 to start the next one, since @key{^L} cannot @emph{start} a node.
676 Also, a nicer way to make a node boundary be a page boundary as well
677 is to put a @key{^L} @emph{right after} the @key{^_}.
678
679   The @key{^_} starting a node must be followed by a newline or a
680 @key{^L} newline, after which comes the node's header line.  The header
681 line must give the node's name (by which Info finds it), and state the
682 names of the @samp{Next}, @samp{Previous}, and @samp{Up} nodes (if there
683 are any).  As you can see, this node's @samp{Up} node is the node
684 @samp{Top}, which points at all the documentation for Info.  The
685 @samp{Next} node is @samp{Menus}.
686
687   The keywords @dfn{Node}, @dfn{Previous}, @dfn{Up}, and @dfn{Next},
688 may appear in any order, anywhere in the header line, but the
689 recommended order is the one in this sentence.  Each keyword must be
690 followed by a colon, spaces and tabs, and then the appropriate name.
691 The name may be terminated with a tab, a comma, or a newline.  A space
692 does not end it; node names may contain spaces.  The case of letters
693 in the names is insignificant.
694
695   A node name has two forms.  A node in the current file is named by
696 what appears after the @samp{Node: } in that node's first line.  For
697 example, this node's name is @samp{Add}.  A node in another file is
698 named by @samp{(@var{filename})@var{node-within-file}}, as in
699 @samp{(info)Add} for this node.  If the file name starts with ``./'',
700 then it is relative to the current directory; otherwise, it is relative
701 starting from the standard Info file directory of your site.
702 The name @samp{(@var{filename})Top} can be abbreviated to just
703 @samp{(@var{filename})}.  By convention, the name @samp{Top} is used for
704 the ``highest'' node in any single file---the node whose @samp{Up} points
705 out of the file.  The Directory node is @file{(dir)}.  The @samp{Top} node
706 of a document file listed in the Directory should have an @samp{Up:
707 (dir)} in it.
708
709   The node name @kbd{*} is special: it refers to the entire file.
710 Thus, @kbd{g*} shows you the whole current file.  The use of the
711 node @kbd{*} is to make it possible to make old-fashioned,
712 unstructured files into nodes of the tree.
713
714   The @samp{Node:} name, in which a node states its own name, must not
715 contain a filename, since Info when searching for a node does not expect
716 one to be there.  The @samp{Next}, @samp{Previous} and @samp{Up} names
717 may contain them.  In this node, since the @samp{Up} node is in the same
718 file, it was not necessary to use one.
719
720   Note that the nodes in this file have a file name in the header
721 line.  The file names are ignored by Info, but they serve as comments
722 to help identify the node for the user.
723
724 @node Menus, Cross-refs, Add, Advanced Info
725 @comment  node-name,  next,  previous,  up
726 @section How to Create Menus
727
728   Any node in the Info hierarchy may have a @dfn{menu}---a list of subnodes.
729 The @kbd{m} command searches the current node's menu for the topic which it
730 reads from the terminal.
731
732   A menu begins with a line starting with @samp{* Menu:}.  The rest of the
733 line is a comment.  After the starting line, every line that begins
734 with a @samp{* } lists a single topic.  The name of the topic--the
735 argument that the user must give to the @kbd{m} command to select this
736 topic---comes right after the star and space, and is followed by a
737 colon, spaces and tabs, and the name of the node which discusses that
738 topic.  The node name, like node names following @samp{Next}, @samp{Previous}
739 and @samp{Up}, may be terminated with a tab, comma, or newline; it may also
740 be terminated with a period.
741
742   If the node name and topic name are the same, then rather than
743 giving the name twice, the abbreviation @samp{* NAME::} may be used
744 (and should be used, whenever possible, as it reduces the visual
745 clutter in the menu).
746
747   It is considerate to choose the topic names so that they differ
748 from each other very near the beginning---this allows the user to type
749 short abbreviations.  In a long menu, it is a good idea to capitalize
750 the beginning of each item name which is the minimum acceptable
751 abbreviation for it (a long menu is more than 5 or so entries).
752
753   The nodes listed in a node's menu are called its ``subnodes'', and it
754 is their ``superior''.  They should each have an @samp{Up:} pointing at
755 the superior.  It is often useful to arrange all or most of the subnodes
756 in a sequence of @samp{Next} and @samp{Previous} pointers so that
757 someone who wants to see them all need not keep revisiting the Menu.
758
759   The Info Directory is simply the menu of the node @samp{(dir)Top}---that
760 is, node @samp{Top} in file @file{.../info/dir}.  You can put new entries
761 in that menu just like any other menu.  The Info Directory is @emph{not} the
762 same as the file directory called @file{info}.  It happens that many of
763 Info's files live on that file directory, but they do not have to; and
764 files on that directory are not automatically listed in the Info
765 Directory node.
766
767   Also, although the Info node graph is claimed to be a ``hierarchy'',
768 in fact it can be @emph{any} directed graph.  Shared structures and
769 pointer cycles are perfectly possible, and can be used if they are
770 appropriate to the meaning to be expressed.  There is no need for all
771 the nodes in a file to form a connected structure.  In fact, this file
772 has two connected components.  You are in one of them, which is under
773 the node @samp{Top}; the other contains the node @samp{Help} which the
774 @kbd{h} command goes to.  In fact, since there is no garbage
775 collector, nothing terrible happens if a substructure is not pointed
776 to, but such a substructure is rather useless since nobody can
777 ever find out that it exists.
778
779 @node Cross-refs, Tags, Menus, Advanced Info
780 @comment  node-name,  next,  previous,  up
781 @section Creating Cross References
782
783   A cross reference can be placed anywhere in the text, unlike a menu
784 item which must go at the front of a line.  A cross reference looks
785 like a menu item except that it has @samp{*note} instead of @kbd{*}.
786 It @emph{cannot} be terminated by a @samp{)}, because @samp{)}'s are
787 so often part of node names.  If you wish to enclose a cross reference
788 in parentheses, terminate it with a period first.  Here are two
789 examples of cross references pointers:
790
791 @example
792 *Note details: commands.  (See *note 3: Full Proof.)
793 @end example
794
795 They are just examples.  The places they ``lead to'' do not really exist!
796
797 @node Tags, Checking, Cross-refs, Advanced Info
798 @comment  node-name,  next,  previous,  up
799 @section Tag Tables for Info Files
800
801   You can speed up the access to nodes of a large Info file by giving
802 it a tag table.  Unlike the tag table for a program, the tag table for
803 an Info file lives inside the file itself and is used
804 automatically whenever Info reads in the file.
805
806   To make a tag table, go to a node in the file using Emacs Info mode and type
807 @kbd{M-x Info-tagify}.  Then you must use @kbd{C-x C-s} to save the
808 file.
809
810   Once the Info file has a tag table, you must make certain it is up
811 to date.  If, as a result of deletion of text, any node moves back
812 more than a thousand characters in the file from the position
813 recorded in the tag table, Info will no longer be able to find that
814 node.  To update the tag table, use the @code{Info-tagify} command again.
815
816   An Info file tag table appears at the end of the file and looks like
817 this:
818
819 @example
820 ^_\f
821 Tag Table:
822 File: info, Node: Cross-refs^?21419
823 File: info,  Node: Tags^?22145
824 ^_
825 End Tag Table
826 @end example
827
828 @noindent
829 Note that it contains one line per node, and this line contains
830 the beginning of the node's header (ending just after the node name),
831 a Delete character, and the character position in the file of the
832 beginning of the node.
833
834
835 @node Checking, Emacs Info Variables, Tags, Advanced Info
836 @section Checking an Info File
837
838 When creating an Info file, it is easy to forget the name of a node when
839 you are making a pointer to it from another node.  If you put in the
840 wrong name for a node, this is not detected until someone tries to go
841 through the pointer using Info.  Verification of the Info file is an
842 automatic process which checks all pointers to nodes and reports any
843 pointers which are invalid.  Every @samp{Next}, @samp{Previous}, and
844 @samp{Up} is checked, as is every menu item and every cross reference.  In
845 addition, any @samp{Next} which does not have a @samp{Previous} pointing
846 back is reported.  Only pointers within the file are checked, because
847 checking pointers to other files would be terribly slow.  But those are
848 usually few.
849
850 To check an Info file, do @kbd{M-x Info-validate} while looking at any
851 node of the file with Emacs Info mode.
852
853 @node Emacs Info Variables, , Checking, Advanced Info
854 @section Emacs Info-mode Variables
855
856 The following variables may modify the behavior of Info-mode in Emacs;
857 you may wish to set one or several of these variables interactively, or
858 in your @file{~/.emacs} init file.  @xref{Examining, Examining and
859 Setting Variables, Examining and Setting Variables, xemacs, XEmacs
860 User's Manual}.
861
862
863 @vtable @code
864 @item Info-enable-edit
865 Set to @code{nil}, disables the @samp{e} (@code{Info-edit}) command.  A
866 non-@code{nil} value enables it.  @xref{Add, Edit}.
867
868 @item Info-enable-active-nodes
869 When set to a non-@code{nil} value, allows Info to execute Lisp code
870 associated with nodes.  The Lisp code is executed when the node is
871 selected.
872
873 @item Info-directory-list
874 The list of directories to search for Info files.  Each element is a
875 string (directory name) or @code{nil} (try default directory).
876
877 @item Info-directory
878 The standard directory for Info documentation files.  Only used when the
879 function @code{Info-directory} is called.
880 @end vtable
881
882
883 @node Creating an Info File
884 @chapter Creating an Info File
885
886 @xref{Top,, Overview of Texinfo, texinfo, Texinfo}, to learn how to
887 write a Texinfo file.
888
889 @xref{Create an Info File, , Creating an Info File, texinfo, Texinfo},
890 to learn how to create an Info file from a Texinfo file.
891
892 @xref{Install an Info File, , Installing an Info File, texinfo, Texinfo},
893 to learn how to install an Info file after you have created one.
894
895 @bye