\input texinfo.tex @c -*-texinfo-*-
-@c $Id: texinfo.txi,v 1.50 1998/02/27 21:21:34 karl Exp $
+@c $Id: texinfo.txi,v 1.162 1999/09/28 19:38:01 karl Exp $
@c %**start of header
@c All text is ignored before the setfilename.
@setfilename ../info/texinfo.info
-@settitle Texinfo @value{edition}
-@c Edition number is now the same as the Texinfo distribution version number.
-@set edition 3.12
-@set update-month February 1998
-@set update-date 27 @value{update-month}
+@set UPDATED 28 September 1999
+@set EDITION 4.0
+@set VERSION 4.0
+@settitle Texinfo @value{VERSION}
@c Define a new index for options.
@defcodeindex op
@footnotestyle separate
@paragraphindent 2
@finalout
-@comment %**end of header
-@c Before release, run C-u C-c C-u C-a (texinfo-all-menus-update with a
-@c prefix arg). This updates the node pointers, which texinfmt.el needs.
+@comment %**end of header
@dircategory Texinfo documentation system
@direntry
* Texinfo: (texinfo). The GNU documentation format.
-* install-info: (texinfo)Invoking install-info. Updating info/dir entries.
-* texi2dvi: (texinfo)Format with texi2dvi. Printing Texinfo documentation.
-* texindex: (texinfo)Format with tex/texindex. Sorting Texinfo index files.
+* install-info: (texinfo)Invoking install-info. Update info/dir entries.
+* texi2dvi: (texinfo)Format with texi2dvi. Print Texinfo documents.
+* texindex: (texinfo)Format with tex/texindex. Sort Texinfo index files.
* makeinfo: (texinfo)makeinfo Preferred. Translate Texinfo source.
@end direntry
+@c Before release, run C-u C-c C-u C-a (texinfo-all-menus-update with a
+@c prefix arg). This updates the node pointers, which texinfmt.el needs.
+
@c Set smallbook if printing in smallbook format so the example of the
@c smallbook font is actually written using smallbook; in bigbook, a kludge
@c is used for TeX output. Do this through the -t option to texi2dvi,
@c set smallbook
@c @@clear smallbook
+@c If you like blank pages. Can add through texi2dvi -t.
+@c setchapternewpage odd
+
@c Currently undocumented command, 5 December 1993:
@c nwnode (Same as node, but no warnings; for `makeinfo'.)
@ifinfo
This file documents Texinfo, a documentation system that can produce
-both on-line information and a printed manual from a single source file.
+both online information and a printed manual from a single source file.
-Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98
+Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98, 99
Free Software Foundation, Inc.
-This edition is for Texinfo version @value{edition}.
+This edition is for Texinfo version @value{VERSION}, @value{UPDATED}.
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
by the Free Software Foundation.
@end ifinfo
-@setchapternewpage odd
@shorttitlepage Texinfo
@c use the new format for titles
@title Texinfo
@subtitle The GNU Documentation Format
-@subtitle for Texinfo version @value{edition}
-@subtitle @value{update-month}
+@subtitle for Texinfo version @value{VERSION}, @value{UPDATED}
-@author Robert J.@: Chassell
-@author Richard M.@: Stallman
+@author Robert J. Chassell
+@author Richard M. Stallman
@c Include the Distribution inside the titlepage so
@c that headings are turned off.
@page
@vskip 0pt plus 1filll
-Copyright @copyright{} 1988, 90, 91, 92, 93, 95, 96, 97, 98
+Copyright @copyright{} 1988, 90, 91, 92, 93, 95, 96, 97, 98, 99
Free Software Foundation, Inc.
+This manual is for Texinfo version @value{VERSION}, @value{UPDATED}.
+
Published by the Free Software Foundation @*
59 Temple Place Suite 330 @*
Boston, MA 02111-1307 @*
USA @*
-ISBN 1-882114-65-5
+ISBN 1-882114-67-1 @c for version 4.0, September 1999.
+@c ISBN 1-882114-65-5 @c for version 3.12, March 1998.
@c ISBN 1-882114-63-9 is for edition 2.20 of 28 February 1995
@c ISBN 1-882114-64-7 is for edition 2.24 of November 1996.
Cover art by Etienne Suvasa.
@end titlepage
-@ifinfo
-@node Top, Copying, (dir), (dir)
+@summarycontents
+@contents
+
+@ifnottex
+@node Top
@top Texinfo
Texinfo is a documentation system that uses a single source file to
-produce both on-line information and printed output.@refill
+produce both online information and printed output.
The first part of this master menu lists the major nodes in this Info
document, including the @@-command and concept indices. The rest of
-the menu lists all the lower level nodes in the document.@refill
-
-This is Edition @value{edition} of the Texinfo documentation,
-@w{@value{update-date}}.
-@end ifinfo
+the menu lists all the lower level nodes in the document.
-@c Here is a spare copy of the chapter menu entry descriptions,
-@c in case they are accidently deleted
-@ignore
-Your rights.
-Texinfo in brief.
-How to use Texinfo mode.
-What is at the beginning of a Texinfo file?
-What is at the end of a Texinfo file?
-How to create chapters, sections, subsections,
- appendices, and other parts.
-How to provide structure for a document.
-How to write nodes.
-How to write menus.
-How to write cross references.
-How to mark words and phrases as code,
- keyboard input, meta-syntactic
- variables, and the like.
-How to write quotations, examples, etc.
-How to write lists and tables.
-How to create indices.
-How to insert @@-signs, braces, etc.
-How to indicate results of evaluation,
- expansion of macros, errors, etc.
-How to force and prevent line and page breaks.
-How to describe functions and the like in a uniform manner.
-How to write footnotes.
-How to specify text for either @TeX{} or Info.
-How to print hardcopy.
-How to create an Info file.
-How to install an Info file
-A list of all the Texinfo @@-commands.
-Hints on how to write a Texinfo document.
-A sample Texinfo file to look at.
-Tell readers they have the right to copy
- and distribute.
-How to incorporate other Texinfo files.
-How to write page headings and footings.
-How to find formatting mistakes.
-All about paragraph refilling.
-A description of @@-Command syntax.
-Texinfo second edition features.
-A menu containing commands and variables.
-A menu covering many topics.
-@end ignore
+This is Edition @value{VERSION} of the Texinfo manual, updated @value{UPDATED}.
+@end ifnottex
@menu
* Copying:: Your rights.
* Breaks:: How to force and prevent line and page breaks.
* Definition Commands:: How to describe functions and the like
in a uniform manner.
-* Footnotes:: How to write footnotes.
* Conditionals:: How to specify text for either @TeX{} or Info.
-* Macros:: Defining new Texinfo commands.
-* Format/Print Hardcopy:: How to convert a Texinfo file to a file
+* Internationalization::
+* Defining New Texinfo Commands::
+* Hardcopy:: How to convert a Texinfo file to a file
for printing and how to print that file.
-* Create an Info File:: Convert a Texinfo file into an Info file.
-* Install an Info File:: Make an Info file accessible to users.
+* Creating and Installing Info Files::
* Command List:: All the Texinfo @@-commands.
* Tips:: Hints on how to write a Texinfo document.
* Sample Texinfo File:: A sample Texinfo file to look at.
Overview of Texinfo
-* Using Texinfo:: Create a conventional printed book
- or an Info file.
+* Reporting Bugs:: Submitting effective bug reports.
+* Using Texinfo:: Create printed or online output.
* Info Files:: What is an Info file?
* Printed Books:: Characteristics of a printed book or manual.
* Formatting Commands:: @@-commands are used for formatting.
* Conventions:: General rules for writing a Texinfo file.
-* Comments:: How to write comments and mark regions that
- the formatting commands will ignore.
+* Comments:: Writing comments and ignored text in general.
* Minimum:: What a Texinfo file must have.
* Six Parts:: Usually, a Texinfo file has six parts.
* Short Sample:: A short sample Texinfo file.
-* Acknowledgements::
+* Acknowledgements and History:: Contributors and genesis.
Using Texinfo Mode
* setfilename:: Tell Info the name of the Info file.
* settitle:: Create a title for the printed work.
* setchapternewpage:: Start chapters on right-hand pages.
-* paragraphindent:: An option to specify paragraph indentation.
+* paragraphindent:: Specify paragraph indentation.
+* exampleindent:: Specify environment indentation.
* End of Header:: Formatting a region requires this.
The Title and Copyright Pages
* Two Paths:: Different commands to structure
Info output and printed output.
* Node Menu Illustration:: A diagram, and sample nodes and menus.
-* node:: How to write a node, in detail.
-* makeinfo Pointer Creation:: How to create node pointers with @code{makeinfo}.
+* node:: Creating nodes, in detail.
+* makeinfo Pointer Creation:: Letting makeinfo determine node pointers.
+* anchor:: Defining arbitrary cross-reference targets.
The @code{@@node} Command
Indicating Definitions, Commands, etc.
* Useful Highlighting:: Highlighting provides useful information.
-* code:: How to indicate code.
-* kbd:: How to show keyboard input.
-* key:: How to specify keys.
-* samp:: How to show a literal sequence of characters.
-* var:: How to indicate a metasyntactic variable.
-* file:: How to indicate the name of a file.
-* dfn:: How to specify a definition.
-* cite:: How to refer to a book that is not in Info.
-* url:: How to indicate a world wide web reference.
-* email:: How to indicate an electronic mail address.
+* code:: Indicating program code.
+* kbd:: Showing keyboard input.
+* key:: Specifying keys.
+* samp:: Showing a literal sequence of characters.
+* var:: Indicating metasyntactic variables.
+* env:: Indicating environment variables.
+* file:: Indicating file names.
+* command:: Indicating command names.
+* option:: Indicating option names.
+* dfn:: Specifying definitions.
+* cite:: Referring to books not in the Info system.
+* acronym:: Indicating acronyms.
+* url:: Indicating a World Wide Web reference.
+* email:: Indicating an electronic mail address.
Emphasizing Text
* emph & strong:: How to emphasize text in Texinfo.
* Smallcaps:: How to use the small caps font.
* Fonts:: Various font commands for printed output.
-* Customized Highlighting:: How to define highlighting commands.
Quotations and Examples
* quotation:: How to write a quotation.
* example:: How to write an example in a fixed-width font.
* noindent:: How to prevent paragraph indentation.
-* Lisp Example:: How to illustrate Lisp code.
-* smallexample & smalllisp:: Forms for the @code{@@smallbook} option.
+* lisp:: How to illustrate Lisp code.
+* small:: Forms for @code{@@smallbook}.
* display:: How to write an example in the current font.
* format:: How to write an example that does not narrow
the margins.
* Multitable Column Widths:: Defining multitable column widths.
* Multitable Rows:: Defining multitable rows, with examples.
-Creating Indices
+Indices
* Index Entries:: Choose different words for index entries.
* Predefined Indices:: Use different indices for different kinds
* math:: How to format a mathematical expression.
* Glyphs:: How to indicate results of evaluation,
expansion of macros, errors, etc.
+* Footnotes:: How to include footnotes.
* Images:: How to include graphics.
Inserting @@ and Braces
Glyphs Summary
-* result::
-* expansion::
-* Print Glyph::
-* Error Glyph::
-* Equivalence::
-* Point Glyph::
+* result::
+* expansion::
+* Print Glyph::
+* Error Glyph::
+* Equivalence::
+* Point Glyph::
+
+Footnotes
+
+* Footnote Commands:: How to write a footnote in Texinfo.
+* Footnote Styles:: Controlling how footnotes appear in Info.
Making and Preventing Breaks
* Abstract Objects:: Commands for object-oriented programming.
* Data Types:: The definition command for data types.
-Footnotes
-
-* Footnote Commands:: How to write a footnote in Texinfo.
-* Footnote Styles:: Controlling how footnotes appear in Info.
-
Conditionally Visible Text
* Conditional Commands:: Specifying text for HTML, Info, or @TeX{}.
@code{@@set}, @code{@@clear}, and @code{@@value}
* ifset ifclear:: Format a region if a flag is set.
-* value:: Replace a flag with a string.
+* set value:: Expand a flag variable to a string.
* value Example:: An easy way to update edition information.
-Macros: Defining New Texinfo Commands
+Internationalization
+
+* documentlanguage:: Declaring the current language.
+* documentencoding:: Declaring the input encoding.
-* Defining Macros:: Both defining and undefining new commands.
+Defining New Texinfo Commands
+
+* Defining Macros:: Defining and undefining new commands.
* Invoking Macros:: Using a macro, once you've defined it.
+* Macro Details:: Beyond basic macro usage.
+* alias:: Command aliases.
+* definfoenclose:: Customized highlighting.
-Format and Print Hardcopy
+Formatting and Printing Hardcopy
* Use TeX:: Use @TeX{} to format for hardcopy.
-* Format with tex/texindex:: How to format in a shell.
-* Format with texi2dvi:: A simpler way to use the shell.
+* Format with tex/texindex:: How to format with explicit shell commands.
+* Format with texi2dvi:: A simpler way to format.
* Print with lpr:: How to print.
* Within Emacs:: How to format and print from an Emacs shell.
* Texinfo Mode Printing:: How to format and print in Texinfo mode.
* Compile-Command:: How to print using Emacs's compile command.
* Requirements Summary:: @TeX{} formatting requirements summary.
-* Preparing for TeX:: What you need to do to use @TeX{}.
+* Preparing for TeX:: What to do before you use @TeX{}.
* Overfull hboxes:: What are and what to do with overfull hboxes.
* smallbook:: How to print small format books and manuals.
* A4 Paper:: How to print on European A4 paper.
+* pagesizes:: How to print with customized page sizes.
* Cropmarks and Magnification:: How to print marks to indicate the size
of pages and how to print scaled up output.
+* PDF Output:: Portable Document Format output.
+
+Creating and Installing Info Files
+
+* Creating an Info File::
+* Install an Info File::
Creating an Info File
* Batch Formatting:: How to format for Info in Emacs Batch mode.
* Tag and Split Files:: How tagged and split files help Info
to run better.
+* makeinfo html:: Generating HTML output.
Installing an Info File
-* Directory file:: The top level menu for all Info files.
+* Directory File:: The top level menu for all Info files.
* New Info File:: Listing a new info file.
* Other Info Directories:: How to specify Info files that are
located in other directories.
* Unsplit:: How to create an unsplit file.
* Tagifying:: How to tagify a file.
* Splitting:: How to split a file manually.
-
-How to Obtain @TeX{}
-
-@c * New Texinfo Mode Commands:: The updating commands are especially useful.
-@c * New Commands:: Many newly described @@-commands.
@end detailmenu
@end menu
-@node Copying, Overview, Top, Top
-@comment node-name, next, previous, up
+@c Reward readers for getting to the end of the menu :).
+@c Contributed by Arnold Robbins.
+@quotation
+Documentation is like sex: when it is good, it is very, very good; and
+when it is bad, it is better than nothing.
+---Dick Brandon
+@end quotation
+
+
+@node Copying
@unnumbered Texinfo Copying Conditions
@cindex Copying conditions
@cindex Conditions for copying Texinfo
so that any problems introduced by others will not reflect on our
reputation.@refill
- The precise conditions of the licenses for the programs currently
+The precise conditions of the licenses for the programs currently
being distributed that relate to Texinfo are found in the General Public
-Licenses that accompany them.@refill
+Licenses that accompany them.
-@node Overview, Texinfo Mode, Copying, Top
-@comment node-name, next, previous, up
+
+@node Overview
@chapter Overview of Texinfo
@cindex Overview of Texinfo
@cindex Texinfo overview
-@dfn{Texinfo}@footnote{Note that the first syllable of ``Texinfo'' is
-pronounced like ``speck'', not ``hex''. This odd pronunciation is
-derived from, but is not the same as, the pronunciation of @TeX{}. In
-the word @TeX{}, the @samp{X} is actually the Greek letter ``chi''
-rather than the English letter ``ex''. Pronounce @TeX{} as if the
-@samp{X} were the last sound in the name `Bach'; but pronounce Texinfo
-as if the @samp{x} were a `k'. Spell ``Texinfo'' with a capital ``T''
-and write the other letters in lower case.}
-is a documentation system that uses a single source file to produce both
-on-line information and printed output. This means that instead of
-writing two different documents, one for the on-line help or other on-line
-information and the other for a typeset manual or other printed work, you
-need write only one document. When the work is revised, you need revise
-only one document. (You can read the on-line information, known as an
-@dfn{Info file}, with an Info documentation-reading program.)@refill
+@dfn{Texinfo}@footnote{The first syllable of ``Texinfo'' is pronounced
+like ``speck'', not ``hex''. This odd pronunciation is derived from,
+but is not the same as, the pronunciation of @TeX{}. In the word
+@TeX{}, the @samp{X} is actually the Greek letter ``chi'' rather than
+the English letter ``ex''. Pronounce @TeX{} as if the @samp{X} were the
+last sound in the name `Bach'; but pronounce Texinfo as if the @samp{x}
+were a `k'. Spell ``Texinfo'' with a capital ``T'' and the other
+letters in lower case.} is a documentation system that uses a single
+source file to produce both online information and printed output. This
+means that instead of writing two different documents, one for the
+online information and the other for a printed work, you need write only
+one document. Therefore, when the work is revised, you need revise only
+that one document.
@menu
-* Using Texinfo:: Create a conventional printed book
- or an Info file.
+* Reporting Bugs:: Submitting effective bug reports.
+* Using Texinfo:: Create printed or online output.
* Info Files:: What is an Info file?
* Printed Books:: Characteristics of a printed book or manual.
* Formatting Commands:: @@-commands are used for formatting.
* Conventions:: General rules for writing a Texinfo file.
-* Comments:: How to write comments and mark regions that
- the formatting commands will ignore.
+* Comments:: Writing comments and ignored text in general.
* Minimum:: What a Texinfo file must have.
* Six Parts:: Usually, a Texinfo file has six parts.
* Short Sample:: A short sample Texinfo file.
-* Acknowledgements::
+* Acknowledgements and History:: Contributors and genesis.
@end menu
-@node Using Texinfo, Info Files, Overview, Overview
-@ifinfo
-@heading Using Texinfo
-@end ifinfo
+
+@node Reporting Bugs
+@section Reporting Bugs
+
+@cindex Bugs, reporting
+@cindex Suggestions for Texinfo, making
+@cindex Reporting bugs
+We welcome bug reports or suggestions for the Texinfo system, both
+programs and documentation. Please email them to
+@email{bug-texinfo@@gnu.org}. You can get the latest version of Texinfo
+from @uref{ftp://ftp.gnu.org/gnu/texinfo/} and its mirrors worldwide.
+
+@cindex Checklist for bug reports
+For bug reports, please include enough information for the maintainers
+to reproduce the problem. Generally speaking, that means:
+
+@itemize @bullet
+@item the version number of Texinfo and the program(s) or manual(s) involved.
+@item hardware, operating system, and compiler versions.
+@item any unusual options you gave to @command{configure}.
+@item the contents of any input files necessary to reproduce the bug.
+@item a description of the problem and samples of any erroneous output.
+@item anything else that you think would be helpful.
+@end itemize
+
+When in doubt whether something is needed or not, include it. It's
+better to include too much than to leave out something important.
+
+Patches are most welcome; if possible, please make them with
+@samp{@w{diff -c}} (@pxref{Top,, Overview, diffutils, Comparing and
+Merging Files}) and include @file{ChangeLog} entries (@pxref{Change
+Log,,, emacs, The GNU Emacs Manual}).
+
+When sending email, please do not encode or split the messages in any
+way if possible; it's much easier to deal with one plain text message,
+however large, than many small ones.
+@uref{ftp://ftp.gnu.org/gnu/sharutils/, GNU shar} is a convenient way of
+packaging multiple and/or binary files for email.
+
+
+@node Using Texinfo
+@section Using Texinfo
+
+@cindex Using Texinfo in general
+@cindex Texinfo, introduction to
+@cindex Introduction to Texinfo
Using Texinfo, you can create a printed document with the normal
-features of a book, including chapters, sections, cross references,
-and indices. From the same Texinfo source file, you can create a
-menu-driven, on-line Info file with nodes, menus, cross references,
-and indices. You can, if you wish, make the chapters and sections of
-the printed document correspond to the nodes of the on-line
-information; and you use the same cross references and indices for
-both the Info file and the printed work. @cite{The GNU
-Emacs Manual} is a good example of a Texinfo file, as is this manual.@refill
+features of a book, including chapters, sections, cross references, and
+indices. From the same Texinfo source file, you can create a
+menu-driven, online Info file with nodes, menus, cross references, and
+indices. You can also create from that same source file an HTML output
+file suitable for use with a web browser. @cite{The GNU Emacs Manual}
+is a good example of a Texinfo file, as is this manual.
To make a printed document, you process a Texinfo source file with the
-@TeX{} typesetting program. This creates a DVI file that you can
-typeset and print as a book or report. (Note that the Texinfo language
-is completely different from @TeX{}'s usual language, plain @TeX{}.) If
-you do not have @TeX{}, but do have @code{troff} or @code{nroff}, you
-can use the @code{texi2roff} program instead.@refill
-
-To make an Info file, you process a Texinfo source file with the
-@code{makeinfo} utility or Emacs's @code{texinfo-format-buffer} command;
-this creates an Info file that you can install on-line.@refill
-
-@TeX{} and @code{texi2roff} work with many types of printers; similarly,
-Info works with almost every type of computer terminal. This power
-makes Texinfo a general purpose system, but brings with it a constraint,
-which is that a Texinfo file may contain only the customary
-``typewriter'' characters (letters, numbers, spaces, and punctuation
-marks) but no special graphics.@refill
-
-A Texinfo file is a plain @sc{ascii} file containing text and
+@TeX{} typesetting program (but the Texinfo language is very different
+from @TeX{}'s usual language, plain @TeX{}). This creates a DVI file
+that you can typeset and print as a book or report (@pxref{Hardcopy}).
+
+@pindex makeinfo
+To output an Info file, process your Texinfo source with the
+@code{makeinfo} utility or Emacs's @code{texinfo-format-buffer} command.
+You can install the result in your Info tree (@pxref{Install an Info
+File}).
+
+To output an HTML file, process your Texinfo source with @code{makeinfo}
+using the @samp{--html} option. You can (for example) install the
+result on your web site.
+
+@cindex Output formats, supporting more
+@cindex Docbook output format
+@cindex SGML-tools output format
+If you are a programmer and would like to contribute to the GNU project
+by implementing additional output formats for Texinfo, that would be
+excellent. But please do not write a separate translator texi2foo for
+your favorite format foo! That is the hard way to do the job, and makes
+extra work in subsequent maintenance, since the Texinfo language is
+continually being enhanced and updated. Instead, the best approach is
+modify @code{makeinfo} to generate the new format, as it does now for
+Info and HTML.
+
+@TeX{} works with virtually all printers; Info works with virtually all
+computer terminals; the HTML output works with virtually all web
+browsers. Thus Texinfo can be used by almost any computer user.
+
+@cindex Source file
+A Texinfo source file is a plain @sc{ascii} file containing text and
@dfn{@@-commands} (words preceded by an @samp{@@}) that tell the
-typesetting and formatting programs what to do. You may edit a
-Texinfo file with any text editor; but it is especially convenient to
-use GNU Emacs since that editor has a special mode, called Texinfo
-mode, that provides various Texinfo-related features. (@xref{Texinfo
-Mode}.)@refill
-
-Before writing a Texinfo source file, you should become familiar with
-the Info documentation reading program and learn about nodes,
-menus, cross references, and the rest. (@inforef{Top, info, info},
-for more information.)@refill
+typesetting and formatting programs what to do. You may edit a Texinfo
+file with any text editor; but it is especially convenient to use GNU
+Emacs since that editor has a special mode, called Texinfo mode, that
+provides various Texinfo-related features. (@xref{Texinfo Mode}.)
-You can use Texinfo to create both on-line help and printed manuals;
-moreover, Texinfo is freely redistributable. For these reasons, Texinfo
-is the format in which documentation for GNU utilities and libraries is
-written.@refill
+Before writing a Texinfo source file, you should learn about nodes,
+menus, cross references, and the rest, for example by reading this
+manual.
-@node Info Files, Printed Books, Using Texinfo, Overview
-@comment node-name, next, previous, up
+You can use Texinfo to create both online help and printed manuals;
+moreover, Texinfo is freely redistributable. For these reasons, Texinfo
+is the official documentation format of the GNU project. More
+information is available at the @uref{http://www.gnu.org/doc/, GNU
+documentation web page}.
+
+@cindex Man page output, not supported
+From time to time, proposals are made to generate traditional Unix man
+pages from Texinfo source. This is not likely to ever be supported,
+because man pages have a very strict conventional format. Merely
+enhancing @command{makeinfo} to output troff format would be
+insufficient. Generating a good man page therefore requires a
+completely different source than the typical Texinfo applications of
+generating a good user manual or a good reference manual. This makes
+generating man pages incompatible with the Texinfo design goal of not
+having to document the same information in different ways for different
+output formats. You might as well just write the man page directly.
+
+@pindex help2man
+@cindex O'Dea, Brendan
+If you wish to support man pages, the program @command{help2man} may be
+useful; it generates a traditional man page from the @samp{--help}
+output of a program. In fact, this is currently used to generate man
+pages for the Texinfo programs themselves. It is free software written
+by Brendan O'Dea, available from
+@uref{http://www.ozemail.com.au/~bod/help2man.tar.gz}.
+
+
+@node Info Files
@section Info files
@cindex Info files
departure point for the whole Info system. From it, you can reach the
`Top' nodes of each of the documents in a complete Info system.@refill
-@node Printed Books, Formatting Commands, Info Files, Overview
-@comment node-name, next, previous, up
+@cindex URI syntax for Info
+If you wish to refer to an Info file in a URI, you can use the
+(unofficial) syntax exemplified in the following. This works with
+Emacs/W3, for example:
+@example
+info:///usr/info/emacs#Dissociated%20Press
+info:emacs#Dissociated%20Press
+info://localhost/usr/info/emacs#Dissociated%20Press
+@end example
+
+The @command{info} program itself does not follow URI's of any kind.
+
+
+@node Printed Books
@section Printed Books
@cindex Printed book and manual characteristics
@cindex Manual characteristics, printed
A Texinfo file can be formatted and typeset as a printed book or manual.
To do this, you need @TeX{}, a powerful, sophisticated typesetting
program written by Donald Knuth.@footnote{You can also use the
-@code{texi2roff} program if you do not have @TeX{}; since Texinfo is
-designed for use with @TeX{}, @code{texi2roff} is not described here.
-@code{texi2roff} is not part of the standard GNU distribution.}
+@pindex texi2roff@r{, unsupported software}
+@uref{ftp://tug.org/texi2roff.tar.gz, @code{texi2roff}} program if you
+do not have @TeX{}; since Texinfo is designed for use with @TeX{},
+@code{texi2roff} is not described here. @code{texi2roff} is not part of
+the standard GNU distribution and is not maintained or up-to-date with
+all the Texinfo features described in this manual.}
A Texinfo-based book is similar to any other typeset, printed work: it
can have a title page, copyright page, table of contents, and preface,
page headers, cross references, footnotes, and indices.@refill
You can use Texinfo to write a book without ever having the intention
-of converting it into on-line information. You can use Texinfo for
+of converting it into online information. You can use Texinfo for
writing a printed novel, and even to write a printed memo, although
this latter application is not recommended since electronic mail is so
much easier.@refill
@TeX{} is a general purpose typesetting program. Texinfo provides a
-file called @file{texinfo.tex} that contains information (definitions or
+file @file{texinfo.tex} that contains information (definitions or
@dfn{macros}) that @TeX{} uses when it typesets a Texinfo file.
(@file{texinfo.tex} tells @TeX{} how to convert the Texinfo @@-commands
to @TeX{} commands, which @TeX{} can then process to create the typeset
document.) @file{texinfo.tex} contains the specifications for printing
-a document.@refill
+a document. You can get the latest version of @file{texinfo.tex} from
+@uref{ftp://ftp.gnu.org/gnu/texinfo.tex}.
Most often, documents are printed on 8.5 inch by 11 inch
pages (216@dmn{mm} by 280@dmn{mm}; this is the default size), but you
@TeX{} is freely distributable. It is written in a superset of Pascal
called WEB and can be compiled either in Pascal or (by using a
conversion program that comes with the @TeX{} distribution) in C.
-(@xref{TeX Mode, ,@TeX{} Mode, xemacs, XEmacs User's Manual}, for information
+(@xref{TeX Mode, ,@TeX{} Mode, emacs, The GNU Emacs Manual}, for information
about @TeX{}.)@refill
@TeX{} is very powerful and has a great many features. Because a
formatting commands that Texinfo supports are necessarily
limited.@refill
-@xref{Obtaining TeX, , How to Obtain @TeX{}}.
+To get a copy of @TeX{}, see
+@ref{Obtaining TeX, , How to Obtain @TeX{}}.
@node Formatting Commands, Conventions, Printed Books, Overview
@TeX{} on a wide variety of printers.@refill
Depending on what they do or what arguments@footnote{The word
-@dfn{argument} comes from the way it is used in mathematics and does
-not refer to a disputation between two people; it refers to the
-information presented to the command. According to the @cite{Oxford
-English Dictionary}, the word derives from the Latin for @dfn{to make
-clear, prove}; thus it came to mean `the evidence offered as proof',
-which is to say, `the information offered', which led to its
-mathematical meaning. In its other thread of derivation, the word
-came to mean `to assert in a manner against which others may make
-counter assertions', which led to the meaning of `argument' as a
-disputation.} they take, you need to write @@-commands on lines of
-their own or as part of sentences:@refill
+@dfn{argument} comes from the way it is used in mathematics and does not
+refer to a dispute between two people; it refers to the information
+presented to the command. According to the @cite{Oxford English
+Dictionary}, the word derives from the Latin for @dfn{to make clear,
+prove}; thus it came to mean `the evidence offered as proof', which is
+to say, `the information offered', which led to its mathematical
+meaning. In its other thread of derivation, the word came to mean `to
+assert in a manner against which others may make counter assertions',
+which led to the meaning of `argument' as a dispute.} they take, you
+need to write @@-commands on lines of their own or as part of
+sentences:
@itemize @bullet
@item
marks text as being code.)@refill
@item
-Write a command such as @code{@@example} at the beginning of a line of
-its own; write the body-text on following lines; and write the matching
-@code{@@end} command, @code{@@end example} in this case, at the
-beginning of a line of its own after the body-text. (@code{@@example}
-@dots{} @code{@@end example} indents and typesets body-text as an
-example.)@refill
+Write a command such as @code{@@example} on a line of its own; write the
+body-text on following lines; and write the matching @code{@@end}
+command, @code{@@end example} in this case, at the on a line of its own
+after the body-text. (@code{@@example} @dots{} @code{@@end example}
+indents and typesets body-text as an example.) It's usually ok to
+indent environment commands like this, but in complicated and
+hard-to-define circumstances the extra spaces cause extra space to
+appear in the output, so beware.
@end itemize
@noindent
@cindex Syntactic conventions
@cindex Conventions, syntactic
+This section describes the general conventions used in all Texinfo documents.
+
+@itemize @bullet
+@item
All printable @sc{ascii} characters except @samp{@@}, @samp{@{} and
@samp{@}} can appear in a Texinfo file and stand for themselves.
@samp{@@} is the escape character which introduces commands.
document, put an @samp{@@} character in front of it, like this:
@samp{@@@@}, @samp{@@@{}, and @samp{@@@}}.@refill
+@item
@ifinfo
It is customary in @TeX{} to use doubled single-quote characters to
begin and end quotations: ` ` and ' ' (but without a space between the
@end ifinfo
@iftex
It is customary in @TeX{} to use doubled single-quote characters to
-begin and end quotations: @w{@tt{ `` }} and @w{@tt{ '' }}. This
+begin and end quotations: @w{@t{ `` }} and @w{@t{ '' }}. This
convention should be followed in Texinfo files. @TeX{} converts
doubled single-quote characters to left- and right-hand doubled
quotation marks, ``like this'', and Info converts doubled single-quote
-characters to @sc{ascii} double-quotes: @w{@tt{ `` }} and
-@w{@tt{ '' }} to @w{@tt{ " }}.@refill
+characters to @sc{ascii} double-quotes: @w{@t{ `` }} and
+@w{@t{ '' }} to @w{@t{ " }}.@refill
@end iftex
+@item
Use three hyphens in a row, @samp{---}, for a dash---like this. In
@TeX{}, a single or double hyphen produces a printed dash that is
shorter than the usual typeset dash. Info reduces three hyphens to two
for display on the screen.
+@item
To prevent a paragraph from being indented in the printed manual, put
the command @code{@@noindent} on a line by itself before the
paragraph.@refill
+@item
If you mark off a region of the Texinfo file with the @code{@@iftex}
and @w{@code{@@end iftex}} commands, that region will appear only in
the printed copy; in that region, you can use certain commands
Similarly for @code{@@ifhtml @dots{} @@end ifhtml},
@code{@@ifnothtml @dots{} @@end ifnothtml},
@code{@@ifnotinfo @dots{} @@end ifnotinfo},
-@code{@@ifnottex @dots{} @@end ifnottex},
+@code{@@ifnottex @dots{} @@end ifnottex}.
@xref{Conditionals}.
+@end itemize
@cindex Tabs; don't use!
@quotation
@noindent
Also, you can run @code{untabify} in Emacs to convert tabs in a region
to multiple spaces.@refill
-
-@noindent
-Don't use tabs.
@end quotation
@node Comments, Minimum, Conventions, Overview
You can write comments in a Texinfo file that will not appear in
either the Info file or the printed manual by using the
@code{@@comment} command (which may be abbreviated to @code{@@c}).
-Such comments are for the person who reads the Texinfo file. All the
+Such comments are for the person who revises the Texinfo file. All the
text on a line that follows either @code{@@comment} or @code{@@c} is a
comment; the rest of the line does not appear in either the Info file
or the printed manual. (Often, you can write the @code{@@comment} or
@cindex Texinfo file minimum
By convention, the names of Texinfo files end with one of the
-extensions @file{.texinfo}, @file{.texi}, or @file{.tex}. The longer
-extension is preferred since it describes more clearly to a human
-reader the nature of the file. The shorter extensions are for
+extensions @file{.texinfo}, @file{.texi}, @file{.txi}, or @file{.tex}.
+The longer extension is preferred since it describes more clearly to a
+human reader the nature of the file. The shorter extensions are for
operating systems that cannot handle long file names.@refill
In order to be made into a printed manual and an Info file, a Texinfo
own.@refill
@end table
-@node Short Sample, Acknowledgements, Six Parts, Overview
-@comment node-name, next, previous, up
+@node Short Sample
@section A Short Sample Texinfo File
@cindex Sample Texinfo file
insert the names for your own manual in this segment. (@xref{Beginning a
File}.)@refill
-@noindent
In the following, the sample text is @emph{indented}; comments on it are
not. The complete file, without any comments, is shown in
@ref{Sample Texinfo File}.
@@c %**start of header
@@setfilename sample.info
@@settitle Sample Document
-@@c %**end of header
-
@@setchapternewpage odd
+@@c %**end of header
@end group
@end example
@subheading Part 6: The End of the Document
@noindent
-The end segment contains commands both for generating an index in a node
-and unnumbered chapter of its own and for generating the table of
-contents; and it contains the @code{@@bye} command that marks the end of
-the document.@refill
+The end segment contains commands for generating an index in a node and
+unnumbered chapter of its own, (usually) for generating the table of
+contents, and the @code{@@bye} command that marks the end of the
+document.@refill
@example
@group
@@node Concept Index, , First Chapter, Top
-@@comment node-name, next, previous, up
@@unnumbered Concept Index
@end group
manual.
@end quotation
-@node Acknowledgements, , Short Sample, Overview
-@comment node-name, next, previous, up
-@section Acknowledgements
+
+@node Acknowledgements and History
+@section Acknowledgements and History
@cindex Stallman, Richard M.
@cindex Chassell, Robert J.
@cindex Berry, Karl
-Richard M.@: Stallman wrote Edition 1.0 of this manual. @w{Robert J.@:
-Chassell} revised and extended it, starting with Edition 1.1. Karl
-Berry made updates for the Texinfo 3.8 and subsequent releases, starting
-with Edition 2.22.
+Richard M.@: Stallman invented the Texinfo format, wrote the initial
+processors, and created Edition 1.0 of this manual. @w{Robert J.@:
+Chassell} greatly revised and extended the manual, starting with Edition
+1.1. Brian Fox was responsible for the standalone Texinfo distribution
+until version 3.8, and wrote the standalone @command{makeinfo} and
+@command{info}. Karl Berry has made the updates since Texinfo 3.8 and
+subsequent releases, starting with Edition 2.22 of the manual.
@cindex Pinard, Fran@,{c}ois
@cindex Zuhn, David D.
@cindex Weisshaus, Melissa
+@cindex Zaretskii, Eli
+@cindex Schwab, Andreas
+@cindex Weinberg, Zack
Our thanks go out to all who helped improve this work, particularly to
Fran@,{c}ois Pinard and @w{David D.@: Zuhn}, who tirelessly recorded and
reported mistakes and obscurities; our special thanks go to Melissa
Weisshaus for her frequent and often tedious reviews of nearly similar
-editions. Our mistakes are our own.
-
-Please send suggestions and corrections to:
-
-@example
-@group
-@r{Internet address:}
- bug-texinfo@@gnu.org
-@end group
-@end example
-
-@noindent
-Please include the manual's edition number and update date in your messages.
-
-@node Texinfo Mode, Beginning a File, Overview, Top
-@comment node-name, next, previous, up
+editions. The indefatigable Eli Zaretskii and Andreas Schwab have
+provided patches beyond counting. Zack Weinberg did the impossible by
+implementing the macro syntax in @file{texinfo.tex}. Dozens of others
+have contributed patches and suggestions, they are gratefully
+acknowledged in the @file{ChangeLog} file. Our mistakes are our own.
+
+@cindex Scribe
+@cindex Reid, Brian
+@cindex History of Texinfo
+A bit of history: in the 1970's at CMU, Brian Reid developed a program
+and format named Scribe to mark up documents for printing. It used the
+@code{@@} character to introduce commands as Texinfo does and strived to
+describe document contents rather than formatting.
+
+@cindex Bolio
+@cindex Bo@TeX{}
+Meanwhile, people at MIT developed another, not too dissimilar format
+called Bolio. This then was converted to using @TeX{} as its typesetting
+language: Bo@TeX{}.
+
+Bo@TeX{} could only be used as a markup language for documents to be
+printed, not for online documents. Richard Stallman (RMS) worked on
+both Bolio and Bo@TeX{}. He also developed a nifty on-line help format
+called Info, and then combined Bo@TeX{} and Info to create Texinfo, a
+mark up language for text that is intended to be read both on line and
+as printed hard copy.
+
+
+
+@node Texinfo Mode
@chapter Using Texinfo Mode
@cindex Texinfo mode
@cindex Mode, using Texinfo
@end ifinfo
Texinfo mode provides special features for working with Texinfo
-files:@refill
+files.
+You can:@refill
@itemize @bullet
@item
delimiter, you can jump from chapter title to chapter title with the
@kbd{C-x ]} (@code{forward-page}) and @kbd{C-x [}
(@code{backward-page}) commands and narrow to a chapter with the
-@kbd{C-x p} (@code{narrow-to-page}) command. (@xref{Pages, , , xemacs,
-XEmacs User's Manual}, for details about the page commands.)@refill
+@kbd{C-x p} (@code{narrow-to-page}) command. (@xref{Pages, , ,emacs,
+The GNU Emacs Manual}, for details about the page commands.)@refill
You may name a Texinfo file however you wish, but the convention is to
-end a Texinfo file name with one of the three extensions
-@file{.texinfo}, @file{.texi}, or @file{.tex}. A longer extension is
-preferred, since it is explicit, but a shorter extension may be
-necessary for operating systems that limit the length of file names.
-GNU Emacs automatically enters Texinfo mode when you visit a file with
-a @file{.texinfo} or @file{.texi}
+end a Texinfo file name with one of the extensions
+@file{.texinfo}, @file{.texi}, @file{.txi}, or @file{.tex}. A longer
+extension is preferred, since it is explicit, but a shorter extension
+may be necessary for operating systems that limit the length of file
+names. GNU Emacs automatically enters Texinfo mode when you visit a
+file with a @file{.texinfo}, @file{.texi} or @file{.txi}
extension. Also, Emacs switches to Texinfo mode
when you visit a
file that has @samp{-*-texinfo-*-} in its first line. If ever you are
If you call @code{texinfo-show-structure} with a prefix argument by
typing @w{@kbd{C-u C-c C-s}}, it will list not only those lines with the
-@@-commands for @code{@@chapter}, @code{@@section}, and the like,
-but also the @code{@@node} lines. (This is how the
-@code{texinfo-show-structure} command worked without an argument in
-the first version of Texinfo. It was changed because @code{@@node}
-lines clutter up the @samp{*Occur*} buffer and are usually not
-needed.) You can use @code{texinfo-show-structure} with a prefix
-argument to check whether the `Next', `Previous', and `Up' pointers of
-an @code{@@node} line are correct.@refill
+@@-commands for @code{@@chapter}, @code{@@section}, and the like, but
+also the @code{@@node} lines. You can use @code{texinfo-show-structure}
+with a prefix argument to check whether the `Next', `Previous', and `Up'
+pointers of an @code{@@node} line are correct.
Often, when you are working on a manual, you will be interested only
in the structure of the current chapter. In this case, you can mark
@kbd{C-x n n} (@code{narrow-to-region}) command and
@code{texinfo-show-structure} will work on only that region. To see
the whole buffer again, use @w{@kbd{C-x n w}} (@code{widen}).
-(@xref{Narrowing, , , xemacs, XEmacs User's Manual}, for more
+(@xref{Narrowing, , , emacs, The GNU Emacs Manual}, for more
information about the narrowing commands.)@refill
@vindex page-delimiter
]} (@code{forward-page}) and @kbd{C-x [} (@code{backward-page})
commands to move forward and backward by chapter, and to use the
@kbd{C-x p} (@code{narrow-to-page}) command to narrow to a chapter.
-@xref{Pages, , , xemacs, XEmacs User's Manual}, for more information
+@xref{Pages, , , emacs, The GNU Emacs Manual}, for more information
about the page commands.@refill
@node Updating Nodes and Menus, Info Formatting, Showing the Structure, Texinfo Mode
@subheading The Updating Commands
@end ifinfo
-You can use the updating commands@refill
+You can use the updating commands to:@refill
@itemize @bullet
@item
-to insert or update the `Next', `Previous', and `Up' pointers of a
+insert or update the `Next', `Previous', and `Up' pointers of a
node,@refill
@item
-to insert or update the menu for a section, and@refill
+insert or update the menu for a section, and@refill
@item
-to create a master menu for a Texinfo source file.@refill
+create a master menu for a Texinfo source file.@refill
@end itemize
You can also use the commands to update all the nodes and menus in a
Commands which work on a whole buffer require that the `Top' node be
followed by a node with an @code{@@chapter} or equivalent-level command.
-Note that the menu updating commands will not create a main or master
-menu for a Texinfo file that has only @code{@@chapter}-level nodes! The
-menu updating commands only create menus @emph{within} nodes for lower level
+The menu updating commands will not create a main or master menu for a
+Texinfo file that has only @code{@@chapter}-level nodes! The menu
+updating commands only create menus @emph{within} nodes for lower level
nodes. To create a menu of chapters, you must provide a `Top'
-node.@refill
+node.
The menu updating commands remove menu entries that refer to other Info
files since they do not refer to nodes within the current buffer. This
@end table
The other major updating commands do smaller jobs and are designed for
-the person who updates nodes and menus as he or she writes a Texinfo
+the person who updates nodes and menus as he or she writes a Texinfo
file.@refill
@need 1000
column to which menu descriptions are indented. By default, the value
is 32 although it is often useful to reduce it to as low as 24. You
can set the variable with the @kbd{M-x edit-options} command
-(@pxref{Edit Options, , Editing Variable Values, xemacs, XEmacs User's
-Manual}) or with the @kbd{M-x set-variable} command (@pxref{Examining, ,
-Examining and Setting Variables, xemacs, XEmacs User's Manual}).@refill
+(@pxref{Edit Options, , Editing Variable Values, emacs, The GNU Emacs
+Manual}) or with the @kbd{M-x set-variable} command (@pxref{Examining,
+, Examining and Setting Variables, emacs, The GNU Emacs
+Manual}).@refill
Also, the @code{texinfo-indent-menu-description} command may be used to
indent existing menu descriptions to a specified column. Finally, if
section. The next node is called `Minimum' and the previous node is
called `Conventions'. The `Comments' section is within the `Overview'
node, which is specified by the `Up' pointer. (Instead of an
-@code{@@comment} line, you can write an @code{@@ifinfo} line.)@refill
+@code{@@comment} line, you may also write an @code{@@ifinfo} line.)@refill
If a file has a `Top' node, it must be called @samp{top} or @samp{Top}
and be the first node in the file.@refill
a menu of subsections within a section, and so on. This means that
you must have a `Top' node if you want a menu of chapters.@refill
-Incidentally, the @code{makeinfo} command will create an Info file for
-a hierarchically organized Texinfo file that lacks `Next', `Previous'
-and `Up' pointers. Thus, if you can be sure that your Texinfo file
-will be formatted with @code{makeinfo}, you have no need for the
-`update node' commands. (@xref{Create an Info File, , Creating an
-Info File}, for more information about @code{makeinfo}.) However,
-both @code{makeinfo} and the @code{texinfo-format-@dots{}} commands
-require that you insert menus in the file.@refill
+Incidentally, the @code{makeinfo} command will create an Info file for a
+hierarchically organized Texinfo file that lacks `Next', `Previous' and
+`Up' pointers. Thus, if you can be sure that your Texinfo file will be
+formatted with @code{makeinfo}, you have no need for the update node
+commands. (@xref{Creating an Info File}, for more information about
+@code{makeinfo}.) However, both @code{makeinfo} and the
+@code{texinfo-format-@dots{}} commands require that you insert menus in
+the file.
@node Other Updating Commands, , Updating Requirements, Updating Nodes and Menus
@comment node-name, next, previous, up
C-x h C-u M-x texinfo-insert-node-lines
@end example
-(Note that this command inserts titles as node names in @code{@@node}
-lines; the @code{texinfo-start-menu-description} command
-(@pxref{Inserting, Inserting Frequently Used Commands}) inserts titles
-as descriptions in menu entries, a different action. However, in both
-cases, you need to edit the inserted text.)@refill
+This command inserts titles as node names in @code{@@node} lines; the
+@code{texinfo-start-menu-description} command (@pxref{Inserting,
+Inserting Frequently Used Commands}) inserts titles as descriptions in
+menu entries, a different action. However, in both cases, you need to
+edit the inserted text.
@item M-x texinfo-multiple-files-update
@findex texinfo-multiple-files-update @r{(in brief)}
For @TeX{} or the Info formatting commands to work, the file @emph{must}
include a line that has @code{@@setfilename} in its header.@refill
-@xref{Create an Info File}, for details about Info formatting.@refill
+@xref{Creating an Info File}, for details about Info formatting.@refill
@node Printing, Texinfo Mode Summary, Info Formatting, Texinfo Mode
@comment node-name, next, previous, up
surround the @code{@@settitle} line with start-of-header and
end-of-header lines.)@refill
-@xref{Format/Print Hardcopy}, for a description of the other @TeX{} related
+@xref{Hardcopy}, for a description of the other @TeX{} related
commands, such as @code{tex-show-print-queue}.@refill
@node Texinfo Mode Summary, , Printing, Texinfo Mode
The @code{texinfo-master-menu} command creates a master menu; and can
be used to update every node and menu in a file as well.@refill
+@c Probably should use @tables in this section.
@example
@group
C-c C-u m
@subheading Other Updating Commands
-The `other updating commands' do not have standard keybindings because
+The remaining updating commands do not have standard keybindings because
they are rarely used.
@example
* setfilename:: Tell Info the name of the Info file.
* settitle:: Create a title for the printed work.
* setchapternewpage:: Start chapters on right-hand pages.
-* paragraphindent:: An option to specify paragraph indentation.
+* paragraphindent:: Specify paragraph indentation.
+* exampleindent:: Specify environment indentation.
* End of Header:: Formatting a region requires this.
@end menu
-@node First Line, Start of Header, Header, Header
-@comment node-name, next, previous, up
+
+@node First Line
@subsection The First Line of a Texinfo File
@cindex First line of a Texinfo file
@cindex Beginning line of a Texinfo file
The odd string of characters, @samp{%**}, is to ensure that no other
comment is accidentally taken for a start-of-header line.@refill
-@node setfilename, settitle, Start of Header, Header
-@comment node-name, next, previous, up
+@node setfilename
@subsection @code{@@setfilename}
@cindex Info file requires @code{@@setfilename}
@findex setfilename
part of the file name, including what would otherwise be a
comment.
-The @code{@@setfilename} line specifies the name of the Info file to be
-generated. This name should be different from the name of the Texinfo
-file. There are two conventions for choosing the name: you can either
-remove the @samp{.texi} extension from the input file name, or replace
-it with the @samp{.info} extension.
+The @code{@@setfilename} line specifies the name of the output file to
+be generated. This name should be different from the name of the
+Texinfo file. There are two conventions for choosing the name: you can
+either remove the extension (such as @samp{.texi}) from the input file
+name, or replace it with the @samp{.info} extension. When producing
+HTML output, @code{makeinfo} will replace any extension with
+@samp{html}, or add @samp{.html} if the given name has no extension.
Some operating systems cannot handle long file names. You can run into
a problem even when the file name you specify is itself short enough.
file name. (@xref{Tag and Split Files, , Tag Files and Split Files}.)
The subfile name @file{texinfo.info-10}, for example, is too long for
some systems; so the Info file name for this document is @file{texinfo}
-rather than @file{texinfo.info}.
+rather than @file{texinfo.info}. When @code{makeinfo} is running on
+operating systems such as MS-DOS which impose grave limits on file
+names, it will sometimes remove some characters from the original file
+name to leave enough space for the subfile suffix, thus producing files
+named @file{texin-10}, @file{gcc.i12}, etc.
@cindex Ignored before @code{@@setfilename}
+@cindex @samp{\input} source line ignored
The Info formatting commands ignore everything written before the
@code{@@setfilename} line, which is why the very first line of
the file (the @code{\input} line) does not show up in the output.
@pindex texinfo.cnf
The @code{@@setfilename} line produces no output when you typeset a
-manual with @TeX{}, but it nevertheless is essential: it opens the
+manual with @TeX{}, but it is nevertheless essential: it opens the
index, cross-reference, and other auxiliary files used by Texinfo, and
also reads @file{texinfo.cnf} if that file is present on your system
-(@pxref{Preparing for TeX,, Preparing to Use @TeX{}}).
+(@pxref{Preparing for TeX,, Preparing for @TeX{}}).
@node settitle, setchapternewpage, setfilename, Header
footings. @xref{Headings, , Page Headings}, for a detailed discussion
of this process.@refill
-@node setchapternewpage, paragraphindent, settitle, Header
-@comment node-name, next, previous, up
+
+@node setchapternewpage
@subsection @code{@@setchapternewpage}
@cindex Starting chapters
@cindex Pages, starting odd
@findex setchapternewpage
-In a book or a manual, text is usually printed on both sides of the
-paper, chapters start on right-hand pages, and right-hand pages have
+In an officially bound book, text is usually printed on both sides of
+the paper, chapters start on right-hand pages, and right-hand pages have
odd numbers. But in short reports, text often is printed only on one
side of the paper. Also in short reports, chapters sometimes do not
start on new pages, but are printed on the same page as the end of the
You can use the @code{@@setchapternewpage} command with various
arguments to specify how @TeX{} should start chapters and whether it
-should typeset pages for printing on one or both sides of the paper
+should format headers for printing on one or both sides of the paper
(single-sided or double-sided printing).@refill
Write the @code{@@setchapternewpage} command at the beginning of a
@code{@@setchapternewpage} command:@refill
@table @asis
-@ignore
-@item No @code{@@setchapternewpage} command
-If the Texinfo file does not contain an @code{@@setchapternewpage}
-command before the @code{@@titlepage} command, @TeX{} automatically
-begins chapters on new pages and prints headings in the standard
-format for single-sided printing. This is the conventional format for
-single-sided printing.@refill
-The result is exactly the same as when you write
-@code{@@setchapternewpage on}.@refill
-@end ignore
@item @code{@@setchapternewpage off}
Cause @TeX{} to typeset a new chapter on the same page as the last
chapter, after skipping some vertical whitespace. Also, cause @TeX{} to
@ref{headings on off, , The @code{@@headings} Command}.)@refill
@item @code{@@setchapternewpage on}
-Cause @TeX{} to start new chapters on new pages and to typeset page
+Cause @TeX{} to start new chapters on new pages and to format page
headers for single-sided printing. This is the form most often
-used for short reports.@refill
+used for short reports or personal printing.
This alternative is the default.@refill
the form most often used for books and manuals.@refill
@end table
-@noindent
Texinfo does not have an @code{@@setchapternewpage even} command.@refill
-@noindent
-(You can countermand or modify an @code{@@setchapternewpage} command
-with an @code{@@headings} command. @xref{headings on off, , The
-@code{@@headings} Command}.)@refill
+You can countermand or modify the effect on headers of an
+@code{@@setchapternewpage} command with an @code{@@headings} command.
+@xref{headings on off, , The @code{@@headings} Command}.@refill
At the beginning of a manual or book, pages are not numbered---for
example, the title and copyright pages of a book are not numbered.
Since an Info file does not have pages, the @code{@@setchapternewpage}
command has no effect on it.@refill
-Usually, you do not write an @code{@@setchapternewpage} command for
-single-sided printing, but accept the default which is to typeset for
-single-sided printing and to start new chapters on new pages. Usually,
-you write an @code{@@setchapternewpage odd} command for double-sided
-printing.@refill
+We recommend not including any @code{@@setchapternewpage} command in
+your manual sources at all, since the desired output is not intrinsic to
+the document. Instead, if you don't want the default option (no blank
+pages, same headers on all pages) use the @option{--texinfo} option to
+@command{texi2dvi} to specify the output you want.
-@node paragraphindent, End of Header, setchapternewpage, Header
-@comment node-name, next, previous, up
+
+
+@node paragraphindent
@subsection Paragraph Indenting
@cindex Indenting paragraphs
@cindex Paragraph indentation
@findex paragraphindent
-The Info formatting commands may insert spaces at the beginning of the
-first line of each paragraph, thereby indenting that paragraph. You
-can use the @code{@@paragraphindent} command to specify the
-indentation. Write an @code{@@paragraphindent} command at the
-beginning of a line followed by either @samp{asis} or a number. The
-template is:@refill
+The Texinfo processors may insert whitespace at the beginning of the
+first line of each paragraph, thereby indenting that paragraph. You can
+use the @code{@@paragraphindent} command to specify this indentation.
+Write an @code{@@paragraphindent} command at the beginning of a line
+followed by either @samp{asis} or a number:
@example
@@paragraphindent @var{indent}
@end example
-The Info formatting commands indent according to the value of
-@var{indent}:@refill
+The indentation is according to the value of @var{indent}:
-@itemize @bullet
-@item
-If the value of @var{indent} is @samp{asis}, the Info formatting
-commands do not change the existing indentation.@refill
+@table @asis
+@item @code{asis}
+Do not change the existing indentation (not implemented in @TeX{}).
-@item
-If the value of @var{indent} is zero, the Info formatting commands delete
-existing indentation.@refill
+@item 0
+Omit all indentation.
-@item
-If the value of @var{indent} is greater than zero, the Info formatting
-commands indent the paragraph by that number of spaces.@refill
-@end itemize
+@item @var{n}
+Indent by @var{n} space characters in Info output, by @var{n} ems in
+@TeX{}.
+
+@end table
-The default value of @var{indent} is @samp{asis}.@refill
+The default value of @var{indent} is @samp{asis}.
+@code{@@paragraphindent} is ignored for HTML output.
Write the @code{@@paragraphindent} command before or shortly after the
end-of-header line at the beginning of a Texinfo file. (If you write
the command between the start-of-header and end-of-header lines, the
-region formatting commands indent paragraphs as specified.)@refill
+region formatting commands indent paragraphs as specified.)
A peculiarity of the @code{texinfo-format-buffer} and
@code{texinfo-format-region} commands is that they do not indent (nor
fill) paragraphs that contain @code{@@w} or @code{@@*} commands.
-@xref{Refilling Paragraphs}, for a detailed description of what goes
-on.@refill
+@xref{Refilling Paragraphs}, for further information.
-@node End of Header, , paragraphindent, Header
-@comment node-name, next, previous, up
+
+@node exampleindent
+@subsection @code{@@exampleindent}: Environment Indenting
+@cindex Indenting environments
+@cindex Environment indentation
+@cindex Example indentation
+@findex exampleindent
+
+The Texinfo processors indent each line of @code{@@example} and similar
+environments. You can use the @code{@@exampleindent} command to specify
+this indentation. Write an @code{@@exampleindent} command at the
+beginning of a line followed by either @samp{asis} or a number:
+
+@example
+@@exampleindent @var{indent}
+@end example
+
+The indentation is according to the value of @var{indent}:
+
+@table @asis
+@item @code{asis}
+Do not change the existing indentation (not implemented in @TeX{}).
+
+@item 0
+Omit all indentation.
+
+@item @var{n}
+Indent environments by @var{n} space characters in Info output, by
+@var{n} ems in @TeX{}.
+
+@end table
+
+The default value of @var{indent} is 5. @code{@@exampleindent} is
+ignored for HTML output.
+
+Write the @code{@@exampleindent} command before or shortly after the
+end-of-header line at the beginning of a Texinfo file. (If you write
+the command between the start-of-header and end-of-header lines, the
+region formatting commands indent examples as specified.)
+
+
+@node End of Header
@subsection End of Header
@cindex End of header line
@xref{Start of Header}.
@end iftex
-@node Info Summary and Permissions, Titlepage & Copyright Page, Header, Beginning a File
-@comment node-name, next, previous, up
+
+@node Info Summary and Permissions
@section Summary and Copying Permissions for Info
The title page and the copyright page appear only in the printed copy of
reading the file using Info, except when using the advanced Info command
@kbd{g *}.
-@node Titlepage & Copyright Page, The Top Node, Info Summary and Permissions, Beginning a File
-@comment node-name, next, previous, up
+
+@node Titlepage & Copyright Page
@section The Title and Copyright Pages
A manual's name and author are usually printed on a title page.
In addition, this part of the beginning of a Texinfo file contains the text
of the copying permissions that will appear in the printed manual.@refill
+@cindex Titlepage, for plain text
+You may wish to include titlepage-like information for plain text
+output. Simply place any such leading material between @code{@@ifinfo}
+and @code{@@end ifinfo}; @command{makeinfo} includes this in its plain
+text output. It will not show up in the Info readers.
+
@xref{Titlepage Permissions, , Titlepage Copying Permissions}, for the
standard text for the copyright permissions.@refill
and double or single sided printing.
@end menu
+
@node titlepage, titlefont center sp, Titlepage & Copyright Page, Titlepage & Copyright Page
@comment node-name, next, previous, up
@subsection @code{@@titlepage}
The @code{@@end titlepage} command starts a new page and turns on page
numbering. (@xref{Headings, , Page Headings}, for details about how to
-generate page headings.) All the material that you want to
-appear on unnumbered pages should be put between the
-@code{@@titlepage} and @code{@@end titlepage} commands. By using the
-@code{@@page} command you can force a page break within the region
-delineated by the @code{@@titlepage} and @code{@@end titlepage}
-commands and thereby create more than one unnumbered page. This is
-how the copyright page is produced. (The @code{@@titlepage} command
-might perhaps have been better named the
-@code{@@titleandadditionalpages} command, but that would have been
-rather long!)@refill
-
-@c !!! append refill to footnote when makeinfo can handle it.
+generate page headings.) All the material that you want to appear on
+unnumbered pages should be put between the @code{@@titlepage} and
+@code{@@end titlepage} commands. You can force the table of contents to
+appear there with the @code{@@setcontentsaftertitlepage} command
+(@pxref{Contents}).
+
+@findex page@r{, within @code{@@titlepage}}
+By using the @code{@@page} command you can force a page break within the
+region delineated by the @code{@@titlepage} and @code{@@end titlepage}
+commands and thereby create more than one unnumbered page. This is how
+the copyright page is produced. (The @code{@@titlepage} command might
+perhaps have been better named the @code{@@titleandadditionalpages}
+command, but that would have been rather long!)
+
When you write a manual about a computer program, you should write the
-version of the program to which the manual applies on the title
-page. If the manual changes more frequently than the program or is
-independent of it, you should also include an edition
-number@footnote{We have found that it is helpful to refer to versions
-of manuals as `editions' and versions of programs as `versions';
-otherwise, we find we are liable to confuse each other in conversation
-by referring to both the documentation and the software with the same
-words.} for the manual. This helps readers keep track of which manual
-is for which version of the program. (The `Top' node
-should also contain this information; see @ref{makeinfo top, ,
-@code{@@top}}.)@refill
+version of the program to which the manual applies on the title page.
+If the manual changes more frequently than the program or is independent
+of it, you should also include an edition number@footnote{We have found
+that it is helpful to refer to versions of manuals as `editions' and
+versions of programs as `versions'; otherwise, we find we are liable to
+confuse each other in conversation by referring to both the
+documentation and the software with the same words.} for the manual.
+This helps readers keep track of which manual is for which version of
+the program. (The `Top' node should also contain this information; see
+@ref{makeinfo top, , @code{@@top}}.)
Texinfo provides two main methods for creating a title page. One method
uses the @code{@@titlefont}, @code{@@sp}, and @code{@@center} commands
to generate a title page in which the words on the page are
-centered.@refill
+centered.
The second method uses the @code{@@title}, @code{@@subtitle}, and
@code{@@author} commands to create a title page with black rules under
the title and author lines and the subtitle text set flush to the
right hand side of the page. With this method, you do not specify any
of the actual formatting of the title page. You specify the text
-you want, and Texinfo does the formatting. You may use either
-method.@refill
+you want, and Texinfo does the formatting.
+
+You may use either method, or you may combine them; see the examples in
+the sections below.
@findex shorttitlepage
-For extremely simple applications, Texinfo also provides a command
-@code{@@shorttitlepage} which takes a single argument as the title.
-The argument is typeset on a page by itself and followed by a blank
-page.
+@cindex Bastard title page
+@cindex Title page, bastard
+For extremely simple applications, and for the bastard title page in
+traditional book front matter, Texinfo also provides a command
+@code{@@shorttitlepage} which takes a single argument as the title. The
+argument is typeset on a page by itself and followed by a blank page.
-@node titlefont center sp, title subtitle author, titlepage, Titlepage & Copyright Page
-@comment node-name, next, previous, up
+@node titlefont center sp
@subsection @code{@@titlefont}, @code{@@center}, and @code{@@sp}
@findex titlefont
@findex center
first of the two methods for creating a title page in Texinfo.)@refill
Use the @code{@@titlefont} command to select a large font suitable for
-the title itself.@refill
+the title itself. You can use @code{@@titlefont} more than once if you
+have an especially long title.
@need 700
For example:
@end group
@end example
-The spacing of the example fits an 8 1/2 by 11 inch manual.@refill
+The spacing of the example fits an 8.5 by 11 inch manual.@refill
-@node title subtitle author, Copyright & Permissions, titlefont center sp, Titlepage & Copyright Page
-@comment node-name, next, previous, up
+
+@node title subtitle author
@subsection @code{@@title}, @code{@@subtitle}, and @code{@@author}
@findex title
@findex subtitle
You can use the @code{@@title}, @code{@@subtitle}, and @code{@@author}
commands to create a title page in which the vertical and horizontal
spacing is done for you automatically. This contrasts with the method
-described in
-the previous section, in which the @code{@@sp} command is needed to
-adjust vertical spacing.@refill
+described in the previous section, in which the @code{@@sp} command is
+needed to adjust vertical spacing.
Write the @code{@@title}, @code{@@subtitle}, or @code{@@author}
commands at the beginning of a line followed by the title, subtitle,
The @code{@@title} command produces a line in which the title is set
flush to the left-hand side of the page in a larger than normal font.
-The title is underlined with a black rule.@refill
+The title is underlined with a black rule. Only a single line is
+allowed; the @code{@@*} command may not be used to break the title into
+two lines. To handle very long titles, you may find it profitable to
+use both @code{@@title} and @code{@@titlefont}; see the final example in
+this section.
The @code{@@subtitle} command sets subtitles in a normal-sized font
flush to the right-hand side of the page.@refill
@end group
@end example
-@ifinfo
-@noindent
-Contrast this form with the form of a title page written using the
-@code{@@sp}, @code{@@center}, and @code{@@titlefont} commands:@refill
+You may also combine the @code{@@titlefont} method described in the
+previous section and @code{@@title} method described in this one. This
+may be useful if you have a very long title. Here is a real-life example:
@example
+@group
@@titlepage
-@@sp 10
-@@center @@titlefont@{Name of Manual When Printed@}
-@@sp 2
-@@center Subtitle, If Any
+@@titlefont@{GNU Software@}
@@sp 1
-@@center Second subtitle
-@@sp 2
-@@center Author
-@@page
-@dots{}
-@@end titlepage
+@@title for MS-Windows and MS-DOS
+@@subtitle Edition @@value@{edition@} for Release @@value@{cd-edition@}
+@@author by Daniel Hagerty, Melissa Weisshaus
+@@author and Eli Zaretskii
+@end group
@end example
-@end ifinfo
-@node Copyright & Permissions, end titlepage, title subtitle author, Titlepage & Copyright Page
-@comment node-name, next, previous, up
+@noindent
+(The use of @code{@@value} here is explained in @ref{value
+Example,,@code{@@value} Example}.)
+
+
+@node Copyright & Permissions
@subsection Copyright Page and Permissions
@cindex Copyright page
@cindex Printed permissions
@end example
It is customary to put information on how to get a manual after the
-copyright notice, followed by the copying permissions for the
-manual.@refill
+copyright notice, followed by the copying permissions for the manual.
-Note that permissions must be given here as well as in the summary
-segment within @code{@@ifinfo} and @code{@@end ifinfo} that
-immediately follows the header since this text appears only in the
-printed manual and the @samp{ifinfo} text appears only in the Info
-file.@refill
+Permissions must be given here as well as in the summary segment within
+@code{@@ifinfo} and @code{@@end ifinfo} that immediately follows the
+header since this text appears only in the printed manual and the
+@samp{ifinfo} text appears only in the Info file.
@xref{Sample Permissions}, for the standard text.@refill
-@node end titlepage, headings on off, Copyright & Permissions, Titlepage & Copyright Page
-@comment node-name, next, previous, up
+
+@node end titlepage
@subsection Heading Generation
@findex end titlepage
@cindex Headings, page, begin to appear
@refill
@item @@headings double
+@itemx @@headings on
Turn on page headings appropriate for double-sided printing. The two
commands, @code{@@headings on} and @code{@@headings double}, are
synonymous.@refill
You can also specify your own style of page heading and footing.
@xref{Headings, , Page Headings}, for more information.@refill
-@node The Top Node, Software Copying Permissions, Titlepage & Copyright Page, Beginning a File
-@comment node-name, next, previous, up
+
+@node The Top Node
@section The `Top' Node and Master Menu
@cindex @samp{@r{Top}} node
@cindex Master menu
* Master Menu Parts:: A master menu has three or more parts.
@end menu
-@node Title of Top Node, Master Menu Parts, The Top Node, The Top Node
-@ifinfo
-@subheading `Top' Node Title
-@end ifinfo
+
+@node Title of Top Node
+@subsection `Top' Node Title
Sometimes, you will want to place an @code{@@top} sectioning command
line containing the title of the document immediately after the
@dots{}
@@end titlepage
-@@ifinfo
+@@ifnottex
@@node Top, Copying, , (dir)
@@top Texinfo
@group
This is edition@dots{}
@dots{}
-@@end ifinfo
+@@end ifnottex
@end group
@group
@cindex File ending
@findex bye
-The end of a Texinfo file should include the commands that create
-indices and generate detailed and summary tables of contents.
-And it must include the @code{@@bye} command that marks the last line
-processed by @TeX{}.@refill
+The end of a Texinfo file should include commands to create indices and
+(usually) to generate detailed and summary tables of contents. And it
+must include the @code{@@bye} command that marks the last line processed
+by @TeX{}.@refill
@need 700
For example:
@code{@@printindex} command at the place in the document where you
want the index to appear. Also, as part of the process of creating a
printed manual, you must run a program called @code{texindex}
-(@pxref{Format/Print Hardcopy}) to sort the raw data to produce a sorted
+(@pxref{Hardcopy}) to sort the raw data to produce a sorted
index file. The sorted index file is what is actually used to
print the index.@refill
@@printindex cp
@end group
-
-@group
-@@summarycontents
-@@contents
-@@bye
-@end group
@end smallexample
@noindent
-(Readers often prefer that the concept index come last in a book,
-since that makes it easiest to find.)@refill
+Readers often prefer that the concept index come last in a book,
+since that makes it easiest to find. Having just one index helps
+readers also, since then they have only one place to look
+(@pxref{synindex}).
-@ignore
-@c TeX can do sorting, just not conveniently enough to handle sorting
-@c Texinfo indexes. --karl, 5may97.
-In @TeX{}, the @code{@@printindex} command needs a sorted index file
-to work from. @TeX{} does not know how to do sorting; this is a
-deficiency. @TeX{} writes output files of raw index data; use the
-@code{texindex} program to convert these files to sorted index files.
-(@xref{Format/Print Hardcopy}, for more information.)@refill
-@end ignore
-
-@node Contents, File End, Printing Indices & Menus, Ending a File
-@comment node-name, next, previous, up
+@node Contents
@section Generating a Table of Contents
@cindex Table of contents
@cindex Contents, Table of
+@cindex Short table of contents
@findex contents
@findex summarycontents
@findex shortcontents
The @code{@@chapter}, @code{@@section}, and other structuring commands
supply the information to make up a table of contents, but they do not
-cause an actual table to appear in the manual. To do this, you must
-use the @code{@@contents} and @code{@@summarycontents}
-commands:@refill
+cause an actual table to appear in the manual. To do this, you must use
+the @code{@@contents} and/or @code{@@summarycontents} command(s).
@table @code
@item @@contents
Generate a table of contents in a printed manual, including all
chapters, sections, subsections, etc., as well as appendices and
unnumbered chapters. (Headings generated by the @code{@@heading}
-series of commands do not appear in the table of contents.) The
-@code{@@contents} command should be written on a line by
-itself.@refill
+series of commands do not appear in the table of contents.)
@item @@shortcontents
@itemx @@summarycontents
and subsubsections. Only a long manual needs a short table
of contents in addition to the full table of contents.@refill
-Write the @code{@@shortcontents} command on a line by itself right
-@emph{before} the @code{@@contents} command.@refill
@end table
-The table of contents commands automatically generate a chapter-like
-heading at the top of the first table of contents page. Write the table
-of contents commands at the very end of a Texinfo file, just before the
-@code{@@bye} command, following any index sections---anything in the
-Texinfo file after the table of contents commands will be omitted from
-the table of contents.@refill
-
-When you print a manual with a table of contents, the table of
-contents are printed last and numbered with roman numerals. You need
-to place those pages in their proper place, after the title page,
-yourself. (This is the only collating you need to do for a printed
-manual. The table of contents is printed last because it is generated
-after the rest of the manual is typeset.)@refill
-
-@need 700
-Here is an example of where to write table of contents commands:@refill
-
-@example
-@group
-@var{indices}@dots{}
-@@shortcontents
-@@contents
-@@bye
-@end group
-@end example
+Both contents commands should be written on a line by themselves.
+The contents commands automatically generate a chapter-like heading at
+the top of the first table of contents page, so don't include any
+sectioning command such as @code{@@unnumbered} before them.
Since an Info file uses menus instead of tables of contents, the Info
-formatting commands ignore the @code{@@contents} and
-@code{@@shortcontents} commands.@refill
-
-@node File End, , Contents, Ending a File
-@comment node-name, next, previous, up
+formatting commands ignore the contents commands. But the contents are
+included in plain text output (generated by @code{makeinfo --no-headers}).
+
+The contents commands can be placed either at the very end of the file,
+after any indices (see the previous section) and just before the
+@code{@@bye} (see the next section), or near the beginning of the file,
+after the @code{@@end titlepage} (@pxref{titlepage}). The advantage to
+the former is that then the contents output is always up to date,
+because it reflects the processing just done. The advantage to the
+latter is that the contents are printed in the proper place, thus you do
+not need to rearrange the DVI file with @command{dviselect} or shuffle
+paper. However, contents commands at the beginning of the document are
+ignored when outputting to standard output.
+
+@findex setcontentsaftertitlepage
+@findex setshortcontentsaftertitlepage
+@cindex Contents, after title page
+@cindex Table of contents, after title page
+As an author, you can put the contents commands wherever you prefer.
+But if you are a user simply printing a manual, you may wish to print
+the contents after the title page even if the author put the contents
+commands at the end of the document (as is the case in most existing
+Texinfo documents). You can do this by specifying
+@code{@@setcontentsaftertitlepage} and/or
+@code{@@setshortcontentsaftertitlepage}. The first prints only the main
+contents after the @code{@@end titlepage}; the second prints both the
+short contents and the main contents. In either case, any subsequent
+@code{@@contents} or @code{@@shortcontents} is ignored (unless no
+@code{@@end titlepage} is ever encountered).
+
+You need to include the @code{@@set@dots{}contentsaftertitlepage}
+commands early in the document (just after @code{@@setfilename}, for
+example). Or, if you're using @command{texi2dvi} (@pxref{Format with
+texi2dvi}), you can use its @option{--texinfo} option to specify this
+without altering the source file at all. For example:
+@example
+texi2dvi --texinfo=@@setshortcontentsaftertitlepage foo.texi
+@end example
+
+
+@node File End
@section @code{@@bye} File Ending
@findex bye
with a local variables list. @xref{Compile-Command, , Using Local
Variables and the Compile Command}, for more information.@refill
-@node Structuring, Nodes, Ending a File, Top
-@comment node-name, next, previous, up
+
+@node Structuring
@chapter Chapter Structuring
@cindex Chapter structuring
@cindex Structuring of chapters
* Raise/lower sections:: How to change commands' hierarchical level.
@end menu
-@node Tree Structuring, Structuring Command Types, Structuring, Structuring
-@comment node-name, next, previous, up
+
+@node Tree Structuring
@section Tree Structure of Sections
@cindex Tree structuring
follow; the @code{@@node} and @code{@@menu} commands are described in
following chapters. (@xref{Nodes}, and see @ref{Menus}.)@refill
-@node Structuring Command Types, makeinfo top, Tree Structuring, Structuring
-@comment node-name, next, previous, up
-@section Types of Structuring Commands
+
+@node Structuring Command Types
+@section Structuring Command Types
The chapter structuring commands fall into four groups or series, each
of which contains structuring commands corresponding to the
do not.@refill
@end itemize
-@need 1000
Here are the four groups of chapter structuring commands:@refill
-@c Slightly different formatting for regular sized books and smallbooks.
-@ifset smallbook
-@sp 1
-@tex
-{\let\rm=\indrm \let\tt=\indtt
-\halign{\hskip\itemindent#\hfil& \hskip.5em#\hfil& \hskip.5em#\hfil&
-\hskip.5em#\hfil\cr
-
-& & & \rm No new pages\cr
-\rm Numbered& \rm Unnumbered& \rm Lettered and numbered& \rm Unnumbered\cr
-\rm In contents& \rm In contents& \rm In contents& \rm Not in contents\cr
-
-& & & \cr
- & \tt @@top& & \tt @@majorheading\cr
-\tt @@chapter& \tt @@unnumbered& \tt @@appendix& \tt @@chapheading\cr
-\tt @@section& \tt @@unnumberedsec& \tt @@appendixsec& \tt @@heading\cr
-\tt @@subsection&\tt @@unnumberedsubsec&\tt @@appendixsubsec&
-\tt @@subheading\cr
-\tt @@subsubsection& \tt @@unnumberedsubsubsec& \tt @@appendixsubsubsec&
-\tt @@subsubheading\cr}}
-@end tex
-@end ifset
-@ifclear smallbook
-@sp 1
-@tex
-\vbox{
-\halign{\hskip\itemindent\hskip.5em#\hfil& \hskip.5em#\hfil&
-\hskip.5em#\hfil& \hskip.5em #\hfil\cr
-
-& & & \cr
-& & & \rm No new pages\cr
-\rm Numbered& \rm Unnumbered& \rm Lettered and numbered& \rm Unnumbered\cr
-\rm In contents& \rm In contents& \rm In contents& \rm Not in contents\cr
-
-& & & \cr
- & \tt @@top& & \tt @@majorheading\cr
-\tt @@chapter& \tt @@unnumbered& \tt @@appendix& \tt @@chapheading\cr
-\tt @@section& \tt @@unnumberedsec& \tt @@appendixsec& \tt @@heading\cr
-\tt @@subsection&\tt @@unnumberedsubsec&\tt @@appendixsubsec&
-\tt @@subheading\cr
-\tt @@subsubsection& \tt @@unnumberedsubsubsec& \tt @@appendixsubsubsec&
-\tt @@subsubheading\cr}}
-@end tex
-@end ifclear
-@ifinfo
-@example
-@group
- @r{No new pages}
-@r{Numbered} @r{Unnumbered} @r{Lettered and numbered} @r{Unnumbered}
-@r{In contents} @r{In contents} @r{In contents} @r{Not in contents}
-
- @@top @@majorheading
-@@chapter @@unnumbered @@appendix @@chapheading
-@@section @@unnumberedsec @@appendixsec @@heading
-@@subsection @@unnumberedsubsec @@appendixsubsec @@subheading
-@@subsubsection @@unnumberedsubsubsec @@appendixsubsubsec @@subsubheading
-@end group
-@end example
-@end ifinfo
+@multitable @columnfractions .19 .30 .29 .22
+
+@item @tab @tab @tab No new page
+@item Numbered @tab Unnumbered @tab Lettered and numbered
+ @tab Unnumbered
+@item In contents @tab In contents @tab In contents @tab Not in contents
+@item @tab @code{@@top} @tab
+ @tab @code{@@majorheading}
+@item @code{@@chapter} @tab @code{@@unnumbered} @tab @code{@@appendix}
+ @tab @code{@@chapheading}
+@item @code{@@section} @tab @code{@@unnumberedsec} @tab @code{@@appendixsec}
+ @tab @code{@@heading}
+@item @code{@@subsection} @tab @code{@@unnumberedsubsec} @tab @code{@@appendixsubsec}
+ @tab @code{@@subheading}
+@item @code{@@subsubsection} @tab @code{@@unnumberedsubsubsec} @tab @code{@@appendixsubsubsec}
+ @tab @code{@@subsubheading}
+@end multitable
-@c Cannot line up columns properly inside of an example because of roman
-@c proportional fonts.
-@ignore
-@ifset smallbook
-@iftex
-@smallexample
-@group
- @r{No new pages}
-@r{Numbered} @r{Unnumbered} @r{Lettered and numbered} @r{Unnumbered}
-@r{In contents} @r{In contents} @r{In contents} @r{Not in contents}
-
- @@top @@majorheading
-@@chapter @@unnumbered @@appendix @@chapheading
-@@section @@unnumberedsec @@appendixsec @@heading
-@@subsection @@unnumberedsubsec @@appendixsubsec @@subheading
-@@subsubsection @@unnumberedsubsubsec @@appendixsubsubsec @@subsubheading
-@end group
-@end smallexample
-@end iftex
-@end ifset
-@ifclear smallbook
-@iftex
-@smallexample
-@group
- @r{No new pages}
-@r{Numbered} @r{Unnumbered} @r{Lettered and numbered} @r{Unnumbered}
-@r{In contents} @r{In contents} @r{In contents} @r{Not in contents}
-
- @@top @@majorheading
-@@chapter @@unnumbered @@appendix @@chapheading
-@@section @@unnumberedsec @@appendixsec @@heading
-@@subsection @@unnumberedsubsec @@appendixsubsec @@subheading
-@@subsubsection @@unnumberedsubsubsec @@appendixsubsubsec @@subsubheading
-@end group
-@end smallexample
-@end iftex
-@end ignore
-@node makeinfo top, chapter, Structuring Command Types, Structuring
-@comment node-name, next, previous, up
+@node makeinfo top
@section @code{@@top}
The @code{@@top} command is a special sectioning command that you use
only after an @samp{@@node Top} line at the beginning of a Texinfo file.
-The @code{@@top} command tells the @code{makeinfo} formatter
-which node is the `Top'
-node. It has the same typesetting effect as @code{@@unnumbered}
-(@pxref{unnumbered & appendix, , @code{@@unnumbered}, @code{@@appendix}}).
-For detailed information, see
-@ref{makeinfo top command, , The @code{@@top} Command}.@refill
+The @code{@@top} command tells the @code{makeinfo} formatter which node
+is the `Top' node, so it can use it as the root of the node tree if your
+manual uses implicit pointers. It has the same typesetting effect as
+@code{@@unnumbered} (@pxref{unnumbered & appendix, , @code{@@unnumbered}
+and @code{@@appendix}}). For detailed information, see @ref{makeinfo
+top command, , The @code{@@top} Command}.
+
+The @code{@@top} node and its menu (if any) is conventionally wrapped in
+an @code{@@ifnottex} conditional so that it will appear only in Info and
+HTML output, not @TeX{}.
+
@node chapter, unnumbered & appendix, makeinfo top, Structuring
@comment node-name, next, previous, up
@c but the Hacker's Dictionary wanted it ...
-@node unnumbered & appendix, majorheading & chapheading, chapter, Structuring
-@comment node-name, next, previous, up
-@section @code{@@unnumbered}, @code{@@appendix}
+@node unnumbered & appendix
+@section @code{@@unnumbered} and @code{@@appendix}
@findex unnumbered
@findex appendix
attempt to lower below `subsubsections' reproduces subsubsection
commands.
-@node Nodes, Menus, Structuring, Top
-@comment node-name, next, previous, up
+@node Nodes
@chapter Nodes
@dfn{Nodes} are the primary segments of a Texinfo file. They do not
-themselves impose a hierarchic or any other kind of structure on a file.
+themselves impose a hierarchical or any other kind of structure on a file.
Nodes contain @dfn{node pointers} that name other nodes, and can contain
@dfn{menus} which are lists of nodes. In Info, the movement commands
can carry you to a pointed-to node or to a node listed in a menu. Node
* Two Paths:: Different commands to structure
Info output and printed output.
* Node Menu Illustration:: A diagram, and sample nodes and menus.
-* node:: How to write a node, in detail.
-* makeinfo Pointer Creation:: How to create node pointers with @code{makeinfo}.
+* node:: Creating nodes, in detail.
+* makeinfo Pointer Creation:: Letting makeinfo determine node pointers.
+* anchor:: Defining arbitrary cross-reference targets.
@end menu
-@node Two Paths, Node Menu Illustration, Nodes, Nodes
-@ifinfo
-@heading Two Paths
-@end ifinfo
+
+@node Two Paths
+@section Two Paths
The node and menu commands and the chapter structuring commands are
-independent of each other:
+technically independent of each other:
@itemize @bullet
@item
You can use node pointers and menus to structure an Info file any way
you want; and you can write a Texinfo file so that its Info output has a
-different structure than its printed output. However, most Texinfo
-files are written such that the structure for the Info output
-corresponds to the structure for the printed output. It is not
-convenient to do otherwise.@refill
+different structure than its printed output. However, virtually all
+Texinfo files are written such that the structure for the Info output
+corresponds to the structure for the printed output. It is neither
+convenient nor understandable to the reader to do otherwise.@refill
Generally, printed output is structured in a tree-like hierarchy in
which the chapters are the major limbs from which the sections branch
out. Similarly, node pointers and menus are organized to create a
matching structure in the Info output.@refill
-@node Node Menu Illustration, node, Two Paths, Nodes
-@comment node-name, next, previous, up
+
+@node Node Menu Illustration
@section Node and Menu Illustration
Here is a copy of the diagram shown earlier that illustrates a Texinfo
file with three chapters, each of which contains two sections.@refill
-Note that the ``root'' is at the top of the diagram and the ``leaves''
-are at the bottom. This is how such a diagram is drawn conventionally;
-it illustrates an upside-down tree. For this reason, the root node is
+The ``root'' is at the top of the diagram and the ``leaves'' are at the
+bottom. This is how such a diagram is drawn conventionally; it
+illustrates an upside-down tree. For this reason, the root node is
called the `Top' node, and `Up' node pointers carry you closer to the
root.@refill
| | | | | |
Section Section Section Section Section Section
1.1 1.2 2.1 2.2 3.1 3.2
-
@end group
@end example
-Write the beginning of the node for Chapter 2 like this:@refill
+The fully-written command to start Chapter 2 would be this:
@example
@group
-@@node Chapter 2, Chapter 3, Chapter 1, top
+@@node Chapter 2, Chapter 3, Chapter 1, Top
@@comment node-name, next, previous, up
@end group
@end example
@noindent
-This @code{@@node} line says that the name of this node is ``Chapter 2'', the
-name of the `Next' node is ``Chapter 3'', the name of the `Previous'
-node is ``Chapter 1'', and the name of the `Up' node is ``Top''.
+This @code{@@node} line says that the name of this node is ``Chapter
+2'', the name of the `Next' node is ``Chapter 3'', the name of the
+`Previous' node is ``Chapter 1'', and the name of the `Up' node is
+``Top''. You can omit writing out these node names if your document is
+hierarchically organized (@pxref{makeinfo Pointer Creation}), but the
+pointer relationships still obtain.
@quotation
@strong{Please Note:} `Next' refers to the next node at the same
hierarchical level in the manual, not necessarily to the next node
within the Texinfo file. In the Texinfo file, the subsequent node may
-be at a lower level---a section-level node may follow a chapter-level
-node, and a subsection-level node may follow a section-level node.
-`Next' and `Previous' refer to nodes at the @emph{same} hierarchical
-level. (The `Top' node contains the exception to this rule. Since the
-`Top' node is the only node at that level, `Next' refers to the first
-following node, which is almost always a chapter or chapter-level
-node.)@refill
+be at a lower level---a section-level node most often follows a
+chapter-level node, for example. `Next' and `Previous' refer to nodes
+at the @emph{same} hierarchical level. (The `Top' node contains the
+exception to this rule. Since the `Top' node is the only node at that
+level, `Next' refers to the first following node, which is almost always
+a chapter or chapter-level node.)@refill
@end quotation
To go to Sections 2.1 and 2.2 using Info, you need a menu inside Chapter
@end group
@end example
-@node node, makeinfo Pointer Creation, Node Menu Illustration, Nodes
-@comment node-name, next, previous, up
+
+@node node
@section The @code{@@node} Command
@cindex Node, defined
+@findex node
+
A @dfn{node} is a segment of text that begins at an @code{@@node}
command and continues until the next @code{@@node} command. The
definition of node is different from that for chapter or section. A
subsubsection.@refill
To create a node, write an @code{@@node} command at the beginning of a
-line, and follow it with four arguments, separated by commas, on the
-rest of the same line. These arguments are the name of the node, and
-the names of the `Next', `Previous', and `Up' pointers, in that order.
-You may insert spaces before each pointer if you wish; the spaces are
-ignored. You must write the name of the node, and the names of the
-`Next', `Previous', and `Up' pointers, all on the same line. Otherwise,
+line, and follow it with up to four arguments, separated by commas, on
+the rest of the same line. The first argument is required; it is the
+name of this node. The subsequent arguments are the names of the
+`Next', `Previous', and `Up' pointers, in that order, and may be omitted
+if your Texinfo document is hierarchically organized (@pxref{makeinfo
+Pointer Creation}).
+
+You may insert spaces before each name if you wish; the spaces are
+ignored. You must write the name of the node and the names of the
+`Next', `Previous', and `Up' pointers all on the same line. Otherwise,
the formatters fail. (@inforef{Top, info, info}, for more information
-about nodes in Info.)@refill
+about nodes in Info.)
Usually, you write one of the chapter-structuring command lines
immediately after an @code{@@node} line---for example, an
@code{@@section} or @code{@@subsection} line. (@xref{Structuring
-Command Types, , Types of Structuring Commands}.)@refill
+Command Types}.)
@quotation
@strong{Please note:} The GNU Emacs Texinfo mode updating commands work
references. For this reason, you must write @code{@@node} lines in a
Texinfo file that you intend to format for printing, even if you do not
intend to format it for Info. (Cross references, such as the one at the
-end of this sentence, are made with @code{@@xref} and its related
-commands; see @ref{Cross References}.)@refill
+end of this sentence, are made with @code{@@xref} and related commands;
+see @ref{Cross References}.)@refill
@menu
* Node Names:: How to choose node and pointer names.
* Top Node Summary:: Write a brief description for readers.
@end menu
-@node Node Names, Writing a Node, node, node
-@ifinfo
-@subheading Choosing Node and Pointer Names
-@end ifinfo
+@node Node Names
+@subsection Choosing Node and Pointer Names
+
+@cindex Node names, choosing
The name of a node identifies the node. The pointers enable
you to reach other nodes and consist of the names of those nodes.@refill
`Top' node. @xref{First Node}, for information on how to write the
first node of a Texinfo file.@refill
-@node Writing a Node, Node Line Tips, Node Names, node
-@comment node-name, next, previous, up
+Even when you explicitly specify all pointers, that does not mean you
+can write the nodes in the Texinfo source file in an arbitrary order!
+Because @TeX{} processes the file sequentially, irrespective of node
+pointers, you must write the nodes in the order you wish them to appear
+in the printed output.
+
+
+@node Writing a Node
@subsection How to Write an @code{@@node} Line
@cindex Writing an @code{@@node} line
@cindex @code{@@node} line writing
arguments are for which pointers. This comment line is especially useful
if you are not familiar with Texinfo.@refill
-The template for a node line with `Next', `Previous', and `Up' pointers
-looks like this:@refill
+The template for a fully-written-out node line with `Next', `Previous',
+and `Up' pointers looks like this:@refill
@example
@@node @var{node-name}, @var{next}, @var{previous}, @var{up}
If you wish, you can ignore @code{@@node} lines altogether in your first
draft and then use the @code{texinfo-insert-node-lines} command to
-create @code{@@node} lines for you. However, we do not
-recommend this practice. It is better to name the node itself
-at the same time that you
-write a segment so you can easily make cross references. A large number
-of cross references are an especially important feature of a good Info
-file.@refill
+create @code{@@node} lines for you. However, we do not recommend this
+practice. It is better to name the node itself at the same time that
+you write a segment so you can easily make cross references. A large
+number of cross references are an especially important feature of a good
+Info file.
After you have inserted an @code{@@node} line, you should immediately
write an @@-command for the chapter or section and insert its name.
Next (and this is important!), put in several index entries. Usually,
you will find at least two and often as many as four or five ways of
referring to the node in the index. Use them all. This will make it
-much easier for people to find the node.@refill
+much easier for people to find the node.
-@node Node Line Tips, Node Line Requirements, Writing a Node, node
-@comment node-name, next, previous, up
+
+@node Node Line Tips
@subsection @code{@@node} Line Tips
Here are three suggestions:
capitalized; others are not.@refill
@end itemize
+
@node Node Line Requirements, First Node, Node Line Tips, node
-@comment node-name, next, previous, up
@subsection @code{@@node} Line Requirements
@cindex Node line requirements
@itemize @bullet
@cindex Unique nodename requirement
-@cindex Nodename must be unique
+@cindex Node name must be unique
@item
All the node names for a single Info file must be unique.@refill
A pointer name must be the name of a node.@refill
The node to which a pointer points may come before or after the
-node containing the pointer.@refill
+node containing the pointer.
-@cindex @@-command in nodename
-@cindex Nodename, cannot contain
+@cindex @@-commands in nodename
+@cindex Node name, should not contain @@-commands
@item
-You cannot use any of the Texinfo @@-commands in a node name;
-@w{@@-commands} confuse Info.@refill
+@w{@@-commands} used in node names generally confuse Info, so you should
+avoid them. For a few rare cases when this is useful, Texinfo has
+limited support for using @w{@@-commands} in node names; see
+@ref{Pointer Validation}.
@need 750
Thus, the beginning of the section called @code{@@chapter} looks like
@end group
@end smallexample
-@cindex Comma in nodename
-@cindex Apostrophe in nodename
@item
-You cannot use commas or apostrophes within a node name; these
-confuse @TeX{} or the Info formatters.@refill
+@cindex Apostrophe in nodename
+@cindex Colon in nodename
+@cindex Comma in nodename
+@cindex Period in nodename
+@cindex Characters, invalid in node name
+@cindex Invalid characters in node names
+Unfortunately, you cannot use periods, commas, colons or apostrophes
+within a node name; these confuse @TeX{} or the Info formatters.@refill
@need 700
For example, the following is a section title:
contain this information: see @ref{titlepage, ,
@code{@@titlepage}}.)@refill
-@node makeinfo Pointer Creation, , node, Nodes
+@node makeinfo Pointer Creation
@section Creating Pointers with @code{makeinfo}
@cindex Creating pointers with @code{makeinfo}
@cindex Pointer creation with @code{makeinfo}
@cindex Automatic pointer creation with @code{makeinfo}
-The @code{makeinfo} program has a feature for automatically creating
-node pointers for a hierarchically organized file that lacks
-them.@refill
+The @code{makeinfo} program has a feature for automatically defining
+node pointers for a hierarchically organized file.
When you take advantage of this feature, you do not need to write the
`Next', `Previous', and `Up' pointers after the name of a node.
However, you must write a sectioning command, such as @code{@@chapter}
or @code{@@section}, on the line immediately following each truncated
-@code{@@node} line. You cannot write a comment line after a node
-line; the section line must follow it immediately.@refill
+@code{@@node} line (except that comment lines may intervene).
-In addition, you must follow the `Top' @code{@@node} line with a line beginning
-with @code{@@top} to mark the `Top' node in the file. @xref{makeinfo
-top, , @code{@@top}}.
+In addition, you must follow the `Top' @code{@@node} line with a line
+beginning with @code{@@top} to mark the `Top' node in the
+file. @xref{makeinfo top, , @code{@@top}}.
Finally, you must write the name of each node (except for the `Top'
node) in a menu that is one or more hierarchical levels above the
-node's hierarchical level.@refill
+node's hierarchical level.
+
+This node pointer insertion feature in @code{makeinfo} relieves you from
+the need to update menus and pointers manually or with Texinfo mode
+commands. (@xref{Updating Nodes and Menus}.)
+
+
+@node anchor
+@section @code{@@anchor}: Defining Arbitrary Cross-reference Targets
+
+@findex anchor
+@cindex Anchors
+@cindex Cross-reference targets, arbitrary
+@cindex Targets for cross-references, arbitrary
+
+An @dfn{anchor} is a position in your document, labeled so that
+cross-references can refer to it, just as they can to nodes. You create
+an anchor with the @code{@@anchor} command, and give the label as a
+normal brace-delimited argument. For example:
+
+@example
+This marks the @@anchor@{x-spot@}spot.
+@dots{}
+@@xref@{x-spot,,the spot@}.
+@end example
+
+@noindent produces:
+
+@example
+This marks the spot.
+@dots{}
+See [the spot], page 1.
+@end example
+
+As you can see, the @code{@@anchor} command itself produces no output.
+This example defines an anchor `x-spot' just before the word `spot'.
+You can refer to it later with an @code{@@xref} or other cross-reference
+command, as shown. @xref{Cross References}, for details on the
+cross-reference commands.
+
+It is best to put @code{@@anchor} commands just before the position you
+wish to refer to; that way, the reader's eye is led on to the correct
+text when they jump to the anchor. You can put the @code{@@anchor}
+command on a line by itself if that helps readability of the source.
+Spaces are always ignored after @code{@@anchor}.
+
+Anchor names and node names may not conflict. Anchors and nodes are
+given similar treatment in some ways; for example, the @code{goto-node}
+command in standalone Info takes either an anchor name or a node name as
+an argument. (@xref{goto-node,,,info-stnd,GNU Info}.)
-This node pointer insertion feature in @code{makeinfo} is an
-alternative to the menu and pointer creation and update commands in
-Texinfo mode. (@xref{Updating Nodes and Menus}.) It is especially
-helpful to people who do not use GNU Emacs for writing Texinfo
-documents.@refill
-@node Menus, Cross References, Nodes, Top
-@comment node-name, next, previous, up
+@node Menus
@chapter Menus
@cindex Menus
@findex menu
-@dfn{Menus} contain pointers to subordinate
-nodes.@footnote{Menus can carry you to any node, regardless
-of the hierarchical structure; even to nodes in a different
-Info file. However, the GNU Emacs Texinfo mode updating
-commands work only to create menus of subordinate nodes.
-Conventionally, cross references are used to refer to other
-nodes.} In Info, you use menus to go to such nodes. Menus
-have no effect in printed manuals and do not appear in
-them.@refill
+@dfn{Menus} contain pointers to subordinate nodes.@footnote{Menus can
+carry you to any node, regardless of the hierarchical structure; even to
+nodes in a different Info file. However, the GNU Emacs Texinfo mode
+updating commands work only to create menus of subordinate nodes.
+Conventionally, cross references are used to refer to other nodes.} In
+Info, you use menus to go to such nodes. Menus have no effect in
+printed manuals and do not appear in them.
By convention, a menu is put at the end of a node since a reader who
-uses the menu may not see text that follows it.@refill
-
-@ifinfo
-A node that has a menu should @emph{not} contain much text. If you
-have a lot of text and a menu, move most of the text into a new
-subnode---all but a few lines.@refill
-@end ifinfo
-@iftex
-@emph{A node that has a menu should not contain much text.} If you
-have a lot of text and a menu, move most of the text into a new
-subnode---all but a few lines. Otherwise, a reader with a terminal
-that displays only a few lines may miss the menu and its associated
-text. As a practical matter, you should locate a menu within 20 lines
-of the beginning of the node.@refill
-@end iftex
+uses the menu may not see text that follows it. Furthermore, a node
+that has a menu should not contain much text. If you have a lot of text
+and a menu, move most of the text into a new subnode---all but a few
+lines. Otherwise, a reader with a terminal that displays only a few
+lines may miss the menu and its associated text. As a practical matter,
+you should locate a menu within 20 lines of the beginning of the
+node.
@menu
* Menu Location:: Put a menu in a short node.
* Other Info Files:: How to refer to a different Info file.
@end menu
+
@node Menu Location, Writing a Menu, Menus, Menus
@ifinfo
@heading Menus Need Short Nodes
@cindex Nodes for menus are short
@cindex Short nodes for menus
-@ifinfo
-A reader can easily see a menu that is close to the beginning of the
-node. The node should be short. As a practical matter, you should
-locate a menu within 20 lines of the beginning of the node.
-Otherwise, a reader with a terminal that displays only a few lines may
-miss the menu and its associated text.@refill
-@end ifinfo
-
The short text before a menu may look awkward in a printed manual. To
avoid this, you can write a menu near the beginning of its node and
follow the menu by an @code{@@node} line, and then an @code{@@heading}
The Texinfo file for this document contains more than a dozen
examples of this procedure. One is at the beginning of this chapter;
-another is at the beginning of the ``Cross References'' chapter.@refill
+another is at the beginning of @ref{Cross References}. @refill
+
@node Writing a Menu, Menu Parts, Menu Location, Menus
@section Writing a Menu
@end group
@end example
-In a menu, every line that begins with an @w{@samp{* }} is a
-@dfn{menu entry}. (Note the space after the asterisk.) A
-line that does not start with an @w{@samp{* }} may also
-appear in a menu. Such a line is not a menu entry but is a
-menu comment line that appears in the Info file. In
-the example above, the line @samp{Larger Units of Text} is a
-menu comment line; the two lines starting with @w{@samp{* }}
-are menu entries.
+In a menu, every line that begins with an @w{@samp{* }} is a @dfn{menu
+entry}. (Note the space after the asterisk.) A line that does not
+start with an @w{@samp{* }} may also appear in a menu. Such a line is
+not a menu entry but is a menu comment line that appears in the Info
+file. In the example above, the line @samp{Larger Units of Text} is a
+menu comment line; the two lines starting with @w{@samp{* }} are menu
+@cindex Spaces, in menus
+entries. Space characters in a menu are preserved as-is; this allows
+you to format the menu as you wish.
+
@node Menu Parts, Less Cluttered Menu Entry, Writing a Menu, Menus
@section The Parts of a Menu
not a Texinfo file, but a menu entry looks the same in both types of
file.)@refill
-Note that the GNU Emacs Texinfo mode menu updating commands only work
-with nodes within the current buffer, so you cannot use them to create
-menus that refer to other files. You must write such menus by hand.@refill
+The GNU Emacs Texinfo mode menu updating commands only work with nodes
+within the current buffer, so you cannot use them to create menus that
+refer to other files. You must write such menus by hand.
-@node Cross References, Marking Text, Menus, Top
-@comment node-name, next, previous, up
+
+@node Cross References
@chapter Cross References
@cindex Making cross references
@cindex Cross references
@cindex References
@dfn{Cross references} are used to refer the reader to other parts of the
-same or different Texinfo files. In Texinfo, nodes are the
-places to which cross references can refer.@refill
+same or different Texinfo files. In Texinfo, nodes and anchors are the
+places to which cross references can refer.
@menu
* References:: What cross references are for.
However, in any document, some information will be too detailed for
the current context, or incidental to it; use cross references to
-provide access to such information. Also, an on-line help system or a
+provide access to such information. Also, an online help system or a
reference manual is not like a novel; few read such documents in
sequence from beginning to end. Instead, people look up what they
need. For this reason, such creations should contain many cross
the Info @samp{f} command. (@inforef{Help-Adv, Some advanced Info
commands, info}.)@refill
-The various cross reference commands use nodes to define cross
-reference locations. This is evident in Info, in which a cross
-reference takes you to the specified node. @TeX{} also uses nodes to
-define cross reference locations, but the action is less obvious. When
-@TeX{} generates a DVI file, it records nodes' page numbers and
-uses the page numbers in making references. Thus, if you are writing
-a manual that will only be printed, and will not be used on-line, you
-must nonetheless write @code{@@node} lines to name the places to which
-you make cross references.@refill
+The various cross reference commands use nodes (or anchors,
+@pxref{anchor,,@code{@@anchor}}) to define cross reference locations.
+This is evident in Info, in which a cross reference takes you to the
+specified location. @TeX{} also uses nodes to define cross reference
+locations, but the action is less obvious. When @TeX{} generates a DVI
+file, it records each node's page number and uses the page numbers in making
+references. Thus, if you are writing a manual that will only be
+printed, and will not be used online, you must nonetheless write
+@code{@@node} lines to name the places to which you make cross
+references.@refill
@need 800
@node Cross Reference Commands, Cross Reference Parts, References, Cross References
@enumerate
@item
-The node name (required). This is the node to which the
+The node or anchor name (required). This is the location to which the
cross reference takes you. In a printed document, the location of the
node provides the page reference only for references within the same
document.@refill
@noindent
In @TeX{}, a cross reference looks like this:
-@example
+@quotation
See Section @var{section-number} [@var{node-name}], page @var{page}.
-@end example
+@end quotation
@noindent
or like this
-@example
+@quotation
See Section @var{section-number} [@var{title-or-topic}], page @var{page}.
-@end example
+@end quotation
The @code{@@xref} command does not generate a period or comma to end
the cross reference in either the Info file or the printed output.
*Note Tropical Storms::, for more info.
@end example
+@noindent
+and
+
@quotation
See Section 3.1 [Tropical Storms], page 24, for more info.
@end quotation
@noindent
(Note that in the preceding example the closing brace is followed by a
-period; and that the node name is printed, not the cross reference name.)@refill
+period; and that the node name is printed, not the cross reference name.)
You can write a clause after the cross reference, like this:@refill
a reference, you need to write a title such as ``Clouds, Mist, and
Fog'' without the commas.@refill
-Also, remember to write a comma or period after the closing brace of a
+Also, remember to write a comma or period after the closing brace of an
@code{@@xref} to terminate the cross reference. In the following
examples, a clause follows a terminating comma.@refill
@noindent
For example,
+@cindex Hurricanes
@example
For more information, see @@ref@{Hurricanes@}.
@end example
produces
@example
-For more information, see *Note Hurricanes.
+For more information, see *Note Hurricanes::.
@end example
@noindent
@noindent
For example,
+@cindex Sea surges
@example
@group
Sea surges are described in @@ref@{Hurricanes@}.
@end example
@quotation
-@strong{Caution:} You @emph{must} write a period or comma immediately
-after an @code{@@ref} command with two or more arguments. Otherwise,
-Info will not find the end of the cross reference entry and its
-attempt to follow the cross reference will fail. As a general rule,
-you should write a period or comma after every @code{@@ref} command.
-This looks best in both the printed and the Info output.@refill
+@strong{Caution:} You @emph{must} write a period, comma, or right
+parenthesis immediately after an @code{@@ref} command with two or more
+arguments. Otherwise, Info will not find the end of the cross reference
+entry and its attempt to follow the cross reference will fail. As a
+general rule, you should write a period or comma after every
+@code{@@ref} command. This looks best in both the printed and the Info
+output.@refill
@end quotation
@node pxref, inforef, ref, Cross References
With one argument, a parenthetical cross reference looks like
this:@refill
+@cindex Flooding
@example
@dots{} storms cause flooding (@@pxref@{Hurricanes@}) @dots{}
@end example
@code{@@cite}}.@refill
-@node uref, , inforef, Cross References
-@section @code{@@uref@{@var{url}[, @var{displayed-text}]@}}
+@node uref
+@section @code{@@uref@{@var{url}[, @var{text}][, @var{replacement}]@}}
@findex uref
@cindex Uniform resource locator, referring to
@cindex URL, referring to
-@code{@@uref} produces a reference to a uniform resource locator (URL).
-It takes one mandatory argument, the URL, and one optional argument, the
-text to display (the default is the URL itself). In HTML output,
-@code{@@uref} produces a link you can follow. For example:
+@cindex @code{href}, producing HTML
+@code{@@uref} produces a reference to a uniform resource locator (url).
+It takes one mandatory argument, the url, and two optional arguments
+which control the text that is displayed. In HTML output, @code{@@uref}
+produces a link you can follow.
+
+The second argument, if specified, is the text to display (the default
+is the url itself); in Info and DVI output, but not in HTML output, the
+url is also output.
+
+@cindex Man page, reference to
+The third argument, on the other hand, if specified is also the text to
+display, but the url is @emph{not} output in any format. This is useful
+when the text is already sufficiently referential, as in a man page. If
+the third argument is given, the second argument is ignored.
+
+The simple one argument form, where the url is both the target and the
+text of the link:
@example
-The official GNU ftp site is
-@@uref@{ftp://ftp.gnu.ai.mit.edu/pub/gnu@}
+The official GNU ftp site is @@uref@{ftp://ftp.gnu.org/gnu@}.
@end example
-@noindent
-produces (in text):
+@noindent produces:
@display
-The official GNU ftp site is
-@uref{ftp://ftp.gnu.ai.mit.edu/pub/gnu}
+The official GNU ftp site is @uref{ftp://ftp.gnu.org/gnu}.
@end display
-@noindent
-whereas
+
+An example of the two-argument form:
@example
-The official
-@@uref@{ftp://ftp.gnu.ai.mit.edu/pub/gnu,
- GNU ftp site@} holds programs and texts.
+The official @@uref@{ftp://ftp.gnu.org/gnu, GNU ftp site@} holds
+programs and texts.
@end example
-@noindent
-produces (in text):
+@noindent produces:
@display
-The official @uref{ftp://ftp.gnu.ai.mit.edu/pub/gnu, GNU ftp site} holds
+The official @uref{ftp://ftp.gnu.org/gnu, GNU ftp site} holds
programs and texts.
@end display
-@noindent
-and (in HTML):
+@noindent that is, the Info output is this:
@example
-The official <A HREF="ftp://ftp.gnu.ai.mit.edu/pub/gnu">GNU ftp
-site</A> holds programs and texts.
+The official GNU ftp site (ftp://ftp.gnu.org/gnu) holds
+programs and texts.
@end example
-To merely indicate a URL, use @code{@@url} (@pxref{url, @code{@@url}}).
+@noindent and the HTML output is this:
+@example
+The official <a href="ftp://ftp.gnu.org/gnu">GNU ftp site</a> holds
+programs and texts.
+@end example
-@node Marking Text, Quotations and Examples, Cross References, Top
-@comment node-name, next, previous, up
+An example of the three-argument form:
+@example
+The @@uref@{http://example.org/man.cgi/1/ls,,ls(1)@} program @dots{}
+@end example
+
+@noindent produces:
+@display
+The @uref{http://example.org/man.cgi/1/ls,,ls(1)} program @dots{}
+@end display
+
+@noindent but with HTML:
+@example
+The <a href="http://example.org/man.cgi/1/ls">ls(1)</a> program @dots{}
+@end example
+
+To merely indicate a url without creating a link people can follow, use
+@code{@@url} (@pxref{url, @code{@@url}}).
+
+
+Some people prefer to display url's in the unambiguous format:
+
+@display
+<URL:http://@var{host}/@var{path}>
+@end display
+
+@noindent
+@cindex <URL: convention, not used
+You can use this form in the input file if you wish. We feel it's not
+necessary to clutter up the output with the extra @samp{<URL:} and
+@samp{>}, since any software that tries to detect url's in text already
+has to detect them without the @samp{<URL:} to be useful.
+
+
+@node Marking Text
@chapter Marking Words and Phrases
@cindex Paragraph, marking text within
@cindex Marking words and phrases
@cindex Words and phrases, marking them
@cindex Marking text within a paragraph
+@cindex Text, marking up
In Texinfo, you can mark words and phrases in a variety of ways.
The Texinfo formatters use this information to determine how to
highlight the text.
You can specify, for example, whether a word or phrase is a
defining occurrence, a metasyntactic variable, or a symbol used in a
-program. Also, you can emphasize text.@refill
+program. Also, you can emphasize text, in several different ways.
@menu
* Indicating:: How to indicate definitions, files, etc.
code is usually illustrated in a typewriter font;
@code{@@code} tells @TeX{} to typeset this text in this font. But it
would be easy to change the way @TeX{} highlights code to use another
-font, and this change would not effect how keystroke examples are
+font, and this change would not affect how keystroke examples are
highlighted. If straight typesetting commands were used in the body
of the file and you wanted to make a change, you would need to check
every single occurrence to make sure that you were changing code and
@menu
* Useful Highlighting:: Highlighting provides useful information.
-* code:: How to indicate code.
-* kbd:: How to show keyboard input.
-* key:: How to specify keys.
-* samp:: How to show a literal sequence of characters.
-* var:: How to indicate a metasyntactic variable.
-* file:: How to indicate the name of a file.
-* dfn:: How to specify a definition.
-* cite:: How to refer to a book that is not in Info.
-* url:: How to indicate a world wide web reference.
-* email:: How to indicate an electronic mail address.
+* code:: Indicating program code.
+* kbd:: Showing keyboard input.
+* key:: Specifying keys.
+* samp:: Showing a literal sequence of characters.
+* var:: Indicating metasyntactic variables.
+* env:: Indicating environment variables.
+* file:: Indicating file names.
+* command:: Indicating command names.
+* option:: Indicating option names.
+* dfn:: Specifying definitions.
+* cite:: Referring to books not in the Info system.
+* acronym:: Indicating acronyms.
+* url:: Indicating a World Wide Web reference.
+* email:: Indicating an electronic mail address.
@end menu
+
@node Useful Highlighting, code, Indicating, Indicating
@ifinfo
@subheading Highlighting Commands are Useful
@end ifinfo
-The highlighting commands can be used to generate useful information
+The highlighting commands can be used to extract useful information
from the file, such as lists of functions or file names. It is
possible, for example, to write a program in Emacs Lisp (or a keyboard
macro) to insert an index entry after every paragraph that contains
@item @@var@{@var{metasyntactic-variable}@}
Indicate a metasyntactic variable.@refill
-@item @@url@{@var{uniform-resource-locator}@}
-Indicate a uniform resource locator for the World Wide Web.
+@item @@env@{@var{environment-variable}@}
+Indicate an environment variable.@refill
@item @@file@{@var{file-name}@}
Indicate the name of a file.@refill
-@item @@email@{@var{email-address}[, @var{displayed-text}]@}
-Indicate an electronic mail address.
+@item @@command@{@var{command-name}@}
+Indicate the name of a command.@refill
+
+@item @@option@{@var{option}@}
+Indicate a command-line option.@refill
@item @@dfn@{@var{term}@}
Indicate the introductory or defining use of a term.@refill
@item @@cite@{@var{reference}@}
Indicate the name of a book.@refill
+@item @@acronym@{@var{acronym}@}
+Indicate an acronym.@refill
+
+@item @@url@{@var{uniform-resource-locator}@}
+Indicate a uniform resource locator for the World Wide Web.
+
+@item @@email@{@var{email-address}[, @var{displayed-text}]@}
+Indicate an electronic mail address.
+
@ignore
@item @@ctrl@{@var{ctrl-char}@}
Use for an @sc{ascii} control character.@refill
@end ignore
@end table
-@node code, kbd, Useful Highlighting, Indicating
-@comment node-name, next, previous, up
+
+@node code
@subsection @code{@@code}@{@var{sample-code}@}
@findex code
+@cindex Syntactic tokens, indicating
Use the @code{@@code} command to indicate text that is a piece of a
program and which consists of entire syntactic tokens. Enclose the
-text in braces.@refill
+text in braces.
+@cindex Expressions in a program, indicating
+@cindex Keywords, indicating
+@cindex Reserved words, indicating
Thus, you should use @code{@@code} for an expression in a program, for
the name of a variable or function used in a program, or for a
-keyword. Also, you should use @code{@@code} for the name of a
-program, such as @code{diff}, that is a name used in the machine. (You
-should write the name of a program in the ordinary text font if you
-regard it as a new English word, such as `Emacs' or `Bison'.)@refill
-
-Use @code{@@code} for environment variables such as @code{TEXINPUTS},
-and other variables.@refill
-
-Use @code{@@code} for command names in command languages that
-resemble programming languages, such as Texinfo or the shell.
-For example, @code{@@code} and @code{@@samp} are produced by writing
-@samp{@@code@{@@@@code@}} and @samp{@@code@{@@@@samp@}} in the Texinfo
-source, respectively.@refill
-
-Note, however, that you should not use @code{@@code} for shell options
-such as @samp{-c} when such options stand alone. (Use @code{@@samp}.)
-Also, an entire shell command often looks better if written using
-@code{@@samp} rather than @code{@@code}. In this case, the rule is to
-choose the more pleasing format.@refill
+keyword in a programming language.
+
+Use @code{@@code} for command names in languages that resemble
+programming languages, such as Texinfo. For example, @code{@@code} and
+@code{@@samp} are produced by writing @samp{@@code@{@@@@code@}} and
+@samp{@@code@{@@@@samp@}} in the Texinfo source, respectively.
+@cindex Case, not altering in @code{@@code}
It is incorrect to alter the case of a word inside an @code{@@code}
command when it appears at the beginning of a sentence. Most computer
languages are case sensitive. In C, for example, @code{Printf} is
misspelling of it. Even in languages which are not case sensitive, it
is confusing to a human reader to see identifiers spelled in different
ways. Pick one spelling and always use that. If you do not want to
-start a sentence with a command written all in lower case, you should
-rearrange the sentence.@refill
-
-Do not use the @code{@@code} command for a string of characters shorter
-than a syntactic token. If you are writing about @samp{TEXINPU}, which
-is just a part of the name for the @code{TEXINPUTS} environment
-variable, you should use @code{@@samp}.@refill
-
-In particular, you should not use the @code{@@code} command when writing
-about the characters used in a token; do not, for example, use
-@code{@@code} when you are explaining what letters or printable symbols
-can be used in the names of functions. (Use @code{@@samp}.) Also, you
-should not use @code{@@code} to mark text that is considered input to
-programs unless the input is written in a language that is like a
-programming language. For example, you should not use @code{@@code} for
-the keystroke commands of GNU Emacs (use @code{@@kbd} instead) although
-you may use @code{@@code} for the names of the Emacs Lisp functions that
-the keystroke commands invoke.@refill
+start a sentence with a command name written all in lower case, you
+should rearrange the sentence.
In the printed manual, @code{@@code} causes @TeX{} to typeset the
argument in a typewriter face. In the Info file, it causes the Info
For example,
@example
-Use @@code@{diff@} to compare two files.
+The function returns @@code@{nil@}.
@end example
@noindent
-produces this in the printed manual:@refill
+produces this in the printed manual:
@quotation
-Use @code{diff} to compare two files.
+The function returns @code{nil}.
@end quotation
-@iftex
+@iftex
@noindent
-and this in the Info file:@refill
-
+and this in the Info file:
@example
-Use `diff' to compare two files.
+The function returns `nil'.
@end example
@end iftex
+Here are some cases for which it is preferable not to use @code{@@code}:
+
+@itemize @bullet
+@item
+For shell command names such as @command{ls} (use @code{@@command}).
+
+@item
+For shell options such as @samp{-c} when such options stand alone (use
+@code{@@option}).
+
+@item
+Also, an entire shell command often looks better if written using
+@code{@@samp} rather than @code{@@code}. In this case, the rule is to
+choose the more pleasing format.
+
+@item
+For environment variable such as @env{TEXINPUTS} (use @code{@@env}).
+
+@item
+For a string of characters shorter than a syntactic token. For example,
+if you are writing about @samp{goto-ch}, which is just a part of the
+name for the @code{goto-char} Emacs Lisp function, you should use
+@code{@@samp}.
+
+@item
+In general, when writing about the characters used in a token; for
+example, do not use @code{@@code} when you are explaining what letters
+or printable symbols can be used in the names of functions. (Use
+@code{@@samp}.) Also, you should not use @code{@@code} to mark text
+that is considered input to programs unless the input is written in a
+language that is like a programming language. For example, you should
+not use @code{@@code} for the keystroke commands of GNU Emacs (use
+@code{@@kbd} instead) although you may use @code{@@code} for the names
+of the Emacs Lisp functions that the keystroke commands invoke.
+
+@end itemize
+
+Since @code{@@command}, @code{@@option}, and @code{@@env} were
+introduced relatively recently, it is acceptable to use @code{@@code} or
+@code{@@samp} for command names, options, and environment variables.
+The new commands allow you to express the markup more precisely, but
+there is no real harm in using the older commands, and of course the
+long-standing manuals do so.
+
-@node kbd, key, code, Indicating
+@node kbd
@subsection @code{@@kbd}@{@var{keyboard-characters}@}
@findex kbd
-@cindex keyboard input
+@cindex Keyboard input
Use the @code{@@kbd} command for characters of input to be typed by
users. For example, to refer to the characters @kbd{M-a},
@item example
Use the distinguishing font for @code{@@kbd} only in @code{@@example}
and similar environments.
-@item example
+@item distinct
(the default) Always use the distinguishing font for @code{@@kbd}.
@end table
Any time you are referring to single characters, you should use
@code{@@samp} unless @code{@@kbd} or @code{@@key} is more appropriate.
-Use @code{@@samp} for the names of command-line options (except in an
-@code{@@table}, where @code{@@code} seems to read more easily). Also,
-you may use @code{@@samp} for entire statements in C and for entire
+Also, you may use @code{@@samp} for entire statements in C and for entire
shell commands---in this case, @code{@@samp} often looks better than
@code{@@code}. Basically, @code{@@samp} is a catchall for whatever is
not covered by @code{@@code}, @code{@@kbd}, or @code{@@key}.@refill
@samp{y}.
@end quotation
-@node var, file, samp, Indicating
-@comment node-name, next, previous, up
+
+@node var
@subsection @code{@@var}@{@var{metasyntactic-variable}@}
@findex var
Do not use @code{@@var} for the names of particular variables in
programming languages. These are specific names from a program, so
-@code{@@code} is correct for them. For example, the Emacs Lisp variable
-@code{texinfo-tex-command} is not a metasyntactic variable; it is
-properly formatted using @code{@@code}.@refill
+@code{@@code} is correct for them (@pxref{code}). For example, the
+Emacs Lisp variable @code{texinfo-tex-command} is not a metasyntactic
+variable; it is properly formatted using @code{@@code}.
+
+Do not use @code{@@var} for environment variables either; @code{@@env}
+is correct for them (see the next section).
-The effect of @code{@@var} in the Info file is to change the case of
-the argument to all upper case; in the printed manual, to italicize it.
+The effect of @code{@@var} in the Info file is to change the case of the
+argument to all upper case. In the printed manual and HTML output, the
+argument is printed in slanted type.
@need 700
For example,
@example
To delete file @@var@{filename@},
-type @@code@{rm @@var@{filename@}@}.
+type @@samp@{rm @@var@{filename@}@}.
@end example
@noindent
produces
@quotation
-To delete file @var{filename}, type @code{rm @var{filename}}.
+To delete file @var{filename}, type @samp{rm @var{filename}}.
@end quotation
@noindent
@noindent
However, that is not the style that Texinfo uses. (You can, of
-course, modify the sources to @TeX{} and the Info formatting commands
+course, modify the sources to @file{texinfo.tex} and the Info formatting commands
to output the @code{<@dots{}>} format if you wish.)@refill
-@node file, dfn, var, Indicating
-@comment node-name, next, previous, up
+
+@node env
+@subsection @code{@@env}@{@var{environment-variable}@}
+@findex env
+
+Use the @code{@@env} command to indicate environment variables, as used
+by many operating systems, including GNU. Do not use it for
+metasyntactic variables; use @code{@@var} instead (see the previous
+section).
+
+@code{@@env} is equivalent to @code{@@code} in its effects.
+For example:
+
+@example
+The @@env@{PATH@} environment variable sets the search path for commands.
+@end example
+@noindent produces
+@quotation
+The @env{PATH} environment variable sets the search path for commands.
+@end quotation
+
+
+@node file
@subsection @code{@@file}@{@var{file-name}@}
@findex file
the @file{/usr/local/emacs/lisp} directory.
@end quotation
-@node dfn, cite, file, Indicating
+
+@node command
+@subsection @code{@@command}@{@var{command-name}@}
+@findex command
+@cindex Command names, indicating
+@cindex Program names, indicating
+
+Use the @code{@@command} command to indicate command names, such as
+@command{ls} or @command{cc}.
+
+@code{@@command} is equivalent to @code{@@code} in its effects.
+For example:
+
+@example
+The command @@command@{ls@} lists directory contents.
+@end example
+@noindent produces
+@quotation
+The command @command{ls} lists directory contents.
+@end quotation
+
+You should write the name of a program in the ordinary text font, rather
+than using @code{@@command}, if you regard it as a new English word,
+such as `Emacs' or `Bison'.
+
+When writing an entire shell command invocation, as in @samp{ls -l},
+you should use either @code{@@samp} or @code{@@code} at your discretion.
+
+
+@node option
+@subsection @code{@@option}@{@var{option-name}@}
+@findex option
+
+Use the @code{@@option} command to indicate a command-line option; for
+example, @option{-l} or @option{--version} or
+@option{--output=@var{filename}}.
+
+@code{@@option} is equivalent to @code{@@samp} in its effects.
+For example:
+
+@example
+The option @@option@{-l@} produces a long listing.
+@end example
+@noindent produces
+@quotation
+The option @option{-l} produces a long listing.
+@end quotation
+
+In tables, putting options inside @code{@@code} produces a
+more pleasing effect.
+
+@node dfn
@comment node-name, next, previous, up
@subsection @code{@@dfn}@{@var{term}@}
@findex dfn
to say explicitly that it is a definition, but it should contain the
information of a definition---it should make the meaning clear.
-@node cite, url, dfn, Indicating
-@comment node-name, next, previous, up
+@node cite
@subsection @code{@@cite}@{@var{reference}@}
@findex cite
Use the @code{@@cite} command for the name of a book that lacks a
-companion Info file. The command produces italics in the printed
-manual, and quotation marks in the Info file.@refill
+companion Info file. The command produces italics in the printed
+manual, and quotation marks in the Info file.
-(If a book is written in Texinfo, it is better to use a cross reference
+If a book is written in Texinfo, it is better to use a cross reference
command since a reader can easily follow such a reference in Info.
-@xref{xref, , @code{@@xref}}.)@refill
+@xref{xref, , @code{@@xref}}.
+
@ignore
@c node ctrl, , cite, Indicating
@end ignore
-@node url, email, cite, Indicating
+@node acronym
+@subsection @code{@@acronym}@{@var{acronym}@}
+@findex acronym
+
+@cindex NASA, as acronym
+@cindex F.B.I., as acronym
+@cindex Abbreviations, tagging
+@cindex Acronyms, tagging
+Use the @code{@@acronym} command for abbreviations written in all
+capital letters, such as `@acronym{NASA}'. The abbreviation is given as
+the single argument in braces, as in @samp{@@acronym@{NASA@}}. As
+a matter of style, or for particular abbreviations, you may prefer to
+use periods, as in @samp{@@acronym@{F.B.I.@}}.
+
+In @TeX{} and HTML, the argument is printed in a slightly smaller font
+size. In Info or plain text output, this command changes nothing.
+
+
+@node url
@subsection @code{@@url}@{@var{uniform-resource-locator}@}
@findex url
@cindex Uniform resource locator, indicating
@cindex URL, indicating
-Use the @code{@@url} to indicate a uniform resource locator on the World
-Wide Web. This is analogous to @code{@@file}, @code{@@var}, etc., and
-is purely for markup purposes. It does not produce a link you can
-follow in HTML output (the @code{@@uref} command does, @pxref{uref,,
-@code{@@uref}}). It is useful for example URL's which do not actually
-exist. For example:
+Use the @code{@@url} command to indicate a uniform resource locator on
+the World Wide Web. This is analogous to @code{@@file}, @code{@@var},
+etc., and is purely for markup purposes. It does not produce a link you
+can follow in HTML output (use the @code{@@uref} command for that,
+@pxref{uref,, @code{@@uref}}). It is useful for url's which do
+not actually exist. For example:
@c Two lines because one is too long for smallbook format.
@example
-For example, the url might be
-@@url@{http://host.domain.org/path@}.
+For example, the url might be @@url@{http://example.org/path@}.
@end example
+@noindent which produces:
+
+@display
+For example, the url might be @url{http://example.org/path}.
+@end display
-@node email, , url, Indicating
+
+@node email
@subsection @code{@@email}@{@var{email-address}[, @var{displayed-text}]@}
@findex email
Send bug reports to @@email@{bug-texinfo@@@@gnu.org@}.
Send suggestions to the @@email@{bug-texinfo@@@@gnu.org, same place@}.
@end example
-@noindent
-produces
-@example
+@noindent produces
+@display
Send bug reports to @email{bug-texinfo@@gnu.org}.
Send suggestions to the @email{bug-texinfo@@gnu.org, same place}.
-@end example
+@end display
@node Emphasis, , Indicating, Marking Text
However, sometimes you will want to emphasize text without indicating a
category. Texinfo has two commands to do this. Also, Texinfo has
several commands that specify the font in which @TeX{} will typeset
-text. These commands have no affect on Info and only one of them,
+text. These commands have no effect on Info and only one of them,
the @code{@@r} command, has any regular use.@refill
@menu
* emph & strong:: How to emphasize text in Texinfo.
* Smallcaps:: How to use the small caps font.
* Fonts:: Various font commands for printed output.
-* Customized Highlighting:: How to define highlighting commands.
@end menu
-@node emph & strong, Smallcaps, Emphasis, Emphasis
-@comment node-name, next, previous, up
+@node emph & strong
@subsection @code{@@emph}@{@var{text}@} and @code{@@strong}@{@var{text}@}
@cindex Emphasizing text, font for
@findex emph
@findex strong
The @code{@@emph} and @code{@@strong} commands are for emphasis;
-@code{@@strong} is stronger. In printed output, @code{@@emph}
-produces @emph{italics} and @code{@@strong} produces
-@strong{bold}.@refill
+@code{@@strong} is stronger. In printed output, @code{@@emph} produces
+@emph{italics} and @code{@@strong} produces @strong{bold}.
@need 800
For example,
produces the following in printed output:
@quotation
-@strong{Caution}: @code{rm * .[^.]*} removes @emph{all}
+@strong{Caution}: @samp{rm * .[^.]*} removes @emph{all}
files in the directory.
@end quotation
@end ifinfo
@example
- *Caution*: `rm * .[^.]*' removes *all*
+ *Caution*: `rm * .[^.]*' removes _all_
files in the directory.
@end example
effect, a typographical element, such as the word `Caution' in the
preceding example.
-In the Info file, both @code{@@emph} and @code{@@strong} put asterisks
-around the text.@refill
+In the Info output, @code{@@emph} surrounds the text with underscores
+(@samp{_}), and @code{@@strong} puts asterisks around the text.
@quotation
-@strong{Caution:} Do not use @code{@@emph} or @code{@@strong} with the
-word @samp{Note}; Info will mistake the combination for a cross
-reference. Use a phrase such as @strong{Please note} or
-@strong{Caution} instead.@refill
+@strong{Caution:} Do not use @code{@@strong} with the word @samp{Note};
+Info will mistake the combination for a cross reference. Use a phrase
+such as @strong{Please note} or @strong{Caution} instead.
@end quotation
-@node Smallcaps, Fonts, emph & strong, Emphasis
+
+@node Smallcaps
@subsection @code{@@sc}@{@var{text}@}: The Small Caps Font
@cindex Small caps font
@findex sc @r{(small caps font)}
-@iftex
-Use the @samp{@@sc} command to set text in the printed output in @sc{a
-small caps font} and set text in the Info file in upper case letters.@refill
-@end iftex
-@ifinfo
-Use the @samp{@@sc} command to set text in the printed output in a
-small caps font and set text in the Info file in upper case letters.@refill
-@end ifinfo
-
-Write the text between braces in lower case, like this:@refill
+Use the @samp{@@sc} command to set text in the printed and the HTML
+output in @sc{a small caps font} and set text in the Info file in upper
+case letters. Write the text you want to be in small caps (where
+possible) between braces in lower case, like this:
@example
The @@sc@{acm@} and @@sc@{ieee@} are technical societies.
@TeX{} typesets the small caps font in a manner that prevents the
letters from `jumping out at you on the page'. This makes small caps
-text easier to read than text in all upper case. The Info formatting
-commands set all small caps text in upper case.@refill
+text easier to read than text in all upper case---but it's usually
+better to use regular mixed case anyway. The Info formatting commands
+set all small caps text in upper case. In HTML, the text is upper-cased
+and a smaller font is used to render it.
-@ifinfo
-If the text between the braces of an @code{@@sc} command is upper case,
-@TeX{} typesets in full-size capitals. Use full-size capitals
-sparingly.@refill
-@end ifinfo
-@iftex
-If the text between the braces of an @code{@@sc} command is upper case,
-@TeX{} typesets in @sc{FULL-SIZE CAPITALS}. Use full-size capitals
-sparingly.@refill
-@end iftex
+If the text between the braces of an @code{@@sc} command is uppercase,
+@TeX{} typesets in FULL-SIZE CAPITALS. Use full-size capitals
+sparingly, if ever, and since it's redundant to mark all-uppercase text
+with @code{@@sc}, @command{makeinfo} warns about such usage.
You may also use the small caps font for a jargon word such as
-@sc{ato} (a @sc{nasa} word meaning `abort to orbit').@refill
+@sc{ato} (a @sc{nasa} word meaning `abort to orbit').
There are subtleties to using the small caps font with a jargon word
such as @sc{cdr}, a word used in Lisp programming. In this case, you
should use the small caps font when the word refers to the second and
subsequent elements of a list (the @sc{cdr} of the list), but you
should use @samp{@@code} when the word refers to the Lisp function of
-the same spelling.@refill
+the same spelling.
-@node Fonts, Customized Highlighting, Smallcaps, Emphasis
-@comment node-name, next, previous, up
+
+@node Fonts
@subsection Fonts for Printing, Not Info
@cindex Fonts for printing, not for Info
@findex i @r{(italic font)}
you need to use one, it probably indicates a gap in the Texinfo
language.@refill
-@node Customized Highlighting, , Fonts, Emphasis
-@comment node-name, next, previous, up
-@subsection Customized Highlighting
-@cindex Highlighting, customized
-@cindex Customized highlighting
-
-@c I think this whole section is obsolete with the advent of macros
-@c --karl, 15sep96.
-You can use regular @TeX{} commands inside of @code{@@iftex} @dots{}
-@code{@@end iftex} to create your own customized highlighting commands
-for Texinfo. The easiest way to do this is to equate your customized
-commands with pre-existing commands, such as those for italics. Such
-new commands work only with @TeX{}.@refill
+@node Quotations and Examples
+@chapter Quotations and Examples
-@findex definfoenclose
-@cindex Enclosure command for Info
-You can use the @code{@@definfoenclose} command inside of
-@code{@@ifinfo} @dots{} @code{@@end ifinfo} to define commands for Info
-with the same names as new commands for @TeX{}.
-@code{@@definfoenclose} creates new commands for Info that mark text by
-enclosing it in strings that precede and follow the text.
-@footnote{Currently, @code{@@definfoenclose} works only with
-@code{texinfo-format-buffer} and @code{texinfo-format-region}, not with
-@code{makeinfo}.}@refill
+Quotations and examples are blocks of text consisting of one or more
+whole paragraphs that are set off from the bulk of the text and
+treated differently. They are usually indented.@refill
-Here is how to create a new @@-command called @code{@@phoo} that causes
-@TeX{} to typeset its argument in italics and causes Info to display the
-argument between @samp{//} and @samp{\\}.@refill
+In Texinfo, you always begin a quotation or example by writing an
+@@-command at the beginning of a line by itself, and end it by writing
+an @code{@@end} command that is also at the beginning of a line by
+itself. For instance, you begin an example by writing @code{@@example}
+by itself at the beginning of a line and end the example by writing
+@code{@@end example} on a line by itself, at the beginning of that
+line.@refill
+@findex end
-@need 1300
-For @TeX{}, write the following to equate the @code{@@phoo} command with
-the existing @code{@@i} italics command:@refill
+@menu
+* Block Enclosing Commands:: Use different constructs for
+ different purposes.
+* quotation:: How to write a quotation.
+* example:: How to write an example in a fixed-width font.
+* noindent:: How to prevent paragraph indentation.
+* lisp:: How to illustrate Lisp code.
+* small:: Forms for @code{@@smallbook}.
+* display:: How to write an example in the current font.
+* format:: How to write an example that does not narrow
+ the margins.
+* exdent:: How to undo the indentation of a line.
+* flushleft & flushright:: How to push text flushleft or flushright.
+* cartouche:: How to draw cartouches around examples.
+@end menu
-@example
-@group
-@@iftex
-@@global@@let@@phoo=@@i
-@@end iftex
-@end group
-@end example
+@node Block Enclosing Commands
+@section Block Enclosing Commands
-@noindent
-This defines @code{@@phoo} as a command that causes @TeX{} to typeset
-the argument to @code{@@phoo} in italics. @code{@@global@@let} tells
-@TeX{} to equate the next argument with the argument that follows the
-equals sign.
+Here are commands for quotations and examples, explained further in the
+following sections:
-@need 1300
-For Info, write the following to tell the Info formatters to enclose the
-argument between @samp{//} and @samp{\\}:
+@table @code
+@item @@quotation
+Indicate text that is quoted. The text is filled, indented, and
+printed in a roman font by default.@refill
-@example
-@group
-@@ifinfo
-@@definfoenclose phoo, //, \\
-@@end ifinfo
-@end group
-@end example
+@item @@example
+Illustrate code, commands, and the like. The text is printed
+in a fixed-width font, and indented but not filled.@refill
-@noindent
-Write the @code{@@definfoenclose} command on a line and follow it with
-three arguments separated by commas (commas are used as separators in an
-@code{@@node} line in the same way).@refill
+@item @@smallexample
+Same as @code{@@example}, except that in @TeX{} this command typesets
+text in a smaller font for the @code{@@smallbook} format than for the
+default 8.5 by 11 inch format.
-@itemize @bullet
-@item
-The first argument to @code{@@definfoenclose} is the @@-command name
-@strong{without} the @samp{@@};
+@item @@lisp
+Like @code{@@example}, but specifically for illustrating Lisp code. The
+text is printed in a fixed-width font, and indented but not filled.
-@item
-the second argument is the Info start delimiter string; and,
-
-@item
-the third argument is the Info end delimiter string.
-@end itemize
-
-@noindent
-The latter two arguments enclose the highlighted text in the Info file.
-A delimiter string may contain spaces. Neither the start nor end
-delimiter is required. However, if you do not provide a start
-delimiter, you must follow the command name with two commas in a row;
-otherwise, the Info formatting commands will misinterpret the end
-delimiter string as a start delimiter string.@refill
-
-After you have defined @code{@@phoo} both for @TeX{} and for Info, you
-can then write @code{@@phoo@{bar@}} to see @samp{//bar\\}
-in Info and see
-@ifinfo
-@samp{bar} in italics in printed output.
-@end ifinfo
-@iftex
-@i{bar} in italics in printed output.
-@end iftex
-
-Note that each definition applies to its own formatter: one for @TeX{},
-the other for Info.
-
-@need 1200
-Here is another example:
-
-@example
-@group
-@@ifinfo
-@@definfoenclose headword, , :
-@@end ifinfo
-@@iftex
-@@global@@let@@headword=@@b
-@@end iftex
-@end group
-@end example
-
-@noindent
-This defines @code{@@headword} as an Info formatting command that
-inserts nothing before and a colon after the argument and as a @TeX{}
-formatting command to typeset its argument in bold.
-
-@node Quotations and Examples, Lists and Tables, Marking Text, Top
-@comment node-name, next, previous, up
-@chapter Quotations and Examples
-
-Quotations and examples are blocks of text consisting of one or more
-whole paragraphs that are set off from the bulk of the text and
-treated differently. They are usually indented.@refill
-
-In Texinfo, you always begin a quotation or example by writing an
-@@-command at the beginning of a line by itself, and end it by writing
-an @code{@@end} command that is also at the beginning of a line by
-itself. For instance, you begin an example by writing @code{@@example}
-by itself at the beginning of a line and end the example by writing
-@code{@@end example} on a line by itself, at the beginning of that
-line.@refill
-@findex end
-
-@menu
-* Block Enclosing Commands:: Use different constructs for
- different purposes.
-* quotation:: How to write a quotation.
-* example:: How to write an example in a fixed-width font.
-* noindent:: How to prevent paragraph indentation.
-* Lisp Example:: How to illustrate Lisp code.
-* smallexample & smalllisp:: Forms for the @code{@@smallbook} option.
-* display:: How to write an example in the current font.
-* format:: How to write an example that does not narrow
- the margins.
-* exdent:: How to undo the indentation of a line.
-* flushleft & flushright:: How to push text flushleft or flushright.
-* cartouche:: How to draw cartouches around examples.
-@end menu
-
-@node Block Enclosing Commands, quotation, Quotations and Examples, Quotations and Examples
-@section The Block Enclosing Commands
-
-Here are commands for quotations and examples:@refill
-
-@table @code
-@item @@quotation
-Indicate text that is quoted. The text is filled, indented, and
-printed in a roman font by default.@refill
-
-@item @@example
-Illustrate code, commands, and the like. The text is printed
-in a fixed-width font, and indented but not filled.@refill
-
-@item @@lisp
-Illustrate Lisp code. The text is printed in a fixed-width font,
-and indented but not filled.@refill
-
-@item @@smallexample
-Illustrate code, commands, and the like. Similar to
-@code{@@example}, except that in @TeX{} this command typesets text in
-a smaller font for the smaller @code{@@smallbook} format than for the
-8.5 by 11 inch format.@refill
-
-@item @@smalllisp
-Illustrate Lisp code. Similar to @code{@@lisp}, except that
-in @TeX{} this command typesets text in a smaller font for the smaller
-@code{@@smallbook} format than for the 8.5 by 11 inch format.@refill
+@item @@smalllisp
+Is to @code{@@lisp} as @code{@@smallexample} is to @code{@@example}.
@item @@display
Display illustrative text. The text is indented but not filled, and
-no font is specified (so, by default, the font is roman).@refill
+no font is selected (so, by default, the font is roman).@refill
+
+@item @@smalldisplay
+Is to @code{@@display} as @code{@@smallexample} is to @code{@@example}.
@item @@format
-Print illustrative text. The text is not indented and not filled
-and no font is specified (so, by default, the font is roman).@refill
+Like @code{@@display} (the text is not filled and no font is selected),
+but the text is not indented.
+
+@item @@smallformat
+Is to @code{@@format} as @code{@@smallexample} is to @code{@@example}.
@end table
The @code{@@exdent} command is used within the above constructs to
You can use the @code{@@cartouche} command within one of the above
constructs to highlight the example or quotation by drawing a box with
-rounded corners around it. (The @code{@@cartouche} command affects
-only the printed manual; it has no effect in the Info file; see
-@ref{cartouche, , Drawing Cartouches Around Examples}.)@refill
+rounded corners around it. @xref{cartouche, , Drawing Cartouches Around
+Examples}.
-@node quotation, example, Block Enclosing Commands, Quotations and Examples
-@comment node-name, next, previous, up
+
+@node quotation
@section @code{@@quotation}
@cindex Quotations
@findex quotation
-The text of a quotation is
-processed normally except that:@refill
+The text of a quotation is processed normally except that:
@itemize @bullet
@item
This is a foo.
@end quotation
-@node example, noindent, quotation, Quotations and Examples
-@comment node-name, next, previous, up
+
+@node example
@section @code{@@example}
@cindex Examples, formatting them
@cindex Formatting examples
@end example
Write an @code{@@example} command at the beginning of a line by itself.
-This line will disappear from the output. Mark the end of the example
+Mark the end of the example
with an @code{@@end example} command, also written at the beginning of a
-line by itself. The @code{@@end example} will disappear from the
-output.@refill
+line by itself.@refill
@need 700
For example,
mv foo bar
@end example
-Since the lines containing @code{@@example} and @code{@@end example}
-will disappear, you should put a blank line before the
-@code{@@example} and another blank line after the @code{@@end
-example}. (Remember that blank lines between the beginning
+The lines containing @code{@@example} and @code{@@end example}
+will disappear from the output.
+To make the output look good,
+you should put a blank line before the
+@code{@@example} and another blank line after the @code{@@end example}.
+Note that blank lines inside the beginning
@code{@@example} and the ending @code{@@end example} will appear in
-the output.)@refill
+the output.@refill
@quotation
@strong{Caution:} Do not use tabs in the lines of an example (or anywhere
@end quotation
Examples are often, logically speaking, ``in the middle'' of a
-paragraph, and the text continues after an example should not be
+paragraph, and the text that continues after an example should not be
indented. The @code{@@noindent} command prevents a piece of text from
being indented as if it were a new paragraph.
@ifinfo
embedded within sentences, not set off from preceding and following
text. @xref{code, , @code{@@code}}.)
-@node noindent, Lisp Example, example, Quotations and Examples
-@comment node-name, next, previous, up
+
+@node noindent
@section @code{@@noindent}
@findex noindent
necessary, since @code{@@noindent} is a command used outside of
paragraphs (@pxref{Command Syntax}).@refill
-@node Lisp Example, smallexample & smalllisp, noindent, Quotations and Examples
-@comment node-name, next, previous, up
+
+@node lisp
@section @code{@@lisp}
-@cindex Lisp example
@findex lisp
+@cindex Lisp example
The @code{@@lisp} command is used for Lisp code. It is synonymous
with the @code{@@example} command.
you write a function that evaluates only and all the Lisp code in a
Texinfo file. Then you can use the Texinfo file as a Lisp
library.@footnote{It would be straightforward to extend Texinfo to work
-in a similar fashion for C, Fortran, or other languages.}@refill
+in a similar fashion for C, Fortran, or other languages.}
Mark the end of @code{@@lisp} with @code{@@end lisp} on a line by
itself.@refill
-@node smallexample & smalllisp, display, Lisp Example, Quotations and Examples
-@comment node-name, next, previous, up
-@section @code{@@smallexample} and @code{@@smalllisp}
+
+@node small
+@section @code{@@small@dots{}} Block Commands
@cindex Small book example
@cindex Example for a small book
@cindex Lisp example for a small book
+@findex smalldisplay
@findex smallexample
+@findex smallformat
@findex smalllisp
In addition to the regular @code{@@example} and @code{@@lisp} commands,
-Texinfo has two other ``example-style'' commands. These are the
-@code{@@smallexample} and @code{@@smalllisp} commands. Both these
-commands are designed for use with the @code{@@smallbook} command that
-causes @TeX{} to produce a printed manual in a 7 by 9.25 inch format
-rather than the regular 8.5 by 11 inch format.@refill
-
-In @TeX{}, the @code{@@smallexample} and @code{@@smalllisp} commands
-typeset text in a smaller font for the smaller @code{@@smallbook}
-format than for the 8.5 by 11 inch format. Consequently, many examples
-containing long lines fit in a narrower, @code{@@smallbook} page
-without needing to be shortened. Both commands typeset in the normal
-font size when you format for the 8.5 by 11 inch size; indeed,
-in this situation, the @code{@@smallexample} and @code{@@smalllisp}
-commands are defined to be the @code{@@example} and @code{@@lisp}
-commands.@refill
-
-In Info, the @code{@@smallexample} and @code{@@smalllisp} commands are
-equivalent to the @code{@@example} and @code{@@lisp} commands, and work
-exactly the same.@refill
-
-Mark the end of @code{@@smallexample} or @code{@@smalllisp} with
-@code{@@end smallexample} or @code{@@end smalllisp},
-respectively.@refill
+Texinfo has ``small'' example-style commands. These are
+@code{@@smalldisplay}, @code{@@smallexample}, @code{@@smallformat}, and
+@code{@@smalllisp}. All of these commands are designed for use with the
+@code{@@smallbook} command (which causes @TeX{} to format a printed book for
+a 7 by 9.25 inch trim size rather than the default 8.5 by 11 inch size).
+
+In @TeX{}, the @code{@@small@dots{}} commands typeset text in a smaller
+font for the smaller @code{@@smallbook} format than for the 8.5 by 11
+inch format. Consequently, many examples containing long lines fit in a
+narrower, @code{@@smallbook} page without needing to be shortened. Both
+commands typeset in the normal font size when you format for the 8.5 by
+11 inch size. Indeed, in this situation, the @code{@@small@dots{}}
+commands are equivalent to their non-small versions.
+
+In Info, the @code{@@small@dots{}} commands are also equivalent to their
+non-small companion commands.
+
+Mark the end of an @code{@@small@dots{}} block with a corresponding
+@code{@@end small@dots{}}. For example, pair @code{@@smallexample} with
+@code{@@end smallexample}.
@iftex
Here is an example written in the small font used by the
@tex
% Remove extra vskip; this is a kludge to counter the effect of display
\vskip-3\baselineskip
-{\ninett
+{\smalltt
\dots{} to make sure that you have the freedom to
distribute copies of free software (and charge for
this service if you wish), that you receive source
@end smallexample
@end ifinfo
-The @code{@@smallexample} and @code{@@smalllisp} commands make it
-easier to prepare smaller format manuals without forcing you to edit
-examples by hand to fit them onto narrower pages.@refill
+The @code{@@small@dots{}} commands make it easier to prepare smaller
+format manuals without forcing you to edit examples by hand to fit them
+onto narrower pages.@refill
-As a general rule, a printed document looks better if you write all the
-examples in a chapter consistently in @code{@@example} or in
-@code{@@smallexample}. Only occasionally should you mix the two
-formats.@refill
+As a general rule, a printed document looks better if you use only one
+of (for example) @code{@@example} or in @code{@@smallexample}
+consistently within a chapter. Only occasionally should you mix the two
+formats.
@xref{smallbook, , Printing ``Small'' Books}, for more information
about the @code{@@smallbook} command.@refill
-@node display, format, smallexample & smalllisp, Quotations and Examples
-@comment node-name, next, previous, up
-@section @code{@@display}
+
+@node display
+@section @code{@@display} and @code{@@smalldisplay}
@cindex Display formatting
@findex display
indents the text, but does not fill it.
@end display
-@node format, exdent, display, Quotations and Examples
-@comment node-name, next, previous, up
-@section @code{@@format}
+@findex smalldisplay
+Texinfo also provides a command @code{@@smalldisplay}, which is like
+@code{@@display} but uses a smaller font in @code{@@smallbook} format.
+@xref{small}.
+
+
+@node format
+@section @code{@@format} and @code{@@smallformat}
@findex format
The @code{@@format} command is similar to @code{@@example} except
the @code{@@format} command does not fill the text.
@end format
-@node exdent, flushleft & flushright, format, Quotations and Examples
+@findex smallformat
+Texinfo also provides a command @code{@@smallformat}, which is like
+@code{@@format} but uses a smaller font in @code{@@smallbook} format.
+@xref{small}.
+
+
+
+@node exdent
@section @code{@@exdent}: Undoing a Line's Indentation
@cindex Indentation undoing
@findex exdent
write a manual in which one type of example is surrounded by a cartouche
for emphasis.@refill
-The @code{@@cartouche} command affects only the printed manual; it has
-no effect in the Info file.@refill
+@code{@@cartouche} affects only the printed manual; it has no effect in
+other output files.
@need 1500
For example,
* Multi-column Tables:: How to construct generalized tables.
@end menu
-@ifinfo
@node Introducing Lists, itemize, Lists and Tables, Lists and Tables
+@ifinfo
@heading Introducing Lists
@end ifinfo
@item @@table
@itemx @@ftable
@itemx @@vtable
-Two-column tables with indexing.
+Two-column tables, optionally with indexing.
@end table
-@node itemize, enumerate, Introducing Lists, Lists and Tables
-@comment node-name, next, previous, up
-@section Making an Itemized List
+
+@node itemize
+@section @code{@@itemize}: Making an Itemized List
@cindex Itemization
@findex itemize
paragraphs, with a bullet or other mark inside the left margin
at the beginning of each paragraph for which such a mark is desired.@refill
+@cindex @code{@@w}, for blank items
Begin an itemized list by writing @code{@@itemize} at the beginning of
a line. Follow the command, on the same line, with a character or a
Texinfo command that generates a mark. Usually, you will write
@code{@@bullet} after @code{@@itemize}, but you can use
-@code{@@minus}, or any character or any special symbol that results in
-a single character in the Info file. (When you write @code{@@bullet}
-or @code{@@minus} after an @code{@@itemize} command, you may omit the
-@samp{@{@}}.)@refill
+@code{@@minus}, or any command or character that results in a single
+character in the Info file. If you don't want any mark at all, use
+@code{@@w}. (When you write the mark command such as
+@code{@@bullet} after an @code{@@itemize} command, you may omit the
+@samp{@{@}}.) If you don't specify a mark command, the default is
+@code{@@bullet}.
Write the text of the indented paragraphs themselves after the
@code{@@itemize}, up to another line that says @code{@@end
itemize}.@refill
-Before each paragraph for which a mark in the margin is desired, write
-a line that says just @code{@@item}. Do not write any other text on this
-line.@refill
@findex item
+Before each paragraph for which a mark in the margin is desired, write a
+line that says just @code{@@item}. It is ok to have text following the
+@code{@@item}.
Usually, you should put a blank line before an @code{@@item}. This
puts a blank line in the Info file. (@TeX{} inserts the proper
very brief, these blank lines make the list look better.@refill
Here is an example of the use of @code{@@itemize}, followed by the
-output it produces. Note that @code{@@bullet} produces an @samp{*} in
-Info and a round dot in @TeX{}.@refill
+output it produces. @code{@@bullet} produces an @samp{*} in Info and a
+round dot in @TeX{}.
@example
@group
@end itemize
@end quotation
-@node enumerate, Two-column Tables, itemize, Lists and Tables
-@comment node-name, next, previous, up
-@section Making a Numbered or Lettered List
+
+@node enumerate
+@section @code{@@enumerate}: Making a Numbered or Lettered List
@cindex Enumeration
@findex enumerate
list with the number @samp{1}. With a numeric argument, such as
@samp{3}, the command starts the list with that number. With an upper
or lower case letter, such as @samp{a} or @samp{A}, the command starts
-the list with that letter.@refill
+the list with that letter.
Write the text of the enumerated list in the same way you write an
itemized list: put @code{@@item} on a line of its own before the start
of each paragraph that you want enumerated. Do not write any other text
-on the line beginning with @code{@@item}.@refill
+on the line beginning with @code{@@item}.
You should put a blank line between entries in the list.
-This generally makes it easier to read the Info file.@refill
+This generally makes it easier to read the Info file.
@need 1500
-Here is an example of @code{@@enumerate} without an argument:@refill
+Here is an example of @code{@@enumerate} without an argument:
@example
@group
* itemx:: How to put more entries in the first column.
@end menu
-@ifinfo
@node table, ftable vtable, Two-column Tables, Two-column Tables
+@ifinfo
@subheading Using the @code{@@table} Command
Use the @code{@@table} command to produce two-column tables.@refill
listed here. However, you can only use commands that normally take
arguments in braces.)@refill
+@findex item
Begin each table entry with an @code{@@item} command at the beginning
of a line. Write the first column text on the same line as the
@code{@@item} command. Write the second column text on the line
need to type anything for an empty second column entry.) You may
write as many lines of supporting text as you wish, even several
paragraphs. But only text on the same line as the @code{@@item} will
-be placed in the first column.@refill
-@findex item
+be placed in the first column, including any footnote.
Normally, you should put a blank line before an @code{@@item} line.
This puts a blank like in the Info file. Except when the entries are
text, use the @code{@@itemx} command. (@xref{itemx, ,
@code{@@itemx}}.)@refill
-@node ftable vtable, itemx, table, Two-column Tables
-@comment node-name, next, previous, up
+
+@node ftable vtable
@subsection @code{@@ftable} and @code{@@vtable}
@cindex Tables with indexes
@cindex Indexing table entries automatically
the first column of the table into the index of variables. This
simplifies the task of creating indices. Only the items on the same
line as the @code{@@item} commands are indexed, and they are indexed in
-exactly the form that they appear on that line. @xref{Indices, ,
-Creating Indices}, for more information about indices.@refill
+exactly the form that they appear on that line. @xref{Indices},
+for more information about indices.@refill
Begin a two-column table using @code{@@ftable} or @code{@@vtable} by
writing the @@-command at the beginning of a line, followed on the same
See the example for @code{@@table} in the previous section.
-@node itemx, , ftable vtable, Two-column Tables
-@comment node-name, next, previous, up
+@node itemx
@subsection @code{@@itemx}
@cindex Two named items for @code{@@table}
@findex itemx
@code{@@itemx} command works exactly like @code{@@item} except that it
does not generate extra vertical space above the first column text.
-@need 1000
For example,
@example
* Multitable Rows:: Defining multitable rows, with examples.
@end menu
-@node Multitable Column Widths, Multitable Rows, Multi-column Tables, Multi-column Tables
+@node Multitable Column Widths
@subsection Multitable Column Widths
@cindex Multitable column widths
@cindex Column widths, defining for multitables
@@multitable @@columnfractions .33 .33 .33
@end example
-@noindent
-The fractions need not add up exactly to 1.0, as these do
+@noindent The fractions need not add up exactly to 1.0, as these do
not. This allows you to produce tables that do not need the full line
-length.
+length. You can use a leading zero if you wish.
@item
@cindex Prototype row, column widths defined by
@cindex Rows, of a multitable
@findex item
-@cindex tab
+@findex tab
After the @code{@@multitable} command defining the column widths (see
the previous section), you begin each row in the body of a multitable
with @code{@@item}, and separate the column entries with @code{@@tab}.
Here is a complete example of a multi-column table (the text is from
@cite{The GNU Emacs Manual}, @pxref{Split Window,, Splitting Windows,
-xemacs, XEmacs User's Manual}):
+emacs, The GNU Emacs Manual}):
@example
@@multitable @@columnfractions .15 .45 .4
@@end multitable
@end example
-@noindent
-produces:
+@noindent produces:
@multitable @columnfractions .15 .45 .4
@item Key @tab Command @tab Description
@node Indices, Insertions, Lists and Tables, Top
@comment node-name, next, previous, up
-@chapter Creating Indices
+@chapter Indices
@cindex Indices
-@cindex Creating indices
Using Texinfo, you can generate indices without having to sort and
collate entries manually. In an index, the entries are listed in
Whichever case convention you use, please use it consistently!
-@ignore
-Concept index entries consist of English text. The usual convention
-is to capitalize the first word of each such index entry, unless that
-word is the name of a function, variable, or other such entity that
-should not be capitalized. However, if your concept index entries are
-consistently short (one or two words each) it may look better for each
-regular entry to start with a lower case letter, aside from proper
-names and acronyms that always call for upper case letters. Whichever
-convention you adapt, please be consistent!
-@end ignore
-
Entries in indices other than the concept index are symbol names in
programming languages, or program names; these names are usually
case-sensitive, so use upper and lower case as required for them.
@quotation
@strong{Caution:} Do not use a colon in an index entry. In Info, a
-colon separates the menu entry name from the node name. An extra
-colon confuses Info.
-@xref{Menu Parts, , The Parts of a Menu},
-for more information about the structure of a menu entry.@refill
+colon separates the menu entry name from the node name, so a colon in
+the entry itself confuses Info. @xref{Menu Parts, , The Parts of a
+Menu}, for more information about the structure of a menu entry.
@end quotation
-If you write several identical index entries in different places in a
-Texinfo file, the index in the printed manual will list all the pages to
-which those entries refer. However, the index in the Info file will
-list @strong{only} the node that references the @strong{first} of those
-index entries. Therefore, it is best to write indices in which each
-entry refers to only one place in the Texinfo file. Fortunately, this
-constraint is a feature rather than a loss since it means that the index
-will be easy to use. Otherwise, you could create an index that lists
-several pages for one entry and your reader would not know to which page
-to turn. If you have two identical entries for one topic, change the
-topics slightly, or qualify them to indicate the difference.@refill
-
You are not actually required to use the predefined indices for their
canonical purposes. For example, suppose you wish to index some C
preprocessor macros. You could put them in the function index along
line of a Texinfo file, before any @code{@@synindex} or
@code{@@syncodeindex} commands (@pxref{Header}).@refill
-@node Insertions, Breaks, Indices, Top
-@comment node-name, next, previous, up
+@node Insertions
@chapter Special Insertions
@cindex Inserting special characters and symbols
@cindex Special insertions
These are:
@itemize @bullet
-@item Braces, @samp{@@} and periods.
+@item Braces and @samp{@@}.
@item Whitespace within and around a sentence.
@item Accents.
@item Dots and bullets.
@item The @TeX{} logo and the copyright symbol.
+@item The pounds currency symbol.
+@item The minus sign.
@item Mathematical expressions.
+@item Glyphs for evaluation, macros, errors, etc.
+@item Footnotes.
+@item Images.
@end itemize
@end iftex
* math:: How to format a mathematical expression.
* Glyphs:: How to indicate results of evaluation,
expansion of macros, errors, etc.
+* Footnotes:: How to include footnotes.
* Images:: How to include graphics.
@end menu
Do not put braces after an @code{@@@@} command.
-@node Inserting Braces, , Inserting An Atsign, Braces Atsigns
+
+@node Inserting Braces
@subsection Inserting @samp{@{} and @samp{@}}with @@@{ and @@@}
@findex @{ @r{(single @samp{@{})}
@findex @} @r{(single @samp{@}})}
command.
-@node Inserting Space, Inserting Accents, Braces Atsigns, Insertions
+@node Inserting Space
@section Inserting Space
@cindex Inserting space
@cindex Spacing, inserting
-@cindex Whitespace, inserting
The following sections describe commands that control spacing of various
kinds within and after sentences.
* dmn:: How to format a dimension.
@end menu
-@node Not Ending a Sentence, Ending a Sentence, Inserting Space, Inserting Space
+
+@node Not Ending a Sentence
@subsection Not Ending a Sentence
@cindex Not ending a sentence
@cindex Periods, inserting
Depending on whether a period or exclamation point or question mark is
inside or at the end of a sentence, less or more space is inserted after
-a period in a typeset manual. Since it is not always possible for
-Texinfo to determine when a period ends a sentence and when it is used
+a period in a typeset manual. Since it is not always possible
+to determine when a period ends a sentence and when it is used
in an abbreviation, special commands are needed in some circumstances.
-(Usually, Texinfo can guess how to handle periods, so you do not need to
+Usually, Texinfo can guess how to handle periods, so you do not need to
use the special commands; you just enter a period as you would if you
were using a typewriter, which means you put two spaces after the
-period, question mark, or exclamation mark that ends a sentence.)
+period, question mark, or exclamation mark that ends a sentence.
@findex : @r{(suppress widening)}
Use the @code{@@:}@: command after a period, question mark,
For example, use @code{@@:}@: after periods that end abbreviations
which are not at the ends of sentences.
-@need 700
For example,
@example
The meanings of @code{@@:} and @code{@@.}@: in Texinfo are designed to
work well with the Emacs sentence motion commands (@pxref{Sentences,,,
-xemacs, XEmacs User's Manual}). This made it necessary for them to be
-incompatible with some other formatting systems that use @@-commands.
+emacs, The GNU Emacs Manual}).
Do not put braces after any of these commands.
@cindex Multiple spaces
@cindex Whitespace, inserting
+@cindex Space, inserting horizontal
@findex (space)
@findex (tab)
@findex (newline)
example.
@end example
-@noindent
-produces
+@noindent produces
@example
Spacey@ @ @ @
Do not follow any of these commands with braces.
-@node dmn, , Multiple Spaces, Inserting Space
+@node dmn
@subsection @code{@@dmn}@{@var{dimension}@}: Format a Dimension
@cindex Thin space between number, dimension
@cindex Dimension formatting
abbreviation for the dimension. You can use the @code{@@dmn} command
to do this. On seeing the command, @TeX{} inserts just enough space
for proper typesetting; the Info formatting commands insert no space
-at all, since the Info file does not require it.@refill
+at all, since the Info file does not require it.
To use the @code{@@dmn} command, write the number and then follow it
immediately, with no intervening space, by @code{@@dmn}, and then by
the number and the dimension, so use @code{@@w} (@pxref{w}). Also, if
you write a period after an abbreviation within a sentence, you should
write @samp{@@:} after the period to prevent @TeX{} from inserting extra
-whitespace, as shown here. @xref{Inserting Space}.
+whitespace, as shown here. @xref{Not Ending a Sentence}.
-@node Inserting Accents, Dots Bullets, Inserting Space, Insertions
+@node Inserting Accents
@section Inserting Accents
@cindex Inserting accents
@findex dotaccent
@cindex Dot accent
@findex H
-@cindex Hungariam umlaut accent
+@cindex Hungarian umlaut accent
@findex ringaccent
@cindex Ring accent
@findex tieaccent
@cindex Es-zet
@cindex Sharp S
@cindex German S
-@multitable {@@questiondown@{@}} {oe,OE} {es-zet or sharp S}
+@multitable {x@@questiondown@{@} } {oe,OE} {es-zet or sharp S}
@item @t{@@exclamdown@{@}} @tab @exclamdown{} @tab upside-down !
@item @t{@@questiondown@{@}} @tab @questiondown{} @tab upside-down ?
-@item @t{@@aa@{@},@@AA@{@}} @tab @aa{},@AA{} @tab A,a with circle
+@item @t{@@aa@{@},@@AA@{@}} @tab @aa{},@AA{} @tab a,A with circle
@item @t{@@ae@{@},@@AE@{@}} @tab @ae{},@AE{} @tab ae,AE ligatures
@item @t{@@dotless@{i@}} @tab @dotless{i} @tab dotless i
@item @t{@@dotless@{j@}} @tab @dotless{j} @tab dotless j
@item @t{@@l@{@},@@L@{@}} @tab @l{},@L{} @tab suppressed-L,l
@item @t{@@o@{@},@@O@{@}} @tab @o{},@O{} @tab O,o with slash
-@item @t{@@oe@{@},@@OE@{@}} @tab @oe{},@OE{} @tab OE,oe ligatures
+@item @t{@@oe@{@},@@OE@{@}} @tab @oe{},@OE{} @tab oe,OE ligatures
@item @t{@@ss@{@}} @tab @ss{} @tab es-zet or sharp S
@end multitable
-@node Dots Bullets, TeX and copyright, Inserting Accents, Insertions
-@section Inserting Ellipsis, Dots, and Bullets
+@node Dots Bullets
+@section Inserting Ellipsis and Bullets
@cindex Dots, inserting
@cindex Bullets, inserting
@cindex Ellipsis, inserting
@end menu
-@node dots, bullet, Dots Bullets, Dots Bullets
-@subsection @code{@@dots}@{@} (@dots{})
+@node dots
+@subsection @code{@@dots}@{@} (@dots{}) and @code{@@enddots}@{@} (@enddots{})
@findex dots
+@findex enddots
@cindex Inserting dots
@cindex Dots, inserting
@end iftex
-@node bullet, , dots, Dots Bullets
+@node bullet
@subsection @code{@@bullet}@{@} (@bullet{})
@findex bullet
@end menu
-@node tex, copyright symbol, TeX and copyright, TeX and copyright
+@node tex
@subsection @code{@@TeX}@{@} (@TeX{})
@findex tex (command)
manual, this is a special logo that is different from three ordinary
letters. In Info, it just looks like @samp{TeX}. The
@code{@@TeX@{@}} command is unique among Texinfo commands in that the
-@kbd{T} and the @kbd{X} are in upper case.@refill
+@samp{T} and the @samp{X} are in upper case.@refill
-@node copyright symbol, , tex, TeX and copyright
+@node copyright symbol
@subsection @code{@@copyright}@{@} (@copyright{})
@findex copyright
@node pounds, minus, TeX and copyright, Insertions
-@section @code{@@pounds@{@}} (@pounds{}): Pounds Sterling
+@section @code{@@pounds}@{@} (@pounds{}): Pounds Sterling
@findex pounds
Use the @code{@@pounds@{@}} command to generate `@pounds{}'. In a
@node math, Glyphs, minus, Insertions
-@section @code{@@math} - Inserting Mathematical Expressions
+@section @code{@@math}: Inserting Mathematical Expressions
@findex math
@cindex Mathematical expressions
@samp{$} (dollar-signs) as appropriate.
-@node Glyphs, Images, math, Insertions
+@node Glyphs
@section Glyphs for Examples
@cindex Glyphs
@menu
-* result::
-* expansion::
-* Print Glyph::
-* Error Glyph::
-* Equivalence::
-* Point Glyph::
+* result::
+* expansion::
+* Print Glyph::
+* Error Glyph::
+* Equivalence::
+* Point Glyph::
@end menu
@node result, expansion, Glyphs Summary, Glyphs
@cindex Indicating evaluation
@cindex Evaluation glyph
@cindex Value of an expression, indicating
+@findex result
Use the @code{@@result@{@}} command to indicate the result of
evaluating an expression.@refill
@node expansion, Print Glyph, result, Glyphs
@subsection @code{@@expansion@{@}} (@expansion{}): Indicating an Expansion
@cindex Expansion, indicating it
+@findex expansion
When an expression is a macro call, it expands into a new expression.
You can indicate the result of the expansion with the
@node Print Glyph, Error Glyph, expansion, Glyphs
@subsection @code{@@print@{@}} (@print{}): Indicating Printed Output
@cindex Printed output, indicating it
+@findex print
Sometimes an expression will print output during its execution. You
can indicate the printed output with the @code{@@print@{@}} command.@refill
@node Error Glyph, Equivalence, Print Glyph, Glyphs
@subsection @code{@@error@{@}} (@error{}): Indicating an Error Message
@cindex Error message, indicating it
+@findex error
A piece of code may cause an error when you evaluate it. You can
designate the error message with the @code{@@error@{@}} command.@refill
@node Equivalence, Point Glyph, Error Glyph, Glyphs
@subsection @code{@@equiv@{@}} (@equiv{}): Indicating Equivalence
@cindex Equivalence, indicating it
+@findex equiv
Sometimes two expressions produce identical results. You can indicate the
exact equivalence of two forms with the @code{@@equiv@{@}} command.@refill
identical results to evaluating @code{(list 'keymap)}.
-@node Point Glyph, , Equivalence, Glyphs
+@node Point Glyph
@subsection @code{@@point@{@}} (@point{}): Indicating Point in a Buffer
-@cindex Point, indicating it in a buffer
+@cindex Point, indicating in a buffer
+@findex point
Sometimes you need to show an example of text in an Emacs buffer. In
such examples, the convention is to include the entire contents of the
@end example
-@c this should be described with figures when we have them
-@c perhaps in the quotation/example chapter.
-@node Images, , Glyphs, Insertions
-@section Inserting Images
-
-@cindex Images, inserting
-@cindex Pictures, inserting
-@findex image
+@node Footnotes
+@section Footnotes
+@cindex Footnotes
+@findex footnote
-You can insert an image in an external file with the @code{@@image}
-command:
+A @dfn{footnote} is for a reference that documents or elucidates the
+primary text.@footnote{A footnote should complement or expand upon
+the primary text, but a reader should not need to read a footnote to
+understand the primary text. For a thorough discussion of footnotes,
+see @cite{The Chicago Manual of Style}, which is published by the
+University of Chicago Press.}@refill
-@example
-@@image@{@var{filename}, @r{[}@var{width}@r{]}, @r{[}@var{height}@r{]}@}
-@end example
+@menu
+* Footnote Commands:: How to write a footnote in Texinfo.
+* Footnote Styles:: Controlling how footnotes appear in Info.
+@end menu
-@cindex Formats for images
-@cindex Image formats
-The @var{filename} argument is mandatory, and must not have an
-extension, because the different processors support different formats:
-@TeX{} reads the file @file{@var{filename}.eps} (Encapsulated PostScript
-format); @code{makeinfo} uses @file{@var{filename}.txt} verbatim for
-Info output (more or less as if it was an @code{@@example}). HTML
-output requires @file{@var{filename}.jpg}.
+@node Footnote Commands
+@subsection Footnote Commands
-@cindex Width of images
-@cindex Height of images
-@cindex Aspect ratio of images
-@cindex Distorting images
-The optional @var{width} and @var{height} arguments specify the size to
-scale the image to (they are ignored for Info output). If they are both
-specified, the image is presented in its natural size (given in the
-file); if only one is specified, the other is scaled proportionately;
-and if both are specified, both are respected, thus possibly distorting
-the original image by changing its aspect ratio.
+In Texinfo, footnotes are created with the @code{@@footnote} command.
+This command is followed immediately by a left brace, then by the text
+of the footnote, and then by a terminating right brace. Footnotes may
+be of any length (they will be broken across pages if necessary), but
+are usually short. The template is:
-@cindex Dimensions and image sizes
-The @var{width} and @var{height} may be specified using any valid @TeX{}
-dimension, namely:
+@example
+ordinary text@@footnote@{@var{text of footnote}@}
+@end example
-@table @asis
-@item pt
-@cindex Points (dimension)
-point (72.27pt = 1in)
-@item pc
-@cindex Picas
-pica (1pc = 12pt)
-@item bp
-@cindex Big points
-big point (72bp = 1in)
-@item in
-@cindex Inches
-inch
-@item cm
-@cindex Centimeters
-centimeter (2.54cm = 1in)
-@item mm
-@cindex Millimeters
-millimeter (10mm = 1cm)
-@item dd
-@cindex Did@^ot points
-did@^ot point (1157dd = 1238pt)
-@item cc
-@cindex Ciceros
-cicero (1cc = 12dd)
-@item sp
-@cindex Scaled points
-scaled point (65536sp = 1pt)
-@end table
+As shown here, the @code{@@footnote} command should come right after the
+text being footnoted, with no intervening space; otherwise, the footnote
+marker might end up starting a line.
-@pindex ridt.eps
-For example, the following will scale a file @file{ridt.eps} to one
-inch vertically, with the width scaled proportionately:
+For example, this clause is followed by a sample footnote@footnote{Here
+is the sample footnote.}; in the Texinfo source, it looks like
+this:@refill
@example
-@@image@{ridt,,1in@}
+@dots{}a sample footnote@@footnote@{Here is the sample
+footnote.@}; in the Texinfo source@dots{}
@end example
-@pindex epsf.tex
-For @code{@@image} to work with @TeX{}, the file @file{epsf.tex} must be
-installed somewhere that @TeX{} can find it. This file is included in
-the Texinfo distribution and is available from
-@uref{ftp://ftp.tug.org/tex/epsf.tex}.
-
-
-@node Breaks, Definition Commands, Insertions, Top
-@chapter Making and Preventing Breaks
-@cindex Making line and page breaks
-@cindex Preventing line and page breaks
+In a printed manual or book, the reference mark for a footnote is a
+small, superscripted number; the text of the footnote appears at the
+bottom of the page, below a horizontal line.@refill
-Usually, a Texinfo file is processed both by @TeX{} and by one of the
-Info formatting commands. Line, paragraph, or page breaks sometimes
-occur in the `wrong' place in one or other form of output. You must
-ensure that text looks right both in the printed manual and in the
-Info file.@refill
+In Info, the reference mark for a footnote is a pair of parentheses
+with the footnote number between them, like this: @samp{(1)}. The
+reference mark is followed by a cross-reference link to the footnote's
+text.
-For example, in a printed manual, page breaks may occur awkwardly in
-the middle of an example; to prevent this, you can hold text together
-using a grouping command that keeps the text from being split across
-two pages. Conversely, you may want to force a page break where none
-would occur normally. Fortunately, problems like these do not often
-arise. When they do, use the break, break prevention, or pagination
-commands.@refill
+In the HTML output, footnote references are marked with a small,
+superscripted number which is rendered as a hypertext link to the
+footnote text.
-@menu
-* Break Commands:: Cause and prevent splits.
-* Line Breaks:: How to force a single line to use two lines.
-* - and hyphenation:: How to tell TeX about hyphenation points.
-* w:: How to prevent unwanted line breaks.
-* sp:: How to insert blank lines.
-* page:: How to force the start of a new page.
-* group:: How to prevent unwanted page breaks.
-* need:: Another way to prevent unwanted page breaks.
-@end menu
+By the way, footnotes in the argument of an @code{@@item} command for a
+@code{@@table} must be on the same line as the @code{@@item}
+(as usual). @xref{Two-column Tables}.
-@ifinfo
-@node Break Commands, Line Breaks, Breaks, Breaks
-@heading The Break Commands
-@end ifinfo
-@iftex
-@sp 1
-@end iftex
-The break commands create or allow line and paragraph breaks:@refill
+@node Footnote Styles
+@subsection Footnote Styles
-@table @code
-@item @@*
-Force a line break.
+Info has two footnote styles, which determine where the text of the
+footnote is located:@refill
+
+@itemize @bullet
+@cindex @samp{@r{End}} node footnote style
+@item
+In the `End' node style, all the footnotes for a single node
+are placed at the end of that node. The footnotes are separated from
+the rest of the node by a line of dashes with the word
+@samp{Footnotes} within it. Each footnote begins with an
+@samp{(@var{n})} reference mark.@refill
+
+@need 700
+@noindent
+Here is an example of a single footnote in the end of node style:@refill
+
+@example
+@group
+ --------- Footnotes ---------
+
+(1) Here is a sample footnote.
+@end group
+@end example
+
+@cindex @samp{@r{Separate}} footnote style
+@item
+In the `Separate' node style, all the footnotes for a single
+node are placed in an automatically constructed node of
+their own. In this style, a ``footnote reference'' follows
+each @samp{(@var{n})} reference mark in the body of the
+node. The footnote reference is actually a cross reference
+which you use to reach the footnote node.@refill
+
+The name of the node with the footnotes is constructed
+by appending @w{@samp{-Footnotes}} to the name of the node
+that contains the footnotes. (Consequently, the footnotes'
+node for the @file{Footnotes} node is
+@w{@file{Footnotes-Footnotes}}!) The footnotes' node has an
+`Up' node pointer that leads back to its parent node.@refill
+
+@noindent
+Here is how the first footnote in this manual looks after being
+formatted for Info in the separate node style:@refill
+
+@smallexample
+@group
+File: texinfo.info Node: Overview-Footnotes, Up: Overview
+
+(1) The first syllable of "Texinfo" is pronounced like "speck", not
+"hex". @dots{}
+@end group
+@end smallexample
+@end itemize
+
+A Texinfo file may be formatted into an Info file with either footnote
+style.@refill
+
+@findex footnotestyle
+Use the @code{@@footnotestyle} command to specify an Info file's
+footnote style. Write this command at the beginning of a line followed
+by an argument, either @samp{end} for the end node style or
+@samp{separate} for the separate node style.
+
+@need 700
+For example,
+
+@example
+@@footnotestyle end
+@end example
+@noindent
+or
+@example
+@@footnotestyle separate
+@end example
+
+Write an @code{@@footnotestyle} command before or shortly after the
+end-of-header line at the beginning of a Texinfo file. (If you
+include the @code{@@footnotestyle} command between the start-of-header
+and end-of-header lines, the region formatting commands will format
+footnotes as specified.)@refill
+
+If you do not specify a footnote style, the formatting commands use
+their default style. Currently, @code{texinfo-format-buffer} and
+@code{texinfo-format-region} use the `separate' style and
+@code{makeinfo} uses the `end' style.@refill
+
+@c !!! note: makeinfo's --footnote-style option overrides footnotestyle
+@ignore
+If you use @code{makeinfo} to create the Info file, the
+@samp{--footnote-style} option determines which style is used,
+@samp{end} for the end of node style or @samp{separate} for the
+separate node style. Thus, to format the Texinfo manual in the
+separate node style, you would use the following shell command:@refill
+
+@example
+makeinfo --footnote-style=separate texinfo.texi
+@end example
+
+@noindent
+To format the Texinfo manual in the end of node style, you would
+type:@refill
+
+@example
+makeinfo --footnote-style=end texinfo.texi
+@end example
+@end ignore
+@ignore
+If you use @code{texinfo-format-buffer} or
+@code{texinfo-format-region} to create the Info file, the value of the
+@code{texinfo-footnote-style} variable controls the footnote style.
+It can be either @samp{"separate"} for the separate node style or
+@samp{"end"} for the end of node style. (You can change the value of
+this variable with the @kbd{M-x edit-options} command (@pxref{Edit
+Options, , Editing Variable Values, emacs, The GNU Emacs Manual}), or
+with the @kbd{M-x set-variable} command (@pxref{Examining, , Examining
+and Setting Variables, emacs, The GNU Emacs Manual}).@refill
+
+The @code{texinfo-footnote-style} variable also controls the style if
+you use the @kbd{M-x makeinfo-region} or @kbd{M-x makeinfo-buffer}
+command in Emacs.@refill
+@end ignore
+@ifinfo
+This chapter contains two footnotes.@refill
+@end ifinfo
+
+
+@c this should be described with figures when we have them
+@c perhaps in the quotation/example chapter.
+@node Images
+@section Inserting Images
+
+@cindex Images, inserting
+@cindex Pictures, inserting
+@findex image
+
+You can insert an image given in an external file with the
+@code{@@image} command:
+
+@example
+@@image@{@var{filename}, @r{[}@var{width}@r{]}, @r{[}@var{height}@r{]}@}
+@end example
+
+@cindex Formats for images
+@cindex Image formats
+The @var{filename} argument is mandatory, and must not have an
+extension, because the different processors support different formats:
+@itemize @bullet
+@item
+@TeX{} reads the file @file{@var{filename}.eps} (Encapsulated PostScript
+format).
+@item
+@pindex pdftex@r{, and images}
+PDF@TeX{} reads @file{@var{filename}.pdf} (Adobe's Portable Document Format).
+@item
+@code{makeinfo} uses @file{@var{filename}.txt} verbatim for
+Info output (more or less as if it was an @code{@@example}).
+@item
+@cindex GIF, unsupported due to patents
+@cindex PNG image format
+@cindex JPEG image format
+@code{makeinfo} producing HTML output tries @file{@var{filename}.png};
+if that does not exist, it tries @file{@var{filename}.jpg}. If that
+does not exist either, it complains. (We cannot support GIF format due
+to patents.)
+@end itemize
+
+@cindex Width of images
+@cindex Height of images
+@cindex Aspect ratio of images
+@cindex Distorting images
+The optional @var{width} and @var{height} arguments specify the size to
+scale the image to (they are ignored for Info output). If neither is
+specified, the image is presented in its natural size (given in the
+file); if only one is specified, the other is scaled proportionately;
+and if both are specified, both are respected, thus possibly distorting
+the original image by changing its aspect ratio.
+
+@cindex Dimensions and image sizes
+The @var{width} and @var{height} may be specified using any valid @TeX{}
+dimension, namely:
+
+@table @asis
+@item pt
+@cindex Points (dimension)
+point (72.27pt = 1in)
+@item pc
+@cindex Picas
+pica (1pc = 12pt)
+@item bp
+@cindex Big points
+big point (72bp = 1in)
+@item in
+@cindex Inches
+inch
+@item cm
+@cindex Centimeters
+centimeter (2.54cm = 1in)
+@item mm
+@cindex Millimeters
+millimeter (10mm = 1cm)
+@item dd
+@cindex Did@^ot points
+did@^ot point (1157dd = 1238pt)
+@item cc
+@cindex Ciceros
+cicero (1cc = 12dd)
+@item sp
+@cindex Scaled points
+scaled point (65536sp = 1pt)
+@end table
+
+@pindex ridt.eps
+For example, the following will scale a file @file{ridt.eps} to one
+inch vertically, with the width scaled proportionately:
+
+@example
+@@image@{ridt,,1in@}
+@end example
+
+@pindex epsf.tex
+For @code{@@image} to work with @TeX{}, the file @file{epsf.tex} must be
+installed somewhere that @TeX{} can find it. (The standard location is
+@file{@var{texmf}/tex/generic/dvips/epsf.tex}, where @var{texmf} is a
+root of your @TeX{} directory tree.) This file is included in the
+Texinfo distribution and is available from
+@uref{ftp://tug.org/tex/epsf.tex}.
+
+@code{@@image} can be used within a line as well as for displayed
+figures. Therefore, if you intend it to be displayed, be sure to leave
+a blank line before the command, or the output will run into the
+preceding text.
+
+
+@node Breaks
+@chapter Making and Preventing Breaks
+@cindex Making line and page breaks
+@cindex Preventing line and page breaks
+
+Usually, a Texinfo file is processed both by @TeX{} and by one of the
+Info formatting commands. Line, paragraph, or page breaks sometimes
+occur in the `wrong' place in one or other form of output. You must
+ensure that text looks right both in the printed manual and in the
+Info file.@refill
+
+For example, in a printed manual, page breaks may occur awkwardly in
+the middle of an example; to prevent this, you can hold text together
+using a grouping command that keeps the text from being split across
+two pages. Conversely, you may want to force a page break where none
+would occur normally. Fortunately, problems like these do not often
+arise. When they do, use the break, break prevention, or pagination
+commands.@refill
+
+@menu
+* Break Commands:: Cause and prevent splits.
+* Line Breaks:: How to force a single line to use two lines.
+* - and hyphenation:: How to tell TeX about hyphenation points.
+* w:: How to prevent unwanted line breaks.
+* sp:: How to insert blank lines.
+* page:: How to force the start of a new page.
+* group:: How to prevent unwanted page breaks.
+* need:: Another way to prevent unwanted page breaks.
+@end menu
+
+@node Break Commands, Line Breaks, Breaks, Breaks
+@ifinfo
+@heading Break Commands
+@end ifinfo
+
+The break commands create or allow line and paragraph breaks:@refill
+
+@table @code
+@item @@*
+Force a line break.
@item @@sp @var{n}
Skip @var{n} blank lines.@refill
@example
@@hyphenation@{man-u-script man-u-scripts@}
@end example
-@noindent
-@TeX{} only uses the specified hyphenation points when the
+@noindent @TeX{} only uses the specified hyphenation points when the
words match exactly, so give all necessary variants.
@end table
Info output is not hyphenated, so these commands have no effect there.
-@node w, sp, - and hyphenation, Breaks
-@comment node-name, next, previous, up
+@node w
@section @code{@@w}@{@var{text}@}: Prevent Line Breaks
@findex w @r{(prevent line break)}
@cindex Line breaks, preventing
You can use the @code{@@w} command to prevent @TeX{} from automatically
hyphenating a long name or phrase that happens to fall near the end of a
-line.@refill
+line. For example:
@example
-You can copy GNU software from @@w@{@@samp@{ftp.gnu.ai.mit.edu@}@}.
+You can copy GNU software from @@w@{@@samp@{ftp.gnu.org@}@}.
@end example
@noindent
produces
@quotation
-You can copy GNU software from @w{@samp{ftp.gnu.ai.mit.edu}}.
+You can copy GNU software from @w{@samp{ftp.gnu.org}}.
@end quotation
-@quotation
-@strong{Caution:} Do not write an @code{@@refill} command at the end
-of a paragraph containing an @code{@@w} command; it will cause the
-paragraph to be refilled and may thereby negate the effect of the
-@code{@@w} command.@refill
-@end quotation
+@cindex Non-breakable space
+@cindex Unbreakable space
+@cindex Tied space
+You can also use @code{@@w} to produce a non-breakable space:
-@node sp, page, w, Breaks
-@comment node-name, next, previous, up
+@example
+None of the formatters will break at this@@w@{ @}space.
+@end example
+
+
+@node sp
@section @code{@@sp} @var{n}: Insert Blank Lines
@findex sp @r{(line spacing)}
-@cindex Spaces (blank lines)
+@cindex Space, inserting vertical
@cindex Blank lines
@cindex Line spacing
A line beginning with and containing only @code{@@sp @var{n}}
generates @var{n} blank lines of space in both the printed manual and
the Info file. @code{@@sp} also forces a paragraph break. For
-example,@refill
+example,
@example
@@sp 2
The @code{@@need} command is useful for preventing orphans (single
lines at the bottoms of printed pages).@refill
-@node Definition Commands, Footnotes, Breaks, Top
+
+@node Definition Commands
@chapter Definition Commands
@cindex Definition commands
These two search commands are similar except @dots{}
@end deffn
-Each of the other definition commands has an `x' form: @code{@@defunx},
+Each definition command has an `x' form: @code{@@defunx},
@code{@@defvrx}, @code{@@deftypefunx}, etc.
The `x' forms work just like @code{@@itemx}; see @ref{itemx, , @code{@@itemx}}.
@item @@defspec @var{name} @var{arguments}@dots{}
The @code{@@defspec} command is the definition command for special
forms. (In Lisp, a special form is an entity much like a function,
-@pxref{Special Forms,,, lispref, XEmacs Lisp Reference Manual}.)
+@pxref{Special Forms,,, elisp, GNU Emacs Lisp Reference Manual}.)
@code{@@defspec} is equivalent to @samp{@@deffn @{Special Form@}
@dots{}} and works like @code{@@defun}.@refill
@end table
choose a term to describe the category of entity being defined; for
example, ``Variable'' could be used if the entity is a variable.
Write the @code{@@defvr} command at the beginning of a line and
-followed it on the same line by the category of the entity and the
-name of the entity.@refill
+follow it on the same line by the category of the entity and the
+name of the entity.
Capitalize the category name like a title. If the name of the category
contains spaces, as in the name ``User Option'', enclose it in braces.
@cindex User options, marking
The @code{@@defopt} command is the definition command for @dfn{user
options}, i.e., variables intended for users to change according to
-taste; Emacs has many such (@pxref{Variables,,, xemacs, XEmacs User's
+taste; Emacs has many such (@pxref{Variables,,, emacs, The GNU Emacs
Manual}). @code{@@defopt} is equivalent to @samp{@@defvr @{User
Option@} @dots{}} and works like @code{@@defvar}.@refill
@end table
@var{name}.@refill
@end table
-@node Abstract Objects, Data Types, Typed Variables, Def Cmds in Detail
+@node Abstract Objects
@subsection Object-Oriented Programming
Here are the commands for formatting descriptions about abstract
illustrates how you would write the first line of a definition of the
@code{border-pattern} class option of the class @code{Window}.@refill
-The template is
-
+The template is:
@example
@group
@@defcv @var{category} @var{class} @var{name}
equivalent to @samp{@@defcv @{Instance Variable@} @dots{}}@refill
The template is:
-
@example
@group
@@defivar @var{class} @var{instance-variable-name}
@code{@@defivar} creates an entry in the index of variables.
+@findex deftypeivar
+@item @@deftypeivar @var{class} @var{data-type} @var{name}
+The @code{@@deftypeivar} command is the definition command for typed
+instance variables in object-oriented programming. It is similar to
+@code{@@defivar} with the addition of the @var{data-type} parameter to
+specify the type of the instance variable. @code{@@deftypeivar} creates an
+entry in the index of variables.
+
@findex defop
@item @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{}
The @code{@@defop} command is the general definition command for
entities that may resemble methods in object-oriented programming.
-These entities take arguments, as functions do, but are associated
-with particular classes of objects.@refill
+These entities take arguments, as functions do, but are associated with
+particular classes of objects.@refill
For example, some systems have constructs called @dfn{wrappers} that
are associated with classes as methods are, but that act more like
operation, the name of the class of the operation, the name of the
operation, and its arguments, if any.@refill
-@need 800
-@noindent
The template is:
-
@example
@group
@@defop @var{category} @var{class} @var{name} @var{arguments}@dots{}
@code{@@defop} creates an entry, such as `@code{expose} on
@code{windows}', in the index of functions.@refill
+@findex deftypeop
+@item @@deftypeop @var{category} @var{class} @var{data-type} @var{name} @var{arguments}@dots{}
+The @code{@@deftypeop} command is the definition command for typed
+operations in object-oriented programming. It is similar to
+@code{@@defop} with the addition of the @var{data-type} parameter to
+specify the return type of the method. @code{@@deftypeop} creates an
+entry in the index of functions.
+
@item @@defmethod @var{class} @var{name} @var{arguments}@dots{}
@findex defmethod
The @code{@@defmethod} command is the definition command for methods
in object-oriented programming. A method is a kind of function that
implements an operation for a particular class of objects and its
-subclasses. In the Lisp Machine, methods actually were functions, but
+subclasses.
+@ignore
+@c ADR: Who cares?!?
+@c KB: Oh, I don't know, I think this info is crucial!
+In the Lisp Machine, methods actually were functions, but
they were usually defined with @code{defmethod}.
+@end ignore
@code{@@defmethod} is equivalent to @samp{@@defop Method @dots{}}.
The command is written at the beginning of a line and is followed by
the name of the class of the method, the name of the method, and its
arguments, if any.@refill
-@need 800
@noindent
-For example,
-
+For example:
@example
@group
@@defmethod @code{bar-class} bar-method argument
@code{@@defmethod} creates an entry, such as `@code{bar-method} on
@code{bar-class}', in the index of functions.@refill
+
@item @@deftypemethod @var{class} @var{data-type} @var{name} @var{arguments}@dots{}
@findex defmethod
The @code{@@deftypemethod} command is the definition command for methods
@end table
-@node Data Types, , Abstract Objects, Def Cmds in Detail
+@node Data Types
@subsection Data Types
Here is the command for data types:@refill
@code{@@defun} command and it is followed, on the same line, by the
parameter list.@refill
-Here is a definition from @ref{Calling Functions,,, lispref, XEmacs Lisp
-Reference Manual}.
+Here is a definition from @ref{Calling Functions,,, elisp, The GNU Emacs
+Lisp Reference Manual}.
@quotation
@defun apply function &rest arguments
@example
@group
@@defun apply function &rest arguments
-
@@code@{apply@} calls @@var@{function@} with
@@var@{arguments@}, just like @@code@{funcall@} but with one
difference: the last of @@var@{arguments@} is a list of
@group
An interesting example of using @@code@{apply@} is found
-in the description of @@code@{mapcar@}.@@refill
+in the description of @@code@{mapcar@}.
@@end defun
@end group
@end example
that for functions except that variables do not take arguments.
-@node Footnotes, Conditionals, Definition Commands, Top
-@chapter Footnotes
-@cindex Footnotes
-@findex footnote
-
-A @dfn{footnote} is for a reference that documents or elucidates the
-primary text.@footnote{A footnote should complement or expand upon
-the primary text, but a reader should not need to read a footnote to
-understand the primary text. For a thorough discussion of footnotes,
-see @cite{The Chicago Manual of Style}, which is published by the
-University of Chicago Press.}@refill
-
-@menu
-* Footnote Commands:: How to write a footnote in Texinfo.
-* Footnote Styles:: Controlling how footnotes appear in Info.
-@end menu
-
-@node Footnote Commands, Footnote Styles, Footnotes, Footnotes
-@section Footnote Commands
-
-In Texinfo, footnotes are created with the @code{@@footnote} command.
-This command is followed immediately by a left brace, then by the text
-of the footnote, and then by a terminating right brace. Footnotes may
-be of any length (they will be broken across pages if necessary), but
-are usually short. The template is:
-
-@example
-ordinary text@@footnote@{@var{text of footnote}@}
-@end example
-
-As shown here, the @code{@@footnote} command should come right after the
-text being footnoted, with no intervening space; otherwise, the
-formatters the footnote mark might end up starting up a line.
-
-For example, this clause is followed by a sample
-footnote@footnote{Here is the sample footnote.}; in the Texinfo
-source, it looks like this:@refill
-
-@example
-@dots{}a sample footnote@@footnote@{Here is the sample
-footnote.@}; in the Texinfo source@dots{}
-@end example
-
-@strong{Warning:} Don't use footnotes in the argument of the
-@code{@@item} command for a @code{@@table} table. This doesn't work, and
-because of limitations of @TeX{}, there is no way to fix it. You must
-put the footnote into the body text of the table.
-
-In a printed manual or book, the reference mark for a footnote is a
-small, superscripted number; the text of the footnote appears at the
-bottom of the page, below a horizontal line.@refill
-
-In Info, the reference mark for a footnote is a pair of parentheses
-with the footnote number between them, like this: @samp{(1)}.@refill
+@node Conditionals
+@chapter Conditionally Visible Text
+@cindex Conditionally visible text
+@cindex Text, conditionally visible
+@cindex Visibility of conditional text
+@cindex If text conditionally visible
+Sometimes it is good to use different text for different output formats.
+For example, you can use the @dfn{conditional commands} to specify
+different text for the printed manual and the Info output.
-@node Footnote Styles, , Footnote Commands, Footnotes
-@section Footnote Styles
+Conditional commands may not be nested.
-Info has two footnote styles, which determine where the text of the
-footnote is located:@refill
+The conditional commands comprise the following categories.
@itemize @bullet
-@cindex @samp{@r{End}} node footnote style
+@item Commands for HTML, Info, or @TeX{}.
+@item Commands for not HTML, Info, or @TeX{}.
+@item Raw @TeX{} or HTML commands.
@item
-In the `End' node style, all the footnotes for a single node
-are placed at the end of that node. The footnotes are separated from
-the rest of the node by a line of dashes with the word
-@samp{Footnotes} within it. Each footnote begins with an
-@samp{(@var{n})} reference mark.@refill
-
-@need 700
-@noindent
-Here is an example of a single footnote in the end of node style:@refill
-
-@example
-@group
- --------- Footnotes ---------
-
-(1) Here is a sample footnote.
-@end group
-@end example
-
-@cindex @samp{@r{Separate}} footnote style
-@item
-In the `Separate' node style, all the footnotes for a single
-node are placed in an automatically constructed node of
-their own. In this style, a ``footnote reference'' follows
-each @samp{(@var{n})} reference mark in the body of the
-node. The footnote reference is actually a cross reference
-which you use to reach the footnote node.@refill
-
-The name of the node containing the footnotes is constructed
-by appending @w{@samp{-Footnotes}} to the name of the node
-that contains the footnotes. (Consequently, the footnotes'
-node for the @file{Footnotes} node is
-@w{@file{Footnotes-Footnotes}}!) The footnotes' node has an
-`Up' node pointer that leads back to its parent node.@refill
-
-@noindent
-Here is how the first footnote in this manual looks after being
-formatted for Info in the separate node style:@refill
-
-@smallexample
-@group
-File: texinfo.info Node: Overview-Footnotes, Up: Overview
-
-(1) Note that the first syllable of "Texinfo" is
-pronounced like "speck", not "hex". @dots{}
-@end group
-@end smallexample
+Substituting text for all formats, and testing if a flag is set or clear.
@end itemize
-A Texinfo file may be formatted into an Info file with either footnote
-style.@refill
-
-@findex footnotestyle
-Use the @code{@@footnotestyle} command to specify an Info file's
-footnote style. Write this command at the beginning of a line followed
-by an argument, either @samp{end} for the end node style or
-@samp{separate} for the separate node style.
-
-@need 700
-For example,
-
-@example
-@@footnotestyle end
-@end example
-@noindent
-or
-@example
-@@footnotestyle separate
-@end example
-
-Write an @code{@@footnotestyle} command before or shortly after the
-end-of-header line at the beginning of a Texinfo file. (If you
-include the @code{@@footnotestyle} command between the start-of-header
-and end-of-header lines, the region formatting commands will format
-footnotes as specified.)@refill
-
-If you do not specify a footnote style, the formatting commands use
-their default style. Currently, @code{texinfo-format-buffer} and
-@code{texinfo-format-region} use the `separate' style and
-@code{makeinfo} uses the `end' style.@refill
-
-@c !!! note: makeinfo's --footnote-style option overrides footnotestyle
-@ignore
-If you use @code{makeinfo} to create the Info file, the
-@samp{--footnote-style} option determines which style is used,
-@samp{end} for the end of node style or @samp{separate} for the
-separate node style. Thus, to format the Texinfo manual in the
-separate node style, you would use the following shell command:@refill
-
-@example
-makeinfo --footnote-style=separate texinfo.texi
-@end example
-
-@noindent
-To format the Texinfo manual in the end of node style, you would
-type:@refill
-
-@example
-makeinfo --footnote-style=end texinfo.texi
-@end example
-@end ignore
-@ignore
-If you use @code{texinfo-format-buffer} or
-@code{texinfo-format-region} to create the Info file, the value of the
-@code{texinfo-footnote-style} variable controls the footnote style.
-It can be either @samp{"separate"} for the separate node style or
-@samp{"end"} for the end of node style. (You can change the value of
-this variable with the @kbd{M-x edit-options} command (@pxref{Edit
-Options, , Editing Variable Values, xemacs, XEmacs User's Manual}), or
-with the @kbd{M-x set-variable} command (@pxref{Examining, , Examining
-and Setting Variables, xemacs, XEmacs User's Manual}).@refill
-
-The @code{texinfo-footnote-style} variable also controls the style if
-you use the @kbd{M-x makeinfo-region} or @kbd{M-x makeinfo-buffer}
-command in Emacs.@refill
-@end ignore
-This chapter contains two footnotes.@refill
-
-
-@node Conditionals, Macros, Footnotes, Top
-@comment node-name, next, previous, up
-@chapter Conditionally Visible Text
-@cindex Conditionally visible text
-@cindex Text, conditionally visible
-@cindex Visibility of conditional text
-@cindex If text conditionally visible
-
-Sometimes it is good to use different text for a printed manual and
-its corresponding Info file. In this case, you can use the
-@dfn{conditional commands} to specify which text is for the printed manual
-and which is for the Info file.@refill
-
@menu
* Conditional Commands:: Specifying text for HTML, Info, or @TeX{}.
* Conditional Not Commands:: Specifying text for not HTML, Info, or @TeX{}.
flag to a string that you can insert.
@end menu
-@node Conditional Commands, Conditional Not Commands, Conditionals, Conditionals
-@ifinfo
-@heading Conditional Commands
-@end ifinfo
+
+@node Conditional Commands
+@section Conditional Commands
@findex ifinfo
-@code{@@ifinfo} begins segments of text that should be ignored
-by @TeX{} when it
-typesets the printed manual. The segment of text appears only
-in the Info file.
-The @code{@@ifinfo} command should appear on a line by itself; end
-the Info-only text with a line containing @code{@@end ifinfo} by
-itself. At the beginning of a Texinfo file, the Info permissions are
-contained within a region marked by @code{@@ifinfo} and @code{@@end
-ifinfo}. (@xref{Info Summary and Permissions}.)@refill
+@code{@@ifinfo} begins segments of text that should be ignored by @TeX{}
+when it typesets the printed manual. The segment of text appears only
+in the Info file. The @code{@@ifinfo} command should appear on a line
+by itself; end the Info-only text with a line containing @code{@@end
+ifinfo} by itself. At the beginning of a Texinfo file, the Info
+permissions are contained within a region marked by @code{@@ifinfo} and
+@code{@@end ifinfo}. (@xref{Info Summary and Permissions}.)
@findex iftex
@findex ifhtml
@@ifinfo
However, this text will appear only in Info.
@@end ifinfo
+@@ifhtml
+And this text will only appear in HTML.
+@@end ifhtml
@end example
@noindent
@ifinfo
However, this text will appear only in Info.
@end ifinfo
+@ifhtml
+And this text will only appear in HTML.
+@end ifhtml
@noindent
-Note how you only see one of the two lines, depending on whether you
-are reading the Info version or the printed version of this
-manual.@refill
+Notice that you only see one of the input lines, depending on which
+version of the manual you are reading.
-The @code{@@titlepage} command is a special variant of @code{@@iftex} that
-is used for making the title and copyright pages of the printed
-manual. (@xref{titlepage, , @code{@@titlepage}}.) @refill
-
-@node Conditional Not Commands, Raw Formatter Commands, Conditional Commands, Conditionals
+@node Conditional Not Commands
@section Conditional Not Commands
@findex ifnothtml
@findex ifnotinfo
included. Otherwise, it is ignored.
The regions delimited by these commands are ordinary Texinfo source as
-with @code{@@iftex}, not raw formatter source as with @code{@@tex}.
+with @code{@@iftex}, not raw formatter source as with @code{@@tex}
+(@pxref{Raw Formatter Commands}).
@node Raw Formatter Commands, set clear value, Conditional Not Commands, Conditionals
You can enter plain @TeX{} completely, and use @samp{\} in the @TeX{}
commands, by delineating a region with the @code{@@tex} and @code{@@end
tex} commands. (The @code{@@tex} command also causes Info to ignore the
-region, like the @code{@@iftex} command.) The sole exception is that
-@code{@@} chracter still introduces a command, so that @code{@@end tex}
+region, like the @code{@@iftex} command.) The sole exception is that the
+@code{@@} character still introduces a command, so that @code{@@end tex}
can be recognized properly.
@cindex Mathematical expressions
@findex html
Analogously, you can use @code{@@ifhtml @dots{} @@end ifhtml} to delimit
a region to be included in HTML output only, and @code{@@html @dots{}
-@@end ifhtml} for a region of raw HTML (again, except that @code{@@} is
+@@end html} for a region of raw HTML (again, except that @code{@@} is
still the escape character, so the @code{@@end} command can be
recognized.)
-@node set clear value, , Raw Formatter Commands, Conditionals
-@comment node-name, next, previous, up
+@node set clear value
@section @code{@@set}, @code{@@clear}, and @code{@@value}
You can direct the Texinfo formatting commands to format or ignore parts
@menu
* ifset ifclear:: Format a region if a flag is set.
-* value:: Replace a flag with a string.
+* set value:: Expand a flag variable to a string.
* value Example:: An easy way to update edition information.
@end menu
-@node ifset ifclear, value, set clear value, set clear value
+@node ifset ifclear
@subsection @code{@@ifset} and @code{@@ifclear}
@findex ifset
commands do @emph{not} format the text.
Use the @code{@@set @var{flag}} command to turn on, or @dfn{set}, a
-@var{flag}; a @dfn{flag} can be any single word. The format for the
-command looks like this:@refill
+@var{flag}; a @dfn{flag} name can be any single word, containing
+letters, numerals, hyphens, or underscores.
+
+The format for the command looks like this:@refill
@findex set
@example
command.@refill
@end table
-@node value, value Example, ifset ifclear, set clear value
-@subsection @code{@@value}
+
+@node set value
+@subsection @code{@@set} and @code{@@value}
@findex value
You can use the @code{@@set} command to specify a value for a flag,
-which is expanded by the @code{@@value} command. The value is a string
-a characters.
+which is expanded by the @code{@@value} command. A flag is an
+identifier; for best results, use only letters and numerals in a flag
+name, not @samp{-} or @samp{_}---they will work in some contexts, but
+not all, due to limitations in @TeX{}. The value is just a string of
+characters, the remainder of the input line.
Write the @code{@@set} command like this:
@end example
@noindent
-This sets the value of @code{foo} to ``This is a string.''
+This sets the value of the flag @code{foo} to ``This is a string.''.
-The Texinfo formatters replace an @code{@@value@{@var{flag}@}} command with
-the string to which @var{flag} is set.@refill
-
-Thus, when @code{foo} is set as shown above, the Texinfo formatters convert
+The Texinfo formatters then replace an @code{@@value@{@var{flag}@}}
+command with the string to which @var{flag} is set. Thus, when
+@code{foo} is set as shown above, the Texinfo formatters convert
@example
@group
@noindent
without specifying a string, the value of @code{foo} is an empty string.
-If you clear a previously set flag with an @code{@@clear @var{flag}}
-command, a subsequent @code{@@value@{flag@}} command is invalid and the
-string is replaced with an error message that says @samp{@{No value for
+If you clear a previously set flag with @code{@@clear @var{flag}}, a
+subsequent @code{@@value@{flag@}} command is invalid and the string is
+replaced with an error message that says @samp{@{No value for
"@var{flag}"@}}.
For example, if you set @code{foo} as follows:@refill
@end group
@end example
-@node value Example, , value, set clear value
+
+@node value Example
@subsection @code{@@value} Example
You can use the @code{@@value} command to limit the number of places you
-need to change when you record an update to a manual.
-Here is how it is done in @cite{The GNU Make Manual}:
+need to change when you record an update to a manual. Here is how it is
+done in @cite{The GNU Make Manual}:
-@need 1000
-@noindent
+@enumerate
+@item
Set the flags:
@example
@end group
@end example
-@need 750
-@noindent
+@item
Write text for the first @code{@@ifinfo} section, for people reading the
Texinfo file:
This is Edition @@value@{EDITION@},
last updated @@value@{UPDATED@},
of @@cite@{The GNU Make Manual@},
-for @@code@{make@}, Version @@value@{VERSION@}.
+for @@code@{make@}, version @@value@{VERSION@}.
@end group
@end example
-@need 1000
-@noindent
+@item
Write text for the title page, for people reading the printed manual:
@c List only the month and the year since that looks less fussy on a
@c printed cover than a date that lists the day as well.
(On a printed cover, a date listing the month and the year looks less
fussy than a date listing the day as well as the month and year.)
-@need 750
-@noindent
+@item
Write text for the Top node, for people reading the Info file:
@example
@end group
@end example
-@need 950
After you format the manual, the text in the first @code{@@ifinfo}
section looks like this:
of `The GNU Make Manual', for `make', Version 3.63 Beta.
@end group
@end example
+@end enumerate
When you update the manual, change only the values of the flags; you do
-not need to rewrite the three sections.
+not need to edit the three sections.
+
+
+@node Internationalization
+@chapter Internationalization
+
+@cindex Internationalization
+Texinfo has some support for writing in languages other than English,
+although this area still needs considerable work.
+For a list of the various accented and special characters Texinfo
+supports, see @ref{Inserting Accents}.
-@node Macros, Format/Print Hardcopy, Conditionals, Top
-@chapter Macros: Defining New Texinfo Commands
+@menu
+* documentlanguage:: Declaring the current language.
+* documentencoding:: Declaring the input encoding.
+@end menu
+
+
+@node documentlanguage
+@section @code{@@documentlanguage @var{cc}}: Set the Document Language
+
+@findex documentlanguage
+@cindex Language, declaring
+@cindex Document language, declaring
+
+The @code{@@documentlanguage} command declares the current document
+language. Write it on a line by itself, with a two-letter ISO-639
+language code following (list is included below). If you have a
+multilingual document, the intent is to be able to use this command
+multiple times, to declare each language change. If the command is not
+used at all, the default is @code{en} for English.
+
+@cindex @file{txi-@var{cc}.tex}
+At present, this command is ignored in Info and HTML output. For
+@TeX{}, it causes the file @file{txi-@var{cc}.tex} to be read (if it
+exists). Such a file appropriately redefines the various English words
+used in @TeX{} output, such as `Chapter', `See', and so on.
+
+@cindex Hyphenation patterns, language-dependent
+It would be good if this command also changed @TeX{}'s ideas of the
+current hyphenation patterns (via the @TeX{} primitive
+@code{\language}), but this is unfortunately not currently implemented.
+
+@cindex ISO 639 codes
+@cindex Language codes
+@cindex African languages
+Here is the list of valid language codes. This list comes from
+@uref{http://www.iro.umontreal.ca/contrib/po/iso-639, the free
+translation project}. In the future we may wish to allow the 3-letter
+POV codes described at @uref{http://www.sil.org/ethnologue/#contents}.
+This will be necessary to support African languages.
+
+@multitable @columnfractions .06 .27 .06 .27 .06 .27
+@item
+@code{aa} @tab Afar @tab
+@code{ab} @tab Abkhazian @tab
+@code{af} @tab Afrikaans
+@item
+@code{am} @tab Amharic @tab
+@code{ar} @tab Arabic @tab
+@code{as} @tab Assamese
+@item
+@code{ay} @tab Aymara @tab
+@code{az} @tab Azerbaijani @tab
+@code{ba} @tab Bashkir
+@item
+@code{be} @tab Byelorussian @tab
+@code{bg} @tab Bulgarian @tab
+@code{bh} @tab Bihari
+@item
+@code{bi} @tab Bislama @tab
+@code{bn} @tab Bengali; Bangla @tab
+@code{bo} @tab Tibetan
+@item
+@code{br} @tab Breton @tab
+@code{ca} @tab Catalan @tab
+@code{co} @tab Corsican
+@item
+@code{cs} @tab Czech @tab
+@code{cy} @tab Welsh @tab
+@code{da} @tab Danish
+@item
+@code{de} @tab German @tab
+@code{dz} @tab Bhutani @tab
+@code{el} @tab Greek
+@item
+@code{en} @tab English @tab
+@code{eo} @tab Esperanto @tab
+@code{es} @tab Spanish
+@item
+@code{et} @tab Estonian @tab
+@code{eu} @tab Basque @tab
+@code{fa} @tab Persian
+@item
+@code{fi} @tab Finnish @tab
+@code{fj} @tab Fiji @tab
+@code{fo} @tab Faroese
+@item
+@code{fr} @tab French @tab
+@code{fy} @tab Frisian @tab
+@code{ga} @tab Irish
+@item
+@code{gd} @tab Scots Gaelic @tab
+@code{gl} @tab Galician @tab
+@code{gn} @tab Guarani
+@item
+@code{gu} @tab Gujarati @tab
+@code{ha} @tab Hausa @tab
+@code{he} @tab Hebrew
+@item
+@code{hi} @tab Hindi @tab
+@code{hr} @tab Croatian @tab
+@code{hu} @tab Hungarian
+@item
+@code{hy} @tab Armenian @tab
+@code{ia} @tab Interlingua @tab
+@code{id} @tab Indonesian
+@item
+@code{ie} @tab Interlingue @tab
+@code{ik} @tab Inupiak @tab
+@code{is} @tab Icelandic
+@item
+@code{it} @tab Italian @tab
+@code{iu} @tab Inuktitut @tab
+@code{ja} @tab Japanese
+@item
+@code{jw} @tab Javanese @tab
+@code{ka} @tab Georgian @tab
+@code{kk} @tab Kazakh
+@item
+@code{kl} @tab Greenlandic @tab
+@code{km} @tab Cambodian @tab
+@code{kn} @tab Kannada
+@item
+@code{ks} @tab Kashmiri @tab
+@code{ko} @tab Korean @tab
+@code{ku} @tab Kurdish
+@item
+@code{ky} @tab Kirghiz @tab
+@code{la} @tab Latin @tab
+@code{ln} @tab Lingala
+@item
+@code{lt} @tab Lithuanian @tab
+@code{lo} @tab Laothian @tab
+@code{lv} @tab Latvian, Lettish
+@item
+@code{mg} @tab Malagasy @tab
+@code{mi} @tab Maori @tab
+@code{mk} @tab Macedonian
+@item
+@code{ml} @tab Malayalam @tab
+@code{mn} @tab Mongolian @tab
+@code{mo} @tab Moldavian
+@item
+@code{mr} @tab Marathi @tab
+@code{ms} @tab Malay @tab
+@code{mt} @tab Maltese
+@item
+@code{my} @tab Burmese @tab
+@code{na} @tab Nauru @tab
+@code{ne} @tab Nepali
+@item
+@code{nl} @tab Dutch @tab
+@code{no} @tab Norwegian @tab
+@code{oc} @tab Occitan
+@item
+@code{om} @tab (Afan) Oromo @tab
+@code{or} @tab Oriya @tab
+@code{pa} @tab Punjabi
+@item
+@code{pl} @tab Polish @tab
+@code{ps} @tab Pashto, Pushto @tab
+@code{pt} @tab Portuguese
+@item
+@code{qu} @tab Quechua @tab
+@code{rm} @tab Rhaeto-Romance @tab
+@code{rn} @tab Kirundi
+@item
+@code{ro} @tab Romanian @tab
+@code{ru} @tab Russian @tab
+@code{rw} @tab Kinyarwanda
+@item
+@code{sa} @tab Sanskrit @tab
+@code{sd} @tab Sindhi @tab
+@code{sg} @tab Sangro
+@item
+@code{sh} @tab Serbo-Croatian @tab
+@code{si} @tab Sinhalese @tab
+@code{sk} @tab Slovak
+@item
+@code{sl} @tab Slovenian @tab
+@code{sm} @tab Samoan @tab
+@code{sn} @tab Shona
+@item
+@code{so} @tab Somali @tab
+@code{sq} @tab Albanian @tab
+@code{sr} @tab Serbian
+@item
+@code{ss} @tab Siswati @tab
+@code{st} @tab Sesotho @tab
+@code{su} @tab Sundanese
+@item
+@code{sv} @tab Swedish @tab
+@code{sw} @tab Swahili @tab
+@code{ta} @tab Tamil
+@item
+@code{te} @tab Telugu @tab
+@code{tg} @tab Tajik @tab
+@code{th} @tab Thai
+@item
+@code{ti} @tab Tigrinya @tab
+@code{tk} @tab Turkmen @tab
+@code{tl} @tab Tagalog
+@item
+@code{tn} @tab Setswana @tab
+@code{to} @tab Tonga @tab
+@code{tr} @tab Turkish
+@item
+@code{ts} @tab Tsonga @tab
+@code{tt} @tab Tatar @tab
+@code{tw} @tab Twi
+@item
+@code{ug} @tab Uighur @tab
+@code{uk} @tab Ukrainian @tab
+@code{ur} @tab Urdu
+@item
+@code{uz} @tab Uzbek @tab
+@code{vi} @tab Vietnamese @tab
+@code{vo} @tab Volapuk
+@item
+@code{wo} @tab Wolof @tab
+@code{xh} @tab Xhosa @tab
+@code{yi} @tab Yiddish
+@item
+@code{yo} @tab Yoruba @tab
+@code{za} @tab Zhuang @tab
+@code{zh} @tab Chinese
+@item
+@code{zu} @tab Zulu
+@end multitable
+
+
+@node documentencoding
+@section @code{@@documentencoding @var{enc}}: Set Input Encoding
+
+@findex documentencoding
+@cindex Encoding, declaring
+@cindex Input encoding, declaring
+@cindex Document input encoding
+
+The @code{@@documentencoding} command declares the input document
+encoding. Write it on a line by itself, with a valid encoding
+specification following, such as @samp{ISO-8859-1}.
+
+@cindex http-equiv, and charset
+@cindex meta HTML tag, and charset
+At present, this is used only in HTML output from @code{makeinfo}. If a
+document encoding @var{enc} is specified, it is used in the
+@samp{<meta>} tag is included in the @samp{<head>} of the output:
+
+@example
+<meta http-equiv="Content-Type" content="text/html; charset=@var{enc}">
+@end example
+
+
+@node Defining New Texinfo Commands
+@chapter Defining New Texinfo Commands
@cindex Macros
@cindex Defining new Texinfo commands
@cindex New Texinfo commands, defining
@cindex Texinfo commands, defining new
@cindex User-defined Texinfo commands
+Texinfo provides several ways to define new commands:
+
+@itemize @bullet
+@item
A Texinfo @dfn{macro} allows you to define a new Texinfo command as any
sequence of text and/or existing commands (including other macros). The
macro can have any number of @dfn{parameters}---text you supply each
-time you use the macro. (This has nothing to do with the
-@code{@@defmac} command, which is for documenting macros in the subject
-of the manual; @pxref{Def Cmd Template}.)
+time you use the macro.
+
+Incidentally, these macros have nothing to do with the @code{@@defmac}
+command, which is for documenting macros in the subject of the manual
+(@pxref{Def Cmd Template}).
+
+@item
+@samp{@@alias} is a convenient way to define a new name for an existing
+command.
+
+@item
+@samp{@@definfoenclose} allows you to define new commands with
+customized output in the Info file.
+
+@end itemize
@menu
-* Defining Macros:: Both defining and undefining new commands.
+* Defining Macros:: Defining and undefining new commands.
* Invoking Macros:: Using a macro, once you've defined it.
+* Macro Details:: Beyond basic macro usage.
+* alias:: Command aliases.
+* definfoenclose:: Customized highlighting.
@end menu
-@node Defining Macros, Invoking Macros, Macros, Macros
+@node Defining Macros
@section Defining Macros
@cindex Defining macros
@cindex Macro definitions
+@cindex Definitions, a.k.a.@: macros
@findex macro
-You use the Texinfo @code{@@macro} command to define a macro. For example:
+You use the Texinfo @code{@@macro} command to define a macro, like this:
@example
-@@macro @var{macro-name}@{@var{param1}, @var{param2}, @dots{}@}
+@@macro @var{macroname}@{@var{param1}, @var{param2}, @dots{}@}
@var{text} @dots{} \@var{param1}\ @dots{}
@@end macro
@end example
The @dfn{parameters} @var{param1}, @var{param2}, @dots{} correspond to
arguments supplied when the macro is subsequently used in the document
-(see the next section).
+(described in the next section).
+
+For a macro to work with @TeX{}, @var{macroname} must consist entirely
+of letters: no digits, hyphens, underscores, or other special characters.
If a macro needs no parameters, you can define it either with an empty
list (@samp{@@macro foo @{@}}) or with no braces at all (@samp{@@macro
@cindex Body of a macro
@cindex Mutually recursive macros
@cindex Recursion, mutual
-The definition or @dfn{body} of the macro can contain any Texinfo
-commands, including previously-defined macros. (It is not possible to
-have mutually recursive Texinfo macros.) In the body, instances of a
-parameter name surrounded by backslashes, as in @samp{\@var{param1}\} in
-the example above, are replaced by the corresponding argument from the
-macro invocation.
+The definition or @dfn{body} of the macro can contain most Texinfo
+commands, including previously-defined macros. Not-yet-defined macro
+invocations are not allowed; thus, it is not possible to have mutually
+recursive Texinfo macros. Also, a macro definition that defines another
+macro does not work in @TeX{} due to limitations in the design of
+@code{@@macro}.
+
+@cindex Parameters to macros
+In the macro body, instances of a parameter name surrounded by
+backslashes, as in @samp{\@var{param1}\} in the example above, are
+replaced by the corresponding argument from the macro invocation. You
+can use parameter names any number of times in the body, including zero.
+
+@cindex Backslash in macros
+To get a single @samp{\} in the macro expansion, use @samp{\\}. Any
+other use of @samp{\} in the body yields a warning.
+
+@cindex Spaces in macros
+@cindex Whitespace in macros
+The newlines after the @code{@@macro} line and before the @code{@@end
+macro} line are ignored, that is, not included in the macro body. All
+other whitespace is treated according to the usual Texinfo rules.
+
+@cindex Recursive macro invocations
+@findex rmacro
+To allow a macro to be used recursively, that is, in an argument to a
+call to itself, you must define it with @samp{@@rmacro}, like this:
+
+@example
+@@rmacro rmac
+a\arg\b
+@@end rmacro
+@dots{}
+@@rmac@{1@@rmac@{text@}2@}
+@end example
+
+This produces the output `a1atextb2b'. With @samp{@@macro} instead of
+@samp{@@rmacro}, an error message is given.
@findex unmacro
@cindex Macros, undefining
@end example
-@node Invoking Macros, , Defining Macros, Macros
+@node Invoking Macros
@section Invoking Macros
@cindex Invoking macros
+@cindex Expanding macros
+@cindex Running macros
@cindex Macro invocation
After a macro is defined (see the previous section), you can use
(@dfn{invoke}) it in your document like this:
@example
-@@@var{macro-name} @{@var{arg1}, @var{arg2}, @dots{}@}
+@@@var{macroname} @{@var{arg1}, @var{arg2}, @dots{}@}
@end example
-@noindent
-and the result will be just as if you typed the body of
-@var{macro-name} at that spot. For example:
+@noindent and the result will be just as if you typed the body of
+@var{macroname} at that spot. For example:
@example
@@macro foo @{p, q@}
@@foo@{a, b@}
@end example
-@noindent
-produces:
+@noindent produces:
@display
Together: a & b.
@end display
-@cindex Backslash, and macros
-Thus, the arguments and parameters are separated by commas and delimited
-by braces; any whitespace after (but not before) a comma is ignored. To
-insert a comma, brace, or backslash in an argument, prepend a backslash,
-as in
+@cindex Backslash, and macros
+Thus, the arguments and parameters are separated by commas and delimited
+by braces; any whitespace after (but not before) a comma is ignored.
+The braces are required in the invocation (but not the definition), even
+when the macro takes no arguments, consistent with all other Texinfo
+commands. For example:
+
+@example
+@@macro argless @{@}
+No arguments here.
+@@end macro
+@@argless@{@}
+@end example
+
+@noindent produces:
+
+@display
+No arguments here.
+@end display
+
+To insert a comma, brace, or backslash in an argument, prepend a
+backslash, as in
+
+@example
+@@@var{macname} @{\\\@{\@}\,@}
+@end example
+
+@noindent
+which will pass the (almost certainly error-producing) argument
+@samp{\@{@},} to @var{macname}.
+
+If the macro is defined to take a single argument, and is invoked
+without any braces, the entire rest of the line after the macro name is
+supplied as the argument. For example:
+
+@example
+@@macro bar @{p@}
+Twice: \p\ & \p\.
+@@end macro
+@@bar aah
+@end example
+
+@noindent produces:
+
+@c Sorry for cheating, but let's not require macros to process the manual.
+@display
+Twice: aah & aah.
+@end display
+
+If the macro is defined to take a single argument, and is invoked with
+braces, the braced text is passed as the argument, regardless of
+commas. For example:
+
+@example
+@@macro bar @{p@}
+Twice: \p\ & \p\.
+@@end macro
+@@bar@{a,b@}
+@end example
+
+@noindent produces:
+
+@display
+Twice: a,b & a,b.
+@end display
+
+
+@node Macro Details
+@section Macro Details
+@cindex Macro details
+@cindex Details of macro usage
+
+Due to unavoidable disparities in the @TeX{} and @command{makeinfo}
+implementations, Texinfo macros have the following limitations.
+
+@itemize @bullet
+@item
+All macros are expanded inside at least one @TeX{} group. This means
+that @set and other such commands will have no effect inside a macro.
+
+@item
+Macros containing a command which must be on a line by itself, such as a
+conditional, cannot be invoked in the middle of a line.
+
+@item
+The @TeX{} implementation cannot construct macros that define macros in
+the natural way. To do this, you must use conditionals and raw @TeX{}.
+For example:
+
+@example
+@@ifinfo
+@@macro ctor @{name, arg@}
+@@macro \name\
+something involving \arg\ somehow
+@@end macro
+@@end macro
+@@end ifinfo
+@@tex
+\gdef\ctor#1@{\ctorx#1,@}
+\gdef\ctorx#1,#2,@{\def#1@{something involving #2 somehow@}@}
+@@end tex
+@end example
+
+@item
+It is best to avoid comments inside macro definitions.
+
+@end itemize
+
+
+@node alias
+@section @samp{@@alias @var{new}=@var{existing}}
+@cindex Aliases, command
+@cindex Command aliases
+@findex alias
+
+The @samp{@@alias} command defines a new command to be just like an
+existing one. This is useful for defining additional markup names, thus
+preserving semantic information in the input even though the output
+result may be the same.
+
+Write the @samp{@@alias} command on a line by itself, followed by the
+new command name, an equals sign, and the existing command name.
+Whitespace around the equals sign is ignored. Thus:
+@example
+@@alias @var{new} = @var{existing}
+@end example
+
+For example, if your document contains citations for both books and
+some other media (movies, for example), you might like to define a
+macro @code{@@moviecite@{@}} that does the same thing as an ordinary
+@code{@@cite@{@}} but conveys the extra semantic information as well.
+You'd do this as follows:
+
+@example
+@@alias moviecite = cite
+@end example
+
+Macros do not always have the same effect due to vagaries of argument
+parsing. Also, aliases are much simpler to define than macros. So the
+command is not redundant. (It was also heavily used in the Jargon File!)
+
+Aliases must not be recursive, directly or indirectly.
+
+@node definfoenclose
+@section @samp{definfoenclose}: Customized Highlighting
+@cindex Highlighting, customized
+@cindex Customized highlighting
+@findex definfoenclose
+
+A @code{@@definfoenclose} command may be used to define a highlighting
+command for Info, but not for TeX. A command defined using
+@code{@@definfoenclose} marks text by enclosing it in strings that
+precede and follow the text. You can use this to get closer control of
+your Info output.
+
+Presumably, if you define a command with @code{@@definfoenclose} for Info,
+you will create a corresponding command for @TeX{}, either in
+@file{texinfo.tex}, @file{texinfo.cnf}, or within an @samp{@@iftex} in
+your document.
+
+Write a @code{@@definfoenclose} command on a line and follow it with
+three arguments separated by commas. The first argument to
+@code{@@definfoenclose} is the @@-command name (without the @code{@@});
+the second argument is the Info start delimiter string; and the third
+argument is the Info end delimiter string. The latter two arguments
+enclose the highlighted text in the Info file. A delimiter string may
+contain spaces. Neither the start nor end delimiter is required. If
+you do not want a start delimiter but do want an end delimiter, you must
+follow the command name with two commas in a row; otherwise, the Info
+formatting commands will naturally misinterpret the end delimiter string
+you intended as the start delimiter string.
+
+If you do a @code{@@definfoenclose} on the name of a pre-defined macro
+(such as @code{@@emph}, @code{@@strong}, @code{@@t}, or @code{@@i}), the
+enclosure definition will override the built-in definition.
+
+An enclosure command defined this way takes one argument in braces; this
+is intended for new markup commands (@pxref{Marking Text}).
+
+@findex phoo
+For example, you can write:
+
+@example
+@@definfoenclose phoo,//,\\
+@end example
+
+@noindent
+near the beginning of a Texinfo file to define @code{@@phoo} as an Info
+formatting command that inserts `//' before and `\\' after the argument
+to @code{@@phoo}. You can then write @code{@@phoo@{bar@}} wherever you
+want `//bar\\' highlighted in Info.
+
+Also, for TeX formatting, you could write
@example
-@@@var{macro-name} @{\\\@{\@}\,@}
+@@iftex
+@@global@@let@@phoo=@@i
+@@end iftex
@end example
@noindent
-which will pass the (almost certainly error-producing) argument
-@samp{\@{@},} to @var{macro-name}.
+to define @code{@@phoo} as a command that causes TeX to typeset the
+argument to @code{@@phoo} in italics.
-If the macro is defined to take a single argument, and is invoked
-without any braces, the entire rest of the line after the macro name is
-supplied as the argument. For example:
+Note that each definition applies to its own formatter: one for TeX,
+the other for @code{texinfo-format-buffer} or
+@code{texinfo-format-region}. The @code{@@definfoenclose} command need
+not be within @samp{@@ifinfo}, but the raw @TeX{} commands do need to be
+in @samp{@@iftex}.
+
+@findex headword
+Here is another example: write
@example
-@@macro bar @{p@}
-Twice: \p\, \p\.
-@@end macro
-@@bar aah
+@@definfoenclose headword, , :
@end example
@noindent
-produces:
+near the beginning of the file, to define @code{@@headword} as an Info
+formatting command that inserts nothing before and a colon after the
+argument to @code{@@headword}.
-@display
-Twice: aah, aah.
-@end display
+@samp{@@definfoenclose} definitions must not be recursive, directly or
+indirectly.
-@node Format/Print Hardcopy, Create an Info File, Macros, Top
-@comment node-name, next, previous, up
-@chapter Format and Print Hardcopy
+@node Hardcopy
+@chapter Formatting and Printing Hardcopy
@cindex Format and print hardcopy
+@cindex Printing hardcopy
@cindex Hardcopy, printing it
@cindex Making a printed manual
@cindex Sorting indices
printed, a second for sorting indices, and a third for printing the
formatted document. When you use the shell commands, you can either
work directly in the operating system shell or work within a shell
-inside GNU Emacs.@refill
+inside GNU Emacs.
If you are using GNU Emacs, you can use commands provided by Texinfo
mode instead of shell commands. In addition to the three commands to
format a file, sort the indices, and print the result, Texinfo mode
offers key bindings for commands to recenter the output buffer, show the
-print queue, and delete a job from the print queue.@refill
+print queue, and delete a job from the print queue.
@menu
* Use TeX:: Use @TeX{} to format for hardcopy.
-* Format with tex/texindex:: How to format in a shell.
-* Format with texi2dvi:: A simpler way to use the shell.
+* Format with tex/texindex:: How to format with explicit shell commands.
+* Format with texi2dvi:: A simpler way to format.
* Print with lpr:: How to print.
* Within Emacs:: How to format and print from an Emacs shell.
* Texinfo Mode Printing:: How to format and print in Texinfo mode.
* Compile-Command:: How to print using Emacs's compile command.
* Requirements Summary:: @TeX{} formatting requirements summary.
-* Preparing for TeX:: What you need to do to use @TeX{}.
+* Preparing for TeX:: What to do before you use @TeX{}.
* Overfull hboxes:: What are and what to do with overfull hboxes.
* smallbook:: How to print small format books and manuals.
* A4 Paper:: How to print on European A4 paper.
+* pagesizes:: How to print with customized page sizes.
* Cropmarks and Magnification:: How to print marks to indicate the size
of pages and how to print scaled up output.
+* PDF Output:: Portable Document Format output.
@end menu
-@node Use TeX, Format with tex/texindex, Format/Print Hardcopy, Format/Print Hardcopy
-@ifinfo
-@heading Use @TeX{}
-@end ifinfo
+@node Use TeX
+@section Use @TeX{}
The typesetting program called @TeX{} is used for formatting a Texinfo
-file. @TeX{} is a very powerful typesetting program and, if used right,
+file. @TeX{} is a very powerful typesetting program and, if used correctly,
does an exceptionally good job. (@xref{Obtaining TeX, , How to Obtain
@TeX{}}, for information on how to obtain @TeX{}.)
The @code{makeinfo}, @code{texinfo-format-region}, and
@code{texinfo-format-buffer} commands read the very same @@-commands
in the Texinfo file as does @TeX{}, but process them differently to
-make an Info file; see @ref{Create an Info File}.@refill
+make an Info file (@pxref{Creating an Info File}).
-@node Format with tex/texindex, Format with texi2dvi, Use TeX, Format/Print Hardcopy
-@comment node-name, next, previous, up
-@section Format using @code{tex} and @code{texindex}
+
+@node Format with tex/texindex
+@section Format with @code{tex} and @code{texindex}
@cindex Shell formatting with @code{tex} and @code{texindex}
@cindex Formatting with @code{tex} and @code{texindex}
@cindex DVI file
tex foo.texi
@end example
-@noindent
-@TeX{} will produce a @dfn{DVI file} as well as several auxiliary
+@noindent @TeX{} will produce a @dfn{DVI file} as well as several auxiliary
files containing information for indices, cross references, etc. The
DVI file (for @dfn{DeVice Independent} file) can be printed on virtually
-any printe (see the following sections).
+any device (see the following sections).
@pindex texindex
The @code{tex} formatting command itself does not sort the indices; it
writes an output file of unsorted index data. (The @code{texi2dvi}
-command automatically generates indices; see @ref{Format with texi2dvi,,
-Format using @code{texi2dvi}}.) To generate a printed index after
+command automatically generates indices; @pxref{Format with texi2dvi,,
+Format with @code{texi2dvi}}.) To generate a printed index after
running the @code{tex} command, you first need a sorted index to work
from. The @code{texindex} command sorts indices. (The source file
@file{texindex.c} comes as part of the standard Texinfo distribution,
among other places.)@refill
@cindex Names of index files
+@cindex Index file names
The @code{tex} formatting command outputs unsorted index files under
names that obey a standard convention: the name of your main input file
with any @samp{.tex} (or similar, @pxref{tex invocation,,, web2c,
For example, the raw index output files for the input file
@file{foo.texinfo} would be @file{foo.cp}, @file{foo.vr}, @file{foo.fn},
@file{foo.tp}, @file{foo.pg} and @file{foo.ky}. Those are exactly the
-arguments to give to @code{texindex}.@refill
+arguments to give to @code{texindex}.
@need 1000
@cindex Wildcards
@cindex Globbing
Instead of specifying all the unsorted index file names explicitly, you
can use @samp{??} as shell wildcards and give the command in this
-form:@refill
+form:
@example
texindex foo.??
or @code{@@defcodeindex}. (You may execute @samp{texindex foo.??}
even if there are similarly named files with two letter extensions
that are not index files, such as @samp{foo.el}. The @code{texindex}
-command reports but otherwise ignores such files.)@refill
+command reports but otherwise ignores such files.)
For each file specified, @code{texindex} generates a sorted index file
whose name is made by appending @samp{s} to the input file name. The
-@code{@@printindex} command knows to look for a file of that name
+@code{@@printindex} command looks for a file with that name
(@pxref{Printing Indices & Menus}). @code{texindex} does not alter the
-raw index output file.@refill
+raw index output file.
After you have sorted the indices, you need to rerun the @code{tex}
formatting command on the Texinfo file. This regenerates the DVI file,
Finally, you may need to run @code{tex} one more time, to get the page
numbers in the cross-references correct.
-To summarize, this is a four step process:
+To summarize, this is a five step process:
@enumerate
@item
numbers for the cross-references from last time, generally incorrect.
@item
+Sort the indices again, with @code{texindex}.
+
+@item
Run @code{tex} one last time. This time the correct page numbers are
written for the cross-references.
@end enumerate
@pindex texi2dvi
-Alternatively, it's a one-step process: run @code{texi2dvi}.
+Alternatively, it's a one-step process: run @code{texi2dvi}
+(@pxref{Format with texi2dvi}).
You need not run @code{texindex} each time after you run @code{tex}. If
you do not, on the next run, the @code{tex} formatting command will use
whatever sorted index files happen to exist from the previous use of
-@code{texindex}. This is usually ok while you are
-debugging.@refill
+@code{texindex}. This is usually ok while you are debugging.
+
+@cindex Auxiliary files, avoiding
+@findex novalidate
+@cindex Pointer validation, suppressing
+@cindex Chapters, formatting one at a time
+Sometimes you may wish to print a document while you know it is
+incomplete, or to print just one chapter of a document. In that case,
+the usual auxiliary files that @TeX{} creates and warnings @TeX{} gives
+when cross-references are not satisfied are just nuisances. You can
+avoid them with the @code{@@novalidate} command, which you must give
+@emph{before} the @code{@@setfilename} command
+(@pxref{setfilename,,@code{@@setfilename}}). Thus, the beginning of
+your file would look approximately like this:
+
+@example
+\input texinfo
+@@novalidate
+@@setfilename myfile.info
+@dots{}
+@end example
+@noindent @code{@@novalidate} also turns off validation in
+@code{makeinfo}, just like its @code{--no-validate} option
+(@pxref{Pointer Validation}).
-@node Format with texi2dvi, Print with lpr, Format with tex/texindex, Format/Print Hardcopy
-@comment node-name, next, previous, up
-@section Format using @code{texi2dvi}
+
+@node Format with texi2dvi
+@section Format with @code{texi2dvi}
@pindex texi2dvi @r{(shell script)}
The @code{texi2dvi} command automatically runs both @code{tex} and
@code{texindex} as many times as necessary to produce a DVI file with
-up-to-date, sorted indices. It simplifies the
-@code{tex}---@code{texindex}---@code{tex} sequence described in the
-previous section.
+sorted indices and all cross-references resolved. It simplifies the
+@code{tex}---@code{texindex}---@code{tex}---@code{tex} sequence
+described in the previous section.
-The syntax for @code{texi2dvi} is like this (where @samp{prompt$} is your
-shell prompt):@refill
+To run @code{texi2dvi} on an input file @file{foo.texi}, do this (where
+@samp{prompt$ } is your shell prompt):
@example
-prompt$ @kbd{texi2dvi @var{filename}@dots{}}
+prompt$ @kbd{texi2dvi foo.texi}
@end example
-For a list of options, run @samp{texi2dvi --help}.
+As shown in this example, the input filenames to @code{texi2dvi} must
+include any extension (@samp{.texi}, @samp{.texinfo}, etc.). Under
+MS-DOS and perhaps in other circumstances, you may need to run @samp{sh
+texi2dvi foo.texi} instead of relying on the operating system to invoke
+the shell on the @samp{texi2dvi} script.
+Perhaps the most useful option to @code{texi2dvi} is
+@samp{--texinfo=@var{cmd}}. This inserts @var{cmd} on a line by itself
+after the @code{@@setfilename} in a temporary copy of the input file
+before running @TeX{}. With this, you can specify different printing
+formats, such as @code{@@smallbook} (@pxref{smallbook}),
+@code{@@afourpaper} (@pxref{A4 Paper}), or @code{@@pageparams}
+(@pxref{pagesizes}), without actually changing the document source.
+(You can also do this on a site-wide basis with @file{texinfo.cnf};
+@pxref{Preparing for TeX,,Preparing for @TeX{}}).
-@node Print with lpr, Within Emacs, Format with texi2dvi, Format/Print Hardcopy
-@comment node-name, next, previous, up
+For a list of other options, run @samp{texi2dvi --help}.
+
+
+@node Print with lpr, Within Emacs, Format with texi2dvi, Hardcopy
@section Shell Print Using @code{lpr -d}
@pindex lpr @r{(DVI print command)}
DVI file name without any extension or with a @samp{.dvi}
extension. (If it is @samp{lpr}, you must include the @samp{.dvi}.)
-The following commands, for example, will (probably) suffice to sort the
+For example, the following commands, will (perhaps) suffice to sort the
indices, format, and print the @cite{Bison Manual}:
@example
@end group
@end example
-@node Within Emacs, Texinfo Mode Printing, Print with lpr, Format/Print Hardcopy
-@comment node-name, next, previous, up
+@cindex Shell printing, on MS-DOS/MS-Windows
+@cindex Printing DVI files, on MS-DOS/MS-Windows
+@pindex lpr@r{-d, replacements on MS-DOS/MS-Windows}
+@code{lpr} is a standard program on Unix systems, but it is usually
+absent on MS-DOS/MS-Windows. Some network packages come with a
+program named @code{lpr}, but these are usually limited to sending files
+to a print server over the network, and generally don't support the
+@samp{-d} option. If you are unfortunate enough to work on one of these
+systems, you have several alternative ways of printing DVI files:
+
+@itemize @bullet{}
+@item Find and install a Unix-like @code{lpr} program, or its clone.
+If you can do that, you will be able to print DVI files just like
+described above.
+
+@item Send the DVI files to a network printer queue for DVI files.
+Some network printers have special queues for printing DVI files. You
+should be able to set up your network software to send files to that
+queue. In some cases, the version of @code{lpr} which comes with your
+network software will have a special option to send a file to specific
+queues, like this:
+
+@example
+lpr -Qdvi -hprint.server.domain bison.dvi
+@end example
+
+@item Convert the DVI file to a Postscript or PCL file and send it to your
+local printer. @xref{dvips invocation,,, dvips, Dvips}, and the man
+pages for @code{dvilj}, for detailed description of these tools. Once
+the DVI file is converted to the format your local printer understands
+directly, just send it to the appropriate port, usually @samp{PRN}.
+@end itemize
+
+
+@node Within Emacs
@section From an Emacs Shell
@cindex Print, format from Emacs shell
@cindex Format, print from Emacs shell
You can give formatting and printing commands from a shell within GNU
Emacs. To create a shell within Emacs, type @kbd{M-x shell}. In this
-shell, you can format and print the document. @xref{Format/Print
-Hardcopy, , Format and Print Hardcopy}, for details.@refill
+shell, you can format and print the document. @xref{Hardcopy, , Format
+and Print Hardcopy}, for details.
You can switch to and from the shell buffer while @code{tex} is
running and do other editing. If you are formatting a long document
and printing in Texinfo mode.@refill
@end ifinfo
-@node Texinfo Mode Printing, Compile-Command, Within Emacs, Format/Print Hardcopy
+
+@node Texinfo Mode Printing, Compile-Command, Within Emacs, Hardcopy
@section Formatting and Printing in Texinfo Mode
@cindex Region printing in Texinfo mode
@cindex Format and print in Texinfo mode
@item C-c C-t C-k
@itemx M-x tex-kill-job
-Kill the currently running @TeX{} job started by
+Kill the currently running @TeX{} job started by either
@code{texinfo-tex-region} or @code{texinfo-tex-buffer}, or any other
process running in the Texinfo shell buffer.@refill
You can change the values of these variables with the @kbd{M-x
edit-options} command (@pxref{Edit Options, , Editing Variable Values,
-xemacs, XEmacs User's Manual}), with the @kbd{M-x set-variable} command
-(@pxref{Examining, , Examining and Setting Variables, xemacs, XEmacs
-User's Manual}), or with your @file{.emacs} initialization file
-(@pxref{Init File, , , xemacs, XEmacs User's Manual}).@refill
-
-@node Compile-Command, Requirements Summary, Texinfo Mode Printing, Format/Print Hardcopy
-@comment node-name, next, previous, up
+emacs, The GNU Emacs Manual}), with the @kbd{M-x set-variable} command
+(@pxref{Examining, , Examining and Setting Variables, emacs, The GNU
+Emacs Manual}), or with your @file{.emacs} initialization file
+(@pxref{Init File, , , emacs, The GNU Emacs Manual}).@refill
+
+@cindex Customize Emacs package
+@findex Development/Docs/Texinfo Customize group
+Beginning with version 20, GNU Emacs offers a user-friendly interface,
+called @dfn{Customize}, for changing values of user-definable variables.
+@xref{Easy Customization, , Easy Customization Interface, emacs, The GNU
+Emacs Manual}, for more details about this. The Texinfo variables can
+be found in the @samp{Development/Docs/Texinfo} group, once you invoke
+the @kbd{M-x customize} command.
+
+
+@node Compile-Command, Requirements Summary, Texinfo Mode Printing, Hardcopy
@section Using the Local Variables List
@cindex Local variables
@cindex Compile command for formatting
@noindent
This technique is most often used by programmers who also compile programs
-this way; see @ref{Compilation, , , xemacs, XEmacs User's Manual}.@refill
+this way; see @ref{Compilation, , , emacs, The GNU Emacs Manual}.@refill
-@node Requirements Summary, Preparing for TeX, Compile-Command, Format/Print Hardcopy
-@comment node-name, next, previous, up
+@node Requirements Summary
@section @TeX{} Formatting Requirements Summary
@cindex Requirements for formatting
@cindex Minimal requirements for formatting
@example
\input texinfo
-@@setfilename @var{arg-not-used-by-@@TeX@{@}}
+@@setfilename @var{arg-not-used-by-@TeX{}}
@end example
@noindent
@end example
Strictly speaking, these lines are all a Texinfo file needs to be
-processed successfully by @TeX{}.
+processed successfully by @TeX{}.
Usually, however, the beginning includes an @code{@@settitle} command to
define the title of the printed manual, an @code{@@setchapternewpage}
@code{@@bye}, the end of a file usually includes indices and a table of
contents. (And of course most manuals contain a body of text as well.)
-@iftex
-For more information, see
-@ref{settitle, , @code{@@settitle}},
-@ref{setchapternewpage, , @code{@@setchapternewpage}},
-@ref{Headings, ,Page Headings},
-@ref{Titlepage & Copyright Page},
-@ref{Printing Indices & Menus}, and
-@ref{Contents}.
-@end iftex
-@noindent
-@ifinfo
-For more information, see@*
-@ref{settitle, , @code{@@settitle}},@*
-@ref{setchapternewpage, , @code{@@setchapternewpage}},@*
-@ref{Headings, ,Page Headings},@*
-@ref{Titlepage & Copyright Page},@*
-@ref{Printing Indices & Menus}, and@*
-@ref{Contents}.
-@end ifinfo
+For more information, see:
+@itemize @bullet
+@item @ref{settitle, , @code{@@settitle}}
+@item @ref{setchapternewpage, , @code{@@setchapternewpage}}
+@item @ref{Headings, ,Page Headings}
+@item @ref{Titlepage & Copyright Page}
+@item @ref{Printing Indices & Menus}
+@item @ref{Contents}
+@end itemize
-@node Preparing for TeX, Overfull hboxes, Requirements Summary, Format/Print Hardcopy
-@comment node-name, next, previous, up
-@section Preparing to Use @TeX{}
-@cindex Preparing to use @TeX{}
+@node Preparing for TeX
+@section Preparing for @TeX{}
+@cindex Preparing for @TeX{}
@cindex @TeX{} input initialization
@cindex @code{TEXINPUTS} environment variable
@vindex TEXINPUTS
@cindex Customizing of @TeX{} for Texinfo
@cindex Site-wide Texinfo configuration file
Optionally, you may create an additional @file{texinfo.cnf}, and install
-it as well. This file is read by @TeX{} at the @code{@@setfilename}
-command (@pxref{setfilename,, @code{@@setfilename}}). You can put any
-commands you like there according to local site-wide conventions, and
-they will be read by @TeX{} when processing any Texinfo document. For
-example, if @file{texinfo.cnf} contains the a single line
-@samp{@@afourpaper} (@pxref{A4 Paper}), then all Texinfo documents will
-be processed with that page size in effect. If you have nothing to put
-in @file{texinfo.cnf}, you do not need to create it.
+it as well. This file is read by @TeX{} when the @code{@@setfilename}
+command is executed (@pxref{setfilename,, @code{@@setfilename}}). You can put any
+commands you like there, according to local site-wide conventions. They
+will be read by @TeX{} when processing any Texinfo document. For
+example, if @file{texinfo.cnf} contains the line @samp{@@afourpaper}
+(@pxref{A4 Paper}), then all Texinfo documents will be processed with
+that page size in effect. If you have nothing to put in
+@file{texinfo.cnf}, you do not need to create it.
@vindex TEXINPUTS
If neither of the above locations for these system files suffice for
@end group
@end example
+On MS-DOS/MS-Windows, you would say it like this@footnote{Note the use
+of the @samp{;} character, instead of @samp{:}, as directory separator
+on these systems.}:
+
+@example
+@group
+set TEXINPUTS=.;d:/home/me/mylib;c:/usr/lib/tex/macros
+@end group
+@end example
+
@noindent
-This would cause @TeX{} to look for @file{\input} file first in the current
-directory, indicated by the @samp{.}, then in a hypothetical user's
-@file{me/mylib} directory, and finally in a system directory.
+It is customary for DOS/Windows users to put such commands in the
+@file{autoexec.bat} file, or in the Windows Registry.@refill
+@noindent
+These settings would cause @TeX{} to look for @file{\input} file first
+in the current directory, indicated by the @samp{.}, then in a
+hypothetical user's @file{me/mylib} directory, and finally in a system
+directory @file{/usr/lib/tex/macros}.
-@node Overfull hboxes, smallbook, Preparing for TeX, Format/Print Hardcopy
-@comment node-name, next, previous, up
+@cindex Dumping a .fmt file
+@cindex Format file, dumping
+Finally, you may wish to dump a @file{.fmt} file (@pxref{Memory dumps,,,
+web2c, Web2c}) so that @TeX{} can load Texinfo faster. (The
+disadvantage is that then updating @file{texinfo.tex} requires
+redumping.) You can do this by running this command, assuming
+@file{epsf.tex} is findable by @TeX{}:
+
+@example
+initex texinfo @@dump
+@end example
+
+(@code{@@dump} is a @TeX{} primitive.) You'll then need to move
+@file{texinfo.fmt} to wherever your @code{.fmt} files are found;
+typically this will be in the subdirectory @file{web2c} of your @TeX{}
+installation, for example, @file{/usr/local/share/tex/web2c}.
+
+
+@node Overfull hboxes
@section Overfull ``hboxes''
@cindex Overfull @samp{hboxes}
@cindex @samp{hboxes}, overfull
the right margin. This can occur when @TeX{} comes upon what it
interprets as a long word that it cannot hyphenate, such as an
electronic mail network address or a very long title. When this
-happens, @TeX{} prints an error message like this:@refill
+happens, @TeX{} prints an error message like this:
@example
-Overfull \hbox (20.76302pt too wide)
+Overfull @@hbox (20.76302pt too wide)
@end example
+@findex hbox
@noindent
(In @TeX{}, lines are in ``horizontal boxes'', hence the term, ``hbox''.
-The backslash, @samp{\}, is the @TeX{} equivalent of @samp{@@}.)@refill
+@samp{@@hbox} is a @TeX{} primitive not needed in the Texinfo language.)
@TeX{} also provides the line number in the Texinfo source file and
the text of the offending line, which is marked at all the places that
-@TeX{} knows how to hyphenate words.
+@TeX{} considered hyphenation.
@xref{Debugging with TeX, , Catching Errors with @TeX{} Formatting},
-for more information about typesetting errors.@refill
+for more information about typesetting errors.
If the Texinfo file has an overfull hbox, you can rewrite the sentence
so the overfull hbox does not occur, or you can decide to leave it. A
small excursion into the right margin often does not matter and may not
-even be noticeable.@refill
+even be noticeable.
+
+If you have many overfull boxes and/or an antipathy to rewriting, you
+can coerce @TeX{} into greatly increasing the allowable interword
+spacing, thus (if you're lucky) avoiding many of the bad line breaks,
+like this:
+
+@findex \emergencystretch
+@example
+@@tex
+\global\emergencystretch = .9\hsize
+@@end tex
+@end example
+
+@noindent
+(You can adjust the fraction as needed.) This huge value for
+@code{\emergencystretch} cannot be the default, since then the typeset
+output would generally be of noticeably lower quality. The default
+value is @samp{.15\hsize}. @code{\hsize} is the @TeX{} dimension
+containing the current line width.
@cindex Black rectangle in hardcopy
-@cindex Rectangle, ugly, black in hardcopy
-However, unless told otherwise, @TeX{} will print a large, ugly, black
-rectangle beside the line that contains the overfull hbox. This is so
-you will notice the location of the problem if you are correcting a
-draft.@refill
+@cindex Rectangle, black in hardcopy
+@cindex Box, ugly black in hardcopy
+@cindex Ugly black rectangles in hardcopy
+For what overfull boxes you have, however, @TeX{} will print a large,
+ugly, black rectangle beside the line that contains the overfull hbox
+unless told otherwise. This is so you will notice the location of the
+problem if you are correcting a draft.
-@need 1000
@findex finalout
To prevent such a monstrosity from marring your final printout, write
the following in the beginning of the Texinfo file on a line of its own,
-before the @code{@@titlepage} command:@refill
+before the @code{@@titlepage} command:
@example
@@finalout
@end example
-@node smallbook, A4 Paper, Overfull hboxes, Format/Print Hardcopy
-@comment node-name, next, previous, up
+
+@node smallbook
@section Printing ``Small'' Books
@findex smallbook
@cindex Small book size
@end example
@noindent
-(Since regular sized books are often about 7 by 9.25 inches, this
-command might better have been called the @code{@@regularbooksize}
-command, but it came to be called the @code{@@smallbook} command by
-comparison to the 8.5 by 11 inch format.)@refill
+(Since many books are about 7 by 9.25 inches, this command might better
+have been called the @code{@@regularbooksize} command, but it came to be
+called the @code{@@smallbook} command by comparison to the 8.5 by 11 inch format.)
If you write the @code{@@smallbook} command between the
start-of-header and end-of-header lines, the Texinfo mode @TeX{}
region formatting command, @code{texinfo-tex-region}, will format the
region in ``small'' book size (@pxref{Start of Header}).@refill
-The Free Software Foundation distributes printed copies of @cite{The GNU
-Emacs Manual} and other manuals in the ``small'' book size.
-@xref{smallexample & smalllisp, , @code{@@smallexample} and
-@code{@@smalllisp}}, for information about commands that make it easier
-to produce examples for a smaller manual.@refill
+@xref{small}, for information about
+commands that make it easier to produce examples for a smaller manual.
-Alternatively, to avoid embedding this physical paper size in your
-document, use @code{texi2dvi} to format your document (@pxref{Format
-with texi2dvi}), and supply @samp{-t @@smallbook} as an argument. Then
-other people do not have to change the document source file to format it
-differently.
+@xref{Format with texi2dvi}, and @ref{Preparing for TeX,,Preparing for
+@TeX{}}, for other ways to format with @code{@@smallbook} that do not
+require changing the source file.
-@node A4 Paper, Cropmarks and Magnification, smallbook, Format/Print Hardcopy
-@comment node-name, next, previous, up
+@node A4 Paper
@section Printing on A4 Paper
@cindex A4 paper, printing on
@cindex Paper size, European A4
@cindex European A4 paper
@findex afourpaper
-You can tell @TeX{} to typeset a document for printing on European size
+You can tell @TeX{} to format a document for printing on European size
A4 paper with the @code{@@afourpaper} command. Write the command on a
-line by itself between @code{@@iftex} and @code{@@end iftex} lines near
-the beginning of the Texinfo file, before the title page:@refill
-
-For example, this is how you would write the header for this manual:@refill
+line by itself near the beginning of the Texinfo file, before the title
+page. For example, this is how you would write the header for this
+manual:
@example
@group
@@c %**start of header
@@setfilename texinfo
@@settitle Texinfo
-@@syncodeindex vr fn
-@@iftex
@@afourpaper
-@@end iftex
@@c %**end of header
@end group
@end example
-Alternatively, to avoid embedding this physical paper size in your
-document, use @code{texi2dvi} to format your document (@pxref{Format
-with texi2dvi}), and supply @samp{-t @@afourpaper} as an argument. Then
-other people do not have to change the document source file to format it
-differently.
+@xref{Format with texi2dvi}, and @ref{Preparing for TeX,,Preparing for
+@TeX{}}, for other ways to format with @code{@@afourpaper} that do not
+require changing the source file.
-@pindex texinfo.cnf
-Another alternative: put the @code{@@afourpaper} command in the file
-@file{texinfo.cnf} that @TeX{} will read. (No need for @code{@@iftex}
-there.) This will automatically typeset all the Texinfo documents at
-your site with that paper size in effect.
+@findex afourlatex
+You may or may not prefer the formatting that results from the command
+@code{@@afourlatex}. There's also @code{@@afourwide} for A4 paper in
+wide format.
-@node Cropmarks and Magnification, , A4 Paper, Format/Print Hardcopy
-@comment node-name, next, previous, up
-@section Cropmarks and Magnification
+@node pagesizes
+@section @code{@@pagesizes} [@var{width}][, @var{height}]: Custom page sizes
+@findex pagesizes
+@cindex Custom page sizes
+@cindex Page sizes, customized
+@cindex Text width and height
+@cindex Width of text area
+@cindex Height of text area
+@cindex Depth of text area
+
+You can explicitly specify the height and (optionally) width of the main
+text area on the page with the @code{@@pagesizes} command. Write this
+on a line by itself near the beginning of the Texinfo file, before the
+title page. The height comes first, then the width if desired,
+separated by a comma. Examples:
+
+@example
+@@pagesizes 200mm,150mm @c for b5 paper
+@end example
+@noindent and
+@example
+@@pagesizes 11.5in @c for legal paper
+@end example
+
+@cindex B5 paper, printing on
+@cindex Legal paper, printing on
+This would be reasonable for printing on B5-size paper. To emphasize,
+this command specifies the size of the @emph{text area}, not the size of
+the paper (which is 250@dmn{mm} by 177@dmn{mm} for B5, 14@dmn{in} by
+8.5@dmn{in} for legal).
+
+@cindex Margins on page, not controllable
+To make more elaborate changes, such as changing any of the page
+margins, you must define a new command in @file{texinfo.tex} (or
+@file{texinfo.cnf}, @pxref{Preparing for TeX,,Preparing for @TeX{}}).
+
+@xref{Format with texi2dvi}, and @ref{Preparing for TeX,,Preparing for
+@TeX{}}, for other ways to specify @code{@@pagesizes} that do not
+require changing the source file.
+@code{@@pagesizes} is ignored by @code{makeinfo}.
+
+
+@node Cropmarks and Magnification
+@section Cropmarks and Magnification
@findex cropmarks
@cindex Cropmarks for printing
@cindex Printing cropmarks
-You can attempt to direct @TeX{} to print cropmarks at the corners of
+You can (attempt to) direct @TeX{} to print cropmarks at the corners of
pages with the @code{@@cropmarks} command. Write the @code{@@cropmarks}
command on a line by itself between @code{@@iftex} and @code{@@end
iftex} lines near the beginning of the Texinfo file, before the title
(Printers will not produce cropmarks for regular sized output that is
printed on regular sized paper.) Since different printing machines work
in different ways, you should explore the use of this command with a
-spirit of adventure. You may have to redefine the command in the
-@file{texinfo.tex} definitions file.@refill
+spirit of adventure. You may have to redefine the command in
+@file{texinfo.tex}.
@findex mag @r{(@TeX{} command)}
@cindex Magnified printing
Follow the @code{\mag} command with an @samp{=} and then a number that
is 1000 times the magnification you desire. For example, to print pages
at 1.2 normal size, write the following near the beginning of the
-Texinfo file, before the title page:@refill
+Texinfo file, before the title page:
@example
@group
@end example
With some printing technologies, you can print normal-sized copies that
-look better than usual by using a larger-than-normal master.@refill
+look better than usual by giving a larger-than-normal master to your
+print shop. They do the reduction, thus effectively increasing the
+resolution.
-Depending on your system, @code{\mag} may not work or may work only at
-certain magnifications. Be prepared to experiment.@refill
+Depending on your system, DVI files prepared with a
+nonstandard-@code{\mag} may not print or may print only with certain
+magnifications. Be prepared to experiment.
-@node Create an Info File, Install an Info File, Format/Print Hardcopy, Top
-@comment node-name, next, previous, up
-@chapter Creating an Info File
+
+@node PDF Output
+@section PDF Output
+@cindex PDF output
+
+@pindex pdftex
+You can generate a PDF output file from Texinfo source by using the
+@command{pdftex} program to process your file instead of plain
+@command{tex}. Just run @samp{pdftex foo.texi} instead of @samp{tex
+foo.texi}, or give the @samp{--pdf} option to @command{texi2dvi}.
+
+PDF stands for Portable Document Format, and was invented by Adobe
+Systems. The
+@uref{http://www.adobe.com/prodindex/acrobat/adobepdf.html, file format
+definition} is freely available, as is a
+@uref{http://www.foolabs.com/xpdf/, free viewer} for the X window
+system. Since PDF is a binary format, there is no @samp{@@ifpdf} or
+@samp{@@pdf} command by analogy with the other output formats.
+
+Despite the `portable' in the name, PDF files are nowhere near as
+portable in practice as the plain ASCII formats (Info, HTML) Texinfo
+also supports (portability relative to DVI is arguable). They also tend
+to be much larger and do not support the bitmap fonts used by @TeX{} (by
+default) very well. Nevertheless, a PDF file does preserve an actual
+printed document on a screen as faithfully as possible, unlike HTML,
+say, so have their place.
+
+PDF support in Texinfo is fairly rudimentary.
+
+
+@node Creating and Installing Info Files
+@chapter Creating and Installing Info Files
+
+This chapter describes how to create and install info files. @xref{Info
+Files}, for general information about the file format itself.
+
+
+@menu
+* Creating an Info File::
+* Install an Info File::
+@end menu
+
+@node Creating an Info File
+@section Creating an Info File
@cindex Creating an Info file
-@cindex Info, creating an on-line file
+@cindex Info, creating an online file
@cindex Formatting a file for Info
-@code{makeinfo} is a utility that converts a Texinfo file into an Info
-file; @code{texinfo-format-region} and @code{texinfo-format-buffer} are
-GNU Emacs functions that do the same.@refill
-
-A Texinfo file must contain an @code{@@setfilename} line near its
-beginning, otherwise the Info formatting commands will fail.
+@code{makeinfo} is a program that converts a Texinfo file into an Info
+file, HTML file, or plain text. @code{texinfo-format-region} and
+@code{texinfo-format-buffer} are GNU Emacs functions that convert
+Texinfo to Info.
-For information on installing the Info file in the Info system, see
-@ref{Install an Info File}.@refill
+For information on installing the Info file in the Info system,
+@pxref{Install an Info File}.
@menu
* makeinfo advantages:: @code{makeinfo} provides better error checking.
* Batch Formatting:: How to format for Info in Emacs Batch mode.
* Tag and Split Files:: How tagged and split files help Info
to run better.
+* makeinfo html:: Generating HTML output.
@end menu
-@node makeinfo advantages, Invoking makeinfo, Create an Info File, Create an Info File
-@ifinfo
-@heading @code{makeinfo} Preferred
-@end ifinfo
+
+@node makeinfo advantages
+@subsection @code{makeinfo} Preferred
The @code{makeinfo} utility creates an Info file from a Texinfo source
file more quickly than either of the Emacs formatting commands and
provides better error messages. We recommend it. @code{makeinfo} is a
C program that is independent of Emacs. You do not need to run Emacs to
use @code{makeinfo}, which means you can use @code{makeinfo} on machines
-that are too small to run Emacs. You can run @code{makeinfo} in
-any one of three ways: from an operating system shell, from a shell
-inside Emacs, or by typing a key command in Texinfo mode in Emacs.
+that are too small to run Emacs. You can run @code{makeinfo} in any one
+of three ways: from an operating system shell, from a shell inside
+Emacs, or by typing the @kbd{C-c C-m C-r} or the @kbd{C-c C-m C-b}
+command in Texinfo mode in Emacs.
@refill
The @code{texinfo-format-region} and the @code{texinfo-format-buffer}
circumstances, they format short regions or buffers more quickly than
@code{makeinfo}.@refill
-@node Invoking makeinfo, makeinfo options, makeinfo advantages, Create an Info File
-@section Running @code{makeinfo} from a Shell
+@node Invoking makeinfo
+@subsection Running @code{makeinfo} from a Shell
To create an Info file from a Texinfo file, type @code{makeinfo}
followed by the name of the Texinfo file. Thus, to create the Info
file for Bison, type the following to the shell:
-is the prompt):@refill
@example
makeinfo bison.texinfo
@end ifinfo
-@node makeinfo options, Pointer Validation, Invoking makeinfo, Create an Info File
+@node makeinfo options
@comment node-name, next, previous, up
-@section Options for @code{makeinfo}
+@subsection Options for @code{makeinfo}
@cindex @code{makeinfo} options
@cindex Options for @code{makeinfo}
Cause the variable @var{var} to be defined. This is equivalent to
@code{@@set @var{var}} in the Texinfo file (@pxref{set clear value}).
+@item --commands-in-node-names
+@opindex --commands-in-node-names
+Allow @code{@@}-commands in node names. This is not recommended, as it
+can probably never be implemented in @TeX{}. It also makes
+@code{makeinfo} much slower. Also, this option is ignored when
+@samp{--no-validate} is used. @xref{Pointer Validation}, for more
+details.
+
@item --error-limit=@var{limit}
+@itemx -e @var{limit}
@opindex --error-limit=@var{limit}
+@opindex -e @var{limit}
Set the maximum number of errors that @code{makeinfo} will report
before exiting (on the assumption that continuing would be useless);
default 100.
-@need 150
@item --fill-column=@var{width}
+@itemx -f @var{width}
@opindex --fill-column=@var{width}
+@opindex -f @var{width}
Specify the maximum number of columns in a line; this is the right-hand
edge of a line. Paragraphs that are filled will be filled to this
width. (Filling is the process of breaking up and connecting lines so
that lines are the same length as or shorter than the number specified
as the fill column. Lines are broken between words.) The default value
-is 72.
+is 72. Ignored with @samp{--html}.
@item --footnote-style=@var{style}
+@itemx -s @var{style}
@opindex --footnote-style=@var{style}
+@opindex -s @var{style}
Set the footnote style to @var{style}, either @samp{end} for the end
node style (the default) or @samp{separate} for the separate node style.
The value set by this option overrides the value set in a Texinfo file
footnote style is @samp{separate}, @code{makeinfo} makes a new node
containing the footnotes found in the current node. When the footnote
style is @samp{end}, @code{makeinfo} places the footnote references at
-the end of the current node.
+the end of the current node. Ignored with @samp{--html}.
@item --force
+@itemx -F
@opindex --force
+@opindex -F
Ordinarily, if the input file has errors, the output files are not
created. With this option, they are preserved.
@item --help
+@itemx -h
@opindex --help
+@opindex -h
Print a usage message listing all available options, then exit successfully.
+@item --html
+Generate HTML output rather than Info. @xref{makeinfo html}.
+
@item -I @var{dir}
@opindex -I @var{dir}
-Add @code{dir} to the directory search list for finding files that are
-included using the @code{@@include} command. By default,
-@code{makeinfo} searches only the current directory.
+Append @var{dir} to the directory search list for finding files that
+are included using the @code{@@include} command. By default,
+@code{makeinfo} searches only the current directory. If @var{dir} is
+not given, the current directory @file{.} is appended. Note that
+@var{dir} can actually be a list of several directories separated by the
+usual path separator character (@samp{:} on Unix, @samp{;} on
+MS-DOS/MS-Windows).
+
+@item --macro-expand=@var{file}
+@itemx -E @var{file}
+Output the Texinfo source with all the macros expanded to the named
+file. Normally, the results of macro expansion are used internally by
+@code{makeinfo} and then discarded. This option is used by
+@command{texi2dvi} if you are using an old version of @file{texinfo.tex}
+that does not support @code{@@macro}.
@item --no-headers
@opindex --no-headers
-Do not include menus or node lines in the output. This results in an
-@sc{ascii} file that you cannot read in Info since it does not contain
-the requisite nodes or menus. It is primarily useful to extract certain
-pieces of a manual into separate files to be included in a distribution,
-such as @file{INSTALL} files.
+@cindex Plain text output
+@cindex ASCII text output
+@cindex Generating plain text files
+@cindex @file{INSTALL} file, generating
+For Info output, do not include menus or node lines in the output and
+write to standard output (unless @option{--output} is specified). This
+results in an @sc{ascii} file that you cannot read in Info since it does
+not contain the requisite nodes or menus. It is primarily useful to
+extract certain pieces of a manual into separate files to be included in
+a distribution, such as @file{INSTALL} files.
+
+@cindex Navigation links, omitting
+For HTML output, if @samp{--no-split} is also specified, do not include a
+navigation links at the top of each node. @xref{makeinfo html}.
@item --no-split
@opindex --no-split
+@cindex Splitting of output files
+@cindex Output file splitting
Suppress the splitting stage of @code{makeinfo}. By default, large
output files (where the size is greater than 70k bytes) are split into
-smaller subfiles, each one approximately 50k bytes.
+smaller subfiles. For Info output, each one is approximately 50k bytes.
+For HTML output, each file contains one node (@pxref{makeinfo html}).
@item --no-pointer-validate
@itemx --no-validate
@opindex --no-pointer-validate
@opindex --no-validate
-Suppress the pointer-validation phase of @code{makeinfo}. Normally,
-after a Texinfo file is processed, some consistency checks are made to
-ensure that cross references can be resolved, etc.
-@xref{Pointer Validation}.@refill
+@cindex Pointer validation, suppressing
+Suppress the pointer-validation phase of @code{makeinfo}. This can also
+be done with the @code{@@novalidate} command (@pxref{Use TeX,,Use
+@TeX{}}). Normally, after a Texinfo file is processed, some consistency
+checks are made to ensure that cross references can be resolved, etc.
+@xref{Pointer Validation}.
@item --no-warn
@opindex --no-warn
references within it, and the nodes that are referenced do not actually
exist.
+@item --number-sections
+@opindex --number-sections
+Output chapter, section, and appendix numbers as in printed manuals.
+
@item --no-number-footnotes
@opindex --no-number-footnotes
Suppress automatic footnote numbering. By default, @code{makeinfo}
Specify that the output should be directed to @var{file} and not to the
file name specified in the @code{@@setfilename} command found in the
Texinfo source (@pxref{setfilename}). If @var{file} is @samp{-}, output
-goes to standard output and @samp{--no-split} is implied.
+goes to standard output and @samp{--no-split} is implied. For split
+HTML output, @var{file} is the name of the output file for the top node
+(@pxref{makeinfo html}).
@item -P @var{dir}
@opindex -P @var{dir}
-Prepend @code{dir} to the directory search list for @code{@@include}.
+Prepend @var{dir} to the directory search list for @code{@@include}.
+If @var{dir} is not given, the current directory @file{.} is prepended.
See @samp{-I} for more details.
@item --paragraph-indent=@var{indent}
+@itemx -p @var{indent}
@opindex --paragraph-indent=@var{indent}
+@opindex -p @var{indent}
Set the paragraph indentation style to @var{indent}. The value set by
this option overrides the value set in a Texinfo file by an
@code{@@paragraphindent} command (@pxref{paragraphindent}). The value
Delete any existing indentation.
@item @var{num}
-Indent each paragraph by that number of spaces.
+Indent each paragraph by @var{num} spaces.
@end table
@item --reference-limit=@var{limit}
+@itemx -r @var{limit}
@opindex --reference-limit=@var{limit}
+@opindex -r @var{limit}
Set the value of the number of references to a node that
@code{makeinfo} will make without reporting a warning. If a node has more
than this number of references in it, @code{makeinfo} will make the
warnings.
@item --version
+@itemx -V
@opindex --version
+@opindex -V
Print the version number, then exit successfully.
@end table
-@node Pointer Validation, makeinfo in Emacs, makeinfo options, Create an Info File
-@section Pointer Validation
+@node Pointer Validation
+@subsection Pointer Validation
@cindex Pointer validation with @code{makeinfo}
@cindex Validation of pointers
-If you do not suppress pointer-validation, @code{makeinfo} will check
-the validity of the final Info file. Mostly, this means ensuring that
-nodes you have referenced really exist. Here is a complete list of what
-is checked:@refill
+If you do not suppress pointer validation with the @samp{--no-validate}
+option or the @code{@@novalidate} command in the source file (@pxref{Use
+TeX,,Use @TeX{}}), @code{makeinfo} will check the validity of the final
+Info file. Mostly, this means ensuring that nodes you have referenced
+really exist. Here is a complete list of what is checked:
@enumerate
@item
@item
In every node, if the `Previous' node is different from the `Up' node,
-then the `Previous' node must also be pointed to by a `Next' node.@refill
+then the node pointed to by the `Previous' field must have a `Next'
+field which points back to this node.@refill
@item
Every node except the `Top' node must have an `Up' pointer.@refill
@item
-The node referenced by an `Up' pointer must contain a reference to the
-current node in some manner other than through a `Next' reference.
-This includes menu entries and cross references.@refill
+The node referenced by an `Up' pointer must itself reference the current
+node through a menu item, unless the node referenced by `Up'
+has the form `(@var{file})'.
@item
If the `Next' reference of a node is not the same as the `Next' reference
must have a `Previous' pointer that points back to the current node.
This rule allows the last node in a section to point to the first node
of the next chapter.@refill
+
+@item
+Every node except `Top' should be referenced by at least one other node,
+either via the `Previous' or `Next' links, or via a menu or a
+cross-reference.@refill
@end enumerate
-@node makeinfo in Emacs, texinfo-format commands, Pointer Validation, Create an Info File
-@section Running @code{makeinfo} inside Emacs
+@cindex @@-commands in @@node, limited support
+Some Texinfo documents might fail during the validation phase because
+they use commands like @code{@@value} and @code{@@definfoenclose} in
+node definitions and cross-references inconsistently. Consider the
+following example:
+
+@example
+@group
+@@set nodename Node 1
+
+@@node @@value@{nodename@}, Node 2, Top, Top
+
+This is node 1.
+
+@@node Node 2, , Node 1, Top
+
+This is node 2.
+@end group
+@end example
+
+@noindent
+Here, the node ``Node 1'' was referenced both verbatim and through
+@code{@@value}.
+
+By default, @code{makeinfo} fails such cases, because node names are not
+fully expanded until they are written to the output file. You should
+always try to reference nodes consistently; e.g., in the above example,
+the second @code{@@node} line should have also used @code{@@value}.
+However, if, for some reason, you @emph{must} reference node names
+inconsistently, and @code{makeinfo} fails to validate the file, you can
+use the @samp{--commands-in-node-names} option to force @code{makeinfo}
+to perform the expensive expansion of all node names it finds in the
+document. This might considerably slow down the program, though;
+twofold increase in conversion time was measured for large documents
+such as the Jargon file.
+
+@cindex @@value in @@node lines
+The support for @code{@@}-commands in @code{@@node} directives is not
+general enough to be freely used. For example, if the example above
+redefined @code{nodename} somewhere in the document, @code{makeinfo}
+will fail to convert it, even if invoked with the
+@samp{--commands-in-node-names} option.
+
+@samp{--commands-in-node-names} has no effect if the @samp{--no-validate}
+option is given.
+
+
+@node makeinfo in Emacs
+@subsection Running @code{makeinfo} inside Emacs
@cindex Running @code{makeinfo} in Emacs
@cindex @code{makeinfo} inside Emacs
@cindex Shell, running @code{makeinfo} in
(@code{next-error}). This causes Emacs to go to and position the
cursor on the line in the Texinfo source that @code{makeinfo} thinks
caused the error. @xref{Compilation, , Running @code{make} or
-Compilers Generally, xemacs, XEmacs User's Manual}, for more
+Compilers Generally, emacs, The GNU Emacs Manual}, for more
information about using the @code{next-error} command.@refill
In addition, you can kill the shell in which the @code{makeinfo}
@item C-c C-m C-k
@itemx M-x makeinfo-kill-job
@findex makeinfo-kill-job
-Kill the current running @code{makeinfo} job created by
-@code{makeinfo-region} or @code{makeinfo-buffer}.@refill
+Kill the current running @code{makeinfo} job
+(from @code{makeinfo-region} or @code{makeinfo-buffer}).@refill
@item C-c C-m C-l
@itemx M-x makeinfo-recenter-output-buffer
@c three references to the same named manual, which looks strange.
@iftex
For more information, see @ref{makeinfo options, , Options for
-@code{makeinfo}}, as well as ``Editing Variable Values,''``Examining and
-Setting Variables,'' and ``Init File'' in the @cite{The GNU Emacs
+@code{makeinfo}}, as well as ``Editing Variable Values,'' ``Examining
+and Setting Variables,'' and ``Init File'' in @cite{The GNU Emacs
Manual}.
@end iftex
@noindent
@ifinfo
For more information, see@*
-@ref{Edit Options, , Editing Variable Values, xemacs, XEmacs User's Manual},@*
-@ref{Examining, , Examining and Setting Variables, xemacs, XEmacs User's Manual},@*
-@ref{Init File, , , xemacs, XEmacs User's Manual}, and@*
+@ref{Edit Options, , Editing Variable Values, emacs, The GNU Emacs Manual},@*
+@ref{Examining, , Examining and Setting Variables, emacs, The GNU Emacs Manual},@*
+@ref{Init File, , , emacs, The GNU Emacs Manual}, and@*
@ref{makeinfo options, , Options for @code{makeinfo}}.
@end ifinfo
-@node texinfo-format commands, Batch Formatting, makeinfo in Emacs, Create an Info File
+@node texinfo-format commands
@comment node-name, next, previous, up
-@section The @code{texinfo-format@dots{}} Commands
+@subsection The @code{texinfo-format@dots{}} Commands
@findex texinfo-format-region
@findex texinfo-format-buffer
However, the @code{makeinfo} program is often faster and
provides better error checking (@pxref{makeinfo in Emacs}).@refill
-@node Batch Formatting, Tag and Split Files, texinfo-format commands, Create an Info File
+@node Batch Formatting
@comment node-name, next, previous, up
-@section Batch Formatting
+@subsection Batch Formatting
@cindex Batch formatting for Info
@cindex Info batch formatting
You can format Texinfo files for Info using @code{batch-texinfo-format}
and Emacs Batch mode. You can run Emacs in Batch mode from any shell,
including a shell inside of Emacs. (@xref{Command Switches, , Command
-Line Switches and Arguments, xemacs, XEmacs User's Manual}.)@refill
+Line Switches and Arguments, emacs, The GNU Emacs Manual}.)@refill
Here is a shell command to format all the files that end in
@file{.texinfo} in the current directory:
@code{texinfo-format-region} or @code{texinfo-format-buffer}, you cannot
use that Emacs for anything else until the command finishes.)@refill
-@node Tag and Split Files, , Batch Formatting, Create an Info File
+@node Tag and Split Files
@comment node-name, next, previous, up
-@section Tag Files and Split Files
+@subsection Tag Files and Split Files
@cindex Making a tag table automatically
@cindex Tag table, making automatically
large Info file into shorter @dfn{indirect} subfiles of about 50,000
bytes each. Big files are split into smaller files so that Emacs does
not need to make a large buffer to hold the whole of a large Info
-file; instead, Emacs allocates just enough memory for the small, split
-off file that is needed at the time. This way, Emacs avoids wasting
+file; instead, Emacs allocates just enough memory for the small, split-off
+file that is needed at the time. This way, Emacs avoids wasting
memory when you run Info. (Before splitting was implemented, Info
files were always kept short and @dfn{include files} were designed as
a way to create a single, large printed manual out of the smaller Info
files. @xref{Include Files}, for more information. Include files are
-still used for very large documents, such as @cite{The XEmacs Lisp
+still used for very large documents, such as @cite{The Emacs Lisp
Reference Manual}, in which each chapter is a separate file.)@refill
When a file is split, Info itself makes use of a shortened version of
the original file that contains just the tag table and references to
-the files that were split off. The split off files are called
+the files that were split off. The split-off files are called
@dfn{indirect} files.@refill
-The split off files have names that are created by appending @w{@samp{-1}},
+The split-off files have names that are created by appending @w{@samp{-1}},
@w{@samp{-2}}, @w{@samp{-3}} and so on to the file name specified by the
@code{@@setfilename} command. The shortened version of the original file
continues to have the name specified by @code{@@setfilename}.@refill
At one stage in writing this document, for example, the Info file was saved
-as @file{test-texinfo} and that file looked like this:@refill
+as the file @file{test-texinfo} and that file looked like this:@refill
@example
@group
@noindent
(But @file{test-texinfo} had far more nodes than are shown here.) Each of
-the split off, indirect files, @file{test-texinfo-1},
+the split-off, indirect files, @file{test-texinfo-1},
@file{test-texinfo-2}, and @file{test-texinfo-3}, is listed in this file
after the line that says @samp{Indirect:}. The tag table is listed after
the line that says @samp{Tag table:}. @refill
not counting the file list itself, the tag table, or the permissions
text in each file. In the tag table, the number following the node name
records the location of the beginning of the node, in bytes from the
-beginning.@refill
+beginning of the (unsplit) output.
If you are using @code{texinfo-format-buffer} to create Info files,
you may want to run the @code{Info-validate} command. (The
Info-validate}.@refill
-@node Install an Info File, Command List, Create an Info File, Top
-@comment node-name, next, previous, up
-@chapter Installing an Info File
+@node makeinfo html
+@subsection Generating HTML
+@cindex HTML
+
+As an alternative to the normal Info format output you can use the
+@samp{--html} option to generate output in HTML format, for installation
+on a web site (for example). In this release, HTML output from
+@code{makeinfo} is monolithic, splitting the output by chapter or node
+is not supported. We hope to implement this feature soon.
+
+The HTML output file is named according to @code{@@setfilename}, but
+with any @samp{.info} extension replaced with @samp{.html}.
+
+Texinfo input marked up with the @code{@@ifhtml} command will produce
+output only with the @samp{--html} option supplied. Input marked up
+with the @code{@@html} is passed literally to the output (suppressing
+the normal escaping of input @samp{<}, @samp{>} and @samp{&} characters
+which have special significance in HTML).
+
+The @samp{--footnote-style} option is currently ignored for HTML output;
+footnotes are hyperlinked at the end of the output file.
+
+The HTML generated is mostly standard (i.e., HTML 2.0, RFC1866). The
+exception is that HTML 3.2 tables are generated from the
+@code{@@multitable} command, but tagged to degrade as well as possible
+in browsers without table support. Please report output from an
+error-free run of @code{makeinfo} which violates the HTML 3.2 DTD as a
+bug.
+
+Navigation bars are inserted at the start of nodes, similarly to Info
+output. The @samp{--no-headers} option will suppress this if used with
+@samp{--no-split}. Header @code{<link>} elements in split output can
+support info-like navigation with browsers like Lynx and @w{Emacs W3}
+which implement this @w{HTML 1.0} feature. You still won't normally get
+the multi-file regexp and index search facilities provided by Info
+readers. Otherwise, hyperlinks are generated from Texinfo commands
+where appropriate. @samp{@@xref} commands to other documents are
+generated assuming the other document is available in HTML form too, and
+@samp{.html} is appended to the @samp{@@xref} Info file name. This
+presumably will often not work.
+
+
+@node Install an Info File
+@section Installing an Info File
@cindex Installing an Info file
@cindex Info file installation
@cindex @file{dir} directory for Info installation
into Emacs. (@inforef{Top, info, info}, for an introduction to Info.)
@menu
-* Directory file:: The top level menu for all Info files.
+* Directory File:: The top level menu for all Info files.
* New Info File:: Listing a new info file.
* Other Info Directories:: How to specify Info files that are
located in other directories.
* Invoking install-info:: @code{install-info} options.
@end menu
-@node Directory file, New Info File, Install an Info File, Install an Info File
-@ifinfo
-@heading The @file{dir} File
-@end ifinfo
+
+@node Directory File
+@subsection The Directory File @file{dir}
For Info to work, the @file{info} directory must contain a file that
serves as a top level directory for the Info system. By convention,
@example
@group
* Menu:
-
* Info: (info). Documentation browsing system.
* Emacs: (emacs). The extensible, self-documenting
text editor.
@end example
@noindent
-(Note that in this case, the @file{dir} file name is written in upper
-case letters---it can be written in either upper or lower case. Info
-has a feature that it will change the case of the file name to lower
-case if it cannot find the name as written.)@refill
-@c !!! Can any file name be written in upper or lower case,
-@c or is dir a special case?
-@c Yes, apparently so, at least with Gillespie's Info. --rjc 24mar92
+In this case, the @file{dir} file name is written in upper case
+letters---it can be written in either upper or lower case. This is not
+true in general, it is a special case for @file{dir}.
-@node New Info File, Other Info Directories, Directory file, Install an Info File
-@section Listing a New Info File
+@node New Info File
+@subsection Listing a New Info File
@cindex Adding a new info file
@cindex Listing a new info file
@cindex New info file, listing it in @file{dir} file
-@cindex Info file, listing new one
+@cindex Info file, listing a new
@cindex @file{dir} file listing
To add a new Info file to your system, you must write a menu entry to
The name of an Info file often has a @file{.info} extension. Thus, the
Info file for GDB might be called either @file{gdb} or @file{gdb.info}.
The Info reader programs automatically try the file name both with and
-without @file{.info}; so it is better to avoid clutter and not to write
-@samp{.info} explicitly in the menu entry. For example, the GDB menu
-entry should use just @samp{gdb} for the file name, not @samp{gdb.info}.
+without @file{.info}@footnote{On MS-DOS/MS-Windows systems, Info will
+try the @file{.inf} extension as well.}; so it is better to avoid
+clutter and not to write @samp{.info} explicitly in the menu entry. For
+example, the GDB menu entry should use just @samp{gdb} for the file
+name, not @samp{gdb.info}.
-@node Other Info Directories, Installing Dir Entries, New Info File, Install an Info File
-@comment node-name, next, previous, up
-@section Info Files in Other Directories
+@node Other Info Directories
+@subsection Info Files in Other Directories
@cindex Installing Info in another directory
@cindex Info installed in another directory
@cindex Another Info directory
+@cindex @file{dir} files and Info directories
If an Info file is not in the @file{info} directory, there are three
ways to specify its location:@refill
-@itemize @bullet
+@enumerate
@item
-Write the pathname in the @file{dir} file as the second part of the
-menu.@refill
+Write the pathname in the @file{dir} file as the second part of the menu.
@item
If you are using Emacs, list the name of the file in a second @file{dir}
@code{Info-directory-list} variable in your personal or site
initialization file.
-This tells Emacs where to look for @file{dir} files. Emacs merges the
-files named @file{dir} from each of the listed directories. (In Emacs
-version 18, you can set the @code{Info-directory} variable to the name
-of only one directory.)@refill
+This variable tells Emacs where to look for @file{dir} files (the files
+must be named @file{dir}). Emacs merges the files named @file{dir} from
+each of the listed directories. (In Emacs version 18, you can set the
+@code{Info-directory} variable to the name of only one
+directory.)@refill
@item
Specify the Info directory name in the @code{INFOPATH} environment
variable in your @file{.profile} or @file{.cshrc} initialization file.
(Only you and others who set this environment variable will be able to
-find Info files whose location is specified this way.)@refill
-@end itemize
+find Info files whose location is specified this way.)
+@end enumerate
-For example, to reach a test file in the @file{/home/bob/manuals}
+For example, to reach a test file in the @file{/home/bob/info}
directory, you could add an entry like this to the menu in the
-@file{dir} file:@refill
+standard @file{dir} file:@refill
@example
-* Test: (/home/bob/manuals/info-test). Bob's own test file.
+* Test: (/home/bob/info/info-test). Bob's own test file.
@end example
@noindent
In this case, the absolute file name of the @file{info-test} file is
written as the second part of the menu entry.@refill
-@vindex Info-directory-list
Alternatively, you could write the following in your @file{.emacs}
file:@refill
+@vindex Info-directory-list
@example
@group
+(require 'info)
(setq Info-directory-list
- '("/home/bob/manuals"
- "/usr/local/info"))
+ (cons (expand-file-name "/home/bob/info") Info-directory-list))
@end group
@end example
-@c reworded to avoid overfill hbox
This tells Emacs to merge the @file{dir} file from the
-@file{/home/bob/manuals} directory with the @file{dir} file from the
-@file{/usr/local/info} directory. Info will list the
-@file{/home/bob/manuals/info-test} file as a menu entry in the
-@file{/home/bob/manuals/dir} file.@refill
+@file{/home/bob/info} directory with the system @file{dir} file. Info
+will list the @file{/home/bob/info/info-test} file as a menu entry in
+the @file{/home/bob/info/dir} file. Emacs does the merging only
+when @kbd{M-x info} is first run, so if you want to set
+@code{Info-directory-list} in an Emacs session where you've already run
+@code{info}, you must @code{(setq Info-dir-contents nil)} to force Emacs
+to recompose the @file{dir} file.
@vindex INFOPATH
Finally, you can tell Info where to look by setting the @code{INFOPATH}
-environment variable in your @file{.cshrc} or @file{.profile} file. If
-you use a Bourne-compatible shell such as @code{sh} or @code{bash} for
-your shell command interpreter, you set the @code{INFOPATH} environment
-variable in the @file{.profile} initialization file; but if you use
-@code{csh} or @code{tcsh}, you must set the variable in the
-@file{.cshrc} initialization file. The two types of shells use
-different syntax.
+environment variable in your shell startup file, such as @file{.cshrc},
+@file{.profile} or @file{autoexec.bat}. If you use a Bourne-compatible
+shell such as @code{sh} or @code{bash} for your shell command
+interpreter, you set the @code{INFOPATH} environment variable in the
+@file{.profile} initialization file; but if you use @code{csh} or
+@code{tcsh}, you set the variable in the @file{.cshrc} initialization
+file. On MS-DOS/MS-Windows systems, you must set @code{INFOPATH} in
+your @file{autoexec.bat} file or in the Registry. Each type of shell
+uses a different syntax.
@itemize @bullet
@item
variable as follows:@refill
@smallexample
-setenv INFOPATH .:~/manuals:/usr/local/emacs/info
+setenv INFOPATH .:~/info:/usr/local/emacs/info
@end smallexample
@item
writing:@refill
@smallexample
-INFOPATH=.:$HOME/manuals:/usr/local/emacs/info
+INFOPATH=.:$HOME/info:/usr/local/emacs/info
export INFOPATH
@end smallexample
+
+@item
+@pindex autoexec.bat
+In a @file{autoexec.bat} file, you write this command@footnote{Note the
+use of @samp{;} as the directory separator, and a different syntax for
+using values of other environment variables.}:
+
+@smallexample
+set INFOPATH=.;%HOME%/info;c:/usr/local/emacs/info
+@end smallexample
@end itemize
@noindent
The @samp{.} indicates the current directory as usual. Emacs uses the
@code{INFOPATH} environment variable to initialize the value of Emacs's
-own @code{Info-directory-list} variable.
-
-@cindex colon @r{last in @code{INFOPATH}}
-However you set @code{INFOPATH}, if its last character is a colon, this
+own @code{Info-directory-list} variable. The stand-alone Info reader
+merges any files named @file{dir} in any directory listed in the
+@env{INFOPATH} variable into a single menu presented to you in the node
+called @samp{(dir)Top}.
+
+@cindex @samp{:} @r{last in @env{INFOPATH}}
+However you set @env{INFOPATH}, if its last character is a
+colon@footnote{On MS-DOS/MS-Windows systems, use semi-colon instead.}, this
is replaced by the default (compiled-in) path. This gives you a way to
augment the default path with new directories without having to list all
-the standard places. For example (using @code{sh} syntax:
+the standard places. For example (using @code{sh} syntax):
@example
INFOPATH=/local/info:
will search @file{/local/info} first, then the standard directories.
Leading or doubled colons are not treated specially.
+@cindex @file{dir} file, creating your own
+When you create your own @file{dir} file for use with
+@code{Info-directory-list} or @env{INFOPATH}, it's easiest to start by
+copying an existing @file{dir} file and replace all the text after the
+@samp{* Menu:} with your desired entries. That way, the punctuation and
+special CTRL-_ characters that Info needs will be present.
+
@node Installing Dir Entries, Invoking install-info, Other Info Directories, Install an Info File
-@section Installing Info Directory Files
+@subsection Installing Info Directory Files
When you install an Info file onto your system, you can use the program
@code{install-info} to update the Info directory file @file{dir}.
@findex dircategory
@findex direntry
In order for the Info file to work with @code{install-info}, you should
-use the commands @code{@@dircategory} and @code{@@direntry} in the
-Texinfo source file. Use @code{@@direntry} to specify the menu entry to
-add to the Info directory file, and use @code{@@dircategory} to specify
-which part of the Info directory to put it in. Here is how these
-commands are used in this manual:
+use the commands @code{@@dircategory} and
+@code{@@direntry}@dots{}@code{@@end direntry} in the Texinfo source
+file. Use @code{@@direntry} to specify the menu entries to add to the
+Info directory file, and use @code{@@dircategory} to specify which part
+of the Info directory to put it in. Here is how these commands are used
+in this manual:
@smallexample
@@dircategory Texinfo documentation system
will not notice them.
If you use @code{@@dircategory} more than once in the Texinfo source,
-each usage specifies one category; the new menu entry is added to the
-Info directory file in each of the categories you specify. If you use
-@code{@@direntry} more than once, each usage specifies one menu entry;
-each of these menu entries is added to the directory in each of the
-specified categories.
+each usage specifies the `current' category; any subsequent
+@code{@@direntry} commands will add to that category.
+
+Here are some recommended @code{@@dircategory} categories: `GNU
+packages', `GNU programming tools', `GNU programming documentation',
+`GNU Emacs Lisp', `GNU libraries', `Linux', `TeX', `Individual
+utilities'. The idea is to include the `invoking' node for every
+program installed by a package under `Individual utilities', and an
+entry for the manual as a whole in the appropriate other category.
-@node Invoking install-info, , Installing Dir Entries, Install an Info File
-@section Invoking install-info
+@node Invoking install-info
+@subsection Invoking install-info
@pindex install-info
@code{install-info} inserts menu entries from an Info file into the
top-level @file{dir} file in the Info system (see the previous sections
for an explanation of how the @file{dir} file works). It's most often
-run as part of software installation, or when constructing a dir file
+run as part of software installation, or when constructing a @file{dir} file
for all manuals on a system. Synopsis:
@example
install-info [@var{option}]@dots{} [@var{info-file} [@var{dir-file}]]
@end example
-If @var{info-file} or @var{dir-file} are not specified, the various
-options (described below) that define them must be. There are no
-compile-time defaults, and standard input is never used.
-@code{install-info} can read only one info file and write only one dir
-file per invocation.
+If @var{info-file} or @var{dir-file} are not specified, the options
+(described below) that define them must be. There are no compile-time
+defaults, and standard input is never used. @code{install-info} can
+read only one Info file and write only one @file{dir} file per invocation.
@cindex @file{dir}, created by @code{install-info}
If @var{dir-file} (however specified) does not exist,
@code{install-info} creates it if possible (with no entries).
+@cindex Compressed files, reading
+@cindex Dir files, compressed
+If any input file is compressed with @code{gzip} (@pxref{Invoking
+gzip,,,gzip, Gzip}), @code{install-info} automatically uncompresses it
+for reading. And if @var{dir-file} is compressed, @code{install-info}
+also automatically leaves it compressed after writing any changes.
+If @var{dir-file} itself does not exist, @code{install-info} tries to
+open @file{@var{dir-file}.gz}.
+
Options:
@table @code
an optional @samp{.info} in either one). Don't insert any new entries.
@item --dir-file=@var{name}
+@itemx -d @var{name}
@opindex --dir-file=@var{name}
+@opindex -d @var{name}
Specify file name of the Info directory file. This is equivalent to
using the @var{dir-file} argument.
@item --entry=@var{text}
+@itemx -e @var{text}
@opindex --entry=@var{text}
+@opindex -e @var{text}
Insert @var{text} as an Info directory entry; @var{text} should have the
form of an Info menu item line plus zero or more extra lines starting
with whitespace. If you specify more than one entry, they are all
information in the Info file itself.
@item --help
+@itemx -h
@opindex --help
+@opindex -h
Display a usage message listing basic usage and all available options,
then exit successfully.
@item --info-file=@var{file}
+@itemx -i @var{file}
@opindex --info-file=@var{file}
+@opindex -i @var{file}
Specify Info file to install in the directory.
-This is equivalent to using the @var{info-file} argument.
+Equivalent to using the @var{info-file} argument.
@item --info-dir=@var{dir}
+@itemx -D @var{dir}
@opindex --info-dir=@var{dir}
+@opindex -D @var{dir}
+Specify the directory where @file{dir} resides.
Equivalent to @samp{--dir-file=@var{dir}/dir}.
@item --item=@var{text}
Suppress warnings.
@item --remove
+@itemx -r
@opindex --remove
+@opindex -r
Same as @samp{--delete}.
@item --section=@var{sec}
+@itemx -s @var{sec}
@opindex --section=@var{sec}
+@opindex -s @var{sec}
Put this file's entries in section @var{sec} of the directory. If you
specify more than one section, all the entries are added in each of the
sections. If you don't specify any sections, they are determined from
information in the Info file itself.
@item --version
+@itemx -V
@opindex --version
+@opindex -V
@cindex version number, finding
Display version information and exit successfully.
@end table
-@node Command List, Tips, Install an Info File, Top
+@node Command List
@appendix @@-Command List
@cindex Alphabetical @@-command list
@cindex List of @@-commands
@cindex @@-command list
+@cindex Reference to @@-commands
Here is an alphabetical list of the @@-commands in Texinfo. Square
brackets, @t{[}@w{ }@t{]}, indicate optional arguments; an ellipsis,
-@samp{@dots{}}, indicates repeated text.@refill
+@samp{@dots{}}, indicates repeated text.
@sp 1
@table @code
mark, exclamation mark, or colon does not end a sentence. Prevent
@TeX{} from inserting extra whitespace as it does at the end of a
sentence. The command has no effect on the Info file output.
-@xref{Not Ending a Sentence}.@refill
+@xref{Not Ending a Sentence}.
@item @@=
-Generate a macro (bar) accent over the next character, as in @=o.
+Generate a macron (bar) accent over the next character, as in @=o.
@xref{Inserting Accents}.
@item @@?
Stands for a right-hand brace, @samp{@}}.@*
@xref{Braces Atsigns, , Inserting @@ and braces}.
-@item @@=
+@item @@~
Generate a tilde accent over the next character, as in @~N.
@xref{Inserting Accents}.
Generate the uppercase and lowercase Scandinavian A-ring letters,
respectively: @AA{}, @aa{}. @xref{Inserting Accents}.
+@item @@acronym@{@var{abbrev}@}
+Tag @var{abbrev} as an acronym, that is, an abbreviation written in all
+capital letters, such as `NASA'. @xref{acronym,, @code{acronym}}.
+
@item @@AE@{@}
@itemx @@ae@{@}
Generate the uppercase and lowercase AE ligatures, respectively:
@AE{}, @ae{}. @xref{Inserting Accents}.
-@item @@afourpaper
-Change page dimensions for the A4 paper size.
-Only allowed inside @code{@@iftex} @dots{} @code{@@end iftex}.
-@xref{A4 Paper}.
+@item @@afourlatex
+@itemx @@afourpaper
+@itemx @@afourwide
+Change page dimensions for the A4 paper size. @xref{A4 Paper}.
+
+@item @@alias @var{new}=@var{existing}
+Make the command @samp{@@@var{new}} an alias for the existing command
+@samp{@@@var{existing}}. @xref{alias}.
+
+@item @@anchor@{@var{name}@}
+Define @var{name} as the current location for use as a cross-reference
+target. @xref{anchor,, @code{@@anchor}}.
@item @@appendix @var{title}
Begin an appendix. The title appears in the table
Highlight text that is an expression, a syntactically complete token
of a program, or a program name. @xref{code, , @code{@@code}}.@refill
+@item @@command@{@var{command-name}@}
+Indicate a command name, such as @command{ls}.
+@xref{command,, @code{@@command}}.
+
@item @@comment @var{comment}
Begin a comment in Texinfo. The rest of the line does not appear in
either the Info file or the printed manual. A synonym for @code{@@c}.
-@xref{Comments, , Comments}.@refill
+@xref{Comments}.
@item @@contents
Print a complete table of contents. Has no effect in Info, which uses
Define a new index and its indexing command. Print entries in a roman
font. @xref{New Indices, , Defining New Indices}.@refill
-@c Unused so far as I can see and unsupported by makeinfo -- karl, 15sep96.
-@item @@definfoenclose @var{new-command}, @var{before}, @var{after},
-Create new @@-command for Info that marks text by enclosing it in
-strings that precede and follow the text. Write definition inside of
-@code{@@ifinfo} @dots{} @code{@@end ifinfo}. @xref{Customized
-Highlighting}.@refill
+@item @@definfoenclose @var{newcmd}, @var{before}, @var{after},
+Create new @@-command @var{newcmd} for Info that marks text by enclosing
+it in strings that precede and follow the text. @xref{definfoenclose}.
@item @@defivar @var{class} @var{instance-variable-name}
@itemx @@defivarx @var{class} @var{instance-variable-name}
@{Instance Variable@} @dots{}}. @xref{Definition Commands}, and
@ref{deffnx,, Def Cmds in Detail}.
-@item @@defmac @var{macro-name} @var{arguments}@dots{}
-@itemx @@defmacx @var{macro-name} @var{arguments}@dots{}
+@item @@defmac @var{macroname} @var{arguments}@dots{}
+@itemx @@defmacx @var{macroname} @var{arguments}@dots{}
Format a description for a macro. The command is equivalent to
@samp{@@deffn Macro @dots{}}. @xref{Definition Commands}, and
@ref{deffnx,, Def Cmds in Detail}.
@code{@@defop} takes as arguments the overall name of the category of
operation, the name of the class of the operation, the name of the
operation, and its arguments, if any. @xref{Definition
-Commands}, and @ref{deffnx,, Def Cmds in Detail}.
+Commands}, and @ref{Abstract Objects}.
@item @@defopt @var{option-name}
@itemx @@defoptx @var{option-name}
Format a description for a data type. @code{@@deftp} takes as arguments
the category, the name of the type (which is a word like @samp{int} or
@samp{float}), and then the names of attributes of objects of that type.
-@xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}.
+@xref{Definition Commands}, and @ref{Data Types}.
@item @@deftypefn @var{classification} @var{data-type} @var{name} @var{arguments}@dots{}
@itemx @@deftypefnx @var{classification} @var{data-type} @var{name} @var{arguments}@dots{}
@itemx @@deftypefunx @var{data-type} @var{function-name} @var{arguments}@dots{}
Format a description for a function in a typed language.
The command is equivalent to @samp{@@deftypefn Function @dots{}}.
-@xref{Definition Commands},
-and @ref{deffnx,, Def Cmds in Detail}.
+@xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}.
+
+@item @@deftypeivar @var{class} @var{data-type} @var{variable-name}
+@itemx @@deftypeivarx @var{class} @var{data-type} @var{variable-name}
+Format a description for a typed instance variable in object-oriented
+programming. @xref{Definition Commands}, and @ref{Abstract Objects}.
@item @@deftypemethod @var{class} @var{data-type} @var{method-name} @var{arguments}@dots{}
@itemx @@deftypemethodx @var{class} @var{data-type} @var{method-name} @var{arguments}@dots{}
Format a description for a typed method in object-oriented programming.
-Takes as arguments the name of the class of the method, the return type
-of the method, the name of the method, and its arguments, if any.
@xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}.
+@item @@deftypeop @var{category} @var{class} @var{data-type} @var{name} @var{arguments}@dots{}
+@itemx @@deftypeopx @var{category} @var{class} @var{data-type} @var{name} @var{arguments}@dots{}
+Format a description for a typed operation in object-oriented programming.
+@xref{Definition Commands}, and @ref{Abstract Objects}.
+
+@item @@deftypevar @var{data-type} @var{variable-name}
+@itemx @@deftypevarx @var{data-type} @var{variable-name}
+Format a description for a variable in a typed language. The command is
+equivalent to @samp{@@deftypevr Variable @dots{}}. @xref{Definition
+Commands}, and @ref{deffnx,, Def Cmds in Detail}.
+
@item @@deftypevr @var{classification} @var{data-type} @var{name}
@itemx @@deftypevrx @var{classification} @var{data-type} @var{name}
Format a description for something like a variable in a typed
entity. @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in
Detail}.
-@item @@deftypevar @var{data-type} @var{variable-name}
-@itemx @@deftypevarx @var{data-type} @var{variable-name}
-Format a description for a variable in a typed language. The command is
-equivalent to @samp{@@deftypevr Variable @dots{}}. @xref{Definition
-Commands}, and @ref{deffnx,, Def Cmds in Detail}.
-
@item @@defun @var{function-name} @var{arguments}@dots{}
@itemx @@defunx @var{function-name} @var{arguments}@dots{}
Format a description for functions. The command is equivalent to
@xref{Definition Commands},
and @ref{deffnx,, Def Cmds in Detail}.
-@item @@detailmenu@{@}
+@item @@detailmenu
Avoid @code{makeinfo} confusion stemming from the detailed node listing
in a master menu. @xref{Master Menu Parts}.
go. @xref{Installing Dir Entries}.
@item @@direntry
-Begin the Info directory menu entry for this file.
-@xref{Installing Dir Entries}.
+Begin the Info directory menu entry for this file. Pair with
+@code{@@end direntry}. @xref{Installing Dir Entries}.
-@need 100
@item @@display
-Begin a kind of example. Indent text, do not fill, do not select a
-new font. Pair with @code{@@end display}. @xref{display, ,
-@code{@@display}}.@refill
+Begin a kind of example. Like @code{@@example} (indent text, do not
+fill), but do not select a new font. Pair with @code{@@end display}.
+@xref{display, , @code{@@display}}.
@item @@dmn@{@var{dimension}@}
Format a unit of measure, as in 12@dmn{pt}. Causes @TeX{} to insert a
thin space before @var{dimension}. No effect in Info.
-@xref{dmn, , @code{@@dmn}}.@refill
+@xref{dmn, , @code{@@dmn}}.
+
+@item @@documentencoding @var{enc}
+Declare the input encoding as @var{enc}.
+@xref{documentencoding,, @code{@@documentencoding}}.
+
+@item @@documentlanguage @var{CC}
+Declare the document language as the two-character ISO-639 abbreviation
+@var{CC}. @xref{documentlanguage,, @code{@@documentlanguage}}.
@item @@dotaccent@{@var{c}@}
-Generate a dot accent over the character @var{c}, as in @dotaccent{oo}.
+Generate a dot accent over the character @var{c}, as in @dotaccent{o}.
@xref{Inserting Accents}.
@item @@dots@{@}
Insert an ellipsis: @samp{@dots{}}.
-@xref{dots, , @code{@@dots@{@}}}.@refill
+@xref{dots, , @code{@@dots}}.@refill
@item @@email@{@var{address}[, @var{displayed-text}]@}
Indicate an electronic mail address.
-@xref{email, , @code{@@email}}.@refill
+@xref{email, , @code{@@email}}.
-@need 100
@item @@emph@{@var{text}@}
Highlight @var{text}; text is displayed in @emph{italics} in printed
output, and surrounded by asterisks in Info. @xref{Emphasis, ,
Ends @var{environment}, as in @samp{@@end example}. @xref{Formatting
Commands,,@@-commands}.
+@item @@env@{@var{environment-variable}@}
+Indicate an environment variable name, such as @env{PATH}.
+@xref{env,, @code{@@env}}.
+
@item @@enddots@{@}
Generate an end-of-sentence of ellipsis, like this @enddots{}
@xref{dots,,@code{@@dots@{@}}}.
-@need 100
@item @@enumerate [@var{number-or-letter}]
Begin a numbered list, using @code{@@item} for each entry.
Optionally, start list with @var{number-or-letter}. Pair with
@code{@@end enumerate}. @xref{enumerate, ,
@code{@@enumerate}}.@refill
-@need 100
@item @@equiv@{@}
Indicate to the reader the exact equivalence of two forms with a
glyph: @samp{@equiv{}}. @xref{Equivalence}.@refill
Pair with @code{@@end example}. @xref{example, ,
@code{@@example}}.@refill
+@item @@exampleindent @var{indent}
+Indent example-like environments by @var{indent} number of spaces
+(perhaps 0). @xref{exampleindent,, Paragraph Indenting}.
+
@item @@exclamdown@{@}
Produce an upside-down exclamation point. @xref{Inserting Accents}.
Prevent @TeX{} from printing large black warning rectangles beside
over-wide lines. @xref{Overfull hboxes}.@refill
-@need 100
@item @@findex @var{entry}
Add @var{entry} to the index of functions. @xref{Index Entries, ,
Defining the Entries of an Index}.@refill
-@need 200
@item @@flushleft
@itemx @@flushright
Left justify every line but leave the right end ragged.
@xref{flushleft & flushright, , @code{@@flushleft} and
@code{@@flushright}}.@refill
-@need 200
@item @@footnote@{@var{text-of-footnote}@}
Enter a footnote. Footnote text is printed at the bottom of the page
by @TeX{}; Info may format in either `End' node or `Separate' node style.
@xref{Footnotes}.@refill
@item @@format
-Begin a kind of example. Like @code{@@example} or @code{@@display},
-but do not narrow the margins and do not select the fixed-width font.
-Pair with @code{@@end format}. @xref{example, ,
-@code{@@example}}.@refill
+Begin a kind of example. Like @code{@@display}, but do not narrow the
+margins. Pair with @code{@@end format}. @xref{example,,
+@code{@@example}}.
@item @@ftable @var{formatting-command}
Begin a two-column table, using @code{@@item} for each entry.
@item @@lisp
Begin an example of Lisp code. Indent text, do not fill, and select
-fixed-width font. Pair with @code{@@end lisp}. @xref{Lisp Example, ,
-@code{@@lisp}}.@refill
+fixed-width font. Pair with @code{@@end lisp}. @xref{lisp, , @code{@@lisp}}.
@item @@lowersections
Change subsequent chapters to sections, sections to subsections, and so
on. @xref{Raise/lower sections, , @code{@@raisesections} and
@code{@@lowersections}}.@refill
-@item @@macro @var{macro-name} @{@var{params}@}
-Define a new Texinfo command @code{@@@var{macro-name}@{@var{params}@}}.
+@item @@macro @var{macroname} @{@var{params}@}
+Define a new Texinfo command @code{@@@var{macroname}@{@var{params}@}}.
Only supported by @code{makeinfo} and @code{texi2dvi}. @xref{Defining
Macros}.
@item @@math@{@var{mathematical-expression}@}
Format a mathematical expression.
-@xref{math, , @code{@@math} - Inserting Mathematical Expressions}.
+@xref{math, , @code{@@math}: Inserting Mathematical Expressions}.
@item @@menu
Mark the beginning of a menu of nodes in Info. No effect in a printed
(thousandths of an inch) remain on the current page. @xref{need, ,
@code{@@need}}.@refill
-@item @@node @var{name, next, previous, up}
+@item @@node @var{name}, @var{next}, @var{previous}, @var{up}
Define the beginning of a new node in Info, and serve as a locator for
references for @TeX{}. @xref{node, , @code{@@node}}.@refill
Prevent text from being indented as if it were a new paragraph.
@xref{noindent, , @code{@@noindent}}.@refill
+@item @@novalidate
+Suppress validation of node references, omit creation of auxiliary files
+with @TeX{}. Use before @code{@@setfilename}. @xref{Pointer Validation}.
+
@item @@O@{@}
@itemx @@o@{@}
Generate the uppercase and lowercase O-with-slash letters, respectively:
Generate the uppercase and lowercase OE ligatures, respectively:
@OE{}, @oe{}. @xref{Inserting Accents}.
+@item @@option@{@var{option-name}@}
+Indicate a command-line option, such as @option{-l} or @option{--help}.
+@xref{option,, @code{@@option}}.
+
@item @@page
Start a new page in a printed manual. No effect in Info.
@xref{page, , @code{@@page}}.@refill
+@item @@pagesizes [@var{width}][, @var{height}]
+Change page dimensions. @xref{pagesizes}.
+
@item @@paragraphindent @var{indent}
-Indent paragraphs by @var{indent} number of spaces; delete indentation
-if the value of @var{indent} is 0; and do not change indentation if
-@var{indent} is @code{asis}. @xref{paragraphindent, , Paragraph
-Indenting}.@refill
+Indent paragraphs by @var{indent} number of spaces (perhaps 0); preserve
+source file indentation if @var{indent} is @code{asis}.
+@xref{paragraphindent,, Paragraph Indenting}.
@item @@pindex @var{entry}
Add @var{entry} to the index of programs. @xref{Index Entries, , Defining
@code{@@end quotation}. @xref{quotation, ,
@code{@@quotation}}.@refill
-@need 100
@item @@r@{@var{text}@}
Print @var{text} in @r{roman} font. No effect in Info.
@xref{Fonts}.@refill
on. @xref{Raise/lower sections, , @code{@@raisesections} and
@code{@@lowersections}}.@refill
-@need 300
@item @@ref@{@var{node-name}, [@var{entry}], [@var{topic-or-title}], [@var{info-file}], [@var{manual}]@}
Make a reference. In a printed manual, the reference does not start
with a `See'. Follow command with a punctuation mark. Only the first
argument is mandatory. @xref{ref, , @code{@@ref}}.@refill
-@need 300
@item @@refill
In Info, refill and indent the paragraph after all the other processing
has been done. No effect on @TeX{}, which always refills. This command
is no longer needed, since all formatters now automatically refill.
@xref{Refilling Paragraphs}.@refill
-@need 300
@item @@result@{@}
Indicate the result of an expression to the reader with a special
glyph: @samp{@result{}}. @xref{result, , @code{@@result}}.@refill
format text between subsequent pairs of @code{@@ifset @var{flag}} and
@code{@@end ifset} commands. Optionally, set value of @var{flag} to
@var{string}.
-@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill
+@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.
@item @@setchapternewpage @var{on-off-odd}
Specify whether chapters start on new pages, and if so, whether on
odd-numbered (right-hand) new pages. @xref{setchapternewpage, ,
-@code{@@setchapternewpage}}.@refill
+@code{@@setchapternewpage}}.
+
+@item @@setcontentsaftertitlepage
+Put the table of contents after the @samp{@@end titlepage} even if the
+@code{@@contents} command is not there. @xref{Contents}.
@item @@setfilename @var{info-file-name}
Provide a name to be used by the Info file. This command is essential
for @TeX{} formatting as well, even though it produces no output.
-@xref{setfilename, , @code{@@setfilename}}.@refill
+@xref{setfilename, , @code{@@setfilename}}.
+
+@item @@setshortcontentsaftertitlepage
+Place the short table of contents after the @samp{@@end titlepage}
+command even if the @code{@@shortcontents} command is not there.
+@xref{Contents}.
@item @@settitle @var{title}
Provide a title for page headers in a printed manual.
@code{@@summarycontents}. @xref{Contents, , Generating a Table of
Contents}.@refill
-@item @@shorttitlepage@{@var{title}@}
+@item @@shorttitlepage @var{title}
Generate a minimal title page. @xref{titlepage,,@code{@@titlepage}}.
-@need 400
@item @@smallbook
Cause @TeX{} to produce a printed manual in a 7 by 9.25 inch format
rather than the regular 8.5 by 11 inch format. @xref{smallbook, ,
-Printing Small Books}. Also, see @ref{smallexample & smalllisp, ,
-@code{@@smallexample} and @code{@@smalllisp}}.@refill
+Printing Small Books}. Also, see @ref{small}.
+
+@item @@smalldisplay
+Begin a kind of example. Like @code{@@smallexample} (indent text, no
+filling), but do not select the fixed-width font. In @code{@@smallbook}
+format, print text in a smaller font than with @code{@@display}. Pair
+with @code{@@end smalldisplay}. @xref{small}.
-@need 400
@item @@smallexample
Indent text to indicate an example. Do not fill, select fixed-width
font. In @code{@@smallbook} format, print text in a smaller font than
with @code{@@example}. Pair with @code{@@end smallexample}.
-@xref{smallexample & smalllisp, , @code{@@smallexample} and
-@code{@@smalllisp}}.@refill
+@xref{small}.
+
+@item @@smallformat
+Begin a kind of example. Like @code{@@smalldisplay}, but do not narrow
+the margins and do not select the fixed-width font.
+In @code{@@smallbook} format, print text in a smaller font than
+with @code{@@format}. Pair with @code{@@end smallformat}.
+@xref{small}.
-@need 400
@item @@smalllisp
Begin an example of Lisp code. Indent text, do not fill, select
fixed-width font. In @code{@@smallbook} format, print text in a
-smaller font. Pair with @code{@@end smalllisp}. @xref{smallexample &
-smalllisp, , @code{@@smallexample} and @code{@@smalllisp}}.@refill
+smaller font. Pair with @code{@@end smalllisp}. @xref{small}.
-@need 700
@item @@sp @var{n}
Skip @var{n} blank lines. @xref{sp, , @code{@@sp}}.@refill
@item @@ss@{@}
Generate the German sharp-S es-zet letter, @ss{}. @xref{Inserting Accents}.
-@need 700
-@item @@strong @var{text}
+@item @@strong @{@var{text}@}
Emphasize @var{text} by typesetting it in a @strong{bold} font for the
printed manual and by surrounding it with asterisks for Info.
@xref{emph & strong, , Emphasizing Text}.@refill
@code{@@shortcontents}. @xref{Contents, , Generating a Table of
Contents}.@refill
-@need 300
@item @@syncodeindex @var{from-index} @var{into-index}
Merge the index named in the first argument into the index named in
the second argument, printing the entries from the first index in
@code{@@code} font. @xref{Combining Indices}.@refill
-@need 300
@item @@synindex @var{from-index} @var{into-index}
Merge the index named in the first argument into the index named in
the second argument. Do not change the font of @var{from-index}
entries. @xref{Combining Indices}.@refill
-@need 100
@item @@t@{@var{text}@}
Print @var{text} in a @t{fixed-width}, typewriter-like font.
No effect in Info. @xref{Fonts}.@refill
@item @@tab
Separate columns in a multitable. @xref{Multitable Rows}.
-@need 400
@item @@table @var{formatting-command}
Begin a two-column table, using @code{@@item} for each entry. Write
each first column entry on the same line as @code{@@item}. First
subtitle author, , The @code{@@title} @code{@@subtitle} and
@code{@@author} Commands}.@refill
-@need 400
@item @@titlefont@{@var{text}@}
In a printed manual, print @var{text} in a larger than normal font.
Not relevant to Info, which does not have title pages.
@xref{titlefont center sp, , The @code{@@titlefont} @code{@@center}
and @code{@@sp} Commands}.@refill
-@need 300
@item @@titlepage
Indicate to Texinfo the beginning of the title page. Write command on
a line of its own. Pair with @code{@@end titlepage}. Nothing between
@code{@@titlepage} and @code{@@end titlepage} appears in Info.
@xref{titlepage, , @code{@@titlepage}}.@refill
-@need 150
@item @@today@{@}
Insert the current date, in `1 Jan 1900' style. @xref{Custom
Headings, , How to Make Your Own Headings}.@refill
manual. In Info, the title is underlined with periods.
@xref{subsubsection, , The `subsub' Commands}.@refill
-@item @@uref@{@var{url}[, @var{displayed-text}@}
+@item @@uref@{@var{url}[, @var{displayed-text}][, @var{replacement}@}
Define a cross reference to an external uniform resource locator for the
-World Wide Web. @xref{url, , @code{@@url}}.@refill
+World Wide Web. @xref{uref, , @code{@@uref}}.@refill
@item @@url@{@var{url}@}
Indicate text that is a uniform resource locator for the World Wide
another piece of text. @xref{var, , Indicating Metasyntactic
Variables}.@refill
-@need 400
@item @@vindex @var{entry}
Add @var{entry} to the index of variables. @xref{Index Entries, ,
Defining the Entries of an Index}.@refill
-@need 400
@item @@vskip @var{amount}
In a printed manual, insert whitespace so as to push text on the
remainder of the page towards the bottom of the page. Used in
only in contexts ignored for Info. @xref{Copyright & Permissions, ,
The Copyright Page and Printed Permissions}.@refill
-@need 400
@item @@vtable @var{formatting-command}
Begin a two-column table, using @code{@@item} for each entry.
Automatically enter each of the items in the first column into the
@code{@@table}, except for indexing. @xref{ftable vtable, ,
@code{@@ftable} and @code{@@vtable}}.@refill
-@need 400
@item @@w@{@var{text}@}
Prevent @var{text} from being split across two lines. Do not end a
paragraph that uses @code{@@w} with an @code{@@refill} command.
@xref{w, , @code{@@w}}.@refill
-@need 400
@item @@xref@{@var{node-name}, [@var{entry}], [@var{topic-or-title}], [@var{info-file}], [@var{manual}]@}
Make a reference that starts with `See' in a printed manual. Follow
command with a punctuation mark. Only the first argument is
@end table
-@node Tips, Sample Texinfo File, Command List, Top
+@node Tips
@appendix Tips and Hints
Here are some tips for writing Texinfo documentation:@refill
@item
Write the indexing commands that refer to a whole section immediately
after the section command, and write the indexing commands that refer to
-the paragraph before the paragraph.
+a paragraph before that paragraph.
-@need 1000
In the example that follows, a blank line comes after the index
entry for ``Leaping'':
@end itemize
-@node Sample Texinfo File, Sample Permissions, Tips, Top
+@node Sample Texinfo File
@appendix A Sample Texinfo File
@cindex Sample Texinfo file, no comments
@end example
-@node Sample Permissions, Include Files, Sample Texinfo File, Top
+@node Sample Permissions
@appendix Sample Permissions
@cindex Permissions
+@cindex Sample permissions
@cindex Copying permissions
Texinfo files should contain sections that tell the readers that they
Also, if you are writing a manual about software, you should explain
that the software is free and either include the GNU General Public
License (GPL) or provide a reference to it. @xref{Distrib, ,
-Distribution, xemacs, XEmacs User's Manual}, for an example of the text
+Distribution, emacs, The GNU Emacs Manual}, for an example of the text
that could be used in the software ``Distribution'', ``General Public
License'', and ``NO WARRANTY'' sections of a document. @xref{Copying,
, Texinfo Copying Conditions}, for an example of a brief explanation
@node Inserting Permissions, ifinfo Permissions, Sample Permissions, Sample Permissions
@ifinfo
-@appendixsec Inserting Permissions
+@section Inserting Permissions
@end ifinfo
In a Texinfo file, the first @code{@@ifinfo} section usually begins
the Texinfo file, sample permission notices for each section are
reproduced in full below.@refill
-Note that you may need to specify the correct name of a section
-mentioned in the permission notice. For example, in @cite{The GDB
-Manual}, the name of the section referring to the General Public
-License is called the ``GDB General Public License'', but in the
-sample shown below, that section is referred to generically as the
-``GNU General Public License''. If the Texinfo file does not carry a
-copy of the General Public License, leave out the reference to it, but
-be sure to include the rest of the sentence.@refill
+You may need to specify the correct name of a section mentioned in the
+permission notice. For example, in @cite{The GDB Manual}, the name of
+the section referring to the General Public License is called the ``GDB
+General Public License'', but in the sample shown below, that section is
+referred to generically as the ``GNU General Public License''. If the
+Texinfo file does not carry a copy of the General Public License, leave
+out the reference to it, but be sure to include the rest of the
+sentence.
@node ifinfo Permissions, Titlepage Permissions, Inserting Permissions, Sample Permissions
@comment node-name, next, previous, up
-@appendixsec @samp{ifinfo} Copying Permissions
+@section @samp{ifinfo} Copying Permissions
@cindex @samp{ifinfo} permissions
In the @code{@@ifinfo} section of a Texinfo file, the standard Free
@example
This file documents @dots{}
-Copyright 1998 Free Software Foundation, Inc.
+Copyright 1999 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim
copies of this manual provided the copyright notice and
@node Titlepage Permissions, , ifinfo Permissions, Sample Permissions
@comment node-name, next, previous, up
-@appendixsec Titlepage Copying Permissions
+@section Titlepage Copying Permissions
@cindex Titlepage permissions
In the @code{@@titlepage} section of a Texinfo file, the standard Free
@end example
-@node Include Files, Headings, Sample Permissions, Top
+@node Include Files
@appendix Include Files
@cindex Include files
@end menu
@node Using Include Files, texinfo-multiple-files-update, Include Files, Include Files
-@appendixsec How to Use Include Files
+@section How to Use Include Files
@findex include
To include another file within a Texinfo file, write the
designed for @code{@@include} files.@refill
@node texinfo-multiple-files-update, Include File Requirements, Using Include Files, Include Files
-@appendixsec @code{texinfo-multiple-files-update}
+@section @code{texinfo-multiple-files-update}
@findex texinfo-multiple-files-update
GNU Emacs Texinfo mode provides the @code{texinfo-multiple-files-update}
master menu.@refill
@node Include File Requirements, Sample Include File, texinfo-multiple-files-update, Include Files
-@appendixsec Include File Requirements
+@section Include File Requirements
@cindex Include file requirements
@cindex Requirements for include files
them.@refill
@node Sample Include File, Include Files Evolution, Include File Requirements, Include Files
-@appendixsec Sample File with @code{@@include}
+@section Sample File with @code{@@include}
@cindex Sample @code{@@include} file
@cindex Include file sample
@cindex @code{@@include} file sample
@group
@@page
@@vskip 0pt plus 1filll
-Copyright @@copyright@{@} 1998 Free Software Foundation, Inc.
+Copyright @@copyright@{@} 1999 Free Software Foundation, Inc.
@@end titlepage
@end group
@example
@group
-@@node Concept Index, , Second, Top
+@@node Concept Index
@@unnumbered Concept Index
@@printindex cp
@end group
@end example
-The outer Texinfo source file for @cite{The XEmacs Lisp Reference
+The outer Texinfo source file for @cite{The GNU Emacs Lisp Reference
Manual} is named @file{elisp.texi}. This outer file contains a master
menu with 417 entries and a list of 41 @code{@@include}
files.@refill
@node Include Files Evolution, , Sample Include File, Include Files
@comment node-name, next, previous, up
-@appendixsec Evolution of Include Files
+@section Evolution of Include Files
When Info was first created, it was customary to create many small
Info files on one subject. Each Info file was formatted from its own
no longer necessary to keep them small.@refill
Nowadays, multiple Texinfo files are used mostly for large documents,
-such as @cite{The XEmacs Lisp Reference Manual}, and for projects
+such as @cite{The GNU Emacs Lisp Reference Manual}, and for projects
in which several different people write different sections of a
document simultaneously.@refill
Texinfo files.@refill
-@node Headings, Catching Mistakes, Include Files, Top
+@node Headings
@appendix Page Headings
@cindex Headings
@cindex Footings
@node Heading Format, Heading Choice, Headings Introduced, Headings
@comment node-name, next, previous, up
-@appendixsec Standard Heading Formats
+@section Standard Heading Formats
Texinfo provides two standard heading formats, one for manuals printed
on one side of each sheet of paper, and the other for manuals printed
@node Heading Choice, Custom Headings, Heading Format, Headings
@comment node-name, next, previous, up
-@appendixsec Specifying the Type of Heading
+@section Specifying the Type of Heading
@TeX{} does not begin to generate page headings for a standard Texinfo
file until it reaches the @code{@@end titlepage} command. Thus, the
@node Custom Headings, , Heading Choice, Headings
@comment node-name, next, previous, up
-@appendixsec How to Make Your Own Headings
+@section How to Make Your Own Headings
You can use the standard headings provided with Texinfo or specify
your own. By default, Texinfo has no footers, so if you specify them,
the available page size for the main text will be slightly reduced.
-@c Following paragraph is verbose to prevent overfull hboxes.
Texinfo provides six commands for specifying headings and
-footings. The @code{@@everyheading} command and
-@code{@@everyfooting} command generate page headers and footers
-that are the same for both even- and odd-numbered pages.
-The @code{@@evenheading} command and @code{@@evenfooting}
-command generate headers and footers for even-numbered
-(left-hand) pages; and the @code{@@oddheading} command and
-@code{@@oddfooting} command generate headers and footers for
-odd-numbered (right-hand) pages.@refill
+footings:
+@itemize @bullet
+@item
+@code{@@everyheading} @code{@@everyfooting} generate page headers and
+footers that are the same for both even- and odd-numbered pages.
+@item
+@code{@@evenheading} and @code{@@evenfooting} command generate headers
+and footers for even-numbered (left-hand) pages.
+@item
+@code{@@oddheading} and @code{@@oddfooting} generate headers and footers
+for odd-numbered (right-hand) pages.
+@end itemize
Write custom heading specifications in the Texinfo file immediately
after the @code{@@end titlepage} command. Enclose your specifications
header or footer and blot it out.@refill
-@node Catching Mistakes, Refilling Paragraphs, Headings, Top
+@node Catching Mistakes
@appendix Formatting Mistakes
@cindex Structure, catching mistakes in
@cindex Nodes, catching mistakes
@node Debugging with Info, Debugging with TeX, makeinfo Preferred, Catching Mistakes
@comment node-name, next, previous, up
-@appendixsec Catching Errors with Info Formatting
+@section Catching Errors with Info Formatting
@cindex Catching errors with Info formatting
@cindex Debugging with Info formatting
@code{re-search-forward} was called; it was this function that could
not find the missing right-hand brace.@refill
-@xref{Lisp Debug, , Debugging Emacs Lisp, xemacs, XEmacs User's Manual},
-for more information.@refill
+@xref{Lisp Debug, , Debugging Emacs Lisp, emacs, The GNU Emacs
+Manual}, for more information.@refill
@end ignore
@node Debugging with TeX, Using texinfo-show-structure, Debugging with Info, Catching Mistakes
@comment node-name, next, previous, up
-@appendixsec Catching Errors with @TeX{} Formatting
+@section Catching Errors with @TeX{} Formatting
@cindex Catching errors with @TeX{} formatting
@cindex Debugging with @TeX{} formatting
at the @samp{?} prompt.@refill
@end enumerate
-Please note that if you are running @TeX{} inside Emacs, you need to
-switch to the shell buffer and line at which @TeX{} offers the @samp{?}
-prompt.@refill
+If you are running @TeX{} inside Emacs, you need to switch to the shell
+buffer and line at which @TeX{} offers the @samp{?} prompt.
Sometimes @TeX{} will format a file without producing error messages even
though there is a problem. This usually occurs if a command is not ended
@node Using texinfo-show-structure, Using occur, Debugging with TeX, Catching Mistakes
@comment node-name, next, previous, up
-@appendixsec Using @code{texinfo-show-structure}
+@section Using @code{texinfo-show-structure}
@cindex Showing the structure of a file
@findex texinfo-show-structure
window, you can position the cursor over one of the lines and use the
@kbd{C-c C-c} command (@code{occur-mode-goto-occurrence}), to jump to
the corresponding spot in the Texinfo file. @xref{Other Repeating
-Search, , Using Occur, xemacs, XEmacs User's Manual}, for more
+Search, , Using Occur, emacs, The GNU Emacs Manual}, for more
information about @code{occur-mode-goto-occurrence}.@refill
The first line in the @samp{*Occur*} window describes the @dfn{regular
expression} specified by @var{texinfo-heading-pattern}. This regular
expression is the pattern that @code{texinfo-show-structure} looks for.
-@xref{Regexps, , Using Regular Expressions, xemacs, XEmacs User's Manual},
+@xref{Regexps, , Using Regular Expressions, emacs, The GNU Emacs Manual},
for more information.@refill
When you invoke the @code{texinfo-show-structure} command, Emacs will
display the structure of the whole buffer. If you want to see the
structure of just a part of the buffer, of one chapter, for example,
use the @kbd{C-x n n} (@code{narrow-to-region}) command to mark the
-region. (@xref{Narrowing, , , xemacs, XEmacs User's Manual}.) This is
+region. (@xref{Narrowing, , , emacs, The GNU Emacs Manual}.) This is
how the example used above was generated. (To see the whole buffer
again, use @kbd{C-x n w} (@code{widen}).)@refill
@node Using occur, Running Info-Validate, Using texinfo-show-structure, Catching Mistakes
@comment node-name, next, previous, up
-@appendixsec Using @code{occur}
+@section Using @code{occur}
@cindex Occurrences, listing with @code{@@occur}
@findex occur
@noindent
and then, when prompted, type a @dfn{regexp}, a regular expression for
the pattern you want to match. (@xref{Regexps, , Regular Expressions,
-xemacs, XEmacs User's Manual}.) The @code{occur} command works from the
-current location of the cursor in the buffer to the end of the buffer.
-If you want to run @code{occur} on the whole buffer, place the cursor at
-the beginning of the buffer.@refill
+emacs, The GNU Emacs Manual}.) The @code{occur} command works from
+the current location of the cursor in the buffer to the end of the
+buffer. If you want to run @code{occur} on the whole buffer, place
+the cursor at the beginning of the buffer.@refill
For example, to see all the lines that contain the word
@samp{@@chapter} in them, just type @samp{@@chapter}. This will
all the nodes that are part of the same chapter or section and
therefore have the same `Up' pointer.@refill
-@xref{Other Repeating Search, , Using Occur, xemacs, XEmacs User's Manual},
+@xref{Other Repeating Search, , Using Occur, emacs , The GNU Emacs Manual},
for more information.@refill
@node Running Info-Validate, , Using occur, Catching Mistakes
@comment node-name, next, previous, up
-@appendixsec Finding Badly Referenced Nodes
+@section Finding Badly Referenced Nodes
@findex Info-validate
@cindex Nodes, checking for badly referenced
@cindex Checking for badly referenced nodes
@end menu
@node Using Info-validate, Unsplit, Running Info-Validate, Running Info-Validate
-@appendixsubsec Running @code{Info-validate}
+@subsection Running @code{Info-validate}
@cindex Running @code{Info-validate}
@cindex Info validating a large file
@cindex Validating a large file
@end example
@noindent
-(Note that the @code{Info-validate} command requires an upper case
+Note that the @code{Info-validate} command requires an upper case
`I'. You may also need to create a tag table before running
-@code{Info-validate}. @xref{Tagifying}.)@refill
+@code{Info-validate}. @xref{Tagifying}.
If your file is valid, you will receive a message that says ``File appears
valid''. However, if you have a pointer that does not point to a node,
@code{Info-validate} also checks that all menu entries and cross references
point to actual nodes.@refill
-Note that @code{Info-validate} requires a tag table and does not work
-with files that have been split. (The @code{texinfo-format-buffer}
-command automatically splits large files.) In order to use
-@code{Info-validate} on a large file, you must run
-@code{texinfo-format-buffer} with an argument so that it does not split
-the Info file; and you must create a tag table for the unsplit
-file.@refill
+@code{Info-validate} requires a tag table and does not work with files
+that have been split. (The @code{texinfo-format-buffer} command
+automatically splits large files.) In order to use @code{Info-validate}
+on a large file, you must run @code{texinfo-format-buffer} with an
+argument so that it does not split the Info file; and you must create a
+tag table for the unsplit file.
@node Unsplit, Tagifying, Using Info-validate, Running Info-Validate
@comment node-name, next, previous, up
-@appendixsubsec Creating an Unsplit File
+@subsection Creating an Unsplit File
@cindex Creating an unsplit file
@cindex Unsplit file creation
@cindex Tag table, making manually
@node Tagifying, Splitting, Unsplit, Running Info-Validate
-@appendixsubsec Tagifying a File
+@subsection Tagifying a File
After creating an unsplit Info file, you must create a tag table for
it. Visit the Info file you wish to tagify and type:@refill
@node Splitting, , Tagifying, Running Info-Validate
@comment node-name, next, previous, up
-@appendixsubsec Splitting a File Manually
+@subsection Splitting a File Manually
@cindex Splitting an Info file manually
@cindex Info file, splitting manually
You should split a large file or else let the
@code{texinfo-format-buffer} or @code{makeinfo-buffer} command do it
for you automatically. (Generally you will let one of the formatting
-commands do this job for you. @xref{Create an Info File}.)@refill
+commands do this job for you. @xref{Creating an Info File}.)@refill
The split-off files are called the indirect subfiles.@refill
the tag table and a directory of subfiles.@refill
-@node Refilling Paragraphs, Command Syntax, Catching Mistakes, Top
+@node Refilling Paragraphs
@appendix Refilling Paragraphs
@cindex Refilling paragraphs
@cindex Filling paragraphs
+@cindex Paragraphs, filling
@findex refill
The @code{@@refill} command refills and, optionally, indents the first
and therefore do not refill or indent them.@refill
-@node Command Syntax, Obtaining TeX, Refilling Paragraphs, Top
-@comment node-name, next, previous, up
+@node Command Syntax
@appendix @@-Command Syntax
@cindex @@-command syntax
+@cindex Syntax, of @@-commands
+@cindex Command syntax
The character @samp{@@} is used to start special Texinfo commands.
(It has the same meaning that @samp{\} has in plain @TeX{}.) Texinfo
a line.@refill
-@node Obtaining TeX, Command and Variable Index, Command Syntax, Top
+@node Obtaining TeX
@appendix How to Obtain @TeX{}
@cindex Obtaining @TeX{}
@cindex @TeX{}, how to obtain
@end example
The Free Software Foundation provides a core distribution on its Source
-Code CD-ROM suitable for printing Texinfo manuals; the University of
-Washington maintains and supports a tape distribution; the @TeX{} Users
-Group co-sponsors a complete CD-ROM @TeX{} distribution.
-
-@itemize @bullet
-
-@item
-For the FSF Source Code CD-ROM, please contact:
+Code CD-ROM suitable for printing Texinfo manuals. To order it, contact:
-@iftex
@display
@group
Free Software Foundation, Inc.
Electronic mail: @code{gnu@@gnu.org}
@end group
@end display
-@end iftex
-@ifinfo
-@display
-@group
-Free Software Foundation, Inc.
-59 Temple Place Suite 330
-Boston, MA @w{ } 02111-1307
-USA
-
-Telephone: @w{+1-617-542-5942}
-Fax: (including Japan) @w{+1-617-542-2652}
-Free Dial Fax (in Japan):
-@w{ } @w{ } @w{ } 0031-13-2473 (KDD)
-@w{ } @w{ } @w{ } 0066-3382-0158 (IDC)
-Electronic mail: @code{gnu@@gnu.org}
-@end group
-@end display
-@end ifinfo
-
-@item
-To order a complete distribution on CD-ROM, please see
-@uref{http://tug.org/tex-live.html}. (This distribution is also
-available by FTP; see the URL's above.)
-
-@item
-To order a full distribution from the University of Washington on either
-a 1/4@dmn{in} 4-track QIC-24 cartridge or a 4@dmn{mm} DAT cartridge,
-send $210 to:
-
-@display
-@group
-Pierre A. MacKay
-Denny Hall, Mail Stop DH-10
-University of Washington
-Seattle, WA @w{ } 98195
-USA
-Telephone: +1-206-543-2268
-Electronic mail: @code{mackay@@cs.washington.edu}
-@end group
-@end display
-
-@noindent
-Please make checks payable to the University of Washington.
-Checks must be in U.S.@: dollars, drawn on a U.S.@: bank. Overseas
-sites: please add to the base cost, if desired, $20.00 for shipment via
-air parcel post, or $30.00 for shipment via courier.
-
-@end itemize
Many other @TeX{} distributions are available; see
@uref{http://tug.org/}.
@c These are no longer ``new'', and the explanations
@c are all given elsewhere anyway, I think. --karl, 25apr97.
-@ignore (the entire appendix)
+@c So ignore the entire appendix.
+@ignore
@c node New Features, Command and Variable Index, Obtaining TeX, Top
@c appendix Second Edition Features
Here is a brief description of the new commands.@refill
-@menu
+@c menu
* New Texinfo Mode Commands:: The updating commands are especially useful.
* New Commands:: Many newly described @@-commands.
-@end menu
+@c end menu
@c node New Texinfo Mode Commands, New Commands, Obtaining TeX, Obtaining TeX
@c appendixsec New Texinfo Mode Commands
Insert node pointers in strict sequence.
@end table
-@c node New Commands, , New Texinfo Mode Commands, Obtaining TeX
-@c appendixsec New Texinfo @@-Commands
+@c no.de New Commands, , New Texinfo Mode Commands, Obtaining TeX
+@c appendix.sec New Texinfo @@-Commands
The second edition of the Texinfo manual describes more than 50
commands that were not described in the first edition. A third or so
see @ref{Footnotes},@*
see @ref{dmn, , Format a Dimension},@*
see @ref{Raise/lower sections, , @code{@@raisesections} and @code{@@lowersections}},@*
-see @ref{math, , @code{@@math} - Inserting Mathematical Expressions}.@*
+see @ref{math, , @code{@@math}: Inserting Mathematical Expressions}.@*
see @ref{minus, , Inserting a Minus Sign},@*
see @ref{paragraphindent, , Paragraph Indenting},@*
see @ref{Cross Reference Commands},@*
@end tex
@end ignore
-@node Command and Variable Index, Concept Index, Obtaining TeX, Top
-@comment node-name, next, previous, up
+
+@node Command and Variable Index
@unnumbered Command and Variable Index
This is an alphabetical list of all the @@-commands, assorted Emacs Lisp
@printindex fn
-@node Concept Index, , Command and Variable Index, Top
+@node Concept Index
@unnumbered Concept Index
@printindex cp
-@summarycontents
-@contents
@bye
projects / chise / xemacs-chise.git.1 / blobdiff