mike@ists.ists.ca (Mike Clarkson) (06/03/90)
#! /bin/sh
# This is a shell archive. Remove anything before this line, then unpack
# it by saving it into a file and typing "sh file". To overwrite existing
# files, type "sh file -c". You can also feed this as standard input via
# unshar, or by typing "sh <file", e.g.. If this archive is complete, you
# will see the following message at the end:
# "End of archive 6 (of 9)."
# Contents: manual/latexinfo.tex-ad
# Wrapped by mike@sam on Sat Jun 2 18:18:13 1990
PATH=/bin:/usr/bin:/usr/ucb ; export PATH
if test -f 'manual/latexinfo.tex-ad' -a "${1}" != "-c" ; then
echo shar: Will not clobber existing file \"'manual/latexinfo.tex-ad'\"
else
echo shar: Extracting \"'manual/latexinfo.tex-ad'\" \(39490 characters\)
sed "s/^X//" >'manual/latexinfo.tex-ad' <<'END_OF_FILE'
Xthe \LaTeX\ and info output.
X
X
X\node Insert Left Brace, Insert Right Brace, Inserting A Backslash, Inserting Braces Backslashes Periods
X\subsection{Insert Left Brace}
X\cindex{Insert Left Brace}
X\findex{left-braces}
X
X\code{\back \{} stands for a single \{ in either printed or Info output.
X
X\node Insert Right Brace, Insert Colon, Insert Left Brace, Inserting Braces Backslashes Periods
X\subsection{Insert Right Brace}
X\cindex{Insert Right Brace}
X\cindex{Insert Right Brace}
X\findex{right-braces}
X
X\code{\back \}} stands for a single \} in either printed or Info output.
X
X\node Insert Colon, Insert Period, Insert Right Brace, Inserting Braces Backslashes Periods
X\subsection{Insert Colon}
X\cindex{Insert Colon}
X
X\code{\back :}\: is used after a character such as period or colon which
Xnormally causes \LaTeX\ to increase the width of the following whitespace,
Xto suppress that effect. For example, it can be used after periods that
Xend abbreviations and do not end sentences. \code{\back :}\: has no effect
Xon the Info file output.
X
X\begin{example}
XIt displays \back code\{Foo:\}\back : at that time.
X\end{example}
X
X\noindent
Xproduces
X
X\begin{quotation}
XIt displays \code{Foo:}\: at that time.
X\end{quotation}
X
XThe meanings of \code{\back :}\: and \code{\back .}\: in \LaTeX info are
Xdesigned to work well with the Emacs sentence motion commands.
X
X\node Insert Period, Inserting Dots Bullets and TeX, Insert Colon, Inserting Braces Backslashes Periods
X\subsection{Insert Period}
X\cindex{Insert Period}
X\findex{periods}
X
X\code{\back .}\: stands for a period that really does end a sentence, useful
Xwhen \LaTeX\ would otherwise assume by its heuristics that that is not so.
XThis happens when there is a single-capital-letter word at the end of a
Xsentence: \LaTeX\ normally guesses that it is an abbreviation.
X
XIn the Info file output, \code{\back .}\: is equivalent to a simple \samp{.}.
XThe \LaTeX info program preserves the amount of space that you use, so put
Xtwo spaces after a period if you intend it to be the end of a sentence
X(as well as using \code{\back .}, if necessary, for the printed manual's sake).
X
X\begin{example}
XGive it to X. Give it to X\back . Give it to X\back .
X\end{example}
X
X\noindent
Xproduces
X
X\begin{quotation}
XGive it to X. Give it to X\. Give it to X\.
X\end{quotation}
X
X\node Inserting Dots Bullets and TeX, Dots, Insert Period, Marking Text Within a Paragraph
X\section{Inserting Dots Bullets and TeX}
X\cindex{Dots, inserting}
X\cindex{Bullets, inserting}
X\cindex{TeX-logo, inserting}
X\cindex{LaTeX-logo, inserting}
X\cindex{Special typesetting commands}
X\cindex{Typesetting commands for dots and the like}
X
XAn ellipsis, a line of dots, is typeset differently than a string of
Xperiods; more whitespace is put between the dots in the ellipsis than is
Xput between the periods. Because of this, a special command is used in
X\LaTeX info for inserting dots. Also, the trademark, \LaTeX, is typeset in a
Xspecial fashion and it needs a command, as does the command for
Xinserting the copyright symbol. The \code{\back bullet} command is
Xspecial, too.
X
X\begin{menu}
X* Dots::
X* Bullet::
X* Tex::
X\end{menu}
X
X\node Dots, Bullet, Inserting Dots Bullets and TeX, Inserting Dots Bullets and TeX
X\subsection{Dots}
X\findex{dots}
X\cindex{Inserting dots}
X\cindex{Dots, inserting}
X
X
X\code{\back dots} generates an ellipsis which is three dots in a row,
Xappropriately spaced, like this: `\dots'. Do not simply write three
Xperiods in the input file; that would work for the Info file output, but
Xwould produce the wrong amount of space between the periods in the printed
Xmanual.
X
X\begin{iftex}
XHere is an ellipsis: \dots
X
XHere are three periods in a row: ...
X
XThe three periods in a row are closer together than the dots in the ellipsis.
X
X\end{iftex}
X
X\node Bullet, TeX, Dots, Inserting Dots Bullets and TeX
X\subsection{Bullet}
X\cindex{Bullet}
X\findex{bullet}
X
X\code{\back bullet} generates a large round dot, or the closest possible
Xthing to one.
X
XHere is a bullet: \bullet
X
X\node TeX, Emphasizing Text, Bullet, Inserting Dots Bullets and TeX
X\subsection{TeX}
X\cindex{TeX}
X\findex{TeX}
X\findex{LaTeX}
X
X\code{\back TeX} generates `\TeX'. In a printed manual, this is a
Xspecial logo that is different from three ordinary letters.
X\code{\back LaTeX} generates `\LaTeX'. In a printed manual, this is
Xa special logo that is different from five ordinary letters.
X
X
X\node Emphasizing Text, Emph and Strong, TeX, Marking Text Within a Paragraph
X\section{Emphasizing Text}
X\cindex{Emphasizing text}
X
XUsually, \LaTeX info changes the font automatically to mark words in the
Xtext according to what category the words belong to. The \code{\back code}
Xcommand, for example, does this. Most often, this is the best way to mark
Xspecified words. However, sometimes you will want to emphasize text
Xdirectly. \LaTeX info has two ways to do this: commands that tell
X\LaTeX info to emphasize the text but leave the method to the program, and
Xcommands that specify the font to use. The first method is generally the
Xbest and it makes it possible to change the style of a document without
Xhave to re-edit it line by line.
X
X\begin{menu}
X* Emph and Strong:: Emphasizing text.
X* Fonts:: Selecting italic, bold or typewriter fonts.
X\end{menu}
X
X\node Emph and Strong, Fonts, Emphasizing Text, Emphasizing Text
X\subsection{Emph and Strong}
X\cindex{Emph and Strong}
X\findex{emph}
X\findex{strong}
X
X\code{\back emph} and \code{\back strong} are two forms of emphasis. \code{\back strong}
Xis stronger.
X
XIn printed output, \code{\back emph} produces \emph{italics} and
X\code{\back strong} produces \strong{bold}. In the Info file, both of
Xthese commands put asterisks around the argument.
X
X\node Fonts, Input and Include Files, Emph and Strong, Emphasizing Text
X\subsection{Fonts}
X\cindex{Fonts}
X\findex{i (italic font)}
X\findex{b (bold font)}
X\findex{t (typewriter font)}
X
XThese three commands specify font changes in the printed manual and have no
Xeffect in the Info file. \code{\back i} requests \i{italic} font (in some
Xversions of \LaTeX, a slanted font is used), \code{\back b} requests \b{bold}
Xface, and \code{\back t} requests the \t{fixed-width} font used by
X\code{\back kbd}. All three commands apply to an argument that follows,
Xsurrounded by braces.\refill
X
XIf possible, you should avoid using these three commands. If you find a
Xneed to use one, it probably indicates a lack in the \LaTeX info language.
X
X\node Input and Include Files, Input Files, Fonts, Top
X\chapter{Input and Include Files}
X\cindex{Input and Include Files}
X
XWhen Info was first created, it was customary to create many small Info
Xfiles on one subject. By doing this, Emacs did not have to make a large
Xbuffer to hold the whole of a large Info file; instead, Emacs allocated
Xjust enough memory for the small Info file that was needed at the time.
XThis way, Emacs could avoid wasting memory. Include Files were designed
Xas a way to create a single, large printed manual out of several smaller
XInfo files. However, because large Info files can now be split, include
Xfiles are no longer strictly necessary and they are used infrequently.
XMost often, they are now used in projects where several different people
Xare writing different sections of a document simultaneously.
X
XInput files are simply inserted at the place where the \code{input} command
Xoccurs, both in the Infor file and the \LaTeX\ file.
X
X\begin{menu}
X* Input Files::
X* Include Files::
X\end{menu}
X
X\node Input Files, Include Files, Input and Include Files, Input and Include Files
X\section{Input Files}
X\cindex{Input Files}
X\findex{input}
X
XA line of the form \code{\back input\{\var{filename}\}} will include the
Xcontents of the file \var{filename} at that point. A standard technique is
Xto have a special file, used only for making a comprehensive manual,
Xcontaining nothing but the beginning, the end, and a series of \code{\back
Xinput} commands. The \code{\back input} \emph{must} occur at the beginning
Xof a line.
X
XA file that is intended to be processed with \code{\back input}
Xshould not end with \code{\back end\{document\}}, since that would
Xterminate \LaTeX\ processing immediately.
X
X
X\node Include Files, Conditionals, Input Files, Input and Include Files
X\section{Include Files}
X\cindex{Include Files}
X\findex{include}
X
XIn a \LaTeX info file, the command \code{\back include\{filename\}} is
Xignored when the Info file is generated, but in a printed manual it
Xcauses the contents of the file \file{filename} to be processed and
Xincluded in the manual. The contents of the file
X\file{filename} can be ignored by Info because the first file can refer
Xto \file{filename} with menus as well as cross references. In the Info
Xsystem, all the information is, as it were, `in one place'. However,
Xwhen two printed manuals are made from two separate \LaTeX info files,
Xthe two manuals are separate, and even if they give each other as
Xreferences, the references are to separate documents. Consequently, you
Xwill sometimes want to create a comprehensive, printed manual that
Xcontains all the necessary information together in one place.
X
X\code{\back include} files are special \LaTeX info files that are used only for
Xmaking such a comprehensive manual. They are listed inside an outer file
Xthat contains nothing but the beginning and end matter of a \LaTeX info file
Xand a number of \code{\back include} commands listing the included files.
X
XAn \code{\back include} file should not start with
X\samp{\back documentstyle[latexinfo]}, as that has already been done by
Xthe outer file, and the character \samp{\back } has already been
Xredefined to generate a backslash in the output. Instead, a \code{\back
Xinclude} file usually begins with a node; it lacks the beginning and
Xending of a
X\LaTeX info file that are described in the chapters on beginning and
XEnding a LaTeXinfo File. \xref{Beginning a LaTeXinfo File}, and
X\pxref{Ending a LaTeXinfo File}. Likewise, a \code{\back include} file
Xshould not end with \code{\back end\{document\}}, since that would
Xterminate \LaTeX\ processing immediately.\refill
X
XHere is an example of a outer \LaTeX info file with \code{\back include} files
Xwithin it:\refill
X
X\clearpage
X\begin{verbatim}
X\documentstyle[11pt,twoside,latexinfo]{report}
X\pagestyle{headings}
X\begin{document}
X\bibliographystyle{alpha}
X
X\newindex{cp}
X
X\title{The Manual}
X
X\author{Fred Foobar,\\
X Clarke Institute,\\
X 999 Queen Street,\\
X Toronto, Ontario}
X
X\date{\today}
X
X\maketitle
X\tableofcontents
X\clearpage
X
X\setfilename{themanual.info}
X
X\include{foo.texinfo}
X\include{bar.texinfo}
X
X\begin{tex}
X\bibliography{references}
X\end{tex}
X
X\twocolumn
X \chapter*{Function Index}
X \printindex{fn}
X
X \chapter*{Variable and Data Type Index}
X \printindex{vr}
X
X\end{document}
X\end{verbatim}
X
X\node Conditionals, Using LaTeX Commands, Include Files, Top
X\chapter{Conditionals}
X\cindex{Conditionals}
X\cindex{Ifinfo}
X\cindex{Iftex}
X\findex{ifinfo}
X\findex{iftex}
X\findex{ignore}
X
XYou may not always be able to use the same text for both the printed manual
Xand the on-line Info file. In this case, you can use the conditional
Xenvironments to specify which text is for the printed manual and which is for
Xthe Info file.
X
X\code{\back begin\{ifinfo\}} begins text that should be ignored by
X\LaTeX\ when it typesets the printed manual. The text appears only
Xin the Info file. The \code{\back begin\{ifinfo\}} command should appear on a
Xline by itself. End the info-only text with a line containing
X\code{\back end\{ifinfo\}} by itself. At the beginning of a \LaTeX info file,
Xthe Info permissions are contained within a region marked by
X\code{\back begin\{ifinfo\}} and \code{\back end\{ifinfo\}}.\refill
X
XLikewise, \code{\back begin\{iftex\}} and \code{\back end\{iftex\}}
Xlines delimit text that will not appear in the Info file but will appear
Xin the printed manual.\refill
X
XFor example,
X
X\begin{verbatim}
X\begin{iftex}
XThis text will appear only in the printed manual.
X\end{iftex}
X
X\begin{ifinfo}
XHowever, this text will appear only in the info manual.
X\end{ifinfo}
X\end{verbatim}
X
X\noindent
XThe preceding example produces the following. Note how you only see one of
Xthe two lines, depending on whether you are reading the on-line Info version
Xor the printed version of this manual.
X
X\begin{iftex}
XThis text will appear only in the printed manual.
X\end{iftex}
X
X\begin{ifinfo}
XHowever, this text will appear only in the info manual.
X\end{ifinfo}
X
X\code{\back begin\{ignore\}} and \code{\back end\{ignore\}}
Xlines delimit text that will not appear in either the Info file or
Xthe printed manual.\refill
X
X
X\begin{menu}
X* Using LaTex Commands:: Using commands from regular LaTeX.
X\end{menu}
X
X\node Using LaTeX Commands, Printing Hardcopy, Conditionals, Conditionals
X\section{Using LaTeX Commands}
X\cindex{Using LaTeX Commands}
X\cindex{LaTeX commands, using them}
X
XInside a region delineated by \code{\back begin\{iftex\}} and
X\code{\back end\{iftex\}}, you can embed ordinary \LaTeX\ commands. Info
Xwill ignore these commands since they are only in that part of the file
Xthat is seen by \LaTeX. Note that you still have the characters \code{#
X$ % ^ & _ |} all printing as normal characters. You can enter \LaTeX\
Xcompletely, by delineating a region with the \code{\back begin\{tex\}}
Xand \code{\back end\{tex\}} commands. For example,\refill
X
X\begin{verbatim}
X\begin{tex}
X\bibliography{references}
X\end{tex}
X\end{verbatim}
X
X\noindent
Xis how you would include a \LaTeX\ bibliography.
XIn the Info file, nothing between \code{\back begin\{tex\}} and
X\code{\back end\{tex\}} will appear, i.e\. \code{tex} implies \code{iftex}.
X.\refill
X
X\node Printing Hardcopy, Formatting Requirements, Using LaTeX Commands, Top
X\chapter{Printing Hardcopy}
X\cindex{Printing hardcopy}
X\cindex{Hardcopy, printing it}
X\cindex{Making a printed manual}
X\cindex{Sorting indices}
X\cindex{Indices, sorting}
X\findex{texindex (for sorting indices)}
X
XThere are three shell commands for printing a hardcopy of a \LaTeX info file.
XOne is for formatting the file, the second is for sorting the index and the
Xthird is for printing the formatted document. When you use the shell
Xcommands, you can either work directly in the operating system shell or
Xwork within a shell inside of GNU Emacs.
X
XThe typesetting program \LaTeX\ is used for formatting a \LaTeX info
Xfile. \LaTeX\ is a very powerful typesetting program and, if used
Xright, does an exceptionally good job. The commands in a \LaTeX info
Xfile are defined by a file called \file{latexinfo.sty} into make \LaTeX\
Xunderstand them. (That is why the beginning of every \LaTeX info file
Xstarts with the line that says \samp{\back documentstyle[latexinfo]};
Xthis command tells \LaTeX\ to use the\*
X\file{latexinfo.sty} file in processing the \LaTeX info file.)
X\code{latexinfo-format-buffer} reads the very same commands in the
X\LaTeX info file and processes them differently from \LaTeX\ to make an
XInfo file.\refill
X
XUsually, the \LaTeX\ formatting command is the shell command \code{latex}
Xfollowed by the name of the \LaTeX info file. The \LaTeX\ command produces a
Xformatted DVI file as well as several auxiliary files containing indices,
Xcross references, etc. The DVI file (for \dfn{DeVice Independent} file)
Xcan be printed on a wide variety of printers.\refill
X
XThe \LaTeX\ formatting command itself does not sort the indices. Hence,
Xto generate a printed index, you first need a sorted index to work from.
X\LaTeX\ outputs raw, unsorted index files under names that obey a
Xstandard convention. These names are the name of your main input file
Xto \LaTeX, with everything after the first period thrown away, and the
Xtwo letter names of indices added at the end. For example, the raw
Xindex output files for the input file \file{foo.texinfo} would be
X\file{foo.cp}, \file{foo.vr}, \file{foo.fn}, \file{foo.tp},
X\file{foo.pg} and \file{foo.ky}. Those are exactly the arguments to
Xgive to \code{texindex}. Or else, you can use \samp{??} as
X``wild-cards'' and give the command in this form:\refill
X
X\begin{example}
Xtexindex foo.??
X\end{example}
X
XFor each file specified, \code{texindex} generates a sorted index file
Xwhose name is made by appending \samp{s} to the input file name. The
X\code{\back printindex} command knows to look for a file of that name.
X\code{texindex} does not alter the raw index output file. After you have
Xsorted the indices, you need to rerun the \LaTeX\ command on the \LaTeX info
Xfile. This regenerates a formatted DVI file with the index entries in the
Xcorrect order.\refill
X
XTo summarize, this is a three step process:
X
X\begin{enumerate}
X\item
XRun the \LaTeX\ command on the \LaTeX info file. This generates the formatted
XDVI file as well as the raw index files with two letter extensions.\refill
X
X\item
XRun the shell command \code{texindex} on the raw index files to sort them.
XThe arguments to \code{texindex} are the names of the raw index files.
X\code{texindex} creates sorted index files whose names are the names of the
Xraw index files with an \samp{s} appended. To cause \code{texindex} to
Xsort all the raw index files, append \samp{??} to the \LaTeX info file name in
Xplace of the \file{.texinfo} extension.\refill
X
X\item
XRerun the \LaTeX\ command on the \LaTeX info file. This regenerates a formatted
XDVI file with the index entries in the correct order. This second run also
Xmakes all the cross references correct as well. (The tables of contents
Xare always correct.)\refill
X\end{enumerate}
X
XIf you are including a bibliography, you should also run the
X\code{bibtex} command on the file between steps 1 and 3. You need not
Xrun \code{texindex} after each \LaTeX\ run. If you don't, the next
X\LaTeX\ run will use whatever sorted index files happen to exist from
Xthe previous use of \code{texindex}. This is usually ok while you are
Xdebugging.
X
XFinally, the document can be printed out with the DVI print command
X(a shell command). Depending on the system used, the DVI print command
Xwill be a command such as \code{lpr -d}. The DVI print command may require
Xa file name with the \samp{.dvi} extension.
X
XThe following commands, for example, sort the indices, format and print the
XBison Reference Manual (\cite{BisonReferenceManual}) (where \samp{%} is the
Xshell prompt):
X
X\begin{example}
X% latex bison.texinfo
X% texindex bison.??
X% bibtex bison
X% latex bison.texinfo
X% lpr -d bison.dvi
X\end{example}
X
X\noindent
X(Remember that the words for the shell commands may be different at your
Xsite; but these are commonly used versions.)
X
XIt is often most convenient to give formatting and printing commands from a
Xshell within GNU Emacs. This way, you can easily keep track of errors. To
Xcreate a shell within Emacs, type \kbd{M-x shell}. In this shell, you can
Xformat and print the document. You can switch to and from this shell while
Xit is running and do other things. If you are formatting a very long
Xdocument on a slow machine, this can be very convenient; on a VAX 750, for
Xexample, formatting often takes 8 seconds or more per page depending on how
Xloaded the computer is. Faster machines take correspondingly less time.
X
X
X\begin{menu}
X* Formatting Requirements::
X* Using Local Variables and the Compile Command::
X\end{menu}
X
X\node Formatting Requirements, Using Local Variables and the Compile Command, Printing Hardcopy, Printing Hardcopy
X\section{Formatting Requirements}
X\cindex{Requirements for formatting }
X\cindex{Formatting requirements}
X
XEvery \LaTeX info file that is to be input to \LaTeX\ must begin with a line
Xthat looks like
X
X\begin{verbatim}
X\documentstyle[12pt,twoside,latexinfo]{report} \c -*-latexinfo-*-
X\end{verbatim}
X
X\noindent
XThis serves two functions.
X
X\begin{enumerate}
X\item
XWhen the file is processed by \LaTeX, it loads the macros needed for
Xprocessing a \LaTeX info file.\refill
X\item
XWhen the file is edited in Emacs, it causes LaTeXinfo Mode to be used.\refill
X\end{enumerate}
X
XEvery \LaTeX info file must end with a line saying
X
X\begin{verbatim}
X\end{document}
X\end{verbatim}
X
Xwhich terminates \LaTeX\ processing and forces out unfinished pages.
X
XYou also have to include a line that specifies the Info file name.
X
X\begin{example}
X\back setfilename\{\var{name-of-latexinfo-file}\}
X\end{example}
X
XBy default, \LaTeX\ typesets pages for printing in an 8.5 by 11 inch
Xformat. However, you can direct \LaTeX\ to typeset a document in a 7 by
X9.25 inch format that is suitable for bound books by inserting the
Xfollowing command on a line by itself at the beginning of the \LaTeX info
Xfile, before the \code{\back setfilename} command:
X
X\begin{example}
X\back smallbook
X\end{example}
X
X\noindent
XThe Free Software Foundation distributes printed copies of the
XGNU Emacs Manual \cite{GNUEmacsManual} in this size.
X
XFinally, \LaTeX\ sometimes is unable to typeset a line without extending
Xit into the right margin. This can occur when \LaTeX\ comes upon what it
Xinterprets as a long word that it cannot hyphenate, like a net address,
Xor a very long title. When this happens, \LaTeX\ prints an error message
Xlike this:
X
X\begin{example}
XOverfull \back hbox (20.76302pt too wide)
X\end{example}
X
X\noindent
Xand gives the line number along with the text of the offending line
Xmarked at all the places that \LaTeX\ knows to hyphenate words. (In
X\LaTeX\ lines are in `horizontal boxes', hence the term, `hbox'.)
X
XIf the \LaTeX info file has an overfull hbox, you can rewrite the sentence
Xso the overfull hbox does not occur or you can decide to leave it. A
Xsmall excursion into the right margin often does not matter and may not
Xeven be noticable. However, unless told otherwise, \LaTeX\ will print a
Xlarge, ugly, black rectangle beside every line that is overfull. This is
Xso you will notice the location of the problem if you are correcting a
Xdraft. To prevent such monstrosities from marring your final printout,
Xput the following in the beginning of the \LaTeX info file before the \code{\back setfilename} command:
X
X\begin{verbatim}
X\finalout
X\end{verbatim}
X
X\xref{Titlepage}, for information about creating a title page.
X\xref{Generating a Table of Contents}, for information about creating a
Xtable of contents.\refill
X
X\node Using Local Variables and the Compile Command, Creating an On-line Info File, Formatting Requirements, Printing Hardcopy
X\section{Using Local Variables and the Compile Command}
X\cindex{Using Local Variables and the Compile Command}
X\cindex{Local variables}
X\cindex{Compile command for formatting}
X\cindex{Formatting with the compile command}
X
XAnother way to give the \LaTeX\ formatting command to \LaTeX info is to
Xput that command in a \dfn{local variables list} at the end of the
X\LaTeX info file. You can then specify the \LaTeX\ formatting command
Xas a \code{compile-command} and have Emacs run the \LaTeX\ formatting
Xcommand by giving the command \kbd{M-x compile}. This creates a special
Xshell called the \samp{*compilation buffer*}. For example, at the end
Xof the \file{gdb.texinfo} file, after the \code{\back end\{document\}},
Xyou would put the following:\refill
X
X\begin{example}
X\back c Local Variables:
X\back c compile-command: "latex gdb.texinfo"
X\back c End:
X\end{example}
X
X\noindent
XThis technique is most often used by programmers who compile programs
Xthis way.
X
X\node Creating an On-line Info File, Installing an Info file, Using Local Variables and the Compile Command, Top
X\chapter{Creating an On-line Info File}
X\cindex{Creating an on-line Info file}
X\cindex{Running Info}
X\cindex{Info, creating an on-line file}
X\cindex{Formatting a file for Info}
X\cindex{Indirect subfiles}
X\findex{latexinfo-format-buffer}
X
XIn GNU Emacs, using LaTeXinfo Mode, you can see what part or all of a
X\LaTeX info file will look like in Info by using the keyboard command
X\ctrl{c} \ctrl{f} (\code{latexinfo-format-region}). This formats a region
Xand displays in a temporary buffer called \samp{*Info Region*}; however,
Xthis command does not turn on Info reading program---it just displays
Xwhat the region will look like. The \code{latexinfo-format-region}
Xcommand is described more extensively in the chapter on using LaTeXinfo
XMode. \xref{Formatting a Region for Info}.
X\refill
X
XIn GNU Emacs, the way to create a working Info file is to visit the file
Xand invoke
X
X\begin{example}
X\kbd{M-x latexinfo-format-buffer}
X\end{example}
X
X\noindent
XA new buffer is created and the Info file text is generated there.
X\ctrl{x} \ctrl{s} will save it under the name specified in the
X\code{\back setfilename} command.\refill
X
XIf the \LaTeX info file has more than 30,000 bytes,
X\code{latexinfo-format-buffer} will automatically create a \dfn{tag
Xtable} for it. With a tag table, Info can jump to new nodes more
Xquickly than it can otherwise. In addition, if the file has more than
X100,000 bytes in it, \code{latexinfo-format-buffer} will split the file
Xinto shorter Indirect subfiles of about 50,000 bytes each. Files are
Xsplit so that Info does not have to make a large buffer to hold the
Xwhole of a large Info file; instead, Info allocates just enough memory
Xfor the small, split off file that is needed at the time. This way,
XEmacs avoids wasting memory when you run Info. (Before splitting was
Ximplemented, Info files were always short and \dfn{include} files were
Xdesigned as a way to create a single, large printed manual out of the
Xsmaller Info files. \xref{Input and Include Files}, for more
Xinformation.)\refill
X
XWhen the file is split, Info itself works through a shortened version of
Xthe original file that contains the tag table and references to the files
Xthat were split off. The split off files are called \dfn{indirect} files.
X
XThe split off files have names that are created by appending \samp{-1},
X\samp{-2}, \samp{-3} and so on to the file names specified by the
X\code{\back setfilename} command. The shortened version of the original file
Xcontinues to have the name specified by \code{\back setfilename}.
X
XAt one stage in writing this document, for example, the Info file was saved
Xas \file{test-texinfo} and that file looked like this:
X
X\begin{example}
XInfo file: test-texinfo, -*-Text-*-
Xproduced by latexinfo-format-buffer
Xfrom file: new-texinfo-manual.texinfo
X
X^_
XIndirect:
Xtest-texinfo-1: 102
Xtest-texinfo-2: 50422
Xtest-texinfo-3: 101300
X^_^L
XTag table:
X(Indirect)
X\dots
X\end{example}
X
X\noindent
X(But \file{test-texinfo} had far more nodes than are shown here.) Each of
Xthe split off, indirect files, \file{test-texinfo-1},
X\file{test-texinfo-2}, and \file{test-texinfo-3}, is listed in this file
Xafter the line that says \samp{Indirect:}. The tag table is listed after
Xthe line that says \samp{Tag table:}. \refill
X
XYou cannot run the \kbd{M-x Info-validate} node checking command on indirect
Xfiles. For information on how to prevent files from being split and how to
Xvalidate the structure of the nodes, \pxref{Info-Validating a Large
XFile}\refill
X
X
X\begin{menu}
X* Installing an Info file::
X* Extending LaTeXinfo::
X\end{menu}
X
X\node Installing an Info file, Extending LaTeXinfo, Creating an On-line Info File, Creating an On-line Info File
X\section{Installing an Info file}
X\cindex{Installing an Info file}
X\cindex{Info file installation}
X\cindex{Dir directory for Info installation}
X
XAn Info file is usually installed in the GNU Emacs directory called
X\file{info}. This directory is the values of the Emacs variable
X\code{Info-directory}. For Info to work, this directory must contain
Xall the Info files, including the split off files. In addition, the
X\file{info} directory must have a file that serves as a top level
Xdirectory for the Info system. This file is called \file{dir}.
X
X
XFor example, in the \file{info} directory, the file called \file{dir}
Xhas the top level menu for all the Info files in the system. This
Xdirectory is the one defined by the GNU Emacs variable
X\code{Info-directory}. This file has a master menu that looks like
Xthis:
X
X\begin{example}
X* Menu:
X
X* Info: (info). Documentation browsing system.
X* Emacs: (emacs). The extensible self-documenting text editor.
X* Texinfo: (texinfo). With one source file, make either a printed
X manual using TeX or an Info file using
X Texinfo.
X\end{example}
X
XTo add a new Info file, just add it to this menu. For example, if you
Xwere adding documentation for GDB, you would make the following entry:
X
X\begin{example}
X* GDB: (gdb). The source-level C debugger.
X\end{example}
X
X\noindent
XThe first item is the menu item name; it is followed by a colon. The
Xsecond item is the name of the Info file, in parentheses; it is followed by
Xa period. The third part of the entry is the description of the item.
X
X
XThe top node of the file, named \samp{top}, should have as its parent the
Xname of a node in another file, where there is a menu that leads to this
Xfile. Specify the file name in parentheses. If the file is to be
Xinstalled directly in the Info directory file, use \samp{(dir)} as the
Xparent of the top node; this is short for \samp{(dir)top}, the node \samp{top}
Xin the file \file{dir}, which is the main menu of Info.
X
X\node Extending LaTeXinfo, Catching Mistakes, Installing an Info file, Creating an On-line Info File
X\section{Extending LaTeXinfo}
X\cindex{Extending LaTeXinfo}
X\cindex{LATEXINFO environment variable}
X\cindex{environment variable, LATEXINFO}
X
XLet's say that you wanted to develop a special format for a program
Xcalled \code{macsyma}, which defined the command \code{\back f} to be
Xused for specifying function. This command would put its argument in
Xthe function index, and set the function in the printed manual in a
Xspecial font. You could create a style file called \file{macsyma.sty}
Xthat contained this definition (and any others you might want for
XMacsyma). The \LaTeX\ commands to do this are quite simple:
X
X\begin{verbatim}
X\def\f#1{\findex{#1}{\sf #1}}
X\end{verbatim}
X
X\noindent
XThen you include \code{macsyma} in the list of options to the
X\code{documentstyle} command, \emph{after} the \code{latexinfo} option.
XYour \LaTeX info file would begin with
X
X\begin{verbatim}
X\documentstyle[12pt,twoside,latexinfo,macsyma]{report}
X\end{verbatim}
X
XBut what about the Info file? As it stands, the command \code{\back f}
Xis not defined in \LaTeX info, so when you formatted the buffer it would
Xignore all the \code{\back f} commands, and their arguments. You need
Xto introduce the appropriate Emacs lisp code to provide the definition
Xof the command that you have added. For each option in the
X\code{documentstyle} command, \LaTeX info looks to see if the file name
X\var{option}\code{-fmt.el} exists in the directory defined by the Emacs
Xvariable \code{latexinfo-formats-directory}. (This variable defaults to
Xthe value of the environment variable \code{LATEXINFO}). If it does
Xexist, then it loads this file. So continuing with our example, if the
Xfile \file{macsyma-fmt.el} contained the code
X
X\begin{example}
X(put 'f 'latexinfo-format 'latexinfo-format-code)
X\end{example}
X
X\noindent
Xthen it would define the \code{\back f} command to treat its argument
Xthe same way that the \code{\back code} command does.
X
XAfter the \var{option}\code{-fmt.el} has been loaded, \LaTeX info checks
Xto see if a function (of no arguments) called \var{option}\code{-fmt-hook}
Xhas been defined. If so, this function is called. This allows you to
Xdefine functions in the \var{option}\code{-fmt.el} file that operate
Xon the whole \LaTeX info file.
X
X\LaTeX\ provides a number of optional style files by default. These include
X\code{latexinfo, 11pt, 12pt, twoside} and \code{titlepage}. If any of
Xthe optional styles is a member of the Emacs variable
X\code{latexinfo-known-document-styles}, then \LaTeX info does not bother to
Xlook for the associated \code{-fmt} file.
X
X\node Catching Mistakes, Catching Errors with Info Formatting, Extending LaTeXinfo, Top
X\chapter{Catching Mistakes}
X\cindex{Structure of LaTeXinfo, catching mistakes}
X\cindex{Nodes, catching mistakes}
X\cindex{Nodes, correcting mistakes}
X\cindex{Catching mistakes}
X\cindex{Correcting mistakes}
X\cindex{Mistakes, catching}
X\cindex{Problems, catching}
X\cindex{Debugging the LaTeXinfo structure}
X
XBesides mistakes with the content of what ever you are describing, there
Xare two kinds of mistake you can make with \LaTeX info: you can make
Xmistakes with commands, and you can make mistakes with the structure of
Xthe nodes and chapters. There are two tools for catching the first kind
Xof mistake and two for catching the second.
X
XFor finding problems with commands, your best action is to run\*
X\kbd{M-x latexinfo-format-region} on regions of your file as you write
Xit. In \LaTeX info mode, the \code{latexinfo-format-region} command is
Xbound to \ctrl{c} \ctrl{f}. In addition, you can run \LaTeX\ on the
Xwhole file.\refill
X
XFor finding problems with the structure of nodes and chapters, you can
Xuse \ctrl{c} \ctrl{s} (\code{latexinfo-show-structure}) (and the related
X\code{occur} command) and you can use the \kbd{M-x Info-validate}
Xcommand.
X
X\begin{menu}
X* Catching Errors with Info Formatting::
X* Catching Errors with LaTeX Formatting::
X* Using latexinfo-show-structure::
X* Finding Badly Referenced Nodes::
X\end{menu}
X
X\node Catching Errors with Info Formatting, Using the Emacs Lisp Debugger, Catching Mistakes, Catching Mistakes
X\section{Catching Errors with Info Formatting}
X\cindex{Catching errors with Info Formatting}
X\cindex{Debugging with Info Formatting}
X
XAfter you have written part of a \LaTeX info file, you can use the\*
X\kbd{M-x latexinfo-format-region} command to see whether the region
Xformats properly. In LaTeXinfo Mode, this command is bound to the
Xkeyboard command \ctrl{c} \ctrl{f}. If you have made a mistake with a
Xcommand, \kbd{M-x latexinfo-format-region} will stop processing at or
Xafter the error and give an error message. To see where in the file the
Xerror occurred, switch to the \samp{*Info Region*} buffer; the cursor
Xwill be in a position that is after the location of the error. Also,
Xthe text will not be formatted after the place the error occurred.\refill
X
XThe \code{latexinfo-format-region} command does not always recognize errors.
XFor example, no errors were reported when \code{latexinfo-format-region} was
Xrun on the whole itemized list of which the following is a part:
X
X\begin{example}
Xname of the \LaTeX info file as an extension. The \back samp\{??\} are
X`wildcards' that cause the shell to substitute all the raw index files.
X(\back xref\{sorting indices), for more information about sorting indices.)
X \back refill
X\back cindex\{Sorting indices\}
X\back cindex\{Indices, sorting\}
X
X\back item
X\back emph\{Third\}, rerun the \back TeX\ command on the \LaTeX info file.
XThis regenerates a formatted DVI file with the index entries in the
Xcorrect order. This second run also makes all the cross references
Xand table of contents correct as well.
X\end{example}
X
X\noindent
XInstead, \code{latexinfo-format-region} ran without reporting the error, but
Xit produced output that looked like this:
X
X\begin{example}
X name of the latexinfo file as an extension. The `??' are `wildcards'
X that cause the shell to substitute all the raw index files. (*Note for more information about sorting indices.) \back refill \back cindex Sorting indices \back cindex Indices: sorting indices), rerun the TeX command on the latexinfo file. This
X regenerates a formatted DVI file with the index entries in the correct
X order. This second run also makes all the cross references and table of
X contents correct as well.
X\end{example}
X
X\noindent
XHowever, when \code{latexinfo-format-region} was run on part of the list that
Xis shown, it did give an error message, \samp{Search failed: "[\},]"}.
X(This error message is explained in the section on using the Emacs Lisp
XDebugger, \pxref{Using the Emacs Lisp Debugger})
X
XSometimes \code{latexinfo-format-region} will stop long after the original
Xerror; this is because it does not discover the problem until then. In this
Xcase, you will have to backtrack.\refill
X
X\node Using the Emacs Lisp Debugger, Catching Errors with LaTeX Formatting, Catching Errors with Info Formatting, Catching Errors with Info Formatting
X\subsection{Using the Emacs Lisp Debugger}
X\cindex{Using the Emacs Lisp debugger}
X\cindex{Emacs Lisp debugger}
X\cindex{Debugger, using the Emacs Lisp }
X
XIf an error is especially elusive, you can turn on the Emacs Lisp debugger
Xand look at the backtrace; this tells you where in the
X\code{latexinfo-format-region} function the problem occurred. You can turn
Xon the debugger with the command:\refill
X
X\begin{example}
XM-x set-variable \key{RET} debug-on-error \key{RET} t \key{RET}
X\end{example}
X
X\noindent
Xand turn it off with
X
X\begin{example}
XM-x set-variable \key{RET} debug-on-error \key{RET} nil \key{RET}
X\end{example}
X
XOften, when you are using the debugger, it is easier to follow what is
Xgoing on if you use the Emacs Lisp files that are not byte-compiled. The
Xbyte-compiled files are read as octal numbers by the debugger that may look
Xmysterious. To use the uncompiled source files, load \file{latexinfo.el}
Xand \file{latexinfo-mode.el} with the \kbd{M-x load-file} command.\refill
X
XThe debugger will not catch an error if \code{latexinfo-format-region} does
Xnot detect one. In the example shown above, \code{latexinfo-format-region}
Xdid not find the error when the whole list was formatted, but only when
Xpart of the list was formatted. When \code{latexinfo-format-region} did not
Xfind an error, the debugger did not find one either. \refill
X
XHowever, when \code{latexinfo-format-region} did report an error, it invoked
Xthe debugger. This is the backtrace it produced:
X
X\begin{example}
XSignalling: (search-failed "[\},]")
X re-search-forward("[\},]")
X (while ...)
X (let ...)
X latexinfo-format-parse-args()
X (let ...)
X latexinfo-format-xref()
X funcall(latexinfo-format-xref)
X (if ...)
X (let ...)
X (if ...)
X (while ...)
X latexinfo-format-scan()
X (save-excursion ...)
X (let ...)
X latexinfo-format-region(103370 103631)
X* call-interactively(latexinfo-format-region)
X\end{example}
X
XThe backtrace is read from the bottom up. \code{latexinfo-format-region} was
Xcalled interactively; and it in turn called various functions, including
X\code{latexinfo-format-scan}, \code{latexinfo-format-xref}\*
Xand \code{latexinfo-format-parse-args}. Inside the function
X\code{latexinfo-format-parse-args}, the function \code{re-search-forward} was
Xcalled; it was this function that could not find the missing right hand
Xbrace.\refill
X
X\xref{Lisp Debug, , Debugging Emacs Lisp, emacs, The GNU Emacs Manual}, for
Xmore information.\refill
X
X
X\node Catching Errors with LaTeX Formatting, Using latexinfo-show-structure, Using the Emacs Lisp Debugger, Catching Mistakes
X\section{Catching Errors with LaTeX Formatting}
X\cindex{Catching errors with LaTeX formatting}
X\cindex{Debugging with LaTeX Formatting}
X
XYou can also catch mistakes when you format a file with \LaTeX.
XUsually, you will want to do this after you have run
X\code{latexinfo-format-buffer} on the same file.
X\code{latexinfo-format-buffer} is usually faster and sometimes gives
Xerror messages that make more sense. \xref{Catching Errors with Info
XFormatting}, for more information.\refill
X
X\clearpage
XFor example, \LaTeX\ was run on the same itemized list discussed in the
Xsection on the use of \code{latexinfo-format-region}; the fragment with
Xthe error looked like this:
X
X\begin{example}
Xname of the latexinfo file as an extension. The \back samp\{??\} are `wildcards'
Xthat cause the shell to substitute all the raw index files. (\back xref\{sorting
END_OF_FILE
if test 39490 -ne `wc -c <'manual/latexinfo.tex-ad'`; then
echo shar: \"'manual/latexinfo.tex-ad'\" unpacked with wrong size!
fi
# end of 'manual/latexinfo.tex-ad'
fi
echo shar: End of archive 6 \(of 9\).
cp /dev/null ark6isdone
MISSING=""
for I in 1 2 3 4 5 6 7 8 9 ; do
if test ! -f ark${I}isdone ; then
MISSING="${MISSING} ${I}"
fi
done
if test "${MISSING}" = "" ; then
echo You have unpacked all 9 archives.
rm -f ark[1-9]isdone ark[1-9][0-9]isdone
else
echo You still need to unpack the following archives:
echo " " ${MISSING}
fi
## End of shell archive.
exit 0
--
Mike Clarkson mike@ists.ists.ca
Institute for Space and Terrestrial Science uunet!attcan!ists!mike
York University, North York, Ontario, FORTRAN - just say no.
CANADA M3J 1P3 +1 (416) 736-5611