Return to texinfo-2 CVS log

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

Annotation of 43BSDReno/contrib/emacs-18.55/info/texinfo-2, 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: Indices,  Prev: Contents,  Up: Ending a File
        !            29: 
        !            30: Creating Indices
        !            31: ================
        !            32: 
        !            33: Using Texinfo, you can generate printed indices and Info file menus
        !            34: without having to sort and collate entries manually.  Texinfo will do
        !            35: this for you automatically.  Each index covers a certain kind of
        !            36: entry (functions, or variables, or concepts, etc.) and lists all of
        !            37: those entries in alphabetical order, together with information on how
        !            38: to find the discussion of each entry.  In a printed manual, this
        !            39: information consists of page numbers.  In an Info file, it consists
        !            40: of a menu item leading to the first node referenced.
        !            41: 
        !            42: When you are making index entries, it is good practice to think of
        !            43: the different categories under which people may look for something. 
        !            44: Different people *do not* think of the same words when they look
        !            45: something up.  They think of different words.  A helpful index will
        !            46: have items indexed under all the different words that people may use.
        !            47: For example, someone might think it obvious that the two letter names
        !            48: for indices should be listed under ``Indices, two letter names'',
        !            49: since the word ``Index'' is the general concept.  But another reader
        !            50: may remember the specific concept of two letter names and search for
        !            51: the entry listed as ``Two letter names for indices''.  A good index
        !            52: will have both entries and will help both kinds of user.
        !            53: 
        !            54: Like typesetting, the construction of an index is a highly skilled,
        !            55: professional art, the subtleties of which are not appreciated until
        !            56: you have to do it yourself.
        !            57: 
        !            58: Normally, six indices are provided for:
        !            59: 
        !            60:    * A "program index" listing names of programs and leading to the
        !            61:      places where those programs are documented.
        !            62: 
        !            63:    * A "function index" listing functions (such as, entry points of
        !            64:      libraries).
        !            65: 
        !            66:    * A "variables index" listing variables (such as, external
        !            67:      variables of libraries).
        !            68: 
        !            69:    * A "data type index" listing data types (such as, structures
        !            70:      defined in header files).
        !            71: 
        !            72:    * A "keystroke index" listing keyboard commands.
        !            73: 
        !            74:    * A "concept index" listing concepts that are discussed.
        !            75: 
        !            76: Not every manual needs all of these.  This manual has two indices: a
        !            77: concept index and an @-command index (that uses the function index
        !            78: but is called a command index in the chapter heading).  Two or more
        !            79: indices can be combined into one using the `@synindex' command. 
        !            80: *Note Combining Indices::.
        !            81: 
        !            82: * Menu:
        !            83: 
        !            84: * Index Entries::      Defining the entries of an index
        !            85: * Combining Indices::
        !            86: * Printing Indices & Menus::
        !            87: 
        !            88: 
        !            89: 
        !            90: File: texinfo,  Node: Index Entries,  Next: Combining Indices,  Up: Indices
        !            91: 
        !            92: Defining the Entries of an Index
        !            93: --------------------------------
        !            94: 
        !            95: The data to make an index comes from many individual commands
        !            96: scattered throughout the Texinfo source file.  Each command says to
        !            97: add one entry to a particular index; after processing, it will give
        !            98: the current page number or node name as the reference.
        !            99: 
        !           100: `@cindex CONCEPT'
        !           101:      Make an entry in the concept index for CONCEPT, referring to the
        !           102:      current page or node.
        !           103: 
        !           104: `@findex FUNCTION'
        !           105:      Make an entry in the function index for FUNCTION, referring to
        !           106:      the current page or node.
        !           107: 
        !           108: `@vindex VARIABLE'
        !           109:      Make an entry in the variable index for VARIABLE, referring to
        !           110:      the current page or node.
        !           111: 
        !           112: `@pindex PROGRAM'
        !           113:      Make an entry in the program index for PROGRAM, referring to the
        !           114:      current page or node.
        !           115: 
        !           116: `@kindex KEY'
        !           117:      Make an entry in the key index for KEY, referring to the current
        !           118:      page or node.
        !           119: 
        !           120: `@tindex DATA TYPE'
        !           121:      Make an entry in the data type index for DATA TYPE, referring to
        !           122:      the current page or node.
        !           123: 
        !           124: If the same name is indexed on several pages, all the pages are
        !           125: listed in the printed manual's index.  However, *only* the *first*
        !           126: node referenced will appear in the index of an Info file.  This means
        !           127: that it is best to write indices in which each entry will refer to
        !           128: only one place in the Texinfo file.  Fortunately, this constraint is
        !           129: a feature rather than loss since it means that the index will be easy
        !           130: to use.  Otherwise, it can be easy to create an index which has many
        !           131: pages listed for an entry and you don't know which one you need.
        !           132: 
        !           133: You are not actually required to use indices for their canonical
        !           134: purposes.  For example, you might wish to index some C preprocessor
        !           135: macros.  You could put them in the function index along with actual
        !           136: functions, just by writing `@findex' commands for them; then, when
        !           137: you print the ``function index'', you could give it the title
        !           138: `Function and Macro Index' and all will be consistent for the reader.
        !           139: Or you could put the macros in with the data types by writing
        !           140: `@tindex' commands for them, and give that index a suitable title so
        !           141: the reader will understand.
        !           142: 
        !           143: 
        !           144: 
        !           145: File: texinfo,  Node: Combining Indices,  Next: Printing Indices & Menus,  Prev: Index Entries,  Up: Indices
        !           146: 
        !           147: Combining Indices
        !           148: -----------------
        !           149: 
        !           150: Sometimes you will want to combine two disparate indices such as
        !           151: functions and variables, perhaps because you have few enough of one
        !           152: of them that a separate index for them would look silly.
        !           153: 
        !           154: You could put variables into the function index by writing `@findex'
        !           155: commands for them instead of `@vindex' commands, and produce a
        !           156: consistent manual by printing the function index with the title
        !           157: `Function and Variable Index' and not printing the `Variable Index'
        !           158: at all; but this is not a robust procedure.  It works only as long as
        !           159: your document is never included in part of or together with another
        !           160: document that is designed to have a separate variable index; if you
        !           161: did that, the variables from your document and those from the other
        !           162: would not end up together.
        !           163: 
        !           164: What you should do instead when you want functions and variables in
        !           165: one index is to index the variables with `@vindex' as they should be,
        !           166: but use the `@synindex' command to redirect these `@vindex' commands
        !           167: to the function index.  `@synindex' takes two arguments: the name of
        !           168: an index to redirect, and the name of an index to redirect it to. 
        !           169: For this purpose, the indices are given two-letter names:
        !           170: 
        !           171: `cp'
        !           172:      the concept index
        !           173: 
        !           174: `vr'
        !           175:      the variable index
        !           176: 
        !           177: `fn'
        !           178:      the function index
        !           179: 
        !           180: `ky'
        !           181:      the key index
        !           182: 
        !           183: `pg'
        !           184:      the program index
        !           185: 
        !           186: `tp'
        !           187:      the data type index
        !           188: 
        !           189: Thus, `@synindex vr fn' at the front of a Texinfo file will cause all
        !           190: entries designated for the variable index to go to the function index
        !           191: instead.
        !           192: 
        !           193: 
        !           194: 
        !           195: File: texinfo,  Node: Printing Indices & Menus,  Prev: Combining Indices,  Up: Indices
        !           196: 
        !           197: Printing an Index and Generating Menus
        !           198: --------------------------------------
        !           199: 
        !           200: To print an index means to include it as part of a manual or Info file.
        !           201: This does not happen automatically just because you use `@cindex' or
        !           202: other index-entry generating commands in the Texinfo file; those just
        !           203: cause the raw data for the index to be accumulated.  To print an
        !           204: index, you must include the `@printindex' command at the place in the
        !           205: document where you want the index to appear.  Also, for the case of
        !           206: the printed manual, you must run a program called `texindex' to sort
        !           207: the raw data to produce a sorted index file, which is what will
        !           208: actually be used to print the index.
        !           209: 
        !           210: The Texinfo command that is used to print indices is `@printindex'. 
        !           211: It takes the two-letter index name (*note Combining Indices::.) as an
        !           212: argument without braces, and reads the corresponding sorted index
        !           213: file and formats it appropriately into an index.
        !           214: 
        !           215: The two-letter index names are:
        !           216: 
        !           217: `cp'
        !           218:      the concept index.
        !           219: 
        !           220: `vr'
        !           221:      the variable index.
        !           222: 
        !           223: `fn'
        !           224:      the function index.
        !           225: 
        !           226: `ky'
        !           227:      the key index.
        !           228: 
        !           229: `pg'
        !           230:      the program index.
        !           231: 
        !           232: `tp'
        !           233:      the data type index.
        !           234: 
        !           235: `@printindex' does not generate a chapter heading for the index. 
        !           236: Consequently, you should precede the command with a suitable section
        !           237: or chapter command (usually `@unnumbered') to supply the chapter
        !           238: heading and put the index into the table of contents.  And before
        !           239: that, you will probably put a `@node' command.  For example,
        !           240: 
        !           241:      @node Variables Index, Concept Index, Function Index, Top
        !           242:      @comment    node-name,          next,       previous,  up
        !           243:      @unnumbered Variable Index
        !           244:      
        !           245:      @printindex vr
        !           246:      
        !           247:      @node     Concept Index,     , Variables Index, Top
        !           248:      @comment      node-name, next,        previous,  up
        !           249:      @unnumbered Concept Index
        !           250:      
        !           251:      @printindex cp
        !           252:      
        !           253:      @summarycontents
        !           254:      @contents
        !           255:      @bye
        !           256: 
        !           257: In TeX, `@printindex' needs a sorted index file to work from.  TeX
        !           258: does not know how to do sorting; this is one of the main deficiencies
        !           259: of TeX.  You must invoke the program `texindex' to do so, giving it
        !           260: the names of the raw index files to be sorted as arguments.  You do
        !           261: not have to run `texindex' on all of them; only the ones you are
        !           262: going to print.  (*Note Printing Hardcopy::, for more information.)
        !           263: 
        !           264: 
        !           265: 
        !           266: File: texinfo,  Node: Structuring,  Next: Quotations and Examples,  Prev: Ending a File,  Up: Top
        !           267: 
        !           268: Node and Chapter Structuring
        !           269: ****************************
        !           270: 
        !           271: The chapter structuring commands divide a document into a hierarchy
        !           272: of chapters, sections, subsections and subsubsections.  These
        !           273: commands generate large headings.
        !           274: 
        !           275: In a printed manual, the table of contents is based on the
        !           276: information specified by the chapter structuring commands.
        !           277: 
        !           278: Although the chapter structuring commands used for creating a printed
        !           279: document are entirely different from the node commands for
        !           280: structuring an Info file, you are likely to use the two kinds of
        !           281: command together since the single Texinfo file is usually designed to
        !           282: be read both as an Info file and as a printed manual.  The only time
        !           283: you are likely to use the chapter structuring commands without using
        !           284: the node structuring commands is if you are writing a document that
        !           285: will never be put into Info format, for example, a novel, a letter,
        !           286: an article or a memorandum.
        !           287: 
        !           288: It is unlikely that you will ever write a Texinfo file that is only
        !           289: intended as an on-line Info file and not as a printable document. 
        !           290: However, Texinfo is flexible enough so that you can do this if you
        !           291: wish.
        !           292: 
        !           293: Although a Texinfo file can be structured in a variety of ways, it is
        !           294: usually structured like a book with chapters, sections, subsections
        !           295: and the like.  This structure can also be visualized as a tree (or
        !           296: rather as an upside down tree) with the root at the top and each
        !           297: level corresponding to chapters or sections or whatnot.  In Info
        !           298: format, you reach the nodes on each level by using the the `Next' and
        !           299: `Previous' pointers in the node line.  For example, you go from one
        !           300: chapter to the next or previous chapter by using the the pointers to
        !           301: the next and previous chapters.  In Info, you go the level above by
        !           302: using an `Up' pointer and you go to the level below through a `Menu'.
        !           303: In the printed manual, cross references are indicated by page and
        !           304: section numbers; in the on-line file, cross references are specified
        !           305: by inline menu items.
        !           306: 
        !           307: Here is a diagram that shows a Texinfo file with three chapters; 
        !           308: each chapter has two sections.
        !           309: 
        !           310:                                       top
        !           311:                                        |
        !           312:                                        |
        !           313:                  --------------------------------------------
        !           314:                 |                      |                      |
        !           315:                 |                      |                      |
        !           316:             Chapter 1              Chapter 2               Chapter 3
        !           317:                 |                      |                      |
        !           318:                 |                      |                      |
        !           319:            ---------             ---------              ---------          
        !           320:           |          |           |          |            |          |         
        !           321:       Sect. 1.1   Sect. 1.2   Sect. 2.1  Sect. 2.2    Sect. 3.1  Sect. 3.2     
        !           322:                                                        
        !           323: 
        !           324: In this structure, the node for Chapter 2 looks like this:
        !           325: 
        !           326:      @node     Chapter 2,  Chapter 3, Chapter 1, top
        !           327:      @comment  node-name,  next,      previous,  up
        !           328: 
        !           329: To get to Sections 2.1 and 2.2, you need a menu inside of Chapter 2
        !           330: that says:
        !           331: 
        !           332:          @menu
        !           333:          * Sect. 2.1::    Description of this section.
        !           334:          * Sect. 2.2::  
        !           335:          @end menu
        !           336: 
        !           337: This menu is located inside Chapter 2, after the beginning of the
        !           338: chapter, just before Section 2.1.
        !           339: 
        !           340: Note that a menu entry has three parts: the menu item name, the name
        !           341: of the node and, optionally, a description of the item (in that
        !           342: order).  If the menu item name and the name of the node are the same,
        !           343: you can put two colons after the item name, as is shown in the
        !           344: example. (If the second part is different from the first, the first
        !           345: part is terminated by a colon and the second part terminated by a
        !           346: tab, newline, comma or period.) (*Note Menu::.)
        !           347: 
        !           348: The node for Sect. 2.1 will look like this:
        !           349: 
        !           350:          @node     Sect. 2.1, Sect. 2.2,         ,  Chapter 2
        !           351:          @comment  node-name, next,      previous,  up
        !           352: 
        !           353: This node does not have a `Previous' node.
        !           354: 
        !           355: Usually, an `@node' command and a chapter structuring command are
        !           356: used in sequence, along with indexing commands.  For example, the
        !           357: node for the chapter on ending a file looks like this:
        !           358: 
        !           359:      @node    Ending a File, Structuring, Beginning a File, Top
        !           360:      @comment node-name,     next,        previous,         up
        !           361:      @chapter Ending a Texinfo File
        !           362:      @cindex  Ending a Texinfo file
        !           363:      @cindex  Texinfo file ending
        !           364:      @cindex  File ending
        !           365: 
        !           366: The chapter structuring commands fall into four groups that have the
        !           367: characteristics of chapters, sections, subsections and subsubsections.
        !           368: The groups are:
        !           369: 
        !           370: `@chapter'
        !           371: `@unnumbered'
        !           372: `@appendix'
        !           373:      For chapters and chapter-like parts of a document.
        !           374: 
        !           375: `@section'
        !           376: `@unnumberedsec'
        !           377: `@appendixsec'
        !           378:      For sections and section-like parts of a document.
        !           379: 
        !           380: `@subsection'
        !           381: `@unnumberedsubsec'
        !           382: `@appendixsubsec'
        !           383:      For subsections and subsection-like parts of a document.
        !           384: 
        !           385: `@subsubsection'
        !           386: `@unnumberedsubsubsec'
        !           387: `@appendixsubsubsec'
        !           388:      For subsubsections and subsubsection-like parts of a document.
        !           389: 
        !           390: In the sections that follow, the chapter structuring commands are
        !           391: described first and then the `@node' and `@menu' commands.
        !           392: 
        !           393: * Menu:
        !           394: 
        !           395: * Chapter::            
        !           396: * Unnumbered and Appendix::
        !           397: * Section::
        !           398: * Subsection::
        !           399: * Subsubsection::
        !           400: * Node::
        !           401: * Menu::
        !           402: 
        !           403: 
        !           404: 
        !           405: File: texinfo,  Node: Chapter,  Next: Unnumbered and Appendix,  Up: Structuring
        !           406: 
        !           407: @chapter
        !           408: ========
        !           409: 
        !           410: `@chapter' identifies a chapter in the document.  It is followed by a
        !           411: single argument which is the rest of the line, as in
        !           412: 
        !           413:      @chapter Node and Chapter Structuring
        !           414: 
        !           415: In TeX, it creates a chapter in the document, specifying the chapter
        !           416: title.
        !           417: 
        !           418: In the Info file, `@chapter' causes its argument to appear on a line
        !           419: by itself, with a line of asterisks inserted underneath.  Thus, the
        !           420: above example produces the following output:
        !           421: 
        !           422:      Node and Chapter Structuring
        !           423:      ****************************
        !           424: 
        !           425: 
        !           426: 
        !           427: File: texinfo,  Node: Unnumbered and Appendix,  Next: Section,  Prev: Chapter,  Up: Structuring
        !           428: 
        !           429: @unnumbered, @appendix
        !           430: ======================
        !           431: 
        !           432: These commands are equivalent to `@chapter' for Info file output. 
        !           433: (*Note Chapter::.)  In a printed manual, they generate chapters that
        !           434: are numbered differently in the table of contents.  `@unnumbered'
        !           435: chapters appear without chapter numbers of any kind, and `@appendix'
        !           436: chapters are given a letter instead of a number.
        !           437: 
        !           438: 
        !           439: 
        !           440: File: texinfo,  Node: Section,  Next: Subsection,  Prev: Unnumbered and Appendix,  Up: Structuring
        !           441: 
        !           442: @section
        !           443: ========
        !           444: 
        !           445: `@section' is like `@chapter' except that in TeX it makes a section
        !           446: rather than a chapter.  (*Note Chapter::.)  Sections go within
        !           447: chapters.  In the Info file, `@chapter' and `@section' differ only in
        !           448: that `@section' underlines with `='.  For example,
        !           449: 
        !           450:      This is a section
        !           451:      =================
        !           452: 
        !           453: @unnumberedsec, @appendixsec
        !           454: ============================
        !           455: 
        !           456: Use these constructs for sections within chapters made by
        !           457: `@unnumbered' or `@appendix'. (*Note Section::.)
        !           458: 
        !           459: 
        !           460: 
        !           461: File: texinfo,  Node: Subsection,  Next: Subsubsection,  Prev: Section,  Up: Structuring
        !           462: 
        !           463: @subsection
        !           464: ===========
        !           465: 
        !           466: Subsections are to sections as sections are to chapters. (*Note
        !           467: Section::.) They are underlined with `-'.  For example,
        !           468: 
        !           469:      This is a subsection
        !           470:      -------------------
        !           471: 
        !           472: @unnumberedsubsec, @appendixsubsec
        !           473: ==================================
        !           474: 
        !           475: Use these constructs for subsections within sections within chapters
        !           476: made by `@unnumberedsec' or `@appendixsec'.  (*Note Subsection::.)
        !           477: 
        !           478: 
        !           479: 
        !           480: File: texinfo,  Node: Subsubsection,  Next: Node,  Prev: Subsection,  Up: Structuring
        !           481: 
        !           482: @subsubsection, @unnumberedsubsubsec, @appendixsubsubsec
        !           483: ========================================================
        !           484: 
        !           485: Subsubsections are to subsections as subsections are to sections. 
        !           486: (*Note Subsection::.)  They are underlined with periods.  The
        !           487: equivalent commands for `@unnumberedsubsec' and `@appendixsubsec' are
        !           488: `@unnumberedsubsubsec' and `@appendixsubsubsec'.  For example,
        !           489: 
        !           490:      This is a subsubsection
        !           491:      .......................
        !           492: 
        !           493:  
        !           494: 
        !           495: File: texinfo,  Node: Node,  Next: Menu,  Prev: Subsubsection,  Up: Structuring
        !           496: 
        !           497: @node
        !           498: =====
        !           499: 
        !           500: `@node' defines the beginning of a new node in the Info output file
        !           501: (*note info: (info)Top.).  It is followed by four arguments,
        !           502: separated by commas, that make up the rest of the line.  Since it is
        !           503: often hard to remember the order in which are arguments are listed,
        !           504: `texinfo-mode' provides the `C-c C-c n' command
        !           505: (`texinfo-insert-@node') which automatically inserts a comment line
        !           506: listing the arguments.  For example,
        !           507: 
        !           508:      @node    Texinfo Mode, Beginning a File,  Overview, Top    
        !           509:      @comment node-name,    next,              previous, up
        !           510: 
        !           511: defines a node named `Texinfo Mode', whose `Next' pointer is to node
        !           512: `Beginning a File', whose `Previous' pointer is to node `Overview',
        !           513: and whose `Up' pointer is to node `Top'.  What this means is that
        !           514: Texinfo changes `@node ARGS' into the special text string necessary
        !           515: to separate Info nodes and to identify the node that is starting and
        !           516: say what nodes it points to.
        !           517: 
        !           518: The pointer names should be the names of nodes defined elsewhere. 
        !           519: For this example, nodes named `Beginning a File', `Overview' and
        !           520: `Top' should be defined elsewhere in the file with other `@node'
        !           521: commands.  It does not matter whether they are before or after the
        !           522: node that refers to them.
        !           523: 
        !           524: Normally, a node's `Up' pointer should point at the node whose menu
        !           525: mentions that node.  The node's `Next' pointer should point at the
        !           526: node that follows that node and its `Previous' pointer should point
        !           527: at the node that precedes it in that menu.
        !           528: 
        !           529: In TeX, `@node' is nearly ignored.  It generates no text.  Its only
        !           530: function is to identify the name to use for cross-references to the
        !           531: chapter or section which follows the `@node' command and which which
        !           532: makes up the body of the node.  (Cross references are made with
        !           533: `@xref'.  *Note Cross References::.)
        !           534: 
        !           535: `@node' should be followed immediately by a chapter-structuring
        !           536: command such as `@chapter', `@section', `@subsection' or
        !           537: `@subsubsection'.
        !           538: 
        !           539: The easiest way to write a node is to use the Texinfo mode keyboard
        !           540: command `C-c C-c n' to insert `@node' and a comment line listing the
        !           541: names of each of the pointers in their proper order.  This way you
        !           542: won't lose track of which arguments are for which pointers.  The
        !           543: template is especially useful if you are not familiar with Texinfo. 
        !           544: It is important to pick a suitable node name.  Generally, these begin
        !           545: with an uppercase letter as if the node name were a heading for a
        !           546: chapter or section.  Do not use any of the Texinfo @-commands in the
        !           547: name; these commands confuse Info.  The node name should be
        !           548: informative.  Unfortunately, long names will not fit onto the line,
        !           549: which can be awkward.  Sometimes it is better to use long but
        !           550: informative names rather than short ones.
        !           551: 
        !           552: Some people insert the names of the `Next', `Previous' and `Up'
        !           553: pointers at the same time they insert the node's own name.  This is
        !           554: because it is easier to keep track of the node structure as you
        !           555: create a document than it is to sort it out after you have dozens of
        !           556: nodes.  Others wait to insert the `Next', `Previous' and `Up'
        !           557: pointers until they have a nearly final version of the document. 
        !           558: This is because they expect to change the organization of the
        !           559: document while they write it and insert or delete sections and move
        !           560: them around.  The command `texinfo-show-structure' can be used to
        !           561: find the `Next', `Previous' and `Up' pointers of a node.  (See *Note
        !           562: Using texinfo-show-structure::.)
        !           563: 
        !           564: However you do it, it is best to name the node whenever you write the
        !           565: section so you can easily make cross references to the section.  A
        !           566: large number of cross references are an especially important feature
        !           567: of a good Info file.
        !           568: 
        !           569: After you have inserted the node-line, you should immediately write
        !           570: an @-command for the chapter or section and insert its name.  Next,
        !           571: (and this is important!), put in several index entries.  Usually, you
        !           572: will find at least two and often as many as four or five ways of
        !           573: referring to the node in the index.  Use them all.  This will make it
        !           574: much easier for people to find the node.
        !           575: 
        !           576: The top node of the file, named `Top', should have as its parent the
        !           577: name of a node in another file, where there is a menu that leads to
        !           578: this file.  Specify the file name in parentheses.  If the file is to
        !           579: be installed directly in the Info directory file, use `(dir)' as the
        !           580: parent of the top node; this is short for `(dir)top', the node `top'
        !           581: in the file `dir', which is the main menu of Info.  For example,
        !           582: 
        !           583:      @node    Top,       Overview, (dir),    (dir)
        !           584:      @comment node-name, next,     previous, up
        !           585: 
        !           586: For more information about installing an Info file in the `info'
        !           587: directory, *note Installing an Info File::.
        !           588: 
        !           589: 
        !           590: 
        !           591: File: texinfo,  Node: Menu,  Prev: Node,  Up: Structuring
        !           592: 
        !           593: @menu
        !           594: =====
        !           595: 
        !           596: Info file nodes can contain "menus" which point to other nodes.  You
        !           597: must type the menus in by hand, and surround them with lines
        !           598: containing `@menu' and `@end menu'.  In Info, the `@menu' line
        !           599: changes into `* Menu:', which indicates the beginning of a menu to
        !           600: the Info program.  Otherwise, the contents are unchanged by Texinfo,
        !           601: except for the processing of any other @-commands within.  The entire
        !           602: menu construct has no effect in the printed manual and will not
        !           603: appear there.
        !           604: 
        !           605: By convention, a menu is put at the end of a node.  This way, it is
        !           606: easy for someone using Info to find the menu, using the `M->'
        !           607: (`end-of-buffer') command.
        !           608: 
        !           609: In a menu, every line that begins with a `*' lists a single topic.  A
        !           610: line that does not start with a `*' will also appear in the menu and
        !           611: can be used as a comment.
        !           612: 
        !           613: A menu item has three parts:
        !           614: 
        !           615:   1. The menu item name.
        !           616: 
        !           617:   2. The name of the node.
        !           618: 
        !           619:   3. A description of the item.
        !           620: 
        !           621: Only the first part is required.  This part is the name of the
        !           622: topic--the name of the menu item that the user must give to the `m'
        !           623: command to select this topic when using Info.  The first part comes
        !           624: right after the asterisk and a space, and is followed by a colon,
        !           625: spaces and tabs, and then the name of the node which discusses that
        !           626: topic.  The name of the node is terminated by a tab, comma, newline
        !           627: or period.  If the node name and topic name are the same, rather than
        !           628: give the name twice, put two colons after the name instead.  For
        !           629: example, `* Name::'.  (You should do this whenever possible, since it
        !           630: reduces visual clutter in the menu).
        !           631: 
        !           632: If the second part is present, it may be terminated with a tab,
        !           633: comma, or newline; or with a period.
        !           634: 
        !           635: For example,
        !           636: 
        !           637:      @menu
        !           638:      A Section on Foo and Switches
        !           639:      * Foo::           The node named Foo tells you how to go fooing.
        !           640:      * Sw: Switches.   Type @code{m Sw} to see node @code{Switches}
        !           641:                        which describes the switches available here.
        !           642:      @end menu
        !           643: 
        !           644: produces
        !           645: 
        !           646:      * menu:
        !           647:      
        !           648:      A Section on Foo and Switches
        !           649:      * Foo::         The node named foo tells you how to go fooing.
        !           650:      * Sw: Switches. Type `m Sw' to see node `Switches'
        !           651:                      which describes the switches available here.
        !           652: 
        !           653:  In this example, the menu has two items.  `Foo' is both a menu item
        !           654: name and the name of the node referred to by that item.  `Sw' is the
        !           655: other menu item name, and it refers to the node named `Switches'. 
        !           656: Since no file name is specified with `Foo' or `Switches', they must
        !           657: be the names of other nodes in the same Info file.
        !           658: 
        !           659: Nodes in other Info files can be referred to by putting the file name
        !           660: in parentheses at the beginning of the node name. For example,
        !           661: 
        !           662:      @menu
        !           663:      * Outlining: (emacs) Outline Mode.  The major mode for editing outlines.
        !           664:      * Rebinding: (emacs) Rebinding.     How to redefine the meaning of a key.
        !           665:      @end menu
        !           666: 
        !           667: When this is done, the item has to have at least two parts: the first
        !           668: part is the menu item name and the second part is the name of the node.
        !           669: 
        !           670: 
        !           671: 
        !           672: File: texinfo,  Node: Quotations and Examples,  Next: Lists and Tables,  Prev: Structuring,  Up: Top
        !           673: 
        !           674: Making Quotations and Examples
        !           675: ******************************
        !           676: 
        !           677: Quotations and examples are blocks of text, consisting of one or more
        !           678: whole paragraphs that are set off from the bulk of the text and
        !           679: treated differently.  They are usually indented.
        !           680: 
        !           681: In Texinfo, an insertion is always begun by writing an @-command on a
        !           682: line by itself, and ended by writing an `@end' command that is also
        !           683: on a line by itself.  For instance, an "example" is a kind of
        !           684: insertion that is begun with `@example' and ended with `@end example'.
        !           685: 
        !           686: There are three commands for quotations and examples:
        !           687: 
        !           688: `@quotation'
        !           689:      Used to indicated text that is quoted.
        !           690: 
        !           691: `@example'
        !           692:      Used to illustrate code, commands and the like in a fixed width
        !           693:      font without filling.
        !           694: 
        !           695: `@display'
        !           696:      Used for illustrative text.
        !           697: 
        !           698: * Menu:
        !           699: 
        !           700: * Quotation::
        !           701: * Example::
        !           702: * Display::
        !           703: 
        !           704: 
        !           705: 
        !           706: File: texinfo,  Node: Quotation,  Next: Example,  Up: Quotations and Examples
        !           707: 
        !           708: @quotation
        !           709: ==========
        !           710: 
        !           711: `@quotation' is used to indicate text that is excerpted from another
        !           712: (real or hypothetical) printed work.  The inside of a quotation is
        !           713: processed normally except that
        !           714: 
        !           715:   1. The margins are narrower.
        !           716: 
        !           717:   2. Paragraphs are not indented.
        !           718: 
        !           719:   3. Interline spacing and interparagraph spacing are reduced.
        !           720: 
        !           721: Thus, the input
        !           722: 
        !           723:      @quotation
        !           724:      This is
        !           725:      a foo.
        !           726:      @end quotation
        !           727: 
        !           728: produces in the printed manual
        !           729: 
        !           730:           This is a foo.
        !           731: 
        !           732: and in the Info file
        !           733: 
        !           734:           This is
        !           735:           a foo.
        !           736: 
        !           737:  
        !           738: 
        !           739: File: texinfo,  Node: Example,  Next: Display,  Prev: Quotation,  Up: Quotations and Examples
        !           740: 
        !           741: @example
        !           742: ========
        !           743: 
        !           744: `@example' is used to indicate an example that is not part of the
        !           745: running text.  In the printed manual, this is done by switching to a
        !           746: fixed width font, turning off filling, and making extra spaces and
        !           747: blank lines significant.  In the Info file, an analogous result is
        !           748: obtained by indenting each line with five extra spaces.
        !           749: 
        !           750: `@example' should appear on a line by itself; this line will
        !           751: disappear from the output.  Mark the end of the example with a line
        !           752: containing `@end example', which will likewise disappear.  For example:
        !           753: 
        !           754:      @example
        !           755:      mv foo bar
        !           756:      @end example
        !           757: 
        !           758: produces
        !           759: 
        !           760:      mv foo bar
        !           761: 
        !           762: Since the lines containing `@example' and `@end example' will
        !           763: disappear, you will want to put a blank line before the `@example'
        !           764: and another blank line after the `@end example'.  (Remember that
        !           765: blank lines between the beginning `@example' and the ending `@end
        !           766: example' will appear in the output.)
        !           767: 
        !           768: Don't use tabs in lines of an example!  TeX has trouble with tabs: 
        !           769: it treats them like single spaces, and that is not what they look like.
        !           770: 
        !           771: 
        !           772: 
        !           773: File: texinfo,  Node: Display,  Prev: Example,  Up: Quotations and Examples
        !           774: 
        !           775: @display
        !           776: ========
        !           777: 
        !           778: `@display' is just like `@example' except that, in the printed
        !           779: manual, `@display' does not select the fixed-width font.  In fact, it
        !           780: does not specify the font at all, so that the text appears in the
        !           781: same font it would have appeared in without the `@display'.
        !           782: 
        !           783: 
        !           784: 
        !           785: File: texinfo,  Node: Lists and Tables,  Next: Cross References,  Prev: Quotations and Examples,  Up: Top
        !           786: 
        !           787: Making Lists and Tables
        !           788: ***********************
        !           789: 
        !           790: Texinfo has several ways of making lists and two-column tables. 
        !           791: Lists can be bulleted or numbered while two-column tables can
        !           792: highlight the items in the first column.
        !           793: 
        !           794: For example, this is an enumerated list:
        !           795: 
        !           796:   1. This is a numbered item.
        !           797: 
        !           798:   2. This is the second item in this list.
        !           799: 
        !           800:   3. This is the third item on this list.
        !           801: 
        !           802: Texinfo will automatically indent the text in lists or tables and
        !           803: number an enumerated list.  This last feature is useful if you are
        !           804: reordering the list, since you do not have to renumber it yourself.
        !           805: 
        !           806: Lists or tables are always begun by an @-command on a line by itself
        !           807: and ended with an `@end' command on a line by itself.  For example,
        !           808: an enumerated list begins with the command `@enumerate' and ends with
        !           809: the command `@end enumerate'; and an itemized list begins with the
        !           810: command `@itemize' and ends with the command `@end itemize'.
        !           811: 
        !           812: The elements of a list are begun with the `@item' command.
        !           813: 
        !           814: Here is an itemized list of the different kinds of table and lists:
        !           815: 
        !           816:    * Itemized lists with or without bullets.
        !           817: 
        !           818:    * Numbered lists.
        !           819: 
        !           820:    * two-column tables with highlighting.
        !           821: 
        !           822: * Menu:
        !           823: 
        !           824: * Itemize::
        !           825: * Enumerate::
        !           826: * Table::
        !           827: 
        !           828: 
        !           829: 
        !           830: File: texinfo,  Node: Itemize,  Next: Enumerate,  Up: Lists and Tables
        !           831: 
        !           832: @itemize
        !           833: ========
        !           834: 
        !           835: `@itemize' is used to produce sequences of indented paragraphs, with
        !           836: a mark inside the left margin at the beginning of each paragraph. 
        !           837: The rest of the line that starts with `@itemize' should contain the
        !           838: character or Texinfo commands to generate such a mark.  Usually, it
        !           839: is the @-command `@bullet'.  Whatever mark you choose, ultimately, it
        !           840: should result in a single character in the Texinfo file, or the
        !           841: indentation will come out wrong.  When you write the command, omit
        !           842: the `{}' after the command if you use just one command and nothing
        !           843: else.
        !           844: 
        !           845: The text of the indented paragraphs themselves come after the
        !           846: `@itemize', up to another line that says `@end itemize'.
        !           847: 
        !           848: Before each paragraph for which a mark in the margin is desired,
        !           849: place a line that says just `@item'.  Don't put any other text on
        !           850: this line.
        !           851: 
        !           852: Info indents the lines in an itemized list by five columns, but it
        !           853: does not fill them.  This can produce lines in the Info file that are
        !           854: too wide.  You can either write shorter lines in the Texinfo file by
        !           855: setting the fill column to five columns less than it is normally, or
        !           856: else you can tell Info to refill the paragraphs by adding the
        !           857: @-command `@refill' to the end of the paragraph. (*Note Refill::, for
        !           858: more information about the use of the `@refill' command.)
        !           859: 
        !           860: Usually, you should put a blank line before an `@item'.  This puts a
        !           861: blank like in the Info file.  Except when the entries are very brief,
        !           862: a blank line looks better.
        !           863: 
        !           864: Here is an example of the use of `@itemize', followed by the output
        !           865: it produces.  Note that `@bullet' produces a `*' in Texinfo and a
        !           866: round dot in TeX.
        !           867: 
        !           868:      @itemize @bullet
        !           869:      @item
        !           870:      Some text for foo.
        !           871:      
        !           872:      @item
        !           873:      Some text
        !           874:      for bar.
        !           875:      @end itemize
        !           876: 
        !           877: produces
        !           878: 
        !           879:         * Some text for foo.
        !           880: 
        !           881:         * Some text for bar.
        !           882: 
        !           883: 
        !           884: 
        !           885: File: texinfo,  Node: Enumerate,  Next: Table,  Prev: Itemize,  Up: Lists and Tables
        !           886: 
        !           887: @enumerate
        !           888: ==========
        !           889: 
        !           890: `@enumerate' is like `@itemize' except that the marks in the left
        !           891: margin contain successive integers starting with 1.  (*Note
        !           892: Itemize::.) Do not put any argument on the same line as `@enumerate'.
        !           893: 
        !           894:      @enumerate
        !           895:      @item
        !           896:      Some text for foo.
        !           897:      @item
        !           898:      Some text
        !           899:      for bar.
        !           900:      @end enumerate
        !           901: 
        !           902: produces
        !           903: 
        !           904:        1. Some text for foo.
        !           905: 
        !           906:        2. Some text for bar.
        !           907: 
        !           908: If you want, you can put a blank line between the entries in the list.
        !           909: This often makes it easier to read the Info file.  For example,
        !           910: 
        !           911:      @enumerate
        !           912:      @item
        !           913:      This is the first item.
        !           914:      
        !           915:      @item
        !           916:      This is the second item.
        !           917:      @end enumerate
        !           918: 
        !           919: Info indents the lines of the enumerated list by five columns, but it
        !           920: does not fill them.  As a result, the lines in the Info file may be
        !           921: too wide.  To prevent this, you can either write shorter lines in the
        !           922: Texinfo file file by setting the fill column to five columns less
        !           923: than it is normally, or else you can tell Info to refill the
        !           924: paragraphs by adding the @-command `@refill' to the end of the
        !           925: paragraph.  (*Note Refill::, for more information about the use of
        !           926: the `@refill' command.)
        !           927: 
        !           928: 
        !           929: 
        !           930: File: texinfo,  Node: Table,  Prev: Enumerate,  Up: Lists and Tables
        !           931: 
        !           932: @table
        !           933: ======
        !           934: 
        !           935: `@table' is similar to `@itemize', but allows you to specify a name
        !           936: or heading line for each item.  (*Note Itemize::.)  The command is
        !           937: used to produce two-column tables, and is especially useful for
        !           938: glossaries and explanatory exhibits.
        !           939: 
        !           940: You must follow each use of `@item' inside of `@table' with text to
        !           941: serve as the heading line for that item.  This text is put on the
        !           942: same line as the `@item' command.  Each heading line is put into the
        !           943: first column of the table and the supporting text, which you put on
        !           944: the line following the line beginning with `@item', goes into the
        !           945: second column.
        !           946: 
        !           947: Also, `@table' itself must be followed by an argument that is a
        !           948: Texinfo command such as `@code', `@var', `@kbd' or `@asis'.  Although
        !           949: these commands are usually followed by arguments in braces, in this
        !           950: case you use the command name without an argument.  (`@item' supplies
        !           951: the argument.)  This command will be applied to the text that goes
        !           952: into the first column of each item and determines how it will be
        !           953: highlighted.  For example, `@samp' will cause the text in the first
        !           954: column to be highlighted as if it were acted on by an `@samp' command.
        !           955: 
        !           956: `@asis' is a command that does nothing; in that case, each item will
        !           957: come out without highlighting, unless that particular piece of text
        !           958: contains @-commands for highlighting.
        !           959: 
        !           960: (Various other command names might work with `@table'.  However, only
        !           961: commands that normally take arguments in braces may be used.)
        !           962: 
        !           963: Usually, you should put a blank line before an `@item'.  This puts a
        !           964: blank like in the Info file.  Except when the entries are very brief,
        !           965: a blank line looks better.
        !           966: 
        !           967: The following table, for example, highlights the text in the first
        !           968: column as if each item were acted on by an `@samp' command:
        !           969: 
        !           970:      @table @samp
        !           971:      @item foo
        !           972:      This is the text for
        !           973:      @samp{foo}.
        !           974:      
        !           975:      @item bar
        !           976:      Text for @samp{bar}.
        !           977:      @end table
        !           978: 
        !           979: produces
        !           980: 
        !           981:     `foo'
        !           982:           This is the text for `foo'.
        !           983: 
        !           984:     `bar'
        !           985:           Text for `bar'.
        !           986: 
        !           987: Info indents the lines of text in the second column, but does not
        !           988: fill them.  As a result, the lines in the Info file may be too wide. 
        !           989: To prevent this, cause Info to refill the paragraphs after processing
        !           990: by adding the @-command `@refill' to the end of the paragraph. (*Note
        !           991: Refill::, for more information about the use of the `@refill' command.)
        !           992: 
        !           993: If you want to list two or more named items with a single block of
        !           994: text, use the `@itemx' command.
        !           995: 
        !           996: * Menu:
        !           997: 
        !           998: * Itemx::
        !           999: 
        !          1000: 
        !          1001: 
        !          1002: File: texinfo,  Node: Itemx,  Prev: Table,  Up: Table
        !          1003: 
        !          1004: @itemx
        !          1005: ------
        !          1006: 
        !          1007: `@itemx' is used inside a `@table' when you have two or more named
        !          1008: items for the same block of text.  Use `@itemx' for all but the first
        !          1009: of the items.  It works exactly like `@item' except that it does not
        !          1010: generate extra vertical space above the item text.  For example,
        !          1011: 
        !          1012:      @table @code
        !          1013:      @item upcase
        !          1014:      @itemx downcase
        !          1015:      These two functions accept a character or a string as argument,
        !          1016:      and return the corresponding upper case (lower case) character
        !          1017:      or string. @refill
        !          1018:      @end table
        !          1019: 
        !          1020: produces
        !          1021: 
        !          1022:     `upcase'
        !          1023:     `downcase'
        !          1024:           These two functions accept a character or a string as
        !          1025:           argument, and return the corresponding upper case (lower
        !          1026:           case) character or string.
        !          1027: 
        !          1028: A more complicated example of the use of `@itemx' comes from the
        !          1029: chapter on structuring commands.  Here is how the list showing how 
        !          1030: the chapter structuring commands fall into four groups was constructed.
        !          1031: (*Note Chapter Structuring Commands: Structuring.)
        !          1032: 
        !          1033:      @table @code
        !          1034:      @item  @@chapter
        !          1035:      @itemx @@unnumbered
        !          1036:      @itemx @@appendix
        !          1037:      For chapters and chapter-like parts of a document.
        !          1038:      
        !          1039:      @item  @@section
        !          1040:      @itemx @@unnumberedsec
        !          1041:      @itemx @@appendixsec
        !          1042:      For sections and section-like parts of a document.
        !          1043:      
        !          1044:      @item  @@subsection
        !          1045:      @itemx @@unnumberedsubsec
        !          1046:      @itemx @@appendixsubsec
        !          1047:      For subsections and subsection-like parts of a document.
        !          1048:      
        !          1049:      @item  @@subsubsection
        !          1050:      @itemx @@unnumberedsubsubsec
        !          1051:      @itemx @@appendixsubsubsec
        !          1052:      For subsubsections and similar parts of a document.
        !          1053:      @end table
        !          1054: 
        !          1055: and this is what the resulting table looks like:
        !          1056: 
        !          1057: `@chapter'
        !          1058: `@unnumbered'
        !          1059: `@appendix'
        !          1060:      For chapters and chapter-like parts of a document.
        !          1061: 
        !          1062: `@section'
        !          1063: `@unnumberedsec'
        !          1064: `@appendixsec'
        !          1065:      For sections and section-like parts of a document.
        !          1066: 
        !          1067: `@subsection'
        !          1068: `@unnumberedsubsec'
        !          1069: `@appendixsubsec'
        !          1070:      For subsections and subsection-like parts of a document.
        !          1071: 
        !          1072: `@subsubsection'
        !          1073: `@unnumberedsubsubsec'
        !          1074: `@appendixsubsubsec'
        !          1075:      For subsubsections and similar parts of a document.
        !          1076: 
        !          1077: Also, either column of a table can be empty.
        !          1078: 
        !          1079: 
        !          1080: 
        !          1081: File: texinfo,  Node: Cross References,  Next: Formatting Paragraphs,  Prev: Lists and Tables,  Up: Top
        !          1082: 
        !          1083: Making Cross References
        !          1084: ***********************
        !          1085: 
        !          1086: Cross references are used to refer the reader to other parts of the
        !          1087: same or different Texinfo files.  In Texinfo, "nodes" are the points
        !          1088: to which cross-references can refer.
        !          1089: 
        !          1090: In general, a document should be designed so that it can be read
        !          1091: sequentially.  People soon tire of flipping back and forth to find
        !          1092: information that should be presented to them as they need it. 
        !          1093: However, there will be information (often too detailed for whatever
        !          1094: the current context may be) that is related to whatever is presented
        !          1095: and to which reference should be made.  More important, in an on-line
        !          1096: help system or in a reference manual, readers do *not* read
        !          1097: everything in sequence from beginning to end.  Instead, they look up
        !          1098: what they need.  For this reason, such creations should contain many
        !          1099: cross references to help the reader find other information that he or
        !          1100: she may not have read.
        !          1101: 
        !          1102: Although nodes are not a fundamental concept in a printed manual,
        !          1103: they still serve to define a cross-reference point and the variants
        !          1104: of `@xref' still serve to make references.  Thus, if you are writing
        !          1105: a manual that will only be printed, and will not be used on-line, you
        !          1106: continue to use the `@node' command for when you make cross references.
        !          1107: 
        !          1108: There are several kinds of cross reference command.
        !          1109: 
        !          1110: `@xref'
        !          1111:      Used to start a sentence in the printed manual saying, `See ...' 
        !          1112:       or an entry in the Info file saying `*note ...'.
        !          1113: 
        !          1114: `@pxref'
        !          1115:      Used to make a reference that starts with a lowercase `see' 
        !          1116:       and is usually contained within parentheses.
        !          1117: 
        !          1118: `@inforef'
        !          1119:      Used to make a reference to an Info file for which there is no
        !          1120:      printed manual.
        !          1121: 
        !          1122: * Menu:
        !          1123: 
        !          1124: * Xref::
        !          1125: * Pxref::
        !          1126: * Inforef::
        !          1127: 
        !          1128: 
        !          1129: 
        !          1130: File: texinfo,  Node: Xref,  Next: Pxref,  Prev: Cross References,  Up: Cross References
        !          1131: 
        !          1132: @xref
        !          1133: =====
        !          1134: 
        !          1135: `@xref' generates a cross-reference.  In Texinfo, it turns into an
        !          1136: Info cross-reference which the Info `f' command can use to go
        !          1137: directly to another node.  In TeX, it turns into a sentence of the form
        !          1138: 
        !          1139:      See section SECTION [TOPIC], page PAGE
        !          1140: 
        !          1141: but does not generate a period to end it.
        !          1142: 
        !          1143: `@xref' must refer to an Info node created by `@node', by the node's
        !          1144: name.
        !          1145: 
        !          1146: `@xref' is followed by an argument inside braces; but actually the
        !          1147: text inside the braces is treated as several arguments, separated by
        !          1148: commas.  Whitespace after these commas is ignored.  A period or comma
        !          1149: *must* follow the closing brace of an `@xref'.  It is required to
        !          1150: terminate the cross reference.  This period or comma will appear in
        !          1151: the output, both in the Info file and in the printed manual.
        !          1152: 
        !          1153: The simplest form of `@xref' takes one argument, the name of another
        !          1154: node in the same Info file.  Here we show the input text, followed by
        !          1155: a blank line and then the output text for Info files and the output
        !          1156: text for printed manuals.
        !          1157: 
        !          1158:      @xref{node-name}, for more info.
        !          1159:      
        !          1160:      *note node-name::, for more info.
        !          1161: 
        !          1162:       See section NNN [node-name], page PPP, for more info.
        !          1163: 
        !          1164: With two arguments, the second one is used as the name of the Info
        !          1165: cross-reference, while the first argument is still the node that the
        !          1166: cross-reference points to:
        !          1167: 
        !          1168:      @xref{node-name, name-for-note}, for more info.
        !          1169:      
        !          1170:      *note name-for-note: node-name, for more info.
        !          1171: 
        !          1172:       See section NNN [node-name], page PPP, for more info.
        !          1173: 
        !          1174: A third argument replaces the node name when it actually appears in
        !          1175: the TeX output.  It should state the topic discussed by the section
        !          1176: being referenced.  Often, you will want to use initial uppercase
        !          1177: letters so it will be easier to read when the reference is printed. 
        !          1178: Use a third argument when the node name is unsuitable because of
        !          1179: syntax, grammar or diction.
        !          1180: 
        !          1181:      @xref{node-name, name-for-note, Topic Description}, for more info.
        !          1182:      
        !          1183:      *note name-for-note: node-name, for more info.
        !          1184: 
        !          1185:       See section NNN [Topic Description], page PPP, for more info.
        !          1186: 
        !          1187: If a third argument is given and the second one is empty, then the
        !          1188: third argument serves both purposes:
        !          1189: 
        !          1190:      @xref{node-name, , Topic Description}, for more info.
        !          1191:      
        !          1192:      *note Topic Description: node-name, for more info.
        !          1193: 
        !          1194:       See section NNN [Topic Description], page PPP, for more info.
        !          1195: 
        !          1196: A fourth argument specifies the name of the Info file in which the
        !          1197: referenced node is located, assuming it is not the one in which the
        !          1198: reference appears.  `@xref' with only four arguments is used when the
        !          1199: reference is not within one Info file, but is within a single printed
        !          1200: manual--when multiple Texinfo files are incorporated into the same
        !          1201: TeX run but make separate Info files.  (This is seldom the case and
        !          1202: usually you will use five arguments if you are making a reference
        !          1203: that is outside the current Info file.)
        !          1204: 
        !          1205:      @xref{node-name, name-for-note, Topic, info-file-name}, 
        !          1206:      for more info.
        !          1207:      
        !          1208:      *note name-for-note: (info-file-name) node-name, for more info.
        !          1209: 
        !          1210:       See section NNN [Topic], page PPP, for more info.
        !          1211: 
        !          1212: A fifth argument is used when you are making a reference to another
        !          1213: Info file which is also part of another printed manual.  Write the
        !          1214: title of the manual in this slot.  Since a different manual is made
        !          1215: during a different TeX run, the printed reference will not have a
        !          1216: page number.
        !          1217: 
        !          1218: Whenever you refer to another manual, use this version of `@xref'
        !          1219: with five arguments.
        !          1220: 
        !          1221:      @xref{node-name, name-for-note, Topic, info-file-name, A Printed Manual},
        !          1222:      for more info.
        !          1223:      
        !          1224:      *note name-for-note: (info-file-name) node-name, for more info.
        !          1225: 
        !          1226:       See section Topic of A Printed Manual, for more info.
        !          1227: 
        !          1228: The name of the printed manual will be typeset in italics.
        !          1229: 
        !          1230: Often, you will leave out the second argument when you use the long
        !          1231: version of `@xref'.  In this case, the third argument, the topic
        !          1232: description, will replace the node name:
        !          1233: 
        !          1234:      @xref{node-name, , Topic Description, info-file-name, A Printed Manual},
        !          1235:      for more info.
        !          1236:      
        !          1237:      *note Topic Description: (info-file-name) node-name, for more info.
        !          1238: 
        !          1239:       See section Topic Description of A Printed Manual, for more info.
        !          1240: 
        !          1241: 
        !          1242: 
        !          1243: File: texinfo,  Node: Pxref,  Next: Inforef,  Prev: Xref,  Up: Cross References
        !          1244: 
        !          1245: @pxref
        !          1246: ======
        !          1247: 
        !          1248: `@pxref' is nearly the same as `@xref'; it differs in only two ways:
        !          1249: 
        !          1250:   1. The output starts with lower case `see' rather than `See'.
        !          1251: 
        !          1252:   2. A period is generated automatically in the Info file output to
        !          1253:      end the Info cross-reference, but no period is generated for the
        !          1254:      printed manual.
        !          1255: 
        !          1256: The purpose of `@pxref' is to be used inside parentheses as part of
        !          1257: another sentence.  In the printed manual, no period is needed after
        !          1258: the cross reference text itself (within the parentheses), but a
        !          1259: period is needed after the cross reference text in the Info file
        !          1260: because only thus can Info recognize the end of the cross-reference. 
        !          1261: `@pxref' spares you the need to use complicated methods to put a
        !          1262: period into one form of the output and not the other.
        !          1263: 
        !          1264: `@pxref' can be used with up to five arguments just like `@xref'. 
        !          1265: (*Note Xref::.)
        !          1266: 
        !          1267: 
        !          1268: 
        !          1269: File: texinfo,  Node: Inforef,  Prev: Pxref,  Up: Cross References
        !          1270: 
        !          1271: @inforef
        !          1272: ========
        !          1273: 
        !          1274: `@inforef' is used for cross-references to Info files for which there
        !          1275: are no printed manuals.  Even in a printed manual, `@inforef'
        !          1276: generates a reference directing the user to look in an Info file. 
        !          1277: `@inforef' takes exactly three arguments.  The syntax is
        !          1278: `@inforef{NODE, NAME, FILE}'.
        !          1279: 
        !          1280:      @inforef{node-name, name-for-note, info-file-name}, for more information.
        !          1281:      
        !          1282:      *note name-for-note: (info-file-name) node-name, for more information.
        !          1283: 
        !          1284:       See Info file `info-file-name', node `node-name', for more
        !          1285:      information.
        !          1286: 
        !          1287: 
        !          1288: 
        !          1289: File: texinfo,  Node: Formatting Paragraphs,  Next: Marking Text,  Prev: Cross References,  Up: Top
        !          1290: 
        !          1291: Formatting Paragraphs
        !          1292: *********************
        !          1293: 
        !          1294: Usually, a Texinfo file will be processed both by TeX and by the `M-x
        !          1295: texinfo-format-buffer' command.  Consequently, you must make sure
        !          1296: that text will come out looking right both in the printed manual and
        !          1297: in the on-line help.
        !          1298: 
        !          1299: For example, unless told otherwise, `M-x texinfo-format-buffer' will
        !          1300: not refill a paragraph after processing it although TeX will.  This
        !          1301: means that a paragraph with numerous or large @-commands may not look
        !          1302: properly filled after processing by Info.  The @-commands are removed
        !          1303: from the text but the lines are not refilled so some are much shorter
        !          1304: than they were.  To cause the `M-x texinfo-format-buffer' command to
        !          1305: refill such a paragraph, put `@refill' at the end of the paragraph.
        !          1306: 
        !          1307: TeX may also format a document improperly.  For example, page breaks
        !          1308: may occur in the ``wrong place''; to control this, text can be held
        !          1309: together by a group command that keeps the text within the group from
        !          1310: being split across two pages.
        !          1311: 
        !          1312: * Menu:
        !          1313: 
        !          1314: * Refilling & Noindent::      Refilling paragraphs & preventing indentation
        !          1315: * Breaks Blank-Lines Groups::  Line and paragraph breaks, blank lines, grouping
        !          1316: 
        !          1317: 
        !          1318: 
        !          1319: File: texinfo,  Node: Refilling & Noindent,  Next: Breaks Blank-Lines Groups,  Prev: Formatting Paragraphs,  Up: Formatting Paragraphs
        !          1320: 
        !          1321: Refilling Paragraphs and Preventing Indentation
        !          1322: ===============================================
        !          1323: 
        !          1324: The `@refill' and `@noindent' commands are used just after or just
        !          1325: before paragraphs which, after processing by either Info or TeX,
        !          1326: might look bad.  The `@refill' command refills a paragraph in the
        !          1327: Info file after all the other processing has been done.  In the
        !          1328: printed manual, the `@noindent' command prevents a piece of text that
        !          1329: is a continuation of the preceding paragraph from being indented as
        !          1330: if it were a new paragraph.
        !          1331: 
        !          1332: * Menu:
        !          1333: 
        !          1334: * Refill::     Refilling an info paragraph after other processing.
        !          1335: * Noindent::   Preventing paragraph indentation in continuation text.
        !          1336: 
        !          1337:  
        !          1338: 
        !          1339: File: texinfo,  Node: Refill,  Next: Noindent,  Prev: Refilling & Noindent,  Up: Refilling & Noindent
        !          1340: 
        !          1341: @refill
        !          1342: -------
        !          1343: 
        !          1344: If a paragraph contains sizable @-constructs, it may look badly
        !          1345: filled after `texinfo-format-buffer' is through with it.
        !          1346: 
        !          1347: Put `@refill' at the end of the paragraph to tell
        !          1348: `texinfo-format-buffer' to refill the paragraph after finishing all
        !          1349: other processing on it.  `@refill' has no effect on TeX, which always
        !          1350: fills everything that ought to be filled.  For example,
        !          1351: 
        !          1352:      To use @code{foo}, pass @samp{xx%$} and @var{flag} and type @kbd{x}
        !          1353:      after running @code{make-foo}.@refill
        !          1354: 
        !          1355: produces (in the Info file)
        !          1356: 
        !          1357:      To use `foo', pass `xx%$' and FLAG and type `x' after running `make-foo'.
        !          1358: 
        !          1359:  whereas without the `@refill' it would produce
        !          1360: 
        !          1361:      To use `foo', pass `xx%$' and FLAG and type `x'
        !          1362:      after running `make-foo'.
        !          1363: 
        !          1364:  with the line broken at the same place as in the Texinfo input file.
        !          1365: 
        !          1366: Do not put a space before `@refill'; otherwise the command might be
        !          1367: put at the beginning of the line when you refill the paragraph in the
        !          1368: Texinfo file with `M-q' (`fill-paragraph').  If this were to happen,
        !          1369: the `@refill' command might fail to work
        !          1370: 
        !          1371: 
        !          1372: 
        !          1373: File: texinfo,  Node: Noindent,  Prev: Refill,  Up: Refilling & Noindent
        !          1374: 
        !          1375: @noindent
        !          1376: ---------
        !          1377: 
        !          1378: If you have text following an `@example' or other similar ``special
        !          1379: paragraph'' that reads as a continuation of the text before the
        !          1380: `@example', it is good to prevent this text from being indented as a
        !          1381: new paragraph.  To accomplish this, put `@noindent' on a line by
        !          1382: itself before the start of the text that should not be indented. For
        !          1383: example,
        !          1384: 
        !          1385:      @example
        !          1386:      This is an example
        !          1387:      @end example
        !          1388:      
        !          1389:      @noindent
        !          1390:      This line will not be indented.
        !          1391: 
        !          1392:  produces
        !          1393: 
        !          1394:      This is an example
        !          1395: 
        !          1396: This line will not be indented.
        !          1397: 
        !          1398: To adjust the number of blank lines properly in the Info file output,
        !          1399: remember that the line containing `@noindent' does not generate a
        !          1400: blank line, and neither does the `@end example' line.
        !          1401: 
        !          1402: In the Texinfo source file for this documentation, each of the lines
        !          1403: that says `produces' is preceded by a line containing `@noindent'.
        !          1404: 
        !          1405: 

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