Return to texinfo-3 CVS log

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

Annotation of 43BSDReno/contrib/emacs-18.55/info/texinfo-3, 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: Breaks Blank-Lines Groups,  Prev: Refilling & Noindent,  Up: Formatting Paragraphs
        !            29: 
        !            30: Breaks, Blank Lines and Groups
        !            31: ==============================
        !            32: 
        !            33: Texinfo has several commands for making blank lines, for forcing
        !            34: paragraph and page breaks in the printed manual and for preventing
        !            35: text from running from one page to the next.
        !            36: 
        !            37: `@*'
        !            38:      Force a line break in the printed manual.  This command has no
        !            39:      effect on the Info file.
        !            40: 
        !            41: `@sp'
        !            42:      Generate blank lines in both the printed manual and in the Info
        !            43:      file.
        !            44: 
        !            45: `@br'
        !            46:      Force a paragraph break in the printed manual.  This command has
        !            47:      no effect on the Info file.
        !            48: 
        !            49: `@w'
        !            50:      Prevent text from being split across two lines in the printed
        !            51:      manual.  This command has no effect on the Info file.
        !            52: 
        !            53: `@page'
        !            54:      Start a new page in the printed manual.  This command has no
        !            55:      effect on the Info file.
        !            56: 
        !            57: `@group'
        !            58:      Hold text together that must appear on one printed page.  This
        !            59:      command has no effect on the Info file.
        !            60: 
        !            61: `@need'
        !            62:      Start a new printed page if required space not on this one. 
        !            63:      This command has no effect on the Info file.
        !            64: 
        !            65: * Menu:
        !            66: 
        !            67: * Line Breaks:: Force a line break in the printed manual.
        !            68: * Sp::         Generate blank lines.
        !            69: * Br::         Force a paragraph break in the printed manual.
        !            70: * W::          Prevent a paragraph break in the printed manual.
        !            71: * Page::       Start a new page in the printed manual.
        !            72: * Group::      Hold text together that must appear on one printed page.
        !            73: * Need::       Start a new printed page if required space not on this one.
        !            74: 
        !            75:  
        !            76: 
        !            77: File: texinfo,  Node: Line Breaks,  Next: Sp,  Prev: Breaks Blank-Lines Groups,  Up: Breaks Blank-Lines Groups
        !            78: 
        !            79: @*
        !            80: --
        !            81: 
        !            82: `@*' forces a line break in the printed manual.  It has no effect on
        !            83: the Info file output, where line breaks follow those in the source
        !            84: file.  If you want a line break at a certain spot in both forms of
        !            85: output, break the line there in the source file and put `@*' at the
        !            86: end of the line.
        !            87: 
        !            88: 
        !            89: 
        !            90: File: texinfo,  Node: Sp,  Next: Br,  Prev: Line Breaks,  Up: Breaks Blank-Lines Groups
        !            91: 
        !            92: @sp
        !            93: ---
        !            94: 
        !            95: A line containing `@sp N' generates N blank lines of space in either
        !            96: the printed manual or the Info file.  For example,
        !            97: 
        !            98:      @sp 2
        !            99: 
        !           100: generates two blank lines.
        !           101: 
        !           102: 
        !           103: 
        !           104: File: texinfo,  Node: Br,  Next: W,  Prev: Sp,  Up: Breaks Blank-Lines Groups
        !           105: 
        !           106: @br
        !           107: ---
        !           108: 
        !           109: In a printed manual, a line containing `@br' forces a paragraph
        !           110: break; in the Info file output, it does nothing (not even a blank
        !           111: line results from it).
        !           112: 
        !           113: 
        !           114: 
        !           115: File: texinfo,  Node: W,  Next: Page,  Prev: Br,  Up: Breaks Blank-Lines Groups
        !           116: 
        !           117: @w
        !           118: --
        !           119: 
        !           120: In a printed manual, `@w{TEXT}' outputs TEXT and prohibits line
        !           121: breaks within TEXT.  `@w' has no effect on the Info file output; it
        !           122: is the same as would result from just TEXT.
        !           123: 
        !           124: 
        !           125: 
        !           126: File: texinfo,  Node: Page,  Next: Group,  Prev: W,  Up: Breaks Blank-Lines Groups
        !           127: 
        !           128: @page
        !           129: -----
        !           130: 
        !           131: A line containing `@page' starts a new page in a printed manual.  The
        !           132: line has no effect on Info files since they are not paginated.
        !           133: 
        !           134: 
        !           135: 
        !           136: File: texinfo,  Node: Group,  Next: Need,  Prev: Page,  Up: Breaks Blank-Lines Groups
        !           137: 
        !           138: @group
        !           139: ------
        !           140: 
        !           141: A line containing `@group' begins an unsplittable vertical group,
        !           142: which must appear entirely on one page.  The group is terminated by a
        !           143: line containing `@end group'.  These two lines produce no output of
        !           144: their own, and in the Info file output they have no effect at all.
        !           145: 
        !           146: If you forget to end a group, you may get strange and unfathomable
        !           147: error messages when you run TeX.  This is because TeX keeps trying to
        !           148: put the rest of the Texinfo file into the group and error messages do
        !           149: not start to get generated until TeX has gone a long way.  It's a
        !           150: good rule of thumb to look for a missing `@end group' if you get
        !           151: incomprehensible error messages in TeX.
        !           152: 
        !           153: 
        !           154: 
        !           155: File: texinfo,  Node: Need,  Prev: Group,  Up: Breaks Blank-Lines Groups
        !           156: 
        !           157: @need
        !           158: -----
        !           159: 
        !           160: A line containing `@need N' starts a new page in a printed manual if
        !           161: fewer than N mils (thousandths of an inch) remain on the current
        !           162: page.  The line has no effect on Info files since they are not
        !           163: paginated.
        !           164: 
        !           165: 
        !           166: 
        !           167: File: texinfo,  Node: Marking Text,  Next: Conditionals,  Prev: Formatting Paragraphs,  Up: Top
        !           168: 
        !           169: Marking Text Within a Paragraph
        !           170: *******************************
        !           171: 
        !           172: In Texinfo, text within a paragraph can be marked in a variety of ways.
        !           173: The most important way is to specify whether a word or phrase is a
        !           174: definition, a metasyntactic variable, a literal example of a program
        !           175: or what not.
        !           176: 
        !           177: In addition, there are special commands for inserting single
        !           178: characters  that have special meaning in Texinfo, such as braces, and
        !           179: for inserting symbols with special handling, such as dots and
        !           180: bullets.  Finally, there are ways to emphasize words.
        !           181: 
        !           182: * Menu:
        !           183: 
        !           184: * Specifying::                 Specifying commands, files and so on.
        !           185: * Braces Atsigns Periods::     Inserting braces, `@' and periods.
        !           186: * Dots Bullets Tex::           Inserting dots, bullets and the TeX logo
        !           187: * Emphasis::                   Emphasizing text.
        !           188: 
        !           189:  
        !           190: 
        !           191: File: texinfo,  Node: Specifying,  Next: Braces Atsigns Periods,  Up: Marking Text
        !           192: 
        !           193: Specifying Definitions, Files, Commands etc.
        !           194: ============================================
        !           195: 
        !           196: Texinfo has a variety of commands for specifying just what kind of
        !           197: object a piece of text refers to.  Metasyntactic variables, for
        !           198: example, are marked by one @-command and code by another.  Texinfo
        !           199: uses this information to determine how to highlight the text.  Since
        !           200: the pieces of text are labelled by commands that tell what kind of
        !           201: object they are, it is easy to change the way Texinfo formats and
        !           202: typesets such text.  For example, code is usually illustrated in a
        !           203: typewriter font, but it would be easy to change the way Texinfo
        !           204: highlights code to use another font.  This change would not effect
        !           205: how metasyntatic variables are highlighted.  If straight typesetting
        !           206: commands were used in the body of the file, you would have to check
        !           207: every single occurrence to make sure that you were changing code and
        !           208: not something else that should not be changed.
        !           209: 
        !           210: In addition, the commands can be used to generate useful information
        !           211: from the file, such as lists of functions or file names.  It is
        !           212: possible, for example, to write code in Emacs Lisp (or a keyboard
        !           213: macro) to insert an index entry after every paragraph that contains
        !           214: the text labelled by a specified command.  You could do this to
        !           215: construct an index of functions if you had not already made the
        !           216: entries.
        !           217: 
        !           218: The commands serve a variety of purposes:
        !           219: 
        !           220: `@code'
        !           221:      Indicates text that is a literal example of a piece of a program.
        !           222: 
        !           223: `@samp'
        !           224:      Indicates text that is a literal example of a sequence of
        !           225:      characters.
        !           226: 
        !           227: `@file'
        !           228:      Indicates the name of a file.
        !           229: 
        !           230: `@kbd'
        !           231:      Indicates the names of keys on the keyboard or characters you
        !           232:      type.
        !           233: 
        !           234: `@key'
        !           235:      Used for the conventional name for a key on a keyboard.
        !           236: 
        !           237: `@ctrl'
        !           238:      Indicates an ASCII control character.
        !           239: 
        !           240: `@var'
        !           241:      Indicates a metasyntactic variable.
        !           242: 
        !           243: `@dfn'
        !           244:      Indicates the introductory or defining use of a term.
        !           245: 
        !           246: `@cite'
        !           247:      Indicates the name of a book.
        !           248: 
        !           249: * Menu:
        !           250: 
        !           251: * Code::       A literal example of a piece of a program.
        !           252: * Samp::       A literal example of a sequence of characters.
        !           253: * File::       The name of a file.
        !           254: * Kbd::                The names of keys or else characters you type.
        !           255: * Key::                The conventional name for a key on a keyboard.
        !           256: * Ctrl::       Indicates the ASCII control character.
        !           257: * Var::                A variable.
        !           258: * Dfn::                The introductory or defining use of a term.
        !           259: * Cite::       The name of a book.
        !           260: 
        !           261:  
        !           262: 
        !           263: File: texinfo,  Node: Code,  Next: Samp,  Up: Specifying
        !           264: 
        !           265: @code
        !           266: -----
        !           267: 
        !           268: `@code' is used to indicate text that is a piece of a program which
        !           269: consists of entire syntactic tokens.  The text follows, enclosed in
        !           270: braces.
        !           271: 
        !           272: For example, `@code' is used for an expression in a program, the name
        !           273: of a variable or function used in a program, or a keyword.  `@code'
        !           274: is not used for a piece of a token, such as when speaking about the
        !           275: characters used in a token; for example, when you are explaining what
        !           276: letters or printable symbols can be used in the names of functions. 
        !           277: It is also not used for input to programs unless the input is written
        !           278: in a language that is like a programming language.  For example, it
        !           279: is not used for the single character commands of GNU Emacs although
        !           280: it is used for the names of Emacs Lisp functions that the keyboard
        !           281: commands invoke.
        !           282: 
        !           283: You should also `@code' for command names in command languages that
        !           284: resemble programming languages, such as Texinfo or the shell.  Note,
        !           285: however, that `@code' is not used for options such as `-c' when such
        !           286: options stand alone.  There is some argument as to whether an entire
        !           287: shell command incorporating an option should be written using `@code'
        !           288: or `@samp'.
        !           289: 
        !           290: It is an error to alter the case of a word inside an `@code' command.
        !           291: This is a particularly insidious error if the language being
        !           292: documented is case sensitive.  If the command is `printf', then
        !           293: `Printf' is a misspelling.  If you do not like having such a command
        !           294: with lower case at the beginning of a sentence, you may wish to
        !           295: rearrange the sentence.
        !           296: 
        !           297: In the printed manual, `@code' puts the argument in bold face.  In
        !           298: the Info file, it uses `...' quotation.  For example:
        !           299: 
        !           300:      To compare two files, showing text inserted or removed, use @code{diff}.
        !           301: 
        !           302:  produces
        !           303: 
        !           304:      To compare two files, showing text inserted or removed, use
        !           305:      `diff'.
        !           306: 
        !           307: 
        !           308: 
        !           309: File: texinfo,  Node: Samp,  Next: File,  Prev: Code,  Up: Specifying
        !           310: 
        !           311: @samp
        !           312: -----
        !           313: 
        !           314: `@samp' is used to indicate text that is a literal example of a
        !           315: sequence of characters in a file, string, pattern, etc.  The text
        !           316: follows, enclosed in braces.  The argument appears within `...'
        !           317: quotation in both the Info file and the printed manual; in addition,
        !           318: it is printed in a fixed-width font.
        !           319: 
        !           320:      To match @samp{foo} at the end of the line, use the regexp @samp{foo$}.
        !           321: 
        !           322:  produces
        !           323: 
        !           324:      To match `foo' at the end of the line, use the regexp `foo$'.
        !           325: 
        !           326: Any time you are referring to single characters, you should use
        !           327: `@samp' unless `@kbd' is more appropriate.  Basically, `@samp' is a
        !           328: catchall for whatever is not covered by `@code', `@file', `@kbd'.
        !           329: 
        !           330: Punctuation marks that are part of the English text that surrounds
        !           331: the strings you are specifying are *never* included within the
        !           332: braces.  In the following sentence, for example, the commas and
        !           333: period are outside of the braces:
        !           334: 
        !           335:      A symbol name ends in @samp{a}, @samp{b}, or @samp{c}.
        !           336: 
        !           337:  
        !           338: 
        !           339: File: texinfo,  Node: File,  Next: Kbd,  Prev: Samp,  Up: Specifying
        !           340: 
        !           341: @file
        !           342: -----
        !           343: 
        !           344: `@file' is used to indicate text that is the name of a file or
        !           345: directory.  Currently, it is equivalent to `@samp' in its effects on
        !           346: the output.  For example,
        !           347: 
        !           348:      The @file{.el} files are in 
        !           349:      the @file{/gnu/emacs/lisp} directory.
        !           350: 
        !           351:  produces
        !           352: 
        !           353:      The `.el' files are in  the `/gnu/emacs/lisp' directory.
        !           354: 
        !           355: 
        !           356: 
        !           357: File: texinfo,  Node: Kbd,  Next: Key,  Prev: File,  Up: Specifying
        !           358: 
        !           359: @kbd
        !           360: ----
        !           361: 
        !           362: `@kbd' is used much like `@code'.  The difference is that `@kbd' is
        !           363: for names of keys on the keyboard, or of characters you can type. 
        !           364: For example, to refer to the command `M-a', you would use
        !           365: 
        !           366:      @kbd{M-a}
        !           367: 
        !           368: and to refer to `M-x shell', you would use
        !           369: 
        !           370:      @kbd{M-x shell}
        !           371: 
        !           372: The `@kbd' command has the same effect as `@code' in Info, but may
        !           373: produce a different font in a printed manual.
        !           374: 
        !           375: You can embed another @-command inside the braces of a `@kbd'
        !           376: command.  This is the way to describe a command that would be
        !           377: described more verbosely as ``press an `r' and then press the RET
        !           378: key'':
        !           379: 
        !           380:      @kbd{r @key{RET}}
        !           381: 
        !           382: This produces: `r RET'
        !           383: 
        !           384: You also use the `@kbd' command if you are spelling out the letters
        !           385: you type; for example:
        !           386: 
        !           387:      To give the @code{logout} command, 
        !           388:      type the characters @kbd{l o g o u t @key{RET}}.
        !           389: 
        !           390:  This produces
        !           391: 
        !           392:      To give the `logout' command,  type the characters `l o g o u t
        !           393:      RET'.
        !           394: 
        !           395: 
        !           396: 
        !           397: File: texinfo,  Node: Key,  Next: Ctrl,  Prev: Kbd,  Up: Specifying
        !           398: 
        !           399: @key
        !           400: ----
        !           401: 
        !           402: `@key' is used for the conventional name for a key on a keyboard, as in
        !           403: 
        !           404:      @key{RET}
        !           405: 
        !           406: Often, `@key' is used within the argument of a `@kbd' command,
        !           407: whenever the sequence of characters to be typed includes one or more
        !           408: keys that are described by name.
        !           409: 
        !           410: For example, to produce `C-x ESC' you would use
        !           411: 
        !           412:      @kbd{C-x @key{ESC}}
        !           413: 
        !           414: The recommended names to use for keys are in upper case and are
        !           415: 
        !           416: SPC
        !           417:      Space.
        !           418: 
        !           419: RET
        !           420:      Return.
        !           421: 
        !           422: LFD
        !           423:      Linefeed.
        !           424: 
        !           425: TAB
        !           426:      Tab.
        !           427: 
        !           428: BS
        !           429:      Backspace.
        !           430: 
        !           431: ESC
        !           432:      Escape.
        !           433: 
        !           434: DEL
        !           435:      Delete.
        !           436: 
        !           437: SFT
        !           438:      Shift.
        !           439: 
        !           440: CTL
        !           441:      Control.
        !           442: 
        !           443: META
        !           444:      Meta.
        !           445: 
        !           446: There are subtleties to handling words like `meta' or `ctrl' which
        !           447: are names of shift keys.  When mentioning a character in which the
        !           448: shift key is used, such as `Meta-a', use the `@kbd' command alone
        !           449: without the `@key' command, but when you are referring to shift key
        !           450: in isolation, use the `@key' command.  For example, you would use
        !           451: `@kbd{Meta-a}' to produce `Meta-a' and `@key{META}' to produce META.
        !           452: 
        !           453: 
        !           454: 
        !           455: File: texinfo,  Node: Ctrl,  Next: Var,  Prev: Key,  Up: Specifying
        !           456: 
        !           457: @ctrl
        !           458: -----
        !           459: 
        !           460: `@ctrl' is used to describe an ASCII control character.  The pattern
        !           461: of usage is `@ctrl{CH}', where CH is an ASCII character whose
        !           462: control-equivalent is wanted.  Thus, you put in an `f' when you want
        !           463: to indicate a `control-f'
        !           464: 
        !           465: Thus, to specify `control-f', you would enter
        !           466: 
        !           467:      @ctrl{f}
        !           468: 
        !           469: which produces
        !           470: 
        !           471:      f
        !           472: 
        !           473: In the Info file, this generates the specified control character,
        !           474: output literally into the file.  This is done so a user can copy the
        !           475: specified control character (along with whatever else he or she
        !           476: wants) into another Emacs buffer and use it.  Since the
        !           477: `control-h',`control-i', and `control-j' characters are formatting
        !           478: characters, they should not be indicated this way.
        !           479: 
        !           480: In a printed manual, this generates text to describe or identify that
        !           481: control character: an uparrow followed by the character CH.
        !           482: 
        !           483: 
        !           484: 
        !           485: File: texinfo,  Node: Var,  Next: Dfn,  Prev: Ctrl,  Up: Specifying
        !           486: 
        !           487: @var
        !           488: ----
        !           489: 
        !           490: `@var' is used to indicate metasyntactic variables.  A metasyntactic
        !           491: variable is something that stands for another piece of text.  You
        !           492: would use a metasyntactic variable in the documentation of a function
        !           493: to describe the arguments that are passed to that function.
        !           494: 
        !           495: `@var' is not used for names of particular variables in programming
        !           496: languages.  For example, the Texinfo variable `texinfo-tex-command'
        !           497: is not a metasyntactic variable.
        !           498: 
        !           499: Its effect in the Info file is to upcase the argument; in the printed
        !           500: manual, to italicize it.  Example:
        !           501: 
        !           502:      To delete file @var{filename}, type @code{rm @var{filename}}.
        !           503: 
        !           504:  produces
        !           505: 
        !           506:      To delete file FILENAME, type `rm FILENAME'.
        !           507: 
        !           508: In some documentation styles, metasyntactic variables are shown with
        !           509: angle brackets, for example:
        !           510: 
        !           511:      ..., type rm <filename>
        !           512: 
        !           513: 
        !           514: 
        !           515: File: texinfo,  Node: Dfn,  Next: Cite,  Prev: Var,  Up: Specifying
        !           516: 
        !           517: @dfn
        !           518: ----
        !           519: 
        !           520: `@dfn' is used to identify the introductory or defining use of a
        !           521: technical term.  The command should be used only in a passage whose
        !           522: purpose is to introduce a term which will be used again or which the
        !           523: reader ought to know.  Mere passing mention of a term for the first
        !           524: time doesn't deserve `@dfn'.  It generates italics in the printed
        !           525: manual, and double quotation marks in the Info file.  Example:
        !           526: 
        !           527:      Getting rid of a file is called @dfn{deleting} it.
        !           528: 
        !           529:  produces
        !           530: 
        !           531:      Getting rid of a file is called "deleting" it.
        !           532: 
        !           533: 
        !           534: 
        !           535: File: texinfo,  Node: Cite,  Prev: Dfn,  Up: Specifying
        !           536: 
        !           537: @cite
        !           538: -----
        !           539: 
        !           540: `@cite' is used for the name of a book.  It produces italics in the
        !           541: printed manual, and quotation marks in the Info file.
        !           542: 
        !           543: 
        !           544: 
        !           545: File: texinfo,  Node: Braces Atsigns Periods,  Next: Dots Bullets Tex,  Prev: Specifying,  Up: Marking Text
        !           546: 
        !           547: Inserting Braces, `@' and Periods
        !           548: =================================
        !           549: 
        !           550: `@' and curly braces are special characters in Texinfo.  This means
        !           551: that you have to put an `@' in front of these characters in order to
        !           552: insert them into text.
        !           553: 
        !           554: Periods are also special.  Depending on whether the period is inside
        !           555: of or at the end of a sentence, less or more space is inserted after
        !           556: a period in a typeset manual.  Since it is not always possible for
        !           557: Texinfo to determine when a period ends a sentence and when it is
        !           558: used in an abbreviation, special commands are needed.  (Usually,
        !           559: Texinfo figures out how to handle periods, so you don't have to use
        !           560: the special commands; you just enter a period as you would if you
        !           561: were using a typewriter, which means you put two spaces after the
        !           562: period that ends a sentence and after a colon.)
        !           563: 
        !           564: * Menu:
        !           565: 
        !           566: * Inserting an Atsign::                inserting an atsign.
        !           567: * Insert Left Brace::          Inserting a left brace.
        !           568: * Insert Colon::               Preventing unintended additional whitespace.
        !           569: * Insert Period::              Inserting a period that does end a sentence.
        !           570: 
        !           571:  
        !           572: 
        !           573: File: texinfo,  Node: Inserting An Atsign,  Next: Insert Left Brace,  Up: Braces Atsigns Periods
        !           574: 
        !           575: @@
        !           576: --
        !           577: 
        !           578: `@@' stands for a single @ in either printed or Info output.
        !           579: 
        !           580: 
        !           581: 
        !           582: File: texinfo,  Node: Insert Left Brace,  Next: Insert Colon,  Prev: Inserting an Atsign,  Up: Braces Atsigns Periods
        !           583: 
        !           584: @{
        !           585: --
        !           586: 
        !           587: `@{' stands for a single { in either printed or Info output.
        !           588: 
        !           589: @}
        !           590: --
        !           591: 
        !           592: `@}' stands for a single } in either printed or Info output.
        !           593: 
        !           594: 
        !           595: 
        !           596: File: texinfo,  Node: Insert Colon,  Next: Insert Period,  Prev: Insert Left Brace,  Up: Braces Atsigns Periods
        !           597: 
        !           598: @:
        !           599: --
        !           600: 
        !           601: `@:' is used after a character such as period or colon which normally
        !           602: causes TeX to increase the width of the following whitespace, to
        !           603: suppress that effect.  For example, it can be used after periods that
        !           604: end abbreviations and do not end sentences.  `@:' has no effect on
        !           605: the Info file output.
        !           606: 
        !           607:      It displays @code{Foo:}@: at that time.
        !           608: 
        !           609:  produces
        !           610: 
        !           611:      It displays `Foo:' at that time.
        !           612: 
        !           613: The meanings of `@:' and `@.' in Texinfo are designed to work well
        !           614: with the Emacs sentence motion commands.  This means they are
        !           615: different from their meanings in some other formatting systems that
        !           616: use @-commands.
        !           617: 
        !           618: 
        !           619: 
        !           620: File: texinfo,  Node: Insert Period,  Prev: Insert Colon,  Up: Braces Atsigns Periods
        !           621: 
        !           622: @.
        !           623: --
        !           624: 
        !           625: `@.' stands for a period that really does end a sentence, useful when
        !           626: TeX would otherwise assume by its heuristics that that is not so. 
        !           627: This happens when there is a single-capital-letter word at the end of
        !           628: a sentence: TeX normally guesses that it is an abbreviation.
        !           629: 
        !           630: In the Info file output, `@.' is equivalent to a simple `.'.  The
        !           631: Texinfo program preserves the amount of space that you use, so put
        !           632: two spaces after a period if you intend it to be the end of a
        !           633: sentence (as well as using `@.', if necessary, for the printed
        !           634: manual's sake).
        !           635: 
        !           636:      Give it to X. Give it to X@.  Give it to X@.
        !           637: 
        !           638:  produces
        !           639: 
        !           640:      Give it to X. Give it to X.  Give it to X.
        !           641: 
        !           642: 
        !           643: 
        !           644: File: texinfo,  Node: Dots Bullets Tex,  Next: Emphasis,  Prev: Braces Atsigns Periods,  Up: Marking Text
        !           645: 
        !           646: Inserting Dots, Bullets and TeX
        !           647: ===============================
        !           648: 
        !           649: An ellipsis, a line of dots, is typeset differently than a string of
        !           650: periods; more whitespace is put between the dots in the ellipsis than
        !           651: is put between the periods.  Because of this, a special command is
        !           652: used in Texinfo for inserting dots.  Also, the trademark, TeX, is
        !           653: typeset in a special fashion and it needs an @-command, as does the
        !           654: command for inserting the copyright symbol.  The `@bullet' command is
        !           655: special, too.  Each of these commands is followed by a pair of
        !           656: braces, `{}', without any whitespace between the name of the command
        !           657: and the braces.
        !           658: 
        !           659: * Menu:
        !           660: 
        !           661: * Dots::               Inserting dots.
        !           662: * Bullet::             Inserting bullets.
        !           663: * Tex::                        Inserting the TeX trademark.
        !           664: 
        !           665:  
        !           666: 
        !           667: File: texinfo,  Node: Dots,  Next: Bullet,  Up: Dots Bullets Tex
        !           668: 
        !           669: @dots{}
        !           670: -------
        !           671: 
        !           672: `@dots{}' generates an ellipsis which is three dots in a row,
        !           673: appropriately spaced, like this: `...'.  Do not simply write three
        !           674: periods in the input file; that would work for the Info file output,
        !           675: but would produce the wrong amount of space between the periods in
        !           676: the printed manual.
        !           677: 
        !           678: 
        !           679: 
        !           680: File: texinfo,  Node: Bullet,  Next: Tex,  Prev: Dots,  Up: Dots Bullets Tex
        !           681: 
        !           682: @bullet{}
        !           683: ---------
        !           684: 
        !           685: `@bullet{}' generates a large round dot, or the closest possible
        !           686: thing to one.
        !           687: 
        !           688: Here is a bullet: *
        !           689: 
        !           690: 
        !           691: 
        !           692: File: texinfo,  Node: Tex,  Prev: Bullet,  Up: Dots Bullets Tex
        !           693: 
        !           694: @TeX{}
        !           695: ------
        !           696: 
        !           697: `@TeX{}' generates `TeX'.  In a printed manual, this is a special
        !           698: logo that is different from three ordinary letters.
        !           699: 
        !           700: 
        !           701: 
        !           702: File: texinfo,  Node: Emphasis,  Prev: Dots Bullets Tex,  Up: Marking Text
        !           703: 
        !           704: Emphasizing Text
        !           705: ================
        !           706: 
        !           707: Usually, Texinfo changes the font automatically to mark words in the
        !           708: text according to what category the words belong to.  The `@code'
        !           709: command, for example, does this.  Most often, this is the best way to
        !           710: mark specified words.  However, sometimes you will want to emphasize
        !           711: text directly.  Texinfo has two ways to do this: commands that tell
        !           712: Texinfo to emphasize the text but leave the method to the program,
        !           713: and commands that specify the font to use.  The first method is
        !           714: generally the best and it makes it possible to change the style of a
        !           715: document without have to re-edit it line by line.
        !           716: 
        !           717: * Menu:
        !           718: 
        !           719: * Emph and Strong::    Emphasizing text.
        !           720: * Fonts::              Selecting italic, bold or typewriter fonts.
        !           721: 
        !           722:  
        !           723: 
        !           724: File: texinfo,  Node: Emph and Strong,  Next: Fonts,  Up: Emphasis
        !           725: 
        !           726: @emph and @strong
        !           727: -----------------
        !           728: 
        !           729: `@emph' and `@strong' are two forms of emphasis.  `@strong' is
        !           730: stronger.
        !           731: 
        !           732: In printed output, `@emph' produces *italics* and `@strong' produces
        !           733: *bold*.
        !           734: 
        !           735: In the Info file, both of these commands put asterisks around the
        !           736: argument.
        !           737: 
        !           738: 
        !           739: 
        !           740: File: texinfo,  Node: Fonts,  Prev: Emph and Strong,  Up: Emphasis
        !           741: 
        !           742: @i,  @b and @t
        !           743: --------------
        !           744: 
        !           745: These three commands specify font changes in the printed manual and
        !           746: have no effect in the Info file.  `@i' requests italic font (in some
        !           747: versions of TeX, a slanted font is used), `@b' requests bold face,
        !           748: and `@t' requests the fixed-width font used by `@kbd'.  All three
        !           749: commands apply to an argument that follows, surrounded by braces.
        !           750: 
        !           751: If possible, you should avoid using these three commands.  If you
        !           752: find a need to use one, it probably indicates a lack in the Texinfo
        !           753: language.
        !           754: 
        !           755: 
        !           756: 
        !           757: File: texinfo,  Node: Conditionals,  Next: Printing Hardcopy,  Prev: Marking Text,  Up: Top
        !           758: 
        !           759: Conditionals
        !           760: ************
        !           761: 
        !           762: You may not always be able to use the same text for both the printed
        !           763: manual and the on-line Info file.  In this case, you can use the
        !           764: conditional commands to specify which text is for the printed manual
        !           765: and which is for the Info file.
        !           766: 
        !           767: `@ifinfo' begins text that should be ignored by TeX when it typesets
        !           768: the printed manual.  The text appears only in the Info file.  The
        !           769: `@ifinfo' command should appear on a line by itself.  End the
        !           770: info-only text with a line containing `@end ifinfo' by itself.  At
        !           771: the beginning of a Texinfo file, the Info permissions are contained
        !           772: within a region marked by `@ifinfo' and `@end ifinfo'.
        !           773: 
        !           774: Likewise, `@iftex' and `@end iftex' lines delimit text that will not
        !           775: appear in the Info file but will appear in the printed manual.
        !           776: 
        !           777: For example,
        !           778: 
        !           779:      @iftex
        !           780:      This text will appear only in the printed manual.
        !           781:      @end iftex
        !           782:      
        !           783:      
        !           784:      @ifinfo
        !           785:      However, this text will appear only in the info manual.
        !           786:      @end ifinfo
        !           787: 
        !           788: The preceding example produces the following.  Note how you only see
        !           789: one of the two lines, depending on whether you are reading the
        !           790: on-line Info version or the printed version of this manual.
        !           791: 
        !           792: However, this text will appear only in the info manual.
        !           793: 
        !           794: The `@titlepage' command is a special variant of `@iftex' that is
        !           795: used for making the title and copyright pages of the printed manual.
        !           796: 
        !           797: * Menu:
        !           798: 
        !           799: * Using Tex Commands::         Using commands from regular TeX.
        !           800: 
        !           801:  
        !           802: 
        !           803: File: texinfo,  Node: Using Tex Commands,  Prev: Conditionals,  Up: Conditionals
        !           804: 
        !           805: Using TeX Commands
        !           806: ==================
        !           807: 
        !           808: Inside a region delineated by `@iftex' and `@end iftex', you can
        !           809: embed ordinary TeX commands.  Info will ignore these commands since
        !           810: they are only in that part of the file that is seen by TeX.  The TeX
        !           811: commands are the same as any TeX commands except that an `@' replaces
        !           812: the `\' used by TeX.  For example, in the `@titlepage' section of a
        !           813: Texinfo file, the TeX command `@vskip' is used to format the
        !           814: copyright page.
        !           815: 
        !           816: You can enter TeX completely, and use `\' in the TeX commands by
        !           817: delineating a region with the `@tex' and `@end tex' commands.  (These
        !           818: commands automatically put the region inside of `@iftex' and `@end
        !           819: iftex' commands.)  For example,
        !           820: 
        !           821:      @tex
        !           822:      Here you would put text with TeX commands;
        !           823:      such as $\bigl(x\in A(n)\bigm|x\in B(n)\bigr)$
        !           824:      that will appear only  in the printed manual.
        !           825:      @end tex
        !           826: 
        !           827: In the Info file, nothing between `@tex' and `@end tex' will appear.
        !           828: 
        !           829: 
        !           830: 
        !           831: File: texinfo,  Node: Printing Hardcopy,  Next: Creating an Info File,  Prev: Conditionals,  Up: Top
        !           832: 
        !           833: Printing Hardcopy
        !           834: *****************
        !           835: 
        !           836: There are three shell commands for printing a hardcopy of a Texinfo
        !           837: file.  One is for formatting the file, the second is for sorting the
        !           838: index and the third is for printing the formatted document.  When you
        !           839: use the shell commands, you can either work directly in the operating
        !           840: system shell or work within a shell inside of GNU Emacs.
        !           841: 
        !           842: The typesetting program TeX is used for formatting a Texinfo file. 
        !           843: TeX is a very powerful typesetting program and, if used right, does
        !           844: an exceptionally good job.  The @-commands in a Texinfo file are
        !           845: translated by a file called `texinfo.tex' into commands that TeX
        !           846: understands.  (That is why the beginning of every Texinfo file starts
        !           847: with the line that says `\input texinfo'; this command tells TeX to
        !           848: use the `texinfo.tex' file in processing the Texinfo file. 
        !           849: Customarily, `texinfo.tex' is in a directory called
        !           850: `/usr/lib/tex/macros'.) `texinfo-format-buffer' reads the very same
        !           851: @-commands in the Texinfo file and processes them differently from
        !           852: TeX to make an Info file.
        !           853: 
        !           854: Usually, the TeX formatting command is the shell command `tex'
        !           855: followed by the name of the Texinfo file.  The TeX command produces a
        !           856: formatted DVI file as well as several auxiliary files containing
        !           857: indices, cross references, etc.  The DVI file (for "DeVice
        !           858: Independent" file) can be printed on a wide variety of printers.
        !           859: 
        !           860: The TeX formatting command itself does not sort the indices.  This is
        !           861: a misfeature of TeX.  Hence, to generate a printed index, you first
        !           862: need a sorted index to work from.
        !           863: 
        !           864: TeX outputs raw, unsorted index files under names that obey a
        !           865: standard convention.  These names are the name of your main input
        !           866: file to TeX, with everything after the first period thrown away, and
        !           867: the two letter names of indices added at the end.  For example, the
        !           868: raw index output files for the input file `foo.texinfo' would be
        !           869: `foo.cp', `foo.vr', `foo.fn', `foo.tp', `foo.pg' and `foo.ky'.  Those
        !           870: are exactly the arguments to give to `texindex'.  Or else, you can
        !           871: use `??' as ``wild-cards'' and give the command in this form:
        !           872: 
        !           873:      texindex foo.??
        !           874: 
        !           875:  For each file specified, `texindex' generates a sorted index file
        !           876: whose name is made by appending `s' to the input file name.  The
        !           877: `@printindex' command knows to look for a file of that name. 
        !           878: `texindex' does not alter the raw index output file. After you have
        !           879: sorted the indices, you need to rerun the TeX command on the Texinfo
        !           880: file.  This regenerates a formatted DVI file with the index entries
        !           881: in the correct order.
        !           882: 
        !           883: To summarize, this is a three step process:
        !           884: 
        !           885:   1. Run the TeX command on the Texinfo file.  This generates the
        !           886:      formatted DVI file as well as the raw index files with two
        !           887:      letter extensions.
        !           888: 
        !           889:   2. Run the shell command `texindex' on the raw index files to sort
        !           890:      them.  The arguments to `texindex' are the names of the raw
        !           891:      index files.  `texindex' creates sorted index files whose names
        !           892:      are the names of the raw index files with an `s' appended.  To
        !           893:      cause `texindex' to sort all the raw index files, append `??' to
        !           894:      the Texinfo file name in place of the `.texinfo' extension.
        !           895: 
        !           896:   3. Rerun the TeX command on the Texinfo file.  This regenerates a
        !           897:      formatted DVI file with the index entries in the correct order. 
        !           898:      This second run also makes all the cross references correct as
        !           899:      well.  (The tables of contents are always correct.)
        !           900: 
        !           901: You need not run `texindex' after each TeX run.  If you don't, the
        !           902: next TeX run will use whatever sorted index files happen to exist
        !           903: from the previous use of `texindex'.  This is usually ok while you
        !           904: are debugging.
        !           905: 
        !           906: Finally, the document can be printed out with the DVI print command
        !           907: (a shell command).  Depending on the system used, the DVI print
        !           908: command will be a command such as `lpr -d'.  The DVI print command
        !           909: may require a file name without any extension or with a `.dvi'
        !           910: extension.
        !           911: 
        !           912: The following commands, for example, sort the indices, format and
        !           913: print the ``Bison Manual'' (where `%' is the shell prompt):
        !           914: 
        !           915:      % tex bison.texinfo
        !           916:      % texindex bison.??
        !           917:      % tex bison.texinfo
        !           918:      % lpr -d bison.dvi
        !           919: 
        !           920: (Remember that the words for the shell commands may be different at
        !           921: your site; but these are commonly used versions.)
        !           922: 
        !           923: It is often most convenient to give formatting and printing commands
        !           924: from a shell within GNU Emacs.  This way, you can easily keep track
        !           925: of errors.  To create a shell within Emacs, type `M-x shell'.  In
        !           926: this shell, you can format and print the document.  You can switch to
        !           927: and from this shell while it is running and do other things.  If you
        !           928: are formatting a very long document on a slow machine, this can be
        !           929: very convenient; on a VAX 750, for example, formatting often takes 8
        !           930: seconds or more per page depending on how loaded the computer is. 
        !           931: Faster machines take correspondingly less time.
        !           932: 
        !           933: * Menu:
        !           934: 
        !           935: * Requirements::       Formatting requirements.
        !           936: * Compile-Command::    Formatting with the compile command.
        !           937: 
        !           938:  
        !           939: 
        !           940: File: texinfo,  Node: Requirements,  Next: Compile-Command,  Up: Printing Hardcopy
        !           941: 
        !           942: Formatting Requirements
        !           943: =======================
        !           944: 
        !           945: Every Texinfo file that is to be input to TeX must begin with a line
        !           946: that looks like
        !           947: 
        !           948:      \input texinfo   @c -*-texinfo-*-
        !           949: 
        !           950: This serves two functions.
        !           951: 
        !           952:   1. When the file is processed by TeX, it loads the macros needed
        !           953:      for processing a Texinfo file.
        !           954: 
        !           955:   2. When the file is edited in Emacs, it causes Texinfo mode to be
        !           956:      used.
        !           957: 
        !           958: Every Texinfo file must end with a line saying
        !           959: 
        !           960:      @bye
        !           961: 
        !           962: which terminates TeX processing and forces out unfinished pages.
        !           963: 
        !           964: You also have to include two lines that specify the Info file name
        !           965: and the title of the printed manual:
        !           966: 
        !           967:      @setfilename NAME-OF-TEXINFO-FILE
        !           968:      @settitle NAME OF MANUAL
        !           969: 
        !           970: You might also want to include a line saying
        !           971: 
        !           972:      @setchapternewpage odd
        !           973: 
        !           974: to cause each chapter to start on a fresh odd-numbered page.
        !           975: 
        !           976: By default, TeX typesets pages for printing in an 8.5 by 11 inch
        !           977: format.  However, you can direct TeX to typeset a document in a 7 by
        !           978: 9.25 inch format that is suitable for bound books by inserting the
        !           979: following command on a line by itself at the beginning of the Texinfo
        !           980: file, before the `@setchapternewpage' command:
        !           981: 
        !           982:      @smallbook
        !           983: 
        !           984: The Free Software Foundation distributes printed copies of the ``GNU
        !           985: Emacs Manual'' in this size.
        !           986: 
        !           987: Finally, TeX sometimes is unable to typeset a line without extending
        !           988: it into the right margin.  This can occur when TeX comes upon what it
        !           989: interprets as a long word that it cannot hyphenate, like a net
        !           990: address, or a very long title.  When this happens, TeX prints an
        !           991: error message like this:
        !           992: 
        !           993:      Overfull \hbox (20.76302pt too wide)
        !           994: 
        !           995: and gives the line number along with the text of the offending line
        !           996: marked at all the places that TeX knows to hyphenate words.  (In TeX
        !           997: lines are in `horizontal boxes', hence the term, `hbox'.)
        !           998: 
        !           999: If the Texinfo file has an overfull hbox, you can rewrite the
        !          1000: sentence so the overfull hbox does not occur or you can decide to
        !          1001: leave it.  A small excursion into the right margin often does not
        !          1002: matter and may not even be noticable.  However, unless told
        !          1003: otherwise, TeX will print a large, ugly, black rectangle beside every
        !          1004: line that is overfull.  This is so you will notice the location of
        !          1005: the problem if you are correcting a draft.  To prevent such
        !          1006: monstrosities from marring your final printout, put the following in
        !          1007: the beginning of the Texinfo file on lines of their own, before the
        !          1008: `@setchapternewpage' command:
        !          1009: 
        !          1010:      @iftex
        !          1011:      @finalout
        !          1012:      @end iftex
        !          1013: 
        !          1014: *Note Titlepage::, for information about creating a title page. 
        !          1015: *Note Contents::, for information about creating a table of contents.
        !          1016: 
        !          1017: 
        !          1018: 
        !          1019: File: texinfo,  Node: Compile-Command,  Prev: Requirements,  Up: Printing Hardcopy
        !          1020: 
        !          1021: Using Local Variables and the Compile Command
        !          1022: =============================================
        !          1023: 
        !          1024: Another way to give the TeX formatting command to Texinfo is to put
        !          1025: that command in a "local variables list" at the end of the Texinfo
        !          1026: file.  You can then specify the TeX formatting command as a
        !          1027: `compile-command' and have Emacs run the TeX formatting command by
        !          1028: giving the command `M-x compile'.  This creates a special shell
        !          1029: called the `*compilation buffer*'.  For example, at the end of the
        !          1030: `gdb.texinfo' file, after the `@bye', you would put the following:
        !          1031: 
        !          1032:      @c Local Variables:
        !          1033:      @c compile-command: "tex gdb.texinfo"
        !          1034:      @c End:
        !          1035: 
        !          1036: This technique is most often used by programmers who compile programs
        !          1037: this way.
        !          1038: 
        !          1039: 
        !          1040: 
        !          1041: File: texinfo,  Node: Creating an Info File,  Next: Catching Mistakes,  Prev: Printing Hardcopy,  Up: Top
        !          1042: 
        !          1043: Creating an On-line Info file
        !          1044: *****************************
        !          1045: 
        !          1046: In GNU Emacs, using Texinfo mode, you can see what part or all of a
        !          1047: Texinfo file will look like in Info by using the keyboard command
        !          1048: `C-c C-f' (`texinfo-format-region').  This formats a region and
        !          1049: displays in a temporary buffer called `*Info Region*'; however, this
        !          1050: command does not turn on Info reading program--it just displays what
        !          1051: the region will look like.  The `texinfo-format-region' command is
        !          1052: described more extensively in the chapter on using Texinfo mode. 
        !          1053: *Note Info on a Region::.
        !          1054: 
        !          1055: In GNU Emacs, the way to create a working Info file is to visit the
        !          1056: file and invoke
        !          1057: 
        !          1058:      `M-x texinfo-format-buffer'
        !          1059: 
        !          1060: A new buffer is created and the Info file text is generated there. 
        !          1061: `C-x C-s' will save it under the name specified in the `@setfilename'
        !          1062: command.
        !          1063: 
        !          1064: If the Texinfo file has more than 30,000 bytes,
        !          1065: `texinfo-format-buffer' will automatically create a "tag table" for
        !          1066: it.  With a tag table, Info can jump to new nodes more quickly than
        !          1067: it can otherwise.  In addition, if the file has more than 100,000
        !          1068: bytes in it, `texinfo-format-buffer' will split the file into shorter
        !          1069: Indirect subfiles of about 50,000 bytes each.  Files are split so
        !          1070: that Info does not have to make a large buffer to hold the whole of a
        !          1071: large Info file; instead, Info allocates just enough memory for the
        !          1072: small, split off file that is needed at the time.  This way, Emacs
        !          1073: avoids wasting memory when you run Info.  (Before splitting was
        !          1074: implemented, Info files were always short and "include" files were
        !          1075: designed as a way to create a single, large printed manual out of the
        !          1076: smaller Info files. *Note Include Files::, for more information.)
        !          1077: 
        !          1078: When the file is split, Info itself works through a shortened version
        !          1079: of the original file that contains the tag table and references to
        !          1080: the files that were split off.  The split off files are called
        !          1081: "indirect" files.
        !          1082: 
        !          1083: The split off files have names that are created by appending `-1',
        !          1084: `-2', `-3' and so on to the file names specified by the
        !          1085: `@setfilename' command.  The shortened version of the original file
        !          1086: continues to have the name specified by `@setfilename'.
        !          1087: 
        !          1088: At one stage in writing this document, for example, the Info file was
        !          1089: saved as `test-texinfo' and that file looked like this:
        !          1090: 
        !          1091:      Info file: test-texinfo,    -*-Text-*-
        !          1092:      produced by texinfo-format-buffer
        !          1093:      from file: new-texinfo-manual.texinfo
        !          1094:      
        !          1095:      ^_
        !          1096:      Indirect:
        !          1097:      test-texinfo-1: 102
        !          1098:      test-texinfo-2: 50422
        !          1099:      test-texinfo-3: 101300
        !          1100:      ^_^L
        !          1101:      Tag table:
        !          1102:      (Indirect)
        !          1103:      Node: overview^?104
        !          1104:      Node: info file^?1271
        !          1105:      Node: printed manual^?4853
        !          1106:      Node: conventions^?6855
        !          1107:      ...
        !          1108: 
        !          1109:  (But `test-texinfo' had far more nodes than are shown here.)  Each of
        !          1110: the split off, indirect files, `test-texinfo-1', `test-texinfo-2',
        !          1111: and `test-texinfo-3', is listed in this file after the line that says
        !          1112: `Indirect:'.  The tag table is listed after the line that says `Tag
        !          1113: table:'.
        !          1114: 
        !          1115: You cannot run the `M-x Info-validate' node checking command on
        !          1116: indirect files.  For information on how to prevent files from being
        !          1117: split and how to validate the structure of the nodes, *note
        !          1118: Info-Validating a Large File::.
        !          1119: 
        !          1120: * Menu:
        !          1121: 
        !          1122: * Installing an Info File::    Putting the Info file in the info directory.
        !          1123: 
        !          1124:  
        !          1125: 
        !          1126: File: texinfo,  Node: Installing an Info File,  Prev: Creating an Info File,  Up: Creating an Info File
        !          1127: 
        !          1128: Installing an Info file
        !          1129: =======================
        !          1130: 
        !          1131: An Info file is usually installed in the GNU Emacs directory called
        !          1132: `info'.  For Info to work, this directory must contain all the Info
        !          1133: files, including the split off files.  In addition, the `info'
        !          1134: directory must have a file that serves as a top level directory for
        !          1135: the Info system.  This file is called `dir'.
        !          1136: 
        !          1137: For example, in the `info' directory, the file called `dir' has the
        !          1138: top level menu for all the Info files in the system.  This file has a
        !          1139: master menu that looks like this:
        !          1140: 
        !          1141:      * Menu:
        !          1142:      
        !          1143:      * Info:    (info).      Documentation browsing system.
        !          1144:      * Emacs:   (emacs).     The extensible self-documenting text editor.
        !          1145:      * Texinfo: (texinfo).   With one source file, make either a printed 
        !          1146:                              manual using TeX or an Info file using
        !          1147:                              Texinfo.
        !          1148: 
        !          1149:  To add a new Info file, just add it to this menu.  For example, if
        !          1150: you were adding documentation for GDB, you would make the following
        !          1151: entry:
        !          1152: 
        !          1153:      * GDB: (gdb).           The source-level C debugger.
        !          1154: 
        !          1155:  The first item is the menu item name; it is followed by a colon.  The
        !          1156: second item is the name of the Info file, in parentheses; it is
        !          1157: followed by a period.  The third part of the entry is the description
        !          1158: of the item.
        !          1159: 
        !          1160: The top node of the file, named `top', should have as its parent the
        !          1161: name of a node in another file, where there is a menu that leads to
        !          1162: this file.  Specify the file name in parentheses.  If the file is to
        !          1163: be installed directly in the Info directory file, use `(dir)' as the
        !          1164: parent of the top node; this is short for `(dir)top', the node `top'
        !          1165: in the file `dir', which is the main menu of Info.
        !          1166: 
        !          1167: 
        !          1168: 
        !          1169: File: texinfo,  Node: Catching Mistakes,  Next: Command Syntax,  Prev: Creating an Info File,  Up: Top
        !          1170: 
        !          1171: Catching Mistakes
        !          1172: *****************
        !          1173: 
        !          1174: Besides mistakes with the content of what ever you are describing,
        !          1175: there are two kinds of mistake you can make with Texinfo:  you can
        !          1176: make mistakes with @-commands, and you can make mistakes with the
        !          1177: structure of the nodes and chapters.
        !          1178: 
        !          1179: There are two tools for catching the first kind of mistake and two
        !          1180: for catching the second.
        !          1181: 
        !          1182: For finding problems with @-commands, your best action is to run `M-x
        !          1183: texinfo-format-region' on regions of your file as you write it.  In
        !          1184: Texinfo mode, the `texinfo-format-region' command is bound to `C-c
        !          1185: C-f'.  In addition, you can run TeX on the whole file.
        !          1186: 
        !          1187: For finding problems with the structure of nodes and chapters, you
        !          1188: can use `C-c C-s' (`texinfo-show-structure') (and the related `occur'
        !          1189: command) and you can use the `M-x Info-validate' command.
        !          1190: 
        !          1191: * Menu:
        !          1192: 
        !          1193: * Debugging with Info::            Catching errors with info formatting.
        !          1194: * Debugging with Tex::             Catching errors with TeX formatting.
        !          1195: * Using texinfo-show-structure::    Using `texinfo-show-structure'
        !          1196:                                    to catch mistakes.
        !          1197: * Running Info-Validate::          Checking for unreferenced nodes.
        !          1198: 
        !          1199:  
        !          1200: 
        !          1201: File: texinfo,  Node: Debugging with Info,  Next: Debugging with Tex,  Up: Catching Mistakes
        !          1202: 
        !          1203: Catching Errors with Info Formatting
        !          1204: ====================================
        !          1205: 
        !          1206: After you have written part of a Texinfo file, you can use the `M-x
        !          1207: texinfo-format-region' command to see whether the region formats
        !          1208: properly.  In Texinfo mode, this command is bound to the keyboard
        !          1209: command `C-c C-f'.
        !          1210: 
        !          1211: If you have made a mistake with an @-command, `M-x
        !          1212: texinfo-format-region' will stop processing at or after the error and
        !          1213: give an error message.  To see where in the file the error occurred,
        !          1214: switch to the `*Info Region*' buffer; the cursor will be in a
        !          1215: position that is after the location of the error.  Also, the text
        !          1216: will not be formatted after the place the error occurred.
        !          1217: 
        !          1218: For example, if you accidently end a menu with the command `@end
        !          1219: menus' with an `s' on the end, instead of with `@end menu', you will
        !          1220: get an error message that says:
        !          1221: 
        !          1222:      @end menus is not handled by texinfo.
        !          1223: 
        !          1224:  The cursor will stop at the point in the file where the error occurs,
        !          1225: or not long after it.  It will look like this:
        !          1226: 
        !          1227:      @menu
        !          1228:      * Using texinfo-show-structure::    Using `texinfo-show-structure'
        !          1229:                                          to catch mistakes.
        !          1230:      * Running Info-Validate::           Checking for unreferenced nodes.
        !          1231:      @end menus
        !          1232: 
        !          1233: The `texinfo-format-region' command does not always recognize errors.
        !          1234: For example, no errors were reported when `texinfo-format-region' was
        !          1235: run on the whole itemized list of which the following is a part:
        !          1236: 
        !          1237:      name of the Texinfo file as an extension.  The @samp{??} are `wildcards'
        !          1238:      that cause the shell to substitute all the raw index files.  (@xref{sorting
        !          1239:      indices), for more information about sorting indices.) @refill
        !          1240:      @cindex Sorting indices
        !          1241:      @cindex Indices, sorting
        !          1242:      
        !          1243:      @item 
        !          1244:      @emph{Third}, rerun the @TeX{} command on the Texinfo file.  This
        !          1245:      regenerates a formatted DVI file with the index entries in the correct
        !          1246:      order.  This second run also makes all the cross references and table of
        !          1247:      contents correct as well.
        !          1248: 
        !          1249:  Instead, `texinfo-format-region' ran without reporting the error, but
        !          1250: it produced output that looked like this:
        !          1251: 
        !          1252:           name of the texinfo file as an extension.  The `??' are `wildcards'
        !          1253:           that cause the shell to substitute all the raw index files.  (*Note for more information about sorting indices.) @refill @cindex Sorting indices @cindex Indices: sorting indices), rerun the TeX command on the texinfo file.  This
        !          1254:           regenerates a formatted DVI file with the index entries in the correct
        !          1255:           order.  This second run also makes all the cross references and table of
        !          1256:           contents correct as well.
        !          1257: 
        !          1258:  However, when `texinfo-format-region' was run on part of the list
        !          1259: that is shown, it did give an error message, `Search failed: "[{,}"'.
        !          1260: (This error message is explained in the section on using the Emacs
        !          1261: Lisp Debugger, *note Using the Emacs Lisp Debugger::.)
        !          1262: 
        !          1263: Sometimes `texinfo-format-region' will stop long after the original
        !          1264: error;  this is because it does not discover the problem until then. 
        !          1265: In this case, you will have to backtrack.
        !          1266: 
        !          1267: 
        !          1268: 
        !          1269: File: texinfo,  Node: Using the Emacs Lisp Debugger,  Up: Debugging with Info
        !          1270: 
        !          1271: Using the Emacs Lisp Debugger
        !          1272: -----------------------------
        !          1273: 
        !          1274: If an error is especially elusive, you can turn on the Emacs Lisp
        !          1275: debugger and look at the backtrace; this tells you where in the
        !          1276: `texinfo-format-region' function the problem occurred.  You can turn
        !          1277: on the debugger with the command:
        !          1278: 
        !          1279:      M-x set-variable RET debug-on-error RET t
        !          1280: 
        !          1281: and turn it off with
        !          1282: 
        !          1283:      M-x set-variable RET debug-on-error RET nil
        !          1284: 
        !          1285: Often, when you are using the debugger, it is easier to follow what
        !          1286: is going on if you use the Emacs Lisp files that are not
        !          1287: byte-compiled.  The byte-compiled sources send octal numbers to the
        !          1288: debugger that may look mysterious.  To use the uncompiled source
        !          1289: files, load `texinfmt.el' and `texinfo.el' with the `M-x load-file'
        !          1290: command.
        !          1291: 
        !          1292: The debugger will not catch an error if `texinfo-format-region' does
        !          1293: not detect one.  In the example shown above, `texinfo-format-region'
        !          1294: did not find the error when the whole list was formatted, but only
        !          1295: when part of the list was formatted.  When `texinfo-format-region'
        !          1296: did not find an error, the debugger did not find one either.
        !          1297: 
        !          1298: However, when `texinfo-format-region' did report an error, it invoked
        !          1299: the debugger.  This is the backtrace it produced:
        !          1300: 
        !          1301:      Signalling: (search-failed "[},]")
        !          1302:        re-search-forward("[},]")
        !          1303:        (while ...)
        !          1304:        (let ...)
        !          1305:        texinfo-format-parse-args()
        !          1306:        (let ...)
        !          1307:        texinfo-format-xref()
        !          1308:        funcall(texinfo-format-xref)
        !          1309:        (if ...)
        !          1310:        (let ...)
        !          1311:        (if ...)
        !          1312:        (while ...)
        !          1313:        texinfo-format-scan()
        !          1314:        (save-excursion ...)
        !          1315:        (let ...)
        !          1316:        texinfo-format-region(103370 103631)
        !          1317:      * call-interactively(texinfo-format-region)
        !          1318: 
        !          1319: The backtrace is read from the bottom up.  `texinfo-format-region'
        !          1320: was called interactively; and it, in turn, called various functions,
        !          1321: including `texinfo-format-scan', `texinfo-format-xref' and
        !          1322: `texinfo-format-parse-args'.  Inside the function
        !          1323: `texinfo-format-parse-args', the function `re-search-forward' was
        !          1324: called; it was this function that could not find the missing right
        !          1325: hand brace.
        !          1326: 
        !          1327: *Note : (emacs)Lisp Debug, for more information.
        !          1328: 
        !          1329: 
        !          1330: 
        !          1331: File: texinfo,  Node: Debugging with Tex,  Next: Using texinfo-show-structure,  Prev: Debugging with Info,  Up: Catching Mistakes
        !          1332: 
        !          1333: Catching Errors with TeX Formatting
        !          1334: ===================================
        !          1335: 
        !          1336: You can also catch mistakes when you format a file with TeX.
        !          1337: 
        !          1338: Usually, you will want to do this after you have run
        !          1339: `texinfo-format-buffer' on the same file.  `texinfo-format-buffer' is
        !          1340: usually faster and sometimes gives error messages that make more
        !          1341: sense.  *Note Debugging with Info::, for more information.
        !          1342: 
        !          1343: For example, TeX was run on the same itemized list discussed in the
        !          1344: section on the use of  `texinfo-format-region' (*note Debugging with
        !          1345: Info::.); the fragment with the error looked like this:
        !          1346: 
        !          1347:      name of the texinfo file as an extension.  The @samp{??} are `wildcards'
        !          1348:      that cause the shell to substitute all the raw index files.  (@xref{sorting
        !          1349:      indices, for more information about sorting indices.) @refill
        !          1350: 
        !          1351: This produced the following output, after which TeX stopped:
        !          1352: 
        !          1353:      Runaway argument?
        !          1354:      {sorting indices, for more information about sorting indices.) @refill @ETC.
        !          1355:      ! Paragraph ended before \xref was complete.
        !          1356:      <to be read again> 
        !          1357:                         \par 
        !          1358:      l.27 
        !          1359:           
        !          1360:      ?
        !          1361: 
        !          1362: In this case, TeX produced an accurate and understandable error
        !          1363: message: `Paragraph ended before \xref was complete.' (Note, however,
        !          1364: that TeX translated the `@' into a `\'.)  Also, `\par' is an internal
        !          1365: TeX command of no relevance to Texinfo.)
        !          1366: 
        !          1367: Unfortunately, TeX is not always so helpful, and sometimes you have
        !          1368: to be truly a Sherlock Holmes to discover what went wrong.
        !          1369: 
        !          1370: In any case, if you run into a problem like this, you can do one of
        !          1371: two things.
        !          1372: 
        !          1373:   1. You can tell TeX to continue running and to ignore errors  as
        !          1374:      best it can by typing `r RET' at the  `?' prompt.
        !          1375: 
        !          1376:      This is often the best thing to do.  However, beware: the one
        !          1377:      error may produce a cascade of additional error messages as it
        !          1378:      consequences are felt through the rest of the file.
        !          1379: 
        !          1380:   2. You can tell TeX to stop this run by typing `x RET'  at the `?'
        !          1381:      prompt.
        !          1382: 
        !          1383: Sometimes TeX will format a file without producing error messages
        !          1384: even though there is a problem.  This usually occurs if a command is
        !          1385: not ended but TeX is able to continue processing anyhow.  For
        !          1386: example, if you fail to end an itemized list with the `@end itemize'
        !          1387: command, TeX will write a DVI file that you can print out.  The only
        !          1388: error message that TeX will give you is the somewhat mysterious
        !          1389: comment that
        !          1390: 
        !          1391:      (\end occurred inside a group at level 1)
        !          1392: 
        !          1393: However, if you print the DVI file, you will find that the text of
        !          1394: the file that follows the itemized list is entirely indented as if it
        !          1395: were part of the last item in the itemized list.  The error message
        !          1396: is the way TeX says that it expected to find an `@end' command
        !          1397: somewhere in the file; but that it could not locate where it was
        !          1398: needed.
        !          1399: 
        !          1400: Another source of notoriously hard to find errors is a missing `@end
        !          1401: group' command.  If you ever are stumped by incomprehensible errors,
        !          1402: look for a missing `@end group' command first.
        !          1403: 
        !          1404: If you do not have the header lines in the file, TeX may stop in the
        !          1405: beginning of its run and display output that looks like the following.
        !          1406: The `*' indicates that TeX is waiting for input.
        !          1407: 
        !          1408:      This is TeX, Version 2.0 for Berkeley UNIX (preloaded format=plain-cm 
        !          1409:      87.10.25) (#tz-bar-a02987.tex [1])
        !          1410:      *
        !          1411: 
        !          1412: In this case, simply type `\end RET' after the asterisk.  Then put
        !          1413: the header lines into the Texinfo file and run the TeX command again.
        !          1414: 
        !          1415: 

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