\documentstyle[12pt,latexinfo,format,smallverb,tabular]{book}
\pagestyle{empty}

\begin{document}
\bibliographystyle{alpha}

\newindex{cp}
\newindex{fn}

\finalout

\title{The \LaTeX info Documentation Format\\
 	{\normalsize Version \latexinfoversion}}

\author{Richard M. Stallman
	and Robert J. Chassell\\
	The Free Software Foundation,\\
	675 Massachusetts Ave., Cambridge MA,\\
	\and  Michael Clarkson\\
	Institute for Space and Terrestrial Science,\\
	York University Campus,\\
	North York, Ontario, M3J 1P3}


\date{ISTS Technical Report: AI-90/1}

\maketitle

\clearpage
\vspace*{0pt plus 1filll}
Copyright \copyright{} 1988 Free Software Foundation, Inc.

This is version \latexinfoversion\ of the \LaTeX info documentation, and is
for Version 18 of GNU Emacs.

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation approved
by the Foundation.


\clearpage
\pagestyle{headings}
\pagenumbering{roman}
\tableofcontents

\clearpage
\pagenumbering{arabic}

\setfilename{latexinfo.info}
\node Top, Licensing Information, (dir)Top, (dir)Top

\begin{ifinfo}
This file documents \LaTeX info, a documentation system that uses a single
source file to produce both on--line help and a printed manual.  

This is edition \latexinfoversion\ of the \LaTeX info documentation, and is 
for Version 18 of GNU Emacs.\refill

Copyright (C) 1988 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation approved
by the Foundation.
\end{ifinfo}




\begin{menu}
* Licensing Information::
* Overview of LaTeXinfo::
* Beginning a LaTeXinfo File::
* Ending a LaTeXinfo File::
* Node and Chapter Structuring::
* Making Quotations and Examples::
* Making Lists and Descriptions::
* Making Cross References::
* Formatting Paragraphs::
* Marking Text Within a Paragraph::
* Input and Include Files::
* Conditionals::
* Printing Hardcopy::
* Creating an On-line Info File::
* Catching Mistakes::
* LaTeXinfo Mode::
* LaTeX Input Initialization::
* Standard text for Copying Permissions::
* LateXinfo and TeXinfo::
* Command Index::
* Concept Index::
\end{menu}

\node Licensing Information, Overview of LaTeXinfo, Top, Top
\unnumbered{Licensing Information}
\cindex{Licensing Information}

The programs currently being distributed that relate to \LaTeX info
include two portions of GNU Emacs, plus two other separate programs
(\code{texindex} and \code{latexinfo.sty}).  These programs are
\dfn{free}; this means that everyone is free to use them and free to
redistribute them on a free basis.  The \LaTeX info related programs are not
in the public domain; they are copyrighted and there are restrictions on
their distribution, but these restrictions are designed to permit
everything that a good cooperating citizen would want to do.  What is
not allowed is to try to prevent others from further sharing any version
of these programs that they might get from you.

  Specifically, we want to make sure that you have the right to give
away copies of the programs that relate to \LaTeX info, that you receive
source code or else can get it if you want it, that you can change these
programs or use pieces of them in new free programs, and that you know
you can do these things.

  To make sure that everyone has such rights, we have to forbid you to
deprive anyone else of these rights.  For example, if you distribute
copies of the \LaTeX info related programs, you must give the recipients all
the rights that you have.  You must make sure that they, too, receive or
can get the source code.  And you must tell them their rights.

  Also, for our own protection, we must make certain that everyone finds
out that there is no warranty for the programs that relate to \LaTeX info.
If these programs are modified by someone else and passed on, we want
their recipients to know that what they have is not what we distributed,
so that any problems introduced by others will not reflect on our
reputation.

The precise conditions of the licenses for the programs currently being
distributed that relate to \LaTeX info are found in the General Public
Licenses that accompany them.  The programs that are part of GNU Emacs are
covered by the GNU Emacs copying terms (\pxref{License, , , emacs, The GNU
Emacs Manual}), and other programs are covered by licenses that are
contained in their source files.

\node Overview of LaTeXinfo, Advantages of LaTeXinfo over TeXinfo, Licensing Information, Top
\chapter{Overview of LaTeXinfo}
\cindex{Overview of LaTeXinfo}
\cindex{LaTeXinfo overview}

\LaTeX info is a documentation system that uses a single source file for both
on--line help and a printed manual.  This means that instead of writing two
different documents, one for the on--line help and the other for the printed
manual, only one document needs to be written.  When the system is revised,
only one file has to be revised.\refill

Using \LaTeX info, you can create a document with the normal features of a
book such as chapters, sections, cross references and indices.  The
chapters and sections of the printed manual can be made to correspond to
the nodes of the on--line help.  The cross references and indices can be
used in both the on--line help and in the printed document.  Indices are
generated semi-automatically.\refill

To make the printed manual, the \LaTeX info source file is processed by the
\LaTeX\ typesetting program; the resulting DVI file can be typeset and
printed as a book.  To make the on--line help file, the \LaTeX info source
file is by processed the \kbd{M-x latexinfo-format-buffer} command from
within GNU Emacs; the resulting Info file should then be installed in the
\file{info} directory.\refill

Since the \LaTeX info source file is used for a dual task---to create both
the on--line help and the printed manual---it must be written in a special
format that uses commands (words preceded by a \samp{\back }) to
indicate chapters, sections, nodes, examples, index entries and the
like.\refill

Before writing a \LaTeX info source file, you should be familiar with the
on--line Info documentation reading program.  (\inforef{Info, info, info},
for more information.)  If you are writing a document that will be both
on--line and printed, you will need both Info and \LaTeX.

To make a printed manual, you need to use \LaTeX, which is based on the
powerful, sophisticated typesetting program written by Donald Knuth,
\TeX.  It is freely distributable. It is written in a dialect of Pascal
called WEB and can be compiled either in Pascal, or in C by using a
conversion program that comes with the \TeX\ distribution.  (For
information about getting \TeX, \pxref{TeX Mode, , , emacs, The GNU
Emacs Manual}.)

When \LaTeX\ processes a \LaTeX info source file, \LaTeX\ makes use of a
macro definitions file called \file{latexinfo.sty} (The first line of every
\LaTeX info file has a command that says \code{\back documentstyle[latexinfo]};
this tells \LaTeX{} to use the \code{latexinfo} style file.)\refill

If the \file{latexinfo.sty} file has not already been copied to the directory
which contains the other \LaTeX\ macro definition files when Emacs was
installed, you will probably want to copy it to that directory.  Usually,
this is the \file{/usr/lib/tex/macros} directory.  For more information,
\pxref{LaTeX Input Initialization, , LaTeX Input Initialization}.

\begin{menu}
* Advantages of LaTeXinfo over TeXinfo::
* Characteristics of the Info File::
* Characteristics of the Printed Manual::
* General Syntactic Conventions::
* A Short Sample LaTeXinfo File::
\end{menu}

\node Advantages of LaTeXinfo over TeXinfo, Characteristics of the Info File, Overview of LaTeXinfo, Overview of LaTeXinfo
\section{Advantages of LaTeXinfo over TeXinfo}
\cindex{Advantages of LaTeXinfo over TeXinfo}

Documentation for GNU utilities and libraries is usually written in a
format called \dfn{\TeX info}.  This document describes an enhancement
of this format which can be used with \LaTeX\ instead of \TeX.

\LaTeX info offers a number of advantages over \TeX info:

\begin{enumerate}

\item
The point size or layout style of a document can be changed easily,
as can the \code{documentstyle} (\t{article, report, book, twoside, \dots}).

\item
\LaTeX\ has better error checking than \TeX\ files, especially in
begin/end environments.  In addition, the \LaTeX\ error messages are more
informative.  This makes it considerably easier to make extensions and
enhancements (read \i{hacks}).

\item
\LaTeX\ delimits its arguments with braces, so it's easier to tell where
a \LaTeX info command starts, and where it ends.

\item
Any \LaTeX\ commands not understood by the on-line manual generator\\
(\file{latexinfo.el}) are simply ignored.  This means that you are free to add
a considerable number of \LaTeX\ commands to make you manual look pretty,
as long as you don't care that there will be no action taken by the 
Info formatting program.

\item
It is easy to add your own extensions to the on-line manual generator
by making GNU Emacs handlers for your \LaTeX\ extensions.  This is
the Emacs counterpart to the \code{documentstyle} options.  \LaTeX info looks
in a specified directory for GNU Elisp code that corresponds to each
style file.  This makes it easy to modularize your style files.

\item \LaTeX\ has many advantages over \TeX, such as being able to
incorporate the Bib\TeX\ bibliography formatting program, and is much more
widely used than either Scribe or plain \TeX.

\end{enumerate}


\node Characteristics of the Info File, Characteristics of the Printed Manual, Advantages of LaTeXinfo over TeXinfo, Overview of LaTeXinfo
\section{Characteristics of the Info File}
\cindex{Characteristics of the Info File}
\cindex{Info file characteristics}

A \LaTeX info file can be transformed into a printed manual and an on-line Info
file.

An on-line Info file is a file formatted so that the Info documentation
reading program can operate on it.  Info files are divided into pieces
called \dfn{nodes}, each of which contains the discussion of one topic.
Each node has a name, and contains both text for the user to read and
pointers to other nodes, which are identified by their names.  The Info
program displays one node at a time, and provides commands with which the
user can move to the other nodes to which the current node points.

\begin{ifinfo}
\inforef{Info, info, info}, for more information about using Info.
\end{ifinfo}

Normally, most of the nodes are arranged in a tree which branches down.
Each node may have any number of child nodes that describe subtopics of the
\dfn{menu} within the parent node; this allows certain Info commands to
be used to move to one of the child nodes.  Each child node records the
parent node name, as its `Up' pointer.  Thus, if a node were at the logical
level of a `chapter', its child nodes would be `sections'; likewise,
the child nodes of a section would be subsections.

The root of the tree is the top node of the file, through which users
enter the file from the Info directory.  By convention, this node is always
called \samp{Top}.  This node normally contains just a brief summary of the
file's purpose, and a large menu through which the rest of the file is
reached.

Generally you enter the Info file from the top; then you can either traverse
the file systematically by going from node to node or you can search large
menus that correspond to indices and go directly to the node that has the
information you want.

If you want to read through an Info file in sequence, as if it were a
printed manual, you can get the whole file with the advanced Info command
\kbd{g *}.  (\inforef{Expert, info, info}.)\refill

All the children of any one parent are linked together in a bidirectional
chain of `Next' and `Previous' pointers.  This means that all the nodes
that are logically parallel to sections within a chapter are all linked
together.  Normally the order in this chain is the same as the order of the
children in the parent's menu.  The last child has no `Next' pointer, and
the first child normally has the parent as its `Previous' pointer (as well
as its `Up' pointer, of course).

Structuring the nodes in a tree is a matter of convention, not a
requirement.  In fact, the `Up', `Previous' and `Next' pointers of a node
can point to any other nodes, and the menu can contain any other nodes.
The structure of nodes can be any directed graph.  But it is usually more
comprehensible to make it a tree.  Info provides another kind of pointer
between nodes, called a reference, that can be sprinkled through the text
of a node.  This is usually the best way to represent links that do not fit
the tree structure.

Most often the nodes fall into a strict tree structure that corresponds to
the structure of chapters and sections in the printed
manual.  But there are times when this is not right for the material being
discussed.  Therefore, \LaTeX info uses separate commands to specify the node
structure of the Info file and the section structure of the printed manual.
Also, \LaTeX info requires that you specify menus explicitly, rather than
generate them automatically based on an assumed tree structure.

\node Characteristics of the Printed Manual, General Syntactic Conventions, Characteristics of the Info File, Overview of LaTeXinfo
\section{Characteristics of the Printed Manual}
\cindex{Printed manual characteristics}
\cindex{Characteristics, printed manual}

A \LaTeX info file can be formatted and typeset as a printed manual.
The printed manual will be the same as any other book; it will have a
title page, copyright page, table of contents, and preface as you would
expect, as well as chapters, sections and subsections, not to mention
page headers, cross references and indices.
\LaTeX info can be used for writing a book without ever having the intention of
converting it into on-line help.  \LaTeX info can be used for writing a novel;
and it can even be used to write a memo.

\LaTeX info uses the formatting language called \LaTeX\ for typesetting. 
A file called \file{latexinfo.sty} contains information (definitions or
\dfn{macros}) that \LaTeX\ uses when it typesets a \LaTeX info file.
(The macros tell \LaTeX\ how to convert the \LaTeX info commands to
\LaTeX\ commands which \LaTeX\ can then process to create the typeset
document.)  By changing the parameters in \file{latexinfo.sty} you can
easily change the size of the printed document.  In addition, you can
readily change the style in which the printed document is formatted; for
example, you can change the sizes and fonts used, the amount of
indentation for each paragraph, the degree to which words are
hyphenated, and the like.  By changing the specifications, you can make
a book look dignified, old and serious, or light-hearted, young and
cheery. See the \LaTeX\ Manual for more details (\cite{Lamport}).\refill

\LaTeX\ is very powerful and has a great many features.  Because a \LaTeX info
file must be able to present information both on a character-only terminal
in Info form and in a typeset book, the commands that \LaTeX info supports are
necessarily limited.  However, you are free to use and \LaTeX\ extensions
as long as you don't mind them being ignored by the Info formatting program.
Or you can write your own extensions to the Info formatting program.
\xref{Extending LaTeXinfo}.


\node General Syntactic Conventions, A Short Sample LaTeXinfo File, Characteristics of the Printed Manual, Overview of LaTeXinfo
\section{General Syntactic Conventions}
\cindex{General syntactic conventions}
\cindex{Syntactic conventions}
\cindex{Conventions, syntactic}

\LaTeX info files are made up of a subset of \LaTeX\ constructs.  The strict
limits make it possible for \LaTeX info files to be understood both by 
\LaTeX\ and by the code which converts them into Info files.

All ASCII printing characters except \samp{\back }, \samp{\{} and
\samp{\}} can appear in body text in a \LaTeX info file and stand for
themselves.  This means that the characters \code{# $ % ^ \& _ |} all
print as normal characters.  \samp{\back } is the escape character which
introduces commands.  \samp{\{} and \samp{\}} should be used only to
surround arguments to certain commands.  \samp{\{} and \samp{\}}
appearing anywhere else will be treated by \LaTeX\ as a grouping but
treated by the code that produces an Info file as themselves; this
inconsistency is undesirable.  To put one of these parentheses into the
document, put a \samp{\back } character in front of it.  To get a
\samp{\back } character itself, use \samp{\back back}. For example, you
would insert \samp{\back \{}, and \samp{\back \}} for parentheses and
\samp{\back back} for a backslash.\refill

It is customary in \LaTeX\ to use doubled single-quote characters to begin
and end quotations, \samp{``} like these \samp{''}.  This convention should
be followed in \LaTeX info files.  Also, three hyphens in a row, \samp{---},
are used for a dash---like this.  In \LaTeX, a single or even a double
hyphen produces a dash that is shorter.\refill

\LaTeX\ ignores the line-breaks in the input text, except for blank
lines, which separate paragraphs.  Info generally preserves the line
breaks that are present in the input file.  Therefore, break the lines
in the \LaTeX info file the way you want them to appear in the output
Info file, and let \LaTeX\ take care of itself.  Since Info does not
normally refill paragraphs when it processes them, a line with commands
in it will sometimes look bad after Info has run on it.  To cause Info
to refill the paragraph after finishing with the other processing, you
need to put the command \code{\back refill} at the end of the paragraph.
(\xref{Refilling Paragraphs and Preventing Indentation}.)\refill

To prevent a paragraph from being indented in the printed manual, put the
command \code{\back noindent} on a line by itself before the start of the text
that should not be indented.

\clearpage
In order to be made into a printed manual, a \LaTeX info file \strong{must}
begin with lines that looks like

\begin{verbatim}
\documentstyle[12pt,latexinfo]{book}
\pagestyle{headings}

\begin{document}

\setfilename{latexinfo.info}
\end{verbatim}

\noindent
The \samp{\back documentstyle[12pt,latexinfo]\{book\}} line tells \LaTeX\
to use the \file{latexinfo.sty} and \file{book.sty} style files.  The
\code{\back pagestyle\{headings\}} command is the \LaTeX\ command to put
the chapter and section headings and page numbers at the top of each page.
The \code{\back begin\{document\}} command starts the document, and makes
the characters \code{# $ % ^ \& _ |} all begin to print as normal
characters.  (These characters retain their normal \LaTeX\ meanings in the
preamble between the \samp{\back documentstyle} and \code{\back
begin\{document\}} commands.) This line must be followed (sooner or later)
by the \samp{\back setfilename\{\var{info-file-name}\}}. It is is needed to
provide a name for the Info file to output to.\refill

\node A Short Sample LaTeXinfo File, Beginning a LaTeXinfo File, General Syntactic Conventions, Overview of LaTeXinfo
\section{A Short Sample LaTeXinfo File}
\cindex{A Short Sample LaTeXinfo File}
\cindex{Sample LaTeXinfo file}

\findex{c}
\findex{comment}

A \LaTeX info file looks like the following, which is a complete but very
short \LaTeX info file.  The \code{\back comment} or \code{\back c} command
introduces comments that will not appear in either the Info file or the
printed manual; they are for the person who reads the \LaTeX info file.

The first part of the file, from \samp{\back documentstyle} through to
\samp{\back setfilename}, looks more intimidating than it is.  Most of the
material is standard boilerplate; when you write a manual, you just put in
the name of your own manual in this section.\refill

All the commands that tell \LaTeX\ how to typeset the printed manual and tell\\
\code{latexinfo-format-buffer} how to create an Info file are preceded
by \samp{\back }; thus, \code{\back node} indicates a node and 
\code{\back chapter} indicates the start of a chapter.\refill

\begin{verbatim}
\documentstyle[12pt,latexinfo]{book}
\pagestyle{headings}

\begin{document}

\c Declare which indices you want to make use of.
\newindex{cp}

\title{The Manual}

\author{Fred Foobar,\\
	Clarke Institute,\\
	999 Queen Street,\\
	Toronto, Ontario}

\date{\today}
\maketitle

\c The following commands start the copyright page for the printed manual.
\clearpage
\vspace{0pt plus 1filll}
Copyright \copyright\ year copyright-owner

Permission is granted to copy and distribute modified versions of this
manual under the following five pages of conditions...

\c End the Copyleft page and don't use headings on this page.
\pagestyle{empty}
\clearpage

\tableofcontents

\c End the Table of Contents
\clearpage

\c Anything before the \setfilename will not appear in the Info file.
\setfilename{themanual.info}

\begin{ifinfo}
Put another 5 page copyleft here for the Info file.
\end{ifinfo}

\c The Top node contains the master menu for the Info file.
\c This appears only in the Info file, not the printed manual.

 \node Top,       First Chapter, (dir),    (dir)

\begin{menu}
* First Chapter::    The first chapter is the 
                     only chapter in this sample.
\end{menu}

 \node First Chapter, Concept Index, Top, Top
 \chapter{First Chapter}
 \cindex{Reference to First Chapter}

This is the contents of the first chapter. 
Here is a numbered list.

\begin{enumerate}
\item
This is the first item.

\item
This is the second item.
\end{enumerate}

The \kbd{M-x latexinfo-format-buffer} command transforms a LaTeXinfo file
like this into an Info file; and \LaTeX\ typesets it for a printed manual.

 \node Concept Index, Top, First Chapter, Top
 \unnumbered{Concept Index}

\twocolumn
\printindex{cp}

\end{document}
\end{verbatim}

\clearpage
Here is what the contents of the first chapter of the sample look like:

\begin{quotation}

This is the contents of the first chapter. 

Here is a numbered list.

\begin{enumerate}
\item
This is the first item.

\item
This is the second item.
\end{enumerate}

The \kbd{M-x latexinfo-format-buffer} command transforms a \LaTeX info file
like this into an Info file; and \LaTeX\ typesets it for a printed manual.
\end{quotation}

\node Beginning a LaTeXinfo File, The LaTeXinfo File Header, A Short Sample LaTeXinfo File, Top
\chapter{Beginning a LaTeXinfo File}
\cindex{LaTeXinfo file beginning}
\cindex{File beginning}

Various pieces of information have to be provided to \LaTeX info at the
beginning of a \LaTeX info file, such as the name of the file, the title
of the document and the like.  Generally, the beginning of a \LaTeX info file
has four parts:

\begin{enumerate}
\item
The header, that includes the commands for naming the \LaTeX info file and
telling \LaTeX\ what style files to use when processing the file.

\item
A section that is terminated by the \code{\back setfilename} command that
contains the title page, the copyright page and the table of contents.
This section appears only in the printed manual.

\item
A section, marked by the \code{\back begin\{ifinfo\}} and 
\code{\back end\{ifinfo\}} commands, that contains a short statement 
of what the file is about, the copyright notice and copying permissions.
This section appears only in the Info file.

\item
The \samp{Top} node that contains an extensive menu for the whole Info
file.  The contents of this node only appear in the Info file.
\end{enumerate}

If the \LaTeX info file has a section containing licensing information and a
warranty disclaimer, that section usually follows the \samp{Top} node.  The
licensing section will be followed by a preface or else by the first
chapter of the manual.

Since the copyright notice and the copying permissions are in sections that
appear either only in the Info file or only in the printed manual, this
information has to be repeated twice.



\begin{menu}
* The LaTeXinfo File Header::
* Copyright Pages::
* Generating a Table of Contents::
* Copying Permissions for Info::
* The Top Node and Master Menu::
* Licensing and Distribution Information::
\end{menu}

\node The LaTeXinfo File Header, The First Line of a LaTeXinfo File, Beginning a LaTeXinfo File, Beginning a LaTeXinfo File
\section{The LaTeXinfo File Header}
\cindex{The LaTeXinfo File Header}
\cindex{Header for LaTeXinfo files}
\cindex{LaTeXinfo file header}

\LaTeX info files start with at least three lines that provide Info and 
\LaTeX\  with necessary information.  

\begin{verbatim}
\documentstyle[12pt,latexinfo]{book}
\pagestyle{headings}
\begin{document}
\end{verbatim}

\begin{menu}
* The First Line of a LaTeXinfo File::
* Titlepage::
\end{menu}

\node The First Line of a LaTeXinfo File, Titlepage, The LaTeXinfo File Header, The LaTeXinfo File Header
\subsection{The First Line of a LaTeXinfo File}
\cindex{First line of a LaTeXinfo file}
\cindex{Beginning line of a LaTeXinfo file}


Every \LaTeX info file that is to be the top-level input to \LaTeX\ must begin
with a line that looks like this:

\begin{verbatim}
\documentstyle[12pt,latexinfo]{book}
\end{verbatim}

When the file is processed by \LaTeX, it loads the macros listed as
options to the \code{documentstyle} command.  The option
\code{latexinfo} is needed for processing a \LaTeX info file, and \LaTeX\ will
then input the file \file{latexinfo.sty}
\pxref{LaTeX Input Initialization}.  

You can also include other options that may also include style files. 
Unlike \TeX info, these style files may have an Emacs counterpart, so
that you can extend \LaTeX info by writing your own styles. 
\xref{Extending LaTeXinfo}, for more information on writing your own
styles. 

\node Titlepage, Copyright Pages, The First Line of a LaTeXinfo File, The LaTeXinfo File Header
\subsection{Titlepage}
\cindex{Titlepage}
\findex{author}
\findex{title}
\findex{date}
\findex{maketitle}

The first printed material after the \code{\back begin\{document\}} will
make up the titlepage.  The \LaTeX\ commands \code{\back title},
\code{\back author} and \code{\back date} are used the same way as in
any \LaTeX\ report or book.  The title page is terminated by 
\code{\back maketitle}. Following the material for the title page 
should be the copyright page.\refill

\node Copyright Pages, The Copyright Page and Printed Permissions, Titlepage, Beginning a LaTeXinfo File
\section{Copyright Pages}
\cindex{Copyright page}

This part of the beginning of a \LaTeX info file contains the text
of the copying permissions that will appear in the printed manual.
This is usually followed by the \code{\back tableofcontents} command.  The
title and copyright pages should appear before the \code{\back setfilename}
command so that this material appears only in the printed manual, not in
the Info file.

\node The Copyright Page and Printed Permissions, Generating a Table of Contents, Copyright Pages, Copyright Pages
\subsection{The Copyright Page and Printed Permissions}
\cindex{Copyright}
\cindex{Printed permissions}
\cindex{Permissions, printed}
\findex{pagestyle}
\findex{thispagestyle}

By international treaty, the copyright notice for a book should either be
on the title page or on the back of the title page.  Other locations in a
book are not official and do not provide copyright protection.  The
copyright notice should include the year followed by the name of the person
or organization who has the copyright.  When the copyright notice is on the
back of the title page, the page is not numbered.  Therefore, this is
usually done while a \code{\back pagestyle\{empty\}} is in effect. See the
\LaTeX\ Manual for more details on the \code{pagestyle} command 
(\cite{Lamport}).\refill

\findex{filll}
\findex{vspace}
\findex{vspace*}
To cause a page break, the \code{\back clearpage} command is used.  In
the sample, the \code{\back clearpage} that ends the titlepage is
followed by the somewhat mysterious line that reads: 
\samp{\back vspace*\{0pt plus 1filll\}}.  This is a line that uses
\LaTeX\ commands to push the copyright notice and the other text 
on the copyright page towards the bottom of the page.  The \code{\back
vspace*} command means to put in white space.  The \samp{0pt plus 1filll}
means to put in zero points of mandatory white space, and as much optional
white space as needed.  Note the use of three \samp{l}s in the word
\samp{filll}; this is the correct use in \LaTeX.\refill

\findex{copyright}
The \code{\back copyright} command generates a \samp{c} inside a circle.
The copyright notice itself has the following legally defined sequence: 

\begin{example}
Copyright \copyright \var{year} \var{copyright-owner}
\end{example}

It is customary to put information on how to get a manual after the
copyright notice (the address of the Free Software Foundation, for
example) and the permissions.  Note that the permissions have to be
repeated here as well as in the \code{ifinfo} section that immediately
follows the header since this section appears only in the printed manual
and the \code{ifinfo} section appears only in the Info file. \xref{Copying
Permissions for Info}.

Standard text for the permissions appears in the appendix.  
\xref{Standard text for Copying Permissions}.

\node Generating a Table of Contents, Setfilename, The Copyright Page and Printed Permissions, Beginning a LaTeXinfo File
\section{Generating a Table of Contents}
\cindex{Generating a Table of Contents}
\cindex{Table of contents}
\cindex{Contents, Table of}

The commands \code{\back chapter}, \code{\back section}, etc., supply the
information to make up a table of contents, but they do not cause an actual
table to be generated.  To do this, you must use the 
\code{\back tableofcontents} command.

The table of contents command outputs (into a printed manual) a complete
table of contents, based on the \code{\back chapter}, \code{\back section}
and other sectioning commands.  This command should be used on
a line by itself. This command automatically generates a Table of Contents
heading at the top of the page.  Tables of contents should be generated at
the beginning of the manual, usually just after the \code{\back maketitle},
but before the \code{\back setfilename}.\refill

\node Setfilename, Copying Permissions for Info, Generating a Table of Contents, Generating a Table of Contents
\subsection{Setfilename}
\cindex{Setfilename command}
\cindex{Info file requirement for \back setfilename}
\findex{setfilename}

In order to be made into an Info file, a \LaTeX info file must contain a
line that looks like this:

\begin{example}
\back setfilename\{\var{info-file-name}\}
\end{example}

\noindent
This command specifies the name of the Info file to be generated.  In
fact, there can be other things in the file before this line, but they
are ignored in the generation of an Info file.  The line containing the
\code{\back setfilename} is ignored when a printed manual is generated.
Any \LaTeX\ commands that precede the \code{\back setfilename} are
ignored by the Info formatting program.
 
\node Copying Permissions for Info, The Top Node and Master Menu, Setfilename, Beginning a LaTeXinfo File
\section{Copying Permissions for Info}
\cindex{Copying Permissions for Info}

Since the title page and the copyright page appear only in the printed copy
of the manual, the same information has to inserted in a section that
appears only in the Info file.  This section usually contains a brief
description of the contents of the Info file, a copyright notice and
copying permissions. For example


\begin{verbatim}
\setfilename{themanual.info}

\begin{ifinfo}
Copyright \copyright \var{year} \var{copyright-owner}
Put another 5 page copyleft here for the Info file.
\end{ifinfo}
\end{verbatim}

\noindent
Standard text for the copyright permissions is contained in the appendix.
\xref{Ifinfo Copying Permissions}, for the complete text.

\node The Top Node and Master Menu, Licensing and Distribution Information, Copying Permissions for Info, Beginning a LaTeXinfo File
\section{The Top Node and Master Menu}
\cindex{Top node}
\cindex{Master menu}

The \samp{Top} node contains an extensive master menu for the whole
Info file.  The contents of this node appear only in the Info file.
Nothing in this node should appear in the printed file.  Since a node
line by itself and a menu by itself are not printed, the contents of
this node do not have to be within a region delineated by 
\code{\back begin\{ifinfo\}} and \code{\back end\{ifinfo\}} commands.
However, any text within the node should be marked off in that manner.
You may want to put a short summary before the master menu inside a
region delineated by \code{\back begin\{ifinfo\}} and
\code{\back end\{ifinfo\}} commands.  Usually, the `Previous' and `Up' 
pointers to \samp{(dir)}.\refill

Generally, the top menu is divided into parts.  

\begin{itemize}

\item
The first part contains the major nodes in the \LaTeX info file.

\item
The second part contains entries for the indices.  In an Info file, it
is very useful to have indices here at the beginning of the file in the
top node rather than at the end, as in a printed book.

\item
The third and subsequent parts contain a listing of the other, lower
level nodes, often ordered by chapter.  This way, an inquirer can go
directly to a particular node if he or she is searching for specific
information.  (These nodes are not required; use them if you think they
are a convenience.)
\end{itemize}

Each section in the menu can be introduced a descriptive line.  So long as
the line does not begin with an asterisk, it will not be treated as a menu
item.  (\xref{Menu Environment}, for more information.)

For example, the Top node of this manual looks like this (but with many
more entries):

\begin{verbatim}
 \node Top, Overview, (dir), (dir)

\begin{menu}
* Overview::                    What is LaTeXinfo?
* LaTeXinfo Mode::              Special features in GNU Emacs.
...

Indices, nodes containing large menus

* Command Index::               An item for each command.
* Concept Index::               An item for each concept.

A detailed node listing

Overview
* Info File::                   Characteristics of the Info file.
* Printed Manual::              Characteristics of the printed manual.

Using LaTeXinfo Mode
* Info on a Region::            Formatting a region for Info.
* Showing the Structure::       Showing the structure of a file.
...
...
\end{verbatim}

\node Licensing and Distribution Information, Ending a LaTeXinfo File, The Top Node and Master Menu, Beginning a LaTeXinfo File
\section{Licensing and Distribution Information}
\cindex{Distribution}
\cindex{License agreement}

If the \LaTeX info file has a section containing the ``General Public License''
and the distribution information or a warranty disclaimer, this section
usually follows the \samp{Top} node.  The licensing and distribution
information and the disclaimer are followed by a preface, or else by the
first chapter of the manual.

The licensing agreement is very important to Project GNU documentation and
software.  Without it, you may find that you can no longer get the software
or its documentation.  This sounds paradoxical, but the state of the world
is such that documentation and software that does not have a
``restrictive'' license to make them freely distributable may be lost to
the public.  This has happened.\refill

For a good example of the text that could be used for the Distribution,
General Public License and NO WARRANTY sections of your document, see the
latest version of the GNU Emacs Manual (\cite{GNUEmacsManual}).

\cindex{Preface}
Although a preface is not a required part of a \LaTeX info file, it is very
helpful.  Ideally, it should state clearly and concisely what the file is
about and who would be interested in reading it.  In general, the preface
would follow the licensing and distribution information, although sometimes
people put it earlier in the document.  Usually, a preface is put in an
\code{\back unnumbered} section.

\node Ending a LaTeXinfo File, Making a Bibliography, Licensing and Distribution Information, Top
\chapter{Ending a LaTeXinfo File}
\cindex{Ending a LaTeXinfo File}
\cindex{LaTeXinfo file ending}
\cindex{File ending}

The end of a \LaTeX info file should include the bibliography, the
indices and the command that tells \LaTeX\ that it has reached the end
of the file. For example, a \LaTeX info file might be ended as follows:

\begin{verbatim}
\begin{tex}
\bibliography{latexinfo}
\end{tex}

\twocolumn
 \node Concept Index,     , Previous Node, Top
 \unnumbered{Concept Index}
\cindex{Concept Index}

\printindex{cp}

\end{document}
\end{verbatim}

The \code{\back end\{document\}} command should be on a line by itself and
every \LaTeX info file must end with such a line.  This command terminates
\LaTeX\ processing and forces out unfinished pages.\refill


\begin{menu}
* Making a Bibliography::
* Creating Indices::
\end{menu}

\node Making a Bibliography, Creating Indices, Ending a LaTeXinfo File, Ending a LaTeXinfo File
\section{Making a Bibliography}
\cindex{Making a Bibliography}
\findex{bibliographystyle}

You may also choose to include a bibliography of citations in the document.
Citations are prepared using the program \t{BibTeX}, which formats the
citations for use with \LaTeX.  See the \LaTeX\ Manual for more details
(\cite{Lamport}).\refill

Before you use the \code{\back cite} command, you must declare the
bibliography style that you are going to use.  This is usually done at
the beginning of the document, for example

\begin{verbatim}
\begin{document}
\bibliographystyle{alpha}
\end{verbatim}

At the end of the document comes the bibliography itself.  
The \code{\back bibliography} takes as an argument a comma separated list
of filenames that contain the bibliography entries.

\begin{verbatim}
\begin{tex}
\bibliography{latexinfo}
\end{tex}
\end{verbatim}

With these two sections in your document, you can use the \code{\back cite}
command to refer to the bibliography.  For example

\begin{verbatim}
a citation of the GNU Emacs Manual \cite{GNUEmacsManual}\dots
\end{verbatim}

\noindent
would produce

\begin{example}
a citation of the GNU Emacs Manual \cite{GNUEmacsManual}\dots
\end{example}

\noindent
and would cause an entry to be put in the Bibliography section something
like

\begin{description}
\item[Sta86]
Richard Stallman. \i{The GNU Emacs Manual},
The Free Software Foundation, 675 Massachusetts Ave., Cambridge MA,
02139, 1986.
\end{description}

\xref{Cite}, for how to use citations in the document.

\node Creating Indices, Defining the Entries of an Index, Making a Bibliography, Ending a LaTeXinfo File
\section{Creating Indices}
\cindex{Indices}
\cindex{Creating indices}

Using \LaTeX info, you can generate printed indices and Info file menus without
having to sort and collate entries manually.  \LaTeX info will do this for you
automatically.  Each index covers a certain kind of entry (functions, or
variables, or concepts, etc.)\: and lists all of those entries in
alphabetical order, together with information on how to find the discussion
of each entry.  In a printed manual, this information consists of page
numbers.  In an Info file, it consists of a menu item leading to the first

When you are making index entries, it is good practice to think of the
different categories under which people may look for something.  Different
people \emph{do not} think of the same words when they look something up.
They think of different words.  A helpful index will have items indexed
under all the different words that people may use.  For example, someone might
think it obvious that the two letter names for indices should be listed
under ``Indices, two letter names'', since the word ``Index'' is the
general concept.  But another reader may remember the specific concept of
two letter names and search for the entry listed as ``Two letter names for
indices''.  A good index will have both entries and will help both kinds of
user.

Like typesetting, the construction of an index is a highly skilled,
professional art, the subtleties of which are not appreciated until you
have to do it yourself.

Normally, six indices are provided for, and are referred to by their
two-letter abbreviations:
\cindex{Two letter names for indices}
\cindex{Indices, two letter names}
\cindex{Names for indices}

\begin{description}
\item[cp]
A \dfn{concept index} listing concepts that are discussed.

\item[pg]
A \dfn{program index} listing names of programs and leading to the places
where those programs are documented.

\item[fn]
A \dfn{function index} listing functions (such as, entry points of
libraries).

\item[vr]
A \dfn{variables index} listing variables (such as, external variables of
libraries).

\item[tp]
A \dfn{data type index} listing data types (such as, structures defined in
header files).

\item[ky]
A \dfn{keystroke index} listing keyboard commands.
\end{description}

\noindent
Not every manual needs all of these.  This manual has two indices: a
concept index and a command index (that uses the function index but is
called a command index in the chapter heading).  Two or more indices can be
combined into one using the \code{\back synindex} command.  \xref{Combining
Indices}.

In order to generate any of these Indices, you must declare it with the
\code{\back newindex} command, before it is first used by one of the index
commands.  This is usually done after the \code{\back begin\{document\}}
but before the \code{\back setfilename}.
\cindex{Indices, declaring}
\cindex{Declaring indices}
\findex{newindex}

\code{newindex} takes one argument, which is the two letter index type
described above.  For example, to declare a concept and function index,
you would use

\begin{verbatim}
\documentstyle[12pt,latexinfo]{book}

\begin{document}
\newindex{cp}
\newindex{fn}
\setfilename{manual.info}
\end{verbatim}

\begin{menu}
* Defining the Entries of an Index::
* Special Index Entries::
* Combining Indices::
* Printing an Index and Generating Menus::
\end{menu}

\node Defining the Entries of an Index, Special Index Entries, Creating Indices, Creating Indices
\subsection{Defining the Entries of an Index}
\cindex{Defining the entries of an index}
\cindex{Index entries}
\cindex{Entries for an index}

The data to make an index comes from many individual commands scattered
throughout the \LaTeX info source file.  Each command says to add one entry to
a particular index; after processing, it will give the current page number
or node name as the reference.

\begin{description}
\item[\back cindex\{\var{concept}\}]
Make an entry in the concept index for \var{concept}, referring to the
current page or node.\refill

\item[\back findex\{\var{function}\}]
Make an entry in the function index for \var{function}, referring to the
current page or node.\refill

\item[\back vindex\{\var{variable}\}]
Make an entry in the variable index for \var{variable}, referring to the
current page or node.\refill

\item[\back pindex\{\var{program}\}]
Make an entry in the program index for \var{program}, referring to the
current page or node.\refill

\item[\back kindex\{\var{key}\}]
Make an entry in the key index for \var{key}, referring to the
current page or node.\refill

\item[\back tindex\{\var{data type}\}]
Make an entry in the data type index for \var{data type}, referring to the
current page or node.\refill
\end{description}

If the same name is indexed on several pages, all the pages are listed in
the printed manual's index.  However, \strong{only} the \strong{first} node
referenced will appear in the index of an Info file.  This means that it is
best to write indices in which each entry will refer to only one place in the
\LaTeX info file.  Fortunately, this constraint is a feature rather than loss
since it means that the index will be easy to use.  Otherwise, it can be
easy to create an index which has many pages listed for an entry and you
don't know which one you need.\refill

You are not actually required to use indices for their canonical
purposes.  For example, you might wish to index some C preprocessor macros.
You could put them in the function index along with actual functions, just
by writing \code{\back findex} commands for them; then, when you print the
``function index'', you could give it the title `Function and Macro Index'
and all will be consistent for the reader.  Or you could put the macros in
with the data types by writing \code{\back tindex} commands for them, and give
that index a suitable title so the reader will understand.\refill

\node Special Index Entries, Combining Indices, Defining the Entries of an Index, Creating Indices
\subsection{Special Index Entries}
\findex{cpsubindex}
\findex{cpindexbold}

The concept index has two special index entries to help you make more elaborate
concept indices.

\code{\back cpsubindex\{topic\}\{subtopic\}} defines an entry in the
concept index, which has a subtopic.  In the Info manual, this line and
anything on it is deleted.

\code{\back cpindexbold\{topic\}} defines an entry in the concept index,
which is set in bold type.  In the Info manual, this line and anything
on it is deleted.

\node Combining Indices, Printing an Index and Generating Menus, Special Index Entries, Creating Indices
\subsection{Combining Indices}
\cindex{Combining Indices}
\cindex{Indices, combining them}

Sometimes you will want to combine two disparate indices such as functions
and variables, perhaps because you have few enough of one of them that
a separate index for them would look silly.

You could put variables into the function index by writing \code{\back findex}
commands for them instead of \code{\back vindex} commands, and produce a
consistent manual by printing the function index with the title `Function
and Variable Index' and not printing the `Variable Index' at all, but this
is not a robust procedure.  It works only as long as your document is never
included in part of or together with another document that is designed to
have a separate variable index; if you did that, the variables from your
document and those from the other would not end up together.

What you should do instead when you want functions and variables in one
index is to index the variables with \code{\back vindex} as they should be, but
use the \code{\back synindex} command to redirect these \code{\back vindex}
commands to the function index.  \code{\back synindex} takes two arguments: the
name of an index to redirect, and the name of an index to redirect it to.
For this purpose, the indices are given two-letter names described above.
Thus, \code{\back synindex\{vr\}\{fn\}} at the front of a \LaTeX info file
will cause all entries designated for the variable index to go to
the function index instead.

\node Printing an Index and Generating Menus, Node and Chapter Structuring, Combining Indices, Creating Indices
\subsection{Printing an Index and Generating Menus}
\cindex{Printing an index}
\cindex{Indices, printing}
\cindex{Generating menus with indices}
\cindex{Menus generated with indices}

To print an index means to include it as part of a manual or Info file.
This does not happen automatically just because you use \code{\back
cindex} or other index-entry generating commands in the \LaTeX info
file; those just cause the raw data for the index to be accumulated.  To
print an index, you must include the \code{\back printindex} command at
the place in the document where you want the index to appear.  Also, for
the case of the printed manual, you must run a program that is supplied
with GNU Emacs, called \code{texindex}, to sort the raw data to produce a
sorted index file, which is what will actually be used to print the
index.\refill

The \LaTeX info command that is used to print indices is 
\code{\back printindex}.  It takes the two--letter index name (\pxref{Combining
Indices}) as an argument without braces, and reads the corresponding sorted
index file and formats it appropriately into an index.\refill

\begin{ifinfo}
The two--letter index names are:

\begin{description}
\item[cp]
the concept index.
\item[vr]
the variable index.
\item[fn]
the function index.
\item[ky]
the key index.
\item[pg]
the program index.
\item[tp]
the data type index.
\end{description}
\end{ifinfo}

\code{\back printindex} does not generate a chapter heading for the index.
Consequently, you should precede the command with a suitable section or
chapter command to supply the chapter heading and put the index into the
table of contents.  And before that, you will probably put a \code{\back
node} command.  Also, if you want the index to be set in two-column mode,
then you should precede the index with the \LaTeX\ \code{\back twocolumn}
command.  For example,\refill

\begin{verbatim}
\twocolumn
 \node Command Index, Concept Index, The Last Section, Top
 \unnumbederd{Command Index}
\cindex{Command Index}

\printindex{fn}

 \node Concept Index,Top,   Command Index, Top
 \unnumbered{Concept Index}
\cindex{Concept Index}

\printindex{cp}

\end{document}
\end{verbatim}

In \LaTeX, \code{\back printindex} needs a sorted index file to work from.
\LaTeX\ does not know how to do sorting; the lack of any way to call
an external program like \code{sort} is one of the main deficiencies of
\TeX.  You must invoke the program \code{texindex} to do so, giving it the
names of the raw index files to be sorted as arguments.  You do not have to
run \code{texindex} on all of them; only the ones you are going to print.
(\xref{Printing Hardcopy}, for more information.)

\node Node and Chapter Structuring, Chapter, Printing an Index and Generating Menus, Top
\chapter{Node and Chapter Structuring}
\cindex{Node and chapter structuring}
\cindex{Chapter structuring}
\cindex{Node structuring}
\cindex{Structuring of nodes and chapters}
\findex{node}

The chapter structuring commands divide a document into a hierarchy of
chapters, sections, subsections and subsubsections.  These commands
generate large headings.  The chapter structuring should be placed at the
beginning of a line.  In a printed manual, the table of contents is based
on the information specified by the chapter structuring commands.

Although the chapter structuring commands used for creating a printed
document are entirely different from the node commands for structuring an
Info file, you are likely to use the two kinds of command together since
the single \LaTeX info file is usually designed to be read both as an Info file
and as a printed manual.  The only time you are likely to use the chapter
structuring commands without using the node structuring commands is if you
are writing a document that will never be put into Info format, for
example, a novel, a letter, an article, or a memorandum.

Although a \LaTeX info file can be structured in a variety of ways, it is
usually structured like a book with chapters, sections, subsections and the
like.  This structure can also be visualized as a tree (or rather as an
upside--down tree) with the root at the top and each level corresponding to
chapters or sections.  In Info format, you reach the nodes on
each level by using the the `Next' and `Previous' pointers in the node
line.  For example, you go from one chapter to the next or previous chapter
by using the the pointers to the next and previous chapters.  In Info, you
go the level above by using an `Up' pointer and you go to the level below
through a `Menu'.  In the printed manual, cross references are indicated by
page and section numbers; in the on-line file, cross references are
specified by inline menu items.

\clearpage
Here is a diagram that shows a \LaTeX info file with three chapters; 
each chapter has two sections.

\begin{verbatim}
                                 top
                                  |
                                  |
            ---------------------------------------------
           |                      |                      |
           |                      |                      |
       Chapter 1              Chapter 2               Chapter 3
           |                      |                      |
           |                      |                      |
      ----------             ----------              ----------          
     |          |           |          |            |          |         
 Sect. 1.1   Sect. 1.2   Sect. 2.1  Sect. 2.2    Sect. 3.1  Sect. 3.2     
			   				   
\end{verbatim}

In this structure, the node for Chapter 2 looks like this:

\begin{verbatim}
 \node     Chapter 2,  Chapter 3, Chapter 1, top
\end{verbatim}

To get to Sections 2.1 and 2.2, you need a menu inside of Chapter 2 that
says:

\begin{verbatim}
\begin{menu}
* Sect. 2.1::    Description of this section.
* Sect. 2.2::  
\end{menu}
\end{verbatim}

\noindent
This menu is located inside Chapter 2, after the beginning of the chapter,
just before Section 2.1.

Note that a menu entry has three parts: the menu item name, the name of the
node and, optionally, a description of the item (in that order).  If the
menu item name and the name of the node are the same, you can put two
colons after the item name, as is shown in the example.
\xref{Menu Environment}.

The node for Sect. 2.1 will look like this:

\begin{verbatim}
 \node     Sect. 2.1, Sect. 2.2,         ,  Chapter 2
\end{verbatim}

This node does not have a `Previous' node.

Usually, a \code{\back node} command and a chapter structuring command are
used in sequence, along with indexing commands.  For example, the node for
the chapter on Ending a LaTeXinfo File looks like this:

\begin{verbatim}
 \node Ending a LaTeXinfo File, Structuring, Beginning a LaTeXinfo File, Top
 \chapter{Ending a LaTeXinfo File}
\cindex{Ending a LaTeXinfo File}
\cindex{LaTeXinfo file ending}
\cindex{File ending}
\end{verbatim}

The \code{\back node} command is the only one in \LaTeX info where the
arguments are not delineated by braces.  The arguments are separated by
commas, and are terminated at the end of the line.  This is because
the Info format itself requires the \code{node} arguments to be like
this.  Note that it also means that you cannot use a comma within any
of the four arguments to the node command.

There are four chapter-structuring commands for chapters, sections,
subsections and subsubsections.  The optional heading argument to these
commands is not supported.  You should avoid the use of any \LaTeX\ 
commands in the headings: any such commands should be preceded by a
\code{\back protect}.  See the \LaTeX\ Manual for more details
(\cite{Lamport}).\refill

\begin{menu}
* Chapter::
* Appendix::
* Section::
* Subsection::
* Subsubsection::
* Node::
* Menu Environment::
\end{menu}

\node Chapter, Appendix, Node and Chapter Structuring, Node and Chapter Structuring
\section{Chapter}
\cindex{Chapter}
\findex{chapter}
\findex{unnumbered}
\findex{chapter*}

\code{\back chapter} identifies a chapter in the document.  It is
followed by a single argument, as in

\begin{verbatim}
 \chapter{Node and Chapter Structuring}
\end{verbatim}

In \LaTeX, it creates a chapter in the document, specifying the chapter
title.  In the Info file, \code{\back chapter} causes its argument to
appear on a line by itself, with a line of asterisks inserted
underneath.  For example:\refill

\begin{example}
This is a Chapter
*****************
\end{example}

\noindent
To start a chapter without it being numbered, use the \code{\back
unnumbered} command.  To start a chapter without it being numbered
or appearing in the table of contents, use the
\code{\back chapter*} command.

In the printed manual, the chapters will begin on a new page.  If you want
the chapters to appear on the odd--sided pages, use the \code{book}
documentstyle.

\node Appendix, Section, Chapter, Node and Chapter Structuring
\section{Appendix}
\cindex{Appendix}
\findex{appendix}

\code{\back appendix} is the same as the \LaTeX\ command of the same name.
In a printed manual, all chapters that follow this command are
numbered differently in the table of contents: they are given a letter
instead of a number, and the letters restart from \code{A}.

\node Section, Subsection, Appendix, Node and Chapter Structuring
\section{Section}
\cindex{Section}
\findex{section}
\findex{unnumberedsec}
\findex{section*}

\code{\back section} is like \code{\back chapter} except that in 
\LaTeX\ it makes a section rather than a chapter.  (\xref{Chapter}.)  
Sections go within chapters.  In the Info file, \code{\back chapter} and
\code{\back section} differ only in that \code{\back section} underlines
with \samp{=}.  For example,\refill

\begin{example}
This is a section
=================
\end{example}

To start a section without it being numbered, use the \code{\back
unnumberedsec} command.  To start a section without it being numbered or
appearing in the table of contents, use the \code{\back section*}
command.

\node Subsection, Subsubsection, Section, Node and Chapter Structuring
\section{Subsection}
\cindex{Subsection}
\findex{subsection}
\findex{unnumberedsubsec}
\findex{subsection*}

Subsections are to sections as sections are to chapters. (\xref{Section}.)
They are underlined with \samp{-}.  For example,\refill

\begin{example}
This is a subsection
--------------------
\end{example}

To start a subsection without it being numbered, use the \code{\back 
unnumberedsubsec} command.  To start a subsection without it being numbered
or appearing in the table of contents, use the
\code{\back subsection*} command.\refill

\node Subsubsection, Node, Subsection, Node and Chapter Structuring
\section{Subsubsection}
\cindex{Subsubsection}
\findex{subsubsection}
\findex{unnumberedsubsubsec}
\findex{subsubsection*}

Subsubsections are to subsections as subsections are to sections.
(\xref{Subsection}.)  They are underlined with periods.  For
example,\refill

\begin{example}
This is a subsubsection
.......................
\end{example}

To start a subsubsection without it being numbered, use the \code{\back 
unnumberedsubsubsec} command.  To start a subsubsection without it being
numbered or appearing in the table of contents, use the
\code{\back subsubsection*} command.\refill

\node Node, Menu Environment, Subsubsection, Node and Chapter Structuring
\section{Node}
\cindex{Node}
\cindex{Node}

\code{\back node} defines the beginning of a new node in the Info output
file (\inforef{Top, info, info}.).  It is followed by four arguments,
separated by commas, that make up the rest of the line.  Since it is
often hard to remember the order in which are arguments are listed,
\code{latexinfo-mode} provides the \ctrl{C} \ctrl{C} \key{n} command
(\code{latexinfo-insert-node}) which automatically inserts a comment
line listing the arguments.  For example,\refill

\begin{example}
\back node    LaTeXinfo Mode, Beginning a LaTeXinfo File,  Overview, Top    
\back comment node-name,    next,              previous, up
\end{example}

\noindent
defines a node named \samp{LaTeXinfo Mode}, whose `Next' pointer is to node
\samp{Beginning a LaTeXinfo File}, whose `Previous' pointer is to node
\samp{Overview}, and whose `Up' pointer is to node \samp{Top}.  What
this means is that \LaTeX info changes \w{\code{\back node \var{args}}}
into the special text string necessary to separate Info nodes and to
identify the node that is starting and say what nodes it points
to.\refill

The pointer names should be the names of nodes defined elsewhere.  For this
example, nodes named \samp{Beginning a LaTeXinfo File}, \samp{Overview} and
\samp{Top} should be defined elsewhere in the file with other \code{\back node}
commands.  It does not matter whether they are before or after the node
that refers to them.\refill Normally, a node's `Up' pointer should point
at the node whose menu mentions that node.  The node's `Next' pointer
should point at the node that follows that node and its `Previous'
pointer should point at the node that precedes it in that menu.\refill

In \LaTeX, \code{\back node} is nearly ignored.  It generates no text.
Its only function is to identify the name to use for cross-references to
the chapter or section which follows the \code{\back node} command and
which makes up the body of the node.  (Cross references are made
with \code{\back xref}.  \xref{Making Cross References}.) 
\code{\back node} should be followed immediately by a
chapter-structuring command such as \code{\back chapter}, \code{\back
section}, \code{\back subsection} or \code{\back subsubsection}.\refill

The easiest way to write a node is to use the \LaTeX info Mode keyboard
command \ctrl{c} \ctrl{c} \key{n} to insert \samp{\back node} and a
comment line listing the names of each of the pointers in their proper
order.  This way you won't lose track of which arguments are for which
pointers.  The template is especially useful if you are not familiar
with \LaTeX info.  It is important to pick a suitable node name.
Generally, these begin with an uppercase letter as if the node name were
a heading for a chapter or section.  Do not use any of the \LaTeX info
commands in the name; these commands confuse Info.  The node name should
be informative.  Unfortunately, long names will not fit onto the line,
which can be awkward, but it is still better to use long but informative
names rather than short ones.

Some people insert the names of the `Next', `Previous' and `Up' pointers
at the same time they insert the node's own name.  This is because it is
easier to keep track of the node structure as you create a document than
it is to sort it out after you have dozens of nodes.  Others wait to
insert the `Next', `Previous' and `Up' pointers until they have a nearly
final version of the document.  This is because they expect to change
the organization of the document while they write it and insert or
delete sections and move them around.  The command
\code{latexinfo-show-structure} can be used to find the `Next',
`Previous' and `Up' pointers of a node.  
(See \xref{Using latexinfo-show-structure}.)

After you have inserted the node-line, you should immediately write an
command for the chapter or section and insert its name.  Next, (and this
is important!), put in several index entries.  Usually, you will find at
least two and often as many as four or five ways of referring to the
node in the index. This will make it much easier for people to find the
node in the index.\refill

The top node of the file, named \samp{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 \samp{(dir)} as the
parent of the top node; this is short for \samp{(dir)top}, the node \samp{top}
in the file \file{dir}, which is the main menu of Info.  For example,\refill

\begin{verbatim}
\node    Top,       Overview, (dir),    (dir)
\comment node-name, next,     previous, up
\end{verbatim}

For more information about installing an Info file in the \file{info}
directory, \pxref{Installing an Info file}

\node Menu Environment, Making Quotations and Examples, Node, Node and Chapter Structuring
\section{Menu Environment}
\cindex{Menu Environment}
\findex{menu}

Info file nodes can contain \dfn{menus} which point to other nodes.  You
must type the menus in by hand, and surround them with lines containing
\code{\back begin\{menu\}} and \code{\back end\{menu\}}.  In Info, the
\code{\back begin\{menu\}} line changes into \samp{* Menu:}, which
indicates the beginning of a menu to the Info program.  Otherwise, the
contents are unchanged by \LaTeX info, except for the processing of any
other commands within.  The entire menu construct has no effect in the
printed manual and will not appear there.\refill

By convention, a menu is put at the end of a node.  This way, it is easy
for someone using Info to find the menu, using the \kbd{M->}
(\code{end-of-buffer}) command.  Menu environments cannot be nested, nor can
they appear inside another environment such as \code{example}.The
\code{\back begin\{menu\}} \emph{must} occur at the beginning of a line.

In a menu, every line that begins with a \samp{*} lists a single topic.  A
line that does not start with a \samp{*} will also appear in the menu and
can be used as a comment.  A menu item has three parts: 

\begin{enumerate}
\item
The menu item name.

\item
The name of the node.

\item
A description of the item.  
\end{enumerate}

\noindent
Only the first part is required.  This part is the name of the topic---the
name of the menu item that the user must give to the \kbd{m} command to
select this topic when using Info.  The first part comes right after the
asterisk and a space, and is followed by a colon, spaces and tabs, and then
the name of the node which discusses that topic.  The name of the node is
terminated by a tab, comma, newline or period.  If the node name and topic
name are the same, rather than give the name twice, put two colons after
the name instead.  For example, \samp{* Name::}.  You should do this
whenever possible, since it reduces visual clutter in the menu.
If the second part is present, it may be terminated with a tab, comma, or
newline; or with a period.

\clearpage
\noindent
For example:

\begin{example}
\back begin\{menu\}
A Section on Foo and Switches
* Foo::           The node named Foo tells you how to go fooing.
* Sw: Switches.   Type \back code\{m Sw\} to see node \back code\{Switches\}
                  which describes the switches available here.
\back end\{menu\}
\end{example}

\noindent
produces

\begin{verbatim}
* menu:

A Section on Foo and Switches
* Foo::         The node named foo tells you how to go fooing.
* Sw: Switches. Type `m Sw' to see node `Switches'
                which describes the switches available here.
\end{verbatim}

In this example, the menu has two items.  \samp{Foo} is both a menu item
name and the name of the node referred to by that item.  \samp{Sw} is
the other menu item name, and it refers to the node named
\samp{Switches}.  Since no file name is specified with \samp{Foo} or
\samp{Switches}, they must be the names of other nodes in the same Info
file.  Nodes in other Info files can be referred to by putting the file
name in parentheses at the beginning of the node name. For example,

\begin{verbatim}
\begin{menu}
* Outlining: (emacs) Outline Mode.  The major mode for editing outlines.
* Rebinding: (emacs) Rebinding.     How to redefine the meaning of a key.
\end{menu}
\end{verbatim}

\noindent
When this is done, the item has to have at least two parts: the first part
is the menu item name and the second part is the name of the node.

\node Making Quotations and Examples, Quotation Environment, Menu Environment, Top
\chapter{Making Quotations and Examples}
\cindex{Making Quotations and Examples}
\cindex{Examples}

Quotations and examples are blocks of text, consisting of one or more whole
paragraphs that are set off from the bulk of the text and treated
differently.  They are usually indented.

In \LaTeX info, an insertion is always begun by writing a 
\code{\back begin} command on a line by itself, and ended by writing a 
\code{\back end} command that is also on a line by itself.  For instance, an
\dfn{example} is a kind of insertion that is begun with
\code{\back begin\{example\}} and ended with
\code{\back end\{example\}}.\refill
\findex{end}

There are five commands for quotations and examples:

\begin{description}
\item[quotation]
Used to indicated text that is quoted.\refill

\item[example]
Used to illustrate code, commands and the like in a fixed width font
without filling.\refill

\item[display]
Used for illustrative text.

\item[verbatim]
Used to illustrate code that you want to protect from parsing by either
\LaTeX\ or \LaTeX info.

\item[center]
Used for centering text.
\end{description}



\begin{menu}
* Quotation Environment::
* Example Environment::
* Display Environment::
* Verbatim Environment::
* Center Environment::
\end{menu}

\node Quotation Environment, Example Environment, Making Quotations and Examples, Making Quotations and Examples
\section{Quotation Environment}
\cindex{Quotation Environment}
\findex{quotation}

The \code{quotation} environment is used to indicate text that is
excerpted from another (real or hypothetical) printed work.  The inside
of a quotation is processed normally except that

\begin{enumerate}
\item
The margins are narrower.
\item
Paragraphs are not indented.
\item
Interline spacing and interparagraph spacing are reduced.
\end{enumerate}

Thus, the input

\begin{verbatim}
\begin{quotation}
This is
a foo.
\end{quotation}
\end{verbatim}

\noindent
produces in the printed manual

\begin{quotation}
\begin{quotation}
This is a foo.
\end{quotation}
\end{quotation}

\noindent
and in the Info file

\noindent
\begin{quotation}
\begin{example}
This is
a foo.
\end{example}
\end{quotation}

\clearpage
\node Example Environment, Display Environment, Quotation Environment, Making Quotations and Examples
\section{Example Environment}
\cindex{Example Environment}
\cindex{Examples}
\findex{example}

The \code{example} environment is used to indicate an example that is
not part of the running text.  In the printed manual, this is done by
switching to a fixed width font, turning off filling, and making extra
spaces and blank lines significant.  In the Info file, an analogous
result is obtained by indenting each line with five extra spaces.

\code{\back begin\{example\}} should appear on a line by itself; this
line will disappear from the output.  Mark the end of the example with a
line containing \code{\back end\{example\}}, which will likewise
disappear.  For example:\refill

\begin{verbatim}
\begin{example}
mv foo bar
\end{example}
\end{verbatim}

\noindent
produces

\begin{example}
mv foo bar
\end{example}

Since the lines containing \code{\back begin\{example\}} and 
\code{\back end\{example\}} will disappear, you will want to put 
a blank line before the \code{\back begin\{example\}} and another
blank line after the \code{\back end\{example\}}.  (Remember that
blank lines between the beginning \code{\back begin\{example\}} 
and the ending \code{\back end\{example\}} will appear in the output.)\refill

Don't use tabs in lines of an example!  \LaTeX\ treats them like single
spaces, and that is not what they look like.

\node Display Environment, Verbatim Environment, Example Environment, Making Quotations and Examples
\section{Display Environment}
\cindex{Display Environment}
\cindex{Display}
\findex{display}

The \code{display} environment is just like \code{example} except
that, in the printed manual, \code{display} does not select the
fixed-width font.  In fact, it does not specify the font at all, so that
the text appears in the same font it would have appeared in without the
\code{display}.\refill

\node Verbatim Environment, Center Environment, Display Environment, Making Quotations and Examples
\section{Verbatim Environment}
\cindex{Verbatim Environment}
\cindex{Including text verbatim}
\findex{verbatim}

The \code{verbatim} environment is very similar to the \code{example}
environment except that no parsing of the contents is carried out, and the
text is not indented.  In the Info file things will appear exactly as they
have been typed in. In the printed manual, this is the same as the 
\LaTeX\ command of the same name.  Verbatim environments cannot be nested,
nor can they appear inside another environment such as \code{example}.  The
\code{\back begin\{verbatim\}} and \code{\back end\{verbatim\}}
\emph{must} occur at the beginning of a line.\refill

\node Center Environment, Making Lists and Descriptions, Verbatim Environment, Making Quotations and Examples
\section{Center Environment}
\cindex{Center Environment}
\cindex{Centering a line}
\findex{center}

Text enclosed in a \code{center} environment produces lines of output
containing text centered between the margins.  This is the same
as the \code{center} environment of \LaTeX, and different from the
\TeX info command of the same name.

\node Making Lists and Descriptions, Itemize Environment, Center Environment, Top
\chapter{Making Lists and Descriptions}
\cindex{Making lists and descriptions}
\cindex{Lists and descriptions, making them}
\cindex{Descriptions and lists, making them}

\LaTeX info has several ways of making lists and two-column descriptions.
Lists can be bulleted or numbered while a two-column description can
highlight the items in the first column.  For example, this is an
enumerated list:

\begin{enumerate}
\item
This is a numbered item.

\item
This is the second item in this list.

\item
This is the third item on this list.
\end{enumerate}

\LaTeX info will automatically indent the text in lists or descriptions
and number an enumerated list.  This last feature is useful if you are
reordering the list, since you do not have to renumber it yourself.

Lists or descriptions are always begun by a \code{\back begin} command
on a line by itself and ended with a \code{\back end} command on a line
by itself.  For example, an enumerated list begins with the command
\code{\back begin\{enumerate\}} and ends with the command 
\code{\back end\{enumerate\}}; and an itemized list begins with the command
\code{\back begin\{itemize\}} and ends with the command 
\code{\back end\{itemize\}}.  The elements of a list are begun with the 
\code{\back item} command.\refill
\findex{end}

\clearpage
Here is an itemized list of the different kinds of table and lists:

\begin{itemize}
\item
Itemized lists with or without bullets.

\item
Numbered lists.

\item
two-column descriptions with highlighting.
\end{itemize}


\begin{menu}
* Itemize Environment::
* Enumerate Environment::
* Description Environment::
\end{menu}

\node Itemize Environment, Enumerate Environment, Making Lists and Descriptions, Making Lists and Descriptions
\section{Itemize Environment}
\cindex{Itemize Environment}
\findex{itemize}
\findex{item}

\code{\back begin\{itemize\}} is used to produce sequences of indented
paragraphs, with a mark inside the left margin at the beginning of each
paragraph.  The text of the indented paragraphs themselves come after
the \code{\back begin\{itemize\}}, up to another line that says
\code{\back end\{itemize\}}.  Before each paragraph for which a mark in
the margin is desired, place a line that says just \code{\back item}.
Don't put any other text on this line.

Info indents the lines in an itemized list by five columns, but it does
not fill them.  This can produce lines in the Info file that are too
wide.  You can either write shorter lines in the \LaTeX info file by
setting the fill column to five columns less than it is normally, or
else you can tell Info to refill the paragraphs by adding the command
\code{\back refill} to the end of the paragraph. (\xref{Refill}, for
more information about the use of the \code{\back refill} command.)

Usually, you should put a blank line before a \code{\back item}.  This
puts a blank like in the Info file.  Except when the entries are very
brief, a blank line looks better.  Here is an example of the use of
\code{itemize}, followed by the output it produces.

\begin{verbatim}
\begin{itemize}
\item
Some text for foo.
\item
Some text
for bar.
\end{itemize}
\end{verbatim}

\noindent
produces in the Info file

\begin{quotation}
\noindent
\begin{itemize}
\item
Some text for foo.
\item
Some text
for bar.
\end{itemize}
\end{quotation}

\node Enumerate Environment, Description Environment, Itemize Environment, Making Lists and Descriptions
\section{Enumerate Environment}
\cindex{Enumerate Environment}
\findex{enumerate}

The \code{enumerate} environment is like the \code{itemize} environment
except that the marks in the left margin contain successive integers
starting with 1.  Do not put any argument on the same line as
\code{\back begin\{enumerate\}}.  If you want, you can put a blank line
between the entries in the list.  This often makes it easier to read the
Info file.  For example,
\refill

\begin{verbatim}
\begin{enumerate}

\item
Some text for foo.

\item
Some text
for bar.
\end{enumerate}
\end{verbatim}

\noindent
produces in the Info file

\begin{quotation}
\noindent
\begin{enumerate}

\item
Some text for foo.

\item
Some text
for bar.
\end{enumerate}
\end{quotation}

\begin{ifinfo}
Info indents the lines of the enumerated list by five columns, but it does
not fill them.  As a result, the lines in the Info file may be too wide.
To prevent this, you can either write shorter lines in the \LaTeX info file
file by setting the fill column to five columns less than it is normally,
or else you can tell Info to refill the paragraphs by adding the command
\code{\back refill} to the end of the paragraph.  (\xref{Refill}, for more
information about the use of the \code{\back refill} command.)
\end{ifinfo}

\begin{iftex}
Info indents the lines of the enumerated list by five columns, but it does
not fill them, just as it does with an itemized list.  You may want to use
shorter lines for text within an enumerated list or use the \code{\back refill}
command at the end of the paragraph. (\xref{Refill}, for more information
about the use of the \code{\back refill} command.)
\end{iftex}

\node Description Environment, Making Cross References, Enumerate Environment, Making Lists and Descriptions
\section{Description Environment}
\cindex{Descriptions, making two-column}
\findex{description}
\findex{item}

The \code{description} environment is similar to \code{\back
begin\{itemize\}}, but allows you to specify a name or heading line for
each item.  (\xref{Itemize Environment}.)  The command is used to
produce two-column descriptions, and is especially useful for glossaries
and explanatory exhibits.  You must follow each use of \code{\back item}
inside of the description environment with text to serve as the heading
line for that item.  This text is put inside square brackets on the same
line as the \code{\back item} command.  Each heading line is put into
the first column of the table and the supporting text, which you put on
the line following the line beginning with \code{\back item}, goes into
the second column.\refill

Usually, you should put a blank line before a \code{\back item}.  This
puts a blank like in the Info file.  Except when the entries are very
brief, a blank line looks better.  The following description highlights
the text in the first column:

\begin{verbatim}
\begin{description}
\item[foo]
This is the text for \samp{foo}.
\item[bar]
This is the text for \samp{bar}.
\end{description}
\end{verbatim}

\noindent
produces

\begin{quotation}
\noindent
\begin{description}
\item[foo]
This is the text for \samp{foo}.
\item[bar]
This is the text for \samp{bar}.
\end{description}
\end{quotation}

Info indents the lines of text in the second column, but does not fill
them.  As a result, the lines in the Info file may be too wide.  To
prevent this, cause Info to refill the paragraphs after processing by
adding the command \code{\back refill} to the end of the paragraph.
(\xref{Refill}, for more information about the use of the 
\code{\back refill} command.)

\node Making Cross References, Xref, Description Environment, Top
\chapter{Making Cross References}
\cindex{Making cross references}
\cindex{Cross references}
\cindex{References}

Cross references are used to refer the reader to other parts of the same or
different \LaTeX info files.  In \LaTeX info, \dfn{nodes} are the points to
which cross-references can refer.

In general, a document should be designed so that it can be read
sequentially.  People soon tire of flipping back and forth to find
information that should be presented to them as they need it.  However,
there will be information (often too detailed for whatever the current
context may be) that is related to whatever is presented and to which
reference should be made.  More important, in an on-line help system or in
a reference manual, readers do \emph{not} read everything in sequence from
beginning to end.  Instead, they look up what they need.  For this reason,
such creations should contain many cross references to help the reader find
other information that he or she may not have read.

Although nodes are not a fundamental concept in a printed manual, they
still serve to define a cross-reference point and the variants of
\code{\back xref} still serve to make references.  Thus, if you are writing a
manual that will only be printed, and will not be used on-line, you
continue to use the \code{\back node} command for when you make cross
references.

There are several kinds of cross reference command.

\begin{description}
\item[\back xref]
Used to start a sentence in the printed manual saying, `See \dots' \\
or an entry in the Info file saying \samp{*note \dots}.

\item[\back pxref]
Used to make a reference that starts with a lowercase \samp{see} \\
and is usually contained within parentheses.\refill

\item[\back inforef]
Used to make a reference to an Info file for which there is no printed
manual.\refill
\end{description}


\begin{menu}
* Xref::
* Pxref::
* Inforef::
\end{menu}

\node Xref, Pxref, Making Cross References, Making Cross References
\section{Xref}
\cindex{Xref for cross references}
\findex{xref}
\findex{ref}
\findex{pageref}
\cindex{Cross references using xref}

\code{\back xref} generates a cross-reference.  In \LaTeX info, it turns into
an Info cross-reference which the Info \samp{f} command can use
to go directly to another node.  In \LaTeX, it turns into a sentence
of the form

\begin{example}
See section \var{section} [\var{topic}], page \var{page}
\end{example}

\noindent
but does not generate a period to end it.

\code{\back xref} must refer to an Info node created by 
\code{\back node}, by the node's name.  It uses the \LaTeX\ commands 
\code{\back ref} and \code{\back pageref}.

\code{\back xref} is followed by an argument inside braces; but actually the
text inside the braces is treated as several arguments, separated by
commas.  Whitespace after these commas is ignored.  A period or comma
\strong{must} follow the closing brace of a \code{\back xref}.  It is required
to terminate the cross reference.  This period or comma will appear in
the output, both in the Info file and in the printed manual.

The simplest form of \code{\back xref} takes one argument, the name of another
blank line and then the output text for Info files and the output text for
printed manuals.

\begin{example}
\back xref\{node-name\}, for more info.

*note node-name::, for more info.
\end{example}

\begin{quotation}
See section \var{nnn} [node-name], page \var{ppp}, for more info.
\end{quotation}

With two arguments, the second one is used as the name of the Info
cross-reference, while the first argument is still the node that the
cross-reference points to:

\begin{example}
\back xref\{node-name, name-for-note\}, for more info.

*note name-for-note: node-name, for more info.
\end{example}

\begin{quotation}
See section \var{nnn} [node-name], page \var{ppp}, for more info.
\end{quotation}

A third argument replaces the node name when it actually appears in the
\LaTeX\ output.  It should state the topic discussed by the section being
referenced.  Often, you will want to use initial uppercase letters so it
will be easier to read when the reference is printed.  Use a third argument
when the node name is unsuitable because of syntax, grammar or diction.

\begin{example}
\back xref\{node-name, name-for-note, Topic Description\}, for more info.

*note name-for-note: node-name, for more info.
\end{example}

\begin{quotation}
See section \var{nnn} [Topic Description], page \var{ppp}, for more info.
\end{quotation}

If a third argument is given and the second one is empty,
then the third argument serves both purposes:

\begin{example}
\back xref\{node-name, , Topic Description\}, for more info.

*note Topic Description: node-name, for more info.
\end{example}

\begin{quotation}
See section \var{nnn} [Topic Description], page \var{ppp}, for more info.
\end{quotation}

A fourth argument specifies the name of the Info file in which the
referenced node is located, assuming it is not the one in which the
reference appears.  \code{\back xref} with only four arguments is used
when the reference is not within one Info file, but is within a single
printed manual---when multiple \LaTeX info files are incorporated into
the same \LaTeX\ run but make separate Info files.  (This is seldom the
case and usually you will use five arguments if you are making a
reference that is outside the current Info file.)

\begin{example}
\back xref\{node-name, name-for-note, Topic, info-file-name\}, 
for more info.

*note name-for-note: (info-file-name) node-name, for more info.
\end{example}

\begin{quotation}
See section \var{nnn} [Topic], page \var{ppp}, for more info.
\end{quotation}

A fifth argument is used when you are making a reference to another Info
file which is also part of another printed manual.  Write the title of the
manual in this slot.  Since a different manual is made during a different
\LaTeX\ run, the printed reference will not have a page number.

\noindent
Whenever you refer to another manual, use this version of \code{\back xref}
with five arguments.

\begin{example}
\back xref\{node-name, name-for-note, Topic, info-file-name, A Printed Manual\},
for more info.

*note name-for-note: (info-file-name) node-name, for more info.
\end{example}

\begin{quotation}
See section Topic of \i{A Printed Manual}, for more info.
\end{quotation}

\noindent
The name of the printed manual will be typeset in italics.

Often, you will leave out the second argument when you use the long version
of \code{\back xref}.  In this case, the third argument, the topic description,
will replace the node name:


\begin{example}
\back xref\{node-name, , Topic Description, info-file-name, A Printed Manual\},
for more info.

*note Topic Description: (info-file-name) node-name, for more info.
\end{example}

\begin{quotation}
See section Topic Description of \i{A Printed Manual}, for more info.
\end{quotation}

\clearpage
\node Pxref, Inforef, Xref, Making Cross References
\section{Pxref}
\cindex{Pxref}
\cindex{Cross references using pxref}
\cindex{Pxref for cross references}
\findex{pxref}

\code{\back pxref} is nearly the same as \code{\back xref}; it differs
in only two ways:

\begin{enumerate}
\item
The output starts with lower case `see' rather than `See'.\refill
\item
A period is generated automatically in the Info file output to end the Info
cross-reference, but no period is generated for the printed manual.\refill
\end{enumerate}

The purpose of \code{\back pxref} is to be used inside parentheses as part of
another sentence.  In the printed manual, no period is needed after the
cross reference text itself (within the parentheses), but a period is
needed after the cross reference text in the Info file because only thus
can Info recognize the end of the cross-reference.  \code{\back pxref} spares
you the need to use complicated methods to put a period into one form of
the output and not the other.

\code{\back pxref} can be used with up to five arguments just like
\code{\back xref}.  (\xref{Xref}.)\refill

\node Inforef, Formatting Paragraphs, Pxref, Making Cross References
\section{Inforef}
\cindex{Inforef for cross references}
\cindex{Cross references using inforef}
\findex{inforef}

\code{\back inforef} is used for cross-references to Info files for
which there are no printed manuals.  Even in a printed manual,
\code{\back inforef} generates a reference directing the user to look in
an Info file.  \code{\back inforef} takes exactly three arguments.  The
syntax is \code{\back inforef\{\var{node}, \var{name}, \var{file}\}}.

\begin{example}
\back inforef\{node-name, name-for-note, info-file-name\}, for more information.

*note name-for-note: (info-file-name) node-name, for more information.
\end{example}

\begin{quotation}
See Info file \file{info-file-name}, node `node-name', for more information.
\end{quotation}

\node Formatting Paragraphs, Refilling Paragraphs and Preventing Indentation, Inforef, Top
\chapter{Formatting Paragraphs}
\cindex{Formatting paragraphs}
\cindex{Paragraphs, formatting}

Usually, a \LaTeX info file will be processed both by \LaTeX\ and by the\\
\kbd{M-x latexinfo-format-buffer} command.  Consequently, you must make sure
that text will come out looking right both in the printed manual and in the
on-line help.\refill

For example, unless told otherwise, \kbd{M-x latexinfo-format-buffer} will
not refill a paragraph after processing it although \LaTeX\ will.  This
means that a paragraph with numerous or large commands may not look
properly filled after processing by Info.  The commands are removed from
the text but the lines are not refilled so some are much shorter than they
were.  To cause the \kbd{M-x latexinfo-format-buffer} command to refill such
a paragraph, put \code{\back refill} at the end of the paragraph.\refill

\findex{same}
\LaTeX\ may also format a document improperly.  For example, page breaks may
occur in the ``wrong place''; to control this, text can be held together by a
\code{same} command that keeps the text within the group from being split 
across two pages.

\begin{iftex}
The first section that follows is about refilling and preventing
indentation; the second section is about line and paragraph breaks,
creating blank lines, and grouping text.
\end{iftex}


\begin{menu}
* Refilling Paragraphs and Preventing Indentation::
* Breaks Blank Lines and Groups::
\end{menu}

\node Refilling Paragraphs and Preventing Indentation, Refill, Formatting Paragraphs, Formatting Paragraphs
\section{Refilling Paragraphs and Preventing Indentation}
\cindex{Refilling paragraphs automatically}
\cindex{Preventing indentation in the printed text}

The \code{\back refill} and \code{\back noindent} commands are used just
after or just before paragraphs which, after processing by either Info
or \LaTeX, might look bad.  The \code{\back refill} command refills a
paragraph in the Info file after all the other processing has been done.
In the printed manual, the \code{\back noindent} command prevents a
piece of text that is a continuation of the preceding paragraph from
being indented as if it were a new paragraph.\refill

\begin{menu}
* Refill::	Refilling an info paragraph after other processing.
* Noindent::	Preventing paragraph indentation in continuation text.
\end{menu}

\node Refill, Noindent, Refilling Paragraphs and Preventing Indentation, Refilling Paragraphs and Preventing Indentation
\subsection{Refill}
\cindex{Refill}
\findex{refill}

If a paragraph contains sizable constructs, it may look badly filled after\\
\code{latexinfo-format-buffer} is through with it.  Put
\code{\back refill} at the end of the paragraph to tell
\code{latexinfo-format-buffer} to refill the paragraph after finishing
all other processing on it.  \code{\back refill} has no effect on
\LaTeX, which always fills everything that ought to be filled.  For
example,\refill

\begin{example}
To use \back code\{foo\}, pass \back samp\{xx%$\} and \back var\{flag\} and type \back kbd\{x\}
after running \back code\{make-foo\}.\back refill
\end{example}

\noindent
produces (in the Info file)

\begin{example}
To use `foo', pass `xx%$' and FLAG and type `x' after running `make-foo'.
\end{example}

\noindent
whereas without the \code{\back refill} it would produce

\begin{example}
To use `foo', pass `xx%$' and FLAG and type `x'
after running `make-foo'.
\end{example}

\noindent
with the line broken at the same place as in the \LaTeX info input file.

Do not put a space before \code{\back refill}; otherwise the command might be
put at the beginning of the line when you refill the paragraph in the
\LaTeX info file with \kbd{M-q} (\code{fill-paragraph}).  If this were to
happen, the \code{\back refill} command might fail to work.

\node Noindent, Breaks Blank Lines and Groups, Refill, Refilling Paragraphs and Preventing Indentation
\subsection{Noindent}
\cindex{Noindent}
\findex{noindent}

If you have text following an \code{example} or other similar ``special
paragraph'' that reads as a continuation of the text before the
\code{example}, it is good to prevent this text from being indented as a
new paragraph.  To accomplish this, put \code{\back noindent} on a line
by itself before the start of the text that should not be indented. For
example,\refill

\begin{example}
\back begin\{example\}
This is an example
\back end\{example\}

\back noindent
This line will not be indented.
\end{example}

\noindent
produces

\begin{example}
This is an example
\end{example}

\noindent
This line will not be indented.

To adjust the number of blank lines properly in the Info file output,
remember that the line containing \code{\back noindent} does not generate a
blank line, and neither does the \code{\back end\{example\}} line.

In the \LaTeX info source file for this documentation, each of the lines that
says `produces' is preceded by a line containing \code{\back noindent}.

\node Breaks Blank Lines and Groups, Line Breaks, Noindent, Formatting Paragraphs
\section{Breaks Blank Lines and Groups}
\cindex{Breaks Blank Lines and Groups}

\LaTeX info has several commands for making blank lines, for forcing paragraph
and page breaks in the printed manual and for preventing text from running
from one page to the next.

\begin{description}
\item[\back \back]
Force a line break in the printed manual.  This command has no effect on
the Info file.  (For compatibility with \TeX info, \code{\back *} also
forces a line break in the printed manual.)\refill

\item[\back sp]
Generate blank lines in both the printed manual and in the Info file.\refill

\item[\back br]
Force a paragraph break in the printed manual.  This command has no effect
on the Info file.\refill

\item[\back w]
Prevent text from being split across two lines in the printed manual.  This
command has no effect on the Info file.\refill

\item[\back clearpage]
Start a new page in the printed manual.  This
command has no effect on the Info file.\refill

\item[\back begin\{same\}]
Hold text together that must appear on one printed page.  This
command has no effect on the Info file.\refill

\end{description}

\begin{menu}
* Line Breaks::
* Line Spacing::
* Paragraph Breaks::
* Preventing A Line Break::
* Clearpage::
* Same Environment::
\end{menu}

\node Line Breaks, Line Spacing, Breaks Blank Lines and Groups, Breaks Blank Lines and Groups
\subsection{Line Breaks}
\findex{asterisk}
\findex{*}
\cindex{Line breaks}
\cindex{Breaks in a line}

\code{\back *} forces a line break in the printed manual.  It has no effect on
the Info file output, where line breaks follow those in the source file.
If you want a line break at a certain spot in both forms of output, break
the line there in the source file and put \code{\back *} at the end of the
line.


\node Line Spacing, Paragraph Breaks, Line Breaks, Breaks Blank Lines and Groups
\subsection{Line Spacing}
\findex{sp (line spacing)}
\cindex{Spaces from line to line}
\cindex{Line spacing}

A line containing \code{\back sp\{\var{n}\}} generates \var{n} blank lines of
space in either the printed manual or the Info file.  For example,

\begin{example}
\back sp\{2\}
\end{example}

\noindent
generates two blank lines.  

\node Paragraph Breaks, Preventing A Line Break, Line Spacing, Breaks Blank Lines and Groups
\subsection{Paragraph Breaks}
\findex{br (paragraph breaks)}
\cindex{Paragraph breaks}
\cindex{Breaks in a paragraph}

In a printed manual, a line containing \code{\back br} forces a paragraph
break; in the Info file output, it does nothing (not even a blank line
results from it).

\node Preventing A Line Break, Clearpage, Paragraph Breaks, Breaks Blank Lines and Groups
\subsection{Preventing A Line Break}
\cindex{Preventing A Line Break}
\findex{w (preventing a line break)}
\cindex{Line breaks, preventing}

In a printed manual, \code{\back w\{\var{text}\}} outputs \var{text} and
prohibits line breaks within \var{text}.  \code{\back w} has no effect
on the Info file output; it is the same as would result from just
\var{text}.


\node Clearpage, Same Environment, Preventing A Line Break, Breaks Blank Lines and Groups
\subsection{Clearpage}
\cindex{Clearpage}
\cindex{Page breaks}
\findex{clearpage}
\findex{newpage}
\findex{cleardoublepage}

A line containing \code{\back page} starts a new page in a printed manual.
The line has no effect on Info files since they are not paginated.  The
\LaTeX\ commands \code{newpage} and \code{cleardoublepage} are also
supported.

\node Same Environment, Marking Text Within a Paragraph, Clearpage, Breaks Blank Lines and Groups
\subsection{Same Environment}
\cindex{Same Environment}
\cindex{Holding text together vertically}
\cindex{Vertically holding text together}
\findex{same}

A line with \code{\back begin\{same\}} begins an unsplittable vertical
group, which must appear entirely on one page.  The group is terminated
by a line containing \code{\back end\{same\}}.  These two lines produce
no output of their own, and in the Info file output they have no effect
at all.

If you forget to end a group, you may get strange and unfathomable error
messages when you run \LaTeX.  This is because \LaTeX\ keeps trying to
put the rest of the \LaTeX info file into the group and error messages
do not start to get generated until \LaTeX\ has gone a long way.  It's a
good rule of thumb to look for a missing \code{\back end\{same\}} if you
get incomprehensible error messages in \LaTeX.

\node Marking Text Within a Paragraph, Specifying Definitions Files and Commands, Same Environment, Top
\chapter{Marking Text Within a Paragraph}
\cindex{Marking Text Within a Paragraph}
\cindex{Marking text within a paragraph}

In \LaTeX info, text within a paragraph can be marked in a variety of ways.
The most important way is to specify whether a word or phrase is a
definition, a metasyntactic variable, a literal example of a program or
what not.

In addition, there are special commands for inserting single characters 
that have special meaning in \LaTeX info, such as braces, and for inserting
symbols with special handling, such as dots and bullets.  Finally, there
are ways to emphasize words.


\begin{menu}
* Specifying Definitions Files and Commands::
* Inserting Braces Backslashes Periods::
* Inserting Dots Bullets and TeX::
* Emphasizing Text::
\end{menu}

\node Specifying Definitions Files and Commands, Code, Marking Text Within a Paragraph, Marking Text Within a Paragraph
\section{Specifying Definitions Files and Commands}
\cindex{Highlighting}
\cindex{Specifying commands, files and the like}
\cindex{Definitions, specifying them within text}
\cindex{Commands, specifying them within text}
\cindex{Files, specifying them within text}

\LaTeX info has a variety of commands for specifying just what kind of object a
piece of text refers to.  Metasyntactic variables, for example, are marked
by one command and code by another.  \LaTeX info uses this
information to determine how to highlight the text.  Since the pieces of
text are labelled by commands that tell what kind of object they are, it is
easy to change the way \LaTeX info formats and typesets such text.  For
example, code is usually illustrated in a typewriter font, but it would be
easy to change the way \LaTeX info highlights code to use another font.
This change would not effect how metasyntatic variables are highlighted.
If straight typesetting commands were used in the body of the file, you
would have to check every single occurrence to make sure that you were
changing code and not something else that should not be changed.

In addition, the commands can be used to generate useful information from
the file, such as lists of functions or file names.  It is possible, for
example, to write code in Emacs Lisp (or a keyboard macro) to insert an
index entry after every paragraph that contains the text labelled by a
specified command.  You could do this to construct an index of functions if
you had not already made the entries.

The commands serve a variety of purposes:

\begin{description}
\item[\back code]
Indicates text that is a literal example of a piece of a program.\refill

\item[\back samp]
Indicates text that is a literal example of a sequence of characters.\refill

\item[\back file]
Indicates the name of a file.\refill

\item[\back kbd]
Indicates the names of keys on the keyboard or characters you type.\refill

\item[\back key]
Used for the conventional name for a key on a keyboard.\refill

\item[\back ctrl]
Indicates an ASCII control character.

\item[\back var]
Indicates a metasyntactic variable.

\item[\back dfn]
Indicates the introductory or defining use of a term.

\item[\back cite]
Indicates the name of a Bib\TeX\ entry.
\end{description}


\begin{menu}
* Code::	A literal example of a piece of a program.
* Samp::	A literal example of a sequence of characters.
* File::	The name of a file.
* Kbd::		The names of keys or else characters you type.
* Key::		The conventional name for a key on a keyboard.
* Ctrl::	Indicates the ASCII control character.
* Var::		A variable.
* Dfn::		The introductory or defining use of a term.
* Cite::	The name of a bibliography entry.
\end{menu}

\node Code, Samp, Specifying Definitions Files and Commands, Specifying Definitions Files and Commands
\subsection{Code}
\cindex{Code}
\findex{code}

\code{\back code} is used to indicate text that is a piece of a program which
consists of entire syntactic tokens.  The text follows, enclosed in braces.

For example, \code{\back code} is used for an expression in a program,
the name of a variable or function used in a program, or a keyword.
\code{\back code} is not used for a piece of a token, such as when
speaking about the characters used in a token; for example, when you are
explaining what letters or printable symbols can be used in the names of
functions.  It is also not used for input to programs unless the input
is written in a language that is like a programming language.  For
example, it is not used for the single character commands of GNU Emacs
although it is used for the names of Emacs Lisp functions that the
keyboard commands invoke.  You should also \code{\back code} for command
names in command languages that resemble programming languages, such as
\LaTeX info or the shell.

In the printed manual, \code{\back code} puts the argument in bold face.
In the Info file, it uses `\dots' quotation.  For example:

\begin{example}
To compare two files, showing text inserted or removed, use \back code\{diff\}.
\end{example}

\noindent
produces

\begin{quotation}
To compare two files, showing text inserted or removed, use \code{diff}.
\end{quotation}

\begin{iftex}
In the Info file, it looks like this:

\begin{example}
\dots, use `diff'
\end{example}
\end{iftex}

\node Samp, File, Code, Specifying Definitions Files and Commands
\subsection{Samp}
\cindex{Samp}
\findex{samp}

\code{\back samp} is used to indicate text that is a literal example of a
sequence of characters in a file, string, pattern, etc.  The text follows,
enclosed in braces.  The argument appears within `\dots' quotation in
both the Info file and the printed manual; in addition, it is printed in a
fixed-width font.

\begin{example}
To match \back samp\{foo\} at the end of the line, use the regexp \back samp\{foo$\}.
\end{example}

\noindent
produces

\begin{quotation}
To match \samp{foo} at the end of the line, use the regexp \samp{foo$}.
\end{quotation}

Punctuation marks that are part of the English text that surrounds the
strings you are specifying are \emph{never} included within the braces.
In the following sentence, for example, the commas and period are
outside of the braces:

\begin{example}
A symbol name ends in \back samp\{a\}, \back samp\{b\}, or \back samp\{c\}.
\end{example}

\node File, Kbd, Samp, Specifying Definitions Files and Commands
\subsection{File}
\cindex{File}
\findex{file}

\code{\back file} is used to indicate text that is the name of a file or
directory.  Currently, it is equivalent to \code{\back samp} in its effects on
the output.  For example,\refill

\begin{example}
The \back file\{.el\} files are in 
the \back file\{/gnu/emacs/lisp\} directory.
\end{example}

\noindent
produces

\begin{quotation}
The \file{.el} files are in 
the \file{/gnu/emacs/lisp} directory.
\end{quotation}

\node Kbd, Key, File, Specifying Definitions Files and Commands
\subsection{Kbd}
\cindex{Kbd}
\findex{kbd}

\code{\back kbd} is used much like \code{\back code}.  The difference is that
\code{\back kbd} is for names of keys on the keyboard, or of characters you can
type.  For example, to refer to the command \kbd{M-a}, you would use

\begin{example}
\back kbd\{M-a\}
\end{example}

\noindent
and to refer to \kbd{M-x shell}, you would use

\begin{example}
\back kbd\{M-x shell\}
\end{example}

The \code{\back kbd} command has the same effect as \code{\back code} in Info,
but may produce a different font in a printed manual.\refill

You can embed another command inside the braces of a \code{\back kbd}
command.  This is the way to describe a command that would be described
more verbosely as ``press an \samp{r} and then press the \key{RET} key'':

\begin{example}
\back kbd\{r \back key\{RET\}\}  
\end{example}

\noindent
This produces: \kbd{r \key{RET}}

You also use the \code{\back kbd} command if you are spelling out the letters
you type; for example:

\begin{example}
To give the \back code\{logout\} command, 
type the characters \back kbd\{l o g o u t \back key\{RET\}\}.
\end{example}

\noindent
This produces

\begin{quotation}
To give the \code{logout} command, 
type the characters \kbd{l o g o u t \key{RET}}.
\end{quotation}

\node Key, Ctrl, Kbd, Specifying Definitions Files and Commands
\subsection{Key}
\cindex{Key}
\findex{key}

\code{\back key} is used for the conventional name for a key on a
keyboard, as in

\begin{example}
\back key\{RET\}
\end{example}

Often, \code{\back key} is used within the argument of a \code{\back kbd}
command, whenever the sequence of characters to be typed includes one or
more keys that are described by name.\refill

For example, to produce \kbd{C-x \key{ESC}} you would use 

\begin{example}
\back kbd\{C-x \back key\{ESC\}\}
\end{example}

The recommended names to use for keys are in upper case and are

\begin{description}
\item[SPC]
Space.
\item[RET]
Return.
\item[LFD]
Linefeed.
\item[TAB]
Tab.
\item[BS]
Backspace.
\item[ESC]
Escape.
\item[DEL]
Delete.
\item[SFT]
Shift.
\item[CTL]
Control.
\item[META]
Meta.
\end{description}

There are subtleties to handling words like `meta' or `ctrl' which are
names of shift keys.  When mentioning a character in which the shift key is
used, such as \kbd{Meta-a}, use the \code{\back kbd} command alone without the
\code{\back key} command, but when you are referring to shift key in isolation,
use the \code{\back key} command.  For example, you would use 
\samp{\back kbd\{Meta-a\}} to produce \kbd{Meta-a} and 
\samp{\back key\{META\}} to produce \key{META}.

\node Ctrl, Var, Key, Specifying Definitions Files and Commands
\subsection{Ctrl}
\cindex{Ctrl}
\findex{ctrl}

\code{\back ctrl} is used to describe an ASCII control character.  The pattern
of usage is \code{\back ctrl\{\var{ch}\}}, where \var{ch} is an ASCII
character whose control-equivalent is wanted.  Thus you put in an \samp{f}
when you want to indicate a \samp{control-f}.  For example, to specify
\samp{control-f}, you would enter

\begin{example}
\back ctrl\{f\}
\end{example}

\noindent
which produces

\begin{quotation}
\ctrl{f}
\end{quotation}

\noindent
In the Info file, this generates the specified control character, output
literally into the file.  This is done so a user can copy the specified
control character (along with whatever else he or she wants) into another
Emacs buffer and use it.  Since the `control-h',`control-i', and
`control-j' characters are formatting characters, they should not be
indicated this way.\refill

In a printed manual, this generates text to describe or identify that
control character: an uparrow followed by the character \var{ch}.

\node Var, Dfn, Ctrl, Specifying Definitions Files and Commands
\subsection{Var}
\cindex{Var}
\findex{var}

\code{\back var} is used to indicate metasyntactic variables.  A metasyntactic
variable is something that stands for another piece of text.  You would use
a metasyntactic variable in the documentation of a function to describe the
arguments that are passed to that function.

\code{\back var} is not used for names of particular variables in programming
languages.  For example, the \LaTeX info variable
\code{latexinfo-tex-command} is not a metasyntactic variable.
Its effect in the Info file is to to convert the argument to uppercase; in
the printed manual, to italicize it.  For, example:

\begin{example}
To delete file \back var\{filename\}, type \back code\{rm \back var\{filename\}\}.
\end{example}

\noindent
produces

\begin{quotation}
To delete file \var{filename}, type \code{rm \var{filename}}.
\end{quotation}

In some documentation styles, metasyntactic variables are shown with angle
brackets, for example: 

\begin{example}
\dots, type rm <filename>
\end{example}

\node Dfn, Cite, Var, Specifying Definitions Files and Commands
\subsection{Dfn}
\cindex{Dfn}
\findex{dfn}

\code{\back dfn} is used to identify the introductory or defining use of a
technical term.  The command should be used only in a passage whose purpose
is to introduce a term which will be used again or which the reader ought
to know.  Mere passing mention of a term for the first time doesn't deserve
\code{\back dfn}.  It generates italics in the printed manual, and double
quotation marks in the Info file.  Example:

\begin{example}
Getting rid of a file is called \back dfn\{deleting\} it.
\end{example}

\noindent
produces

\begin{quotation}
Getting rid of a file is called \dfn{deleting} it.
\end{quotation}

\node Cite, Inserting Braces Backslashes Periods, Dfn, Specifying Definitions Files and Commands
\subsection{Cite}
\cindex{Cite}
\findex{cite}

\code{\back cite} is the \LaTeX\  command for a bibliographic citations.
Citations are usually prepared using the program \t{BibTeX}, which formats
the citations for use with \LaTeX.  The argument to the \code{\back cite}
command is the citation key, which appears in the printed manual as the
citation key surrounded by square brackets.  How it appears in the printed
manual is dependent on the bibliographic style chosen.  See the \LaTeX\
Manual for more details (\cite{Lamport}).\refill

Before you use the \code{\back cite} command, you must declare the
bibliography style that you are going to use.
\xref{Making a Bibliography}.


\node Inserting Braces Backslashes Periods, Inserting A Backslash, Cite, Marking Text Within a Paragraph
\section{Inserting Braces Backslashes Periods}
\cindex{Braces, inserting}
\cindex{Periods, inserting}
\cindex{Single characters,  commands to insert}
\cindex{Commands to insert single characters}

\samp{\back } and curly braces are special characters in \LaTeX info.  
To insert parentheses, you have to put a \samp{\back } in front of these
characters in order to insert them into text.  To insert a backslash,
you must use the \code{\back back} command.

Periods are also special.  Depending on whether the period is inside of or
at the end of a sentence, less or more space is inserted after a period in
a typeset manual.  Since it is not always possible for \LaTeX info to determine
when a period ends a sentence and when it is used in an abbreviation,
special commands are needed.  (Usually, \LaTeX info figures out how to handle
periods, so you don't have to use the special commands; you just enter a
period as you would if you were using a typewriter, which means you put two
spaces after the period that ends a sentence and after a colon.)\refill

\begin{menu}
* Inserting A Backslash::		Inserting A Backslash.
* Insert Left Brace::		Inserting a left brace.
* Insert Colon::		Preventing unintended additional whitespace.
* Insert Period:: 		Inserting a period that does end a sentence.
\end{menu}

\node Inserting A Backslash, Insert Left Brace, Inserting Braces Backslashes Periods, Inserting Braces Backslashes Periods
\subsection{Inserting A Backslash}
\cindex{Inserting A Backslash}

\code{\back back} stands for a backslash in either printed or Info output.
Do not use \code{\back back} in chapter-structuring commands, or in the
arguments to a \code{\back node} command.

You must follow a \code{\back back} by a space in an \code{example} or
\code{display} environment.  This following space will be deleted in both
the \LaTeX\ and info output.


\node Insert Left Brace, Insert Right Brace, Inserting A Backslash, Inserting Braces Backslashes Periods
\subsection{Insert Left Brace}
\cindex{Insert Left Brace}
\findex{left-braces}

\code{\back \{} stands for a single \{ in either printed or Info output.

\node Insert Right Brace, Insert Colon, Insert Left Brace, Inserting Braces Backslashes Periods
\subsection{Insert Right Brace}
\cindex{Insert Right Brace}
\cindex{Insert Right Brace}
\findex{right-braces}

\code{\back \}} stands for a single \} in either printed or Info output.

\node Insert Colon, Insert Period, Insert Right Brace, Inserting Braces Backslashes Periods
\subsection{Insert Colon}
\cindex{Insert Colon}

\code{\back :}\: is used after a character such as period or colon which
normally causes \LaTeX\ to increase the width of the following whitespace,
to suppress that effect.  For example, it can be used after periods that
end abbreviations and do not end sentences.  \code{\back :}\: has no effect
on the Info file output.

\begin{example}
It displays \back code\{Foo:\}\back : at that time.
\end{example}

\noindent
produces

\begin{quotation}
It displays \code{Foo:}\: at that time.
\end{quotation}

The meanings of \code{\back :}\: and \code{\back .}\: in \LaTeX info are
designed to work well with the Emacs sentence motion commands.

\node Insert Period, Inserting Dots Bullets and TeX, Insert Colon, Inserting Braces Backslashes Periods
\subsection{Insert Period}
\cindex{Insert Period}
\findex{periods}

\code{\back .}\: stands for a period that really does end a sentence, useful
when \LaTeX\ would otherwise assume by its heuristics that that is not so.
This happens when there is a single-capital-letter word at the end of a
sentence: \LaTeX\ normally guesses that it is an abbreviation.

In the Info file output, \code{\back .}\: is equivalent to a simple \samp{.}.
The \LaTeX info program preserves the amount of space that you use, so put
two spaces after a period if you intend it to be the end of a sentence
(as well as using \code{\back .}, if necessary, for the printed manual's sake).

\begin{example}
Give it to X. Give it to X\back .  Give it to X\back .
\end{example}

\noindent
produces

\begin{quotation}
Give it to X. Give it to X\.  Give it to X\.
\end{quotation}

\node Inserting Dots Bullets and TeX, Dots, Insert Period, Marking Text Within a Paragraph
\section{Inserting Dots Bullets and TeX}
\cindex{Dots, inserting}
\cindex{Bullets, inserting}
\cindex{TeX-logo, inserting}
\cindex{LaTeX-logo, inserting}
\cindex{Special typesetting commands}
\cindex{Typesetting commands for dots and the like}

An ellipsis, a line of dots, is typeset differently than a string of
periods; more whitespace is put between the dots in the ellipsis than is
put between the periods.  Because of this, a special command is used in
\LaTeX info for inserting dots.  Also, the trademark, \LaTeX, is typeset in a
special fashion and it needs a command, as does the command for
inserting the copyright symbol.  The \code{\back bullet} command is
special, too.

\begin{menu}
* Dots::
* Bullet::
* Tex::
\end{menu}

\node Dots, Bullet, Inserting Dots Bullets and TeX, Inserting Dots Bullets and TeX
\subsection{Dots}
\findex{dots}
\cindex{Inserting dots}
\cindex{Dots, inserting}


\code{\back dots} generates an ellipsis which is three dots in a row,
appropriately spaced, like this: `\dots'.  Do not simply write three
periods in the input file; that would work for the Info file output, but
would produce the wrong amount of space between the periods in the printed
manual.

\begin{iftex}
Here is an ellipsis: \dots

Here are three periods in a row: ...

The three periods in a row are closer together than the dots in the ellipsis.

\end{iftex}

\node Bullet, TeX, Dots, Inserting Dots Bullets and TeX
\subsection{Bullet}
\cindex{Bullet}
\findex{bullet}

\code{\back bullet} generates a large round dot, or the closest possible
thing to one.

Here is a bullet: \bullet

\node TeX, Emphasizing Text, Bullet, Inserting Dots Bullets and TeX
\subsection{TeX}
\cindex{TeX}
\findex{TeX}
\findex{LaTeX}

\code{\back TeX} generates `\TeX'.  In a printed manual, this is a
special logo that is different from three ordinary letters.  
\code{\back LaTeX} generates `\LaTeX'.  In a printed manual, this is
a special logo that is different from five ordinary letters.


\node Emphasizing Text, Emph and Strong, TeX, Marking Text Within a Paragraph
\section{Emphasizing Text}
\cindex{Emphasizing text}

Usually, \LaTeX info changes the font automatically to mark words in the
text according to what category the words belong to.  The \code{\back code}
command, for example, does this.  Most often, this is the best way to mark
specified words.  However, sometimes you will want to emphasize text
directly. \LaTeX info has two ways to do this: commands that tell 
\LaTeX info to emphasize the text but leave the method to the program, and
commands that specify the font to use.  The first method is generally the
best and it makes it possible to change the style of a document without
have to re-edit it line by line.

\begin{menu}
* Emph and Strong::	Emphasizing text.
* Fonts::		Selecting italic, bold or typewriter fonts.
\end{menu}

\node Emph and Strong, Fonts, Emphasizing Text, Emphasizing Text
\subsection{Emph and Strong}
\cindex{Emph and Strong}
\findex{emph}
\findex{strong}

\code{\back emph} and \code{\back strong} are two forms of emphasis.  \code{\back strong}
is stronger.

In printed output, \code{\back emph} produces \emph{italics} and
\code{\back strong} produces \strong{bold}.  In the Info file, both of
these commands put asterisks around the argument.

\node Fonts, Input and Include Files, Emph and Strong, Emphasizing Text
\subsection{Fonts}
\cindex{Fonts}
\findex{i (italic font)}
\findex{b (bold font)}
\findex{t (typewriter font)}

These three commands specify font changes in the printed manual and have no
effect in the Info file.  \code{\back i} requests \i{italic} font (in some
versions of \LaTeX, a slanted font is used), \code{\back b} requests \b{bold}
face, and \code{\back t} requests the \t{fixed-width} font used by
\code{\back kbd}.  All three commands apply to an argument that follows,
surrounded by braces.\refill

If possible, you should avoid using these three commands.  If you find a
need to use one, it probably indicates a lack in the \LaTeX info language.

\node Input and Include Files, Input Files, Fonts, Top
\chapter{Input and Include Files}
\cindex{Input and Include Files}

When Info was first created, it was customary to create many small Info
files on one subject.  By doing this, Emacs did not have to make a large
buffer to hold the whole of a large Info file; instead, Emacs allocated
just enough memory for the small Info file that was needed at the time.
This way, Emacs could avoid wasting memory.  Include Files were designed
as a way to create a single, large printed manual out of several smaller
Info files.  However, because large Info files can now be split, include
files are no longer strictly necessary and they are used infrequently.
Most often, they are now used in projects where several different people
are writing different sections of a document simultaneously.  

Input files are simply inserted at the place where the \code{input} command
occurs, both in the Info file and the \LaTeX\ file.

\begin{menu}
* Input Files::
* Include Files::
\end{menu}

\node Input Files, Include Files, Input and Include Files, Input and Include Files
\section{Input Files}
\cindex{Input Files}
\findex{input}

A line of the form \code{\back input\{\var{filename}\}} will include the
contents of the file \var{filename} at that point.  A standard technique is
to have a special file, used only for making a comprehensive manual,
containing nothing but the beginning, the end, and a series of \code{\back
input} commands.  The \code{\back input} \emph{must} occur at the beginning
of a line.

A file that is intended to be processed with \code{\back input}
should not end with \code{\back end\{document\}}, since that would
terminate \LaTeX\  processing immediately.


\node Include Files, Conditionals, Input Files, Input and Include Files
\section{Include Files}
\cindex{Include Files}
\findex{include}

In a \LaTeX info file, the command \code{\back include\{filename\}} is
ignored when the Info file is generated, but in a printed manual it
causes the contents of the file \file{filename} to be processed and
included in the manual.  The contents of the file
\file{filename} can be ignored by Info because the first file can refer
to \file{filename} with menus as well as cross references.  In the Info
system, all the information is, as it were, `in one place'.  However,
when two printed manuals are made from two separate \LaTeX info files,
the two manuals are separate, and even if they give each other as
references, the references are to separate documents.  Consequently, you
will sometimes want to create a comprehensive, printed manual that
contains all the necessary information together in one place.

\code{\back include} files are special \LaTeX info files that are used only for
making such a comprehensive manual.  They are listed inside an outer file
that contains nothing but the beginning and end matter of a \LaTeX info file
and a number of \code{\back include} commands listing the included files.

An \code{\back include} file should not start with 
\samp{\back documentstyle[latexinfo]}, as that has already been done by
the outer file.  A \code{\back include} file usually begins with a node; it
lacks the beginning and ending of a \LaTeX info file that are described in
the chapters on beginning and Ending a LaTeXinfo File. \xref{Beginning a
LaTeXinfo File}, and \pxref{Ending a LaTeXinfo File}.  Likewise, a
\code{\back include} file should not end with \code{\back end\{document\}},
since that would terminate \LaTeX\ processing immediately.\refill

Here is an example of an outer \LaTeX info file with \code{\back include} files
within it:\refill

\clearpage
\begin{verbatim}
\documentstyle[12pt,latexinfo]{book}
\pagestyle{headings}
\begin{document}
\bibliographystyle{alpha}

\newindex{cp}

\title{The Manual}

\author{Fred Foobar,\\
	Clarke Institute,\\
	999 Queen Street,\\
	Toronto, Ontario}

\date{\today}

\maketitle
\tableofcontents
\clearpage

\setfilename{themanual.info}

\include{foo.texinfo}
\include{bar.texinfo}

\begin{tex}
\bibliography{references}
\end{tex}

\twocolumn
 \unnumbered{Function Index}
 \printindex{fn}

 \unnumbered{Variable and Data Type Index}
 \printindex{vr}

\end{document}
\end{verbatim}

\node Conditionals, Using LaTeX Commands, Include Files, Top
\chapter{Conditionals}
\cindex{Conditionals}
\cindex{Ifinfo}
\cindex{Iftex}
\findex{ifinfo}
\findex{iftex}
\findex{ignore}
\findex{c}
\findex{comment}

You may not always be able to use the same text for both the printed manual
and the on-line Info file.  In this case, you can use the conditional
environments  to specify which text is for the printed manual and which is for
the Info file.

\code{\back begin\{ifinfo\}} begins text that should be ignored by 
\LaTeX\ when it typesets the printed manual.  The text appears only 
in the Info file.  The \code{\back begin\{ifinfo\}} command should appear on a
line by itself.  End the info-only text with a line containing
\code{\back end\{ifinfo\}} by itself.  At the beginning of a \LaTeX info file,
the Info permissions are contained within a region marked by 
\code{\back begin\{ifinfo\}} and \code{\back end\{ifinfo\}}.\refill

Likewise, \code{\back begin\{iftex\}} and \code{\back end\{iftex\}}
lines delimit text that will not appear in the Info file but will appear
in the printed manual.\refill

For example, 

\begin{verbatim}
\begin{iftex}
This text will appear only in the printed manual.
\end{iftex}

\begin{ifinfo}
However, this text will appear only in the info manual.
\end{ifinfo}
\end{verbatim}

\noindent
The preceding example produces the following.  Note how you only see one of
the two lines, depending on whether you are reading the on-line Info version
or the printed version of this manual.

\begin{iftex}
This text will appear only in the printed manual.
\end{iftex}

\begin{ifinfo}
However, this text will appear only in the info manual.
\end{ifinfo}

\code{\back begin\{ignore\}} and \code{\back end\{ignore\}}
lines delimit text that will not appear in either the Info file or
the printed manual.\refill

The \code{\back comment} or \code{\back c} command introduces comments that
will not appear in either the Info file or the printed manual; anything
following the \code{\back c} command will be ignored, up to and including
the end of the line.


\begin{menu}
* Using LaTex Commands::		Using commands from regular LaTeX.
\end{menu}

\node Using LaTeX Commands, Printing Hardcopy, Conditionals, Conditionals
\section{Using LaTeX Commands}
\cindex{Using LaTeX Commands}
\cindex{LaTeX commands, using them}

Inside a region delineated by \code{\back begin\{iftex\}} and 
\code{\back end\{iftex\}}, you can embed ordinary \LaTeX\ commands.  Info
will ignore these commands since they are only in that part of the file
that is seen by \LaTeX.  Note that you still have the characters \code{#
$ % ^ \& _ |} all printing as normal characters.  You can enter \LaTeX\
completely, by delineating a region with the \code{\back begin\{tex\}}
and \code{\back end\{tex\}} commands.  For example,\refill

\begin{verbatim}
\begin{tex}
\bibliography{references}
\end{tex}
\end{verbatim}

\noindent
is how you would include a \LaTeX\ bibliography.  In the Info file, nothing
between \code{\back begin\{tex\}} and \code{\back end\{tex\}} will appear,
i.e\. \code{tex} implies \code{iftex}.\refill

\node Printing Hardcopy, Formatting Requirements, Using LaTeX Commands, Top
\chapter{Printing Hardcopy}
\cindex{Printing hardcopy}
\cindex{Hardcopy, printing it}
\cindex{Making a printed manual}
\cindex{Sorting indices}
\cindex{Indices, sorting}
\findex{texindex (for sorting indices)}

There are three shell commands for printing a hardcopy of a \LaTeX info file.
One is for formatting the file, the second is for sorting the index and the
third is for printing the formatted document.  When you use the shell
commands, you can either work directly in the operating system shell or
work within a shell inside of GNU Emacs.

The typesetting program \LaTeX\ is used for formatting a \LaTeX info file.
\LaTeX\ is a very powerful typesetting program and, if used correctly, does
an exceptionally good job.  The macros used in a \LaTeX info file are
defined by a file called \file{latexinfo.sty}, which is why the beginning
of every \LaTeX info file starts with the line that says\\
\samp{\back documentstyle[latexinfo]}; this command tells \LaTeX\ to use the
\file{latexinfo.sty} file in processing the \LaTeX info file.
\code{latexinfo-format-buffer} reads the very same commands in the
\LaTeX info file and processes them differently from \LaTeX\ to make an
Info file.\refill

Usually, the \LaTeX\ formatting command is the shell command \code{latex}
followed by the name of the \LaTeX info file.  The \LaTeX\ command produces a
formatted DVI file as well as several auxiliary files containing indices,
cross references, etc.  The DVI file (for \dfn{DeVice Independent} file)
can be printed on a wide variety of printers.\refill

The \LaTeX\ formatting command itself does not sort the indices. Hence,
to generate a printed index, you first need a sorted index to work from.
\LaTeX\ outputs raw, unsorted index files under names that obey a
standard convention.  These names are the name of your main input file
to \LaTeX, 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 \file{foo.texinfo} would be
\file{foo.cp}, \file{foo.vr}, \file{foo.fn}, \file{foo.tp},
\file{foo.pg} and \file{foo.ky}.  Those are exactly the arguments to
give to \code{texindex}.  Or else, on UNIX, you can use \samp{??} as
``wild-cards'' and give the command in this form:\refill

\begin{example}
texindex foo.??
\end{example}

For each file specified, \code{texindex} generates a sorted index file
whose name is made by appending \samp{s} to the input file name.  The
\code{\back printindex} command knows to look for a file of that name.
\code{texindex} does not alter the raw index output file. After you have
sorted the indices, you need to rerun the \LaTeX\ command on the \LaTeX info
file.  This regenerates a formatted DVI file with the index entries in the
correct order.\refill

To summarize, this is a three step process:
 
\begin{enumerate}
\item
Run the \LaTeX\ command on the \LaTeX info file.  This generates the formatted
DVI file as well as the raw index files with two letter extensions.\refill

\item
Run the shell command \code{texindex} on the raw index files to sort them.
The arguments to \code{texindex} are the names of the raw index files.
\code{texindex} creates sorted index files whose names are the names of the
raw index files with an \samp{s} appended.\refill

\item
Rerun the \LaTeX\ command on the \LaTeX info file.  This regenerates a formatted
DVI file with the index entries in the correct order.  This second run also
makes all the cross references correct as well.  (The tables of contents
are always correct.)\refill
\end{enumerate}

If you are including a bibliography, you should also run the
\code{bibtex} command on the file between steps 1 and 3.  You need not
run \code{texindex} after each \LaTeX\ run.  If you don't, the next
\LaTeX\ run will use whatever sorted index files happen to exist from
the previous use of \code{texindex}.  This is usually ok while you are
debugging.

Finally, the document can be printed out with the DVI print command
(a shell command).  Depending on the system used, the DVI print command
will be a command such as \code{lpr -d}.  The DVI print command may require
a file name with the \samp{.dvi} extension.

The following commands, for example, sort the indices, format and print the
Bison Reference Manual (\cite{BisonReferenceManual}) (where \samp{%} is the
shell prompt):

\begin{example}
% latex bison.texinfo
% texindex bison.??
% bibtex bison
% latex bison.texinfo
% lpr -d bison.dvi
\end{example}

\noindent
(Remember that the words for the shell commands may be different at your
site; but these are commonly used versions.)

It is often most convenient to give formatting and printing commands from a
shell within GNU Emacs.  This way, you can easily keep track of errors.  To
create a shell within Emacs, type \kbd{M-x shell}.  In this shell, you can
format and print the document.  You can switch to and from this shell while
it is running and do other things.  If you are formatting a very long
document on a slow machine, this can be very convenient; on a VAX 750, for
example, formatting often takes 8 seconds or more per page depending on how
loaded the computer is.  Faster machines take correspondingly less time.


\begin{menu}
* Formatting Requirements::
* Using Local Variables and the Compile Command::
\end{menu}

\node Formatting Requirements, Using Local Variables and the Compile Command, Printing Hardcopy, Printing Hardcopy
\section{Formatting Requirements}
\cindex{Requirements for formatting }
\cindex{Formatting requirements}

Every \LaTeX info file that is to be input to \LaTeX\ must begin with a line
that looks like

\begin{verbatim}
\documentstyle[12pt,latexinfo]{book} \c -*-latexinfo-*-
\end{verbatim}

\noindent
This serves two functions.

\begin{enumerate}
\item
When the file is processed by \LaTeX, it loads the macros needed for
processing a \LaTeX info file.\refill
\item
When the file is edited in Emacs, it causes LaTeXinfo Mode to be used.\refill
\end{enumerate}

Every \LaTeX info file must end with a line saying

\begin{verbatim}
\end{document}
\end{verbatim}

\noindent
which terminates \LaTeX\ processing and forces out unfinished pages.

You also have to include a line that specifies the Info file name.

\begin{example}
\back setfilename\{\var{name-of-latexinfo-file}\}
\end{example}

By default, \LaTeX\ typesets pages for printing in an 8.5 by 11 inch
format.  However, you can direct \LaTeX\ 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 \LaTeX info
file, before the \code{\back setfilename} command:

\begin{example}
\back smallbook
\end{example}

\noindent
The Free Software Foundation distributes printed copies of the
GNU Emacs Manual \cite{GNUEmacsManual} in this size.

Finally, \LaTeX\ sometimes is unable to typeset a line without extending
it into the right margin.  This can occur when \LaTeX\ comes upon what it
interprets as a long word that it cannot hyphenate, like a net address,
or a very long title.  When this happens, \LaTeX\ prints an error message
like this:

\begin{example}
Overfull \back hbox (20.76302pt too wide)
\end{example}

\noindent
and gives the line number along with the text of the offending line
marked at all the places that \LaTeX\ knows to hyphenate words.  (In
\LaTeX\ lines are in `horizontal boxes', hence the term, `hbox'.)

If the \LaTeX info file has an overfull hbox, you can rewrite the sentence
so the overfull hbox does not occur or you can decide to leave it.  A small
excursion into the right margin often does not matter and may not even be
noticable.  However, unless told otherwise, \LaTeX\ will print a large,
ugly, black rectangle beside every line that is overfull.  This is so you
will notice the location of the problem if you are correcting a draft.  To
prevent such monstrosities from marring your final printout, put the
following in the beginning of the \LaTeX info file before the \code{\back
setfilename} command:

\begin{verbatim}
\finalout
\end{verbatim}

\xref{Titlepage}, for information about creating a title page.
\xref{Generating a Table of Contents}, for information about creating a 
table of contents.\refill

\node Using Local Variables and the Compile Command, Creating an On-line Info File, Formatting Requirements, Printing Hardcopy
\section{Using Local Variables and the Compile Command}
\cindex{Using Local Variables and the Compile Command}
\cindex{Local variables}
\cindex{Compile command for formatting}
\cindex{Formatting with the compile command}

Another way to give the \LaTeX\ formatting command to \LaTeX info is to
put that command in a \dfn{local variables list} at the end of the
\LaTeX info file.  You can then specify the \LaTeX\ formatting command
as a \code{compile-command} and have Emacs run the \LaTeX\ formatting
command by giving the command \kbd{M-x compile}.  This creates a special
shell called the \samp{*compilation buffer*}.  For example, at the end
of the \file{gdb.texinfo} file, after the \code{\back end\{document\}},
you would put the following:\refill

\begin{example}
\back c Local Variables:
\back c compile-command: "latex gdb.texinfo"
\back c End:
\end{example}

\noindent
This technique is most often used by programmers who compile programs
this way.
     
\node Creating an On-line Info File, Installing an Info file, Using Local Variables and the Compile Command, Top
\chapter{Creating an On-line Info File}
\cindex{Creating an on-line Info file}
\cindex{Running Info}
\cindex{Info, creating an on-line file}
\cindex{Formatting a file for Info}
\cindex{Indirect subfiles}
\findex{latexinfo-format-buffer}

In GNU Emacs, using LaTeXinfo Mode, you can see what part or all of a
\LaTeX info file will look like in Info by using the keyboard command
\ctrl{c} \ctrl{f} (\code{latexinfo-format-region}).  This formats a region
and displays in a temporary buffer called \samp{*Info Region*}; however,
this command does not turn on Info reading program---it just displays
what the region will look like.  The \code{latexinfo-format-region}
command is described more extensively in the chapter on using LaTeXinfo
Mode.  \xref{Formatting a Region for Info}.
\refill

In GNU Emacs, the way to create a working Info file is to visit the file
and invoke

\begin{example}
\kbd{M-x latexinfo-format-buffer}
\end{example}

\noindent
A new buffer is created and the Info file text is generated there.
\ctrl{x} \ctrl{s} (\code{save-buffer}) will save it under the name 
specified in the \code{\back setfilename} command.\refill

If the \LaTeX info file has more than 30,000 bytes,
\code{latexinfo-format-buffer} will automatically create a \dfn{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, \code{latexinfo-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 \dfn{include} files were
designed as a way to create a single, large printed manual out of the
smaller Info files. \xref{Input and Include Files}, for more
information.)\refill

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 \dfn{indirect} files.

The split--off files have names that are created by appending \samp{-1},
\samp{-2}, \samp{-3} and so on to the file names specified by the
\code{\back setfilename} command.  The shortened version of the original file
continues to have the name specified by \code{\back setfilename}.

At one stage in writing this document, for example, the Info file was saved
as \file{test-texinfo} and that file looked like this:

\begin{example}
Info file: test-texinfo,    -*-Text-*-
produced by latexinfo-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)
\dots
\end{example}

\noindent
(But \file{test-texinfo} had far more nodes than are shown here.)  Each of
the split--off, indirect files, \file{test-texinfo-1},
\file{test-texinfo-2}, and \file{test-texinfo-3}, is listed in this file
after the line that says \samp{Indirect:}.  The tag table is listed after
the line that says \samp{Tag table:}. \refill

You cannot run the \kbd{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, \pxref{Info-Validating a Large 
File}\refill


\begin{menu}
* Installing an Info file::
* Extending LaTeXinfo::
\end{menu}

\node Installing an Info file, Extending LaTeXinfo, Creating an On-line Info File, Creating an On-line Info File
\section{Installing an Info file}
\cindex{Installing an Info file}
\cindex{Info file installation}
\cindex{Dir directory for Info installation}

An Info file is usually installed in the GNU Emacs directory called
\file{info}.  This directory is the values of the Emacs variable
\code{Info-directory}.  For Info to work, this directory must contain
all the Info files, including the split--off files.  In addition, the
\file{info} directory must have a file that serves as a top--level
directory for the Info system.  This file is called \file{dir}.


For example, in the \file{info} directory, the file called \file{dir}
has the top--level menu for all the Info files in the system.  This
directory is the one defined by the GNU Emacs variable
\code{Info-directory}.  This file has a master menu that looks like
this:

\begin{example}
* 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.
\end{example}

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:

\begin{example}
* GDB: (gdb).           The source-level C debugger.
\end{example}

\noindent
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 \samp{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 \samp{(dir)} as the
parent of the top node; this is short for \samp{(dir)top}, the node \samp{top}
in the file \file{dir}, which is the main menu of Info.

\node Extending LaTeXinfo, Catching Mistakes, Installing an Info file, Creating an On-line Info File
\section{Extending LaTeXinfo}
\cindex{Extending LaTeXinfo}
\cindex{LATEXINFO environment variable}
\cindex{environment variable, LATEXINFO}

Let's say that you wanted to develop a special format for a program
called \code{macsyma}, which defined the command \code{\back f} to be
used for specifying functions.  This command would put its argument in
the function index, and set the function in the printed manual in a
special font.  You could create a style file called \file{macsyma.sty}
that contained this definition (and any others you might want for
Macsyma).  The \LaTeX\ commands to do this are quite simple:

\begin{verbatim}
\def\f#1{\findex{#1}{\sf #1}}
\end{verbatim}

\noindent
Then you include \code{macsyma} in the list of options to the
\code{documentstyle} command, \emph{after} the \code{latexinfo} option.
Your \LaTeX info file would begin with

\begin{verbatim}
\documentstyle[12pt,latexinfo,macsyma]{book}
\end{verbatim}

But what about the Info file?  As it stands, the command \code{\back f}
is not defined in \LaTeX info, so when you formatted the buffer it would
ignore all the \code{\back f} commands, and their arguments.  You need
to introduce the appropriate Emacs lisp code to provide the definition
of the command that you have added.  For each option in the
\code{documentstyle} command, \LaTeX info looks to see if the file name
\var{option}\code{-fmt.el} exists in the directory defined by the Emacs
variable \code{latexinfo-formats-directory}.  (This variable defaults to
the value of the environment variable \code{LATEXINFO}). If it does
exist, then it loads this file.  So continuing with our example, if the
file \file{macsyma-fmt.el} contained the code

\begin{example}
(put 'f 'latexinfo-format 'latexinfo-format-code)
\end{example}

\noindent
then it would define the \code{\back f} command to treat its argument
the same way that the \code{\back code} command does.

After the \var{option}\code{-fmt.el} has been loaded, \LaTeX info checks
to see if a function (of no arguments) called \var{option}\code{-fmt-hook}
has been defined.  If so, this function is called.  This allows you to
define functions in the \var{option}\code{-fmt.el} file that operate
on the whole \LaTeX info file.

\LaTeX\ provides a number of optional style files by default.  These include 
\code{latexinfo, 11pt, 12pt, twoside} and \code{titlepage}.  If any of
the optional styles is a member of the Emacs variable
\code{latexinfo-known-document-styles}, then \LaTeX info does not bother to
look for the associated \code{-fmt} file.

\node Catching Mistakes, Catching Errors with Info Formatting, Extending LaTeXinfo, Top
\chapter{Catching Mistakes}
\cindex{Structure of LaTeXinfo, catching mistakes}
\cindex{Nodes, catching mistakes}
\cindex{Nodes, correcting mistakes}
\cindex{Catching mistakes}
\cindex{Correcting mistakes}
\cindex{Mistakes, catching}
\cindex{Problems, catching}
\cindex{Debugging the LaTeXinfo structure}

Besides mistakes with the content of what ever you are describing, there
are two kinds of mistake you can make with \LaTeX info: 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\\
\kbd{M-x latexinfo-format-region} on regions of your file as you write
it.  In \LaTeX info mode, the \code{latexinfo-format-region} command is
bound to \ctrl{c} \ctrl{f}.  In addition, you can run \LaTeX\ on the
whole file.\refill

For finding problems with the structure of nodes and chapters, you can
use \ctrl{c} \ctrl{s} (\code{latexinfo-show-structure}) (and the related
\code{occur} command) and you can use the \kbd{M-x Info-validate}
command.

\begin{menu}
* Catching Errors with Info Formatting::
* Catching Errors with LaTeX Formatting::
* Using latexinfo-show-structure::
* Finding Badly Referenced Nodes::
\end{menu}

\node Catching Errors with Info Formatting, Using the Emacs Lisp Debugger, Catching Mistakes, Catching Mistakes
\section{Catching Errors with Info Formatting}
\cindex{Catching errors with Info Formatting}
\cindex{Debugging with Info Formatting}

After you have written part of a \LaTeX info file, you can use the\\
\kbd{M-x latexinfo-format-region} command to see whether the region
formats properly.  In LaTeXinfo Mode, this command is bound to the
keyboard command \ctrl{c} \ctrl{f}.  If you have made a mistake with a
command, \kbd{M-x latexinfo-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 \samp{*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.\refill

The \code{latexinfo-format-region} command does not always recognize errors.
For example, no errors were reported when \code{latexinfo-format-region} was
run on the whole itemized list of which the following is a part:

\begin{example}
name of the \LaTeX info file as an extension.  The \back samp\{??\} are
`wildcards' that cause the shell to substitute all the raw index files.
(\back xref\{sorting indices), for more information about sorting indices.)
 \back refill
\back cindex\{Sorting indices\}
\back cindex\{Indices, sorting\}

\back item 
\back emph\{Third\}, rerun the \back TeX\ command on the \LaTeX info 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.
\end{example}

\noindent
Instead, \code{latexinfo-format-region} ran without reporting the error, but
it produced output that looked like this:

\begin{example}
name of the latexinfo 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.) \back refill \back cindex Sorting indices \back cindex Indices: sorting indices), rerun the TeX command on the latexinfo 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.
\end{example}

\noindent
However, when \code{latexinfo-format-region} was run on part of the list that
is shown, it did give an error message, \samp{Search failed: "[\},]"}.
(This error message is explained in the section on using the Emacs Lisp
Debugger, \pxref{Using the Emacs Lisp Debugger})

Sometimes \code{latexinfo-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.\refill

\node Using the Emacs Lisp Debugger, Catching Errors with LaTeX Formatting, Catching Errors with Info Formatting, Catching Errors with Info Formatting
\subsection{Using the Emacs Lisp Debugger}
\cindex{Using the Emacs Lisp debugger}
\cindex{Emacs Lisp debugger}
\cindex{Debugger, using the Emacs Lisp }

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
\code{latexinfo-format-region} function the problem occurred.  You can turn
on the debugger with the command:\refill

\begin{example}
M-x set-variable \key{RET} debug-on-error \key{RET} t \key{RET}
\end{example}

\noindent
and turn it off with

\begin{example}
M-x set-variable \key{RET} debug-on-error \key{RET} nil \key{RET}
\end{example}

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 files are read as octal numbers by the debugger that may look
mysterious.  To use the uncompiled source files, load \file{latexinfo.el}
and \file{latexinfo-mode.el} with the \kbd{M-x load-file} command.\refill

The debugger will not catch an error if \code{latexinfo-format-region} does
not detect one.  In the example shown above, \code{latexinfo-format-region}
did not find the error when the whole list was formatted, but only when
part of the list was formatted.  When \code{latexinfo-format-region} did not
find an error, the debugger did not find one either. \refill

However, when \code{latexinfo-format-region} did report an error, it invoked
the debugger.  This is the backtrace it produced:

\begin{example}
Signalling: (search-failed "[\},]")
  re-search-forward("[\},]")
  (while ...)
  (let ...)
  latexinfo-format-parse-args()
  (let ...)
  latexinfo-format-xref()
  funcall(latexinfo-format-xref)
  (if ...)
  (let ...)
  (if ...)
  (while ...)
  latexinfo-format-scan()
  (save-excursion ...)
  (let ...)
  latexinfo-format-region(103370 103631)
* call-interactively(latexinfo-format-region)
\end{example}

The backtrace is read from the bottom up.  \code{latexinfo-format-region} was
called interactively; and it in turn called various functions, including
\code{latexinfo-format-scan},\\
\code{latexinfo-format-xref} and \code{latexinfo-format-parse-args}.
Inside the function\\
\code{latexinfo-format-parse-args}, the function
\code{re-search-forward} was called; it was this function that could not
find the missing right hand brace.\refill

\xref{Lisp Debug, , Debugging Emacs Lisp, emacs, The GNU Emacs Manual}, for
more information.\refill


\node Catching Errors with LaTeX Formatting, Using latexinfo-show-structure, Using the Emacs Lisp Debugger, Catching Mistakes
\section{Catching Errors with LaTeX Formatting}
\cindex{Catching errors with LaTeX formatting}
\cindex{Debugging with LaTeX Formatting}

You can also catch mistakes when you format a file with \LaTeX.
Usually, you will want to do this after you have run
\code{latexinfo-format-buffer} on the same file, as it
is usually faster and sometimes gives error messages that make more sense.
\xref{Catching Errors with Info Formatting}, for more information.\refill

\clearpage
For example, \LaTeX\ was run on the same itemized list discussed in the
section on the use of \code{latexinfo-format-region}; the fragment with
the error looked like this:

\begin{example}
name of the latexinfo file as an extension.  The \back samp\{??\} are `wildcards'
that cause the shell to substitute all the raw index files.  (\back xref\{sorting
indices, for more information about sorting indices.) \back refill
\end{example}

\noindent
This produced the following output, after which \LaTeX\ stopped:

\begin{example}
Runaway argument?
\{sorting indices, for more information about sorting indices.) \back refill \back ETC.
! Paragraph ended before \back xref was complete.
<to be read again> 
                   \back par 
l.27 
     
? 
\end{example}

In this case, \LaTeX\ produced an accurate and understandable error message:
\samp{Paragraph ended before \back xref was complete.}   Also,
\samp{\back par} is an internal \LaTeX\ command meaning new--paragraph.
Unfortunately, \LaTeX\ is not always so helpful, and sometimes you have
to be truly a Sherlock Holmes to discover what went wrong.  If you run
into a problem like this, you can do one of two things.

\begin{enumerate}
\item
You can tell \LaTeX\ to continue running and to ignore errors 
as best it can by typing \kbd{r \key{RET}} at the 
\samp{?} prompt.\refill

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.\refill

\item
You can tell \LaTeX\ to stop this run by typing \kbd{x \key{RET}} 
at the \samp{?} prompt. 
\end{enumerate}

Sometimes \LaTeX\ will format a file without producing error messages even
though there is a problem.  This usually occurs if a command is not ended
but \LaTeX\ is able to continue processing anyhow.  For example, if you
fail to end an itemized list with the \code{\back end\{itemize\}} command,
\LaTeX\ will write a DVI file that you can print out.  The only error
message that
\LaTeX\ will give you is the somewhat mysterious comment that

\begin{example}
(\back end occurred inside a group at level 1)
\end{example}

\noindent
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 
\LaTeX\ says that it expected to find a \code{\back end} command somewhere
in the file; but that it could not locate where it was needed. \refill

Another source of notoriously hard to find errors is a missing
\code{\back end\{same\}} command.  If you ever are stumped by
incomprehensible errors, look for a missing \code{\back end\{same\}}
command first.\refill

If you do not have the header lines in the file, \LaTeX\ may stop in the
beginning of its run and display output that looks like the following.
The \samp{*} indicates that \LaTeX\ is waiting for input.\refill

\begin{example}
This is TeX, Version 2.0 for Berkeley UNIX (preloaded format=plain-cm 
87.10.25) (#tz-bar-a02987.tex [1])
*
\end{example}

\noindent
In this case, simply type \kbd{\back end \key{RET}} after the asterisk.  Then
put the header lines into the \LaTeX info file and run the \LaTeX\ command
again.\refill


\node Using latexinfo-show-structure, Using Occur, Catching Errors with LaTeX Formatting, Catching Mistakes
\section{Using latexinfo-show-structure}
\cindex{Using latexinfo-show-structure}
\cindex{Showing the structure of a file}
\cindex{Using latexinfo-show-structure to catch mistakes}
\cindex{latexinfo-show-structure for catching mistakes}
\findex{latexinfo-show-structure}

It is not always easy to keep track of the nodes, chapters, sections and
subsections of a \LaTeX info file.  This is especially true if you are revising
or adding to a \LaTeX info file that someone else has written.

In GNU Emacs, in LaTeXinfo Mode, there is a command that will list all the
lines that begin with the commands that specify the structure: \code{\back
node}, \code{\back chapter}, \code{\back section}, \code{\back appendix}
and so on.  This is the \code{latexinfo-show-structure} command.  It is
bound to the keyboard command \ctrl{c} \ctrl{s}.
\code{latexinfo-show-structure} displays the lines that begin with the node
and chapter structuring commands in another window called the
\samp{*Occur*} buffer.  For example, when it is run on the first part of
this chapter, it produces the following:\refill

\begin{example}
Lines matching
"^\back \back \back (chapter\back \back |sect\back \back |sub\back \back |heading\back \back |major
\back \back |node\back \back )" in buffer new-texinfo-manual.texinfo.
  2:\back node     catching mistakes, command Syntax, running info, top
  4:\back chapter\{Catching Mistakes\}
 41:\back node debugging with info, debugging with tex, , catching mistakes
 43:\back section\{Catching errors with Info Formatting\}
\end{example}

This means that lines 2, 4, 41 and 43 began with \code{\back node},
\code{\back chapter}, \code{\back node}, and \code{\back section}
respectively.  If you move your cursor into the \samp{*Occur*} window, you
can position the cursor over one of the lines and use the \ctrl{c} \ctrl{c}
command\\
(\code{occur-mode-goto-occurrence}), to jump to the corresponding
spot in the \LaTeX info file. \xref{Other Repeating Search, , Using Occur,
emacs, The GNU Emacs Manual}, for more information about
\code{occur-mode-goto-occurrence}.\refill

The first line in the \samp{*Occur*} window describes the \dfn{regular
expression} specified by \var{latexinfo-heading-pattern}.  This regular
expression is the pattern that\\
\code{latexinfo-show-structure} looks for.
\xref{Regexps, , Using Regular Expressions, emacs, The GNU Emacs Manual},
for more information.\refill

When you give the \code{latexinfo-show-structure} command, it will show
the structure of the whole buffer.  If you want to see the structure of
just a part of the buffer, of one chapter, for example, use the \kbd{C-x
n} (\code{narrow-to-region}) command to mark the region.
(\xref{Narrowing, , , emacs, The GNU Emacs Manual
\cite{GNUEmacsManual}}.)  This is how the example used above was
generated.  (To see the whole buffer again, use \kbd{C-x w}
(\code{widen}).)\refill

You can remind yourself of the structure of a \LaTeX info file by looking at
the list in the \samp{*Occur*} window; and if you have mis-named a node
or left out a section, you can correct the mistake.

\begin{menu}
* Using Occur::
\end{menu}

\node Using Occur, Finding Badly Referenced Nodes, Using latexinfo-show-structure, Using latexinfo-show-structure
\subsection{Using Occur}
\cindex{Using occur}
\cindex{Occur, using the command}

Sometimes the \code{latexinfo-show-structure} command produces too much
information.  Perhaps you want to remind yourself of the overall structure
of a \LaTeX info file, and are overwhelmed by the detailed list produced by
\code{latexinfo-show-structure}.  In this case, you can use the \code{occur}
command itself.  To do this, type

\begin{example}
\kbd{M-x occur}
\end{example}

\noindent 
and then, when prompted, type a \dfn{regexp}, a regular expression for the
pattern you want to match.  
(\xref{Regexps, , Regular Expressions, emacs, The GNU Emacs Manual}.)
\code{occur} works from the current location of
the cursor in the buffer to the end of the buffer.  If you want to run
\code{occur} on the whole buffer, place the cursor at the beginning of the
buffer.  For example, to see all the lines that contain the word
\samp{\back chapter} in them, just type \samp{\back chapter}.
This will produce a list of the chapters.  It will also list all the
sentences with \samp{\back chapter} in the middle of the line.  If
you want to see only those lines that start with the word 
\samp{\back chapter}, type \samp{^\back chapter} when prompted by
\code{occur}.  If you want to see all the lines that end with a word or
phrase, end the last word with a \samp{$}; for example, \samp{catching
mistakes$}.  This can be helpful when you want to see all the nodes that
are part of the same chapter or section and therefore have the same `Up'
pointer.\refill

\xref{Other Repeating Search, , Using Occur, emacs , The GNU Emacs Manual},
for more information.\refill

\node Finding Badly Referenced Nodes, Info-Validating a Large File, Using Occur, Catching Mistakes
\section{Finding Badly Referenced Nodes}
\cindex{Finding Badly Referenced Nodes}
\cindex{Running Info-validate}
\cindex{Info-validate,  running the command}
\cindex{Nodes, checking for badly referenced nodes}
\cindex{Checking for badly referenced nodes}
\cindex{Looking for badly referenced nodes}
\cindex{Finding badly referenced nodes}
\cindex{Badly referenced nodes }

You can check whether any of the `Next', `Previous', `Up' or other node
pointers fail to point to a node with the \code{Info-validate} command.
This command checks that every node pointer points to an existing node.

To use this command, you first need to load the \code{info} library and then do
\kbd{M-x Info-validate}.

\begin{example}
\kbd{M-x load-library \key{RET} informat \key{RET}} 
\kbd{M-x Info-validate}
\end{example}

\noindent
(Note that all the \code{Info} commands require an uppercase `I'.)

If your file is ok, you will receive a message that says ``File appears
valid''.  However, if you have a pointer that does not point to a node,
error messages will be displayed in a buffer called \samp{*problems in
info file*}.

For example, \code{Info-validate} was run on a test file that contained
only the first node of this manual.  One of the messages said:

\begin{example}
In node "Overview", invalid Next: LaTeXinfo Mode
\end{example}

\noindent
This meant that the node called \samp{Overview} had a `Next' pointer that
did not point to anything (which was true in this case, since the test file
had only one node in it).

Now suppose we add a node named \samp{LaTeXinfo Mode} to our test case
but we don't specify a `Previous' for this node.  Then we will get
the following error message:

\begin{example}
In node "LaTeXinfo Mode", should have Previous: Overview
\end{example}

\noindent
This is because every `Next' pointer should be matched by a
`Previous' (in the node where the `Next' points) which points back.

\code{Info-validate} also checks that all menu items and cross-references
point to actual nodes.

\code{Info-validate} does not work with large files that have been
split.  (Info thinks of a large file as being over 100,000 bytes,
approximately.)  In order to use \code{Info-validate} on a large file,
you must run \code{latexinfo-format-buffer} with an argument so that it
does not split the Info file, and then create a tag table.

\begin{menu}
* Info-Validating a Large File::
* Splitting a File Manually::
\end{menu}

\node Info-Validating a Large File, Splitting a File Manually, Finding Badly Referenced Nodes, Finding Badly Referenced Nodes
\subsection{Info-Validating a Large File}
\cindex{Running Info-validate on a large file}
\cindex{Info validating a large file}
\cindex{Validating a large file}

You can run \code{Info-validate} only on a single Info file.  The command
will not work on indirect subfiles that are generated when the master file
is split.  If you have a large file (longer than 100,000 bytes), you need
to run the \code{latexinfo-format-buffer} command in such a way that it
does not create indirect subfiles.  You will also need to create a tag
table.  When you have done this, you can run \code{Info-validate} and look
for badly referenced nodes.\refill

After you have validated the node structure, you can rerun\\
\code{latexinfo-format-buffer} in the normal way so it will construct
the tag table and split the file automatically or, you can make the tag
table and split the file manually.  To prevent the
\code{latexinfo-format-buffer} command from splitting a
\LaTeX info file into smaller Info files, give a prefix to the \kbd{M-x
latexinfo-format-buffer} command:

\begin{example}
C-u  M-x latexinfo-format-buffer
\end{example}

\noindent
When you do this, \LaTeX info will not split the file and will not create a tag
table for it. \refill
\cindex{Making a tag table manually}
\cindex{Tag table, making manually}

Before you can run \kbd{M-x Info-validate} on the Info file, you need to
create a tag table for it.  In order to do this, you first need to load the
\code{info} library into Emacs with the following command:\refill

\begin{example}
M-x load-library \key{RET} informat \key{RET}
\end{example}

\noindent
Then you can give the command:

\begin{example}
M-x Info-tagify
\end{example}

This creates a file which you can validate:\refill

\begin{example}
M-x Info-validate
\end{example}

After you have checked the validity of the nodes, you can either run\\
\kbd{M-x latexinfo-format-buffer} as you would normally, or else tagify and
split the file manually with the two commands \code{Info-tagify} and
\code{Info-split}.\refill

\node Splitting a File Manually, LaTeXinfo Mode, Info-Validating a Large File, Finding Badly Referenced Nodes
\subsection{Splitting a File Manually}
\cindex{Splitting an Info file manually}
\cindex{Info file, splitting manually}

If the file has more than 100,000 or so bytes in it, you should split it or
else let the \code{latexinfo-format-buffer} command do it for you
automatically.  (Generally you will let \code{latexinfo-format-buffer} do
this job for you.  \xref{Creating an On-line Info File}.)
The split--off files are called the indirect subfiles.\refill

Info files are split to save memory.  With smaller files, Emacs does not
have make such a large buffer to hold the information.  This way, Emacs
can save memory.

If the Info file has more than 30 nodes, you should also make a tag table for
it. \xref{Info-Validating a Large File}, for information about creating a
tag table.

Before running \code{Info-split}, you need to load the \code{info} library
into Emacs by giving the command \kbd{M-x load-library \key{RET} informat
\key{RET}}.  After you have done this, you can give the two commands:\refill

\begin{example}
M-x Info-tagify
M-x Info-split
\end{example}

\noindent
(Note that the \samp{I} in \samp{Info} is uppercase.)

When you use the \code{Info-split} command, the buffer is modified into a
(small) Info file which lists the indirect subfiles.  This file should be
saved in place of the original visited file.  The indirect subfiles are
written in the same directory the original file is in, with names generated
by appending \samp{-} and a number to the original file name.

The primary file still functions as an Info file, but it contains just
the tag table and a directory of subfiles.

\node LaTeXinfo Mode, Formatting a Region for Info, Splitting a File Manually, Top
\chapter{LaTeXinfo Mode}
\cindex{LaTeXinfo Mode}
\cindex{Mode, using LaTeXinfo}
\cindex{GNU Emacs}
\cindex{Emacs}

In GNU Emacs, LaTeXinfo Mode is a major mode for editing LaTeXinfo files.
This means that Emacs has commands and features especially designed for
working with \LaTeX info files.  Like all other Emacs features, you can
customize or enhance these as you wish.  In particular, the keybindings are
very easy to change.  The keybindings described here are the default or
standard ones.

The major features of LaTeXinfo Mode are:

\begin{itemize}
\item
Paragraph filling control.

\item
A command to show the structure of the file.

\item
Pre-defined keystroke commands to insert commonly used strings of text.

\item
Formatting a part of a file for Info, rather than the whole file.
\end{itemize}

In general, in LaTeXinfo Mode, the GNU Emacs editing commands are like
those in text-mode.  The major difference is that the paragraph separation
variable and syntax table are set up so expression commands skip \LaTeX
info bracket groups.  This means, for example, that the
\kbd{M-q} (\code{fill-paragraph}) command will refill a paragraph but
not the command on a line adjacent to it.\refill


\begin{menu}
* Formatting a Region for Info::
* Showing the Structure of a File::
* Inserting Frequently Used Commands::
\end{menu}

\node Formatting a Region for Info, Showing the Structure of a File, LaTeXinfo Mode, LaTeXinfo Mode
\section{Formatting a Region for Info}
\cindex{Formatting a Region for Info}
\cindex{Running Info on a region}
\cindex{Info, formatting on a region}
\findex{latexinfo-format-region}

To see what part of a \LaTeX info file will look like after it has been
transformed into an Info file, use the command \ctrl{c} \ctrl{f}
(\code{latexinfo-format-region}).  This command formats the current region of
the \LaTeX info file for Info and writes it to a temporary buffer called
\samp{*Info Region*}.\refill

For \code{latexinfo-format-region} to work, the file \strong{must} include a
line that has\\
\code{\back setfilename} in its header.\refill

\comment  node-name,  next,  previous,  up
\node Showing the Structure of a File, Inserting Frequently Used Commands, Formatting a Region for Info, LaTeXinfo Mode
\section{Showing the Structure of a File}
\cindex{Showing the structure of a file}
\cindex{Structure of a file, showing it}
\cindex{File structure, showing it}
\cindex{LaTeXinfo file structure, showing it}

You can show the structure of a \LaTeX info file by using the \ctrl{c}
\ctrl{s} command\\
(\code{latexinfo-show-structure}).  This command shows the structure of a
\LaTeX info file by listing the lines with the commands for
\code{\back{}node}, \code{\back{}chapter}, \code{\back{}section} and the
like.  These lines are displayed in another window called the
\samp{*Occur*} window.  In that window, you can position the cursor over
one of the lines and use the \ctrl{c} \ctrl{c} command 
(\code{occur-mode-goto-occurrence}), to jump to the
corresponding spot in the \LaTeX info file. The two commands are:\refill

\begin{description}
\item[C-c C-s ]
latexinfo-show-structure

\item[C-c C-c]
occur-mode-goto-occurrence
\end{description}

Often, when you are working on a manual, you will be interested only in the
structure of the current chapter.  In this case, you can mark off the
region of the buffer that you are interested in with the \kbd{C-x n}
(\code{narrow-to-region}) command and \code{latexinfo-show-structure} will
work on only that region.  (To see the whole buffer again, use \kbd{C-x w}
(\code{widen}).)\refill

\comment  node-name,  next,  previous,  up
\node Inserting Frequently Used Commands, LaTeX Input Initialization, Showing the Structure of a File, LaTeXinfo Mode
\section{Inserting Frequently Used Commands}
\cindex{Inserting frequently used commands}
\cindex{Frequently used commands, inserting them}
\cindex{Commands, inserting them}

\LaTeX info mode provides commands that insert various frequently used
commands into the buffer.  You can use these commands to save
keystrokes.  And you can insert balanced curly braces with the
\kbd{M-\{} command, (\code{latexinfo-insert-braces}) and later use the 
\kbd{M-\}} command (\code{up-list}) to move forward past the closing brace.
The special commands are invoked by typing \kbd{C-c} twice and then the
first letter of the command.\refill

\begin{description}
\item[C-c C-c c]
latexinfo-insert-code

\item[C-c C-c d ]
latexinfo-insert-dfn

\item[C-c C-c e ]
latexinfo-insert-end

\item[C-c C-c i ]
latexinfo-insert-item

\item[C-c C-c n ]
latexinfo-insert-node

\item[C-c C-c s]
latexinfo-insert-samp

\item[C-c C-c v]
latexinfo-insert-var

\item[M-\{ ]
latexinfo-insert-braces

\item[M-\} ]
up-list
\end{description}

This list was generated by analyzing the frequency with which commands were
used in the GNU Emacs Manual (\cite{GNUEmacsManual}) and the GDB Manual
(\cite{GDBManual}).  If you wish to add your own insert commands, you can
bind a keyboard macro to a key, use abbreviations or extend the code in
\file{latexinfo-mode.el}.

\c ;;;;;;;;;;;;;;;; Appendix starts here ;;;;;;;;;;;;;;;;
\appendix

\node LaTeX Input Initialization, Standard text for Copying Permissions, Inserting Frequently Used Commands, Top
\chapter{LaTeX Input Initialization}
\cindex{LaTeX Input Initialization }
\cindex{TEXINPUTS environment variable}
\cindex{profile initialization file}
\cindex{cshrc initialization file}

You must put \code{latexinfo} as an option to the \code{documentstyle}
of every \LaTeX info file to tell \LaTeX\ to use the
\file{latexinfo.sty} file when it is processing the \LaTeX info source
file.  Otherwise \LaTeX\ will not know what to do with the commands.
\xref{The First Line of a LaTeXinfo File}.\refill

\LaTeX\ needs to be told where to find the \file{latexinfo.sty} file
that you have told it to input.  One way to do this is to put
\file{latexinfo.sty} in the default inputs directory, which is the
\file{/usr/lib/tex/macros} directory.  \LaTeX\ will find the file and
you don't have to do anything.  Alternatively, you can put
\file{latexinfo.sty} in the directory in which the \LaTeX info source
file is located.\refill

However, you may want to specify the location of the file yourself.  One
way is to set the \samp{TEXINPUTS} environment variable in your
\file{.login} or \file{.profile} file.  The \samp{TEXINPUTS} environment
variable will tell \LaTeX\ where to find the \file{latexinfo.sty} file
and any other file that you might want \LaTeX\ to use.  Whether you use
a \file{.login} or \file{.profile} file depends on whether you use
\samp{csh} or \samp{sh} for your shell command interpreter.  When you
use \samp{csh}, it looks to the \file{.login} file for initialization
information, and when you use \samp{sh}, it looks to the \file{.profile}
file.\refill

In a \file{.login} file, you could use the following \code{csh} command
sequence:\refill

\begin{verbatim}
setenv LATEXINFO /usr/me/mylib
# Add the format files to the list of directories that LaTeX searches.
if ( $?TEXINPUTS ) then
	setenv TEXINPUTS "$TEXINPUTS"':'"$LATEXINFO"
  else
	setenv TEXINPUTS "$LATEXINFO"
endif
\end{verbatim}

\clearpage
In a \file{.profile} file, you could use the following \code{sh} command
sequence:

\begin{example}
TEXINPUTS=.:/usr/me/mylib:/usr/lib/tex/macros
export TEXINPUTS
\end{example}

\noindent
This would cause \LaTeX\ to look for style file first in the current
directory, indicated by the \samp{.}, then in a hypothetical user's
\file{/usr/me/mylib} directory, and finally in the system library.\refill

\node Standard text for Copying Permissions, Ifinfo Copying Permissions, LaTeX Input Initialization, Top
\chapter{Standard Text for Copying Permissions}
\cindex{Permissions}
\cindex{Copying permissions}

\LaTeX info files should contain sections that tell the readers that they have
the right to copy and distribute the Info file, the printed manual and any
accompanying software.  This appendix contains the standard text of the
Free Software Foundation copying permission notice.  For an example of the
text that could be used for the Distribution, General Public License and NO
WARRANTY sections of a document, see the latest version of the
GNU Emacs Manual \cite{GNUEmacsManual}.

The texts of the Free Software Foundation copying permission notice in the\\
\code{\back begin\{ifinfo\}} section and in the Titlepage section
are slightly different.

The \code{\back begin\{ifinfo\}} section usually begins with a line that says
what the file documents.  This is what a person looking at the file will
first read if he or she reads the unprocessed \LaTeX info file or if he or she
uses the advanced Info command \kbd{g *}.  \inforef{Expert, info, info},
for more information. (If the reader uses the regular Info commands, he or
she will usually start reading at the first node and skip this first
section, which is not in a node.)

In the \code{\back begin\{ifinfo\}} section, the summary sentence should
be followed by a copyright notice and then by the copying permission
notice.  One of the copying permission paragraphs is enclosed in
\code{\back begin\{ignore\}} and \code{\back end\{ignore\}} commands.
This paragraph states that the \LaTeX info file can be processed through
\LaTeX\ and printed, provided the printed manual carries the proper
copying permission notice.  This paragraph is not made part of the Info
file since it is not relevant to the Info file; but it is a mandatory
part of the \LaTeX info file since it permits people to process the
\LaTeX info file in \LaTeX.\refill

In the printed manual, the Free Software Foundation copying permission
notice follows the copyright notice and publishing information and is
located before the\\
\code{\back setfilename}.  The copying permission
notice is exactly the same as the notice in the
\code{\back begin\{ifinfo\}} section except that the paragraph enclosed in
\code{\back begin\{ignore\}} and \code{\back end\{ignore\}} commands is
not part of the notice.\refill

To make it simpler to copy the permission notice into each section of the
\LaTeX info file, the complete permission notices for each section are
reproduced in full below even though most of the information is
redundant.\refill

Note that you my have to specify the correct name of a section mentioned in
the permission notice.  For example, in the GDB Manual (\cite{GDBManual}),
the name of the section referring to the General Public License is called
the ``GDB General Public License'', but in the sample shown below, that
section is referred to generically as the ``General Public License''.


\begin{menu}
* Ifinfo Copying Permissions::
* Titlepage Copying Permissions::
\end{menu}

\node Ifinfo Copying Permissions, Titlepage Copying Permissions, Standard text for Copying Permissions, Standard text for Copying Permissions
\section{Ifinfo Copying Permissions}
\cindex{Ifinfo permissions}

In the \code{\back begin\{ifinfo\}} section of the \LaTeX info file, the
standard Free Software Foundation permission notices reads as follows:

\begin{verbatim}
This file documents...

Copyright 1988 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

\begin{ignore}
Permission is granted to process this file through TeX and print the
results, provided the printed document carries a copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

\end{ignore}
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
sections entitled ``Distribution'' and ``General Public License'' are
included exactly as in the original, and 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 the sections entitled ``Distribution'' and ``General Public
License'' may be included in a translation approved by the author instead
of in the original English.
\end{verbatim}

\node Titlepage Copying Permissions, LateXinfo and TeXinfo, Ifinfo Copying Permissions, Standard text for Copying Permissions
\section{Titlepage Copying Permissions}
\cindex{Titlepage permissions}

In the  Titlepage section of the \LaTeX info file, the standard
Free Software Foundation copying permission notices follows the copyright
notice and publishing information.  The standard phrasing is:

\begin{verbatim}
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 also that the
sections entitled ``Distribution'' and ``General Public License'' are
included exactly as in the original, and 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 the sections entitled ``Distribution'' and ``General Public
License'' may be included in a translation approved by the author instead
of in the original English.
\end{verbatim}

\node LateXinfo and TeXinfo, Differences from LaTeX, Titlepage Copying Permissions, Top
\chapter{LaTeXinfo and TeXinfo}
\cindex{LaTeXinfo and TeXinfo}

Documentation for GNU utilities and libraries is usually written in a
format called \dfn{\TeX info}.  Perhaps the most significant difference
of \LaTeX info from \TeX info is that if a \LaTeX\ command is found that
the Info formatter does not know about, an error is not signalled, and
processing simply continues.  This means that as long as you don't mind
having the commands ignored in the Info file, you can use any \LaTeX\ command.

\node Differences from TeXinfo, Differences from LaTeX, LateXinfo and TeXinfo, LateXinfo and TeXinfo
\section{Differences from TeXinfo}
\cindex{Differences from TeXinfo}

The following \TeX info commands have been deleted:

\begin{verbatim}
\asis
\itemx
\setchapternewpage
\summarycontents
\end{verbatim}

The following commands have been replaced by their \LaTeX\ equivalents:

\begin{verbatim}
\bye                    replaced by \end{document}
\center                 replaced by \begin{center} .. \end{center}
\contents               replaced by \tableofcontents
\group                  replaced by \begin{same}
\headings               replaced by \pagestyle
\page                   replaced by \clearpage
\settitle               replaced by \title
\table                  replaced by \begin{description}
\titlepage              replaced by \maketitle
\end{verbatim}

The following commands have been added and are supported by the Info
formatter.

\begin{verbatim}
\LaTeX
\S
\input
\label
\markboth
\pagestyle
\thispagestyle
\pagenumbering
\protect
\tie
\vspace
\vspace*
\end{verbatim}

The following commands have been changed to their \LaTeX\ definitions:

\begin{verbatim}
\appendix
\chapter
\section
\subsection
\subsection
\subsubsection
\begin{enumerate}
\begin{flushleft}
\end{verbatim}


\node Differences from LaTeX, Tabular Environment, Differences from TeXinfo, LateXinfo and TeXinfo
\section{Differences from LaTeX}
\cindex{Differences from LaTeX}

If you want to use \LaTeX\ commands for which there is no support of any
kind, you can wrap them in a \code{tex} environment:

\begin{verbatim}
\begin{tex}
...
\end{tex}
\end{verbatim}

\noindent
This ensures that this part will be ignored by the Info processor, and
that all special characters will be processed according to the normal
\LaTeX\ definitions.

\findex{figure}
Tables and Figures are only weakly supported by \LaTeX info.  Anything
within a \code{figure} environment is completely ignored in the Info file:
\code{\back begin\{figure\}} is equivalent to \code{\back begin\{tex\}}

\findex{table}
\findex{caption}
\code{\back begin\{table\}} is supported by \LaTeX info, as is the
\code{caption} command.  The lines containing the \code{\back
begin\{table\}} and \code{\back end\{table\}} are deleted from the Info
file.  The \code{caption} command causes its argument to be centered on a
line, preceded by the word Table and the table number.  \code{caption}s are
assumed to be within tables because figures are not supported.

\node Tabular Environment, Converting TeXinfo Files into LaTeXinfo Files, Differences from LaTeX, LateXinfo and TeXinfo
\subsection{Tabular Environment}
\findex{tabular}
\cindex{Tabular environment}

The \code{tabular} environment is weakly supported by the optional tabular
style.  This style makes the ampersand character revert to its \LaTeX\ special
meaning of a separator in tables.  To insert a \code{\&}, type 
\code{\back \&}.  To use this style, the \LaTeX info file \strong{must}
begin with lines that looks like

\begin{verbatim}
\documentstyle[12pt,latexinfo,tabular]{book}
\end{verbatim}

In the \code{tabular} environment, you must line the columns up the way you
want them to appear in the Info file, and you must use \key{\&} as a
separator.  In the Info file, the separator will become a \key{SPC} thus
preserving the alignment.  The trailing \code{\back \back } will be
stripped; these \emph{must} occur at the end of the line.

\findex{hline} 
The \code{hline} command is supported by the Info program.  It will insert
a line of hyphens all the way to the current \code{fill-column}.  Neither
the \code{cline} or \code{multicolum} commands are supported. For example:

\begin{verbatim}
\begin{table}[hbtp]
\caption{The First Table's Caption}
\begin{tabular}{||l|l|l|l||}
\hline
Column A        & Column B      & Column C      & Column D      \\
\hline
A 1             & B 1           & C 1           & D 1           \\
A 2             & B 2           & C 2           & D 2           \\
A 3             & B 3           & C 3           & D 3           \\
\hline
\end{tabular}
\end{table}
\end{verbatim}

\begin{same}
\noindent
produces in the Info file
\begin{verbatim}
                  Table 1 : The First Table's Caption
------------------------------------------------------------------------
Column A          Column B        Column C        Column D      
------------------------------------------------------------------------
A 1               B 1             C 1             D 1           
A 2               B 2             C 2             D 2           
A 3               B 3             C 3             D 3           
------------------------------------------------------------------------
\end{verbatim}
\end{same}

\begin{iftex}
\noindent
and in the \LaTeX\ file

\begin{table}[hbtp]
\caption{The First Table's Caption}
\begin{tabular}{||l|l|l|l||}
\hline
Column A	& Column B	& Column C	& Column D	\\
\hline
A 1		& B 1		& C 1		& D 1		\\
A 2		& B 2		& C 2		& D 2		\\
A 3		& B 3		& C 3		& D 3		\\
\hline
\end{tabular}
\end{table}
\end{iftex}

With the \code{tabular} environment, the math environments
\code{displaymath}, \code{equation}, \code{eqnarray} and
\code{array} will be completely ignored in the Info file, but will
have their \LaTeX\ definitions in the printed manual.


\node Converting TeXinfo Files into LaTeXinfo Files, Command Index, Tabular Environment, LateXinfo and TeXinfo
\section{Converting TeXinfo Files into LaTeXinfo Files}
\cindex{Converting TeXinfo Files into LaTeXinfo Files}

With the \LaTeX info distribution is a file called \file{tolatexinfo.el},
which helps convert a \TeX info file to a \LaTeX info file.  Although it is
not a perfectly automatic conversion, it will convert most of a file to
\LaTeX info.  To convert a \TeX info File into an \LaTeX Info file, just
visit a \TeX info file in GNU Emacs and invoke

\begin{example}
\kbd{Meta-x tex-to-latexinfo}
\end{example}

\noindent to convert it to a \LaTeX Info file.  Then search through the
buffer to see if there are any command that were not converted.  These
start with the symbol \samp{@}.  You will have to fix up the titlepage to
use \code{\back \{author\}} and \code{\back \{title\}} etc, and should move
the \code{setfilename} command down to somewhere after the title and
copyright pages.  You will also have to fix up any places where you have
embedded \TeX\ code such as

\begin{verbatim}
@tex
\overfullrule=0pt
@end tex
\end{verbatim}

\noindent
which will be converted into

\begin{verbatim}
@tex
\back overfullrule=0pt
@end tex
\end{verbatim}

You will be asked

\code{Would you like to do the @input files now, to do it all at once?}

\noindent
If you say \code{yes}, all the \code{@input} files will be included, so
you can doo all of the subfiles at the same time.  You will also be asked:

\begin{example}
Would you like all occurences of `@@' replaced by `@'?
\end{example}

This is normally the case, but if you say no, you will be asked

\begin{example}
Would you like all occurences of `@@' replaced by `\back \back '?
\end{example}

\noindent
You must choose one of these two options.

\node Converting LaTeX Files into LaTeXinfo Files, Command Index, Converting TeXinfo Files into LaTeXinfo Files, LateXinfo and TeXinfo
\section{Converting LaTeX Files into LaTeXinfo Files}
\cindex{Converting LaTeX Files into LaTeXinfo Files}


\LaTeX info files are essentially a superset of standard \LaTeX\ files.
To make a standard \LaTeX\ file into a \LaTeX info file, you must begin it with
the lines

\begin{verbatim}
\documentstyle[12pt,latexinfo]{book}
\pagestyle{headings}

\begin{document}

\setfilename{latexinfo.info}
\end{verbatim}

\noindent
\xref{A Short Sample LaTeXinfo File}, for details of how a \LaTeX info file
begins.  Once you have added these lines, you will have a document that will
pass both \LaTeX, and info formating program, but it will be a document
with any node structure, so it will be in essence one large node.  
(\xref{Node and Chapter Structuring} for more information on nodes.)

This is not very useful for the people who read the document under the info
program.  To add nodes and menus to the document, you can do it by hand,
or you can use the function \code{nodify-file} contained in the file
\code{nodify.el}.
\emph{Warning:  This code is a kludgy hack:}   it should never have seen the
light of day, but it beats doing a document by hand.  It assumes:\refill

\begin{enumerate}
\item	
There are no \code{\back node} commands in the file, or if there
are, they will be deleted.

\item	
There are no \code{\back menu} commands in the file.

\item
That all chapter-structuring commands (chapters, sections,
subsections and subsubsections) have unique arguments, i.e.~there are no two
sections that are called the same thing. 

\item
That the \code{documentstyle} is either \code{report} or \code{book},
i.e.~something that contains \code{chapters}.

\end{enumerate}

The \code{nodify-file} command makes each chapter, section, subsection and
subsubsection a node, with the node-name being the same as the the name of
