1308 lines
49 KiB
Plaintext
1308 lines
49 KiB
Plaintext
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::.).
|
||
|