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