+Info file ../info/texinfo, produced by Makeinfo, -*- Text -*- from
+input file texinfo.texinfo.
+
+This file documents Texinfo, a documentation system that uses a
+single source file to produce both on-line help and a printed manual.
+
+This is edition 1.1 of the Texinfo documentation, and is for the
+Texinfo that is distributed as part of Version 18 of GNU Emacs.
+
+Copyright (C) 1988 Free Software Foundation, Inc.
+
+Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that
+the entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+
+\1f
+File: texinfo, Node: Breaks Blank-Lines Groups, Prev: Refilling & Noindent, Up: Formatting Paragraphs
+
+Breaks, Blank Lines and Groups
+==============================
+
+Texinfo has several commands for making blank lines, for forcing
+paragraph and page breaks in the printed manual and for preventing
+text from running from one page to the next.
+
+`@*'
+ Force a line break in the printed manual. This command has no
+ effect on the Info file.
+
+`@sp'
+ Generate blank lines in both the printed manual and in the Info
+ file.
+
+`@br'
+ Force a paragraph break in the printed manual. This command has
+ no effect on the Info file.
+
+`@w'
+ Prevent text from being split across two lines in the printed
+ manual. This command has no effect on the Info file.
+
+`@page'
+ Start a new page in the printed manual. This command has no
+ effect on the Info file.
+
+`@group'
+ Hold text together that must appear on one printed page. This
+ command has no effect on the Info file.
+
+`@need'
+ Start a new printed page if required space not on this one.
+ This command has no effect on the Info file.
+
+* Menu:
+
+* Line Breaks:: Force a line break in the printed manual.
+* Sp:: Generate blank lines.
+* Br:: Force a paragraph break in the printed manual.
+* W:: Prevent a paragraph break in the printed manual.
+* Page:: Start a new page in the printed manual.
+* Group:: Hold text together that must appear on one printed page.
+* Need:: Start a new printed page if required space not on this one.
+
+
+\1f
+File: texinfo, Node: Line Breaks, Next: Sp, Prev: Breaks Blank-Lines Groups, Up: Breaks Blank-Lines Groups
+
+@*
+--
+
+`@*' forces a line break in the printed manual. It has no effect on
+the Info file output, where line breaks follow those in the source
+file. If you want a line break at a certain spot in both forms of
+output, break the line there in the source file and put `@*' at the
+end of the line.
+
+
+\1f
+File: texinfo, Node: Sp, Next: Br, Prev: Line Breaks, Up: Breaks Blank-Lines Groups
+
+@sp
+---
+
+A line containing `@sp N' generates N blank lines of space in either
+the printed manual or the Info file. For example,
+
+ @sp 2
+
+generates two blank lines.
+
+
+\1f
+File: texinfo, Node: Br, Next: W, Prev: Sp, Up: Breaks Blank-Lines Groups
+
+@br
+---
+
+In a printed manual, a line containing `@br' forces a paragraph
+break; in the Info file output, it does nothing (not even a blank
+line results from it).
+
+
+\1f
+File: texinfo, Node: W, Next: Page, Prev: Br, Up: Breaks Blank-Lines Groups
+
+@w
+--
+
+In a printed manual, `@w{TEXT}' outputs TEXT and prohibits line
+breaks within TEXT. `@w' has no effect on the Info file output; it
+is the same as would result from just TEXT.
+
+
+\1f
+File: texinfo, Node: Page, Next: Group, Prev: W, Up: Breaks Blank-Lines Groups
+
+@page
+-----
+
+A line containing `@page' starts a new page in a printed manual. The
+line has no effect on Info files since they are not paginated.
+
+
+\1f
+File: texinfo, Node: Group, Next: Need, Prev: Page, Up: Breaks Blank-Lines Groups
+
+@group
+------
+
+A line containing `@group' begins an unsplittable vertical group,
+which must appear entirely on one page. The group is terminated by a
+line containing `@end group'. These two lines produce no output of
+their own, and in the Info file output they have no effect at all.
+
+If you forget to end a group, you may get strange and unfathomable
+error messages when you run TeX. This is because TeX keeps trying to
+put the rest of the Texinfo file into the group and error messages do
+not start to get generated until TeX has gone a long way. It's a
+good rule of thumb to look for a missing `@end group' if you get
+incomprehensible error messages in TeX.
+
+
+\1f
+File: texinfo, Node: Need, Prev: Group, Up: Breaks Blank-Lines Groups
+
+@need
+-----
+
+A line containing `@need N' starts a new page in a printed manual if
+fewer than N mils (thousandths of an inch) remain on the current
+page. The line has no effect on Info files since they are not
+paginated.
+
+
+\1f
+File: texinfo, Node: Marking Text, Next: Conditionals, Prev: Formatting Paragraphs, Up: Top
+
+Marking Text Within a Paragraph
+*******************************
+
+In Texinfo, text within a paragraph can be marked in a variety of ways.
+The most important way is to specify whether a word or phrase is a
+definition, a metasyntactic variable, a literal example of a program
+or what not.
+
+In addition, there are special commands for inserting single
+characters that have special meaning in Texinfo, such as braces, and
+for inserting symbols with special handling, such as dots and
+bullets. Finally, there are ways to emphasize words.
+
+* Menu:
+
+* Specifying:: Specifying commands, files and so on.
+* Braces Atsigns Periods:: Inserting braces, `@' and periods.
+* Dots Bullets Tex:: Inserting dots, bullets and the TeX logo
+* Emphasis:: Emphasizing text.
+
+
+\1f
+File: texinfo, Node: Specifying, Next: Braces Atsigns Periods, Up: Marking Text
+
+Specifying Definitions, Files, Commands etc.
+============================================
+
+Texinfo has a variety of commands for specifying just what kind of
+object a piece of text refers to. Metasyntactic variables, for
+example, are marked by one @-command and code by another. Texinfo
+uses this information to determine how to highlight the text. Since
+the pieces of text are labelled by commands that tell what kind of
+object they are, it is easy to change the way Texinfo formats and
+typesets such text. For example, code is usually illustrated in a
+typewriter font, but it would be easy to change the way Texinfo
+highlights code to use another font. This change would not effect
+how metasyntatic variables are highlighted. If straight typesetting
+commands were used in the body of the file, you would have to check
+every single occurrence to make sure that you were changing code and
+not something else that should not be changed.
+
+In addition, the commands can be used to generate useful information
+from the file, such as lists of functions or file names. It is
+possible, for example, to write code in Emacs Lisp (or a keyboard
+macro) to insert an index entry after every paragraph that contains
+the text labelled by a specified command. You could do this to
+construct an index of functions if you had not already made the
+entries.
+
+The commands serve a variety of purposes:
+
+`@code'
+ Indicates text that is a literal example of a piece of a program.
+
+`@samp'
+ Indicates text that is a literal example of a sequence of
+ characters.
+
+`@file'
+ Indicates the name of a file.
+
+`@kbd'
+ Indicates the names of keys on the keyboard or characters you
+ type.
+
+`@key'
+ Used for the conventional name for a key on a keyboard.
+
+`@ctrl'
+ Indicates an ASCII control character.
+
+`@var'
+ Indicates a metasyntactic variable.
+
+`@dfn'
+ Indicates the introductory or defining use of a term.
+
+`@cite'
+ Indicates the name of a book.
+
+* Menu:
+
+* Code:: A literal example of a piece of a program.
+* Samp:: A literal example of a sequence of characters.
+* File:: The name of a file.
+* Kbd:: The names of keys or else characters you type.
+* Key:: The conventional name for a key on a keyboard.
+* Ctrl:: Indicates the ASCII control character.
+* Var:: A variable.
+* Dfn:: The introductory or defining use of a term.
+* Cite:: The name of a book.
+
+
+\1f
+File: texinfo, Node: Code, Next: Samp, Up: Specifying
+
+@code
+-----
+
+`@code' is used to indicate text that is a piece of a program which
+consists of entire syntactic tokens. The text follows, enclosed in
+braces.
+
+For example, `@code' is used for an expression in a program, the name
+of a variable or function used in a program, or a keyword. `@code'
+is not used for a piece of a token, such as when speaking about the
+characters used in a token; for example, when you are explaining what
+letters or printable symbols can be used in the names of functions.
+It is also not used for input to programs unless the input is written
+in a language that is like a programming language. For example, it
+is not used for the single character commands of GNU Emacs although
+it is used for the names of Emacs Lisp functions that the keyboard
+commands invoke.
+
+You should also `@code' for command names in command languages that
+resemble programming languages, such as Texinfo or the shell. Note,
+however, that `@code' is not used for options such as `-c' when such
+options stand alone. There is some argument as to whether an entire
+shell command incorporating an option should be written using `@code'
+or `@samp'.
+
+It is an error to alter the case of a word inside an `@code' command.
+This is a particularly insidious error if the language being
+documented is case sensitive. If the command is `printf', then
+`Printf' is a misspelling. If you do not like having such a command
+with lower case at the beginning of a sentence, you may wish to
+rearrange the sentence.
+
+In the printed manual, `@code' puts the argument in bold face. In
+the Info file, it uses `...' quotation. For example:
+
+ To compare two files, showing text inserted or removed, use @code{diff}.
+
+ produces
+
+ To compare two files, showing text inserted or removed, use
+ `diff'.
+
+
+\1f
+File: texinfo, Node: Samp, Next: File, Prev: Code, Up: Specifying
+
+@samp
+-----
+
+`@samp' is used to indicate text that is a literal example of a
+sequence of characters in a file, string, pattern, etc. The text
+follows, enclosed in braces. The argument appears within `...'
+quotation in both the Info file and the printed manual; in addition,
+it is printed in a fixed-width font.
+
+ To match @samp{foo} at the end of the line, use the regexp @samp{foo$}.
+
+ produces
+
+ To match `foo' at the end of the line, use the regexp `foo$'.
+
+Any time you are referring to single characters, you should use
+`@samp' unless `@kbd' is more appropriate. Basically, `@samp' is a
+catchall for whatever is not covered by `@code', `@file', `@kbd'.
+
+Punctuation marks that are part of the English text that surrounds
+the strings you are specifying are *never* included within the
+braces. In the following sentence, for example, the commas and
+period are outside of the braces:
+
+ A symbol name ends in @samp{a}, @samp{b}, or @samp{c}.
+
+
+\1f
+File: texinfo, Node: File, Next: Kbd, Prev: Samp, Up: Specifying
+
+@file
+-----
+
+`@file' is used to indicate text that is the name of a file or
+directory. Currently, it is equivalent to `@samp' in its effects on
+the output. For example,
+
+ The @file{.el} files are in
+ the @file{/gnu/emacs/lisp} directory.
+
+ produces
+
+ The `.el' files are in the `/gnu/emacs/lisp' directory.
+
+
+\1f
+File: texinfo, Node: Kbd, Next: Key, Prev: File, Up: Specifying
+
+@kbd
+----
+
+`@kbd' is used much like `@code'. The difference is that `@kbd' is
+for names of keys on the keyboard, or of characters you can type.
+For example, to refer to the command `M-a', you would use
+
+ @kbd{M-a}
+
+and to refer to `M-x shell', you would use
+
+ @kbd{M-x shell}
+
+The `@kbd' command has the same effect as `@code' in Info, but may
+produce a different font in a printed manual.
+
+You can embed another @-command inside the braces of a `@kbd'
+command. This is the way to describe a command that would be
+described more verbosely as "press an `r' and then press the RET key":
+
+ @kbd{r @key{RET}}
+
+This produces: `r RET'
+
+You also use the `@kbd' command if you are spelling out the letters
+you type; for example:
+
+ To give the @code{logout} command,
+ type the characters @kbd{l o g o u t @key{RET}}.
+
+ This produces
+
+ To give the `logout' command, type the characters `l o g o u t
+ RET'.
+
+
+\1f
+File: texinfo, Node: Key, Next: Ctrl, Prev: Kbd, Up: Specifying
+
+@key
+----
+
+`@key' is used for the conventional name for a key on a keyboard, as in
+
+ @key{RET}
+
+Often, `@key' is used within the argument of a `@kbd' command,
+whenever the sequence of characters to be typed includes one or more
+keys that are described by name.
+
+For example, to produce `C-x ESC' you would use
+
+ @kbd{C-x @key{ESC}}
+
+The recommended names to use for keys are in upper case and are
+
+SPC
+ Space.
+
+RET
+ Return.
+
+LFD
+ Linefeed.
+
+TAB
+ Tab.
+
+BS
+ Backspace.
+
+ESC
+ Escape.
+
+DEL
+ Delete.
+
+SFT
+ Shift.
+
+CTL
+ Control.
+
+META
+ Meta.
+
+There are subtleties to handling words like `meta' or `ctrl' which
+are names of shift keys. When mentioning a character in which the
+shift key is used, such as `Meta-a', use the `@kbd' command alone
+without the `@key' command, but when you are referring to shift key
+in isolation, use the `@key' command. For example, you would use
+`@kbd{Meta-a}' to produce `Meta-a' and `@key{META}' to produce META.
+
+
+\1f
+File: texinfo, Node: Ctrl, Next: Var, Prev: Key, Up: Specifying
+
+@ctrl
+-----
+
+`@ctrl' is used to describe an ASCII control character. The pattern
+of usage is `@ctrl{CH}', where CH is an ASCII character whose
+control-equivalent is wanted. Thus, you put in an `f' when you want
+to indicate a `control-f'
+
+Thus, to specify `control-f', you would enter
+
+ @ctrl{f}
+
+which produces
+
+ f
+
+In the Info file, this generates the specified control character,
+output literally into the file. This is done so a user can copy the
+specified control character (along with whatever else he or she
+wants) into another Emacs buffer and use it. Since the
+`control-h',`control-i', and `control-j' characters are formatting
+characters, they should not be indicated this way.
+
+In a printed manual, this generates text to describe or identify that
+control character: an uparrow followed by the character CH.
+
+
+\1f
+File: texinfo, Node: Var, Next: Dfn, Prev: Ctrl, Up: Specifying
+
+@var
+----
+
+`@var' is used to indicate metasyntactic variables. A metasyntactic
+variable is something that stands for another piece of text. You
+would use a metasyntactic variable in the documentation of a function
+to describe the arguments that are passed to that function.
+
+`@var' is not used for names of particular variables in programming
+languages. For example, the Texinfo variable `texinfo-tex-command'
+is not a metasyntactic variable.
+
+Its effect in the Info file is to upcase the argument; in the printed
+manual, to italicize it. Example:
+
+ To delete file @var{filename}, type @code{rm @var{filename}}.
+
+ produces
+
+ To delete file FILENAME, type `rm FILENAME'.
+
+In some documentation styles, metasyntactic variables are shown with
+angle brackets, for example:
+
+ ..., type rm <filename>
+
+
+\1f
+File: texinfo, Node: Dfn, Next: Cite, Prev: Var, Up: Specifying
+
+@dfn
+----
+
+`@dfn' is used to identify the introductory or defining use of a
+technical term. The command should be used only in a passage whose
+purpose is to introduce a term which will be used again or which the
+reader ought to know. Mere passing mention of a term for the first
+time doesn't deserve `@dfn'. It generates italics in the printed
+manual, and double quotation marks in the Info file. Example:
+
+ Getting rid of a file is called @dfn{deleting} it.
+
+ produces
+
+ Getting rid of a file is called "deleting" it.
+
+
+\1f
+File: texinfo, Node: Cite, Prev: Dfn, Up: Specifying
+
+@cite
+-----
+
+`@cite' is used for the name of a book. It produces italics in the
+printed manual, and quotation marks in the Info file.
+
+
+\1f
+File: texinfo, Node: Braces Atsigns Periods, Next: Dots Bullets Tex, Prev: Specifying, Up: Marking Text
+
+Inserting Braces, `@' and Periods
+=================================
+
+`@' and curly braces are special characters in Texinfo. This means
+that you have to put an `@' in front of these characters in order to
+insert them into text.
+
+Periods are also special. Depending on whether the period is inside
+of or at the end of a sentence, less or more space is inserted after
+a period in a typeset manual. Since it is not always possible for
+Texinfo to determine when a period ends a sentence and when it is
+used in an abbreviation, special commands are needed. (Usually,
+Texinfo figures out how to handle periods, so you don't have to use
+the special commands; you just enter a period as you would if you
+were using a typewriter, which means you put two spaces after the
+period that ends a sentence and after a colon.)
+
+* Menu:
+
+* Inserting an Atsign:: inserting an atsign.
+* Insert Left Brace:: Inserting a left brace.
+* Insert Colon:: Preventing unintended additional whitespace.
+* Insert Period:: Inserting a period that does end a sentence.
+
+
+\1f
+File: texinfo, Node: Inserting An Atsign, Next: Insert Left Brace, Up: Braces Atsigns Periods
+
+@@
+--
+
+`@@' stands for a single @ in either printed or Info output.
+
+
+\1f
+File: texinfo, Node: Insert Left Brace, Next: Insert Colon, Prev: Inserting an Atsign, Up: Braces Atsigns Periods
+
+@{
+--
+
+`@{' stands for a single { in either printed or Info output.
+
+@}
+--
+
+`@}' stands for a single } in either printed or Info output.
+
+
+\1f
+File: texinfo, Node: Insert Colon, Next: Insert Period, Prev: Insert Left Brace, Up: Braces Atsigns Periods
+
+@:
+--
+
+`@:' is used after a character such as period or colon which normally
+causes TeX to increase the width of the following whitespace, to
+suppress that effect. For example, it can be used after periods that
+end abbreviations and do not end sentences. `@:' has no effect on
+the Info file output.
+
+ It displays @code{Foo:}@: at that time.
+
+ produces
+
+ It displays `Foo:' at that time.
+
+The meanings of `@:' and `@.' in Texinfo are designed to work well
+with the Emacs sentence motion commands. This means they are
+different from their meanings in some other formatting systems that
+use @-commands.
+
+
+\1f
+File: texinfo, Node: Insert Period, Prev: Insert Colon, Up: Braces Atsigns Periods
+
+@.
+--
+
+`@.' stands for a period that really does end a sentence, useful when
+TeX would otherwise assume by its heuristics that that is not so.
+This happens when there is a single-capital-letter word at the end of
+a sentence: TeX normally guesses that it is an abbreviation.
+
+In the Info file output, `@.' is equivalent to a simple `.'. The
+Texinfo program preserves the amount of space that you use, so put
+two spaces after a period if you intend it to be the end of a
+sentence (as well as using `@.', if necessary, for the printed
+manual's sake).
+
+ Give it to X. Give it to X@. Give it to X@.
+
+ produces
+
+ Give it to X. Give it to X. Give it to X.
+
+
+\1f
+File: texinfo, Node: Dots Bullets Tex, Next: Emphasis, Prev: Braces Atsigns Periods, Up: Marking Text
+
+Inserting Dots, Bullets and TeX
+===============================
+
+An ellipsis, a line of dots, is typeset differently than a string of
+periods; more whitespace is put between the dots in the ellipsis than
+is put between the periods. Because of this, a special command is
+used in Texinfo for inserting dots. Also, the trademark, TeX, is
+typeset in a special fashion and it needs an @-command, as does the
+command for inserting the copyright symbol. The `@bullet' command is
+special, too. Each of these commands is followed by a pair of
+braces, `{}', without any whitespace between the name of the command
+and the braces.
+
+* Menu:
+
+* Dots:: Inserting dots.
+* Bullet:: Inserting bullets.
+* Tex:: Inserting the TeX trademark.
+
+
+\1f
+File: texinfo, Node: Dots, Next: Bullet, Up: Dots Bullets Tex
+
+@dots{}
+-------
+
+`@dots{}' generates an ellipsis which is three dots in a row,
+appropriately spaced, like this: `...'. Do not simply write three
+periods in the input file; that would work for the Info file output,
+but would produce the wrong amount of space between the periods in
+the printed manual.
+
+
+\1f
+File: texinfo, Node: Bullet, Next: Tex, Prev: Dots, Up: Dots Bullets Tex
+
+@bullet{}
+---------
+
+`@bullet{}' generates a large round dot, or the closest possible
+thing to one.
+
+Here is a bullet: *
+
+
+\1f
+File: texinfo, Node: Tex, Prev: Bullet, Up: Dots Bullets Tex
+
+@TeX{}
+------
+
+`@TeX{}' generates `TeX'. In a printed manual, this is a special
+logo that is different from three ordinary letters.
+
+
+\1f
+File: texinfo, Node: Emphasis, Prev: Dots Bullets Tex, Up: Marking Text
+
+Emphasizing Text
+================
+
+Usually, Texinfo changes the font automatically to mark words in the
+text according to what category the words belong to. The `@code'
+command, for example, does this. Most often, this is the best way to
+mark specified words. However, sometimes you will want to emphasize
+text directly. Texinfo has two ways to do this: commands that tell
+Texinfo to emphasize the text but leave the method to the program,
+and commands that specify the font to use. The first method is
+generally the best and it makes it possible to change the style of a
+document without have to re-edit it line by line.
+
+* Menu:
+
+* Emph and Strong:: Emphasizing text.
+* Fonts:: Selecting italic, bold or typewriter fonts.
+
+
+\1f
+File: texinfo, Node: Emph and Strong, Next: Fonts, Up: Emphasis
+
+@emph and @strong
+-----------------
+
+`@emph' and `@strong' are two forms of emphasis. `@strong' is
+stronger.
+
+In printed output, `@emph' produces *italics* and `@strong' produces
+*bold*.
+
+In the Info file, both of these commands put asterisks around the
+argument.
+
+
+\1f
+File: texinfo, Node: Fonts, Prev: Emph and Strong, Up: Emphasis
+
+@i, @b and @t
+--------------
+
+These three commands specify font changes in the printed manual and
+have no effect in the Info file. `@i' requests italic font (in some
+versions of TeX, a slanted font is used), `@b' requests bold face,
+and `@t' requests the fixed-width font used by `@kbd'. All three
+commands apply to an argument that follows, surrounded by braces.
+
+If possible, you should avoid using these three commands. If you
+find a need to use one, it probably indicates a lack in the Texinfo
+language.
+
+
+\1f
+File: texinfo, Node: Conditionals, Next: Printing Hardcopy, Prev: Marking Text, Up: Top
+
+Conditionals
+************
+
+You may not always be able to use the same text for both the printed
+manual and the on-line Info file. In this case, you can use the
+conditional commands to specify which text is for the printed manual
+and which is for the Info file.
+
+`@ifinfo' begins text that should be ignored by TeX when it typesets
+the printed manual. The text appears only in the Info file. The
+`@ifinfo' command should appear on a line by itself. End the
+info-only text with a line containing `@end ifinfo' by itself. At
+the beginning of a Texinfo file, the Info permissions are contained
+within a region marked by `@ifinfo' and `@end ifinfo'.
+
+Likewise, `@iftex' and `@end iftex' lines delimit text that will not
+appear in the Info file but will appear in the printed manual.
+
+For example,
+
+ @iftex
+ This text will appear only in the printed manual.
+ @end iftex
+
+
+ @ifinfo
+ However, this text will appear only in the info manual.
+ @end ifinfo
+
+The preceding example produces the following. Note how you only see
+one of the two lines, depending on whether you are reading the
+on-line Info version or the printed version of this manual.
+
+However, this text will appear only in the info manual.
+
+The `@titlepage' command is a special variant of `@iftex' that is
+used for making the title and copyright pages of the printed manual.
+
+* Menu:
+
+* Using Tex Commands:: Using commands from regular TeX.
+
+
+\1f
+File: texinfo, Node: Using Tex Commands, Prev: Conditionals, Up: Conditionals
+
+Using TeX Commands
+==================
+
+Inside a region delineated by `@iftex' and `@end iftex', you can
+embed ordinary TeX commands. Info will ignore these commands since
+they are only in that part of the file that is seen by TeX. The TeX
+commands are the same as any TeX commands except that an `@' replaces
+the `\' used by TeX. For example, in the `@titlepage' section of a
+Texinfo file, the TeX command `@vskip' is used to format the
+copyright page.
+
+You can enter TeX completely, and use `\' in the TeX commands by
+delineating a region with the `@tex' and `@end tex' commands. (These
+commands automatically put the region inside of `@iftex' and `@end
+iftex' commands.) For example,
+
+ @tex
+ Here you would put text with TeX commands;
+ such as $\bigl(x\in A(n)\bigm|x\in B(n)\bigr)$
+ that will appear only in the printed manual.
+ @end tex
+
+In the Info file, nothing between `@tex' and `@end tex' will appear.
+
+
+\1f
+File: texinfo, Node: Printing Hardcopy, Next: Creating an Info File, Prev: Conditionals, Up: Top
+
+Printing Hardcopy
+*****************
+
+There are three shell commands for printing a hardcopy of a Texinfo
+file. One is for formatting the file, the second is for sorting the
+index and the third is for printing the formatted document. When you
+use the shell commands, you can either work directly in the operating
+system shell or work within a shell inside of GNU Emacs.
+
+The typesetting program TeX is used for formatting a Texinfo file.
+TeX is a very powerful typesetting program and, if used right, does
+an exceptionally good job. The @-commands in a Texinfo file are
+translated by a file called `texinfo.tex' into commands that TeX
+understands. (That is why the beginning of every Texinfo file starts
+with the line that says `\input texinfo'; this command tells TeX to
+use the `texinfo.tex' file in processing the Texinfo file.
+Customarily, `texinfo.tex' is in a directory called
+`/usr/lib/tex/macros'.) `texinfo-format-buffer' reads the very same
+@-commands in the Texinfo file and processes them differently from
+TeX to make an Info file.
+
+Usually, the TeX formatting command is the shell command `tex'
+followed by the name of the Texinfo file. The TeX command produces a
+formatted DVI file as well as several auxiliary files containing
+indices, cross references, etc. The DVI file (for "DeVice
+Independent" file) can be printed on a wide variety of printers.
+
+The TeX formatting command itself does not sort the indices. This is
+a misfeature of TeX. Hence, to generate a printed index, you first
+need a sorted index to work from.
+
+TeX outputs raw, unsorted index files under names that obey a
+standard convention. These names are the name of your main input
+file to TeX, with everything after the first period thrown away, and
+the two letter names of indices added at the end. For example, the
+raw index output files for the input file `foo.texinfo' would be
+`foo.cp', `foo.vr', `foo.fn', `foo.tp', `foo.pg' and `foo.ky'. Those
+are exactly the arguments to give to `texindex'. Or else, you can
+use `??' as "wild-cards" and give the command in this form:
+
+ texindex foo.??
+
+ For each file specified, `texindex' generates a sorted index file
+whose name is made by appending `s' to the input file name. The
+`@printindex' command knows to look for a file of that name.
+`texindex' does not alter the raw index output file. After you have
+sorted the indices, you need to rerun the TeX command on the Texinfo
+file. This regenerates a formatted DVI file with the index entries
+in the correct order.
+
+To summarize, this is a three step process:
+
+ 1. Run the TeX command on the Texinfo file. This generates the
+ formatted DVI file as well as the raw index files with two
+ letter extensions.
+
+ 2. Run the shell command `texindex' on the raw index files to sort
+ them. The arguments to `texindex' are the names of the raw
+ index files. `texindex' creates sorted index files whose names
+ are the names of the raw index files with an `s' appended. To
+ cause `texindex' to sort all the raw index files, append `??' to
+ the Texinfo file name in place of the `.texinfo' extension.
+
+ 3. Rerun the TeX command on the Texinfo file. This regenerates a
+ formatted DVI file with the index entries in the correct order.
+ This second run also makes all the cross references correct as
+ well. (The tables of contents are always correct.)
+
+You need not run `texindex' after each TeX run. If you don't, the
+next TeX run will use whatever sorted index files happen to exist
+from the previous use of `texindex'. This is usually ok while you
+are debugging.
+
+Finally, the document can be printed out with the DVI print command
+(a shell command). Depending on the system used, the DVI print
+command will be a command such as `lpr -d'. The DVI print command
+may require a file name without any extension or with a `.dvi'
+extension.
+
+The following commands, for example, sort the indices, format and
+print the ``Bison Manual'' (where `%' is the shell prompt):
+
+ % tex bison.texinfo
+ % texindex bison.??
+ % tex bison.texinfo
+ % lpr -d bison.dvi
+
+(Remember that the words for the shell commands may be different at
+your site; but these are commonly used versions.)
+
+It is often most convenient to give formatting and printing commands
+from a shell within GNU Emacs. This way, you can easily keep track
+of errors. To create a shell within Emacs, type `M-x shell'. In
+this shell, you can format and print the document. You can switch to
+and from this shell while it is running and do other things. If you
+are formatting a very long document on a slow machine, this can be
+very convenient; on a VAX 750, for example, formatting often takes 8
+seconds or more per page depending on how loaded the computer is.
+Faster machines take correspondingly less time.
+
+* Menu:
+
+* Requirements:: Formatting requirements.
+* Compile-Command:: Formatting with the compile command.
+
+
+\1f
+File: texinfo, Node: Requirements, Next: Compile-Command, Up: Printing Hardcopy
+
+Formatting Requirements
+=======================
+
+Every Texinfo file that is to be input to TeX must begin with a line
+that looks like
+
+ \input texinfo @c -*-texinfo-*-
+
+This serves two functions.
+
+ 1. When the file is processed by TeX, it loads the macros needed
+ for processing a Texinfo file.
+
+ 2. When the file is edited in Emacs, it causes Texinfo mode to be
+ used.
+
+Every Texinfo file must end with a line saying
+
+ @bye
+
+which terminates TeX processing and forces out unfinished pages.
+
+You also have to include two lines that specify the Info file name
+and the title of the printed manual:
+
+ @setfilename NAME-OF-TEXINFO-FILE
+ @settitle NAME OF MANUAL
+
+You might also want to include a line saying
+
+ @setchapternewpage odd
+
+to cause each chapter to start on a fresh odd-numbered page.
+
+By default, TeX typesets pages for printing in an 8.5 by 11 inch
+format. However, you can direct TeX to typeset a document in a 7 by
+9.25 inch format that is suitable for bound books by inserting the
+following command on a line by itself at the beginning of the Texinfo
+file, before the `@setchapternewpage' command:
+
+ @smallbook
+
+The Free Software Foundation distributes printed copies of the ``GNU
+Emacs Manual'' in this size.
+
+Finally, TeX sometimes is unable to typeset a line without extending
+it into the right margin. This can occur when TeX comes upon what it
+interprets as a long word that it cannot hyphenate, like a net
+address, or a very long title. When this happens, TeX prints an
+error message like this:
+
+ Overfull \hbox (20.76302pt too wide)
+
+and gives the line number along with the text of the offending line
+marked at all the places that TeX knows to hyphenate words. (In TeX
+lines are in `horizontal boxes', hence the term, `hbox'.)
+
+If the Texinfo file has an overfull hbox, you can rewrite the
+sentence so the overfull hbox does not occur or you can decide to
+leave it. A small excursion into the right margin often does not
+matter and may not even be noticable. However, unless told
+otherwise, TeX will print a large, ugly, black rectangle beside every
+line that is overfull. This is so you will notice the location of
+the problem if you are correcting a draft. To prevent such
+monstrosities from marring your final printout, put the following in
+the beginning of the Texinfo file on lines of their own, before the
+`@setchapternewpage' command:
+
+ @iftex
+ @finalout
+ @end iftex
+
+*Note Titlepage::, for information about creating a title page.
+*Note Contents::, for information about creating a table of contents.
+
+
+\1f
+File: texinfo, Node: Compile-Command, Prev: Requirements, Up: Printing Hardcopy
+
+Using Local Variables and the Compile Command
+=============================================
+
+Another way to give the TeX formatting command to Texinfo is to put
+that command in a "local variables list" at the end of the Texinfo
+file. You can then specify the TeX formatting command as a
+`compile-command' and have Emacs run the TeX formatting command by
+giving the command `M-x compile'. This creates a special shell
+called the `*compilation buffer*'. For example, at the end of the
+`gdb.texinfo' file, after the `@bye', you would put the following:
+
+ @c Local Variables:
+ @c compile-command: "tex gdb.texinfo"
+ @c End:
+
+This technique is most often used by programmers who compile programs
+this way.
+
+
+\1f
+File: texinfo, Node: Creating an Info File, Next: Catching Mistakes, Prev: Printing Hardcopy, Up: Top
+
+Creating an On-line Info file
+*****************************
+
+In GNU Emacs, using Texinfo mode, you can see what part or all of a
+Texinfo file will look like in Info by using the keyboard command
+`C-c C-f' (`texinfo-format-region'). This formats a region and
+displays in a temporary buffer called `*Info Region*'; however, this
+command does not turn on Info reading program--it just displays what
+the region will look like. The `texinfo-format-region' command is
+described more extensively in the chapter on using Texinfo mode.
+*Note Info on a Region::.
+
+In GNU Emacs, the way to create a working Info file is to visit the
+file and invoke
+
+ `M-x texinfo-format-buffer'
+
+A new buffer is created and the Info file text is generated there.
+`C-x C-s' will save it under the name specified in the `@setfilename'
+command.
+
+If the Texinfo file has more than 30,000 bytes,
+`texinfo-format-buffer' will automatically create a "tag table" for
+it. With a tag table, Info can jump to new nodes more quickly than
+it can otherwise. In addition, if the file has more than 100,000
+bytes in it, `texinfo-format-buffer' will split the file into shorter
+Indirect subfiles of about 50,000 bytes each. Files are split so
+that Info does not have to make a large buffer to hold the whole of a
+large Info file; instead, Info allocates just enough memory for the
+small, split off file that is needed at the time. This way, Emacs
+avoids wasting memory when you run Info. (Before splitting was
+implemented, Info files were always short and "include" files were
+designed as a way to create a single, large printed manual out of the
+smaller Info files. *Note Include Files::, for more information.)
+
+When the file is split, Info itself works through a shortened version
+of the original file that contains the tag table and references to
+the files that were split off. The split off files are called
+"indirect" files.
+
+The split off files have names that are created by appending `-1',
+`-2', `-3' and so on to the file names specified by the
+`@setfilename' command. The shortened version of the original file
+continues to have the name specified by `@setfilename'.
+
+At one stage in writing this document, for example, the Info file was
+saved as `test-texinfo' and that file looked like this:
+
+ Info file: test-texinfo, -*-Text-*-
+ produced by texinfo-format-buffer
+ from file: new-texinfo-manual.texinfo
+
+ ^_
+ Indirect:
+ test-texinfo-1: 102
+ test-texinfo-2: 50422
+ test-texinfo-3: 101300
+ ^_^L
+ Tag table:
+ (Indirect)
+ Node: overview^?104
+ Node: info file^?1271
+ Node: printed manual^?4853
+ Node: conventions^?6855
+ ...
+
+ (But `test-texinfo' had far more nodes than are shown here.) Each of
+the split off, indirect files, `test-texinfo-1', `test-texinfo-2',
+and `test-texinfo-3', is listed in this file after the line that says
+`Indirect:'. The tag table is listed after the line that says `Tag
+table:'.
+
+You cannot run the `M-x Info-validate' node checking command on
+indirect files. For information on how to prevent files from being
+split and how to validate the structure of the nodes, *note
+Info-Validating a Large File::.
+
+* Menu:
+
+* Installing an Info File:: Putting the Info file in the info directory.
+
+
+\1f
+File: texinfo, Node: Installing an Info File, Prev: Creating an Info File, Up: Creating an Info File
+
+Installing an Info file
+=======================
+
+An Info file is usually installed in the GNU Emacs directory called
+`info'. For Info to work, this directory must contain all the Info
+files, including the split off files. In addition, the `info'
+directory must have a file that serves as a top level directory for
+the Info system. This file is called `dir'.
+
+For example, in the `info' directory, the file called `dir' has the
+top level menu for all the Info files in the system. This file has a
+master menu that looks like this:
+
+ * Menu:
+
+ * Info: (info). Documentation browsing system.
+ * Emacs: (emacs). The extensible self-documenting text editor.
+ * Texinfo: (texinfo). With one source file, make either a printed
+ manual using TeX or an Info file using
+ Texinfo.
+
+ To add a new Info file, just add it to this menu. For example, if
+you were adding documentation for GDB, you would make the following
+entry:
+
+ * GDB: (gdb). The source-level C debugger.
+
+ The first item is the menu item name; it is followed by a colon. The
+second item is the name of the Info file, in parentheses; it is
+followed by a period. The third part of the entry is the description
+of the item.
+
+The top node of the file, named `top', should have as its parent the
+name of a node in another file, where there is a menu that leads to
+this file. Specify the file name in parentheses. If the file is to
+be installed directly in the Info directory file, use `(dir)' as the
+parent of the top node; this is short for `(dir)top', the node `top'
+in the file `dir', which is the main menu of Info.
+
+
+\1f
+File: texinfo, Node: Catching Mistakes, Next: Command Syntax, Prev: Creating an Info File, Up: Top
+
+Catching Mistakes
+*****************
+
+Besides mistakes with the content of what ever you are describing,
+there are two kinds of mistake you can make with Texinfo: you can
+make mistakes with @-commands, and you can make mistakes with the
+structure of the nodes and chapters.
+
+There are two tools for catching the first kind of mistake and two
+for catching the second.
+
+For finding problems with @-commands, your best action is to run `M-x
+texinfo-format-region' on regions of your file as you write it. In
+Texinfo mode, the `texinfo-format-region' command is bound to `C-c
+C-f'. In addition, you can run TeX on the whole file.
+
+For finding problems with the structure of nodes and chapters, you
+can use `C-c C-s' (`texinfo-show-structure') (and the related `occur'
+command) and you can use the `M-x Info-validate' command.
+
+* Menu:
+
+* Debugging with Info:: Catching errors with info formatting.
+* Debugging with Tex:: Catching errors with TeX formatting.
+* Using texinfo-show-structure:: Using `texinfo-show-structure'
+ to catch mistakes.
+* Running Info-Validate:: Checking for unreferenced nodes.
+
+
+\1f
+File: texinfo, Node: Debugging with Info, Next: Debugging with Tex, Up: Catching Mistakes
+
+Catching Errors with Info Formatting
+====================================
+
+After you have written part of a Texinfo file, you can use the `M-x
+texinfo-format-region' command to see whether the region formats
+properly. In Texinfo mode, this command is bound to the keyboard
+command `C-c C-f'.
+
+If you have made a mistake with an @-command, `M-x
+texinfo-format-region' will stop processing at or after the error and
+give an error message. To see where in the file the error occurred,
+switch to the `*Info Region*' buffer; the cursor will be in a
+position that is after the location of the error. Also, the text
+will not be formatted after the place the error occurred.
+
+For example, if you accidently end a menu with the command `@end
+menus' with an `s' on the end, instead of with `@end menu', you will
+get an error message that says:
+
+ @end menus is not handled by texinfo.
+
+ The cursor will stop at the point in the file where the error occurs,
+or not long after it. It will look like this:
+
+ @menu
+ * Using texinfo-show-structure:: Using `texinfo-show-structure'
+ to catch mistakes.
+ * Running Info-Validate:: Checking for unreferenced nodes.
+ @end menus
+
+The `texinfo-format-region' command does not always recognize errors.
+For example, no errors were reported when `texinfo-format-region' was
+run on the whole itemized list of which the following is a part:
+
+ name of the Texinfo file as an extension. The @samp{??} are `wildcards'
+ that cause the shell to substitute all the raw index files. (@xref{sorting
+ indices), for more information about sorting indices.) @refill
+ @cindex Sorting indices
+ @cindex Indices, sorting
+
+ @item
+ @emph{Third}, rerun the @TeX{} command on the Texinfo file. This
+ regenerates a formatted DVI file with the index entries in the correct
+ order. This second run also makes all the cross references and table of
+ contents correct as well.
+
+ Instead, `texinfo-format-region' ran without reporting the error, but
+it produced output with very long lines, containing some of the
+original `@cindex' commands mixed in. (It is not practical to
+display these over long lines here.
+
+However, when `texinfo-format-region' was run on part of the list
+that is shown, it did give an error message, `Search failed: "[{,}"'.
+(This error message is explained in the section on using the Emacs
+Lisp Debugger, *note Using the Emacs Lisp Debugger::.)
+
+Sometimes `texinfo-format-region' will stop long after the original
+error; this is because it does not discover the problem until then.
+In this case, you will have to backtrack.
+
+
+\1f
+File: texinfo, Node: Using the Emacs Lisp Debugger, Up: Debugging with Info
+
+Using the Emacs Lisp Debugger
+-----------------------------
+
+If an error is especially elusive, you can turn on the Emacs Lisp
+debugger and look at the backtrace; this tells you where in the
+`texinfo-format-region' function the problem occurred. You can turn
+on the debugger with the command:
+
+ M-x set-variable RET debug-on-error RET t
+
+and turn it off with
+
+ M-x set-variable RET debug-on-error RET nil
+
+Often, when you are using the debugger, it is easier to follow what
+is going on if you use the Emacs Lisp files that are not
+byte-compiled. The byte-compiled sources send octal numbers to the
+debugger that may look mysterious. To use the uncompiled source
+files, load `texinfmt.el' and `texinfo.el' with the `M-x load-file'
+command.
+
+The debugger will not catch an error if `texinfo-format-region' does
+not detect one. In the example shown above, `texinfo-format-region'
+did not find the error when the whole list was formatted, but only
+when part of the list was formatted. When `texinfo-format-region'
+did not find an error, the debugger did not find one either.
+
+However, when `texinfo-format-region' did report an error, it invoked
+the debugger. This is the backtrace it produced:
+
+ Signalling: (search-failed "[},]")
+ re-search-forward("[},]")
+ (while ...)
+ (let ...)
+ texinfo-format-parse-args()
+ (let ...)
+ texinfo-format-xref()
+ funcall(texinfo-format-xref)
+ (if ...)
+ (let ...)
+ (if ...)
+ (while ...)
+ texinfo-format-scan()
+ (save-excursion ...)
+ (let ...)
+ texinfo-format-region(103370 103631)
+ * call-interactively(texinfo-format-region)
+
+The backtrace is read from the bottom up. `texinfo-format-region'
+was called interactively; and it, in turn, called various functions,
+including `texinfo-format-scan', `texinfo-format-xref' and
+`texinfo-format-parse-args'. Inside the function
+`texinfo-format-parse-args', the function `re-search-forward' was
+called; it was this function that could not find the missing right
+hand brace.
+
+*Note : (emacs)Lisp Debug, for more information.
+
+
+\1f
+File: texinfo, Node: Debugging with Tex, Next: Using texinfo-show-structure, Prev: Debugging with Info, Up: Catching Mistakes
+
+Catching Errors with TeX Formatting
+===================================
+
+You can also catch mistakes when you format a file with TeX.
+
+Usually, you will want to do this after you have run
+`texinfo-format-buffer' on the same file. `texinfo-format-buffer' is
+usually faster and sometimes gives error messages that make more
+sense. *Note Debugging with Info::, for more information.
+
+For example, TeX was run on the same itemized list discussed in the
+section on the use of `texinfo-format-region' (*note Debugging with
+Info::.); the fragment with the error looked like this:
+
+ name of the texinfo file as an extension. The @samp{??} are `wildcards'
+ that cause the shell to substitute all the raw index files. (@xref{sorting
+ indices, for more information about sorting indices.) @refill
+
+This produced the following output, after which TeX stopped:
+
+ Runaway argument?
+ {sorting indices, for more information about sorting indices.) @refill @ETC.
+ ! Paragraph ended before \xref was complete.
+ <to be read again>
+ \par
+ l.27
+
+ ?
+
+In this case, TeX produced an accurate and understandable error
+message: `Paragraph ended before \xref was complete.' (Note, however,
+that TeX translated the `@' into a `\'.) Also, `\par' is an internal
+TeX command of no relevance to Texinfo.)
+
+Unfortunately, TeX is not always so helpful, and sometimes you have
+to be truly a Sherlock Holmes to discover what went wrong.
+
+In any case, if you run into a problem like this, you can do one of
+two things.
+
+ 1. You can tell TeX to continue running and to ignore errors as
+ best it can by typing `r RET' at the `?' prompt.
+
+ This is often the best thing to do. However, beware: the one
+ error may produce a cascade of additional error messages as it
+ consequences are felt through the rest of the file.
+
+ 2. You can tell TeX to stop this run by typing `x RET' at the `?'
+ prompt.
+
+Sometimes TeX will format a file without producing error messages
+even though there is a problem. This usually occurs if a command is
+not ended but TeX is able to continue processing anyhow. For
+example, if you fail to end an itemized list with the `@end itemize'
+command, TeX will write a DVI file that you can print out. The only
+error message that TeX will give you is the somewhat mysterious
+comment that
+
+ (\end occurred inside a group at level 1)
+
+However, if you print the DVI file, you will find that the text of
+the file that follows the itemized list is entirely indented as if it
+were part of the last item in the itemized list. The error message
+is the way TeX says that it expected to find an `@end' command
+somewhere in the file; but that it could not locate where it was
+needed.
+
+Another source of notoriously hard to find errors is a missing `@end
+group' command. If you ever are stumped by incomprehensible errors,
+look for a missing `@end group' command first.
+
+If you do not have the header lines in the file, TeX may stop in the
+beginning of its run and display output that looks like the following.
+The `*' indicates that TeX is waiting for input.
+
+ This is TeX, Version 2.0 for Berkeley UNIX (preloaded format=plain-cm
+ 87.10.25) (#tz-bar-a02987.tex [1])
+ *
+
+In this case, simply type `\end RET' after the asterisk. Then put
+the header lines into the Texinfo file and run the TeX command again.
+
+
projects / unix-history / commitdiff