home *** CD-ROM | disk | FTP | other *** search
/ Geek Gadgets 1 / ADE-1.bin / ade-bin / info / texinfo.info-9 < prev    next >
Encoding:
GNU Info File  |  1996-10-12  |  49.4 KB  |  1,316 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: Command List,  Next: Tips,  Prev: Install an Info File,  Up: Top
  29.  
  30. @-Command List
  31. **************
  32.  
  33.   Here is an alphabetical list of the @-commands in Texinfo.  Square
  34. brackets, [ ], indicate optional arguments; an ellipsis, `...',
  35. indicates repeated text.
  36.  
  37. `@*'
  38.      Force a line break. Do not end a paragraph that uses `@*' with an
  39.      `@refill' command.  *Note Line Breaks::.
  40.  
  41. `@.'
  42.      Stands for a period that really does end a sentence (usually after
  43.      an end-of-sentence capital letter).  *Note Controlling Spacing::.
  44.  
  45. `@:'
  46.      Indicate to TeX that an immediately preceding period, question
  47.      mark, exclamation mark, or colon does not end a sentence.  Prevent
  48.      TeX from inserting extra whitespace as it does at the end of a
  49.      sentence.  The command has no effect on the Info file output.
  50.      *Note Controlling Spacing::.
  51.  
  52. `@@'
  53.      Stands for `@'.  *Note Inserting `@': Braces Atsigns Periods.
  54.  
  55. `@{'
  56.      Stands for a left-hand brace, `{'.
  57.      *Note Inserting @ braces and periods: Braces Atsigns Periods.
  58.  
  59. `@}'
  60.      Stands for a right-hand brace, `}'.
  61.      *Note Inserting @ braces and periods: Braces Atsigns Periods.
  62.  
  63. `@appendix TITLE'
  64.      Begin an appendix.  The title appears in the table of contents of
  65.      a printed manual.  In Info, the title is underlined with
  66.      asterisks.  *Note The `@unnumbered' and `@appendix' Commands:
  67.      unnumbered & appendix.
  68.  
  69. `@appendixsec TITLE'
  70. `@appendixsection TITLE'
  71.      Begin an appendix section within an appendix.  The section title
  72.      appears in the table of contents of a printed manual.  In Info,
  73.      the title is underlined with equal signs.  `@appendixsection' is a
  74.      longer spelling of the `@appendixsec' command.  *Note Section
  75.      Commands: unnumberedsec appendixsec heading.
  76.  
  77. `@appendixsubsec TITLE'
  78.      Begin an appendix subsection within an appendix.  The title appears
  79.      in the table of contents of a printed manual.  In Info, the title
  80.      is underlined with hyphens.  *Note Subsection Commands:
  81.      unnumberedsubsec appendixsubsec subheading.
  82.  
  83. `@appendixsubsubsec TITLE'
  84.      Begin an appendix subsubsection within a subappendix.  The title
  85.      appears in the table of contents of a printed manual.  In Info, the
  86.      title is underlined with periods.  *Note The `subsub' Commands:
  87.      subsubsection.
  88.  
  89. `@asis'
  90.      Used following `@table', `@ftable', and `@vtable' to print the
  91.      table's first column without highlighting ("as is").  *Note Making
  92.      a Two-column Table: Two-column Tables.
  93.  
  94. `@author AUTHOR'
  95.      Typeset AUTHOR flushleft and underline it.  *Note The `@title' and
  96.      `@author' Commands: title subtitle author.
  97.  
  98. `@b{TEXT}'
  99.      Print TEXT in bold font.  No effect in Info.  *Note Fonts::.
  100.  
  101. `@bullet{}'
  102.      Generate a large round dot, or the closest possible thing to one.
  103.      *Note `@bullet': bullet.
  104.  
  105. `@bye'
  106.      Stop formatting a file.  The formatters do not see the contents of
  107.      a file following an `@bye' command.  *Note Ending a File::.
  108.  
  109. `@c COMMENT'
  110.      Begin a comment in Texinfo.  The rest of the line does not appear
  111.      in either the Info file or the printed manual.  A synonym for
  112.      `@comment'.  *Note Comments: Comments.
  113.  
  114. `@cartouche'
  115.      Highlight an example or quotation by drawing a box with rounded
  116.      corners around it.  Pair with `@end cartouche'.  No effect in
  117.      Info.  *Note Drawing Cartouches Around Examples: cartouche.)
  118.  
  119. `@center LINE-OF-TEXT'
  120.      Center the line of text following the command.  *Note `@center':
  121.      titlefont center sp.
  122.  
  123. `@lowersections'
  124.      Change subsequent chapters to sections, sections to subsections,
  125.      and so on. *Note `@raisesections' and `@lowersections':
  126.      Raise/lower sections.
  127.  
  128. `@chapheading TITLE'
  129.      Print a chapter-like heading in the text, but not in the table of
  130.      contents of a printed manual.  In Info, the title is underlined
  131.      with asterisks.  *Note `@majorheading' and `@chapheading':
  132.      majorheading & chapheading.
  133.  
  134. `@chapter TITLE'
  135.      Begin a chapter.  The chapter title appears in the table of
  136.      contents of a printed manual.  In Info, the title is underlined
  137.      with asterisks.  *Note `@chapter': chapter.
  138.  
  139. `@cindex ENTRY'
  140.      Add ENTRY to the index of concepts.  *Note Defining the Entries of
  141.      an Index: Index Entries.
  142.  
  143. `@cite{REFERENCE}'
  144.      Highlight the name of a book or other reference that lacks a
  145.      companion Info file.  *Note `@cite': cite.
  146.  
  147. `@clear FLAG'
  148.      Unset FLAG, preventing the Texinfo formatting commands from
  149.      formatting text between subsequent pairs of `@ifset FLAG' and
  150.      `@end ifset' commands, and preventing `@value{FLAG}' from
  151.      expanding to the value to which FLAG is set.  *Note `@set'
  152.      `@clear' `@value': set clear value.
  153.  
  154. `@code{SAMPLE-CODE}'
  155.      Highlight text that is an expression, a syntactically complete
  156.      token of a program, or a program name.  *Note `@code': code.
  157.  
  158. `@comment COMMENT'
  159.      Begin a comment in Texinfo.  The rest of the line does not appear
  160.      in either the Info file or the printed manual.  A synonym for `@c'.
  161.      *Note Comments: Comments.
  162.  
  163. `@contents'
  164.      Print a complete table of contents.  Has no effect in Info, which
  165.      uses menus instead.  *Note Generating a Table of Contents:
  166.      Contents.
  167.  
  168. `@copyright{}'
  169.      Generate a copyright symbol.  *Note `@copyright': copyright symbol.
  170.  
  171. `@defcodeindex INDEX-NAME'
  172.      Define a new index and its indexing command.  Print entries in an
  173.      `@code' font.  *Note Defining New Indices: New Indices.
  174.  
  175. `@defcv CATEGORY CLASS NAME'
  176.      Format a description for a variable associated with a class in
  177.      object-oriented programming.  Takes three arguments: the category
  178.      of thing being defined, the class to which it belongs, and its
  179.      name.  *Note Definition Commands::.
  180.  
  181. `@deffn CATEGORY NAME ARGUMENTS...'
  182.      Format a description for a function, interactive command, or
  183.      similar entity that may take arguments.  `@deffn' takes as
  184.      arguments the category of entity being described, the name of this
  185.      particular entity, and its arguments, if any.  *Note Definition
  186.      Commands::.
  187.  
  188. `@defindex INDEX-NAME'
  189.      Define a new index and its indexing command.  Print entries in a
  190.      roman font.  *Note Defining New Indices: New Indices.
  191.  
  192. `@definfoenclose NEW-COMMAND, BEFORE, AFTER,'
  193.      Create new @-command for Info that marks text by enclosing it in
  194.      strings that precede and follow the text.  Write definition inside
  195.      of `@ifinfo' ... `@end ifinfo'. *Note Customized Highlighting::.
  196.  
  197. `@defivar CLASS INSTANCE-VARIABLE-NAME'
  198.      This command formats a description for an instance variable in
  199.      object-oriented programming.  The command is equivalent to `@defcv
  200.      {Instance Variable} ...'.  *Note Definition Commands::.
  201.  
  202. `@defmac MACRO-NAME ARGUMENTS...'
  203.      Format a description for a macro.  The command is equivalent to
  204.      `@deffn Macro ...'.  *Note Definition Commands::.
  205.  
  206. `@defmethod CLASS METHOD-NAME ARGUMENTS...'
  207.      Format a description for a method in object-oriented programming.
  208.      The command is equivalent to `@defop Method ...'.  Takes as
  209.      arguments the name of the class of the method, the name of the
  210.      method, and its arguments, if any.  *Note Definition Commands::.
  211.  
  212. `@defop CATEGORY CLASS NAME ARGUMENTS...'
  213.      Format a description for an operation in object-oriented
  214.      programming.  `@defop' takes as arguments the overall name of the
  215.      category of operation, the name of the class of the operation, the
  216.      name of the operation, and its arguments, if any.  *Note
  217.      Definition Commands::.
  218.  
  219. `@defopt OPTION-NAME'
  220.      Format a description for a user option.  The command is equivalent
  221.      to `@defvr {User Option} ...'.  *Note Definition Commands::.
  222.  
  223. `@defspec SPECIAL-FORM-NAME ARGUMENTS...'
  224.      Format a description for a special form.  The command is
  225.      equivalent to `@deffn {Special Form} ...'.  *Note Definition
  226.      Commands::.
  227.  
  228. `@deftp CATEGORY NAME-OF-TYPE ATTRIBUTES...'
  229.      Format a description for a data type.  `@deftp' takes as arguments
  230.      the category, the name of the type (which is a word like `int' or
  231.      `float'), and then the names of attributes of objects of that
  232.      type.  *Note Definition Commands::.
  233.  
  234. `@deftypefn CLASSIFICATION DATA-TYPE NAME ARGUMENTS...'
  235.      Format a description for a function or similar entity that may take
  236.      arguments and that is typed.  `@deftypefn' takes as arguments the
  237.      classification of entity being described, the type, the name of
  238.      the entity, and its arguments, if any.  *Note Definition
  239.      Commands::.
  240.  
  241. `@deftypefun DATA-TYPE FUNCTION-NAME ARGUMENTS...'
  242.      Format a description for a function in a typed language.  The
  243.      command is equivalent to `@deftypefn Function ...'.  *Note
  244.      Definition Commands::.
  245.  
  246. `@deftypevr CLASSIFICATION DATA-TYPE NAME'
  247.      Format a description for something like a variable in a typed
  248.      language--an entity that records a value.  Takes as arguments the
  249.      classification of entity being described, the type, and the name of
  250.      the entity.  *Note Definition Commands::.
  251.  
  252. `@deftypevar DATA-TYPE VARIABLE-NAME'
  253.      Format a description for a variable in a typed language.  The
  254.      command is equivalent to `@deftypevr Variable ...'.  *Note
  255.      Definition Commands::.
  256.  
  257. `@defun FUNCTION-NAME ARGUMENTS...'
  258.      Format a description for functions.  The command is equivalent to
  259.      `@deffn Function ...'.  *Note Definition Commands::.
  260.  
  261. `@defvar VARIABLE-NAME'
  262.      Format a description for variables.  The command is equivalent to
  263.      `@defvr Variable ...'.  *Note Definition Commands::.
  264.  
  265. `@defvr CATEGORY NAME'
  266.      Format a description for any kind of variable.  `@defvr' takes as
  267.      arguments the category of the entity and the name of the entity.
  268.      *Note Definition Commands::.
  269.  
  270. `@dfn{TERM}'
  271.      Highlight the introductory or defining use of a term.  *Note
  272.      `@dfn': dfn.
  273.  
  274. `@display'
  275.      Begin a kind of example.  Indent text, do not fill, do not select a
  276.      new font.  Pair with `@end display'.  *Note `@display': display.
  277.  
  278. `@dmn{DIMENSION}'
  279.      Format a dimension.  Cause TeX to insert a narrow space before
  280.      DIMENSION.  No effect in Info.  Use for writing a number followed
  281.      by an abbreviation of a dimension name, such as `12pt', written as
  282.      `12@dmn{pt}', with no space between the number and the `@dmn'
  283.      command.  *Note `@dmn': dmn.
  284.  
  285. `@dots{}'
  286.      Insert an ellipsis: `...'.  *Note `@dots': dots.
  287.  
  288. `@emph{TEXT}'
  289.      Highlight TEXT; text is displayed in *italics* in printed output,
  290.      and surrounded by asterisks in Info.  *Note Emphasizing Text:
  291.      Emphasis.
  292.  
  293. `@enumerate [NUMBER-OR-LETTER]'
  294.      Begin a numbered list, using `@item' for each entry.  Optionally,
  295.      start list with NUMBER-OR-LETTER.  Pair with `@end enumerate'.
  296.      *Note `@enumerate': enumerate.
  297.  
  298. `@equiv{}'
  299.      Indicate to the reader the exact equivalence of two forms with a
  300.      glyph: `=='.  *Note Equivalence::.
  301.  
  302. `@error{}'
  303.      Indicate to the reader with a glyph that the following text is an
  304.      error message: `error-->'.  *Note Error Glyph::.
  305.  
  306. `@evenfooting [LEFT] @| [CENTER] @| [RIGHT]'
  307.      Specify page footings for even-numbered (left-hand) pages.  Not
  308.      relevant to Info.  *Note How to Make Your Own Headings: Custom
  309.      Headings.
  310.  
  311. `@evenheading [LEFT] @| [CENTER] @| [RIGHT]'
  312.      Specify page headings for even-numbered (left-hand) pages.  Not
  313.      relevant to Info.  *Note How to Make Your Own Headings: Custom
  314.      Headings.
  315.  
  316. `@everyfooting [LEFT] @| [CENTER] @| [RIGHT]'
  317.      Specify page footings for every page.  Not relevant to Info.
  318.      *Note How to Make Your Own Headings: Custom Headings.
  319.  
  320. `@everyheading [LEFT] @| [CENTER] @| [RIGHT]'
  321.      Specify page headings for every page.  Not relevant to Info.
  322.      *Note How to Make Your Own Headings: Custom Headings.
  323.  
  324. `@example'
  325.      Begin an example.  Indent text, do not fill, and select
  326.      fixed-width font.  Pair with `@end example'.  *Note `@example':
  327.      example.
  328.  
  329. `@exdent LINE-OF-TEXT'
  330.      Remove any indentation a line might have.  *Note Undoing the
  331.      Indentation of a Line: exdent.
  332.  
  333. `@expansion{}'
  334.      Indicate the result of a macro expansion to the reader with a
  335.      special glyph: `==>'.  *Note ==> Indicating an Expansion:
  336.      expansion.
  337.  
  338. `@file{FILENAME}'
  339.      Highlight the name of a file, buffer, node, or directory.  *Note
  340.      `@file': file.
  341.  
  342. `@finalout'
  343.      Prevent TeX from printing large black warning rectangles beside
  344.      over-wide lines.  *Note Overfull hboxes::.
  345.  
  346. `@findex ENTRY'
  347.      Add ENTRY to the index of functions.  *Note Defining the Entries
  348.      of an Index: Index Entries.
  349.  
  350. `@flushleft'
  351.      Left justify every line but leave the right end ragged.  Leave
  352.      font as is.  Pair with `@end flushleft'.  *Note `@flushleft' and
  353.      `@flushright': flushleft & flushright.
  354.  
  355. `@flushright'
  356.      Right justify every line but leave the left end ragged.  Leave
  357.      font as is.  Pair with `@end flushright'.  *Note `@flushleft' and
  358.      `@flushright': flushleft & flushright.
  359.  
  360. `@footnote{TEXT-OF-FOOTNOTE}'
  361.      Enter a footnote.  Footnote text is printed at the bottom of the
  362.      page by TeX; Info may format in either `End' node or `Separate'
  363.      node style.  *Note Footnotes::.
  364.  
  365. `@footnotestyle STYLE'
  366.      Specify an Info file's footnote style, either `end' for the end
  367.      node style or `separate' for the separate node style.  *Note
  368.      Footnotes::.
  369.  
  370. `@format'
  371.      Begin a kind of example.  Like `@example' or `@display', but do
  372.      not narrow the margins and do not select the fixed-width font.
  373.      Pair with `@end format'.  *Note `@example': example.
  374.  
  375. `@ftable FORMATTING-COMMAND'
  376.      Begin a two-column table, using `@item' for each entry.
  377.      Automatically enter each of the items in the first column into the
  378.      index of functions.  Pair with `@end ftable'.  The same as
  379.      `@table', except for indexing.  *Note `@ftable' and `@vtable':
  380.      ftable vtable.
  381.  
  382. `@group'
  383.      Hold text together that must appear on one printed page.  Pair with
  384.      `@end group'.  Not relevant to Info.  *Note `@group': group.
  385.  
  386. `@heading TITLE'
  387.      Print an unnumbered section-like heading in the text, but not in
  388.      the table of contents of a printed manual.  In Info, the title is
  389.      underlined with equal signs.  *Note Section Commands:
  390.      unnumberedsec appendixsec heading.
  391.  
  392. `@headings ON-OFF-SINGLE-DOUBLE'
  393.      Turn page headings on or off, or specify single-sided or
  394.      double-sided page headings for printing.  `@headings on' is
  395.      synonymous with `@headings double'.  *Note The `@headings'
  396.      Command: headings on off.
  397.  
  398. `@i{TEXT}'
  399.      Print TEXT in italic font.  No effect in Info.  *Note Fonts::.
  400.  
  401. `@ifclear FLAG'
  402.      If FLAG is cleared, the Texinfo formatting commands format text
  403.      between `@ifclear FLAG' and the following `@end ifclear' command.
  404.      *Note `@set' `@clear' `@value': set clear value.
  405.  
  406. `@ifinfo'
  407.      Begin a stretch of text that will be ignored by TeX when it
  408.      typesets the printed manual.  The text appears only in the Info
  409.      file.  Pair with `@end ifinfo'.  *Note Conditionally Visible Text:
  410.      Conditionals.
  411.  
  412. `@ifset FLAG'
  413.      If FLAG is set, the Texinfo formatting commands format text
  414.      between `@ifset FLAG' and the following `@end ifset' command.
  415.      *Note `@set' `@clear' `@value': set clear value.
  416.  
  417. `@iftex'
  418.      Begin a stretch of text that will not appear in the Info file, but
  419.      will be processed only by TeX.  Pair with `@end iftex'.  *Note
  420.      Conditionally Visible Text: Conditionals.
  421.  
  422. `@ignore'
  423.      Begin a stretch of text that will not appear in either the Info
  424.      file or the printed output.  Pair with `@end ignore'.  *Note
  425.      Comments and Ignored Text: Comments.
  426.  
  427. `@include FILENAME'
  428.      Incorporate the contents of the file FILENAME into the Info file
  429.      or printed document.  *Note Include Files::.
  430.  
  431. `@inforef{NODE-NAME, [ENTRY-NAME], INFO-FILE-NAME}'
  432.      Make a cross reference to an Info file for which there is no
  433.      printed manual.  *Note Cross references using `@inforef': inforef.
  434.  
  435. `\input MACRO-DEFINITIONS-FILE'
  436.      Use the specified macro definitions file.  This command is used
  437.      only in the first line of a Texinfo file to cause TeX to make use
  438.      of the `texinfo' macro definitions file.  The backslash in `\input'
  439.      is used instead of an `@' because TeX does not properly recognize
  440.      `@' until after it has read the definitions file.  *Note The
  441.      Texinfo File Header: Header.
  442.  
  443. `@item'
  444.      Indicate the beginning of a marked paragraph for `@itemize' and
  445.      `@enumerate'; indicate the beginning of the text of a first column
  446.      entry for `@table', `@ftable', and `@vtable'.  *Note Lists and
  447.      Tables::.
  448.  
  449. `@itemize  MARK-GENERATING-CHARACTER-OR-COMMAND'
  450.      Produce a sequence of indented paragraphs, with a mark inside the
  451.      left margin at the beginning of each paragraph.  Pair with `@end
  452.      itemize'.  *Note `@itemize': itemize.
  453.  
  454. `@itemx'
  455.      Like `@item' but do not generate extra vertical space above the
  456.      item text.  *Note `@itemx': itemx.
  457.  
  458. `@kbd{KEYBOARD-CHARACTERS}'
  459.      Indicate text that consists of characters of input to be typed by
  460.      users.  *Note `@kbd': kbd.
  461.  
  462. `@key{KEY-NAME}'
  463.      Highlight KEY-NAME, a conventional name for a key on a keyboard.
  464.      *Note `@key': key.
  465.  
  466. `@kindex ENTRY'
  467.      Add ENTRY to the index of keys.  *Note Defining the Entries of an
  468.      Index: Index Entries.
  469.  
  470. `@global@letNEW-COMMAND=EXISTING-COMMAND'
  471.      Equate a new highlighting command with an existing one.  Only for
  472.      TeX.  Write definition inside of `@iftex' ... `@end iftex'. *Note
  473.      Customized Highlighting::.
  474.  
  475. `@lisp'
  476.      Begin an example of Lisp code.  Indent text, do not fill, and
  477.      select fixed-width font.  Pair with `@end lisp'.  *Note `@lisp':
  478.      Lisp Example.
  479.  
  480. `@majorheading  TITLE'
  481.      Print a chapter-like heading in the text, but not in the table of
  482.      contents of a printed manual.  Generate more vertical whitespace
  483.      before the heading than the `@chapheading' command.  In Info, the
  484.      chapter heading line is underlined with asterisks.  *Note
  485.      `@majorheading' and `@chapheading': majorheading & chapheading.
  486.  
  487. `@math{MATHEMATICAL-EXPRESSION}'
  488.      Format a mathematical expression.  *Note `@math': Inserting
  489.      Mathematical Expressions: math.
  490.  
  491. `@menu'
  492.      Mark the beginning of a menu of nodes in Info.  No effect in a
  493.      printed manual.  Pair with `@end menu'.  *Note Menus::.
  494.  
  495. `@minus{}'
  496.      Generate a minus sign.  *Note `@minus': minus.
  497.  
  498. `@need N'
  499.      Start a new page in a printed manual if fewer than N mils
  500.      (thousandths of an inch) remain on the current page.  *Note
  501.      `@need': need.
  502.  
  503. `@node NAME, NEXT, PREVIOUS, UP'
  504.      Define the beginning of a new node in Info, and serve as a locator
  505.      for references for TeX.  *Note `@node': node.
  506.  
  507. `@noindent'
  508.      Prevent text from being indented as if it were a new paragraph.
  509.      *Note `@noindent': noindent.
  510.  
  511. `@oddfooting [LEFT] @| [CENTER] @| [RIGHT]'
  512.      Specify page footings for odd-numbered (right-hand) pages.  Not
  513.      relevant to Info.  *Note How to Make Your Own Headings: Custom
  514.      Headings.
  515.  
  516. `@oddheading [LEFT] @| [CENTER] @| [RIGHT]'
  517.      Specify page headings for odd-numbered (right-hand) pages.  Not
  518.      relevant to Info.  *Note How to Make Your Own Headings: Custom
  519.      Headings.
  520.  
  521. `@page'
  522.      Start a new page in a printed manual.  No effect in Info.  *Note
  523.      `@page': page.
  524.  
  525. `@paragraphindent INDENT'
  526.      Indent paragraphs by INDENT number of spaces; delete indentation
  527.      if the value of INDENT is 0; and do not change indentation if
  528.      INDENT is `asis'. *Note Paragraph Indenting: paragraphindent.
  529.  
  530. `@pindex ENTRY'
  531.      Add ENTRY to the index of programs.  *Note Defining the Entries of
  532.      an Index: Index Entries.
  533.  
  534. `@point{}'
  535.      Indicate the position of point in a buffer to the reader with a
  536.      glyph: `-!-'.  *Note Indicating Point in a Buffer: Point Glyph.
  537.  
  538. `@print{}'
  539.      Indicate printed output to the reader with a glyph: `-|'.  *Note
  540.      Print Glyph::.
  541.  
  542. `@printindex INDEX-NAME'
  543.      Print an alphabetized two-column index in a printed manual or
  544.      generate an alphabetized menu of index entries for Info.  *Note
  545.      Printing Indices & Menus::.
  546.  
  547. `@pxref{NODE-NAME, [ENTRY], [TOPIC-OR-TITLE], [INFO-FILE], [MANUAL]}'
  548.      Make a reference that starts with a lower case `see' in a printed
  549.      manual.  Use within parentheses only.  Do not follow command with a
  550.      punctuation mark.  The Info formatting commands automatically
  551.      insert terminating punctuation as needed, which is why you do not
  552.      need to insert punctuation.  Only the first argument is mandatory.
  553.      *Note `@pxref': pxref.
  554.  
  555. `@quotation'
  556.      Narrow the margins to indicate text that is quoted from another
  557.      real or imaginary work.  Write command on a line of its own.  Pair
  558.      with `@end quotation'.  *Note `@quotation': quotation.
  559.  
  560. `@r{TEXT}'
  561.      Print TEXT in roman font.  No effect in Info.  *Note Fonts::.
  562.  
  563. `@raisesections'
  564.      Change subsequent sections to chapters, subsections to sections,
  565.      and so on.  *Note `@raisesections' and `@lowersections':
  566.      Raise/lower sections.
  567.  
  568. `@ref{NODE-NAME, [ENTRY], [TOPIC-OR-TITLE], [INFO-FILE], [MANUAL]}'
  569.      Make a reference.  In a printed manual, the reference does not
  570.      start with a `See'.  Follow command with a punctuation mark.  Only
  571.      the first argument is mandatory.  *Note `@ref': ref.
  572.  
  573. `@refill'
  574.      In Info, refill and indent the paragraph after all the other
  575.      processing has been done.  No effect on TeX, which always refills.
  576.      This command is no longer needed, since all formatters now
  577.      automatically refill.  *Note Refilling Paragraphs::.
  578.  
  579. `@result{}'
  580.      Indicate the result of an expression to the reader with a special
  581.      glyph: `=>'.  *Note `@result': result.
  582.  
  583. `@samp{TEXT}'
  584.      Highlight TEXT that is a literal example of a sequence of
  585.      characters.  Used for single characters, for statements, and often
  586.      for entire shell commands.  *Note `@samp': samp.
  587.  
  588. `@sc{TEXT}'
  589.      Set TEXT in a printed output in THE SMALL CAPS FONT and set text
  590.      in the Info file in uppercase letters.  *Note Smallcaps::.
  591.  
  592. `@section TITLE'
  593.      Begin a section within a chapter.  In a printed manual, the section
  594.      title is numbered and appears in the table of contents.  In Info,
  595.      the title is underlined with equal signs.  *Note `@section':
  596.      section.
  597.  
  598. `@set FLAG [STRING]'
  599.      Make FLAG active, causing the Texinfo formatting commands to
  600.      format text between subsequent pairs of `@ifset FLAG' and `@end
  601.      ifset' commands.  Optionally, set value of FLAG to STRING.  *Note
  602.      `@set' `@clear' `@value': set clear value.
  603.  
  604. `@setchapternewpage ON-OFF-ODD'
  605.      Specify whether chapters start on new pages, and if so, whether on
  606.      odd-numbered (right-hand) new pages.  *Note `@setchapternewpage':
  607.      setchapternewpage.
  608.  
  609. `@setfilename INFO-FILE-NAME'
  610.      Provide a name to be used by the Info file.  *Note `@setfilename':
  611.      setfilename.
  612.  
  613. `@settitle TITLE'
  614.      Provide a title for page headers in a printed manual.  *Note
  615.      `@settitle': settitle.
  616.  
  617. `@shortcontents'
  618.      Print a short table of contents.  Not relevant to Info, which uses
  619.      menus rather than tables of contents.  A synonym for
  620.      `@summarycontents'.  *Note Generating a Table of Contents:
  621.      Contents.
  622.  
  623. `@smallbook'
  624.      Cause TeX to produce a printed manual in a 7 by 9.25 inch format
  625.      rather than the regular 8.5 by 11 inch format.  *Note Printing
  626.      Small Books: smallbook.  Also, see *Note `@smallexample' and
  627.      `@smalllisp': smallexample & smalllisp.
  628.  
  629. `@smallexample'
  630.      Indent text to indicate an example.  Do not fill, select
  631.      fixed-width font.  In `@smallbook' format, print text in a smaller
  632.      font than with `@example'.  Pair with `@end smallexample'.  *Note
  633.      `@smallexample' and `@smalllisp': smallexample & smalllisp.
  634.  
  635. `@smalllisp'
  636.      Begin an example of Lisp code.  Indent text, do not fill, select
  637.      fixed-width font.  In `@smallbook' format, print text in a smaller
  638.      font.  Pair with `@end smalllisp'.  *Note `@smallexample' and
  639.      `@smalllisp': smallexample & smalllisp.
  640.  
  641. `@sp N'
  642.      Skip N blank lines.  *Note `@sp': sp.
  643.  
  644. `@strong TEXT'
  645.      Emphasize TEXT by typesetting it in a *bold* font for the printed
  646.      manual and by surrounding it with asterisks for Info.  *Note
  647.      Emphasizing Text: emph & strong.
  648.  
  649. `@subheading TITLE'
  650.      Print an unnumbered subsection-like heading in the text, but not in
  651.      the table of contents of a printed manual.  In Info, the title is
  652.      underlined with hyphens.  *Note `@unnumberedsubsec'
  653.      `@appendixsubsec' `@subheading': unnumberedsubsec appendixsubsec
  654.      subheading.
  655.  
  656. `@subsection TITLE'
  657.      Begin a subsection within a section.  In a printed manual, the
  658.      subsection title is numbered and appears in the table of contents.
  659.      In Info, the title is underlined with hyphens.  *Note
  660.      `@subsection': subsection.
  661.  
  662. `@subsubheading TITLE'
  663.      Print an unnumbered subsubsection-like heading in the text, but
  664.      not in the table of contents of a printed manual.  In Info, the
  665.      title is underlined with periods.  *Note The `subsub' Commands:
  666.      subsubsection.
  667.  
  668. `@subsubsection TITLE'
  669.      Begin a subsubsection within a subsection.  In a printed manual,
  670.      the subsubsection title is numbered and appears in the table of
  671.      contents.  In Info, the title is underlined with periods.  *Note
  672.      The `subsub' Commands: subsubsection.
  673.  
  674. `@subtitle TITLE'
  675.      In a printed manual, set a subtitle in a normal sized font flush to
  676.      the right-hand side of the page.  Not relevant to Info, which does
  677.      not have title pages.  *Note `@title' `@subtitle' and `@author'
  678.      Commands: title subtitle author.
  679.  
  680. `@summarycontents'
  681.      Print a short table of contents.  Not relevant to Info, which uses
  682.      menus rather than tables of contents.  A synonym for
  683.      `@shortcontents'.  *Note Generating a Table of Contents: Contents.
  684.  
  685. `@syncodeindex FROM-INDEX INTO-INDEX'
  686.      Merge the index named in the first argument into the index named in
  687.      the second argument, printing the entries from the first index in
  688.      `@code' font.  *Note Combining Indices::.
  689.  
  690. `@synindex FROM-INDEX INTO-INDEX'
  691.      Merge the index named in the first argument into the index named in
  692.      the second argument.  Do not change the font of FROM-INDEX
  693.      entries.  *Note Combining Indices::.
  694.  
  695. `@t{TEXT}'
  696.      Print TEXT in a fixed-width, typewriter-like font.  No effect in
  697.      Info.  *Note Fonts::.
  698.  
  699. `@table FORMATTING-COMMAND'
  700.      Begin a two-column table, using `@item' for each entry.  Write
  701.      each first column entry on the same line as `@item'.  First column
  702.      entries are printed in the font resulting from FORMATTING-COMMAND.
  703.      Pair with `@end table'.  *Note Making a Two-column Table:
  704.      Two-column Tables.  Also see *Note `@ftable' and `@vtable': ftable
  705.      vtable, and *Note `@itemx': itemx.
  706.  
  707. `@TeX{}'
  708.      Insert the logo TeX.  *Note Inserting TeX and (C): TeX and
  709.      copyright.
  710.  
  711. `@tex'
  712.      Enter TeX completely.  Pair with `@end tex'.  *Note Using Ordinary
  713.      TeX Commands: Using Ordinary TeX Commands.
  714.  
  715. `@thischapter'
  716.      In a heading or footing, stands for the number and name of the
  717.      current chapter, in the format `Chapter 1: Title'.  *Note How to
  718.      Make Your Own Headings: Custom Headings.
  719.  
  720. `@thischaptername'
  721.      In a heading or footing, stands for the name of the current
  722.      chapter.  *Note How to Make Your Own Headings: Custom Headings.
  723.  
  724. `@thisfile'
  725.      In a heading or footing, stands for the name of the current
  726.      `@include' file.  Does not insert anything if not within an
  727.      `@include' file.  *Note How to Make Your Own Headings: Custom
  728.      Headings.
  729.  
  730. `@thispage'
  731.      In a heading or footing, stands for the current page number.
  732.      *Note How to Make Your Own Headings: Custom Headings.
  733.  
  734. `@thistitle'
  735.      In a heading or footing, stands for the name of the document, as
  736.      specified by the `@settitle' command.  *Note How to Make Your Own
  737.      Headings: Custom Headings.
  738.  
  739. `@tindex ENTRY'
  740.      Add ENTRY to the index of data types.  *Note Defining the Entries
  741.      of an Index: Index Entries.
  742.  
  743. `@title TITLE'
  744.      In a printed manual, set a title flush to the left-hand side of the
  745.      page in a larger than normal font and underline it with a black
  746.      rule.  Not relevant to Info, which does not have title pages.
  747.      *Note The `@title' `@subtitle' and `@author' Commands: title
  748.      subtitle author.
  749.  
  750. `@titlefont{TEXT}'
  751.      In a printed manual, print TEXT in a larger than normal font.  Not
  752.      relevant to Info, which does not have title pages.  *Note The
  753.      `@titlefont' `@center' and `@sp' Commands: titlefont center sp.
  754.  
  755. `@titlepage'
  756.      Indicate to Texinfo the beginning of the title page.  Write
  757.      command on a line of its own.  Pair with `@end titlepage'.
  758.      Nothing between `@titlepage' and `@end titlepage' appears in Info.
  759.      *Note `@titlepage': titlepage.
  760.  
  761. `@today{}'
  762.      Insert the current date, in `1 Jan 1900' style.  *Note How to Make
  763.      Your Own Headings: Custom Headings.
  764.  
  765. `@top TITLE'
  766.      In a Texinfo file to be formatted with `makeinfo', identify the
  767.      topmost `@node' line in the file, which must be written on the line
  768.      immediately preceding the `@top' command.  Used for `makeinfo''s
  769.      node pointer insertion feature.  The title is underlined with
  770.      asterisks.  Both the `@node' line and the `@top' line normally
  771.      should be enclosed by `@ifinfo' and `@end ifinfo'.  In TeX and
  772.      `texinfo-format-buffer', the `@top' command is merely a synonym
  773.      for `@unnumbered'.  *Note Creating Pointers with `makeinfo':
  774.      makeinfo Pointer Creation.
  775.  
  776. `@unnumbered TITLE'
  777.      In a printed manual, begin a chapter that appears without chapter
  778.      numbers of any kind.  The title appears in the table of contents
  779.      of a printed manual.  In Info, the title is underlined with
  780.      asterisks.  *Note `@unnumbered' and `@appendix': unnumbered &
  781.      appendix.
  782.  
  783. `@unnumberedsec TITLE'
  784.      In a printed manual, begin a section that appears without section
  785.      numbers of any kind.  The title appears in the table of contents
  786.      of a printed manual.  In Info, the title is underlined with equal
  787.      signs.  *Note Section Commands: unnumberedsec appendixsec heading.
  788.  
  789. `@unnumberedsubsec TITLE'
  790.      In a printed manual, begin an unnumbered subsection within a
  791.      chapter.  The title appears in the table of contents of a printed
  792.      manual.  In Info, the title is underlined with hyphens.  *Note
  793.      `@unnumberedsubsec' `@appendixsubsec' `@subheading':
  794.      unnumberedsubsec appendixsubsec subheading.
  795.  
  796. `@unnumberedsubsubsec TITLE'
  797.      In a printed manual, begin an unnumbered subsubsection within a
  798.      chapter.  The title appears in the table of contents of a printed
  799.      manual.  In Info, the title is underlined with periods.  *Note The
  800.      `subsub' Commands: subsubsection.
  801.  
  802. `@value{FLAG}'
  803.      Replace FLAG with the value to which it is set by `@set FLAG'.
  804.      *Note `@set' `@clear' `@value': set clear value.
  805.  
  806. `@var{METASYNTACTIC-VARIABLE}'
  807.      Highlight a metasyntactic variable, which is something that stands
  808.      for another piece of text.  *Note Indicating Metasyntactic
  809.      Variables: var.
  810.  
  811. `@vindex ENTRY'
  812.      Add ENTRY to the index of variables.  *Note Defining the Entries
  813.      of an Index: Index Entries.
  814.  
  815. `@vskip AMOUNT'
  816.      In a printed manual, insert whitespace so as to push text on the
  817.      remainder of the page towards the bottom of the page.  Used in
  818.      formatting the copyright page with the argument `0pt plus 1filll'.
  819.      (Note spelling of `filll'.)  `@vskip' may be used only in
  820.      contexts ignored for Info.  *Note The Copyright Page and Printed
  821.      Permissions: Copyright & Permissions.
  822.  
  823. `@vtable FORMATTING-COMMAND'
  824.      Begin a two-column table, using `@item' for each entry.
  825.      Automatically enter each of the items in the first column into the
  826.      index of variables.  Pair with `@end vtable'.  The same as
  827.      `@table', except for indexing.  *Note `@ftable' and `@vtable':
  828.      ftable vtable.
  829.  
  830. `@w{TEXT}'
  831.      Prevent TEXT from being split across two lines.  Do not end a
  832.      paragraph that uses `@w' with an `@refill' command.  In the
  833.      Texinfo file, keep TEXT on one line.  *Note `@w': w.
  834.  
  835. `@xref{NODE-NAME, [ENTRY], [TOPIC-OR-TITLE], [INFO-FILE], [MANUAL]}'
  836.      Make a reference that starts with `See' in a printed manual.
  837.      Follow command with a punctuation mark.  Only the first argument is
  838.      mandatory.  *Note `@xref': xref.
  839.  
  840. 
  841. File: texinfo.info,  Node: Tips,  Next: Sample Texinfo File,  Prev: Command List,  Up: Top
  842.  
  843. Tips and Hints
  844. **************
  845.  
  846.   Here are some tips for writing Texinfo documentation:
  847.  
  848.    * Write in the present tense, not in the past or the future.
  849.  
  850.    * Write actively!  For example, write "We recommend that ..." rather
  851.      than "It is recommended that ...".
  852.  
  853.    * Use 70 or 72 as your fill column.  Longer lines are hard to read.
  854.  
  855.    * Include a copyright notice and copying permissions.
  856.  
  857. Index, index, index!
  858. ....................
  859.  
  860.   Write many index entries, in different ways.  Readers like indices;
  861. they are helpful and convenient.
  862.  
  863.   Although it is easiest to write index entries as you write the body of
  864. the text, some people prefer to write entries afterwards.  In either
  865. case, write an entry before the paragraph to which it applies.  This
  866. way, an index entry points to the first page of a paragraph that is
  867. split across pages.
  868.  
  869.   Here are more hints we have found valuable:
  870.  
  871.    * Write each index entry differently, so each entry refers to a
  872.      different place in the document.  The index of an Info file lists
  873.      only one location for each entry.
  874.  
  875.    * Write index entries only where a topic is discussed significantly.
  876.      For example, it is not useful to index "debugging information" in
  877.      a chapter on reporting bugs.  Someone who wants to know about
  878.      debugging information will certainly not find it in that chapter.
  879.  
  880.    * Consistently capitalize the first word of every concept index
  881.      entry, or else consistently use lower case.  Terse entries often
  882.      call for lower case; longer entries for capitalization.  Whichever
  883.      case convention you use, please use one or the other consistently!
  884.      Mixing the two styles looks bad.
  885.  
  886.    * Always capitalize or use upper case for those words in an index for
  887.      which this is proper, such as names of countries or acronyms.
  888.      Always use the appropriate case for case-sensitive names, such as
  889.      those in C or Lisp.
  890.  
  891.    * Write the indexing commands that refer to a whole section
  892.      immediately after the section command, and write the indexing
  893.      commands that refer to the paragraph before the paragraph.
  894.  
  895.      In the example that follows, a blank line comes after the index
  896.      entry for "Leaping":
  897.  
  898.           @section The Dog and the Fox
  899.           @cindex Jumping, in general
  900.           @cindex Leaping
  901.           
  902.           @cindex Dog, lazy, jumped over
  903.           @cindex Lazy dog jumped over
  904.           @cindex Fox, jumps over dog
  905.           @cindex Quick fox jumps over dog
  906.           The quick brown fox jumps over the lazy dog.
  907.  
  908.      (Note that the example shows entries for the same concept that are
  909.      written in different ways--`Lazy dog', and `Dog, lazy'--so readers
  910.      can look up the concept in different ways.)
  911.  
  912. Blank lines
  913. ...........
  914.  
  915.    * Insert a blank line between a sectioning command and the first
  916.      following sentence or paragraph, or between the indexing commands
  917.      associated with the sectioning command and the first following
  918.      sentence or paragraph, as shown in the tip on indexing.
  919.      Otherwise, a formatter may fold title and paragraph together.
  920.  
  921.    * Always insert a blank line before an `@table' command and after an
  922.      `@end table' command; but never insert a blank line after an
  923.      `@table' command or before an `@end table' command.
  924.  
  925.      For example,
  926.  
  927.           Types of fox:
  928.           
  929.           @table @samp
  930.           @item Quick
  931.           Jump over lazy dogs.
  932.           
  933.           @item Brown
  934.           Also jump over lazy dogs.
  935.           @end table
  936.           @noindent
  937.           On the other hand, ...
  938.  
  939.      Insert blank lines before and after `@itemize' ... `@end itemize'
  940.      and `@enumerate' ... `@end enumerate' in the same way.
  941.  
  942. Complete phrases
  943. ................
  944.  
  945.   Complete phrases are easier to read than ...
  946.  
  947.    * Write entries in an itemized list as complete sentences; or at
  948.      least, as complete phrases.  Incomplete expressions ... awkward
  949.      ... like this.
  950.  
  951.    * Write the prefatory sentence or phrase for a multi-item list or
  952.      table as a complete expression.  Do not write "You can set:";
  953.      instead, write "You can set these variables:".  The former
  954.      expression sounds cut off.
  955.  
  956. Editions, dates and versions
  957. ............................
  958.  
  959.   Write the edition and version numbers and date in three places in
  960. every manual:
  961.  
  962.   1. In the first `@ifinfo' section, for people reading the Texinfo
  963.      file.
  964.  
  965.   2. In the `@titlepage' section, for people reading the printed manual.
  966.  
  967.   3. In the `Top' node, for people reading the Info file.
  968.  
  969. Also, it helps to write a note before the first `@ifinfo' section to
  970. explain what you are doing.
  971.  
  972. For example:
  973.  
  974.      @c ===> NOTE! <==
  975.      @c Specify the edition and version numbers and date
  976.      @c in *three* places:
  977.      @c   1. First ifinfo section  2. title page  3. top node
  978.      @c To find the locations, search for !!set
  979.      
  980.      @ifinfo
  981.      @c !!set edition, date, version
  982.      This is Edition 4.03, January 1992,
  983.      of the @cite{GDB Manual} for GDB Version 4.3.
  984.      ...
  985.  
  986. --or use `@set' and `@value' (*note `@value' Example: value Example.).
  987.  
  988. Definition Commands
  989. ...................
  990.  
  991.   Definition commands are `@deffn', `@defun', `@defmac', and the like,
  992. and enable you to write descriptions in a uniform format.
  993.  
  994.    * Write just one definition command for each entity you define with a
  995.      definition command.  The automatic indexing feature creates an
  996.      index entry that leads the reader to the definition.
  997.  
  998.    * Use `@table' ... `@end table' in an appendix that contains a
  999.      summary of functions, not `@deffn' or other definition commands.
  1000.  
  1001. Capitalization
  1002. ..............
  1003.  
  1004.    * Capitalize `Texinfo'; it is a name.  Do not write the `x' or `i'
  1005.      in upper case.
  1006.  
  1007.    * Capitalize `Info'; it is a name.
  1008.  
  1009.    * Write TeX using the `@TeX{}' command.  Note the uppercase `T' and
  1010.      `X'.  This command causes the formatters to typeset the name
  1011.      according to the wishes of Donald Knuth, who wrote TeX.
  1012.  
  1013. Spaces
  1014. ......
  1015.  
  1016.   Do not use spaces to format a Texinfo file, except inside of
  1017. `@example' ... `@end example' and similar commands.
  1018.  
  1019.   For example, TeX fills the following:
  1020.  
  1021.          @kbd{C-x v}
  1022.          @kbd{M-x vc-next-action}
  1023.             Perform the next logical operation
  1024.             on the version-controlled file
  1025.             corresponding to the current buffer.
  1026.  
  1027. so it looks like this:
  1028.  
  1029.      `C-x v' `M-x vc-next-action' Perform the next logical operation on
  1030.      the version-controlled file corresponding to the current buffer.
  1031.  
  1032. In this case, the text should be formatted with `@table', `@item', and
  1033. `@itemx', to create a table.
  1034.  
  1035. @code, @samp, @var, and `---'
  1036. .............................
  1037.  
  1038.    * Use `@code' around Lisp symbols, including command names.  For
  1039.      example,
  1040.  
  1041.           The main function is @code{vc-next-action}, ...
  1042.  
  1043.    * Avoid putting letters such as `s' immediately after an `@code'.
  1044.      Such letters look bad.
  1045.  
  1046.    * Use `@var' around meta-variables.  Do not write angle brackets
  1047.      around them.
  1048.  
  1049.    * Use three hyphens in a row, `---', to indicate a long dash.  TeX
  1050.      typesets these as a long dash and the Info formatters reduce three
  1051.      hyphens to two.
  1052.  
  1053. Periods Outside of Quotes
  1054. .........................
  1055.  
  1056.   Place periods and other punctuation marks *outside* of quotations,
  1057. unless the punctuation is part of the quotation.  This practice goes
  1058. against convention, but enables the reader to distinguish between the
  1059. contents of the quotation and the whole passage.
  1060.  
  1061.   For example, you should write the following sentence with the period
  1062. outside the end quotation marks:
  1063.  
  1064.      Evidently, `au' is an abbreviation for ``author''.
  1065.  
  1066. since `au' does *not* serve as an  abbreviation for `author.' (with a
  1067. period following the word).
  1068.  
  1069. Introducing New Terms
  1070. .....................
  1071.  
  1072.    * Introduce new terms so that a user who does not know them can
  1073.      understand them from context; or write a definition for the term.
  1074.  
  1075.      For example, in the following, the terms "check in", "register" and
  1076.      "delta" are all appearing for the first time; the example sentence
  1077.      should be rewritten so they are understandable.
  1078.  
  1079.           The major function assists you in checking in a file to your
  1080.           version control system and registering successive sets of
  1081.           changes to it as deltas.
  1082.  
  1083.    * Use the `@dfn' command around a word being introduced, to indicate
  1084.      that the user should not expect to know the meaning already, and
  1085.      should expect to learn the meaning from this passage.
  1086.  
  1087. @pxref
  1088. ......
  1089.  
  1090.   Absolutely never use `@pxref' except in the special context for which
  1091. it is designed: inside parentheses, with the closing parenthesis
  1092. following immediately after the closing brace.  One formatter
  1093. automatically inserts closing punctuation and the other does not.  This
  1094. means that the output looks right both in printed output and in an Info
  1095. file, but only when the command is used inside parentheses.
  1096.  
  1097. Invoking from a Shell
  1098. .....................
  1099.  
  1100.   You can invoke programs such as Emacs, GCC, and GAWK from a shell.
  1101. The documentation for each program should contain a section that
  1102. describes this.  Unfortunately, if the node names and titles for these
  1103. sections are all different, readers find it hard to search for the
  1104. section.
  1105.  
  1106.   Name such sections with a phrase beginning with the word
  1107. `Invoking ...', as in `Invoking Emacs'; this way users can find the
  1108. section easily.
  1109.  
  1110. ANSI C Syntax
  1111. .............
  1112.  
  1113.   When you use `@example' to describe a C function's calling
  1114. conventions, use the ANSI C syntax, like this:
  1115.  
  1116.      void dld_init (char *@var{path});
  1117.  
  1118. And in the subsequent discussion, refer to the argument values by
  1119. writing the same argument names, again highlighted with `@var'.
  1120.  
  1121.   Avoid the obsolete style that looks like this:
  1122.  
  1123.      #include <dld.h>
  1124.      
  1125.      dld_init (path)
  1126.      char *path;
  1127.  
  1128.   Also, it is best to avoid writing `#include' above the declaration
  1129. just to indicate that the function is declared in a header file.  The
  1130. practice may give the misimpression that the `#include' belongs near
  1131. the declaration of the function.  Either state explicitly which header
  1132. file holds the declaration or, better yet, name the header file used
  1133. for a group of functions at the beginning of the section that describes
  1134. the functions.
  1135.  
  1136. Bad Examples
  1137. ............
  1138.  
  1139.   Here are several examples of bad writing to avoid:
  1140.  
  1141.   In this example, say, " ... you must `@dfn'{check in} the new
  1142. version."  That flows better.
  1143.  
  1144.      When you are done editing the file, you must perform a
  1145.      `@dfn'{check in}.
  1146.  
  1147.   In the following example, say, "... makes a unified interface such as
  1148. VC mode possible."
  1149.  
  1150.      SCCS, RCS and other version-control systems all perform similar
  1151.      functions in broadly similar ways (it is this resemblance which
  1152.      makes a unified control mode like this possible).
  1153.  
  1154.   And in this example, you should specify what `it' refers to:
  1155.  
  1156.      If you are working with other people, it assists in coordinating
  1157.      everyone's changes so they do not step on each other.
  1158.  
  1159. And Finally ...
  1160. ...............
  1161.  
  1162.    * Pronounce TeX as if the `X' were a Greek `chi', as the last sound
  1163.      in the name `Bach'.  But pronounce Texinfo as in `speck':
  1164.      `teckinfo'.
  1165.  
  1166.    * Write notes for yourself at the very end of a Texinfo file after
  1167.      the `@bye'.  None of the formatters process text after the `@bye';
  1168.      it is as if the text were within `@ignore' ...  `@end ignore'.
  1169.  
  1170. 
  1171. File: texinfo.info,  Node: Sample Texinfo File,  Next: Sample Permissions,  Prev: Tips,  Up: Top
  1172.  
  1173. A Sample Texinfo File
  1174. *********************
  1175.  
  1176.   Here is a complete, short sample Texinfo file, without any commentary.
  1177. You can see this file, with comments, in the first chapter.  *Note A
  1178. Short Sample Texinfo File: Short Sample.
  1179.  
  1180.      \input texinfo   @c -*-texinfo-*-
  1181.      @c %**start of header
  1182.      @setfilename sample.info
  1183.      @settitle Sample Document
  1184.      @c %**end of header
  1185.      
  1186.      @setchapternewpage odd
  1187.      
  1188.      @ifinfo
  1189.      This is a short example of a complete Texinfo file.
  1190.      
  1191.      Copyright 1990 Free Software Foundation, Inc.
  1192.      @end ifinfo
  1193.      
  1194.      @titlepage
  1195.      @sp 10
  1196.      @comment The title is printed in a large font.
  1197.      @center @titlefont{Sample Title}
  1198.      
  1199.      @c The following two commands start the copyright page.
  1200.      @page
  1201.      @vskip 0pt plus 1filll
  1202.      Copyright @copyright{} 1990 Free Software Foundation, Inc.
  1203.      @end titlepage
  1204.      
  1205.      @node    Top,       First Chapter, (dir),    (dir)
  1206.      @comment node-name, next,          previous, up
  1207.      
  1208.      @menu
  1209.      * First Chapter::    The first chapter is the
  1210.                           only chapter in this sample.
  1211.      * Concept Index::    This index has two entries.
  1212.      @end menu
  1213.      
  1214.      @node    First Chapter, Concept Index, Top,      Top
  1215.      @comment node-name,     next,          previous, up
  1216.      @chapter First Chapter
  1217.      @cindex Sample index entry
  1218.      
  1219.      This is the contents of the first chapter.
  1220.      @cindex Another sample index entry
  1221.      
  1222.      Here is a numbered list.
  1223.      
  1224.      @enumerate
  1225.      @item
  1226.      This is the first item.
  1227.      
  1228.      @item
  1229.      This is the second item.
  1230.      @end enumerate
  1231.      
  1232.      The @code{makeinfo} and @code{texinfo-format-buffer}
  1233.      commands transform a Texinfo file such as this into
  1234.      an Info file; and @TeX{} typesets it for a printed
  1235.      manual.
  1236.      
  1237.      @node    Concept Index,    ,  First Chapter, Top
  1238.      @comment node-name,    next,  previous,      up
  1239.      @unnumbered Concept Index
  1240.      
  1241.      @printindex cp
  1242.      
  1243.      @contents
  1244.      @bye
  1245.  
  1246. 
  1247. File: texinfo.info,  Node: Sample Permissions,  Next: Include Files,  Prev: Sample Texinfo File,  Up: Top
  1248.  
  1249. Sample Permissions
  1250. ******************
  1251.  
  1252.   Texinfo files should contain sections that tell the readers that they
  1253. have the right to copy and distribute the Texinfo file, the Info file,
  1254. and the printed manual.
  1255.  
  1256.   Also, if you are writing a manual about software, you should explain
  1257. that the software is free and either include the GNU General Public
  1258. License (GPL) or provide a reference to it.  *Note Distribution:
  1259. (emacs)Distrib, for an example of the text that could be used in the
  1260. software "Distribution", "General Public License", and "NO WARRANTY"
  1261. sections of a document.  *Note Texinfo Copying Conditions: Copying, for
  1262. an example of a brief explanation of how the copying conditions provide
  1263. you with rights.
  1264.  
  1265. * Menu:
  1266.  
  1267. * Inserting Permissions::       How to put permissions in your document.
  1268. * ifinfo Permissions::          Sample `ifinfo' copying permissions.
  1269. * Titlepage Permissions::       Sample Titlepage copying permissions.
  1270.  
  1271. 
  1272. File: texinfo.info,  Node: Inserting Permissions,  Next: ifinfo Permissions,  Prev: Sample Permissions,  Up: Sample Permissions
  1273.  
  1274. Inserting Permissions
  1275. =====================
  1276.  
  1277.   In a Texinfo file, the first `@ifinfo' section usually begins with a
  1278. line that says what the file documents.  This is what a person reading
  1279. the unprocessed Texinfo file or using the advanced Info command `g *'
  1280. sees first.  *note Advanced Info commands: (info)Expert, for more
  1281. information. (A reader using the regular Info commands usually starts
  1282. reading at the first node and skips this first section, which is not in
  1283. a node.)
  1284.  
  1285.   In the `@ifinfo' section, the summary sentence is followed by a
  1286. copyright notice and then by the copying permission notice.  One of the
  1287. copying permission paragraphs is enclosed in `@ignore' and `@end
  1288. ignore' commands.  This paragraph states that the Texinfo file can be
  1289. processed through TeX and printed, provided the printed manual carries
  1290. the proper copying permission notice.  This paragraph is not made part
  1291. of the Info file since it is not relevant to the Info file; but it is a
  1292. mandatory part of the Texinfo file since it permits people to process
  1293. the Texinfo file in TeX and print the results.
  1294.  
  1295.   In the printed manual, the Free Software Foundation copying permission
  1296. notice follows the copyright notice and publishing information and is
  1297. located within the region delineated by the `@titlepage' and `@end
  1298. titlepage' commands.  The copying permission notice is exactly the same
  1299. as the notice in the `@ifinfo' section except that the paragraph
  1300. enclosed in `@ignore' and `@end ignore' commands is not part of the
  1301. notice.
  1302.  
  1303.   To make it simple to insert a permission notice into each section of
  1304. the Texinfo file, sample permission notices for each section are
  1305. reproduced in full below.
  1306.  
  1307.   Note that you may need to specify the correct name of a section
  1308. mentioned in the permission notice.  For example, in `The GDB Manual',
  1309. the name of the section referring to the General Public License is
  1310. called the "GDB General Public License", but in the sample shown below,
  1311. that section is referred to generically as the "GNU General Public
  1312. License".  If the Texinfo file does not carry a copy of the General
  1313. Public License, leave out the reference to it, but be sure to include
  1314. the rest of the sentence.
  1315.  
  1316.