Return to texinfo CVS log

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

Annotation of 43BSD/contrib/emacs/info/texinfo, revision 1.1

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

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