OS/2 Professional

home *** CD-ROM | disk | FTP | other *** search

/ OS/2 Professional / OS2PRO194.ISO / os2 / prgramer / unix / info / texinfo.i04 < prev next >

Wrap

GNU Info File | 1993-06-12 | 51.3 KB | 1,490 lines

This is Info file texinfo, produced by Makeinfo-1.47 from the input file texinfo2.tex. This file documents Texinfo, a documentation system that uses a single source file to produce both on-line information and a printed manual. Copyright (C) 1988, 1990, 1991, 1992 Free Software Foundation, Inc. This is the second edition of the Texinfo documentation, and is consistent with version 2 of `texinfo.tex'. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Foundation. File: texinfo, Node: makeinfo top command, Next: Top Node Summary, Prev: First Node, Up: node The `@top' Sectioning Command ----------------------------- A special sectioning command, `@top', has been created for use with the `@node Top' line. The `@top' sectioning command tells `makeinfo' that it marks the `Top' node in the file. It provides the information that `makeinfo' needs to insert node pointers automatically. Write the `@top' command at the beginning of the line immediately following the `@node Top' line. Write the title on the remaining part of the same line as the `@top' command. In Info, the `@top' sectioning command causes the title to appear on a line by itself, with a line of asterisks inserted underneath. In TeX and `texinfo-format-buffer', the `@top' sectioning command is merely a synonym for `@unnumbered'. Neither of these formatters require an `@top' command, and do nothing special with it. You can use `@chapter' or `@unnumbered' after the `@node Top' line when you use these formatters. Also, you can use `@chapter' or `@unnumbered' when you use the Texinfo updating commands to create or update pointers and menus. Whatever sectioning command follows an `@node Top' line, whether it be `@top' or `@chapter', the `@node Top' line and the immediately following line and any additional text must be enclosed between `@ifinfo' and `@end ifinfo' commands. (*Note Conditionals::.) This prevents the title and the accompanying text from appearing in printed output. Write the `@ifinfo' command before the `@node' line and write the `@end ifinfo' command after the `@top' or other sectioning command and after any additional text. (You can write the `@end ifinfo' command after the `@end menu' command if you like.) File: texinfo, Node: Top Node Summary, Prev: makeinfo top command, Up: node The `Top' Node Summary ---------------------- You can help readers by writing a summary in the `Top' node, after the `@top' line, before the main or master menu. The summary should briefly describe the Info file. You should also write the version number of the program to which the manual applies in this section. This helps the reader keep track of which manual is for which version of the program. If the manual changes more frequently than the program or is independent of it, you should also include an edition number for the manual. (The title page should also contain this information: see *Note `@titlepage': titlepage.) Put the whole of the `Top' node, including the `@top' sectioning command line if you have one, between `@ifinfo' and `@end ifinfo' so none of the text appears in the printed output (*note Conditionally Visible Text: Conditionals.). (You may want to repeat the brief description from the `Top' node within `@iftex' ... `@end iftex' at the beginning of the first chapter, for those who read the printed manual.) File: texinfo, Node: makeinfo Pointer Creation, Prev: node, Up: Nodes Creating Pointers with `makeinfo' ================================= The `makeinfo' program has a feature for automatically creating node pointers for a hierarchically organized file that lacks them. When you take advantage of this feature, you do not need to write the `Next', `Previous', and `Up' pointers after the name of a node. However, you must write a sectioning command, such as `@chapter' or `@section', on the line immediately following each truncated `@node' line. You cannot write a comment line after a node line; the section line must follow it immediately. In addition, you must follow the `Top' `@node' line with a line beginning with `@top' to mark the `Top' node in the file. *Note `@top': makeinfo top. Finally, you must write the name of each node (except for the `Top' node) in a menu that is one or more hierarchical levels above the node's hierarchical level. This node pointer insertion feature in `makeinfo' is an alternative to the menu and pointer creation and update commands in Texinfo mode. (*Note Updating Nodes and Menus::.) It is especially helpful to people who do not use GNU Emacs for writing Texinfo documents. File: texinfo, Node: Menus, Next: Cross References, Prev: Nodes, Up: Top Menus ***** "Menus" contain pointers to subordinate nodes.(1) In Info, you use menus to go to such nodes. Menus have no effect in printed manuals and do not appear in them. By convention, a menu is put at the end of a node. This way, it is easy for someone using Info to find the menu, using the `M->' (`end-of-buffer') command. A node that has a menu should *not* contain much text. If you have a lot of text and a menu, move most of the text into a new subnode--all but a few lines. * Menu: * Menu Location:: Put a menu in a short node. * Writing a Menu:: What is a menu? * Writing a Menu Entry:: How to write a menu entry. * Menu Example:: A menu example. * Other Info Files:: How to refer to a different Info file. ---------- Footnotes ---------- (1) Menus can carry you to any node, regardless of the hierarchical structure; even to nodes in a different Info file. However, the GNU Emacs Texinfo mode updating commands work only to create menus of subordinate nodes. Conventionally, cross references are used to refer to other nodes. File: texinfo, Node: Menu Location, Next: Writing a Menu, Up: Menus Menus Need Short Nodes ====================== A reader can easily see a menu that is close to the beginning of the node. The node should be short. As a practical matter, you should locate a menu within 20 lines of the beginning of the node. Otherwise, a reader with a terminal that displays only a few lines may miss the menu and its associated text. The short text before a menu may look awkward in a printed manual. To avoid this, you can write a menu near the beginning of its node and follow the menu by an `@node' line, and then an `@heading' line located within `@ifinfo' and `@end ifinfo'. This way, the menu, `@node' line, and title appear only in the Info file, not the printed document. For example, the preceding two paragraphs follow an Info-only menu, `@node' line, and heading, and look like this: @menu * Menu Location:: Put a menu in a short node. * Menu Entry:: How to write a menu entry. * Menu Example:: A menu example. @end menu @node Menu Location @ifinfo @heading Menus Need Short Nodes @end ifinfo The Texinfo file for this document contains more than a dozen other examples of this procedure. One is at the beginning of this chapter; another is at the beginning of the "Cross References" chapter. File: texinfo, Node: Writing a Menu, Next: Writing a Menu Entry, Prev: Menu Location, Up: Menus Writing a Menu ============== A menu consists of an `@menu' command on a line by itself followed by menu entry lines or menu comment lines and then by an `@end menu' command on a line by itself. A menu looks like this: @menu Larger Units of Text * Files:: All about handling files. * Multiples: Buffers. Multiple buffers; editing several files at once. @end menu In a menu, every line that begins with an `* ' is a "menu entry". (Note the space after the asterisk.) A line that does not start with an `* ' may also appear in a menu. Such a line is not a menu entry but is a menu comment line that appears in the Info file. In the example above, the line `Larger Units of Text' is a menu comment line; the two lines starting with `* ' are menu entries. File: texinfo, Node: Writing a Menu Entry, Next: Menu Example, Prev: Writing a Menu, Up: Menus How to Write a Menu Entry ========================= A menu entry has three parts, only the second of which is required: 1. The menu entry name. 2. The name of the node. 3. A description of the item. The template for a menu entry looks like this: * MENU-ENTRY-NAME: NODE-NAME. DESCRIPTION Follow the menu entry name with a single colon and follow the node name with tab, comma, period, or newline. In Info, a user selects a node with the `m' (`Info-menu') command. The menu entry name is what the user types after the `m' command. If the menu entry name and the node name are the same, you can write the name immediately after the asterisk and space at the beginning of the line and follow the name with two colons. For example, write * Name:: instead of * Name: Name. You should use the node name for the menu entry name whenever possible, since it reduces visual clutter in the menu. The third part of a menu entry is a short descriptive phrase or sentence. Menu entry names and node names are often short; the description explains to the reader what the node is about. The description, which is optional, can spread over two or more lines. A useful description complements the node name rather than repeats it. File: texinfo, Node: Menu Example, Next: Other Info Files, Prev: Writing a Menu Entry, Up: Menus A Menu Example ============== A menu looks like this in Texinfo: @menu * menu entry name: Node name. A short description. * Node name:: This form is preferred. @end menu This produces: * menu: * menu entry name: Node name. A short description. * Node name:: This form is preferred. Here is an example as you might see it in a Texinfo file: @menu Larger Units of Text * Files:: All about handling files. * Multiples: Buffers. Multiple buffers; editing several files at once. @end menu This produces: * menu: Larger Units of Text * Files:: All about handling files. * Multiples: Buffers. Multiple buffers; editing several files at once. In this example, the menu has two entries. `Files' is both a menu entry name and the name of the node referred to by that name. In the other entry, `Multiples' is the menu entry name, and it refers to the node named `Buffers'. Since no file name is specified with either `Files' or `Buffers', they must be the names of nodes in the same Info file. (*Note Referring to Other Info Files: Other Info Files.) The line `Larger Units of Text' is a comment; it appears as part of the menu in Info, but is not a menu entry. File: texinfo, Node: Other Info Files, Prev: Menu Example, Up: Menus Referring to Other Info Files ============================= You can create a menu entry that enables an reader in Info to go to a node in another Info file by writing the file name in parentheses just before the node name. In this case, you should use the three-part menu entry format, which saves the reader from having to type the file name. The format looks like this: @menu * FIRST-ENTRY-NAME:(FILENAME)NODENAME. DESCRIPTION * SECOND-ENTRY-NAME:(FILENAME)SECOND-NODE. DESCRIPTION @end menu For example, to refer directly to the `Outlining' and `Rebinding' nodes in the `Emacs Manual', you would write a menu in a Texinfo file similar to the following: @menu * Outlining: (emacs)Outline Mode. The major mode for editing outlines. * Rebinding: (emacs)Rebinding. How to redefine the meaning of a key. @end menu If you do not list the node name, but only name the file, then Info presumes that you are referring to the `Top' node. The `dir' top level directory for the Info system has menu entries that take you directly to the `Top' nodes of each Info document. Only the file names are listed, not the `Top' nodes. (*Note Install an Info File::.) For example: ... * Info: (info). Documentation browsing system. * Emacs: (emacs). The extensible, self-documenting text editor. ... (The `dir' top level directory for the Info system is an Info file, not a Texinfo file, but a menu entry looks the same in both types of file.) Note that the GNU Emacs Texinfo mode menu updating commands only work with nodes within the current buffer, so you cannot use them to create menus that refer to other files. You must write such menus by hand. File: texinfo, Node: Cross References, Next: Marking Text, Prev: Menus, Up: Top Cross References **************** "Cross references" are used to refer the reader to other parts of the same or different Texinfo files. In Texinfo, nodes are the places to which cross references can refer. * Menu: * References:: What cross references are for. * Cross Reference Commands:: A summary of the different commands. * Cross Reference Parts:: A cross reference has several parts. * xref:: Begin a reference with `See' ... * Top Node Naming:: How to refer to the beginning of another file. * ref:: A reference for the last part of a sentence. * pxref:: How to write a parenthetical cross reference. * inforef:: How to refer to an Info-only file. File: texinfo, Node: References, Next: Cross Reference Commands, Up: Cross References What References Are For ======================= Often, but not always, a printed document should be designed so that it can be read sequentially. People tire of flipping back and forth to find information that should be presented to them as they need it. However, in any document, some information will be too detailed for the current context, or incidental to it; use cross references to provide access to such information. Also, an on-line help system or a reference manual is not like a novel; few read such documents in sequence from beginning to end. Instead, people look up what they need. For this reason, such creations should contain many cross references to help readers find other information that they may not have read. In a printed manual, a cross reference results in a page reference, unless it is to another manual altogether, in which case the cross reference names that manual. In Info, a cross reference results in an entry that you can follow using the Info `f' command. (*note Some advanced Info commands: (info)Help-Adv.) The various cross reference commands use nodes to define cross reference locations. This is evident in Info, in which a cross reference takes you to the specified node. TeX also uses nodes to define cross reference locations, but the action is less obvious. When TeX generates a DVI file, it records nodes' page numbers and uses the page numbers in making references. Thus, if you are writing a manual that will only be printed, and will not be used on-line, you must nonetheless write `@node' lines to name the places to which you make cross references. File: texinfo, Node: Cross Reference Commands, Next: Cross Reference Parts, Prev: References, Up: Cross References Different Cross Reference Commands ================================== There are four different cross reference commands: `@xref' Used to start a sentence in the printed manual saying `See ...' or an entry in the Info file saying `*Note ...'. `@ref' Used within or, more often, at the end of a sentence; produces just the reference in the printed manual without a preceding `See'. `@pxref' Used within parentheses to make a reference that starts with a lower case `see' within the printed manual. (`p' is for `parenthesis'.) `@inforef' Used to make a reference to an Info file for which there is no printed manual. (The `@cite' command is used to make references to books and manuals for which there is no corresponding Info file and, therefore, no node to which to point. *Note `@cite': cite.) File: texinfo, Node: Cross Reference Parts, Next: xref, Prev: Cross Reference Commands, Up: Cross References Parts of a Cross Reference ========================== A cross reference command requires only one argument, which is the name of the node to which it refers. But a cross reference command may contain up to four additional arguments. By using these arguments, you can provide a cross reference name for Info, a topic description or section title for the printed output, the name of a different Info file, and the name of a different printed manual. Here is a simple cross reference example: @xref{Node name}. which produces *Note Node name::. and See Section NNN [Node name], page PPP. Here, however, is an example of a full five-part cross reference: @xref{Node name, Cross Reference Name, Particular Topic, info-file-name, A Printed Manual}, for details. which produces *Note Cross Reference Name: (info-file-name)Node name, for details. and See Section Particular Topic of A Printed Manual, for details. The five possible arguments for a cross reference are: 1. The node name (required). This is the node to which the cross reference takes you. In a printed document, the location of the node provides the page reference only for references within the same document. 2. The cross reference name for the Info reference, if it is to be different from the node name. If you include this argument, it argument becomes the first part of the cross reference. It is usually omitted. 3. A topic description or section name. Often, this is the title of the section. This is used as the name of the reference in the printed manual. If omitted, the node name is used. 4. The name of the Info file in which the reference is located, if it is different from the current file. 5. The name of a printed manual from a different Texinfo file. The template for a full five argument cross reference looks like this: @xref{NODE-NAME, CROSS-REFERENCE-NAME, TITLE-OR-TOPIC, INFO-FILE-NAME, PRINTED-MANUAL-TITLE}. Cross references with one, two, three, four, and five arguments are described separately following the description of `@xref'. Write a node name in a cross reference in exactly the same way as in the `@node' line, including the same capitalization; otherwise, the formatters may not find the reference. You can write cross reference commands within a paragraph, but note how Info and TeX format the output of each of the various commands: write `@xref' at the beginning of a sentence; write `@pxref' only within parentheses, and so on. File: texinfo, Node: xref, Next: Top Node Naming, Prev: Cross Reference Parts, Up: Cross References `@xref' ======= The `@xref' command generates a cross reference for the beginning of a sentence. The Info formatting commands convert it into an Info cross reference, which the Info `f' command can use to bring you directly to another node. The TeX typesetting commands convert it into a page reference, or a reference to another book or manual. * Menu: * Reference Syntax:: What a reference looks like and requires. * One Argument:: `@xref' with one argument. * Two Arguments:: `@xref' with two arguments. * Three Arguments:: `@xref' with three arguments. * Four and Five Arguments:: `@xref' with four and five arguments. File: texinfo, Node: Reference Syntax, Next: One Argument, Up: xref What a Reference Looks Like and Requires ---------------------------------------- Most often, an Info cross reference looks like this: *Note NODE-NAME::. or like this *Note CROSS-REFERENCE-NAME: NODE-NAME. In TeX, a cross reference looks like this: See Section SECTION [NODE-NAME], page PAGE. or like this See Section SECTION [TITLE-OR-TOPIC], page PAGE. The `@xref' command does not generate a period or comma to end the cross reference in either the Info file or the printed output. You must write that period or comma yourself; otherwise, Info will not recognize the end of the reference. (The `@pxref' command works differently. *Note `@pxref': pxref.) *Please note:* A period or comma *must* follow the closing brace of an `@xref'. It is required to terminate the cross reference. This period or comma will appear in the output, both in the Info file and in the printed manual. `@xref' must refer to an Info node by name. Use `@node' to define the node (*note Writing a Node::.). `@xref' is followed by several arguments inside braces, separated by commas. Whitespace before and after these commas is ignored. A cross reference requires only the name of a node; but it may contain up to four additional arguments. Each of these variations produces a cross reference that looks somewhat different. File: texinfo, Node: One Argument, Next: Two Arguments, Prev: Reference Syntax, Up: xref `@xref' with One Argument ------------------------- The simplest form of `@xref' takes one argument, the name of another node in the same Info file. The Info formatters produce output that the Info readers can use to jump to the reference; TeX produces output that specifies the page and section number for you. For example, @xref{Tropical Storms}. produces *Note Tropical Storms::. and See Section 3.1 [Tropical Storms], page 24. (Note that in the preceding example the closing brace is followed by a period.) You can write a clause after the cross reference, like this: @xref{Tropical Storms}, for more info. which produces *Note Tropical Storms::, for more info. See Section 3.1 [Tropical Storms], page 24, for more info. (Note that in the preceding example the closing brace is followed by a comma, and then by the clause, which is followed by a period.) File: texinfo, Node: Two Arguments, Next: Three Arguments, Prev: One Argument, Up: xref `@xref' with Two Arguments -------------------------- With two arguments, the second one is used as the name of the Info cross reference, while the first argument is still the node that the cross reference points to. The template is like this: @xref{NODE-NAME, CROSS-REFERENCE-NAME}. For example, @xref{Electrical Effects, Lightning}. produces: *Note Lightning: Electrical Effects. and See Section 5.2 [Electrical Effects], page 57. (Note that in the preceding example the closing brace is followed by a period; and that the node name is printed, not the cross reference name.) You can write a clause after the cross reference, like this: @xref{Electrical Effects, Lightning}, for more info. which produces *Note Lightning: Electrical Effects, for more info. and See Section 5.2 [Electrical Effects], page 57, for more info. (Note that in the preceding example the closing brace is followed by a comma, and then by the clause, which is followed by a period.) File: texinfo, Node: Three Arguments, Next: Four and Five Arguments, Prev: Two Arguments, Up: xref `@xref' with Three Arguments ---------------------------- A third argument replaces the node name in the TeX output. The third argument should be the name of the section in the printed output, or else state the topic discussed by that section. Often, you will want to use initial upper case letters so it will be easier to read when the reference is printed. Use a third argument when the node name is unsuitable because of syntax or meaning. Remember that a comma or period must follow the closing brace of an `@xref' command to terminate the cross reference. In the following examples, a clause follows a terminating comma. The template is like this: @xref{NODE-NAME, CROSS-REFERENCE-NAME, TITLE-OR-TOPIC}. For example, @xref{Electrical Effects, Lightning, Thunder and Lightning}, for details. produces *Note Lightning: Electrical Effects, for details. and See Section 5.2 [Thunder and Lightning], page 57, for details. If a third argument is given and the second one is empty, then the third argument serves both. (Note how two commas, side by side, mark the empty second argument.) @xref{Electrical Effects, , Thunder and Lightning}, for details. produces *Note Thunder and Lightning: Electrical Effects, for details. and See Section 5.2 [Thunder and Lightning], page 57, for details. As a practical matter, it is often best to write cross references with just the first argument if the node name and the section title are the same, and with the first and third arguments if the node name and title are different. Here are several examples from `The GAWK Manual': @xref{Sample Program}. @xref{Glossary}. @xref{Case-sensitivity, ,Case-sensitivity in Matching}. @xref{Close Output, , Closing Output Files and Pipes}, for more information. @xref{Regexp, , Regular Expressions as Patterns}. File: texinfo, Node: Four and Five Arguments, Prev: Three Arguments, Up: xref `@xref' with Four and Five Arguments ------------------------------------ In a cross reference, a fourth argument specifies the name of another Info file, different from the file in which the reference appears, and a fifth argument specifies its title as a printed manual. Remember that a comma or period must follow the closing brace of an `@xref' command to terminate the cross reference. In the following examples, a clause follows a terminating comma. The template is: @xref{NODE-NAME, CROSS-REFERENCE-NAME, TITLE-OR-TOPIC, INFO-FILE-NAME, PRINTED-MANUAL-TITLE}. For example, @xref{Electrical Effects, Lightning, Thunder and Lightning, weather, An Introduction to Meteorology}, for details. produces *Note Lightning: (weather)Electrical Effects, for details. The name of the Info file is enclosed in parentheses and precedes the name of the node. In a printed manual, the reference looks like this: See Section Thunder and Lightning of An Introduction to Meteorology, for details. The title of the printed manual is typeset in italics; and the reference lacks a page number since TeX cannot know to which page a reference refers when that reference is to another manual. Often, you will leave out the second argument when you use the long version of `@xref'. In this case, the third argument, the topic description, will be used as the cross reference name in Info. The template looks like this: @xref{NODE-NAME, , TITLE-OR-TOPIC, INFO-FILE-NAME, PRINTED-MANUAL-TITLE}, for details. produces *Note TITLE-OR-TOPIC: (INFO-FILE-NAME)NODE-NAME, for details. and See Section TITLE-OR-TOPIC of PRINTED-MANUAL-TITLE, for details. For example, @xref{Electrical Effects, , Thunder and Lightning, weather, An Introduction to Meteorology}, for details. produces *Note Thunder and Lightning: (weather)Electrical Effects, for details. and See Section Thunder and Lightning of An Introduction to Meteorology, for details. On rare occasions, you may want to refer to another Info file that is within a single printed manual--when multiple Texinfo files are incorporated into the same TeX run but make separate Info files. In this case, you need to specify only the fourth argument, and not the fifth. File: texinfo, Node: Top Node Naming, Next: ref, Prev: xref, Up: Cross References Naming a `Top' Node =================== In a cross reference, you must always name a node. This means that in order to refer to a whole manual, you must identify the `Top' node by writing it as the first argument to the `@xref' command. (This is different from the way you write a menu entry; see *Note Referring to Other Info Files: Other Info Files.) At the same time, to provide a meaningful section topic or title in the printed cross reference (instead of the word `Top'), you must write an appropriate entry for the third argument to the `@xref' command. Thus, to make a cross reference to `The GNU Make Manual', write: @xref{Top, , Overview, make, The GNU Make Manual}. which produces *Note Overview: (make)Top. and See Section Overview of The GNU Make Manual. In this example, `Top' is the name of the first node, and `Overview' is the name of the first section of the manual. File: texinfo, Node: ref, Next: pxref, Prev: Top Node Naming, Up: Cross References `@ref' ====== `@ref' is nearly the same as `@xref' except that it does not generate a `See' in the printed output, just the reference itself. This makes it useful as the last part of a sentence. For example, For more information, see @ref{Hurricanes}. produces For more information, see *Note Hurricanes. and For more information, see Section 8.2 [Hurricanes], page 123. The `@ref' command sometimes leads writers to express themselves in a manner that is suitable for a printed manual but looks awkward in the Info format. Bear in mind that your audience will be using both the printed and the Info format. For example, Sea surges are described in @ref{Hurricanes}. produces Sea surges are described in Section 6.7 [Hurricanes], page 72. in a printed document, but Sea surges are described in *Note Hurricanes::. in Info. *Caution:* You *must* write a period or comma immediately after an `@ref' command with two or more arguments. Otherwise, Info will not find the end of the cross reference entry and its attempt to follow the cross reference will fail. As a general rule, you should write a period or comma after every `@ref' command. This looks best in both the printed and the Info output. File: texinfo, Node: pxref, Next: inforef, Prev: ref, Up: Cross References `@pxref' ======== The parenthetical reference command, `@pxref', is nearly the same as `@xref', but you use it *only* inside parentheses and you do *not* type a comma or period after the command's closing brace. The command differs from `@xref' in two ways: 1. TeX typesets the reference for the printed manual with a lower case `see' rather than an upper case `See'. 2. The Info formatting commands automatically end the reference with a closing colon or period. Because one type of formatting automatically inserts closing punctuation and the other does not, you should use `@pxref' *only* inside parentheses as part of another sentence. Also, you yourself should not insert punctuation after the reference, as you do with `@xref'. `@pxref' is designed so that the output looks right and works right between parentheses both in printed output and in an Info file. In a printed manual, a closing comma or period should not follow a cross reference within parentheses; such punctuation is wrong. But in an Info file, suitable closing punctuation must follow the cross reference so Info can recognize its end. `@pxref' spares you the need to use complicated methods to put a terminator into one form of the output and not the other. With one argument, a parenthetical cross reference looks like this: ... storms cause flooding (@pxref{Hurricanes}) ... produces ... storms cause flooding (*Note Hurricanes::) ... and ... storms cause flooding (see Section 6.7 [Hurricanes], page 72) ... With two arguments, a parenthetical cross reference has this template: ... (@pxref{NODE-NAME, CROSS-REFERENCE-NAME}) ... produces ... (*Note CROSS-REFERENCE-NAME: NODE-NAME.) ... and ... (see Section NNN [NODE-NAME], page PPP) ... `@pxref' can be used with up to five arguments just like `@xref' (*note `@xref': xref.). *Please note:* Use `@pxref' only as a parenthetical reference. Do not try to use `@pxref' as a clause in a sentence. It will look bad in either the Info file, the printed output, or both. Also, parenthetical cross references look best at the ends of sentences. Although you may write them in the middle of a sentence, that location breaks up the flow of text. File: texinfo, Node: inforef, Prev: pxref, Up: Cross References `@inforef' ========== `@inforef' is used for cross references to Info files for which there are no printed manuals. Even in a printed manual, `@inforef' generates a reference directing the user to look in an Info file. The command takes either two or three arguments, in the following order: 1. The node name. 2. The cross reference name (optional). 3. The Info file name. Separate the arguments with commas, as with `@xref'. Also, you must terminate the reference with a comma or period after the `}', as you do with `@xref'. The template is: @inforef{NODE-NAME, CROSS-REFERENCE-NAME, INFO-FILE-NAME}, Thus, @inforef{Expert, Advanced Info commands, info}, for more information. produces *Note Advanced Info commands: (info)Expert, for more information. and See Info file `info', node `Expert', for more information. Similarly, @inforef{Expert, , info}, for more information. produces *Note (info)Expert::, for more information. and See Info file `info', node `Expert', for more information. The converse of `@inforef' is `@cite', which is used to refer to printed works for which no Info form exists. *Note `@cite': cite. File: texinfo, Node: Marking Text, Next: Quotations and Examples, Prev: Cross References, Up: Top Marking Words and Phrases ************************* In Texinfo, you can mark words and phrases in a variety of ways. The Texinfo formatters use this information to determine how to highlight the text. You can specify, for example, whether a word or phrase is a defining occurrence, a metasyntactic variable, or a symbol used in a program. Also, you can emphasize text. * Menu: * Indicating:: How to indicate definitions, files, etc. * Emphasis:: How to emphasize text. File: texinfo, Node: Indicating, Next: Emphasis, Up: Marking Text Indicating Definitions, Commands, etc. ====================================== Texinfo has commands for indicating just what kind of object a piece of text refers to. For example, metasyntactic variables are marked by `@var', and code by `@code'. Since the pieces of text are labelled by commands that tell what kind of object they are, it is easy to change the way the Texinfo formatters prepare such text. (Texinfo is an *intentional* formatting language rather than a *typesetting* formatting language.) For example, in a printed manual, code is usually illustrated in a typewriter font; `@code' tells TeX to typeset this text in this font. But it would be easy to change the way TeX highlights code to use another font, and this change would not effect how keystroke examples are highlighted. If straight typesetting commands were used in the body of the file and you wanted to make a change, you would need to check every single occurrence to make sure that you were changing code and not something else that should not be changed. * Menu: * Useful Highlighting:: Highlighting provides useful information. * code:: How to indicate code. * kbd:: How to show keyboard input. * key:: How to specify keys. * samp:: How to show a literal sequence of characters. * var:: How to indicate a metasyntactic variable. * file:: How to indicate the name of a file. * dfn:: How to specify a definition. * cite:: How to refer to a book that is not in Info. File: texinfo, Node: Useful Highlighting, Next: code, Up: Indicating Highlighting Commands are Useful -------------------------------- The highlighting commands can be used to generate useful information from the file, such as lists of functions or file names. It is possible, for example, to write a program in Emacs Lisp (or a keyboard macro) to insert an index entry after every paragraph that contains words or phrases marked by a specified command. You could do this to construct an index of functions if you had not already made the entries. The commands serve a variety of purposes: `@code{SAMPLE-CODE}' Indicate text that is a literal example of a piece of a program. `@kbd{KEYBOARD-CHARACTERS}' Indicate keyboard input. `@key{KEY-NAME}' Indicate the conventional name for a key on a keyboard. `@samp{TEXT}' Indicate text that is a literal example of a sequence of characters. `@var{METASYNTACTIC-VARIABLE}' Indicate a metasyntactic variable. `@file{FILE-NAME}' Indicate the name of a file. `@dfn{TERM}' Indicate the introductory or defining use of a term. `@cite{REFERENCE}' Indicate the name of a book. File: texinfo, Node: code, Next: kbd, Prev: Useful Highlighting, Up: Indicating `@code'{SAMPLE-CODE} -------------------- Use the `@code' command to indicate text that is a piece of a program and which consists of entire syntactic tokens. Enclose the text in braces. Thus, you should use `@code' for an expression in a program, for the name of a variable or function used in a program, or for a keyword. Also, you should use `@code' for the name of a program, such as `diff', that is a name used in the machine. (You should write the name of a program in the ordinary text font if you regard it as a new English word, such as `Emacs' or `Bison'.) Use `@code' for environment variables such as `TEXINPUTS', and other variables. Use `@code' for command names in command languages that resemble programming languages, such as Texinfo or the shell. For example, `@code' and `@samp' are produced by writing `@code{@@code}' and `@code{@@samp}' in the Texinfo source, respectively. Note, however, that you should not use `@code' for shell options such as `-c' when such options stand alone. (Use `@samp'.) Also, an entire shell command often looks better if written using `@samp' rather than `@code'. In this case, the rule is to choose the more pleasing format. It is incorrect to alter the case of a word inside an `@code' command when it appears at the beginning of a sentence. Most computer languages are case sensitive. In C, for example, `Printf' is different from the identifier `printf', and most likely is a misspelling of it. Even in languages which are not case sensitive, it is confusing to a human reader to see identifiers spelled in different ways. Pick one spelling and always use that. If you do not want to start a sentence with a command written all in lower case, you should rearrange the sentence. Do not use the `@code' command for a string of characters shorter than a syntactic token. If you are writing about `TEXINPU', which is just a part of the name for the `TEXINPUTS' environment variable, you should use `@samp'. In particular, you should not use the `@code' command when writing about the characters used in a token; do not, for example, use `@code' when you are explaining what letters or printable symbols can be used in the names of functions. (Use `@samp'.) Also, you should not use `@code' to mark text that is considered input to programs unless the input is written in a language that is like a programming language. For example, you should not use `@code' for the keystroke commands of GNU Emacs (use `@kbd' instead) although you may use `@code' for the names of the Emacs Lisp functions that the keystroke commands invoke. In the printed manual, `@code' causes TeX to typeset the argument in a typewriter face. In the Info file, it causes the Info formatting commands to use single quotation marks around the text. For example, Use @code{diff} to compare two files. produces this in the printed manual: Use `diff' to compare two files. File: texinfo, Node: kbd, Next: key, Prev: code, Up: Indicating `@kbd'{KEYBOARD-CHARACTERS} --------------------------- Use the `@kbd' command for characters of input to be typed by users. For example, to refer to the characters `M-a', write @kbd{M-a} and to refer to the characters `M-x shell', write @kbd{M-x shell} The `@kbd' command has the same effect as `@code' in Info, but may produce a different font in a printed manual. You can embed another @-command inside the braces of an `@kbd' command. Here, for example, is the way to describe a command that would be described more verbosely as "press an `r' and then press the RET key": @kbd{r @key{RET}} This produces: `r RET' You also use the `@kbd' command if you are spelling out the letters you type; for example: To give the @code{logout} command, type the characters @kbd{l o g o u t @key{RET}}. This produces: To give the `logout' command, type the characters `l o g o u t RET'. (Also, this example shows that you can add spaces for clarity. If you really want to mention a space character as one of the characters of input, write `@key{SPC}' for it.) File: texinfo, Node: key, Next: samp, Prev: kbd, Up: Indicating `@key'{KEY-NAME} ---------------- Use the `@key' command for the conventional name for a key on a keyboard, as in: @key{RET} You can use the `@key' command within the argument of an `@kbd' command when the sequence of characters to be typed includes one or more keys that are described by name. For example, to produce `C-x ESC' you would type: @kbd{C-x @key{ESC}} Here is a list of the recommended names for keys; they are all in upper case: SPC Space RET Return LFD Linefeed TAB Tab BS Backspace ESC Escape DEL Delete SFT Shift CTL Control META Meta There are subtleties to handling words like `meta' or `ctl' that are names of shift keys. When mentioning a character in which the shift key is used, such as `Meta-a', use the `@kbd' command alone; do not use the `@key' command; but when you are referring to the shift key in isolation, use the `@key' command. For example, write `@kbd{Meta-a}' to produce `Meta-a' and `@key{META}' to produce META. This is because `Meta-a' refers to keys that you press on a keyboard, but META refers to a key without implying that you press it. In short, use `@kbd' for what you do, and use `@key' for what you talk about: "Press `@kbd{M-a}' to move point to the beginning of the sentence. The `@key{META}' is often in the lower left of the keyboard." File: texinfo, Node: samp, Next: var, Prev: key, Up: Indicating `@samp'{TEXT} ------------- Use the `@samp' command to indicate text that is a literal example or `sample' of a sequence of characters in a file, string, pattern, etc. Enclose the text in braces. The argument appears within single quotation marks in both the Info file and the printed manual; in addition, it is printed in a fixed-width font. To match @samp{foo} at the end of the line, use the regexp @samp{foo$}. produces To match `foo' at the end of the line, use the regexp `foo$'. Any time you are referring to single characters, you should use `@samp' unless `@kbd' is more appropriate. Use `@samp' for the names of command-line options. Also, you may use `@samp' for entire statements in C and for entire shell commands--in this case, `@samp' often looks better than `@code'. Basically, `@samp' is a catchall for whatever is not covered by `@code', `@kbd', or `@key'. Only include punctuation marks within braces if they are part of the string you are specifying. Write punctuation marks outside the braces if those punctuation marks are part of the English text that surrounds the string. In the following sentence, for example, the commas and period are outside of the braces: In English, the vowels are @samp{a}, @samp{e}, @samp{i}, @samp{o}, @samp{u}, and sometimes @samp{y}. This produces: In English, the vowels are `a', `e', `i', `o', `u', and sometimes `y'. File: texinfo, Node: var, Next: file, Prev: samp, Up: Indicating `@var'{METASYNTACTIC-VARIABLE} ------------------------------ Use the `@var' command to indicate metasyntactic variables. A "metasyntactic variable" is something that stands for another piece of text. For example, you should use a metasyntactic variable in the documentation of a function to describe the arguments that are passed to that function. Do not use `@var' for the names of particular variables in programming languages. These are specific names from a program, so `@code' is correct for them. For example, the Lisp variable `texinfo-tex-command' is not a metasyntactic variable; it is properly formatted using `@code'. The effect of `@var' in the Info file is to upcase the argument; in the printed manual, to italicize it. For example, To delete file @var{filename}, type @code{rm @var{filename}}. produces To delete file FILENAME, type `rm FILENAME'. (Note that `@var' may appear inside `@code', `@samp', `@file', etc.) Write a metasyntactic variable all in lower case without spaces, and use hyphens to make it more readable. Thus, the illustration of how to begin a Texinfo manual looks like this: \input texinfo @setfilename INFO-FILE-NAME @settitle NAME-OF-MANUAL In some documentation styles, metasyntactic variables are shown with angle brackets, for example: ..., type rm <filename> However, that is not the style that Texinfo uses. (You can, of course, modify the sources to TeX and the Info formatting commands to output the `<...>' format if you wish.) File: texinfo, Node: file, Next: dfn, Prev: var, Up: Indicating `@file'{FILE-NAME} ------------------ Use the `@file' command to indicate text that is the name of a file, buffer, or directory, or is the name of a node in Info. You can also use the command for file name suffixes. Do not use `@file' for symbols in a programming language; use `@code'. Currently, `@file' is equivalent to `@samp' in its effects on the output. For example, The @file{.el} files are in the @file{/usr/local/emacs/lisp} directory. produces The `.el' files are in the `/usr/local/emacs/lisp' directory. File: texinfo, Node: dfn, Next: cite, Prev: file, Up: Indicating `@dfn'{TERM} ------------ Use the `@dfn' command to identify the introductory or defining use of a technical term. Use the command only in passages whose purpose is to introduce a term which will be used again or which the reader ought to know. Mere passing mention of a term for the first time does not deserve `@dfn'. The command generates italics in the printed manual, and double quotation marks in the Info file. For example: Getting rid of a file is called @dfn{deleting} it. produces Getting rid of a file is called "deleting" it. As a general rule, a sentence containing the defining occurrence of a term should be a definition of the term. The sentence does not need to say explicitly that it is a definition, but it should contain the information of a definition--it should make the meaning clear. File: texinfo, Node: cite, Prev: dfn, Up: Indicating `@cite'{REFERENCE} ------------------ Use the `@cite' command for the name of a book that lacks a companion Info file. The command produces italics in the printed manual, and quotation marks in the Info file. (If a book is written in Texinfo, it is better to use a cross reference command since a reader can easily follow such a reference in Info. *Note `@xref': xref.) File: texinfo, Node: Emphasis, Prev: Indicating, Up: Marking Text Emphasizing Text ================ Usually, Texinfo changes the font to mark words in the text according to what category the words belong to; an example is the `@code' command. Most often, this is the best way to mark words. However, sometimes you will want to emphasize text without indicating a category. Texinfo has two commands to do this. Also, Texinfo has several commands that specify the font in which TeX will typeset text. These commands have no affect on Info and only one of them, the `@r' command, has any regular use. * Menu: * emph & strong:: How to emphasize text in Texinfo. * Smallcaps:: How to use the small caps font. * Fonts:: Various font commands for printed output. File: texinfo, Node: emph & strong, Next: Smallcaps, Up: Emphasis `@emph'{TEXT} and `@strong'{TEXT} --------------------------------- The `@emph' and `@strong' commands are for emphasis; `@strong' is stronger. In printed output, `@emph' produces *italics* and `@strong' produces *bold*. For example, @quotation @strong{Caution:} @code{rm * .[^.]*} removes @emph{all} files in the directory. @end quotation produces: *Caution*: `rm * .[^.]*' removes *all* files in the directory. The `@strong' command is seldom used except to mark what is, in effect, a typographical element, such as the word `Caution' in the preceding example.(1) In the Info file, both `@emph' and `@strong' put asterisks around the text. ---------- Footnotes ---------- (1) Do not use `@emph' or `@strong' with the word `Note'; Info will mistake the combination for a cross reference. Use a phrase such as *Please note* or *Caution* instead.