[comp.emacs] LaTeXinfo - 6 of 10

mike@ists.ists.ca (Mike Clarkson) (06/03/90)

#! /bin/sh
# This is a shell archive.  Remove anything before this line, then unpack
# it by saving it into a file and typing "sh file".  To overwrite existing
# files, type "sh file -c".  You can also feed this as standard input via
# unshar, or by typing "sh <file", e.g..  If this archive is complete, you
# will see the following message at the end:
#		"End of archive 5 (of 9)."
# Contents:  manual/latexinfo.tex-ab
# Wrapped by mike@sam on Sat Jun  2 18:18:13 1990
PATH=/bin:/usr/bin:/usr/ucb ; export PATH
if test -f 'manual/latexinfo.tex-ab' -a "${1}" != "-c" ; then 
  echo shar: Will not clobber existing file \"'manual/latexinfo.tex-ab'\"
else
echo shar: Extracting \"'manual/latexinfo.tex-ab'\" \(37464 characters\)
sed "s/^X//" >'manual/latexinfo.tex-ab' <<'END_OF_FILE'
Xnumbers.  In an Info file, it consists of a menu item leading to the first
X
XWhen you are making index entries, it is good practice to think of the
Xdifferent categories under which people may look for something.  Different
Xpeople \emph{do not} think of the same words when they look something up.
XThey think of different words.  A helpful index will have items indexed
Xunder all the different words that people may use.  For example, someone might
Xthink it obvious that the two letter names for indices should be listed
Xunder ``Indices, two letter names'', since the word ``Index'' is the
Xgeneral concept.  But another reader may remember the specific concept of
Xtwo letter names and search for the entry listed as ``Two letter names for
Xindices''.  A good index will have both entries and will help both kinds of
Xuser.
X
XLike typesetting, the construction of an index is a highly skilled,
Xprofessional art, the subtleties of which are not appreciated until you
Xhave to do it yourself.
X
XNormally, six indices are provided for, and are referred to by their
Xtwo-letter abbreviations:
X\cindex{Two letter names for indices}
X\cindex{Indices, two letter names}
X\cindex{Names for indices}
X
X\begin{description}
X\item[cp]
XA \dfn{concept index} listing concepts that are discussed.
X
X\item[pg]
XA \dfn{program index} listing names of programs and leading to the places
Xwhere those programs are documented.
X
X\item[fn]
XA \dfn{function index} listing functions (such as, entry points of
Xlibraries).
X
X\item[vr]
XA \dfn{variables index} listing variables (such as, external variables of
Xlibraries).
X
X\item[tp]
XA \dfn{data type index} listing data types (such as, structures defined in
Xheader files).
X
X\item[ky]
XA \dfn{keystroke index} listing keyboard commands.
X\end{description}
X
X\noindent
XNot every manual needs all of these.  This manual has two indices: a
Xconcept index and a command index (that uses the function index but is
Xcalled a command index in the chapter heading).  Two or more indices can be
Xcombined into one using the \code{\back synindex} command.  \xref{Combining
XIndices}.
X
XIn order to generate any of these Indices, you must declare it with the
X\code{\back newindex} command, before it is first used by one of the index
Xcommands.  This is usually done after the \code{\back begin\{document\}}
Xbut before the \code{\back setfilename}.
X\cindex{Indices, declaring}
X\cindex{Declaring indices}
X\findex{newindex}
X
X\code{newindex} takes one argument, which is the two letter index type
Xdescribed above.  For example, to declare a concept and function index,
Xyou would use
X
X\begin{verbatim}
X\documentstyle[12pt,twoside,latexinfo]{report}
X
X\begin{document}
X\newindex{cp}
X\newindex{fn}
X\setfilename{manual.info}
X\end{verbatim}
X
X\begin{menu}
X* Defining the Entries of an Index::
X* Special Index Entries::
X* Combining Indices::
X* Printing an Index and Generating Menus::
X\end{menu}
X
X\node Defining the Entries of an Index, Special Index Entries, Creating Indices, Creating Indices
X\subsection{Defining the Entries of an Index}
X\cindex{Defining the entries of an index}
X\cindex{Index entries}
X\cindex{Entries for an index}
X
XThe data to make an index comes from many individual commands scattered
Xthroughout the \LaTeX info source file.  Each command says to add one entry to
Xa particular index; after processing, it will give the current page number
Xor node name as the reference.
X
X\begin{description}
X\item[\back cindex\{\var{concept}\}]
XMake an entry in the concept index for \var{concept}, referring to the
Xcurrent page or node.\refill
X
X\item[\back findex\{\var{function}\}]
XMake an entry in the function index for \var{function}, referring to the
Xcurrent page or node.\refill
X
X\item[\back vindex\{\var{variable}\}]
XMake an entry in the variable index for \var{variable}, referring to the
Xcurrent page or node.\refill
X
X\item[\back pindex\{\var{program}\}]
XMake an entry in the program index for \var{program}, referring to the
Xcurrent page or node.\refill
X
X\item[\back kindex\{\var{key}\}]
XMake an entry in the key index for \var{key}, referring to the
Xcurrent page or node.\refill
X
X\item[\back tindex\{\var{data type}\}]
XMake an entry in the data type index for \var{data type}, referring to the
Xcurrent page or node.\refill
X\end{description}
X
XIf the same name is indexed on several pages, all the pages are listed in
Xthe printed manual's index.  However, \strong{only} the \strong{first} node
Xreferenced will appear in the index of an Info file.  This means that it is
Xbest to write indices in which each entry will refer to only one place in the
X\LaTeX info file.  Fortunately, this constraint is a feature rather than loss
Xsince it means that the index will be easy to use.  Otherwise, it can be
Xeasy to create an index which has many pages listed for an entry and you
Xdon't know which one you need.\refill
X
XYou are not actually required to use indices for their canonical
Xpurposes.  For example, you might wish to index some C preprocessor macros.
XYou could put them in the function index along with actual functions, just
Xby writing \code{\back findex} commands for them; then, when you print the
X``function index'', you could give it the title `Function and Macro Index'
Xand all will be consistent for the reader.  Or you could put the macros in
Xwith the data types by writing \code{\back tindex} commands for them, and give
Xthat index a suitable title so the reader will understand.\refill
X
X\node Special Index Entries, Combining Indices, Defining the Entries of an Index, Creating Indices
X\subsection{Special Index Entries}
X\findex{cpsubindex}
X\findex{cpindexbold}
X
XThe concept index has two special index entries to help you make more elaborate
Xconcept indices.
X
X\code{\back cpsubindex\{topic\}\{subtopic\}} defines an entry in the
Xconcept index, which has a subtopic.  In the Info manual, this line and
Xanything on it is deleted.
X
X\code{\back cpindexbold\{topic\}} defines an entry in the concept index,
Xwhich is set in bold type.  In the Info manual, this line and anything
Xon it is deleted.
X
X\node Combining Indices, Printing an Index and Generating Menus, Special Index Entries, Creating Indices
X\subsection{Combining Indices}
X\cindex{Combining Indices}
X\cindex{Indices, combining them}
X
XSometimes you will want to combine two disparate indices such as functions
Xand variables, perhaps because you have few enough of one of them that
Xa separate index for them would look silly.
X
XYou could put variables into the function index by writing \code{\back findex}
Xcommands for them instead of \code{\back vindex} commands, and produce a
Xconsistent manual by printing the function index with the title `Function
Xand Variable Index' and not printing the `Variable Index' at all; but this
Xis not a robust procedure.  It works only as long as your document is never
Xincluded in part of or together with another document that is designed to
Xhave a separate variable index; if you did that, the variables from your
Xdocument and those from the other would not end up together.
X
XWhat you should do instead when you want functions and variables in one
Xindex is to index the variables with \code{\back vindex} as they should be, but
Xuse the \code{\back synindex} command to redirect these \code{\back vindex}
Xcommands to the function index.  \code{\back synindex} takes two arguments: the
Xname of an index to redirect, and the name of an index to redirect it to.
XFor this purpose, the indices are given two-letter names described above.
XThus, \code{\back synindex\{vr\}\{fn\}} at the front of a \LaTeX info file
Xwill cause all entries designated for the variable index to go to
Xthe function index instead.
X
X\node Printing an Index and Generating Menus, Node and Chapter Structuring, Combining Indices, Creating Indices
X\subsection{Printing an Index and Generating Menus}
X\cindex{Printing an index}
X\cindex{Indices, printing}
X\cindex{Generating menus with indices}
X\cindex{Menus generated with indices}
X
XTo print an index means to include it as part of a manual or Info file.
XThis does not happen automatically just because you use \code{\back
Xcindex} or other index-entry generating commands in the \LaTeX info
Xfile; those just cause the raw data for the index to be accumulated.  To
Xprint an index, you must include the \code{\back printindex} command at
Xthe place in the document where you want the index to appear.  Also, for
Xthe case of the printed manual, you must run a program that is supplied
Xwith GNU Emacs called \code{texindex} to sort the raw data to produce a
Xsorted index file, which is what will actually be used to print the
Xindex.\refill
X
XThe \LaTeX info command that is used to print indices is 
X\code{\back printindex}.  It takes the two-letter index name (\pxref{Combining
XIndices}) as an argument without braces, and reads the corresponding sorted
Xindex file and formats it appropriately into an index.\refill
X
X\begin{ifinfo}
XThe two-letter index names are:
X
X\begin{description}
X\item[cp]
Xthe concept index.
X\item[vr]
Xthe variable index.
X\item[fn]
Xthe function index.
X\item[ky]
Xthe key index.
X\item[pg]
Xthe program index.
X\item[tp]
Xthe data type index.
X\end{description}
X\end{ifinfo}
X
X\code{\back printindex} does not generate a chapter heading for the index.
XConsequently, you should precede the command with a suitable section or
Xchapter command (usually \code{\back chapter*}) to supply the chapter heading
Xand put the index into the table of contents.  And before that, you will
Xprobably put a \code{\back node} command.  Also, if you want the index
Xto be set in two-column mode, then you should precede the index with 
Xthe \LaTeX\ \code{\back twocolumn} command.  For example,\refill
X
X\begin{verbatim}
X\twocolumn
X \node Command Index, Concept Index, The Last Section, Top
X \chapter*{Command Index}
X\cindex{Command Index}
X
X\printindex{fn}
X
X \node Concept Index,Top,   Command Index, Top
X \chapter*{Concept Index}
X\cindex{Concept Index}
X
X\printindex{cp}
X
X\end{document}
X\end{verbatim}
X
XIn \LaTeX, \code{\back printindex} needs a sorted index file to work from.
X\LaTeX\ does not know how to do sorting; the lack of any way to call
Xan external program like \code{sort} is one of the main deficiencies of
X\TeX.  You must invoke the program \code{texindex} to do so, giving it the
Xnames of the raw index files to be sorted as arguments.  You do not have to
Xrun \code{texindex} on all of them; only the ones you are going to print.
X(\xref{Printing Hardcopy}, for more information.)
X
X\node Node and Chapter Structuring, Chapter, Printing an Index and Generating Menus, Top
X\chapter{Node and Chapter Structuring}
X\cindex{Node and chapter structuring}
X\cindex{Chapter structuring}
X\cindex{Node structuring}
X\cindex{Structuring of nodes and chapters}
X\findex{node}
X
XThe chapter structuring commands divide a document into a hierarchy of
Xchapters, sections, subsections and subsubsections.  These commands
Xgenerate large headings.  The chapter structuring should be placed at the
Xbeginning of a line.  In a printed manual, the table of contents is based
Xon the information specified by the chapter structuring commands.
X
XAlthough the chapter structuring commands used for creating a printed
Xdocument are entirely different from the node commands for structuring an
XInfo file, you are likely to use the two kinds of command together since
Xthe single \LaTeX info file is usually designed to be read both as an Info file
Xand as a printed manual.  The only time you are likely to use the chapter
Xstructuring commands without using the node structuring commands is if you
Xare writing a document that will never be put into Info format, for
Xexample, a novel, a letter, an article or a memorandum.
X
XAlthough a \LaTeX info file can be structured in a variety of ways, it is
Xusually structured like a book with chapters, sections, subsections and the
Xlike.  This structure can also be visualized as a tree (or rather as an
Xupside down tree) with the root at the top and each level corresponding to
Xchapters or sections.  In Info format, you reach the nodes on
Xeach level by using the the `Next' and `Previous' pointers in the node
Xline.  For example, you go from one chapter to the next or previous chapter
Xby using the the pointers to the next and previous chapters.  In Info, you
Xgo the level above by using an `Up' pointer and you go to the level below
Xthrough a `Menu'.  In the printed manual, cross references are indicated by
Xpage and section numbers; in the on-line file, cross references are
Xspecified by inline menu items.
X
X\clearpage
XHere is a diagram that shows a \LaTeX info file with three chapters; 
Xeach chapter has two sections.
X
X\begin{verbatim}
X                                 top
X                                  |
X                                  |
X            ---------------------------------------------
X           |                      |                      |
X           |                      |                      |
X       Chapter 1              Chapter 2               Chapter 3
X           |                      |                      |
X           |                      |                      |
X      ----------             ----------              ----------          
X     |          |           |          |            |          |         
X Sect. 1.1   Sect. 1.2   Sect. 2.1  Sect. 2.2    Sect. 3.1  Sect. 3.2     
X			   				   
X\end{verbatim}
X
XIn this structure, the node for Chapter 2 looks like this:
X
X\begin{verbatim}
X \node     Chapter 2,  Chapter 3, Chapter 1, top
X\end{verbatim}
X
XTo get to Sections 2.1 and 2.2, you need a menu inside of Chapter 2 that
Xsays:
X
X\begin{verbatim}
X\begin{menu}
X* Sect. 2.1::    Description of this section.
X* Sect. 2.2::  
X\end{menu}
X\end{verbatim}
X
X\noindent
XThis menu is located inside Chapter 2, after the beginning of the chapter,
Xjust before Section 2.1.
X
XNote that a menu entry has three parts: the menu item name, the name of the
Xmenu item name and the name of the node are the same, you can put two
Xcolons after the item name, as is shown in the example. (If the second part
Xis different from the first, the first part is terminated by a colon and
Xthe second part terminated by a tab, newline, comma or period.)
X(\xref{Menu Environment}.)
X
XThe node for Sect. 2.1 will look like this:
X
X\begin{verbatim}
X \node     Sect. 2.1, Sect. 2.2,         ,  Chapter 2
X\end{verbatim}
X
XThis node does not have a `Previous' node.
X
XUsually, a \code{\back node} command and a chapter structuring command are
Xused in sequence, along with indexing commands.  For example, the node for
Xthe chapter on Ending a LaTeXinfo File looks like this:
X
X\begin{verbatim}
X \node Ending a LaTeXinfo File, Structuring, Beginning a LaTeXinfo File, Top
X \chapter{Ending a LaTeXinfo File}
X\cindex{Ending a LaTeXinfo File}
X\cindex{LaTeXinfo file ending}
X\cindex{File ending}
X\end{verbatim}
X
XThe \code{\back node} command is the only one in \LaTeX info where its
Xarguments are not delineated by braces.  The arguments are separated by
Xcommas, and are terminated at the end of the line.  This is because
Xthe Info format itself requires the \code{node} arguments to be like
Xthis.  Note that it also means that you cannot use a comma within any
Xof the four arguments to the node command.
X
XThere are four chapter-structuring commands for chapters, sections,
Xsubsections and subsubsections.  The optional heading argument to these
Xcommands is not supported.  You should avoid the use of any \LaTeX\ 
Xcommands in the headings: any such commands should be preceded by a
X\code{\back protect}.  See the \LaTeX\ Manual for more details
X(\cite{Lamport}).\refill
X
X\begin{menu}
X* Chapter::
X* Appendix::
X* Section::
X* Subsection::
X* Subsubsection::
X* Node::
X* Menu Environment::
X\end{menu}
X
X\node Chapter, Appendix, Node and Chapter Structuring, Node and Chapter Structuring
X\section{Chapter}
X\cindex{Chapter}
X\findex{chapter}
X\findex{chapter*}
X
X\code{\back chapter} identifies a chapter in the document.  It is
Xfollowed by a single argument which is the rest of the line, as in
X
X\begin{verbatim}
X \chapter{Node and Chapter Structuring}
X\end{verbatim}
X
XIn \LaTeX, it creates a chapter in the document, specifying the chapter
Xtitle.  In the Info file, \code{\back chapter} causes its argument to
Xappear on a line by itself, with a line of asterisks inserted
Xunderneath.  For example:\refill
X
X\begin{example}
XThis is a Chapter
X*****************
X\end{example}
X
XTo start a chapter without it being numbered, use the \code{\back chapter*}
Xcommand.
X
X\node Appendix, Section, Chapter, Node and Chapter Structuring
X\section{Appendix}
X\cindex{Appendix}
X\findex{appendix}
X
X\code{\back appendix} is the same as the \LaTeX\ command of the same name.
XIn a printed manual, all chapters that follow this command are
Xnumbered differently in the table of contents: they are given a letter
Xinstead of a number, and the letters restart from \code{A}.
X
X\node Section, Subsection, Appendix, Node and Chapter Structuring
X\section{Section}
X\cindex{Section}
X\findex{section}
X\findex{section*}
X
X\code{\back section} is like \code{\back chapter} except that in 
X\LaTeX\ it makes a section rather than a chapter.  (\xref{Chapter}.)  
XSections go within chapters.  In the Info file, \code{\back chapter} and
X\code{\back section} differ only in that \code{\back section} underlines
Xwith \samp{=}.  For example,\refill
X
X\begin{example}
XThis is a section
X=================
X\end{example}
X
XTo start a section without it being numbered, use the \code{\back section*}
Xcommand.
X
X\node Subsection, Subsubsection, Section, Node and Chapter Structuring
X\section{Subsection}
X\cindex{Subsection}
X\findex{subsection}
X
XSubsections are to sections as sections are to chapters. (\xref{Section}.)
XThey are underlined with \samp{-}.  For example,\refill
X
X\begin{example}
XThis is a subsection
X--------------------
X\end{example}
X
XTo start a subsection without it being numbered, use the 
X\code{\back subsection*} command.\refill
X
X\node Subsubsection, Node, Subsection, Node and Chapter Structuring
X\section{Subsubsection}
X\cindex{Subsubsection}
X\findex{subsubsection}
X\findex{subsubsection*}
X
XSubsubsections are to subsections as subsections are to sections.
X(\xref{Subsection}.)  They are underlined with periods.  For
Xexample,\refill
X
X\begin{example}
XThis is a subsubsection
X.......................
X\end{example}
X
XTo start a subsubsection without it being numbered, use the 
X\code{\back subsubsection*} command.\refill
X
X\node Node, Menu Environment, Subsubsection, Node and Chapter Structuring
X\section{Node}
X\cindex{Node}
X\cindex{Node}
X
X\code{\back node} defines the beginning of a new node in the Info output
Xfile (\inforef{Top, info, info}.).  It is followed by four arguments,
Xseparated by commas, that make up the rest of the line.  Since it is
Xoften hard to remember the order in which are arguments are listed,
X\code{latexinfo-mode} provides the \ctrl{C} \ctrl{C} \key{n} command
X(\code{latexinfo-insert-node}) which automatically inserts a comment
Xline listing the arguments.  For example,\refill
X
X\begin{example}
X\back node    LaTeXinfo Mode, Beginning a LaTeXinfo File,  Overview, Top    
X\back comment node-name,    next,              previous, up
X\end{example}
X
X\noindent
Xdefines a node named \samp{LaTeXinfo Mode}, whose `Next' pointer is to node
X\samp{Beginning a LaTeXinfo File}, whose `Previous' pointer is to node
X\samp{Overview}, and whose `Up' pointer is to node \samp{Top}.  What
Xthis means is that \LaTeX info changes \w{\code{\back node \var{args}}}
Xinto the special text string necessary to separate Info nodes and to
Xidentify the node that is starting and say what nodes it points
Xto.\refill
X
XThe pointer names should be the names of nodes defined elsewhere.  For this
Xexample, nodes named \samp{Beginning a LaTeXinfo File}, \samp{Overview} and
X\samp{Top} should be defined elsewhere in the file with other \code{\back node}
Xcommands.  It does not matter whether they are before or after the node
Xthat refers to them.\refill Normally, a node's `Up' pointer should point
Xat the node whose menu mentions that node.  The node's `Next' pointer
Xshould point at the node that follows that node and its `Previous'
Xpointer should point at the node that precedes it in that menu.\refill
X
XIn \LaTeX, \code{\back node} is nearly ignored.  It generates no text.
XIts only function is to identify the name to use for cross-references to
Xthe chapter or section which follows the \code{\back node} command and
Xwhich which makes up the body of the node.  (Cross references are made
Xwith \code{\back xref}.  \xref{Making Cross References}.) 
X\code{\back node} should be followed immediately by a
Xchapter-structuring command such as \code{\back chapter}, \code{\back
Xsection}, \code{\back subsection} or \code{\back subsubsection}.\refill
X
XThe easiest way to write a node is to use the LaTeXinfo Mode keyboard
Xcommand \ctrl{c} \ctrl{c} \key{n} to insert \samp{\back node} and a
Xcomment line listing the names of each of the pointers in their proper
Xorder.  This way you won't lose track of which arguments are for which
Xpointers.  The template is especially useful if you are not familiar
Xwith \LaTeX info.  It is important to pick a suitable node name.
XGenerally, these begin with an uppercase letter as if the node name were
Xa heading for a chapter or section.  Do not use any of the \LaTeX info
Xcommands in the name; these commands confuse Info.  The node name should
Xbe informative.  Unfortunately, long names will not fit onto the line,
Xwhich can be awkward, but it is still better to use long but informative
Xnames rather than short ones.
X
XSome people insert the names of the `Next', `Previous' and `Up' pointers
Xat the same time they insert the node's own name.  This is because it is
Xeasier to keep track of the node structure as you create a document than
Xit is to sort it out after you have dozens of nodes.  Others wait to
Xinsert the `Next', `Previous' and `Up' pointers until they have a nearly
Xfinal version of the document.  This is because they expect to change
Xthe organization of the document while they write it and insert or
Xdelete sections and move them around.  The command
X\code{latexinfo-show-structure} can be used to find the `Next',
X`Previous' and `Up' pointers of a node.  
X(See \xref{Using latexinfo-show-structure}.)
X
XAfter you have inserted the node-line, you should immediately write an
Xcommand for the chapter or section and insert its name.  Next, (and this
Xis important!), put in several index entries.  Usually, you will find at
Xleast two and often as many as four or five ways of referring to the
Xnode in the index. This will make it much easier for people to find the
Xnode in the index.\refill
X
XThe top node of the file, named \samp{Top}, should have as its parent the
Xname of a node in another file, where there is a menu that leads to this
Xfile.  Specify the file name in parentheses.  If the file is to be
Xinstalled directly in the Info directory file, use \samp{(dir)} as the
Xparent of the top node; this is short for \samp{(dir)top}, the node \samp{top}
Xin the file \file{dir}, which is the main menu of Info.  For example,\refill
X
X\begin{verbatim}
X\node    Top,       Overview, (dir),    (dir)
X\comment node-name, next,     previous, up
X\end{verbatim}
X
XFor more information about installing an Info file in the \file{info}
Xdirectory, \pxref{Installing an Info file}
X
X\node Menu Environment, Making Quotations and Examples, Node, Node and Chapter Structuring
X\section{Menu Environment}
X\cindex{Menu Environment}
X\findex{menu}
X
XInfo file nodes can contain \dfn{menus} which point to other nodes.  You
Xmust type the menus in by hand, and surround them with lines containing
X\code{\back begin\{menu\}} and \code{\back end\{menu\}}.  In Info, the
X\code{\back begin\{menu\}} line changes into \samp{* Menu:}, which
Xindicates the beginning of a menu to the Info program.  Otherwise, the
Xcontents are unchanged by \LaTeX info, except for the processing of any
Xother commands within.  The entire menu construct has no effect in the
Xprinted manual and will not appear there.\refill
X
XBy convention, a menu is put at the end of a node.  This way, it is easy
Xfor someone using Info to find the menu, using the \kbd{M->}
X(\code{end-of-buffer}) command.  Menu environments cannot be nested, nor can
Xthey appear inside another environment such as \code{example}.The
X\code{\back begin\{menu\}} \emph{must} occur at the beginning of a line.
X
XIn a menu, every line that begins with a \samp{*} lists a single topic.  A
Xline that does not start with a \samp{*} will also appear in the menu and
Xcan be used as a comment.  A menu item has three parts: 
X
X\begin{enumerate}
X\item
XThe menu item name.
X
X\item
XThe name of the node.
X
X\item
XA description of the item.  
X\end{enumerate}
X
X\noindent
XOnly the first part is required.  This part is the name of the topic---the
Xname of the menu item that the user must give to the \kbd{m} command to
Xselect this topic when using Info.  The first part comes right after the
Xasterisk and a space, and is followed by a colon, spaces and tabs, and then
Xthe name of the node which discusses that topic.  The name of the node is
Xterminated by a tab, comma, newline or period.  If the node name and topic
Xname are the same, rather than give the name twice, put two colons after
Xthe name instead.  For example, \samp{* Name::}.  You should do this
Xwhenever possible, since it reduces visual clutter in the menu.
XIf the second part is present, it may be terminated with a tab, comma, or
Xnewline; or with a period.
X
X\clearpage
XFor example:
X
X\begin{example}
X\back begin\{menu\}
XA Section on Foo and Switches
X* Foo::           The node named Foo tells you how to go fooing.
X* Sw: Switches.   Type \back code\{m Sw\} to see node \back code\{Switches\}
X                  which describes the switches available here.
X\back end\{menu\}
X\end{example}
X
X\noindent
Xproduces
X
X\begin{verbatim}
X* menu:
X
XA Section on Foo and Switches
X* Foo::         The node named foo tells you how to go fooing.
X* Sw: Switches. Type `m Sw' to see node `Switches'
X                which describes the switches available here.
X\end{verbatim}
X
XIn this example, the menu has two items.  \samp{Foo} is both a menu item
Xname and the name of the node referred to by that item.  \samp{Sw} is
Xthe other menu item name, and it refers to the node named
X\samp{Switches}.  Since no file name is specified with \samp{Foo} or
X\samp{Switches}, they must be the names of other nodes in the same Info
Xfile.  Nodes in other Info files can be referred to by putting the file
Xname in parentheses at the beginning of the node name. For example,
X
X\begin{verbatim}
X\begin{menu}
X* Outlining: (emacs) Outline Mode.  The major mode for editing outlines.
X* Rebinding: (emacs) Rebinding.     How to redefine the meaning of a key.
X\end{menu}
X\end{verbatim}
X
X\noindent
XWhen this is done, the item has to have at least two parts: the first part
Xis the menu item name and the second part is the name of the node.
X
X\node Making Quotations and Examples, Quotation Environment, Menu Environment, Top
X\chapter{Making Quotations and Examples}
X\cindex{Making Quotations and Examples}
X\cindex{Examples}
X
XQuotations and examples are blocks of text, consisting of one or more whole
Xparagraphs that are set off from the bulk of the text and treated
Xdifferently.  They are usually indented.
X
XIn \LaTeX info, an insertion is always begun by writing a 
X\code{\back begin} command on a line by itself, and ended by writing a 
X\code{\back end} command that is also on a line by itself.  For instance, an
X\dfn{example} is a kind of insertion that is begun with
X\code{\back begin\{example\}} and ended with
X\code{\back end\{example\}}.\refill
X\findex{end}
X
XThere are five commands for quotations and examples:
X
X\begin{description}
X\item[quotation]
XUsed to indicated text that is quoted.\refill
X
X\item[example]
XUsed to illustrate code, commands and the like in a fixed width font
Xwithout filling.\refill
X
X\item[display]
XUsed for illustrative text.
X
X\item[verbatim]
XUsed to illustrate code that you want to protect from parsing by either
X\LaTeX\ or \LaTeX info.
X
X\item[center]
XUsed for centering text.
X\end{description}
X
X
X
X\begin{menu}
X* Quotation Environment::
X* Example Environment::
X* Display Environment::
X* Verbatim Environment::
X* Center Environment::
X\end{menu}
X
X\node Quotation Environment, Example Environment, Making Quotations and Examples, Making Quotations and Examples
X\section{Quotation Environment}
X\cindex{Quotation Environment}
X\findex{quotation}
X
XThe \code{quotation} environment is used to indicate text that is
Xexcerpted from another (real or hypothetical) printed work.  The inside
Xof a quotation is processed normally except that
X
X\begin{enumerate}
X\item
XThe margins are narrower.
X\item
XParagraphs are not indented.
X\item
XInterline spacing and interparagraph spacing are reduced.
X\end{enumerate}
X
XThus, the input
X
X\begin{verbatim}
X\begin{quotation}
XThis is
Xa foo.
X\end{quotation}
X\end{verbatim}
X
X\noindent
Xproduces in the printed manual
X
X\begin{quotation}
X\begin{quotation}
XThis is a foo.
X\end{quotation}
X\end{quotation}
X
X\noindent
Xand in the Info file
X
X\noindent
X\begin{quotation}
X\begin{example}
XThis is
Xa foo.
X\end{example}
X\end{quotation}
X
X\clearpage
X\node Example Environment, Display Environment, Quotation Environment, Making Quotations and Examples
X\section{Example Environment}
X\cindex{Example Environment}
X\cindex{Examples}
X\findex{example}
X
XThe \code{example} environment is used to indicate an example that is
Xnot part of the running text.  In the printed manual, this is done by
Xswitching to a fixed width font, turning off filling, and making extra
Xspaces and blank lines significant.  In the Info file, an analogous
Xresult is obtained by indenting each line with five extra spaces.
X
X\code{\back begin\{example\}} should appear on a line by itself; this
Xline will disappear from the output.  Mark the end of the example with a
Xline containing \code{\back end\{example\}}, which will likewise
Xdisappear.  For example:\refill
X
X\begin{verbatim}
X\begin{example}
Xmv foo bar
X\end{example}
X\end{verbatim}
X
X\noindent
Xproduces
X
X\begin{example}
Xmv foo bar
X\end{example}
X
XSince the lines containing \code{\back begin\{example\}} and 
X\code{\back end\{example\}} will disappear, you will want to put 
Xa blank line before the \code{\back begin\{example\}} and another
Xblank line after the \code{\back end\{example\}}.  (Remember that
Xblank lines between the beginning \code{\back begin\{example\}} 
Xand the ending \code{\back end\{example\}} will appear in the output.)\refill
X
XDon't use tabs in lines of an example!  \LaTeX\ treats them like single
Xspaces, and that is not what they look like.
X
X\node Display Environment, Verbatim Environment, Example Environment, Making Quotations and Examples
X\section{Display Environment}
X\cindex{Display Environment}
X\cindex{Display}
X\findex{display}
X
XThe \code{display} environment is just like \code{example} except
Xthat, in the printed manual, \code{display} does not select the
Xfixed-width font.  In fact, it does not specify the font at all, so that
Xthe text appears in the same font it would have appeared in without the
X\code{display}.\refill
X
X\node Verbatim Environment, Center Environment, Display Environment, Making Quotations and Examples
X\section{Verbatim Environment}
X\cindex{Verbatim Environment}
X\cindex{Including text verbatim}
X\findex{verbatim}
X
XThe \code{verbatim} environment is very similar to the \code{example}
Xenvironment except that no parsing of the contents is carried out, and the
Xtext is not indented.  In the Info file things will appear exactly as they
Xhave been typed in. In the printed manual, this is the same as the 
X\LaTeX\ command of the same name.  Verbatim environments cannot be nested,
Xnor can they appear inside another environment such as \code{example}.  The
X\code{\back begin\{verbatim\}} and \code{\back end\{verbatim\}}
X\emph{must} occur at the beginning of a line.\refill
X
X\node Center Environment, Making Lists and Descriptions, Verbatim Environment, Making Quotations and Examples
X\section{Center Environment}
X\cindex{Center Environment}
X\cindex{Centering a line}
X\findex{center}
X
XText enclosed in a \code{center} environment produces lines of output
Xcontaining text centered between the margins.  This is the same
Xas the \code{center} environment of \LaTeX, and different from the
X\TeX info command of the same name.
X
X\node Making Lists and Descriptions, Itemize Environment, Center Environment, Top
X\chapter{Making Lists and Descriptions}
X\cindex{Making lists and descriptions}
X\cindex{Lists and descriptions, making them}
X\cindex{Descriptions and lists, making them}
X
X\LaTeX info has several ways of making lists and two-column descriptions.
XLists can be bulleted or numbered while a two-column description can
Xhighlight the items in the first column.  For example, this is an
Xenumerated list:
X
X\begin{enumerate}
X\item
XThis is a numbered item.
X
X\item
XThis is the second item in this list.
X
X\item
XThis is the third item on this list.
X\end{enumerate}
X
X\LaTeX info will automatically indent the text in lists or descriptions
Xand number an enumerated list.  This last feature is useful if you are
Xreordering the list, since you do not have to renumber it yourself.
X
XLists or descriptions are always begun by a \code{\back begin} command
Xon a line by itself and ended with a \code{\back end} command on a line
Xby itself.  For example, an enumerated list begins with the command
X\code{\back begin\{enumerate\}} and ends with the command 
X\code{\back end\{enumerate\}}; and an itemized list begins with the command
X\code{\back begin\{itemize\}} and ends with the command 
X\code{\back end\{itemize\}}.  The elements of a list are begun with the 
X\code{\back item} command.\refill
X\findex{end}
X
X\clearpage
XHere is an itemized list of the different kinds of table and lists:
X
X\begin{itemize}
X\item
XItemized lists with or without bullets.
X
X\item
XNumbered lists.
X
X\item
Xtwo-column descriptions with highlighting.
X\end{itemize}
X
X
X\begin{menu}
X* Itemize Environment::
X* Enumerate Environment::
X* Description Environment::
X\end{menu}
X
X\node Itemize Environment, Enumerate Environment, Making Lists and Descriptions, Making Lists and Descriptions
X\section{Itemize Environment}
X\cindex{Itemize Environment}
X\findex{itemize}
X\findex{item}
X
X\code{\back begin\{itemize\}} is used to produce sequences of indented
Xparagraphs, with a mark inside the left margin at the beginning of each
Xparagraph.  The text of the indented paragraphs themselves come after
Xthe \code{\back begin\{itemize\}}, up to another line that says
X\code{\back end\{itemize\}}.  Before each paragraph for which a mark in
Xthe margin is desired, place a line that says just \code{\back item}.
XDon't put any other text on this line.
X
XInfo indents the lines in an itemized list by five columns, but it does
Xnot fill them.  This can produce lines in the Info file that are too
Xwide.  You can either write shorter lines in the \LaTeX info file by
Xsetting the fill column to five columns less than it is normally, or
Xelse you can tell Info to refill the paragraphs by adding the command
X\code{\back refill} to the end of the paragraph. (\xref{Refill}, for
Xmore information about the use of the \code{\back refill} command.)
X
XUsually, you should put a blank line before a \code{\back item}.  This
Xputs a blank like in the Info file.  Except when the entries are very
Xbrief, a blank line looks better.  Here is an example of the use of
X\code{itemize}, followed by the output it produces.
X
X\begin{verbatim}
X\begin{itemize}
X\item
XSome text for foo.
X\item
XSome text
Xfor bar.
X\end{itemize}
X\end{verbatim}
X
X\noindent
Xproduces in the Info file
X
X\noindent
X\noindent
X\begin{quotation}
X\begin{itemize}
X\item
XSome text for foo.
X\item
XSome text
Xfor bar.
X\end{itemize}
X\end{quotation}
X
X\node Enumerate Environment, Description Environment, Itemize Environment, Making Lists and Descriptions
X\section{Enumerate Environment}
X\cindex{Enumerate Environment}
X\findex{enumerate}
X
XThe \code{enumerate} environment is like the \code{itemize} environment
Xexcept that the marks in the left margin contain successive integers
Xstarting with 1.  Do not put any argument on the same line as
X\code{\back begin\{enumerate\}}.  If you want, you can put a blank line
Xbetween the entries in the list.  This often makes it easier to read the
XInfo file.  For example,
X\refill
X
X\begin{verbatim}
X\begin{enumerate}
X
X\item
XSome text for foo.
X
X\item
XSome text
Xfor bar.
X\end{enumerate}
X\end{verbatim}
X
X\noindent
Xproduces in the Info file
X
X\begin{quotation}
X\noindent
X\begin{enumerate}
X
X\item
XSome text for foo.
X
X\item
XSome text
Xfor bar.
X\end{enumerate}
X\end{quotation}
X
X\begin{ifinfo}
XInfo indents the lines of the enumerated list by five columns, but it does
Xnot fill them.  As a result, the lines in the Info file may be too wide.
XTo prevent this, you can either write shorter lines in the \LaTeX info file
Xfile by setting the fill column to five columns less than it is normally,
Xor else you can tell Info to refill the paragraphs by adding the command
X\code{\back refill} to the end of the paragraph.  (\xref{Refill}, for more
Xinformation about the use of the \code{\back refill} command.)
X\end{ifinfo}
X
X\begin{iftex}
XInfo indents the lines of the enumerated list by five columns, but it does
Xnot fill them, just as it does with an itemized list.  You may want to use
Xshorter lines for text within an enumerated list or use the \code{\back refill}
Xcommand at the end of the paragraph. (\xref{Refill}, for more information
Xabout the use of the \code{\back refill} command.)
X\end{iftex}
X
X\node Description Environment, Making Cross References, Enumerate Environment, Making Lists and Descriptions
END_OF_FILE
if test 37464 -ne `wc -c <'manual/latexinfo.tex-ab'`; then
    echo shar: \"'manual/latexinfo.tex-ab'\" unpacked with wrong size!
fi
# end of 'manual/latexinfo.tex-ab'
fi
echo shar: End of archive 5 \(of 9\).
cp /dev/null ark5isdone
MISSING=""
for I in 1 2 3 4 5 6 7 8 9 ; do
    if test ! -f ark${I}isdone ; then
	MISSING="${MISSING} ${I}"
    fi
done
if test "${MISSING}" = "" ; then
    echo You have unpacked all 9 archives.
    rm -f ark[1-9]isdone ark[1-9][0-9]isdone
else
    echo You still need to unpack the following archives:
    echo "        " ${MISSING}
fi
##  End of shell archive.
exit 0
-- 
Mike Clarkson					mike@ists.ists.ca
Institute for Space and Terrestrial Science	uunet!attcan!ists!mike
York University, North York, Ontario,		FORTRAN - just say no. 
CANADA M3J 1P3					+1 (416) 736-5611