home *** CD-ROM | disk | FTP | other *** search
/ Geek Gadgets 1 / ADE-1.bin / ade-bin / info / texinfo.info-4 < prev    next >
Encoding:
GNU Info File  |  1996-10-12  |  49.5 KB  |  1,432 lines
  1. This is Info file texinfo.info, produced by Makeinfo-1.64 from the
  2. input file /ade-src/fsf/texinfo/texinfo.texi.
  3.  
  4.   This file documents Texinfo, a documentation system that uses a single
  5. source file to produce both on-line information and a printed manual.
  6.  
  7.   Copyright (C) 1988, 1990, 1991, 1992, 1993, 1995 Free Software
  8. Foundation, Inc.
  9.  
  10.   This is the second edition of the Texinfo documentation,
  11. and is consistent with version 2 of `texinfo.tex'.
  12.  
  13.   Permission is granted to make and distribute verbatim copies of this
  14. manual provided the copyright notice and this permission notice are
  15. preserved on all copies.
  16.  
  17.   Permission is granted to copy and distribute modified versions of this
  18. manual under the conditions for verbatim copying, provided that the
  19. entire resulting derived work is distributed under the terms of a
  20. permission notice identical to this one.
  21.  
  22.   Permission is granted to copy and distribute translations of this
  23. manual into another language, under the above conditions for modified
  24. versions, except that this permission notice may be stated in a
  25. translation approved by the Free Software Foundation.
  26.  
  27. 
  28. File: texinfo.info,  Node: Writing a Node,  Next: Node Line Tips,  Prev: Node Names,  Up: node
  29.  
  30. How to Write an `@node' Line
  31. ----------------------------
  32.  
  33.   The easiest way to write an `@node' line is to write `@node' at the
  34. beginning of a line and then the name of the node, like this:
  35.  
  36.      @node NODE-NAME
  37.  
  38.   If you are using GNU Emacs, you can use the update node commands
  39. provided by Texinfo mode to insert the names of the pointers; or you
  40. can leave the pointers out of the Texinfo file and let `makeinfo'
  41. insert node pointers into the Info file it creates.  (*Note Texinfo
  42. Mode::, and *Note makeinfo Pointer Creation::.)
  43.  
  44.   Alternatively, you can insert the `Next', `Previous', and `Up'
  45. pointers yourself.  If you do this, you may find it helpful to use the
  46. Texinfo mode keyboard command `C-c C-c n'.  This command inserts
  47. `@node' and a comment line listing the names of the pointers in their
  48. proper order.  The comment line helps you keep track of which arguments
  49. are for which pointers.  This comment line is especially useful if you
  50. are not familiar with Texinfo.
  51.  
  52.   The template for a node line with `Next', `Previous', and `Up'
  53. pointers looks like this:
  54.  
  55.      @node NODE-NAME, NEXT, PREVIOUS, UP
  56.  
  57.   If you wish, you can ignore `@node' lines altogether in your first
  58. draft and then use the `texinfo-insert-node-lines' command to create
  59. `@node' lines for you.  However, we do not recommend this practice.  It
  60. is better to name the node itself at the same time that you write a
  61. segment so you can easily make cross references.  A large number of
  62. cross references are an especially important feature of a good Info
  63. file.
  64.  
  65.   After you have inserted an `@node' line, you should immediately write
  66. an @-command for the chapter or section and insert its name.  Next (and
  67. this is important!), put in several index entries.  Usually, you will
  68. find at least two and often as many as four or five ways of referring
  69. to the node in the index.  Use them all.  This will make it much easier
  70. for people to find the node.
  71.  
  72. 
  73. File: texinfo.info,  Node: Node Line Tips,  Next: Node Line Requirements,  Prev: Writing a Node,  Up: node
  74.  
  75. `@node' Line Tips
  76. -----------------
  77.  
  78.   Here are three suggestions:
  79.  
  80.    * Try to pick node names that are informative but short.
  81.  
  82.      In the Info file, the file name, node name, and pointer names are
  83.      all inserted on one line, which may run into the right edge of the
  84.      window.  (This does not cause a problem with Info, but is ugly.)
  85.  
  86.    * Try to pick node names that differ from each other near the
  87.      beginnings of their names.  This way, it is easy to use automatic
  88.      name completion in Info.
  89.  
  90.    * By convention, node names are capitalized just as they would be for
  91.      section or chapter titles--initial and significant words are
  92.      capitalized; others are not.
  93.  
  94. 
  95. File: texinfo.info,  Node: Node Line Requirements,  Next: First Node,  Prev: Node Line Tips,  Up: node
  96.  
  97. `@node' Line Requirements
  98. -------------------------
  99.  
  100.   Here are several requirements for `@node' lines:
  101.  
  102.    * All the node names for a single Info file must be unique.
  103.  
  104.      Duplicates confuse the Info movement commands.  This means, for
  105.      example, that if you end every chapter with a summary, you must
  106.      name each summary node differently.  You cannot just call each one
  107.      "Summary".  You may, however, duplicate the titles of chapters,
  108.      sections, and the like.  Thus you can end each chapter in a book
  109.      with a section called "Summary", so long as the node names for
  110.      those sections are all different.
  111.  
  112.    * A pointer name must be the name of a node.
  113.  
  114.      The node to which a pointer points may come before or after the
  115.      node containing the pointer.
  116.  
  117.    * You cannot use any of the Texinfo @-commands in a node name;
  118.      @-commands confuse Info.
  119.  
  120.      Thus, the beginning of the section called `@chapter' looks like
  121.      this:
  122.  
  123.           @node  chapter, unnumbered & appendix, makeinfo top, Structuring
  124.           @comment  node-name,  next,  previous,  up
  125.           @section @code{@@chapter}
  126.           @findex chapter
  127.  
  128.    * You cannot use commas, colons, or apostrophes within a node name;
  129.      these confuse TeX or the Info formatters.
  130.  
  131.      For example, the following is a section title:
  132.  
  133.           @code{@@unnumberedsec}, @code{@@appendixsec}, @code{@@heading}
  134.  
  135.      The corresponding node name is:
  136.  
  137.           unnumberedsec appendixsec heading
  138.  
  139.    * Case is significant.
  140.  
  141. 
  142. File: texinfo.info,  Node: First Node,  Next: makeinfo top command,  Prev: Node Line Requirements,  Up: node
  143.  
  144. The First Node
  145. --------------
  146.  
  147.   The first node of a Texinfo file is the `Top' node, except in an
  148. included file (*note Include Files::.).
  149.  
  150.   The `Top' node (which must be named `top' or `Top') should have as
  151. its `Up' and `Previous' nodes the name of a node in another file, where
  152. there is a menu that leads to this file.  Specify the file name in
  153. parentheses.  If the file is to be installed directly in the Info
  154. directory file, use `(dir)' as the parent of the `Top' node; this is
  155. short for `(dir)top', and specifies the `Top' node in the `dir' file,
  156. which contains the main menu for Info.  For example, the `@node Top'
  157. line of this manual looks like this:
  158.  
  159.      @node Top, Overview, (dir), (dir)
  160.  
  161. (You may use the Texinfo updating commands or the `makeinfo' utility to
  162. insert these `Next' and `(dir)' pointers automatically.)
  163.  
  164.   *Note Install an Info File::, for more information about installing
  165. an Info file in the `info' directory.
  166.  
  167.   The `Top' node contains the main or master menu for the document.
  168.  
  169. 
  170. File: texinfo.info,  Node: makeinfo top command,  Next: Top Node Summary,  Prev: First Node,  Up: node
  171.  
  172. The `@top' Sectioning Command
  173. -----------------------------
  174.  
  175.   A special sectioning command, `@top', has been created for use with
  176. the `@node Top' line.  The `@top' sectioning command tells `makeinfo'
  177. that it marks the `Top' node in the file.  It provides the information
  178. that `makeinfo' needs to insert node pointers automatically.  Write the
  179. `@top' command at the beginning of the line immediately following the
  180. `@node Top' line.  Write the title on the remaining part of the same
  181. line as the `@top' command.
  182.  
  183.   In Info, the `@top' sectioning command causes the title to appear on a
  184. line by itself, with a line of asterisks inserted underneath.
  185.  
  186.   In TeX and `texinfo-format-buffer', the `@top' sectioning command is
  187. merely a synonym for `@unnumbered'.  Neither of these formatters
  188. require an `@top' command, and do nothing special with it.  You can use
  189. `@chapter' or `@unnumbered' after the `@node Top' line when you use
  190. these formatters.  Also, you can use `@chapter' or `@unnumbered' when
  191. you use the Texinfo updating commands to create or update pointers and
  192. menus.
  193.  
  194. 
  195. File: texinfo.info,  Node: Top Node Summary,  Prev: makeinfo top command,  Up: node
  196.  
  197. The `Top' Node Summary
  198. ----------------------
  199.  
  200.   You can help readers by writing a summary in the `Top' node, after the
  201. `@top' line, before the main or master menu.  The summary should
  202. briefly describe the document.  In Info, this summary will appear just
  203. before the master menu.  In a printed manual, this summary will appear
  204. on a page of its own.
  205.  
  206.   If you do not want the summary to appear on a page of its own in a
  207. printed manual, you can enclose the whole of the `Top' node, including
  208. the `@node Top' line and the `@top' sectioning command line or other
  209. sectioning command line between `@ifinfo' and `@end ifinfo'.  This
  210. prevents any of the text from appearing in the printed output. (*note
  211. Conditionally Visible Text: Conditionals.).  You can repeat the brief
  212. description from the `Top' node within `@iftex' ... `@end iftex' at the
  213. beginning of the first chapter, for those who read the printed manual.
  214. This saves paper and may look neater.
  215.  
  216.   You should write the version number of the program to which the manual
  217. applies in the summary.  This helps the reader keep track of which
  218. manual is for which version of the program.  If the manual changes more
  219. frequently than the program or is independent of it, you should also
  220. include an edition number for the manual.  (The title page should also
  221. contain this information: see *Note `@titlepage': titlepage.)
  222.  
  223. 
  224. File: texinfo.info,  Node: makeinfo Pointer Creation,  Prev: node,  Up: Nodes
  225.  
  226. Creating Pointers with `makeinfo'
  227. =================================
  228.  
  229.   The `makeinfo' program has a feature for automatically creating node
  230. pointers for a hierarchically organized file that lacks them.
  231.  
  232.   When you take advantage of this feature, you do not need to write the
  233. `Next', `Previous', and `Up' pointers after the name of a node.
  234. However, you must write a sectioning command, such as `@chapter' or
  235. `@section', on the line immediately following each truncated `@node'
  236. line.  You cannot write a comment line after a node line; the section
  237. line must follow it immediately.
  238.  
  239.   In addition, you must follow the `Top' `@node' line with a line
  240. beginning with `@top' to mark the `Top' node in the file. *Note `@top':
  241. makeinfo top.
  242.  
  243.   Finally, you must write the name of each node (except for the `Top'
  244. node) in a menu that is one or more hierarchical levels above the
  245. node's hierarchical level.
  246.  
  247.   This node pointer insertion feature in `makeinfo' is an alternative
  248. to the menu and pointer creation and update commands in Texinfo mode.
  249. (*Note Updating Nodes and Menus::.)  It is especially helpful to people
  250. who do not use GNU Emacs for writing Texinfo documents.
  251.  
  252. 
  253. File: texinfo.info,  Node: Menus,  Next: Cross References,  Prev: Nodes,  Up: Top
  254.  
  255. Menus
  256. *****
  257.  
  258.   "Menus" contain pointers to subordinate nodes.(1) (*note
  259. Menus-Footnotes::) In Info, you use menus to go to such nodes.  Menus
  260. have no effect in printed manuals and do not appear in them.
  261.  
  262.   By convention, a menu is put at the end of a node since a reader who
  263. uses the menu may not see text that follows it.
  264.  
  265.   A node that has a menu should *not* contain much text.  If you have a
  266. lot of text and a menu, move most of the text into a new subnode--all
  267. but a few lines.
  268.  
  269. * Menu:
  270.  
  271. * Menu Location::               Put a menu in a short node.
  272. * Writing a Menu::              What is a menu?
  273. * Menu Parts::                  A menu entry has three parts.
  274. * Less Cluttered Menu Entry::   Two part menu entry.
  275. * Menu Example::                Two and three part menu entries.
  276. * Other Info Files::            How to refer to a different Info file.
  277.  
  278. 
  279. File: texinfo.info,  Node: Menus-Footnotes,  Up: Menus
  280.  
  281.   (1)  Menus can carry you to any node, regardless of the hierarchical
  282. structure; even to nodes in a different Info file.  However, the GNU
  283. Emacs Texinfo mode updating commands work only to create menus of
  284. subordinate nodes.  Conventionally, cross references are used to refer
  285. to other nodes.
  286.  
  287. 
  288. File: texinfo.info,  Node: Menu Location,  Next: Writing a Menu,  Prev: Menus,  Up: Menus
  289.  
  290. Menus Need Short Nodes
  291. ======================
  292.  
  293.   A reader can easily see a menu that is close to the beginning of the
  294. node.  The node should be short.  As a practical matter, you should
  295. locate a menu within 20 lines of the beginning of the node.  Otherwise,
  296. a reader with a terminal that displays only a few lines may miss the
  297. menu and its associated text.
  298.  
  299.   The short text before a menu may look awkward in a printed manual.  To
  300. avoid this, you can write a menu near the beginning of its node and
  301. follow the menu by an `@node' line, and then an `@heading' line located
  302. within `@ifinfo' and `@end ifinfo'.  This way, the menu, `@node' line,
  303. and title appear only in the Info file, not the printed document.
  304.  
  305.   For example, the preceding two paragraphs follow an Info-only menu,
  306. `@node' line, and heading, and look like this:
  307.  
  308.      @menu
  309.      * Menu Location::             Put a menu in a short node.
  310.      * Writing a Menu::            What is a menu?
  311.      * Menu Parts::                A menu entry has three parts.
  312.      * Less Cluttered Menu Entry:: Two part menu entry.
  313.      * Menu Example::              Two and three part entries.
  314.      * Other Info Files::          How to refer to a different
  315.                                      Info file.
  316.      @end menu
  317.      
  318.      @node Menu Location, Writing a Menu,  , Menus
  319.      @ifinfo
  320.      @heading Menus Need Short Nodes
  321.      @end ifinfo
  322.  
  323.   The Texinfo file for this document contains more than a dozen
  324. examples of this procedure.  One is at the beginning of this chapter;
  325. another is at the beginning of the "Cross References" chapter.
  326.  
  327. 
  328. File: texinfo.info,  Node: Writing a Menu,  Next: Menu Parts,  Prev: Menu Location,  Up: Menus
  329.  
  330. Writing a Menu
  331. ==============
  332.  
  333.   A menu consists of an `@menu' command on a line by itself followed by
  334. menu entry lines or menu comment lines and then by an `@end menu'
  335. command on a line by itself.
  336.  
  337.   A menu looks like this:
  338.  
  339.      @menu
  340.      Larger Units of Text
  341.      
  342.      * Files::                       All about handling files.
  343.      * Multiples: Buffers.           Multiple buffers; editing
  344.                                        several files at once.
  345.      @end menu
  346.  
  347.   In a menu, every line that begins with an `* ' is a "menu entry".
  348. (Note the space after the asterisk.)  A line that does not start with
  349. an `* ' may also appear in a menu.  Such a line is not a menu entry but
  350. is a menu comment line that appears in the Info file.  In the example
  351. above, the line `Larger Units of Text' is a menu comment line; the two
  352. lines starting with `* ' are menu entries.
  353.  
  354. 
  355. File: texinfo.info,  Node: Menu Parts,  Next: Less Cluttered Menu Entry,  Prev: Writing a Menu,  Up: Menus
  356.  
  357. The Parts of a Menu
  358. ===================
  359.  
  360.   A menu entry has three parts, only the second of which is required:
  361.  
  362.   1. The menu entry name.
  363.  
  364.   2. The name of the node (required).
  365.  
  366.   3. A description of the item.
  367.  
  368.   The template for a menu entry looks like this:
  369.  
  370.      * MENU-ENTRY-NAME: NODE-NAME.   DESCRIPTION
  371.  
  372.   Follow the menu entry name with a single colon and follow the node
  373. name with tab, comma, period, or newline.
  374.  
  375.   In Info, a user selects a node with the `m' (`Info-menu') command.
  376. The menu entry name is what the user types after the `m' command.
  377.  
  378.   The third part of a menu entry is a descriptive phrase or sentence.
  379. Menu entry names and node names are often short; the description
  380. explains to the reader what the node is about.  The description, which
  381. is optional, can spread over two or more lines.  A useful description
  382. complements the node name rather than repeats it.
  383.  
  384. 
  385. File: texinfo.info,  Node: Less Cluttered Menu Entry,  Next: Menu Example,  Prev: Menu Parts,  Up: Menus
  386.  
  387. Less Cluttered Menu Entry
  388. =========================
  389.  
  390.   When the menu entry name and node name are the same, you can write
  391. the name immediately after the asterisk and space at the beginning of
  392. the line and follow the name with two colons.
  393.  
  394.   For example, write
  395.  
  396.      * Name::                                    DESCRIPTION
  397.  
  398. instead of
  399.  
  400.      * Name: Name.                               DESCRIPTION
  401.  
  402.   You should use the node name for the menu entry name whenever
  403. possible, since it reduces visual clutter in the menu.
  404.  
  405. 
  406. File: texinfo.info,  Node: Menu Example,  Next: Other Info Files,  Prev: Less Cluttered Menu Entry,  Up: Menus
  407.  
  408. A Menu Example
  409. ==============
  410.  
  411.   A menu looks like this in Texinfo:
  412.  
  413.      @menu
  414.      * menu entry name: Node name.   A short description.
  415.      * Node name::                   This form is preferred.
  416.      @end menu
  417.  
  418. This produces:
  419.  
  420.      * menu:
  421.      
  422.      * menu entry name: Node name.   A short description.
  423.      * Node name::                   This form is preferred.
  424.  
  425.   Here is an example as you might see it in a Texinfo file:
  426.  
  427.      @menu
  428.      Larger Units of Text
  429.      
  430.      * Files::                       All about handling files.
  431.      * Multiples: Buffers.           Multiple buffers; editing
  432.                                        several files at once.
  433.      @end menu
  434.  
  435. This produces:
  436.  
  437.      * menu:
  438.      Larger Units of Text
  439.      
  440.      * Files::                       All about handling files.
  441.      * Multiples: Buffers.           Multiple buffers; editing
  442.                                        several files at once.
  443.  
  444.   In this example, the menu has two entries.  `Files' is both a menu
  445. entry name and the name of the node referred to by that name.
  446. `Multiples' is the menu entry name; it refers to the node named
  447. `Buffers'. The line `Larger Units of Text' is a comment; it appears in
  448. the menu, but is not an entry.
  449.  
  450.   Since no file name is specified with either `Files' or `Buffers',
  451. they must be the names of nodes in the same Info file (*note Referring
  452. to Other Info Files: Other Info Files.).
  453.  
  454. 
  455. File: texinfo.info,  Node: Other Info Files,  Prev: Menu Example,  Up: Menus
  456.  
  457. Referring to Other Info Files
  458. =============================
  459.  
  460.   You can create a menu entry that enables a reader in Info to go to a
  461. node in another Info file by writing the file name in parentheses just
  462. before the node name.  In this case, you should use the three-part menu
  463. entry format, which saves the reader from having to type the file name.
  464.  
  465.   The format looks like this:
  466.  
  467.      @menu
  468.      * FIRST-ENTRY-NAME:(FILENAME)NODENAME.     DESCRIPTION
  469.      * SECOND-ENTRY-NAME:(FILENAME)SECOND-NODE. DESCRIPTION
  470.      @end menu
  471.  
  472.   For example, to refer directly to the `Outlining' and `Rebinding'
  473. nodes in the `Emacs Manual', you would write a menu like this:
  474.  
  475.      @menu
  476.      * Outlining: (emacs)Outline Mode. The major mode for
  477.                                        editing outlines.
  478.      * Rebinding: (emacs)Rebinding.    How to redefine the
  479.                                        meaning of a key.
  480.      @end menu
  481.  
  482.   If you do not list the node name, but only name the file, then Info
  483. presumes that you are referring to the `Top' node.
  484.  
  485.   The `dir' file that contains the main menu for Info has menu entries
  486. that list only file names.  These take you directly to the `Top' nodes
  487. of each Info document.  (*Note Install an Info File::.)
  488.  
  489.   For example:
  490.  
  491.      * Info: (info).         Documentation browsing system.
  492.      * Emacs: (emacs).       The extensible, self-documenting
  493.                              text editor.
  494.  
  495. (The `dir' top level directory for the Info system is an Info file, not
  496. a Texinfo file, but a menu entry looks the same in both types of file.)
  497.  
  498.   Note that the GNU Emacs Texinfo mode menu updating commands only work
  499. with nodes within the current buffer, so you cannot use them to create
  500. menus that refer to other files.  You must write such menus by hand.
  501.  
  502. 
  503. File: texinfo.info,  Node: Cross References,  Next: Marking Text,  Prev: Menus,  Up: Top
  504.  
  505. Cross References
  506. ****************
  507.  
  508.   "Cross references" are used to refer the reader to other parts of the
  509. same or different Texinfo files.  In Texinfo, nodes are the places to
  510. which cross references can refer.
  511.  
  512. * Menu:
  513.  
  514. * References::                  What cross references are for.
  515. * Cross Reference Commands::    A summary of the different commands.
  516. * Cross Reference Parts::       A cross reference has several parts.
  517. * xref::                        Begin a reference with `See' ...
  518. * Top Node Naming::             How to refer to the beginning of another file.
  519. * ref::                         A reference for the last part of a sentence.
  520. * pxref::                       How to write a parenthetical cross reference.
  521. * inforef::                     How to refer to an Info-only file.
  522.  
  523. 
  524. File: texinfo.info,  Node: References,  Next: Cross Reference Commands,  Prev: Cross References,  Up: Cross References
  525.  
  526. What References Are For
  527. =======================
  528.  
  529.   Often, but not always, a printed document should be designed so that
  530. it can be read sequentially.  People tire of flipping back and forth to
  531. find information that should be presented to them as they need it.
  532.  
  533.   However, in any document, some information will be too detailed for
  534. the current context, or incidental to it; use cross references to
  535. provide access to such information.  Also, an on-line help system or a
  536. reference manual is not like a novel; few read such documents in
  537. sequence from beginning to end.  Instead, people look up what they
  538. need.  For this reason, such creations should contain many cross
  539. references to help readers find other information that they may not
  540. have read.
  541.  
  542.   In a printed manual, a cross reference results in a page reference,
  543. unless it is to another manual altogether, in which case the cross
  544. reference names that manual.
  545.  
  546.   In Info, a cross reference results in an entry that you can follow
  547. using the Info `f' command.  (*note Some advanced Info commands:
  548. (info)Help-Adv.)
  549.  
  550.   The various cross reference commands use nodes to define cross
  551. reference locations.  This is evident in Info, in which a cross
  552. reference takes you to the specified node.  TeX also uses nodes to
  553. define cross reference locations, but the action is less obvious.  When
  554. TeX generates a DVI file, it records nodes' page numbers and uses the
  555. page numbers in making references.  Thus, if you are writing a manual
  556. that will only be printed, and will not be used on-line, you must
  557. nonetheless write `@node' lines to name the places to which you make
  558. cross references.
  559.  
  560. 
  561. File: texinfo.info,  Node: Cross Reference Commands,  Next: Cross Reference Parts,  Prev: References,  Up: Cross References
  562.  
  563. Different Cross Reference Commands
  564. ==================================
  565.  
  566.   There are four different cross reference commands:
  567.  
  568. `@xref'
  569.      Used to start a sentence in the printed manual saying `See ...' or
  570.      an Info cross-reference saying `*Note NAME: NODE.'.
  571.  
  572. `@ref'
  573.      Used within or, more often, at the end of a sentence; same as
  574.      `@xref' for Info; produces just the reference in the printed
  575.      manual without a preceding `See'.
  576.  
  577. `@pxref'
  578.      Used within parentheses to make a reference that suits both an Info
  579.      file and a printed book.  Starts with a lower case `see' within the
  580.      printed manual. (`p' is for `parenthesis'.)
  581.  
  582. `@inforef'
  583.      Used to make a reference to an Info file for which there is no
  584.      printed manual.
  585.  
  586. (The `@cite' command is used to make references to books and manuals
  587. for which there is no corresponding Info file and, therefore, no node
  588. to which to point.   *Note `@cite': cite.)
  589.  
  590. 
  591. File: texinfo.info,  Node: Cross Reference Parts,  Next: xref,  Prev: Cross Reference Commands,  Up: Cross References
  592.  
  593. Parts of a Cross Reference
  594. ==========================
  595.  
  596.   A cross reference command requires only one argument, which is the
  597. name of the node to which it refers.  But a cross reference command may
  598. contain up to four additional arguments.  By using these arguments, you
  599. can provide a cross reference name for Info, a topic description or
  600. section title for the printed output, the name of a different Info
  601. file, and the name of a different printed manual.
  602.  
  603.   Here is a simple cross reference example:
  604.  
  605.      @xref{Node name}.
  606.  
  607. which produces
  608.  
  609.      *Note Node name::.
  610.  
  611. and
  612.  
  613.      See Section NNN [Node name], page PPP.
  614.  
  615.   Here is an example of a full five-part cross reference:
  616.  
  617.      @xref{Node name, Cross Reference Name, Particular Topic,
  618.      info-file-name, A Printed Manual}, for details.
  619.  
  620. which produces
  621.  
  622.      *Note Cross Reference Name: (info-file-name)Node name,
  623.      for details.
  624.  
  625. in Info and
  626.  
  627.      See section "Particular Topic" in A Printed Manual, for details.
  628.  
  629. in a printed book.
  630.  
  631.   The five possible arguments for a cross reference are:
  632.  
  633.   1. The node name (required).  This is the node to which the cross
  634.      reference takes you.  In a printed document, the location of the
  635.      node provides the page reference only for references within the
  636.      same document.
  637.  
  638.   2. The cross reference name for the Info reference, if it is to be
  639.      different from the node name.  If you include this argument, it
  640.      argument becomes the first part of the cross reference. It is
  641.      usually omitted.
  642.  
  643.   3. A topic description or section name.  Often, this is the title of
  644.      the section.  This is used as the name of the reference in the
  645.      printed manual.  If omitted, the node name is used.
  646.  
  647.   4. The name of the Info file in which the reference is located, if it
  648.      is different from the current file.
  649.  
  650.   5. The name of a printed manual from a different Texinfo file.
  651.  
  652.   The template for a full five argument cross reference looks like this:
  653.  
  654.      @xref{NODE-NAME, CROSS-REFERENCE-NAME, TITLE-OR-TOPIC,
  655.      INFO-FILE-NAME, PRINTED-MANUAL-TITLE}.
  656.  
  657.   Cross references with one, two, three, four, and five arguments are
  658. described separately following the description of `@xref'.
  659.  
  660.   Write a node name in a cross reference in exactly the same way as in
  661. the `@node' line, including the same capitalization; otherwise, the
  662. formatters may not find the reference.
  663.  
  664.   You can write cross reference commands within a paragraph, but note
  665. how Info and TeX format the output of each of the various commands:
  666. write `@xref' at the beginning of a sentence; write `@pxref' only
  667. within parentheses, and so on.
  668.  
  669. 
  670. File: texinfo.info,  Node: xref,  Next: Top Node Naming,  Prev: Cross Reference Parts,  Up: Cross References
  671.  
  672. `@xref'
  673. =======
  674.  
  675.   The `@xref' command generates a cross reference for the beginning of
  676. a sentence.  The Info formatting commands convert it into an Info cross
  677. reference, which the Info `f' command can use to bring you directly to
  678. another node.  The TeX typesetting commands convert it into a page
  679. reference, or a reference to another book or manual.
  680.  
  681. * Menu:
  682.  
  683. * Reference Syntax::            What a reference looks like and requires.
  684. * One Argument::                `@xref' with one argument.
  685. * Two Arguments::               `@xref' with two arguments.
  686. * Three Arguments::             `@xref' with three arguments.
  687. * Four and Five Arguments::     `@xref' with four and five arguments.
  688.  
  689. 
  690. File: texinfo.info,  Node: Reference Syntax,  Next: One Argument,  Prev: xref,  Up: xref
  691.  
  692. What a Reference Looks Like and Requires
  693. ----------------------------------------
  694.  
  695.   Most often, an Info cross reference looks like this:
  696.  
  697.      *Note NODE-NAME::.
  698.  
  699. or like this
  700.  
  701.      *Note CROSS-REFERENCE-NAME: NODE-NAME.
  702.  
  703. In TeX, a cross reference looks like this:
  704.  
  705.      See Section SECTION-NUMBER [NODE-NAME], page PAGE.
  706.  
  707. or like this
  708.  
  709.      See Section SECTION-NUMBER [TITLE-OR-TOPIC], page PAGE.
  710.  
  711.   The `@xref' command does not generate a period or comma to end the
  712. cross reference in either the Info file or the printed output.  You
  713. must write that period or comma yourself; otherwise, Info will not
  714. recognize the end of the reference.  (The `@pxref' command works
  715. differently.  *Note `@pxref': pxref.)
  716.  
  717.      *Please note:* A period or comma *must* follow the closing brace
  718.      of an `@xref'.  It is required to terminate the cross reference.
  719.      This period or comma will appear in the output, both in the Info
  720.      file and in the printed manual.
  721.  
  722.   `@xref' must refer to an Info node by name.  Use `@node' to define
  723. the node (*note Writing a Node::.).
  724.  
  725.   `@xref' is followed by several arguments inside braces, separated by
  726. commas.  Whitespace before and after these commas is ignored.
  727.  
  728.   A cross reference requires only the name of a node; but it may contain
  729. up to four additional arguments.  Each of these variations produces a
  730. cross reference that looks somewhat different.
  731.  
  732.      *Please note:* Commas separate arguments in a cross reference;
  733.      avoid including them in the title or other part lest the formatters
  734.      mistake them for separators.
  735.  
  736. 
  737. File: texinfo.info,  Node: One Argument,  Next: Two Arguments,  Prev: Reference Syntax,  Up: xref
  738.  
  739. `@xref' with One Argument
  740. -------------------------
  741.  
  742.   The simplest form of `@xref' takes one argument, the name of another
  743. node in the same Info file.    The Info formatters produce output that
  744. the Info readers can use to jump to the reference; TeX produces output
  745. that specifies the page and section number for you.
  746.  
  747. For example,
  748.  
  749.      @xref{Tropical Storms}.
  750.  
  751. produces
  752.  
  753.      *Note Tropical Storms::.
  754.  
  755. and
  756.  
  757.      See Section 3.1 [Tropical Storms], page 24.
  758.  
  759. (Note that in the preceding example the closing brace is followed by a
  760. period.)
  761.  
  762.   You can write a clause after the cross reference, like this:
  763.  
  764.      @xref{Tropical Storms}, for more info.
  765.  
  766. which produces
  767.  
  768.      *Note Tropical Storms::, for more info.
  769.  
  770.      See Section 3.1 [Tropical Storms], page 24, for more info.
  771.  
  772. (Note that in the preceding example the closing brace is followed by a
  773. comma, and then by the clause, which is followed by a period.)
  774.  
  775. 
  776. File: texinfo.info,  Node: Two Arguments,  Next: Three Arguments,  Prev: One Argument,  Up: xref
  777.  
  778. `@xref' with Two Arguments
  779. --------------------------
  780.  
  781.   With two arguments, the second is used as the name of the Info cross
  782. reference, while the first is still the name of the node to which the
  783. cross reference points.
  784.  
  785. The template is like this:
  786.  
  787.      @xref{NODE-NAME, CROSS-REFERENCE-NAME}.
  788.  
  789. For example,
  790.  
  791.      @xref{Electrical Effects, Lightning}.
  792.  
  793. produces:
  794.  
  795.      *Note Lightning: Electrical Effects.
  796.  
  797. and
  798.  
  799.      See Section 5.2 [Electrical Effects], page 57.
  800.  
  801. (Note that in the preceding example the closing brace is followed by a
  802. period; and that the node name is printed, not the cross reference
  803. name.)
  804.  
  805.   You can write a clause after the cross reference, like this:
  806.  
  807.      @xref{Electrical Effects, Lightning}, for more info.
  808.  
  809. which produces
  810.      *Note Lightning: Electrical Effects, for more info.
  811.  
  812. and
  813.  
  814.      See Section 5.2 [Electrical Effects], page 57, for more info.
  815.  
  816. (Note that in the preceding example the closing brace is followed by a
  817. comma, and then by the clause, which is followed by a period.)
  818.  
  819. 
  820. File: texinfo.info,  Node: Three Arguments,  Next: Four and Five Arguments,  Prev: Two Arguments,  Up: xref
  821.  
  822. `@xref' with Three Arguments
  823. ----------------------------
  824.  
  825.   A third argument replaces the node name in the TeX output.  The third
  826. argument should be the name of the section in the printed output, or
  827. else state the topic discussed by that section.  Often, you will want to
  828. use initial upper case letters so it will be easier to read when the
  829. reference is printed.  Use a third argument when the node name is
  830. unsuitable because of syntax or meaning.
  831.  
  832.   Remember to avoid placing a comma within the title or topic section of
  833. a cross reference, or within any other section.  The formatters divide
  834. cross references into arguments according to the commas; a comma within
  835. a title or other section will divide it into two arguments.  In a
  836. reference, you need to write a title such as "Clouds, Mist, and Fog"
  837. without the commas.
  838.  
  839.   Also, remember to write a comma or period after the closing brace of a
  840. `@xref' to terminate the cross reference.  In the following examples, a
  841. clause follows a terminating comma.
  842.  
  843. The template is like this:
  844.  
  845.      @xref{NODE-NAME, CROSS-REFERENCE-NAME, TITLE-OR-TOPIC}.
  846.  
  847. For example,
  848.  
  849.      @xref{Electrical Effects, Lightning, Thunder and Lightning},
  850.      for details.
  851.  
  852. produces
  853.  
  854.      *Note Lightning: Electrical Effects, for details.
  855.  
  856. and
  857.  
  858.      See Section 5.2 [Thunder and Lightning], page 57, for details.
  859.  
  860.   If a third argument is given and the second one is empty, then the
  861. third argument serves both.  (Note how two commas, side by side, mark
  862. the empty second argument.)
  863.  
  864.      @xref{Electrical Effects, , Thunder and Lightning},
  865.      for details.
  866.  
  867. produces
  868.  
  869.      *Note Thunder and Lightning: Electrical Effects, for details.
  870.  
  871. and
  872.  
  873.      See Section 5.2 [Thunder and Lightning], page 57, for details.
  874.  
  875.   As a practical matter, it is often best to write cross references with
  876. just the first argument if the node name and the section title are the
  877. same, and with the first and third arguments if the node name and title
  878. are different.
  879.  
  880.   Here are several examples from `The GAWK Manual':
  881.  
  882.      @xref{Sample Program}.
  883.      @xref{Glossary}.
  884.      @xref{Case-sensitivity, ,Case-sensitivity in Matching}.
  885.      @xref{Close Output, , Closing Output Files and Pipes},
  886.         for more information.
  887.      @xref{Regexp, , Regular Expressions as Patterns}.
  888.  
  889. 
  890. File: texinfo.info,  Node: Four and Five Arguments,  Prev: Three Arguments,  Up: xref
  891.  
  892. `@xref' with Four and Five Arguments
  893. ------------------------------------
  894.  
  895.   In a cross reference, a fourth argument specifies the name of another
  896. Info file, different from the file in which the reference appears, and
  897. a fifth argument specifies its title as a printed manual.
  898.  
  899.   Remember that a comma or period must follow the closing brace of an
  900. `@xref' command to terminate the cross reference.  In the following
  901. examples, a clause follows a terminating comma.
  902.  
  903. The template is:
  904.  
  905.      @xref{NODE-NAME, CROSS-REFERENCE-NAME, TITLE-OR-TOPIC,
  906.      INFO-FILE-NAME, PRINTED-MANUAL-TITLE}.
  907.  
  908. For example,
  909.  
  910.      @xref{Electrical Effects, Lightning, Thunder and Lightning,
  911.      weather, An Introduction to Meteorology}, for details.
  912.  
  913. produces
  914.  
  915.      *Note Lightning: (weather)Electrical Effects, for details.
  916.  
  917. The name of the Info file is enclosed in parentheses and precedes the
  918. name of the node.
  919.  
  920. In a printed manual, the reference looks like this:
  921.  
  922.      See section "Thunder and Lightning" in An Introduction to
  923.      Meteorology, for details.
  924.  
  925. The title of the printed manual is typeset in italics; and the
  926. reference lacks a page number since TeX cannot know to which page a
  927. reference refers when that reference is to another manual.
  928.  
  929.   Often, you will leave out the second argument when you use the long
  930. version of `@xref'.  In this case, the third argument, the topic
  931. description, will be used as the cross reference name in Info.
  932.  
  933. The template looks like this:
  934.  
  935.      @xref{NODE-NAME, , TITLE-OR-TOPIC, INFO-FILE-NAME,
  936.      PRINTED-MANUAL-TITLE}, for details.
  937.  
  938. which produces
  939.  
  940.      *Note TITLE-OR-TOPIC: (INFO-FILE-NAME)NODE-NAME, for details.
  941.  
  942. and
  943.  
  944.      See section TITLE-OR-TOPIC in PRINTED-MANUAL-TITLE, for details.
  945.  
  946. For example,
  947.  
  948.      @xref{Electrical Effects, , Thunder and Lightning,
  949.      weather, An Introduction to Meteorology}, for details.
  950.  
  951. produces
  952.  
  953.      *Note Thunder and Lightning: (weather)Electrical Effects,
  954.      for details.
  955.  
  956. and
  957.  
  958.      See section "Thunder and Lightning" in An Introduction to
  959.      Meteorology, for details.
  960.  
  961.   On rare occasions, you may want to refer to another Info file that is
  962. within a single printed manual--when multiple Texinfo files are
  963. incorporated into the same TeX run but make separate Info files.  In
  964. this case, you need to specify only the fourth argument, and not the
  965. fifth.
  966.  
  967. 
  968. File: texinfo.info,  Node: Top Node Naming,  Next: ref,  Prev: xref,  Up: Cross References
  969.  
  970. Naming a `Top' Node
  971. ===================
  972.  
  973.   In a cross reference, you must always name a node.  This means that in
  974. order to refer to a whole manual, you must identify the `Top' node by
  975. writing it as the first argument to the `@xref' command.  (This is
  976. different from the way you write a menu entry; see *Note Referring to
  977. Other Info Files: Other Info Files.)  At the same time, to provide a
  978. meaningful section topic or title in the printed cross reference
  979. (instead of the word `Top'), you must write an appropriate entry for
  980. the third argument to the `@xref' command.
  981.  
  982. Thus, to make a cross reference to `The GNU Make Manual', write:
  983.  
  984.      @xref{Top, , Overview, make, The GNU Make Manual}.
  985.  
  986. which produces
  987.  
  988.      *Note Overview: (make)Top.
  989.  
  990. and
  991.  
  992.      See section "Overview" in The GNU Make Manual.
  993.  
  994. In this example, `Top' is the name of the first node, and `Overview' is
  995. the name of the first section of the manual.
  996.  
  997. 
  998. File: texinfo.info,  Node: ref,  Next: pxref,  Prev: Top Node Naming,  Up: Cross References
  999.  
  1000. `@ref'
  1001. ======
  1002.  
  1003.   `@ref' is nearly the same as `@xref' except that it does not generate
  1004. a `See' in the printed output, just the reference itself.  This makes
  1005. it useful as the last part of a sentence.
  1006.  
  1007. For example,
  1008.  
  1009.      For more information, see @ref{Hurricanes}.
  1010.  
  1011. produces
  1012.  
  1013.      For more information, see *Note Hurricanes.
  1014.  
  1015. and
  1016.  
  1017.      For more information, see Section 8.2 [Hurricanes], page 123.
  1018.  
  1019.   The `@ref' command sometimes leads writers to express themselves in a
  1020. manner that is suitable for a printed manual but looks awkward in the
  1021. Info format.  Bear in mind that your audience will be using both the
  1022. printed and the Info format.
  1023.  
  1024. For example,
  1025.  
  1026.      Sea surges are described in @ref{Hurricanes}.
  1027.  
  1028. produces
  1029.  
  1030.      Sea surges are described in Section 6.7 [Hurricanes], page 72.
  1031.  
  1032. in a printed document, and the following in Info:
  1033.  
  1034.      Sea surges are described in *Note Hurricanes::.
  1035.  
  1036.      *Caution:* You *must* write a period or comma immediately after an
  1037.      `@ref' command with two or more arguments.  Otherwise, Info will
  1038.      not find the end of the cross reference entry and its attempt to
  1039.      follow the cross reference will fail.  As a general rule, you
  1040.      should write a period or comma after every `@ref' command.  This
  1041.      looks best in both the printed and the Info output.
  1042.  
  1043. 
  1044. File: texinfo.info,  Node: pxref,  Next: inforef,  Prev: ref,  Up: Cross References
  1045.  
  1046. `@pxref'
  1047. ========
  1048.  
  1049.   The parenthetical reference command, `@pxref', is nearly the same as
  1050. `@xref', but you use it *only* inside parentheses and you do *not* type
  1051. a comma or period after the command's closing brace.  The command
  1052. differs from `@xref' in two ways:
  1053.  
  1054.   1. TeX typesets the reference for the printed manual with a lower case
  1055.      `see' rather than an upper case `See'.
  1056.  
  1057.   2. The Info formatting commands automatically end the reference with a
  1058.      closing colon or period.
  1059.  
  1060.   Because one type of formatting automatically inserts closing
  1061. punctuation and the other does not, you should use `@pxref' *only*
  1062. inside parentheses as part of another sentence.  Also, you yourself
  1063. should not insert punctuation after the reference, as you do with
  1064. `@xref'.
  1065.  
  1066.   `@pxref' is designed so that the output looks right and works right
  1067. between parentheses both in printed output and in an Info file.  In a
  1068. printed manual, a closing comma or period should not follow a cross
  1069. reference within parentheses; such punctuation is wrong.  But in an
  1070. Info file, suitable closing punctuation must follow the cross reference
  1071. so Info can recognize its end.  `@pxref' spares you the need to use
  1072. complicated methods to put a terminator into one form of the output and
  1073. not the other.
  1074.  
  1075. With one argument, a parenthetical cross reference looks like this:
  1076.  
  1077.      ... storms cause flooding (@pxref{Hurricanes}) ...
  1078.  
  1079. which produces
  1080.  
  1081.      ... storms cause flooding (*Note Hurricanes::) ...
  1082.  
  1083. and
  1084.  
  1085.      ... storms cause flooding (see Section 6.7 [Hurricanes], page 72)
  1086.      ...
  1087.  
  1088.   With two arguments, a parenthetical cross reference has this template:
  1089.  
  1090.      ... (@pxref{NODE-NAME, CROSS-REFERENCE-NAME}) ...
  1091.  
  1092. which produces
  1093.  
  1094.      ... (*Note CROSS-REFERENCE-NAME: NODE-NAME.) ...
  1095.  
  1096. and
  1097.  
  1098.      ... (see Section NNN [NODE-NAME], page PPP) ...
  1099.  
  1100.   `@pxref' can be used with up to five arguments just like `@xref'
  1101. (*note `@xref': xref.).
  1102.  
  1103.      *Please note:* Use `@pxref' only as a parenthetical reference.  Do
  1104.      not try to use `@pxref' as a clause in a sentence.  It will look
  1105.      bad in either the Info file, the printed output, or both.
  1106.  
  1107.      Also, parenthetical cross references look best at the ends of
  1108.      sentences.  Although you may write them in the middle of a
  1109.      sentence, that location breaks up the flow of text.
  1110.  
  1111. 
  1112. File: texinfo.info,  Node: inforef,  Prev: pxref,  Up: Cross References
  1113.  
  1114. `@inforef'
  1115. ==========
  1116.  
  1117.   `@inforef' is used for cross references to Info files for which there
  1118. are no printed manuals.  Even in a printed manual, `@inforef' generates
  1119. a reference directing the user to look in an Info file.
  1120.  
  1121.   The command takes either two or three arguments, in the following
  1122. order:
  1123.  
  1124.   1. The node name.
  1125.  
  1126.   2. The cross reference name (optional).
  1127.  
  1128.   3. The Info file name.
  1129.  
  1130. Separate the arguments with commas, as with `@xref'.  Also, you must
  1131. terminate the reference with a comma or period after the `}', as you do
  1132. with `@xref'.
  1133.  
  1134. The template is:
  1135.  
  1136.      @inforef{NODE-NAME, CROSS-REFERENCE-NAME, INFO-FILE-NAME},
  1137.  
  1138. Thus,
  1139.  
  1140.      @inforef{Expert, Advanced Info commands, info},
  1141.      for more information.
  1142.  
  1143. produces
  1144.  
  1145.      *Note Advanced Info commands: (info)Expert,
  1146.      for more information.
  1147.  
  1148. and
  1149.  
  1150.      See Info file `info', node `Expert', for more information.
  1151.  
  1152. Similarly,
  1153.  
  1154.      @inforef{Expert, , info}, for more information.
  1155.  
  1156. produces
  1157.  
  1158.      *Note (info)Expert::, for more information.
  1159.  
  1160. and
  1161.  
  1162.      See Info file `info', node `Expert', for more information.
  1163.  
  1164.   The converse of `@inforef' is `@cite', which is used to refer to
  1165. printed works for which no Info form exists.  *Note `@cite': cite.
  1166.  
  1167. 
  1168. File: texinfo.info,  Node: Marking Text,  Next: Quotations and Examples,  Prev: Cross References,  Up: Top
  1169.  
  1170. Marking Words and Phrases
  1171. *************************
  1172.  
  1173.   In Texinfo, you can mark words and phrases in a variety of ways.  The
  1174. Texinfo formatters use this information to determine how to highlight
  1175. the text.  You can specify, for example, whether a word or phrase is a
  1176. defining occurrence, a metasyntactic variable, or a symbol used in a
  1177. program.  Also, you can emphasize text.
  1178.  
  1179. * Menu:
  1180.  
  1181. * Indicating::                  How to indicate definitions, files, etc.
  1182. * Emphasis::                    How to emphasize text.
  1183.  
  1184. 
  1185. File: texinfo.info,  Node: Indicating,  Next: Emphasis,  Prev: Marking Text,  Up: Marking Text
  1186.  
  1187. Indicating Definitions, Commands, etc.
  1188. ======================================
  1189.  
  1190.   Texinfo has commands for indicating just what kind of object a piece
  1191. of text refers to.  For example, metasyntactic variables are marked by
  1192. `@var', and code by `@code'.  Since the pieces of text are labelled by
  1193. commands that tell what kind of object they are, it is easy to change
  1194. the way the Texinfo formatters prepare such text.  (Texinfo is an
  1195. *intentional* formatting language rather than a *typesetting*
  1196. formatting language.)
  1197.  
  1198.   For example, in a printed manual, code is usually illustrated in a
  1199. typewriter font; `@code' tells TeX to typeset this text in this font.
  1200. But it would be easy to change the way TeX highlights code to use
  1201. another font, and this change would not effect how keystroke examples
  1202. are highlighted.  If straight typesetting commands were used in the body
  1203. of the file and you wanted to make a change, you would need to check
  1204. every single occurrence to make sure that you were changing code and
  1205. not something else that should not be changed.
  1206.  
  1207. * Menu:
  1208.  
  1209. * Useful Highlighting::         Highlighting provides useful information.
  1210. * code::                        How to indicate code.
  1211. * kbd::                         How to show keyboard input.
  1212. * key::                         How to specify keys.
  1213. * samp::                        How to show a literal sequence of characters.
  1214. * var::                         How to indicate a metasyntactic variable.
  1215. * file::                        How to indicate the name of a file.
  1216. * dfn::                         How to specify a definition.
  1217. * cite::                        How to refer to a book that is not in Info.
  1218.  
  1219. 
  1220. File: texinfo.info,  Node: Useful Highlighting,  Next: code,  Prev: Indicating,  Up: Indicating
  1221.  
  1222. Highlighting Commands are Useful
  1223. --------------------------------
  1224.  
  1225.   The highlighting commands can be used to generate useful information
  1226. from the file, such as lists of functions or file names.  It is
  1227. possible, for example, to write a program in Emacs Lisp (or a keyboard
  1228. macro) to insert an index entry after every paragraph that contains
  1229. words or phrases marked by a specified command.  You could do this to
  1230. construct an index of functions if you had not already made the entries.
  1231.  
  1232.   The commands serve a variety of purposes:
  1233.  
  1234. `@code{SAMPLE-CODE}'
  1235.      Indicate text that is a literal example of a piece of a program.
  1236.  
  1237. `@kbd{KEYBOARD-CHARACTERS}'
  1238.      Indicate keyboard input.
  1239.  
  1240. `@key{KEY-NAME}'
  1241.      Indicate the conventional name for a key on a keyboard.
  1242.  
  1243. `@samp{TEXT}'
  1244.      Indicate text that is a literal example of a sequence of
  1245.      characters.
  1246.  
  1247. `@var{METASYNTACTIC-VARIABLE}'
  1248.      Indicate a metasyntactic variable.
  1249.  
  1250. `@file{FILE-NAME}'
  1251.      Indicate the name of a file.
  1252.  
  1253. `@dfn{TERM}'
  1254.      Indicate the introductory or defining use of a term.
  1255.  
  1256. `@cite{REFERENCE}'
  1257.      Indicate the name of a book.
  1258.  
  1259. 
  1260. File: texinfo.info,  Node: code,  Next: kbd,  Prev: Useful Highlighting,  Up: Indicating
  1261.  
  1262. `@code'{SAMPLE-CODE}
  1263. --------------------
  1264.  
  1265.   Use the `@code' command to indicate text that is a piece of a program
  1266. and which consists of entire syntactic tokens.  Enclose the text in
  1267. braces.
  1268.  
  1269.   Thus, you should use `@code' for an expression in a program, for the
  1270. name of a variable or function used in a program, or for a keyword.
  1271. Also, you should use `@code' for the name of a program, such as `diff',
  1272. that is a name used in the machine. (You should write the name of a
  1273. program in the ordinary text font if you regard it as a new English
  1274. word, such as `Emacs' or `Bison'.)
  1275.  
  1276.   Use `@code' for environment variables such as `TEXINPUTS', and other
  1277. variables.
  1278.  
  1279.   Use `@code' for command names in command languages that resemble
  1280. programming languages, such as Texinfo or the shell.  For example,
  1281. `@code' and `@samp' are produced by writing `@code{@@code}' and
  1282. `@code{@@samp}' in the Texinfo source, respectively.
  1283.  
  1284.   Note, however, that you should not use `@code' for shell options such
  1285. as `-c' when such options stand alone. (Use `@samp'.) Also, an entire
  1286. shell command often looks better if written using `@samp' rather than
  1287. `@code'.  In this case, the rule is to choose the more pleasing format.
  1288.  
  1289.   It is incorrect to alter the case of a word inside an `@code' command
  1290. when it appears at the beginning of a sentence.  Most computer
  1291. languages are case sensitive.  In C, for example, `Printf' is different
  1292. from the identifier `printf', and most likely is a misspelling of it.
  1293. Even in languages which are not case sensitive, it is confusing to a
  1294. human reader to see identifiers spelled in different ways.  Pick one
  1295. spelling and always use that.  If you do not want to start a sentence
  1296. with a command written all in lower case, you should rearrange the
  1297. sentence.
  1298.  
  1299.   Do not use the `@code' command for a string of characters shorter
  1300. than a syntactic token.  If you are writing about `TEXINPU', which is
  1301. just a part of the name for the `TEXINPUTS' environment variable, you
  1302. should use `@samp'.
  1303.  
  1304.   In particular, you should not use the `@code' command when writing
  1305. about the characters used in a token; do not, for example, use `@code'
  1306. when you are explaining what letters or printable symbols can be used
  1307. in the names of functions.  (Use `@samp'.)  Also, you should not use
  1308. `@code' to mark text that is considered input to programs unless the
  1309. input is written in a language that is like a programming language.
  1310. For example, you should not use `@code' for the keystroke commands of
  1311. GNU Emacs (use `@kbd' instead) although you may use `@code' for the
  1312. names of the Emacs Lisp functions that the keystroke commands invoke.
  1313.  
  1314.   In the printed manual, `@code' causes TeX to typeset the argument in
  1315. a typewriter face.  In the Info file, it causes the Info formatting
  1316. commands to use single quotation marks around the text.
  1317.  
  1318.   For example,
  1319.  
  1320.      Use @code{diff} to compare two files.
  1321.  
  1322. produces this in the printed manual:
  1323.  
  1324.      Use `diff' to compare two files.
  1325.  
  1326. 
  1327. File: texinfo.info,  Node: kbd,  Next: key,  Prev: code,  Up: Indicating
  1328.  
  1329. `@kbd'{KEYBOARD-CHARACTERS}
  1330. ---------------------------
  1331.  
  1332.   Use the `@kbd' command for characters of input to be typed by users.
  1333. For example, to refer to the characters `M-a', write
  1334.  
  1335.      @kbd{M-a}
  1336.  
  1337. and to refer to the characters `M-x shell', write
  1338.  
  1339.      @kbd{M-x shell}
  1340.  
  1341.   The `@kbd' command has the same effect as `@code' in Info, but may
  1342. produce a different font in a printed manual.
  1343.  
  1344.   You can embed another @-command inside the braces of an `@kbd'
  1345. command.  Here, for example, is the way to describe a command that
  1346. would be described more verbosely as "press an `r' and then press the
  1347. RET key":
  1348.  
  1349.      @kbd{r @key{RET}}
  1350.  
  1351. This produces: `r RET'
  1352.  
  1353.   You also use the `@kbd' command if you are spelling out the letters
  1354. you type; for example:
  1355.  
  1356.      To give the @code{logout} command,
  1357.      type the characters @kbd{l o g o u t @key{RET}}.
  1358.  
  1359. This produces:
  1360.  
  1361.      To give the `logout' command, type the characters `l o g o u t
  1362.      RET'.
  1363.  
  1364.   (Also, this example shows that you can add spaces for clarity.  If you
  1365. really want to mention a space character as one of the characters of
  1366. input, write `@key{SPC}' for it.)
  1367.  
  1368. 
  1369. File: texinfo.info,  Node: key,  Next: samp,  Prev: kbd,  Up: Indicating
  1370.  
  1371. `@key'{KEY-NAME}
  1372. ----------------
  1373.  
  1374.   Use the `@key' command for the conventional name for a key on a
  1375. keyboard, as in:
  1376.  
  1377.      @key{RET}
  1378.  
  1379.   You can use the `@key' command within the argument of an `@kbd'
  1380. command when the sequence of characters to be typed includes one or
  1381. more keys that are described by name.
  1382.  
  1383.   For example, to produce `C-x ESC' you would type:
  1384.  
  1385.      @kbd{C-x @key{ESC}}
  1386.  
  1387.   Here is a list of the recommended names for keys; they are all in
  1388. upper case:
  1389.  
  1390.     SPC
  1391.           Space
  1392.  
  1393.     RET
  1394.           Return
  1395.  
  1396.     LFD
  1397.           Linefeed
  1398.  
  1399.     TAB
  1400.           Tab
  1401.  
  1402.     BS
  1403.           Backspace
  1404.  
  1405.     ESC
  1406.           Escape
  1407.  
  1408.     DEL
  1409.           Delete
  1410.  
  1411.     SFT
  1412.           Shift
  1413.  
  1414.     CTL
  1415.           Control
  1416.  
  1417.     META
  1418.           Meta
  1419.  
  1420.   There are subtleties to handling words like `meta' or `ctl' that are
  1421. names of shift keys.  When mentioning a character in which the shift
  1422. key is used, such as `Meta-a', use the `@kbd' command alone; do not use
  1423. the `@key' command; but when you are referring to the shift key in
  1424. isolation, use the `@key' command.  For example, write `@kbd{Meta-a}'
  1425. to produce `Meta-a' and `@key{META}' to produce META.  This is because
  1426. `Meta-a' refers to keys that you press on a keyboard, but META refers
  1427. to a key without implying that you press it.  In short, use `@kbd' for
  1428. what you do, and use `@key' for what you talk about: "Press `@kbd{M-a}'
  1429. to move point to the beginning of the sentence.  The `@key{META}' key
  1430. is often in the lower left of the keyboard."
  1431.  
  1432.