diff options
Diffstat (limited to 'gnu/usr.bin/texinfo/info-files/texi.info-7')
| -rw-r--r-- | gnu/usr.bin/texinfo/info-files/texi.info-7 | 1307 |
1 files changed, 0 insertions, 1307 deletions
diff --git a/gnu/usr.bin/texinfo/info-files/texi.info-7 b/gnu/usr.bin/texinfo/info-files/texi.info-7 deleted file mode 100644 index 3ea85ee..0000000 --- a/gnu/usr.bin/texinfo/info-files/texi.info-7 +++ /dev/null @@ -1,1307 +0,0 @@ -This is Info file texi.info, produced by Makeinfo-1.55 from the input -file texi.texi. - - This file documents Texinfo, a documentation system that uses a -single source file to produce both on-line information and a printed -manual. - - Copyright (C) 1988, 1990, 1991, 1992, 1993 Free Software Foundation, -Inc. - - This is the second edition of the Texinfo documentation, -and is consistent with version 2 of `texinfo.tex'. - - 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 Free Software Foundation. - - -File: texi.info, Node: Footnotes, Next: Conditionals, Prev: Definition Commands, Up: Top - -Footnotes -********* - - A "footnote" is for a reference that documents or elucidates the -primary text.(1) - - In Texinfo, footnotes are created with the `@footnote' command. -This command is followed immediately by a left brace, then by the text -of the footnote, and then by a terminating right brace. The template -is: - - @footnote{TEXT} - - Footnotes may be of any length, but are usually short. - - For example, this clause is followed by a sample footnote(2); in the -Texinfo source, it looks like this: - - ...a sample footnote @footnote{Here is the sample - footnote.}; in the Texinfo source... - - In a printed manual or book, the reference mark for a footnote is a -small, superscripted number; the text of the footnote is written at the -bottom of the page, below a horizontal line. - - In Info, the reference mark for a footnote is a pair of parentheses -with the footnote number between them, like this: `(1)'. - - Info has two footnote styles, which determine where the text of the -footnote is located: - - * In the `End' node style, all the footnotes for a single node are - placed at the end of that node. The footnotes are separated from - the rest of the node by a line of dashes with the word `Footnotes' - within it. Each footnote begins with an `(N)' reference mark. - - Here is an example of a single footnote in the end of node style: - - --------- Footnotes --------- - - (1) Here is a sample footnote. - - * In the `Separate' node style, all the footnotes for a single node - are placed in an automatically constructed node of their own. In - this style, a "footnote reference" follows each `(N)' reference - mark in the body of the node. The footnote reference is actually - a cross reference which you use to reach the footnote node. - - The name of the node containing the footnotes is constructed by - appending `-Footnotes' to the name of the node that contains the - footnotes. (Consequently, the footnotes' node for the `Footnotes' - node is `Footnotes-Footnotes'!) The footnotes' node has an `Up' - node pointer that leads back to its parent node. - - Here is how the first footnote in this manual looks after being - formatted for Info in the separate node style: - - File: texinfo.info Node: Overview-Footnotes, Up: Overview - - (1) Note that the first syllable of "Texinfo" is - pronounced like "speck", not "hex". ... - - A Texinfo file may be formatted into an Info file with either -footnote style. - - Use the `@footnotestyle' command to specify an Info file's footnote -style. Write this command at the beginning of a line followed by an -argument, either `end' for the end node style or `separate' for the -separate node style. - - For example, - - @footnotestyle end - -or - @footnotestyle separate - - Write an `@footnotestyle' command before or shortly after the -end-of-header line at the beginning of a Texinfo file. (If you include -the `@footnotestyle' command between the start-of-header and -end-of-header lines, the region formatting commands will format -footnotes as specified.) - - If you do not specify a footnote style, the formatting commands use -their default style. Currently, `makeinfo' uses the `end' style, while -`texinfo-format-buffer' and `texinfo-format-region' use the `separate' -style. - - This chapter contains two footnotes. - - ---------- Footnotes ---------- - - (1) A footnote should complement or expand upon the primary text, -but a reader should not need to read a footnote to understand the -primary text. For a thorough discussion of footnotes, see `The Chicago -Manual of Style', which is published by the University of Chicago Press. - - (2) Here is the sample footnote. - - -File: texi.info, Node: Conditionals, Next: Format/Print Hardcopy, Prev: Footnotes, Up: Top - -Conditionally Visible Text -************************** - - Sometimes it is good to use different text for a printed manual and -its corresponding 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. - -* Menu: - -* Conditional Commands:: How to specify text for Info or TeX. -* Using Ordinary TeX Commands:: You can use any and all TeX commands. -* set clear value:: How to designate which text to format (for - both Info and TeX); and how to set a - flag to a string that you can insert. - - -File: texi.info, Node: Conditional Commands, Next: Using Ordinary TeX Commands, Up: Conditionals - -Using `@ifinfo' and `@iftex' -============================ - - `@ifinfo' begins segments of text that should be ignored by TeX when -it typesets the printed manual. The segment of 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'. (*Note -Info Summary and Permissions::.) - - The `@iftex' and `@end iftex' commands are similar to the `@ifinfo' -and `@end ifinfo' commands, except that they specify text that will -appear in the printed manual but not in the Info file. - - For example, - - @iftex - This text will appear only in the printed manual. - @end iftex - - @ifinfo - However, this text will appear only in Info. - @end ifinfo - -The preceding example produces the following line: - - However, this text will appear only in Info. - -Note how you only see one of the two lines, depending on whether you -are reading the Info version or the printed version of this manual. - - The `@titlepage' command is a special variant of `@iftex' that is -used for making the title and copyright pages of the printed manual. -(*Note `@titlepage': titlepage.) - - -File: texi.info, Node: Using Ordinary TeX Commands, Next: set clear value, Prev: Conditional Commands, Up: Conditionals - -Using Ordinary TeX Commands -=========================== - - Inside a region delineated by `@iftex' and `@end iftex', you can -embed some PlainTeX commands. Info will ignore these commands since -they are only in that part of the file which is seen by TeX. You can -write the TeX commands as you would write them in a normal TeX file, -except that you must replace the `\' used by TeX with an `@'. For -example, in the `@titlepage' section of a Texinfo file, you can use the -TeX command `@vskip' to format the copyright page. (The `@titlepage' -command causes Info to ignore the region automatically, as it does with -the `@iftex' command.) - - However, many features of PlainTeX will not work, as they are -overridden by features of Texinfo. - - You can enter PlainTeX completely, and use `\' in the TeX commands, -by delineating a region with the `@tex' and `@end tex' commands. (The -`@tex' command also causes Info to ignore the region, like the `@iftex' -command.) - - For example, here is a mathematical expression written in PlainTeX: - - @tex - $$ \chi^2 = \sum_{i=1}^N - \left (y_i - (a + b x_i) - \over \sigma_i\right)^2 $$ - @end tex - -The output of this example will appear only in a printed manual. If -you are reading this in Info, you will not see anything after this -paragraph. - - -File: texi.info, Node: set clear value, Prev: Using Ordinary TeX Commands, Up: Conditionals - -`@set', `@clear', and `@value' -============================== - - You can direct the Texinfo formatting commands to format or ignore -parts of a Texinfo file with the `@set', `@clear', `@ifset', and -`@ifclear' commands. - - In addition, you can use the `@set FLAG' command to set the value of -FLAG to a string of characters; and use `@value{FLAG}' to insert that -string. You can use `@set', for example, to set a date and use -`@value' to insert the date in several places in the Texinfo file. - -* Menu: - -* ifset ifclear:: Format a region if a flag is set. -* value:: Replace a flag with a string. -* value Example:: An easy way to update edition information. - - -File: texi.info, Node: ifset ifclear, Next: value, Up: set clear value - -`@ifset' and `@ifclear' ------------------------ - - When a FLAG is set, the Texinfo formatting commands format text -between subsequent pairs of `@ifset FLAG' and `@end ifset' commands. -When the FLAG is cleared, the Texinfo formatting commands do *not* -format the text. - - Use the `@set FLAG' command to turn on, or "set", a FLAG; a "flag" -can be any single word. The format for the command looks like this: - - @set FLAG - - Write the conditionally formatted text between `@ifset FLAG' and -`@end ifset' commands, like this: - - @ifset FLAG - CONDITIONAL-TEXT - @end ifset - - For example, you can create one document that has two variants, such -as a manual for a `large' and `small' model: - - You can use this machine to dig up shrubs - without hurting them. - - @set large - - @ifset large - It can also dig up fully grown trees. - @end ifset - - Remember to replant promptly ... - -In the example, the formatting commands will format the text between -`@ifset large' and `@end ifset' because the `large' flag is set. - - Use the `@clear FLAG' command to turn off, or "clear", a flag. -Clearing a flag is the opposite of setting a flag. The command looks -like this: - - @clear FLAG - -Write the command on a line of its own. - - When FLAG is cleared, the Texinfo formatting commands do *not* -format the text between `@ifset FLAG' and `@end ifset'; that text is -ignored and does not appear in either printed or Info output. - - For example, if you clear the flag of the preceding example by -writing an `@clear large' command after the `@set large' command (but -before the conditional text), then the Texinfo formatting commands -ignore the text between the `@ifset large' and `@end ifset' commands. -In the formatted output, that text does not appear; in both printed and -Info output, you see only the lines that say, "You can use this machine -to dig up shrubs without hurting them. Remember to replant promptly -...". - - If a flag is cleared with an `@clear FLAG' command, then the -formatting commands format text between subsequent pairs of `@ifclear' -and `@end ifclear' commands. But if the flag is set with `@set FLAG', -then the formatting commands do *not* format text between an `@ifclear' -and an `@end ifclear' command; rather, they ignore that text. An -`@ifclear' command looks like this: - - @ifclear FLAG - - In brief, the commands are: - -`@set FLAG' - Tell the Texinfo formatting commands that FLAG is set. - -`@clear FLAG' - Tell the Texinfo formatting commands that FLAG is cleared. - -`@ifset FLAG' - If FLAG is set, tell the Texinfo formatting commands to format the - text up to the following `@end ifset' command. - - If FLAG is cleared, tell the Texinfo formatting commands to ignore - text up to the following `@end ifset' command. - -`@ifclear FLAG' - If FLAG is set, tell the Texinfo formatting commands to ignore the - text up to the following `@end ifclear' command. - - If FLAG is cleared, tell the Texinfo formatting commands to format - the text up to the following `@end ifclear' command. - - -File: texi.info, Node: value, Next: value Example, Prev: ifset ifclear, Up: set clear value - -`@value' --------- - - You can use the `@set' command to specify a value for a flag, which -is expanded by the `@value' command. The value is a string a -characters. - - Write the `@set' command like this: - - @set foo This is a string. - -This sets the value of `foo' to "This is a string." - - The Texinfo formatters replace an `@value{FLAG}' command with the -string to which FLAG is set. - - Thus, when `foo' is set as shown above, the Texinfo formatters -convert - - @value{foo} -to - This is a string. - - You can write an `@value' command within a paragraph; but you must -write an `@set' command on a line of its own. - - If you write the `@set' command like this: - - @set foo - -without specifying a string, the value of `foo' is an empty string. - - If you clear a previously set flag with an `@clear FLAG' command, a -subsequent `@value{flag}' command is invalid and the string is replaced -with an error message that says `{No value for "FLAG"}'. - - For example, if you set `foo' as follows: - - @set how-much very, very, very - -then the formatters transform - - It is a @value{how-much} wet day. -into - It is a very, very, very wet day. - - If you write - - @clear how-much - -then the formatters transform - - It is a @value{how-much} wet day. -into - It is a {No value for "how-much"} wet day. - - -File: texi.info, Node: value Example, Prev: value, Up: set clear value - -`@value' Example ----------------- - - You can use the `@value' command to limit the number of places you -need to change when you record an update to a manual. Here is how it -is done in `The GNU Make Manual': - -Set the flags: - - @set EDITION 0.35 Beta - @set VERSION 3.63 Beta - @set UPDATED 14 August 1992 - @set UPDATE-MONTH August 1992 - -Write text for the first `@ifinfo' section, for people reading the -Texinfo file: - - This is Edition @value{EDITION}, - last updated @value{UPDATED}, - of @cite{The GNU Make Manual}, - for @code{make}, Version @value{VERSION}. - -Write text for the title page, for people reading the printed manual: - - @title GNU Make - @subtitle A Program for Directing Recompilation - @subtitle Edition @value{EDITION}, ... - @subtitle @value{UPDATE-MONTH} - -(On a printed cover, a date listing the month and the year looks less -fussy than a date listing the day as well as the month and year.) - -Write text for the Top node, for people reading the Info file: - - This is Edition @value{EDITION} - of the @cite{GNU Make Manual}, - last updated @value{UPDATED} - for @code{make} Version @value{VERSION}. - - After you format the manual, the text in the first `@ifinfo' section -looks like this: - - This is Edition 0.35 Beta, last updated 14 August 1992, - of `The GNU Make Manual', for `make', Version 3.63 Beta. - - When you update the manual, change only the values of the flags; you -do not need to rewrite the three sections. - - -File: texi.info, Node: Format/Print Hardcopy, Next: Create an Info File, Prev: Conditionals, Up: Top - -Format and Print Hardcopy -************************* - - There are three major shell commands for making a printed manual -from a Texinfo file: one for converting the Texinfo file into a file -that will be printed, a second for sorting indices, and a third 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 GNU Emacs. - - If you are using GNU Emacs, you can use commands provided by Texinfo -mode instead of shell commands. In addition to the three commands to -format a file, sort the indices, and print the result, Texinfo mode -offers key bindings for commands to recenter the output buffer, show the -print queue, and delete a job from the print queue. - -* Menu: - -* Use TeX:: Use TeX to format for hardcopy. -* Shell Format & Print:: How to format and print a hardcopy manual - with shell commands. -* Within Emacs:: How to format and print from an Emacs shell. -* Texinfo Mode Printing:: How to format and print in Texinfo mode. -* Compile-Command:: How to print using Emacs's compile command. -* Requirements Summary:: TeX formatting requirements summary. -* Preparing for TeX:: What you need to do to use TeX. -* Overfull hboxes:: What are and what to do with overfull hboxes. -* smallbook:: How to print small format books and manuals. -* A4 Paper:: How to print on European A4 paper. -* Cropmarks and Magnification:: How to print marks to indicate the size - of pages and how to print scaled up output. - - -File: texi.info, Node: Use TeX, Next: Shell Format & Print, Up: Format/Print Hardcopy - -Use TeX -======= - - The typesetting program called TeX is used for formatting a Texinfo -file. TeX is a very powerful typesetting program and, if used right, -does an exceptionally good job. *Note How to Obtain TeX: Obtaining -TeX, for information on how to obtain TeX. - - The `makeinfo', `texinfo-format-region', and `texinfo-format-buffer' -commands read the very same @-commands in the Texinfo file as does TeX, -but process them differently to make an Info file; see *Note Create an -Info File::. - - -File: texi.info, Node: Shell Format & Print, Next: Within Emacs, Prev: Use TeX, Up: Format/Print Hardcopy - -Format and Print Using Shell Commands -===================================== - - Format the Texinfo file with the shell command `tex' followed by the -name of the Texinfo file. This 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; it -writes an output file of unsorted index data. This is a misfeature of -TeX. Hence, to generate a printed index, you first need a sorted index -to work from. The `texindex' command sorts indices. (The source file -`texindex.c' comes as part of the standard GNU distribution and is -usually installed when Emacs is installed.) - - The `tex' formatting command outputs unsorted index files under -names that obey a standard convention. These names are the name of -your main input file to the `tex' formatting command, 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.?? - -This command will run `texindex' on all the unsorted index files, -including any that you have defined yourself using `@defindex' or -`@defcodeindex'. (You may execute `texindex foo.??' even if there are -similarly named files with two letter extensions that are not index -files, such as `foo.el'. The `texindex' command reports but otherwise -ignores such files.) - - 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' -formatting command on the Texinfo file. This regenerates a formatted -DVI file with up-to-date index entries.(1) - - To summarize, this is a three step process: - - 1. Run the `tex' formatting 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. This creates the corresponding sorted index files. - - 3. Rerun the `tex' formatting command on the Texinfo file. This - regenerates a formatted DVI file with the index entries in the - correct order. This second run also corrects the page numbers for - the cross references. (The tables of contents are always correct.) - - You need not run `texindex' each time after you run the `tex' -formatting. If you do not, on the next run, the `tex' formatting -command will use whatever sorted index files happen to exist from the -previous use of `texindex'. This is usually OK while you are debugging. - - Rather than type the `tex' and `texindex' commands yourself, you can -use `texi2dvi'. This shell script is designed to simplify the -`tex'--`texindex'--`tex' sequence by figuring out whether index files -and DVI files are up-to-date. It runs `texindex' and `tex' only when -necessary. - - The syntax for `texi2dvi' is like this (where `%' is the shell -prompt): - - % texi2dvi FILENAME... - - Finally, you can print the DVI file with the DVI print command. The -precise command to use depends on the system; `lpr -d' is common. 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 shell commands may be different at your site; but -these are commonly used versions.) - - ---------- Footnotes ---------- - - (1) If you use more than one index and have cross references to an -index other than the first, you must run `tex' *three times* to get -correct output: once to generate raw index data; again (after -`texindex') to output the text of the indices and determine their true -page numbers; and a third time to output correct page numbers in cross -references to them. However, cross references to indices are rare. - - -File: texi.info, Node: Within Emacs, Next: Texinfo Mode Printing, Prev: Shell Format & Print, Up: Format/Print Hardcopy - -From an Emacs Shell ... -======================= - - You can give formatting and printing commands from a shell within GNU -Emacs. To create a shell within Emacs, type `M-x shell'. In this -shell, you can format and print the document. *Note How to Format and -Print Using Shell Commands: Shell Format & Print, for details. - - You can switch to and from the shell buffer while `tex' is running -and do other editing. If you are formatting a long document on a slow -machine, this can be very convenient. - - You can also use `texi2dvi' from an Emacs shell. For example, here -is how to use `texi2dvi' to format and print `Using and Porting GNU CC' -from a shell within Emacs (where `%' is the shell prompt): - - % texi2dvi gcc.texinfo - % lpr -d gcc.dvi - - *Note Texinfo Mode Printing::, for more information about formatting -and printing in Texinfo mode. - - -File: texi.info, Node: Texinfo Mode Printing, Next: Compile-Command, Prev: Within Emacs, Up: Format/Print Hardcopy - -Formatting and Printing in Texinfo Mode -======================================= - - Texinfo mode provides several predefined key commands for TeX -formatting and printing. These include commands for sorting indices, -looking at the printer queue, killing the formatting job, and -recentering the display of the buffer in which the operations occur. - -`C-c C-t C-r' -`M-x texinfo-tex-region' - Run TeX on the current region. - -`C-c C-t C-b' -`M-x texinfo-tex-buffer' - Run TeX on the current buffer. - -`C-c C-t C-i' -`M-x texinfo-texindex' - Sort the indices of a Texinfo file that have been formatted with - `texinfo-tex-region' or `texinfo-tex-buffer'. - -`C-c C-t C-p' -`M-x texinfo-tex-print' - Print a DVI file that was made with `texinfo-tex-region' or - `texinfo-tex-buffer'. - -`C-c C-t C-q' -`M-x texinfo-show-tex-print-queue' - Show the print queue. - -`C-c C-t C-d' -`M-x texinfo-delete-from-tex-print-queue' - Delete a job from the print queue; you will be prompted for the job - number shown by a preceding `C-c C-t C-q' command - (`texinfo-show-tex-print-queue'). - -`C-c C-t C-k' -`M-x texinfo-kill-tex-job' - Kill either the currently running TeX job that has been started by - `texinfo-tex-region' or `texinfo-tex-buffer', or any other process - running in the Texinfo shell buffer. - -`C-c C-t C-x' -`M-x texinfo-quit-tex-job' - Quit a TeX formatting job that has stopped because of an error by - sending an x to it. When you do this, TeX preserves a record of - what it did in a `.log' file. - -`C-c C-t C-l' -`M-x texinfo-recenter-tex-output-buffer' - Redisplay the shell buffer in which the TeX printing and formatting - commands are run to show its most recent output. - - Thus, the usual sequence of commands for formatting a buffer is as -follows (with comments to the right): - - C-c C-t C-b Run TeX on the buffer. - C-c C-t C-i Sort the indices. - C-c C-t C-b Rerun TeX to regenerate indices. - C-c C-t C-p Print the DVI file. - C-c C-t C-q Display the printer queue. - - The Texinfo mode TeX formatting commands start a subshell in Emacs -called the `*texinfo-tex-shell*'. The `texinfo-tex-command', -`texinfo-texindex-command', and `tex-dvi-print-command' commands are -all run in this shell. - - You can watch the commands operate in the `*texinfo-tex-shell*' -buffer, and you can switch to and from and use the -`*texinfo-tex-shell*' buffer as you would any other shell buffer. - - The formatting and print commands depend on the values of several -variables. The default values are: - - Variable Default value - - texinfo-tex-command "tex" - texinfo-texindex-command "texindex" - texinfo-tex-shell-cd-command "cd" - texinfo-tex-dvi-print-command "lpr -d" - texinfo-show-tex-queue-command "lpq" - texinfo-delete-from-print-queue-command "lprm" - texinfo-start-of-header "%**start" - texinfo-end-of-header "%**end" - texinfo-tex-trailer "@bye" - - The default values of both the `texinfo-tex-command' and the -`texinfo-texindex-command' variables are set in the `texnfo-tex.el' -file. - - You can change the values of these variables with the `M-x -edit-options' command (*note Editing Variable Values: (emacs)Edit -Options.), with the `M-x set-variable' command (*note Examining and -Setting Variables: (emacs)Examining.), or with your `.emacs' -initialization file (*note Init File: (emacs)Init File.). - - -File: texi.info, Node: Compile-Command, Next: Requirements Summary, Prev: Texinfo Mode Printing, Up: Format/Print Hardcopy - -Using the Local Variables List -============================== - - Yet another way to apply the TeX formatting command to a Texinfo -file 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 -typing `M-x compile'. This creates a special shell called the -`*compilation buffer*' in which Emacs runs the compile command. 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 also compile -programs this way; see *Note Compilation: (emacs)Compilation. - - -File: texi.info, Node: Requirements Summary, Next: Preparing for TeX, Prev: Compile-Command, Up: Format/Print Hardcopy - -TeX Formatting Requirements Summary -=================================== - - Every Texinfo file that is to be input to TeX must begin with a -`\input' command and contain an `@settitle' command: - - \input texinfo - @settitle NAME-OF-MANUAL - -The first command instructs TeX to load the macros it needs to process -a Texinfo file and the second command specifies the title of printed -manual. - - Every Texinfo file must end with a line that terminates TeX -processing and forces out unfinished pages: - - @bye - - Strictly speaking, these three lines are all a Texinfo file needs for -TeX, besides the body. (The `@setfilename' line is the only line that -a Texinfo file needs for Info formatting.) - - Usually, the file's first line contains an `@c -*-texinfo-*-' -comment that causes Emacs to switch to Texinfo mode when you edit the -file. In addition, the beginning usually includes an `@setfilename' -for Info formatting, an `@setchapternewpage' command, a title page, a -copyright page, and permissions. Besides an `@bye', the end of a file -usually includes indices and a table of contents. - -For more information, see -*Note `@setchapternewpage': setchapternewpage, -*Note Page Headings: Headings, -*Note Titlepage & Copyright Page::, -*Note Printing Indices & Menus::, and -*Note Contents::. - - -File: texi.info, Node: Preparing for TeX, Next: Overfull hboxes, Prev: Requirements Summary, Up: Format/Print Hardcopy - -Preparing to Use TeX -==================== - -TeX needs to know where to find the `texinfo.tex' file that you have -told it to input with the `\input texinfo' command at the beginning of -the first line. The `texinfo.tex' file tells TeX how to handle -@-commands. (`texinfo.tex' is included in the standard GNU -distributions.) - - Usually, the `texinfo.tex' file is put in the default directory that -contains TeX macros (the `/usr/lib/tex/macros' directory) when GNU -Emacs or other GNU software is installed. In this case, TeX will find -the file and you do not need to do anything special. Alternatively, -you can put `texinfo.tex' in the directory in which the Texinfo source -file is located, and TeX will find it there. - - However, you may want to specify the location of the `\input' file -yourself. One way to do this is to write the complete path for the file -after the `\input' command. Another way is to set the `TEXINPUTS' -environment variable in your `.cshrc' or `.profile' file. The -`TEXINPUTS' environment variable will tell TeX where to find the -`texinfo.tex' file and any other file that you might want TeX to use. - - Whether you use a `.cshrc' or `.profile' file depends on whether you -use `csh', `sh', or `bash' for your shell command interpreter. When -you use `csh', it looks to the `.cshrc' file for initialization -information, and when you use `sh' or `bash', it looks to the -`.profile' file. - - In a `.cshrc' file, you could use the following `csh' command -sequence: - - setenv TEXINPUTS .:/usr/me/mylib:/usr/lib/tex/macros - - In a `.profile' file, you could use the following `sh' command -sequence: - - TEXINPUTS=.:/usr/me/mylib:/usr/lib/tex/macros - export TEXINPUTS - -This would cause TeX to look for `\input' file first in the current -directory, indicated by the `.', then in a hypothetical user's -`me/mylib' directory, and finally in the system library. - - -File: texi.info, Node: Overfull hboxes, Next: smallbook, Prev: Preparing for TeX, Up: Format/Print Hardcopy - -Overfull "hboxes" -================= - - TeX is sometimes 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, such as an -electronic mail network address or a very long title. When this -happens, TeX prints an error message like this: - - Overfull \hbox (20.76302pt too wide) - -(In TeX, lines are in "horizontal boxes", hence the term, "hbox". The -backslash, `\', is the TeX equivalent of `@'.) - - TeX also provides the line number in the Texinfo source file and the -text of the offending line, which is marked at all the places that TeX -knows how to hyphenate words. *Note Catching Errors with TeX -Formatting: Debugging with TeX, for more information about typesetting -errors. - - 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 noticeable. - - However, unless told otherwise, TeX will print a large, ugly, black -rectangle beside the line that contains the overful hbox. This is so -you will notice the location of the problem if you are correcting a -draft. - - To prevent such a monstrosity from marring your final printout, write -the following in the beginning of the Texinfo file on a line of its own, -before the `@titlepage' command: - - @finalout - - -File: texi.info, Node: smallbook, Next: A4 Paper, Prev: Overfull hboxes, Up: Format/Print Hardcopy - -Printing "Small" Books -====================== - - 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 title page: - - @smallbook - -(Since regular sized books are often about 7 by 9.25 inches, this -command might better have been called the `@regularbooksize' command, -but it came to be called the `@smallbook' command by comparison to the -8.5 by 11 inch format.) - - If you write the `@smallbook' command between the start-of-header -and end-of-header lines, the Texinfo mode TeX region formatting -command, `texinfo-tex-region', will format the region in "small" book -size (*note Start of Header::.). - - The Free Software Foundation distributes printed copies of `The GNU -Emacs Manual' and other manuals in the "small" book size. *Note -`@smallexample' and `@smalllisp': smallexample & smalllisp, for -information about commands that make it easier to produce examples for -a smaller manual. - - -File: texi.info, Node: A4 Paper, Next: Cropmarks and Magnification, Prev: smallbook, Up: Format/Print Hardcopy - -Printing on A4 Paper -==================== - - You can tell TeX to typeset a document for printing on European size -A4 paper with the `@afourpaper' command. Write the command on a line -by itself between `@iftex' and `@end iftex' lines near the beginning of -the Texinfo file, before the title page: - - For example, this is how you would write the header for this manual: - - \input texinfo @c -*-texinfo-*- - @c %**start of header - @setfilename texinfo - @settitle Texinfo - @syncodeindex vr fn - @iftex - @afourpaper - @end iftex - @c %**end of header - - -File: texi.info, Node: Cropmarks and Magnification, Prev: A4 Paper, Up: Format/Print Hardcopy - -Cropmarks and Magnification -=========================== - - You can attempt to direct TeX to print cropmarks at the corners of -pages with the `@cropmarks' command. Write the `@cropmarks' command on -a line by itself between `@iftex' and `@end iftex' lines near the -beginning of the Texinfo file, before the title page, like this: - - @iftex - @cropmarks - @end iftex - - This command is mainly for printers that typeset several pages on one -sheet of film; but you can attempt to use it to mark the corners of a -book set to 7 by 9.25 inches with the `@smallbook' command. (Printers -will not produce cropmarks for regular sized output that is printed on -regular sized paper.) Since different printing machines work in -different ways, you should explore the use of this command with a -spirit of adventure. You may have to redefine the command in the -`texinfo.tex' definitions file. - - You can attempt to direct TeX to typeset pages larger or smaller than -usual with the `\mag' TeX command. Everything that is typeset is -scaled proportionally larger or smaller. (`\mag' stands for -"magnification".) This is *not* a Texinfo @-command, but is a PlainTeX -command that is prefixed with a backslash. You have to write this -command between `@tex' and `@end tex' (*note Using Ordinary TeX -Commands: Using Ordinary TeX Commands.). - - Follow the `\mag' command with an `=' and then a number that is 1000 -times the magnification you desire. For example, to print pages at 1.2 -normal size, write the following near the beginning of the Texinfo -file, before the title page: - - @tex - \mag=1200 - @end tex - - With some printing technologies, you can print normal-sized copies -that look better than usual by using a larger-than-normal master. - - Depending on your system, `\mag' may not work or may work only at -certain magnifications. Be prepared to experiment. - - -File: texi.info, Node: Create an Info File, Next: Install an Info File, Prev: Format/Print Hardcopy, Up: Top - -Creating an Info File -********************* - - `makeinfo' is a utility that converts a Texinfo file into an Info -file; `texinfo-format-region' and `texinfo-format-buffer' are GNU Emacs -functions that do the same. - - A Texinfo file must possess an `@setfilename' line near its -beginning, otherwise the Info formatting commands will fail. - - For information on installing the Info file in the Info system, see -*Note Install an Info File::. - -* Menu: - -* makeinfo advantages:: `makeinfo' provides better error checking. -* Invoking makeinfo:: How to run `makeinfo' from a shell. -* makeinfo options:: Specify fill-column and other options. -* Pointer Validation:: How to check that pointers point somewhere. -* makeinfo in Emacs:: How to run `makeinfo' from Emacs. -* texinfo-format commands:: Two Info formatting commands written - in Emacs Lisp are an alternative - to `makeinfo'. -* Batch Formatting:: How to format for Info in Emacs Batch mode. -* Tag and Split Files:: How tagged and split files help Info - to run better. - - -File: texi.info, Node: makeinfo advantages, Next: Invoking makeinfo, Up: Create an Info File - -`makeinfo' Preferred -==================== - - The `makeinfo' utility creates an Info file from a Texinfo source -file more quickly than either of the Emacs formatting commands and -provides better error messages. We recommend it. `makeinfo' is a C -program that is independent of Emacs. You do not need to run Emacs to -use `makeinfo', which means you can use `makeinfo' on machines that are -too small to run Emacs. You can run `makeinfo' in any one of three -ways: from an operating system shell, from a shell inside Emacs, or by -typing a key command in Texinfo mode in Emacs. - - The `texinfo-format-region' and the `texinfo-format-buffer' commands -are useful if you cannot run `makeinfo'. Also, in some circumstances, -they format short regions or buffers more quickly than `makeinfo'. - - -File: texi.info, Node: Invoking makeinfo, Next: makeinfo options, Prev: makeinfo advantages, Up: Create an Info File - -Invoking `makeinfo' from a Shell -================================ - - To create an Info file from a Texinfo file, type `makeinfo' followed -by the name of the Texinfo file. Thus, to create the Info file for -Bison, type the following at the shell prompt (where `%' is the prompt): - - % makeinfo bison.texinfo - - (You can run a shell inside Emacs by typing `M-x shell'.) - - Sometimes you will want to specify options. For example, if you wish -to discover which version of `makeinfo' you are using, type: - - % makeinfo --version - - *Note makeinfo options::, for more information. - - -File: texi.info, Node: makeinfo options, Next: Pointer Validation, Prev: Invoking makeinfo, Up: Create an Info File - -Options for `makeinfo' -====================== - - The `makeinfo' command takes a number of options. Most often, -options are used to set the value of the fill column and specify the -footnote style. Each command line option is a word preceded by `--'(1) -or a letter preceded by `-'. You can use abbreviations for the option -names as long as they are unique. - - For example, you could use the following command to create an Info -file for `bison.texinfo' in which each line is filled to only 68 -columns (where `%' is the prompt): - - % makeinfo --fill-column=68 bison.texinfo - - You can write two or more options in sequence, like this: - - % makeinfo --no-split --fill-column=70 ... - -This would keep the Info file together as one possibly very long file -and would also set the fill column to 70. - - The options are: - -`-D VAR' - Cause VAR to be defined. This is equivalent to `@set VAR' in the - Texinfo file. - -`--error-limit LIMIT' - Set the maximum number of errors that `makeinfo' will report - before exiting (on the assumption that continuing would be - useless). The default number of errors that can be reported before - `makeinfo' gives up is 100. - -`--fill-column WIDTH' - Specify the maximum number of columns in a line; this is the - right-hand edge of a line. Paragraphs that are filled will be - filled to this width. (Filling is the process of breaking up and - connecting lines so that lines are the same length as or shorter - than the number specified as the fill column. Lines are broken - between words.) The default value for `fill-column' is 72. - -`--footnote-style STYLE' - Set the footnote style to STYLE, either `end' for the end node - style or `separate' for the separate node style. The value set by - this option overrides the value set in a Texinfo file by an - `@footnotestyle' command. When the footnote style is `separate', - `makeinfo' makes a new node containing the footnotes found in the - current node. When the footnote style is `end', `makeinfo' places - the footnote references at the end of the current node. - -`-I DIR' - Add `dir' to the directory search list for finding files that are - included using the `@include' command. By default, `makeinfo' - searches only the current directory. - -`--no-headers' - Do not include menus or node lines in the output. This results in - an ASCII file that you cannot read in Info since it does not - contain the requisite nodes or menus; but you can print such a - file in a single, typewriter-like font and produce acceptable - output. - -`--no-split' - Suppress the splitting stage of `makeinfo'. Normally, large - output files (where the size is greater than 70k bytes) are split - into smaller subfiles, each one approximately 50k bytes. If you - specify `--no-split', `makeinfo' will not split up the output file. - -`--no-pointer-validate' -`--no-validate' - Suppress the pointer-validation phase of `makeinfo'. Normally, - after a Texinfo file is processed, some consistency checks are - made to ensure that cross references can be resolved, etc. *Note - Pointer Validation::. - -`--no-warn' - Suppress the output of warning messages. This does *not* suppress - the output of error messages, only warnings. You might want this - if the file you are creating has examples of Texinfo cross - references within it, and the nodes that are referenced do not - actually exist. - -`--no-number-footnotes' - Supress automatic footnote numbering. By default, `makeinfo' - numbers each footnote sequentially in a single node, resetting the - current footnote number to 1 at the start of each node. - -`--output FILE' -`-o FILE' - Specify that the output should be directed to FILE and not to the - file name specified in the `@setfilename' command found in the - Texinfo source. FILE can be the special token `-', which specifies - standard output. - -`--paragraph-indent INDENT' - Set the paragraph indentation style to INDENT. The value set by - this option overrides the value set in a Texinfo file by an - `@paragraphindent' command. The value of INDENT is interpreted as - follows: - - * If the value of INDENT is `asis', do not change the existing - indentation at the starts of paragraphs. - - * If the value of INDENT is zero, delete any existing - indentation. - - * If the value of INDENT is greater than zero, indent each - paragraph by that number of spaces. - -`--reference-limit LIMIT' - Set the value of the number of references to a node that - `makeinfo' will make without reporting a warning. If a node has - more than this number of references in it, `makeinfo' will make the - references but also report a warning. - -`-U VAR' - Cause VAR to be undefined. This is equivalent to `@clear VAR' in - the Texinfo file. - -`--verbose' - Cause `makeinfo' to display messages saying what it is doing. - Normally, `makeinfo' only outputs messages if there are errors or - warnings. - -`--version' - Report the version number of this copy of `makeinfo'. - - ---------- Footnotes ---------- - - (1) `--' has replaced `+', the old introductory character, to -maintain POSIX.2 compatibility without losing long-named options. - - -File: texi.info, Node: Pointer Validation, Next: makeinfo in Emacs, Prev: makeinfo options, Up: Create an Info File - -Pointer Validation -================== - - `makeinfo' will check the validity of the final Info file unless you -suppress pointer-validation by using the `--no-pointer-validation' -option. Mostly, this means ensuring that nodes you have referenced -really exist. Here is a complete list of what is checked: - - 1. If a `Next', `Previous', or `Up' node reference is a reference to a - node in the current file and is not an external reference such as - to `(dir)', then the referenced node must exist. - - 2. In every node, if the `Previous' node is different from the `Up' - node, then the `Previous' node must also be pointed to by a `Next' - node. - - 3. Every node except the `Top' node must have an `Up' pointer. - - 4. The node referenced by an `Up' pointer must contain a reference to - the current node in some manner other than through a `Next' - reference. This includes menu entries and cross references. - - 5. If the `Next' reference of a node is not the same as the `Next' - reference of the `Up' reference, then the node referenced by the - `Next' pointer must have a `Previous' pointer that points back to - the current node. This rule allows the last node in a section to - point to the first node of the next chapter. - - -File: texi.info, Node: makeinfo in Emacs, Next: texinfo-format commands, Prev: Pointer Validation, Up: Create an Info File - -Running `makeinfo' inside Emacs -=============================== - - You can run `makeinfo' in GNU Emacs Texinfo mode by using either the -`makeinfo-region' or the `makeinfo-buffer' commands. In Texinfo mode, -the commands are bound to `C-c C-m C-r' and `C-c C-m C-b' by default. - -`C-c C-m C-r' -`M-x makeinfo-region' - Format the current region for Info. - -`C-c C-m C-b' -`M-x makeinfo-buffer' - Format the current buffer for Info. - - When you invoke either `makeinfo-region' or `makeinfo-buffer', Emacs -prompts for a file name, offering the name of the visited file as the -default. You can edit the default file name in the minibuffer if you -wish, before typing RET to start the `makeinfo' process. - - The Emacs `makeinfo-region' and `makeinfo-buffer' commands run the -`makeinfo' program in a temporary shell buffer. If `makeinfo' finds -any errors, Emacs displays the error messages in the temporary buffer. - - You can parse the error messages by typing `C-x `' (`next-error'). -This causes Emacs to go to and position the cursor on the line in the -Texinfo source that `makeinfo' thinks caused the error. *Note Running -`make' or Compilers Generally: (emacs)Compilation, for more information -about using the `next-error' command. - - In addition, you can kill the shell in which the `makeinfo' command -is running or make the shell buffer display its most recent output. - -`C-c C-m C-k' -`M-x makeinfo-kill-job' - Kill the currently running job created by `makeinfo-region' or - `makeinfo-buffer'. - -`C-c C-m C-l' -`M-x makeinfo-recenter-output-buffer' - Redisplay the `makeinfo' shell buffer to display its most recent - output. - -(Note that the parallel commands for killing and recentering a TeX job -are `C-c C-t C-k' and `C-c C-t C-l'. *Note Texinfo Mode Printing::.) - - You can specify options for `makeinfo' by setting the -`makeinfo-options' variable with either the `M-x edit-options' or the -`M-x set-variable' command, or by setting the variable in your `.emacs' -initialization file. - - For example, you could write the following in your `.emacs' file: - - (setq makeinfo-options - "--paragraph-indent=0 --no-split - --fill-column=70 --verbose") - -For more information, see -*Note Editing Variable Values: (emacs)Edit Options, -*Note Examining and Setting Variables: (emacs)Examining, -*Note Init File: (emacs)Init File, and -*Note Options for `makeinfo': makeinfo options. - - -File: texi.info, Node: texinfo-format commands, Next: Batch Formatting, Prev: makeinfo in Emacs, Up: Create an Info File - -The `texinfo-format...' Commands -================================ - -In GNU Emacs in Texinfo mode, you can format part or all of a Texinfo -file with the `texinfo-format-region' command. This formats the -current region and displays the formatted text in a temporary buffer -called `*Info Region*'. - - Similarly, you can format a buffer with the `texinfo-format-buffer' -command. This command creates a new buffer and generates the Info file -in it. Typing `C-x C-s' will save the Info file under the name -specified by the `@setfilename' line which must be near the beginning -of the Texinfo file. - -`C-c C-e C-r' -``texinfo-format-region'' - Format the current region for Info. - -`C-c C-e C-b' -``texinfo-format-buffer'' - Format the current buffer for Info. - - The `texinfo-format-region' and `texinfo-format-buffer' commands -provide you with some error checking, and other functions can provide -you with further help in finding formatting errors. These procedures -are described in an appendix; see *Note Catching Mistakes::. However, -the `makeinfo' program is often faster and provides better error -checking (*note makeinfo in Emacs::.). - |
