Return to texinfo.texinfo CVS log

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

Annotation of 43BSDReno/contrib/emacs-18.55/man/texinfo.texinfo, revision 1.1

1.1     ! root        1: \input texinfo    @c -*-texinfo-*-
        !             2: @comment %**start of header (This is for running Texinfo on a region.)
        !             3: @setfilename ../info/texinfo
        !             4: @settitle Texinfo 1.1
        !             5: @comment %**end of header (This is for running Texinfo on a region.)
        !             6: 
        !             7: @iftex
        !             8: @finalout
        !             9: @end iftex
        !            10: 
        !            11: @ifinfo
        !            12: This file documents Texinfo, a documentation system that uses a single
        !            13: source file to produce both on-line help and a printed manual.  
        !            14: 
        !            15: This is edition 1.1 of the Texinfo documentation, and is for the Texinfo
        !            16: that is distributed as part of Version 18 of GNU Emacs.
        !            17: 
        !            18: Copyright (C) 1988 Free Software Foundation, Inc.
        !            19: 
        !            20: Permission is granted to make and distribute verbatim copies of
        !            21: this manual provided the copyright notice and this permission notice
        !            22: are preserved on all copies.
        !            23: 
        !            24: @ignore
        !            25: Permission is granted to process this file through TeX and print the
        !            26: results, provided the printed document carries copying permission
        !            27: notice identical to this one except for the removal of this paragraph
        !            28: (this paragraph not being relevant to the printed manual).
        !            29: 
        !            30: @end ignore
        !            31: Permission is granted to copy and distribute modified versions of this
        !            32: manual under the conditions for verbatim copying, provided that the entire
        !            33: resulting derived work is distributed under the terms of a permission
        !            34: notice identical to this one.
        !            35: 
        !            36: Permission is granted to copy and distribute translations of this manual
        !            37: into another language, under the above conditions for modified versions,
        !            38: except that this permission notice may be stated in a translation approved
        !            39: by the Foundation.
        !            40: @end ifinfo
        !            41: 
        !            42: @setchapternewpage odd
        !            43: @titlepage
        !            44: @sp 11
        !            45: @center @titlefont{Texinfo}
        !            46: @sp 2
        !            47: @center The GNU Documentation Format
        !            48: @sp 2
        !            49: @center by Richard M. Stallman and Robert J. Chassell
        !            50: @sp 2
        !            51: @center Edition 1.1
        !            52: @sp 2
        !            53: @center May 1988
        !            54: 
        !            55: @comment   Include the Distribution inside the titlepage environment so
        !            56: @c that headings are turned off. 
        !            57: 
        !            58: @page
        !            59: @vskip 0pt plus 1filll
        !            60: Copyright @copyright{} 1988 Free Software Foundation, Inc.
        !            61: 
        !            62: @sp 2
        !            63: This is version 1.1 of the Texinfo documentation, and is for @*
        !            64: the Texinfo that is distributed as part of Version 18 of GNU Emacs.
        !            65: @sp 2
        !            66: 
        !            67: Published by the Free Software Foundation @*
        !            68: 675 Massachusetts Avenue, @*
        !            69: Cambridge, MA 02139 USA @*
        !            70: Printed copies are available for $10 each.
        !            71: 
        !            72: Permission is granted to make and distribute verbatim copies of
        !            73: this manual provided the copyright notice and this permission notice
        !            74: are preserved on all copies.
        !            75: 
        !            76: Permission is granted to copy and distribute modified versions of this
        !            77: manual under the conditions for verbatim copying, provided that the entire
        !            78: resulting derived work is distributed under the terms of a permission
        !            79: notice identical to this one.
        !            80: 
        !            81: Permission is granted to copy and distribute translations of this manual
        !            82: into another language, under the above conditions for modified versions,
        !            83: except that this permission notice may be stated in a translation approved
        !            84: by the Foundation.
        !            85: 
        !            86: @end titlepage
        !            87: 
        !            88: 
        !            89: @node Top, License, (dir), (dir)
        !            90: 
        !            91: @menu
        !            92: * License::                    Licensing information.
        !            93: * Overview::                   What is Texinfo?
        !            94: * Texinfo Mode::               Special features in GNU Emacs.
        !            95: * Beginning a File::           What to put at the beginning of a Texinfo file.
        !            96: * Ending a File::              What to put at the end of a Texinfo file.
        !            97: * Structuring::                        How to make nodes and chapters.
        !            98: * Quotations and Examples::    How to insert quotations and examples.
        !            99: * Lists and Tables::           How to make lists and tables.
        !           100: * Cross References::           How to make cross references.
        !           101: * Formatting Paragraphs::      How to format paragraphs.
        !           102: * Marking Text::               How to mark code, definitions, variables etc.
        !           103: * Conditionals::               Putting text in only Info or the printed work.
        !           104: * Printing Hardcopy::          How to print a hardcopy of the manual.
        !           105: * Creating an Info File::      How to create an on-line Info file.
        !           106: * Catching Mistakes::          How to find problems.
        !           107: 
        !           108: Indices, nodes containing large menus
        !           109: 
        !           110: * Command Index::              An item for each @@-command.
        !           111: * Concept Index::              An item for each concept.
        !           112: 
        !           113: A detailed node listing
        !           114: 
        !           115: Overview
        !           116: * Info File::                  Characteristics of the Info file.
        !           117: * Printed Manual::             Characteristics of the printed manual.
        !           118: * Conventions::                        General syntactic conventions.
        !           119: * Short Sample::               A short sample Texinfo file.
        !           120: 
        !           121: Using Texinfo Mode
        !           122: * Info on a Region::           Formatting a region for Info.
        !           123: * Showing the Structure::      Showing the structure of a file.
        !           124: * Inserting::                  Inserting frequently used commands.
        !           125: 
        !           126: Beginning a Texinfo File.
        !           127: * First Line::                 The first line of a Texinfo file.
        !           128: * Start-of-Header::            Identifying the start of the header.
        !           129: * Setfilename::                        Specifying the name of the Info file.
        !           130: * Settitle::                   Specifying the title used by the headings.
        !           131: * Setchapternewpage::          Starting chapters on odd numbered pages.
        !           132: * Titlepage::                  The title and copyright page.
        !           133: * Center::                     Centering a line.
        !           134: * Copyright & Printed Permissions:: Ensuring free distributability.
        !           135: * Top Node::                   The master menu.  
        !           136: * License and Distribution::   Your are free to copy and distribute this.
        !           137: 
        !           138: Ending a Texinfo File
        !           139: * Contents::                   Generating tables of contents.
        !           140: * Indices::                    Generating indices.
        !           141: * Index Entries::              Defining the entries of an index.
        !           142: * Combining Indices::          Putting two or more indices together.
        !           143: * Printing Indices & Menus::   Printing an index and generating menus.
        !           144: 
        !           145: Node and Chapter Structuring
        !           146: * Chapter::                    Creating a chapter.
        !           147: * Unnumbered and Appendix::    Chapter-like parts.
        !           148: * Section::                    Creating sections
        !           149: * Subsection::                 Creating subsections.
        !           150: * Subsubsection::              Creating subsubsections.
        !           151: 
        !           152: * Node::                       Creating nodes.
        !           153: * Menu::                       Creating menus.
        !           154: 
        !           155: 
        !           156: Making quotations and examples
        !           157: * Quotation::                  Inserting long quotations.
        !           158: * Example::                    Inserting examples of code and the like.
        !           159: * Display::                    Inserting displayed text.
        !           160: 
        !           161: Making lists and two column tables
        !           162: * Itemize::                    Creating itemized lists.
        !           163: * Enumerate::                  Creating enumerated lists.
        !           164: * Table::                      Creating two column tables.
        !           165: * Itemx::                      Putting an extra item in the 
        !           166:                                first column of a table.
        !           167: 
        !           168: Making Cross References
        !           169: * Xref::                       Making a regular cross reference.
        !           170: * Pxref::                      Making a parenthetical cross reference.
        !           171: * Inforef::                    Making a cross reference to an Info file.
        !           172: 
        !           173: 
        !           174: Formatting Paragraphs
        !           175: * Refilling & Noindent::       Refilling paragraphs 
        !           176:                                and preventing indentation
        !           177: * Refill::                     Using the @code{@@refill} command.
        !           178: * Noindent::                   Using the @code{@@noindent} command.
        !           179: 
        !           180: 
        !           181: Breaks, Blank Lines and Groups
        !           182: * Line Breaks::                        Inserting line breaks in @TeX{}.
        !           183: * Sp::                         Inserting blank lines.
        !           184: * Br::                         Inserting paragraph breaks.
        !           185: * W::                          Preventing line breaks.
        !           186: * Page::                       Starting new pages.
        !           187: * Group::                      Holding text together on one page.
        !           188: * Need::                       Keeping text together.
        !           189: 
        !           190: Marking Text Within a Paragraph
        !           191: * Code::                       A literal example of a piece of a program.
        !           192: * Samp::                       A literal example of a sequence of characters.
        !           193: * File::                       The name of a file.
        !           194: * Kbd::                                The names of keys or else characters you type.
        !           195: * Key::                                The conventional name for a key on a keyboard.
        !           196: * Ctrl::                       Indicates the ASCII control character.
        !           197: * Var::                                A variable.
        !           198: * Dfn::                                The introductory or defining use of a term.
        !           199: * Cite::                       The name of a book.
        !           200: 
        !           201: Inserting Braces, @samp{@@} and Periods
        !           202: * Braces Atsigns Periods::     Inserting braces, @samp{@@} and periods.
        !           203: * Dots Bullets Tex::           Inserting dots, bullets and the @TeX{} logo
        !           204: * Emphasis::                   Emphasizing text.
        !           205: 
        !           206: Emphasizing Text
        !           207: * Emph and Strong::            Emphasizing text.
        !           208: * Fonts::                      Selecting italic, bold or typewriter fonts.
        !           209: 
        !           210: Creating an Info File
        !           211: * Installing an Info File::    Putting the Info file in the 
        !           212:                                @file{info} directory.
        !           213: 
        !           214: Catching Mistakes
        !           215: * Debugging with Info::            Catching errors with info formatting.
        !           216: * Using the Emacs Lisp Debugger::   Using the Emacs Lisp Debugger
        !           217: * Debugging with Tex::             Catching errors with @TeX{} formatting.
        !           218: * Using texinfo-show-structure::    Using @code{texinfo-show-structure}
        !           219:                                    to catch mistakes.
        !           220: * Using Occur::                            Using @code{occur} to catch mistakes.
        !           221: * Running Info-Validate::          Checking for unreferenced nodes.
        !           222: 
        !           223: Finding badly referenced nodes
        !           224: * Info-Validating a Large File::     Running @code{Info-validate} 
        !           225:                                     on a large file.
        !           226: * Splitting::                        Splitting a file manually.
        !           227: 
        !           228: Appendices
        !           229: * Command Syntax::             Details about the syntax.
        !           230: * Include Files::              Making one printed file out of 
        !           231:                                several Info files.
        !           232: * TeX Input::                  Where @TeX{} finds its @samp{\input} file.
        !           233: * Sample Permissions::         You may copy GNU Software.
        !           234: * Ifinfo Permissions::         What to put in the `ifinfo' section.
        !           235: * Titlepage Permissions::      What to put in the `@@titlepage' section.
        !           236: @end menu
        !           237: 
        !           238: @node     License,   Overview,  Top, Top 
        !           239: @comment  node-name, next, previous,  up
        !           240: @unnumbered Licensing Information
        !           241: 
        !           242:   The programs currently being distributed that relate to Texinfo
        !           243: include two portions of GNU Emacs, plus two other separate programs
        !           244: (@code{texindex} and @code{texinfo.tex}).  These programs are
        !           245: @dfn{free}; this means that everyone is free to use them and free to
        !           246: redistribute them on a free basis.  The Texinfo related programs are not
        !           247: in the public domain; they are copyrighted and there are restrictions on
        !           248: their distribution, but these restrictions are designed to permit
        !           249: everything that a good cooperating citizen would want to do.  What is
        !           250: not allowed is to try to prevent others from further sharing any version
        !           251: of these programs that they might get from you.
        !           252: 
        !           253:   Specifically, we want to make sure that you have the right to give
        !           254: away copies of the programs that relate to Texinfo, that you receive
        !           255: source code or else can get it if you want it, that you can change these
        !           256: programs or use pieces of them in new free programs, and that you know
        !           257: you can do these things.
        !           258: 
        !           259:   To make sure that everyone has such rights, we have to forbid you to
        !           260: deprive anyone else of these rights.  For example, if you distribute
        !           261: copies of the Texinfo related programs, you must give the recipients all
        !           262: the rights that you have.  You must make sure that they, too, receive or
        !           263: can get the source code.  And you must tell them their rights.
        !           264: 
        !           265:   Also, for our own protection, we must make certain that everyone finds
        !           266: out that there is no warranty for the programs that relate to Texinfo.
        !           267: If these programs are modified by someone else and passed on, we want
        !           268: their recipients to know that what they have is not what we distributed,
        !           269: so that any problems introduced by others will not reflect on our
        !           270: reputation.
        !           271: 
        !           272:   The precise conditions of the licenses for the programs currently
        !           273: being distributed that relate to Texinfo are found in the General Public
        !           274: Licenses that accompany them.  The programs that are part of GNU Emacs
        !           275: are covered by the GNU Emacs copying terms (@pxref{License, , , emacs,
        !           276: The GNU Emacs Manual}), and other programs are covered by licenses that
        !           277: are contained in their source files.
        !           278: 
        !           279: @node Overview, Texinfo Mode, License, Top
        !           280: @comment  node-name,  next,  previous,  up
        !           281: @chapter Overview of Texinfo
        !           282: @cindex Overview of Texinfo
        !           283: @cindex Texinfo overview
        !           284: 
        !           285: Texinfo is a documentation system that uses a single source file for both
        !           286: on-line help and a printed manual.  This means that instead of writing two
        !           287: different documents, one for the on-line help and the other for the printed
        !           288: manual, only one document needs to be written.  When the system is revised,
        !           289: only one file has to be revised.@refill
        !           290: 
        !           291: Using Texinfo, you can create a document with the normal features of a book
        !           292: such as chapters, sections, cross references and indices.  The chapters and
        !           293: sections of the printed manual can be made to correspond to the nodes of
        !           294: the on-line help.  The cross references and indices can be used in both the
        !           295: on-line help and in the printed document.  Indices are generated
        !           296: semi-automatically.  The @cite{GNU Emacs Manual} is a good example of a
        !           297: Texinfo file.@refill
        !           298: 
        !           299: To make the printed manual, the Texinfo source file is processed by the
        !           300: @TeX{} typesetting program; the resulting DVI file can be typeset and
        !           301: printed as a book.  To make the on-line help, the Texinfo source file is by
        !           302: processed the @kbd{M-x texinfo-format-buffer} command; the resulting Info
        !           303: file is installed in the @file{info} directory.@refill
        !           304: 
        !           305: Since the Texinfo source file is used for a dual task---to create both the
        !           306: on-line help and the printed manual---it must be written in a special
        !           307: format that uses @@-commands (words preceded by an @samp{@@}) to indicate
        !           308: chapters, sections, nodes, examples, index entries and the like.@refill
        !           309: 
        !           310: Before writing a Texinfo source file, you should be familiar with the
        !           311: on-line Info documentation reading program.  (@inforef{Info, info, info},
        !           312: for more information.)  If you are writing a document that will be both
        !           313: on-line and printed, you will need both Info and @TeX{}.
        !           314: 
        !           315: To make an Info file, you use the @kbd{M-x texinfo-format-buffer} command
        !           316: in GNU Emacs.@refill
        !           317: 
        !           318: To make a printed manual, you need to use @TeX{}, a powerful,
        !           319: sophisticated typesetting program written by Donald Knuth.  @TeX{} is
        !           320: freely distributable. It is written in a dialect of Pascal called WEB and
        !           321: can be compiled either in Pascal or (by using a conversion program that
        !           322: comes with the @TeX{} distribution) in C.  (For information about getting
        !           323: @TeX{}, @pxref{TeX Mode, , , emacs, The GNU Emacs Manual})
        !           324: 
        !           325: When @TeX{} processes a Texinfo source file, @TeX{} makes use of a macro
        !           326: definitions file called @file{texinfo.tex} that comes with the GNU Emacs
        !           327: distribution in the @file{emacs/man} sources directory.  (The first line of
        !           328: every Texinfo file has a command that says @code{\input texinfo}; this
        !           329: tells @TeX{} to use the @file{texinfo.tex} file.)@refill
        !           330: 
        !           331: If the @file{texinfo.tex} file has not already been copied to the directory
        !           332: which contains the other @TeX{} macro definition files when Emacs was
        !           333: installed, you will probably want to copy it to that directory.  Usually,
        !           334: this is the @file{/usr/lib/tex/macros} directory.  For more information,
        !           335: @pxref{TeX Input, , @TeX{} Input Initialization}
        !           336: 
        !           337: Documentation for GNU utilities and libraries should be written in Texinfo
        !           338: format.
        !           339: 
        !           340: @menu
        !           341: * Info File::         Characteristics of the Info file.
        !           342: * Printed Manual::    Characteristics of the Printed Manual.
        !           343: * Conventions::       General Syntactic Conventions.
        !           344: * Short Sample::      A short sample Texinfo file.
        !           345: @end menu
        !           346: 
        !           347: @node Info File, Printed Manual, , Overview
        !           348: @comment  node-name,  next,  previous,  up
        !           349: @section Characteristics of the Info file
        !           350: @cindex Characteristics of the Info file
        !           351: @cindex Info file characteristics
        !           352: 
        !           353: A Texinfo file can be transformed into a printed manual and an on-line Info
        !           354: file.
        !           355: 
        !           356: An on-line Info file is a file formatted so that the Info documentation
        !           357: reading program can operate on it.  Info files are divided into pieces
        !           358: called @dfn{nodes}, each of which contains the discussion of one topic.
        !           359: Each node has a name, and contains both text for the user to read and
        !           360: pointers to other nodes, which are identified by their names.  The Info
        !           361: program displays one node at a time, and provides commands with which the
        !           362: user can move to the other nodes to which the current node points.
        !           363: 
        !           364: @ifinfo
        !           365: @inforef{Info, info, info}, for more information about using Info.
        !           366: @end ifinfo
        !           367: 
        !           368: Normally, most of the nodes are arranged in a tree which branches down.
        !           369: Each node may have any number of child nodes that describe subtopics of the
        !           370: node's topic.  The names of these child nodes, if any, are listed in a
        !           371: @dfn{menu} within the parent node; this allows certain Info commands to
        !           372: be used to move to one of the child nodes.  Each child node records the
        !           373: parent node name, as its `Up' pointer.  Thus, if a node were at the logical
        !           374: level of a `chapter', its child nodes would be `sections'; likewise,
        !           375: the child nodes of a section would be subsections.
        !           376: 
        !           377: The root of the tree is the top node of the file, through which users
        !           378: enter the file from the Info directory.  By convention, this node is always
        !           379: called @samp{Top}.  This node normally contains just a brief summary of the
        !           380: file's purpose, and a large menu through which the rest of the file is
        !           381: reached.
        !           382: 
        !           383: Generally you enter the Info file from the top; then you can either traverse
        !           384: the file systematically by going from node to node or you can search large
        !           385: menus that correspond to indices and go directly to the node that has the
        !           386: information you want.
        !           387: 
        !           388: If you want to read through an Info file in sequence, as if it were a
        !           389: printed manual, you can get the whole file with the advanced Info command
        !           390: @kbd{g *}.  (@inforef{Expert, info, info}.)@refill
        !           391: 
        !           392: All the children of any one parent are linked together in a bidirectional
        !           393: chain of `Next' and `Previous' pointers.  This means that all the nodes
        !           394: that are logically parallel to sections within a chapter are all linked
        !           395: together.  Normally the order in this chain is the same as the order of the
        !           396: children in the parent's menu.  The last child has no `Next' pointer, and
        !           397: the first child normally has the parent as its `Previous' pointer (as well
        !           398: as its `Up' pointer, of course).
        !           399: 
        !           400: Structuring the nodes in a tree is a matter of convention, not a
        !           401: requirement.  In fact, the `Up', `Previous' and `Next' pointers of a node
        !           402: can point to any other nodes, and the menu can contain any other nodes.
        !           403: The structure of nodes can be any directed graph.  But it is usually more
        !           404: comprehensible to make it a tree.  Info provides another kind of pointer
        !           405: between nodes, called a reference, that can be sprinkled through the text
        !           406: of a node.  This is usually the best way to represent links that do not fit
        !           407: the tree structure.
        !           408: 
        !           409: Most often the nodes fall into a strict tree structure that corresponds to
        !           410: the structure of chapters and sections in the printed
        !           411: manual.  But there are times when this is not right for the material being
        !           412: discussed.  Therefore, Texinfo uses separate commands to specify the node
        !           413: structure of the Info file and the section structure of the printed manual.
        !           414: Also, Texinfo requires that you specify menus explicitly, rather than
        !           415: generate them automatically based on an assumed tree structure.
        !           416: 
        !           417: @node     Printed Manual, Conventions, Info File, Top
        !           418: @comment  node-name,  next,  previous,  up
        !           419: @section Characteristics of the Printed Manual
        !           420: @cindex Printed manual characteristics
        !           421: @cindex Characteristics, printed manual 
        !           422: 
        !           423: A Texinfo file can be formatted and typeset as a printed manual.  The
        !           424: printed manual will be the same as any other book; it will have a title
        !           425: page, copyright page, table of contents, and preface as you would expect,
        !           426: as well as chapters, numbered or unnumbered sections and subsections, not
        !           427: to mention page headers, cross references and indices.
        !           428: 
        !           429: Texinfo can be used for writing a book without ever having the intention of
        !           430: converting it into on-line help.  Texinfo can be used for writing a novel;
        !           431: and it can even be used to write a memo, although this application is not
        !           432: recommended since electronic mail is so much easier.
        !           433: 
        !           434: Texinfo uses the formatting language called @TeX{} for typesetting.  A file
        !           435: called @file{texinfo.tex} contains information (definitions or
        !           436: @dfn{macros}) that @TeX{} uses when it typesets a Texinfo file.  (The
        !           437: macros tell @TeX{} how to convert the Texinfo @@-commands to @TeX{}
        !           438: commands which @TeX{} can then process to create the typeset document.)
        !           439: @file{texinfo.tex} contains the specifications for printing a document,
        !           440: either with 7 inch by 9.25 inch pages or with 8.5 inch by 11 inch pages.
        !           441: (This is 178 mm by 235 mm or else 216 mm by 280 mm.) Also, by changing the
        !           442: parameters in @file{texinfo.tex} you can easily change the size of the
        !           443: printed document.  In addition, you can readily change the style in which
        !           444: the printed document is formatted; for example, you can change the sizes and
        !           445: fonts used, the amount of indentation for each paragraph, the degree to
        !           446: which words are hyphenated, and the like.  By changing the specifications,
        !           447: you can make a book look dignified, old and serious, or light-hearted,
        !           448: young and cheery.@refill
        !           449: 
        !           450: @TeX{} is very powerful and has a great many features.  Because a Texinfo
        !           451: file must be able to present information both on a character-only terminal
        !           452: in Info form and in a typeset book, the commands that Texinfo supports are
        !           453: necessarily limited.
        !           454: 
        !           455: 
        !           456: @node   Conventions, Short Sample,  Printed Manual, Overview
        !           457: @comment  node-name,  next,  previous,  up
        !           458: @section General Syntactic Conventions
        !           459: @cindex  General syntactic conventions
        !           460: @cindex  Syntactic conventions
        !           461: @cindex  Conventions, syntactic
        !           462: 
        !           463: 
        !           464: Texinfo files contain a strictly limited set of constructs.  The strict
        !           465: limits make it possible for Texinfo files to be understood both by @TeX{}
        !           466: and by the code which converts them into Info files.
        !           467: 
        !           468: All ASCII printing characters except @samp{@@}, @samp{@{} and @samp{@}} can
        !           469: appear in body text in a Texinfo file and stand for themselves.  @samp{@@}
        !           470: is the escape character which introduces commands.  @samp{@{} and @samp{@}}
        !           471: should be used only to surround arguments to certain commands.  @samp{@{}
        !           472: and @samp{@}} appearing anywhere else will be treated by @TeX{} as a
        !           473: grouping but treated by the code that produces an Info file as themselves;
        !           474: this inconsistency is undesirable, so don't let it occur.  To put one of
        !           475: these special characters into the document, put an @samp{@@} character in
        !           476: front of it.  For example, you would insert @samp{@@@@}, @samp{@@@{}, and
        !           477: @samp{@@@}}.@refill
        !           478: 
        !           479: It is customary in @TeX{} to use doubled single-quote characters to begin
        !           480: and end quotations, @samp{``} like these @samp{''}.  This convention should
        !           481: be followed in Texinfo files.  Also, three hyphens in a row, @samp{---},
        !           482: are used for a dash---like this.  In @TeX{}, a single or even a double
        !           483: hyphen produces a dash that is shorter than you want.@refill
        !           484: 
        !           485: @comment Remove for version 19
        !           486: 
        !           487: @TeX{} ignores the line-breaks in the input text, except for blank lines,
        !           488: which separate paragraphs.  Info generally preserves the line breaks that
        !           489: are present in the input file.  Therefore, break the lines in the Texinfo
        !           490: file the way you want them to appear in the output Info file, and let
        !           491: @TeX{} take care of itself.
        !           492: 
        !           493: Since Info does not normally refill paragraphs when it processes them, a
        !           494: line with @@-commands in it will sometimes look bad after Info has run on
        !           495: it.  To cause Info to refill the paragraph after finishing with the other
        !           496: processing, you need to put the command @code{@@refill} at the end of the
        !           497: paragraph. (@xref{Refilling & Noindent, , Refilling paragraphs and
        !           498: Preventing indentation}.)@refill
        !           499: 
        !           500: To prevent a paragraph from being indented in the printed manual, put the
        !           501: command @code{@@noindent} on a line by itself before the start of the text
        !           502: that should not be indented.
        !           503: 
        !           504: If you mark off a region of the Texinfo file with the @code{@@iftex} and
        !           505: @code{@@end iftex} commands so that the region will appear only in the
        !           506: printed copy, you can use @TeX{} commands that cannot be used in the Info
        !           507: file.
        !           508: 
        !           509: In order to be made into a printed manual, a Texinfo file @strong{must}
        !           510: begin with lines that looks like
        !           511: 
        !           512: @example
        !           513: \input texinfo   @@c -*-texinfo-*-
        !           514: @@setfilename @var{info-file-name}
        !           515: @@settitle @var{Name of Manual}
        !           516: @end example
        !           517: 
        !           518: @noindent
        !           519: The @samp{\input texinfo} line tells @TeX{} to use the @file{texinfo.tex}
        !           520: file.  This line is usually followed by a start-of-header line (not shown
        !           521: here) and then by the @samp{@@setfilename @var{info-file-name}} and
        !           522: @samp{@@settitle @var{Name of Manual}} lines.  These two lines are needed
        !           523: to provide a name for the Info file and to specify the name used on the
        !           524: left-hand page headers of the printed manual.@refill
        !           525: 
        !           526: The two lines that contain the @code{@@setfilename} and @code{@@settitle}
        !           527: commands usually are sandwiched between the start-of-header line and the
        !           528: end-of-header line. (@xref{Start-of-Header}, for more information.)  The
        !           529: start-of-header and end-of-header lines are needed if you are going to run
        !           530: @TeX{} or Info on just part of a file.@refill
        !           531: 
        !           532: @node  Short Sample,      , Conventions, Overview
        !           533: @comment  node-name,  next,  previous,  up
        !           534: @section A Short Sample Texinfo File
        !           535: @cindex Sample texinfo file
        !           536: 
        !           537: A Texinfo file looks like the following, which is a complete but very short
        !           538: Texinfo file.  The @code{@@comment} command introduces comments that will
        !           539: not appear in either the Info file or the printed manual; they are for the
        !           540: person who reads the Texinfo file.
        !           541: 
        !           542: The first part of the file, from @samp{\input texinfo} through to
        !           543: @samp{@@end titlepage}, looks more intimidating than it is.  Most of the
        !           544: material is standard boilerplate; when you write a manual, you just put in
        !           545: the name of your own manual in this section.@refill
        !           546: 
        !           547: All the commands that tell @TeX{} how to typeset the printed manual and
        !           548: tell @code{texinfo-format-buffer} how to create an Info file are preceded
        !           549: by @samp{@@}; thus, @code{@@node} indicates a node and @code{@@chapter}
        !           550: indicates the start of a chapter.
        !           551: 
        !           552: @example
        !           553: \input texinfo   @@c -*-texinfo-*-
        !           554: @@setfilename name-of-texinfo-file
        !           555: @@settitle Name of Manual
        !           556: @@setchapternewpage odd
        !           557: 
        !           558: @@ifinfo
        !           559: @@comment The following line inserts the copyright notice 
        !           560: @@comment into the Info file.
        !           561: Copyright @@copyright@{@} 1988 Free Software Foundation, Inc.
        !           562: @@end ifinfo
        !           563: 
        !           564: @@comment The titlepage section does not appear in the Info file.
        !           565: @@titlepage
        !           566: @@sp 10
        !           567: @@comment The title is printed in a large font.
        !           568: @@center @@titlefont@{Sample Title@}
        !           569: 
        !           570: @@comment  The following two commands start the copyright page
        !           571: @@comment  for the printed manual.  This will not appear in the Info file.
        !           572: @@page
        !           573: @@vskip 0pt plus 1filll
        !           574: Copyright @@copyright@{@} year copyright-owner
        !           575: @@end titlepage
        !           576: 
        !           577: @@comment The Top node contains the master menu for the Info file.
        !           578: @@comment This appears only in the Info file, not the printed manual.
        !           579: 
        !           580: @@node    Top,       First Chapter, (dir),    (dir)
        !           581: @@comment node-name, next,          previous, up
        !           582: 
        !           583: @@menu
        !           584: * First Chapter::    The first chapter is the 
        !           585:                      only chapter in this sample.
        !           586: @@end menu
        !           587: 
        !           588: @@node     First Chapter,     , Top,      Top
        !           589: @@comment  node-name,     next, previous, up
        !           590: @@chapter First Chapter
        !           591: @@cindex Reference to First Chapter
        !           592: 
        !           593: This is the contents of the first chapter. 
        !           594: 
        !           595: Here is a numbered list.
        !           596: 
        !           597: @@enumerate
        !           598: @@item
        !           599: This is the first item.
        !           600: 
        !           601: @@item
        !           602: This is the second item.
        !           603: @@end enumerate
        !           604: 
        !           605: The @@kbd@{M-x texinfo-format-buffer@} command transforms a Texinfo file
        !           606: like this into an Info file; and @@TeX@{@} typesets it for a printed
        !           607: manual.
        !           608: 
        !           609: @@node    Concept Index,    ,  Previous Node, Top
        !           610: @@comment node-name,    next,  previous,      up
        !           611: @@unnumbered Concept Index
        !           612: 
        !           613: @@printindex cp
        !           614: 
        !           615: @@contents
        !           616: @@bye
        !           617: @end example
        !           618: 
        !           619: Here is what the contents of the first chapter of the sample look like:
        !           620: 
        !           621: @quotation
        !           622: 
        !           623: This is the contents of the first chapter. 
        !           624: 
        !           625: Here is a numbered list.
        !           626: 
        !           627: @enumerate
        !           628: @item
        !           629: This is the first item.
        !           630: 
        !           631: @item
        !           632: This is the second item.
        !           633: @end enumerate
        !           634: 
        !           635: The @kbd{M-x texinfo-format-buffer} command transforms a Texinfo file like
        !           636: this into an Info file; and @TeX{} typesets it for a printed manual.
        !           637: @end quotation
        !           638: 
        !           639: @node  Texinfo Mode, Beginning a File,  Overview, Top
        !           640: @comment  node-name,  next,  previous,  up
        !           641: @chapter Using Texinfo Mode
        !           642: @cindex Texinfo mode
        !           643: @cindex Mode, using Texinfo
        !           644: @cindex GNU Emacs
        !           645: @cindex Emacs
        !           646: 
        !           647: In GNU Emacs, Texinfo mode is a major mode for editing Texinfo files.
        !           648: This means that Emacs has commands and features especially designed for
        !           649: working with Texinfo files.  Like all other Emacs features, you can
        !           650: customize or enhance these as you wish.  In particular, the keybindings are
        !           651: very easy to change.  The keybindings described here are the default or
        !           652: standard ones.
        !           653: 
        !           654: The major features of Texinfo mode are:
        !           655: 
        !           656: @itemize @bullet
        !           657: @item 
        !           658: Paragraph filling control.
        !           659: 
        !           660: @item 
        !           661: A command to show the structure of the file.
        !           662: 
        !           663: @item 
        !           664: Pre-defined keystroke commands to insert commonly used strings of text.
        !           665: 
        !           666: @item 
        !           667: Formatting a part of a file for Info, rather than the whole file.
        !           668: @end itemize
        !           669: 
        !           670: In general, in Texinfo mode, the GNU Emacs editing commands are like those
        !           671: in text-mode.  The major difference is that the paragraph separation
        !           672: variable and syntax table are set up so expression commands skip Texinfo
        !           673: bracket groups.  This means, for example, that the @kbd{M-q}
        !           674: (@code{fill-paragraph}) command will refill a paragraph but not the
        !           675: @@-command on a line adjacent to it.@refill
        !           676: 
        !           677: By convention, the Texinfo file name shall end with the extension
        !           678: @file{.texinfo} so that Emacs knows to use Texinfo mode for editing it.
        !           679: 
        !           680: @menu
        !           681: * Info on a Region::           Formatting part of a file for Info.
        !           682: * Showing the Structure::      Showing the structure of a file.
        !           683: * Inserting::                  Inserting frequently used commands. 
        !           684: @end menu
        !           685: 
        !           686: @node Info on a Region, Showing the Structure, Texinfo Mode, Texinfo Mode
        !           687: @comment  node-name,  next,  previous,  up
        !           688: @section Formatting a Region for Info
        !           689: @cindex  Running Info on a region
        !           690: @cindex  Info, formatting on a region
        !           691: @findex texinfo-format-region
        !           692: 
        !           693: To see what part of a Texinfo file will look like after it has been
        !           694: transformed into an Info file, use the command @kbd{C-c C-f}
        !           695: (@code{texinfo-format-region}).  This command formats the current region of
        !           696: the Texinfo file for Info and writes it to a temporary buffer called
        !           697: @samp{*Info Region*}.@refill
        !           698: 
        !           699: For @code{texinfo-format-region} to work, the file @strong{must} include a
        !           700: line that has @code{@@setfilename} in its header.@refill
        !           701: 
        !           702: The command is:
        !           703: 
        !           704: @table @kbd
        !           705: @item  C-c C-f 
        !           706: texinfo-format-region
        !           707: @end table
        !           708: 
        !           709: @node Showing the Structure, Inserting, Info on a Region, Texinfo Mode     
        !           710: @comment  node-name,  next,  previous,  up
        !           711: @section Showing the Structure of a File
        !           712: @cindex  Showing the structure of a file
        !           713: @cindex Structure of a file, showing it
        !           714: @cindex File structure, showing it
        !           715: @cindex Texinfo file structure, showing it
        !           716: 
        !           717: You can show the structure of a Texinfo file by using the @kbd{C-c C-s}
        !           718: command (@code{texinfo-show-structure}).  This command shows the structure
        !           719: of a Texinfo file by listing the lines with the @@-commands for
        !           720: @code{@@node}, @code{@@chapter}, @code{@@section} and the like.  These
        !           721: lines are displayed in another window called the @samp{*Occur*} window.  In
        !           722: that window, you can position the cursor over one of the lines and use the
        !           723: @kbd{C-c C-c} command (@code{occur-mode-goto-occurrence}), to jump to the
        !           724: corresponding spot in the Texinfo file.@refill
        !           725: 
        !           726: The two commands are:
        !           727: 
        !           728: @table @kbd
        !           729: @item  C-c C-s 
        !           730: texinfo-show-structure
        !           731: 
        !           732: @item  C-c C-c
        !           733: occur-mode-goto-occurrence
        !           734: @end table
        !           735: 
        !           736: Often, when you are working on a manual, you will be interested only in the
        !           737: structure of the current chapter.  In this case, you can mark off the
        !           738: region of the buffer that you are interested in with the @kbd{C-x n}
        !           739: (@code{narrow-to-region}) command and @code{texinfo-show-structure} will
        !           740: work on only that region.  (To see the whole buffer again, use @kbd{C-x w}
        !           741: (@code{widen}).)@refill
        !           742: 
        !           743: @node     Inserting, , Showing the Structure, Texinfo Mode
        !           744: @comment  node-name,  next,  previous,  up
        !           745: @section Inserting Frequently Used Commands
        !           746: @cindex Inserting frequently used commands
        !           747: @cindex Frequently used commands, inserting them
        !           748: @cindex Commands, inserting them
        !           749: 
        !           750: Texinfo mode provides commands that insert various frequently used
        !           751: @@-commands into the buffer.  You can use these commands to save
        !           752: keystrokes.  And you can insert balanced curly braces with the @kbd{M-@{}
        !           753: command, (@code{texinfo-insert-braces}) and later use the @kbd{M-@}}
        !           754: command (@code{up-list}) to move forward past the closing brace.@refill
        !           755: 
        !           756: The special commands are invoked by typing @kbd{C-c} twice and then the
        !           757: first letter of the @@-command.
        !           758: 
        !           759: @table @kbd
        !           760: @item  C-c C-c c
        !           761: texinfo-insert-@@code
        !           762: 
        !           763: @item  C-c C-c d 
        !           764: texinfo-insert-@@dfn
        !           765: 
        !           766: @item  C-c C-c e 
        !           767: texinfo-insert-@@end
        !           768: 
        !           769: @item  C-c C-c i 
        !           770: texinfo-insert-@@item
        !           771: 
        !           772: @item  C-c C-c n 
        !           773: texinfo-insert-@@node
        !           774: 
        !           775: @item  C-c C-c s
        !           776: texinfo-insert-@@samp
        !           777: 
        !           778: @item  C-c C-c v
        !           779: texinfo-insert-@@var
        !           780: 
        !           781: @item M-@{ 
        !           782: texinfo-insert-braces
        !           783: 
        !           784: @item M-@} 
        !           785: up-list
        !           786: @end table
        !           787: 
        !           788: This list was generated by analyzing the frequency with which commands were
        !           789: used in the @cite{GNU Emacs Manual} and the @cite{GDB Manual}.  If you wish
        !           790: to add your own insert commands, you can bind a keyboard macro to a key, use
        !           791: abbreviations or extend the code in @file{texinfo.el}.
        !           792: 
        !           793: @node Beginning a File, Ending a File, Texinfo Mode, Top
        !           794: @comment  node-name,  next,  previous,  up
        !           795: @chapter Beginning a Texinfo File
        !           796: @cindex Beginning a Texinfo file
        !           797: @cindex Texinfo file beginning
        !           798: @cindex File beginning
        !           799: 
        !           800: Various pieces of information have to be provided to Texinfo at the
        !           801: beginning of a Texinfo file, such as the name of the file, the title
        !           802: of the document and the like.  Generally, the beginning of a Texinfo file
        !           803: has four parts:
        !           804: 
        !           805: @enumerate
        !           806: @item 
        !           807: The header, marked by start-of-header and end-of-header lines, that
        !           808: includes the commands for naming the Texinfo file and telling @TeX{} what
        !           809: definitions' file to use when processing the file.
        !           810: 
        !           811: @item 
        !           812: A section, marked by the @code{@@ifinfo} and @code{@@end ifinfo} commands,
        !           813: that contains a short statement of what the file is about, the copyright
        !           814: notice and copying permissions. This section appears only in the Info file.
        !           815: 
        !           816: @item 
        !           817: A section, marked by the @code{@@titlepage} and @code{@@end titlepage}
        !           818: commands, that contains the title page, the copyright page and copying
        !           819: permissions.  This section appears only in the printed manual.
        !           820: 
        !           821: @item
        !           822: The @samp{Top} node that contains an extensive menu for the whole Info
        !           823: file.  The contents of this node only appear in the Info file.
        !           824: @end enumerate
        !           825: 
        !           826: If the Texinfo file has a section containing licensing information and a
        !           827: warranty disclaimer, that section usually follows the @samp{Top} node.  The
        !           828: licensing section will be followed by a preface or else by the first
        !           829: chapter of the manual.
        !           830: 
        !           831: Since the copyright notice and the copying permissions are in sections that
        !           832: appear only in the Info file or only in the printed manual, this
        !           833: information has to be repeated twice.
        !           834: 
        !           835: The following sample shows what is needed.
        !           836: 
        !           837: @example
        !           838: \input texinfo   @@c -*-texinfo-*-
        !           839: @@comment %**start of header (This is for running Texinfo on a region.)
        !           840: @@setfilename name-of-texinfo-file
        !           841: @@settitle Name of Manual
        !           842: @@setchapternewpage odd
        !           843: @@comment %**end of header (This is for running Texinfo on a region.)
        !           844: 
        !           845: @@ifinfo
        !           846: This file documents @dots{}
        !           847: 
        !           848: Copyright @@copyright@{@} year  copyright-owner
        !           849: 
        !           850: Permission is granted to @dots{}
        !           851: @@end ifinfo
        !           852: 
        !           853: @@titlepage
        !           854: @@sp 10
        !           855: @@center @@titlefont@{Name of Manual When Printed@}
        !           856: @@sp 2
        !           857: @@center Subtitle, If Any
        !           858: @@sp 2
        !           859: @@center Author
        !           860: 
        !           861: @@comment  The following two commands start the copyright page.
        !           862: @@page
        !           863: @@vskip 0pt plus 1filll
        !           864: Copyright @@copyright@{@} year copyright-owner
        !           865: 
        !           866: Published by @dots{}
        !           867: 
        !           868: Permission is granted to @dots{}
        !           869: @@end titlepage
        !           870: 
        !           871: 
        !           872: @@node Top, Overview, (dir), (dir)
        !           873: 
        !           874: @@menu
        !           875: * First Chapter::              The first chapter is usually an overview.
        !           876: * Second Chapter::             @dots{}
        !           877:   <many more menu items here>
        !           878: @@end menu
        !           879: 
        !           880: @@node    First Chapter, Second Chapter, top,      top
        !           881: @@comment node-name,     next,           previous, up
        !           882: @@chapter First Chapter
        !           883: @@cindex Reference to First Chapter
        !           884: @end example
        !           885: 
        !           886: @menu
        !           887: * Header::                     Necessary first lines.
        !           888: * Permissions for Info::       Copyright notice and copying permissions.
        !           889: * Titlepage & Copyright Page:: Printed title and copyright pages.
        !           890: * Top Node::                   The top node and master menu.
        !           891: * License and Distribution::   The importance of the license. 
        !           892: @end menu
        !           893: 
        !           894: @node Header, Permissions for Info , Beginning a File, Beginning a File
        !           895: @comment  node-name,  next,  previous,  up
        !           896: @section The Texinfo File Header
        !           897: @cindex Header for Texinfo files
        !           898: @cindex Texinfo file header
        !           899: 
        !           900: Texinfo files start with at least three lines that provide Info and @TeX{}
        !           901: with necessary information.  If you want to run @TeX{} on just a part of
        !           902: the Texinfo File, you also have to mark these heading lines with
        !           903: start-of-header and end-of-header lines.@refill
        !           904: 
        !           905: @menu
        !           906: * First Line::                 The first line of a Texinfo file.
        !           907: * Start-of-Header::            Identifying the start of the header.
        !           908: * Setfilename::                        Specifying the name of the Info file.
        !           909: * Settitle::                   Specifying the title used by the headings.
        !           910: * Setchapternewpage::          Starting chapters on odd numbered pages.
        !           911: * End-of-Header::              Identifying the end of the header.
        !           912: @end menu
        !           913: 
        !           914: @node     First Line, Start-of-Header, Header, Header
        !           915: @comment  node-name,  next,  previous,  up
        !           916: @subsection The First Line of a Texinfo File
        !           917: @cindex First line of a Texinfo file
        !           918: @cindex Beginning line of a Texinfo file
        !           919: 
        !           920: 
        !           921: Every Texinfo file that is to be the top-level input to @TeX{} must begin
        !           922: with a line that looks like this:
        !           923: 
        !           924: @example
        !           925: \input texinfo   @@c -*-texinfo-*-
        !           926: @end example
        !           927: 
        !           928: @noindent
        !           929: The line serves two functions:
        !           930: 
        !           931: @enumerate
        !           932: @item 
        !           933: When the file is processed by @TeX{}, it loads the macros needed for
        !           934: processing a Texinfo file.  These are in a file called @file{texinfo.tex}
        !           935: which is usually located in the @file{/usr/lib/tex/macros} directory.@refill
        !           936: 
        !           937: @item 
        !           938: When the file is edited in GNU Emacs, it causes Texinfo mode to be used.@refill
        !           939: @end enumerate
        !           940: 
        !           941: The @samp{\input texinfo} line should be followed by the start-of-header
        !           942: line.  This makes it possible for the command for running @TeX{} on a part
        !           943: of the Texinfo file (@code{texinfo-hardcopy-region}) to operate.  The
        !           944: reason for this is that the @code{texinfo-hardcopy-region} command will
        !           945: look on the line preceding the start-of-header line for the @samp{\input
        !           946: texinfo} line.
        !           947: 
        !           948: @node Start-of-Header, Setfilename, First Line, Header
        !           949: @comment  node-name,  next,  previous,  up
        !           950: @subsection @samp{start-of-header}
        !           951: @cindex start-of-header
        !           952: @findex start-of-header
        !           953: 
        !           954: The start-of-header line should immediately follow the first line of the
        !           955: Texinfo file.  
        !           956: 
        !           957: @ifinfo
        !           958: The @code{texinfo-hardcopy-region} command will look at the
        !           959: line preceding the start-of-header line to find the @samp{\input
        !           960: texinfo} line.
        !           961: @end ifinfo
        !           962: 
        !           963: Usually, the start-of-header line looks like this:
        !           964: 
        !           965: @example
        !           966: @@comment %**start of header (This is for running Texinfo on a region.)
        !           967: @end example
        !           968: 
        !           969: The reason for the odd string of characters (@samp{%**}) is so that the
        !           970: @code{texinfo-hardcopy-region} command does not accidently find something
        !           971: that it shouldn't when it is looking for the header.
        !           972: 
        !           973: In the default configuration, the phrase @samp{(This is for running Texinfo
        !           974: on a region.)} is not needed and is just included to make it easier for
        !           975: someone reading the Texinfo file.
        !           976: 
        !           977: The start-of-header line and the end-of-header line are Texinfo mode
        !           978: variables that you can change.
        !           979: 
        !           980: @node     Setfilename, Settitle, Start-of-Header, Header
        !           981: @comment  node-name,  next,  previous,  up
        !           982: @subsection @@setfilename
        !           983: @cindex Setfilename command
        !           984: @cindex Info file requirement for @@setfilename
        !           985: @findex setfilename
        !           986: 
        !           987: In order to be made into an Info file, a Texinfo file must contain a line
        !           988: that looks like this:
        !           989: @example
        !           990: @@setfilename @var{info-file-name}
        !           991: @end example
        !           992: 
        !           993: @noindent
        !           994: This line specifies the name of the Info file to be generated.  In fact, there
        !           995: can be other things in the file before this line, but they are ignored in
        !           996: the generation of an Info file.  The @code{@@setfilename} line is ignored
        !           997: when a printed manual is generated.
        !           998:  
        !           999: @node Settitle, Setchapternewpage, Setfilename, Header
        !          1000: @comment  node-name,  next,  previous,  up
        !          1001: @subsection @@settitle
        !          1002: @findex settitle
        !          1003: 
        !          1004: In order to be made into a printed manual file, a Texinfo file must contain
        !          1005: a line that specifies the title of the manual.  Texinfo uses this
        !          1006: information during printing to put the title on every other page as a
        !          1007: heading; Texinfo puts the current chapter title on the other pages.
        !          1008: Texinfo can find the name of the chapter title from the information
        !          1009: provided by the @code{@@chapter} command, but you must tell it the manual
        !          1010: title with @code{@@settitle}:
        !          1011: 
        !          1012: @example
        !          1013: @@settitle @var{Title}
        !          1014: @end example
        !          1015: 
        !          1016: @noindent
        !          1017: This command, on a line by itself, causes @var{title} to be used for the
        !          1018: headings.  Usually, you will use the same words for the title on the title
        !          1019: page and for the title specified by this command for the headings, but the
        !          1020: two could be different.  For example, the title on the title page may be
        !          1021: longer than the title specified by the @code{settitle} command.
        !          1022: 
        !          1023: The @code{@@settitle} command should precede everything that generates
        !          1024: actual output.
        !          1025: 
        !          1026: @node Setchapternewpage, End-of-Header, Settitle, Header
        !          1027: @comment  node-name,  next,  previous,  up
        !          1028: @subsection @@setchapternewpage
        !          1029: @cindex Starting chapters
        !          1030: @cindex Pages, starting odd
        !          1031: @findex setchapternewpage
        !          1032: 
        !          1033: Conventionally, chapters start on the page on the right hand side of a
        !          1034: book; and the right hand page has an odd number.  To make sure that Texinfo
        !          1035: does this, you can use the command @code{@@setchapternewpage}.  For
        !          1036: example, to cause each chapter to start on a fresh odd-numbered page:
        !          1037: 
        !          1038: @example
        !          1039: @@setchapternewpage odd
        !          1040: @end example
        !          1041: 
        !          1042: Page numbering is turned on by the @code{@@end titlepage} command, so the
        !          1043: @code{@@setchapternewpage} should come before it.  Although it can occur
        !          1044: anywhere in the beginning of the file, it is most convenient to put it in
        !          1045: this location.
        !          1046: 
        !          1047: 
        !          1048: @node End-of-Header, , Setchapternewpage, Header
        !          1049: @comment  node-name,  next,  previous,  up
        !          1050: @subsection  @samp{end-of-header}
        !          1051: @cindex end-of-header
        !          1052: 
        !          1053: The end-of-header line should follow the line containing the
        !          1054: @code{@@setchapternewpage} command.
        !          1055: 
        !          1056: Usually, the end-of-header line looks like this:
        !          1057: 
        !          1058: @example
        !          1059: @@comment %**end of header (This is for running Texinfo on a region.)
        !          1060: @end example
        !          1061: 
        !          1062: @ifinfo
        !          1063: In the default configuration, the phrase @samp{(This is for running Texinfo
        !          1064: on a region.)} is not needed and is just included to make it easier for
        !          1065: someone reading the Texinfo file.
        !          1066: 
        !          1067: The reason for the odd string of characters (`%**') is so that the
        !          1068: @code{texinfo-hardcopy-region} command does not accidently find something
        !          1069: that it shouldn't when it is looking for the header.
        !          1070: 
        !          1071: The start-of-header line and the end-of-header line are Texinfo mode
        !          1072: variables that you can change.
        !          1073: @end ifinfo
        !          1074: 
        !          1075: @iftex
        !          1076: Also, @pxref{Start-of-Header}
        !          1077: @end iftex
        !          1078: 
        !          1079: @node Permissions for Info,  Titlepage & Copyright Page, Header, Beginning a File
        !          1080: @comment  node-name,  next,  previous,  up
        !          1081: @section Copying Permissions for Info
        !          1082: 
        !          1083: Since the title page and the copyright page appear only in the printed copy
        !          1084: of the manual, the same information has to inserted in a section that
        !          1085: appears only in the Info file.  This section usually contains a brief
        !          1086: description of the contents of the Info file, a copyright notice and
        !          1087: copying permissions.
        !          1088: 
        !          1089: The copyright notice should read:
        !          1090: 
        !          1091: @example
        !          1092: Copyright @var{year} @var{copyright-owner}
        !          1093: @end example
        !          1094: 
        !          1095: @noindent
        !          1096: and be put on a line by itself.
        !          1097: 
        !          1098: Standard text for the copyright permissions is contained in the appendix.
        !          1099: @xref{Ifinfo Permissions}, for the complete text.
        !          1100: 
        !          1101: @node Titlepage & Copyright Page, Top Node, Permissions for Info, Beginning a File
        !          1102: @comment  node-name,  next,  previous,  up
        !          1103: @section The Title and Copyright Pages
        !          1104: @cindex Titlepage
        !          1105: @cindex Copyright page
        !          1106: 
        !          1107: The title and copyright pages appear in the printed manual, but not in the
        !          1108: Info file.  Because of this, it is possible to use a couple of slightly
        !          1109: obscure @TeX{} typesetting commands that could not be used in an Info file.
        !          1110: In addition, this part of the beginning of a Texinfo file contains the text
        !          1111: of the copying permissions that will appear in the printed manual.
        !          1112: 
        !          1113: @menu
        !          1114: * Titlepage::                  Creating a title page for the printed manual.
        !          1115: * Center::                     Centering a line.
        !          1116: * Copyright & Printed Permissions::    Inserting the copyright notice 
        !          1117:                                        and printed permissions.
        !          1118: @end menu
        !          1119: 
        !          1120: @node     Titlepage, Center , Setchapternewpage, Titlepage & Copyright Page
        !          1121: @comment  node-name,  next,  previous,  up
        !          1122: @subsection @@titlepage
        !          1123: @cindex Titlepage
        !          1124: @findex titlepage
        !          1125: 
        !          1126: Start the material for the title page and following copyright page with
        !          1127: @code{@@titlepage} on a line by itself and end it with @code{@@end
        !          1128: titlepage} on a line by itself.  The title page and copyright page material
        !          1129: appears only in the printed manual, not in the Info file.  
        !          1130: 
        !          1131: Also, the @code{@@end titlepage} command starts a new page and turns on
        !          1132: page numbering (generation of headings).  Therefore, all the material that
        !          1133: you want to appear on unnumbered pages should be put between the
        !          1134: @code{@@titlepage} and @code{@@end titlepage} commands.  By using the
        !          1135: @code{@@page} command you can force a page break within the region
        !          1136: delineated by the @code{@@titlepage} and @code{@@end titlepage} commands
        !          1137: and create more than one unnumbered page.  This is how the copyright page
        !          1138: is produced.@refill
        !          1139: 
        !          1140: @findex titlefont
        !          1141: To select a large font suitable for the title itself, you can use the
        !          1142: command @code{@@titlefont}.  For example:
        !          1143: 
        !          1144: @example
        !          1145: @@center @@titlefont@{Texinfo@}
        !          1146: @end example
        !          1147: 
        !          1148: Also, you can use @code{@@sp} commands to adjust vertical spacing.  
        !          1149: For example:
        !          1150: 
        !          1151: @example
        !          1152: @@sp 2
        !          1153: @end example
        !          1154: 
        !          1155: @noindent
        !          1156: In the sample, the spacing was chosen to fit an 8 1/2 by 11 inch manual.
        !          1157: 
        !          1158: @node Center, Titlepage, Copyright & Printed Permissions, Titlepage & Copyright Page
        !          1159: @comment  node-name,  next,  previous,  up
        !          1160: @subsection @@center
        !          1161: @cindex Centering a line
        !          1162: @findex center
        !          1163: 
        !          1164: A line containing @code{@@center @var{text}} produces a line of output
        !          1165: containing @var{text}, centered between the margins.@refill
        !          1166: 
        !          1167: 
        !          1168: 
        !          1169: @node     Copyright & Printed Permissions, Center, , Titlepage & Copyright Page
        !          1170: @comment  node-name,  next,  previous,  up
        !          1171: @subsection The Copyright Page and Printed Permissions
        !          1172: @cindex Copyright
        !          1173: @cindex Printed permissions
        !          1174: @cindex Permissions, printed
        !          1175: 
        !          1176: By international treaty, the copyright notice for a book should either be
        !          1177: on the title page or on the back of the title page.  Other locations in a
        !          1178: book are not official and do not provide copyright protection.  The
        !          1179: copyright notice should include the year followed by the name of the person
        !          1180: or organization who has the copyright.
        !          1181: 
        !          1182: When the copyright notice is on the back of the title page, the page is not
        !          1183: numbered.  Therefore, in Texinfo, the information on the copyright page
        !          1184: should be within the region delineated by the @code{@@titlepage} and
        !          1185: @code{@@end titlepage} commands.@refill
        !          1186: 
        !          1187: @findex vskip
        !          1188: @findex filll
        !          1189: To cause a page break, the @code{@@page} command is used.  In the sample,
        !          1190: the @code{@@page} command is followed by the somewhat mysterious line that
        !          1191: reads: @samp{@@vskip 0pt plus 1filll}.  This is a line that uses @TeX{}
        !          1192: commands to push the copyright notice and the other text on the copyright
        !          1193: page towards the bottom of the page.  The @code{@@vskip} command means to
        !          1194: skip lines and put in white space.  The @samp{0pt plus 1filll} means to put
        !          1195: in zero points of mandatory white space, and as much optional white space
        !          1196: as needed.  Note the use of three @samp{l}s in the word @samp{filll}; this
        !          1197: is the correct use in @TeX{}.@refill
        !          1198: 
        !          1199: @findex copyright
        !          1200: The @code{@@copyright@{@}} command generates a @samp{c} inside a circle.
        !          1201: The copyright notice itself has the following legally defined sequence: 
        !          1202: 
        !          1203: @example
        !          1204: Copyright @copyright{} @var{year} @var{copyright-owner}
        !          1205: @end example
        !          1206: 
        !          1207: It is customary to put information on how to get a manual after the
        !          1208: copyright notice (the address of the Free Software Foundation, for example)
        !          1209: and the permissions.  
        !          1210: 
        !          1211: Note that the permissions have to be repeated here as well as in the
        !          1212: `ifinfo' section that immediately follows the header since this section
        !          1213: appears only in the printed manual and the `ifinfo' section appears only in
        !          1214: the Info file.
        !          1215: 
        !          1216: Standard text for the permissions appears in the appendix.  
        !          1217: @xref{Sample Permissions}.
        !          1218: 
        !          1219: @node Top Node, License and Distribution, Titlepage & Copyright Page, Beginning a File    
        !          1220: @comment  node-name,  next,  previous,  up
        !          1221: @section The Top Node and Master Menu
        !          1222: @cindex Top node
        !          1223: @cindex Master menu
        !          1224: 
        !          1225: The @samp{Top} node contains an extensive, master menu for the whole Info
        !          1226: file.  The contents of this node appear only in the Info file.  Nothing in
        !          1227: this node should appear in the printed file.  Since a node line by itself
        !          1228: and a menu by itself are not printed, the contents of this node do not have
        !          1229: to be within a region delineated by @code{@@ifinfo} and @code{@@end ifinfo}
        !          1230: commands.  However, any text within the node should be marked off in that
        !          1231: manner.  You may want to put a short summary before the master menu inside
        !          1232: a region delineated by @code{@@ifinfo} and @code{@@end ifinfo} commands.
        !          1233: Usually, the `Previous' and `Up' nodes refer to the top level directory of
        !          1234: the whole Info system, with pointers to @samp{(dir)}.@refill
        !          1235: 
        !          1236: Generally, the top menu is divided into parts.  
        !          1237: 
        !          1238: @itemize @bullet
        !          1239: 
        !          1240: @item
        !          1241: The first part contains the major nodes in the Texinfo file: the nodes for
        !          1242: the chapters, chapter-like sections and the major appendices.
        !          1243: 
        !          1244: @item
        !          1245: The second part contains entries for the indices.  In an Info file, it is
        !          1246: very useful to have indices here at the beginning of the file in the top
        !          1247: node rather than at the end, as in a printed book.
        !          1248: 
        !          1249: @item
        !          1250: The third and subsequent parts contain a listing of the other, lower level
        !          1251: nodes, often ordered by chapter.  This way, an inquirer can go directly to
        !          1252: a particular node if he or she is searching for specific information.
        !          1253: (These nodes are not required; use them if you think they are a
        !          1254: convenience.)
        !          1255: @end itemize
        !          1256: 
        !          1257: Each section in the menu can be introduced a descriptive line.  So long as
        !          1258: the line does not begin with an asterisk, it will not be treated as a menu
        !          1259: item.  (@xref{Menu, , Making Menus}, for more information.)
        !          1260: 
        !          1261: For example, the Top node of this manual looks like this (but with many
        !          1262: more entries):
        !          1263: 
        !          1264: @example
        !          1265: @@node Top, Overview, (dir), (dir)
        !          1266: 
        !          1267: @@menu
        !          1268: * Overview::                    What is Texinfo?
        !          1269: * Texinfo Mode::                Special features in GNU Emacs.
        !          1270: @dots{}
        !          1271: 
        !          1272: Indices, nodes containing large menus
        !          1273: 
        !          1274: * Command Index::               An item for each @@-command.
        !          1275: * Concept Index::               An item for each concept.
        !          1276: 
        !          1277: A detailed node listing
        !          1278: 
        !          1279: Overview
        !          1280: * Info File::                   Characteristics of the Info file.
        !          1281: * Printed Manual::              Characteristics of the printed manual.
        !          1282: 
        !          1283: Using Texinfo Mode
        !          1284: * Info on a Region::            Formatting a region for Info.
        !          1285: * Showing the Structure::       Showing the structure of a file.
        !          1286: @dots{}
        !          1287: @dots{}
        !          1288: @end example
        !          1289: 
        !          1290: 
        !          1291: @node License and Distribution, , Top Node, Beginning a File
        !          1292: @comment  node-name,  next,  previous,  up
        !          1293: @section Licensing and Distribution Information
        !          1294: @cindex Distribution
        !          1295: @cindex License agreement
        !          1296: 
        !          1297: If the Texinfo file has a section containing the ``General Public License''
        !          1298: and the distribution information and a warranty disclaimer, this section
        !          1299: usually follows the @samp{Top} node.  The licensing and distribution
        !          1300: information and the disclaimer are followed by a preface or else by the
        !          1301: first chapter of the manual.
        !          1302: 
        !          1303: The licensing agreement is very important to Project GNU documentation and
        !          1304: software.  Without it, you may find that you can no longer get the software
        !          1305: or its documentation.  This sounds paradoxical, but the state of the world
        !          1306: is such that documentation and software that does not have a
        !          1307: ``restrictive'' license to make them freely distributable may be lost to
        !          1308: the public.  This has happened.@refill
        !          1309: 
        !          1310: For a good example of the text that could be used for the Distribution,
        !          1311: General Public License and NO WARRANTY sections of your document, see the
        !          1312: latest version of the @cite{GNU Emacs Manual}.
        !          1313: 
        !          1314: @cindex Preface
        !          1315: Although a preface is not a required part of a Texinfo file, it is very
        !          1316: helpful.  Ideally, it should state clearly and concisely what the file is
        !          1317: about and who would be interested in reading it.  In general, the preface
        !          1318: would follow the licensing and distribution information, although sometimes
        !          1319: people put it earlier in the document.  Usually, a preface is put in an
        !          1320: @code{@@unnumbered} section.  (@xref{Unnumbered and Appendix}.)
        !          1321: 
        !          1322: @node     Ending a File, Structuring, Beginning a File, Top
        !          1323: @comment  node-name,  next,  previous,  up
        !          1324: @chapter Ending a Texinfo File
        !          1325: @cindex Ending a Texinfo file
        !          1326: @cindex Texinfo file ending
        !          1327: @cindex File ending
        !          1328: @findex bye
        !          1329: 
        !          1330: The end of a Texinfo file should include the indices, the commands to
        !          1331: generate detailed and summary tables of contents and the @@-command
        !          1332: that tells @TeX{} that it has reached the end of the file.
        !          1333: 
        !          1334: For example, a Texinfo file might be ended as follows:
        !          1335: 
        !          1336: @example
        !          1337: @@node    Concept Index,     , Previous Node, Top
        !          1338: @@comment node-name,     next, previous,      up
        !          1339: @@unnumbered Concept Index
        !          1340: 
        !          1341: @@printindex cp
        !          1342: 
        !          1343: @@contents
        !          1344: @@bye
        !          1345: @end example
        !          1346: 
        !          1347: The @code{@@bye} command should be on a line by itself and every Texinfo
        !          1348: file must end with such a line.  This command terminates @TeX{} processing
        !          1349: and forces out unfinished pages.@refill
        !          1350: 
        !          1351: @menu
        !          1352: * Contents::           Generating a table of contents
        !          1353: * Indices::            Generating, sorting and printing indices
        !          1354: @end menu
        !          1355: 
        !          1356: @node     Contents, Indices , , Ending a File
        !          1357: @comment  node-name,  next,  previous,  up
        !          1358: @section Generating a Table of Contents
        !          1359: @cindex Table of contents
        !          1360: @cindex Contents, Table of 
        !          1361: 
        !          1362: The commands @code{@@chapter}, @code{@@section}, etc., supply the
        !          1363: information to make up a table of contents, but they do not cause an actual
        !          1364: table to be generated.  To do this, you must use the commands
        !          1365: @code{@@contents} and @code{@@summarycontents}.@refill
        !          1366: 
        !          1367: @table @code
        !          1368: 
        !          1369: @item @@contents
        !          1370: The table of contents command outputs (into a printed manual) a complete
        !          1371: table of contents, based on the @code{@@chapter}, @code{@@unnumbered} and
        !          1372: other sectioning commands.  This command should be used on a line by
        !          1373: itself.@refill
        !          1374: 
        !          1375: @item @@summarycontents 
        !          1376: The summary contents command generates a summary table of contents that
        !          1377: lists only the chapters (and appendices and unnumbered chapters); sections,
        !          1378: subsections and subsubsections are omitted.  This command should be used on
        !          1379: a line by itself.  Only large manuals need a summary table of
        !          1380: contents.@refill
        !          1381: @end table
        !          1382: 
        !          1383: You can use either one of these commands, or both.  Each command
        !          1384: automatically generates a chapter-like heading at the top of the page.
        !          1385: Tables of contents should be generated at the very end of the manual, just
        !          1386: before the @code{@@bye} command; the tables of contents commands should
        !          1387: follow any indices that are output, so that the indices will appear in the
        !          1388: contents.@refill
        !          1389: 
        !          1390: @group
        !          1391: @example
        !          1392: @var{indices}@dots{}
        !          1393: @@summarycontents
        !          1394: @@contents
        !          1395: @@bye
        !          1396: @end example
        !          1397: @end group
        !          1398: 
        !          1399: The commands @code{@@contents} and @code{@@summarycontents} are ignored when an
        !          1400: Info file is being generated.
        !          1401: 
        !          1402: @node     Indices, , Contents, Ending a File
        !          1403: @comment  node-name,  next,  previous,  up
        !          1404: @section Creating Indices
        !          1405: @cindex Indices
        !          1406: @cindex Creating indices
        !          1407: 
        !          1408: Using Texinfo, you can generate printed indices and Info file menus without
        !          1409: having to sort and collate entries manually.  Texinfo will do this for you
        !          1410: automatically.  Each index covers a certain kind of entry (functions, or
        !          1411: variables, or concepts, etc.)@: and lists all of those entries in
        !          1412: alphabetical order, together with information on how to find the discussion
        !          1413: of each entry.  In a printed manual, this information consists of page
        !          1414: numbers.  In an Info file, it consists of a menu item leading to the first
        !          1415: node referenced.
        !          1416: 
        !          1417: When you are making index entries, it is good practice to think of the
        !          1418: different categories under which people may look for something.  Different
        !          1419: people @emph{do not} think of the same words when they look something up.
        !          1420: They think of different words.  A helpful index will have items indexed
        !          1421: under all the different words that people may use.  For example, someone might
        !          1422: think it obvious that the two letter names for indices should be listed
        !          1423: under ``Indices, two letter names'', since the word ``Index'' is the
        !          1424: general concept.  But another reader may remember the specific concept of
        !          1425: two letter names and search for the entry listed as ``Two letter names for
        !          1426: indices''.  A good index will have both entries and will help both kinds of
        !          1427: user.
        !          1428: 
        !          1429: Like typesetting, the construction of an index is a highly skilled,
        !          1430: professional art, the subtleties of which are not appreciated until you
        !          1431: have to do it yourself.
        !          1432: 
        !          1433: Normally, six indices are provided for:
        !          1434: 
        !          1435: @itemize @bullet
        !          1436: @item
        !          1437: A @dfn{program index} listing names of programs and leading to the places
        !          1438: where those programs are documented.@refill
        !          1439: 
        !          1440: @item
        !          1441: A @dfn{function index} listing functions (such as, entry points of
        !          1442: libraries).@refill
        !          1443: 
        !          1444: @item
        !          1445: A @dfn{variables index} listing variables (such as, external variables of
        !          1446: libraries).@refill
        !          1447: 
        !          1448: @item
        !          1449: A @dfn{data type index} listing data types (such as, structures defined in
        !          1450: header files).@refill
        !          1451: 
        !          1452: @item
        !          1453: A @dfn{keystroke index} listing keyboard commands.@refill
        !          1454: 
        !          1455: @item
        !          1456: A @dfn{concept index} listing concepts that are discussed.@refill
        !          1457: @end itemize
        !          1458: 
        !          1459: @noindent
        !          1460: Not every manual needs all of these.  This manual has two indices: a
        !          1461: concept index and an @@-command index (that uses the function index but is
        !          1462: called a command index in the chapter heading).  Two or more indices can be
        !          1463: combined into one using the @code{@@synindex} command.  @xref{Combining
        !          1464: Indices}.
        !          1465: 
        !          1466: @menu
        !          1467: * Index Entries::      Defining the entries of an index
        !          1468: * Combining Indices::
        !          1469: * Printing Indices & Menus::
        !          1470: @end menu
        !          1471: 
        !          1472: @node     Index Entries, Combining Indices, , Indices
        !          1473: @comment  node-name,  next,  previous,  up
        !          1474: @subsection Defining the Entries of an Index
        !          1475: @cindex  Defining the entries of an index
        !          1476: @cindex Index entries
        !          1477: @cindex Entries for an index
        !          1478: 
        !          1479: The data to make an index comes from many individual commands scattered
        !          1480: throughout the Texinfo source file.  Each command says to add one entry to
        !          1481: a particular index; after processing, it will give the current page number
        !          1482: or node name as the reference.
        !          1483: 
        !          1484: @table @code
        !          1485: @item @@cindex @var{concept}
        !          1486: Make an entry in the concept index for @var{concept}, referring to the
        !          1487: current page or node.@refill
        !          1488: @item @@findex @var{function}
        !          1489: Make an entry in the function index for @var{function}, referring to the
        !          1490: current page or node.@refill
        !          1491: @item @@vindex @var{variable}
        !          1492: Make an entry in the variable index for @var{variable}, referring to the
        !          1493: current page or node.@refill
        !          1494: @item @@pindex @var{program}
        !          1495: Make an entry in the program index for @var{program}, referring to the
        !          1496: current page or node.@refill
        !          1497: @item @@kindex @var{key}
        !          1498: Make an entry in the key index for @var{key}, referring to the
        !          1499: current page or node.@refill
        !          1500: @item @@tindex @var{data type}
        !          1501: Make an entry in the data type index for @var{data type}, referring to the
        !          1502: current page or node.@refill
        !          1503: @end table
        !          1504: 
        !          1505: If the same name is indexed on several pages, all the pages are listed in
        !          1506: the printed manual's index.  However, @strong{only} the @strong{first} node
        !          1507: referenced will appear in the index of an Info file.  This means that it is
        !          1508: best to write indices in which each entry will refer to only one place in the
        !          1509: Texinfo file.  Fortunately, this constraint is a feature rather than loss
        !          1510: since it means that the index will be easy to use.  Otherwise, it can be
        !          1511: easy to create an index which has many pages listed for an entry and you
        !          1512: don't know which one you need.@refill
        !          1513: 
        !          1514: You are not actually required to use indices for their canonical
        !          1515: purposes.  For example, you might wish to index some C preprocessor macros.
        !          1516: You could put them in the function index along with actual functions, just
        !          1517: by writing @code{@@findex} commands for them; then, when you print the
        !          1518: ``function index'', you could give it the title `Function and Macro Index'
        !          1519: and all will be consistent for the reader.  Or you could put the macros in
        !          1520: with the data types by writing @code{@@tindex} commands for them, and give
        !          1521: that index a suitable title so the reader will understand.@refill
        !          1522: 
        !          1523: @node     Combining Indices, Printing Indices & Menus, Index Entries, Indices
        !          1524: @comment  node-name,  next,  previous,  up
        !          1525: @subsection Combining Indices
        !          1526: @cindex Combining Indices
        !          1527: @cindex Indices, combining them
        !          1528: 
        !          1529: Sometimes you will want to combine two disparate indices such as functions
        !          1530: and variables, perhaps because you have few enough of one of them that
        !          1531: a separate index for them would look silly.
        !          1532: 
        !          1533: You could put variables into the function index by writing @code{@@findex}
        !          1534: commands for them instead of @code{@@vindex} commands, and produce a
        !          1535: consistent manual by printing the function index with the title `Function
        !          1536: and Variable Index' and not printing the `Variable Index' at all; but this
        !          1537: is not a robust procedure.  It works only as long as your document is never
        !          1538: included in part of or together with another document that is designed to
        !          1539: have a separate variable index; if you did that, the variables from your
        !          1540: document and those from the other would not end up together.
        !          1541: 
        !          1542: What you should do instead when you want functions and variables in one
        !          1543: index is to index the variables with @code{@@vindex} as they should be, but
        !          1544: use the @code{@@synindex} command to redirect these @code{@@vindex}
        !          1545: commands to the function index.  @code{@@synindex} takes two arguments: the
        !          1546: name of an index to redirect, and the name of an index to redirect it to.
        !          1547: For this purpose, the indices are given two-letter names:
        !          1548: @cindex Two letter names for indices
        !          1549: @cindex Indices, two letter names
        !          1550: @cindex Names for indices
        !          1551: 
        !          1552: @table @samp
        !          1553: @item cp
        !          1554: the concept index
        !          1555: @item vr
        !          1556: the variable index
        !          1557: @item fn
        !          1558: the function index
        !          1559: @item ky
        !          1560: the key index
        !          1561: @item pg
        !          1562: the program index
        !          1563: @item tp
        !          1564: the data type index
        !          1565: @end table
        !          1566: 
        !          1567: Thus, @code{@@synindex vr fn} at the front of a Texinfo file
        !          1568: will cause all entries designated for the variable index to go to
        !          1569: the function index instead.
        !          1570: 
        !          1571: @node Printing Indices & Menus, , Combining Indices, Indices
        !          1572: @comment  node-name,  next,  previous,  up
        !          1573: @subsection Printing an Index and Generating Menus
        !          1574: @cindex Printing an index
        !          1575: @cindex Indices, printing
        !          1576: @cindex Generating menus with indices
        !          1577: @cindex Menus generated with indices
        !          1578: 
        !          1579: To print an index means to include it as part of a manual or Info file.
        !          1580: This does not happen automatically just because you use @code{@@cindex} or
        !          1581: other index-entry generating commands in the Texinfo file; those just cause
        !          1582: the raw data for the index to be accumulated.  To print an index, you must
        !          1583: include the @code{@@printindex} command at the place in the document where
        !          1584: you want the index to appear.  Also, for the case of the printed manual,
        !          1585: you must run a program called @code{texindex} to sort the raw data to
        !          1586: produce a sorted index file, which is what will actually be used to print
        !          1587: the index.@refill
        !          1588: 
        !          1589: The Texinfo command that is used to print indices is @code{@@printindex}.
        !          1590: It takes the two-letter index name (@pxref{Combining Indices}) as an
        !          1591: argument without braces, and reads the corresponding sorted index file and
        !          1592: formats it appropriately into an index.@refill
        !          1593: 
        !          1594: @ifinfo
        !          1595: The two-letter index names are:
        !          1596: 
        !          1597: @table @samp
        !          1598: @item cp
        !          1599: the concept index.
        !          1600: @item vr
        !          1601: the variable index.
        !          1602: @item fn
        !          1603: the function index.
        !          1604: @item ky
        !          1605: the key index.
        !          1606: @item pg
        !          1607: the program index.
        !          1608: @item tp
        !          1609: the data type index.
        !          1610: @end table
        !          1611: @end ifinfo
        !          1612: 
        !          1613: @code{@@printindex} does not generate a chapter heading for the index.
        !          1614: Consequently, you should precede the command with a suitable section or
        !          1615: chapter command (usually @code{@@unnumbered}) to supply the chapter heading
        !          1616: and put the index into the table of contents.  And before that, you will
        !          1617: probably put a @code{@@node} command.  For example,@refill
        !          1618: 
        !          1619: @example
        !          1620: @@node Variables Index, Concept Index, Function Index, Top
        !          1621: @@comment    node-name,          next,       previous,  up
        !          1622: @@unnumbered Variable Index
        !          1623: 
        !          1624: @@printindex vr
        !          1625: 
        !          1626: @@node     Concept Index,     , Variables Index, Top
        !          1627: @@comment      node-name, next,        previous,  up
        !          1628: @@unnumbered Concept Index
        !          1629: 
        !          1630: @@printindex cp
        !          1631: 
        !          1632: @@summarycontents
        !          1633: @@contents
        !          1634: @@bye
        !          1635: @end example
        !          1636: 
        !          1637: In @TeX{}, @code{@@printindex} needs a sorted index file to work from.
        !          1638: @TeX{} does not know how to do sorting; this is one of the main
        !          1639: deficiencies of @TeX{}.  You must invoke the program @code{texindex} to do
        !          1640: so, giving it the names of the raw index files to be sorted as arguments.
        !          1641: You do not have to run @code{texindex} on all of them; only the ones you
        !          1642: are going to print.  (@xref{Printing Hardcopy}, for more information.)
        !          1643: 
        !          1644: @node Structuring, Quotations and Examples, Ending a File, Top
        !          1645: @comment  node-name,  next,  previous,  up
        !          1646: @chapter Node and Chapter Structuring
        !          1647: @cindex Node and chapter structuring
        !          1648: @cindex Chapter structuring
        !          1649: @cindex Node structuring
        !          1650: @cindex Structuring of nodes and chapters
        !          1651: @findex node
        !          1652: 
        !          1653: The chapter structuring commands divide a document into a hierarchy of
        !          1654: chapters, sections, subsections and subsubsections.  These commands
        !          1655: generate large headings.
        !          1656: 
        !          1657: In a printed manual, the table of contents is based on the information
        !          1658: specified by the chapter structuring commands.
        !          1659: 
        !          1660: Although the chapter structuring commands used for creating a printed
        !          1661: document are entirely different from the node commands for structuring an
        !          1662: Info file, you are likely to use the two kinds of command together since
        !          1663: the single Texinfo file is usually designed to be read both as an Info file
        !          1664: and as a printed manual.  The only time you are likely to use the chapter
        !          1665: structuring commands without using the node structuring commands is if you
        !          1666: are writing a document that will never be put into Info format, for
        !          1667: example, a novel, a letter, an article or a memorandum.
        !          1668: 
        !          1669: It is unlikely that you will ever write a Texinfo file that is only
        !          1670: intended as an on-line Info file and not as a printable document.  However,
        !          1671: Texinfo is flexible enough so that you can do this if you wish.
        !          1672: 
        !          1673: Although a Texinfo file can be structured in a variety of ways, it is
        !          1674: usually structured like a book with chapters, sections, subsections and the
        !          1675: like.  This structure can also be visualized as a tree (or rather as an
        !          1676: upside down tree) with the root at the top and each level corresponding to
        !          1677: chapters or sections or whatnot.  In Info format, you reach the nodes on
        !          1678: each level by using the the `Next' and `Previous' pointers in the node
        !          1679: line.  For example, you go from one chapter to the next or previous chapter
        !          1680: by using the the pointers to the next and previous chapters.  In Info, you
        !          1681: go the level above by using an `Up' pointer and you go to the level below
        !          1682: through a `Menu'.  In the printed manual, cross references are indicated by
        !          1683: page and section numbers; in the on-line file, cross references are
        !          1684: specified by inline menu items.
        !          1685: 
        !          1686: @group
        !          1687: Here is a diagram that shows a Texinfo file with three chapters; 
        !          1688: each chapter has two sections.
        !          1689: 
        !          1690: @example
        !          1691:                                  top
        !          1692:                                   |
        !          1693:                                   |
        !          1694:             ---------------------------------------------
        !          1695:            |                      |                      |
        !          1696:            |                      |                      |
        !          1697:        Chapter 1              Chapter 2               Chapter 3
        !          1698:            |                      |                      |
        !          1699:            |                      |                      |
        !          1700:       ----------             ----------              ----------          
        !          1701:      |          |           |          |            |          |         
        !          1702:  Sect. 1.1   Sect. 1.2   Sect. 2.1  Sect. 2.2    Sect. 3.1  Sect. 3.2     
        !          1703:                                                           
        !          1704: @end example
        !          1705: @end group
        !          1706: 
        !          1707: In this structure, the node for Chapter 2 looks like this:
        !          1708: 
        !          1709: @example
        !          1710: @@node     Chapter 2,  Chapter 3, Chapter 1, top
        !          1711: @@comment  node-name,  next,      previous,  up
        !          1712: @end example
        !          1713: 
        !          1714: To get to Sections 2.1 and 2.2, you need a menu inside of Chapter 2 that
        !          1715: says:
        !          1716: 
        !          1717: @example
        !          1718:     @@menu
        !          1719:     * Sect. 2.1::    Description of this section.
        !          1720:     * Sect. 2.2::  
        !          1721:     @@end menu
        !          1722: @end example
        !          1723: 
        !          1724: @noindent
        !          1725: This menu is located inside Chapter 2, after the beginning of the chapter,
        !          1726: just before Section 2.1.
        !          1727: 
        !          1728: Note that a menu entry has three parts: the menu item name, the name of the
        !          1729: node and, optionally, a description of the item (in that order).  If the
        !          1730: menu item name and the name of the node are the same, you can put two
        !          1731: colons after the item name, as is shown in the example. (If the second part
        !          1732: is different from the first, the first part is terminated by a colon and
        !          1733: the second part terminated by a tab, newline, comma or period.)
        !          1734: (@xref{Menu}.)
        !          1735: 
        !          1736: The node for Sect. 2.1 will look like this:
        !          1737: 
        !          1738: @example
        !          1739:     @@node     Sect. 2.1, Sect. 2.2,         ,  Chapter 2
        !          1740:     @@comment  node-name, next,      previous,  up
        !          1741: @end example
        !          1742: 
        !          1743: This node does not have a `Previous' node.
        !          1744: 
        !          1745: 
        !          1746: Usually, an @code{@@node} command and a chapter structuring command are
        !          1747: used in sequence, along with indexing commands.  For example, the node for
        !          1748: the chapter on ending a file looks like this:
        !          1749: 
        !          1750: @group
        !          1751: @example
        !          1752: @@node    Ending a File, Structuring, Beginning a File, Top
        !          1753: @@comment node-name,     next,        previous,         up
        !          1754: @@chapter Ending a Texinfo File
        !          1755: @@cindex  Ending a Texinfo file
        !          1756: @@cindex  Texinfo file ending
        !          1757: @@cindex  File ending
        !          1758: @end example
        !          1759: @end group
        !          1760: 
        !          1761: The chapter structuring commands fall into four groups that have the
        !          1762: characteristics of chapters, sections, subsections and subsubsections.
        !          1763: The groups are:
        !          1764: 
        !          1765: @group
        !          1766: @table @code
        !          1767: @item @@chapter
        !          1768: @itemx @@unnumbered
        !          1769: @itemx @@appendix
        !          1770: For chapters and chapter-like parts of a document.
        !          1771: 
        !          1772: @item @@section
        !          1773: @itemx @@unnumberedsec
        !          1774: @itemx @@appendixsec
        !          1775: For sections and section-like parts of a document.
        !          1776: 
        !          1777: @item @@subsection
        !          1778: @itemx @@unnumberedsubsec
        !          1779: @itemx @@appendixsubsec
        !          1780: For subsections and subsection-like parts of a document.
        !          1781: 
        !          1782: @item @@subsubsection
        !          1783: @itemx @@unnumberedsubsubsec
        !          1784: @itemx @@appendixsubsubsec
        !          1785: For subsubsections and subsubsection-like parts of a document.
        !          1786: @end table
        !          1787: @end group
        !          1788: 
        !          1789: In the sections that follow, the chapter structuring commands are described
        !          1790: first and then the @code{@@node} and @code{@@menu} commands.
        !          1791: 
        !          1792: @menu
        !          1793: * Chapter::            
        !          1794: * Unnumbered and Appendix::
        !          1795: * Section::
        !          1796: * Subsection::
        !          1797: * Subsubsection::
        !          1798: * Node::
        !          1799: * Menu::
        !          1800: @end menu
        !          1801: 
        !          1802: @node  Chapter, Unnumbered and Appendix, , Structuring
        !          1803: @comment  node-name,  next,  previous,  up
        !          1804: @section @@chapter
        !          1805: @findex chapter
        !          1806: 
        !          1807: @code{@@chapter} identifies a chapter in the document.  It is followed by a
        !          1808: single argument which is the rest of the line, as in
        !          1809: 
        !          1810: @example
        !          1811: @@chapter Node and Chapter Structuring
        !          1812: @end example
        !          1813: 
        !          1814: In @TeX{}, it creates a chapter in the document, specifying the chapter
        !          1815: title.
        !          1816: 
        !          1817: In the Info file, @code{@@chapter} causes its argument to appear on a line
        !          1818: by itself, with a line of asterisks inserted underneath.  Thus, the above
        !          1819: example produces the following output:@refill
        !          1820: 
        !          1821: @example
        !          1822: Node and Chapter Structuring
        !          1823: ****************************
        !          1824: @end example
        !          1825: 
        !          1826: @node Unnumbered and Appendix, Section, Chapter, Structuring
        !          1827: @comment  node-name,  next,  previous,  up
        !          1828: @section @@unnumbered, @@appendix
        !          1829: @findex unnumbered
        !          1830: @findex appendix
        !          1831: 
        !          1832: These commands are equivalent to @code{@@chapter} for Info file output.
        !          1833: (@xref{Chapter}.)  In a printed manual, they generate chapters that are
        !          1834: numbered differently in the table of contents.  @code{@@unnumbered}
        !          1835: chapters appear without chapter numbers of any kind, and @code{@@appendix}
        !          1836: chapters are given a letter instead of a number.
        !          1837: 
        !          1838: @node Section, Subsection, Unnumbered and Appendix, Structuring
        !          1839: @comment  node-name,  next,  previous,  up
        !          1840: @section @@section
        !          1841: @findex section
        !          1842: 
        !          1843: @code{@@section} is like @code{@@chapter} except that in @TeX{} it makes a
        !          1844: section rather than a chapter.  (@xref{Chapter}.)  Sections go within
        !          1845: chapters.  In the Info file, @code{@@chapter} and @code{@@section} differ
        !          1846: only in that @code{@@section} underlines with @samp{=}.  For example,@refill
        !          1847: 
        !          1848: @example
        !          1849: This is a section
        !          1850: =================
        !          1851: @end example
        !          1852: 
        !          1853: @section @@unnumberedsec, @@appendixsec
        !          1854: @findex unnumberedsec
        !          1855: @findex appendixsec
        !          1856: 
        !          1857: Use these constructs for sections within chapters made by
        !          1858: @code{@@unnumbered} or @code{@@appendix}. (@xref{Section}.)@refill
        !          1859: 
        !          1860: @node Subsection, Subsubsection, Section, Structuring    
        !          1861: @comment  node-name,  next,  previous,  up
        !          1862: @section @@subsection
        !          1863: @findex subsection
        !          1864: 
        !          1865: Subsections are to sections as sections are to chapters. (@xref{Section}.)
        !          1866: They are underlined with @samp{-}.  For example,@refill
        !          1867: 
        !          1868: @example
        !          1869: This is a subsection
        !          1870: --------------------
        !          1871: @end example
        !          1872: 
        !          1873: @section @@unnumberedsubsec, @@appendixsubsec
        !          1874: @findex unnumberedsubsec
        !          1875: @findex appendixsubsec
        !          1876: 
        !          1877: Use these constructs for subsections within sections within chapters made
        !          1878: by @code{@@unnumberedsec} or @code{@@appendixsec}.  (@xref{Subsection}.)@refill
        !          1879: 
        !          1880: @node  Subsubsection, Node, Subsection, Structuring
        !          1881: @comment  node-name,  next,  previous,  up
        !          1882: @section @@subsubsection, @@unnumberedsubsubsec, @@appendixsubsubsec
        !          1883: @findex unnumberedsubsubsec
        !          1884: @findex appendixsubsubsec
        !          1885: @findex subsubsection
        !          1886: 
        !          1887: Subsubsections are to subsections as subsections are to sections.
        !          1888: (@xref{Subsection}.)  They are underlined with periods.  The equivalent
        !          1889: commands for @code{@@unnumberedsubsec} and @code{@@appendixsubsec} are
        !          1890: @code{@@unnumberedsubsubsec} and @code{@@appendixsubsubsec}.  For
        !          1891: example,@refill
        !          1892: 
        !          1893: @example
        !          1894: This is a subsubsection
        !          1895: .......................
        !          1896: @end example
        !          1897: 
        !          1898: 
        !          1899: @node   Node, Menu, Subsubsection, Structuring
        !          1900: @comment  node-name,  next,  previous,  up
        !          1901: @section @@node
        !          1902: 
        !          1903: @code{@@node} defines the beginning of a new node in the Info output file
        !          1904: (@inforef{Top, info, info}.).  It is followed by four arguments, separated
        !          1905: by commas, that make up the rest of the line.  Since it is often hard to
        !          1906: remember the order in which are arguments are listed, @code{texinfo-mode}
        !          1907: provides the @kbd{C-c C-c n} command (@code{texinfo-insert-@@node}) which
        !          1908: automatically inserts a comment line listing the arguments.  For
        !          1909: example,@refill
        !          1910: 
        !          1911: @example
        !          1912: @@node    Texinfo Mode, Beginning a File,  Overview, Top    
        !          1913: @@comment node-name,    next,              previous, up
        !          1914: @end example
        !          1915: 
        !          1916: @noindent
        !          1917: defines a node named @samp{Texinfo Mode}, whose `Next' pointer is to node
        !          1918: @samp{Beginning a File}, whose `Previous' pointer is to node
        !          1919: @samp{Overview}, and whose `Up' pointer is to node @samp{Top}.  What this
        !          1920: means is that Texinfo changes @w{@code{@@node @var{args}}} into the special
        !          1921: text string necessary to separate Info nodes and to identify the node that
        !          1922: is starting and say what nodes it points to.@refill
        !          1923: 
        !          1924: The pointer names should be the names of nodes defined elsewhere.  For this
        !          1925: example, nodes named @samp{Beginning a File}, @samp{Overview} and
        !          1926: @samp{Top} should be defined elsewhere in the file with other @code{@@node}
        !          1927: commands.  It does not matter whether they are before or after the node
        !          1928: that refers to them.@refill
        !          1929: 
        !          1930: Normally, a node's `Up' pointer should point at the node whose menu
        !          1931: mentions that node.  The node's `Next' pointer should point at the node
        !          1932: that follows that node and its `Previous' pointer should point at the node
        !          1933: that precedes it in that menu.@refill
        !          1934: 
        !          1935: In @TeX{}, @code{@@node} is nearly ignored.  It generates no text.  Its
        !          1936: only function is to identify the name to use for cross-references to the
        !          1937: chapter or section which follows the @code{@@node} command and which which
        !          1938: makes up the body of the node.  (Cross references are made with
        !          1939: @code{@@xref}.  @xref{Cross References}.)@refill
        !          1940: 
        !          1941: @code{@@node} should be followed immediately by a chapter-structuring
        !          1942: command such as @code{@@chapter}, @code{@@section}, @code{@@subsection} or
        !          1943: @code{@@subsubsection}.@refill
        !          1944: 
        !          1945: The easiest way to write a node is to use the Texinfo mode keyboard command
        !          1946: @kbd{C-c C-c n} to insert @samp{@@node} and a comment line listing the
        !          1947: names of each of the pointers in their proper order.  This way you won't
        !          1948: lose track of which arguments are for which pointers.  The template is
        !          1949: especially useful if you are not familiar with Texinfo.  It is important to
        !          1950: pick a suitable node name.  Generally, these begin with an uppercase letter
        !          1951: as if the node name were a heading for a chapter or section.  Do not use
        !          1952: any of the Texinfo @@-commands in the name; these commands confuse Info.
        !          1953: The node name should be informative.  Unfortunately, long names will not
        !          1954: fit onto the line, which can be awkward.  Sometimes it is better to use
        !          1955: long but informative names rather than short ones.
        !          1956: 
        !          1957: Some people insert the names of the `Next', `Previous' and `Up' pointers at
        !          1958: the same time they insert the node's own name.  This is because it is
        !          1959: easier to keep track of the node structure as you create a document than it
        !          1960: is to sort it out after you have dozens of nodes.  Others wait to insert
        !          1961: the `Next', `Previous' and `Up' pointers until they have a nearly final
        !          1962: version of the document.  This is because they expect to change the
        !          1963: organization of the document while they write it and insert or delete
        !          1964: sections and move them around.  The command @code{texinfo-show-structure}
        !          1965: can be used to find the `Next', `Previous' and `Up' pointers of a node.
        !          1966: (See @xref{Using texinfo-show-structure}.)
        !          1967: 
        !          1968: However you do it, it is best to name the node whenever you write the
        !          1969: section so you can easily make cross references to the section.  A large
        !          1970: number of cross references are an especially important feature of a good
        !          1971: Info file.
        !          1972: 
        !          1973: After you have inserted the node-line, you should immediately write an
        !          1974: @@-command for the chapter or section and insert its name.  Next, (and this
        !          1975: is important!), put in several index entries.  Usually, you will find at
        !          1976: least two and often as many as four or five ways of referring to the node
        !          1977: in the index.  Use them all.  This will make it much easier for people to
        !          1978: find the node.@refill
        !          1979: 
        !          1980: The top node of the file, named @samp{Top}, should have as its parent the
        !          1981: name of a node in another file, where there is a menu that leads to this
        !          1982: file.  Specify the file name in parentheses.  If the file is to be
        !          1983: installed directly in the Info directory file, use @samp{(dir)} as the
        !          1984: parent of the top node; this is short for @samp{(dir)top}, the node @samp{top}
        !          1985: in the file @file{dir}, which is the main menu of Info.  For example,@refill
        !          1986: 
        !          1987: @example
        !          1988: @@node    Top,       Overview, (dir),    (dir)
        !          1989: @@comment node-name, next,     previous, up
        !          1990: @end example
        !          1991: 
        !          1992: For more information about installing an Info file in the @file{info}
        !          1993: directory, @pxref{Installing an Info File}
        !          1994: 
        !          1995: @node          Menu,      ,      Node, Structuring   
        !          1996: @comment  node-name,  next,  previous,          up
        !          1997: @section @@menu
        !          1998: @cindex Menus
        !          1999: @findex menu
        !          2000: 
        !          2001: Info file nodes can contain @dfn{menus} which point to other nodes.  You
        !          2002: must type the menus in by hand, and surround them with lines containing
        !          2003: @code{@@menu} and @code{@@end menu}.  In Info, the @code{@@menu} line
        !          2004: changes into @samp{* Menu:}, which indicates the beginning of a menu to the
        !          2005: Info program.  Otherwise, the contents are unchanged by Texinfo, except for
        !          2006: the processing of any other @@-commands within.  The entire menu construct
        !          2007: has no effect in the printed manual and will not appear there.@refill
        !          2008: 
        !          2009: By convention, a menu is put at the end of a node.  This way, it is easy
        !          2010: for someone using Info to find the menu, using the @kbd{M->}
        !          2011: (@code{end-of-buffer}) command.
        !          2012: 
        !          2013: In a menu, every line that begins with a @samp{*} lists a single topic.  A
        !          2014: line that does not start with a @samp{*} will also appear in the menu and
        !          2015: can be used as a comment.
        !          2016: 
        !          2017: A menu item has three parts: 
        !          2018: 
        !          2019: @enumerate
        !          2020: @item
        !          2021: The menu item name.
        !          2022: 
        !          2023: @item
        !          2024: The name of the node.
        !          2025: 
        !          2026: @item
        !          2027: A description of the item.  
        !          2028: @end enumerate
        !          2029: 
        !          2030: @noindent
        !          2031: Only the first part is required.  This part is the name of the topic---the
        !          2032: name of the menu item that the user must give to the @kbd{m} command to
        !          2033: select this topic when using Info.  The first part comes right after the
        !          2034: asterisk and a space, and is followed by a colon, spaces and tabs, and then
        !          2035: the name of the node which discusses that topic.  The name of the node is
        !          2036: terminated by a tab, comma, newline or period.  If the node name and topic
        !          2037: name are the same, rather than give the name twice, put two colons after
        !          2038: the name instead.  For example, @samp{* Name::}.  (You should do this
        !          2039: whenever possible, since it reduces visual clutter in the menu).
        !          2040: 
        !          2041: If the second part is present, it may be terminated with a tab, comma, or
        !          2042: newline; or with a period.
        !          2043: 
        !          2044: For example,@refill
        !          2045: 
        !          2046: @group
        !          2047: @example
        !          2048: @@menu
        !          2049: A Section on Foo and Switches
        !          2050: * Foo::           The node named Foo tells you how to go fooing.
        !          2051: * Sw: Switches.   Type @@code@{m Sw@} to see node @@code@{Switches@}
        !          2052:                   which describes the switches available here.
        !          2053: @@end menu
        !          2054: @end example
        !          2055: @end group
        !          2056: 
        !          2057: @noindent
        !          2058: produces
        !          2059: 
        !          2060: @group
        !          2061: @example
        !          2062: * menu:
        !          2063: 
        !          2064: A Section on Foo and Switches
        !          2065: * Foo::         The node named foo tells you how to go fooing.
        !          2066: * Sw: Switches. Type `m Sw' to see node `Switches'
        !          2067:                 which describes the switches available here.
        !          2068: @end example
        !          2069: @end group
        !          2070: 
        !          2071: In this example, the menu has two items.  @samp{Foo} is both a menu item
        !          2072: name and the name of the node referred to by that item.  @samp{Sw} is the
        !          2073: other menu item name, and it refers to the node named @samp{Switches}.
        !          2074: Since no file name is specified with @samp{Foo} or @samp{Switches}, they
        !          2075: must be the names of other nodes in the same Info file.  
        !          2076: 
        !          2077: Nodes in other Info files can be referred to by putting the file name in
        !          2078: parentheses at the beginning of the node name. For example, 
        !          2079: 
        !          2080: @example
        !          2081: @@menu
        !          2082: * Outlining: (emacs) Outline Mode.  The major mode for editing outlines.
        !          2083: * Rebinding: (emacs) Rebinding.     How to redefine the meaning of a key.
        !          2084: @@end menu
        !          2085: @end example
        !          2086: 
        !          2087: @noindent
        !          2088: When this is done, the item has to have at least two parts: the first part
        !          2089: is the menu item name and the second part is the name of the node.
        !          2090: 
        !          2091: @node Quotations and Examples, Lists and Tables, Structuring, Top
        !          2092: @comment  node-name,  next,  previous,  up
        !          2093: @chapter Making Quotations and Examples
        !          2094: @cindex Quotations
        !          2095: @cindex Examples
        !          2096: 
        !          2097: Quotations and examples are blocks of text, consisting of one or more whole
        !          2098: paragraphs that are set off from the bulk of the text and treated
        !          2099: differently.  They are usually indented.
        !          2100: 
        !          2101: In Texinfo, an insertion is always begun by writing an @@-command on a line
        !          2102: by itself, and ended by writing an @code{@@end} command that is also on a
        !          2103: line by itself.  For instance, an @dfn{example} is a kind of insertion that
        !          2104: is begun with @code{@@example} and ended with @code{@@end example}.@refill
        !          2105: @findex end
        !          2106: 
        !          2107: There are three commands for quotations and examples:
        !          2108: 
        !          2109: @table @code
        !          2110: @item @@quotation
        !          2111: Used to indicated text that is quoted.@refill
        !          2112: 
        !          2113: @item @@example
        !          2114: Used to illustrate code, commands and the like in a fixed width font
        !          2115: without filling.@refill
        !          2116: 
        !          2117: @item @@display
        !          2118: Used for illustrative text.
        !          2119: @end table
        !          2120: 
        !          2121: @menu
        !          2122: * Quotation::
        !          2123: * Example::
        !          2124: * Display::
        !          2125: @end menu
        !          2126: 
        !          2127: @node     Quotation, Example, ,  Quotations and Examples
        !          2128: @comment  node-name,  next,  previous,  up
        !          2129: @section @@quotation
        !          2130: @cindex Quotations
        !          2131: @findex quotation
        !          2132: 
        !          2133: @code{@@quotation} is used to indicate text that is excerpted from another
        !          2134: (real or hypothetical) printed work.  The inside of a quotation is
        !          2135: processed normally except that
        !          2136: 
        !          2137: @enumerate
        !          2138: @item
        !          2139: The margins are narrower.
        !          2140: @item
        !          2141: Paragraphs are not indented.
        !          2142: @item
        !          2143: Interline spacing and interparagraph spacing are reduced.
        !          2144: @end enumerate
        !          2145: 
        !          2146: Thus, the input
        !          2147: 
        !          2148: @example
        !          2149: @@quotation
        !          2150: This is
        !          2151: a foo.
        !          2152: @@end quotation
        !          2153: @end example
        !          2154: 
        !          2155: @noindent
        !          2156: produces in the printed manual
        !          2157: 
        !          2158: @quotation
        !          2159: @quotation
        !          2160: This is a foo.
        !          2161: @end quotation
        !          2162: @end quotation
        !          2163: 
        !          2164: @noindent
        !          2165: and in the Info file
        !          2166: 
        !          2167: @quotation
        !          2168: @example
        !          2169: This is
        !          2170: a foo.
        !          2171: @end example
        !          2172: @end quotation
        !          2173: 
        !          2174: @node     Example, Display, Quotation,  Quotations and Examples
        !          2175: @comment  node-name,  next,  previous,  up
        !          2176: @section @@example
        !          2177: @cindex Examples
        !          2178: @findex example
        !          2179: 
        !          2180: @code{@@example} is used to indicate an example that is not part of the
        !          2181: running text.  In the printed manual, this is done by switching to
        !          2182: a fixed width font, turning off filling, and making extra spaces
        !          2183: and blank lines significant.  In the Info file, an analogous result
        !          2184: is obtained by indenting each line with five extra spaces.
        !          2185: 
        !          2186: @code{@@example} should appear on a line by itself; this line will
        !          2187: disappear from the output.  Mark the end of the example with a line
        !          2188: containing @code{@@end example}, which will likewise disappear.  For
        !          2189: example:@refill
        !          2190: 
        !          2191: @example
        !          2192: @@example
        !          2193: mv foo bar
        !          2194: @@end example
        !          2195: @end example
        !          2196: 
        !          2197: @noindent
        !          2198: produces
        !          2199: 
        !          2200: @example
        !          2201: mv foo bar
        !          2202: @end example
        !          2203: 
        !          2204: Since the lines containing @code{@@example} and @code{@@end example} will
        !          2205: disappear, you will want to put a blank line before the @code{@@example} and
        !          2206: another blank line after the @code{@@end example}.  (Remember that blank
        !          2207: lines between the beginning @code{@@example} and the ending @code{@@end
        !          2208: example} will appear in the output.)@refill
        !          2209: 
        !          2210: Don't use tabs in lines of an example!  @TeX{} has trouble with tabs:  it
        !          2211: treats them like single spaces, and that is not what they look like.
        !          2212: 
        !          2213: @node     Display, , Example,  Quotations and Examples
        !          2214: @comment  node-name,  next,  previous,  up
        !          2215: @section @@display
        !          2216: @cindex Display
        !          2217: @findex display
        !          2218: 
        !          2219: @code{@@display} is just like @code{@@example} except that, in the
        !          2220: printed manual, @code{@@display} does not select the fixed-width font.
        !          2221: In fact, it does not specify the font at all, so that the text appears
        !          2222: in the same font it would have appeared in without the @code{@@display}.@refill
        !          2223: 
        !          2224: 
        !          2225: @node Lists and Tables, Cross References, Quotations and Examples, Top
        !          2226: @comment  node-name,  next,  previous,  up
        !          2227: @chapter Making Lists and Tables
        !          2228: @cindex  Making lists and tables
        !          2229: @cindex Lists and tables, making them
        !          2230: @cindex Tables and lists, making them
        !          2231: 
        !          2232: Texinfo has several ways of making lists and two-column tables.  Lists can
        !          2233: be bulleted or numbered while two-column tables can highlight the items in
        !          2234: the first column. 
        !          2235: 
        !          2236: For example, this is an enumerated list:
        !          2237: 
        !          2238: @enumerate
        !          2239: @item 
        !          2240: This is a numbered item.
        !          2241: 
        !          2242: @item 
        !          2243: This is the second item in this list.
        !          2244: 
        !          2245: @item 
        !          2246: This is the third item on this list.
        !          2247: @end enumerate
        !          2248: 
        !          2249: Texinfo will automatically indent the text in lists or tables and number an
        !          2250: enumerated list.  This last feature is useful if you are reordering the
        !          2251: list, since you do not have to renumber it yourself.
        !          2252: 
        !          2253: Lists or tables are always begun by an @@-command on a line by itself and
        !          2254: ended with an @code{@@end} command on a line by itself.  For example, an
        !          2255: enumerated list begins with the command @code{@@enumerate} and ends with
        !          2256: the command @code{@@end enumerate}; and an itemized list begins with the
        !          2257: command @code{@@itemize} and ends with the command @code{@@end
        !          2258: itemize}.@refill
        !          2259: @findex end
        !          2260: 
        !          2261: The elements of a list are begun with the @code{@@item} command.
        !          2262: 
        !          2263: Here is an itemized list of the different kinds of table and lists:
        !          2264: 
        !          2265: @itemize @bullet
        !          2266: @item 
        !          2267: Itemized lists with or without bullets.
        !          2268: 
        !          2269: @item 
        !          2270: Numbered lists.
        !          2271: 
        !          2272: @item 
        !          2273: two-column tables with highlighting.
        !          2274: @end itemize
        !          2275: 
        !          2276: @menu
        !          2277: * Itemize::
        !          2278: * Enumerate::
        !          2279: * Table::
        !          2280: @end menu
        !          2281: 
        !          2282: @node     Itemize, Enumerate, , Lists and Tables
        !          2283: @comment  node-name,  next,  previous,  up
        !          2284: @section @@itemize
        !          2285: @cindex Itemize
        !          2286: @findex itemize
        !          2287: 
        !          2288: @code{@@itemize} is used to produce sequences of indented paragraphs, with
        !          2289: a mark inside the left margin at the beginning of each paragraph.  The rest
        !          2290: of the line that starts with @code{@@itemize} should contain the character
        !          2291: or Texinfo commands to generate such a mark.  Usually, it is the @@-command
        !          2292: @code{@@bullet}.  Whatever mark you choose, ultimately, it should result in
        !          2293: a single character in the Texinfo file, or the indentation will come out
        !          2294: wrong.  When you write the command, omit the @samp{@{@}} after the command
        !          2295: if you use just one command and nothing else.
        !          2296: 
        !          2297: The text of the indented paragraphs themselves come after the @code{@@itemize},
        !          2298: up to another line that says @code{@@end itemize}.
        !          2299: 
        !          2300: Before each paragraph for which a mark in the margin is desired, place a
        !          2301: line that says just @code{@@item}.  Don't put any other text on this line.
        !          2302: @findex item
        !          2303: 
        !          2304: Info indents the lines in an itemized list by five columns, but it does not
        !          2305: fill them.  This can produce lines in the Info file that are too wide.  You
        !          2306: can either write shorter lines in the Texinfo file by setting the fill
        !          2307: column to five columns less than it is normally, or else you can tell Info
        !          2308: to refill the paragraphs by adding the @@-command @code{@@refill} to the
        !          2309: end of the paragraph. (@xref{Refill}, for more information about the use of
        !          2310: the @code{@@refill} command.)
        !          2311: 
        !          2312: Usually, you should put a blank line before an @code{@@item}.  This puts a
        !          2313: blank like in the Info file.  Except when the entries are very brief, a
        !          2314: blank line looks better.
        !          2315: 
        !          2316: Here is an example of the use of @code{@@itemize}, followed by the output
        !          2317: it produces.  Note that @code{@@bullet} produces a @samp{*} in Texinfo and
        !          2318: a round dot in @TeX{}. 
        !          2319: 
        !          2320: @group
        !          2321: @example
        !          2322: @@itemize @@bullet
        !          2323: @@item
        !          2324: Some text for foo.
        !          2325: 
        !          2326: @@item
        !          2327: Some text
        !          2328: for bar.
        !          2329: @@end itemize
        !          2330: @end example
        !          2331: @end group
        !          2332: 
        !          2333: @noindent
        !          2334: produces
        !          2335: 
        !          2336: @group
        !          2337: @quotation
        !          2338: @itemize @bullet
        !          2339: @item
        !          2340: Some text for foo.
        !          2341: 
        !          2342: @item
        !          2343: Some text
        !          2344: for bar.
        !          2345: @end itemize
        !          2346: @end quotation
        !          2347: @end group
        !          2348: 
        !          2349: @node Enumerate, Table, Itemize, Lists and Tables    
        !          2350: @comment  node-name,  next,  previous,  up
        !          2351: @section @@enumerate
        !          2352: @cindex Enumerate
        !          2353: @findex enumerate
        !          2354: 
        !          2355: @code{@@enumerate} is like @code{@@itemize} except that the marks in the
        !          2356: left margin contain successive integers starting with 1.  (@xref{Itemize}.)
        !          2357: Do not put any argument on the same line as @code{@@enumerate}.@refill
        !          2358: 
        !          2359: @group
        !          2360: @example
        !          2361: @@enumerate
        !          2362: @@item
        !          2363: Some text for foo.
        !          2364: @@item
        !          2365: Some text
        !          2366: for bar.
        !          2367: @@end enumerate
        !          2368: @end example
        !          2369: @end group
        !          2370: 
        !          2371: @noindent
        !          2372: produces
        !          2373: 
        !          2374: @quotation
        !          2375: @enumerate
        !          2376: @item
        !          2377: Some text for foo.
        !          2378: @item
        !          2379: Some text
        !          2380: for bar.
        !          2381: @end enumerate
        !          2382: @end quotation
        !          2383: 
        !          2384: If you want, you can put a blank line between the entries in the list.
        !          2385: This often makes it easier to read the Info file.  For example,
        !          2386: 
        !          2387: 
        !          2388: @group
        !          2389: @example
        !          2390: @@enumerate
        !          2391: @@item
        !          2392: This is the first item.
        !          2393: 
        !          2394: @@item
        !          2395: This is the second item.
        !          2396: @@end enumerate
        !          2397: @end example
        !          2398: @end group
        !          2399: 
        !          2400: @ifinfo
        !          2401: Info indents the lines of the enumerated list by five columns, but it does
        !          2402: not fill them.  As a result, the lines in the Info file may be too wide.
        !          2403: To prevent this, you can either write shorter lines in the Texinfo file
        !          2404: file by setting the fill column to five columns less than it is normally,
        !          2405: or else you can tell Info to refill the paragraphs by adding the @@-command
        !          2406: @code{@@refill} to the end of the paragraph.  (@xref{Refill}, for more
        !          2407: information about the use of the @code{@@refill} command.)
        !          2408: @end ifinfo
        !          2409: 
        !          2410: @iftex
        !          2411: Info indents the lines of the enumerated list by five columns, but it does
        !          2412: not fill them, just as it does with an itemized list.  You may want to use
        !          2413: shorter lines for text within an enumerated list or use the @code{@@refill}
        !          2414: command at the end of the paragraph. (@xref{Refill}, for more information
        !          2415: about the use of the @code{@@refill} command.)
        !          2416: @end iftex
        !          2417: 
        !          2418: @node     Table, , Enumerate, Lists and Tables
        !          2419: @comment  node-name,  next,  previous,  up
        !          2420: @section @@table
        !          2421: @cindex Tables, making two-column
        !          2422: @findex table
        !          2423: 
        !          2424: @code{@@table} is similar to @code{@@itemize}, but allows you to specify a
        !          2425: name or heading line for each item.  (@xref{Itemize}.)  The command is used
        !          2426: to produce two-column tables, and is especially useful for glossaries and
        !          2427: explanatory exhibits.@refill
        !          2428: 
        !          2429: You must follow each use of @code{@@item} inside of @code{@@table} with
        !          2430: text to serve as the heading line for that item.  This text is put on the
        !          2431: same line as the @code{@@item} command.  Each heading line is put into the
        !          2432: first column of the table and the supporting text, which you put on the line
        !          2433: following the line beginning with @code{@@item}, goes into the second
        !          2434: column.@refill
        !          2435: @findex item
        !          2436: 
        !          2437: Also, @code{@@table} itself must be followed by an argument that is a
        !          2438: Texinfo command such as @code{@@code}, @code{@@var}, @code{@@kbd} or
        !          2439: @code{@@asis}.  Although these commands are usually followed by arguments
        !          2440: in braces, in this case you use the command name without an argument.
        !          2441: (@code{@@item} supplies the argument.)  This command will be applied to
        !          2442: the text that goes into the first column of each item and determines how it
        !          2443: will be highlighted.  For example, @code{@@samp} will cause the text in the
        !          2444: first column to be highlighted as if it were acted on by an @code{@@samp}
        !          2445: command.@refill
        !          2446: 
        !          2447: @code{@@asis} is a command that does nothing; in that case, each item will
        !          2448: come out without highlighting, unless that particular piece of text
        !          2449: contains @@-commands for highlighting.@refill
        !          2450: 
        !          2451: (Various other command names might work with @code{@@table}.  However, only
        !          2452: commands that normally take arguments in braces may be used.)@refill
        !          2453: 
        !          2454: @ifinfo
        !          2455: Usually, you should put a blank line before an @code{@@item}.  This puts a
        !          2456: blank like in the Info file.  Except when the entries are very brief, a
        !          2457: blank line looks better.
        !          2458: @end ifinfo
        !          2459: 
        !          2460: The following table, for example, highlights the text in the first column
        !          2461: as if each item were acted on by an @code{@@samp} command:@refill
        !          2462: 
        !          2463: @example
        !          2464: @@table @@samp
        !          2465: @@item foo
        !          2466: This is the text for
        !          2467: @@samp@{foo@}.
        !          2468: 
        !          2469: @@item bar
        !          2470: Text for @@samp@{bar@}.
        !          2471: @@end table
        !          2472: @end example
        !          2473: 
        !          2474: @noindent
        !          2475: produces
        !          2476: 
        !          2477: @quotation
        !          2478: @table @samp
        !          2479: @item foo
        !          2480: This is the text for
        !          2481: @samp{foo}.
        !          2482: @item bar
        !          2483: Text for @samp{bar}.
        !          2484: @end table
        !          2485: @end quotation
        !          2486: 
        !          2487: Info indents the lines of text in the second column, but does not fill
        !          2488: them.  As a result, the lines in the Info file may be too wide.  To prevent
        !          2489: this, cause Info to refill the paragraphs after processing by adding the
        !          2490: @@-command @code{@@refill} to the end of the paragraph. (@xref{Refill}, for
        !          2491: more information about the use of the @code{@@refill} command.)
        !          2492: 
        !          2493: If you want to list two or more named items with a single block of text,
        !          2494: use the @code{@@itemx} command.
        !          2495: 
        !          2496: @menu
        !          2497: * Itemx::
        !          2498: @end menu
        !          2499: 
        !          2500: @node     Itemx, , Table, Table
        !          2501: @comment  node-name,  next,  previous,  up
        !          2502: @subsection @@itemx
        !          2503: @cindex Itemx 
        !          2504: @findex itemx
        !          2505: 
        !          2506: @code{@@itemx} is used inside a @code{@@table} when you have two or more
        !          2507: named items for the same block of text.  Use @code{@@itemx} for all but the
        !          2508: first of the items.  It works exactly like @code{@@item} except that it
        !          2509: does not generate extra vertical space above the item text.
        !          2510: For example,@refill
        !          2511: 
        !          2512: @example
        !          2513: @@table @@code
        !          2514: @@item upcase
        !          2515: @@itemx downcase
        !          2516: These two functions accept a character or a string as argument,
        !          2517: and return the corresponding upper case (lower case) character
        !          2518: or string. @@refill
        !          2519: @@end table
        !          2520: @end example
        !          2521: 
        !          2522: @noindent
        !          2523: produces
        !          2524: 
        !          2525: @quotation
        !          2526: @table @code
        !          2527: @item upcase
        !          2528: @itemx downcase
        !          2529: These two functions accept a character or a string as argument,
        !          2530: and return the corresponding upper case (lower case) character
        !          2531: or string. @refill
        !          2532: @end table
        !          2533: @end quotation
        !          2534: 
        !          2535: A more complicated example of the use of @code{@@itemx} comes from the
        !          2536: chapter on structuring commands.  Here is how the list showing how 
        !          2537: the chapter structuring commands fall into four groups was constructed.
        !          2538: (@xref{Structuring, , Chapter Structuring Commands}.)
        !          2539: 
        !          2540: @group
        !          2541: @example
        !          2542: @@table @@code
        !          2543: @@item  @@@@chapter
        !          2544: @@itemx @@@@unnumbered
        !          2545: @@itemx @@@@appendix
        !          2546: For chapters and chapter-like parts of a document.
        !          2547: 
        !          2548: @@item  @@@@section
        !          2549: @@itemx @@@@unnumberedsec
        !          2550: @@itemx @@@@appendixsec
        !          2551: For sections and section-like parts of a document.
        !          2552: 
        !          2553: @@item  @@@@subsection
        !          2554: @@itemx @@@@unnumberedsubsec
        !          2555: @@itemx @@@@appendixsubsec
        !          2556: For subsections and subsection-like parts of a document.
        !          2557: 
        !          2558: @@item  @@@@subsubsection
        !          2559: @@itemx @@@@unnumberedsubsubsec
        !          2560: @@itemx @@@@appendixsubsubsec
        !          2561: For subsubsections and similar parts of a document.
        !          2562: @@end table
        !          2563: @end example
        !          2564: @end group
        !          2565: 
        !          2566: @noindent
        !          2567: and this is what the resulting table looks like:
        !          2568: 
        !          2569: 
        !          2570: @table @code
        !          2571: 
        !          2572: @item  @@chapter
        !          2573: @itemx @@unnumbered
        !          2574: @itemx @@appendix
        !          2575: For chapters and chapter-like parts of a document.
        !          2576: 
        !          2577: @item  @@section
        !          2578: @itemx @@unnumberedsec
        !          2579: @itemx @@appendixsec
        !          2580: For sections and section-like parts of a document.
        !          2581: 
        !          2582: @item  @@subsection
        !          2583: @itemx @@unnumberedsubsec
        !          2584: @itemx @@appendixsubsec
        !          2585: For subsections and subsection-like parts of a document.
        !          2586: 
        !          2587: @item  @@subsubsection
        !          2588: @itemx @@unnumberedsubsubsec
        !          2589: @itemx @@appendixsubsubsec
        !          2590: For subsubsections and similar parts of a document.
        !          2591: @end table
        !          2592: 
        !          2593: 
        !          2594: Also, either column of a table can be empty.  
        !          2595: 
        !          2596: @node Cross References, Formatting Paragraphs, Lists and Tables, Top
        !          2597: @comment  node-name,  next,  previous,  up
        !          2598: @chapter Making Cross References
        !          2599: @cindex  Making cross references
        !          2600: @cindex Cross references
        !          2601: @cindex References
        !          2602: 
        !          2603: Cross references are used to refer the reader to other parts of the same or
        !          2604: different Texinfo files.  In Texinfo, @dfn{nodes} are the points to which
        !          2605: cross-references can refer.  
        !          2606: 
        !          2607: In general, a document should be designed so that it can be read
        !          2608: sequentially.  People soon tire of flipping back and forth to find
        !          2609: information that should be presented to them as they need it.  However,
        !          2610: there will be information (often too detailed for whatever the current
        !          2611: context may be) that is related to whatever is presented and to which
        !          2612: reference should be made.  More important, in an on-line help system or in
        !          2613: a reference manual, readers do @emph{not} read everything in sequence from
        !          2614: beginning to end.  Instead, they look up what they need.  For this reason,
        !          2615: such creations should contain many cross references to help the reader find
        !          2616: other information that he or she may not have read.
        !          2617: 
        !          2618: Although nodes are not a fundamental concept in a printed manual, they
        !          2619: still serve to define a cross-reference point and the variants of
        !          2620: @code{@@xref} still serve to make references.  Thus, if you are writing a
        !          2621: manual that will only be printed, and will not be used on-line, you
        !          2622: continue to use the @code{@@node} command for when you make cross
        !          2623: references.
        !          2624: 
        !          2625: There are several kinds of cross reference command.
        !          2626: 
        !          2627: @table @code
        !          2628: @item @@xref
        !          2629: Used to start a sentence in the printed manual saying, `See @dots{}' @*
        !          2630: or an entry in the Info file saying @samp{*note @dots{}}.
        !          2631: 
        !          2632: @item @@pxref
        !          2633: Used to make a reference that starts with a lowercase @samp{see} @*
        !          2634: and is usually contained within parentheses.@refill
        !          2635: 
        !          2636: @item @@inforef
        !          2637: Used to make a reference to an Info file for which there is no printed
        !          2638: manual.@refill
        !          2639: @end table
        !          2640: 
        !          2641: @menu
        !          2642: * Xref::
        !          2643: * Pxref::
        !          2644: * Inforef::
        !          2645: @end menu
        !          2646: 
        !          2647: 
        !          2648: @node     Xref,  Pxref, Cross References, Cross References
        !          2649: @comment  node-name,  next,  previous,  up
        !          2650: @section @@xref
        !          2651: @cindex Xref for cross references
        !          2652: @findex xref
        !          2653: @cindex Cross references using xref
        !          2654: 
        !          2655: @code{@@xref} generates a cross-reference.  In Texinfo, it turns into
        !          2656: an Info cross-reference which the Info @samp{f} command can use
        !          2657: to go directly to another node.  In @TeX{}, it turns into a sentence
        !          2658: of the form
        !          2659: 
        !          2660: @example
        !          2661: See section @var{section} [@var{topic}], page @var{page}
        !          2662: @end example
        !          2663: 
        !          2664: @noindent
        !          2665: but does not generate a period to end it.
        !          2666: 
        !          2667: @code{@@xref} must refer to an Info node created by @code{@@node}, by the
        !          2668: node's name.  
        !          2669: 
        !          2670: @code{@@xref} is followed by an argument inside braces; but actually the
        !          2671: text inside the braces is treated as several arguments, separated by
        !          2672: commas.  Whitespace after these commas is ignored.  A period or comma
        !          2673: @strong{must} follow the closing brace of an @code{@@xref}.  It is required
        !          2674: to terminate the cross reference.  This period or comma will appear in the
        !          2675: output, both in the Info file and in the printed manual.
        !          2676: 
        !          2677: The simplest form of @code{@@xref} takes one argument, the name of another
        !          2678: node in the same Info file.  Here we show the input text, followed by a
        !          2679: blank line and then the output text for Info files and the output text for
        !          2680: printed manuals.
        !          2681: 
        !          2682: @example
        !          2683: @@xref@{node-name@}, for more info.
        !          2684: 
        !          2685: *note node-name::, for more info.
        !          2686: @end example
        !          2687: 
        !          2688: @quotation
        !          2689: See section @var{nnn} [node-name], page @var{ppp}, for more info.
        !          2690: @end quotation
        !          2691: 
        !          2692: With two arguments, the second one is used as the name of the Info
        !          2693: cross-reference, while the first argument is still the node that the
        !          2694: cross-reference points to:
        !          2695: 
        !          2696: @example
        !          2697: @@xref@{node-name, name-for-note@}, for more info.
        !          2698: 
        !          2699: *note name-for-note: node-name, for more info.
        !          2700: @end example
        !          2701: 
        !          2702: @quotation
        !          2703: See section @var{nnn} [node-name], page @var{ppp}, for more info.
        !          2704: @end quotation
        !          2705: 
        !          2706: A third argument replaces the node name when it actually appears in the
        !          2707: @TeX{} output.  It should state the topic discussed by the section being
        !          2708: referenced.  Often, you will want to use initial uppercase letters so it
        !          2709: will be easier to read when the reference is printed.  Use a third argument
        !          2710: when the node name is unsuitable because of syntax, grammar or diction.
        !          2711: 
        !          2712: @example
        !          2713: @@xref@{node-name, name-for-note, Topic Description@}, for more info.
        !          2714: 
        !          2715: *note name-for-note: node-name, for more info.
        !          2716: @end example
        !          2717: 
        !          2718: @quotation
        !          2719: See section @var{nnn} [Topic Description], page @var{ppp}, for more info.
        !          2720: @end quotation
        !          2721: 
        !          2722: If a third argument is given and the second one is empty,
        !          2723: then the third argument serves both purposes:
        !          2724: 
        !          2725: @example
        !          2726: @@xref@{node-name, , Topic Description@}, for more info.
        !          2727: 
        !          2728: *note Topic Description: node-name, for more info.
        !          2729: @end example
        !          2730: 
        !          2731: @quotation
        !          2732: See section @var{nnn} [Topic Description], page @var{ppp}, for more info.
        !          2733: @end quotation
        !          2734: 
        !          2735: A fourth argument specifies the name of the Info file in which the
        !          2736: referenced node is located, assuming it is not the one in which the
        !          2737: reference appears.  @code{@@xref} with only four arguments is used when the
        !          2738: reference is not within one Info file, but is within a single printed
        !          2739: manual---when multiple Texinfo files are incorporated into the same @TeX{}
        !          2740: run but make separate Info files.  (This is seldom the case and usually you
        !          2741: will use five arguments if you are making a reference that is outside the
        !          2742: current Info file.)
        !          2743: 
        !          2744: @example
        !          2745: @@xref@{node-name, name-for-note, Topic, info-file-name@}, 
        !          2746: for more info.
        !          2747: 
        !          2748: *note name-for-note: (info-file-name) node-name, for more info.
        !          2749: @end example
        !          2750: 
        !          2751: @quotation
        !          2752: See section @var{nnn} [Topic], page @var{ppp}, for more info.
        !          2753: @end quotation
        !          2754: 
        !          2755: A fifth argument is used when you are making a reference to another Info
        !          2756: file which is also part of another printed manual.  Write the title of the
        !          2757: manual in this slot.  Since a different manual is made during a different
        !          2758: @TeX{} run, the printed reference will not have a page number.
        !          2759: 
        !          2760: @noindent
        !          2761: Whenever you refer to another manual, use this version of @code{@@xref}
        !          2762: with five arguments.
        !          2763: 
        !          2764: @example
        !          2765: @@xref@{node-name, name-for-note, Topic, info-file-name, A Printed Manual@},
        !          2766: for more info.
        !          2767: 
        !          2768: *note name-for-note: (info-file-name) node-name, for more info.
        !          2769: @end example
        !          2770: 
        !          2771: @quotation
        !          2772: See section Topic of @i{A Printed Manual}, for more info.
        !          2773: @end quotation
        !          2774: 
        !          2775: @noindent
        !          2776: The name of the printed manual will be typeset in italics.
        !          2777: 
        !          2778: Often, you will leave out the second argument when you use the long version
        !          2779: of @code{@@xref}.  In this case, the third argument, the topic description,
        !          2780: will replace the node name:
        !          2781: 
        !          2782: 
        !          2783: @example
        !          2784: @@xref@{node-name, , Topic Description, info-file-name, A Printed Manual@},
        !          2785: for more info.
        !          2786: 
        !          2787: *note Topic Description: (info-file-name) node-name, for more info.
        !          2788: @end example
        !          2789: 
        !          2790: @quotation
        !          2791: See section Topic Description of @i{A Printed Manual}, for more info.
        !          2792: @end quotation
        !          2793: 
        !          2794: 
        !          2795: @node     Pxref, Inforef, Xref, Cross References
        !          2796: @comment  node-name,  next,  previous,  up
        !          2797: @section @@pxref
        !          2798: @cindex Cross references using pxref
        !          2799: @cindex Pxref for cross references
        !          2800: @findex pxref
        !          2801: 
        !          2802: @code{@@pxref} is nearly the same as @code{@@xref}; it differs in only
        !          2803: two ways:
        !          2804: 
        !          2805: @enumerate
        !          2806: @item
        !          2807: The output starts with lower case `see' rather than `See'.@refill
        !          2808: @item
        !          2809: A period is generated automatically in the Info file output to end the Info
        !          2810: cross-reference, but no period is generated for the printed manual.@refill
        !          2811: @end enumerate
        !          2812: 
        !          2813: The purpose of @code{@@pxref} is to be used inside parentheses as part of
        !          2814: another sentence.  In the printed manual, no period is needed after the
        !          2815: cross reference text itself (within the parentheses), but a period is
        !          2816: needed after the cross reference text in the Info file because only thus
        !          2817: can Info recognize the end of the cross-reference.  @code{@@pxref} spares
        !          2818: you the need to use complicated methods to put a period into one form of
        !          2819: the output and not the other.
        !          2820: 
        !          2821: @code{@@pxref} can be used with up to five arguments just like
        !          2822: @code{@@xref}.  (@xref{Xref}.)@refill
        !          2823: 
        !          2824: @node     Inforef, , Pxref, Cross References
        !          2825: @comment  node-name,  next,  previous,  up
        !          2826: @section @@inforef
        !          2827: @cindex Inforef for cross references
        !          2828: @cindex Cross references using inforef
        !          2829: @findex inforef
        !          2830: 
        !          2831: @code{@@inforef} is used for cross-references to Info files for which there
        !          2832: are no printed manuals.  Even in a printed manual, @code{@@inforef}
        !          2833: generates a reference directing the user to look in an Info file.
        !          2834: @code{@@inforef} takes exactly three arguments.  The syntax is
        !          2835: @code{@@inforef@{@var{node}, @var{name}, @var{file}@}}.
        !          2836: 
        !          2837: @example
        !          2838: @@inforef@{node-name, name-for-note, info-file-name@}, for more information.
        !          2839: 
        !          2840: *note name-for-note: (info-file-name) node-name, for more information.
        !          2841: @end example
        !          2842: 
        !          2843: @quotation
        !          2844: See Info file @file{info-file-name}, node `node-name', for more information.
        !          2845: @end quotation
        !          2846: 
        !          2847: @node Formatting Paragraphs, Marking Text, Cross References, Top
        !          2848: @comment  node-name,  next,  previous,  up
        !          2849: @chapter Formatting Paragraphs
        !          2850: @cindex Formatting paragraphs
        !          2851: @cindex Paragraphs, formatting
        !          2852: 
        !          2853: Usually, a Texinfo file will be processed both by @TeX{} and by the
        !          2854: @kbd{M-x texinfo-format-buffer} command.  Consequently, you must make sure
        !          2855: that text will come out looking right both in the printed manual and in the
        !          2856: on-line help.@refill
        !          2857: 
        !          2858: For example, unless told otherwise, @kbd{M-x texinfo-format-buffer} will
        !          2859: not refill a paragraph after processing it although @TeX{} will.  This
        !          2860: means that a paragraph with numerous or large @@-commands may not look
        !          2861: properly filled after processing by Info.  The @@-commands are removed from
        !          2862: the text but the lines are not refilled so some are much shorter than they
        !          2863: were.  To cause the @kbd{M-x texinfo-format-buffer} command to refill such
        !          2864: a paragraph, put @code{@@refill} at the end of the paragraph.@refill
        !          2865: 
        !          2866: @TeX{} may also format a document improperly.  For example, page breaks may
        !          2867: occur in the ``wrong place''; to control this, text can be held together by a
        !          2868: group command that keeps the text within the group from being split across
        !          2869: two pages.
        !          2870: 
        !          2871: @iftex
        !          2872: The first section that follows is about refilling and preventing
        !          2873: indentation; the second section is about line and paragraph breaks,
        !          2874: creating blank lines, and grouping text.
        !          2875: @end iftex
        !          2876: 
        !          2877: @menu
        !          2878: * Refilling & Noindent::      Refilling paragraphs & preventing indentation
        !          2879: * Breaks Blank-Lines Groups::  Line and paragraph breaks, blank lines, grouping
        !          2880: @end menu
        !          2881: 
        !          2882: @node Refilling & Noindent, Breaks Blank-Lines Groups, Formatting Paragraphs, Formatting Paragraphs
        !          2883: @comment  node-name,  next,  previous,  up
        !          2884: @section Refilling Paragraphs and Preventing Indentation
        !          2885: @cindex Refilling paragraphs automatically
        !          2886: @cindex Preventing indentation in the printed text
        !          2887: 
        !          2888: The @code{@@refill} and @code{@@noindent} commands are used just after or
        !          2889: just before paragraphs which, after processing by either Info or @TeX{},
        !          2890: might look bad.  The @code{@@refill} command refills a paragraph in the
        !          2891: Info file after all the other processing has been done.  In the printed
        !          2892: manual, the @code{@@noindent} command prevents a piece of text that is a
        !          2893: continuation of the preceding paragraph from being indented as if it were a
        !          2894: new paragraph.@refill
        !          2895: 
        !          2896: @menu
        !          2897: * Refill::     Refilling an info paragraph after other processing.
        !          2898: * Noindent::   Preventing paragraph indentation in continuation text.
        !          2899: @end menu
        !          2900: 
        !          2901: @node     Refill, Noindent, Refilling & Noindent, Refilling & Noindent
        !          2902: @comment  node-name,  next,  previous,  up
        !          2903: @subsection @@refill
        !          2904: @findex refill
        !          2905: 
        !          2906: If a paragraph contains sizable @@-constructs, it may look badly filled
        !          2907: after @code{texinfo-format-buffer} is through with it.
        !          2908: 
        !          2909: Put @code{@@refill} at the end of the paragraph to tell
        !          2910: @code{texinfo-format-buffer} to refill the paragraph after finishing all
        !          2911: other processing on it.  @code{@@refill} has no effect on @TeX{}, which
        !          2912: always fills everything that ought to be filled.  For example,@refill
        !          2913: 
        !          2914: @example
        !          2915: To use @@code@{foo@}, pass @@samp@{xx%$@} and @@var@{flag@} and type @@kbd@{x@}
        !          2916: after running @@code@{make-foo@}.@@refill
        !          2917: @end example
        !          2918: 
        !          2919: @noindent
        !          2920: produces (in the Info file)
        !          2921: 
        !          2922: @example
        !          2923: To use `foo', pass `xx%$' and FLAG and type `x' after running `make-foo'.
        !          2924: @end example
        !          2925: 
        !          2926: @noindent
        !          2927: whereas without the @code{@@refill} it would produce
        !          2928: 
        !          2929: @example
        !          2930: To use `foo', pass `xx%$' and FLAG and type `x'
        !          2931: after running `make-foo'.
        !          2932: @end example
        !          2933: 
        !          2934: @noindent
        !          2935: with the line broken at the same place as in the Texinfo input file.
        !          2936: 
        !          2937: Do not put a space before @code{@@refill}; otherwise the command might be
        !          2938: put at the beginning of the line when you refill the paragraph in the
        !          2939: Texinfo file with @kbd{M-q} (@code{fill-paragraph}).  If this were to
        !          2940: happen, the @code{@@refill} command might fail to work
        !          2941: 
        !          2942: @node     Noindent, , Refill, Refilling & Noindent
        !          2943: @comment  node-name,  next,  previous,  up
        !          2944: @subsection @@noindent
        !          2945: @findex noindent
        !          2946: 
        !          2947: If you have text following an @code{@@example} or other similar ``special
        !          2948: paragraph'' that reads as a continuation of the text before the
        !          2949: @code{@@example}, it is good to prevent this text from being indented as a
        !          2950: new paragraph.  To accomplish this, put @code{@@noindent} on a line by
        !          2951: itself before the start of the text that should not be indented. For
        !          2952: example,@refill
        !          2953: 
        !          2954: @example
        !          2955: @@example
        !          2956: This is an example
        !          2957: @@end example
        !          2958: 
        !          2959: @@noindent
        !          2960: This line will not be indented.
        !          2961: @end example
        !          2962: 
        !          2963: @noindent
        !          2964: produces
        !          2965: 
        !          2966: @example
        !          2967: This is an example
        !          2968: @end example
        !          2969: 
        !          2970: @noindent
        !          2971: This line will not be indented.
        !          2972: 
        !          2973: To adjust the number of blank lines properly in the Info file output,
        !          2974: remember that the line containing @code{@@noindent} does not generate a
        !          2975: blank line, and neither does the @code{@@end example} line.
        !          2976: 
        !          2977: In the Texinfo source file for this documentation, each of the lines that
        !          2978: says `produces' is preceded by a line containing @code{@@noindent}.
        !          2979: 
        !          2980: @node Breaks Blank-Lines Groups, , Refilling & Noindent, Formatting Paragraphs
        !          2981: @comment  node-name,  next,  previous,  up
        !          2982: @section Breaks, Blank Lines and Groups
        !          2983: 
        !          2984: Texinfo has several commands for making blank lines, for forcing paragraph
        !          2985: and page breaks in the printed manual and for preventing text from running
        !          2986: from one page to the next.
        !          2987: 
        !          2988: @table @code
        !          2989: @item @@*
        !          2990: Force a line break in the printed manual.  This
        !          2991: command has no effect on the Info file.@refill
        !          2992: 
        !          2993: @item @@sp
        !          2994: Generate blank lines in both the printed manual and in the Info file.@refill
        !          2995: 
        !          2996: @item @@br
        !          2997: Force a paragraph break in the printed manual.  This command has no effect
        !          2998: on the Info file.@refill
        !          2999: 
        !          3000: @item @@w
        !          3001: Prevent text from being split across two lines in the printed manual.  This
        !          3002: command has no effect on the Info file.@refill
        !          3003: 
        !          3004: @item @@page
        !          3005: Start a new page in the printed manual.  This
        !          3006: command has no effect on the Info file.@refill
        !          3007: 
        !          3008: @item @@group
        !          3009: Hold text together that must appear on one printed page.  This
        !          3010: command has no effect on the Info file.@refill
        !          3011: 
        !          3012: @item @@need
        !          3013: Start a new printed page if required space not on this one.  This
        !          3014: command has no effect on the Info file.@refill
        !          3015: @end table
        !          3016: 
        !          3017: @menu
        !          3018: * Line Breaks:: Force a line break in the printed manual.
        !          3019: * Sp::         Generate blank lines.
        !          3020: * Br::         Force a paragraph break in the printed manual.
        !          3021: * W::          Prevent a paragraph break in the printed manual.
        !          3022: * Page::       Start a new page in the printed manual.
        !          3023: * Group::      Hold text together that must appear on one printed page.
        !          3024: * Need::       Start a new printed page if required space not on this one.
        !          3025: @end menu
        !          3026: 
        !          3027: 
        !          3028: @node     Line Breaks, Sp, Breaks Blank-Lines Groups, Breaks Blank-Lines Groups
        !          3029: @comment  node-name,  next,  previous,  up
        !          3030: @subsection @@*
        !          3031: @findex asterisk
        !          3032: @findex *
        !          3033: @cindex Line breaks
        !          3034: @cindex Breaks in a line
        !          3035: 
        !          3036: 
        !          3037: @code{@@*} forces a line break in the printed manual.  It has no effect on
        !          3038: the Info file output, where line breaks follow those in the source file.
        !          3039: If you want a line break at a certain spot in both forms of output, break
        !          3040: the line there in the source file and put @code{@@*} at the end of the
        !          3041: line.
        !          3042: 
        !          3043: 
        !          3044: @node     Sp, Br, Line Breaks,  Breaks Blank-Lines Groups
        !          3045: @comment  node-name,  next,  previous,  up
        !          3046: @subsection @@sp
        !          3047: @findex sp (line spacing)
        !          3048: @cindex Spaces from line to line
        !          3049: @cindex Line spacing
        !          3050: 
        !          3051: A line containing @code{@@sp @var{n}} generates @var{n} blank lines of
        !          3052: space in either the printed manual or the Info file.  For example,
        !          3053: 
        !          3054: @example
        !          3055: @@sp 2
        !          3056: @end example
        !          3057: 
        !          3058: @noindent
        !          3059: generates two blank lines.  
        !          3060: 
        !          3061: @node     Br, W, Sp, Breaks Blank-Lines Groups
        !          3062: @comment  node-name,  next,  previous,  up
        !          3063: @subsection @@br
        !          3064: @findex br (paragraph breaks)
        !          3065: @cindex Paragraph breaks
        !          3066: @cindex Breaks in a paragraph
        !          3067: 
        !          3068: In a printed manual, a line containing @code{@@br} forces a paragraph
        !          3069: break; in the Info file output, it does nothing (not even a blank line
        !          3070: results from it).
        !          3071: 
        !          3072: @node     W, Page,  Br, Breaks Blank-Lines Groups
        !          3073: @comment  node-name,  next,  previous,  up
        !          3074: @subsection @@w
        !          3075: @findex w (preventing a line break)
        !          3076: @cindex Line breaks, preventing
        !          3077: 
        !          3078: In a printed manual, @code{@@w@{@var{text}@}} outputs @var{text} and prohibits
        !          3079: line breaks within @var{text}.  @code{@@w} has no effect on the Info file
        !          3080: output; it is the same as would result from just @var{text}.
        !          3081: 
        !          3082: 
        !          3083: @node     Page, Group, W,  Breaks Blank-Lines Groups
        !          3084: @comment  node-name,  next,  previous,  up
        !          3085: @subsection @@page
        !          3086: @cindex Page breaks
        !          3087: @findex page
        !          3088: 
        !          3089: A line containing @code{@@page} starts a new page in a printed manual.  The
        !          3090: line has no effect on Info files since they are not paginated.
        !          3091: 
        !          3092: @node     Group, Need, Page,  Breaks Blank-Lines Groups
        !          3093: @comment  node-name,  next,  previous,  up
        !          3094: @subsection @@group
        !          3095: @cindex Group
        !          3096: @cindex Holding text together vertically
        !          3097: @cindex Vertically holding text together
        !          3098: @findex group
        !          3099: 
        !          3100: A line containing @code{@@group} begins an unsplittable vertical group,
        !          3101: which must appear entirely on one page.  The group is terminated by a line
        !          3102: containing @code{@@end group}.  These two lines produce no output of their
        !          3103: own, and in the Info file output they have no effect at all.
        !          3104: 
        !          3105: If you forget to end a group, you may get strange and unfathomable error
        !          3106: messages when you run @TeX{}.  This is because @TeX{} keeps trying to put
        !          3107: the rest of the Texinfo file into the group and error messages do not start
        !          3108: to get generated until @TeX{} has gone a long way.  It's a good rule of
        !          3109: thumb to look for a missing @code{@@end group} if you get incomprehensible
        !          3110: error messages in @TeX{}.
        !          3111: 
        !          3112: @node     Need, , Group,  Breaks Blank-Lines Groups
        !          3113: @comment  node-name,  next,  previous,  up
        !          3114: @subsection @@need
        !          3115: @cindex Need
        !          3116: @findex need
        !          3117: 
        !          3118: A line containing @code{@@need @var{n}} starts a new page in a printed
        !          3119: manual if fewer than @var{n} mils (thousandths of an inch) remain on the
        !          3120: current page.  The line has no effect on Info files since they are not
        !          3121: paginated.@refill
        !          3122: 
        !          3123: @node Marking Text, Conditionals , Formatting Paragraphs, Top
        !          3124: @comment  node-name,  next,  previous,  up
        !          3125: @chapter Marking Text Within a Paragraph
        !          3126: @cindex Marking text within a paragraph
        !          3127: 
        !          3128: In Texinfo, text within a paragraph can be marked in a variety of ways.
        !          3129: The most important way is to specify whether a word or phrase is a
        !          3130: definition, a metasyntactic variable, a literal example of a program or
        !          3131: what not.
        !          3132: 
        !          3133: In addition, there are special commands for inserting single characters 
        !          3134: that have special meaning in Texinfo, such as braces, and for inserting
        !          3135: symbols with special handling, such as dots and bullets.  Finally, there
        !          3136: are ways to emphasize words.
        !          3137: 
        !          3138: @menu
        !          3139: * Specifying::                 Specifying commands, files and so on.
        !          3140: * Braces Atsigns Periods::     Inserting braces, @samp{@@} and periods.
        !          3141: * Dots Bullets Tex::           Inserting dots, bullets and the @TeX{} logo
        !          3142: * Emphasis::                   Emphasizing text.
        !          3143: @end menu
        !          3144: 
        !          3145: @node Specifying, Braces Atsigns Periods, , Marking Text
        !          3146: @comment  node-name,  next,  previous,  up
        !          3147: @section Specifying Definitions, Files, Commands etc.
        !          3148: @cindex Highlighting
        !          3149: @cindex Specifying commands, files and the like
        !          3150: @cindex Definitions, specifying them within text
        !          3151: @cindex Commands, specifying them within text
        !          3152: @cindex Files, specifying them within text
        !          3153: 
        !          3154: Texinfo has a variety of commands for specifying just what kind of object a
        !          3155: piece of text refers to.  Metasyntactic variables, for example, are marked
        !          3156: by one @@-command and code by another.  Texinfo uses this information to
        !          3157: determine how to highlight the text.  Since the pieces of text are labelled
        !          3158: by commands that tell what kind of object they are, it is easy to change
        !          3159: the way Texinfo formats and typesets such text.  For example, code is
        !          3160: usually illustrated in a typewriter font, but it would be easy to change
        !          3161: the way Texinfo highlights code to use another font.  This change would not
        !          3162: effect how metasyntatic variables are highlighted.  If straight typesetting
        !          3163: commands were used in the body of the file, you would have to check every
        !          3164: single occurrence to make sure that you were changing code and not
        !          3165: something else that should not be changed.
        !          3166: 
        !          3167: In addition, the commands can be used to generate useful information from
        !          3168: the file, such as lists of functions or file names.  It is possible, for
        !          3169: example, to write code in Emacs Lisp (or a keyboard macro) to insert an
        !          3170: index entry after every paragraph that contains the text labelled by a
        !          3171: specified command.  You could do this to construct an index of functions if
        !          3172: you had not already made the entries.
        !          3173: 
        !          3174: The commands serve a variety of purposes:
        !          3175: 
        !          3176: @table @code
        !          3177: @item @@code
        !          3178: Indicates text that is a literal example of a piece of a program.@refill
        !          3179: 
        !          3180: @item @@samp
        !          3181: Indicates text that is a literal example of a sequence of characters.@refill
        !          3182: 
        !          3183: @item @@file
        !          3184: Indicates the name of a file.@refill
        !          3185: 
        !          3186: @item @@kbd
        !          3187: Indicates the names of keys on the keyboard or characters you type.@refill
        !          3188: 
        !          3189: @item @@key
        !          3190: Used for the conventional name for a key on a keyboard.@refill
        !          3191: 
        !          3192: @item @@ctrl
        !          3193: Indicates an ASCII control character.
        !          3194: 
        !          3195: @item @@var
        !          3196: Indicates a metasyntactic variable.
        !          3197: 
        !          3198: @item @@dfn
        !          3199: Indicates the introductory or defining use of a term.
        !          3200: 
        !          3201: @item @@cite
        !          3202: Indicates the name of a book.
        !          3203: @end table
        !          3204: 
        !          3205: 
        !          3206: 
        !          3207: @menu
        !          3208: * Code::       A literal example of a piece of a program.
        !          3209: * Samp::       A literal example of a sequence of characters.
        !          3210: * File::       The name of a file.
        !          3211: * Kbd::                The names of keys or else characters you type.
        !          3212: * Key::                The conventional name for a key on a keyboard.
        !          3213: * Ctrl::       Indicates the ASCII control character.
        !          3214: * Var::                A variable.
        !          3215: * Dfn::                The introductory or defining use of a term.
        !          3216: * Cite::       The name of a book.
        !          3217: @end menu
        !          3218: 
        !          3219: @node     Code, Samp, , Specifying
        !          3220: @comment  node-name,  next,  previous,  up
        !          3221: @subsection @@code
        !          3222: @findex code
        !          3223: 
        !          3224: @code{@@code} is used to indicate text that is a piece of a program which
        !          3225: consists of entire syntactic tokens.  The text follows, enclosed in braces.
        !          3226: 
        !          3227: For example, @code{@@code} is used for an expression in a program, the name
        !          3228: of a variable or function used in a program, or a keyword.  @code{@@code}
        !          3229: is not used for a piece of a token, such as when speaking about the
        !          3230: characters used in a token; for example, when you are explaining what
        !          3231: letters or printable symbols can be used in the names of functions.  It is
        !          3232: also not used for input to programs unless the input is written in a
        !          3233: language that is like a programming language.  For example, it is not used
        !          3234: for the single character commands of GNU Emacs although it is used for the
        !          3235: names of Emacs Lisp functions that the keyboard commands invoke.
        !          3236: 
        !          3237: You should also @code{@@code} for command names in command languages that
        !          3238: resemble programming languages, such as Texinfo or the shell.  Note,
        !          3239: however, that @code{@@code} is not used for options such as @samp{-c} when
        !          3240: such options stand alone.  There is some argument as to whether an entire
        !          3241: shell command incorporating an option should be written using @code{@@code}
        !          3242: or @code{@@samp}.@refill
        !          3243: 
        !          3244: It is an error to alter the case of a word inside an @code{@@code}
        !          3245: command.  This is a particularly insidious error if the language being
        !          3246: documented is case sensitive.  If the command is @code{printf}, then
        !          3247: @code{Printf} is a misspelling.  If you do not like having such a command
        !          3248: with lower case at the beginning of a sentence, you may wish to rearrange
        !          3249: the sentence.
        !          3250: 
        !          3251: In the printed manual, @code{@@code} puts the argument in bold face.
        !          3252: In the Info file, it uses `@dots{}' quotation.  For example:
        !          3253: 
        !          3254: @example
        !          3255: To compare two files, showing text inserted or removed, use @@code@{diff@}.
        !          3256: @end example
        !          3257: 
        !          3258: @noindent
        !          3259: produces
        !          3260: 
        !          3261: @quotation
        !          3262: To compare two files, showing text inserted or removed, use @code{diff}.
        !          3263: @end quotation
        !          3264: 
        !          3265: @iftex
        !          3266: In the Info file, it looks like this:
        !          3267: 
        !          3268: @example
        !          3269: @dots{}, use `diff'
        !          3270: @end example
        !          3271: @end iftex
        !          3272: 
        !          3273: @node     Samp, File, Code, Specifying
        !          3274: @comment  node-name,  next,  previous,  up
        !          3275: @subsection @@samp
        !          3276: @findex samp
        !          3277: 
        !          3278: @code{@@samp} is used to indicate text that is a literal example of a
        !          3279: sequence of characters in a file, string, pattern, etc.  The text follows,
        !          3280: enclosed in braces.  The argument appears within `@dots{}' quotation in
        !          3281: both the Info file and the printed manual; in addition, it is printed in a
        !          3282: fixed-width font.
        !          3283: 
        !          3284: @example
        !          3285: To match @@samp@{foo@} at the end of the line, use the regexp @@samp@{foo$@}.
        !          3286: @end example
        !          3287: 
        !          3288: @noindent
        !          3289: produces
        !          3290: 
        !          3291: @quotation
        !          3292: To match @samp{foo} at the end of the line, use the regexp @samp{foo$}.
        !          3293: @end quotation
        !          3294: 
        !          3295: Any time you are referring to single characters, you should use @code{@@samp}
        !          3296: unless @code{@@kbd} is more appropriate.  Basically, @code{@@samp} is a
        !          3297: catchall for whatever is not covered by @code{@@code}, @code{@@file},
        !          3298: @code{@@kbd}.
        !          3299: 
        !          3300: Punctuation marks that are part of the English text that surrounds the
        !          3301: strings you are specifying are @emph{never} included within the braces.  In
        !          3302: the following sentence, for example, the commas and period are outside of
        !          3303: the braces:
        !          3304: 
        !          3305: @example
        !          3306: A symbol name ends in @@samp@{a@}, @@samp@{b@}, or @@samp@{c@}.
        !          3307: @end example
        !          3308: 
        !          3309: @node     File, Kbd, Samp, Specifying
        !          3310: @comment  node-name,  next,  previous,  up
        !          3311: @subsection @@file
        !          3312: @findex file
        !          3313: 
        !          3314: @code{@@file} is used to indicate text that is the name of a file or
        !          3315: directory.  Currently, it is equivalent to @code{@@samp} in its effects on
        !          3316: the output.  For example,@refill
        !          3317: 
        !          3318: @example
        !          3319: The @@file@{.el@} files are in 
        !          3320: the @@file@{/gnu/emacs/lisp@} directory.
        !          3321: @end example
        !          3322: 
        !          3323: @noindent
        !          3324: produces
        !          3325: 
        !          3326: @quotation
        !          3327: The @file{.el} files are in 
        !          3328: the @file{/gnu/emacs/lisp} directory.
        !          3329: @end quotation
        !          3330: 
        !          3331: @node     Kbd, Key, File, Specifying
        !          3332: @comment  node-name,  next,  previous,  up
        !          3333: @subsection @@kbd
        !          3334: @findex kbd
        !          3335: 
        !          3336: @code{@@kbd} is used much like @code{@@code}.  The difference is that
        !          3337: @code{@@kbd} is for names of keys on the keyboard, or of characters you can
        !          3338: type.  For example, to refer to the command @kbd{M-a}, you would use
        !          3339: 
        !          3340: @example
        !          3341: @@kbd@{M-a@}
        !          3342: @end example
        !          3343: 
        !          3344: @noindent
        !          3345: and to refer to @kbd{M-x shell}, you would use
        !          3346: 
        !          3347: @example
        !          3348: @@kbd@{M-x shell@}
        !          3349: @end example
        !          3350: 
        !          3351: The @code{@@kbd} command has the same effect as @code{@@code} in Info,
        !          3352: but may produce a different font in a printed manual.@refill
        !          3353: 
        !          3354: You can embed another @@-command inside the braces of a @code{@@kbd}
        !          3355: command.  This is the way to describe a command that would be described
        !          3356: more verbosely as ``press an @samp{r} and then press the @key{RET} key'':
        !          3357: 
        !          3358: @example
        !          3359: @@kbd@{r @@key@{RET@}@}  
        !          3360: @end example
        !          3361: 
        !          3362: @noindent
        !          3363: This produces: @kbd{r @key{RET}}
        !          3364: 
        !          3365: You also use the @code{@@kbd} command if you are spelling out the letters
        !          3366: you type; for example:
        !          3367: 
        !          3368: @example
        !          3369: To give the @@code@{logout@} command, 
        !          3370: type the characters @@kbd@{l o g o u t @@key@{RET@}@}.
        !          3371: @end example
        !          3372: 
        !          3373: @noindent
        !          3374: This produces
        !          3375: 
        !          3376: @quotation
        !          3377: To give the @code{logout} command, 
        !          3378: type the characters @kbd{l o g o u t @key{RET}}.
        !          3379: @end quotation
        !          3380: 
        !          3381: @node     Key, Ctrl, Kbd, Specifying
        !          3382: @comment  node-name,  next,  previous,  up
        !          3383: @subsection @@key
        !          3384: @findex key
        !          3385: 
        !          3386: @code{@@key} is used for the conventional name for a key on a keyboard, as
        !          3387: in
        !          3388: 
        !          3389: @example
        !          3390: @@key@{RET@}
        !          3391: @end example
        !          3392: 
        !          3393: Often, @code{@@key} is used within the argument of a @code{@@kbd}
        !          3394: command, whenever the sequence of characters to be typed includes one or
        !          3395: more keys that are described by name.@refill
        !          3396: 
        !          3397: For example, to produce @kbd{C-x @key{ESC}} you would use 
        !          3398: 
        !          3399: @example
        !          3400: @@kbd@{C-x @@key@{ESC@}@}
        !          3401: @end example
        !          3402: 
        !          3403: 
        !          3404: The recommended names to use for keys are in upper case and are
        !          3405: 
        !          3406: @table @t
        !          3407: @item SPC
        !          3408: Space.
        !          3409: @item RET
        !          3410: Return.
        !          3411: @item LFD
        !          3412: Linefeed.
        !          3413: @item TAB
        !          3414: Tab.
        !          3415: @item BS
        !          3416: Backspace.
        !          3417: @item ESC
        !          3418: Escape.
        !          3419: @item DEL
        !          3420: Delete.
        !          3421: @item SFT
        !          3422: Shift.
        !          3423: @item CTL
        !          3424: Control.
        !          3425: @item META
        !          3426: Meta.
        !          3427: @end table
        !          3428: 
        !          3429: There are subtleties to handling words like `meta' or `ctrl' which are
        !          3430: names of shift keys.  When mentioning a character in which the shift key is
        !          3431: used, such as @kbd{Meta-a}, use the @code{@@kbd} command alone without the
        !          3432: @code{@@key} command, but when you are referring to shift key in isolation,
        !          3433: use the @code{@@key} command.  For example, you would use
        !          3434: @samp{@@kbd@{Meta-a@}} to produce @kbd{Meta-a} and @samp{@@key@{META@}} to
        !          3435: produce @key{META}.
        !          3436: 
        !          3437: @node     Ctrl, Var, Key, Specifying
        !          3438: @comment  node-name,  next,  previous,  up
        !          3439: @subsection @@ctrl
        !          3440: @findex ctrl
        !          3441: 
        !          3442: @code{@@ctrl} is used to describe an ASCII control character.  The pattern
        !          3443: of usage is @code{@@ctrl@{@var{ch}@}}, where @var{ch} is an ASCII character
        !          3444: whose control-equivalent is wanted.  Thus, you put in an @samp{f} when
        !          3445: you want to indicate a @samp{control-f}
        !          3446: 
        !          3447: Thus, to specify @samp{control-f}, you would enter
        !          3448: 
        !          3449: @example
        !          3450: @@ctrl@{f@}
        !          3451: @end example
        !          3452: 
        !          3453: @noindent
        !          3454: which produces
        !          3455: 
        !          3456: @quotation
        !          3457: @ctrl{f}
        !          3458: @end quotation
        !          3459: 
        !          3460: In the Info file, this generates the specified control character, output
        !          3461: literally into the file.  This is done so a user can copy the specified
        !          3462: control character (along with whatever else he or she wants) into another
        !          3463: Emacs buffer and use it.  Since the `control-h',`control-i', and
        !          3464: `control-j' characters are formatting characters, they should not be
        !          3465: indicated this way.@refill
        !          3466: 
        !          3467: In a printed manual, this generates text to describe or identify that
        !          3468: control character: an uparrow followed by the character @var{ch}.
        !          3469: 
        !          3470: @node     Var, Dfn, Ctrl, Specifying
        !          3471: @comment  node-name,  next,  previous,  up
        !          3472: @subsection @@var
        !          3473: @findex var
        !          3474: 
        !          3475: @code{@@var} is used to indicate metasyntactic variables.  A metasyntactic
        !          3476: variable is something that stands for another piece of text.  You would use
        !          3477: a metasyntactic variable in the documentation of a function to describe the
        !          3478: arguments that are passed to that function.
        !          3479: 
        !          3480: @code{@@var} is not used for names of particular variables in programming
        !          3481: languages.  For example, the Texinfo variable @code{texinfo-tex-command} is
        !          3482: not a metasyntactic variable.
        !          3483: 
        !          3484: Its effect in the Info file is to upcase the argument; in the printed
        !          3485: manual, to italicize it.  Example:
        !          3486: 
        !          3487: @example
        !          3488: To delete file @@var@{filename@}, type @@code@{rm @@var@{filename@}@}.
        !          3489: @end example
        !          3490: 
        !          3491: @noindent
        !          3492: produces
        !          3493: 
        !          3494: @quotation
        !          3495: To delete file @var{filename}, type @code{rm @var{filename}}.
        !          3496: @end quotation
        !          3497: 
        !          3498: In some documentation styles, metasyntactic variables are shown with angle
        !          3499: brackets, for example: 
        !          3500: 
        !          3501: @example
        !          3502: @dots{}, type rm <filename>
        !          3503: @end example
        !          3504: 
        !          3505: @node     Dfn, Cite, Var, Specifying
        !          3506: @comment  node-name,  next,  previous,  up
        !          3507: @subsection @@dfn
        !          3508: @findex dfn
        !          3509: 
        !          3510: @code{@@dfn} is used to identify the introductory or defining use of a
        !          3511: technical term.  The command should be used only in a passage whose purpose
        !          3512: is to introduce a term which will be used again or which the reader ought
        !          3513: to know.  Mere passing mention of a term for the first time doesn't deserve
        !          3514: @code{@@dfn}.  It generates italics in the printed manual, and double
        !          3515: quotation marks in the Info file.  Example:
        !          3516: 
        !          3517: @example
        !          3518: Getting rid of a file is called @@dfn@{deleting@} it.
        !          3519: @end example
        !          3520: 
        !          3521: @noindent
        !          3522: produces
        !          3523: 
        !          3524: @quotation
        !          3525: Getting rid of a file is called @dfn{deleting} it.
        !          3526: @end quotation
        !          3527: 
        !          3528: @node     Cite, , Dfn, Specifying
        !          3529: @comment  node-name,  next,  previous,  up
        !          3530: @subsection @@cite
        !          3531: @findex cite
        !          3532: 
        !          3533: @code{@@cite} is used for the name of a book.  It produces italics
        !          3534: in the printed manual, and quotation marks in the Info file.
        !          3535: 
        !          3536: 
        !          3537: @node Braces Atsigns Periods, Dots Bullets Tex, Specifying , Marking Text
        !          3538: @comment  node-name,  next,  previous,  up
        !          3539: @section Inserting Braces, @samp{@@} and Periods
        !          3540: @cindex Inserting braces, @@ and periods
        !          3541: @cindex Braces, inserting
        !          3542: @cindex Periods, inserting
        !          3543: @cindex Single characters,  commands to insert
        !          3544: @cindex Commands to insert single characters
        !          3545: 
        !          3546: @samp{@@} and curly braces are special characters in Texinfo.  This means
        !          3547: that you have to put an @samp{@@} in front of these characters in order to
        !          3548: insert them into text.  
        !          3549: 
        !          3550: Periods are also special.  Depending on whether the period is inside of or
        !          3551: at the end of a sentence, less or more space is inserted after a period in
        !          3552: a typeset manual.  Since it is not always possible for Texinfo to determine
        !          3553: when a period ends a sentence and when it is used in an abbreviation,
        !          3554: special commands are needed.  (Usually, Texinfo figures out how to handle
        !          3555: periods, so you don't have to use the special commands; you just enter a
        !          3556: period as you would if you were using a typewriter, which means you put two
        !          3557: spaces after the period that ends a sentence and after a colon.)@refill
        !          3558: 
        !          3559: @menu
        !          3560: * Inserting an Atsign::                inserting an atsign.
        !          3561: * Insert Left Brace::          Inserting a left brace.
        !          3562: * Insert Colon::               Preventing unintended additional whitespace.
        !          3563: * Insert Period::              Inserting a period that does end a sentence.
        !          3564: @end menu
        !          3565: 
        !          3566: @node Inserting An Atsign, Insert Left Brace, , Braces Atsigns Periods
        !          3567: @comment  node-name,  next,  previous,  up
        !          3568: @subsection @@@@
        !          3569: @findex at-signs
        !          3570: @comment for version 19: this does not work findex @@
        !          3571: 
        !          3572: @code{@@@@} stands for a single @@ in either printed or Info output.
        !          3573: 
        !          3574: @node Insert Left Brace, Insert Colon, Inserting an Atsign, Braces Atsigns Periods
        !          3575: @comment  node-name,  next,  previous,  up
        !          3576: @subsection @@@{
        !          3577: @findex left-braces
        !          3578: @comment for version 19: this does not work findex @{
        !          3579: 
        !          3580: @code{@@@{} stands for a single @{ in either printed or Info output.
        !          3581: 
        !          3582: @subsection @@@}
        !          3583: @findex right-braces
        !          3584: @comment for version 19: this does not work findex @}
        !          3585: 
        !          3586: @code{@@@}} stands for a single @} in either printed or Info output.
        !          3587: 
        !          3588: @node Insert Colon, Insert Period, Insert Left Brace, Braces Atsigns Periods
        !          3589: @comment  node-name,  next,  previous,  up
        !          3590: @subsection @@:
        !          3591: @findex at-sign colons
        !          3592: @comment for version 19: this does not work findex @:
        !          3593: 
        !          3594: @code{@@:}@: is used after a character such as period or colon which
        !          3595: normally causes @TeX{} to increase the width of the following whitespace,
        !          3596: to suppress that effect.  For example, it can be used after periods that
        !          3597: end abbreviations and do not end sentences.  @code{@@:}@: has no effect
        !          3598: on the Info file output.
        !          3599: 
        !          3600: @example
        !          3601: It displays @@code@{Foo:@}@@: at that time.
        !          3602: @end example
        !          3603: 
        !          3604: @noindent
        !          3605: produces
        !          3606: 
        !          3607: @quotation
        !          3608: It displays @code{Foo:}@: at that time.
        !          3609: @end quotation
        !          3610: 
        !          3611: The meanings of @code{@@:}@: and @code{@@.}@: in Texinfo are designed to
        !          3612: work well with the Emacs sentence motion commands.  This means they are
        !          3613: different from their meanings in some other formatting systems that use
        !          3614: @@-commands.
        !          3615: 
        !          3616: @refill
        !          3617: 
        !          3618: @node Insert Period, , Insert Colon, Braces Atsigns Periods
        !          3619: @comment  node-name,  next,  previous,  up
        !          3620: @subsection @@.
        !          3621: @findex at-sign periods
        !          3622: @comment for version 19: this does not work at-sign period
        !          3623: 
        !          3624: @code{@@.}@: stands for a period that really does end a sentence, useful
        !          3625: when @TeX{} would otherwise assume by its heuristics that that is not so.
        !          3626: This happens when there is a single-capital-letter word at the end of a
        !          3627: sentence: @TeX{} normally guesses that it is an abbreviation.
        !          3628: 
        !          3629: In the Info file output, @code{@@.}@: is equivalent to a simple @samp{.}.
        !          3630: The Texinfo program preserves the amount of space that you use, so put
        !          3631: two spaces after a period if you intend it to be the end of a sentence
        !          3632: (as well as using @code{@@.}, if necessary, for the printed manual's sake).
        !          3633: 
        !          3634: @example
        !          3635: Give it to X. Give it to X@@.  Give it to X@@.
        !          3636: @end example
        !          3637: 
        !          3638: @noindent
        !          3639: produces
        !          3640: 
        !          3641: @quotation
        !          3642: Give it to X. Give it to X@.  Give it to X@.
        !          3643: @end quotation
        !          3644: 
        !          3645: @node Dots Bullets Tex, Emphasis, Braces Atsigns Periods, Marking Text
        !          3646: @comment  node-name,  next,  previous,  up
        !          3647: @section Inserting Dots, Bullets and @TeX{}
        !          3648: @cindex Dots, inserting
        !          3649: @cindex Bullets, inserting
        !          3650: @cindex TeX-logo, inserting
        !          3651: @cindex Special typesetting commands
        !          3652: @cindex Typesetting commands for dots and the like
        !          3653: 
        !          3654: An ellipsis, a line of dots, is typeset differently than a string of
        !          3655: periods; more whitespace is put between the dots in the ellipsis than is
        !          3656: put between the periods.  Because of this, a special command is used in
        !          3657: Texinfo for inserting dots.  Also, the trademark, @TeX{}, is typeset in a
        !          3658: special fashion and it needs an @@-command, as does the command for
        !          3659: inserting the copyright symbol.  The @code{@@bullet} command is special,
        !          3660: too.  Each of these commands is followed by a pair of braces, @samp{@{@}},
        !          3661: without any whitespace between the name of the command and the braces.
        !          3662: 
        !          3663: @menu
        !          3664: * Dots::               Inserting dots.
        !          3665: * Bullet::             Inserting bullets.
        !          3666: * Tex::                        Inserting the @TeX{} trademark.
        !          3667: @end menu
        !          3668: 
        !          3669: @node     Dots, Bullet, , Dots Bullets Tex
        !          3670: @comment  node-name,  next,  previous,  up
        !          3671: @subsection @@dots@{@}
        !          3672: @findex dots
        !          3673: @cindex Inserting dots
        !          3674: @cindex Dots, inserting
        !          3675: 
        !          3676: 
        !          3677: @code{@@dots@{@}} generates an ellipsis which is three dots in a row,
        !          3678: appropriately spaced, like this: `@dots{}'.  Do not simply write three
        !          3679: periods in the input file; that would work for the Info file output, but
        !          3680: would produce the wrong amount of space between the periods in the printed
        !          3681: manual.
        !          3682: 
        !          3683: @iftex
        !          3684: Here is an ellipsis: @dots{}
        !          3685: 
        !          3686: Here are three periods in a row: ...
        !          3687: 
        !          3688: The three periods in a row are closer together than the dots in the ellipsis.
        !          3689: 
        !          3690: @end iftex
        !          3691: 
        !          3692: @node     Bullet, Tex, Dots, Dots Bullets Tex
        !          3693: @comment  node-name,  next,  previous,  up
        !          3694: @subsection @@bullet@{@}
        !          3695: @findex bullet
        !          3696: 
        !          3697: @code{@@bullet@{@}} generates a large round dot, or the closest possible
        !          3698: thing to one.
        !          3699: 
        !          3700: Here is a bullet: @bullet{}
        !          3701: 
        !          3702: @node     Tex, , Bullet, Dots Bullets Tex
        !          3703: @comment  node-name,  next,  previous,  up
        !          3704: @subsection @@TeX@{@}
        !          3705: @findex TeX
        !          3706: 
        !          3707: @code{@@TeX@{@}} generates `@TeX{}'.  In a printed manual, this is a special
        !          3708: logo that is different from three ordinary letters.
        !          3709: 
        !          3710: 
        !          3711: 
        !          3712: @node     Emphasis, , Dots Bullets Tex, Marking Text
        !          3713: @comment  node-name,  next,  previous,  up
        !          3714: @section Emphasizing Text
        !          3715: @cindex  Emphasizing text
        !          3716: 
        !          3717: Usually, Texinfo changes the font automatically to mark words in the text
        !          3718: according to what category the words belong to.  The @code{@@code} command,
        !          3719: for example, does this.  Most often, this is the best way to mark specified
        !          3720: words.  However, sometimes you will want to emphasize text directly.
        !          3721: Texinfo has two ways to do this: commands that tell Texinfo to emphasize
        !          3722: the text but leave the method to the program, and commands that specify the
        !          3723: font to use.  The first method is generally the best and it makes it
        !          3724: possible to change the style of a document without have to re-edit it line
        !          3725: by line.
        !          3726: 
        !          3727: @menu
        !          3728: * Emph and Strong::    Emphasizing text.
        !          3729: * Fonts::              Selecting italic, bold or typewriter fonts.
        !          3730: @end menu
        !          3731: 
        !          3732: @node     Emph and Strong, Fonts, , Emphasis
        !          3733: @comment  node-name,  next,  previous,  up
        !          3734: @subsection @@emph and @@strong
        !          3735: @findex emph
        !          3736: @findex strong
        !          3737: 
        !          3738: @code{@@emph} and @code{@@strong} are two forms of emphasis.  @code{@@strong}
        !          3739: is stronger.
        !          3740: 
        !          3741: In printed output, @code{@@emph} produces @emph{italics} and @code{@@strong}
        !          3742: produces @strong{bold}.
        !          3743: 
        !          3744: In the Info file, both of these commands put asterisks around the
        !          3745: argument.
        !          3746: 
        !          3747: @node     Fonts, , Emph and Strong, Emphasis
        !          3748: @comment  node-name,  next,  previous,  up
        !          3749: @subsection @@i,  @@b and @@t
        !          3750: @findex i (italic font)
        !          3751: @findex b (bold font)
        !          3752: @findex t (typewriter font)
        !          3753: 
        !          3754: These three commands specify font changes in the printed manual and have no
        !          3755: effect in the Info file.  @code{@@i} requests @i{italic} font (in some
        !          3756: versions of @TeX{}, a slanted font is used), @code{@@b} requests @b{bold}
        !          3757: face, and @code{@@t} requests the @t{fixed-width} font used by
        !          3758: @code{@@kbd}.  All three commands apply to an argument that follows,
        !          3759: surrounded by braces.@refill
        !          3760: 
        !          3761: If possible, you should avoid using these three commands.  If you find a
        !          3762: need to use one, it probably indicates a lack in the Texinfo language.
        !          3763: 
        !          3764: @node Conditionals, Printing Hardcopy, Marking Text, Top
        !          3765: @comment  node-name,  next,  previous,  up
        !          3766: @chapter Conditionals
        !          3767: @cindex Conditionals
        !          3768: @cindex Ifinfo
        !          3769: @cindex Iftex
        !          3770: @findex ifinfo
        !          3771: @findex iftex
        !          3772: 
        !          3773: 
        !          3774: You may not always be able to use the same text for both the printed manual
        !          3775: and the on-line Info file.  In this case, you can use the conditional
        !          3776: commands to specify which text is for the printed manual and which is for
        !          3777: the Info file.
        !          3778: 
        !          3779: @code{@@ifinfo} begins text that should be ignored by @TeX{} when it
        !          3780: typesets the printed manual.  The text appears only in the Info file.  The
        !          3781: @code{@@ifinfo} command should appear on a line by itself.  End the
        !          3782: info-only text with a line containing @code{@@end ifinfo} by itself.  At
        !          3783: the beginning of a Texinfo file, the Info permissions are contained within a
        !          3784: region marked by @code{@@ifinfo} and @code{@@end ifinfo}.@refill
        !          3785: 
        !          3786: Likewise, @code{@@iftex} and @code{@@end iftex} lines delimit text that
        !          3787: will not appear in the Info file but will appear in the printed manual.@refill
        !          3788: 
        !          3789: For example, 
        !          3790: 
        !          3791: @example
        !          3792: @@iftex
        !          3793: This text will appear only in the printed manual.
        !          3794: @@end iftex
        !          3795: 
        !          3796: 
        !          3797: @@ifinfo
        !          3798: However, this text will appear only in the info manual.
        !          3799: @@end ifinfo
        !          3800: @end example
        !          3801: 
        !          3802: @noindent
        !          3803: The preceding example produces the following.  Note how you only see one of
        !          3804: the two lines, depending on whether you are reading the on-line Info version
        !          3805: or the printed version of this manual.
        !          3806: 
        !          3807: 
        !          3808: @iftex
        !          3809: This text will appear only in the printed manual.
        !          3810: @end iftex
        !          3811: 
        !          3812: @ifinfo
        !          3813: However, this text will appear only in the info manual.
        !          3814: @end ifinfo
        !          3815: 
        !          3816: The @code{@@titlepage} command is a special variant of @code{@@iftex} that
        !          3817: is used for making the title and copyright pages of the printed manual.
        !          3818: 
        !          3819: @menu
        !          3820: * Using Tex Commands::         Using commands from regular @TeX{}.
        !          3821: @end menu
        !          3822: 
        !          3823: @node Using Tex Commands, , Conditionals, Conditionals    
        !          3824: @comment  node-name,  next,  previous,  up
        !          3825: @section Using @TeX{} Commands
        !          3826: @cindex  Using TeX commands
        !          3827: @cindex TeX commands, using them
        !          3828: 
        !          3829: Inside a region delineated by @code{@@iftex} and @code{@@end iftex}, you
        !          3830: can embed ordinary @TeX{} commands.  Info will ignore these commands since
        !          3831: they are only in that part of the file that is seen by @TeX{}.  The @TeX{}
        !          3832: commands are the same as any @TeX{} commands except that an @samp{@@}
        !          3833: replaces the @samp{\} used by @TeX{}.  For example, in the
        !          3834: @code{@@titlepage} section of a Texinfo file, the @TeX{} command
        !          3835: @code{@@vskip} is used to format the copyright page.@refill
        !          3836: 
        !          3837: You can enter @TeX{} completely, and use @samp{\} in the @TeX{} commands by
        !          3838: delineating a region with the @code{@@tex} and @code{@@end tex} commands.
        !          3839: (These commands automatically put the region inside of @code{@@iftex} and
        !          3840: @code{@@end iftex} commands.)  For example,@refill
        !          3841: 
        !          3842: @example
        !          3843: @@tex
        !          3844: Here you would put text with @TeX{} commands;
        !          3845: such as $\bigl(x\in A(n)\bigm|x\in B(n)\bigr)$
        !          3846: that will appear only  in the printed manual.
        !          3847: @@end tex
        !          3848: @end example
        !          3849: 
        !          3850: @noindent
        !          3851: In the Info file, nothing between @code{@@tex} and @code{@@end tex} will
        !          3852: appear.@refill
        !          3853: 
        !          3854: @iftex
        !          3855: In the printed manual, the mathematics will look like this:
        !          3856: 
        !          3857: @tex
        !          3858: $\bigl(x\in A(n)\bigm|x\in B(n)\bigr)$
        !          3859: @end tex
        !          3860: @end iftex
        !          3861: 
        !          3862: @node Printing Hardcopy, Creating an Info File, Conditionals, Top
        !          3863: @comment  node-name,  next,  previous,  up
        !          3864: @chapter Printing Hardcopy
        !          3865: @cindex Printing hardcopy
        !          3866: @cindex Hardcopy, printing it
        !          3867: @cindex Making a printed manual
        !          3868: @cindex Sorting indices
        !          3869: @cindex Indices, sorting
        !          3870: @findex texindex (for sorting indices)
        !          3871: 
        !          3872: There are three shell commands for printing a hardcopy of a Texinfo file.
        !          3873: One is for formatting the file, the second is for sorting the index and the
        !          3874: third is for printing the formatted document.  When you use the shell
        !          3875: commands, you can either work directly in the operating system shell or
        !          3876: work within a shell inside of GNU Emacs.
        !          3877: 
        !          3878: The typesetting program @TeX{} is used for formatting a Texinfo file.
        !          3879: @TeX{} is a very powerful typesetting program and, if used right, does an
        !          3880: exceptionally good job.  The @@-commands in a Texinfo file are translated
        !          3881: by a file called @file{texinfo.tex} into commands that @TeX{} understands.
        !          3882: (That is why the beginning of every Texinfo file starts with the line that
        !          3883: says @samp{\input texinfo}; this command tells @TeX{} to use the
        !          3884: @file{texinfo.tex} file in processing the Texinfo file.  Customarily,
        !          3885: @file{texinfo.tex} is in a directory called @file{/usr/lib/tex/macros}.)
        !          3886: @code{texinfo-format-buffer} reads the very same @@-commands in the Texinfo
        !          3887: file and processes them differently from @TeX{} to make an Info
        !          3888: file.@refill
        !          3889: 
        !          3890: Usually, the @TeX{} formatting command is the shell command @code{tex}
        !          3891: followed by the name of the Texinfo file.  The @TeX{} command produces a
        !          3892: formatted DVI file as well as several auxiliary files containing indices,
        !          3893: cross references, etc.  The DVI file (for @dfn{DeVice Independent} file)
        !          3894: can be printed on a wide variety of printers.@refill
        !          3895: 
        !          3896: The @TeX{} formatting command itself does not sort the indices.  This is a
        !          3897: misfeature of @TeX{}.  Hence, to generate a printed index, you first need a
        !          3898: sorted index to work from.@refill
        !          3899: 
        !          3900: @TeX{} outputs raw, unsorted index files under names that obey a standard
        !          3901: convention.  These names are the name of your main input file to @TeX{},
        !          3902: with everything after the first period thrown away, and the two letter
        !          3903: names of indices added at the end.  For example, the raw index output files
        !          3904: for the input file @file{foo.texinfo} would be @file{foo.cp},
        !          3905: @file{foo.vr}, @file{foo.fn}, @file{foo.tp}, @file{foo.pg} and
        !          3906: @file{foo.ky}.  Those are exactly the arguments to give to @code{texindex}.
        !          3907: Or else, you can use @samp{??} as ``wild-cards'' and give the command in
        !          3908: this form:@refill
        !          3909: 
        !          3910: @example
        !          3911: texindex foo.??
        !          3912: @end example
        !          3913: 
        !          3914: For each file specified, @code{texindex} generates a sorted index file
        !          3915: whose name is made by appending @samp{s} to the input file name.  The
        !          3916: @code{@@printindex} command knows to look for a file of that name.
        !          3917: @code{texindex} does not alter the raw index output file. After you have
        !          3918: sorted the indices, you need to rerun the @TeX{} command on the Texinfo
        !          3919: file.  This regenerates a formatted DVI file with the index entries in the
        !          3920: correct order.@refill
        !          3921: 
        !          3922: To summarize, this is a three step process:
        !          3923:  
        !          3924: @enumerate
        !          3925: @item 
        !          3926: Run the @TeX{} command on the Texinfo file.  This generates the formatted
        !          3927: DVI file as well as the raw index files with two letter extensions.@refill
        !          3928: 
        !          3929: @item 
        !          3930: Run the shell command @code{texindex} on the raw index files to sort them.
        !          3931: The arguments to @code{texindex} are the names of the raw index files.
        !          3932: @code{texindex} creates sorted index files whose names are the names of the
        !          3933: raw index files with an @samp{s} appended.  To cause @code{texindex} to
        !          3934: sort all the raw index files, append @samp{??} to the Texinfo file name in
        !          3935: place of the @file{.texinfo} extension.@refill
        !          3936: 
        !          3937: @item 
        !          3938: Rerun the @TeX{} command on the Texinfo file.  This regenerates a formatted
        !          3939: DVI file with the index entries in the correct order.  This second run also
        !          3940: makes all the cross references correct as well.  (The tables of contents
        !          3941: are always correct.)@refill
        !          3942: @end enumerate
        !          3943: 
        !          3944: You need not run @code{texindex} after each @TeX{} run.  If you don't, the
        !          3945: next @TeX{} run will use whatever sorted index files happen to exist from
        !          3946: the previous use of @code{texindex}.  This is usually ok while you are
        !          3947: debugging.
        !          3948: 
        !          3949: Finally, the document can be printed out with the DVI print command
        !          3950: (a shell command).  Depending on the system used, the DVI print command
        !          3951: will be a command such as @code{lpr -d}.  The DVI print command may require
        !          3952: a file name without any extension or with a @samp{.dvi} extension.
        !          3953: 
        !          3954: The following commands, for example, sort the indices, format and print
        !          3955: the @cite{Bison Manual} (where @samp{%} is the shell prompt):
        !          3956: 
        !          3957: @example
        !          3958: % tex bison.texinfo
        !          3959: % texindex bison.??
        !          3960: % tex bison.texinfo
        !          3961: % lpr -d bison.dvi
        !          3962: @end example
        !          3963: 
        !          3964: @noindent
        !          3965: (Remember that the words for the shell commands may be different at your
        !          3966: site; but these are commonly used versions.)
        !          3967: 
        !          3968: It is often most convenient to give formatting and printing commands from a
        !          3969: shell within GNU Emacs.  This way, you can easily keep track of errors.  To
        !          3970: create a shell within Emacs, type @kbd{M-x shell}.  In this shell, you can
        !          3971: format and print the document.  You can switch to and from this shell while
        !          3972: it is running and do other things.  If you are formatting a very long
        !          3973: document on a slow machine, this can be very convenient; on a VAX 750, for
        !          3974: example, formatting often takes 8 seconds or more per page depending on how
        !          3975: loaded the computer is.  Faster machines take correspondingly less time.
        !          3976: 
        !          3977: @menu
        !          3978: * Requirements::       Formatting requirements.
        !          3979: * Compile-Command::    Formatting with the compile command.
        !          3980: @end menu
        !          3981: 
        !          3982: @node     Requirements, Compile-Command, , Printing Hardcopy
        !          3983: @comment  node-name,  next,  previous,  up
        !          3984: @section Formatting Requirements
        !          3985: @cindex Requirements for formatting 
        !          3986: @cindex Formatting requirements
        !          3987: 
        !          3988: Every Texinfo file that is to be input to @TeX{} must begin with a line
        !          3989: that looks like
        !          3990: 
        !          3991: @example
        !          3992: \input texinfo   @@c -*-texinfo-*-
        !          3993: @end example
        !          3994: 
        !          3995: @noindent
        !          3996: This serves two functions.
        !          3997: 
        !          3998: @enumerate
        !          3999: @item
        !          4000: When the file is processed by @TeX{}, it loads the macros needed for
        !          4001: processing a Texinfo file.@refill
        !          4002: @item
        !          4003: When the file is edited in Emacs, it causes Texinfo mode to be used.@refill
        !          4004: @end enumerate
        !          4005: 
        !          4006: Every Texinfo file must end with a line saying
        !          4007: 
        !          4008: @example
        !          4009: @@bye
        !          4010: @end example
        !          4011: 
        !          4012: which terminates @TeX{} processing and forces out unfinished pages.
        !          4013: 
        !          4014: You also have to include two lines that specify the Info file name and the
        !          4015: title of the printed manual:
        !          4016: 
        !          4017: @example
        !          4018: @@setfilename @var{name-of-texinfo-file}
        !          4019: @@settitle @var{Name of Manual}
        !          4020: @end example
        !          4021: 
        !          4022: You might also want to include a line saying
        !          4023: 
        !          4024: @example
        !          4025: @@setchapternewpage odd
        !          4026: @end example
        !          4027: 
        !          4028: @noindent
        !          4029: to cause each chapter to start on a fresh odd-numbered page.
        !          4030: 
        !          4031: By default, @TeX{} typesets pages for printing in an 8.5 by 11 inch
        !          4032: format.  However, you can direct @TeX{} to typeset a document in a 7 by
        !          4033: 9.25 inch format that is suitable for bound books by inserting the
        !          4034: following command on a line by itself at the beginning of the Texinfo
        !          4035: file, before the @code{@@setchapternewpage} command:
        !          4036: 
        !          4037: @example
        !          4038: @@smallbook
        !          4039: @end example
        !          4040: 
        !          4041: @noindent
        !          4042: The Free Software Foundation distributes printed copies of the @cite{GNU
        !          4043: Emacs Manual} in this size.
        !          4044: 
        !          4045: Finally, @TeX{} sometimes is unable to typeset a line without extending
        !          4046: it into the right margin.  This can occur when @TeX{} comes upon what it
        !          4047: interprets as a long word that it cannot hyphenate, like a net address,
        !          4048: or a very long title.  When this happens, @TeX{} prints an error message
        !          4049: like this:
        !          4050: 
        !          4051: @example
        !          4052: Overfull \hbox (20.76302pt too wide)
        !          4053: @end example
        !          4054: 
        !          4055: @noindent
        !          4056: and gives the line number along with the text of the offending line
        !          4057: marked at all the places that @TeX{} knows to hyphenate words.  (In
        !          4058: @TeX{} lines are in `horizontal boxes', hence the term, `hbox'.)
        !          4059: 
        !          4060: If the Texinfo file has an overfull hbox, you can rewrite the sentence
        !          4061: so the overfull hbox does not occur or you can decide to leave it.  A
        !          4062: small excursion into the right margin often does not matter and may not
        !          4063: even be noticable.  However, unless told otherwise, @TeX{} will print a
        !          4064: large, ugly, black rectangle beside every line that is overfull.  This is
        !          4065: so you will notice the location of the problem if you are correcting a
        !          4066: draft.  To prevent such monstrosities from marring your final printout,
        !          4067: put the following in the beginning of the Texinfo file on lines of their
        !          4068: own, before the @code{@@setchapternewpage} command:
        !          4069: 
        !          4070: @example
        !          4071: @@iftex
        !          4072: @@finalout
        !          4073: @@end iftex
        !          4074: @end example
        !          4075: 
        !          4076: @xref{Titlepage}, for information about creating a title page.
        !          4077: @xref{Contents}, for information about creating a table of contents.@refill
        !          4078: 
        !          4079: @node     Compile-Command, , Requirements, Printing Hardcopy
        !          4080: @comment  node-name,  next,  previous,  up
        !          4081: @section Using Local Variables and the Compile Command
        !          4082: @cindex Local variables
        !          4083: @cindex Compile command for formatting
        !          4084: @cindex Formatting with the compile command
        !          4085: 
        !          4086: Another way to give the @TeX{} formatting command to Texinfo is to put that
        !          4087: command in a @dfn{local variables list} at the end of the Texinfo file.
        !          4088: You can then specify the @TeX{} formatting command as a
        !          4089: @code{compile-command} and have Emacs run the @TeX{} formatting command by
        !          4090: giving the command @kbd{M-x compile}.  This creates a special shell called
        !          4091: the @samp{*compilation buffer*}.  For example, at the end of the
        !          4092: @file{gdb.texinfo} file, after the @code{@@bye}, you would put the
        !          4093: following:@refill
        !          4094: 
        !          4095: @example
        !          4096: @@c Local Variables:
        !          4097: @@c compile-command: "tex gdb.texinfo"
        !          4098: @@c End:
        !          4099: @end example
        !          4100: 
        !          4101: @noindent
        !          4102: This technique is most often used by programmers who compile programs
        !          4103: this way.
        !          4104:      
        !          4105: @node Creating an Info File, Catching Mistakes, Printing Hardcopy, Top
        !          4106: @comment  node-name,  next,  previous,  up
        !          4107: @chapter Creating an On-line Info file
        !          4108: @cindex Creating an on-line Info file
        !          4109: @cindex Running Info
        !          4110: @cindex Info, creating an on-line file
        !          4111: @cindex Formatting a file for Info
        !          4112: @cindex Indirect subfiles
        !          4113: @findex texinfo-format-buffer
        !          4114: 
        !          4115: In GNU Emacs, using Texinfo mode, you can see what part or all of a Texinfo
        !          4116: file will look like in Info by using the keyboard command @kbd{C-c C-f}
        !          4117: (@code{texinfo-format-region}).  This formats a region and displays in a
        !          4118: temporary buffer called @samp{*Info Region*}; however, this command does
        !          4119: not turn on Info reading program---it just displays what the region will
        !          4120: look like.  The @code{texinfo-format-region} command is described more
        !          4121: extensively in the chapter on using Texinfo mode.  @xref{Info on a Region}.
        !          4122: @refill
        !          4123: 
        !          4124: In GNU Emacs, the way to create a working Info file is to visit the file
        !          4125: and invoke
        !          4126: 
        !          4127: @example
        !          4128: @kbd{M-x texinfo-format-buffer}
        !          4129: @end example
        !          4130: 
        !          4131: @noindent
        !          4132: A new buffer is created and the Info file text is generated there.
        !          4133: @kbd{C-x C-s} will save it under the name specified in the
        !          4134: @code{@@setfilename} command.@refill
        !          4135: 
        !          4136: If the Texinfo file has more than 30,000 bytes,
        !          4137: @code{texinfo-format-buffer} will automatically create a @dfn{tag table}
        !          4138: for it.  With a tag table, Info can jump to new nodes more quickly than it
        !          4139: can otherwise.  In addition, if the file has more than 100,000 bytes in it,
        !          4140: @code{texinfo-format-buffer} will split the file into shorter Indirect
        !          4141: subfiles of about 50,000 bytes each.  Files are split so that Info does not
        !          4142: have to make a large buffer to hold the whole of a large Info file;
        !          4143: instead, Info allocates just enough memory for the small, split off file
        !          4144: that is needed at the time.  This way, Emacs avoids wasting memory when you
        !          4145: run Info.  (Before splitting was implemented, Info files were always short
        !          4146: and @dfn{include} files were designed as a way to create a single, large
        !          4147: printed manual out of the smaller Info files. @xref{Include Files}, for
        !          4148: more information.)@refill
        !          4149: 
        !          4150: When the file is split, Info itself works through a shortened version of
        !          4151: the original file that contains the tag table and references to the files
        !          4152: that were split off.  The split off files are called @dfn{indirect} files.
        !          4153: 
        !          4154: The split off files have names that are created by appending @samp{-1},
        !          4155: @samp{-2}, @samp{-3} and so on to the file names specified by the
        !          4156: @code{@@setfilename} command.  The shortened version of the original file
        !          4157: continues to have the name specified by @code{@@setfilename}.
        !          4158: 
        !          4159: At one stage in writing this document, for example, the Info file was saved
        !          4160: as @file{test-texinfo} and that file looked like this:
        !          4161: 
        !          4162: @group
        !          4163: @example
        !          4164: Info file: test-texinfo,    -*-Text-*-
        !          4165: produced by texinfo-format-buffer
        !          4166: from file: new-texinfo-manual.texinfo
        !          4167: 
        !          4168: ^_
        !          4169: Indirect:
        !          4170: test-texinfo-1: 102
        !          4171: test-texinfo-2: 50422
        !          4172: test-texinfo-3: 101300
        !          4173: ^_^L
        !          4174: Tag table:
        !          4175: (Indirect)
        !          4176: Node: overview^?104
        !          4177: Node: info file^?1271
        !          4178: Node: printed manual^?4853
        !          4179: Node: conventions^?6855
        !          4180: @dots{}
        !          4181: @end example
        !          4182: @end group
        !          4183: 
        !          4184: @noindent
        !          4185: (But @file{test-texinfo} had far more nodes than are shown here.)  Each of
        !          4186: the split off, indirect files, @file{test-texinfo-1},
        !          4187: @file{test-texinfo-2}, and @file{test-texinfo-3}, is listed in this file
        !          4188: after the line that says @samp{Indirect:}.  The tag table is listed after
        !          4189: the line that says @samp{Tag table:}. @refill
        !          4190: 
        !          4191: You cannot run the @kbd{M-x Info-validate} node checking command on indirect
        !          4192: files.  For information on how to prevent files from being split and how to
        !          4193: validate the structure of the nodes, @pxref{Info-Validating a Large 
        !          4194: File}@refill
        !          4195: 
        !          4196: @menu
        !          4197: * Installing an Info File::    Putting the Info file in the info directory.
        !          4198: @end menu
        !          4199: 
        !          4200: @node Installing an Info File, , Creating an Info File, Creating an Info File
        !          4201: @comment  node-name,  next,  previous,  up
        !          4202: @section Installing an Info file
        !          4203: @cindex  Installing an Info file
        !          4204: @cindex Info file installation
        !          4205: @cindex Dir directory for Info installation
        !          4206: 
        !          4207: An Info file is usually installed in the GNU Emacs directory called
        !          4208: @file{info}.  For Info to work, this directory must contain all the Info
        !          4209: files, including the split off files.  In addition, the @file{info}
        !          4210: directory must have a file that serves as a top level directory for the
        !          4211: Info system.  This file is called @file{dir}.
        !          4212: 
        !          4213: 
        !          4214: For example, in the @file{info} directory, the file called @file{dir} has
        !          4215: the top level menu for all the Info files in the system.  This file has a
        !          4216: master menu that looks like this:
        !          4217: 
        !          4218: @example
        !          4219: * Menu:
        !          4220: 
        !          4221: * Info:    (info).      Documentation browsing system.
        !          4222: * Emacs:   (emacs).     The extensible self-documenting text editor.
        !          4223: * Texinfo: (texinfo).   With one source file, make either a printed 
        !          4224:                         manual using TeX or an Info file using
        !          4225:                         Texinfo.
        !          4226: @end example
        !          4227: 
        !          4228: To add a new Info file, just add it to this menu.  For example, if you
        !          4229: were adding documentation for GDB, you would make the following entry:
        !          4230: 
        !          4231: @example
        !          4232: * GDB: (gdb).           The source-level C debugger.
        !          4233: @end example
        !          4234: 
        !          4235: @noindent
        !          4236: The first item is the menu item name; it is followed by a colon.  The
        !          4237: second item is the name of the Info file, in parentheses; it is followed by
        !          4238: a period.  The third part of the entry is the description of the item.
        !          4239: 
        !          4240: 
        !          4241: 
        !          4242: The top node of the file, named @samp{top}, should have as its parent the
        !          4243: name of a node in another file, where there is a menu that leads to this
        !          4244: file.  Specify the file name in parentheses.  If the file is to be
        !          4245: installed directly in the Info directory file, use @samp{(dir)} as the
        !          4246: parent of the top node; this is short for @samp{(dir)top}, the node @samp{top}
        !          4247: in the file @file{dir}, which is the main menu of Info.
        !          4248: 
        !          4249: 
        !          4250: 
        !          4251: 
        !          4252: @node     Catching Mistakes, Command Syntax, Creating an Info File, Top
        !          4253: @comment  node-name,  next,  previous,  up
        !          4254: @chapter Catching Mistakes
        !          4255: @cindex Structure of Texinfo, catching mistakes
        !          4256: @cindex Nodes, catching mistakes
        !          4257: @cindex Nodes, correcting mistakes
        !          4258: @cindex Catching mistakes
        !          4259: @cindex Correcting mistakes
        !          4260: @cindex Mistakes, catching
        !          4261: @cindex Problems, catching
        !          4262: @cindex Debugging the Texinfo structure
        !          4263: 
        !          4264: Besides mistakes with the content of what ever you are describing, there
        !          4265: are two kinds of mistake you can make with Texinfo:  you can make mistakes
        !          4266: with @@-commands, and you can make mistakes with the structure of the
        !          4267: nodes and chapters.
        !          4268: 
        !          4269: There are two tools for catching the first kind of mistake and two for
        !          4270: catching the second.
        !          4271: 
        !          4272: For finding problems with @@-commands, your best action is to run @kbd{M-x
        !          4273: texinfo-format-region} on regions of your file as you write it.  In Texinfo
        !          4274: mode, the @code{texinfo-format-region} command is bound to @kbd{C-c C-f}.
        !          4275: In addition, you can run @TeX{} on the whole file.@refill
        !          4276: 
        !          4277: For finding problems with the structure of nodes and chapters, you can use
        !          4278: @kbd{C-c C-s} (@code{texinfo-show-structure}) (and the related @code{occur}
        !          4279: command) and you can use the @kbd{M-x Info-validate} command.
        !          4280: 
        !          4281: 
        !          4282: @menu
        !          4283: * Debugging with Info::            Catching errors with info formatting.
        !          4284: * Debugging with Tex::             Catching errors with @TeX{} formatting.
        !          4285: * Using texinfo-show-structure::    Using @code{texinfo-show-structure}
        !          4286:                                    to catch mistakes.
        !          4287: * Running Info-Validate::          Checking for unreferenced nodes.
        !          4288: @end menu
        !          4289: 
        !          4290: 
        !          4291: @node Debugging with Info, Debugging with Tex, , Catching Mistakes
        !          4292: @comment  node-name,  next,  previous,  up
        !          4293: @section Catching Errors with Info Formatting
        !          4294: @cindex Catching errors with Info Formatting
        !          4295: @cindex Debugging with Info Formatting
        !          4296: 
        !          4297: After you have written part of a Texinfo file, you can use the @kbd{M-x
        !          4298: texinfo-format-region} command to see whether the region formats properly.
        !          4299: In Texinfo mode, this command is bound to the keyboard command @kbd{C-c
        !          4300: C-f}.
        !          4301: 
        !          4302: If you have made a mistake with an @@-command, @kbd{M-x
        !          4303: texinfo-format-region} will stop processing at or after the error and give
        !          4304: an error message.  To see where in the file the error occurred, switch to
        !          4305: the @samp{*Info Region*} buffer; the cursor will be in a position that is
        !          4306: after the location of the error.  Also, the text will not be formatted
        !          4307: after the place the error occurred.@refill
        !          4308: 
        !          4309: For example, if you accidently end a menu with the command @code{@@end
        !          4310: menus} with an `s' on the end, instead of with @code{@@end menu}, you will
        !          4311: get an error message that says:
        !          4312: 
        !          4313: @example
        !          4314: @@end menus is not handled by texinfo.
        !          4315: @end example
        !          4316: 
        !          4317: @noindent
        !          4318: The cursor will stop at the point in the file where the error occurs, or
        !          4319: not long after it.  It will look like this:
        !          4320: 
        !          4321: @group
        !          4322: @example
        !          4323: @@menu
        !          4324: * Using texinfo-show-structure::    Using @code{texinfo-show-structure}
        !          4325:                                     to catch mistakes.
        !          4326: * Running Info-Validate::           Checking for unreferenced nodes.
        !          4327: @@end menus
        !          4328: @end example
        !          4329: @end group
        !          4330: 
        !          4331: The @code{texinfo-format-region} command does not always recognize errors.
        !          4332: For example, no errors were reported when @code{texinfo-format-region} was
        !          4333: run on the whole itemized list of which the following is a part:
        !          4334: 
        !          4335: @example
        !          4336: name of the Texinfo file as an extension.  The @@samp@{??@} are `wildcards'
        !          4337: that cause the shell to substitute all the raw index files.  (@@xref@{sorting
        !          4338: indices), for more information about sorting indices.) @@refill
        !          4339: @@cindex Sorting indices
        !          4340: @@cindex Indices, sorting
        !          4341: 
        !          4342: @@item 
        !          4343: @@emph@{Third@}, rerun the @@TeX@{@} command on the Texinfo file.  This
        !          4344: regenerates a formatted DVI file with the index entries in the correct
        !          4345: order.  This second run also makes all the cross references and table of
        !          4346: contents correct as well.
        !          4347: @end example
        !          4348: 
        !          4349: @noindent
        !          4350: Instead, @code{texinfo-format-region} ran without reporting the error, but
        !          4351: it produced output that looked like this:
        !          4352: 
        !          4353: @example
        !          4354:      name of the texinfo file as an extension.  The `??' are `wildcards'
        !          4355:      that cause the shell to substitute all the raw index files.  (*Note for more information about sorting indices.) @@refill @@cindex Sorting indices @@cindex Indices: sorting indices), rerun the TeX command on the texinfo file.  This
        !          4356:      regenerates a formatted DVI file with the index entries in the correct
        !          4357:      order.  This second run also makes all the cross references and table of
        !          4358:      contents correct as well.
        !          4359: @end example
        !          4360: 
        !          4361: @noindent
        !          4362: However, when @code{texinfo-format-region} was run on part of the list that
        !          4363: is shown, it did give an error message, @samp{Search failed: "[@{,@}"}.  (This
        !          4364: error message is explained in the section on using the Emacs Lisp Debugger, @pxref{Using the Emacs Lisp Debugger})
        !          4365: 
        !          4366: Sometimes @code{texinfo-format-region} will stop long after the original
        !          4367: error;  this is because it does not discover the problem until then.  In this
        !          4368: case, you will have to backtrack.@refill
        !          4369: 
        !          4370: @node Using the Emacs Lisp Debugger, , ,Debugging with Info
        !          4371: @comment  node-name,  next,  previous,  up
        !          4372: @subsection Using the Emacs Lisp Debugger
        !          4373: @cindex Using the Emacs Lisp debugger
        !          4374: @cindex Emacs Lisp debugger
        !          4375: @cindex Debugger, using the Emacs Lisp 
        !          4376: 
        !          4377: If an error is especially elusive, you can turn on the Emacs Lisp debugger
        !          4378: and look at the backtrace; this tells you where in the
        !          4379: @code{texinfo-format-region} function the problem occurred.  You can turn
        !          4380: on the debugger with the command:@refill
        !          4381: 
        !          4382: @example
        !          4383: M-x set-variable @key{RET} debug-on-error @key{RET} t
        !          4384: @end example
        !          4385: 
        !          4386: @noindent
        !          4387: and turn it off with
        !          4388: 
        !          4389: @example
        !          4390: M-x set-variable @key{RET} debug-on-error @key{RET} nil
        !          4391: @end example
        !          4392: 
        !          4393: Often, when you are using the debugger, it is easier to follow what is
        !          4394: going on if you use the Emacs Lisp files that are not byte-compiled.  The
        !          4395: byte-compiled sources send octal numbers to the debugger that may look
        !          4396: mysterious.  To use the uncompiled source files, load @file{texinfmt.el}
        !          4397: and @file{texinfo.el} with the @kbd{M-x load-file} command.@refill
        !          4398: 
        !          4399: The debugger will not catch an error if @code{texinfo-format-region} does
        !          4400: not detect one.  In the example shown above, @code{texinfo-format-region}
        !          4401: did not find the error when the whole list was formatted, but only when
        !          4402: part of the list was formatted.  When @code{texinfo-format-region} did not
        !          4403: find an error, the debugger did not find one either. @refill
        !          4404: 
        !          4405: However, when @code{texinfo-format-region} did report an error, it invoked
        !          4406: the debugger.  This is the backtrace it produced:
        !          4407: 
        !          4408: @example
        !          4409: Signalling: (search-failed "[@},]")
        !          4410:   re-search-forward("[@},]")
        !          4411:   (while ...)
        !          4412:   (let ...)
        !          4413:   texinfo-format-parse-args()
        !          4414:   (let ...)
        !          4415:   texinfo-format-xref()
        !          4416:   funcall(texinfo-format-xref)
        !          4417:   (if ...)
        !          4418:   (let ...)
        !          4419:   (if ...)
        !          4420:   (while ...)
        !          4421:   texinfo-format-scan()
        !          4422:   (save-excursion ...)
        !          4423:   (let ...)
        !          4424:   texinfo-format-region(103370 103631)
        !          4425: * call-interactively(texinfo-format-region)
        !          4426: @end example
        !          4427: 
        !          4428: The backtrace is read from the bottom up.  @code{texinfo-format-region} was
        !          4429: called interactively; and it, in turn, called various functions, including
        !          4430: @code{texinfo-format-scan}, @code{texinfo-format-xref} and
        !          4431: @code{texinfo-format-parse-args}.  Inside the function
        !          4432: @code{texinfo-format-parse-args}, the function @code{re-search-forward} was
        !          4433: called; it was this function that could not find the missing right hand
        !          4434: brace.@refill
        !          4435: 
        !          4436: @xref{Lisp Debug, , Debugging Emacs Lisp, emacs, The GNU Emacs Manual}, for
        !          4437: more information.@refill
        !          4438: 
        !          4439: 
        !          4440: 
        !          4441: @node Debugging with Tex, Using texinfo-show-structure, Debugging with Info, Catching Mistakes
        !          4442: @comment  node-name,  next,  previous,  up
        !          4443: @section Catching Errors with @TeX{} Formatting
        !          4444: @cindex Catching errors with TeX Formatting
        !          4445: @cindex Debugging with TeX Formatting
        !          4446: 
        !          4447: You can also catch mistakes when you format a file with @TeX{}.
        !          4448: 
        !          4449: 
        !          4450: Usually, you will want to do this after you have run
        !          4451: @code{texinfo-format-buffer} on the same file.
        !          4452: @code{texinfo-format-buffer} is usually faster and sometimes gives error
        !          4453: messages that make more sense.  @xref{Debugging with Info}, for more
        !          4454: information.@refill
        !          4455: 
        !          4456: For example, @TeX{} was run on the same itemized list discussed
        !          4457: in the section on the use of  @code{texinfo-format-region}
        !          4458: (@pxref{Debugging with Info}); the fragment with the error looked like
        !          4459: this:
        !          4460: 
        !          4461: @example
        !          4462: name of the texinfo file as an extension.  The @@samp@{??@} are `wildcards'
        !          4463: that cause the shell to substitute all the raw index files.  (@@xref@{sorting
        !          4464: indices, for more information about sorting indices.) @@refill
        !          4465: @end example
        !          4466: 
        !          4467: @noindent
        !          4468: This produced the following output, after which @TeX{} stopped:
        !          4469: 
        !          4470: @example
        !          4471: Runaway argument?
        !          4472: @{sorting indices, for more information about sorting indices.) @@refill @@ETC.
        !          4473: ! Paragraph ended before \xref was complete.
        !          4474: <to be read again> 
        !          4475:                    \par 
        !          4476: l.27 
        !          4477:      
        !          4478: ? 
        !          4479: @end example
        !          4480: 
        !          4481: In this case, @TeX{} produced an accurate and understandable error message:
        !          4482: @samp{Paragraph ended before \xref was complete.} (Note, however, that
        !          4483: @TeX{} translated the @samp{@@} into a @samp{\}.)  Also, @samp{\par} is an
        !          4484: internal @TeX{} command of no relevance to Texinfo.)
        !          4485: 
        !          4486: Unfortunately, @TeX{} is not always so helpful, and sometimes you have to be
        !          4487: truly a Sherlock Holmes to discover what went wrong.
        !          4488: 
        !          4489: In any case, if you run into a problem like this, you can do one of two
        !          4490: things.
        !          4491: 
        !          4492: @enumerate
        !          4493: @item 
        !          4494: You can tell @TeX{} to continue running and to ignore errors 
        !          4495: as best it can by typing @kbd{r @key{RET}} at the 
        !          4496: @samp{?} prompt.@refill
        !          4497: 
        !          4498: This is often the best thing to do.  However, beware: the one error may
        !          4499: produce a cascade of additional error messages as it consequences are felt
        !          4500: through the rest of the file.@refill
        !          4501: 
        !          4502: @item 
        !          4503: You can tell @TeX{} to stop this run by typing @kbd{x @key{RET}} 
        !          4504: at the @samp{?} prompt. 
        !          4505: @end enumerate
        !          4506: 
        !          4507: Sometimes @TeX{} will format a file without producing error messages even
        !          4508: though there is a problem.  This usually occurs if a command is not ended
        !          4509: but @TeX{} is able to continue processing anyhow.  For example, if you fail
        !          4510: to end an itemized list with the @code{@@end itemize} command, @TeX{} will
        !          4511: write a DVI file that you can print out.  The only error message that
        !          4512: @TeX{} will give you is the somewhat mysterious comment that
        !          4513: 
        !          4514: @example
        !          4515: (\end occurred inside a group at level 1)
        !          4516: @end example
        !          4517: 
        !          4518: @noindent
        !          4519: However, if you print the DVI file, you will find that the text of the file
        !          4520: that follows the itemized list is entirely indented as if it were part of
        !          4521: the last item in the itemized list.  The error message is the way @TeX{}
        !          4522: says that it expected to find an @code{@@end} command somewhere in the
        !          4523: file; but that it could not locate where it was needed. @refill
        !          4524: 
        !          4525: Another source of notoriously hard to find errors is a missing @code{@@end
        !          4526: group} command.  If you ever are stumped by incomprehensible errors, look
        !          4527: for a missing @code{@@end group} command first.@refill
        !          4528: 
        !          4529: If you do not have the header lines in the file, @TeX{} may stop in the
        !          4530: beginning of its run and display output that looks like the following.
        !          4531: The @samp{*} indicates that @TeX{} is waiting for input.@refill
        !          4532: 
        !          4533: @example
        !          4534: This is TeX, Version 2.0 for Berkeley UNIX (preloaded format=plain-cm 
        !          4535: 87.10.25) (#tz-bar-a02987.tex [1])
        !          4536: *
        !          4537: @end example
        !          4538: 
        !          4539: @noindent
        !          4540: In this case, simply type @kbd{\end @key{RET}} after the asterisk.  Then
        !          4541: put the header lines into the Texinfo file and run the @TeX{} command
        !          4542: again.@refill
        !          4543: 
        !          4544: 
        !          4545: @node Using texinfo-show-structure, Running Info-Validate, Debugging with Tex, Catching Mistakes
        !          4546: @comment  node-name,  next,  previous,  up
        !          4547: @section Using @code{texinfo-show-structure}
        !          4548: @cindex  Showing the structure of a file
        !          4549: @cindex Using texinfo-show-structure to catch mistakes
        !          4550: @cindex texinfo-show-structure for catching mistakes
        !          4551: @findex texinfo-show-structure
        !          4552: 
        !          4553: It is not always easy to keep track of the nodes, chapters, sections and
        !          4554: subsections of a Texinfo file.  This is especially true if you are revising
        !          4555: or adding to a Texinfo file that someone else has written.
        !          4556: 
        !          4557: In GNU Emacs, in Texinfo mode, there is a command that will list all the
        !          4558: lines that begin with the @@-commands that specify the structure: @@node,
        !          4559: @@chapter, @@section, @@appendix and so on.  This is the
        !          4560: @code{texinfo-show-structure} command.  It is bound to the keyboard command
        !          4561: @kbd{C-c C-s}.  @code{texinfo-show-structure} displays the lines that begin
        !          4562: with the node and chapter structuring @@-commands in another window called
        !          4563: the @samp{*Occur*} buffer.  For example, when @code{texinfo-show-structure}
        !          4564: is run on the first part of this chapter, it produces the following:@refill
        !          4565: 
        !          4566: @example
        !          4567: Lines matching
        !          4568: "^@@\\(chapter\\|unnum\\|appendix\\|sect\\|sub\\|heading\\|major
        !          4569: \\|node\\)" in buffer new-texinfo-manual.texinfo.
        !          4570:   2:@@node     catching mistakes, @@-Command Syntax, running info, top
        !          4571:   4:@@chapter Catching Mistakes
        !          4572:  41:@@node debugging with info, debugging with tex, , catching mistakes
        !          4573:  43:@@section Catching errors with Info Formatting
        !          4574: @end example
        !          4575: 
        !          4576: This means that lines 2, 4, 41 and 43 began with @code{@@node},
        !          4577: @code{@@chapter}, @code{@@node}, and @code{@@section} respectively.  If you
        !          4578: move your cursor into the @samp{*Occur*} window, you can position the
        !          4579: cursor over one of the lines and use the @kbd{C-c C-c} command
        !          4580: (@code{occur-mode-goto-occurrence}), to jump to the corresponding spot in
        !          4581: the Texinfo file. 
        !          4582: @xref{Other Repeating Search, , Using Occur, emacs, The GNU Emacs Manual}, 
        !          4583: for more information about @code{occur-mode-goto-occurrence}.@refill
        !          4584: 
        !          4585: The first line in the @samp{*Occur*} window describes the @dfn{regular
        !          4586: expression} specified by @var{texinfo-heading-pattern}.  This regular
        !          4587: expression is the pattern that @code{texinfo-show-structure} looks for.
        !          4588: @xref{Regexps, , Using Regular Expressions, emacs, The GNU Emacs Manual},
        !          4589: for more information.@refill
        !          4590: 
        !          4591: When you give the @code{texinfo-show-structure} command, it will show the
        !          4592: structure of the whole buffer.  If you want to see the structure of just a
        !          4593: part of the buffer, of one chapter, for example, use the @kbd{C-x n}
        !          4594: (@code{narrow-to-region}) command to mark the region.  (@xref{Narrowing, ,
        !          4595: , emacs, The GNU Emacs Manual}.)  This is how the example used above was
        !          4596: generated.  (To see the whole buffer again, use @kbd{C-x w}
        !          4597: (@code{widen}).)@refill
        !          4598: 
        !          4599: You can remind yourself of the structure of a Texinfo file by looking at
        !          4600: the list in the @samp{*Occur*} window; and if you have mis-named a node
        !          4601: or left out a section, you can correct the mistake.
        !          4602: 
        !          4603: @menu
        !          4604: * Using Occur::
        !          4605: @end menu
        !          4606: 
        !          4607: @node Using Occur, , Using texinfo-show-structure, Using texinfo-show-structure
        !          4608: @comment  node-name,  next,  previous,  up
        !          4609: @subsection Using @code{occur}
        !          4610: @cindex Using occur
        !          4611: @cindex Occur, using the command
        !          4612: 
        !          4613: Sometimes the @code{texinfo-show-structure} command produces too much
        !          4614: information.  Perhaps you want to remind yourself of the overall structure
        !          4615: of a Texinfo file, and are overwhelmed by the detailed list produced by
        !          4616: @code{texinfo-show-structure}.  In this case, you can use the @code{occur}
        !          4617: command itself.  To do this, type
        !          4618: 
        !          4619: @example
        !          4620: @kbd{M-x occur}
        !          4621: @end example
        !          4622: 
        !          4623: @noindent 
        !          4624: and then, when prompted, type a @dfn{regexp}, a regular expression for the
        !          4625: pattern you want to match.  
        !          4626: (@xref{Regexps, , Regular Expressions, emacs, The GNU Emacs Manual}.)
        !          4627: @code{occur} works from the current location of
        !          4628: the cursor in the buffer to the end of the buffer.  If you want to run
        !          4629: @code{occur} on the whole buffer, place the cursor at the beginning of the
        !          4630: buffer.  For example, to see all the lines that contain the word
        !          4631: @samp{@@chapter} in them, just type @samp{@@chapter}.  This will produce a
        !          4632: list of the chapters.  It will also list all the sentences with
        !          4633: @samp{@@chapter} in the middle of the line.  If you want to see only those
        !          4634: lines that start with the word @samp{@@chapter}, type @samp{^@@chapter}
        !          4635: when prompted by @code{occur}.  If you want to see all the lines that end
        !          4636: with a word or phrase, end the last word with a @samp{$}; for example,
        !          4637: @samp{catching mistakes$}.  This can be helpful when you want to see all
        !          4638: the nodes that are part of the same chapter or section and therefore have
        !          4639: the same `Up' pointer.@refill
        !          4640: 
        !          4641: @xref{Other Repeating Search, , Using Occur, emacs , The GNU Emacs Manual},
        !          4642: for more information.@refill
        !          4643: 
        !          4644: @node Running Info-Validate, ,  Using texinfo-show-structure, Catching Mistakes
        !          4645: @comment  node-name,  next,  previous,  up
        !          4646: @section Finding Badly Referenced Nodes
        !          4647: @cindex  Running Info-validate
        !          4648: @cindex  Info-validate,  running the command
        !          4649: @cindex Nodes, checking for badly referenced nodes
        !          4650: @cindex Checking for badly referenced nodes
        !          4651: @cindex Looking for badly referenced nodes
        !          4652: @cindex Finding badly referenced nodes
        !          4653: @cindex Badly referenced nodes 
        !          4654: 
        !          4655: You can check whether any of the `Next', `Previous', `Up' or other node
        !          4656: pointers fail to point to a node with the @code{Info-validate} command.
        !          4657: This command checks that every node pointer points to an existing node.
        !          4658: 
        !          4659: To use this command, you first need to load the @code{info} library and then do
        !          4660: @kbd{M-x Info-validate}.
        !          4661: 
        !          4662: @example
        !          4663: @kbd{M-x load-library @key{RET} info @key{RET}} 
        !          4664: @kbd{M-x Info-validate}
        !          4665: @end example
        !          4666: 
        !          4667: @noindent
        !          4668: (Note that all the @code{Info} commands require an uppercase `I'.)
        !          4669: 
        !          4670: If your file is ok, you will receive a message that says ``File appears
        !          4671: valid''.  However, if you have a pointer that does not point to a node,
        !          4672: error messages will be displayed in a buffer called @samp{*problems in
        !          4673: info file*}.
        !          4674: 
        !          4675: For example, @code{Info-validate} was run on a test file that contained
        !          4676: only the first node of this manual.  One of the messages said:
        !          4677: 
        !          4678: @example
        !          4679: In node "Overview", invalid Next: Texinfo Mode
        !          4680: @end example
        !          4681: 
        !          4682: @noindent
        !          4683: This meant that the node called @samp{Overview} had a `Next' pointer that
        !          4684: did not point to anything (which was true in this case, since the test file
        !          4685: had only one node in it).
        !          4686: 
        !          4687: Now suppose we add a node named @samp{Texinfo Mode} to our test case
        !          4688: but we don't specify a `Previous' for this node.  Then we will get
        !          4689: the following error message:
        !          4690: 
        !          4691: @example
        !          4692: In node "Texinfo Mode", should have Previous: Overview
        !          4693: @end example
        !          4694: 
        !          4695: @noindent
        !          4696: This is because every `Next' pointer should be matched by a
        !          4697: `Previous' (in the node where the `Next' points) which points back.
        !          4698: 
        !          4699: @code{Info-validate} also checks that all menu items and cross-references
        !          4700: point to actual nodes.
        !          4701: 
        !          4702: Significantly, @code{Info-validate} does not work with large files that
        !          4703: have been split.  (Info thinks of a large file as being over 100,000 bytes,
        !          4704: approximately.)  In order to use @code{Info-validate} on a large file, you
        !          4705: must run @code{texinfo-format-buffer} with an argument so that it does not
        !          4706: split the Info file, and then create a tag table.
        !          4707: 
        !          4708: @menu
        !          4709: * Info-Validating a Large File:: Running @code{Info-validate} on a large file.
        !          4710: * Splitting::                    Splitting a file manually.
        !          4711: @end menu
        !          4712: 
        !          4713: @node     Info-Validating a Large File, Splitting, Running Info-Validate, Running Info-Validate
        !          4714: @comment  node-name,  next,  previous,  up
        !          4715: @subsection Running @code{Info-validate} on a Large File.
        !          4716: @cindex Running Info-validate on a large file
        !          4717: @cindex Info validating a large file
        !          4718: @cindex Validating a large file
        !          4719: 
        !          4720: 
        !          4721: You can run @code{Info-validate} only on a single Info file.  The command
        !          4722: will not work on indirect subfiles that are generated when the master file
        !          4723: is split.  If you have a large file (longer than 100,000 bytes), you need
        !          4724: to run the @code{texinfo-format-buffer} command in such a way that it does
        !          4725: not create indirect subfiles.  You will also need to create a tag table.
        !          4726: When you have done this, you can run @code{Info-validate} and look for
        !          4727: badly referenced nodes.@refill
        !          4728: 
        !          4729: After you have validated the node structure, you can rerun
        !          4730: @code{texinfo-format-buffer} in the normal way so it will construct the tag
        !          4731: table and split the file automatically or, you can make the tag table and
        !          4732: split the file manually.@refill
        !          4733: 
        !          4734: To prevent the @code{texinfo-format-buffer} command from splitting a
        !          4735: Texinfo file into smaller Info files, give a prefix to the @kbd{M-x
        !          4736: texinfo-format-buffer} command:
        !          4737: 
        !          4738: @example
        !          4739: C-u  M-x texinfo-format-buffer
        !          4740: @end example
        !          4741: 
        !          4742: @noindent
        !          4743: When you do this, Texinfo will not split the file and will not create a tag
        !          4744: table for it. @refill
        !          4745: @cindex Making a tag table manually
        !          4746: @cindex Tag table, making manually
        !          4747: 
        !          4748: Before you can run @kbd{M-x Info-validate} on the Info file, you need to
        !          4749: create a tag table for it.  In order to do this, you first need to load the
        !          4750: @code{info} library into Emacs with the following command:@refill
        !          4751: 
        !          4752: @example
        !          4753: M-x load-library @key{RET} info @key{RET}
        !          4754: @end example
        !          4755: 
        !          4756: @noindent
        !          4757: Then you can give the command:
        !          4758: 
        !          4759: @example
        !          4760: M-x Info-tagify
        !          4761: @end example
        !          4762: 
        !          4763: This creates a file which you can validate.@refill
        !          4764: 
        !          4765: @example
        !          4766: M-x Info-validate
        !          4767: @end example
        !          4768: 
        !          4769: After you have checked the validity of the nodes, you can either run
        !          4770: @kbd{M-x texinfo-format-buffer} as you would normally, or else tagify and
        !          4771: split the file manually with the two commands @code{Info-tagify} and
        !          4772: @code{Info-split}.@refill
        !          4773: 
        !          4774: @node     Splitting, ,Info-Validating a Large File , Running Info-Validate
        !          4775: @comment  node-name,  next,  previous,  up
        !          4776: @subsection Splitting a File Manually
        !          4777: @cindex Splitting an Info file manually
        !          4778: @cindex Info file, splitting manually
        !          4779: 
        !          4780: If the file has more than 100,000 or so bytes in it, you should split it or
        !          4781: else let the @code{texinfo-format-buffer} command do it for you
        !          4782: automatically.  (Generally you will let @code{texinfo-format-buffer} do
        !          4783: this job for you.  @xref{Creating an Info File}.)@refill
        !          4784: 
        !          4785: The split off files are called the indirect subfiles.
        !          4786: 
        !          4787: Info files are split to save memory.  With smaller files, Emacs does not
        !          4788: have make such a large buffer to hold the information.  This way, Emacs
        !          4789: can save memory.
        !          4790: 
        !          4791: If the Info file has more than 30 nodes, you should also make a tag table for
        !          4792: it. @xref{Info-Validating a Large File}, for information about creating a
        !          4793: tag table.
        !          4794: 
        !          4795: Before running @code{Info-split}, you need to load the @code{info} library
        !          4796: into Emacs by giving the command @kbd{M-x load-library @key{RET} info
        !          4797: @key{RET}}.  After you have done this, you can give the two commands:@refill
        !          4798: 
        !          4799: @example
        !          4800: M-x Info-tagify
        !          4801: M-x Info-split
        !          4802: @end example
        !          4803: 
        !          4804: @noindent
        !          4805: (Note that the @samp{I} in @samp{Info} is uppercase.)
        !          4806: 
        !          4807: When you use the @code{Info-split} command, the buffer is modified into a
        !          4808: (small) Info file which lists the indirect subfiles.  This file should be
        !          4809: saved in place of the original visited file.  The indirect subfiles are
        !          4810: written in the same directory the original file is in, with names generated
        !          4811: by appending @samp{-} and a number to the original file name.
        !          4812: 
        !          4813: The primary file still functions as an Info file, but it contains just
        !          4814: the tag table and a directory of subfiles.
        !          4815: 
        !          4816: @c ;;;;;;;;;;;;;;;; Appendix starts here ;;;;;;;;;;;;;;;;
        !          4817: 
        !          4818: @node    Command Syntax, Include Files  , Catching Mistakes  , Top
        !          4819: @comment  node-name,  next,  previous,  up
        !          4820: @appendix @@-Command Syntax
        !          4821: @cindex  @@-Command Syntax
        !          4822: 
        !          4823: The character @samp{@@} is used to start special Texinfo commands.  (It has the
        !          4824: same meaning that @samp{\} has in plain @TeX{}.)  Syntactically, there
        !          4825: are three classes of @@-commands:
        !          4826: 
        !          4827: @table @asis
        !          4828: @item 1. Non-alphabetic commands: @@ followed by a punctuation character.
        !          4829: These commands are always part of the text within a paragraph, and
        !          4830: never take any argument.  The two characters (@@ and the other one)
        !          4831: are complete in themselves.  For example, @code{@@.}, @code{@@:},
        !          4832: @code{@@@{} and @code{@@@}}.@refill
        !          4833: 
        !          4834: @item 2. Alphabetic commands used within a paragraph.
        !          4835: These commands have @@ followed by a letter or a word, followed by an
        !          4836: argument within braces.  For example, the command @code{@@dfn} indicates
        !          4837: the introductory or defining use of a term; it is used as follows: @samp{In
        !          4838: Texinfo, @@-commands are @@dfn@{mark-up@} commands.}@refill
        !          4839: 
        !          4840: @item 3. Alphabetic commands used outside of paragraphs.
        !          4841: Each such command occupies an entire line.  The line starts with @@,
        !          4842: followed by the name of the command (a word) such as @code{@@center} or
        !          4843: @code{@@cindex}.  If no argument is needed, the word is followed by the end
        !          4844: of the line.  If there is an argument, it is separated from the command
        !          4845: name by a space.@refill
        !          4846: @end table
        !          4847: 
        !          4848: Thus, the alphabetic commands fall into two classes that have different
        !          4849: argument syntax.  You cannot tell which class a command falls in by the
        !          4850: appearance of its name, but you can tell by the command's meaning: if it
        !          4851: makes sense to use the command together with other words as part of a
        !          4852: paragraph, the command is in class 2 and must be followed by an argument in
        !          4853: braces; otherwise, it is in class 3 and uses the rest of the line as its
        !          4854: argument.
        !          4855: 
        !          4856: The purpose of having different syntax for commands of classes 2 and 3 is
        !          4857: to make the Texinfo file easier to read, and also to help the GNU Emacs
        !          4858: paragraph and filling commands work properly.  There is only one exception
        !          4859: to this rule: the command @code{@@refill}, which is always used at the end
        !          4860: of a paragraph immediately following the final period or other punctuation
        !          4861: character.  @code{@@refill} takes no argument.  @code{@@refill} never
        !          4862: confuses the Emacs paragraph commands because it cannot start at the
        !          4863: beginning of a line.@refill
        !          4864: 
        !          4865: 
        !          4866: @node  Include Files, TeX Input, Command Syntax, Top
        !          4867: @comment  node-name,  next,  previous,  up
        !          4868: @appendix Include Files
        !          4869: @cindex Include files
        !          4870: 
        !          4871: When Info was first created, it was customary to create many small Info
        !          4872: files on one subject.  By doing this, Emacs did not have to make a large
        !          4873: buffer to hold the whole of a large Info file; instead, Emacs allocated
        !          4874: just enough memory for the small Info file that was needed at the time.
        !          4875: This way, Emacs could avoid wasting memory.  Include files were designed as
        !          4876: a way to create a single, large printed manual out of several smaller Info
        !          4877: files.
        !          4878: 
        !          4879: However, because large Info files can now be split, include files are no
        !          4880: longer strictly necessary and they are used infrequently.  Most often, they
        !          4881: are now used in projects where several different people are writing
        !          4882: different sections of a document simultaneously.
        !          4883: 
        !          4884: @appendixsec How Include Files Work
        !          4885: 
        !          4886: In a Texinfo file, a line of the form @code{@@include @file{filename}} is
        !          4887: ignored when the Info file is generated, but in a printed manual it causes
        !          4888: the contents of the file @file{filename} to be processed and included in the
        !          4889: manual.  The contents of the file @file{filename} can be ignored by Info
        !          4890: because the first file can refer to @file{filename} with menus as well as
        !          4891: cross references.  In the Info system, all the information is, as it were,
        !          4892: `in one place'.  However, when two printed manuals are made from two
        !          4893: separate Texinfo files, the two manuals are separate, and even if they give
        !          4894: each other as references, the references are to separate documents.
        !          4895: Consequently, you will sometimes want to create a comprehensive, printed
        !          4896: manual that contains all the necessary information together in one place.
        !          4897: 
        !          4898: @code{@@include} files are special Texinfo files that are used only for
        !          4899: making such a comprehensive manual.  They are listed inside an outer file
        !          4900: that contains nothing but the beginning and end matter of a Texinfo file
        !          4901: and a number of @code{@@include} commands listing the included files.
        !          4902: 
        !          4903: An @code{@@include} file--a file that will be listed inside an outer file
        !          4904: and processed with the @code{@@include} command--should not start with
        !          4905: @samp{\input texinfo}, as that has already been done by the outer file, and
        !          4906: the character @samp{\} has already been redefined to generate a backslash
        !          4907: in the output.  Instead, an @code{@@include} file usually begins with a
        !          4908: node; it lacks the beginning and ending of a Texinfo file that are
        !          4909: described in the chapters on beginning and ending a file.  @xref{Beginning
        !          4910: a File}, and @pxref{Ending a File} @refill
        !          4911: 
        !          4912: Likewise, an @code{@@include} file should not end with @code{@@bye}, since
        !          4913: that would terminate @TeX{} processing immediately.
        !          4914: 
        !          4915: Here is an example of a outer Texinfo file with @code{@@include} files
        !          4916: within it:@refill
        !          4917: 
        !          4918: @example
        !          4919: \input texinfo @@c -*-texinfo-*-
        !          4920: @@setfilename  include 
        !          4921: @@settitle Include Manual
        !          4922: 
        !          4923: @@setchapternewpage odd
        !          4924: @@titlepage
        !          4925: @@sp 12
        !          4926: @@center @@titlefont@{Include Manual@}
        !          4927: @@sp 2
        !          4928: @@center by Whom Ever
        !          4929: 
        !          4930: @@page
        !          4931: Copyright @@copyright@{@} 1988 Free Software Foundation, Inc.
        !          4932: @@end titlepage
        !          4933: 
        !          4934: @@include foo.texinfo
        !          4935: @@include bar.texinfo
        !          4936: 
        !          4937: @@unnumbered Concept Index
        !          4938: @@printindex cp
        !          4939: 
        !          4940: @@summarycontents
        !          4941: @@contents
        !          4942: 
        !          4943: @@bye
        !          4944: @end example
        !          4945: 
        !          4946: @node TeX Input, Sample Permissions, Include Files, Top
        !          4947: @comment  node-name,  next,  previous,  up
        !          4948: @appendix @TeX{} Input Initialization
        !          4949: @cindex TeX Input Initialization
        !          4950: @cindex TEXINPUTS environment variable
        !          4951: @cindex profile initialization file
        !          4952: @cindex cshrc initialization file
        !          4953: 
        !          4954: You must put an input command on the first line of every Texinfo file to
        !          4955: tell @TeX{} to use the @file{texinfo.tex} file when it is processing the
        !          4956: Texinfo source file.  Otherwise @TeX{} will not know what to do with the
        !          4957: @@-commands.  (The @TeX{} input command is written as @samp{\input
        !          4958: texinfo}.  @xref{First Line}.)@refill
        !          4959: 
        !          4960: @TeX{} needs to be told where to find the @file{texinfo.tex} file that you
        !          4961: have told it to input.  The preferred way to do this is to put
        !          4962: @file{texinfo.tex} in the default inputs directory, which is the
        !          4963: @file{/usr/lib/tex/macros} directory.  If this is done (as it usually is
        !          4964: when GNU Emacs is installed), @TeX{} will find the file and you don't have
        !          4965: to do anything.  Alternatively, you can put @file{texinfo.tex} in the
        !          4966: directory in which the Texinfo source file is located.@refill
        !          4967: 
        !          4968: However, you may want to specify the location of the @code{\input} file
        !          4969: yourself.  One way to do this is to write the complete path for the file
        !          4970: after the @code{\input} command.  Another way is to set the
        !          4971: @samp{TEXINPUTS} environment variable in your @file{.cshrc} or
        !          4972: @file{.profile} file.  The @samp{TEXINPUTS} environment variable will tell
        !          4973: @TeX{} where to find the @file{texinfo.tex} file and any other file that
        !          4974: you might want @TeX{} to use.@refill
        !          4975: 
        !          4976: Whether you use a @file{.cshrc} or @file{.profile} file depends on whether
        !          4977: you use @samp{csh} or @samp{sh} for your shell command interpreter.  When
        !          4978: you use @samp{csh}, it looks to the @file{.cshrc} file for initialization
        !          4979: information, and when you use @samp{sh}, it looks to the @file{.profile}
        !          4980: file.@refill
        !          4981: 
        !          4982: In a @file{.cshrc} file, you could use the following @code{csh} command
        !          4983: sequence:@refill
        !          4984: 
        !          4985: @example
        !          4986: setenv TEXINPUTS .:/usr/me/mylib:/usr/lib/tex/macros
        !          4987: @end example
        !          4988: 
        !          4989: @noindent
        !          4990: In a @file{.profile} file, you could use the following @code{sh} command
        !          4991: sequence:
        !          4992: 
        !          4993: @example
        !          4994: TEXINPUTS=.:/usr/me/mylib:/usr/lib/tex/macros
        !          4995: export TEXINPUTS
        !          4996: @end example
        !          4997: 
        !          4998: @noindent
        !          4999: This would cause @TeX{} to look for @file{\input} file first in the current
        !          5000: directory, indicated by the @samp{.}, then in a hypothetical user's
        !          5001: @file{me/mylib} directory, and finally in the system library.@refill
        !          5002: 
        !          5003: @node Sample Permissions,  Command Index, TeX Input, Top    
        !          5004: @comment  node-name,  next,  previous,  up
        !          5005: @appendix Standard text for Copying Permissions
        !          5006: @cindex Permissions
        !          5007: @cindex Copying permissions
        !          5008: 
        !          5009: Texinfo files should contain sections that tell the readers that they have
        !          5010: the right to copy and distribute the Info file, the printed manual and any
        !          5011: accompanying software.  This appendix contains the standard text of the
        !          5012: Free Software Foundation copying permission notice.  For an example of the
        !          5013: text that could be used for the Distribution, General Public License and NO
        !          5014: WARRANTY sections of a document, see the latest version of the @cite{GNU
        !          5015: Emacs Manual}.
        !          5016: 
        !          5017: The texts of the Free Software Foundation copying permission notice in the
        !          5018: @code{@@ifinfo} section and in the @code{@@titlepage} section are slightly
        !          5019: different.
        !          5020: 
        !          5021: The @code{@@ifinfo} section usually begins with a line that says what the
        !          5022: file documents.  This is what a person looking at the file will first read
        !          5023: if he or she reads the unprocessed Texinfo file or if he or she uses the
        !          5024: advanced Info command @kbd{g *}.  @inforef{Expert, info, info}, for more
        !          5025: information. (If the reader uses the regular Info commands, he or she will
        !          5026: usually start reading at the first node and skip this first section, which
        !          5027: is not in a node.)
        !          5028: 
        !          5029: In the @code{@@ifinfo} section, the summary sentence should be followed by
        !          5030: a copyright notice and then by the copying permission notice.  One of the
        !          5031: copying permission paragraphs is enclosed in @code{@@ignore} and
        !          5032: @code{@@end ignore} commands.  This paragraph states that the Texinfo file
        !          5033: can be processed through @TeX{} and printed, provided the printed manual
        !          5034: carries the proper copying permission notice.  This paragraph is not made
        !          5035: part of the Info file since it is not relevant to the Info file; but it is
        !          5036: a mandatory part of the Texinfo file since it permits people to process the
        !          5037: Texinfo file in @TeX{}.@refill
        !          5038: 
        !          5039: In the printed manual, the Free Software Foundation copying permission
        !          5040: notice follows the copyright notice and publishing information and is
        !          5041: located within the region delineated by the @code{@@titlepage} and
        !          5042: @code{@@end titlepage} commands.  The copying permission notice is exactly
        !          5043: the same as the notice in the @code{@@ifinfo} section except that the
        !          5044: paragraph enclosed in @code{@@ignore} and @code{@@end ignore} commands is
        !          5045: not part of the notice.@refill
        !          5046: 
        !          5047: To make it simpler to copy the permission notice into each section of the
        !          5048: Texinfo file, the complete permission notices for each section are
        !          5049: reproduced in full below even though most of the information is
        !          5050: redundant.@refill
        !          5051: 
        !          5052: Note that you my have to specify the correct name of a section mentioned in
        !          5053: the permission notice.  For example, in the @cite{GDB Manual}, the name of
        !          5054: the section referring to the General Public License is called the ``GDB
        !          5055: General Public License'', but in the sample shown below, that section is
        !          5056: referred to generically as the ``General Public License''.
        !          5057: 
        !          5058: @menu
        !          5059: * Ifinfo Permissions::
        !          5060: * Titlepage Permissions::
        !          5061: @end menu
        !          5062: 
        !          5063: 
        !          5064: @node Ifinfo Permissions, Titlepage Permissions, Sample Permissions, Sample Permissions    
        !          5065: @comment  node-name,  next,  previous,  up
        !          5066: @appendixsec Ifinfo Copying Permissions
        !          5067: @cindex  Ifinfo permissions
        !          5068: 
        !          5069: In the @code{@@ifinfo} section of the Texinfo file, the standard Free
        !          5070: Software Foundation permission notices reads as follows:
        !          5071: 
        !          5072: @example
        !          5073: This file documents @dots{}
        !          5074: 
        !          5075: Copyright 1988 Free Software Foundation, Inc.
        !          5076: 
        !          5077: Permission is granted to make and distribute verbatim copies of
        !          5078: this manual provided the copyright notice and this permission notice
        !          5079: are preserved on all copies.
        !          5080: 
        !          5081: @@ignore
        !          5082: Permission is granted to process this file through TeX and print the
        !          5083: results, provided the printed document carries a copying permission
        !          5084: notice identical to this one except for the removal of this paragraph
        !          5085: (this paragraph not being relevant to the printed manual).
        !          5086: 
        !          5087: @@end ignore
        !          5088: Permission is granted to copy and distribute modified versions of this
        !          5089: manual under the conditions for verbatim copying, provided also that the
        !          5090: sections entitled ``Distribution'' and ``General Public License'' are
        !          5091: included exactly as in the original, and provided that the entire
        !          5092: resulting derived work is distributed under the terms of a permission
        !          5093: notice identical to this one.
        !          5094: 
        !          5095: Permission is granted to copy and distribute translations of this manual
        !          5096: into another language, under the above conditions for modified versions,
        !          5097: except that the sections entitled ``Distribution'' and ``General Public
        !          5098: License'' may be included in a translation approved by the author instead
        !          5099: of in the original English.
        !          5100: @end example
        !          5101: 
        !          5102: @node Titlepage Permissions, , Ifinfo Permissions, Sample Permissions    
        !          5103: @comment  node-name,  next,  previous,  up
        !          5104: @appendixsec Titlepage Copying Permissions
        !          5105: @cindex  Titlepage permissions
        !          5106: 
        !          5107: In the @code{@@titlepage} section of the Texinfo file, the standard Free
        !          5108: Software Foundation copying permission notices follows the copyright notice
        !          5109: and publishing information.  The standard phrasing is:
        !          5110: 
        !          5111: @example
        !          5112: Permission is granted to make and distribute verbatim copies of
        !          5113: this manual provided the copyright notice and this permission notice
        !          5114: are preserved on all copies.
        !          5115: 
        !          5116: Permission is granted to copy and distribute modified versions of this
        !          5117: manual under the conditions for verbatim copying, provided also that the
        !          5118: sections entitled ``Distribution'' and ``General Public License'' are
        !          5119: included exactly as in the original, and provided that the entire
        !          5120: resulting derived work is distributed under the terms of a permission
        !          5121: notice identical to this one.
        !          5122: 
        !          5123: Permission is granted to copy and distribute translations of this manual
        !          5124: into another language, under the above conditions for modified versions,
        !          5125: except that the sections entitled ``Distribution'' and ``General Public
        !          5126: License'' may be included in a translation approved by the author instead
        !          5127: of in the original English.
        !          5128: @end example
        !          5129: 
        !          5130: @node     Command Index, Concept Index, Sample Permissions, Top
        !          5131: @comment  node-name,  next,  previous,  up
        !          5132: @unnumbered  Command Index
        !          5133: 
        !          5134: (When used in a Texinfo file, @@-commands are preceded by an
        !          5135: @samp{@@}.)@refill
        !          5136: 
        !          5137: @printindex fn
        !          5138: 
        !          5139: @node     Concept Index,     ,   Command Index, Top
        !          5140: @comment  node-name,     next,  previous,      up
        !          5141: @unnumbered Concept Index
        !          5142: 
        !          5143: @printindex cp
        !          5144: 
        !          5145: @summarycontents
        !          5146: @contents
        !          5147: @bye

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