1 This is ../info/texinfo.info, produced by makeinfo version 4.0 from
4 INFO-DIR-SECTION Texinfo documentation system
6 * Texinfo: (texinfo). The GNU documentation format.
7 * install-info: (texinfo)Invoking install-info. Updating info/dir entries.
8 * texi2dvi: (texinfo)Format with texi2dvi. Printing Texinfo documentation.
9 * texindex: (texinfo)Format with tex/texindex. Sorting Texinfo index files.
10 * makeinfo: (texinfo)makeinfo Preferred. Translate Texinfo source.
13 This file documents Texinfo, a documentation system that can produce
14 both on-line information and a printed manual from a single source file.
16 Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98 Free Software
19 This edition is for Texinfo version 3.12.
21 Permission is granted to make and distribute verbatim copies of this
22 manual provided the copyright notice and this permission notice are
23 preserved on all copies.
25 Permission is granted to copy and distribute modified versions of this
26 manual under the conditions for verbatim copying, provided that the
27 entire resulting derived work is distributed under the terms of a
28 permission notice identical to this one.
30 Permission is granted to copy and distribute translations of this
31 manual into another language, under the above conditions for modified
32 versions, except that this permission notice may be stated in a
33 translation approved by the Free Software Foundation.
36 File: texinfo.info, Node: Node Menu Illustration, Next: node, Prev: Two Paths, Up: Nodes
38 Node and Menu Illustration
39 ==========================
41 Here is a copy of the diagram shown earlier that illustrates a Texinfo
42 file with three chapters, each of which contains two sections.
44 Note that the "root" is at the top of the diagram and the "leaves"
45 are at the bottom. This is how such a diagram is drawn conventionally;
46 it illustrates an upside-down tree. For this reason, the root node is
47 called the `Top' node, and `Up' node pointers carry you closer to the
52 -------------------------------------
54 Chapter 1 Chapter 2 Chapter 3
56 -------- -------- --------
58 Section Section Section Section Section Section
59 1.1 1.2 2.1 2.2 3.1 3.2
61 Write the beginning of the node for Chapter 2 like this:
63 @node Chapter 2, Chapter 3, Chapter 1, top
64 @comment node-name, next, previous, up
66 This `@node' line says that the name of this node is "Chapter 2", the
67 name of the `Next' node is "Chapter 3", the name of the `Previous' node
68 is "Chapter 1", and the name of the `Up' node is "Top".
70 *Please Note:* `Next' refers to the next node at the same
71 hierarchical level in the manual, not necessarily to the next node
72 within the Texinfo file. In the Texinfo file, the subsequent node
73 may be at a lower level--a section-level node may follow a
74 chapter-level node, and a subsection-level node may follow a
75 section-level node. `Next' and `Previous' refer to nodes at the
76 _same_ hierarchical level. (The `Top' node contains the exception
77 to this rule. Since the `Top' node is the only node at that
78 level, `Next' refers to the first following node, which is almost
79 always a chapter or chapter-level node.)
81 To go to Sections 2.1 and 2.2 using Info, you need a menu inside
82 Chapter 2. (*Note Menus::.) You would write the menu just before the
83 beginning of Section 2.1, like this:
86 * Sect. 2.1:: Description of this section.
90 Write the node for Sect. 2.1 like this:
92 @node Sect. 2.1, Sect. 2.2, Chapter 2, Chapter 2
93 @comment node-name, next, previous, up
95 In Info format, the `Next' and `Previous' pointers of a node usually
96 lead to other nodes at the same level--from chapter to chapter or from
97 section to section (sometimes, as shown, the `Previous' pointer points
98 up); an `Up' pointer usually leads to a node at the level above (closer
99 to the `Top' node); and a `Menu' leads to nodes at a level below (closer
100 to `leaves'). (A cross reference can point to a node at any level; see
101 *Note Cross References::.)
103 Usually, an `@node' command and a chapter structuring command are
104 used in sequence, along with indexing commands. (You may follow the
105 `@node' line with a comment line that reminds you which pointer is
108 Here is the beginning of the chapter in this manual called "Ending a
109 Texinfo File". This shows an `@node' line followed by a comment line,
110 an `@chapter' line, and then by indexing lines.
112 @node Ending a File, Structuring, Beginning a File, Top
113 @comment node-name, next, previous, up
114 @chapter Ending a Texinfo File
115 @cindex Ending a Texinfo file
116 @cindex Texinfo file ending
120 File: texinfo.info, Node: node, Next: makeinfo Pointer Creation, Prev: Node Menu Illustration, Up: Nodes
125 A "node" is a segment of text that begins at an `@node' command and
126 continues until the next `@node' command. The definition of node is
127 different from that for chapter or section. A chapter may contain
128 sections and a section may contain subsections; but a node cannot
129 contain subnodes; the text of a node continues only until the next
130 `@node' command in the file. A node usually contains only one chapter
131 structuring command, the one that follows the `@node' line. On the
132 other hand, in printed output nodes are used only for cross references,
133 so a chapter or section may contain any number of nodes. Indeed, a
134 chapter usually contains several nodes, one for each section,
135 subsection, and subsubsection.
137 To create a node, write an `@node' command at the beginning of a
138 line, and follow it with four arguments, separated by commas, on the
139 rest of the same line. These arguments are the name of the node, and
140 the names of the `Next', `Previous', and `Up' pointers, in that order.
141 You may insert spaces before each pointer if you wish; the spaces are
142 ignored. You must write the name of the node, and the names of the
143 `Next', `Previous', and `Up' pointers, all on the same line. Otherwise,
144 the formatters fail. (*note info: (info)Top, for more information
145 about nodes in Info.)
147 Usually, you write one of the chapter-structuring command lines
148 immediately after an `@node' line--for example, an `@section' or
149 `@subsection' line. (*Note Types of Structuring Commands: Structuring
152 *Please note:* The GNU Emacs Texinfo mode updating commands work
153 only with Texinfo files in which `@node' lines are followed by
154 chapter structuring lines. *Note Updating Requirements::.
156 TeX uses `@node' lines to identify the names to use for cross
157 references. For this reason, you must write `@node' lines in a Texinfo
158 file that you intend to format for printing, even if you do not intend
159 to format it for Info. (Cross references, such as the one at the end
160 of this sentence, are made with `@xref' and its related commands; see
161 *Note Cross References::.)
165 * Node Names:: How to choose node and pointer names.
166 * Writing a Node:: How to write an `@node' line.
167 * Node Line Tips:: Keep names short.
168 * Node Line Requirements:: Keep names unique, without @-commands.
169 * First Node:: How to write a `Top' node.
170 * makeinfo top command:: How to use the `@top' command.
171 * Top Node Summary:: Write a brief description for readers.
174 File: texinfo.info, Node: Node Names, Next: Writing a Node, Prev: node, Up: node
176 Choosing Node and Pointer Names
177 -------------------------------
179 The name of a node identifies the node. The pointers enable you to
180 reach other nodes and consist of the names of those nodes.
182 Normally, a node's `Up' pointer contains the name of the node whose
183 menu mentions that node. The node's `Next' pointer contains the name
184 of the node that follows that node in that menu and its `Previous'
185 pointer contains the name of the node that precedes it in that menu.
186 When a node's `Previous' node is the same as its `Up' node, both node
187 pointers name the same node.
189 Usually, the first node of a Texinfo file is the `Top' node, and its
190 `Up' and `Previous' pointers point to the `dir' file, which contains
191 the main menu for all of Info.
193 The `Top' node itself contains the main or master menu for the manual.
194 Also, it is helpful to include a brief description of the manual in the
195 `Top' node. *Note First Node::, for information on how to write the
196 first node of a Texinfo file.
199 File: texinfo.info, Node: Writing a Node, Next: Node Line Tips, Prev: Node Names, Up: node
201 How to Write an `@node' Line
202 ----------------------------
204 The easiest way to write an `@node' line is to write `@node' at the
205 beginning of a line and then the name of the node, like this:
209 If you are using GNU Emacs, you can use the update node commands
210 provided by Texinfo mode to insert the names of the pointers; or you
211 can leave the pointers out of the Texinfo file and let `makeinfo'
212 insert node pointers into the Info file it creates. (*Note Texinfo
213 Mode::, and *Note makeinfo Pointer Creation::.)
215 Alternatively, you can insert the `Next', `Previous', and `Up'
216 pointers yourself. If you do this, you may find it helpful to use the
217 Texinfo mode keyboard command `C-c C-c n'. This command inserts
218 `@node' and a comment line listing the names of the pointers in their
219 proper order. The comment line helps you keep track of which arguments
220 are for which pointers. This comment line is especially useful if you
221 are not familiar with Texinfo.
223 The template for a node line with `Next', `Previous', and `Up'
224 pointers looks like this:
226 @node NODE-NAME, NEXT, PREVIOUS, UP
228 If you wish, you can ignore `@node' lines altogether in your first
229 draft and then use the `texinfo-insert-node-lines' command to create
230 `@node' lines for you. However, we do not recommend this practice. It
231 is better to name the node itself at the same time that you write a
232 segment so you can easily make cross references. A large number of
233 cross references are an especially important feature of a good Info
236 After you have inserted an `@node' line, you should immediately write
237 an @-command for the chapter or section and insert its name. Next (and
238 this is important!), put in several index entries. Usually, you will
239 find at least two and often as many as four or five ways of referring
240 to the node in the index. Use them all. This will make it much easier
241 for people to find the node.
244 File: texinfo.info, Node: Node Line Tips, Next: Node Line Requirements, Prev: Writing a Node, Up: node
249 Here are three suggestions:
251 * Try to pick node names that are informative but short.
253 In the Info file, the file name, node name, and pointer names are
254 all inserted on one line, which may run into the right edge of the
255 window. (This does not cause a problem with Info, but is ugly.)
257 * Try to pick node names that differ from each other near the
258 beginnings of their names. This way, it is easy to use automatic
259 name completion in Info.
261 * By convention, node names are capitalized just as they would be for
262 section or chapter titles--initial and significant words are
263 capitalized; others are not.
266 File: texinfo.info, Node: Node Line Requirements, Next: First Node, Prev: Node Line Tips, Up: node
268 `@node' Line Requirements
269 -------------------------
271 Here are several requirements for `@node' lines:
273 * All the node names for a single Info file must be unique.
275 Duplicates confuse the Info movement commands. This means, for
276 example, that if you end every chapter with a summary, you must
277 name each summary node differently. You cannot just call each one
278 "Summary". You may, however, duplicate the titles of chapters,
279 sections, and the like. Thus you can end each chapter in a book
280 with a section called "Summary", so long as the node names for
281 those sections are all different.
283 * A pointer name must be the name of a node.
285 The node to which a pointer points may come before or after the
286 node containing the pointer.
288 * You cannot use any of the Texinfo @-commands in a node name;
289 @-commands confuse Info.
291 Thus, the beginning of the section called `@chapter' looks like
294 @node chapter, unnumbered & appendix, makeinfo top, Structuring
295 @comment node-name, next, previous, up
296 @section @code{@@chapter}
299 * You cannot use commas or apostrophes within a node name; these
300 confuse TeX or the Info formatters.
302 For example, the following is a section title:
304 @code{@@unnumberedsec}, @code{@@appendixsec}, @code{@@heading}
306 The corresponding node name is:
308 unnumberedsec appendixsec heading
310 * Case is significant.
313 File: texinfo.info, Node: First Node, Next: makeinfo top command, Prev: Node Line Requirements, Up: node
318 The first node of a Texinfo file is the "Top" node, except in an
319 included file (*note Include Files::). The Top node contains the main
320 or master menu for the document, and a short summary of the document
321 (*note Top Node Summary::).
323 The Top node (which must be named `top' or `Top') should have as its
324 `Up' node the name of a node in another file, where there is a menu
325 that leads to this file. Specify the file name in parentheses. If the
326 file is to be installed directly in the Info directory file, use
327 `(dir)' as the parent of the Top node; this is short for `(dir)top',
328 and specifies the Top node in the `dir' file, which contains the main
329 menu for the Info system as a whole. For example, the `@node Top' line
330 of this manual looks like this:
332 @node Top, Copying, , (dir)
334 (You can use the Texinfo updating commands or the `makeinfo' utility to
335 insert these pointers automatically.)
337 Do not define the `Previous' node of the Top node to be `(dir)', as
338 it causes confusing behavior for users: if you are in the Top node and
339 hits <DEL> to go backwards, you wind up in the middle of the some other
340 entry in the `dir' file, which has nothing to do with what you were
343 *Note Install an Info File::, for more information about installing
344 an Info file in the `info' directory.
347 File: texinfo.info, Node: makeinfo top command, Next: Top Node Summary, Prev: First Node, Up: node
349 The `@top' Sectioning Command
350 -----------------------------
352 A special sectioning command, `@top', has been created for use with
353 the `@node Top' line. The `@top' sectioning command tells `makeinfo'
354 that it marks the `Top' node in the file. It provides the information
355 that `makeinfo' needs to insert node pointers automatically. Write the
356 `@top' command at the beginning of the line immediately following the
357 `@node Top' line. Write the title on the remaining part of the same
358 line as the `@top' command.
360 In Info, the `@top' sectioning command causes the title to appear on a
361 line by itself, with a line of asterisks inserted underneath.
363 In TeX and `texinfo-format-buffer', the `@top' sectioning command is
364 merely a synonym for `@unnumbered'. Neither of these formatters
365 require an `@top' command, and do nothing special with it. You can use
366 `@chapter' or `@unnumbered' after the `@node Top' line when you use
367 these formatters. Also, you can use `@chapter' or `@unnumbered' when
368 you use the Texinfo updating commands to create or update pointers and
372 File: texinfo.info, Node: Top Node Summary, Prev: makeinfo top command, Up: node
374 The `Top' Node Summary
375 ----------------------
377 You can help readers by writing a summary in the `Top' node, after the
378 `@top' line, before the main or master menu. The summary should
379 briefly describe the document. In Info, this summary will appear just
380 before the master menu. In a printed manual, this summary will appear
381 on a page of its own.
383 If you do not want the summary to appear on a page of its own in a
384 printed manual, you can enclose the whole of the `Top' node, including
385 the `@node Top' line and the `@top' sectioning command line or other
386 sectioning command line between `@ifinfo' and `@end ifinfo'. This
387 prevents any of the text from appearing in the printed output. (*note
388 Conditionally Visible Text: Conditionals.). You can repeat the brief
389 description from the `Top' node within `@iftex' ... `@end iftex' at the
390 beginning of the first chapter, for those who read the printed manual.
391 This saves paper and may look neater.
393 You should write the version number of the program to which the manual
394 applies in the summary. This helps the reader keep track of which
395 manual is for which version of the program. If the manual changes more
396 frequently than the program or is independent of it, you should also
397 include an edition number for the manual. (The title page should also
398 contain this information: see *Note `@titlepage': titlepage.)
401 File: texinfo.info, Node: makeinfo Pointer Creation, Prev: node, Up: Nodes
403 Creating Pointers with `makeinfo'
404 =================================
406 The `makeinfo' program has a feature for automatically creating node
407 pointers for a hierarchically organized file that lacks them.
409 When you take advantage of this feature, you do not need to write the
410 `Next', `Previous', and `Up' pointers after the name of a node.
411 However, you must write a sectioning command, such as `@chapter' or
412 `@section', on the line immediately following each truncated `@node'
413 line. You cannot write a comment line after a node line; the section
414 line must follow it immediately.
416 In addition, you must follow the `Top' `@node' line with a line
417 beginning with `@top' to mark the `Top' node in the file. *Note `@top':
420 Finally, you must write the name of each node (except for the `Top'
421 node) in a menu that is one or more hierarchical levels above the
422 node's hierarchical level.
424 This node pointer insertion feature in `makeinfo' is an alternative
425 to the menu and pointer creation and update commands in Texinfo mode.
426 (*Note Updating Nodes and Menus::.) It is especially helpful to people
427 who do not use GNU Emacs for writing Texinfo documents.
430 File: texinfo.info, Node: Menus, Next: Cross References, Prev: Nodes, Up: Top
435 "Menus" contain pointers to subordinate nodes.(1) (*note
436 Menus-Footnote-1::) In Info, you use menus to go to such nodes. Menus
437 have no effect in printed manuals and do not appear in them.
439 By convention, a menu is put at the end of a node since a reader who
440 uses the menu may not see text that follows it.
442 A node that has a menu should _not_ contain much text. If you have a
443 lot of text and a menu, move most of the text into a new subnode--all
448 * Menu Location:: Put a menu in a short node.
449 * Writing a Menu:: What is a menu?
450 * Menu Parts:: A menu entry has three parts.
451 * Less Cluttered Menu Entry:: Two part menu entry.
452 * Menu Example:: Two and three part menu entries.
453 * Other Info Files:: How to refer to a different Info file.
456 File: texinfo.info, Node: Menus-Footnotes, Up: Menus
458 (1) Menus can carry you to any node, regardless of the hierarchical
459 structure; even to nodes in a different Info file. However, the GNU
460 Emacs Texinfo mode updating commands work only to create menus of
461 subordinate nodes. Conventionally, cross references are used to refer
465 File: texinfo.info, Node: Menu Location, Next: Writing a Menu, Prev: Menus, Up: Menus
467 Menus Need Short Nodes
468 ======================
470 A reader can easily see a menu that is close to the beginning of the
471 node. The node should be short. As a practical matter, you should
472 locate a menu within 20 lines of the beginning of the node. Otherwise,
473 a reader with a terminal that displays only a few lines may miss the
474 menu and its associated text.
476 The short text before a menu may look awkward in a printed manual. To
477 avoid this, you can write a menu near the beginning of its node and
478 follow the menu by an `@node' line, and then an `@heading' line located
479 within `@ifinfo' and `@end ifinfo'. This way, the menu, `@node' line,
480 and title appear only in the Info file, not the printed document.
482 For example, the preceding two paragraphs follow an Info-only menu,
483 `@node' line, and heading, and look like this:
486 * Menu Location:: Put a menu in a short node.
487 * Writing a Menu:: What is a menu?
488 * Menu Parts:: A menu entry has three parts.
489 * Less Cluttered Menu Entry:: Two part menu entry.
490 * Menu Example:: Two and three part entries.
491 * Other Info Files:: How to refer to a different
495 @node Menu Location, Writing a Menu, , Menus
497 @heading Menus Need Short Nodes
500 The Texinfo file for this document contains more than a dozen
501 examples of this procedure. One is at the beginning of this chapter;
502 another is at the beginning of the "Cross References" chapter.
505 File: texinfo.info, Node: Writing a Menu, Next: Menu Parts, Prev: Menu Location, Up: Menus
510 A menu consists of an `@menu' command on a line by itself followed by
511 menu entry lines or menu comment lines and then by an `@end menu'
512 command on a line by itself.
514 A menu looks like this:
519 * Files:: All about handling files.
520 * Multiples: Buffers. Multiple buffers; editing
521 several files at once.
524 In a menu, every line that begins with an `* ' is a "menu entry".
525 (Note the space after the asterisk.) A line that does not start with
526 an `* ' may also appear in a menu. Such a line is not a menu entry but
527 is a menu comment line that appears in the Info file. In the example
528 above, the line `Larger Units of Text' is a menu comment line; the two
529 lines starting with `* ' are menu entries.
532 File: texinfo.info, Node: Menu Parts, Next: Less Cluttered Menu Entry, Prev: Writing a Menu, Up: Menus
537 A menu entry has three parts, only the second of which is required:
539 1. The menu entry name (optional).
541 2. The name of the node (required).
543 3. A description of the item (optional).
545 The template for a menu entry looks like this:
547 * MENU-ENTRY-NAME: NODE-NAME. DESCRIPTION
549 Follow the menu entry name with a single colon and follow the node
550 name with tab, comma, period, or newline.
552 In Info, a user selects a node with the `m' (`Info-menu') command.
553 The menu entry name is what the user types after the `m' command.
555 The third part of a menu entry is a descriptive phrase or sentence.
556 Menu entry names and node names are often short; the description
557 explains to the reader what the node is about. A useful description
558 complements the node name rather than repeats it. The description,
559 which is optional, can spread over two or more lines; if it does, some
560 authors prefer to indent the second line while others prefer to align it
561 with the first (and all others). It's up to you.
564 File: texinfo.info, Node: Less Cluttered Menu Entry, Next: Menu Example, Prev: Menu Parts, Up: Menus
566 Less Cluttered Menu Entry
567 =========================
569 When the menu entry name and node name are the same, you can write
570 the name immediately after the asterisk and space at the beginning of
571 the line and follow the name with two colons.
579 * Name: Name. DESCRIPTION
581 You should use the node name for the menu entry name whenever
582 possible, since it reduces visual clutter in the menu.
585 File: texinfo.info, Node: Menu Example, Next: Other Info Files, Prev: Less Cluttered Menu Entry, Up: Menus
590 A menu looks like this in Texinfo:
593 * menu entry name: Node name. A short description.
594 * Node name:: This form is preferred.
601 * menu entry name: Node name. A short description.
602 * Node name:: This form is preferred.
604 Here is an example as you might see it in a Texinfo file:
609 * Files:: All about handling files.
610 * Multiples: Buffers. Multiple buffers; editing
611 several files at once.
619 * Files:: All about handling files.
620 * Multiples: Buffers. Multiple buffers; editing
621 several files at once.
623 In this example, the menu has two entries. `Files' is both a menu
624 entry name and the name of the node referred to by that name.
625 `Multiples' is the menu entry name; it refers to the node named
626 `Buffers'. The line `Larger Units of Text' is a comment; it appears in
627 the menu, but is not an entry.
629 Since no file name is specified with either `Files' or `Buffers',
630 they must be the names of nodes in the same Info file (*note Referring
631 to Other Info Files: Other Info Files.).
634 File: texinfo.info, Node: Other Info Files, Prev: Menu Example, Up: Menus
636 Referring to Other Info Files
637 =============================
639 You can create a menu entry that enables a reader in Info to go to a
640 node in another Info file by writing the file name in parentheses just
641 before the node name. In this case, you should use the three-part menu
642 entry format, which saves the reader from having to type the file name.
644 The format looks like this:
647 * FIRST-ENTRY-NAME:(FILENAME)NODENAME. DESCRIPTION
648 * SECOND-ENTRY-NAME:(FILENAME)SECOND-NODE. DESCRIPTION
651 For example, to refer directly to the `Outlining' and `Rebinding'
652 nodes in the `Emacs Manual', you would write a menu like this:
655 * Outlining: (emacs)Outline Mode. The major mode for
657 * Rebinding: (emacs)Rebinding. How to redefine the
661 If you do not list the node name, but only name the file, then Info
662 presumes that you are referring to the `Top' node.
664 The `dir' file that contains the main menu for Info has menu entries
665 that list only file names. These take you directly to the `Top' nodes
666 of each Info document. (*Note Install an Info File::.)
670 * Info: (info). Documentation browsing system.
671 * Emacs: (emacs). The extensible, self-documenting
674 (The `dir' top level directory for the Info system is an Info file, not
675 a Texinfo file, but a menu entry looks the same in both types of file.)
677 Note that the GNU Emacs Texinfo mode menu updating commands only work
678 with nodes within the current buffer, so you cannot use them to create
679 menus that refer to other files. You must write such menus by hand.
682 File: texinfo.info, Node: Cross References, Next: Marking Text, Prev: Menus, Up: Top
687 "Cross references" are used to refer the reader to other parts of the
688 same or different Texinfo files. In Texinfo, nodes are the places to
689 which cross references can refer.
693 * References:: What cross references are for.
694 * Cross Reference Commands:: A summary of the different commands.
695 * Cross Reference Parts:: A cross reference has several parts.
696 * xref:: Begin a reference with `See' ...
697 * Top Node Naming:: How to refer to the beginning of another file.
698 * ref:: A reference for the last part of a sentence.
699 * pxref:: How to write a parenthetical cross reference.
700 * inforef:: How to refer to an Info-only file.
701 * uref:: How to refer to a uniform resource locator.
704 File: texinfo.info, Node: References, Next: Cross Reference Commands, Prev: Cross References, Up: Cross References
706 What References Are For
707 =======================
709 Often, but not always, a printed document should be designed so that
710 it can be read sequentially. People tire of flipping back and forth to
711 find information that should be presented to them as they need it.
713 However, in any document, some information will be too detailed for
714 the current context, or incidental to it; use cross references to
715 provide access to such information. Also, an on-line help system or a
716 reference manual is not like a novel; few read such documents in
717 sequence from beginning to end. Instead, people look up what they
718 need. For this reason, such creations should contain many cross
719 references to help readers find other information that they may not
722 In a printed manual, a cross reference results in a page reference,
723 unless it is to another manual altogether, in which case the cross
724 reference names that manual.
726 In Info, a cross reference results in an entry that you can follow
727 using the Info `f' command. (*note Some advanced Info commands:
730 The various cross reference commands use nodes to define cross
731 reference locations. This is evident in Info, in which a cross
732 reference takes you to the specified node. TeX also uses nodes to
733 define cross reference locations, but the action is less obvious. When
734 TeX generates a DVI file, it records nodes' page numbers and uses the
735 page numbers in making references. Thus, if you are writing a manual
736 that will only be printed, and will not be used on-line, you must
737 nonetheless write `@node' lines to name the places to which you make
741 File: texinfo.info, Node: Cross Reference Commands, Next: Cross Reference Parts, Prev: References, Up: Cross References
743 Different Cross Reference Commands
744 ==================================
746 There are four different cross reference commands:
749 Used to start a sentence in the printed manual saying `See ...'
750 or an Info cross-reference saying `*Note NAME: NODE.'.
753 Used within or, more often, at the end of a sentence; same as
754 `@xref' for Info; produces just the reference in the printed
755 manual without a preceding `See'.
758 Used within parentheses to make a reference that suits both an Info
759 file and a printed book. Starts with a lower case `see' within the
760 printed manual. (`p' is for `parenthesis'.)
763 Used to make a reference to an Info file for which there is no
766 (The `@cite' command is used to make references to books and manuals
767 for which there is no corresponding Info file and, therefore, no node
768 to which to point. *Note `@cite': cite.)
771 File: texinfo.info, Node: Cross Reference Parts, Next: xref, Prev: Cross Reference Commands, Up: Cross References
773 Parts of a Cross Reference
774 ==========================
776 A cross reference command requires only one argument, which is the
777 name of the node to which it refers. But a cross reference command may
778 contain up to four additional arguments. By using these arguments, you
779 can provide a cross reference name for Info, a topic description or
780 section title for the printed output, the name of a different Info
781 file, and the name of a different printed manual.
783 Here is a simple cross reference example:
793 See Section NNN [Node name], page PPP.
795 Here is an example of a full five-part cross reference:
797 @xref{Node name, Cross Reference Name, Particular Topic,
798 info-file-name, A Printed Manual}, for details.
802 *Note Cross Reference Name: (info-file-name)Node name,
807 See section "Particular Topic" in A Printed Manual, for details.
811 The five possible arguments for a cross reference are:
813 1. The node name (required). This is the node to which the cross
814 reference takes you. In a printed document, the location of the
815 node provides the page reference only for references within the
818 2. The cross reference name for the Info reference, if it is to be
819 different from the node name. If you include this argument, it
820 becomes the first part of the cross reference. It is usually
823 3. A topic description or section name. Often, this is the title of
824 the section. This is used as the name of the reference in the
825 printed manual. If omitted, the node name is used.
827 4. The name of the Info file in which the reference is located, if it
828 is different from the current file. You need not include any
829 `.info' suffix on the file name, since Info readers try appending
832 5. The name of a printed manual from a different Texinfo file.
834 The template for a full five argument cross reference looks like this:
836 @xref{NODE-NAME, CROSS-REFERENCE-NAME, TITLE-OR-TOPIC,
837 INFO-FILE-NAME, PRINTED-MANUAL-TITLE}.
839 Cross references with one, two, three, four, and five arguments are
840 described separately following the description of `@xref'.
842 Write a node name in a cross reference in exactly the same way as in
843 the `@node' line, including the same capitalization; otherwise, the
844 formatters may not find the reference.
846 You can write cross reference commands within a paragraph, but note
847 how Info and TeX format the output of each of the various commands:
848 write `@xref' at the beginning of a sentence; write `@pxref' only
849 within parentheses, and so on.
852 File: texinfo.info, Node: xref, Next: Top Node Naming, Prev: Cross Reference Parts, Up: Cross References
857 The `@xref' command generates a cross reference for the beginning of
858 a sentence. The Info formatting commands convert it into an Info cross
859 reference, which the Info `f' command can use to bring you directly to
860 another node. The TeX typesetting commands convert it into a page
861 reference, or a reference to another book or manual.
865 * Reference Syntax:: What a reference looks like and requires.
866 * One Argument:: `@xref' with one argument.
867 * Two Arguments:: `@xref' with two arguments.
868 * Three Arguments:: `@xref' with three arguments.
869 * Four and Five Arguments:: `@xref' with four and five arguments.
872 File: texinfo.info, Node: Reference Syntax, Next: One Argument, Prev: xref, Up: xref
874 What a Reference Looks Like and Requires
875 ----------------------------------------
877 Most often, an Info cross reference looks like this:
883 *Note CROSS-REFERENCE-NAME: NODE-NAME.
885 In TeX, a cross reference looks like this:
887 See Section SECTION-NUMBER [NODE-NAME], page PAGE.
891 See Section SECTION-NUMBER [TITLE-OR-TOPIC], page PAGE.
893 The `@xref' command does not generate a period or comma to end the
894 cross reference in either the Info file or the printed output. You
895 must write that period or comma yourself; otherwise, Info will not
896 recognize the end of the reference. (The `@pxref' command works
897 differently. *Note `@pxref': pxref.)
899 *Please note:* A period or comma *must* follow the closing brace
900 of an `@xref'. It is required to terminate the cross reference.
901 This period or comma will appear in the output, both in the Info
902 file and in the printed manual.
904 `@xref' must refer to an Info node by name. Use `@node' to define
905 the node (*note Writing a Node::).
907 `@xref' is followed by several arguments inside braces, separated by
908 commas. Whitespace before and after these commas is ignored.
910 A cross reference requires only the name of a node; but it may contain
911 up to four additional arguments. Each of these variations produces a
912 cross reference that looks somewhat different.
914 *Please note:* Commas separate arguments in a cross reference;
915 avoid including them in the title or other part lest the formatters
916 mistake them for separators.
919 File: texinfo.info, Node: One Argument, Next: Two Arguments, Prev: Reference Syntax, Up: xref
921 `@xref' with One Argument
922 -------------------------
924 The simplest form of `@xref' takes one argument, the name of another
925 node in the same Info file. The Info formatters produce output that
926 the Info readers can use to jump to the reference; TeX produces output
927 that specifies the page and section number for you.
931 @xref{Tropical Storms}.
935 *Note Tropical Storms::.
939 See Section 3.1 [Tropical Storms], page 24.
941 (Note that in the preceding example the closing brace is followed by a
944 You can write a clause after the cross reference, like this:
946 @xref{Tropical Storms}, for more info.
950 *Note Tropical Storms::, for more info.
952 See Section 3.1 [Tropical Storms], page 24, for more info.
954 (Note that in the preceding example the closing brace is followed by a
955 comma, and then by the clause, which is followed by a period.)
958 File: texinfo.info, Node: Two Arguments, Next: Three Arguments, Prev: One Argument, Up: xref
960 `@xref' with Two Arguments
961 --------------------------
963 With two arguments, the second is used as the name of the Info cross
964 reference, while the first is still the name of the node to which the
965 cross reference points.
967 The template is like this:
969 @xref{NODE-NAME, CROSS-REFERENCE-NAME}.
973 @xref{Electrical Effects, Lightning}.
977 *Note Lightning: Electrical Effects.
981 See Section 5.2 [Electrical Effects], page 57.
983 (Note that in the preceding example the closing brace is followed by a
984 period; and that the node name is printed, not the cross reference
987 You can write a clause after the cross reference, like this:
989 @xref{Electrical Effects, Lightning}, for more info.
992 *Note Lightning: Electrical Effects, for more info.
996 See Section 5.2 [Electrical Effects], page 57, for more info.
998 (Note that in the preceding example the closing brace is followed by a
999 comma, and then by the clause, which is followed by a period.)
1002 File: texinfo.info, Node: Three Arguments, Next: Four and Five Arguments, Prev: Two Arguments, Up: xref
1004 `@xref' with Three Arguments
1005 ----------------------------
1007 A third argument replaces the node name in the TeX output. The third
1008 argument should be the name of the section in the printed output, or
1009 else state the topic discussed by that section. Often, you will want to
1010 use initial upper case letters so it will be easier to read when the
1011 reference is printed. Use a third argument when the node name is
1012 unsuitable because of syntax or meaning.
1014 Remember to avoid placing a comma within the title or topic section of
1015 a cross reference, or within any other section. The formatters divide
1016 cross references into arguments according to the commas; a comma within
1017 a title or other section will divide it into two arguments. In a
1018 reference, you need to write a title such as "Clouds, Mist, and Fog"
1021 Also, remember to write a comma or period after the closing brace of a
1022 `@xref' to terminate the cross reference. In the following examples, a
1023 clause follows a terminating comma.
1025 The template is like this:
1027 @xref{NODE-NAME, CROSS-REFERENCE-NAME, TITLE-OR-TOPIC}.
1031 @xref{Electrical Effects, Lightning, Thunder and Lightning},
1036 *Note Lightning: Electrical Effects, for details.
1040 See Section 5.2 [Thunder and Lightning], page 57, for details.
1042 If a third argument is given and the second one is empty, then the
1043 third argument serves both. (Note how two commas, side by side, mark
1044 the empty second argument.)
1046 @xref{Electrical Effects, , Thunder and Lightning},
1051 *Note Thunder and Lightning: Electrical Effects, for details.
1055 See Section 5.2 [Thunder and Lightning], page 57, for details.
1057 As a practical matter, it is often best to write cross references with
1058 just the first argument if the node name and the section title are the
1059 same, and with the first and third arguments if the node name and title
1062 Here are several examples from `The GNU Awk User's Guide':
1064 @xref{Sample Program}.
1066 @xref{Case-sensitivity, ,Case-sensitivity in Matching}.
1067 @xref{Close Output, , Closing Output Files and Pipes},
1068 for more information.
1069 @xref{Regexp, , Regular Expressions as Patterns}.
1072 File: texinfo.info, Node: Four and Five Arguments, Prev: Three Arguments, Up: xref
1074 `@xref' with Four and Five Arguments
1075 ------------------------------------
1077 In a cross reference, a fourth argument specifies the name of another
1078 Info file, different from the file in which the reference appears, and
1079 a fifth argument specifies its title as a printed manual.
1081 Remember that a comma or period must follow the closing brace of an
1082 `@xref' command to terminate the cross reference. In the following
1083 examples, a clause follows a terminating comma.
1087 @xref{NODE-NAME, CROSS-REFERENCE-NAME, TITLE-OR-TOPIC,
1088 INFO-FILE-NAME, PRINTED-MANUAL-TITLE}.
1092 @xref{Electrical Effects, Lightning, Thunder and Lightning,
1093 weather, An Introduction to Meteorology}, for details.
1097 *Note Lightning: (weather)Electrical Effects, for details.
1099 The name of the Info file is enclosed in parentheses and precedes the
1102 In a printed manual, the reference looks like this:
1104 See section "Thunder and Lightning" in An Introduction to
1105 Meteorology, for details.
1107 The title of the printed manual is typeset in italics; and the
1108 reference lacks a page number since TeX cannot know to which page a
1109 reference refers when that reference is to another manual.
1111 Often, you will leave out the second argument when you use the long
1112 version of `@xref'. In this case, the third argument, the topic
1113 description, will be used as the cross reference name in Info.
1115 The template looks like this:
1117 @xref{NODE-NAME, , TITLE-OR-TOPIC, INFO-FILE-NAME,
1118 PRINTED-MANUAL-TITLE}, for details.
1122 *Note TITLE-OR-TOPIC: (INFO-FILE-NAME)NODE-NAME, for details.
1126 See section TITLE-OR-TOPIC in PRINTED-MANUAL-TITLE, for details.
1130 @xref{Electrical Effects, , Thunder and Lightning,
1131 weather, An Introduction to Meteorology}, for details.
1135 *Note Thunder and Lightning: (weather)Electrical Effects,
1140 See section "Thunder and Lightning" in An Introduction to
1141 Meteorology, for details.
1143 On rare occasions, you may want to refer to another Info file that is
1144 within a single printed manual--when multiple Texinfo files are
1145 incorporated into the same TeX run but make separate Info files. In
1146 this case, you need to specify only the fourth argument, and not the
1150 File: texinfo.info, Node: Top Node Naming, Next: ref, Prev: xref, Up: Cross References
1155 In a cross reference, you must always name a node. This means that in
1156 order to refer to a whole manual, you must identify the `Top' node by
1157 writing it as the first argument to the `@xref' command. (This is
1158 different from the way you write a menu entry; see *Note Referring to
1159 Other Info Files: Other Info Files.) At the same time, to provide a
1160 meaningful section topic or title in the printed cross reference
1161 (instead of the word `Top'), you must write an appropriate entry for
1162 the third argument to the `@xref' command.
1164 Thus, to make a cross reference to `The GNU Make Manual', write:
1166 @xref{Top, , Overview, make, The GNU Make Manual}.
1170 *Note Overview: (make)Top.
1174 See section "Overview" in The GNU Make Manual.
1176 In this example, `Top' is the name of the first node, and `Overview' is
1177 the name of the first section of the manual.
1180 File: texinfo.info, Node: ref, Next: pxref, Prev: Top Node Naming, Up: Cross References
1185 `@ref' is nearly the same as `@xref' except that it does not generate
1186 a `See' in the printed output, just the reference itself. This makes
1187 it useful as the last part of a sentence.
1191 For more information, see @ref{Hurricanes}.
1195 For more information, see *Note Hurricanes.
1199 For more information, see Section 8.2 [Hurricanes], page 123.
1201 The `@ref' command sometimes leads writers to express themselves in a
1202 manner that is suitable for a printed manual but looks awkward in the
1203 Info format. Bear in mind that your audience will be using both the
1204 printed and the Info format.
1208 Sea surges are described in @ref{Hurricanes}.
1212 Sea surges are described in Section 6.7 [Hurricanes], page 72.
1214 in a printed document, and the following in Info:
1216 Sea surges are described in *Note Hurricanes::.
1218 *Caution:* You _must_ write a period or comma immediately after an
1219 `@ref' command with two or more arguments. Otherwise, Info will
1220 not find the end of the cross reference entry and its attempt to
1221 follow the cross reference will fail. As a general rule, you
1222 should write a period or comma after every `@ref' command. This
1223 looks best in both the printed and the Info output.
1226 File: texinfo.info, Node: pxref, Next: inforef, Prev: ref, Up: Cross References
1231 The parenthetical reference command, `@pxref', is nearly the same as
1232 `@xref', but you use it _only_ inside parentheses and you do _not_ type
1233 a comma or period after the command's closing brace. The command
1234 differs from `@xref' in two ways:
1236 1. TeX typesets the reference for the printed manual with a lower case
1237 `see' rather than an upper case `See'.
1239 2. The Info formatting commands automatically end the reference with a
1240 closing colon or period.
1242 Because one type of formatting automatically inserts closing
1243 punctuation and the other does not, you should use `@pxref' _only_
1244 inside parentheses as part of another sentence. Also, you yourself
1245 should not insert punctuation after the reference, as you do with
1248 `@pxref' is designed so that the output looks right and works right
1249 between parentheses both in printed output and in an Info file. In a
1250 printed manual, a closing comma or period should not follow a cross
1251 reference within parentheses; such punctuation is wrong. But in an
1252 Info file, suitable closing punctuation must follow the cross reference
1253 so Info can recognize its end. `@pxref' spares you the need to use
1254 complicated methods to put a terminator into one form of the output and
1257 With one argument, a parenthetical cross reference looks like this:
1259 ... storms cause flooding (@pxref{Hurricanes}) ...
1263 ... storms cause flooding (*Note Hurricanes::) ...
1267 ... storms cause flooding (see Section 6.7 [Hurricanes], page 72)
1270 With two arguments, a parenthetical cross reference has this template:
1272 ... (@pxref{NODE-NAME, CROSS-REFERENCE-NAME}) ...
1276 ... (*Note CROSS-REFERENCE-NAME: NODE-NAME.) ...
1280 ... (see Section NNN [NODE-NAME], page PPP) ...
1282 `@pxref' can be used with up to five arguments just like `@xref'
1283 (*note `@xref': xref.).
1285 *Please note:* Use `@pxref' only as a parenthetical reference. Do
1286 not try to use `@pxref' as a clause in a sentence. It will look
1287 bad in either the Info file, the printed output, or both.
1289 Also, parenthetical cross references look best at the ends of
1290 sentences. Although you may write them in the middle of a
1291 sentence, that location breaks up the flow of text.
1294 File: texinfo.info, Node: inforef, Next: uref, Prev: pxref, Up: Cross References
1299 `@inforef' is used for cross references to Info files for which there
1300 are no printed manuals. Even in a printed manual, `@inforef' generates
1301 a reference directing the user to look in an Info file.
1303 The command takes either two or three arguments, in the following
1308 2. The cross reference name (optional).
1310 3. The Info file name.
1312 Separate the arguments with commas, as with `@xref'. Also, you must
1313 terminate the reference with a comma or period after the `}', as you do
1318 @inforef{NODE-NAME, CROSS-REFERENCE-NAME, INFO-FILE-NAME},
1322 @inforef{Expert, Advanced Info commands, info},
1323 for more information.
1327 *Note Advanced Info commands: (info)Expert,
1328 for more information.
1332 See Info file `info', node `Expert', for more information.
1336 @inforef{Expert, , info}, for more information.
1340 *Note (info)Expert::, for more information.
1344 See Info file `info', node `Expert', for more information.
1346 The converse of `@inforef' is `@cite', which is used to refer to
1347 printed works for which no Info form exists. *Note `@cite': cite.
1350 File: texinfo.info, Node: uref, Prev: inforef, Up: Cross References
1352 `@uref{URL[, DISPLAYED-TEXT]}'
1353 ==============================
1355 `@uref' produces a reference to a uniform resource locator (URL). It
1356 takes one mandatory argument, the URL, and one optional argument, the
1357 text to display (the default is the URL itself). In HTML output,
1358 `@uref' produces a link you can follow. For example:
1360 The official GNU ftp site is
1361 @uref{ftp://ftp.gnu.ai.mit.edu/pub/gnu}
1364 The official GNU ftp site is
1365 `ftp://ftp.gnu.ai.mit.edu/pub/gnu'
1369 @uref{ftp://ftp.gnu.ai.mit.edu/pub/gnu,
1370 GNU ftp site} holds programs and texts.
1373 The official GNU ftp site (ftp://ftp.gnu.ai.mit.edu/pub/gnu) holds
1377 The official <A HREF="ftp://ftp.gnu.ai.mit.edu/pub/gnu">GNU ftp
1378 site</A> holds programs and texts.
1380 To merely indicate a URL, use `@url' (*note `@url': url.).
1383 File: texinfo.info, Node: Marking Text, Next: Quotations and Examples, Prev: Cross References, Up: Top
1385 Marking Words and Phrases
1386 *************************
1388 In Texinfo, you can mark words and phrases in a variety of ways. The
1389 Texinfo formatters use this information to determine how to highlight
1390 the text. You can specify, for example, whether a word or phrase is a
1391 defining occurrence, a metasyntactic variable, or a symbol used in a
1392 program. Also, you can emphasize text.
1396 * Indicating:: How to indicate definitions, files, etc.
1397 * Emphasis:: How to emphasize text.