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 7 (of 9)."
# Contents: manual/latexinfo.tex-aa
# Wrapped by mike@sam on Sat Jun 2 18:18:14 1990
PATH=/bin:/usr/bin:/usr/ucb ; export PATH
if test -f 'manual/latexinfo.tex-aa' -a "${1}" != "-c" ; then
echo shar: Will not clobber existing file \"'manual/latexinfo.tex-aa'\"
else
echo shar: Extracting \"'manual/latexinfo.tex-aa'\" \(40336 characters\)
sed "s/^X//" >'manual/latexinfo.tex-aa' <<'END_OF_FILE'
X\documentstyle[12pt,twoside,latexinfo,format,smallverb]{report} \c -*-latexinfo-*-
X\pagestyle{empty}
X
X\begin{document}
X\bibliographystyle{alpha}
X
X\newindex{cp}
X\newindex{fn}
X
X\finalout
X
X\title{The \LaTeX info Documentation Format\\
X {\normalsize Version \latexinfoversion}}
X
X\author{Richard M. Stallman
X and Robert J. Chassell\\
X The Free Software Foundation,\\
X 675 Massachusetts Ave., Cambridge MA,\\
X \and Michael Clarkson\\
X Institute for Space and Terrestrial Science,\\
X York University Campus,\\
X North York, Ontario, M3J 1P3}
X
X
X\date{ISTS Technical Report: AI-90/1}
X
X\maketitle
X
X\clearpage
X\vspace{0pt plus 1filll}
XCopyright \copyright{} 1988 Free Software Foundation, Inc.
X
X\sp{2}
XThis is version \latexinfoversion\ of the \LaTeX info documentation, and is
Xfor Version 18 of GNU Emacs.
X\sp{2}
X
XPermission is granted to make and distribute verbatim copies of
Xthis manual provided the copyright notice and this permission notice
Xare preserved on all copies.
X
XPermission is granted to copy and distribute modified versions of this
Xmanual under the conditions for verbatim copying, provided that the entire
Xresulting derived work is distributed under the terms of a permission
Xnotice identical to this one.
X
XPermission is granted to copy and distribute translations of this manual
Xinto another language, under the above conditions for modified versions,
Xexcept that this permission notice may be stated in a translation approved
Xby the Foundation.
X
X\clearpage
X\pagestyle{headings}
X
X\pagenumbering{roman}
X\tableofcontents
X
X\clearpage
X\pagenumbering{arabic}
X
X\setfilename{latexinfo.info}
X\node Top, Licensing Information, (dir)Top, (dir)Top
X
X\begin{ifinfo}
XThis file documents \LaTeX info, a documentation system that uses a single
Xsource file to produce both on-line help and a printed manual.
X
XThis is edition \latexinfoversion\ of the \LaTeX info documentation, and is
Xfor Version 18 of GNU Emacs.\refill
X
XCopyright (C) 1988 Free Software Foundation, Inc.
X
XPermission is granted to make and distribute verbatim copies of
Xthis manual provided the copyright notice and this permission notice
Xare preserved on all copies.
X
XPermission is granted to copy and distribute modified versions of this
Xmanual under the conditions for verbatim copying, provided that the entire
Xresulting derived work is distributed under the terms of a permission
Xnotice identical to this one.
X
XPermission is granted to copy and distribute translations of this manual
Xinto another language, under the above conditions for modified versions,
Xexcept that this permission notice may be stated in a translation approved
Xby the Foundation.
X\end{ifinfo}
X
X
X
X
X\begin{menu}
X* Licensing Information::
X* Overview of LaTeXinfo::
X* Beginning a LaTeXinfo File::
X* Ending a LaTeXinfo File::
X* Node and Chapter Structuring::
X* Making Quotations and Examples::
X* Making Lists and Descriptions::
X* Making Cross References::
X* Formatting Paragraphs::
X* Marking Text Within a Paragraph::
X* Input and Include Files::
X* Function Index::
X* Variable and Data Type Index::
X* Conditionals::
X* Printing Hardcopy::
X* Creating an On-line Info File::
X* Catching Mistakes::
X* LaTeXinfo Mode::
X* LaTeX Input Initialization::
X* Standard text for Copying Permissions::
X* LateXinfo and TeXinfo::
X* Command Index::
X* Concept Index::
X\end{menu}
X
X\node Licensing Information, Overview of LaTeXinfo, Top, Top
X\chapter*{Licensing Information}
X\cindex{Licensing Information}
X
XThe programs currently being distributed that relate to \LaTeX info
Xinclude two portions of GNU Emacs, plus two other separate programs
X(\code{texindex} and \code{latexinfo.sty}). These programs are
X\dfn{free}; this means that everyone is free to use them and free to
Xredistribute them on a free basis. The \LaTeX info related programs are not
Xin the public domain; they are copyrighted and there are restrictions on
Xtheir distribution, but these restrictions are designed to permit
Xeverything that a good cooperating citizen would want to do. What is
Xnot allowed is to try to prevent others from further sharing any version
Xof these programs that they might get from you.
X
X Specifically, we want to make sure that you have the right to give
Xaway copies of the programs that relate to \LaTeX info, that you receive
Xsource code or else can get it if you want it, that you can change these
Xprograms or use pieces of them in new free programs, and that you know
Xyou can do these things.
X
X To make sure that everyone has such rights, we have to forbid you to
Xdeprive anyone else of these rights. For example, if you distribute
Xcopies of the \LaTeX info related programs, you must give the recipients all
Xthe rights that you have. You must make sure that they, too, receive or
Xcan get the source code. And you must tell them their rights.
X
X Also, for our own protection, we must make certain that everyone finds
Xout that there is no warranty for the programs that relate to \LaTeX info.
XIf these programs are modified by someone else and passed on, we want
Xtheir recipients to know that what they have is not what we distributed,
Xso that any problems introduced by others will not reflect on our
Xreputation.
X
X The precise conditions of the licenses for the programs currently
Xbeing distributed that relate to \LaTeX info are found in the General Public
XLicenses that accompany them. The programs that are part of GNU Emacs
Xare covered by the GNU Emacs copying terms
X(\pxref{License, , , emacs, The GNU Emacs Manual}),
Xand other programs are covered by licenses that are contained in their
Xsource files.
X
X\node Overview of LaTeXinfo, Advantages of LaTeXinfo over TeXinfo, Licensing Information, Top
X\chapter{Overview of LaTeXinfo}
X\cindex{Overview of LaTeXinfo}
X\cindex{LaTeXinfo overview}
X
X\LaTeX info is a documentation system that uses a single source file for both
Xon-line help and a printed manual. This means that instead of writing two
Xdifferent documents, one for the on-line help and the other for the printed
Xmanual, only one document needs to be written. When the system is revised,
Xonly one file has to be revised.\refill
X
XUsing \LaTeX info, you can create a document with the normal features of a
Xbook such as chapters, sections, cross references and indices. The
Xchapters and sections of the printed manual can be made to correspond to
Xthe nodes of the on-line help. The cross references and indices can be
Xused in both the on-line help and in the printed document. Indices are
Xgenerated semi-automatically.\refill
X
XTo make the printed manual, the \LaTeX info source file is processed by the
X\LaTeX\ typesetting program; the resulting DVI file can be typeset and
Xprinted as a book. To make the on-line help, the \LaTeX info source file
Xis by processed the \kbd{M-x latexinfo-format-buffer} command in GNU Emacs;
Xthe resulting Info file should be installed in the \file{info}
Xdirectory.\refill
X
XSince the \LaTeX info source file is used for a dual task---to create both
Xthe on-line help and the printed manual---it must be written in a special
Xformat that uses commands (words preceded by a \samp{\back }) to
Xindicate chapters, sections, nodes, examples, index entries and the
Xlike.\refill
X
XBefore writing a \LaTeX info source file, you should be familiar with the
Xon-line Info documentation reading program. (\inforef{Info, info, info},
Xfor more information.) If you are writing a document that will be both
Xon-line and printed, you will need both Info and \LaTeX.
X
XTo make a printed manual, you need to use \LaTeX, which is based on the
Xpowerful, sophisticated typesetting program written by Donald Knuth,
X\TeX. It is freely distributable. It is written in a dialect of Pascal
Xcalled WEB and can be compiled either in Pascal, or in C by using a
Xconversion program that comes with the \TeX\ distribution. (For
Xinformation about getting \TeX, \pxref{TeX Mode, , , emacs, The GNU
XEmacs Manual}.)
X
XWhen \LaTeX\ processes a \LaTeX info source file, \LaTeX\ makes use of a
Xmacro definitions file called \file{latexinfo.sty} (The first line of every
X\LaTeX info file has a command that says \code{\back documentstyle[latexinfo]};
Xthis tells \LaTeX{} to use the \code{latexinfo} style file.)\refill
X
XIf the \file{latexinfo.sty} file has not already been copied to the directory
Xwhich contains the other \LaTeX\ macro definition files when Emacs was
Xinstalled, you will probably want to copy it to that directory. Usually,
Xthis is the \file{/usr/lib/tex/macros} directory. For more information,
X\pxref{LaTeX Input Initialization, , LaTeX Input Initialization}.
X
X\begin{menu}
X* Advantages of LaTeXinfo over TeXinfo::
X* Characteristics of the Info File::
X* Characteristics of the Printed Manual::
X* General Syntactic Conventions::
X* A Short Sample LaTeXinfo File::
X\end{menu}
X
X\node Advantages of LaTeXinfo over TeXinfo, Characteristics of the Info File, Overview of LaTeXinfo, Overview of LaTeXinfo
X\section{Advantages of LaTeXinfo over TeXinfo}
X\cindex{Advantages of LaTeXinfo over TeXinfo}
X
XDocumentation for GNU utilities and libraries is usually written in a
Xformat called \dfn{\TeX info}. This document describes an enhancement
Xof this format which can be used with \LaTeX\ instead of \TeX.
X
X\LaTeX info offers a number of advantages over \TeX info:
X
X\begin{enumerate}
X
X\item
XThe point size or layout style of a document can be changed easily using
Xas can the \code{documentstyle} (\t{article, report, book, twoside, \dots}).
X
X\item
X\LaTeX\ has better error checking than \TeX\ files, especially in
Xbegin/end environments. In addition, the \LaTeX\ error messages are more
Xinformative. This makes it considerably easier to make extensions and
Xenhancements (read \i{hacks}).
X
X\item
X\LaTeX\ delimits its arguments with braces, so it's easier to tell where
Xa \LaTeX info command starts, and where it ends.
X
X\item
XAny \LaTeX\ commands not understood by the on-line manual generator
X(\file{latexinfo.el}) are simply ignored. This means that you are free to add
Xa considerable number of \LaTeX\ commands to make you manual look pretty,
Xas long as you don't care that there will be no action taken by the
XInfo formatting program.
X
X\item
XIt is easy to add your own extensions to the on-line manual generator
Xby making GNU Emacs handlers for your \LaTeX\ extensions. This is
Xthe Emacs counterpart to the \code{documentstyle} options. \LaTeX info looks
Xin a specified directory for GNU Elisp code that corresponds to each
Xstyle file. This makes it easy to modularize you style files.
X
X\item \LaTeX\ has many advantages over \TeX, such as being able to
Xincorporate the Bib\TeX\ bibliography formatting program, and is much more
Xwidely used than either Scribe or plain \TeX.
X
X\end{enumerate}
X
X
X\node Characteristics of the Info File, Characteristics of the Printed Manual, Advantages of LaTeXinfo over TeXinfo, Overview of LaTeXinfo
X\section{Characteristics of the Info File}
X\cindex{Characteristics of the Info File}
X\cindex{Info file characteristics}
X
XA \LaTeX info file can be transformed into a printed manual and an on-line Info
Xfile.
X
XAn on-line Info file is a file formatted so that the Info documentation
Xreading program can operate on it. Info files are divided into pieces
Xcalled \dfn{nodes}, each of which contains the discussion of one topic.
XEach node has a name, and contains both text for the user to read and
Xpointers to other nodes, which are identified by their names. The Info
Xprogram displays one node at a time, and provides commands with which the
Xuser can move to the other nodes to which the current node points.
X
X\begin{ifinfo}
X\inforef{Info, info, info}, for more information about using Info.
X\end{ifinfo}
X
XNormally, most of the nodes are arranged in a tree which branches down.
XEach node may have any number of child nodes that describe subtopics of the
X\dfn{menu} within the parent node; this allows certain Info commands to
Xbe used to move to one of the child nodes. Each child node records the
Xparent node name, as its `Up' pointer. Thus, if a node were at the logical
Xlevel of a `chapter', its child nodes would be `sections'; likewise,
Xthe child nodes of a section would be subsections.
X
XThe root of the tree is the top node of the file, through which users
Xenter the file from the Info directory. By convention, this node is always
Xcalled \samp{Top}. This node normally contains just a brief summary of the
Xfile's purpose, and a large menu through which the rest of the file is
Xreached.
X
XGenerally you enter the Info file from the top; then you can either traverse
Xthe file systematically by going from node to node or you can search large
Xmenus that correspond to indices and go directly to the node that has the
Xinformation you want.
X
XIf you want to read through an Info file in sequence, as if it were a
Xprinted manual, you can get the whole file with the advanced Info command
X\kbd{g *}. (\inforef{Expert, info, info}.)\refill
X
XAll the children of any one parent are linked together in a bidirectional
Xchain of `Next' and `Previous' pointers. This means that all the nodes
Xthat are logically parallel to sections within a chapter are all linked
Xtogether. Normally the order in this chain is the same as the order of the
Xchildren in the parent's menu. The last child has no `Next' pointer, and
Xthe first child normally has the parent as its `Previous' pointer (as well
Xas its `Up' pointer, of course).
X
XStructuring the nodes in a tree is a matter of convention, not a
Xrequirement. In fact, the `Up', `Previous' and `Next' pointers of a node
Xcan point to any other nodes, and the menu can contain any other nodes.
XThe structure of nodes can be any directed graph. But it is usually more
Xcomprehensible to make it a tree. Info provides another kind of pointer
Xbetween nodes, called a reference, that can be sprinkled through the text
Xof a node. This is usually the best way to represent links that do not fit
Xthe tree structure.
X
XMost often the nodes fall into a strict tree structure that corresponds to
Xthe structure of chapters and sections in the printed
Xmanual. But there are times when this is not right for the material being
Xdiscussed. Therefore, \LaTeX info uses separate commands to specify the node
Xstructure of the Info file and the section structure of the printed manual.
XAlso, \LaTeX info requires that you specify menus explicitly, rather than
Xgenerate them automatically based on an assumed tree structure.
X
X\node Characteristics of the Printed Manual, General Syntactic Conventions, Characteristics of the Info File, Overview of LaTeXinfo
X\section{Characteristics of the Printed Manual}
X\cindex{Printed manual characteristics}
X\cindex{Characteristics, printed manual}
X
XA \LaTeX info file can be formatted and typeset as a printed manual.
XThe printed manual will be the same as any other book; it will have a
Xtitle page, copyright page, table of contents, and preface as you would
Xexpect, as well as chapters, sections and subsections, not to mention
Xpage headers, cross references and indices.
X\LaTeX info can be used for writing a book without ever having the intention of
Xconverting it into on-line help. \LaTeX info can be used for writing a novel;
Xand it can even be used to write a memo.
X
X\LaTeX info uses the formatting language called \LaTeX\ for typesetting.
XA file called \file{latexinfo.sty} contains information (definitions or
X\dfn{macros}) that \LaTeX\ uses when it typesets a \LaTeX info file.
X(The macros tell \LaTeX\ how to convert the \LaTeX info commands to
X\LaTeX\ commands which \LaTeX\ can then process to create the typeset
Xdocument.) By changing the parameters in \file{latexinfo.sty} you can
Xeasily change the size of the printed document. In addition, you can
Xreadily change the style in which the printed document is formatted; for
Xexample, you can change the sizes and fonts used, the amount of
Xindentation for each paragraph, the degree to which words are
Xhyphenated, and the like. By changing the specifications, you can make
Xa book look dignified, old and serious, or light-hearted, young and
Xcheery. See the \LaTeX\ Manual for more details (\cite{Lamport}).\refill
X
X\LaTeX\ is very powerful and has a great many features. Because a \LaTeX info
Xfile must be able to present information both on a character-only terminal
Xin Info form and in a typeset book, the commands that \LaTeX info supports are
Xnecessarily limited. However, you are free to use and \LaTeX\ extensions
Xas long as you don't mind them being ignored by the Info formatting program.
XOr you can write your own extensions to the Info formatting program.
X\xref{Extending LaTeXinfo}.
X
X
X\node General Syntactic Conventions, A Short Sample LaTeXinfo File, Characteristics of the Printed Manual, Overview of LaTeXinfo
X\section{General Syntactic Conventions}
X\cindex{General syntactic conventions}
X\cindex{Syntactic conventions}
X\cindex{Conventions, syntactic}
X
X\LaTeX info files are made up of a subset of \LaTeX\ constructs. The strict
Xlimits make it possible for \LaTeX info files to be understood both by
X\LaTeX\ and by the code which converts them into Info files.
X
XAll ASCII printing characters except \samp{\back }, \samp{\{} and
X\samp{\}} can appear in body text in a \LaTeX info file and stand for
Xthemselves. This means that the characters \code{# $ % ^ & _ |} all
Xprint as normal characters. \samp{\back } is the escape character which
Xintroduces commands. \samp{\{} and \samp{\}} should be used only to
Xsurround arguments to certain commands. \samp{\{} and \samp{\}}
Xappearing anywhere else will be treated by \LaTeX\ as a grouping but
Xtreated by the code that produces an Info file as themselves; this
Xinconsistency is undesirable. To put one of these parentheses into the
Xdocument, put a \samp{\back } character in front of it. To get a
X\samp{\back } character itself, use \samp{\back back}. For example, you
Xwould insert \samp{\back \{}, and \samp{\back \}} for parentheses and
X\samp{\back back} for a backslash.\refill
X
XIt is customary in \LaTeX\ to use doubled single-quote characters to begin
Xand end quotations, \samp{``} like these \samp{''}. This convention should
Xbe followed in \LaTeX info files. Also, three hyphens in a row, \samp{---},
Xare used for a dash---like this. In \LaTeX, a single or even a double
Xhyphen produces a dash that is shorter.\refill
X
X\LaTeX\ ignores the line-breaks in the input text, except for blank
Xlines, which separate paragraphs. Info generally preserves the line
Xbreaks that are present in the input file. Therefore, break the lines
Xin the \LaTeX info file the way you want them to appear in the output
XInfo file, and let \LaTeX\ take care of itself. Since Info does not
Xnormally refill paragraphs when it processes them, a line with commands
Xin it will sometimes look bad after Info has run on it. To cause Info
Xto refill the paragraph after finishing with the other processing, you
Xneed to put the command \code{\back refill} at the end of the paragraph.
X(\xref{Refilling Paragraphs and Preventing Indentation}.)\refill
X
XTo prevent a paragraph from being indented in the printed manual, put the
Xcommand \code{\back noindent} on a line by itself before the start of the text
Xthat should not be indented.
X
X\clearpage
XIn order to be made into a printed manual, a \LaTeX info file \strong{must}
Xbegin with lines that looks like
X
X\begin{verbatim}
X\documentstyle[12pt,twoside,latexinfo]{report}
X\pagestyle{headings}
X
X\begin{document}
X
X\setfilename{latexinfo.info}
X\end{verbatim}
X
X\noindent
XThe \samp{\back documentstyle[12pt,twoside,latexinfo]} line tells
X\LaTeX\ to use the \file{latexinfo.sty} style file. The \code{\back
Xpagestyle\{headings\}} command is the \LaTeX\ command to put the chapter
Xand section headings and page numbers at the top of each page. The
X\code{\back begin\{document\}} command starts the document, and makes
Xthe characters \code{# $ % ^ & _ |} all begin to print as normal
Xcharacters. This line must be followed (sooner or later) by the
X\samp{\back setfilename\{\var{info-file-name}\}}. It is is needed to
Xprovide a name for the Info file to output to.\refill
X
X\node A Short Sample LaTeXinfo File, Beginning a LaTeXinfo File, General Syntactic Conventions, Overview of LaTeXinfo
X\section{A Short Sample LaTeXinfo File}
X\cindex{A Short Sample LaTeXinfo File}
X\cindex{Sample LaTeXinfo file}
X
XA \LaTeX info file looks like the following, which is a complete but very
Xshort \LaTeX info file. The \code{\back comment} command introduces
Xcomments that will not appear in either the Info file or the printed
Xmanual; they are for the person who reads the \LaTeX info file.
X
XThe first part of the file, from \samp{\back documentstyle} through to
X\samp{\back setfilename}, looks more intimidating than it is. Most of the
Xmaterial is standard boilerplate; when you write a manual, you just put in
Xthe name of your own manual in this section.\refill
X
XAll the commands that tell \LaTeX\ how to typeset the printed manual and
Xtell \code{latexinfo-format-buffer} how to create an Info file are preceded
Xby \samp{\back }; thus, \code{\back node} indicates a node and
X\code{\back chapter} indicates the start of a chapter.
X
X\begin{verbatim}
X\documentstyle[11pt,twoside,latexinfo]{report}
X\pagestyle{empty}
X
X\begin{document}
X
X\c Declare which indices you want to make use of.
X\newindex{cp}
X
X\title{The Manual}
X
X\author{Fred Foobar,\\
X Clarke Institute,\\
X 999 Queen Street,\\
X Toronto, Ontario}
X
X\date{\today}
X\maketitle
X
X\c The following commands start the copyright page for the printed manual.
X\clearpage
X\vpace{0pt plus 1filll}
XCopyright \copyright\ year copyright-owner
X
XPermission is granted to copy and distribute modified versions of this
Xmanual under the following five pages of conditions...
X
X\c End the Copyleft page and Turn on the headings to each page.
X\clearpage
X\pagestyle{headings}
X
X\c Use roman numerals for the page numbers and Insert the Table of Contents.
X\pagenumbering{roman}
X\tableofcontents
X
X\c End the Table of Contents and start numbering from 1 with Arabic numbers
X\clearpage
X\pagenumbering{arabic}
X
X\c Anything before the \setfilename will not appear in the Info file.
X\setfilename{themanual.info}
X
X\begin{ifinfo}
XPut another 5 page copyleft here for the Info file.
X\end{ifinfo}
X
X\c The Top node contains the master menu for the Info file.
X\c This appears only in the Info file, not the printed manual.
X
X \node Top, First Chapter, (dir), (dir)
X
X\begin{menu}
X* First Chapter:: The first chapter is the
X only chapter in this sample.
X\end{menu}
X
X \node First Chapter, Concept Index, Top, Top
X \chapter{First Chapter}
X \cindex{Reference to First Chapter}
X
XThis is the contents of the first chapter.
XHere is a numbered list.
X
X\begin{enumerate}
X\item
XThis is the first item.
X
X\item
XThis is the second item.
X\end{enumerate}
X
XThe \kbd{M-x latexinfo-format-buffer} command transforms a LaTeXinfo file
Xlike this into an Info file; and \LaTeX\ typesets it for a printed manual.
X
X \node Concept Index, Top, First Chapter, Top
X \chapter*{Concept Index}
X
X\twocolumn
X\printindex{cp}
X
X\end{document}
X\end{verbatim}
X
X\clearpage
XHere is what the contents of the first chapter of the sample look like:
X
X\begin{quotation}
X
XThis is the contents of the first chapter.
X
XHere is a numbered list.
X
X\begin{enumerate}
X\item
XThis is the first item.
X
X\item
XThis is the second item.
X\end{enumerate}
X
XThe \kbd{M-x latexinfo-format-buffer} command transforms a \LaTeX info file
Xlike this into an Info file; and \LaTeX\ typesets it for a printed manual.
X\end{quotation}
X
X\node Beginning a LaTeXinfo File, The LaTeXinfo File Header, A Short Sample LaTeXinfo File, Top
X\chapter{Beginning a LaTeXinfo File}
X\cindex{LaTeXinfo file beginning}
X\cindex{File beginning}
X
XVarious pieces of information have to be provided to \LaTeX info at the
Xbeginning of a \LaTeX info file, such as the name of the file, the title
Xof the document and the like. Generally, the beginning of a \LaTeX info file
Xhas four parts:
X
X\begin{enumerate}
X\item
XThe header, that includes the commands for naming the \LaTeX info file and
Xtelling \LaTeX\ what style files to use when processing the file.
X
X\item
XA section that is terminated by the \code{\back setfilename} command that
Xcontains the title page, the copyright page and the table of contents.
XThis section appears only in the printed manual.
X
X\item
XA section, marked by the \code{\back begin\{ifinfo\}} and
X\code{\back end\{ifinfo\}} commands, that contains a short statement
Xof what the file is about, the copyright notice and copying permissions.
XThis section appears only in the Info file.
X
X\item
XThe \samp{Top} node that contains an extensive menu for the whole Info
Xfile. The contents of this node only appear in the Info file.
X\end{enumerate}
X
XIf the \LaTeX info file has a section containing licensing information and a
Xwarranty disclaimer, that section usually follows the \samp{Top} node. The
Xlicensing section will be followed by a preface or else by the first
Xchapter of the manual.
X
XSince the copyright notice and the copying permissions are in sections that
Xappear either only in the Info file or only in the printed manual, this
Xinformation has to be repeated twice.
X
X
X
X\begin{menu}
X* The LaTeXinfo File Header::
X* Copyright Pages::
X* Generating a Table of Contents::
X* Copying Permissions for Info::
X* The Top Node and Master Menu::
X* Licensing and Distribution Information::
X\end{menu}
X
X\node The LaTeXinfo File Header, The First Line of a LaTeXinfo File, Beginning a LaTeXinfo File, Beginning a LaTeXinfo File
X\section{The LaTeXinfo File Header}
X\cindex{The LaTeXinfo File Header}
X\cindex{Header for LaTeXinfo files}
X\cindex{LaTeXinfo file header}
X
X\LaTeX info files start with at least three lines that provide Info and
X\LaTeX\ with necessary information. If you want to run \LaTeX\ on just
Xa part of the \LaTeX info File, you also have to mark these heading lines
Xwith start-of-header and end-of-header lines.\refill
X
X\begin{menu}
X* The First Line of a LaTeXinfo File::
X* Titlepage::
X\end{menu}
X
X\node The First Line of a LaTeXinfo File, Titlepage, The LaTeXinfo File Header, The LaTeXinfo File Header
X\subsection{The First Line of a LaTeXinfo File}
X\cindex{First line of a LaTeXinfo file}
X\cindex{Beginning line of a LaTeXinfo file}
X
X
XEvery \LaTeX info file that is to be the top-level input to \LaTeX\ must begin
Xwith a line that looks like this:
X
X\begin{verbatim}
X\documentstyle[12pt,twoside,latexinfo]{report}
X\end{verbatim}
X
XWhen the file is processed by \LaTeX, it loads the macros listed as
Xoptions to the \code{documentstyle} command. The option
X\code{latexinfo} is needed for processing a \LaTeX info file, and \LaTeX\ will
Xthen input the file \file{latexinfo.sty}
X\pxref{LaTeX Input Initialization}.
X
X\code{12pt} and \code{twoside} are other \LaTeX\ options that also
Xinclude style files. Unlike \TeX info, these style files may have an
XEmacs counterpart, so that you can extend \LaTeX info by writing your
Xown styles.
X\xref{Extending LaTeXinfo}, for more information on writing your own styles.
X
X\node Titlepage, Copyright Pages, The First Line of a LaTeXinfo File, The LaTeXinfo File Header
X\subsection{Titlepage}
X\cindex{Titlepage}
X\findex{author}
X\findex{title}
X\findex{date}
X\findex{maketitle}
X
XThe first printed material after the \code{\back begin\{document\}} will
Xmake up the titlepage. The \LaTeX\ commands \code{\back title},
X\code{\back author} and \code{\back date} are used the same way as in
Xany \LaTeX\ report or book. The title page is terminated by
X\code{\back maketitle}. Following the material for the title page
Xshould be the copyright page.\refill
X
X\node Copyright Pages, The Copyright Page and Printed Permissions, Titlepage, Beginning a LaTeXinfo File
X\section{Copyright Pages}
X\cindex{Copyright page}
X
XThis part of the beginning of a \LaTeX info file contains the text
Xof the copying permissions that will appear in the printed manual.
XThis is usually followed by the \code{\back tableofcontents} command. The
Xtitle and copyright pages should appear before the \code{\back setfilename}
Xcommand so that this material appears only in the printed manual, not in
Xthe Info file.
X
X\node The Copyright Page and Printed Permissions, Generating a Table of Contents, Copyright Pages, Copyright Pages
X\subsection{The Copyright Page and Printed Permissions}
X\cindex{Copyright}
X\cindex{Printed permissions}
X\cindex{Permissions, printed}
X\findex{pagestyle}
X
XBy international treaty, the copyright notice for a book should either
Xbe on the title page or on the back of the title page. Other locations
Xin a book are not official and do not provide copyright protection. The
Xcopyright notice should include the year followed by the name of the
Xperson or organization who has the copyright. When the copyright notice
Xis on the back of the title page, the page is not numbered. Therefore,
Xthis is usually done while a \code{\back pagestyle\{empty\}} is in
Xeffect. See the \LaTeX\ Manual for more details on the \code{pagestyle}
Xcommand (\cite{Lamport}).\refill
X
X\findex{filll}
X\findex{vspace}
XTo cause a page break, the \code{\back clearpage} command is used. In
Xthe sample, the \code{\back clearpage} that ends the titlepage is
Xfollowed by the somewhat mysterious line that reads:
X\samp{\back vspace\{0pt plus 1filll\}}. This is a line that uses
X\LaTeX commands to push the copyright notice and the other text
Xon the copyright page towards the bottom of the page.
XThe \code{\back vspace} command means to put in white space.
XThe \samp{0pt plus 1filll}
Xmeans to put in zero points of mandatory white space, and as much
Xoptional white space as needed. Note the use of three \samp{l}s in the
Xword \samp{filll}; this is the correct use in \LaTeX.\refill
X
X\findex{copyright}
XThe \code{\back copyright} command generates a \samp{c} inside a circle.
XThe copyright notice itself has the following legally defined sequence:
X
X\begin{example}
XCopyright \copyright \var{year} \var{copyright-owner}
X\end{example}
X
XIt is customary to put information on how to get a manual after the
Xcopyright notice (the address of the Free Software Foundation, for
Xexample) and the permissions. Note that the permissions have to be
Xrepeated here as well as in the \code{ifinfo} section that immediately
Xfollows the header since this section appears only in the printed manual
Xand the \code{ifinfo} section appears only in the Info file. \xref{Copying
XPermissions for Info}.
X
XStandard text for the permissions appears in the appendix.
X\xref{Standard text for Copying Permissions}.
X
X\node Generating a Table of Contents, Setfilename, The Copyright Page and Printed Permissions, Beginning a LaTeXinfo File
X\section{Generating a Table of Contents}
X\cindex{Generating a Table of Contents}
X\cindex{Table of contents}
X\cindex{Contents, Table of}
X
XThe commands \code{\back chapter}, \code{\back section}, etc., supply the
Xinformation to make up a table of contents, but they do not cause an actual
Xtable to be generated. To do this, you must use the
X\code{\back tableofcontents} command.
X
XThe table of contents command outputs (into a printed manual) a complete
Xtable of contents, based on the \code{\back chapter}, \code{\back section}
Xand other sectioning commands. This command should be used on
Xa line by itself. This command automatically generates a Table of Contents
Xheading at the top of the page. Tables of contents should be generated at
Xthe beginning of the manual, usually just after the \code{\back maketitle},
Xbut before the \code{\back setfilename}.\refill
X
X\node Setfilename, Copying Permissions for Info, Generating a Table of Contents, Generating a Table of Contents
X\subsection{Setfilename}
X\cindex{Setfilename command}
X\cindex{Info file requirement for \back setfilename}
X\findex{setfilename}
X
XIn order to be made into an Info file, a \LaTeX info file must contain a
Xline that looks like this:
X
X\begin{example}
X\back setfilename\{\var{info-file-name}\}
X\end{example}
X
X\noindent
XThis command specifies the name of the Info file to be generated. In
Xfact, there can be other things in the file before this line, but they
Xare ignored in the generation of an Info file. The line containing the
X\code{\back setfilename} is ignored when a printed manual is generated.
XAny \LaTeX\ commands that precede the \code{\back setfilename} are
Xignored by the Info formatting program.
X
X\node Copying Permissions for Info, The Top Node and Master Menu, Setfilename, Beginning a LaTeXinfo File
X\section{Copying Permissions for Info}
X\cindex{Copying Permissions for Info}
X
XSince the title page and the copyright page appear only in the printed copy
Xof the manual, the same information has to inserted in a section that
Xappears only in the Info file. This section usually contains a brief
Xdescription of the contents of the Info file, a copyright notice and
Xcopying permissions. For example
X
X
X\begin{verbatim}
X\setfilename{themanual.info}
X
X\begin{ifinfo}
XCopyright \copyright \var{year} \var{copyright-owner}
XPut another 5 page copyleft here for the Info file.
X\end{ifinfo}
X\end{verbatim}
X
X\noindent
XStandard text for the copyright permissions is contained in the appendix.
X\xref{Ifinfo Copying Permissions}, for the complete text.
X
X\node The Top Node and Master Menu, Licensing and Distribution Information, Copying Permissions for Info, Beginning a LaTeXinfo File
X\section{The Top Node and Master Menu}
X\cindex{Top node}
X\cindex{Master menu}
X
XThe \samp{Top} node contains an extensive, master menu for the whole
XInfo file. The contents of this node appear only in the Info file.
XNothing in this node should appear in the printed file. Since a node
Xline by itself and a menu by itself are not printed, the contents of
Xthis node do not have to be within a region delineated by
X\code{\back begin\{ifinfo\}} and \code{\back end\{ifinfo\}} commands.
XHowever, any text within the node should be marked off in that manner.
XYou may want to put a short summary before the master menu inside a
Xregion delineated by \code{\back begin\{ifinfo\}} and
X\code{\back end\{ifinfo\}} commands. Usually, the `Previous' and `Up'
Xpointers to \samp{(dir)}.\refill
X
XGenerally, the top menu is divided into parts.
X
X\begin{itemize}
X
X\item
XThe first part contains the major nodes in the \LaTeX info file: the
X
X\item
XThe second part contains entries for the indices. In an Info file, it
Xis very useful to have indices here at the beginning of the file in the
Xtop node rather than at the end, as in a printed book.
X
X\item
XThe third and subsequent parts contain a listing of the other, lower
Xlevel nodes, often ordered by chapter. This way, an inquirer can go
Xdirectly to a particular node if he or she is searching for specific
Xinformation. (These nodes are not required; use them if you think they
Xare a convenience.)
X\end{itemize}
X
XEach section in the menu can be introduced a descriptive line. So long as
Xthe line does not begin with an asterisk, it will not be treated as a menu
Xitem. (\xref{Menu Environment}, for more information.)
X
XFor example, the Top node of this manual looks like this (but with many
Xmore entries):
X
X\begin{verbatim}
X \node Top, Overview, (dir), (dir)
X
X\begin{menu}
X* Overview:: What is LaTeXinfo?
X* LaTeXinfo Mode:: Special features in GNU Emacs.
X...
X
XIndices, nodes containing large menus
X
X* Command Index:: An item for each command.
X* Concept Index:: An item for each concept.
X
XA detailed node listing
X
XOverview
X* Info File:: Characteristics of the Info file.
X* Printed Manual:: Characteristics of the printed manual.
X
XUsing LaTeXinfo Mode
X* Info on a Region:: Formatting a region for Info.
X* Showing the Structure:: Showing the structure of a file.
X...
X...
X\end{verbatim}
X
X\node Licensing and Distribution Information, Ending a LaTeXinfo File, The Top Node and Master Menu, Beginning a LaTeXinfo File
X\section{Licensing and Distribution Information}
X\cindex{Distribution}
X\cindex{License agreement}
X
XIf the \LaTeX info file has a section containing the ``General Public License''
Xand the distribution information or a warranty disclaimer, this section
Xusually follows the \samp{Top} node. The licensing and distribution
Xinformation and the disclaimer are followed by a preface, or else by the
Xfirst chapter of the manual.
X
XThe licensing agreement is very important to Project GNU documentation and
Xsoftware. Without it, you may find that you can no longer get the software
Xor its documentation. This sounds paradoxical, but the state of the world
Xis such that documentation and software that does not have a
X``restrictive'' license to make them freely distributable may be lost to
Xthe public. This has happened.\refill
X
XFor a good example of the text that could be used for the Distribution,
XGeneral Public License and NO WARRANTY sections of your document, see the
Xlatest version of the GNU Emacs Manual (\cite{GNUEmacsManual}).
X
X\cindex{Preface}
XAlthough a preface is not a required part of a \LaTeX info file, it is very
Xhelpful. Ideally, it should state clearly and concisely what the file is
Xabout and who would be interested in reading it. In general, the preface
Xwould follow the licensing and distribution information, although sometimes
Xpeople put it earlier in the document. Usually, a preface is put in an
X\code{\back chapter*} section.
X
X\node Ending a LaTeXinfo File, Making a Bibliography, Licensing and Distribution Information, Top
X\chapter{Ending a LaTeXinfo File}
X\cindex{Ending a LaTeXinfo File}
X\cindex{LaTeXinfo file ending}
X\cindex{File ending}
X
XThe end of a \LaTeX info file should include the bibliography, the
Xindices and the command that tells \LaTeX\ that it has reached the end
Xof the file. For example, a \LaTeX info file might be ended as follows:
X
X\begin{verbatim}
X\begin{tex}
X\bibliography{latexinfo}
X\end{tex}
X
X\twocolumn
X \node Concept Index, , Previous Node, Top
X \chapter*{Concept Index}
X\cindex{Concept Index}
X
X\printindex{cp}
X
X\end{document}
X\end{verbatim}
X
XThe \code{\back end\{document\}} command should be on a line by itself and
Xevery \LaTeX info file must end with such a line. This command terminates
X\LaTeX\ processing and forces out unfinished pages.\refill
X
X
X\begin{menu}
X* Making a Bibliography::
X* Creating Indices::
X\end{menu}
X
X\node Making a Bibliography, Creating Indices, Ending a LaTeXinfo File, Ending a LaTeXinfo File
X\section{Making a Bibliography}
X\cindex{Making a Bibliography}
X\findex{bibliographystyle}
X
XYou may also choose to include a bibliography of citations in the document.
XCitations are prepared using the program \t{BibTeX}, which formats the
Xcitations for use with \LaTeX. See the \LaTeX\ Manual for more details
X(\cite{Lamport}).\refill
X
XBefore you use the \code{\back cite} command, you must declare the
Xbibliography style that you are going to use. This is usually done at
Xthe beginning of the document, for example
X
X\begin{verbatim}
X\begin{document}
X\bibliographystyle{alpha}
X\end{verbatim}
X
XAt the end of the document comes the bibliography itself.
XThe \code{\back bibliography} takes as an argument a comma separated list
Xof filenames that contain the bibliography entries.
X
X\begin{verbatim}
X\begin{tex}
X\bibliography{latexinfo}
X\end{tex}
X\end{verbatim}
X
XWith these two sections in your document, you can use the \code{\back cite}
Xcommand to refer to the bibliography. For example
X
X\begin{verbatim}
Xa citation of the GNU Emacs Manual \cite{GNUEmacsManual}\dots
X\end{verbatim}
X
X\noindent
Xwould produce
X
X\begin{example}
Xa citation of the GNU Emacs Manual \cite{GNUEmacsManual}\dots
X\end{example}
X
X\noindent
Xand would cause an entry to be put in the Bibliography section something
Xlike
X
X\begin{description}
X\item[Sta86]
XRichard Stallman. \i{The GNU Emacs Manual},
XThe Free Software Foundation, 675 Massachusetts Ave., Cambridge MA,
X02139, 1986.
X\end{description}
X
X\xref{Cite}, for how to use citations in the document.
X
X\node Creating Indices, Defining the Entries of an Index, Making a Bibliography, Ending a LaTeXinfo File
X\section{Creating Indices}
X\cindex{Indices}
X\cindex{Creating indices}
X
XUsing \LaTeX info, you can generate printed indices and Info file menus without
Xhaving to sort and collate entries manually. \LaTeX info will do this for you
Xautomatically. Each index covers a certain kind of entry (functions, or
Xvariables, or concepts, etc.)\: and lists all of those entries in
Xalphabetical order, together with information on how to find the discussion
Xof each entry. In a printed manual, this information consists of page
END_OF_FILE
if test 40336 -ne `wc -c <'manual/latexinfo.tex-aa'`; then
echo shar: \"'manual/latexinfo.tex-aa'\" unpacked with wrong size!
fi
# end of 'manual/latexinfo.tex-aa'
fi
echo shar: End of archive 7 \(of 9\).
cp /dev/null ark7isdone
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