Another way to give the TeX formatting command to Texinfo is to put
that command in a "local variables list" at the end of the Texinfo
file. You can then specify the TeX formatting command as a
`compile-command' and have Emacs run the TeX formatting command by
giving the command `M-x compile'. This creates a special shell
called the `*compilation buffer*'. For example, at the end of the
`gdb.texinfo' file, after the `@bye', you would put the following:
@c Local Variables:
@c compile-command: "tex gdb.texinfo"
@c End:
This technique is most often used by programmers who compile programs
this way.
File: texinfo, Node: Creating an Info File, Next: Catching Mistakes, Prev: Printing Hardcopy, Up: Top
Creating an On-line Info file
*****************************
In GNU Emacs, using Texinfo mode, you can see what part or all of a
Texinfo file will look like in Info by using the keyboard command
`C-c C-f' (`texinfo-format-region'). This formats a region and
displays in a temporary buffer called `*Info Region*'; however, this
command does not turn on Info reading program--it just displays what
the region will look like. The `texinfo-format-region' command is
described more extensively in the chapter on using Texinfo mode.
*Note Info on a Region::.
In GNU Emacs, the way to create a working Info file is to visit the
file and invoke
`M-x texinfo-format-buffer'
A new buffer is created and the Info file text is generated there.
`C-x C-s' will save it under the name specified in the `@setfilename'
command.
If the Texinfo file has more than 30,000 bytes,
`texinfo-format-buffer' will automatically create a "tag table" for
it. With a tag table, Info can jump to new nodes more quickly than
it can otherwise. In addition, if the file has more than 100,000
bytes in it, `texinfo-format-buffer' will split the file into shorter
Indirect subfiles of about 50,000 bytes each. Files are split so
that Info does not have to make a large buffer to hold the whole of a
large Info file; instead, Info allocates just enough memory for the
small, split off file that is needed at the time. This way, Emacs
avoids wasting memory when you run Info. (Before splitting was
implemented, Info files were always short and "include" files were
designed as a way to create a single, large printed manual out of the
smaller Info files. *Note Include Files::, for more information.)
When the file is split, Info itself works through a shortened version
of the original file that contains the tag table and references to
the files that were split off. The split off files are called
"indirect" files.
The split off files have names that are created by appending `-1',
`-2', `-3' and so on to the file names specified by the
`@setfilename' command. The shortened version of the original file
continues to have the name specified by `@setfilename'.
At one stage in writing this document, for example, the Info file was
saved as `test-texinfo' and that file looked like this:
Info file: test-texinfo, -*-Text-*-
produced by texinfo-format-buffer
from file: new-texinfo-manual.texinfo
^_
Indirect:
test-texinfo-1: 102
test-texinfo-2: 50422
test-texinfo-3: 101300
^_^L
Tag table:
(Indirect)
Node: overview^?104
Node: info file^?1271
Node: printed manual^?4853
Node: conventions^?6855
...
(But `test-texinfo' had far more nodes than are shown here.) Each of
the split off, indirect files, `test-texinfo-1', `test-texinfo-2',
and `test-texinfo-3', is listed in this file after the line that says
`Indirect:'. The tag table is listed after the line that says `Tag
table:'.
You cannot run the `M-x Info-validate' node checking command on
indirect files. For information on how to prevent files from being
split and how to validate the structure of the nodes, *note
Info-Validating a Large File::.
* Menu:
* Installing an Info File:: Putting the Info file in the info directory.
File: texinfo, Node: Installing an Info File, Prev: Creating an Info File, Up: Creating an Info File
Installing an Info file
=======================
An Info file is usually installed in the GNU Emacs directory called
`info'. For Info to work, this directory must contain all the Info
files, including the split off files. In addition, the `info'
directory must have a file that serves as a top level directory for
the Info system. This file is called `dir'.
For example, in the `info' directory, the file called `dir' has the
top level menu for all the Info files in the system. This file has a
master menu that looks like this:
* Menu:
* Info: (info). Documentation browsing system.
* Emacs: (emacs). The extensible self-documenting text editor.
* Texinfo: (texinfo). With one source file, make either a printed
manual using TeX or an Info file using
Texinfo.
To add a new Info file, just add it to this menu. For example, if
you were adding documentation for GDB, you would make the following
entry:
* GDB: (gdb). The source-level C debugger.
The first item is the menu item name; it is followed by a colon. The
second item is the name of the Info file, in parentheses; it is
followed by a period. The third part of the entry is the description
of the item.
The top node of the file, named `top', should have as its parent the
name of a node in another file, where there is a menu that leads to
this file. Specify the file name in parentheses. If the file is to
be installed directly in the Info directory file, use `(dir)' as the
parent of the top node; this is short for `(dir)top', the node `top'
in the file `dir', which is the main menu of Info.
File: texinfo, Node: Catching Mistakes, Next: Command Syntax, Prev: Creating an Info File, Up: Top
Catching Mistakes
*****************
Besides mistakes with the content of what ever you are describing,
there are two kinds of mistake you can make with Texinfo: you can
make mistakes with @-commands, and you can make mistakes with the
structure of the nodes and chapters.
There are two tools for catching the first kind of mistake and two
for catching the second.
For finding problems with @-commands, your best action is to run `M-x
texinfo-format-region' on regions of your file as you write it. In
Texinfo mode, the `texinfo-format-region' command is bound to `C-c
C-f'. In addition, you can run TeX on the whole file.
For finding problems with the structure of nodes and chapters, you
can use `C-c C-s' (`texinfo-show-structure') (and the related `occur'
command) and you can use the `M-x Info-validate' command.
* Menu:
* Debugging with Info:: Catching errors with info formatting.
* Debugging with Tex:: Catching errors with TeX formatting.
* Using texinfo-show-structure:: Using `texinfo-show-structure'
to catch mistakes.
* Running Info-Validate:: Checking for unreferenced nodes.
File: texinfo, Node: Debugging with Info, Next: Debugging with Tex, Up: Catching Mistakes
Catching Errors with Info Formatting
====================================
After you have written part of a Texinfo file, you can use the `M-x
texinfo-format-region' command to see whether the region formats
properly. In Texinfo mode, this command is bound to the keyboard
command `C-c C-f'.
If you have made a mistake with an @-command, `M-x
texinfo-format-region' will stop processing at or after the error and
give an error message. To see where in the file the error occurred,
switch to the `*Info Region*' buffer; the cursor will be in a
position that is after the location of the error. Also, the text
will not be formatted after the place the error occurred.
For example, if you accidently end a menu with the command `@end
menus' with an `s' on the end, instead of with `@end menu', you will
get an error message that says:
@end menus is not handled by texinfo.
The cursor will stop at the point in the file where the error occurs,
or not long after it. It will look like this:
@menu
* Using texinfo-show-structure:: Using `texinfo-show-structure'
to catch mistakes.
* Running Info-Validate:: Checking for unreferenced nodes.
@end menus
The `texinfo-format-region' command does not always recognize errors.
For example, no errors were reported when `texinfo-format-region' was
run on the whole itemized list of which the following is a part:
name of the Texinfo file as an extension. The @samp{??} are `wildcards'
that cause the shell to substitute all the raw index files. (@xref{sorting
indices), for more information about sorting indices.) @refill
@cindex Sorting indices
@cindex Indices, sorting
@item
@emph{Third}, rerun the @TeX{} command on the Texinfo file. This
regenerates a formatted DVI file with the index entries in the correct
order. This second run also makes all the cross references and table of
contents correct as well.
Instead, `texinfo-format-region' ran without reporting the error, but
it produced output that looked like this:
name of the texinfo file as an extension. The `??' are `wildcards'
that cause the shell to substitute all the raw index files. (*Note for more information about sorting indices.) @refill @cindex Sorting indices @cindex Indices: sorting indices), rerun the TeX command on the texinfo file. This
regenerates a formatted DVI file with the index entries in the correct
order. This second run also makes all the cross references and table of
contents correct as well.
However, when `texinfo-format-region' was run on part of the list
that is shown, it did give an error message, `Search failed: "[{,}"'.
(This error message is explained in the section on using the Emacs
Lisp Debugger, *note Using the Emacs Lisp Debugger::.)
Sometimes `texinfo-format-region' will stop long after the original
error; this is because it does not discover the problem until then.
In this case, you will have to backtrack.
File: texinfo, Node: Using the Emacs Lisp Debugger, Up: Debugging with Info
Using the Emacs Lisp Debugger
-----------------------------
If an error is especially elusive, you can turn on the Emacs Lisp
debugger and look at the backtrace; this tells you where in the
`texinfo-format-region' function the problem occurred. You can turn
on the debugger with the command:
M-x set-variable RET debug-on-error RET t
and turn it off with
M-x set-variable RET debug-on-error RET nil
Often, when you are using the debugger, it is easier to follow what
is going on if you use the Emacs Lisp files that are not
byte-compiled. The byte-compiled sources send octal numbers to the
debugger that may look mysterious. To use the uncompiled source
files, load `texinfmt.el' and `texinfo.el' with the `M-x load-file'
command.
The debugger will not catch an error if `texinfo-format-region' does
not detect one. In the example shown above, `texinfo-format-region'
did not find the error when the whole list was formatted, but only
when part of the list was formatted. When `texinfo-format-region'
did not find an error, the debugger did not find one either.
However, when `texinfo-format-region' did report an error, it invoked
the debugger. This is the backtrace it produced:
Signalling: (search-failed "[},]")
re-search-forward("[},]")
(while ...)
(let ...)
texinfo-format-parse-args()
(let ...)
texinfo-format-xref()
funcall(texinfo-format-xref)
(if ...)
(let ...)
(if ...)
(while ...)
texinfo-format-scan()
(save-excursion ...)
(let ...)
texinfo-format-region(103370 103631)
* call-interactively(texinfo-format-region)
The backtrace is read from the bottom up. `texinfo-format-region'
was called interactively; and it, in turn, called various functions,
including `texinfo-format-scan', `texinfo-format-xref' and
`texinfo-format-parse-args'. Inside the function
`texinfo-format-parse-args', the function `re-search-forward' was
called; it was this function that could not find the missing right
hand brace.
*Note : (emacs)Lisp Debug, for more information.
File: texinfo, Node: Debugging with Tex, Next: Using texinfo-show-structure, Prev: Debugging with Info, Up: Catching Mistakes
Catching Errors with TeX Formatting
===================================
You can also catch mistakes when you format a file with TeX.
Usually, you will want to do this after you have run
`texinfo-format-buffer' on the same file. `texinfo-format-buffer' is
usually faster and sometimes gives error messages that make more
sense. *Note Debugging with Info::, for more information.
For example, TeX was run on the same itemized list discussed in the
section on the use of `texinfo-format-region' (*note Debugging with
Info::.); the fragment with the error looked like this:
name of the texinfo file as an extension. The @samp{??} are `wildcards'
that cause the shell to substitute all the raw index files. (@xref{sorting
indices, for more information about sorting indices.) @refill
This produced the following output, after which TeX stopped:
Runaway argument?
{sorting indices, for more information about sorting indices.) @refill @ETC.
! Paragraph ended before \xref was complete.
<to be read again>
\par
l.27
?
In this case, TeX produced an accurate and understandable error
message: `Paragraph ended before \xref was complete.' (Note, however,
that TeX translated the `@' into a `\'.) Also, `\par' is an internal
TeX command of no relevance to Texinfo.)
Unfortunately, TeX is not always so helpful, and sometimes you have
to be truly a Sherlock Holmes to discover what went wrong.
In any case, if you run into a problem like this, you can do one of
two things.
1. You can tell TeX to continue running and to ignore errors as
best it can by typing `r RET' at the `?' prompt.
This is often the best thing to do. However, beware: the one
error may produce a cascade of additional error messages as it
consequences are felt through the rest of the file.
2. You can tell TeX to stop this run by typing `x RET' at the `?'
prompt.
Sometimes TeX will format a file without producing error messages
even though there is a problem. This usually occurs if a command is
not ended but TeX is able to continue processing anyhow. For
example, if you fail to end an itemized list with the `@end itemize'
command, TeX will write a DVI file that you can print out. The only
error message that TeX will give you is the somewhat mysterious
comment that
(\end occurred inside a group at level 1)
However, if you print the DVI file, you will find that the text of
the file that follows the itemized list is entirely indented as if it
were part of the last item in the itemized list. The error message
is the way TeX says that it expected to find an `@end' command
somewhere in the file; but that it could not locate where it was
needed.
Another source of notoriously hard to find errors is a missing `@end
group' command. If you ever are stumped by incomprehensible errors,
look for a missing `@end group' command first.
If you do not have the header lines in the file, TeX may stop in the
beginning of its run and display output that looks like the following.
The `*' indicates that TeX is waiting for input.
This is TeX, Version 2.0 for Berkeley UNIX (preloaded format=plain-cm
87.10.25) (#tz-bar-a02987.tex [1])
*
In this case, simply type `\end RET' after the asterisk. Then put
the header lines into the Texinfo file and run the TeX command again.
