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 4 (of 9)."
# Contents: manual/latexinfo.tex-ac
# Wrapped by mike@sam on Sat Jun 2 18:18:12 1990
PATH=/bin:/usr/bin:/usr/ucb ; export PATH
if test -f 'manual/latexinfo.tex-ac' -a "${1}" != "-c" ; then
echo shar: Will not clobber existing file \"'manual/latexinfo.tex-ac'\"
else
echo shar: Extracting \"'manual/latexinfo.tex-ac'\" \(35046 characters\)
sed "s/^X//" >'manual/latexinfo.tex-ac' <<'END_OF_FILE'
X\section{Description Environment}
X\cindex{Descriptions, making two-column}
X\findex{description}
X\findex{item}
X
XThe \code{description} environment is similar to \code{\back
Xbegin\{itemize\}}, but allows you to specify a name or heading line for
Xeach item. (\xref{Itemize Environment}.) The command is used to
Xproduce two-column descriptions, and is especially useful for glossaries
Xand explanatory exhibits. You must follow each use of \code{\back item}
Xinside of the description environment with text to serve as the heading
Xline for that item. This text is put inside square brackets on the same
Xline as the \code{\back item} command. Each heading line is put into
Xthe first column of the table and the supporting text, which you put on
Xthe line following the line beginning with \code{\back item}, goes into
Xthe second column.\refill
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. The following description highlights
Xthe text in the first column:
X
X\begin{verbatim}
X\begin{description}
X\item[foo]
XThis is the text for \samp{foo}.
X\item[bar]
XThis is the text for \samp{bar}.
X\end{description}
X\end{verbatim}
X
X\noindent
Xproduces
X
X\begin{quotation}
X\begin{description}
X\item[foo]
XThis is the text for \samp{foo}.
X\item[bar]
XThis is the text for \samp{bar}.
X\end{description}
X\end{quotation}
X
XInfo indents the lines of text in the second column, but does not fill
Xthem. As a result, the lines in the Info file may be too wide. To
Xprevent this, cause Info to refill the paragraphs after processing by
Xadding the command \code{\back refill} to the end of the paragraph.
X(\xref{Refill}, for more information about the use of the
X\code{\back refill} command.)
X
X\node Making Cross References, Xref, Description Environment, Top
X\chapter{Making Cross References}
X\cindex{Making cross references}
X\cindex{Cross references}
X\cindex{References}
X
XCross references are used to refer the reader to other parts of the same or
Xdifferent \LaTeX info files. In \LaTeX info, \dfn{nodes} are the points to
Xwhich cross-references can refer.
X
XIn general, a document should be designed so that it can be read
Xsequentially. People soon tire of flipping back and forth to find
Xinformation that should be presented to them as they need it. However,
Xthere will be information (often too detailed for whatever the current
Xcontext may be) that is related to whatever is presented and to which
Xreference should be made. More important, in an on-line help system or in
Xa reference manual, readers do \emph{not} read everything in sequence from
Xbeginning to end. Instead, they look up what they need. For this reason,
Xsuch creations should contain many cross references to help the reader find
Xother information that he or she may not have read.
X
XAlthough nodes are not a fundamental concept in a printed manual, they
Xstill serve to define a cross-reference point and the variants of
X\code{\back xref} still serve to make references. Thus, if you are writing a
Xmanual that will only be printed, and will not be used on-line, you
Xcontinue to use the \code{\back node} command for when you make cross
Xreferences.
X
XThere are several kinds of cross reference command.
X
X\begin{description}
X\item[\back xref]
XUsed to start a sentence in the printed manual saying, `See \dots' \*
Xor an entry in the Info file saying \samp{*note \dots}.
X
X\item[\back pxref]
XUsed to make a reference that starts with a lowercase \samp{see} \*
Xand is usually contained within parentheses.\refill
X
X\item[\back inforef]
XUsed to make a reference to an Info file for which there is no printed
Xmanual.\refill
X\end{description}
X
X
X\begin{menu}
X* Xref::
X* Pxref::
X* Inforef::
X\end{menu}
X
X\node Xref, Pxref, Making Cross References, Making Cross References
X\section{Xref}
X\cindex{Xref for cross references}
X\findex{xref}
X\findex{ref}
X\findex{pageref}
X\cindex{Cross references using xref}
X
X\code{\back xref} generates a cross-reference. In \LaTeX info, it turns into
Xan Info cross-reference which the Info \samp{f} command can use
Xto go directly to another node. In \LaTeX, it turns into a sentence
Xof the form
X
X\begin{example}
XSee section \var{section} [\var{topic}], page \var{page}
X\end{example}
X
X\noindent
Xbut does not generate a period to end it.
X
X\code{\back xref} must refer to an Info node created by
X\code{\back node}, by the node's name. It uses the \LaTeX\ commands
X\code{ref} and \code{pageref}.
X
X\code{\back xref} is followed by an argument inside braces; but actually the
Xtext inside the braces is treated as several arguments, separated by
Xcommas. Whitespace after these commas is ignored. A period or comma
X\strong{must} follow the closing brace of a \code{\back xref}. It is required
Xto terminate the cross reference. This period or comma will appear in
Xthe output, both in the Info file and in the printed manual.
X
XThe simplest form of \code{\back xref} takes one argument, the name of another
Xblank line and then the output text for Info files and the output text for
Xprinted manuals.
X
X\begin{example}
X\back xref\{node-name\}, for more info.
X
X*note node-name::, for more info.
X\end{example}
X
X\begin{quotation}
XSee section \var{nnn} [node-name], page \var{ppp}, for more info.
X\end{quotation}
X
XWith two arguments, the second one is used as the name of the Info
Xcross-reference, while the first argument is still the node that the
Xcross-reference points to:
X
X\begin{example}
X\back xref\{node-name, name-for-note\}, for more info.
X
X*note name-for-note: node-name, for more info.
X\end{example}
X
X\begin{quotation}
XSee section \var{nnn} [node-name], page \var{ppp}, for more info.
X\end{quotation}
X
XA third argument replaces the node name when it actually appears in the
X\LaTeX\ output. It should state the topic discussed by the section being
Xreferenced. Often, you will want to use initial uppercase letters so it
Xwill be easier to read when the reference is printed. Use a third argument
Xwhen the node name is unsuitable because of syntax, grammar or diction.
X
X\begin{example}
X\back xref\{node-name, name-for-note, Topic Description\}, for more info.
X
X*note name-for-note: node-name, for more info.
X\end{example}
X
X\begin{quotation}
XSee section \var{nnn} [Topic Description], page \var{ppp}, for more info.
X\end{quotation}
X
XIf a third argument is given and the second one is empty,
Xthen the third argument serves both purposes:
X
X\begin{example}
X\back xref\{node-name, , Topic Description\}, for more info.
X
X*note Topic Description: node-name, for more info.
X\end{example}
X
X\begin{quotation}
XSee section \var{nnn} [Topic Description], page \var{ppp}, for more info.
X\end{quotation}
X
XA fourth argument specifies the name of the Info file in which the
Xreferenced node is located, assuming it is not the one in which the
Xreference appears. \code{\back xref} with only four arguments is used
Xwhen the reference is not within one Info file, but is within a single
Xprinted manual---when multiple \LaTeX info files are incorporated into
Xthe same \LaTeX\ run but make separate Info files. (This is seldom the
Xcase and usually you will use five arguments if you are making a
Xreference that is outside the current Info file.)
X
X\begin{example}
X\back xref\{node-name, name-for-note, Topic, info-file-name\},
Xfor more info.
X
X*note name-for-note: (info-file-name) node-name, for more info.
X\end{example}
X
X\begin{quotation}
XSee section \var{nnn} [Topic], page \var{ppp}, for more info.
X\end{quotation}
X
XA fifth argument is used when you are making a reference to another Info
Xfile which is also part of another printed manual. Write the title of the
Xmanual in this slot. Since a different manual is made during a different
X\LaTeX\ run, the printed reference will not have a page number.
X
X\noindent
XWhenever you refer to another manual, use this version of \code{\back xref}
Xwith five arguments.
X
X\begin{example}
X\back xref\{node-name, name-for-note, Topic, info-file-name, A Printed Manual\},
Xfor more info.
X
X*note name-for-note: (info-file-name) node-name, for more info.
X\end{example}
X
X\begin{quotation}
XSee section Topic of \i{A Printed Manual}, for more info.
X\end{quotation}
X
X\noindent
XThe name of the printed manual will be typeset in italics.
X
XOften, you will leave out the second argument when you use the long version
Xof \code{\back xref}. In this case, the third argument, the topic description,
Xwill replace the node name:
X
X
X\begin{example}
X\back xref\{node-name, , Topic Description, info-file-name, A Printed Manual\},
Xfor more info.
X
X*note Topic Description: (info-file-name) node-name, for more info.
X\end{example}
X
X\begin{quotation}
XSee section Topic Description of \i{A Printed Manual}, for more info.
X\end{quotation}
X
X\clearpage
X\node Pxref, Inforef, Xref, Making Cross References
X\section{Pxref}
X\cindex{Pxref}
X\cindex{Cross references using pxref}
X\cindex{Pxref for cross references}
X\findex{pxref}
X
X\code{\back pxref} is nearly the same as \code{\back xref}; it differs
Xin only two ways:
X
X\begin{enumerate}
X\item
XThe output starts with lower case `see' rather than `See'.\refill
X\item
XA period is generated automatically in the Info file output to end the Info
Xcross-reference, but no period is generated for the printed manual.\refill
X\end{enumerate}
X
XThe purpose of \code{\back pxref} is to be used inside parentheses as part of
Xanother sentence. In the printed manual, no period is needed after the
Xcross reference text itself (within the parentheses), but a period is
Xneeded after the cross reference text in the Info file because only thus
Xcan Info recognize the end of the cross-reference. \code{\back pxref} spares
Xyou the need to use complicated methods to put a period into one form of
Xthe output and not the other.
X
X\code{\back pxref} can be used with up to five arguments just like
X\code{\back xref}. (\xref{Xref}.)\refill
X
X\node Inforef, Formatting Paragraphs, Pxref, Making Cross References
X\section{Inforef}
X\cindex{Inforef for cross references}
X\cindex{Cross references using inforef}
X\findex{inforef}
X
X\code{\back inforef} is used for cross-references to Info files for
Xwhich there are no printed manuals. Even in a printed manual,
X\code{\back inforef} generates a reference directing the user to look in
Xan Info file. \code{\back inforef} takes exactly three arguments. The
Xsyntax is \code{\back inforef\{\var{node}, \var{name}, \var{file}\}}.
X
X\begin{example}
X\back inforef\{node-name, name-for-note, info-file-name\}, for more information.
X
X*note name-for-note: (info-file-name) node-name, for more information.
X\end{example}
X
X\begin{quotation}
XSee Info file \file{info-file-name}, node `node-name', for more information.
X\end{quotation}
X
X\node Formatting Paragraphs, Refilling Paragraphs and Preventing Indentation, Inforef, Top
X\chapter{Formatting Paragraphs}
X\cindex{Formatting paragraphs}
X\cindex{Paragraphs, formatting}
X
XUsually, a \LaTeX info file will be processed both by \LaTeX\ and by the
X\kbd{M-x latexinfo-format-buffer} command. Consequently, you must make sure
Xthat text will come out looking right both in the printed manual and in the
Xon-line help.\refill
X
XFor example, unless told otherwise, \kbd{M-x latexinfo-format-buffer} will
Xnot refill a paragraph after processing it although \LaTeX\ will. This
Xmeans that a paragraph with numerous or large commands may not look
Xproperly filled after processing by Info. The commands are removed from
Xthe text but the lines are not refilled so some are much shorter than they
Xwere. To cause the \kbd{M-x latexinfo-format-buffer} command to refill such
Xa paragraph, put \code{\back refill} at the end of the paragraph.\refill
X
X\findex{same}
X\LaTeX\ may also format a document improperly. For example, page breaks may
Xoccur in the ``wrong place''; to control this, text can be held together by a
X\code{same} command that keeps the text within the group from being split
Xacross two pages.
X
X\begin{iftex}
XThe first section that follows is about refilling and preventing
Xindentation; the second section is about line and paragraph breaks,
Xcreating blank lines, and grouping text.
X\end{iftex}
X
X
X\begin{menu}
X* Refilling Paragraphs and Preventing Indentation::
X* Breaks Blank Lines and Groups::
X\end{menu}
X
X\node Refilling Paragraphs and Preventing Indentation, Refill, Formatting Paragraphs, Formatting Paragraphs
X\section{Refilling Paragraphs and Preventing Indentation}
X\cindex{Refilling paragraphs automatically}
X\cindex{Preventing indentation in the printed text}
X
XThe \code{\back refill} and \code{\back noindent} commands are used just
Xafter or just before paragraphs which, after processing by either Info
Xor \LaTeX, might look bad. The \code{\back refill} command refills a
Xparagraph in the Info file after all the other processing has been done.
XIn the printed manual, the \code{\back noindent} command prevents a
Xpiece of text that is a continuation of the preceding paragraph from
Xbeing indented as if it were a new paragraph.\refill
X
X\begin{menu}
X* Refill:: Refilling an info paragraph after other processing.
X* Noindent:: Preventing paragraph indentation in continuation text.
X\end{menu}
X
X\node Refill, Noindent, Refilling Paragraphs and Preventing Indentation, Refilling Paragraphs and Preventing Indentation
X\subsection{Refill}
X\cindex{Refill}
X\findex{refill}
X
XIf a paragraph contains sizable constructs, it may look badly filled
Xafter \code{latexinfo-format-buffer} is through with it. Put
X\code{\back refill} at the end of the paragraph to tell
X\code{latexinfo-format-buffer} to refill the paragraph after finishing
Xall other processing on it. \code{\back refill} has no effect on
X\LaTeX, which always fills everything that ought to be filled. For
Xexample,\refill
X
X\begin{example}
XTo use \back code\{foo\}, pass \back samp\{xx%$\} and \back var\{flag\} and type \back kbd\{x\}
Xafter running \back code\{make-foo\}.\back refill
X\end{example}
X
X\noindent
Xproduces (in the Info file)
X
X\begin{example}
XTo use `foo', pass `xx%$' and FLAG and type `x' after running `make-foo'.
X\end{example}
X
X\noindent
Xwhereas without the \code{\back refill} it would produce
X
X\begin{example}
XTo use `foo', pass `xx%$' and FLAG and type `x'
Xafter running `make-foo'.
X\end{example}
X
X\noindent
Xwith the line broken at the same place as in the \LaTeX info input file.
X
XDo not put a space before \code{\back refill}; otherwise the command might be
Xput at the beginning of the line when you refill the paragraph in the
X\LaTeX info file with \kbd{M-q} (\code{fill-paragraph}). If this were to
Xhappen, the \code{\back refill} command might fail to work.
X
X\node Noindent, Breaks Blank Lines and Groups, Refill, Refilling Paragraphs and Preventing Indentation
X\subsection{Noindent}
X\cindex{Noindent}
X\findex{noindent}
X
XIf you have text following a \code{example} or other similar ``special
Xparagraph'' that reads as a continuation of the text before the
X\code{example}, it is good to prevent this text from being indented as a
Xnew paragraph. To accomplish this, put \code{\back noindent} on a line
Xby itself before the start of the text that should not be indented. For
Xexample,\refill
X
X\begin{example}
X\back begin\{example\}
XThis is an example
X\back end\{example\}
X
X\back noindent
XThis line will not be indented.
X\end{example}
X
X\noindent
Xproduces
X
X\begin{example}
XThis is an example
X\end{example}
X
X\noindent
XThis line will not be indented.
X
XTo adjust the number of blank lines properly in the Info file output,
Xremember that the line containing \code{\back noindent} does not generate a
Xblank line, and neither does the \code{\back end\{example\}} line.
X
XIn the \LaTeX info source file for this documentation, each of the lines that
Xsays `produces' is preceded by a line containing \code{\back noindent}.
X
X\node Breaks Blank Lines and Groups, Line Breaks, Noindent, Formatting Paragraphs
X\section{Breaks Blank Lines and Groups}
X\cindex{Breaks Blank Lines and Groups}
X
X\LaTeX info has several commands for making blank lines, for forcing paragraph
Xand page breaks in the printed manual and for preventing text from running
Xfrom one page to the next.
X
X\begin{description}
X\item[\back *]
XForce a line break in the printed manual. This
Xcommand has no effect on the Info file.\refill
X
X\item[\back sp]
XGenerate blank lines in both the printed manual and in the Info file.\refill
X
X\item[\back br]
XForce a paragraph break in the printed manual. This command has no effect
Xon the Info file.\refill
X
X\item[\back w]
XPrevent text from being split across two lines in the printed manual. This
Xcommand has no effect on the Info file.\refill
X
X\item[\back clearpage]
XStart a new page in the printed manual. This
Xcommand has no effect on the Info file.\refill
X
X\item[\back begin\{same\}]
XHold text together that must appear on one printed page. This
Xcommand has no effect on the Info file.\refill
X
X\end{description}
X
X\begin{menu}
X* Line Breaks::
X* Line Spacing::
X* Paragraph Breaks::
X* Preventing A Line Break::
X* Clearpage::
X* Same Environment::
X\end{menu}
X
X\node Line Breaks, Line Spacing, Breaks Blank Lines and Groups, Breaks Blank Lines and Groups
X\subsection{Line Breaks}
X\findex{asterisk}
X\findex{*}
X\cindex{Line breaks}
X\cindex{Breaks in a line}
X
X\code{\back *} forces a line break in the printed manual. It has no effect on
Xthe Info file output, where line breaks follow those in the source file.
XIf you want a line break at a certain spot in both forms of output, break
Xthe line there in the source file and put \code{\back *} at the end of the
Xline.
X
X
X\node Line Spacing, Paragraph Breaks, Line Breaks, Breaks Blank Lines and Groups
X\subsection{Line Spacing}
X\findex{sp (line spacing)}
X\cindex{Spaces from line to line}
X\cindex{Line spacing}
X
XA line containing \code{\back sp\{\var{n}\}} generates \var{n} blank lines of
Xspace in either the printed manual or the Info file. For example,
X
X\begin{example}
X\back sp\{2\}
X\end{example}
X
X\noindent
Xgenerates two blank lines.
X
X\node Paragraph Breaks, Preventing A Line Break, Line Spacing, Breaks Blank Lines and Groups
X\subsection{Paragraph Breaks}
X\findex{br (paragraph breaks)}
X\cindex{Paragraph breaks}
X\cindex{Breaks in a paragraph}
X
XIn a printed manual, a line containing \code{\back br} forces a paragraph
Xbreak; in the Info file output, it does nothing (not even a blank line
Xresults from it).
X
X\node Preventing A Line Break, Clearpage, Paragraph Breaks, Breaks Blank Lines and Groups
X\subsection{Preventing A Line Break}
X\cindex{Preventing A Line Break}
X\findex{w (preventing a line break)}
X\cindex{Line breaks, preventing}
X
XIn a printed manual, \code{\back w\{\var{text}\}} outputs \var{text} and
Xprohibits line breaks within \var{text}. \code{\back w} has no effect
Xon the Info file output; it is the same as would result from just
X\var{text}.
X
X
X\node Clearpage, Same Environment, Preventing A Line Break, Breaks Blank Lines and Groups
X\subsection{Clearpage}
X\cindex{Clearpage}
X\cindex{Page breaks}
X\findex{clearpage}
X
XA line containing \code{\back page} starts a new page in a printed manual. The
Xline has no effect on Info files since they are not paginated.
X
X\node Same Environment, Marking Text Within a Paragraph, Clearpage, Breaks Blank Lines and Groups
X\subsection{Same Environment}
X\cindex{Same Environment}
X\cindex{Holding text together vertically}
X\cindex{Vertically holding text together}
X\findex{same}
X
XA line with \code{\back begin\{same\}} begins an unsplittable vertical
Xgroup, which must appear entirely on one page. The group is terminated
Xby a line containing \code{\back end\{same\}}. These two lines produce
Xno output of their own, and in the Info file output they have no effect
Xat all.
X
XIf you forget to end a group, you may get strange and unfathomable error
Xmessages when you run \LaTeX. This is because \LaTeX\ keeps trying to
Xput the rest of the \LaTeX info file into the group and error messages
Xdo not start to get generated until \LaTeX\ has gone a long way. It's a
Xgood rule of thumb to look for a missing \code{\back end\{same\}} if you
Xget incomprehensible error messages in \LaTeX.
X
X\node Marking Text Within a Paragraph, Specifying Definitions Files and Commands, Same Environment, Top
X\chapter{Marking Text Within a Paragraph}
X\cindex{Marking Text Within a Paragraph}
X\cindex{Marking text within a paragraph}
X
XIn \LaTeX info, text within a paragraph can be marked in a variety of ways.
XThe most important way is to specify whether a word or phrase is a
Xdefinition, a metasyntactic variable, a literal example of a program or
Xwhat not.
X
XIn addition, there are special commands for inserting single characters
Xthat have special meaning in \LaTeX info, such as braces, and for inserting
Xsymbols with special handling, such as dots and bullets. Finally, there
Xare ways to emphasize words.
X
X
X\begin{menu}
X* Specifying Definitions Files and Commands::
X* Inserting Braces Backslashes Periods::
X* Inserting Dots Bullets and TeX::
X* Emphasizing Text::
X\end{menu}
X
X\node Specifying Definitions Files and Commands, Code, Marking Text Within a Paragraph, Marking Text Within a Paragraph
X\section{Specifying Definitions Files and Commands}
X\cindex{Highlighting}
X\cindex{Specifying commands, files and the like}
X\cindex{Definitions, specifying them within text}
X\cindex{Commands, specifying them within text}
X\cindex{Files, specifying them within text}
X
X\LaTeX info has a variety of commands for specifying just what kind of object a
Xpiece of text refers to. Metasyntactic variables, for example, are marked
Xby one command and code by another. \LaTeX info uses this
Xinformation to determine how to highlight the text. Since the pieces of
Xtext are labelled by commands that tell what kind of object they are, it is
Xeasy to change the way \LaTeX info formats and typesets such text. For
Xexample, code is usually illustrated in a typewriter font, but it would be
Xeasy to change the way \LaTeX info highlights code to use another font.
XThis change would not effect how metasyntatic variables are highlighted.
XIf straight typesetting commands were used in the body of the file, you
Xwould have to check every single occurrence to make sure that you were
Xchanging code and not something else that should not be changed.
X
XIn addition, the commands can be used to generate useful information from
Xthe file, such as lists of functions or file names. It is possible, for
Xexample, to write code in Emacs Lisp (or a keyboard macro) to insert an
Xindex entry after every paragraph that contains the text labelled by a
Xspecified command. You could do this to construct an index of functions if
Xyou had not already made the entries.
X
XThe commands serve a variety of purposes:
X
X\begin{description}
X\item[\back code]
XIndicates text that is a literal example of a piece of a program.\refill
X
X\item[\back samp]
XIndicates text that is a literal example of a sequence of characters.\refill
X
X\item[\back file]
XIndicates the name of a file.\refill
X
X\item[\back kbd]
XIndicates the names of keys on the keyboard or characters you type.\refill
X
X\item[\back key]
XUsed for the conventional name for a key on a keyboard.\refill
X
X\item[\back ctrl]
XIndicates an ASCII control character.
X
X\item[\back var]
XIndicates a metasyntactic variable.
X
X\item[\back dfn]
XIndicates the introductory or defining use of a term.
X
X\item[\back cite]
XIndicates the name of a Bib\TeX\ entry.
X\end{description}
X
X
X\begin{menu}
X* Code:: A literal example of a piece of a program.
X* Samp:: A literal example of a sequence of characters.
X* File:: The name of a file.
X* Kbd:: The names of keys or else characters you type.
X* Key:: The conventional name for a key on a keyboard.
X* Ctrl:: Indicates the ASCII control character.
X* Var:: A variable.
X* Dfn:: The introductory or defining use of a term.
X* Cite:: The name of a BiBTeX entry.
X\end{menu}
X
X\node Code, Samp, Specifying Definitions Files and Commands, Specifying Definitions Files and Commands
X\subsection{Code}
X\cindex{Code}
X\findex{code}
X
X\code{\back code} is used to indicate text that is a piece of a program which
Xconsists of entire syntactic tokens. The text follows, enclosed in braces.
X
XFor example, \code{\back code} is used for an expression in a program,
Xthe name of a variable or function used in a program, or a keyword.
X\code{\back code} is not used for a piece of a token, such as when
Xspeaking about the characters used in a token; for example, when you are
Xexplaining what letters or printable symbols can be used in the names of
Xfunctions. It is also not used for input to programs unless the input
Xis written in a language that is like a programming language. For
Xexample, it is not used for the single character commands of GNU Emacs
Xalthough it is used for the names of Emacs Lisp functions that the
Xkeyboard commands invoke. You should also \code{\back code} for command
Xnames in command languages that resemble programming languages, such as
X\LaTeX info or the shell.
X
XIn the printed manual, \code{\back code} puts the argument in bold face.
XIn the Info file, it uses `\dots' quotation. For example:
X
X\begin{example}
XTo compare two files, showing text inserted or removed, use \back code\{diff\}.
X\end{example}
X
X\noindent
Xproduces
X
X\begin{quotation}
XTo compare two files, showing text inserted or removed, use \code{diff}.
X\end{quotation}
X
X\begin{iftex}
XIn the Info file, it looks like this:
X
X\begin{example}
X\dots, use `diff'
X\end{example}
X\end{iftex}
X
X\node Samp, File, Code, Specifying Definitions Files and Commands
X\subsection{Samp}
X\cindex{Samp}
X\findex{samp}
X
X\code{\back samp} is used to indicate text that is a literal example of a
Xsequence of characters in a file, string, pattern, etc. The text follows,
Xenclosed in braces. The argument appears within `\dots' quotation in
Xboth the Info file and the printed manual; in addition, it is printed in a
Xfixed-width font.
X
X\begin{example}
XTo match \back samp\{foo\} at the end of the line, use the regexp \back samp\{foo$\}.
X\end{example}
X
X\noindent
Xproduces
X
X\begin{quotation}
XTo match \samp{foo} at the end of the line, use the regexp \samp{foo$}.
X\end{quotation}
X
XPunctuation marks that are part of the English text that surrounds the
Xstrings you are specifying are \emph{never} included within the braces.
XIn the following sentence, for example, the commas and period are
Xoutside of the braces:
X
X\begin{example}
XA symbol name ends in \back samp\{a\}, \back samp\{b\}, or \back samp\{c\}.
X\end{example}
X
X\node File, Kbd, Samp, Specifying Definitions Files and Commands
X\subsection{File}
X\cindex{File}
X\findex{file}
X
X\code{\back file} is used to indicate text that is the name of a file or
Xdirectory. Currently, it is equivalent to \code{\back samp} in its effects on
Xthe output. For example,\refill
X
X\begin{example}
XThe \back file\{.el\} files are in
Xthe \back file\{/gnu/emacs/lisp\} directory.
X\end{example}
X
X\noindent
Xproduces
X
X\begin{quotation}
XThe \file{.el} files are in
Xthe \file{/gnu/emacs/lisp} directory.
X\end{quotation}
X
X\node Kbd, Key, File, Specifying Definitions Files and Commands
X\subsection{Kbd}
X\cindex{Kbd}
X\findex{kbd}
X
X\code{\back kbd} is used much like \code{\back code}. The difference is that
X\code{\back kbd} is for names of keys on the keyboard, or of characters you can
Xtype. For example, to refer to the command \kbd{M-a}, you would use
X
X\begin{example}
X\back kbd\{M-a\}
X\end{example}
X
X\noindent
Xand to refer to \kbd{M-x shell}, you would use
X
X\begin{example}
X\back kbd\{M-x shell\}
X\end{example}
X
XThe \code{\back kbd} command has the same effect as \code{\back code} in Info,
Xbut may produce a different font in a printed manual.\refill
X
XYou can embed another command inside the braces of a \code{\back kbd}
Xcommand. This is the way to describe a command that would be described
Xmore verbosely as ``press an \samp{r} and then press the \key{RET} key'':
X
X\begin{example}
X\back kbd\{r \back key\{RET\}\}
X\end{example}
X
X\noindent
XThis produces: \kbd{r \key{RET}}
X
XYou also use the \code{\back kbd} command if you are spelling out the letters
Xyou type; for example:
X
X\begin{example}
XTo give the \back code\{logout\} command,
Xtype the characters \back kbd\{l o g o u t \back key\{RET\}\}.
X\end{example}
X
X\noindent
XThis produces
X
X\begin{quotation}
XTo give the \code{logout} command,
Xtype the characters \kbd{l o g o u t \key{RET}}.
X\end{quotation}
X
X\node Key, Ctrl, Kbd, Specifying Definitions Files and Commands
X\subsection{Key}
X\cindex{Key}
X\findex{key}
X
X\code{\back key} is used for the conventional name for a key on a
Xkeyboard, as in
X
X\begin{example}
X\back key\{RET\}
X\end{example}
X
XOften, \code{\back key} is used within the argument of a \code{\back kbd}
Xcommand, whenever the sequence of characters to be typed includes one or
Xmore keys that are described by name.\refill
X
XFor example, to produce \kbd{C-x \key{ESC}} you would use
X
X\begin{example}
X\back kbd\{C-x \back key\{ESC\}\}
X\end{example}
X
XThe recommended names to use for keys are in upper case and are
X
X\begin{description}
X\item[SPC]
XSpace.
X\item[RET]
XReturn.
X\item[LFD]
XLinefeed.
X\item[TAB]
XTab.
X\item[BS]
XBackspace.
X\item[ESC]
XEscape.
X\item[DEL]
XDelete.
X\item[SFT]
XShift.
X\item[CTL]
XControl.
X\item[META]
XMeta.
X\end{description}
X
XThere are subtleties to handling words like `meta' or `ctrl' which are
Xnames of shift keys. When mentioning a character in which the shift key is
Xused, such as \kbd{Meta-a}, use the \code{\back kbd} command alone without the
X\code{\back key} command, but when you are referring to shift key in isolation,
Xuse the \code{\back key} command. For example, you would use
X\samp{\back kbd\{Meta-a\}} to produce \kbd{Meta-a} and
X\samp{\back key\{META\}} to produce \key{META}.
X
X\node Ctrl, Var, Key, Specifying Definitions Files and Commands
X\subsection{Ctrl}
X\cindex{Ctrl}
X\findex{ctrl}
X
X\code{\back ctrl} is used to describe an ASCII control character. The pattern
Xof usage is \code{\back ctrl\{\var{ch}\}}, where \var{ch} is an ASCII character
Xwhose control-equivalent is wanted. Thus, you put in an \samp{f} when
Xyou want to indicate a \samp{control-f}
X
XThus, to specify \samp{control-f}, you would enter
X
X\begin{example}
X\back ctrl\{f\}
X\end{example}
X
X\noindent
Xwhich produces
X
X\begin{quotation}
X\ctrl{f}
X\end{quotation}
X
XIn the Info file, this generates the specified control character, output
Xliterally into the file. This is done so a user can copy the specified
Xcontrol character (along with whatever else he or she wants) into another
XEmacs buffer and use it. Since the `control-h',`control-i', and
X`control-j' characters are formatting characters, they should not be
Xindicated this way.\refill
X
XIn a printed manual, this generates text to describe or identify that
Xcontrol character: an uparrow followed by the character \var{ch}.
X
X\node Var, Dfn, Ctrl, Specifying Definitions Files and Commands
X\subsection{Var}
X\cindex{Var}
X\findex{var}
X
X\code{\back var} is used to indicate metasyntactic variables. A metasyntactic
Xvariable is something that stands for another piece of text. You would use
Xa metasyntactic variable in the documentation of a function to describe the
Xarguments that are passed to that function.
X
X\code{\back var} is not used for names of particular variables in programming
Xlanguages. For example, the \LaTeX info variable \code{latexinfo-tex-command} is
Xnot a metasyntactic variable.
X
XIts effect in the Info file is to upcase the argument; in the printed
Xmanual, to italicize it. Example:
X
X\begin{example}
XTo delete file \back var\{filename\}, type \back code\{rm \back var\{filename\}\}.
X\end{example}
X
X\noindent
Xproduces
X
X\begin{quotation}
XTo delete file \var{filename}, type \code{rm \var{filename}}.
X\end{quotation}
X
XIn some documentation styles, metasyntactic variables are shown with angle
Xbrackets, for example:
X
X\begin{example}
X\dots, type rm <filename>
X\end{example}
X
X\node Dfn, Cite, Var, Specifying Definitions Files and Commands
X\subsection{Dfn}
X\cindex{Dfn}
X\findex{dfn}
X
X\code{\back dfn} is used to identify the introductory or defining use of a
Xtechnical term. The command should be used only in a passage whose purpose
Xis to introduce a term which will be used again or which the reader ought
Xto know. Mere passing mention of a term for the first time doesn't deserve
X\code{\back dfn}. It generates italics in the printed manual, and double
Xquotation marks in the Info file. Example:
X
X\begin{example}
XGetting rid of a file is called \back dfn\{deleting\} it.
X\end{example}
X
X\noindent
Xproduces
X
X\begin{quotation}
XGetting rid of a file is called \dfn{deleting} it.
X\end{quotation}
X
X\node Cite, Inserting Braces Backslashes Periods, Dfn, Specifying Definitions Files and Commands
X\subsection{Cite}
X\cindex{Cite}
X\findex{cite}
X
X\code{\back cite} is the \LaTeX\ command for a bibliographic citations.
XCitations are prepared using the program \t{BibTeX}, which formats the
Xcitations for use with \LaTeX. The argument to the \code{\back cite}
Xcommand is the citation key, which appears in the printed manual as the
Xcitation key surrounded by square brackets. How it appears in the printed
Xmanual is dependent on the bibliographic style chosen.
XSee the \LaTeX\ Manual for more details (\cite{Lamport}).\refill
X
XBefore you use the \code{\back cite} command, you must declare the
Xbibliography style that you are going to use.
X\xref{Making a Bibliography}.
X
X
X\node Inserting Braces Backslashes Periods, Inserting A Backslash, Cite, Marking Text Within a Paragraph
X\section{Inserting Braces Backslashes Periods}
X\cindex{Braces, inserting}
X\cindex{Periods, inserting}
X\cindex{Single characters, commands to insert}
X\cindex{Commands to insert single characters}
X
X\samp{\back } and curly braces are special characters in \LaTeX info.
XTo insert a parenthese you have to put a \samp{\back } in front of these
Xcharacters in order to insert them into text. To insert a backslash,
Xyou must use the \code{\back back} command.
X
XPeriods are also special. Depending on whether the period is inside of or
Xat the end of a sentence, less or more space is inserted after a period in
Xa typeset manual. Since it is not always possible for \LaTeX info to determine
Xwhen a period ends a sentence and when it is used in an abbreviation,
Xspecial commands are needed. (Usually, \LaTeX info figures out how to handle
Xperiods, so you don't have to use the special commands; you just enter a
Xperiod as you would if you were using a typewriter, which means you put two
Xspaces after the period that ends a sentence and after a colon.)\refill
X
X\begin{menu}
X* Inserting A Backslash:: Inserting A Backslash.
X* Insert Left Brace:: Inserting a left brace.
X* Insert Colon:: Preventing unintended additional whitespace.
X* Insert Period:: Inserting a period that does end a sentence.
X\end{menu}
X
X\node Inserting A Backslash, Insert Left Brace, Inserting Braces Backslashes Periods, Inserting Braces Backslashes Periods
X\subsection{Inserting A Backslash}
X\cindex{Inserting A Backslash}
X
X\code{\back back} stands for a backslash in either printed or Info output.
XDo not use \code{\back back} in chapter-structuring commands, or in the
Xarguments to a \code{\back node} command.
X
XYou must follow a \code{\back back} by a space in an \code{example} or
X\code{display} environment. This following space will be deleted in both
END_OF_FILE
if test 35046 -ne `wc -c <'manual/latexinfo.tex-ac'`; then
echo shar: \"'manual/latexinfo.tex-ac'\" unpacked with wrong size!
fi
# end of 'manual/latexinfo.tex-ac'
fi
echo shar: End of archive 4 \(of 9\).
cp /dev/null ark4isdone
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