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