Return to texinfo.texinfo CVS log

Up to [CSRG BSD Unix] / 43BSD / contrib / emacs / man

Annotation of 43BSD/contrib/emacs/man/texinfo.texinfo, revision 1.1

1.1     ! root        1: \input texinfo   @c -*-texinfo-*-
        !             2: @setfilename ../info/texinfo
        !             3: @settitle Texinfo
        !             4: 
        !             5: @titlepage
        !             6: @center @titlefont{Texinfo}
        !             7: @sp 1
        !             8: @center The GNU Documentation Format
        !             9: @sp 2
        !            10: @center Richard M. Stallman
        !            11: @end titlepage
        !            12: 
        !            13: @unnumbered Distribution
        !            14: 
        !            15: Copyright @copyright{} 1985 Richard M. Stallman.
        !            16: 
        !            17: Permission is granted to make and distribute verbatim copies of
        !            18: this manual provided the copyright notice and this permission notice
        !            19: are preserved on all copies.
        !            20: 
        !            21: @ignore
        !            22: Permission is granted to process this file through Tex and print the
        !            23: results, provided the printed document carries copying permission
        !            24: notice identical to this one except for the removal of this paragraph
        !            25: (this paragraph not being relevant to the printed manual).
        !            26: 
        !            27: @end ignore
        !            28: Permission is granted to copy and distribute modified versions of this
        !            29: manual under the conditions for verbatim copying, provided that the entire
        !            30: resulting derived work is distributed under the terms of a permission
        !            31: notice identical to this one.
        !            32: 
        !            33: Permission is granted to copy and distribute translations of this manual
        !            34: into another language, under the same conditions as for modified versions.
        !            35: 
        !            36: @node top, commands, , (DIR)
        !            37: @chapter Texinfo Files
        !            38: 
        !            39: Documentation for GNU utilities and libraries should be written
        !            40: in a format called @dfn{texinfo}.  This format can be translated
        !            41: mechanically into either printed manuals or on-line readable
        !            42: Info files.@refill
        !            43: 
        !            44: @menu
        !            45: * info::       What Info files do.
        !            46: * commands::   What goes into a texinfo file.
        !            47: * make-info::  Making a texinfo file into an Info file.
        !            48: * manual::     Making a texinfo file into a printed manual.
        !            49: @end menu
        !            50: 
        !            51: @node info, commands, top, top
        !            52: @section What Info Files Do
        !            53: 
        !            54: An Info file is a file formatted so that the Info documentation reading
        !            55: program can operate on it.  Info files are divided into pieces called
        !            56: @dfn{nodes}, each of which contains the discussion of one topic.  Each node
        !            57: has a name, and contains both text for the user to read and pointers to
        !            58: other nodes, which are identified by their names.  Info displays one node
        !            59: at a time, and provides commands with which the user can move to the other
        !            60: nodes that the current node points to.
        !            61: 
        !            62: Normally most of the nodes are arranged in a tree which branches down.
        !            63: Each node may have any number of child nodes that describe subtopics of the
        !            64: node's topic.  The names of these child nodes, if any, are listed in a
        !            65: @dfn{menu} within the parent node; this allows certain Info commands to
        !            66: be used to move to one of the child nodes.  Each child node records the
        !            67: parent node name, as its `up' pointer.
        !            68: 
        !            69: All the children of any one parent are linked together in a bidirectional
        !            70: chain of `next' and `previous' pointers.  Normally the order in this chain
        !            71: is the same as the order of the children in the parent's menu.  The last
        !            72: child has no `next' pointer, and the first child normally has the parent as
        !            73: its `previous' pointer (as well as its `up' pointer, of course).
        !            74: 
        !            75: The root of the tree is the top node of the file, through which users
        !            76: enter the file from the Info directory.  By convention, this node is always
        !            77: called @samp{top}.  This node normally contains just a brief summary of the
        !            78: file's purpose, and a large menu through which the rest of the file is
        !            79: reached.
        !            80: 
        !            81: Structuring the nodes in a tree is a matter of convention, not a
        !            82: requirement.  In fact, the `up', `previous' and `next' pointers of a node
        !            83: can point to any other nodes, and the menu can contain any other nodes.
        !            84: The structure of nodes can be any directed graph.  But it is usually more
        !            85: comprehensible to the user to make it a tree.  Info provides another kind
        !            86: of pointer between nodes, called a reference, that can be sprinkled through
        !            87: the text of a node.  This is usually the best way to represent links that
        !            88: do not fit the tree structure.
        !            89: 
        !            90: Most often the nodes fall into a strict tree structure, and most often this
        !            91: structure corresponds to the structure of chapters, sections, subsections,
        !            92: and so on of a printed manual.  But there are times when this is not right
        !            93: for the material being discussed.  Therefore, texinfo format uses separate
        !            94: commands to specify the node structure of the Info file and the section
        !            95: structure of the a printed manual.  Also, texinfo requires menus to be
        !            96: specified explicitly, rather than generating them automatically based on an
        !            97: assumed tree structure.
        !            98: 
        !            99: @node commands, make-info, info, top
        !           100: @section General Syntactic Conventions
        !           101: 
        !           102: Texinfo files contain a strictly limited set of constructs for a @TeX{}
        !           103: macro package quite different from plain @TeX{}.  The strict limits make it
        !           104: possible for texinfo files to be understood also by the @code{texinfo}
        !           105: program, which converts them into Info files.
        !           106: 
        !           107: In order to be made into an Info file, a texinfo file must start with a
        !           108: line that looks like
        !           109: @example
        !           110: @@setfilename @var{info-file-name}
        !           111: @end example
        !           112: @noindent
        !           113: which specifies the name of the Info file to be generated.  In fact, there
        !           114: can be other things in the file before this line, but they are ignored in
        !           115: the generation of an Info file.  The @code{@@setfilename} line is ignored
        !           116: when a printed manual is generated.
        !           117: 
        !           118: All ASCII printing characters except @code{@@}, @code{@{} and @code{@}} can
        !           119: appear in body text in a texinfo file and stand for themselves.  @code{@@}
        !           120: is the escape character which introduces commands.  @code{@{} and @code{@}}
        !           121: should be used only to surround arguments to certain commands.  @code{@{}
        !           122: and @code{@}} appearing anywhere else will be treated by @TeX{} as a
        !           123: grouping but treated by texinfo as themselves; this inconsistency is
        !           124: undesirable, so don't let it occur.  To put one of these special characters
        !           125: into the document, put an @samp{@@} character in front of it.@refill
        !           126: 
        !           127: It is customary in @TeX{} to use doubled single-quote characters to begin
        !           128: and end quotations.  This convention should be followed in texinfo files.
        !           129: 
        !           130: @TeX{} ignores the line-breaks in the input text, except for blank lines,
        !           131: which separate paragraphs.  Texinfo generally preserves the line breaks
        !           132: that are present in the input file.  Therefore, you break the lines in the
        !           133: texinfo file the way you want them to appear in the output Info file, and
        !           134: let @TeX{} take care of itself.
        !           135: 
        !           136: @section @@-Command Syntax
        !           137: 
        !           138: The character @@ is used to start special texinfo commands.  (It has the
        !           139: same meaning that @t{\} has in plain @TeX{}.)  Syntactically, there
        !           140: are three classes of @@-commands:
        !           141: 
        !           142: @enumerate
        !           143: @item
        !           144: Non-alphabetic commands, @@ followed by a punctuation character.
        !           145: These commands are always part of the text within a paragraph, and
        !           146: never take any argument.  The two characters (@@ and the other one)
        !           147: are complete in themselves.
        !           148: @item
        !           149: Alphabetic commands used within a paragraph.  These commands have @@
        !           150: followed by a word, followed by an argument within braces.  For
        !           151: example, the command @code{@@i} specifies italic font (for @TeX{}
        !           152: processing only); it is used as follows: @samp{I do @@i@{not@} want
        !           153: to eat that.}
        !           154: @item
        !           155: Alphabetic commands used outside of paragraphs.  Each such command
        !           156: occupies an entire line.  The line starts with @@, followed by the
        !           157: name of the command (a word).  If no argument is needed, the word is
        !           158: followed by the end of the line.  If there is an argument, it is
        !           159: separated from the command name by a space.
        !           160: @end enumerate
        !           161: 
        !           162: Thus, the alphabetic commands fall into two classes that have different
        !           163: argument syntax.  You cannot tell which class a command falls in by the
        !           164: appearance of its name, but you can tell by the command's meaning: if it
        !           165: makes sense to use the command together with other words as part of a
        !           166: paragraph, the command is in class 2 and must be followed by an argument in
        !           167: braces; otherwise, it is in class 3 and uses the rest of the line as its
        !           168: argument.
        !           169: 
        !           170: The purpose of having different syntax for commands of classes 2 and 3 is
        !           171: to make the texinfo file easier to read, and also to help the Emacs
        !           172: paragraph and filling commands work properly.  There is only one exception
        !           173: to this rule: the command @code{@@refill}, which is always used at the end
        !           174: of a paragraph immediately following the final period or other punctuation
        !           175: character.  @code{@@refill} takes no argument.  @code{@@refill} never
        !           176: confuses the Emacs paragraph commands because it cannot start at the
        !           177: beginning of a line.@refill
        !           178: 
        !           179: @section Within-Paragraph Commands
        !           180: 
        !           181: The @@-commands used within a paragraph either generate a small amount of
        !           182: text or modify the treatment of some text.
        !           183: 
        !           184: @subsection @@@@
        !           185: 
        !           186: @code{@@@@} stands for a single @@ in either printed or Info output.
        !           187: 
        !           188: @subsection @@@{
        !           189: 
        !           190: @code{@@@{} stands for a single @{ in either printed or Info output.
        !           191: 
        !           192: @subsection @@@}
        !           193: 
        !           194: @code{@@@}} stands for a single @} in either printed or Info output.
        !           195: 
        !           196: @subsection @@:
        !           197: 
        !           198: @code{@@:}@: is used after a character such as period or colon which
        !           199: normally causes @TeX{} to increase the width of the following whitespace,
        !           200: to suppress that effect.  For example, it can be used after periods that
        !           201: end abbreviations and do not end sentences.  @code{@@:}@: has no effect
        !           202: on the Info file output.
        !           203: 
        !           204: @example
        !           205: It displays @@code@{Foo:@}@@: at that time.
        !           206: @end example
        !           207: 
        !           208: @noindent
        !           209: produces
        !           210: 
        !           211: @quotation
        !           212: It displays @code{Foo:}@: at that time.
        !           213: @end quotation
        !           214: 
        !           215: Note that the meanings of @code{@@:}@: and @code{@@.}@: in texinfo are
        !           216: not compatible with their meanings in Scribe; in fact, they are nearly the
        !           217: opposite.  The meanings in texinfo were designed to work well with the
        !           218: Emacs sentence motion commands.@refill
        !           219: 
        !           220: @subsection @@.
        !           221: 
        !           222: @code{@@.}@: stands for a period that really does end a sentence, useful when
        !           223: @TeX{} will assume by its heuristics that that is not so.  This happens
        !           224: when there is a single-capital-letter word at the end of a sentence: @TeX{}
        !           225: normally guesses that it is an abbreviation.
        !           226: 
        !           227: In the Info file output, @code{@@.}@: is equivalent to a simple @samp{.}.
        !           228: The texinfo program preserves the amount of space that you use, so put
        !           229: two spaces after a period if you intend it to be the end of a sentence
        !           230: (as well as using @code{@@.}, if necessary, for the printed manual's sake).
        !           231: 
        !           232: @example
        !           233: Give it to X. Give it to X@@.  Give it to X@@.
        !           234: @end example
        !           235: 
        !           236: @noindent
        !           237: produces
        !           238: 
        !           239: @quotation
        !           240: Give it to X. Give it to X@.  Give it to X@.
        !           241: @end quotation
        !           242: 
        !           243: @subsection @@*
        !           244: 
        !           245: @code{@@*} forces a line break in the printed manual.  It has no effect on
        !           246: the Info file output, where line breaks follow those in the source file.
        !           247: If you want a line break at a certain spot in both forms of output, break
        !           248: the line there in the source file and put @code{@@*} at the end of the
        !           249: line.
        !           250: 
        !           251: @subsection @@dots
        !           252: 
        !           253: @code{@@dots@{@}} generates an ellipsis: three periods in a row, or `@dots{}'.
        !           254: Do not simply write three periods in the input file; that would work ok for
        !           255: the Info file output, but would produce the wrong amount of space between
        !           256: the periods in the printed manual.
        !           257: 
        !           258: @subsection @@bullet
        !           259: 
        !           260: @code{@@bullet@{@}} generates a large round dot, or the closest possible
        !           261: thing to one.
        !           262: 
        !           263: @subsection @@TeX
        !           264: 
        !           265: @code{@@TeX@{@}} generates `@TeX{}'.  In a printed manual, this is a special
        !           266: logo that is different from three ordinary letters.
        !           267: 
        !           268: @subsection @@copyright
        !           269: 
        !           270: @code{@@copyright@{@}} generates a @samp{C} inside a circle.
        !           271: 
        !           272: @subsection @@code
        !           273: 
        !           274: @code{@@code} is used to indicate text that is a literal example of input
        !           275: to a program.  The text follows, enclosed in braces.  Any time you give a
        !           276: sample of an expression in C, or of a command for the shell, or any such
        !           277: thing, use @code{@@code}.  In the printed manual, it puts the argument in
        !           278: bold face.  In the Info file, it uses `@dots{}' quotation.  Example:
        !           279: 
        !           280: @example
        !           281: To compare two files, showing text inserted or removed, use @@code@{diff@}.
        !           282: @end example
        !           283: 
        !           284: @noindent
        !           285: produces
        !           286: 
        !           287: @quotation
        !           288: To compare two files, showing text inserted or removed, use @code{diff}.
        !           289: @end quotation
        !           290: 
        !           291: @subsection @@samp
        !           292: 
        !           293: @code{@@samp} is used to indicate text that is a literal example of a
        !           294: sequence of characters in a file, string, pattern, etc.  The text follows,
        !           295: enclosed in braces.  The argument appears within `@dots{}' quotation in
        !           296: both the Info file and the printed manual; in addition, it is printed in
        !           297: a fixed-width font.
        !           298: 
        !           299: @example
        !           300: To match @@samp@{foo@} at the end of the line, use the regexp @@samp@{foo$@}.
        !           301: @end example
        !           302: 
        !           303: @noindent
        !           304: produces
        !           305: 
        !           306: @quotation
        !           307: To match @samp{foo} at the end of the line, use the regexp @samp{foo$}.
        !           308: @end quotation
        !           309: 
        !           310: @subsection @@file
        !           311: 
        !           312: @code{@@file} is used to indicate text that is a file name.  Currently
        !           313: it is equivalent to @code{@@samp} in its effects on the output.
        !           314: 
        !           315: @subsection @@kbd
        !           316: 
        !           317: @code{@@kbd} is used much like @code{@@code}.  The difference is that
        !           318: @code{@@kbd} is for names of keys on the keyboard, or of characters you can
        !           319: type.  It has the same effect as @code{@@code} in texinfo, but may produce
        !           320: a different font in a printed manual.@refill
        !           321: 
        !           322: @example
        !           323: To give the @@code@{logout@} command, type the characters @@kbd@{l o g o u t
        !           324: @@key@{RET@}@}.
        !           325: @end example
        !           326: 
        !           327: @noindent
        !           328: produces
        !           329: 
        !           330: @quotation
        !           331: To give the @code{logout} command, type the characters @kbd{l o g o u t
        !           332: @key{RET}}.
        !           333: @end quotation
        !           334: 
        !           335: @subsection @@key
        !           336: 
        !           337: @code{@@key} is used to indicate text that is the name of a key on
        !           338: the keyboard, as in
        !           339: 
        !           340: @example
        !           341: @@key@{RET@}
        !           342: @end example
        !           343: 
        !           344: Often, @code{@@key} is used within the argument of a @code{@@kbd}
        !           345: command, whenever the sequence of characters to be typed includes one or
        !           346: more keys that are described by name.@refill
        !           347: 
        !           348: The recommended names to use for keys are
        !           349: 
        !           350: @table @t
        !           351: @item SPC
        !           352: Space.
        !           353: @item RET
        !           354: Return.
        !           355: @item LFD
        !           356: Linefeed.
        !           357: @item TAB
        !           358: Tab.
        !           359: @item BS
        !           360: Backspace.
        !           361: @item ESC
        !           362: Escape.
        !           363: @item DEL
        !           364: Delete.
        !           365: @item SFT
        !           366: Shift.
        !           367: @item CTL
        !           368: Control.
        !           369: @item META
        !           370: Meta.
        !           371: @end table
        !           372: 
        !           373: @subsection @@ctrl
        !           374: 
        !           375: @code{@@ctrl} is used to describe an ASCII control character.  The pattern
        !           376: of usage is @code{@@ctrl@{@var{ch}@}}, where @var{ch} is an ASCII character whose
        !           377: control-equivalent is wanted.
        !           378: 
        !           379: In the Info file, this generates the specified control character, output
        !           380: literally into the file.
        !           381: 
        !           382: In a printed manual, this generates text to describe or identify that
        !           383: control character: an uparrow followed by the character @var{ch}.
        !           384: 
        !           385: @subsection @@var
        !           386: 
        !           387: @code{@@var} is used to indicate metasyntactic variables.  Its effect in
        !           388: the Info file is to upcase the argument; in the printed manual, to
        !           389: italicize it.  Example:
        !           390: 
        !           391: @example
        !           392: To delete file @@var@{file@}, type @@code@{rm @@var@{file@}@}.
        !           393: @end example
        !           394: 
        !           395: @noindent
        !           396: produces
        !           397: 
        !           398: @quotation
        !           399: To delete file @var{file}, type @code{rm @var{file}}.
        !           400: @end quotation
        !           401: 
        !           402: @subsection @@dfn
        !           403: 
        !           404: @code{@@dfn} is used to identify the introductory or defining use of a
        !           405: technical term.  It generates italics in the printed manual, and double
        !           406: quotation marks in the Info file.  Example:
        !           407: 
        !           408: @example
        !           409: Getting rid of a file is called @@dfn@{deleting@} it.
        !           410: @end example
        !           411: 
        !           412: @noindent
        !           413: produces
        !           414: 
        !           415: @quotation
        !           416: Getting rid of a file is called @dfn{deleting} it.
        !           417: @end quotation
        !           418: 
        !           419: @subsection @@i or @@b or @@t
        !           420: 
        !           421: These three commands specify font change in the printed manual and have no
        !           422: effect in the Info file.  @code{@@i} requests italic font (actually,
        !           423: slanted font is used by @TeX{}), @code{@@b} requests bold face, and
        !           424: @code{@@t} requests the fixed-width font used by @code{@@kbd}.
        !           425: All three commands apply to an argument that follows, surrounded by
        !           426: braces.@refill
        !           427: 
        !           428: @subsection @@w
        !           429: 
        !           430: In a printed manual, @code{@@w@{@var{text}@}} outputs @var{text} and prohibits
        !           431: line breaks within @var{text}.  @code{@@w} has no effect on the Info file
        !           432: output; it is the same as would result from just @var{text}.
        !           433: 
        !           434: @subsection @@refill
        !           435: 
        !           436: If a paragraph contains sizeable @@-constructs, it may look badly filled
        !           437: once texinfo is through with it.
        !           438: 
        !           439: Put @code{@@refill} at the end of the paragraph to tell texinfo to
        !           440: refill the paragraph after finishing all other processing on it.
        !           441: @code{@@refill} has no effect on @TeX{}, which always fills everything
        !           442: that ought to be filled.  Example:@refill
        !           443: 
        !           444: @example
        !           445: To use @@code@{foo@}, pass @@samp@{xx%$@} and @@var@{flag@} and type @@kbd@{x@}
        !           446: after running @@code@{make-foo@}.@@refill
        !           447: @end example
        !           448: 
        !           449: @noindent
        !           450: produces (in the Info file)
        !           451: 
        !           452: @example
        !           453: To use `foo', pass `xx%$' and FLAG and type `x' after running `make-foo'.
        !           454: @end example
        !           455: 
        !           456: @noindent
        !           457: whereas without the @code{@@refill} it would produce
        !           458: 
        !           459: @example
        !           460: To use `foo', pass `xx%$' and FLAG and type `x'
        !           461: after running `make-foo'.
        !           462: @end example
        !           463: 
        !           464: @noindent
        !           465: with the line broken at the same place as in the input.
        !           466: 
        !           467: @section Chapter Structuring Commands
        !           468: 
        !           469: The chapter structuring commands divide a document into a hierarchy of
        !           470: chapters, sections, subsections and subsubsections.  These commands
        !           471: generate large headings in the middle of the text.
        !           472: 
        !           473: In a printed manual, the table of contents is based on the information
        !           474: specified by the chapter structuring commands.
        !           475: 
        !           476: @subsection @@chapter
        !           477: 
        !           478: @code{@@chapter} identifies a chapter in the document.  It is followed by a
        !           479: single argument which is the rest of the line, as in
        !           480: 
        !           481: @example
        !           482: @@chapter Texinfo Files
        !           483: @end example
        !           484: 
        !           485: In @TeX{}, it serves to create a chapter of the document, specifying the
        !           486: chapter title.
        !           487: 
        !           488: In the Info file, @code{@@chapter} causes its argument to appear on a line
        !           489: by itself, with a line of asterisks inserted underneath.  Thus, the above
        !           490: example produces the output@refill
        !           491: 
        !           492: @example
        !           493: Texinfo Files
        !           494: *************
        !           495: @end example
        !           496: 
        !           497: @subsection @@unnumbered, @@appendix
        !           498: 
        !           499: These are equivalent to @code{@@chapter} for Info file output.  In a
        !           500: printed manual, they generate chapters that are numbered differently in the
        !           501: table of contents.  @code{@@unnumbered} chapters appear without chapter
        !           502: numbers of any kind, and @code{@@appendix} chapters are given a letter
        !           503: instead of a number.
        !           504: 
        !           505: @subsection @@section
        !           506: 
        !           507: @code{@@section} is like @code{@@chapter} except that in @TeX{} it makes
        !           508: a section rather than a chapter.  Sections go within chapters.  In the Info
        !           509: file, @code{@@chapter} and @code{@@section} differ only in that
        !           510: @code{@@section} underlines with @samp{=}.@refill
        !           511: 
        !           512: @subsection @@unnumberedsec, @@appendixsec
        !           513: 
        !           514: Use these constructs for sections within chapters made by
        !           515: @code{@@unnumbered} or @code{@@appendix}.
        !           516: 
        !           517: @subsection @@subsection
        !           518: 
        !           519: Subsections are to sections as sections are to chapters.  They are
        !           520: underlined with @samp{-}.
        !           521: 
        !           522: @subsection @@unnumberedsubsec, @@appendixsubsec
        !           523: 
        !           524: Use these constructs for subsections within sections within chapters made
        !           525: by @code{@@unnumbered} or @code{@@appendix}.
        !           526: 
        !           527: @subsection @@subsubsection
        !           528: 
        !           529: Subsubsections are to subsections as subsections are to sections.  They are
        !           530: underlined with periods.
        !           531: 
        !           532: @section Nodes and Cross References
        !           533: 
        !           534: @dfn{Nodes} are the points to which cross-references can refer.  The
        !           535: @code{@@node} command is used to define them.  Each node must be, also, a
        !           536: chapter, section, subsection or subsubsection, and the @code{@@node}
        !           537: command must always be followed by a chapter structuring command (with no
        !           538: blank line between them).
        !           539: 
        !           540: In the Info file, nodes play a fundamental role.  Each node has a name,
        !           541: and other nodes can refer to it by that name.  The @code{@@node} command
        !           542: specifies the name of the node that it defines, and also defines certain
        !           543: references to other nodes.  References to other nodes can also be defined
        !           544: with @code{@@menu} and the variants of @code{@@xref}.
        !           545: 
        !           546: In a printed manual, nodes are not a fundamental concept, but the
        !           547: @code{@@node} command still serves to define a cross-reference point
        !           548: and the variants of @code{@@xref} still serve to make references.
        !           549: 
        !           550: @subsection @@node
        !           551: 
        !           552: @code{@@node} defines the beginning of a new node in the Info output file
        !           553: (@inforef{top, info, info}.).  It is followed by four arguments, separated
        !           554: by commas, making up the rest of the line.  For example,@refill
        !           555: 
        !           556: @example
        !           557: @@node info, tex, commands, top
        !           558: @end example
        !           559: 
        !           560: @noindent
        !           561: defines a node named @code{info}, whose `next' pointer is to node
        !           562: @code{tex}, whose `previous' pointer is to node @code{commands}, and whose
        !           563: `up' pointer is to node @code{top}.  What this means is that texinfo
        !           564: changes @w{@code{@@node @var{args}}} into the special text string necessary to
        !           565: separate Info nodes and to identify the node that is starting and say what
        !           566: nodes it points to.@refill
        !           567: 
        !           568: The pointer names should be the names of nodes defined elsewhere.  For this
        !           569: example, nodes named @code{tex}, @code{commands} and @code{top} should be
        !           570: defined elsewhere in the file with other @code{@@node} commands.  It does
        !           571: not matter whether they are before or after the node that refers to
        !           572: them.@refill
        !           573: 
        !           574: Normally, node @var{a}'s `up' should point at the node whose menu mentions
        !           575: node @var{a}.  Node @var{a}'s `next' should point at the node that follows
        !           576: @var{a} in that menu, and node @var{a}'s `previous' should point at the
        !           577: node that precedes @var{a} in that menu.@refill
        !           578: 
        !           579: The top node of the file, named @samp{top}, should have as its parent the
        !           580: name of a node in another file, where there is a menu that leads to this
        !           581: file.  Specify the file name in parentheses.  If this file is to be
        !           582: installed directly in the Info directory file, use @samp{(dir)} as the
        !           583: parent of the top node; this is short for @samp{(dir)top}, the node @samp{top}
        !           584: in the file @file{dir}, which is the main menu of Info.
        !           585: 
        !           586: In @TeX{}, @code{@@node} is nearly ignored.  It generates no text.  Its
        !           587: only function is to identify the name to use for cross-references to the
        !           588: following chapter or section which makes up the body of the node.  (Cross
        !           589: references are made with @code{@@xref}.)@refill
        !           590: 
        !           591: @code{@@node} should always be followed immediately by a
        !           592: chapter-structuring command such as @code{@@chapter}, @code{@@section},
        !           593: @code{@@subsection} or @code{@@subsubsection}.
        !           594: 
        !           595: @subsection @@menu
        !           596: 
        !           597: Info file nodes can contain @dfn{menus} which point to other nodes.  You
        !           598: must type the menus in by hand, and surround them with lines containing
        !           599: @code{@@menu} and @code{@@end menu}.  The @code{@@menu} line changes
        !           600: into @code{* Menu:}, which indicates the beginning of a menu to the Info
        !           601: program.  The contents are unchanged by texinfo, except for the processing
        !           602: of any other @@ commands within.  The entire menu construct has no effect
        !           603: in the printed manual.@refill
        !           604: 
        !           605: @example
        !           606: @@menu
        !           607: * foo::         The node named foo tells you how to go fooing.
        !           608: * sw: switches. Type @@code@{m sw@} to see node @@code@{switches@}.
        !           609:                 which describes the switches available here.
        !           610: @@end menu
        !           611: @end example
        !           612: 
        !           613: @noindent
        !           614: produces
        !           615: 
        !           616: @example
        !           617: * menu:
        !           618: 
        !           619: * foo::         The node named foo tells you how to go fooing.
        !           620: * sw: switches. Type `m sw' to see node `switches'
        !           621:                 which describes the switches available here.
        !           622: @end example
        !           623: 
        !           624: In this example, the menu has two items.  @samp{foo} is both a menu item name
        !           625: and the name of the node referred to by that item.  @samp{sw} is the other
        !           626: menu item name, and it refers to the node named @samp{switches}.  Since no
        !           627: file name is specified with @samp{foo} or @samp{switches}, they must be the names
        !           628: of other nodes in the same Info file.  Nodes in other Info files can be
        !           629: referred to by putting the file name in parentheses at the beginning of the
        !           630: node name.
        !           631: 
        !           632: @subsection @@xref
        !           633: 
        !           634: @code{@@xref} generates a cross-reference.  In texinfo, it turns into
        !           635: an Info cross-reference which the Info @code{f} command can use
        !           636: to go directly to another node.  In @TeX{}, it turns into a sentence
        !           637: of the form
        !           638: 
        !           639: @example
        !           640: See section @var{section} [@var{topic}], page @var{page}
        !           641: @end example
        !           642: 
        !           643: @noindent
        !           644: but does not generate a period to end it.
        !           645: 
        !           646: @code{@@xref} must refer to an Info node created by @code{@@node}, by the
        !           647: node's name.  If I were in less of a rush, I would have made a node in this
        !           648: file for each texinfo command, and put in plenty of @@xref's to
        !           649: cross-reference them together.  The big node named @code{commands} would
        !           650: actually contain a menu naming the nodes for individual commands.
        !           651: 
        !           652: @code{@@xref} is followed by an argument inside braces, since it is used
        !           653: within a paragraph; but actually the text inside the braces is treated as
        !           654: several arguments, separated by commas.  Whitespace after these commas is
        !           655: ignored.  The closing brace must be followed by a period or a comma, since
        !           656: one of those two is required to terminate an Info cross-reference.  This
        !           657: period or comma will appear in the output, both Info file and printed
        !           658: manual.
        !           659: 
        !           660: The simplest form of @code{@@xref} takes one argument, the name of another
        !           661: node in the same Info file.  Here we show the input text, followed after a
        !           662: blank line by the output text for Info files and the output text for
        !           663: printed manuals.
        !           664: 
        !           665: @example
        !           666: @@xref@{foo@}, for more info.
        !           667: 
        !           668: *note foo::, for more info.
        !           669: @end example
        !           670: 
        !           671: @quotation
        !           672: See section @var{nnn} [foo], page @var{ppp}, for more info.
        !           673: @end quotation
        !           674: 
        !           675: With two arguments, the second one is used as the name of the Info
        !           676: cross-reference, while the first argument is still the node that the
        !           677: cross-reference points to:
        !           678: 
        !           679: @example
        !           680: @@xref@{foo node, foo@}, for more info.
        !           681: 
        !           682: *note foo: foo node, for more info.
        !           683: @end example
        !           684: 
        !           685: @quotation
        !           686: See section @var{nnn} [foo node], page @var{ppp}, for more info.
        !           687: @end quotation
        !           688: 
        !           689: A third argument replaces the node name when it actually appears
        !           690: in the TeX output.  It should state the topic discussed by the
        !           691: section being referenced.  Use a third argument when the node
        !           692: name is unsuitable because of syntax, grammar or diction.
        !           693: 
        !           694: @example
        !           695: @@xref@{foo node, foo, using foo@}, for more info.
        !           696: 
        !           697: *note foo: foo node, for more info.
        !           698: @end example
        !           699: 
        !           700: @quotation
        !           701: See section @var{nnn} [using foo], page @var{ppp}, for more info.
        !           702: @end quotation
        !           703: 
        !           704: If a third argument is given and the second one is empty,
        !           705: then the third argument serves both purposes:
        !           706: 
        !           707: @example
        !           708: @@xref@{foo node, , using foo@}, for more info.
        !           709: 
        !           710: *note using foo: foo node, for more info.
        !           711: @end example
        !           712: 
        !           713: @quotation
        !           714: See section @var{nnn} [using foo], page @var{ppp}, for more info.
        !           715: @end quotation
        !           716: 
        !           717: A fourth argument specifies the name of the Info file in which
        !           718: the referenced node is located, assuming it is not the one which
        !           719: the reference appears in.  @code{@@xref} with only four arguments
        !           720: is used when the reference is not within one Info file, but is
        !           721: within a single printed manual---when multiple texinfo files are
        !           722: incorporated into the same TeX run but make separate Info files.
        !           723: 
        !           724: @example
        !           725: @@xref@{foo node, foo, using foo, myinfofile@}, for more info.
        !           726: 
        !           727: *note foo: (myinfofile) foo node, for more info.
        !           728: @end example
        !           729: 
        !           730: @quotation
        !           731: See section @var{nnn} [using foo], page @var{ppp}, for more info.
        !           732: @end quotation
        !           733: 
        !           734: A fifth argument is used when referencing another Info file
        !           735: which is also part of another printed manual.  It gives the
        !           736: title of that manual.
        !           737: 
        !           738: @example
        !           739: @@xref@{foo node, foo, using foo, myinfofile, Mymanual@},
        !           740: for more info.
        !           741: 
        !           742: *note foo: (myinfofile) foo node, for more info.
        !           743: @end example
        !           744: 
        !           745: @quotation
        !           746: See section @var{nnn} [using foo], page @var{ppp}
        !           747: of Mymanual, for more info.
        !           748: @end quotation
        !           749: 
        !           750: @subsection @@pxref
        !           751: 
        !           752: @code{@@pxref} is nearly the same as @code{@@xref}; it differs in only
        !           753: two ways:
        !           754: 
        !           755: @enumerate
        !           756: @item
        !           757: The output starts with lower case `see' rather than `See'.
        !           758: @item
        !           759: A period is generated automatically in the Info file output to end the
        !           760: Info cross-reference.
        !           761: @end enumerate
        !           762: 
        !           763: The purpose of @code{@@pxref} is to be used inside parentheses as part of
        !           764: another sentence.  In the printed manual, no period is needed after the
        !           765: cross reference text itself (within the parentheses), but a period is
        !           766: needed there in the Info file because only thus can Info recognize the end
        !           767: of the cross-reference.  @code{@@pxref} spares you the need to use complicated
        !           768: methods to put a period into one form of the output and not the other.
        !           769: 
        !           770: @subsection @@inforef
        !           771: 
        !           772: @code{@@inforef} is used for cross-references to Info files for which
        !           773: there are no printed manuals.  Even in a printed manual, @code{@@inforef}
        !           774: generates a reference directing the user to look in an Info file.  The
        !           775: syntax is @code{@@inforef@{@var{node}, @var{name}, @var{file}@}}.
        !           776: 
        !           777: @example
        !           778: @@inforef@{foo node, fooing, FOO@}, to lose.
        !           779: 
        !           780: *note fooing: (FOO) foo node, to lose.
        !           781: @end example
        !           782: 
        !           783: @quotation
        !           784: See Info file @file{FOO}, node `foo node', to lose.
        !           785: @end quotation
        !           786: 
        !           787: @section Insertions
        !           788: 
        !           789: Insertions are blocks of text, consisting of one or more whole paragraphs
        !           790: that are set off from the bulk of the text and treated differently.  They
        !           791: are usually indented, and often not filled.
        !           792: 
        !           793: In texinfo, an insertion is always begun by an @@-command on a line by
        !           794: itself, and ended with an @code{@@end} command.  For example, an @dfn{example}
        !           795: is a kind of insertion that is begun with @code{@@example} and ended with
        !           796: @code{@@end example}.
        !           797: 
        !           798: @subsection @@quotation
        !           799: 
        !           800: @code{@@quotation} is used to indicate text that is excerpted from another
        !           801: (real or hypothetical) printed work.  The inside of a quotation is
        !           802: processed normally except that
        !           803: 
        !           804: @enumerate
        !           805: @item
        !           806: The margins are narrower.
        !           807: @item
        !           808: Paragraphs are not indented.
        !           809: @item
        !           810: Interline spacing and interparagraph spacing are reduced.
        !           811: @end enumerate
        !           812: 
        !           813: Thus, the input
        !           814: 
        !           815: @example
        !           816: @@quotation
        !           817: This is
        !           818: a foo.
        !           819: @@end quotation
        !           820: @end example
        !           821: 
        !           822: @noindent
        !           823: produces in the printed manual
        !           824: 
        !           825: @quotation
        !           826: @quotation
        !           827: This is a foo.
        !           828: @end quotation
        !           829: @end quotation
        !           830: 
        !           831: @noindent
        !           832: and in the Info file
        !           833: 
        !           834: @quotation
        !           835: @example
        !           836: This is
        !           837: a foo.
        !           838: @end example
        !           839: @end quotation
        !           840: 
        !           841: @subsection @@example
        !           842: 
        !           843: @code{@@example} is used to indicate an example that is not part of the
        !           844: running text.  In the printed manual, this is done by switching to
        !           845: a fixed width font, turning off filling, and making extra spaces
        !           846: and blank lines significant.  In the Info file, an analogous result
        !           847: is obtained by indenting each line with five extra spaces.
        !           848: 
        !           849: @code{@@example} should appear on a line by itself; this line will
        !           850: disappear from the output.  Mark the end of the example with a line
        !           851: containing @code{@@end example}, which will likewise disappear.
        !           852: Example:
        !           853: 
        !           854: @example
        !           855: @@example
        !           856: mv foo bar
        !           857: @@end example
        !           858: @end example
        !           859: 
        !           860: @noindent
        !           861: produces
        !           862: 
        !           863: @quotation
        !           864: @example
        !           865: mv foo bar
        !           866: @end example
        !           867: @end quotation
        !           868: 
        !           869: Don't use tabs in lines of an example!
        !           870: 
        !           871: @subsection @@display
        !           872: 
        !           873: @code{@@display} is just like @code{@@example} except that, in the
        !           874: printed manual, @code{@@display} does not select the fixed-width font.
        !           875: In fact, it does not specify the font at all, so that the text appears
        !           876: in the same font it would have appeared in without the @code{@@display}.@refill
        !           877: 
        !           878: @subsection @@itemize
        !           879: 
        !           880: @code{@@itemize} is used to produce sequences of indented paragraphs, with
        !           881: a mark inside the left margin at the beginning of each.  The rest of the
        !           882: line that starts with @code{@@itemize} should contain the character or
        !           883: texinfo commands to generate such a mark.  It should ultimately result in a
        !           884: single character, or the indentation will come out wrong.  You may use
        !           885: the texinfo commands that are normally followed by @samp{@{@}}; in fact, you 
        !           886: may omit the @samp{@{@}} after the command if you use just one command
        !           887: and nothing else.
        !           888: 
        !           889: The text of the indented paragraphs themselves come after the @code{@@itemize},
        !           890: up to another line that says @code{@@end @@itemize}.
        !           891: 
        !           892: Before each paragraph for which a mark in the margin is desired, place a
        !           893: line that says just @code{@@item}.
        !           894: 
        !           895: Here is an example of the use of @code{@@itemize}, followed by the output
        !           896: it produces.  Note that @code{@@bullet} produces a @code{*} in texinfo and
        !           897: a round dot in @TeX{}.
        !           898: 
        !           899: @example
        !           900: @@itemize @@bullet
        !           901: @@item
        !           902: Some text for foo.
        !           903: @@item
        !           904: Some text
        !           905: for bar.
        !           906: @@end itemize
        !           907: @end example
        !           908: 
        !           909: @noindent
        !           910: produces
        !           911: 
        !           912: @quotation
        !           913: @itemize @bullet
        !           914: @item
        !           915: Some text for foo.
        !           916: @item
        !           917: Some text
        !           918: for bar.
        !           919: @end itemize
        !           920: @end quotation
        !           921: 
        !           922: Texinfo indents the lines of the itemization by five additional columns,
        !           923: but it does not fill them.  If @code{@@refill} is used, the paragraph is
        !           924: filled to the narrowed width.
        !           925: 
        !           926: @subsection @@enumerate
        !           927: 
        !           928: @code{@@enumerate} is like @code{@@itemize} except that the marks in the
        !           929: left margin contain successive integers starting with 1.  Do not put any
        !           930: argument on the same line as @code{@@enumerate}.@refill
        !           931: 
        !           932: @example
        !           933: @@enumerate
        !           934: @@item
        !           935: Some text for foo.
        !           936: @@item
        !           937: Some text
        !           938: for bar.
        !           939: @@end enumerate
        !           940: @end example
        !           941: 
        !           942: @noindent
        !           943: produces
        !           944: 
        !           945: @quotation
        !           946: @enumerate
        !           947: @item
        !           948: Some text for foo.
        !           949: @item
        !           950: Some text
        !           951: for bar.
        !           952: @end enumerate
        !           953: @end quotation
        !           954: 
        !           955: @subsection @@table
        !           956: 
        !           957: @code{@@table} is similar to @code{@@itemize}, but allows you to specify a
        !           958: name or heading line for each item.
        !           959: 
        !           960: You must follow each use of @code{@@item} inside of @code{@@table} with
        !           961: text to serve as the heading line for that item.
        !           962: 
        !           963: Also, @code{@@table} itself must be followed by an argument that is a
        !           964: texinfo command such as @code{@@code}, @code{@@var}, @code{@@kbd} or
        !           965: @code{@@asis}.  This command will be applied to the text of each item.
        !           966: @code{@@asis} is a command that does nothing; in that case, each item will
        !           967: come out exactly as it specifies.  (Various other command names might work
        !           968: in this context.  Only commands that normally take arguments in braces may
        !           969: be used, but here you use the command name without an argument.
        !           970: @code{@@item} supplies the arguments.)@refill
        !           971: 
        !           972: @example
        !           973: @@table @@samp
        !           974: @@item foo
        !           975: This is the text for
        !           976: @@samp@{foo@}.
        !           977: @@item bar
        !           978: Text for @@samp@{bar@}.
        !           979: @@end table
        !           980: @end example
        !           981: 
        !           982: @noindent
        !           983: produces
        !           984: 
        !           985: @quotation
        !           986: @table @samp
        !           987: @item foo
        !           988: This is the text for
        !           989: @samp{foo}.
        !           990: @item bar
        !           991: Text for @samp{bar}.
        !           992: @end table
        !           993: @end quotation
        !           994: 
        !           995: @subsection @@itemx
        !           996: 
        !           997: @code{@@itemx} is used inside a @code{@@table} when you have
        !           998: two or more named items for the same block of text.  Use @code{@@itemx}
        !           999: for all but the first of the items.  It works exactly like @code{@@item}
        !          1000: except that it does not generate extra vertical space above the item text.
        !          1001: Example:@refill
        !          1002: 
        !          1003: @example
        !          1004: @@table @@code
        !          1005: @@item upcase
        !          1006: @@itemx downcase
        !          1007: These two functions accept a character or a string as argument,
        !          1008: and return the corresponding upper case (lower case) character
        !          1009: or string.
        !          1010: @@end table
        !          1011: @end example
        !          1012: 
        !          1013: @noindent
        !          1014: produces
        !          1015: 
        !          1016: @quotation
        !          1017: @table @code
        !          1018: @item upcase
        !          1019: @itemx downcase
        !          1020: These two functions accept a character or a string as argument,
        !          1021: and return the corresponding upper case (lower case) character
        !          1022: or string.
        !          1023: @end table
        !          1024: @end quotation
        !          1025: 
        !          1026: @subsection @@noindent
        !          1027: 
        !          1028: @code{@@noindent} is not a kind of insertion, but it is normally used
        !          1029: following an insertion.
        !          1030: 
        !          1031: If you have text following an @code{@@example} or other similar ``special
        !          1032: paragraph'' that reads as a continuation of the text before the
        !          1033: @code{@@example}, it is good to prevent this text from being indented as a
        !          1034: new paragraph.  To accomplish this, put @code{@@noindent} on a line by
        !          1035: itself before the start of the text that should not be indented.
        !          1036: 
        !          1037: To adjust the number of blank lines properly in the Info file output,
        !          1038: remember that the line containing @code{@@noindent} does not generate a
        !          1039: blank line, and neither does the @code{@@end example} line.
        !          1040: 
        !          1041: In the texinfo source file for this documentation, each of the lines that
        !          1042: says `produces' is preceded by a line containing @code{@@noindent}.
        !          1043: 
        !          1044: @section Other Paragraph-Separating Commands
        !          1045: 
        !          1046: @subsection @@setfilename
        !          1047: 
        !          1048: @code{@@setfilename @var{file}} informs texinfo that the Info file being
        !          1049: produced is named @var{file}.  This information is entered in every node
        !          1050: header.  It also tells texinfo the name for the output file.
        !          1051: 
        !          1052: @subsection @@comment
        !          1053: 
        !          1054: A line starting with @code{@@comment} or @code{@@c} is ignored in both
        !          1055: printed and Info output.
        !          1056: 
        !          1057: @subsection @@ignore
        !          1058: 
        !          1059: A line saying @code{@@ignore} causes everything up to the following
        !          1060: @code{@@end ignore} to be ignored in both printed and Info output.
        !          1061: 
        !          1062: @subsection @@br
        !          1063: 
        !          1064: In a printed manual, a line containing @code{@@br} forces a paragraph
        !          1065: break; in the Info file output, it does nothing (not even a blank line
        !          1066: results from it).
        !          1067: 
        !          1068: @subsection @@sp
        !          1069: 
        !          1070: A line containing @code{@@sp @var{n}} generates @var{n} blank lines of space in either the
        !          1071: printed manual or the Info file.
        !          1072: 
        !          1073: @subsection @@page
        !          1074: 
        !          1075: A line containing @code{@@page} starts a new page in a printed manual.  The
        !          1076: line has no effect on Info files since they are not paginated.
        !          1077: 
        !          1078: @subsection @@group
        !          1079: 
        !          1080: A line containing @code{@@group} begins an unsplittable vertical group,
        !          1081: which must appear entirely on one page.  The group is terminated by a line
        !          1082: containing @code{@@end group}.  These two lines produce no output of their
        !          1083: own, and in the Info file output they have no effect at all.
        !          1084: 
        !          1085: @subsection @@need
        !          1086: 
        !          1087: A line containing @code{@@need @var{n}} starts a new page in a printed
        !          1088: manual if fewer than @var{n} mils (thousandths of an inch) remain on the
        !          1089: current page.  The line has no effect on Info files since they are not
        !          1090: paginated.@refill
        !          1091: 
        !          1092: @subsection @@center
        !          1093: 
        !          1094: A line containing @code{@@center @var{text}} produces a line of output containing @var{text},
        !          1095: centered between the margins.
        !          1096: 
        !          1097: @subsection Conditionals
        !          1098: 
        !          1099: You may not always be able to use the same text for @TeX{} and texinfo.
        !          1100: Use the conditional commands to specify which text is for @TeX{} and which
        !          1101: is for texinfo.
        !          1102: 
        !          1103: @code{@@ifinfo} begins text that should be ignored by @TeX{}.  It should
        !          1104: appear on a line by itself.  End the texinfo-only text with a line
        !          1105: containing @code{@@end ifinfo}.@refill
        !          1106: 
        !          1107: Likewise, @code{@@iftex} and @code{@@end iftex} lines delimit code
        !          1108: that should be ignored by texinfo.@refill
        !          1109: 
        !          1110: @section Generating Indices
        !          1111: 
        !          1112: Texinfo files can generate indices automatically.  Each index covers
        !          1113: a certain kind of entry (functions, or variables, or concepts, etc.)@:
        !          1114: and lists all of those entries in alphabetical order, together with
        !          1115: information on how to find the discussion of each entry.  In a printed
        !          1116: manual, this information consists of page numbers.  In an Info file,
        !          1117: it consists of a menu item leading to the node in which the entry
        !          1118: is discussed.
        !          1119: 
        !          1120: 
        !          1121: Normally, six indices are provided for:
        !          1122: 
        !          1123: @itemize @bullet
        !          1124: @item
        !          1125: A @dfn{program index} listing names of programs and leading to the places
        !          1126: where those programs are documented.
        !          1127: 
        !          1128: @item
        !          1129: A @dfn{function index} listing functions (such as, entry points of
        !          1130: libraries).
        !          1131: 
        !          1132: @item
        !          1133: A @dfn{variables index} listing variables (such as, external variables of
        !          1134: libraries).
        !          1135: 
        !          1136: @item
        !          1137: A @dfn{data type index} listing data types (such as, structures defined in
        !          1138: header files).
        !          1139: 
        !          1140: @item
        !          1141: A @dfn{keystroke index} listing keyboard commands.
        !          1142: 
        !          1143: @item
        !          1144: A @dfn{concept index} listing concepts that are discussed.
        !          1145: @end itemize
        !          1146: 
        !          1147: @noindent
        !          1148: Not every manual needs all of these.  Two or more indices can be combined
        !          1149: into one using the @code{@@synindex} command as described below.
        !          1150: 
        !          1151: @subsection Defining the Entries of an Index
        !          1152: 
        !          1153: The data to make an index comes from many individual commands scattered
        !          1154: throughout the source file.  Each command says to add one entry to a
        !          1155: particular index, giving the current page number or node name as the
        !          1156: reference.
        !          1157: 
        !          1158: @table @code
        !          1159: @item @@cindex @var{concept}
        !          1160: Make an entry in the concept index for @var{concept}, referring to the
        !          1161: current page or node.
        !          1162: @item @@findex @var{function}
        !          1163: Make an entry in the function index for @var{function}, referring to the
        !          1164: current page or node.
        !          1165: @item @@vindex @var{variable}
        !          1166: Make an entry in the variable index for @var{variable}, referring to the
        !          1167: current page or node.
        !          1168: @item @@pindex @var{program}
        !          1169: Make an entry in the program index for @var{program}, referring to the
        !          1170: current page or node.
        !          1171: @item @@kindex @var{key}
        !          1172: Make an entry in the key index for @var{key}, referring to the
        !          1173: current page or node.
        !          1174: @item @@tindex @var{data type}
        !          1175: Make an entry in the data type index for @var{data type}, referring to the
        !          1176: current page or node.
        !          1177: @end table
        !          1178: 
        !          1179: If the same name is indexed on several pages, all the pages are listed
        !          1180: in the printed manual's index.  However, only the first node referenced
        !          1181: will appear in the index of an Info file.
        !          1182: 
        !          1183: You are not actually required to use these indices for their canonical
        !          1184: purposes.  For example, you might wish to index some C preprocessor macros.
        !          1185: You could put them in the function index along with actual functions, just
        !          1186: by writing @code{@@findex} commands for them; then, when you print the
        !          1187: ``function index'', you could give it the title `Function and Macro Index'
        !          1188: and all will be consistent for the reader.  Or you could put the macros in
        !          1189: with the data types by writing @code{@@tindex} commands for them, and give
        !          1190: that index a suitable title so the reader will understand.
        !          1191: 
        !          1192: @subsection Combining Indices
        !          1193: 
        !          1194: Sometimes you will want to combine two disparate indices such as functions
        !          1195: and variables, perhaps because you have few enough of one of them that
        !          1196: a separate index for them would look silly.
        !          1197: 
        !          1198: You could put variables into the function index by writing @code{@@findex}
        !          1199: commands for them instead of @code{@@vindex} commands, and produce a
        !          1200: consistent manual by printing the function index with the title `Function
        !          1201: and Variable Index' and not printing the ``variable index'' at all; but this
        !          1202: is not a robust procedure.  It works only as long as your document is never
        !          1203: included in part of or together with another document that is designed to
        !          1204: have a separate variable index; if you did that, the variables from your
        !          1205: document and those from the other would not end up together.
        !          1206: 
        !          1207: What you should do instead when you want functions and variables in one
        !          1208: index is to index the variables with @code{@@vindex} as they should be,
        !          1209: but in the overall file for the document use @code{@@synindex} to redirect
        !          1210: these @code{@@vindex} commands to the function index.  @code{@@synindex} takes two
        !          1211: arguments: the name of an index to redirect, and the name of an index to
        !          1212: redirect it to.  For this purpose, the indices are given two-letter names:
        !          1213: 
        !          1214: @table @samp
        !          1215: @item cp
        !          1216: the concept index.
        !          1217: @item vr
        !          1218: the variable index.
        !          1219: @item fn
        !          1220: the function index.
        !          1221: @item ky
        !          1222: the key index.
        !          1223: @item pg
        !          1224: the program index.
        !          1225: @item tp
        !          1226: the data type index.
        !          1227: @end table
        !          1228: 
        !          1229: Thus, @code{@@synindex vr fn} at the front of an overall manual file
        !          1230: will cause all entries designated for the variable index to go to
        !          1231: the function index as well.  But the included files of this manual
        !          1232: could be used in some other manual, that does not do @code{@@synindex},
        !          1233: and generate a separate variable index.
        !          1234: 
        !          1235: If the texinfo file containing @code{@@synindex} is also to be made into
        !          1236: an Info file itself, you should use @code{@@iftex} around the @code{@@synindex}
        !          1237: commands.
        !          1238: 
        !          1239: @subsection Printing an Index
        !          1240: 
        !          1241: To print an index means to include it as part of a manual or Info file.
        !          1242: This does not happen automatically just because you use @code{@@cindex} or
        !          1243: other index-entry generating commands in the input; those just cause the
        !          1244: raw data for the index to be accumulated.  To print an index, you must
        !          1245: include special texinfo commands at the place in the document where you
        !          1246: want the index to appear.  Also, for the case of the printed manual, you
        !          1247: must run a special program to sort the raw data to produce a sorted index
        !          1248: file, which is what will actually be used to print the index.@refill
        !          1249: 
        !          1250: The texinfo command you need is @code{@@printindex}.  It takes the
        !          1251: two-letter index name (see table above) as an argument without braces, and
        !          1252: reads the corresponding sorted index file and formats it appropriately into
        !          1253: an index.@refill
        !          1254: 
        !          1255: @code{@@printindex} does not generate a chapter heading for the index.
        !          1256: You should precede it with a suitable section or chapter command (usually
        !          1257: @code{@@unnumbered}) to supply the chapter heading and put the index into
        !          1258: the table of contents.  And before that, you probably need a @code{@@node}
        !          1259: command.  For example,@refill
        !          1260: 
        !          1261: @example
        !          1262: @@node Variables Index, Concept Index, Function Index, Top
        !          1263: @@unnumbered Variable Index
        !          1264: 
        !          1265: @@printindex vr
        !          1266: 
        !          1267: @@node Concept index,, Variables Index, Top
        !          1268: @@unnumbered Concept Index
        !          1269: 
        !          1270: @@printindex cp
        !          1271: @end example
        !          1272: 
        !          1273: @subsection Sorting Indices
        !          1274: 
        !          1275: In @TeX{}, @code{@@printindex} needs a sorted index file to work from.
        !          1276: @TeX{} does not know how to do sorting; this is one of the main
        !          1277: deficiencies of @TeX{}.  You must invoke the program @code{texindex} to do
        !          1278: so, giving it the names of the raw index files to be sorted as arguments.
        !          1279: You do not have to run @code{texindex} on all of them; only the ones you
        !          1280: are going to print.
        !          1281: 
        !          1282: @TeX{} outputs raw index files under names that obey a standard convention.
        !          1283: These names are the name of your main input file to @TeX{}, with everything
        !          1284: after the first period thrown away, and the two letter names of indices
        !          1285: added at the end.  For example, the raw index output files for the input
        !          1286: file @file{foo.texinfo} would be @file{foo.cp}, @file{foo.vr},
        !          1287: @file{foo.fn}, @file{foo.tp}, @file{foo.pg} and @file{foo.ky}.  Those are
        !          1288: exactly the arguments to give to @code{texindex}.@refill
        !          1289: 
        !          1290: For each file specified, @code{texindex} generates a sorted index file whose
        !          1291: name is made by appending @samp{s} to the input file name.  The
        !          1292: @code{@@printindex} command knows to look for a file of that name.
        !          1293: @code{texindex} does not alter the raw index output file.@refill
        !          1294: 
        !          1295: You need not run @code{texindex} after each @TeX{} run.  If you don't, the
        !          1296: next @TeX{} run will use whatever sorted index files happen to exist from
        !          1297: the previous use of @code{texindex}.  This is usually ok while you are
        !          1298: debugging.
        !          1299: 
        !          1300: @node make-info, manual ,commands, top
        !          1301: @section Converting Texinfo Files into Info Files
        !          1302: 
        !          1303: Just visit a texinfo file and invoke
        !          1304: 
        !          1305: @example
        !          1306: @kbd{Meta-x texinfo-format-buffer}
        !          1307: @end example
        !          1308: 
        !          1309: @noindent
        !          1310: to convert it to an Info file.  A new buffer is created and the Info file
        !          1311: text is generated there.  @kbd{C-x C-s} will save it under the name specified
        !          1312: in the @code{@@setfilename} command.
        !          1313: 
        !          1314: If the file is large (more than 30 nodes) it is desirable to make a
        !          1315: @dfn{tag table} for it.  To do this, load the @code{info} library
        !          1316: into Emacs with @kbd{M-x load @key{RET} info @key{RET}} and then
        !          1317: do @kbd{M-x Info-tagify}.@refill
        !          1318: 
        !          1319: To check your node structure for errors, load Info and then do
        !          1320: @kbd{M-x Info-validate}.
        !          1321: 
        !          1322: @node manual,, make-info, top
        !          1323: @section Generating a Real Manual
        !          1324: 
        !          1325: Most of the time a single printed manual will be made from several texinfo
        !          1326: source files, each of which is made into a single Info file.  Also, the
        !          1327: real manual should have a table of contents.  Several special commands are
        !          1328: used for these purposes.
        !          1329: 
        !          1330: Every texinfo file that is to be the top-level input to @TeX{} must begin
        !          1331: with a line that looks like
        !          1332: 
        !          1333: @example
        !          1334: \input texinfo   @@c -*-texinfo-*-
        !          1335: @end example
        !          1336: 
        !          1337: @noindent
        !          1338: This serves two functions.
        !          1339: 
        !          1340: @enumerate
        !          1341: @item
        !          1342: When the file is processed by @TeX{}, it loads the macros needed for
        !          1343: processing a texinfo file.
        !          1344: @item
        !          1345: When the file is edited in Emacs, it causes Texinfo Mode to be used.
        !          1346: @end enumerate
        !          1347: 
        !          1348: Every such texinfo file must end with a line saying
        !          1349: 
        !          1350: @example
        !          1351: @@bye
        !          1352: @end example
        !          1353: 
        !          1354: which terminates @TeX{} processing and forces out unfinished pages.
        !          1355: 
        !          1356: You might also want to include a line saying
        !          1357: 
        !          1358: @example
        !          1359: @@setchapternewpage odd
        !          1360: @end example
        !          1361: 
        !          1362: @noindent
        !          1363: to cause each chapter to start on a fresh odd-numbered page.
        !          1364: 
        !          1365: Here is an example of a texinfo file used to generate a manual from two
        !          1366: other texinfo files, @samp{foo.texinfo} and @samp{bar.texinfo}, each of
        !          1367: which makes a separate Info file.  The commands used in it are explained
        !          1368: in the rest of this section.@refill
        !          1369: 
        !          1370: @example
        !          1371: \input texinfo @@c -*-texinfo-*-
        !          1372: @@settitle This Manual
        !          1373: 
        !          1374: @@c put entries intended for the data type index
        !          1375: @@c into the variable index instead.
        !          1376: @@synindex tp vr
        !          1377: @@setchapternewpage odd
        !          1378: 
        !          1379: @@titlepage
        !          1380: @@sp 10
        !          1381: @@center @@titlefont@{This Manual@}
        !          1382: @@sp 3
        !          1383: @@center by
        !          1384: @@sp 3
        !          1385: @@center @@titlefont@{Me@}
        !          1386: @@end titlepage
        !          1387: 
        !          1388: @@c Include the files with the actual text
        !          1389: @@include foo.texinfo
        !          1390: @@include bar.texinfo
        !          1391: 
        !          1392: @@c Print the indices
        !          1393: @@unnumbered Function Index
        !          1394: @@printindex fn
        !          1395: @@unnumbered Variable and Data Type Index
        !          1396: @@printindex vr
        !          1397: @@unnumbered Program Index
        !          1398: @@printindex pg
        !          1399: @@unnumbered Concept Index
        !          1400: @@printindex cp
        !          1401: 
        !          1402: @@c Print the tables of contents
        !          1403: @@summarycontents
        !          1404: @@contents
        !          1405: 
        !          1406: @@c That's all
        !          1407: @@bye
        !          1408: @end example
        !          1409: 
        !          1410: @subsection Title Page
        !          1411: 
        !          1412: Start the material for the title page with @samp{@@titlepage} and follow it
        !          1413: with @samp{@@end titlepage}.  Both of these commands should stand alone on
        !          1414: a line.  They cause the title material to appear only in the printed
        !          1415: manual, not in an info file.  Also, the @samp{@@end titlepage} command
        !          1416: starts a new page and turns on page numbering (generation of headings).
        !          1417: 
        !          1418: The within-paragraph command @samp{@@titlefont} can be used to select a
        !          1419: large font suitable for the title itself.
        !          1420: 
        !          1421: @subsection Headings
        !          1422: 
        !          1423: Texinfo prints the manual title on every other page as a heading, and the
        !          1424: current chapter title on the remaining pages.  It knows the chapter title
        !          1425: automatically, but you must tell it the manual title with @code{@@settitle}:
        !          1426: 
        !          1427: @example
        !          1428: @@settitle @var{title}
        !          1429: @end example
        !          1430: 
        !          1431: @noindent
        !          1432: on a line by itself causes @var{title} to be used for the headings.
        !          1433: 
        !          1434: The @code{@@settitle} command should precede everything that generates
        !          1435: actual output.
        !          1436: 
        !          1437: Normally, headings start appearing after the @samp{@@end titlepage} command.
        !          1438: (They are not wanted on the title page.)  However, you can turn headings on
        !          1439: and off explicitly with the @samp{@@headings} command:
        !          1440: 
        !          1441: @example
        !          1442: @@headings on
        !          1443: @end example
        !          1444: 
        !          1445: @noindent
        !          1446: to start output of headings (starting with the page containing the command)
        !          1447: or
        !          1448: 
        !          1449: @example
        !          1450: @@headings off
        !          1451: @end example
        !          1452: 
        !          1453: @noindent
        !          1454: to stop output of headings (starting also with the current page).
        !          1455: 
        !          1456: @subsection @@include
        !          1457: 
        !          1458: A line of the form @code{@@include @var{filename}} is ignored when generating an
        !          1459: Info file, but in a printed manual it causes the contents of the file
        !          1460: @var{filename} to be processed at that point.
        !          1461: 
        !          1462: Normally, the file named @var{filename} is made into a separate Info file.
        !          1463: The file containing the @code{@@include} may refer to the other Info file
        !          1464: with Info cross-references or menus, since those fill the function of
        !          1465: inclusion for the Info data base.
        !          1466: 
        !          1467: Another technique is to have a special file, used only for making a
        !          1468: comprehensive manual, containing nothing but the beginning, the end, and a
        !          1469: bunch of @code{@@include} commands.
        !          1470: 
        !          1471: A file that is intended to be processed with @code{@@include} should not
        !          1472: start with @samp{\input texinfo}, as that has already been done by the
        !          1473: outer file, and the character @samp{\} has already been redefined to
        !          1474: generate a backslash in the output.
        !          1475: 
        !          1476: A file that is intended to be processed with @code{@@include} should not
        !          1477: end with @code{@@bye}, since that would terminate @TeX{} processing immediately.
        !          1478: 
        !          1479: @subsection Table of Contents
        !          1480: 
        !          1481: The commands @code{@@chapter}, @code{@@section}, etc., supply the
        !          1482: information to make up a table of contents, but they do not cause an actual
        !          1483: table to be output.  To do this, you must use the commands
        !          1484: @code{@@contents} and @code{@@summarycontents}.@refill
        !          1485: 
        !          1486: @code{@@contents}, which should be used on a line by itself, outputs (into
        !          1487: a printed manual) a complete table of contents, based on the
        !          1488: @code{@@chapter} and other sectioning commands already seen.@refill
        !          1489: 
        !          1490: @code{@@summarycontents} generates a summary table of contents that lists
        !          1491: only the chapters (and appendixes and unnumbered chapters); sections,
        !          1492: subsections and subsubsections are omitted.
        !          1493: 
        !          1494: You can use either one of these commands, or both.  Each one automatically
        !          1495: generates a chapter-like heading at the top of the page.  Tables of
        !          1496: contents should be generated at the very end of the manual, just before the
        !          1497: @code{@@bye} command; they should follow any indices that are output, so
        !          1498: that the indices will appear in the contents.
        !          1499: 
        !          1500: @example
        !          1501: @var{indices}@dots{}
        !          1502: @@summarycontents
        !          1503: @@contents
        !          1504: @@bye
        !          1505: @end example
        !          1506: 
        !          1507: The commands @code{@@contents} and @code{@@summarycontents} are ignored when an
        !          1508: Info file is being generated.
        !          1509: 
        !          1510: @contents
        !          1511: @bye

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.