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