Return to texinfo-3 CVS log

Up to [Apple XNU] / GNUtools / emacs / info

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

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