Return to texinfo-1 CVS log

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

Annotation of 43BSDReno/contrib/emacs-18.55/info/texinfo-1, revision 1.1

1.1     ! root        1: Info file ../info/texinfo, produced by Makeinfo, -*- Text -*- from
        !             2: input file texinfo.texinfo.
        !             3: 
        !             4: This file documents Texinfo, a documentation system that uses a
        !             5: single source file to produce both on-line help and a printed manual.
        !             6: 
        !             7: This is edition 1.1 of the Texinfo documentation, and is for the
        !             8: Texinfo that is distributed as part of Version 18 of GNU Emacs.
        !             9: 
        !            10: Copyright (C) 1988 Free Software Foundation, Inc.
        !            11: 
        !            12: Permission is granted to make and distribute verbatim copies of this
        !            13: manual provided the copyright notice and this permission notice are
        !            14: preserved on all copies.
        !            15: 
        !            16: Permission is granted to copy and distribute modified versions of
        !            17: this manual under the conditions for verbatim copying, provided that
        !            18: the entire resulting derived work is distributed under the terms of a
        !            19: permission notice identical to this one.
        !            20: 
        !            21: Permission is granted to copy and distribute translations of this
        !            22: manual into another language, under the above conditions for modified
        !            23: versions, except that this permission notice may be stated in a
        !            24: translation approved by the Foundation.
        !            25: 
        !            26: 
        !            27: 
        !            28: File: texinfo,  Node: Top,  Next: License,  Prev: (dir),  Up: (dir)
        !            29: 
        !            30: * Menu:
        !            31: 
        !            32: * License::                    Licensing information.
        !            33: * Overview::                   What is Texinfo?
        !            34: * Texinfo Mode::               Special features in GNU Emacs.
        !            35: * Beginning a File::           What to put at the beginning of a Texinfo file.
        !            36: * Ending a File::              What to put at the end of a Texinfo file.
        !            37: * Structuring::                        How to make nodes and chapters.
        !            38: * Quotations and Examples::    How to insert quotations and examples.
        !            39: * Lists and Tables::           How to make lists and tables.
        !            40: * Cross References::           How to make cross references.
        !            41: * Formatting Paragraphs::      How to format paragraphs.
        !            42: * Marking Text::               How to mark code, definitions, variables etc.
        !            43: * Conditionals::               Putting text in only Info or the printed work.
        !            44: * Printing Hardcopy::          How to print a hardcopy of the manual.
        !            45: * Creating an Info File::      How to create an on-line Info file.
        !            46: * Catching Mistakes::          How to find problems.
        !            47: 
        !            48: Indices, nodes containing large menus
        !            49: 
        !            50: * Command Index::              An item for each @-command.
        !            51: * Concept Index::              An item for each concept.
        !            52: 
        !            53: A detailed node listing
        !            54: 
        !            55: Overview
        !            56: * Info File::                  Characteristics of the Info file.
        !            57: * Printed Manual::             Characteristics of the printed manual.
        !            58: * Conventions::                        General syntactic conventions.
        !            59: * Short Sample::               A short sample Texinfo file.
        !            60: 
        !            61: Using Texinfo Mode
        !            62: * Info on a Region::           Formatting a region for Info.
        !            63: * Showing the Structure::      Showing the structure of a file.
        !            64: * Inserting::                  Inserting frequently used commands.
        !            65: 
        !            66: Beginning a Texinfo File.
        !            67: * First Line::                 The first line of a Texinfo file.
        !            68: * Start-of-Header::            Identifying the start of the header.
        !            69: * Setfilename::                        Specifying the name of the Info file.
        !            70: * Settitle::                   Specifying the title used by the headings.
        !            71: * Setchapternewpage::          Starting chapters on odd numbered pages.
        !            72: * Titlepage::                  The title and copyright page.
        !            73: * Center::                     Centering a line.
        !            74: * Copyright & Printed Permissions:: Ensuring free distributability.
        !            75: * Top Node::                   The master menu.  
        !            76: * License and Distribution::   Your are free to copy and distribute this.
        !            77: 
        !            78: Ending a Texinfo File
        !            79: * Contents::                   Generating tables of contents.
        !            80: * Indices::                    Generating indices.
        !            81: * Index Entries::              Defining the entries of an index.
        !            82: * Combining Indices::          Putting two or more indices together.
        !            83: * Printing Indices & Menus::   Printing an index and generating menus.
        !            84: 
        !            85: Node and Chapter Structuring
        !            86: * Chapter::                    Creating a chapter.
        !            87: * Unnumbered and Appendix::    Chapter-like parts.
        !            88: * Section::                    Creating sections
        !            89: * Subsection::                 Creating subsections.
        !            90: * Subsubsection::              Creating subsubsections.
        !            91: 
        !            92: * Node::                       Creating nodes.
        !            93: * Menu::                       Creating menus.
        !            94: 
        !            95: 
        !            96: Making quotations and examples
        !            97: * Quotation::                  Inserting long quotations.
        !            98: * Example::                    Inserting examples of code and the like.
        !            99: * Display::                    Inserting displayed text.
        !           100: 
        !           101: Making lists and two column tables
        !           102: * Itemize::                    Creating itemized lists.
        !           103: * Enumerate::                  Creating enumerated lists.
        !           104: * Table::                      Creating two column tables.
        !           105: * Itemx::                      Putting an extra item in the 
        !           106:                                first column of a table.
        !           107: 
        !           108: Making Cross References
        !           109: * Xref::                       Making a regular cross reference.
        !           110: * Pxref::                      Making a parenthetical cross reference.
        !           111: * Inforef::                    Making a cross reference to an Info file.
        !           112: 
        !           113: 
        !           114: Formatting Paragraphs
        !           115: * Refilling & Noindent::       Refilling paragraphs 
        !           116:                                and preventing indentation
        !           117: * Refill::                     Using the `@refill' command.
        !           118: * Noindent::                   Using the `@noindent' command.
        !           119: 
        !           120: 
        !           121: Breaks, Blank Lines and Groups
        !           122: * Line Breaks::                        Inserting line breaks in TeX.
        !           123: * Sp::                         Inserting blank lines.
        !           124: * Br::                         Inserting paragraph breaks.
        !           125: * W::                          Preventing line breaks.
        !           126: * Page::                       Starting new pages.
        !           127: * Group::                      Holding text together on one page.
        !           128: * Need::                       Keeping text together.
        !           129: 
        !           130: Marking Text Within a Paragraph
        !           131: * Code::                       A literal example of a piece of a program.
        !           132: * Samp::                       A literal example of a sequence of characters.
        !           133: * File::                       The name of a file.
        !           134: * Kbd::                                The names of keys or else characters you type.
        !           135: * Key::                                The conventional name for a key on a keyboard.
        !           136: * Ctrl::                       Indicates the ASCII control character.
        !           137: * Var::                                A variable.
        !           138: * Dfn::                                The introductory or defining use of a term.
        !           139: * Cite::                       The name of a book.
        !           140: 
        !           141: Inserting Braces, `@' and Periods
        !           142: * Braces Atsigns Periods::     Inserting braces, `@' and periods.
        !           143: * Dots Bullets Tex::           Inserting dots, bullets and the TeX logo
        !           144: * Emphasis::                   Emphasizing text.
        !           145: 
        !           146: Emphasizing Text
        !           147: * Emph and Strong::            Emphasizing text.
        !           148: * Fonts::                      Selecting italic, bold or typewriter fonts.
        !           149: 
        !           150: Creating an Info File
        !           151: * Installing an Info File::    Putting the Info file in the 
        !           152:                                `info' directory.
        !           153: 
        !           154: Catching Mistakes
        !           155: * Debugging with Info::            Catching errors with info formatting.
        !           156: * Using the Emacs Lisp Debugger::   Using the Emacs Lisp Debugger
        !           157: * Debugging with Tex::             Catching errors with TeX formatting.
        !           158: * Using texinfo-show-structure::    Using `texinfo-show-structure'
        !           159:                                    to catch mistakes.
        !           160: * Using Occur::                            Using `occur' to catch mistakes.
        !           161: * Running Info-Validate::          Checking for unreferenced nodes.
        !           162: 
        !           163: Finding badly referenced nodes
        !           164: * Info-Validating a Large File::     Running `Info-validate' 
        !           165:                                     on a large file.
        !           166: * Splitting::                        Splitting a file manually.
        !           167: 
        !           168: Appendices
        !           169: * Command Syntax::             Details about the syntax.
        !           170: * Include Files::              Making one printed file out of 
        !           171:                                several Info files.
        !           172: * TeX Input::                  Where TeX finds its `\input' file.
        !           173: * Sample Permissions::         You may copy GNU Software.
        !           174: * Ifinfo Permissions::         What to put in the `ifinfo' section.
        !           175: * Titlepage Permissions::      What to put in the `@titlepage' section.
        !           176: 
        !           177:  
        !           178: 
        !           179: File: texinfo,  Node: License,  Next: Overview,  Prev: Top,  Up: Top
        !           180: 
        !           181: Licensing Information
        !           182: *********************
        !           183: 
        !           184:   The programs currently being distributed that relate to Texinfo
        !           185: include two portions of GNU Emacs, plus two other separate programs
        !           186: (`texindex' and `texinfo.tex').  These programs are "free"; this
        !           187: means that everyone is free to use them and free to redistribute them
        !           188: on a free basis.  The Texinfo related programs are not in the public
        !           189: domain; they are copyrighted and there are restrictions on their
        !           190: distribution, but these restrictions are designed to permit
        !           191: everything that a good cooperating citizen would want to do.  What is
        !           192: not allowed is to try to prevent others from further sharing any
        !           193: version of these programs that they might get from you.
        !           194: 
        !           195:   Specifically, we want to make sure that you have the right to give
        !           196: away copies of the programs that relate to Texinfo, that you receive
        !           197: source code or else can get it if you want it, that you can change
        !           198: these programs or use pieces of them in new free programs, and that
        !           199: you know you can do these things.
        !           200: 
        !           201:   To make sure that everyone has such rights, we have to forbid you to
        !           202: deprive anyone else of these rights.  For example, if you distribute
        !           203: copies of the Texinfo related programs, you must give the recipients
        !           204: all the rights that you have.  You must make sure that they, too,
        !           205: receive or can get the source code.  And you must tell them their
        !           206: rights.
        !           207: 
        !           208:   Also, for our own protection, we must make certain that everyone
        !           209: finds out that there is no warranty for the programs that relate to
        !           210: Texinfo.  If these programs are modified by someone else and passed
        !           211: on, we want their recipients to know that what they have is not what
        !           212: we distributed, so that any problems introduced by others will not
        !           213: reflect on our reputation.
        !           214: 
        !           215:   The precise conditions of the licenses for the programs currently
        !           216: being distributed that relate to Texinfo are found in the General
        !           217: Public Licenses that accompany them.  The programs that are part of
        !           218: GNU Emacs are covered by the GNU Emacs copying terms (*note :
        !           219: (emacs)License.), and other programs are covered by licenses that are
        !           220: contained in their source files.
        !           221: 
        !           222: 
        !           223: 
        !           224: File: texinfo,  Node: Overview,  Next: Texinfo Mode,  Prev: License,  Up: Top
        !           225: 
        !           226: Overview of Texinfo
        !           227: *******************
        !           228: 
        !           229: Texinfo is a documentation system that uses a single source file for
        !           230: both on-line help and a printed manual.  This means that instead of
        !           231: writing two different documents, one for the on-line help and the
        !           232: other for the printed manual, only one document needs to be written. 
        !           233: When the system is revised, only one file has to be revised.
        !           234: 
        !           235: Using Texinfo, you can create a document with the normal features of
        !           236: a book such as chapters, sections, cross references and indices.  The
        !           237: chapters and sections of the printed manual can be made to correspond
        !           238: to the nodes of the on-line help.  The cross references and indices
        !           239: can be used in both the on-line help and in the printed document. 
        !           240: Indices are generated semi-automatically.  The ``GNU Emacs Manual''
        !           241: is a good example of a Texinfo file.
        !           242: 
        !           243: To make the printed manual, the Texinfo source file is processed by
        !           244: the TeX typesetting program; the resulting DVI file can be typeset
        !           245: and printed as a book.  To make the on-line help, the Texinfo source
        !           246: file is by processed the `M-x texinfo-format-buffer' command; the
        !           247: resulting Info file is installed in the `info' directory.
        !           248: 
        !           249: Since the Texinfo source file is used for a dual task--to create both
        !           250: the on-line help and the printed manual--it must be written in a
        !           251: special format that uses @-commands (words preceded by an `@') to
        !           252: indicate chapters, sections, nodes, examples, index entries and the
        !           253: like.
        !           254: 
        !           255: Before writing a Texinfo source file, you should be familiar with the
        !           256: on-line Info documentation reading program.  (*note info: (info)Info,
        !           257: for more information.)  If you are writing a document that will be
        !           258: both on-line and printed, you will need both Info and TeX.
        !           259: 
        !           260: To make an Info file, you use the `M-x texinfo-format-buffer' command
        !           261: in GNU Emacs.
        !           262: 
        !           263: To make a printed manual, you need to use TeX, a powerful,
        !           264: sophisticated typesetting program written by Donald Knuth.  TeX is
        !           265: freely distributable. It is written in a dialect of Pascal called WEB
        !           266: and can be compiled either in Pascal or (by using a conversion
        !           267: program that comes with the TeX distribution) in C.  (For information
        !           268: about getting TeX, *note : (emacs)TeX Mode.)
        !           269: 
        !           270: When TeX processes a Texinfo source file, TeX makes use of a macro
        !           271: definitions file called `texinfo.tex' that comes with the GNU Emacs
        !           272: distribution in the `emacs/man' sources directory.  (The first line
        !           273: of every Texinfo file has a command that says `\input texinfo'; this
        !           274: tells TeX to use the `texinfo.tex' file.)
        !           275: 
        !           276: If the `texinfo.tex' file has not already been copied to the
        !           277: directory which contains the other TeX macro definition files when
        !           278: Emacs was installed, you will probably want to copy it to that
        !           279: directory.  Usually, this is the `/usr/lib/tex/macros' directory. 
        !           280: For more information, *note @TeX{} Input Initialization: TeX Input.
        !           281: 
        !           282: Documentation for GNU utilities and libraries should be written in
        !           283: Texinfo format.
        !           284: 
        !           285: * Menu:
        !           286: 
        !           287: * Info File::         Characteristics of the Info file.
        !           288: * Printed Manual::    Characteristics of the Printed Manual.
        !           289: * Conventions::       General Syntactic Conventions.
        !           290: * Short Sample::      A short sample Texinfo file.
        !           291: 
        !           292:  
        !           293: 
        !           294: File: texinfo,  Node: Info File,  Next: Printed Manual,  Up: Overview
        !           295: 
        !           296: Characteristics of the Info file
        !           297: ================================
        !           298: 
        !           299: A Texinfo file can be transformed into a printed manual and an
        !           300: on-line Info file.
        !           301: 
        !           302: An on-line Info file is a file formatted so that the Info
        !           303: documentation reading program can operate on it.  Info files are
        !           304: divided into pieces called "nodes", each of which contains the
        !           305: discussion of one topic.  Each node has a name, and contains both
        !           306: text for the user to read and pointers to other nodes, which are
        !           307: identified by their names.  The Info program displays one node at a
        !           308: time, and provides commands with which the user can move to the other
        !           309: nodes to which the current node points.
        !           310: 
        !           311: *note info: (info)Info, for more information about using Info.
        !           312: 
        !           313: Normally, most of the nodes are arranged in a tree which branches down.
        !           314: Each node may have any number of child nodes that describe subtopics
        !           315: of the node's topic.  The names of these child nodes, if any, are
        !           316: listed in a "menu" within the parent node; this allows certain Info
        !           317: commands to be used to move to one of the child nodes.  Each child
        !           318: node records the parent node name, as its `Up' pointer.  Thus, if a
        !           319: node were at the logical level of a `chapter', its child nodes would
        !           320: be `sections'; likewise, the child nodes of a section would be
        !           321: subsections.
        !           322: 
        !           323: The root of the tree is the top node of the file, through which users
        !           324: enter the file from the Info directory.  By convention, this node is
        !           325: always called `Top'.  This node normally contains just a brief
        !           326: summary of the file's purpose, and a large menu through which the
        !           327: rest of the file is reached.
        !           328: 
        !           329: Generally you enter the Info file from the top; then you can either
        !           330: traverse the file systematically by going from node to node or you
        !           331: can search large menus that correspond to indices and go directly to
        !           332: the node that has the information you want.
        !           333: 
        !           334: If you want to read through an Info file in sequence, as if it were a
        !           335: printed manual, you can get the whole file with the advanced Info
        !           336: command `g *'.  (*note info: (info)Expert.)
        !           337: 
        !           338: All the children of any one parent are linked together in a
        !           339: bidirectional chain of `Next' and `Previous' pointers.  This means
        !           340: that all the nodes that are logically parallel to sections within a
        !           341: chapter are all linked together.  Normally the order in this chain is
        !           342: the same as the order of the children in the parent's menu.  The last
        !           343: child has no `Next' pointer, and the first child normally has the
        !           344: parent as its `Previous' pointer (as well as its `Up' pointer, of
        !           345: course).
        !           346: 
        !           347: Structuring the nodes in a tree is a matter of convention, not a
        !           348: requirement.  In fact, the `Up', `Previous' and `Next' pointers of a
        !           349: node can point to any other nodes, and the menu can contain any other
        !           350: nodes.  The structure of nodes can be any directed graph.  But it is
        !           351: usually more comprehensible to make it a tree.  Info provides another
        !           352: kind of pointer between nodes, called a reference, that can be
        !           353: sprinkled through the text of a node.  This is usually the best way
        !           354: to represent links that do not fit the tree structure.
        !           355: 
        !           356: Most often the nodes fall into a strict tree structure that
        !           357: corresponds to the structure of chapters and sections in the printed
        !           358: manual.  But there are times when this is not right for the material
        !           359: being discussed.  Therefore, Texinfo uses separate commands to
        !           360: specify the node structure of the Info file and the section structure
        !           361: of the printed manual.  Also, Texinfo requires that you specify menus
        !           362: explicitly, rather than generate them automatically based on an
        !           363: assumed tree structure.
        !           364: 
        !           365: 
        !           366: 
        !           367: File: texinfo,  Node: Printed Manual,  Next: Conventions,  Prev: Info File,  Up: Top
        !           368: 
        !           369: Characteristics of the Printed Manual
        !           370: =====================================
        !           371: 
        !           372: A Texinfo file can be formatted and typeset as a printed manual.  The
        !           373: printed manual will be the same as any other book; it will have a
        !           374: title page, copyright page, table of contents, and preface as you
        !           375: would expect, as well as chapters, numbered or unnumbered sections
        !           376: and subsections, not to mention page headers, cross references and
        !           377: indices.
        !           378: 
        !           379: Texinfo can be used for writing a book without ever having the
        !           380: intention of converting it into on-line help.  Texinfo can be used
        !           381: for writing a novel; and it can even be used to write a memo,
        !           382: although this application is not recommended since electronic mail is
        !           383: so much easier.
        !           384: 
        !           385: Texinfo uses the formatting language called TeX for typesetting.  A
        !           386: file called `texinfo.tex' contains information (definitions or
        !           387: "macros") that TeX uses when it typesets a Texinfo file.  (The macros
        !           388: tell TeX how to convert the Texinfo @-commands to TeX commands which
        !           389: TeX can then process to create the typeset document.) `texinfo.tex'
        !           390: contains the specifications for printing a document, either with 7
        !           391: inch by 9.25 inch pages or with 8.5 inch by 11 inch pages.  (This is
        !           392: 178 mm by 235 mm or else 216 mm by 280 mm.) Also, by changing the
        !           393: parameters in `texinfo.tex' you can easily change the size of the
        !           394: printed document.  In addition, you can readily change the style in
        !           395: which the printed document is formatted; for example, you can change
        !           396: the sizes and fonts used, the amount of indentation for each
        !           397: paragraph, the degree to which words are hyphenated, and the like. 
        !           398: By changing the specifications, you can make a book look dignified,
        !           399: old and serious, or light-hearted, young and cheery.
        !           400: 
        !           401: TeX is very powerful and has a great many features.  Because a
        !           402: Texinfo file must be able to present information both on a
        !           403: character-only terminal in Info form and in a typeset book, the
        !           404: commands that Texinfo supports are necessarily limited.
        !           405: 
        !           406: 
        !           407: 
        !           408: File: texinfo,  Node: Conventions,  Next: Short Sample,  Prev: Printed Manual,  Up: Overview
        !           409: 
        !           410: General Syntactic Conventions
        !           411: =============================
        !           412: 
        !           413: Texinfo files contain a strictly limited set of constructs.  The
        !           414: strict limits make it possible for Texinfo files to be understood
        !           415: both by TeX and by the code which converts them into Info files.
        !           416: 
        !           417: All ASCII printing characters except `@', `{' and `}' can appear in
        !           418: body text in a Texinfo file and stand for themselves.  `@' is the
        !           419: escape character which introduces commands.  `{' and `}' should be
        !           420: used only to surround arguments to certain commands.  `{' and `}'
        !           421: appearing anywhere else will be treated by TeX as a grouping but
        !           422: treated by the code that produces an Info file as themselves; this
        !           423: inconsistency is undesirable, so don't let it occur.  To put one of
        !           424: these special characters into the document, put an `@' character in
        !           425: front of it.  For example, you would insert `@@', `@{', and `@}'.
        !           426: 
        !           427: It is customary in TeX to use doubled single-quote characters to
        !           428: begin and end quotations, ```' like these `'''.  This convention
        !           429: should be followed in Texinfo files.  Also, three hyphens in a row,
        !           430: `--', are used for a dash--like this.  In TeX, a single or even a
        !           431: double hyphen produces a dash that is shorter than you want.
        !           432: 
        !           433: TeX ignores the line-breaks in the input text, except for blank
        !           434: lines, which separate paragraphs.  Info generally preserves the line
        !           435: breaks that are present in the input file.  Therefore, break the
        !           436: lines in the Texinfo file the way you want them to appear in the
        !           437: output Info file, and let TeX take care of itself.
        !           438: 
        !           439: Since Info does not normally refill paragraphs when it processes
        !           440: them, a line with @-commands in it will sometimes look bad after Info
        !           441: has run on it.  To cause Info to refill the paragraph after finishing
        !           442: with the other processing, you need to put the command `@refill' at
        !           443: the end of the paragraph. (*Note Refilling paragraphs and Preventing
        !           444: indentation: Refilling & Noindent.)
        !           445: 
        !           446: To prevent a paragraph from being indented in the printed manual, put
        !           447: the command `@noindent' on a line by itself before the start of the
        !           448: text that should not be indented.
        !           449: 
        !           450: If you mark off a region of the Texinfo file with the `@iftex' and
        !           451: `@end iftex' commands so that the region will appear only in the
        !           452: printed copy, you can use TeX commands that cannot be used in the
        !           453: Info file.
        !           454: 
        !           455: In order to be made into a printed manual, a Texinfo file *must*
        !           456: begin with lines that looks like
        !           457: 
        !           458:      \input texinfo   @c -*-texinfo-*-
        !           459:      @setfilename INFO-FILE-NAME
        !           460:      @settitle NAME OF MANUAL
        !           461: 
        !           462: The `\input texinfo' line tells TeX to use the `texinfo.tex' file. 
        !           463: This line is usually followed by a start-of-header line (not shown
        !           464: here) and then by the `@setfilename INFO-FILE-NAME' and `@settitle
        !           465: NAME OF MANUAL' lines.  These two lines are needed to provide a name
        !           466: for the Info file and to specify the name used on the left-hand page
        !           467: headers of the printed manual.
        !           468: 
        !           469: The two lines that contain the `@setfilename' and `@settitle'
        !           470: commands usually are sandwiched between the start-of-header line and
        !           471: the end-of-header line. (*Note Start-of-Header::, for more
        !           472: information.)  The start-of-header and end-of-header lines are needed
        !           473: if you are going to run TeX or Info on just part of a file.
        !           474: 
        !           475: 
        !           476: 
        !           477: File: texinfo,  Node: Short Sample,  Prev: Conventions,  Up: Overview
        !           478: 
        !           479: A Short Sample Texinfo File
        !           480: ===========================
        !           481: 
        !           482: A Texinfo file looks like the following, which is a complete but very
        !           483: short Texinfo file.  The `@comment' command introduces comments that
        !           484: will not appear in either the Info file or the printed manual; they
        !           485: are for the person who reads the Texinfo file.
        !           486: 
        !           487: The first part of the file, from `\input texinfo' through to `@end
        !           488: titlepage', looks more intimidating than it is.  Most of the material
        !           489: is standard boilerplate; when you write a manual, you just put in the
        !           490: name of your own manual in this section.
        !           491: 
        !           492: All the commands that tell TeX how to typeset the printed manual and
        !           493: tell `texinfo-format-buffer' how to create an Info file are preceded
        !           494: by `@'; thus, `@node' indicates a node and `@chapter' indicates the
        !           495: start of a chapter.
        !           496: 
        !           497:      \input texinfo   @c -*-texinfo-*-
        !           498:      @setfilename name-of-texinfo-file
        !           499:      @settitle Name of Manual
        !           500:      @setchapternewpage odd
        !           501:      
        !           502:      @ifinfo
        !           503:      @comment The following line inserts the copyright notice 
        !           504:      @comment into the Info file.
        !           505:      Copyright @copyright{} 1988 Free Software Foundation, Inc.
        !           506:      @end ifinfo
        !           507:      
        !           508:      @comment The titlepage section does not appear in the Info file.
        !           509:      @titlepage
        !           510:      @sp 10
        !           511:      @comment The title is printed in a large font.
        !           512:      @center @titlefont{Sample Title}
        !           513:      
        !           514:      @comment  The following two commands start the copyright page
        !           515:      @comment  for the printed manual.  This will not appear in the Info file.
        !           516:      @page
        !           517:      @vskip 0pt plus 1filll
        !           518:      Copyright @copyright{} year copyright-owner
        !           519:      @end titlepage
        !           520:      
        !           521:      @comment The Top node contains the master menu for the Info file.
        !           522:      @comment This appears only in the Info file, not the printed manual.
        !           523:      
        !           524:      @node    Top,       First Chapter, (dir),    (dir)
        !           525:      @comment node-name, next,          previous, up
        !           526:      
        !           527:      @menu
        !           528:      * First Chapter::    The first chapter is the 
        !           529:                           only chapter in this sample.
        !           530:      @end menu
        !           531:      
        !           532:      @node     First Chapter,     , Top,      Top
        !           533:      @comment  node-name,     next, previous, up
        !           534:      @chapter First Chapter
        !           535:      @cindex Reference to First Chapter
        !           536:      
        !           537:      This is the contents of the first chapter. 
        !           538:      
        !           539:      Here is a numbered list.
        !           540:      
        !           541:      @enumerate
        !           542:      @item
        !           543:      This is the first item.
        !           544:      
        !           545:      @item
        !           546:      This is the second item.
        !           547:      @end enumerate
        !           548:      
        !           549:      The @kbd{M-x texinfo-format-buffer} command transforms a Texinfo file
        !           550:      like this into an Info file; and @TeX{} typesets it for a printed
        !           551:      manual.
        !           552:      
        !           553:      @node    Concept Index,    ,  Previous Node, Top
        !           554:      @comment node-name,    next,  previous,      up
        !           555:      @unnumbered Concept Index
        !           556:      
        !           557:      @printindex cp
        !           558:      
        !           559:      @contents
        !           560:      @bye
        !           561: 
        !           562: Here is what the contents of the first chapter of the sample look like:
        !           563: 
        !           564:      This is the contents of the first chapter.
        !           565: 
        !           566:      Here is a numbered list.
        !           567: 
        !           568:        1. This is the first item.
        !           569: 
        !           570:        2. This is the second item.
        !           571: 
        !           572:      The `M-x texinfo-format-buffer' command transforms a Texinfo
        !           573:      file like this into an Info file; and TeX typesets it for a
        !           574:      printed manual.
        !           575: 
        !           576: 
        !           577: 
        !           578: File: texinfo,  Node: Texinfo Mode,  Next: Beginning a File,  Prev: Overview,  Up: Top
        !           579: 
        !           580: Using Texinfo Mode
        !           581: ******************
        !           582: 
        !           583: In GNU Emacs, Texinfo mode is a major mode for editing Texinfo files.
        !           584: This means that Emacs has commands and features especially designed
        !           585: for working with Texinfo files.  Like all other Emacs features, you
        !           586: can customize or enhance these as you wish.  In particular, the
        !           587: keybindings are very easy to change.  The keybindings described here
        !           588: are the default or standard ones.
        !           589: 
        !           590: The major features of Texinfo mode are:
        !           591: 
        !           592:    * Paragraph filling control.
        !           593: 
        !           594:    * A command to show the structure of the file.
        !           595: 
        !           596:    * Pre-defined keystroke commands to insert commonly used strings
        !           597:      of text.
        !           598: 
        !           599:    * Formatting a part of a file for Info, rather than the whole file.
        !           600: 
        !           601: In general, in Texinfo mode, the GNU Emacs editing commands are like
        !           602: those in text-mode.  The major difference is that the paragraph
        !           603: separation variable and syntax table are set up so expression
        !           604: commands skip Texinfo bracket groups.  This means, for example, that
        !           605: the `M-q' (`fill-paragraph') command will refill a paragraph but not
        !           606: the @-command on a line adjacent to it.
        !           607: 
        !           608: By convention, the Texinfo file name shall end with the extension
        !           609: `.texinfo' so that Emacs knows to use Texinfo mode for editing it.
        !           610: 
        !           611: * Menu:
        !           612: 
        !           613: * Info on a Region::           Formatting part of a file for Info.
        !           614: * Showing the Structure::      Showing the structure of a file.
        !           615: * Inserting::                  Inserting frequently used commands.
        !           616: 
        !           617: 
        !           618: 
        !           619: File: texinfo,  Node: Info on a Region,  Next: Showing the Structure,  Prev: Texinfo Mode,  Up: Texinfo Mode
        !           620: 
        !           621: Formatting a Region for Info
        !           622: ============================
        !           623: 
        !           624: To see what part of a Texinfo file will look like after it has been
        !           625: transformed into an Info file, use the command `C-c C-f'
        !           626: (`texinfo-format-region').  This command formats the current region
        !           627: of the Texinfo file for Info and writes it to a temporary buffer
        !           628: called `*Info Region*'.
        !           629: 
        !           630: For `texinfo-format-region' to work, the file *must* include a line
        !           631: that has `@setfilename' in its header.
        !           632: 
        !           633: The command is:
        !           634: 
        !           635: `C-c C-f'
        !           636:      texinfo-format-region
        !           637: 
        !           638: 
        !           639: 
        !           640: File: texinfo,  Node: Showing the Structure,  Next: Inserting,  Prev: Info on a Region,  Up: Texinfo Mode
        !           641: 
        !           642: Showing the Structure of a File
        !           643: ===============================
        !           644: 
        !           645: You can show the structure of a Texinfo file by using the `C-c C-s'
        !           646: command (`texinfo-show-structure').  This command shows the structure
        !           647: of a Texinfo file by listing the lines with the @-commands for
        !           648: `@node', `@chapter', `@section' and the like.  These lines are
        !           649: displayed in another window called the `*Occur*' window.  In that
        !           650: window, you can position the cursor over one of the lines and use the
        !           651: `C-c C-c' command (`occur-mode-goto-occurrence'), to jump to the
        !           652: corresponding spot in the Texinfo file.
        !           653: 
        !           654: The two commands are:
        !           655: 
        !           656: `C-c C-s'
        !           657:      texinfo-show-structure
        !           658: 
        !           659: `C-c C-c'
        !           660:      occur-mode-goto-occurrence
        !           661: 
        !           662: Often, when you are working on a manual, you will be interested only
        !           663: in the structure of the current chapter.  In this case, you can mark
        !           664: off the region of the buffer that you are interested in with the `C-x
        !           665: n' (`narrow-to-region') command and `texinfo-show-structure' will
        !           666: work on only that region.  (To see the whole buffer again, use `C-x
        !           667: w' (`widen').)
        !           668: 
        !           669: 
        !           670: 
        !           671: File: texinfo,  Node: Inserting,  Prev: Showing the Structure,  Up: Texinfo Mode
        !           672: 
        !           673: Inserting Frequently Used Commands
        !           674: ==================================
        !           675: 
        !           676: Texinfo mode provides commands that insert various frequently used
        !           677: @-commands into the buffer.  You can use these commands to save
        !           678: keystrokes.  And you can insert balanced curly braces with the `M-{'
        !           679: command, (`texinfo-insert-braces') and later use the `M-}' command
        !           680: (`up-list') to move forward past the closing brace.
        !           681: 
        !           682: The special commands are invoked by typing `C-c' twice and then the
        !           683: first letter of the @-command.
        !           684: 
        !           685: `C-c C-c c'
        !           686:      texinfo-insert-@code
        !           687: 
        !           688: `C-c C-c d'
        !           689:      texinfo-insert-@dfn
        !           690: 
        !           691: `C-c C-c e'
        !           692:      texinfo-insert-@end
        !           693: 
        !           694: `C-c C-c i'
        !           695:      texinfo-insert-@item
        !           696: 
        !           697: `C-c C-c n'
        !           698:      texinfo-insert-@node
        !           699: 
        !           700: `C-c C-c s'
        !           701:      texinfo-insert-@samp
        !           702: 
        !           703: `C-c C-c v'
        !           704:      texinfo-insert-@var
        !           705: 
        !           706: `M-{'
        !           707:      texinfo-insert-braces
        !           708: 
        !           709: `M-}'
        !           710:      up-list
        !           711: 
        !           712: This list was generated by analyzing the frequency with which
        !           713: commands were used in the ``GNU Emacs Manual'' and the ``GDB
        !           714: Manual''.  If you wish to add your own insert commands, you can bind
        !           715: a keyboard macro to a key, use abbreviations or extend the code in
        !           716: `texinfo.el'.
        !           717: 
        !           718: 
        !           719: 
        !           720: File: texinfo,  Node: Beginning a File,  Next: Ending a File,  Prev: Texinfo Mode,  Up: Top
        !           721: 
        !           722: Beginning a Texinfo File
        !           723: ************************
        !           724: 
        !           725: Various pieces of information have to be provided to Texinfo at the
        !           726: beginning of a Texinfo file, such as the name of the file, the title
        !           727: of the document and the like.  Generally, the beginning of a Texinfo
        !           728: file has four parts:
        !           729: 
        !           730:   1. The header, marked by start-of-header and end-of-header lines,
        !           731:      that includes the commands for naming the Texinfo file and
        !           732:      telling TeX what definitions' file to use when processing the
        !           733:      file.
        !           734: 
        !           735:   2. A section, marked by the `@ifinfo' and `@end ifinfo' commands,
        !           736:      that contains a short statement of what the file is about, the
        !           737:      copyright notice and copying permissions. This section appears
        !           738:      only in the Info file.
        !           739: 
        !           740:   3. A section, marked by the `@titlepage' and `@end titlepage'
        !           741:      commands, that contains the title page, the copyright page and
        !           742:      copying permissions.  This section appears only in the printed
        !           743:      manual.
        !           744: 
        !           745:   4. The `Top' node that contains an extensive menu for the whole
        !           746:      Info file.  The contents of this node only appear in the Info
        !           747:      file.
        !           748: 
        !           749: If the Texinfo file has a section containing licensing information
        !           750: and a warranty disclaimer, that section usually follows the `Top'
        !           751: node.  The licensing section will be followed by a preface or else by
        !           752: the first chapter of the manual.
        !           753: 
        !           754: Since the copyright notice and the copying permissions are in
        !           755: sections that appear only in the Info file or only in the printed
        !           756: manual, this information has to be repeated twice.
        !           757: 
        !           758: The following sample shows what is needed.
        !           759: 
        !           760:      \input texinfo   @c -*-texinfo-*-
        !           761:      @comment %**start of header (This is for running Texinfo on a region.)
        !           762:      @setfilename name-of-texinfo-file
        !           763:      @settitle Name of Manual
        !           764:      @setchapternewpage odd
        !           765:      @comment %**end of header (This is for running Texinfo on a region.)
        !           766:      
        !           767:      @ifinfo
        !           768:      This file documents ...
        !           769:      
        !           770:      Copyright @copyright{} year  copyright-owner
        !           771:      
        !           772:      Permission is granted to ...
        !           773:      @end ifinfo
        !           774:      
        !           775:      @titlepage
        !           776:      @sp 10
        !           777:      @center @titlefont{Name of Manual When Printed}
        !           778:      @sp 2
        !           779:      @center Subtitle, If Any
        !           780:      @sp 2
        !           781:      @center Author
        !           782:      
        !           783:      @comment  The following two commands start the copyright page.
        !           784:      @page
        !           785:      @vskip 0pt plus 1filll
        !           786:      Copyright @copyright{} year copyright-owner
        !           787:      
        !           788:      Published by ...
        !           789:      
        !           790:      Permission is granted to ...
        !           791:      @end titlepage
        !           792:      
        !           793:      
        !           794:      @node Top, Overview, (dir), (dir)
        !           795:      
        !           796:      @menu
        !           797:      * First Chapter::         The first chapter is usually an overview.
        !           798:      * Second Chapter::                ...
        !           799:        <many more menu items here>
        !           800:      @end menu
        !           801:      
        !           802:      @node    First Chapter, Second Chapter, top,      top
        !           803:      @comment node-name,     next,           previous, up
        !           804:      @chapter First Chapter
        !           805:      @cindex Reference to First Chapter
        !           806: 
        !           807: * Menu:
        !           808: 
        !           809: * Header::                     Necessary first lines.
        !           810: * Permissions for Info::       Copyright notice and copying permissions.
        !           811: * Titlepage & Copyright Page:: Printed title and copyright pages.
        !           812: * Top Node::                   The top node and master menu.
        !           813: * License and Distribution::   The importance of the license.
        !           814: 
        !           815: 
        !           816: 
        !           817: File: texinfo,  Node: Header,  Next: Permissions for Info,  Prev: Beginning a File,  Up: Beginning a File
        !           818: 
        !           819: The Texinfo File Header
        !           820: =======================
        !           821: 
        !           822: Texinfo files start with at least three lines that provide Info and
        !           823: TeX with necessary information.  If you want to run TeX on just a
        !           824: part of the Texinfo File, you also have to mark these heading lines
        !           825: with start-of-header and end-of-header lines.
        !           826: 
        !           827: * Menu:
        !           828: 
        !           829: * First Line::                 The first line of a Texinfo file.
        !           830: * Start-of-Header::            Identifying the start of the header.
        !           831: * Setfilename::                        Specifying the name of the Info file.
        !           832: * Settitle::                   Specifying the title used by the headings.
        !           833: * Setchapternewpage::          Starting chapters on odd numbered pages.
        !           834: * End-of-Header::              Identifying the end of the header.
        !           835: 
        !           836:  
        !           837: 
        !           838: File: texinfo,  Node: First Line,  Next: Start-of-Header,  Prev: Header,  Up: Header
        !           839: 
        !           840: The First Line of a Texinfo File
        !           841: --------------------------------
        !           842: 
        !           843: Every Texinfo file that is to be the top-level input to TeX must
        !           844: begin with a line that looks like this:
        !           845: 
        !           846:      \input texinfo   @c -*-texinfo-*-
        !           847: 
        !           848: The line serves two functions:
        !           849: 
        !           850:   1. When the file is processed by TeX, it loads the macros needed
        !           851:      for processing a Texinfo file.  These are in a file called
        !           852:      `texinfo.tex' which is usually located in the
        !           853:      `/usr/lib/tex/macros' directory.
        !           854: 
        !           855:   2. When the file is edited in GNU Emacs, it causes Texinfo mode to
        !           856:      be used.
        !           857: 
        !           858: The `\input texinfo' line should be followed by the start-of-header
        !           859: line.  This makes it possible for the command for running TeX on a
        !           860: part of the Texinfo file (`texinfo-hardcopy-region') to operate.  The
        !           861: reason for this is that the `texinfo-hardcopy-region' command will
        !           862: look on the line preceding the start-of-header line for the `\input
        !           863: texinfo' line.
        !           864: 
        !           865: 
        !           866: 
        !           867: File: texinfo,  Node: Start-of-Header,  Next: Setfilename,  Prev: First Line,  Up: Header
        !           868: 
        !           869: `start-of-header'
        !           870: -----------------
        !           871: 
        !           872: The start-of-header line should immediately follow the first line of
        !           873: the Texinfo file.
        !           874: 
        !           875: The `texinfo-hardcopy-region' command will look at the line preceding
        !           876: the start-of-header line to find the `\input texinfo' line.
        !           877: 
        !           878: Usually, the start-of-header line looks like this:
        !           879: 
        !           880:      @comment %**start of header (This is for running Texinfo on a region.)
        !           881: 
        !           882: The reason for the odd string of characters (`%**') is so that the
        !           883: `texinfo-hardcopy-region' command does not accidently find something
        !           884: that it shouldn't when it is looking for the header.
        !           885: 
        !           886: In the default configuration, the phrase `(This is for running
        !           887: Texinfo on a region.)' is not needed and is just included to make it
        !           888: easier for someone reading the Texinfo file.
        !           889: 
        !           890: The start-of-header line and the end-of-header line are Texinfo mode
        !           891: variables that you can change.
        !           892: 
        !           893: 
        !           894: 
        !           895: File: texinfo,  Node: Setfilename,  Next: Settitle,  Prev: Start-of-Header,  Up: Header
        !           896: 
        !           897: @setfilename
        !           898: ------------
        !           899: 
        !           900: In order to be made into an Info file, a Texinfo file must contain a
        !           901: line that looks like this:
        !           902: 
        !           903:      @setfilename INFO-FILE-NAME
        !           904: 
        !           905: This line specifies the name of the Info file to be generated.  In
        !           906: fact, there can be other things in the file before this line, but
        !           907: they are ignored in the generation of an Info file.  The
        !           908: `@setfilename' line is ignored when a printed manual is generated.
        !           909: 
        !           910: 
        !           911: 
        !           912: File: texinfo,  Node: Settitle,  Next: Setchapternewpage,  Prev: Setfilename,  Up: Header
        !           913: 
        !           914: @settitle
        !           915: ---------
        !           916: 
        !           917: In order to be made into a printed manual file, a Texinfo file must
        !           918: contain a line that specifies the title of the manual.  Texinfo uses
        !           919: this information during printing to put the title on every other page
        !           920: as a heading; Texinfo puts the current chapter title on the other
        !           921: pages.  Texinfo can find the name of the chapter title from the
        !           922: information provided by the `@chapter' command, but you must tell it
        !           923: the manual title with `@settitle':
        !           924: 
        !           925:      @settitle TITLE
        !           926: 
        !           927: This command, on a line by itself, causes TITLE to be used for the
        !           928: headings.  Usually, you will use the same words for the title on the
        !           929: title page and for the title specified by this command for the
        !           930: headings, but the two could be different.  For example, the title on
        !           931: the title page may be longer than the title specified by the
        !           932: `settitle' command.
        !           933: 
        !           934: The `@settitle' command should precede everything that generates
        !           935: actual output.
        !           936: 
        !           937: 
        !           938: 
        !           939: File: texinfo,  Node: Setchapternewpage,  Next: End-of-Header,  Prev: Settitle,  Up: Header
        !           940: 
        !           941: @setchapternewpage
        !           942: ------------------
        !           943: 
        !           944: Conventionally, chapters start on the page on the right hand side of
        !           945: a book; and the right hand page has an odd number.  To make sure that
        !           946: Texinfo does this, you can use the command `@setchapternewpage'.  For
        !           947: example, to cause each chapter to start on a fresh odd-numbered page:
        !           948: 
        !           949:      @setchapternewpage odd
        !           950: 
        !           951: Page numbering is turned on by the `@end titlepage' command, so the
        !           952: `@setchapternewpage' should come before it.  Although it can occur
        !           953: anywhere in the beginning of the file, it is most convenient to put
        !           954: it in this location.
        !           955: 
        !           956: 
        !           957: 
        !           958: File: texinfo,  Node: End-of-Header,  Prev: Setchapternewpage,  Up: Header
        !           959: 
        !           960: `end-of-header'
        !           961: ---------------
        !           962: 
        !           963: The end-of-header line should follow the line containing the
        !           964: `@setchapternewpage' command.
        !           965: 
        !           966: Usually, the end-of-header line looks like this:
        !           967: 
        !           968:      @comment %**end of header (This is for running Texinfo on a region.)
        !           969: 
        !           970: In the default configuration, the phrase `(This is for running
        !           971: Texinfo on a region.)' is not needed and is just included to make it
        !           972: easier for someone reading the Texinfo file.
        !           973: 
        !           974: The reason for the odd string of characters (`%**') is so that the
        !           975: `texinfo-hardcopy-region' command does not accidently find something
        !           976: that it shouldn't when it is looking for the header.
        !           977: 
        !           978: The start-of-header line and the end-of-header line are Texinfo mode
        !           979: variables that you can change.
        !           980: 
        !           981: 
        !           982: 
        !           983: File: texinfo,  Node: Permissions for Info,  Next: Titlepage & Copyright Page,  Prev: Header,  Up: Beginning a File
        !           984: 
        !           985: Copying Permissions for Info
        !           986: ============================
        !           987: 
        !           988: Since the title page and the copyright page appear only in the
        !           989: printed copy of the manual, the same information has to inserted in a
        !           990: section that appears only in the Info file.  This section usually
        !           991: contains a brief description of the contents of the Info file, a
        !           992: copyright notice and copying permissions.
        !           993: 
        !           994: The copyright notice should read:
        !           995: 
        !           996:      Copyright YEAR COPYRIGHT-OWNER
        !           997: 
        !           998: and be put on a line by itself.
        !           999: 
        !          1000: Standard text for the copyright permissions is contained in the
        !          1001: appendix.  *Note Ifinfo Permissions::, for the complete text.
        !          1002: 
        !          1003: 
        !          1004: 
        !          1005: File: texinfo,  Node: Titlepage & Copyright Page,  Next: Top Node,  Prev: Permissions for Info,  Up: Beginning a File
        !          1006: 
        !          1007: The Title and Copyright Pages
        !          1008: =============================
        !          1009: 
        !          1010: The title and copyright pages appear in the printed manual, but not
        !          1011: in the Info file.  Because of this, it is possible to use a couple of
        !          1012: slightly obscure TeX typesetting commands that could not be used in
        !          1013: an Info file.  In addition, this part of the beginning of a Texinfo
        !          1014: file contains the text of the copying permissions that will appear in
        !          1015: the printed manual.
        !          1016: 
        !          1017: * Menu:
        !          1018: 
        !          1019: * Titlepage::                  Creating a title page for the printed manual.
        !          1020: * Center::                     Centering a line.
        !          1021: * Copyright & Printed Permissions::    Inserting the copyright notice 
        !          1022:                                        and printed permissions.
        !          1023: 
        !          1024:  
        !          1025: 
        !          1026: File: texinfo,  Node: Titlepage,  Next: Center,  Prev: Setchapternewpage,  Up: Titlepage & Copyright Page
        !          1027: 
        !          1028: @titlepage
        !          1029: ----------
        !          1030: 
        !          1031: Start the material for the title page and following copyright page
        !          1032: with `@titlepage' on a line by itself and end it with `@end
        !          1033: titlepage' on a line by itself.  The title page and copyright page
        !          1034: material appears only in the printed manual, not in the Info file.
        !          1035: 
        !          1036: Also, the `@end titlepage' command starts a new page and turns on
        !          1037: page numbering (generation of headings).  Therefore, all the material
        !          1038: that you want to appear on unnumbered pages should be put between the
        !          1039: `@titlepage' and `@end titlepage' commands.  By using the `@page'
        !          1040: command you can force a page break within the region delineated by
        !          1041: the `@titlepage' and `@end titlepage' commands and create more than
        !          1042: one unnumbered page.  This is how the copyright page is produced.
        !          1043: 
        !          1044: To select a large font suitable for the title itself, you can use the
        !          1045: command `@titlefont'.  For example:
        !          1046: 
        !          1047:      @center @titlefont{Texinfo}
        !          1048: 
        !          1049: Also, you can use `@sp' commands to adjust vertical spacing.   For
        !          1050: example:
        !          1051: 
        !          1052:      @sp 2
        !          1053: 
        !          1054: In the sample, the spacing was chosen to fit an 8 1/2 by 11 inch
        !          1055: manual.
        !          1056: 
        !          1057: 
        !          1058: 
        !          1059: File: texinfo,  Node: Center,  Next: Titlepage,  Prev: Copyright & Printed Permissions,  Up: Titlepage & Copyright Page
        !          1060: 
        !          1061: @center
        !          1062: -------
        !          1063: 
        !          1064: A line containing `@center TEXT' produces a line of output containing
        !          1065: TEXT, centered between the margins.
        !          1066: 
        !          1067: 
        !          1068: 
        !          1069: File: texinfo,  Node: Copyright & Printed Permissions,  Next: Center,  Up: Titlepage & Copyright Page
        !          1070: 
        !          1071: The Copyright Page and Printed Permissions
        !          1072: ------------------------------------------
        !          1073: 
        !          1074: By international treaty, the copyright notice for a book should
        !          1075: either be on the title page or on the back of the title page.  Other
        !          1076: locations in a book are not official and do not provide copyright
        !          1077: protection.  The copyright notice should include the year followed by
        !          1078: the name of the person or organization who has the copyright.
        !          1079: 
        !          1080: When the copyright notice is on the back of the title page, the page
        !          1081: is not numbered.  Therefore, in Texinfo, the information on the
        !          1082: copyright page should be within the region delineated by the
        !          1083: `@titlepage' and `@end titlepage' commands.
        !          1084: 
        !          1085: To cause a page break, the `@page' command is used.  In the sample,
        !          1086: the `@page' command is followed by the somewhat mysterious line that
        !          1087: reads: `@vskip 0pt plus 1filll'.  This is a line that uses TeX
        !          1088: commands to push the copyright notice and the other text on the
        !          1089: copyright page towards the bottom of the page.  The `@vskip' command
        !          1090: means to skip lines and put in white space.  The `0pt plus 1filll'
        !          1091: means to put in zero points of mandatory white space, and as much
        !          1092: optional white space as needed.  Note the use of three `l's in the
        !          1093: word `filll'; this is the correct use in TeX.
        !          1094: 
        !          1095: The `@copyright{}' command generates a `c' inside a circle.  The
        !          1096: copyright notice itself has the following legally defined sequence:
        !          1097: 
        !          1098:      Copyright (C) YEAR COPYRIGHT-OWNER
        !          1099: 
        !          1100: It is customary to put information on how to get a manual after the
        !          1101: copyright notice (the address of the Free Software Foundation, for
        !          1102: example) and the permissions.
        !          1103: 
        !          1104: Note that the permissions have to be repeated here as well as in the
        !          1105: `ifinfo' section that immediately follows the header since this
        !          1106: section appears only in the printed manual and the `ifinfo' section
        !          1107: appears only in the Info file.
        !          1108: 
        !          1109: Standard text for the permissions appears in the appendix.   *Note
        !          1110: Sample Permissions::.
        !          1111: 
        !          1112: 
        !          1113: 
        !          1114: File: texinfo,  Node: Top Node,  Next: License and Distribution,  Prev: Titlepage & Copyright Page,  Up: Beginning a File
        !          1115: 
        !          1116: The Top Node and Master Menu
        !          1117: ============================
        !          1118: 
        !          1119: The `Top' node contains an extensive, master menu for the whole Info
        !          1120: file.  The contents of this node appear only in the Info file. 
        !          1121: Nothing in this node should appear in the printed file.  Since a node
        !          1122: line by itself and a menu by itself are not printed, the contents of
        !          1123: this node do not have to be within a region delineated by `@ifinfo'
        !          1124: and `@end ifinfo' commands.  However, any text within the node should
        !          1125: be marked off in that manner.  You may want to put a short summary
        !          1126: before the master menu inside a region delineated by `@ifinfo' and
        !          1127: `@end ifinfo' commands.  Usually, the `Previous' and `Up' nodes refer
        !          1128: to the top level directory of the whole Info system, with pointers to
        !          1129: `(dir)'.
        !          1130: 
        !          1131: Generally, the top menu is divided into parts.
        !          1132: 
        !          1133:    * The first part contains the major nodes in the Texinfo file: the
        !          1134:      nodes for the chapters, chapter-like sections and the major
        !          1135:      appendices.
        !          1136: 
        !          1137:    * The second part contains entries for the indices.  In an Info
        !          1138:      file, it is very useful to have indices here at the beginning of
        !          1139:      the file in the top node rather than at the end, as in a printed
        !          1140:      book.
        !          1141: 
        !          1142:    * The third and subsequent parts contain a listing of the other,
        !          1143:      lower level nodes, often ordered by chapter.  This way, an
        !          1144:      inquirer can go directly to a particular node if he or she is
        !          1145:      searching for specific information.  (These nodes are not
        !          1146:      required; use them if you think they are a convenience.)
        !          1147: 
        !          1148: Each section in the menu can be introduced a descriptive line.  So
        !          1149: long as the line does not begin with an asterisk, it will not be
        !          1150: treated as a menu item.  (*Note Making Menus: Menu, for more
        !          1151: information.)
        !          1152: 
        !          1153: For example, the Top node of this manual looks like this (but with
        !          1154: many more entries):
        !          1155: 
        !          1156:      @node Top, Overview, (dir), (dir)
        !          1157:      
        !          1158:      @menu
        !          1159:      * Overview::                    What is Texinfo?
        !          1160:      * Texinfo Mode::                Special features in GNU Emacs.
        !          1161:      ...
        !          1162:      
        !          1163:      Indices, nodes containing large menus
        !          1164:      
        !          1165:      * Command Index::               An item for each @-command.
        !          1166:      * Concept Index::               An item for each concept.
        !          1167:      
        !          1168:      A detailed node listing
        !          1169:      
        !          1170:      Overview
        !          1171:      * Info File::                   Characteristics of the Info file.
        !          1172:      * Printed Manual::              Characteristics of the printed manual.
        !          1173:      
        !          1174:      Using Texinfo Mode
        !          1175:      * Info on a Region::            Formatting a region for Info.
        !          1176:      * Showing the Structure::       Showing the structure of a file.
        !          1177:      ...
        !          1178:      ...
        !          1179: 
        !          1180:  
        !          1181: 
        !          1182: File: texinfo,  Node: License and Distribution,  Prev: Top Node,  Up: Beginning a File
        !          1183: 
        !          1184: Licensing and Distribution Information
        !          1185: ======================================
        !          1186: 
        !          1187: If the Texinfo file has a section containing the ``General Public
        !          1188: License'' and the distribution information and a warranty disclaimer,
        !          1189: this section usually follows the `Top' node.  The licensing and
        !          1190: distribution information and the disclaimer are followed by a preface
        !          1191: or else by the first chapter of the manual.
        !          1192: 
        !          1193: The licensing agreement is very important to Project GNU
        !          1194: documentation and software.  Without it, you may find that you can no
        !          1195: longer get the software or its documentation.  This sounds
        !          1196: paradoxical, but the state of the world is such that documentation
        !          1197: and software that does not have a ``restrictive'' license to make
        !          1198: them freely distributable may be lost to the public.  This has
        !          1199: happened.
        !          1200: 
        !          1201: For a good example of the text that could be used for the
        !          1202: Distribution, General Public License and NO WARRANTY sections of your
        !          1203: document, see the latest version of the ``GNU Emacs Manual''.
        !          1204: 
        !          1205: Although a preface is not a required part of a Texinfo file, it is
        !          1206: very helpful.  Ideally, it should state clearly and concisely what
        !          1207: the file is about and who would be interested in reading it.  In
        !          1208: general, the preface would follow the licensing and distribution
        !          1209: information, although sometimes people put it earlier in the
        !          1210: document.  Usually, a preface is put in an `@unnumbered' section. 
        !          1211: (*Note Unnumbered and Appendix::.)
        !          1212: 
        !          1213: 
        !          1214: 
        !          1215: File: texinfo,  Node: Ending a File,  Next: Structuring,  Prev: Beginning a File,  Up: Top
        !          1216: 
        !          1217: Ending a Texinfo File
        !          1218: *********************
        !          1219: 
        !          1220: The end of a Texinfo file should include the indices, the commands to
        !          1221: generate detailed and summary tables of contents and the @-command
        !          1222: that tells TeX that it has reached the end of the file.
        !          1223: 
        !          1224: For example, a Texinfo file might be ended as follows:
        !          1225: 
        !          1226:      @node    Concept Index,     , Previous Node, Top
        !          1227:      @comment node-name,     next, previous,      up
        !          1228:      @unnumbered Concept Index
        !          1229:      
        !          1230:      @printindex cp
        !          1231:      
        !          1232:      @contents
        !          1233:      @bye
        !          1234: 
        !          1235: The `@bye' command should be on a line by itself and every Texinfo
        !          1236: file must end with such a line.  This command terminates TeX
        !          1237: processing and forces out unfinished pages.
        !          1238: 
        !          1239: * Menu:
        !          1240: 
        !          1241: * Contents::           Generating a table of contents
        !          1242: * Indices::            Generating, sorting and printing indices
        !          1243: 
        !          1244: 
        !          1245: 
        !          1246: File: texinfo,  Node: Contents,  Next: Indices,  Up: Ending a File
        !          1247: 
        !          1248: Generating a Table of Contents
        !          1249: ==============================
        !          1250: 
        !          1251: The commands `@chapter', `@section', etc., supply the information to
        !          1252: make up a table of contents, but they do not cause an actual table to
        !          1253: be generated.  To do this, you must use the commands `@contents' and
        !          1254: `@summarycontents'.
        !          1255: 
        !          1256: `@contents'
        !          1257:      The table of contents command outputs (into a printed manual) a
        !          1258:      complete table of contents, based on the `@chapter',
        !          1259:      `@unnumbered' and other sectioning commands.  This command
        !          1260:      should be used on a line by itself.
        !          1261: 
        !          1262: `@summarycontents'
        !          1263:      The summary contents command generates a summary table of
        !          1264:      contents that lists only the chapters (and appendices and
        !          1265:      unnumbered chapters); sections, subsections and subsubsections
        !          1266:      are omitted.  This command should be used on a line by itself. 
        !          1267:      Only large manuals need a summary table of contents.
        !          1268: 
        !          1269: You can use either one of these commands, or both.  Each command
        !          1270: automatically generates a chapter-like heading at the top of the page.
        !          1271: Tables of contents should be generated at the very end of the manual,
        !          1272: just before the `@bye' command; the tables of contents commands
        !          1273: should follow any indices that are output, so that the indices will
        !          1274: appear in the contents.
        !          1275: 
        !          1276:      INDICES...
        !          1277:      @summarycontents
        !          1278:      @contents
        !          1279:      @bye
        !          1280: 
        !          1281: The commands `@contents' and `@summarycontents' are ignored when an
        !          1282: Info file is being generated.
        !          1283: 
        !          1284: 

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