summaryrefslogtreecommitdiff
path: root/macros/texinfo/texinfo/doc/texinfo.texi
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2021-07-04 03:01:24 +0000
committerNorbert Preining <norbert@preining.info>2021-07-04 03:01:24 +0000
commit7994f86ec5e18f9d0d9f90161a2f26dd26d26af7 (patch)
tree88edb7d1a1aed3183a1350202c898716b4ac59ce /macros/texinfo/texinfo/doc/texinfo.texi
parent03fa062b03ce2bb5385f8f30888f94d441fa5cb4 (diff)
CTAN sync 202107040301
Diffstat (limited to 'macros/texinfo/texinfo/doc/texinfo.texi')
-rw-r--r--macros/texinfo/texinfo/doc/texinfo.texi4488
1 files changed, 2026 insertions, 2462 deletions
diff --git a/macros/texinfo/texinfo/doc/texinfo.texi b/macros/texinfo/texinfo/doc/texinfo.texi
index f0fb2412ab..51f12775a6 100644
--- a/macros/texinfo/texinfo/doc/texinfo.texi
+++ b/macros/texinfo/texinfo/doc/texinfo.texi
@@ -1,10 +1,5 @@
\input texinfo.tex @c -*-texinfo-*-
-@c Everything between the start/end of header lines will be passed by
-@c Emacs's {texinfo,makeinfo}-format region commands. See the `start of
-@c header' node for more info.
-@c %**start of header
-
@c Automake requires this
@setfilename texinfo.info
@@ -24,17 +19,12 @@
@c finalout
-@comment %**end of header
-
@copying
This manual is for GNU Texinfo (version @value{VERSION}, @value{UPDATED}),
a documentation system that can produce both online information and a
printed manual from a single source using semantic markup.
-Copyright @copyright{} 1988, 1990, 1991, 1992, 1993, 1995, 1996, 1997,
-1998, 1999, 2001, 2001, 2003, 2004, 2005, 2006, 2007, 2008, 2009,
-2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019 Free Software
-Foundation, Inc.
+Copyright @copyright{} 1988, 1990-1993, 1995-1999, 2001-2021 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
@@ -58,17 +48,6 @@ Texts. A copy of the license is included in the section entitled
* texindex: (texinfo)Format with tex/texindex. Sort Texinfo index files.
@end direntry
-@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 so this same source can be used for other paper sizes as well.
-@c smallbook
-@c set smallbook
-@c @@clear smallbook
-
-@c If you like blank pages, add through texi2dvi -t.
-@c setchapternewpage odd
-
@set txiindexatsignignore
@set txiindexbackslashignore
@set txiindexlessthanignore
@@ -83,9 +62,6 @@ Texts. A copy of the license is included in the section entitled
@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
@insertcopying
@@ -127,7 +103,6 @@ the menu lists all the lower-level nodes in the document.
* Copying Conditions:: Your rights.
* Overview:: Texinfo in brief.
* Writing a Texinfo File:: Format of a Texinfo source file.
-* Beginning and Ending a File:: Beginning and end of a Texinfo file.
* Nodes:: Writing nodes, the basic unit of Texinfo.
* Chapter Structuring:: Creating chapters, sections, appendices, etc.
* Cross References:: Writing cross-references.
@@ -157,8 +132,7 @@ Appendices
* Tips:: Hints on how to write a Texinfo document.
* Sample Texinfo Files:: Complete examples, including full texts.
* Texinfo Mode:: Using the GNU Emacs Texinfo mode.
-* Headings:: How to write page headings and footings.
-* Catching Mistakes:: How to find mistakes in formatting.
+* Global Document Commands:: Affecting formatting throughout.
* Info Format Specification:: Technical details of the Info file format.
* GNU Free Documentation License:: Copying this manual.
* Command and Variable Index:: A menu containing commands and variables.
@@ -182,17 +156,13 @@ Writing a Texinfo File
* Conventions:: General rules for writing a Texinfo file.
* Comments:: Writing comments and ignored text in general.
* Minimum:: What a Texinfo file must have.
-* Short Sample:: A short sample Texinfo file.
-
-Beginning and Ending a Texinfo File
-
-* Sample Beginning:: A sample beginning for a Texinfo file.
+* Short Sample Texinfo File:: A short sample Texinfo file.
* Texinfo File Header:: The first lines.
* Document Permissions:: Ensuring your manual is free.
* Titlepage & Copyright Page:: Creating the title and copyright pages.
* Contents:: How to create a table of contents.
* The Top Node:: Creating the `Top' node and master menu.
-* Global Document Commands:: Affecting formatting throughout.
+* The Body of the Document:: The rest of the nodes.
* Ending a File:: What is at the end of a Texinfo file?
Texinfo File Header
@@ -211,10 +181,10 @@ Document Permissions
Title and Copyright Pages
* @code{@@titlepage}:: Create a title for the printed document.
-* @code{@@titlefont @@center @@sp}:: The @code{@@titlefont}, @code{@@center},
- and @code{@@sp} commands.
* @code{@@title @@subtitle @@author}:: The @code{@@title}, @code{@@subtitle},
and @code{@@author} commands.
+* @code{@@titlefont @@center @@sp}:: The @code{@@titlefont}, @code{@@center},
+ and @code{@@sp} commands.
* Copyright:: How to write the copyright notice and
include copying permissions.
* Heading Generation:: Turn on page headings after the title and
@@ -222,29 +192,17 @@ Title and Copyright Pages
The `Top' Node and Master Menu
-* Top Node Example::
* Master Menu Parts::
-Global Document Commands
-
-* @code{@@documentdescription}:: Document summary for the HTML output.
-* @code{@@setchapternewpage}:: Start chapters on right-hand pages.
-* @code{@@headings}:: An option for turning headings on and off
- and double or single sided printing.
-* @code{@@paragraphindent}:: Specify paragraph indentation.
-* @code{@@firstparagraphindent}:: Suppressing first paragraph indentation.
-* @code{@@exampleindent}:: Specify environment indentation.
-
Nodes
-* Texinfo Document Structure:: How Texinfo manuals are usually arranged.
+* Writing a Node:: How to write a @code{@@node} line.
* Node Names:: How to choose node names.
-* Writing a Node:: How to write an @code{@@node} line.
* Node Line Requirements:: Keep names unique.
* First Node:: How to write a `Top' node.
* @code{@@top} Command:: How to use the @code{@@top} command.
+* Texinfo Document Structure:: How Texinfo manuals are usually arranged.
* Node Menu Illustration:: A diagram, and sample nodes and menus.
-* @command{makeinfo} Pointer Creation:: Letting makeinfo determine node pointers.
* Menus:: Listing subordinate nodes.
Menus
@@ -338,7 +296,7 @@ Quotations and Examples
* @code{@@verbatim}:: Writing a verbatim example.
* @code{@@verbatiminclude}:: Including a file verbatim.
* @code{@@lisp}:: Illustrating Lisp code.
-* @code{@@small@dots{}}:: Examples in a smaller font.
+* small:: Examples in a smaller font.
* @code{@@display}:: Writing an example in the current font.
* @code{@@format}:: Writing an example without narrowed margins.
* @code{@@exdent}:: Undo indentation on a line.
@@ -545,8 +503,6 @@ Include Files
* Include Files Requirements:: @code{texinfo-multiple-files-update} needs.
* Sample Include File:: A sample outer file with included files
within it; and a sample included file.
-* Include Files Evolution:: How use of the @code{@@include} command
- has changed over time.
Formatting and Printing Hardcopy
@@ -560,12 +516,7 @@ Formatting and Printing Hardcopy
* Requirements Summary:: @TeX{} formatting requirements summary.
* Preparing for @TeX{}:: What to do before you use @TeX{}.
* Overfull hboxes:: What are and what to do with overfull hboxes.
-* @code{@@smallbook}:: How to print small format books and manuals.
-* A4 Paper:: How to print on A4 or A5 paper.
-* @code{@@pagesizes}:: How to print with customized page sizes.
-* Magnification:: How to print scaled up output.
* PDF Output:: Portable Document Format output.
-* Obtaining @TeX{}:: How to obtain @TeX{}.
Format with @command{tex}/@command{texindex}
@@ -574,11 +525,9 @@ Format with @command{tex}/@command{texindex}
@command{texi2any}: The Generic Translator for Texinfo
-* Reference Implementation:: @command{texi2any}: the reference implementation.
* Invoking @command{texi2any}:: Running the translator from a shell.
* @command{texi2any} Environment Variables::
* @command{texi2any} Printed Output:: Calling @command{texi2dvi}.
-* Pointer Validation:: How to check that pointers point somewhere.
* Customization Variables:: Configuring @command{texi2any}.
* Internationalization of Document Strings:: Translating program-inserted text.
* Invoking @command{pod2texi}:: Translating Perl pod to Texinfo.
@@ -586,15 +535,18 @@ Format with @command{tex}/@command{texindex}
Customization Variables
-* Commands: Customization Variables for @@-Commands.
-* Options: Customization Variables and Options.
-* HTML: HTML Customization Variables.
-* Other: Other Customization Variables.
+* Customization Variables for @@-Commands::
+* Customization Variables and Options::
+* HTML Customization Variables::
+* @command{latex2html} Customization Variables::
+* MathJax Customization Variables::
+* Other Customization Variables::
Creating and Installing Info Files
* Creating an Info File::
* Installing an Info File::
+* Info Format FAQ::
Creating an Info File
@@ -609,7 +561,7 @@ Creating an Info File
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.
@@ -623,6 +575,7 @@ Generating HTML
* HTML Splitting:: How HTML output is split.
* HTML CSS:: Influencing HTML output with Cascading Style Sheets.
* HTML Xref:: Cross-references in HTML output.
+* @code{@@documentdescription}:: Document summary for the HTML output.
HTML Cross-references
@@ -635,7 +588,6 @@ HTML Cross-references
Sample Texinfo Files
-* Short Sample Texinfo File::
* GNU Sample Texts::
* Verbatim Copying License::
* All-permissive Copying License::
@@ -660,14 +612,6 @@ Updating Nodes and Menus
* Other Updating Commands:: How to indent descriptions, insert
missing nodes lines, and update
nodes in sequence.
-
-Page Headings
-
-* Headings Introduced:: Conventions for using page headings.
-* Heading Format:: Standard page heading formats.
-* Heading Choice:: How to specify the type of page heading.
-* Custom Headings:: How to create your own headings and footings.
-
Catching Mistakes
* @command{makeinfo} Preferred:: @code{makeinfo} finds errors.
@@ -677,6 +621,27 @@ Catching Mistakes
* Using @code{occur}:: How to list all lines containing a pattern.
* Running @code{Info-validate}:: How to find badly referenced nodes.
+Global Document Commands
+
+* @code{@@setchapternewpage}:: Start chapters on right-hand pages.
+* @code{@@headings}:: An option for turning headings on and off
+ and double or single sided printing.
+* Headings:: Page headings
+* @code{@@paragraphindent}:: Specify paragraph indentation.
+* @code{@@firstparagraphindent}:: Suppressing first paragraph indentation.
+* @code{@@exampleindent}:: Specify environment indentation.
+* @code{@@smallbook}:: How to print small format books and manuals.
+* A4 Paper:: How to print on A4, A5 or B6 paper.
+* @code{@@pagesizes}:: How to print with customized page sizes.
+* Magnification:: How to print scaled up output.
+
+Page Headings
+
+* @code{@@headings}:: An option for turning headings on and off
+ and double or single sided printing.
+* Heading Format:: Standard page heading formats.
+* Custom Headings:: How to create your own headings and footings.
+
Finding Badly Referenced Nodes
* Using @code{Info-validate}:: How to run @code{Info-validate}.
@@ -686,17 +651,17 @@ Finding Badly Referenced Nodes
Info Format Specification
-* General: Info Format General Layout.
-* Text: Info Format Text Constructs.
+* Info Format General Layout::
+* Info Format Text Constructs::
Info Format General Layout
-* Whole: Info Format Whole Manual. Split vs.@: nonsplit manuals.
-* Preamble: Info Format Preamble.
-* Indirect: Info Format Indirect Table.
-* Tag table: Info Format Tag Table.
-* Local variables: Info Format Local Variables.
-* Regular nodes: Info Format Regular Nodes.
+* Info Format Whole Manual::. Split vs.@: nonsplit manuals.
+* Info Format Preamble::
+* Info Format Indirect Table::
+* Info Format Tag Table::
+* Info Format Local Variables::
+* Info Format Regular Nodes::
Info Format Text Constructs
@@ -708,6 +673,7 @@ Info Format Text Constructs
@end detailmenu
@end menu
+@ifinfo
@c Reward readers for getting to the end of the menu :).
@c Contributed by Arnold Robbins.
@quotation
@@ -715,6 +681,7 @@ 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
+@end ifinfo
@node Copying Conditions
@@ -777,7 +744,7 @@ typesetting system) in PDF or PostScript format, including chapters,
sections, cross-references, and indices. From the same Texinfo source
file, you can create an HTML output file suitable for use with a web
browser, you can create an Info file with special features to make
-browsing documentation easy, and also create a Docbook file or a
+browsing documentation easy, and also create a DocBook file or a
transliteration to XML format.
@cindex Source file format
@@ -796,11 +763,11 @@ called Texinfo mode, that provides various Texinfo-related features.
Texinfo was devised specifically for the purpose of writing software
documentation and manuals. If you want to write a good manual for
your program, Texinfo has many features which we hope will make your
-job easier. However, it provides almost no commands for controlling
-the final formatting. Texinfo is not intended to be a general-purpose
-formatting program, so if you need to lay out a newspaper, devise a
-glossy magazine ad, or follow the exact formatting requirements of
-a publishing house, Texinfo may not be the simplest tool.
+job easier. However, Texinfo is not intended to be a general-purpose
+formatting program. It provides almost no commands for controlling
+the final formatting, so may be inappropriate for your needs if you
+if you want to lay out a newspaper, devise a glossy magazine ad,
+or follow the exact formatting requirements of a publishing house.
@cindex Spelling of Texinfo
@cindex Pronunciation of Texinfo
@@ -859,6 +826,9 @@ smallest possible input---the actual input with which you discovered
the bug will suffice. (Of course, if you do do experiments, the
smaller the input file, the better.)
+Any problems with the Info reader in Emacs should be reported to
+the Emacs developers: see @ref{Bugs,,, emacs, The GNU Emacs Manual}.
+
@cindex Patches, contributing
Patches are most welcome; if possible, please make them with
@samp{@w{diff -c}} (@pxref{Top,,, diffutils, Comparing and Merging
@@ -949,14 +919,14 @@ background. By default, Texinfo uses the @command{pdftex} program, an
extension of @TeX{}, to output PDF; see
@uref{http://tug.org/applications/pdftex}. @xref{PDF Output}.
-@item Docbook
-@cindex Docbook output, overview
-@cindex XML Docbook output, overview
+@item DocBook
+@cindex DocBook output, overview
+@cindex XML DocBook output, overview
(Generated via @command{makeinfo --docbook}.) This is an XML-based
format developed some years ago, primarily for technical
documentation. It therefore bears some resemblance, in broad
outline, to Texinfo. See @uref{http://www.docbook.org}. Various
-converters from Docbook @emph{to} Texinfo have also been developed;
+converters from DocBook @emph{to} Texinfo have also been developed;
see the Texinfo web pages.
@item XML
@@ -1042,42 +1012,27 @@ The @command{info} program itself does not follow URIs of any kind.
@cindex Knuth, Donald
A Texinfo file can be formatted and typeset as a printed book or
manual. To do this, you need @TeX{}, a sophisticated typesetting
-program written by Donald Knuth of Stanford University.
+program written by Donald Knuth of Stanford University. It is not part
+of the Texinfo distribution.
+
+Texinfo provides a file @file{texinfo.tex} that contains the definitions
+that @TeX{} uses when it typesets a Texinfo file.
+You can get the latest version of @file{texinfo.tex} from
+the Texinfo home page, @uref{http://www.gnu.org/software/texinfo/}.
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,
as well as chapters, numbered or unnumbered sections and subsections,
page headers, cross-references, footnotes, and indices.
-@TeX{} is a general purpose typesetting program. Texinfo provides a
-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. You can get the latest version of @file{texinfo.tex} from
-the Texinfo home page, @uref{http://www.gnu.org/software/texinfo/}.
-
-In the United States, documents are most often printed on 8.5 inch by
-11 inch pages (216@dmn{mm} by 280@dmn{mm}); this is the default size.
-But you can also print for 7 inch by 9.25 inch pages (178@dmn{mm} by
-235@dmn{mm}, the @code{@@smallbook} size; or on A4 or A5 size paper
-(@code{@@afourpaper}, @code{@@afivepaper}).
-@xref{@code{@@smallbook}}, and @ref{A4 Paper}.
-
-@cindex Literate programming
-@TeX{} is freely distributable. It is written in a superset of Pascal
-for literate programming called WEB and can be compiled either in
-Pascal or (by using a conversion program that comes with the @TeX{}
-distribution) in C.
-
-@TeX{} is very powerful and has a great many features. Because a
-Texinfo file must be able to present information both on a
+@TeX{} is very powerful and has a great many features. However,
+because a Texinfo file must be able to present information both on a
character-only terminal in Info form and in a typeset book, the
formatting commands that Texinfo supports are necessarily limited.
-@xref{Obtaining @TeX{}}, for information on acquiring @TeX{}. It is
-not part of the Texinfo distribution.
+@xref{Hardcopy}, for more information on processing a manual with
+@TeX{}.
+
@node Adding Output Formats
@@ -1142,13 +1097,15 @@ It is GNU software written by Brendan O'Dea, available from
@cindex Chassell, Robert J.
@cindex Fox, Brian
@cindex Berry, Karl
+@cindex Smith, Gavin
Richard M. Stallman invented the Texinfo format, wrote the initial
processors, and created Edition 1.0 of this manual. Robert@tie{}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 originally wrote the standalone
-@command{makeinfo} and @command{info} programs. Karl Berry has
-continued maintenance since Texinfo 3.8 (manual edition 2.22).
+@command{makeinfo} and @command{info} programs. Karl Berry
+continued maintenance from Texinfo 3.8 (manual edition 2.22), and Gavin
+Smith has continued maintenance since Texinfo 6.0.
@cindex Pinard, Fran@,{c}ois
@cindex Schwab, Andreas
@@ -1210,13 +1167,22 @@ Lionel Cons, later with substantial work by many others. The many
additional features needed to make @command{texi2html} a replacement
for @command{makeinfo} were implemented by Patrice Dumas. The first
never-released version of @command{texi2any} was based on the
-@command{texi2html} code. That implementation, however, was abandoned
-in favor of the current program, which parses the Texinfo input into a
-tree for processing. It still supports nearly all the features of
-@command{texi2html}.
+@command{texi2html} code.
-The new Perl program is much slower than the old C program. We hope
-the speed gap will close in the future, but it may not ever be
+@cindex Tree representation of documents
+@cindex Syntax tree representation of documents
+@cindex Abstract syntax tree representation of documents
+That implementation, however, was abandoned in favor of the current
+program (also written by Patrice Dumas), which parses the Texinfo
+input into a tree for processing. It inherited the design of
+customization and other features from @command{texi2html} (for more
+on @command{texi2html} compatibility, @pxref{@command{texi2html}}).
+However, @code{texi2any} is a full reimplementation: it constructs
+a tree-based representation of the input document for all back-ends
+to work from.
+
+The new Perl program is much slower than the old C program. The speed
+gap has partially closed since first release, but it may not ever be
entirely comparable. So why did we switch? In short, we intend and
hope that the present program will be much easier than the previous C
implementation of @command{makeinfo} to extend to different output
@@ -1252,11 +1218,33 @@ for anyone to read and contribute to, with the resulting obvious
benefits.
@end itemize
-@xref{Reference Implementation}, for more on the rationale for and
-role of @command{texi2any}.
+@cindex @command{texi2any}, as reference implementation
+@cindex Reference implementation
+@cindex Implementation, @command{texi2any} as reference
+@cindex Texinfo language tests
+@cindex Tests, of Texinfo language
+@anchor{Reference Implementation}@c
+@command{texi2any} is intended to be a reference implementation
+that defines parts of the language not fully specified by the manual.
+Without such a reference, alternative implementations would be very
+likely to have subtle, or not-so-subtle, differences in behavior,
+and thus Texinfo documents would become dependent on the processor.
+It is also important to have consistent command-line options for
+all processors. Extensive tests of the language and processor were
+developed at the same time as @command{texi2any}; we encourage anyone
+thinking of writing a program to parse Texinfo input to make use of
+these tests.
+
+@cindex Future of Texinfo implementations
+With the release of @command{texi2any} as the reference
+implementation, development of both the C implementation of
+@command{makeinfo} and @command{texi2html} has been halted. Going
+forward, we ask authors of Texinfo documents to use only
+@command{texi2any}.
@node Writing a Texinfo File
+@anchor{Beginning and Ending a File}@c old name
@chapter Writing a Texinfo File
This chapter describes Texinfo syntax and what is required in a Texinfo
@@ -1266,7 +1254,14 @@ file, and gives a short sample file.
* Conventions:: General rules for writing a Texinfo file.
* Comments:: Writing comments and ignored text in general.
* Minimum:: What a Texinfo file must have.
-* Short Sample:: A short sample Texinfo file.
+* Short Sample Texinfo File:: A short sample Texinfo file.
+* Texinfo File Header:: The first lines.
+* Document Permissions:: Ensuring your manual is free.
+* Titlepage & Copyright Page:: Creating the title and copyright pages.
+* Contents:: How to create a table of contents.
+* The Top Node:: Creating the `Top' node and master menu.
+* The Body of the Document:: The rest of the nodes.
+* Ending a File:: What is at the end of a Texinfo file?
@end menu
@@ -1292,7 +1287,7 @@ an @samp{@@} character in front of it, like this: @samp{@@@@},
@samp{@@@{}, and @samp{@@@}}.
@item
-@cindex @@-commands
+@cindex @sortas{at} @@-commands
@cindex Formatting commands
In a Texinfo file, the commands you write to describe the contents of
the manual are preceded by an @samp{@@} character; they are called
@@ -1300,16 +1295,7 @@ the manual are preceded by an @samp{@@} character; they are called
@samp{\} has in plain @TeX{}.)
@cindex Braces, when to use
-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 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
+Depending on what they do or what arguments they take, you
need to write @@-commands on lines of their own, or as part of
sentences. As a general rule, a command requires braces if it mingles
among other text; but it does not need braces if it is on a line of its
@@ -1344,9 +1330,24 @@ any number of hyphens in the source remain as they are in literal
contexts, such as @code{@@code} and @code{@@example}.
@item
+Do not use tab characters in a Texinfo file!
+(Except perhaps in verbatim modes.) @TeX{} uses variable-width fonts,
+which means that it is impractical at best to define a tab to work in
+all circumstances. Consequently, @TeX{} treats tabs like single
+spaces, and that is not what they look like in the source.
+Furthermore, @code{makeinfo} does nothing special with tabs, and thus
+a tab character in your input file will usually have a different
+appearance in the output.
+
+To avoid this problem, Texinfo mode in GNU Emacs inserts
+multiple spaces when you press the @key{TAB} key. Also, you can run
+@code{untabify} in Emacs to convert tabs in a region to multiple
+spaces, or use the @code{unexpand} command from the shell.
+
+@item
@cindex Form feed characters
@cindex @kbd{CTRL-l}
-Form feed (@kbd{CTRL-l}) characters in the input are handled as
+Lastly, form feed (@kbd{CTRL-l}) characters in the input are handled as
follows:
@table @asis
@@ -1368,29 +1369,13 @@ ignored.
Keep them everywhere; in attributes, escaped as @samp{\f}; also,
@samp{\} is escaped as @samp{\\} and newline as @samp{\n}.
-@item Docbook
+@item DocBook
Completely removed, as they are not allowed.
@end table
As you can see, because of these differing requirements of the output
formats, it's not possible to use form feeds completely portably.
-@item
-@cindex Tabs; don't use!
-@strong{Caution:} Last, do not use tab characters in a Texinfo file!
-(Except perhaps in verbatim modes.) @TeX{} uses variable-width fonts,
-which means that it is impractical at best to define a tab to work in
-all circumstances. Consequently, @TeX{} treats tabs like single
-spaces, and that is not what they look like in the source.
-Furthermore, @code{makeinfo} does nothing special with tabs, and thus
-a tab character in your input file will usually have a different
-appearance in the output.
-
-@noindent
-To avoid this problem, Texinfo mode in GNU Emacs inserts
-multiple spaces when you press the @key{TAB} key. Also, you can run
-@code{untabify} in Emacs to convert tabs in a region to multiple
-spaces, or use the @code{unexpand} command from the shell.
@end itemize
@@ -1440,7 +1425,6 @@ regarding nesting of such commands, @pxref{Conditional Nesting}.)
@node Minimum
@section What a Texinfo File Must Have
@cindex Minimal Texinfo file (requirements)
-@cindex Must have in Texinfo file
@cindex Required in Texinfo file
@cindex Texinfo file minimum
@@ -1467,29 +1451,11 @@ must end the Texinfo source with a line like this:
@end example
@findex \input @r{(raw @TeX{} startup)}
-@noindent
-Here's an explanation:
-@itemize @bullet
-@item
-The @samp{\input texinfo} line tells @TeX{} to use the
-@file{texinfo.tex} file, which tells @TeX{} how to translate the Texinfo
-@@-commands into @TeX{} typesetting commands. (Note the use of the
-backslash, @samp{\}; this is correct for @TeX{}.)
-
-@item
-The @code{@@settitle} line specifies a title for the page headers (or
-footers) of the printed manual, and the default title and document
-description for the @samp{<head>} in HTML@. Strictly speaking,
-@code{@@settitle} is optional---if you don't mind your document being
-titled `Untitled'.
-
-@item
The @code{@@bye} line at the end of the file on a line of its own tells
the formatters that the file is ended and to stop formatting. If you
leave this out, you'll be dumped at @TeX{}'s prompt at the end of the
run.
-@end itemize
Furthermore, you will usually provide a Texinfo file with a title page,
indices, and the like, all of which are explained in this manual. But
@@ -1498,138 +1464,57 @@ lines at the beginning and the one line at the end.
-@node Short Sample
-@section A Short Sample Texinfo File
-@cindex Sample Texinfo file, with comments
-
-Here is a short but complete Texinfo file, so you can see how Texinfo
-source appears in practice. The first three parts of the file are
-mostly boilerplate: when writing a manual, you simply change
-the names as appropriate.
-
-The complete file, without interspersed comments, is shown in
-@ref{Short Sample Texinfo File}.
-
-@xref{Beginning and Ending a File}, for more documentation on the
-commands listed here.
-
+@node Short Sample Texinfo File
+@anchor{Short Sample}@c
+@anchor{Sample Beginning}@c
+@section Short Sample
+@cindex Sample Texinfo file, no comments
-@subheading Header
+Here is a short sample Texinfo file. The @command{makeinfo}
+program transforms a Texinfo source file such as this into an Info
+file or HTML, and @TeX{} typesets it for a printed manual.
-@noindent
-The header tells @TeX{} which definitions file to
-use, names the manual, and carries out other such housekeeping tasks.
@example
-@group
\input texinfo
@@settitle Sample Manual 1.0
-@end group
-@end example
-
-@subheading Summary Description and Copyright
-
-This segment describes the document and contains the copyright notice
-and copying permissions. This is done with the @code{@@copying} command.
-
-@noindent
-A real manual includes more text here, according to the license under
-which it is distributed. @xref{GNU Sample Texts}.
-
-@example
-@group
@@copying
-This is a short example of a complete Texinfo file, version 1.0.
+This is a short example of a complete Texinfo file.
Copyright @@copyright@{@} 2016 Free Software Foundation, Inc.
@@end copying
-@end group
-@end example
-
-@subheading Titlepage, Copyright, Contents
-
-The title and copyright segment contains the title and copyright
-pages for the printed manual. The segment must be enclosed between
-@code{@@titlepage} and @code{@@end titlepage} commands. The title and
-copyright page does not appear in the online output.
-@noindent
-We use the @code{@@insertcopying} command to
-include the permission text from the previous section, instead of
-writing it out again; it is output on the back of the title page. The
-@code{@@contents} command generates a table of contents.
-
-@example
-@group
@@titlepage
@@title Sample Title
-@end group
-
-@group
-@@c The following two commands start the copyright page.
@@page
@@vskip 0pt plus 1filll
@@insertcopying
@@end titlepage
-@end group
-@@c Output the table of contents at the beginning.
@@contents
-@end example
-
-@subheading `Top' Node and Master Menu
-
-The `Top' node starts off the online output; it does not appear in the
-printed manual. We repeat the short description from the beginning of
-the @samp{@@copying} text, but there's no need to repeat the copyright
-information, so we don't use @samp{@@insertcopying} here.
-
-The @samp{@@top} command itself helps @command{makeinfo} determine
-the relationships between nodes. The `Top' node contains at least a
-top-level @dfn{menu} listing the chapters, and possibly a @dfn{Master
-Menu} listing all the nodes in the entire document.
-
-@example
-@@ifnottex
@@node Top
-@@top Short Sample
+@@top GNU Sample
-This is a short sample Texinfo file.
-@@end ifnottex
+This manual is for GNU Sample
+(version @@value@{VERSION@}, @@value@{UPDATED@}).
-@group
@@menu
* First Chapter:: The first chapter is the
- only chapter in this sample.
+ only chapter in this sample.
* Index:: Complete index.
@@end menu
-@end group
-@end example
-@subheading The Body of the Document
-
-@noindent
-The body segment contains all the text of the document, but not the
-indices or table of contents. This example illustrates a node and a
-chapter containing an enumerated list.
-
-@example
@group
@@node First Chapter
@@chapter First Chapter
@@cindex chapter, first
-@end group
-
-@group
This is the first chapter.
@@cindex index entry, another
-@end group
-@group
Here is a numbered list.
@@enumerate
@@ -1639,156 +1524,27 @@ This is the first item.
@@item
This is the second item.
@@end enumerate
-@end group
-@end example
-
-
-@subheading The End of the Document
-
-This may contain commands for printing indices, and
-closes with the @code{@@bye} command, which marks the end of the document.
-
-@example
-@group
-@@node Index
-@@unnumbered Index
-@end group
-
-@group
-@@printindex cp
-
-@@bye
-@end group
-@end example
-
-
-@subheading Some Results
-
-Here is what the contents of the first chapter of the sample look like:
-
-@sp 1
-@need 700
-@quotation
-This is the first chapter.
-
-Here is a numbered list.
-
-@enumerate
-@item
-This is the first item.
-
-@item
-This is the second item.
-@end enumerate
-@end quotation
-
-@node Beginning and Ending a File
-@anchor{Beginning a File} @c old name
-@chapter Beginning and Ending a Texinfo File
-@cindex Beginning a Texinfo file
-@cindex Texinfo file beginning
-@cindex File beginning
-This chapter expands on the minimal complete Texinfo source file
-previously given (@pxref{Short Sample}).
+@@node First Section
+@@section First Section
-Certain pieces of information must be provided at the beginning of a
-Texinfo file, such as the title of the document and the Top node. A table
-of contents is also generally produced here.
+First section of first chapter.
-@cindex Frontmatter, text in
-Straight text outside of any command before the Top node should be
-avoided. Such text is treated differently in the different output
-formats: at the time of writing, it is visible in @TeX{} and HTML, by
-default not shown in Info readers, and so on.
-
-@menu
-* Sample Beginning:: A sample beginning for a Texinfo file.
-* Texinfo File Header:: The first lines.
-* Document Permissions:: Ensuring your manual is free.
-* Titlepage & Copyright Page:: Creating the title and copyright pages.
-* Contents:: How to create a table of contents.
-* The Top Node:: Creating the `Top' node and master menu.
-* Global Document Commands:: Affecting formatting throughout.
-* Ending a File:: What is at the end of a Texinfo file?
-@end menu
-
-
-@node Sample Beginning
-@section Sample Texinfo File Beginning
-
-@cindex Example beginning of Texinfo file
-
-The following sample shows what is needed. The elements given here are
-explained in more detail in the following sections. Other commands are
-often included at the beginning of Texinfo files, but the ones here are
-the most critical.
-
-@xref{GNU Sample Texts}, for the full texts to be used in GNU manuals.
-
-@example
-\input texinfo
-@@settitle @var{name-of-manual} @var{version}
-
-@@copying
-This manual is for @var{program}, version @var{version}.
-Copyright @@copyright@{@} @var{years} @var{copyright-owner}.
+@@node Second Section
+@@section Second Section
-@group
-@@quotation
-Permission is granted to @dots{}
-@@end quotation
-@@end copying
+Second section of first chapter.
@end group
-@group
-@@titlepage
-@@title @var{name-of-manual-when-printed}
-@@subtitle @var{subtitle-if-any}
-@@subtitle @var{second-subtitle}
-@@author @var{author}
-@end group
-
-@group
-@@c The following two commands
-@@c start the copyright page.
-@@page
-@@vskip 0pt plus 1filll
-@@insertcopying
-@end group
-
-Published by @dots{}
-@@end titlepage
-
-@@c So the toc is printed at the start.
-@@contents
-
-@@ifnottex
-@@node Top
-@@top @var{title}
-This manual is for @var{program}, version @var{version}.
-@@end ifnottex
-
-@group
-@@menu
-* First Chapter:: Getting started @dots{}
-* Second Chapter:: @dots{}
- @dots{}
-* Copying:: Your rights and freedoms.
-@@end menu
-@end group
+@@node Index
+@@unnumbered Index
-@group
-@@node First Chapter
-@@chapter First Chapter
+@@printindex cp
-@@cindex first chapter
-@@cindex chapter, first
-@dots{}
-@end group
+@@bye
@end example
@@ -1797,20 +1553,7 @@ This manual is for @var{program}, version @var{version}.
@cindex Header for Texinfo files
@cindex Texinfo file header
-Texinfo files start with at least two lines. These are the
-@code{\input texinfo} line and the @code{@@settitle} line.
-
-Also, if you want to format just part of the Texinfo file in Emacs,
-you must write the @code{@@settitle} line between start-of-header and
-end-of-header lines. These start- and end-of-header lines are optional,
-but they do no harm, so you might as well always include them.
-
-Any command that affects document formatting as a whole makes sense to
-include in the header. @code{@@synindex} (@pxref{@code{@@synindex}}),
-for instance, is another command often included in the header.
-
-Thus, the beginning of a Texinfo file looks approximately
-like this:
+Texinfo files start with at least two lines:
@example
@group
@@ -1819,7 +1562,25 @@ like this:
@end group
@end example
-(@xref{GNU Sample Texts} for complete sample texts.)
+The @samp{\input texinfo} line tells @TeX{} to use the
+@file{texinfo.tex} file, which tells @TeX{} how to translate the Texinfo
+@@-commands into @TeX{} typesetting commands. (Note the use of the
+backslash, @samp{\}; this is correct for @TeX{}.)
+
+The @code{@@settitle} line specifies a title for the page headers (or
+footers) of the printed manual, and the default title and document
+description for the @samp{<head>} in HTML@. (Strictly speaking,
+@code{@@settitle} is optional---if you don't mind your document being
+titled `Untitled'.)
+
+Also, you can optionally write the @code{@@settitle} line between
+start-of-header and end-of-header lines
+if you want to format just part of the Texinfo file in Emacs.
+
+It makes sense to include any command that affects document formatting
+as a whole in the header. @code{@@synindex} (@pxref{@code{@@synindex}}),
+for instance, is another command often included in the header.
+
@menu
* First Line:: The first line of a Texinfo file.
@@ -1893,8 +1654,6 @@ change it if you wish by setting the @code{tex-start-of-header} and/or
@anchor{setfilename}@c old name
@findex setfilename
-@cindex Texinfo requires @code{@@setfilename}
-@cindex Output file name, required
The @code{@@setfilename} line specifies the name of the output file to
be generated.
@@ -1984,8 +1743,7 @@ more on headings for @TeX{}, see @ref{Heading Generation}.
@cindex @code{<title>} HTML tag
In the HTML file produced by @command{makeinfo}, @var{title} serves as
the document @samp{<title>}. It also becomes the default document
-description in the @samp{<head>} part
-(@pxref{@code{@@documentdescription}}).
+description in the @samp{<head>} part.
When the title page is used in the output, the title in the
@code{@@settitle} command does not affect the title as it appears on
@@ -2011,9 +1769,25 @@ Texinfo comment that looks like this:
@node Document Permissions
+@anchor{Software Copying Permissions}@c old node name
@section Document Permissions
-@cindex Document Permissions
-@cindex Copying Permissions
+@cindex Document permissions
+@cindex Copying permissions
+
+This segment describes the document and contains the copyright notice
+and copying permissions. This is done with the @code{@@copying} command.
+A real manual includes more text here, according to the license under
+which it is distributed.
+
+@example
+@group
+@@copying
+This is a short example of a complete Texinfo file, version 1.0.
+
+Copyright @@copyright@{@} 2016 Free Software Foundation, Inc.
+@@end copying
+@end group
+@end example
The copyright notice and copying permissions for a document need to
appear in several places in the various Texinfo output formats.
@@ -2021,9 +1795,7 @@ Therefore, Texinfo provides a command (@code{@@copying}) to declare
this text once, and another command (@code{@@insertcopying}) to
insert the text at appropriate points.
-@anchor{Software Copying Permissions}@c old node name
-This section is about the license of the Texinfo document. If the
-document is a software manual, the software is typically under a
+If the document is a software manual, the software is typically under a
different license---for GNU and many other free software packages,
software is usually released under the GNU GPL, and manuals are
released under the GNU FDL@. It is helpful to state the license of
@@ -2066,7 +1838,7 @@ The @code{@@quotation} has no legal significance; it's there to improve
readability in some contexts.
The text of @code{@@copying} is output as a comment at the beginning
-of Info, HTML, XML, and Docbook output files. It is @emph{not} output
+of Info, HTML, XML, and DocBook output files. It is @emph{not} output
implicitly in plain text or @TeX{}; it's up to you to use
@code{@@insertcopying} to emit the copying information. See the next
section for details.
@@ -2148,29 +1920,46 @@ beginning of each HTML output file, as an HTML comment. Again, this
text is not visible (unless the reader views the HTML source).
The permissions text defined by @code{@@copying} also appears
-automatically at the beginning of the XML and Docbook output files.
+automatically at the beginning of the XML and DocBook output files.
@node Titlepage & Copyright Page
@section Title and Copyright Pages
In hard copy output, the manual's name and author are usually printed on
-a title page. Copyright information is usually printed on the back of
-the title page.
+a title page. Copyright information is usually printed on the back
+(verso) of the title page. This segment must be enclosed between
+@code{@@titlepage} and @code{@@end titlepage} commands:
+
+@example
+@group
+@@titlepage
+@@title Sample Title
+@end group
+
+@group
+@@c The following two commands start the copyright page.
+@@page
+@@vskip 0pt plus 1filll
+@@insertcopying
+@@end titlepage
+@end group
+@end example
+
+@noindent
+We use the @code{@@insertcopying} command to
+include the permission text from the previous section, instead of
+writing it out again.
The title and copyright pages appear in printed manuals, but not in
-most other output formats. Because of this, it is possible to use
-several slightly obscure typesetting commands that are not to be used
-in the main text. In addition, this part of the beginning of a
-Texinfo file contains the text of the copying permissions that appears
-in the printed manual.
+most other output formats.
@menu
* @code{@@titlepage}:: Create a title for the printed document.
-* @code{@@titlefont @@center @@sp}:: The @code{@@titlefont}, @code{@@center},
- and @code{@@sp} commands.
* @code{@@title @@subtitle @@author}:: The @code{@@title}, @code{@@subtitle},
and @code{@@author} commands.
+* @code{@@titlefont @@center @@sp}:: The @code{@@titlefont}, @code{@@center},
+ and @code{@@sp} commands.
* Copyright:: How to write the copyright notice and
include copying permissions.
* Heading Generation:: Turn on page headings after the title and
@@ -2195,7 +1984,7 @@ material that you want to appear on unnumbered pages should be put
between the @code{@@titlepage} and @code{@@end titlepage} commands.
@findex page@r{, within @code{@@titlepage}}
-By using the @code{@@page} command you can force a page break within the
+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
@@ -2214,24 +2003,22 @@ 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{The Top Node}.)
-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.
-
-The second method uses the @code{@@title}, @code{@@subtitle}, and
+One 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
+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, or you may combine them; see the examples in
-the sections below.
+Texinfo also provides a second method for creating a title page.
+using typesetting commands that are not to be used in the main text.
+This method uses uses the @code{@@titlefont}, @code{@@sp}, and @code{@@center}
+commands to generate a title page in which the words on the page are
+centered.
@findex shorttitlepage
@cindex Bastard title page
-@cindex Title page, bastard
+@cindex Title page @subentry bastard
For sufficiently simple documents, and for the bastard title page in
traditional book frontmatter, Texinfo also provides a command
@code{@@shorttitlepage} which takes the rest of the line as the title.
@@ -2239,73 +2026,6 @@ The argument is typeset on a page by itself and followed by a blank
page.
-@node @code{@@titlefont @@center @@sp}
-@subsection @code{@@titlefont}, @code{@@center}, and @code{@@sp}
-
-@anchor{titlefont center sp}@c old name
-@findex titlefont
-@findex center
-@findex sp @r{(titlepage line spacing)}
-
-You can use the @code{@@titlefont}, @code{@@sp}, and @code{@@center}
-commands to create a title page for a printed document. (This is the
-first of the two methods for creating a title page in Texinfo.)
-
-Use the @code{@@titlefont} command to select a large font suitable for
-the title itself. You can use @code{@@titlefont} more than once if you
-have an especially long title.
-
-For HTML output, each @code{@@titlefont} command produces an
-@code{<h1>} heading, but the HTML document @code{<title>} is not
-affected. For that, you must put a @code{@@settitle} command before
-the @code{@@titlefont} command (@pxref{@code{@@settitle}}).
-
-@need 700
-For example:
-
-@example
-@@titlefont@{Texinfo@}
-@end example
-
-Use the @code{@@center} command at the beginning of a line to center
-the remaining text on that line. Thus,
-
-@example
-@@center @@titlefont@{Texinfo@}
-@end example
-
-@noindent
-centers the title, which in this example is ``Texinfo'' printed
-in the title font.
-
-Use the @code{@@sp} command to insert vertical space. For example:
-
-@example
-@@sp 2
-@end example
-
-@noindent
-This inserts two blank lines on the printed page.
-(@xref{@code{@@sp}}, for more information about the @code{@@sp}
-command.)
-
-A template for this method looks like this:
-
-@example
-@group
-@@titlepage
-@@sp 10
-@@center @@titlefont@{@var{name-of-manual-when-printed}@}
-@@sp 2
-@@center @var{subtitle-if-any}
-@@sp 2
-@@center @var{author}
-@dots{}
-@@end titlepage
-@end group
-@end example
-
-The spacing of the example fits an 8.5 by 11 inch manual.
@node @code{@@title @@subtitle @@author}
@@ -2318,9 +2038,7 @@ The spacing of the example fits an 8.5 by 11 inch manual.
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.
+spacing is done for you automatically.
Write the @code{@@title}, @code{@@subtitle}, or @code{@@author}
commands at the beginning of a line followed by the title, subtitle,
@@ -2389,6 +2107,74 @@ A template for this method looks like this:
@end example
+@node @code{@@titlefont @@center @@sp}
+@subsection @code{@@titlefont}, @code{@@center}, and @code{@@sp}
+
+@anchor{titlefont center sp}@c old name
+@findex titlefont
+@findex center
+@findex sp @r{(titlepage line spacing)}
+
+You can also use the @code{@@titlefont}, @code{@@sp}, and @code{@@center}
+commands to create a title page for a printed document.
+
+Use the @code{@@titlefont} command to select a large font suitable for
+the title itself. You can use @code{@@titlefont} more than once if you
+have an especially long title.
+
+For HTML output, each @code{@@titlefont} command produces an
+@code{<h1>} heading, but the HTML document @code{<title>} is not
+affected. For that, you must put a @code{@@settitle} command before
+the @code{@@titlefont} command (@pxref{@code{@@settitle}}).
+
+@need 700
+For example:
+
+@example
+@@titlefont@{Texinfo@}
+@end example
+
+Use the @code{@@center} command at the beginning of a line to center
+the remaining text on that line. Thus,
+
+@example
+@@center @@titlefont@{Texinfo@}
+@end example
+
+@noindent
+centers the title, which in this example is ``Texinfo'' printed
+in the title font.
+
+Use the @code{@@sp} command to insert vertical space. For example:
+
+@example
+@@sp 2
+@end example
+
+@noindent
+This inserts two blank lines on the printed page.
+(@xref{@code{@@sp}}, for more information about the @code{@@sp}
+command.)
+
+A template for this method looks like this:
+
+@example
+@group
+@@titlepage
+@@sp 10
+@@center @@titlefont@{@var{name-of-manual-when-printed}@}
+@@sp 2
+@@center @var{subtitle-if-any}
+@@sp 2
+@@center @var{author}
+@dots{}
+@@end titlepage
+@end group
+@end example
+
+The spacing of the example fits an 8.5 by 11 inch manual.
+
+
@node Copyright
@subsection Copyright Page
@cindex Copyright page
@@ -2568,61 +2354,47 @@ main text of the document.
@section The `Top' Node and Master Menu
@cindex Top node
@cindex Node, `Top'
+@anchor{Top Node Example}@c
The `Top' node is the node in which a reader enters an Info manual.
-As such, it should begin with a brief description of the manual
-(including the version number), and end with a master menu for the
-whole manual. Of course you should include any other general
-information you feel a reader would find helpful.
+As such, it should contain a very brief description of the manual
+(including the version number). The contents of the `Top' node do
+not appear in printed output.
@findex top
-It is conventional and desirable to write a @code{@@top} sectioning
-command line containing the title of the document immediately after
-the @code{@@node Top} line (@pxref{@code{@@top} Command}).
-
-The contents of the `Top' node should appear only in the online output;
-none of it should appear in printed output, so enclose it between
-@code{@@ifnottex} and @code{@@end ifnottex} commands. (@TeX{} does not
-print either an @code{@@node} line or a menu; they appear only in Info;
-strictly speaking, you are not required to enclose these parts between
-@code{@@ifnottex} and @code{@@end ifnottex}, but it is simplest to do
-so. @xref{Conditionals, , Conditionally Visible Text}.)
-
-@menu
-* Top Node Example::
-* Master Menu Parts::
-@end menu
+It is conventional to write a @code{@@top} sectioning command
+line containing the title of the document immediately after the
+@code{@@node Top} line (@pxref{@code{@@top} Command}). This command
+helps @command{makeinfo} determine the relationships between nodes.
+We repeat the short description from the beginning of
+the @samp{@@copying} text, but there's no need to repeat the copyright
+information, so we don't use @samp{@@insertcopying} here.
-@node Top Node Example
-@subsection Top Node Example
+The `Top' node contains a top-level @dfn{menu} listing the chapters,
+and possibly a @dfn{detailed menu} listing all the nodes in the
+entire document.
@cindex Top node example
-
-Here is an example of a Top node.
-
@example
-@group
-@@ifnottex
@@node Top
-@@top Sample Title
-
-This is the text of the top node.
-@@end ifnottex
-@end group
+@@top Short Sample
-Additional general information.
+This is a short sample Texinfo file.
@group
@@menu
-* First Chapter::
-* Second Chapter::
-@dots{}
-* Index::
-@end group
+* First Chapter:: The first chapter is the
+ only chapter in this sample.
+* Index:: Complete index.
@@end menu
+@end group
@end example
+@menu
+* Master Menu Parts::
+@end menu
+
@node Master Menu Parts
@subsection Parts of a Master Menu
@@ -2632,32 +2404,23 @@ Additional general information.
A @dfn{master menu} is the main menu. It is customary to include a
detailed menu listing all the nodes in the document in this menu.
-
Like any other menu, a master menu is enclosed in @code{@@menu} and
@code{@@end menu} and does not appear in the printed output.
-Generally, a master menu is divided into parts.
-
-@itemize @bullet
-@item
-The first part contains the major nodes in the Texinfo file: the nodes
-for the chapters, chapter-like sections, and the appendices.
-
-@item
-The second part contains nodes for the indices.
+The master menu contains entries for the major nodes in the Texinfo
+file: the nodes for the chapters, chapter-like sections, and the
+appendices, followed by nodes for the indices.
-@item
@findex detailmenu
@cindex Detailed menu
-The third and subsequent parts contain a listing of the other,
-lower-level nodes, often ordered by chapter. This way, rather than go
-through an intermediary menu, an inquirer can go directly to a
-particular node when searching for specific information. These menu
-items are not required; add them if you think they are a convenience.
-If you do use them, put @code{@@detailmenu} before the first one, and
-@code{@@end detailmenu} after the last; otherwise, @code{makeinfo}
-will get confused.
-@end itemize
+
+You may choose to follow these entries with a @dfn{defailed menu}.
+This lists other, lower-level nodes, often ordered by chapter.
+These items may be a convenience for an inquirer who can go directly
+to a particular node when searching for specific information, rather
+than going through an intermediate menu. If you use a detailed menu
+in your master menu, mark it with the @code{@@detailmenu @dots{}
+@@end detailmenu} environment, or @command{makeinfo} will get confused.
Each section in the menu can be introduced by a descriptive line. So
long as the line does not begin with an asterisk, it will not be
@@ -2699,324 +2462,84 @@ Beginning a Texinfo File
@end group
@end example
+@node The Body of the Document
+@section The Body of the Document
-@node Global Document Commands
-@section Global Document Commands
-@cindex Global Document Commands
-
-Besides the basic commands mentioned in the previous sections, here are
-additional commands which affect the document as a whole. They are
-generally all given before the Top node, if they are given at all.
-
-@menu
-* @code{@@documentdescription}:: Document summary for the HTML output.
-* @code{@@setchapternewpage}:: Start chapters on right-hand pages.
-* @code{@@headings}:: An option for turning headings on and off
- and double or single sided printing.
-* @code{@@paragraphindent}:: Specify paragraph indentation.
-* @code{@@firstparagraphindent}:: Suppressing first paragraph indentation.
-* @code{@@exampleindent}:: Specify environment indentation.
-@end menu
-
-
-@node @code{@@documentdescription}
-@subsection @code{@@documentdescription}: Summary Text
-@anchor{documentdescription}@c old name
-
-@cindex Document description
-@cindex Description of document
-@cindex Summary of document
-@cindex Abstract of document
-@cindex @code{<meta>} HTML tag, and document description
-@findex documentdescription
-
-When producing HTML output for a document, @command{makeinfo} writes a
-@samp{<meta>} element in the @samp{<head>} to give some idea of the
-content of the document. By default, this @dfn{description} is the
-title of the document, taken from the @code{@@settitle} command
-(@pxref{@code{@@settitle}}). To change this, use the
-@code{@@documentdescription} environment, as in:
-
-@example
-@@documentdescription
-descriptive text.
-@@end documentdescription
-@end example
-
-@noindent
-This will produce the following output in the @samp{<head>} of the HTML:
-
-@example
-<meta name=description content="descriptive text.">
-@end example
-
-@code{@@documentdescription} must be specified before the first node of
-the document.
-
-
-@node @code{@@setchapternewpage}
-@subsection @code{@@setchapternewpage}: Blank Pages Before Chapters
-
-@anchor{setchapternewpage}@c old name
-@findex setchapternewpage
-@cindex Starting chapters
-@cindex Pages, starting odd
-
-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
-preceding chapter, after a small amount of vertical whitespace.
-
-You can use the @code{@@setchapternewpage} command with various
-arguments to specify how @TeX{} should start chapters and whether it
-should format headers for printing on one or both sides of the paper
-(single-sided or double-sided printing).
-
-Write the @code{@@setchapternewpage} command at the beginning of a
-line followed by its argument.
-
-For example, you would write the following to cause each chapter to
-start on a fresh odd-numbered page:
-
-@example
-@@setchapternewpage odd
-@end example
-
-You can specify one of three alternatives with the
-@code{@@setchapternewpage} command:
-
-@table @asis
-
-@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
-format page headers for single-sided printing.
-
-@item @code{@@setchapternewpage on}
-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 or personal printing. This is the default.
-
-@item @code{@@setchapternewpage odd}
-Cause @TeX{} to start new chapters on new, odd-numbered pages
-(right-handed pages) and to typeset for double-sided printing. This is
-the form most often used for books and manuals.
-@end table
-
-Texinfo does not have a @code{@@setchapternewpage even} command,
-because there is no printing tradition of starting chapters or books on
-an even-numbered page.
-
-If you don't like the default headers that @code{@@setchapternewpage}
-sets, you can explicit control them with the @code{@@headings} command.
-@xref{@code{@@headings}}.
-
-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. By
-convention, table of contents and frontmatter pages are numbered with
-roman numerals and not in sequence with the rest of the document.
-
-The @code{@@setchapternewpage} has no effect in output formats that do
-not have pages, such as Info and HTML.
-
-We recommend not including any @code{@@setchapternewpage} command in
-your document source at all, since such desired pagination is not
-intrinsic to the document. For a particular hard copy run, if you
-don't want the default output (no blank pages, same headers on all
-pages) use the @option{--texinfo} option to @command{texi2dvi} to
-specify the output you want.
-
-
-@node @code{@@headings}
-@subsection The @code{@@headings} Command
-
-@anchor{headings on off}@c old name
-@findex headings
-
-The @code{@@headings} command is rarely used. It specifies what kind of
-page headings and footings to print on each page. Usually, this is
-controlled by the @code{@@setchapternewpage} command. You need the
-@code{@@headings} command only if the @code{@@setchapternewpage} command
-does not do what you want, or if you want to turn off predefined page
-headings prior to defining your own. Write a @code{@@headings} command
-immediately after the @code{@@end titlepage} command.
-
-You can use @code{@@headings} as follows:
-
-@table @code
-@item @@headings off
-Turn off printing of page headings.
-
-@item @@headings single
-Turn on page headings appropriate for single-sided printing.
-
-@item @@headings double
-Turn on page headings appropriate for double-sided printing.
-
-@item @@headings singleafter
-@itemx @@headings doubleafter
-Turn on @code{single} or @code{double} headings, respectively, after the
-current page is output.
-
-@item @@headings on
-Turn on page headings: @code{single} if @samp{@@setchapternewpage
-on}, @code{double} otherwise.
-@end table
-
-For example, suppose you write @code{@@setchapternewpage off} before the
-@code{@@titlepage} command to tell @TeX{} to start a new chapter on the
-same page as the end of the last chapter. This command also causes
-@TeX{} to typeset page headers for single-sided printing. To cause
-@TeX{} to typeset for double sided printing, write @code{@@headings
-double} after the @code{@@end titlepage} command.
-
-You can stop @TeX{} from generating any page headings at all by
-writing @code{@@headings off} on a line of its own immediately after the
-line containing the @code{@@end titlepage} command, like this:
-
-@example
-@@end titlepage
-@@headings off
-@end example
-
-@noindent
-The @code{@@headings off} command overrides the @code{@@end titlepage}
-command, which would otherwise cause @TeX{} to print page headings.
-
-You can also specify your own style of page heading and footing.
-@xref{Headings, , Page Headings}, for more information.
-
-
-@node @code{@@paragraphindent}
-@subsection @code{@@paragraphindent}: Controlling Paragraph Indentation
-
-@anchor{paragraphindent}@c old name
-@findex paragraphindent
-@cindex Indenting paragraphs, control of
-@cindex Paragraph indentation control
-
-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 a @code{@@paragraphindent} command at the beginning of a line
-followed by either @samp{asis} or a number:
+@cindex Frontmatter, text in
+The body segment contains all the text of the document.
+A manual is divided into one or more @dfn{nodes} (@pxref{Nodes}).
+The example illustrates a chapter made of three nodes, one
+for introductory material in the chapter, and two sections.
+The introductory material contains an enumerated list.
@example
-@@paragraphindent @var{indent}
-@end example
+@group
+@@node First Chapter
+@@chapter First Chapter
-The indentation is according to the value of @var{indent}:
+@@cindex chapter, first
+This is the first chapter.
+@@cindex index entry, another
-@table @asis
-@item @code{asis}
-Do not change the existing indentation (not implemented in @TeX{}).
+Here is a numbered list.
-@item @code{none}
-@itemx 0
-Omit all indentation.
+@@enumerate
+@@item
+This is the first item.
-@item @var{n}
-Indent by @var{n} space characters in Info output, by @var{n} ems in
-@TeX{}.
+@@item
+This is the second item.
+@@end enumerate
-@end table
-The default value of @var{indent} is 3. @code{@@paragraphindent} is
-ignored for HTML output.
-
-It is best to write the @code{@@paragraphindent} command before the
-end-of-header line at the beginning of a Texinfo file, so the region
-formatting commands indent paragraphs as specified. @xref{Start of
-Header}.
+@@node First Section
+@@section First Section
+First section of first chapter.
-@node @code{@@firstparagraphindent}
-@subsection @code{@@firstparagraphindent}: Indenting After Headings
-@anchor{firstparagraphindent}@c old name
-@findex firstparagraphindent
-@cindex First paragraph, suppressing indentation of
-@cindex Suppressing first paragraph indentation
-@cindex Preventing first paragraph indentation
-@cindex Indenting, suppressing of first paragraph
-@cindex Headings, indentation after
+@@node Second Section
+@@section Second Section
-As you can see in the present manual, the first paragraph in any
-section is not indented by default. Typographically, indentation is a
-paragraph separator, which means that it is unnecessary when a new
-section begins. This indentation is controlled with the
-@code{@@firstparagraphindent} command:
-
-@example
-@@firstparagraphindent @var{word}
+Second section of first chapter.
+@end group
@end example
-The first paragraph after a heading is indented according to the value
-of @var{word}:
-
-@table @asis
-@item @code{none}
-Prevents the first paragraph from being indented (default).
-This option is ignored by @command{makeinfo} if
-@code{@@paragraphindent asis} is in effect.
+In the Info output, the @samp{First Chapter} node will contain a
+menu listing the two sections in the chapter. Similarly, when this
+node is output in its own HTML file, it will contain a table of contents
+for the chapter.
-@item @code{insert}
-Include normal paragraph indentation. This respects the paragraph
-indentation set by a @code{@@paragraphindent} command
-(@pxref{@code{@@paragraphindent}}).
-@end table
-
-@code{@@firstparagraphindent} is ignored for HTML and Docbook output.
-
-It is best to write the @code{@@firstparagraphindent} command before the
-end-of-header line at the beginning of a Texinfo file, so the region
-formatting commands indent paragraphs as specified. @xref{Start of
-Header}.
-
-
-@node @code{@@exampleindent}
-@subsection @code{@@exampleindent}: Environment Indenting
+Here is what the contents of this chapter will look like:
-@anchor{exampleindent}@c old name
-@findex exampleindent
-@cindex Indenting environments
-@cindex Environment indentation
-@cindex Example indentation
+@sp 1
+@need 700
+@quotation
+@chapheading 1. First Chapter
-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:
+This is the first chapter.
-@example
-@@exampleindent @var{indent}
-@end example
+Here is a numbered list.
-The indentation is according to the value of @var{indent}:
+@enumerate
+@item
+This is the first item.
-@table @asis
-@item @code{asis}
-Do not change the existing indentation (not implemented in @TeX{}).
+@item
+This is the second item.
+@end enumerate
-@item 0
-Omit all indentation.
+@heading 1.1 First Section
-@item @var{n}
-Indent environments by @var{n} space characters in Info output, by
-@var{n} ems in @TeX{}.
+First section of first chapter.
-@end table
+@heading 1.2 Second Section
-The default value of @var{indent} is 5 spaces in Info, and 0.4@dmn{in}
-in @TeX{}, which is somewhat less. (The reduction is to help @TeX{}
-fit more characters onto physical lines.)
+Second section of first chapter.
+@end quotation
-It is best to write the @code{@@exampleindent} command before the
-end-of-header line at the beginning of a Texinfo file, so the region
-formatting commands indent paragraphs as specified. @xref{Start of
-Header}.
+@noindent (In the Info and HTML output, the chapter would also be split
+into nodes.)
@node Ending a File
@@ -3041,15 +2564,11 @@ the last line to be processed. For example:
@findex bye
@anchor{File End}
-An @code{@@bye} command terminates Texinfo processing. None of the
-formatters process anything following @code{@@bye}; any such text is
-completely ignored. The @code{@@bye} command should be on a line by
-itself.
+A @code{@@bye} command terminates Texinfo processing. It should be on
+a line by itself. Anything following @code{@@bye} is completely
+ignored.
+
-Thus, if you wish, you may follow the @code{@@bye} line with arbitrary
-notes. Also, you may follow the @code{@@bye} line with a local
-variables list for Emacs, most typically a @samp{compile-command}
-(@pxref{Compile-Command,, Using the Local Variables List}).
@node Nodes
@@ -3073,7 +2592,7 @@ that do not fit a hierarchical structure.
Normally, you put a node command immediately before each chapter
structuring command---for example, an @code{@@section} or
-@code{@@subsection} line. (@xref{Chapter Structuring}.).
+@code{@@subsection} line. (@xref{Chapter Structuring}.)
You must do this even if you do not intend to format the file for Info.
This is because @TeX{} uses both @code{@@node} names and
chapter-structuring names in the output for cross-references. The only
@@ -3084,71 +2603,98 @@ other formats.
@menu
-* Texinfo Document Structure:: Double structure of documents.
+* Writing a Node:: How to write a @code{@@node} line.
* Node Names:: How to choose node names.
-* Writing a Node:: How to write an @code{@@node} line.
* Node Line Requirements:: Keep names unique.
* First Node:: How to write a `Top' node.
* @code{@@top} Command:: How to use the @code{@@top} command.
+* Texinfo Document Structure:: Double structure of documents.
* Node Menu Illustration:: A diagram, and sample nodes and menus.
-* @command{makeinfo} Pointer Creation:: Letting makeinfo determine node pointers.
* Menus:: Listing subordinate nodes.
@end menu
-@node Texinfo Document Structure
-@section Texinfo Document Structure
-@cindex Texinfo document structure
-@cindex Document structure, of Texinfo
-@cindex Structure, of Texinfo documents
-@cindex Double structure, of Texinfo documents
+@node Writing a Node
+@section Writing a @code{@@node} Line
+@cindex Writing a @code{@@node} line
+@cindex @code{@@node} line writing
+@cindex Node line writing
-@anchor{Two Paths}@c node name
+@findex node
+Write @code{@@node} at the beginning of a line followed by the name of
+the node, like this:
-Nodes can contain @dfn{menus}, which contain the names of @dfn{child
-nodes} within the parent node; for example, a node corresponding to a
-chapter would have a menu of the sections in that chapter. The menus
-allow the user to move to the child nodes in a natural way in the online
-output.
+@example
+@@node @var{node-name}
+@end example
-In addition, nodes contain @dfn{node pointers} that name other nodes.
-The `Next' and `Previous' pointers form nodes at the same sectioning
-level into a chain. As you might imagine, the `Next' pointer links to
-the next node, and the `Previous' pointer links to the previous node.
-Thus, for example, all the nodes that are at the level of sections
-within a chapter are linked together, and the order in this chain
-is the same as the order of the children in the menu of the parent
-chapter. Each child node records the parent node name as its `Up'
-pointer.
+After you have inserted a @code{@@node} line, you should immediately
+write an @@-command for the chapter or section and insert its name.
-@opindex accesskey@r{, in HTML output of nodes}
-The Info and HTML output from @command{makeinfo} for each node includes
-links to the `Next', `Previous', and `Up' nodes. The HTML also uses
-the @code{accesskey} attribute with the values @samp{n}, @samp{p}, and
-@samp{u} respectively. This allows people using web browsers to
-follow the navigation using (typically) @kbd{M-@var{letter}}, e.g.,
-@kbd{M-n} for the `Next' node, from anywhere within the node.
-Node pointers and menus provide structure for Info files just as
-chapters, sections, subsections, and the like provide structure for
-printed books. The two structures are theoretically distinct; in
-practice, however, the tree structure of printed books is essentially
-always used for the node and menu structure also, as this leads to a
-document which is easiest to follow. @xref{Texinfo Document
-Structure}.
+You may optionally follow the node name argument to @code{@@node}
+with up to three optional arguments on the rest of the same line,
+separating the arguments with commas. These are the names of the
+`Next', `Previous', and `Up' pointers, in that order. Hence,
+the template for a fully-written-out node line with `Next', `Previous',
+and `Up' pointers looks like this:
-Typically, the sectioning structure and the node structure are
-completely parallel, with one node for each chapter, section, etc.,
-and with the nodes following the same hierarchical arrangement as the
-sectioning. Thus, if a node is at the logical level of a chapter, its
-child nodes are at the level of sections; similarly, the child nodes
-of sections are at the level of subsections.
+@example
+@@node @var{node-name}, @var{next}, @var{previous}, @var{up}
+@end example
+
+The @var{node-name} argument must be present, but the others are
+optional. If you wish to specify some but not others, just insert
+commas as needed, as in: @samp{@@node mynode,,,uppernode}.
+Any spaces before or after each name on the @code{@@node} line are
+ignored. However, if your Texinfo document is hierarchically organized,
+as virtually all are, we recommend leaving off all the pointers and
+letting @code{makeinfo} determine them.
+
+@cindex Creating pointers with @code{makeinfo}
+@cindex Pointer creation with @code{makeinfo}
+@cindex Automatic pointer creation with @code{makeinfo}
+@cindex Implicit pointer creation with @code{makeinfo}
+The @code{makeinfo} program automatically determines node pointers
+for a hierarchically organized document. For it do to do this, each
+@code{@@node} command should be followed immediately by a sectioning
+command such as @code{@@chapter} or @code{@@section} (except that
+comment lines may intervene). Finally, you must follow the `Top'
+@code{@@node} line with a line beginning with @code{@@top} to mark
+the top-level node in the file. @xref{@code{@@top} Command}.
+
+Even when you explicitly specify all pointers, you cannot write the
+nodes in the Texinfo source file in an arbitrary order.
+You must write the nodes in the order you wish them to appear in the
+output. For Info format one can imagine that the order may not matter,
+but it matters for the other formats.
+
+In most cases, you will want to take advantage of the pointer creation
+feature, and not redundantly specify node pointers that the programs can
+determine.
+However, Texinfo documents are not required to be organized
+hierarchically or in fact to contain sectioning commands at all (for
+example, if you never intend the document to be printed), so node
+pointers may still be specified explicitly, in full generality.
+
+If you are using GNU Emacs, you can use the update node commands
+provided by Texinfo mode to insert the names of the pointers.
+(@xref{Updating Nodes and Menus}.)
+
+Alternatively, you can insert the `Next', `Previous', and `Up'
+pointers yourself. If you do this, you may find it helpful to use the
+Texinfo mode keyboard command @kbd{C-c C-c n}. This command inserts
+@samp{@@node} and a comment line listing the names of the pointers in
+their proper order. The comment line helps you keep track of which
+arguments are for which pointers.
+
+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.
+Useful cross-references are an especially important feature of a good
+Texinfo manual.
-Although it is technically possible to create Texinfo documents with
-only one structure or the other, or for the two structures not to be
-parallel, or for either the sectioning or node structure to be
-abnormally formed, etc., this is @emph{not at all recommended}. To
-the best of our knowledge, all the Texinfo manuals currently in
-general use do follow the conventional parallel structure.
@node Node Names
@@ -3186,7 +2732,7 @@ In HTML output, any characters in the node name other than plain ASCII
letters, numbers or spaces will be changed in the file name.
(@xref{HTML Xref Node Name Expansion}.)
This can make the URL's for the pages in your manual less user-friendly;
-for example in this manual the @samp{@@dots} node is output as
+for example, in this manual the @samp{@@dots} node is output as
@file{__0040dots.html}.
@end itemize
@@ -3195,9 +2741,7 @@ to casually change them once published. Such name changes invalidate
references from other manuals, from mail archives, and so on.
The pointers from a given node enable you to reach other nodes and
-consist simply of the names of those nodes. The pointers are usually
-not specified explicitly, as @command{makeinfo} can determine them
-(@pxref{@command{makeinfo} Pointer Creation}).
+consist simply of the names of those nodes.
Normally, a node's `Up' pointer contains the name of the node whose
menu mentions that node. The node's `Next' pointer contains the name
@@ -3211,81 +2755,6 @@ Usually, the first node of a Texinfo file is the `Top' node, and its
for all of Info.
-@node Writing a Node
-@section Writing an @code{@@node} Line
-@cindex Writing an @code{@@node} line
-@cindex @code{@@node} line writing
-@cindex Node line writing
-
-@findex node
-The easiest way to write an @code{@@node} line is to write @code{@@node}
-at the beginning of a line and then the name of the node, like this:
-
-@example
-@@node @var{node-name}
-@end example
-
-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.
-
-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.
-Useful cross-references are an especially important feature of a good
-Texinfo manual.
-
-Even when you explicitly specify all pointers, you cannot write the
-nodes in the Texinfo source file in an arbitrary order! Because
-formatters must process the file sequentially, irrespective of node
-pointers, you must write the nodes in the order you wish them to
-appear in the output. For Info format one can imagine that the order
-may not matter, but it matters for the other formats.
-
-You may optionally follow the node name argument to @code{@@node}
-with up to three optional arguments on the rest of the same line,
-separating the arguments with commas. These are the names of the
-`Next', `Previous', and `Up' pointers, in that order. We recommend
-omitting them if your Texinfo document is hierarchically organized,
-as virtually all are (@pxref{@command{makeinfo} Pointer Creation}).
-
-Any spaces before or after each name on the @code{@@node} line are
-ignored.
-
-The template for a fully-written-out node line with `Next', `Previous',
-and `Up' pointers looks like this:
-
-@example
-@@node @var{node-name}, @var{next}, @var{previous}, @var{up}
-@end example
-
-The @var{node-name} argument must be present, but the others are
-optional. If you wish to specify some but not others, just insert
-commas as needed, as in: @samp{@@node mynode,,,uppernode}. However,
-we recommend leaving off all the pointers and letting @code{makeinfo}
-determine them.
-
-If you are using GNU Emacs, you can use the update node commands
-provided by Texinfo mode to insert the names of the pointers; or
-(recommended), you can leave the pointers out of the Texinfo file and
-let @code{makeinfo} insert node pointers into the Info file it
-creates. (@xref{Texinfo Mode}, and @ref{@command{makeinfo} Pointer
-Creation}.)
-
-Alternatively, you can insert the `Next', `Previous', and `Up'
-pointers yourself. If you do this, you may find it helpful to use the
-Texinfo mode keyboard command @kbd{C-c C-c n}. This command inserts
-@samp{@@node} and a comment line listing the names of the pointers in
-their proper order. The comment line helps you keep track of which
-arguments are for which pointers. This comment line is especially useful
-if you are not familiar with Texinfo.
-
-
@node Node Line Requirements
@section @code{@@node} Line Requirements
@@ -3309,7 +2778,7 @@ sections are all different.
@item
@cindex Commands in node names
-@cindex @@-commands in node names
+@cindex @sortas{at} @@-commands @subentry in node names
Node names can contain @@-commands. The output is generally the
natural result of the command; for example, using @code{@@TeX@{@}} in a
node name results in the @TeX{} logo being output, as it would be in
@@ -3370,16 +2839,16 @@ either special insertions (@pxref{Inserting a Comma}) or @code{@@asis}
As an example of avoiding the special characters, the following is a
section title in this manual:
-@smallexample
-@@section @@code@{@@@@unnumbered@}, @@code@{@@@@appendix@}: ...
-@end smallexample
+@example
+@@section @@code@{@@@@unnumbered@}, @@code@{@@@@appendix@}: Chapters with@enddots{}
+@end example
@noindent
But the corresponding node name lacks the commas and the subtitle:
-@smallexample
-@@node @code{@@unnumbered @@appendix}
-@end smallexample
+@example
+@@node @@code@{@@@@unnumbered @@@@appendix@}
+@end example
@cindex Case in node name
@item
@@ -3405,12 +2874,6 @@ In menu entries, this is the name that should be used: no leading or
trailing spaces, and a single internal space. (For cross-references,
the node name used in the Texinfo sources is automatically normalized
in this way.)
-
-@item
-The next/previous/up pointers on @code{@@node} lines must be the names
-of nodes. (It's recommended to leave out these explicit node pointer
-names, which automatically avoids any problem here; @pxref{@command{makeinfo}
-Pointer Creation}.)
@end itemize
@@ -3420,9 +2883,11 @@ Pointer Creation}.)
@cindex First node
The first node of a Texinfo file is the @dfn{Top} node, except in an
-included file (@pxref{Include Files}). The Top node should contain a
-short summary, copying permissions, and a master menu. @xref{The Top
-Node}, for more information on the Top node contents and examples.
+included file (@pxref{Include Files}). The Top node should contain
+a short summary and a master menu. @xref{The Top Node} for more
+information on the Top node contents and examples. Straight text
+before the Top node outside of any node should be avoided.
+
Here is a description of the node pointers to be used in the Top node:
@@ -3496,10 +2961,14 @@ formatter which node is to be used as the root of the node tree.
It produces the same sort of output as @code{@@unnumbered}
(@pxref{@code{@@unnumbered @@appendix}}).
-The @code{@@top} node is conventionally wrapped in an
-@code{@@ifnottex} conditional so that it will not appear in @TeX{}
-output (@pxref{Conditionals}).
-Thus, in practice, a Top node usually looks like this:
+@code{@@top} is ignored when raising or lowering sections. That is,
+it is never lowered and nothing can be raised to it
+(@pxref{Raise/lower sections}).
+
+It used to be conventionial to wrap the @samp{Top} node
+in an @code{@@ifnottex} conditional so that it would not appear in
+@TeX{} output (@pxref{Conditionals}). Thus, a Top node often looked
+like this:
@example
@@ifnottex
@@ -3510,9 +2979,61 @@ Thus, in practice, a Top node usually looks like this:
@@end ifnottex
@end example
-@code{@@top} is ignored when raising or lowering sections. That is,
-it is never lowered and nothing can be raised to it
-(@pxref{Raise/lower sections}).
+This is no longer necessary, as the @samp{Top} node is now never output
+for @TeX{} output.
+
+
+@node Texinfo Document Structure
+@section Texinfo Document Structure
+@cindex Texinfo document structure
+@cindex Document structure, of Texinfo
+@cindex Structure, of Texinfo documents
+@cindex Double structure, of Texinfo documents
+
+@anchor{Two Paths}@c node name
+
+Nodes can contain @dfn{menus}, which contain the names of @dfn{child
+nodes} within the parent node; for example, a node corresponding to a
+chapter would have a menu of the sections in that chapter. The menus
+allow the user to move to the child nodes in the Info output.
+
+In addition, nodes contain @dfn{node pointers} that name other nodes.
+The `Next' and `Previous' pointers link nodes at the same sectioning
+level into a chain. As you might imagine, the `Next' pointer links to
+the next node, and the `Previous' pointer links to the previous node.
+Thus, for example, all the nodes that are at the level of sections
+within a chapter are linked together, and the order in this chain
+is the same as the order of the children in the menu of the parent
+chapter. Each child node records the parent node name as its `Up'
+pointer.
+
+@cindex @code{accesskey} @subentry in HTML output of nodes
+The Info and HTML output from @command{makeinfo} for each node includes
+links to the `Next', `Previous', and `Up' nodes. The HTML also uses
+the @code{accesskey} attribute with the values @samp{n}, @samp{p}, and
+@samp{u} respectively. This allows people using web browsers to
+follow the navigation using (typically) @kbd{M-@var{letter}}, e.g.,
+@kbd{M-n} for the `Next' node, from anywhere within the node.
+Node pointers and menus provide structure for Info files just as
+chapters, sections, subsections, and the like provide structure for
+printed books. The two structures are theoretically distinct; in
+practice, however, the tree structure of printed books is essentially
+always used for the node and menu structure also, as this leads to a
+document which is easiest to follow.
+
+Typically, the sectioning structure and the node structure are
+completely parallel, with one node for each chapter, section, etc.,
+and with the nodes following the same hierarchical arrangement as the
+sectioning. Thus, if a node is at the logical level of a chapter, its
+child nodes are at the level of sections; similarly, the child nodes
+of sections are at the level of subsections.
+
+Although it is technically possible to create Texinfo documents with
+only one structure or the other, or for the two structures not to be
+parallel, or for either the sectioning or node structure to be
+abnormally formed, etc., this is @emph{not at all recommended}. To
+the best of our knowledge, all the Texinfo manuals currently in
+general use do follow the conventional parallel structure.
@node Node Menu Illustration
@@ -3558,9 +3079,8 @@ This @code{@@node} line says that the name of this node is
``Chapter@tie{}2'', the name of the `Next' node is ``Chapter 3'', the
name of the `Previous' node is ``Chapter@tie{}1'', and the name of the
`Up' node is ``Top''. You can (and should) omit writing out these
-node names if your document is hierarchically organized
-(@pxref{@command{makeinfo} Pointer Creation}), but the pointer
-relationships still obtain.
+node names if your document is hierarchically organized , but the
+pointer relationships still obtain.
@quotation Note
`Next' and `Previous' refer to nodes at the @emph{same hierarchical
@@ -3612,7 +3132,7 @@ construct to determine the relationships between nodes and sectioning
commands.
Here is the beginning of the chapter in this manual called ``Ending a
-Texinfo File''. This shows an @code{@@node} line followed by an
+Texinfo File''. This shows a @code{@@node} line followed by a
@code{@@chapter} line, and then by indexing lines.
@example
@@ -3625,75 +3145,6 @@ Texinfo File''. This shows an @code{@@node} line followed by an
@end group
@end example
-An earlier version of the manual used explicit node pointers. Here is
-the beginning of the same chapter for that case. This shows an
-@code{@@node} line followed by a comment line, a @code{@@chapter}
-line, and then by indexing lines.
-
-@example
-@group
-@@node Ending a File, Structuring, Beginning a File, Top
-@@comment node-name, next, previous, up
-@@chapter Ending a Texinfo File
-@@cindex Ending a Texinfo file
-@dots{}
-@end group
-@end example
-
-
-@node @command{makeinfo} Pointer Creation
-@section @code{makeinfo} Pointer Creation
-
-@cindex Creating pointers with @code{makeinfo}
-@cindex Pointer creation with @code{makeinfo}
-@cindex Automatic pointer creation with @code{makeinfo}
-@cindex Implicit pointer creation with @code{makeinfo}
-
-The @code{makeinfo} program can automatically determine node pointers
-for a hierarchically organized document. This implicit node pointer
-creation 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}.) We highly recommend taking
-advantage of this.
-
-To do so, write your @code{@@node} lines with just the name of the
-node:
-
-@example
-@@node My Node
-@end example
-
-@noindent
-You do not need to write out the `Next', `Previous', and `Up'
-pointers.
-
-Then, you must write a sectioning command, such as @code{@@chapter}
-or @code{@@section}, on the line immediately following each truncated
-@code{@@node} line (except that comment lines may intervene). This is
-where it normally goes.
-
-Also, 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
-level.
-
-Finally, you must follow the `Top' @code{@@node} line with a line
-beginning with @code{@@top} to mark the top-level node in the file.
-@xref{@code{@@top} Command}.
-
-@cindex Detail menu
-@findex detailmenu
-If you use a detailed menu in your master menu (@pxref{Master Menu
-Parts}), mark it with the @code{@@detailmenu @dots{} @@end
-detailmenu} environment, or @command{makeinfo} will get confused,
-typically about the last and/or first node in the document.
-
-In most cases, you will want to take advantage of this feature and not
-redundantly specify node pointers that the programs can determine.
-However, Texinfo documents are not required to be organized
-hierarchically or in fact to contain sectioning commands at all (for
-example, if you never intend the document to be printed), so node
-pointers may still be specified explicitly, in full generality.
-
@node Menus
@section Menus
@@ -3752,22 +3203,15 @@ Technically, menus can carry you to any node, regardless of the
structure of the document; even to nodes in a different Info file.
However, we do not recommend making use of this, because it is hard
for readers to follow. Also, the @command{makeinfo} implicit pointer
-creation feature (@pxref{@command{makeinfo} Pointer Creation}) and GNU
+creation feature (@pxref{Writing a Node}) and GNU
Emacs Texinfo mode updating commands work only to create menus of
subordinate nodes in a hierarchically structured document. It is much
better to use cross-references to refer to arbitrary nodes.
-@cindex Menus, automatically generating
-@findex validatemenus
-@command{makeinfo} can automatically generate menus in nodes for Info
-and HTML output, based on the chapter structure of the document. To
-specify that you want it to do this, place the line
-@samp{@@validatemenus off} near the beginning of the document.
-
In Info, a user selects a node with the @kbd{m} (@code{Info-menu})
command. The menu entry name is what the user types after the @kbd{m}
command.
-@opindex accesskey@r{, in HTML output of menus}
+@cindex @code{accesskey} @subentry in HTML output of menus
In the HTML output from @command{makeinfo}, the @code{accesskey}
attribute is used with the values @samp{1}@dots{}@samp{9} for the
first nine entries. This allows people using web browsers to follow
@@ -4203,7 +3647,7 @@ In HTML, the @code{@@chapter} command produces an @code{<h2>}-level
header by default (controlled by the @code{CHAPTER_HEADER_LEVEL}
customization variable, @pxref{Other Customization Variables}).
-In the XML and Docbook output, a @code{<chapter>} element is produced
+In the XML and DocBook output, a @code{<chapter>} element is produced
that includes all the following sections, up to the next chapter.
@@ -4228,11 +3672,13 @@ just as with @code{@@chapter}.
Texinfo also provides a command @code{@@centerchap}, which is analogous
to @code{@@unnumbered}, but centers its argument in the printed and HTML
outputs. This kind of stylistic choice is not usually offered by
-Texinfo. It may be suitable for short documents.
+Texinfo.
@c but the Hacker's Dictionary wanted it, before they quit Texinfo.
+You are recommended not to use this command, as
+it may be removed in future releases of Texinfo.
-@cindex Docbook and prefatory sections
-@cindex Preface, etc., and Docbook
+@cindex DocBook and prefatory sections
+@cindex Preface, etc., and DocBook
With @code{@@unnumbered}, if the name of the associated node is one of
these English words (case-insensitive):
@@ -4240,13 +3686,13 @@ these English words (case-insensitive):
Acknowledgements Colophon Dedication Preface
@end example
-@cindex @code{<acknowledgements>} Docbook tag
-@cindex @code{<colophon>} Docbook tag
-@cindex @code{<dedication>} Docbook tag
-@cindex @code{<preface>} Docbook tag
-@cindex @code{<chapter>} Docbook tag
-@cindex @code{<title>} Docbook tag
-@noindent then the Docbook output uses corresponding special tags
+@cindex @code{<acknowledgements>} DocBook tag
+@cindex @code{<colophon>} DocBook tag
+@cindex @code{<dedication>} DocBook tag
+@cindex @code{<preface>} DocBook tag
+@cindex @code{<chapter>} DocBook tag
+@cindex @code{<title>} DocBook tag
+@noindent then the DocBook output uses corresponding special tags
(@code{<preface>}, etc.)@: instead of the default @code{<chapter>}.
The argument to @code{@@unnumbered} itself can be anything, and is
output as the following @code{<title>} text as usual.
@@ -4313,7 +3759,7 @@ might produce the following in Info:
Section titles are listed in the table of contents.
-The @TeX{}, HTML, Docbook, and XML output is all analogous to the
+The @TeX{}, HTML, DocBook, and XML output is all analogous to the
chapter-level output, just ``one level down''; @pxref{@code{@@chapter}}.
@@ -4388,7 +3834,7 @@ might produce
Subsection titles are listed in the table of contents.
-The @TeX{}, HTML, Docbook, and XML output is all analogous to the
+The @TeX{}, HTML, DocBook, and XML output is all analogous to the
chapter-level output, just ``two levels down'';
@pxref{@code{@@chapter}}.
@@ -4479,7 +3925,7 @@ might produce
@end group
@end example
-The @TeX{}, HTML, Docbook, and XML output is all analogous to the
+The @TeX{}, HTML, DocBook, and XML output is all analogous to the
chapter-level output, just ``three levels down''; @pxref{@code{@@chapter}}.
@@ -4532,7 +3978,7 @@ In the HTML output, the @code{@@part} text is similarly included in
the tables of contents, and a heading is included in the main document
text, as part of the following chapter or appendix node.
-In the XML and Docbook output, the @code{<part>} element includes all
+In the XML and DocBook output, the @code{<part>} element includes all
the following chapters, up to the next @code{<part>}. A @code{<part>}
containing chapters is also closed at an appendix.
@@ -4633,8 +4079,8 @@ the current context, or incidental to it; use cross-references to
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
-references to help readers find other information that they may not
+need. For this reason, such creations should contain many
+cross-references to help readers find other information that they may not
have read.
In a printed manual, a cross-reference results in a page reference,
@@ -4682,8 +4128,7 @@ Additionally, there are commands to produce references to documents
outside the Texinfo system. The @code{@@cite} command is used
to make references to books and manuals. @code{@@url} produces
a @acronym{URL}, for example a reference to a page on the World
-Wide Web. @code{@@inforef} is used to make a reference to an Info
-file for which there is no printed manual.
+Wide Web.
@node Cross Reference Parts
@@ -5029,7 +4474,9 @@ Typically this line would be given near the beginning of the document
and used for the whole manual. But you can turn it off if you want
(@code{@@xrefautomaticsectiontitle off}), for example, if you're
including some other sub-document that doesn't have suitable section
-names.
+names. This setting also applies to node headers in HTML, if
+@code{@@xrefautomaticsectiontitle} is on, the sections names are used
+in node headers instead of the node names when possible.
@node Four and Five Arguments
@@ -5426,11 +4873,9 @@ manuals or general web pages, keep working.
@cindex References using @code{@@inforef}
@code{@@inforef} is used for making cross-references to Info
-documents---even from a printed manual. This might be because you
-want to refer to conditional @code{@@ifinfo} text
-(@pxref{Conditionals}), or because printed output is not available
-(perhaps because there is no Texinfo source), among other
-possibilities.
+documents---even from a printed manual. This was originally
+used for Info files that were not generated from any Texinfo source.
+The command is now obsolete and should not be used.
The command takes either two or three arguments, in the following
order:
@@ -5497,8 +4942,7 @@ refer to printed works for which no Info form exists.
@anchor{uref}@c old name
@anchor{url}
-@cindex Uniform resource locator, referring to
-@cindex URL, referring to
+@cindex URL @subentry referring to
@findex url
@cindex @code{href}, producing HTML
@@ -5538,7 +4982,7 @@ the third argument is given, the second argument is ignored.
@subsection @code{@@url} Examples
@cindex @code{@@url}, examples of using
-@cindex URL, examples of displaying
+@cindex URL @subentry examples of displaying
First, here is an example of the simplest form of @code{@@url}, with
just one argument. The given url is both the target and the visible
@@ -5615,7 +5059,7 @@ already has to detect them without the @samp{<URL:}.
@node URL Line Breaking
@subsection URL Line Breaking
-@cindex Line breaking, and urls
+@cindex Line breaks @subentry URL's
@cindex Breakpoints within urls
@TeX{} allows line breaking within urls at only a few characters
(which are special in urls): @samp{&}, @samp{.}, @samp{#}, @samp{?},
@@ -6464,7 +5908,7 @@ the abbreviation do not end a sentence.
@cindex @code{<abbr>} and @code{<abbrev>} tags
In @TeX{} and in the Info output, the first argument is printed as-is;
if the second argument is present, it is printed in parentheses after
-the abbreviation. In HTML the @code{<abbr>} tag is used; in Docbook,
+the abbreviation. In HTML the @code{<abbr>} tag is used; in DocBook,
the @code{<abbrev>} tag is used. For instance:
@example
@@ -6508,7 +5952,7 @@ argument, remember to use the @code{@@.} or similar command
In @TeX{}, the acronym is printed in slightly smaller font. In the
Info output, the argument is printed as-is. In either format, if the
second argument is present, it is printed in parentheses after the
-acronym. In HTML and Docbook the @code{<acronym>} tag is used.
+acronym. In HTML and DocBook the @code{<acronym>} tag is used.
For instance (since GNU is a recursive acronym, we use
@code{@@acronym} recursively):
@@ -6574,8 +6018,7 @@ them.
@anchor{indicateurl}@c old name
@findex indicateurl
-@cindex Uniform resource locator, indicating
-@cindex URL, indicating
+@cindex URL @subentry indicating
Use the @code{@@indicateurl} command to indicate a uniform resource
locator on the World Wide Web. This is purely for markup purposes and
@@ -6701,14 +6144,14 @@ Use the @samp{@@sc} command to set text in @sc{a small caps font}
braces in lowercase, like this:
@example
-Richard @@sc@{Stallman@} commenc@'{e} GNU.
+Richard @@sc@{Stallman@} a commenc@'{e} le projet GNU.
@end example
@noindent
This produces:
@display
-Richard @sc{Stallman} commenc@'{e} GNU.
+Richard @sc{Stallman} a commenc@'{e} le projet GNU.
@end display
As shown here, we recommend reserving @code{@@sc} for special cases
@@ -6805,11 +6248,11 @@ selects the @t{fixed-width}, typewriter-style font used by @code{@@code};
others, at which time it did not seem desirable to use very short
names for such infrequently needed features.)
-@cindex @code{<lineannotation>} Docbook tag
+@cindex @code{<lineannotation>} DocBook tag
The @code{@@r} command can be useful in example-like environments, to
write comments in the standard roman font instead of the fixed-width
font. This looks better in printed output, and produces a
-@code{<lineannotation>} tag in Docbook output.
+@code{<lineannotation>} tag in DocBook output.
For example,
@@ -6870,7 +6313,7 @@ beginning of that line, and with only one space between the
* @code{@@noindent}:: Preventing paragraph indentation.
* @code{@@indent}:: Forcing paragraph indentation.
* @code{@@cartouche}:: Drawing rounded rectangles around text.
-* @code{@@small@dots{}}:: Examples in a smaller font.
+* small:: Examples in a smaller font.
@end menu
@@ -7007,13 +6450,13 @@ If the @code{@@quotation} argument is one of these English words
Caution Important Note Tip Warning
@end example
-@cindex @code{<caution>} Docbook tag
-@cindex @code{<important>} Docbook tag
-@cindex @code{<note>} Docbook tag
-@cindex @code{<tip>} Docbook tag
-@cindex @code{<warning>} Docbook tag
+@cindex @code{<caution>} DocBook tag
+@cindex @code{<important>} DocBook tag
+@cindex @code{<note>} DocBook tag
+@cindex @code{<tip>} DocBook tag
+@cindex @code{<warning>} DocBook tag
@cindex @code{<blockquote>} HTML tag
-@noindent then the Docbook output uses corresponding special tags
+@noindent then the DocBook output uses corresponding special tags
(@code{<note>}, etc.)@: instead of the default @code{<blockquote>}.
HTML output always uses @code{<blockquote>}.
@@ -7042,11 +6485,6 @@ hacking.
@author Richard Stallman
@end quotation
-@findex smallquotation
-Texinfo also provides a command @code{@@smallquotation}, which is just
-like @code{@@quotation} but uses a smaller font size where possible.
-@xref{@code{@@small@dots{}}}.
-
@node @code{@@indentedblock}
@section @code{@@indentedblock}: Indented text blocks
@@ -7074,11 +6512,6 @@ This is an example ...
@@end indentedblock
@end example
-@findex smallindentedblock
-Texinfo also provides a command @code{@@smallindentedblock}, which is
-just like @code{@@indentedblock} but uses a smaller font size where
-possible. @xref{@code{@@small@dots{}}}.
-
@node @code{@@example}
@section @code{@@example}: Example Text
@@ -7088,25 +6521,13 @@ possible. @xref{@code{@@small@dots{}}}.
@cindex Examples, formatting them
@cindex Formatting examples
-The @code{@@example} environment is used to indicate an example that
-is not part of the running text, such as computer input or output.
-Write an @code{@@example} command at the beginning of a line by
-itself. Mark the end of the example with an @code{@@end example}
-command, also written at the beginning of a line by itself.
-
-An @code{@@example} environment has the following characteristics:
-
-@itemize
-@item Each line in the input file is a line in the output; that is,
-the source text is not filled as it normally is.
-@item Extra spaces and blank lines are significant.
-@item The output is indented.
-@item The output uses a fixed-width font.
-@item Texinfo commands @emph{are} expanded; if you want the output to
-be the input verbatim, use the @code{@@verbatim} environment instead
-(@pxref{@code{@@verbatim}}).
-@end itemize
+The @code{@@example} environment is used to indicate
+computer input or output that is not part of the running text. If you
+want to embed code fragments within sentences, use the @code{@@code}
+command or its relatives instead (@pxref{@code{@@code}}).
+Write an @code{@@example} command at the beginning of a line by
+itself. Mark the end of the block with @code{@@end example}.
For example,
@example
@@ -7124,19 +6545,12 @@ cp foo @var{dest1}; \
cp foo @var{dest2}
@end example
-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}. Blank lines inside the beginning
-@code{@@example} and the ending @code{@@end example}, on the other
-hand, do appear in the output.
-
-@quotation Caution
-Do not use tabs in the lines of an example! (Or anywhere else in
-Texinfo, except in verbatim environments.) @TeX{} treats tabs as
-single spaces, and that is not what they look like. In Emacs, you can
-use @kbd{M-x untabify} to convert tabs in a region to multiple spaces.
-@end quotation
+The output uses a fixed-width font and is indented. Each line
+in the input file is a line in the output; that is, the source
+text is not filled. Extra spaces and blank lines are significant.
+Texinfo commands @emph{are} expanded; if you want the output to be
+the input verbatim, use the @code{@@verbatim} environment instead
+(@pxref{@code{@@verbatim}}).
Examples are often, logically speaking, ``in the middle'' of a
paragraph, and the text that continues afterwards should not be
@@ -7144,12 +6558,26 @@ indented, as in the example above. The @code{@@noindent} command
prevents a piece of text from being indented as if it were a new
paragraph (@pxref{@code{@@noindent}}).
-If you want to embed code fragments within sentences, instead of
-displaying them, use the @code{@@code} command or its relatives
-(@pxref{@code{@@code}}).
+If you wish to use the normal roman font for a code comment, you can
+use the @code{@@r} command (@pxref{Fonts}).
+
+You may optionally give arguments to the @code{@@example} command,
+separated by commas if there is more than one. In the HTML output,
+any such arguments are output as class names. This may be useful for
+adding syntax highlighting to manuals for code samples. We recommend
+that when you give multiple arguments to @code{@@example}, you
+use the first argument to specify the language of the code (e.g.@:
+@samp{C}, @samp{lisp}, @samp{Cplusplus}). You may find uses for other
+arguments, such as providing a formatting hint or marking code samples
+for extraction and further processing, but for now nothing definitive
+is recommended. Perhaps this will change in future Texinfo releases.
+
+@quotation Caution
+Do not use tabs in the lines of an example! (Or anywhere else in
+Texinfo, except in verbatim environments.) @TeX{} treats tabs as
+single spaces, and that is not what they look like.
+@end quotation
-If you wish to write a ``comment'' on a line of an example in the
-normal roman font, you can use the @code{@@r} command (@pxref{Fonts}).
@node @code{@@verbatim}
@@ -7231,20 +6659,26 @@ See also @ref{@code{@@verbatiminclude}}.
@findex lisp
@cindex Lisp example
-The @code{@@lisp} command is used for Lisp code. It is synonymous
-with the @code{@@example} command.
+The @code{@@lisp} command is used for Lisp code:
-@lisp
-This is an example of text written between an
-@code{@@lisp} command and an @code{@@end lisp} command.
-@end lisp
+@example
+@@lisp
+Example lisp code
+@@end lisp
+@end example
+
+@noindent This is synonymous with the following:
+
+@example
+@@example lisp
+Example lisp code
+@@end example
+@end example
-Use @code{@@lisp} instead of @code{@@example} to preserve information
-regarding the nature of the example. This is useful, for example, if
-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. Mark the end of @code{@@lisp} with @code{@@end lisp} on a line
-by itself.
+Use @code{@@lisp} to preserve information regarding the nature of
+the example. This is useful, for example, if 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.
@node @code{@@display}
@@ -7265,11 +6699,6 @@ and an @code{@@end display} command. The @code{@@display} command
indents the text, but does not fill it.
@end display
-@findex smalldisplay
-Texinfo also provides the environment @code{@@smalldisplay}, which is
-like @code{@@display} but uses a smaller font size.
-@xref{@code{@@small@dots{}}}.
-
@node @code{@@format}
@section @code{@@format}: Examples Using the Full Line Width
@@ -7288,11 +6717,6 @@ from this example,
the @code{@@format} command does not fill the text.
@end format
-@findex smallformat
-Texinfo also provides the environment @code{@@smallformat}, which is
-like @code{@@format} but uses a smaller font size.
-@xref{@code{@@small@dots{}}}.
-
@node @code{@@exdent}
@section @code{@@exdent}: Undoing a Line's Indentation
@@ -7583,14 +7007,15 @@ Info, you'll see the @code{@@cartouche} had no effect):
@code{@@cartouche} also implies @code{@@group} (@pxref{@code{@@group}}).
-@node @code{@@small@dots{}}
+@node small
@section @code{@@small@dots{}} Block Commands
-@anchor{small}@c old name
@findex smallexample
@findex smallformat
@findex smalllisp
@findex smallquotation
+@findex smalldisplay
+@findex smallindentedblock
@cindex Small examples
@cindex Examples in smaller fonts
@cindex Quotations in smaller fonts
@@ -7634,10 +7059,9 @@ a fixed-width font, and everything else uses the regular font.
They also have the same behavior in other respects---whether filling
is done and whether margins are narrowed.
-As a general rule, a printed document looks better if you use only one
-of (for instance) @code{@@example} or @code{@@smallexample}
-consistently within a chapter.
-
+As a general rule, it's better to just use the regular
+commands (such as @code{@@example} instead of @code{@@smallexample}),
+unless you have a good reason for it.
@@ -8200,6 +7624,11 @@ To specify column widths as fractions of the line length, write
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.
+When using @code{@@columnfractions}, the leftmost column may appear
+slightly wider than you might expect, relative to the other columns.
+This is due to spacing between columns being included in the width of
+the other columns.
+
@item
@cindex Prototype row, column widths defined by
To specify a prototype row, write the longest entry for each column
@@ -8241,7 +7670,7 @@ input lines in your source file as necessary.
@cindex @code{<thead>} HTML/XML tag
You can also use @code{@@headitem} instead of @code{@@item} to produce
a @dfn{heading row}. The @TeX{} output for such a row is in bold, and
-the HTML and Docbook output uses the @code{<thead>} tag. In Info, the
+the HTML and DocBook output uses the @code{<thead>} tag. In Info, the
heading row is followed by a separator line made of dashes (@samp{-}
characters).
@@ -8318,7 +7747,7 @@ Another group of commands is for creating footnotes in Texinfo.
@node Floats
@section Floats
-@cindex Floats, in general
+@cindex Floats
A @dfn{float} is a display which is set off from the main text. It is
typically labeled as being a ``Figure'', ``Table'', ``Example'', or
@@ -8383,7 +7812,7 @@ float is automatically given a number, and will appear in any
@code{@@listoffloats} output (@pxref{@code{@@listoffloats}}). Cross
references to @var{label} are allowed.
-@cindex Floats, making unnumbered
+@cindex Floats @subentry making unnumbered
@cindex Unnumbered float, creating
On the other hand, if @var{label} is not given, then the float will
not be numbered and consequently will not appear in the
@@ -8393,7 +7822,7 @@ not be numbered and consequently will not appear in the
@noindent Ordinarily, you specify both @var{type} and @var{label}, to get a
labeled and numbered float.
-@cindex Floats, numbering of
+@cindex Floats @subentry numbering of
@cindex Numbering of floats
In Texinfo, all floats are numbered in the same way: with the chapter
number (or appendix letter), a period, and the float number, which
@@ -8469,7 +7898,7 @@ there is a @code{@@shortcaption}.
@anchor{listoffloats}@c old name
@findex listoffloats
@cindex List of floats
-@cindex Floats, list of
+@cindex Floats @subentry list of
@cindex Table of contents, for floats
You can write a @code{@@listoffloats} command to generate a list of
@@ -8518,7 +7947,7 @@ from the list of floats.
@node Images
@section Inserting Images
-@cindex Images, inserting
+@cindex Images
@cindex Pictures, inserting
@findex image
@@ -8577,18 +8006,18 @@ order). If none of those exist, it gives an error, and outputs a
reference to @file{@var{filename}.jpg} anyway.
@item
-@cindex SVG images, used in Docbook
-For Docbook, @code{makeinfo} outputs references to
+@cindex SVG images, used in DocBook
+For DocBook, @code{makeinfo} outputs references to
@file{@var{filename}.eps}, @file{@var{filename}.gif}
@file{@var{filename}.jpeg}, @file{@var{filename}.jpg},
@file{@var{filename}.pdf}, @file{@var{filename}.png} and
@file{@var{filename}.svg}, for every file found. Also,
@file{@var{filename}.txt} is included verbatim, if present. (The
-subsequent Docbook processor is supposed to choose the appropriate one.)
+subsequent DocBook processor is supposed to choose the appropriate one.)
@item
For Info and HTML output, @code{makeinfo} uses the optional fifth
-argument @var{extension} to @code{@@image} for the filename extension,
+argument @var{extension} to @code{@@image} for the file extension,
if it is specified and the file is found. Any leading period should
be included in @var{extension}. For example:
@@ -8608,14 +8037,17 @@ for a package @var{foo}. Copying the files into
The @var{width} and @var{height} arguments are described in the next
section.
-For @TeX{} output, if an image is the only thing in a paragraph it
-will ordinarily be displayed on a line by itself, respecting the
-current environment indentation, but without the normal paragraph
-indentation. If you want it centered, use @code{@@center}
+If an image is the first thing in a paragraph and followed by
+more text, then you should precede the @code{@@image} command with
+@code{@@indent} or @code{@@noindent} to indicate the beginning of
+paragraph formatting. This is especially important for @TeX{} output
+to get correct paragraph indentation.
+
+Use @code{@@center} to center an image
(@pxref{@code{@@titlefont @@center @@sp}}).
@cindex Alt attribute for images
-@cindex Images, alternate text for
+@cindex Images @subentry alternate text for
@findex @sortas{-} -@r{ (in image alt string)}
For HTML output, @code{makeinfo} sets the @dfn{alt attribute} for
inline images to the optional @var{alttext} (fourth) argument to
@@ -8660,7 +8092,7 @@ literally, which, although not pretty, should not be harmful.
@node Image Scaling
@subsection Image Scaling
-@cindex Images, scaling
+@cindex Images @subentry scaling
@cindex Scaling images
@cindex Width of images
@cindex Height of images
@@ -8860,14 +8292,14 @@ node for the @file{Footnotes} node is
Here is how the first footnote in this manual looks after being
formatted for Info in the separate node style:
-@smallexample
+@example
@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 example
@end itemize
Unless your document has long and important footnotes (as in, say,
@@ -9089,13 +8521,13 @@ similar to the indices you may see in professionally published books.
@findex @@subentry
First, you can create @dfn{multilevel} index entries, allowing you
-to group many related subtopics under the same higher level topic.
+to group many related subtopics under the same higher-level topic.
You do this by separating the parts of such an entry with the
@code{@@subentry} command. Such commands might look like this:
@example
-@@cindex Superhumans @@subentry villians
-@@cindex Superhumans @@subentry heros
+@@cindex Superhumans @@subentry villains
+@@cindex Superhumans @@subentry heroes
@end example
You may have up to three levels in an entry:
@@ -9109,7 +8541,7 @@ You can use the @code{@@sortas} command mentioned earlier with any or
all of the three parts of an entry to cause them to sort differently
than they would by default.
-@findex @@seeentry
+@findex seeentry
Second, you may provide an index entry that points to another,
using the @code{@@seeentry} (``see entry'') command. For example:
@@ -9121,7 +8553,7 @@ Such an entry should be unique in your document; the idea is to
redirect the reader to the other entry where they will find all
the information they are looking for.
-@findex @@seealso
+@findex seealso
Finally, you may provide a ``see also'' entry using the @code{@@seealso}
command. These entries go along with regular entries, and are grouped
together with them in the final printed index. For example:
@@ -9135,13 +8567,13 @@ together with them in the final printed index. For example:
@end example
When using all three of these advanced commands, @emph{do not}
-place a comma betwen the different parts of the index text. The
+place a comma between the different parts of the index text. The
@command{texindex} program, which sorts the index entries and
generates the indexing formatting commands, takes care of placing
commas in the correct places for you.
These features are most useful with printed documents created
-with @TeX{}, and when translating Texinfo to Docbook.
+with @TeX{}, and when translating Texinfo to DocBook.
@node Index Entries
@section Making Index Entries
@@ -9240,7 +8672,7 @@ into the table of contents. Precede the chapter heading with an
For example:
-@smallexample
+@example
@group
@@node Variable Index
@@unnumbered Variable Index
@@ -9254,7 +8686,7 @@ For example:
@@printindex cp
@end group
-@end smallexample
+@end example
If you have more than one index, we recommend placing the concept index last.
@@ -9271,9 +8703,9 @@ readers can use this to go to the exact line of an entry, not just the
containing node. (Older Info readers will just go to the node.)
Here's an example:
-@smallexample
+@example
* First index entry: Top. (line 7)
-@end smallexample
+@end example
@noindent The actual number of spaces is variable, to right-justify
the line number; it's been reduced here to make the line fit in the
@@ -9289,7 +8721,7 @@ In HTML output, @code{@@printindex} produces links to the index
entries.
@item
-In XML and Docbook output, it simply records the index to be printed.
+In XML and DocBook output, it simply records the index to be printed.
@end itemize
@@ -9376,7 +8808,7 @@ following:
This causes all entries designated for the function index to merge
in with the concept index instead.
-To merge both a variables index and a function index into a concept
+To merge both a variable index and a function index into a concept
index, write the following:
@example
@@ -9480,7 +8912,7 @@ Texinfo file, and (of course) before any @code{@@synindex} or
@code{@@syncodeindex} commands (@pxref{Texinfo File Header}).
As mentioned earlier (@pxref{Predefined Indices}), we recommend having
-a single index in the final document whenever possible (no matter however many
+a single index in the final document whenever possible (no matter how many
source indices you use), since then readers have only one place to
look.
@@ -9785,8 +9217,8 @@ be the undirected single quote, like this:
@item @@codequotebacktick @var{on-off}
@findex codequotebacktick
-@cindex backtick
-@cindex grave accent, standalone
+@cindex Backtick
+@cindex Grave accent @subentry standalone
causes the output for the @code{`} character in code environments to
be the backtick character (standalone grave accent), like this:
@set txicodequotebacktick on
@@ -9802,12 +9234,11 @@ These settings affect @code{@@code}, @code{@@example}, @code{@@kbd},
@code{@@samp}, @code{@@verb}, and @code{@@verbatim}. @xref{Useful
Highlighting}.
-@vindex txicodequoteundirected@r{, obsolete variable}
-@vindex txicodequotebacktick@r{, obsolete variable}
-This feature used to be controlled by using @code{@@set} to change the
+@vindex txicodequoteundirected
+@vindex txicodequotebacktick
+This feature can also be controlled by using @code{@@set} to change the
values of the corresponding variables @code{txicodequoteundirected}
-and @code{txicodequotebacktick}; they are still supported, but the
-command interface is preferred.
+and @code{txicodequotebacktick}.
@node Inserting Space
@@ -9893,7 +9324,7 @@ necessary in the following situations:
@enumerate
@item After a period that ends a lowercase abbreviation which is not at
-the end of a sentences.
+the end of a sentence.
@item When a parenthetical remark in the middle of a sentence (like
this one!)@: ends with a period, exclamation point or question mark,
@@ -9932,7 +9363,7 @@ the code-like highlighting commands, @code{@@var}, @code{@@abbr}, and
@samp{@@code@{foo. bar@}} the period is not considered to be the end of a
sentence, and no extra space is inserted.
-@code{@@:} has no effect on the HTML or Docbook output.
+@code{@@:} has no effect on the HTML or DocBook output.
@node Ending a Sentence
@@ -10042,7 +9473,7 @@ This is text. Two sentences. Three sentences. Non-French spacing.
@code{@@frenchspacing} also affects the output after @code{@@.},
@code{@@!}, and @code{@@?} (@pxref{Ending a Sentence}).
-@code{@@frenchspacing} has no effect on the HTML or Docbook output;
+@code{@@frenchspacing} has no effect on the HTML or DocBook output;
for XML, it outputs a transliteration of itself (@pxref{Output
Formats}).
@@ -10257,7 +9688,7 @@ left- and right-hand doubled quotation marks,
``like this'',
@end iftex
and Info converts doubled single-quote characters to ASCII
-double-quotes: @w{@t{`@w{}`@dots{}'@w{}'}} becomes @w{@t{"@dots{}"}}.
+double quotes: @w{@t{`@w{}`@dots{}'@w{}'}} becomes @w{@t{"@dots{}"}}.
You may occasionally need to produce two consecutive single quotes;
for example, in documenting a computer language such as Maxima where
@@ -10266,7 +9697,7 @@ for example, in documenting a computer language such as Maxima where
the double-quote characters.
@cindex Unicode quotation characters
-@cindex Grave accent, vs. left quote
+@cindex Grave accent @subentry vs. left quote
The left quote character (@t{`}, ASCII code 96) used in Texinfo is a
grave accent in ANSI and ISO character set standards. We use it as a
quote character because that is how @TeX{} is set up, by default.
@@ -10290,7 +9721,7 @@ Latin@tie{}9).
@cindex EC fonts
The standard @TeX{} fonts support the usual quotation marks used in
English (the ones produced with single and doubled ASCII
-single-quotes). For the other quotation marks, @TeX{} uses European
+single quotes). For the other quotation marks, @TeX{} uses European
Computer Modern (EC) fonts (@file{ecrm1000} and other variants).
These fonts are freely available, of course; you can download them
from @url{http://ctan.org/pkg/ec}, among other places.
@@ -10380,7 +9811,7 @@ manual. Sometimes aliases (@pxref{@code{@@alias}}) can simplify the
usage and make the source code more readable. For example, in German,
@code{@@quotedblbase} is used for the left double quote, and the right
double quote is the glyph produced by @code{@@quotedblleft}, which is
-counter-intuitive. Thus, in this case the following aliases would be
+counterintuitive. Thus, in this case the following aliases would be
convenient:
@example
@@ -10396,10 +9827,8 @@ convenient:
@findex sup
@cindex Subscripts and superscripts, text
-You can insert subscripts and superscripts, in either text or math,
-with the @code{@@sub} and @code{@@sup} commands. (For other
-mathematical expressions, see the next section.) For example, here is
-a purely textual subscript and superscript:
+You can insert subscripts and superscripts with the @code{@@sub}
+and @code{@@sup} commands. For example:
@example
here@@sub@{below@}@@sup@{above@}
@@ -10411,116 +9840,93 @@ here@@sub@{below@}@@sup@{above@}
here@sub{below}@sup{above}
@end display
-@cindex Math italic font
-Inside @code{@@math}, @code{@@sub} and @code{@@sup} produce
-mathematical subscripts and superscripts. This uses a different font
-in the @TeX{} output (math italic instead of text italic); it makes no
-difference in the other output formats. Here's an example:
+In Info and plain text, @code{@@sub@{@var{text}@}} is output
+as @samp{_@{@var{text}@}} and @code{@@sup@{@var{text}@}} as
+@samp{^@{@var{text}@}}, including the literal braces (to mark the
+beginning and end of the ``script'' text to the reader).
-@example
-@@math@{e@@sup@{x@}@}
-@end example
+When the output format (and display program) permit (@TeX{}, HTML),
+the superscript is set above the subscript when both commands are
+given consecutively.
-@noindent produces:
-
-@display
-@math{e@sup{x}}
-@end display
-
-In Info and plain text, regardless of being used inside @code{@@math},
-@code{@@sub@{@var{text}@}} is output as @samp{_@{@var{text}@}} and
-@code{@@sup@{@var{text}@}} as @samp{^@{@var{text}@}}, including the
-literal braces (to mark the beginning and end of the ``script'' text
-to the reader).
-
-When the output format (and display program) permit (@TeX{} math,
-HTML), the superscript is set above the subscript when both commands
-are given consecutively.
+For subscripts and superscripts in mathematical expressions, it is
+better to use @TeX{}'s @samp{_} and @samp{^} characters. See the
+next section.
@node Inserting Math
-@section @code{@@math}: Inserting Mathematical Expressions
+@section @code{@@math} and @code{@@displaymath}: Formatting Mathematics
@anchor{math}@c old name
@findex math
@cindex Mathematical expressions, inserting
@cindex Formulas, mathematical
-
You can write a short mathematical expression with the @code{@@math}
command. Write the mathematical expression between braces, like this:
@example
-@@math@{(a + b) = (b + a)@}
+@@math@{\sin 2\pi \equiv \cos 3\pi@}
@end example
-@iftex
-@noindent This produces the following in @TeX{}:
-
+@noindent which looks like this:
@display
-@math{(a + b) = (b + a)}
+@math{\sin 2\pi \equiv \cos 3\pi}
@end display
-@noindent and the following in other formats:
-@end iftex
-@ifnottex
-@noindent This produces the following in Info and HTML:
-@end ifnottex
-
-@example
-(a + b) = (b + a)
-@end example
-
-@cindex MathML, not used
-The @code{@@math} command has no special effect on the Info and HTML
-output. @command{makeinfo} expands any @@-commands as usual, but it
-does not try to use produce good mathematical formatting in any way
-(no use of MathML, etc.). The HTML output is enclosed by
-@code{<em>...</em>}, but nothing more.
-
-@findex \mathopsup
-However, as far as the @TeX{} output is concerned, plain @TeX{}
-mathematical commands are allowed in @code{@@math}, starting with
-@samp{\}. In essence, @code{@@math} switches into plain @TeX{} math
-mode. (Exception: the plain @TeX{} command @code{\sup}, which
-typesets the mathematical operator name `sup', must be accessed as
-@code{\mathopsup}, due to the conflict with Texinfo's @code{@@sup}
-command.)
-
-This allows you to use all the plain @TeX{} math control sequences for
-symbols, functions, and so on, and thus get proper formatting in the
-@TeX{} output, at least.
-
-The @code{@@sub} and @code{@@sup} commands described in the previous
-section produce subscripts and superscripts in HTML output as well as
-@TeX{}; the plain @TeX{} characters @code{_} and @code{^} for
-subscripts and superscripts are recognized by @TeX{} inside
-@code{@@math}, but do nothing special in HTML or other output formats.
+The @code{@@math} command has no special effect on the Info
+output or (by default) the HTML output, merely outputting
+the contents verbatim.
+
+For the @TeX{} output, @code{@@math} switches into math mode.
+This allows you to use all the
+plain @TeX{} math control sequences for symbols, functions, and so on,
+starting with @samp{\}. It's best to use @samp{\} instead of @samp{@@}
+for any such mathematical commands; otherwise, @command{texi2any}
+will complain.
+
+@cindex Math output for HTML
+By default, the HTML output is only enclosed by @code{<em>}.
+@command{texi2any} provides three options for displaying properly
+formatted mathematics for HTML. You can select these with the
+@code{HTML_MATH} variable (@pxref{HTML Customization Variables}).
+With @code{HTML_MATH} set to @samp{l2h}, @command{texi2any} attempts
+to use the @command{latex2html} program to produce image files for
+mathematical material. With the @samp{t4h} setting, @command{texi2any}
+attempts to use the @command{tex4ht} program. With the @samp{mathjax}
+setting, @command{texi2any} inserts references in the output files
+to MathJax scripts to format the material. The MathJax option
+requires JavaScript to be enabled in the browser to work. See also
+@ref{MathJax Customization Variables} and @ref{@command{latex2html}
+Customization Variables}.
-It's best to use @samp{\} instead of @samp{@@} for any such
-mathematical commands; otherwise, @command{makeinfo} will complain.
-On the other hand, @command{makeinfo} does allow input with matching
-(but unescaped) braces, such as @samp{k_@{75@}}; it complains about
-such bare braces in regular input.
-
-Here's an example:
+@cindex Displayed equations
+@cindex Equations, displayed
+@findex displaymath
+For displayed equations, you can use the @code{@@displaymath}
+command. Example:
@example
-@@math@{\sin 2\pi \equiv \cos 3\pi@}
+@@displaymath
+f(x) = @{1\over\sigma\sqrt@{2\pi@}@}
+e^@{-@{1\over2@}\left(@{x-\mu\over\sigma@}\right)^2@}
+@@end displaymath
@end example
-@iftex
-@noindent which looks like this in @TeX{}:
-@display
-@math{\sin 2\pi \equiv \cos 3\pi}
-@end display
+@noindent which produces:
-@noindent but
-@end iftex
-@noindent which looks like the input in Info and HTML:
-@example
-\sin 2\pi \equiv \cos 3\pi
-@end example
+@displaymath
+f(x) = {1\over\sigma\sqrt{2\pi}}
+e^{-{1\over2}\left({x-\mu\over\sigma}\right)^2}
+@end displaymath
+Although @code{@@sub} and @code{@@sup} may work inside math mode in
+some contexts, it is better to use @TeX{}'s @samp{_} and @samp{^}
+characters to denote subscripts and superscripts within mathematical
+expressions. In general, the contents of @code{@@math} or
+@code{@@displaymath} should be plain @TeX{} only, with no
+interspersed Texinfo commands.
+
+@ignore
@findex @sortas{\} \ @r{(literal \ in @code{@@math})}
Since @samp{\} is an escape character inside @code{@@math}, you can
use @code{@@\} to get a literal backslash (@code{\\} will work in
@@ -10529,11 +9935,16 @@ use @code{@@\} to get a literal backslash (@code{\\} will work in
ordinarily produces a literal (typewriter) @samp{\}. You can also use
@code{@@backslashchar@{@}} in any mode to get a typewriter backslash.
@xref{Inserting a Backslash}.
+@end ignore
+
+@findex \mathopsup
+Due to the conflict with Texinfo's @code{@@sup} command, you can access
+the plain @TeX{} command @code{\sup} as @code{\mathopsup} instead,
+in the unlikely occurrence that you want to do this (but only when
+processing with @TeX{}, not with any of the @code{HTML_MATH} options).
+
+
-@cindex Displayed equations
-@cindex Equations, displayed
-For displayed equations, you must at present use @TeX{} directly
-(@pxref{Raw Formatter Commands}).
@node Glyphs for Text
@@ -10584,7 +9995,7 @@ incorrect @code{La@@TeX@{@}}. In Info, the result is just
@TeX{}, very loosely analogous to Texinfo in that it emphasizes
logical structure, but much (much) larger.)
-The spelling of these commands are unusual for Texinfo, in that they
+The spelling of these commands is unusual for Texinfo, in that they
use both uppercase and lowercase letters.
@@ -10829,7 +10240,7 @@ Here is a summary of the glyph commands:
@code{@@point@{@}} shows the location of point.
@item @clicksequence{A @click{} B}
-@code{@@clicksequence@{A @@click@{@} B} indicates a GUI operation
+@code{@@clicksequence@{A @@click@{@} B@}} indicates a GUI operation
sequence: first A, then clicking B, or choosing B from a menu, or
otherwise selecting it.
@end table
@@ -11182,7 +10593,7 @@ an error is given. (@xref{@code{@@documentencoding}}.)
@cindex Entity reference in HTML et al.
@cindex @samp{&#x@var{hex};}, output from @code{@@U}
-In HTML, XML, and Docbook, the output from @code{@@U} is always an
+In HTML, XML, and DocBook, the output from @code{@@U} is always an
entity reference of the form @samp{&#x@var{hex};}, as in
@samp{&#x0132;} for the example above. This should work even when an
HTML document uses some other encoding (say, Latin@tie{}1) and the
@@ -11199,7 +10610,7 @@ is the ASCII sequence @samp{U+@var{hex}}, as in the six ASCII characters
@cindex Forcing line and page breaks
@cindex Making line and page breaks
@cindex Preventing line and page breaks
-@cindex Line breaks, awkward
+@cindex Line breaks @subentry awkward
@cindex Page breaks, awkward
Line and page breaks can sometimes occur in the `wrong' place in one
@@ -11210,7 +10621,7 @@ 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.
+would normally occur.
You can use the break, break prevention, or pagination commands to fix
problematic line and page breaks.
@@ -11278,7 +10689,7 @@ Start a new page if not enough space on this one.
@findex * @r{(force line break)}
@findex / @r{(allow line break)}
-@cindex Line breaks, controlling
+@cindex Line breaks @subentry controlling
@cindex Controlling line breaks
@cindex Breaks in a line
@cindex Force line break
@@ -11306,7 +10717,7 @@ The @code{@@/} command can be useful within long urls or other
identifiers where @TeX{} can't find a good place to break. @TeX{}
will automatically break urls at the natural places (@pxref{URL Line
Breaking}), so only use @code{@@/} if you need it. @code{@@/} has no
-effect in the other output format.
+effect on the other output format.
@node @code{@@- @@hyphenation}
@@ -11365,7 +10776,7 @@ hyphenation points.
This is necessary since many manuals, especially for Lisp-family
languages, must document very long identifiers. On the other hand,
-some manuals don't have this problems, and you may not wish to allow a
+some manuals don't have this problem, and you may not wish to allow a
line break at the underscore in, for example, @code{SIZE_MAX}, or even
worse, after any of the four underscores in @code{__typeof__}.
@@ -12216,7 +11627,7 @@ style is to put the return type on a line by itself. So Texinfo
provides an option to do that: @code{@@deftypefnnewline on}.
This affects typed functions only---not untyped functions, not typed
-variables, etc.. Specifically, it affects the commands in this
+variables, etc. Specifically, it affects the commands in this
section, and the analogous commands for object-oriented languages,
namely @code{@@deftypeop} and @code{@@deftypemethod}
(@pxref{Object-Oriented Methods}).
@@ -12876,7 +12287,7 @@ this:
charset=@var{enc}">
@end example
-In XML and Docbook output, UTF-8 is always used for the output,
+In XML and DocBook output, UTF-8 is always used for the output,
according to the conventions of those formats.
@cindex Computer Modern fonts
@@ -12967,7 +12378,7 @@ The environments for the other formats are analogous:
@table @code
@item @@ifdocbook @dots{} @@end ifdocbook
-Text to appear only in the Docbook output.
+Text to appear only in the DocBook output.
@item @@ifhtml @dots{} @@end ifhtml
Text to appear only in the HTML output.
@@ -13010,7 +12421,7 @@ Whereas this text will only appear in plain text.
Notwithstanding that this will only appear in XML@.
@@end ifxml
@@ifdocbook
-Nevertheless, this will only appear in Docbook.
+Nevertheless, this will only appear in DocBook.
@@end ifdocbook
@end example
@@ -13033,7 +12444,7 @@ Whereas this text will only appear in plain text.
Notwithstanding that this will only appear in XML@.
@end ifxml
@ifdocbook
-Nevertheless, this will only appear in Docbook.
+Nevertheless, this will only appear in DocBook.
@end ifdocbook
@noindent
@@ -13126,7 +12537,7 @@ commands. All plain @TeX{} commands and category codes are restored
within a @code{@@tex} region. The sole exception is that the
@code{@@} character still introduces a command, so that @code{@@end
tex} can be recognized. Texinfo processors will not output material
-in such a region, unless @TeX{} output is being produced.
+in such a region unless @TeX{} output is being produced.
@findex \gdef @r{within @code{@@tex}}
@findex \globaldefs @r{within @code{@@tex}}
@@ -13197,12 +12608,12 @@ will be included in the XML output as:
@end group
@end example
-@cindex Docbook, including raw
+@cindex DocBook, including raw
@findex ifdocbook
@findex docbook
Again likewise, you can use @code{@@ifdocbook @dots{} @@end ifdocbook}
-to delimit Texinfo source to be included in Docbook output only, and
-@code{@@docbook @dots{} @@end docbook} for a region of raw Docbook.
+to delimit Texinfo source to be included in DocBook output only, and
+@code{@@docbook @dots{} @@end docbook} for a region of raw DocBook.
The behavior of newlines in raw regions is unspecified.
@@ -13703,7 +13114,7 @@ and thus no reason to worry about older versions. (It is
straightforward for anyone to download and install the Texinfo source;
it does not have any problematic dependencies.)
-The issue of Texinfo versions does not generally arise for end-users.
+The issue of Texinfo versions does not generally arise for end users.
With properly distributed packages, users need not process the Texinfo
manual simply to build and install the package; they can use
preformatted Info (or other) output files. This is desirable in
@@ -14106,7 +13517,7 @@ As mentioned earlier, macro names must consist entirely of letters.
@item
It is not advisable to redefine any @TeX{} primitive, plain, or
-Texinfo command name as a macro. Unfortunately this is a large and
+Texinfo command name as a macro. Unfortunately, this is a large and
open-ended set of names, and the possible resulting errors are
unpredictable.
@@ -14170,7 +13581,7 @@ The backslash escape for commas in macro arguments does not work;
@item
Likewise, if you want to pass an argument with the Texinfo command
@code{@@,} (to produce a cedilla, see @ref{Inserting Accents}), you have
-to use @code{@@value} or another work-around. Otherwise, the comma
+to use @code{@@value} or another workaround. Otherwise, the comma
may be taken as separating the arguments. For example,
@example
@@ -14339,19 +13750,16 @@ character) @samp{-}.
@anchor{definfoenclose}@c old name
@cindex Highlighting, customized
-@cindex Customized highlighting
@findex definfoenclose
An @code{@@definfoenclose} command may be used to define a
highlighting command for all the non-@TeX{} output formats. 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 output.
+strings that precede and follow the text.
-Presumably, if you define a command with @code{@@definfoenclose}, you
-will create a corresponding command for @TeX{}, either in
-@file{texinfo.tex}, @file{texinfo.cnf}, or within an @samp{@@iftex} or
-@samp{@@tex} in your document.
+In practice, there is little use for this command, and we do not
+recommend you use it. Support for @code{@@definfoenclose} may be
+removed in future releases of Texinfo.
Write a @code{@@definfoenclose} command at the beginning of a line
followed by three comma-separated arguments. The first argument to
@@ -14366,11 +13774,6 @@ want an end delimiter, you must follow the command name with two
commas in a row; otherwise, the end delimiter string you intended will
naturally be (mis)interpreted as the start delimiter string.
-If you do a @code{@@definfoenclose} on the name of a predefined
-command (such as @code{@@emph}, @code{@@strong}, @code{@@t}, or
-@code{@@i}), the enclosure definition will override the built-in
-definition. We don't recommend this.
-
An enclosure command defined this way takes one argument in braces,
since it is intended for new markup commands (@pxref{Marking Text}).
@@ -14402,7 +13805,7 @@ argument to @code{@@phoo} in italics.
Each definition applies to its own formatter: one for @TeX{}, the
other for everything else. The raw @TeX{} commands need to be in
@samp{@@iftex}. @code{@@definfoenclose} command need not be within
-@samp{@@ifinfo}, unless you want to use different definitions for
+@samp{@@ifinfo} unless you want to use different definitions for
different output formats.
@findex headword
@@ -14508,7 +13911,7 @@ disabled inside verbatim blocks.
@subsection @samp{#line} and @TeX{}
@cindex @TeX{} and @samp{#line} directives
-@cindex @samp{#line} directives, not processing with @TeX{}
+@cindex @samp{#line} directive @subentry not processing with @TeX{}
As mentioned, @command{makeinfo} recognizes the @samp{#line}
directives described in the previous section. However,
@@ -14550,7 +13953,7 @@ Advantages}).
@node @samp{#line} Syntax Details
@subsection @samp{#line} Syntax Details
-@cindex @samp{#line} syntax details
+@cindex @samp{#line} directive @subentry syntax details
@cindex Syntax details, @samp{#line}
@cindex Regular expression, for @samp{#line}
@@ -14566,7 +13969,7 @@ cases). For those who like to know the gory details, the actual
@end example
As far as we've been able to tell, the trailing integer flags only
-occur in conjunction with a filename, so that is reflected in the
+occur in conjunction with a file name, so that is reflected in the
regular expression.
As an example, the following is a syntactically valid @samp{#line}
@@ -14576,7 +13979,7 @@ directive, meaning line 1 of @file{/usr/include/stdio.h}:
@hashchar{} 1 "/usr/include/stdio.h" 2 3 4
@end example
-Unfortunately, the quoted filename (@samp{"..."}) has to be optional,
+Unfortunately, the quoted file name (@samp{"..."}) has to be optional,
because M4 (especially) can often generate @samp{#line} directives
within a single file. Since the @samp{line} is also optional, the
result is that lines might match which you wouldn't expect, e.g.,
@@ -14607,8 +14010,6 @@ collection of conveniently small parts.
* Sample Include File:: A sample outer file with included files
within it; and a sample included file.
* @code{@@verbatiminclude}:: Including a file verbatim.
-* Include Files Evolution:: How use of the @code{@@include} command
- has changed over time.
@end menu
@@ -14851,6 +14252,8 @@ For a method on printing the file contents in a smaller font size, see
the end of the section on @code{@@verbatim}.
+@ignore
+
@node Include Files Evolution
@section Evolution of Include Files
@@ -14890,6 +14293,8 @@ file that is split into smaller files if necessary. This means that
you can write menus and cross-references without naming the different
Texinfo files.
+@end ignore
+
@node Hardcopy
@chapter Formatting and Printing Hardcopy
@@ -14918,6 +14323,14 @@ 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.
+In the United States, documents are most often printed on 8.5 inch by
+11 inch pages (216@dmn{mm} by 280@dmn{mm}); this is the default size.
+But you can also print for 7 inch by 9.25 inch pages (178@dmn{mm} by
+235@dmn{mm}, the @code{@@smallbook} size; or on A4 or A5 size paper
+(@code{@@afourpaper}, @code{@@afivepaper}).
+@xref{@code{@@smallbook}}, and @ref{A4 Paper}.
+
+
Details are in the following sections.
@menu
@@ -14931,12 +14344,7 @@ Details are in the following sections.
* Requirements Summary:: @TeX{} formatting requirements summary.
* Preparing for @TeX{}:: What to do before you use @TeX{}.
* Overfull hboxes:: What are and what to do with overfull hboxes.
-* @code{@@smallbook}:: How to print small format books and manuals.
-* A4 Paper:: How to print on A4 or A5 paper.
-* @code{@@pagesizes}:: How to print with customized page sizes.
-* Magnification:: How to print scaled up output.
* PDF Output:: Portable Document Format output.
-* Obtaining @TeX{}:: How to obtain @TeX{}.
@end menu
@@ -14945,12 +14353,23 @@ Details are in the following sections.
The typesetting program called @TeX{} is used to format a Texinfo
document for printable output. @TeX{} is a very powerful typesetting
-program and, when used correctly, does an exceptionally good job.
-
-@xref{Obtaining @TeX{}}, for information on how to obtain @TeX{}. It
-is not included in the Texinfo package, being a vast suite of software
+program and, when used correctly, does an exceptionally good job. It is
+not included in the Texinfo package, being a vast suite of software
in itself.
+@anchor{Obtaining @TeX{}}
+@cindex Obtaining @TeX{}
+@cindex @TeX{}, how to obtain
+@TeX{} is a document formatter that is used by the FSF for its
+documentation. It is the easiest way to get printed output (e.g., PDF
+and PostScript) for Texinfo manuals. TeX is freely redistributable,
+and you can get it over the Internet or on physical media. See
+@url{http://tug.org/texlive}.
+
+@c please keep that text in sync with www.gnu.org/prep/FTP
+
+
+
@node Format with @command{texi2dvi}
@section Format with @command{texi2dvi}
@@ -14970,11 +14389,8 @@ prompt$ @kbd{texi2dvi foo.texi}
prompt$ @kbd{texi2pdf foo.texi}
@end example
-As shown in this example, the input filenames to @code{texi2dvi} and
+As shown in this example, the file names given to @code{texi2dvi} and
@code{texi2pdf} must include any extension, such as @samp{.texi}.
-(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.)
For a list of all the options, run @samp{texi2dvi --help}. Some of the
options are discussed below.
@@ -15087,7 +14503,7 @@ not required, and the DVI output is identical.
same, but we still run @command{pdfetex} to cater to ancient @TeX{}
installations.)
-@cindex filename recorder for @TeX{}
+@cindex file recorder for @TeX{}
@cindex @samp{\openout} line in log file
@command{texi2dvi} attempts to detect auxiliary files output by @TeX{},
either by using the @option{-recorder} option, or by scanning for
@@ -15189,7 +14605,7 @@ up-to-date index entries.
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 five step process. (Alternatively, it's a
+To summarize, this is a five-step process. (Alternatively, it's a
one-step process: run @code{texi2dvi}; see the previous section.)
@enumerate
@@ -15228,7 +14644,7 @@ written for the cross-references.
@cindex Partial documents, formatting
@cindex Chapters, formatting one at a time
@cindex Auxiliary files, omitting
-@cindex Pointer validation, suppressing
+@cindex Pointer validation @subentry suppressing
@findex novalidate
Sometimes you may wish to print a document while you know it is
@@ -15248,7 +14664,7 @@ Thus, the beginning of your file would look approximately like this:
@noindent @code{@@novalidate} also turns off validation in
@code{makeinfo}, just like its @code{--no-validate} option
-(@pxref{Pointer Validation}).
+(@pxref{Invoking @command{texi2any}}).
Furthermore, you need not run @code{texindex} each time after you run
@code{tex}. The @code{tex} formatting command simply uses whatever
@@ -15317,7 +14733,7 @@ lpr texinfo.ps
@end group
@end example
-Depending on the @code{lpr} setup on your machine, you might able to
+Depending on the @code{lpr} setup on your machine, you might be able to
combine the last two steps into @code{lpr -d texinfo.dvi}.
@cindex PCL file, for printing
@@ -15597,14 +15013,14 @@ Also, you should install @file{epsf.tex}, if it is not already installed
from another distribution. More details are at the end of the description
of the @code{@@image} command (@pxref{Images}).
-@cindex European Computer Modern fonts, installing
+@cindex European Computer Modern fonts @subentry installing
@cindex EC fonts, installing
-@cindex CM-Super fonts, installing
+@cindex CM-Super fonts @subentry installing
To use quotation marks other than those used in English, you'll need
to have the European Computer Modern fonts (e.g., @file{ecrm1000}) and
(for PDF output) CM-Super fonts (@pxref{Inserting Quotation Marks}).
-@pindex feymr10@r{, installing}
+@cindex @code{feymr10} @subentry installing
@cindex Euro font, installing
To use the @code{@@euro} command, you'll need the @samp{feym*} fonts
(e.g., @file{feymr10}). @xref{@code{@@euro}}.
@@ -15646,17 +15062,6 @@ hypothetical user @samp{me}'s @file{mylib} directory, and finally in
the system directories. (A leading, trailing, or doubled @samp{:}
indicates searching the system directories at that point.)
-On MS-DOS/MS-Windows, you'd do this like this (note the use of the @samp{;}
-character as directory separator, instead of @samp{:}):
-
-@example
-set TEXINPUTS=.;d:/home/me/mylib;c:
-@end example
-
-@noindent
-It is customary for DOS/Windows users to put such commands in the
-@file{autoexec.bat} file, or in the Windows registry.
-
@node Overfull hboxes
@section Overfull ``hboxes''
@@ -15727,162 +15132,6 @@ before the @code{@@titlepage} command:
@end example
-@node @code{@@smallbook}
-@section @code{@@smallbook}: Printing ``Small'' Books
-
-@anchor{smallbook}@c old name
-@findex smallbook
-@cindex Small book size
-@cindex Book, printing small
-@cindex Page sizes for books
-@cindex Size of printed book
-
-By default, @TeX{} typesets pages for printing in an 8.5 by 11 inch
-format. However, you can direct @TeX{} to typeset a document in a 7 by
-9.25 inch format that is suitable for bound books by inserting the
-following command on a line by itself at the beginning of the Texinfo
-file, before the title page:
-
-@example
-@@smallbook
-@end example
-
-@noindent
-(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}).
-
-@xref{@code{@@small@dots{}}}, for information about commands that make
-it easier to produce examples for a smaller manual.
-
-@xref{Format with @command{texi2dvi}}, and @ref{Preparing for @TeX{}},
-for other ways to format with @code{@@smallbook} that do not require
-changing the source file.
-
-
-@node A4 Paper
-@section Printing on A4 Paper
-@cindex A4 paper, printing on
-@cindex A5 paper, printing on
-@cindex Paper size, A4
-@cindex European A4 paper
-@findex afourpaper
-@findex afivepaper
-
-You can tell @TeX{} to format a document for printing on European size
-A4 paper (or A5) with the @code{@@afourpaper} (or @code{@@afivepaper})
-command. Write the command on a 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
-\input texinfo @@c -*-texinfo-*-
-@@c %**start of header
-@@settitle Texinfo
-@@afourpaper
-@@c %**end of header
-@end group
-@end example
-
-@xref{Format with @command{texi2dvi}}, and @ref{Preparing for @TeX{}},
-for other ways to format for different paper sizes that do not require
-changing the source file.
-
-@findex afourlatex
-@findex afourwide
-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 @code{@@pagesizes}
-@section @code{@@pagesizes} [@var{width}][, @var{height}]: Custom Page Sizes
-@anchor{pagesizes}@c old node name
-
-@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}.
-
-@xref{Format with @command{texi2dvi}}, and @ref{Preparing for @TeX{}},
-for other ways to specify @code{@@pagesizes} that do not require
-changing the source file.
-
-
-@node Magnification
-@section Magnification
-@anchor{Cropmarks and Magnification} @c old name
-
-@findex \mag @r{(raw @TeX{} magnification)}
-@cindex Magnified printing
-@cindex Larger or smaller pages
-You can attempt to direct @TeX{} to typeset pages larger or smaller
-than usual with the @code{\mag} @TeX{} command. Everything that is
-typeset is scaled proportionally larger or smaller. (@code{\mag}
-stands for ``magnification''.) This is @emph{not} a Texinfo
-@@-command, but is a raw @TeX{} command that is prefixed with a
-backslash. You have to write this command between @code{@@tex} and
-@code{@@end tex} (@pxref{Raw Formatter Commands}).
-
-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:
-
-@example
-@group
-@@tex
-\global\mag=1200
-@@end tex
-@end group
-@end example
-
-With some printing technologies, you can print normal-sized copies that
-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, DVI files prepared with a
-nonstandard-@code{\mag} may not print or may print only with certain
-magnifications. Be prepared to experiment.
-
-
@node PDF Output
@section PDF Output
@cindex PDF output
@@ -15930,20 +15179,6 @@ self-contained file, notably including all the fonts that are used, so
it has its place.
-@node Obtaining @TeX{}
-@section Obtaining @TeX{}
-@cindex Obtaining @TeX{}
-@cindex @TeX{}, how to obtain
-
-@TeX{} is a document formatter that is used by the FSF for its
-documentation. It is the easiest way to get printed output (e.g., PDF
-and PostScript) for Texinfo manuals. TeX is freely redistributable,
-and you can get it over the Internet or on physical media. See
-@url{http://tug.org/texlive}.
-
-@c please keep that text in sync with www.gnu.org/prep/FTP
-
-
@node Generic Translator @command{texi2any}
@chapter @command{texi2any}: The Generic Translator for Texinfo
@@ -15958,7 +15193,7 @@ supports these formats:
@item plain text (with @option{--plaintext}),
-@item Docbook (with @option{--docbook}),
+@item DocBook (with @option{--docbook}),
@item Texinfo XML (with @option{--xml}).
@end table
@@ -15975,14 +15210,10 @@ Initialization files are written in Perl, like the main program, and
anything which can be specified on the command line can also be
specified within a initialization file.
-The rest of this chapter goes into the details.
-
@menu
-* Reference Implementation:: @command{texi2any}: the reference implementation.
* Invoking @command{texi2any}:: Running the translator from a shell.
* @command{texi2any} Environment Variables::
* @command{texi2any} Printed Output:: Calling @command{texi2dvi}.
-* Pointer Validation:: How to check that pointers point somewhere.
* Customization Variables:: Configuring @command{texi2any}.
* Internationalization of Document Strings:: Translating program-inserted text.
* Invoking @command{pod2texi}:: Translating Perl pod to Texinfo.
@@ -15990,62 +15221,6 @@ The rest of this chapter goes into the details.
@end menu
-@node Reference Implementation
-@section @command{texi2any}: A Texinfo Reference Implementation
-
-@cindex @command{texi2any}, as reference implementation
-@cindex Reference implementation
-@cindex Implementation, @command{texi2any} as reference
-
-Above, we called @command{texi2any} ``the'' translator for Texinfo
-instead of just ``a'' translator, even though (of course) it's
-technically and legally possible for other implementations to be
-written. The reason is that alternative implementations are very
-likely to have subtle, or not-so-subtle, differences in behavior, and
-thus Texinfo documents would become dependent on the processor.
-Therefore, it is important to have a reference implementation that
-defines parts of the language not fully specified by the manual (often
-intentionally so). It is equally important to have consistent
-command-line options and other behavior for all processors.
-
-@cindex Tree representation of documents
-@cindex Syntax tree representation of documents
-@cindex Abstract syntax tree representation of documents
-For this reason, the once-independent @command{texi2html} Perl Texinfo
-processor was made compatible with the C implementation of
-@command{makeinfo}, to avoid continuing with two different
-implementations (@pxref{History}). The current implementation,
-@command{texi2any}, serves as the reference implementation. It
-inherited the design of customization and other features from
-@command{texi2html} (for more on @command{texi2html} compatibility,
-@pxref{@command{texi2html}}). However, @code{texi2any} is a full
-reimplementation: it constructs a tree-based representation of the
-input document for all back-ends to work from.
-
-@cindex Texinfo language tests
-@cindex Tests, of Texinfo language
-Extensive tests of the language were developed at the same time as
-@command{texi2any}; we plead with anyone thinking of writing a program
-to parse Texinfo input to at least make use of these tests.
-
-@cindex Examples of using @command{texi2any}
-@findex Texinfo::Parser module
-The @command{texi2html} wrapper script (@pxref{@command{texi2html}})
-provides a very simple example of calling @command{texi2any} from a
-shell script; it's in @file{util/texi2html} in the Texinfo sources.
-More consequentially, @command{texi-elements-by-size} is an example
-Perl script using the @code{Texinfo::Parser} module interface; it's
-also in the @file{util} source directory. (Its functionality may also
-be useful to authors; @pxref{texi-elements-by-size}.)
-
-@cindex Future of Texinfo implementations
-With the release of @command{texi2any} as the reference
-implementation, development of both the C implementation of
-@command{makeinfo} and @command{texi2html} has been halted. Going
-forward, we ask authors of Texinfo documents to use only
-@command{texi2any}.
-
-
@node Invoking @command{texi2any}
@section Invoking @command{texi2any}/@command{makeinfo} from a Shell
@@ -16110,11 +15285,11 @@ This option now does nothing, but remains for compatibility. (It used
to ensure that @@-commands in node names were expanded throughout the
document, especially @code{@@value}. This is now done by default.)
-@item --conf-dir=@var{path}
-@opindex --conf-dir=@var{path}
-Prepend @var{path} to the directory search list for finding
+@item --conf-dir=@var{dir}
+@opindex --conf-dir=@var{dir}
+Prepend @var{dir} to the directory search list for finding
customization files that may be loaded with @option{--init-file} (see
-below). The @var{path} value can be a single directory, or a list of
+below). The @var{dir} value can be a single directory, or a list of
several directories separated by the usual path separator character
(@samp{:} on Unix-like systems, @samp{;} on Windows). @c @xref{Loading
@c Init Files}.
@@ -16148,6 +15323,7 @@ someval'} is equivalent to @code{@@set myvar someval}.
@itemx --enable-encoding
@opindex --disable-encoding
@opindex --enable-encoding
+@vindex ENABLE_ENCODING
By default, or with @option{--enable-encoding}, output accented and
special characters in Info and plain text output based on
@samp{@@documentencoding}. With @option{--disable-encoding}, 7-bit
@@ -16156,7 +15332,7 @@ and @ref{Inserting Accents}.
@item --docbook
@opindex --docbook
-Generate Docbook output (rather than Info).
+Generate DocBook output (rather than Info).
@item --document-language=@var{lang}
@opindex --document-language
@@ -16179,13 +15355,15 @@ Info (@pxref{@command{texi2any} Printed Output}).
@itemx -e @var{limit}
@opindex --error-limit=@var{limit}
@opindex -e @var{limit}
-Report @var{LIMIT} errors before aborting (on the assumption that
+@vindex ERROR_LIMIT
+Report @var{limit} errors before aborting (on the assumption that
continuing would be useless); default 100.
@item --fill-column=@var{width}
@itemx -f @var{width}
@opindex --fill-column=@var{width}
@opindex -f @var{width}
+@vindex FILLCOLUMN
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
@@ -16197,6 +15375,7 @@ default value is 72.
@itemx -s @var{style}
@opindex --footnote-style=@var{style}
@opindex -s @var{style}
+@vindex footnotestyle
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
@@ -16217,6 +15396,7 @@ separate file.
@itemx -F
@opindex --force
@opindex -F
+@vindex FORCE
Ordinarily, if the input file has errors, the output files are not
created. With this option, they are preserved.
@@ -16234,12 +15414,12 @@ is split into one output file per Texinfo source node, and the split
output is written into a subdirectory based on the name of the
top-level Info file. @xref{Generating HTML}.
-@item -I @var{path}
-@opindex -I @var{path}
-Append @var{path} to the directory search list for finding files that
+@item -I @var{dir}
+@opindex -I @var{dir}
+Append @var{dir} to the directory search list for finding files that
are included using the @code{@@include} command. By default,
-@code{texi2any} searches only the current directory. If @var{path} is
-not given, the current directory is appended. The @var{path} value
+@code{texi2any} searches only the current directory. If @var{dir} is
+not given, the current directory is appended. The @var{dir} value
can be a single directory or a list of several directories separated
by the usual path separator character (@samp{:} on Unix-like systems,
@samp{;} on Windows).
@@ -16284,6 +15464,7 @@ of directories in which these customization files are searched for.
@item --internal-links=@var{file}
@opindex --internal-links=@var{file}
@cindex Internal links, of HTML
+@vindex INTERNAL_LINKS
In HTML mode, output a tab-separated file containing three columns:
the internal link to an indexed item or item in the table of contents,
the name of the index (or table of contents) in which it occurs, and
@@ -16295,6 +15476,7 @@ post-processors.
@itemx -E @var{file}
@opindex --macro-expand=@var{file}
@opindex -E @var{file}
+@vindex MACRO_EXPAND
Output the Texinfo source, with all Texinfo macros expanded, to
@var{file}. Normally, the result of macro expansion is used
internally by @code{makeinfo} and then discarded.
@@ -16304,6 +15486,7 @@ internally by @code{makeinfo} and then discarded.
@cindex Node separators, omitting with @option{--no-headers}
@cindex Generating plain text files with @option{--no-headers}
@cindex Menus, omitting with @option{--no-headers}
+@vindex HEADERS
Do not include menus or node separator lines in the output.
When generating Info, this is the same as using @option{--plaintext},
@@ -16341,6 +15524,7 @@ blocks will be.
@itemx --node-files
@opindex --no-node-files
@opindex --node-files
+@vindex NODE_FILES
When generating HTML, create redirection files for anchors and any
nodes not already output with the file name corresponding to the node
name (@pxref{HTML Xref Node Name Expansion}). This makes it possible
@@ -16355,7 +15539,9 @@ in any case. This option has no effect with any output format other
than HTML@. @xref{Generating HTML}.
@item --no-number-footnotes
+@itemx --number-footnotes
@opindex --no-number-footnotes
+@vindex NUMBER_FOOTNOTES
Suppress automatic footnote numbering. By default, footnotes are
numbered sequentially within a node, i.e., the current footnote number
is reset to 1 at the start of each node.
@@ -16364,30 +15550,64 @@ is reset to 1 at the start of each node.
@itemx --number-sections
@opindex --no-number-sections
@opindex --number-sections
+@vindex NUMBER_SECTIONS
With @option{--number_sections} (the default), output chapter,
section, and appendix numbers as in printed manuals. This works only
-with hierarchically-structured manuals. You should specify
+with hierarchically structured manuals. You should specify
@code{--no-number-sections} if your manual is not normally structured.
-@item --no-pointer-validate
-@itemx --no-validate
-@opindex --no-pointer-validate
+@item --no-validate
+@itemx --no-pointer-validate
@opindex --no-validate
-@cindex Pointer validation, suppressing from command line
+@opindex --no-pointer-validate
+@cindex Pointer validation
+@anchor{Pointer Validation}@c
Suppress the pointer-validation phase of @code{makeinfo}---a dangerous
thing to do. This can also be done with the @code{@@novalidate}
-command (@pxref{Use @TeX{}}). Normally, consistency checks are made
-to ensure that cross-references can be resolved, etc. @xref{Pointer
-Validation}.
+command (@pxref{Formatting Partial Documents}).
+
+If you do not suppress pointer validation, @code{makeinfo} will check the
+validity of cross-references and menu entries in the Texinfo file, as
+well as node pointers if they are given explicitly.
+
+@ignore @c TODO this may not be accurate
+If node pointers are implicitly determined, @code{makeinfo} checks
+that the tree constructed from the document's menus matches the
+tree constructed from the sectioning commands. For example, if a
+chapter-level menu mentions nodes @var{n1} and @var{n2}, in that order,
+nodes @var{n1} and @var{n2} must be associated with @code{@@section}
+commands in the chapter.
+
+If node pointers are explicitly determined, here is the list of what
+is checked:
+
+@enumerate
+@item
+If a `Next', `Previous', or `Up' node reference is a reference to a
+node in the current file and is not an external reference such as to
+@file{(dir)}, then the referenced node must exist.
+
+@item
+Every node except the `Top' node must have an `Up' pointer.
+
+@item
+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 @samp{(@var{file})}.
+@end enumerate
+@end ignore
@item --no-warn
@opindex --no-warn
+@vindex NO_WARN
Suppress warning messages (but not error messages).
@item --output=@var{file}
@itemx -o @var{file}
@opindex --output=@var{file}
@opindex -o @var{file}
+@vindex OUTFILE
+@vindex SUBDIR
Specify that the output should be directed to @var{file}. This
overrides any file name specified in a @code{@@setfilename} command
found in the Texinfo source. If neither @code{@@setfilename} nor this
@@ -16412,7 +15632,7 @@ name for the directory into which all files are written. For example,
@item --output-indent=@var{val}
@opindex --outputindent
This option now does nothing, but remains for compatibility. (It used
-to alter indentation in XML/Docbook output.)
+to alter indentation in XML/DocBook output.)
@item -P @var{path}
@opindex -P @var{path}
@@ -16496,6 +15716,7 @@ smaller subfiles, of approximately 300k bytes. When generating HTML,
by default each output file contains one node (@pxref{Generating
HTML}). @option{--no-split} suppresses this splitting of the output.
+@vindex SPLIT
Alternatively, @option{--split=@var{how}} may be used to specify at
which level the HTML output should be split. The possible values for
@var{how} are:
@@ -16518,12 +15739,14 @@ available as separate files.
@item --split-size=@var{num}
@opindex --split-size=@var{num}
+@vindex SPLIT_SIZE
Keep Info files to at most @var{num} characters if possible; default
is 300,000. (However, a single node will never be split across Info
files.)
@item --transliterate-file-names
@opindex --transliterate-file-names
+@vindex TRANSLITERATE_FILE_NAMES
Enable transliteration of 8-bit characters in node names for the
purpose of file name creation. @xref{HTML Xref 8-bit Character Expansion}.
@@ -16533,6 +15756,7 @@ Cause @var{var} to be undefined. This is equivalent to @code{@@clear
@item --verbose
@opindex --verbose
+@vindex VERBOSE
Cause @code{makeinfo} to display messages saying what it is doing.
Normally, @code{makeinfo} only outputs messages if there are errors or
warnings.
@@ -16579,7 +15803,7 @@ option. @xref{Customization Variables and Options}.
You can control @command{texi2any}'s use of Perl extension modules
by setting the @env{TEXINFO_XS} environment variable. These modules
are compiled native code that the interpreted Perl code can use.
-Ideally, these extension modules should just work, and the only noticable
+Ideally, these extension modules should just work, and the only noticeable
difference they should make is that @command{texi2any} finishes running
sooner. However, you can use this environment variable for the purposes
of troubleshooting: for example, if you have problems with the output of
@@ -16607,18 +15831,12 @@ Do not use extension modules.
@end table
@vindex TEXINFO_XS_PARSER
-Set @env{TEXINFO_XS_PARSER} to @samp{1} to enable the use of the native
-code implementation of the parser module. This is the part of
-@command{texi2any} that converts Texinfo input into an internal tree
-format used for further processing into output formats. This is not
-enabled by default due to the greater complexity of this module compared
-with the other modules that have a native code implementation, and the
-lack of confidence we have that the native code implementation matches
-the Perl code in all significant aspects. Despite the lack of maturity
-of this module in terms of development and testing, it may be useful for
-decreasing @command{texi2any} run times when working on Texinfo
-documentation files. Note that some error and warning messages will not
-be translated from English if this module is used.
+Set @env{TEXINFO_XS_PARSER} to @samp{0} to disable the use of the
+native code implementation of the parser module. This is the part of
+@command{texi2any} that converts Texinfo input into an internal tree
+format used for further processing into output formats. This may
+be useful for working around bugs or incompatibilities between the
+native code implementation and the implementation in pure Perl code.
@node @command{texi2any} Printed Output
@@ -16677,50 +15895,6 @@ Variables}). As you might guess, the default is @samp{texi2dvi}.
invokes @command{texi2dvi}, only diagnostic messages.
-@node Pointer Validation
-@section Pointer Validation
-@cindex Pointer validation with @code{makeinfo}
-@cindex Validation of pointers
-
-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{}}), @code{makeinfo} will check the
-validity of the Texinfo file.
-
-Most validation checks are different depending on whether node
-pointers are explicitly or implicitly determined. With explicit node
-pointers, here is the list of what is checked:
-
-@enumerate
-@item
-If a `Next', `Previous', or `Up' node reference is a reference to a
-node in the current file and is not an external reference such as to
-@file{(dir)}, then the referenced node must exist.
-
-@item
-Every node except the `Top' node must have an `Up' pointer.
-
-@item
-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 @samp{(@var{file})}.
-@end enumerate
-
-With implicit node pointers, the above error cannot occur, as such.
-(Which is a major reason why we recommend using this feature of
-@code{makeinfo}, and not specifying any node pointers yourself.)
-
-Instead, @code{makeinfo} checks that the tree constructed from the
-document's menus matches the tree constructed from the sectioning
-commands. For example, if a chapter-level menu mentions nodes
-@var{n1} and @var{n2}, in that order, nodes @var{n1} and @var{n2} must
-be associated with @code{@@section} commands in the chapter.
-
-Finally, with both explicit and implicit node pointers,
-@code{makeinfo} checks that every node except the `Top' node is
-referenced in a menu.
-
-
@node Customization Variables
@section Customization Variables
@@ -16765,6 +15939,7 @@ The sections below give the details for each of these.
* Commands: Customization Variables for @@-Commands.
* Options: Customization Variables and Options.
* HTML: HTML Customization Variables.
+* MathJax: MathJax Customization Variables.
* latex2html: @command{latex2html} Customization Variables.
* Other: Other Customization Variables.
@end menu
@@ -16774,35 +15949,19 @@ The sections below give the details for each of these.
@subsection Customization Variables for @@-Commands
@cindex Customization variables for @@-commands
-@cindex @@-commands, customization variables for
+@cindex @sortas{at} @@-commands @subentry customization variables for
Each of the following @@-commands has an associated customization
variable with the same name (minus the leading @code{@@}):
-@smallexample
-@@allowcodebreaks @@clickstyle
-@@codequotebacktick @@codequoteundirected
-@@contents @@deftypefnnewline
-@@documentdescription @@documentencoding @@documentlanguage
-@@exampleindent @@firstparagraphindent
-@@footnotestyle @@frenchspacing
-@@kbdinputstyle @@novalidate
-@@paragraphindent @@setfilename
-@@shortcontents @@urefbreakstyle
-@@validatemenus @@xrefautomaticsectiontitle
-@end smallexample
-
-@c Relevant to TeX only.
-@c @@evenfooting @@evenfootingmarks
-@c @@evenheading @@evenheadingmarks
-@c @@everyfooting @@everyfootingmarks
-@c @@everyheading @@everyheadingmarks
-@c @@fonttextsize
-@c @@headings
-@c @@oddfooting @@oddfootingmarks
-@c @@oddheading @@oddheadingmarks
-@c @@pagesizes
-@c @@setchapternewpage
+@example
+@@allowcodebreaks @@clickstyle @@codequotebacktick
+@@codequoteundirected @@deftypefnnewline @@documentdescription
+@@documentencoding @@documentlanguage @@exampleindent
+@@firstparagraphindent @@footnotestyle @@frenchspacing
+@@kbdinputstyle @@novalidate @@paragraphindent
+@@setfilename @@urefbreakstyle @@xrefautomaticsectiontitle
+@end example
Setting such a customization variable to a value @samp{foo} is similar
to executing @code{@@@var{cmd} foo}. It is not exactly the same,
@@ -16829,66 +15988,48 @@ meaning of the options.
@multitable @columnfractions 0.5 0.5
@headitem Option @tab Variable
@item
-@vindex ENABLE_ENCODING
@option{--enable-encoding} @tab @code{ENABLE_ENCODING}
@item
@option{--document-language} @tab @code{documentlanguage}
@item
-@vindex ERROR_LIMIT
@option{--error-limit} @tab @code{ERROR_LIMIT}
@item
-@vindex FILLCOLUMN
@option{--fill-column} @tab @code{FILLCOLUMN}
-@vindex footnotestyle
@item
@option{--footnote-style} @tab @code{footnotestyle}
@item
-@vindex FORCE
@option{--force} @tab @code{FORCE}
-@vindex INTERNAL_LINKS
@item
@option{--internal-links} @tab @code{INTERNAL_LINKS}
@item
-@vindex MACRO_EXPAND
@option{--macro-expand} @tab @code{MACRO_EXPAND}
@item
-@option{--headers} @tab @code{HEADERS}, @code{SHOW_MENU}
+@option{--headers} @tab @code{HEADERS}, @code{FORMAT_MENU}
@item
-@vindex NO_WARN
@option{--no-warn} @tab @code{NO_WARN}
@item
@vindex novalidate
@option{--no-validate} @tab @code{novalidate}
@item
-@vindex NUMBER_FOOTNOTES
@option{--number-footnotes} @tab @code{NUMBER_FOOTNOTES}
@item
-@vindex NUMBER_SECTIONS
@option{--number-sections} @tab @code{NUMBER_SECTIONS}
@item
-@vindex NODE_FILES
@option{--node-files} @tab @code{NODE_FILES}
@item
-@vindex OUTFILE
-@vindex SUBDIR
@option{--output} @tab @code{OUTFILE}, @code{SUBDIR}
@item
@vindex paragraphindent
@option{--paragraph-indent} @tab @code{paragraphindent}
@item
-@vindex SILENT
@option{--silent} @tab @code{SILENT}
@item
-@vindex SPLIT
@option{--split} @tab @code{SPLIT}
@item
-@vindex SPLIT_SIZE
@option{--split-size} @tab @code{SPLIT_SIZE}
@item
-@vindex TRANSLITERATE_FILE_NAMES
@option{--transliterate-file-names} @tab @code{TRANSLITERATE_FILE_NAMES}
@item
-@vindex VERBOSE
@option{--verbose} @tab @code{VERBOSE}
@end multitable
@@ -16967,7 +16108,7 @@ exec texi2any -c TEXINPUT_OUTPUT_FORMAT=textcontent "$@@"
@subsection HTML Customization Variables
This table gives the customization variables which apply to HTML
-output only. A few other customization variable apply to both HTML
+output only. A few other customization variables apply to both HTML
and other output formats; see @ref{Other Customization Variables}.
@vtable @code
@@ -16994,9 +16135,8 @@ In general, you should set @code{BEFORE_OVERVIEW} if
@code{AFTER_OVERVIEW} is set, and you should set
@code{BEFORE_TOC_LINES} if @code{AFTER_TOC_LINES} is set.
-
@item BASEFILENAME_LENGTH
-The maximum length of the base filenames; default 245.
+The maximum length of a base file name; default 245.
Changing this would make cross-manual references to such long node
names invalid (@pxref{HTML Xref Link Basics}).
@@ -17041,6 +16181,22 @@ cross-references (@pxref{Four and Five Arguments}) are present in
If set, use tables for indentation of complex formats; default
false.
+@item CONTENTS_OUTPUT_LOCATION
+If set to @samp{after_top}, output the contents at the end of the @code{@@top}
+section. If set to @samp{inline}, output the contents where the
+@code{@@contents} and similar @@-commands are located. If set to
+@samp{separate_element} output the contents in separate elements, either at the
+end of the document if not split, or in a separate file. If set to
+@samp{after_title} the tables of contents are output after the title; default
+@samp{after_top}.
+
+@item COPIABLE_ANCHORS
+If set, output copiable anchors for the definition commands
+(@pxref{Definition Commands}) and table commands (@pxref{Two-column
+Tables}) where an index entry is defined. An anchor appears as a `@U{00B6}'
+@c pilcrow sign
+sign that appears when you hover the mouse pointer over the heading text.
+
@item CSS_LINES
CSS output, automatically determined by default (@pxref{HTML CSS}).
@@ -17092,6 +16248,13 @@ description.
Use tables for header formatting rather than a simple
@code{<div>} element; default false.
+@item HTML_MATH
+Method to use to render @code{@@math}. This can be unset, set to
+@samp{mathjax} (@pxref{MathJax Customization Variables}),
+set to @samp{l2h}, which has the same effect as setting @code{L2H}
+(@pxref{@command{latex2html} Customization Variables}), or set to
+@samp{t2h}, which uses @command{tex4ht}.
+
@item ICONS
Use icons for the navigation panel; default false.
@@ -17099,15 +16262,50 @@ Use icons for the navigation panel; default false.
If set, the associated value is prepended to the image file
links; default unset.
-@item INLINE_CONTENTS
-If set, output the contents where the @code{@@contents} and
-similar @@-commands are located; default true. This is ignored if
-@code{@@set*contentsaftertitlepage} is set (@pxref{Contents}).
+@item INDEX_ENTRY_COLON
+Symbol used between the index entry and the associated node or section;
+default @samp{:}.
+
+@item INFO_JS_DIR
+(Experimental.) Add a JavaScript browsing interface to the manual.
+The value of the variable is the directory to place the code for this
+interface, so you would run the program as e.g.@: @samp{texi2any --html
+-c INFO_JS_DIR=js @var{manual}.texi} to place files in a @samp{js}
+directory under the output. This provides some of the functionality
+of the Info browsers in a web browser, such as keyboard navigation
+and index lookup. This only works with non-split HTML output.
+
+The interface should provide an acceptable fallback in functionality
+if JavaScript or web browser features are not available. However,
+please be cautious when using this option, in case you do make your
+documentation harder to access for some of your users.
@item INLINE_CSS_STYLE
Put CSS directly in HTML elements rather than at the
beginning of the output; default false.
+@item JS_WEBLABELS
+@itemx JS_WEBLABELS_FILE
+Specify how to use a @dfn{JavaScript license web labels} page to
+give licensing information and source code for any JavaScript used
+in the HTML files for the manual.
+(See @uref{https://www.gnu.org/licenses/javascript-labels.html}).
+
+With the value @samp{generate} (the default), generate a labels page
+at @code{JS_WEBLABELS_FILE}, and link to it in the HTML output files.
+Only do this if actually referencing JavaScript files (either with
+@code{HTML_MATH} set to @samp{mathjax}, or when using the experimental
+JS browsing interface when @code{INFO_JS_DIR} is set). With this
+setting, @code{JS_WEBLABELS_FILE} must be a relative file name.
+
+With the value @samp{reference}, link to the labels
+file given by @code{JS_WEBLABELS_FILE} in the output, and do not
+generate a labels file. This setting is useful if you separately
+maintain a single labels file for a larger website that includes
+your manual.
+
+With @samp{omit}, neither generate nor link to a labels file.
+
@item KEEP_TOP_EXTERNAL_REF
If set, do not ignore @samp{Top} as the first
argument for an external ref to a manual, as is done by default.
@@ -17118,6 +16316,10 @@ Maximum header formatting level used (higher header
formatting level numbers correspond to lower sectioning levels);
default @samp{4}.
+@item MENU_ENTRY_COLON
+Symbol used between the menu entry and the description; default
+@samp{:}.
+
@item MENU_SYMBOL
Symbol used in front of menu entries when node names are used
for menu entries formatting; default @samp{&bull;}.
@@ -17176,12 +16378,12 @@ default is @code{index.html}.
A url used for Top node up references; the default is
@code{undef}, in that case no Top node Up reference is generated.
For more about the Top node pointers, @pxref{First Node}. For
-overriding the Up pointer name in cas @code{TOP_NODE_UP_URL} is set
+overriding the Up pointer name in case @code{TOP_NODE_UP_URL} is set
and for other formats, see @code{TOP_NODE_UP} in
@ref{Other Customization Variables}.
@item USE_ACCESSKEY
-@cindex @code{accesskey}, customization variable for
+@cindex @code{accesskey} @subentry customization variable for
Use @code{accesskey} in cross-references; default true.
@item USE_ISO
@@ -17195,6 +16397,15 @@ Use entities for doubled single-quote characters
Generate @code{<link>} elements in the HTML @code{<head>}
output; default true.
+@item USE_NODE_DIRECTIONS
+If true, use nodes to determine where next, up and prev
+link to in node headers. If false, use sections. If undefined, use
+@code{USE_NODES} value. Default is undefined. Note that this setting does not
+determine the link string only where the links points to, see @ref{Three
+Arguments, , xrefautomaticsectiontitle} for the link string customization. If
+nodes and sections are systematically associated, this customization has no
+practical effect.
+
@item USE_REL_REV
Use @code{rel} in cross-references; default true.
@@ -17228,6 +16439,36 @@ otherwise use the node name or section name depending on
@end vtable
+@node MathJax Customization Variables
+@subsection MathJax Customization Variables
+
+This table lists the customization variables which can be used when
+MathJax is being used, which will be the case when @code{HTML_MATH}
+is set to @samp{mathjax}.
+
+@vtable @code
+@item MATHJAX_SCRIPT
+URL of the MathJax component file (e.g.@: @file{tex-svg.js}) you are using.
+@command{texi2any} provides a default value for this variable, but you
+are encouraged to host this file yourself on your website so that you are
+not dependent on others' hosting.
+
+@item MATHJAX_SOURCE
+A URL of the full source code in its preferred form for modification,
+or instructions for obtaining such source code, for the component file
+named by @code{MATHJAX_SCRIPT}. `Preferred form for modification'
+means that this should not be in a `minified' form. Used in the
+license labels page (@pxref{HTML Customization Variables}, under
+@code{JS_WEBLABELS}).
+
+Again, @command{texi2any} provides a default value for this variable,
+but you are encouraged to host the source code for MathJax and its
+dependencies yourself. This is in order to make the source code
+available reliably, and to reduce you and your users' dependence on
+others' distribution systems.
+@end vtable
+
+
@node @command{latex2html} Customization Variables
@subsection @command{latex2html} Customization Variables
@@ -17283,15 +16524,15 @@ multiple formats, or affect global behavior, or otherwise don't fit
into the categories of the previous sections.
@vtable @code
+@item CHECK_NORMAL_MENU_STRUCTURE
+Warn if the nodes pointers (either explicitly or automatically set)
+are not consistent with the order of node menu entries.
+
@item CLOSE_QUOTE_SYMBOL
When a closing quote is needed, use this character; default @code{&rsquo;}
-in HTML, @code{&#8217;} in Docbook. The default for Info is the same
+in HTML, @code{&#8217;} in DocBook. The default for Info is the same
as @code{OPEN_QUOTE_SYMBOL} (see below).
-@c @item COMPLETE_IMAGE_PATHS
-@c If set, the image files are computed to be relative from the document
-@c directory to the source manual directory, and then to the image.
-
@item CPP_LINE_DIRECTIVES
Recognize @code{#line} directives in a ``preprocessing'' pass
(@pxref{External Macro Processors}); on by default.
@@ -17304,10 +16545,10 @@ If set, debugging output is generated; default is off (zero).
@item DOCTYPE
@vindex SystemLiteral
-For Docbook, HTML, XML@. Specifies the @code{SystemLiteral}, the
+For DocBook, HTML, XML@. Specifies the @code{SystemLiteral}, the
entity's system identifier. This is a URI which may be used to
retrieve the entity, and identifies the canonical DTD for the
-document. The default value is different for each of HTML, Docbook
+document. The default value is different for each of HTML, DocBook
and Texinfo@tie{}XML.
@item DUMP_TEXI
@@ -17334,16 +16575,16 @@ Xref Configuration}.
The extension added to the output file name. The default is different
for each output format.
-@c @item IDX_SUMMARY
-@c If set, for each @code{@@printindex} a file named
-@c @file{@var{docname}_@var{idxname}.idx} is created, containing lines of
-@c the form:
-@c
-@c @example
-@c @var{key} @var{reference}
-@c @end example
-@c
-@c @noindent sorted alphabetically (case matters).
+@item FORMAT_MENU
+@opindex --no-headers
+If set to @samp{menu}, output Texinfo menus. This is the default for
+Info. @samp{sectiontoc} is the default setting for HTML, where instead
+of the contents of @code{@@menu} blocks being output, a list of subordinate
+sections is output in each node. If set to @samp{nomenu}, do not output
+menus.
+
+This variable is set to @samp{nomenu} when generating DocBook, or when
+@option{--no-headers} is specified.
@item IGNORE_BEFORE_SETFILENAME
If set, begin outputting at @code{@@setfilename}, if
@@ -17353,10 +16594,6 @@ If set, begin outputting at @code{@@setfilename}, if
If set, spaces are ignored after an @@-command that takes braces.
Default true, matching the @TeX{} behavior.
-@item INDEX_ENTRY_COLON
-Symbol used between the index entry and the associated node or section;
-default @samp{:}.
-
@item INDEX_SPECIAL_CHARS_WARNING
If set, warn about @samp{:} in index entry, as it leads to invalid entries in
index menus in output Info files. For Info and plaintext only.
@@ -17380,10 +16617,6 @@ The maximal number of recursive calls of @@-commands defined through
@code{@@rmacro}; default 100000. The purpose of this variable is to
avoid infinite recursions.
-@item MENU_ENTRY_COLON
-Symbol used between the menu entry and the description; default
-empty.
-
@item NO_USE_SETFILENAME
If set, do not use @code{@@setfilename} to set the document name;
instead, base the output document name only on the input file name.
@@ -17400,7 +16633,7 @@ default true.
@item OPEN_QUOTE_SYMBOL
When an opening quote is needed, e.g., for @samp{@@samp} output, use
the specified character; default @code{&lsquo;} for HTML,
-@code{&#8216;} for Docbook. For Info, the default depends on the
+@code{&#8216;} for DocBook. For Info, the default depends on the
enabled document encoding (@pxref{@code{@@documentencoding}}); if no
document encoding is set, or the encoding is US-ASCII, etc., @samp{'}
is used. This character usually appears as an undirected single quote
@@ -17442,12 +16675,6 @@ as whether the output is split. The default is unset.
Name of the program used. By default, it is set to the name of the
program launched, with a trailing @samp{.pl} removed.
-@item SHOW_MENU
-@vindex HEADERS
-@opindex --no-headers
-If set, Texinfo menus are output. By default, it is set unless
-generating Docbook or if @option{--no-headers} is specified.
-
@item SORT_ELEMENT_COUNT
@pindex texi-elements-by-size
@cindex Longest nodes, finding
@@ -17463,12 +16690,6 @@ the @file{util/} directory of the Texinfo source distribution
When dumping the elements-by-size file (see preceding item), use word
counts instead of line counts; default false.
-@c @item SPLIT_INDEX
-@c For HTML@. If set, the output is split, and the output from
-@c @code{@@printindex} happens in a sectioning element at the level of
-@c splitting, then split index pages at the next letter after they have
-@c more than that many entries. If set to 0, no index splitting.
-
@item TEST
If set to true, some variables which are normally dynamically
generated anew for each run (date, program name, version) are set to
@@ -17507,21 +16728,21 @@ more than one is specified, the ordering is irrelevant; each is always
applied at the necessary point during processing.
The only one executed by default is
-@samp{move_index_entries_after_items} for HTML and Docbook output.
+@samp{move_index_entries_after_items} for HTML and DocBook output.
Here's an example of updating the master menu in a document:
@example
makeinfo \
-c TREE_TRANSFORMATIONS=regenerate_master_menu \
- -c PLAINTEXINFO=1 \
+ -c TEXINFO_OUTPUT_FORMAT=plaintexinfo \
mydoc.texi \
-o /tmp/out
@end example
-@noindent (Caveat: Since @code{PLAINTEXINFO} output does expand
+@noindent (Caveat: Since @samp{plaintexinfo} output expands
Texinfo macros and conditionals, it's necessary to remove any such
differences before installing the updates in the original document.
-This will be remedied in a future release.)
+This may be remedied in a future release.)
The following transformations are currently supported (many are used
in the @code{pod2texi} utility distributed with Texinfo;
@@ -17532,6 +16753,10 @@ in the @code{pod2texi} utility distributed with Texinfo;
Add menu entries or whole menus for nodes associated with sections of
any level, based on the sectioning tree.
+@item complete_tree_nodes_missing_menu
+Add whole menus for nodes associated with sections without menu. The
+menus are based on the sectioning tree.
+
@item fill_gaps_in_sectioning
Adds empty @code{@@unnumbered...} sections in a tree to fill gaps in
sectioning. For example, an @code{@@unnumberedsec} will be inserted
@@ -17544,7 +16769,7 @@ Insert nodes for sectioning commands lacking a corresponding node.
In @code{@@enumerate} and @code{@@itemize}, move index entries
appearing just before an @code{@@item} to just after the
@code{@@item}. Comment lines between index entries are moved too. As
-mentioned, this is always done for HTML and Docbook output.
+mentioned, this is always done for HTML and DocBook output.
@item regenerate_master_menu
Update the Top node master menu, either replacing the (first)
@@ -17563,10 +16788,6 @@ Preferentially use nodes to decide where elements are separated. If
set to false, preferentially use sectioning to decide where elements
are separated. The default is true.
-@item USE_NODE_TARGET
-If set, use the node associated with a section for the section target
-in cross-references; default true.
-
@item USE_NUMERIC_ENTITY
For HTML and XML@. If set, use numeric entities instead of ASCII
characters when there is no named entity. By default, set to true for
@@ -17720,8 +16941,7 @@ output of @code{pod2texi --help}, the version on the web at
For an example of using @code{pod2texi} to make Texinfo out of the
Perl documentation itself, see
@url{http://svn.savannah.gnu.org/viewvc/trunk/contrib/perldoc-all/?root=texinfo,
-@file{contrib/perldoc-all}} in the Texinfo source distribution (the
-output is available at @url{http://www.gnu.org/software/perl/manual}).
+@file{contrib/perldoc-all}} in the Texinfo source distribution.
@node @command{texi2html}
@@ -17802,9 +17022,8 @@ corresponding @command{texi2any} customization variables.
@item @option{--use-nodes} @tab @code{USE_NODES}
@item @option{--monolithic} @tab @code{MONOLITHIC}
@item @option{--top-file} @tab @code{TOP_FILE}
-@item @option{--toc-file} @tab @code{TOC_FILE}
@item @option{--frames} @tab @code{FRAMES}
-@item @option{--menu} @tab @code{SHOW_MENU}
+@item @option{--menu} @tab @code{FORMAT_MENU}
@item @option{--debug} @tab @code{DEBUG}
@item @option{--doctype} @tab @code{DOCTYPE}
@item @option{--frameset-doctype} @tab @code{FRAMESET_DOCTYPE}
@@ -17828,6 +17047,7 @@ itself.
@menu
* Creating an Info File::
* Installing an Info File::
+* Info Format FAQ::
@end menu
@@ -18137,7 +17357,7 @@ validate the structure of the nodes, see @ref{Using
@node Installing an Info File
@section Installing an Info File
@cindex Installing an Info file
-@cindex Info file installation
+@cindex Info files @subentry installation
@cindex @file{dir} directory for Info installation
Info files are usually kept in the @file{info} directory. You can
@@ -18146,7 +17366,7 @@ built into Emacs. (@xref{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.
@@ -18160,12 +17380,12 @@ Info.)
@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,
+serves as a top-level directory for the Info system. By convention,
this file is called @file{dir}. (You can find the location of this file
within Emacs by typing @kbd{C-h i} to enter Info and then typing
-@kbd{C-x C-f} to see the pathname to the @file{info} directory.)
+@kbd{C-x C-f} to see the location of the @file{info} directory.)
-The @file{dir} file is itself an Info file. It contains the top level
+The @file{dir} file is itself an Info file. It contains the top-level
menu for all the Info files in the system. The menu looks like
this:
@@ -18211,7 +17431,7 @@ true in general, it is a special case for @file{dir}.
@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 a new
+@cindex Info files @subentry listing a new
@cindex @file{dir} file listing
To add a new Info file to your system, you must write a menu entry to
@@ -18250,7 +17470,7 @@ ways to specify its location:
@enumerate
@item
-Write the pathname in the @file{dir} file as the second part of the menu.
+Write the file name in the @file{dir} file as the second part of the menu.
@item
Specify the Info directory name in the @code{INFOPATH} environment
@@ -18290,47 +17510,8 @@ Info where to look by setting the @code{INFOPATH} environment variable
in your shell startup file. This works with both the Emacs and
standalone Info readers.
-Specifically, 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
-In a @file{.cshrc} file, you could set the @code{INFOPATH}
-variable as follows:
-
-@smallexample
-setenv INFOPATH .:~/info:/usr/local/emacs/info
-@end smallexample
-
-@item
-In a @file{.profile} file, you would achieve the same effect by writing:
-
-@smallexample
-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 (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. The standalone Info reader
+Emacs uses the @code{INFOPATH} environment variable to initialize the value of
+Emacs's own @code{Info-directory-list} variable. The standalone 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}.
@@ -18386,25 +17567,25 @@ 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
+@example
@@dircategory Texinfo documentation system
@@direntry
* Texinfo: (texinfo). The GNU documentation format.
* install-info: (texinfo)Invoking install-info. @dots{}
@dots{}
@@end direntry
-@end smallexample
+@end example
Here's what this produces in the Info file:
-@smallexample
+@example
INFO-DIR-SECTION Texinfo documentation system
START-INFO-DIR-ENTRY
* Texinfo: (texinfo). The GNU documentation format.
* install-info: (texinfo)Invoking install-info. @dots{}
@dots{}
END-INFO-DIR-ENTRY
-@end smallexample
+@end example
@noindent
The @code{install-info} program sees these lines in the Info file, and
@@ -18662,7 +17843,7 @@ Otherwise the alternate syntax is used.
@end enumerate
When the heuristic fails because your section title starts with a
-hyphen, or it happens to be a filename that can be opened, the syntax
+hyphen, or it happens to be a file that can be opened, the syntax
should be changed to @samp{--regex=@var{regex} --section=@var{sec}
--add-once}.
@@ -18684,6 +17865,103 @@ Display version information and exit successfully.
@end table
+@node Info Format FAQ
+@section Info Format FAQ
+
+Here are some questions that have been frequently asked on
+the project mailing lists and elsewhere.
+
+@table @asis
+@item Why when I run @samp{info @var{foo}} do I get the same output as @samp{man @var{foo}}?
+
+Check that the Info manuals are installed. Not all GNU/Linux
+distributions install all the Info manuals by default. This is
+regrettable, as often the Info manual provides more information than
+the provided man page.
+
+@item Why not use HTML instead of Info?
+
+Manuals are rarely written in the Info format itself, but are
+generated from Texinfo source by the @command{texi2any} program.
+@command{texi2any} can generate HTML as well as Info from Texinfo
+source. You can also access and download HTML manuals from the GNU
+website (@uref{https://www.gnu.org/manual/manual.html}). Additionally,
+some GNU/Linux distributions provide packages for the installation
+of HTML manuals.
+
+Info still has some advantages over HTML for locally installed
+documentation. The Info browsers support index lookup and support
+for links between locally installed manuals in multiple locations.
+It's important to have documentation installed locally on your machine
+rather than relying on the Internet; this makes accessing documentation
+more reliable, and ensures it matches installed versions of packages.
+It's hoped that support for browsing locally installed Texinfo
+documentation in some form of HTML can be improved in the future.
+
+
+@item Why provide the command-line @command{info} program when it is not very good?
+
+@command{info} has had improvements over time, so perhaps give
+it another go. It can be configured to change the default key
+bindings, as well as change the color of cross-references and search
+results, and to enable mouse scrolling support. You should not
+need to be experienced with the Emacs editor to use @command{info}.
+(Some recommend another program called @command{pinfo}, but this
+lacks in important features like index lookup.)
+
+Some prefer to be able to scroll through the entire manual at once (as
+happens with man pages), rather than being limited to a single `node'
+of content at once. Of course, there is no accounting for taste,
+but a single, unstructured block of text becomes more awkward as a
+manual becomes longer and more complicated. (However, if you really
+want to, you can view an info manual all at once in the @command{less}
+pager with @samp{info @var{foo} | less}.)
+
+@item Why do I have `see' appearing in front of all of my links?
+
+By default, Emacs Info mode either changes the marker @samp{*note} for
+cross-references to `see', or hides it completely. Unfortunately,
+there is no way to do this reliably, as both the @code{@@pxref}
+and @code{@@ref} commands in Texinfo output this marker in the Info
+output, and the `see' text is only appropriate for @code{@@pxref}.
+
+@item Yes, but how do I get a plain link, with no extra markup?
+
+You can't. Info is a plain text format that is displayed mostly as-is
+in the viewers, and without the @samp{*note} text there would be nothing
+to mark text as a link. Additionally, in printed output there is no
+such thing as a plain link, as the page number of the target would have
+to be printed somewhere.
+
+If you really want a plain link in HTML output without affecting other
+output formats, you could create a macro with conditional definitions for
+each output format.
+
+@item Why do lines containing links appear mysteriously short?
+
+This due to Emacs (or @command{info} with @code{hide-note-references}
+set to @samp{On}) hiding @samp{*note} strings, as mentioned above.
+
+@item Can the Info format be extended to support fonts, colors or reflowable text?
+
+Any extension would be incompatible with existing Info-viewing programs.
+Extra markup added to Info files would be displayed to the user, making
+files ugly and unreadable.
+
+When Texinfo files are processed into Info files, information about
+which Texinfo commands were used to markup text is lost. Moreover,
+it is not possible to reliably detect whether text can be reflowed
+(e.g.@: a paragraph of prose), or whether line breaks should be kept
+(e.g.@: a code sample, or poem).
+
+Info's core purpose is to display documentation on text terminals.
+If you want more, you are recommended to use the HTML output from
+@command{texi2any} instead.
+
+@end table
+
+
+
@node Generating HTML
@chapter Generating HTML
@@ -18699,7 +17977,7 @@ other programs. This chapter gives some details on such HTML output.
with which you can influence the HTML output. @xref{Customization
Variables}.
-@command{makeinfo} can also produce output in XML and Docbook formats,
+@command{makeinfo} can also produce output in XML and DocBook formats,
but we do not as yet describe these in detail. @xref{Output Formats},
for a brief overview of all the output formats.
@@ -18708,6 +17986,7 @@ for a brief overview of all the output formats.
* HTML Splitting:: How HTML output is split.
* HTML CSS:: Influencing HTML output with Cascading Style Sheets.
* HTML Xref:: Cross-references in HTML output.
+* @code{@@documentdescription}:: Document summary for the HTML output.
@end menu
@@ -18821,7 +18100,7 @@ per Texinfo source @code{@@node}.
Each output file name is the node name with spaces replaced by
@samp{-}'s and special characters changed to @samp{_} followed by
their code point in hex (@pxref{HTML Xref}). This is to make it
-portable and easy to use as a filename. In the unusual case of two
+portable and easy to use as a file name. In the unusual case of two
different nodes having the same name after this treatment, they are
written consecutively to the same file, with HTML anchors so each can
be referred to independently.
@@ -18885,19 +18164,16 @@ influencing the display of HTML documents: see
By default, @command{makeinfo} includes a few simple CSS commands to
better implement the appearance of some Texinfo environments. Here
-are two of them, as an example:
+is one of them, as an example:
@example
pre.display @{ font-family:inherit @}
-pre.smalldisplay @{ font-family:inherit; font-size:smaller @}
@end example
A full explanation of CSS is (far) beyond this manual; please see the
-reference above. In brief, however, the above tells the web browser
-to use a `smaller' font size for @code{@@smalldisplay} text, and to
-use the same font as the main document for both @code{@@smalldisplay}
-and @code{@@display}. By default, the HTML @samp{<pre>} command uses
-a monospaced font.
+reference above. In brief, however, the above tells the web browser to
+use the same font as the main document for @code{@@display}.
+By default, the HTML @samp{<pre>} command uses a monospaced font.
You can influence the CSS in the HTML output with two
@command{makeinfo} options: @option{--css-include=@var{file}} and
@@ -18953,7 +18229,7 @@ default CSS is included. If you need to override @command{makeinfo}'s
defaults from an @samp{@@import}, you can do so with the @samp{!@:
important} CSS construct, as in:
@example
-pre.smallexample @{ font-size: inherit ! important @}
+pre.example @{ font-size: inherit ! important @}
@end example
@item If @var{file} contains both @samp{@@import} and inline CSS
@@ -19013,7 +18289,7 @@ The algorithm was primarily devised by Patrice Dumas in 2003--04.
@node HTML Xref Link Basics
@subsection HTML Cross-reference Link Basics
-@cindex HTML cross-reference link basics
+@cindex HTML cross-references @subentry link basics
For our purposes, an HTML link consists of four components: a host
name, a directory part, a file part, and a target part. We
@@ -19065,7 +18341,7 @@ the directory is @file{./} (or just the empty string), and the file is
@end itemize
@vindex BASEFILENAME_LENGTH
-Another rule, that only holds for filenames, is that base filenames
+Another rule, that only holds for file names, is that base file names
are truncated to 245 characters, to allow for an extension to be
appended and still comply with the 255-character limit which is common
to many filesystems. Although technically this can be changed with
@@ -19073,7 +18349,7 @@ the @code{BASEFILENAME_LENGTH} customization variable (@pxref{Other
Customization Variables}), doing so would make cross-manual references
to such nodes invalid.
-Any directory part in the filename argument of the source cross
+Any directory part in the file name argument of the source cross
reference command is ignored. Thus, @code{@@xref@{,,,../foo@}} and
@code{@@xref@{,,,foo@}} both use @samp{foo} as the manual name. This
is because any such attempted hardwiring of the directory is very
@@ -19097,13 +18373,13 @@ actually present in. @xref{HTML Xref Mismatch}.
@node HTML Xref Node Name Expansion
@subsection HTML Cross-reference Node Name Expansion
-@cindex HTML cross-reference node name expansion
+@cindex HTML cross-references @subentry node name expansion
@cindex node name expansion, in HTML cross-references
@cindex expansion, of node names in HTML cross-references
As mentioned in the previous section, the key part of the HTML cross
reference algorithm is the conversion of node names in the Texinfo
-source into strings suitable for XHTML identifiers and filenames. The
+source into strings suitable for XHTML identifiers and file names. The
restrictions are similar for each: plain ASCII letters, numbers, and
the @samp{-} and @samp{_} characters are all that can be used.
(Although HTML anchors can contain most characters, XHTML is more
@@ -19185,7 +18461,7 @@ independent of operating system.
@node HTML Xref Command Expansion
@subsection HTML Cross-reference Command Expansion
-@cindex HTML cross-reference command expansion
+@cindex HTML cross-references @subentry command expansion
Node names may contain @@-commands (@pxref{Node Line Requirements}).
This section describes how they are handled.
@@ -19276,7 +18552,7 @@ Any other command is an error, and the result is unspecified.
@node HTML Xref 8-bit Character Expansion
@subsection HTML Cross-reference 8-bit Character Expansion
-@cindex HTML cross-reference 8-bit character expansion
+@cindex HTML cross-references @subentry 8-bit character expansion
@cindex 8-bit characters, in HTML cross-references
@cindex Expansion of 8-bit characters in HTML cross-references
@cindex Transliteration of 8-bit characters in HTML cross-references
@@ -19321,7 +18597,7 @@ the @option{--transliterate-file-names} command line option. This
option enables @dfn{transliteration} of node names into ASCII
characters for the purposes of file name creation and referencing.
The transliteration is based on phonetic principles, which makes the
-generated file names more easily understanable.
+generated file names more easily understandable.
@cindex Normalization Form C, Unicode
For the definition of Unicode Normalization Form@tie{}C, see Unicode
@@ -19332,12 +18608,11 @@ web.
@node HTML Xref Mismatch
@subsection HTML Cross-reference Mismatch
-@cindex HTML cross-reference mismatch
+@cindex HTML cross-references @subentry mismatch
@cindex Mismatched HTML cross-reference source and target
As mentioned earlier (@pxref{HTML Xref Link Basics}), the generating
-software may need to guess whether a given manual being cross
-referenced is available in split or monolithic form---and, inevitably,
+software may need to guess whether a given manual being cross-referenced is available in split or monolithic form---and, inevitably,
it might guess wrong. However, when the @emph{referent} manual is
generated, it is possible to handle at least some mismatches.
@@ -19382,7 +18657,7 @@ control.
@subsection HTML Cross-reference Configuration: @file{htmlxref.cnf}
@pindex htmlxref.cnf
-@cindex HTML cross-reference configuration
+@cindex HTML cross-references @subentry configuration
@cindex Cross-reference configuration, for HTML
@cindex Configuration, for HTML cross-manual references
@@ -19447,14 +18722,14 @@ being one of: @code{mono}, @code{node}, @code{section},
references can occur only in the @var{urlprefix}. For example (used
in the canonical @file{htmlxref.cnf}):
-@smallexample
+@example
G = http://www.gnu.org
GS = $@{G@}/software
hello mono $@{GS@}/hello/manual/hello.html
hello chapter $@{GS@}/hello/manual/html_chapter/
hello section $@{GS@}/hello/manual/html_section/
hello node $@{GS@}/hello/manual/html_node/
-@end smallexample
+@end example
@cindex monolithic manuals, for HTML cross-references
If the keyword is @code{mono}, @var{urlprefix} gives the host,
@@ -19473,12 +18748,12 @@ url will be used, etc. However, if a manual is not available in that
form, anything that is available can be used. Here is the search
order for each style:
-@smallexample
+@example
node @result{} node, section, chapter, mono
section @result{} section, chapter, node, mono
chapter @result{} chapter, section, node, mono
mono @result{} mono, chapter, section, node
-@end smallexample
+@end example
@opindex --node-files@r{, and HTML cross-references}
These section- and chapter-level cross-manual references can succeed
@@ -19490,6 +18765,41 @@ distributed with Texinfo, please email @email{bug-texinfo@@gnu.org} as
usual. You can get the latest version from
@url{http://ftpmirror.gnu.org/@/texinfo/@/htmlxref.cnf}.
+@node @code{@@documentdescription}
+@section @code{@@documentdescription}: Summary Text
+@anchor{documentdescription}@c old name
+
+@cindex Document description
+@cindex Description of document
+@cindex Summary of document
+@cindex Abstract of document
+@cindex @code{<meta>} HTML tag, and document description
+@findex documentdescription
+
+When producing HTML output for a document, @command{makeinfo} writes a
+@samp{<meta>} element in the @samp{<head>} to give some idea of the
+content of the document. By default, this @dfn{description} is the
+title of the document, taken from the @code{@@settitle} command
+(@pxref{@code{@@settitle}}). To change this, use the
+@code{@@documentdescription} environment, as in:
+
+@example
+@@documentdescription
+descriptive text.
+@@end documentdescription
+@end example
+
+@noindent
+This will produce the following output in the @samp{<head>} of the HTML:
+
+@example
+<meta name=description content="descriptive text.">
+@end example
+
+@code{@@documentdescription} must be specified before the first node of
+the document.
+
+
@node @@-Command Details
@appendix @@-Command Details
@@ -19499,7 +18809,7 @@ list of commands, and information about where commands can appear.
@node Command Syntax
@section @@-Command Syntax
-@cindex @@-command syntax
+@cindex @sortas{at} @@-commands @subentry syntax
@cindex Syntax, of @@-commands
@cindex Command syntax
@@ -19539,7 +18849,7 @@ the document; they do not take arguments. Some examples:
@item 5. Non-alphabetic commands
The names of commands in all of the above categories consist of
alphabetic characters, almost entirely in lower-case. Unlike those, the
-non-alphabetic commands commands consist of an @@ followed by a
+non-alphabetic commands consist of an @@ followed by a
punctuation mark or other character that is not part of the Latin
alphabet. Non-alphabetic commands are almost always part of text
within a paragraph. The non-alphabetic commands include @code{@@@@},
@@ -19576,7 +18886,7 @@ filling commands work properly.
@section @@-Command List
@cindex Alphabetical @@-command list
@cindex List of @@-commands
-@cindex @@-command list
+@cindex @sortas{at} @@-commands @subentry list of
@cindex Reference to @@-commands
Here is an alphabetical list of the @@-commands in Texinfo. Square
@@ -19740,6 +19050,9 @@ Set @var{text} in a @b{bold} font. No effect in Info. @xref{Fonts}.
Generate a large round dot, @bullet{} (@samp{*} in Info). Often used
with @code{@@table}. @xref{@code{@@bullet}}.
+@item @@bsixpaper
+Change page dimensions for the B6 paper size. @xref{A4 Paper}.
+
@item @@bye
Stop formatting a file. The formatters do not see anything in the
input file following @code{@@bye}. @xref{Ending a File}.
@@ -19997,13 +19310,16 @@ 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{@code{@@display}}.
+@item @@displaymath
+Format a block of math in ``display'' format. @xref{Inserting Math}.
+
@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{@code{@@dmn}}.
@item @@docbook
-Enter Docbook completely. Pair with @code{@@end docbook}. @xref{Raw
+Enter DocBook completely. Pair with @code{@@end docbook}. @xref{Raw
Formatter Commands}.
@item @@documentdescription
@@ -20275,7 +19591,7 @@ Read the contents of Texinfo source file @var{filename}. @xref{Include Files}.
Insert paragraph indentation. @xref{@code{@@indent}}.
@item @@indentedblock
-Indent a block of arbitary text on the left. Pair with @code{@@end
+Indent a block of arbitrary text on the left. Pair with @code{@@end
indentedblock}. @xref{@code{@@indentedblock}}.
@item @@indicateurl@{@var{indicateurl}@}
@@ -20518,13 +19834,6 @@ Make a plain reference that does not start with any special text.
Follow command with a punctuation mark. Only the first argument is
mandatory. @xref{@code{@@ref}}.
-@item @@refill
-@findex refill
-This command used to refill and indent the paragraph after all the
-other processing has been done. It is no longer needed, since all
-formatters now automatically refill as needed, but you may still see
-it in the source to some manuals, as it does no harm.
-
@item @@registeredsymbol@{@}
Generate the legal symbol @registeredsymbol{}.
@xref{@code{@@registeredsymbol}}.
@@ -20592,35 +19901,35 @@ in Info. @xref{Fonts}.
@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{@code{@@smallbook}}. Also, see @ref{@code{@@small@dots{}}}.
+@xref{@code{@@smallbook}}. Also, see @ref{small}.
@item @@smalldisplay
Begin a kind of example. Like @code{@@display}, but use a smaller
font size where possible. Pair with @code{@@end smalldisplay}.
-@xref{@code{@@small@dots{}}}.
+@xref{small}.
@item @@smallexample
Begin an example. Like @code{@@example}, but use a smaller font size
where possible. Pair with @code{@@end smallexample}.
-@xref{@code{@@small@dots{}}}.
+@xref{small}.
@item @@smallformat
Begin a kind of example. Like @code{@@format}, but use a smaller font
size where possible. Pair with @code{@@end smallformat}.
-@xref{@code{@@small@dots{}}}.
+@xref{small}.
@item @@smallindentedblock
Like @code{@@indentedblock}, but use a smaller font size where
possible. Pair with @code{@@end smallindentedblock}.
-@xref{@code{@@small@dots{}}}.
+@xref{small}.
@item @@smalllisp
Begin an example of Lisp code. Same as @code{@@smallexample}. Pair
-with @code{@@end smalllisp}. @xref{@code{@@small@dots{}}}.
+with @code{@@end smalllisp}. @xref{small}.
@item @@smallquotation
Like @code{@@quotation}, but use a smaller font size where possible.
-Pair with @code{@@end smallquotation}. @xref{@code{@@small@dots{}}}.
+Pair with @code{@@end smallquotation}. @xref{small}.
@item @@sortas @{@var{key}@}
Used in the arguments to index commands to give a string by which the
@@ -20718,7 +20027,7 @@ Generate the degree symbol. @xref{@code{@@textdegree}}.
Only allowed in a heading or footing. Stands for, respectively, the
number and name of the current chapter (in the format `Chapter 1:
Title'), the current chapter name only, the current chapter number
-only, the filename, the current page number, and the title of the
+only, the file name, the current page number, and the title of the
document, respectively. @xref{Custom Headings, , How to Make Your Own
Headings}.
@@ -20761,12 +20070,9 @@ Headings, , How to Make Your Own Headings}.
@item @@top @var{title}
Mark the topmost @code{@@node} in the file, which must be defined on
the line immediately preceding the @code{@@top} command. The title is
-formatted as a chapter-level heading. The entire top node, including
-the @code{@@node} and @code{@@top} lines, are normally enclosed with
-@code{@@ifnottex ... @@end ifnottex}. In @TeX{} and
+formatted as a chapter-level heading. In @TeX{} and
@code{texinfo-format-buffer}, the @code{@@top} command is merely a
-synonym for @code{@@unnumbered}. @xref{@command{makeinfo} Pointer
-Creation}.
+synonym for @code{@@unnumbered}.
@item @@U@{@var{hex}@}
Output a representation of Unicode character U+@var{hex}.
@@ -20818,10 +20124,6 @@ characters: @code{after}, @code{before}, @code{none}.
Generate check accent over the character @var{c}, as in @v{o}.
@xref{Inserting Accents}.
-@item @@validatemenus @var{on-off}
-Control whether menus can be automatically generated. @xref{Writing a
-Menu}.
-
@item @@value@{@var{txivar}@}
Insert the value, if any, of the Texinfo variable @var{txivar},
previously defined by @code{@@set}. @xref{@code{@@set @@clear
@@ -20875,7 +20177,7 @@ mandatory. @xref{@code{@@xref}}.
@item @@xrefautomaticsectiontitle @var{on-off}
By default, use the section title instead of the node name in cross
-references. @xref{Three Arguments}.
+references, including in node headers in HTML. @xref{Three Arguments}.
@end table
@@ -20886,7 +20188,7 @@ references. @xref{Three Arguments}.
@cindex Contexts, of @@-commands
Here we describe approximately which @@-commands can be used in which
-contexts. It not exhaustive or meant to be a complete reference.
+contexts. It is not exhaustive or meant to be a complete reference.
Discrepancies between the information here and the @code{makeinfo} or
@TeX{} implementations are most likely to be resolved in favor of the
implementation.
@@ -20933,6 +20235,12 @@ Here are Texinfo @@-commands which are obsolete or have been removed
completely. This section is for historical purposes.
@ftable @code
+@item @@refill
+This command used to refill and indent the paragraph after all the
+other processing has been done. It is no longer needed, since all
+formatters now automatically refill as needed, but you may still see
+it in the source to some manuals, as it does no harm.
+
@item @@setcontentsaftertitlepage
@cindex Contents, after title page
@cindex Table of contents, after title page
@@ -20942,13 +20250,11 @@ no longer recommend this.
This command could be used by a user printing a manual, to force the
contents to be printed after the title page
(after the @samp{@@end titlepage} line)
-even if the @code{@@contents} command was at the end of the manual. It
-now does nothing.
+even if the @code{@@contents} command was at the end of the manual.
@item @@setshortcontentsaftertitlepage
This placed the short table of contents after the @samp{@@end titlepage}
-command even if the @code{@@shortcontents} command was at the end. It
-now does nothing.
+command even if the @code{@@shortcontents} command was at the end.
@end ftable
@@ -21375,94 +20681,15 @@ Write notes for yourself at the very end of a Texinfo file after the
@appendix Sample Texinfo Files
@cindex Sample Texinfo files
-The first example from the first chapter (@pxref{Short Sample}) is
-given here in its entirety, without commentary. The second example
-includes the full texts to be used in GNU manuals.
+This appendix includes texts to be used in GNU manuals.
@menu
-* Short Sample Texinfo File::
* GNU Sample Texts::
* Verbatim Copying License::
* All-permissive Copying License::
@end menu
-@node Short Sample Texinfo File
-@section Short Sample
-@cindex Sample Texinfo file, no comments
-
-Here is a complete, short sample Texinfo file. You can see this file,
-with comments, in the first chapter. @xref{Short Sample}.
-
-In a nutshell: The @command{makeinfo} program transforms a Texinfo
-source file such as this into an Info file or HTML; and @TeX{} typesets
-it for a printed manual.
-
-
-@sp 1
-@example
-\input texinfo
-@@settitle Sample Manual 1.0
-
-@@copying
-This is a short example of a complete Texinfo file.
-
-Copyright @@copyright@{@} 2016 Free Software Foundation, Inc.
-@@end copying
-
-@@titlepage
-@@title Sample Title
-@@page
-@@vskip 0pt plus 1filll
-@@insertcopying
-@@end titlepage
-
-@@c Output the table of the contents at the beginning.
-@@contents
-
-@@ifnottex
-@@node Top
-@@top GNU Sample
-
-This manual is for GNU Sample
-(version @@value@{VERSION@}, @@value@{UPDATED@}).
-@@end ifnottex
-
-@@menu
-* First Chapter:: The first chapter is the
- only chapter in this sample.
-* Index:: Complete index.
-@@end menu
-
-
-@@node First Chapter
-@@chapter First Chapter
-
-@@cindex chapter, first
-
-This is the first chapter.
-@@cindex index entry, another
-
-Here is a numbered list.
-
-@@enumerate
-@@item
-This is the first item.
-
-@@item
-This is the second item.
-@@end enumerate
-
-
-@@node Index
-@@unnumbered Index
-
-@@printindex cp
-
-@@bye
-@end example
-
-
@node GNU Sample Texts
@section GNU Sample Texts
@@ -21481,37 +20708,11 @@ They're included here nonetheless because many manuals do (or could)
benefit from them.
@xref{Short Sample}, for a minimal example of a Texinfo file.
-@xref{Beginning and Ending a File}, for a full explanation of that
-minimal example.
Here are some notes on the example:
@itemize @bullet
@item
-@cindex $Id
-@cindex CVS $Id
-@cindex RCS $Id
-@cindex Documentation identification
-@cindex Identification of documentation
-The @samp{$Id:} comment is for the CVS
-(@url{http://www.nongnu.org/cvs/}), RCS (@pxref{Top,,, rcs, Revision
-Control System}) and other version control systems, which expand it
-into a string such as:
-
-@example
-$Id$
-@end example
-
-(This is potentially useful in all sources that use version control,
-not just manuals.) You may wish to include the @samp{$Id:} comment in
-the @code{@@copying} text, if you want a completely unambiguous
-reference to the documentation source version.
-
-If you want to literally write @t{@w{$}Id$}, use @code{@@w}:
-@code{@@w@{$@}Id$}. Unfortunately, this technique does not work in
-plain text output, where it's not clear what should be done.
-
-@item
@pindex automake@r{, and version info}
@vindex UPDATED @r{Automake variable}
@vindex UPDATED-MONTH @r{Automake variable}
@@ -21542,26 +20743,17 @@ Structure Details,,, standards, GNU Coding Standards}.
@item
@cindex GNU Free Documentation License, including entire
@cindex Free Documentation License, including entire
-It is best to include the entire GNU Free Documentation License in a GNU
-manual, unless the manual is only a few pages long. Of course this
-sample is even shorter than that, but it includes the FDL anyway in
-order to show one conventional way to do so. The @file{fdl.texi} file
-is available on the GNU machines and in the Texinfo and other GNU
-source distributions.
-
-The FDL provides for omitting itself under certain conditions, but in
-that case the sample texts given here have to be modified. @xref{GNU
-Free Documentation License}.
+This sample shows how to includes the FDL in a manual using the
+@command{@@include} command. The @file{fdl.texi} file
+is available in the Texinfo and other GNU source distributions. It is
+also available on the GNU website (at
+@uref{https://www.gnu.org/licenses/fdl-1.3.html}) along with guidance
+for using it.
@item
If the FSF is not the copyright holder, then use the appropriate name.
@item
-If your manual is published on paper by the FSF or is longer than 400
-pages, you should include the standard FSF cover texts (@pxref{License
-Notices for Documentation,,, maintain, GNU Maintainer Information}).
-
-@item
For documents that express your personal views, feelings or
experiences, it is more appropriate to use a license permitting only
verbatim copying, rather than the FDL@. @xref{Verbatim Copying
@@ -21573,7 +20765,6 @@ Here is the sample document:
@verbatim
\input texinfo @c -*-texinfo-*-
-@comment $Id@w{$}
@comment %**start of header
@include version.texi
@settitle GNU Sample @value{VERSION}
@@ -21611,12 +20802,10 @@ Texts. A copy of the license is included in the section entitled
@contents
-@ifnottex
@node Top
@top GNU Sample
This manual is for GNU Sample (version @value{VERSION}, @value{UPDATED}).
-@end ifnottex
@menu
* Invoking sample::
@@ -21665,7 +20854,7 @@ On the other hand, for documents that express your personal views,
feelings or experiences, it is more appropriate to use a license
permitting only verbatim copying.
-Here is sample text for such a license permitting verbatim copying only.
+Here is a sample text for such a license permitting verbatim copying only.
This is just the license text itself. For a complete sample document,
see the previous sections.
@@ -21699,7 +20888,7 @@ lines long) and rough documentation (README files, INSTALL files, etc.),
the full FDL would be overkill. They can use a simple all-permissive
license.
-Here is sample text for such an all-permissive license. This is just
+Here is a sample text for such an all-permissive license. This is just
the license text itself. For a complete sample document, see the
previous sections.
@@ -21734,6 +20923,7 @@ commands and tools to help ease your work.
* Info Formatting:: How to format for Info.
* Printing:: How to format and print part or all of a file.
* Texinfo Mode Summary:: Summary of all the Texinfo mode commands.
+* Catching Mistakes:: How to find mistakes in formatting.
@end menu
@node Texinfo Mode Overview
@@ -21957,7 +21147,7 @@ required, but a description helps explain what the node is about.
To use @code{texinfo-start-menu-description}, position point in a menu
entry line and type @kbd{C-c C-c C-d}. The command looks for and copies
the title that goes with the node name, and inserts the title as a
-description; it positions point at beginning of the inserted text so you
+description; it positions point at the beginning of the inserted text so you
can edit it. The function does not insert the title if the menu entry
line already contains a description.
@@ -22659,357 +21849,7 @@ M-x texinfo-sequential-node-update
@end example
-@node Headings
-@appendix Page Headings
-@cindex Headings
-@cindex Footings
-@cindex Page numbering
-@cindex Page headings
-@cindex Formatting headings and footings
-
-Most printed manuals contain headings along the top of every page
-except the title and copyright pages. Some manuals also contain
-footings. @c HTML output also supports something like these, but in a
-@c completely different way: @pxref{Customizing HTML Page Layout}.
-Headings and footings have no meaning in Info or the other output
-formats.
-
-@menu
-* Headings Introduced:: Conventions for using page headings.
-* Heading Format:: Standard page heading formats.
-* Heading Choice:: How to specify the type of page heading.
-* Custom Headings:: How to create your own headings and footings.
-@end menu
-
-@node Headings Introduced
-@section Headings Introduced
-
-Texinfo provides standard page heading formats for manuals that are
-printed on one side of each sheet of paper and for manuals that are
-printed on both sides of the paper. Typically, you will use these
-formats, but you can specify your own format if you wish.
-
-In addition, you can specify whether chapters should begin on a new
-page, or merely continue the same page as the previous chapter; and if
-chapters begin on new pages, you can specify whether they must be
-odd-numbered pages.
-
-By convention, a book is printed on both sides of each sheet of paper.
-When you open a book, the right-hand page is odd-numbered, and
-chapters begin on right-hand pages---a preceding left-hand page is
-left blank if necessary. Reports, however, are often printed on just
-one side of paper, and chapters begin on a fresh page immediately
-following the end of the preceding chapter. In short or informal
-reports, chapters often do not begin on a new page at all, but are
-separated from the preceding text by a small amount of whitespace.
-
-The @code{@@setchapternewpage} command controls whether chapters begin
-on new pages, and whether one of the standard heading formats is used.
-In addition, Texinfo has several heading and footing commands that you
-can use to generate your own heading and footing formats.
-
-In Texinfo, headings and footings are single lines at the tops and
-bottoms of pages; you cannot create multiline headings or footings.
-Each header or footer line is divided into three parts: a left part, a
-middle part, and a right part. Any part, or a whole line, may be left
-blank. Text for the left part of a header or footer line is set
-flushleft; text for the middle part is centered; and, text for the
-right part is set flushright.
-
-
-@node Heading Format
-@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
-on both sides of the paper.
-
-By default, nothing is specified for the footing of a Texinfo file,
-so the footing remains blank.
-
-The standard format for single-sided printing consists of a header
-line in which the left-hand part contains the name of the chapter, the
-central part is blank, and the right-hand part contains the page
-number.
-
-@need 950
-A single-sided page looks like this:
-
-@example
-@group
- _______________________
- | |
- | chapter page number |
- | |
- | Start of text ... |
- | ... |
- | |
-@end group
-@end example
-
-The standard format for two-sided printing depends on whether the page
-number is even or odd. By convention, even-numbered pages are on the
-left- and odd-numbered pages are on the right. (@TeX{} will adjust the
-widths of the left- and right-hand margins. Usually, widths are
-correct, but during double-sided printing, it is wise to check that
-pages will bind properly---sometimes a printer will produce output in
-which the even-numbered pages have a larger right-hand margin than the
-odd-numbered pages.)
-
-In the standard double-sided format, the left part of the left-hand
-(even-numbered) page contains the page number, the central part is
-blank, and the right part contains the title (specified by the
-@code{@@settitle} command). The left part of the right-hand
-(odd-numbered) page contains the name of the chapter, the central part
-is blank, and the right part contains the page number.
-
-@need 750
-Two pages, side by side as in an open book, look like this:
-
-@example
-@group
- _______________________ _______________________
- | | | |
- | page number title | | chapter page number |
- | | | |
- | Start of text ... | | More text ... |
- | ... | | ... |
- | | | |
-@end group
-@end example
-
-@noindent
-The chapter name is preceded by the word ``Chapter'', the chapter number
-and a colon. This makes it easier to keep track of where you are in the
-manual.
-
-@node Heading Choice
-@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
-title and copyright pages are not numbered. The @code{@@end
-titlepage} command causes @TeX{} to begin to generate page headings
-according to a standard format specified by the
-@code{@@setchapternewpage} command that precedes the
-@code{@@titlepage} section.
-
-@need 1000
-There are four possibilities:
-
-@table @asis
-@item No @code{@@setchapternewpage} command
-Cause @TeX{} to specify the single-sided heading format, with chapters
-on new pages. This is the same as @code{@@setchapternewpage on}.
-
-@item @code{@@setchapternewpage on}
-Specify the single-sided heading format, with chapters on new pages.
-
-@item @code{@@setchapternewpage off}
-Cause @TeX{} to start a new chapter on the same page as the last page
-of the preceding chapter, after skipping some vertical whitespace.
-Also cause @TeX{} to typeset for single-sided printing. (You can
-override the headers format with the @code{@@headings double} command;
-@pxref{@code{@@headings}}.)
-
-@item @code{@@setchapternewpage odd}
-Specify the double-sided heading format, with chapters on new pages.
-@end table
-
-@noindent
-Texinfo lacks a @code{@@setchapternewpage even} command.
-
-
-@node Custom 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.
-
-Texinfo provides six commands for specifying headings and
-footings:
-@itemize @bullet
-@item
-@code{@@everyheading} and @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. You must cancel the
-predefined heading commands with the @code{@@headings off} command
-before defining your own specifications.
-
-@need 1000
-Here is how to tell @TeX{} to place the chapter name at the left, the
-page number in the center, and the date at the right of every header
-for both even- and odd-numbered pages:
-
-@example
-@group
-@@headings off
-@@everyheading @@thischapter @@| @@thispage @@| @@today@{@}
-@end group
-@end example
-
-@noindent
-You need to divide the left part from the central part and the central
-part from the right part by inserting @samp{@@|} between parts.
-Otherwise, the specification command will not be able to tell where
-the text for one part ends and the next part begins.
-
-Each part can contain text or @@-commands. The text is printed as if
-the part were within an ordinary paragraph in the body of the page.
-The @@-commands replace themselves with the page number, date, chapter
-name, or whatever.
-
-@need 950
-Here are the six heading and footing commands:
-
-@table @code
-@item @@everyheading @var{left} @@| @var{center} @@| @var{right}
-@itemx @@everyfooting @var{left} @@| @var{center} @@| @var{right}
-@findex everyheading
-@findex everyfooting
-The `every' commands specify the format for both even- and odd-numbered
-pages. These commands are for documents that are printed on one side
-of each sheet of paper, or for documents in which you want symmetrical
-headers or footers.
-
-@item @@evenheading @var{left} @@| @var{center} @@| @var{right}
-@itemx @@oddheading @var{left} @@| @var{center} @@| @var{right}
-@itemx @@evenfooting @var{left} @@| @var{center} @@| @var{right}
-@itemx @@oddfooting @var{left} @@| @var{center} @@| @var{right}
-@findex evenheading
-@findex evenfooting
-@findex oddheading
-@findex oddfooting
-The `even' and `odd' commands specify the format for even-numbered
-pages and odd-numbered pages. These commands are for books and
-manuals that are printed on both sides of each sheet of paper.
-@end table
-
-Use the @samp{@@this@dots{}} series of @@-commands to
-provide the names of chapters
-and sections and the page number. You can use the
-@samp{@@this@dots{}} commands in the left, center, or right portions
-of headers and footers, or anywhere else in a Texinfo file so long as
-they are between @code{@@iftex} and @code{@@end iftex} commands.
-
-@need 1000
-Here are the @samp{@@this@dots{}} commands:
-
-@table @code
-@item @@thispage
-@findex thispage
-Expands to the current page number.
-
-@item @@thissectionname
-@findex thissectionname
-Expands to the name of the current section.
-
-@item @@thissectionnum
-@findex thissectionnum
-Expands to the number of the current section.
-
-@item @@thissection
-@findex thissection
-Expands to the number and name of the current section, in the format
-`Section 1: Title'.
-
-@item @@thischaptername
-@findex thischaptername
-Expands to the name of the current chapter.
-
-@item @@thischapternum
-@findex thischapternum
-Expands to the number of the current chapter, or letter of the current
-appendix.
-
-@item @@thischapter
-@findex thischapter
-Expands to the number and name of the current
-chapter, in the format `Chapter 1: Title'.
-
-@item @@thistitle
-@findex thistitle
-Expands to the name of the document, as specified by the
-@code{@@settitle} command.
-
-@item @@thisfile
-@findex thisfile
-For @code{@@include} files only: expands to the name of the current
-@code{@@include} file. If the current Texinfo source file is not an
-@code{@@include} file, this command has no effect. This command does
-@emph{not} provide the name of the current Texinfo source file unless
-it is an @code{@@include} file. (@xref{Include Files}, for more
-information about @code{@@include} files.)
-@end table
-
-@noindent
-You can also use the @code{@@today@{@}} command, which expands to the
-current date, in `1 Jan 1900' format.
-@findex today
-
-Other @@-commands and text are printed in a header or footer just as
-if they were in the body of a page. It is useful to incorporate text,
-particularly when you are writing drafts:
-
-@example
-@group
-@@headings off
-@@everyheading @@emph@{Draft!@} @@| @@thispage @@| @@thischapter
-@@everyfooting @@| @@| Version: 0.27: @@today@{@}
-@end group
-@end example
-
-Beware of overlong titles: they may overlap another part of the
-header or footer and blot it out.
-
-If you have very short chapters and/or sections, several of them can
-appear on a single page. You can specify which chapters and sections
-you want @code{@@thischapter}, @code{@@thissection} and other such
-macros to refer to on such pages as follows:
-
-@table @code
-@item @@everyheadingmarks @var{ref}
-@itemx @@everyfootingmarks @var{ref}
-@findex everyheadingmarks
-@findex everyfootingmarks
-The @var{ref} argument can be either @code{top} (the @code{@@this...}
-commands will refer to the chapter/section at the top of a page) or
-@code{bottom} (the commands will reflect the situation at the bottom
-of a page). These @samp{@@every...} commands specify what to do on
-both even- and odd-numbered pages.
-
-@item @@evenheadingmarks @var{ref}
-@itemx @@oddheadingmarks @var{ref}
-@itemx @@evenfootingmarks @var{ref}
-@itemx @@oddfootingmarks @var{ref}
-@findex evenheadingmarks
-@findex oddheadingmarks
-@findex evenfootingmarks
-@findex oddfootingmarks
-These @samp{@@even...} and @samp{@@odd...} commands specify what to do
-on only even- or odd-numbered pages, respectively. The @var{ref}
-argument is the same as with the @samp{@@every...} commands.
-@end table
-
-Write these commands immediately after the @code{@@...contents}
-commands, or after the @code{@@end titlepage} command if you don't
-have a table of contents or if it is printed at the end of your
-manual.
-
-By default the @code{@@this...} commands reflect the situation at the
-bottom of a page both in headings and in footings.
-
-
+@lowersections
@node Catching Mistakes
@appendix Catching Mistakes
@cindex Structure, catching mistakes in
@@ -23063,7 +21903,7 @@ its Texinfo mode manifestations, @code{makeinfo-region} and
@code{makeinfo-buffer}) to format your file and check for other
errors. This is the best way to work with Texinfo. But if you
cannot use @code{makeinfo}, or your problem is very puzzling, then you
-may want to use the tools described in this appendix.
+may want to use the tools described in this section.
@node Debugging with Info
@@ -23579,7 +22419,7 @@ table and split the file manually.
@node Splitting
@subsection Splitting a File Manually
@cindex Splitting an Info file manually
-@cindex Info file, splitting manually
+@cindex Info files @subentry splitting manually
You should split a large file or else let the
@code{texinfo-format-buffer} or @code{makeinfo-buffer} command do it
@@ -23589,7 +22429,7 @@ commands do this job for you. @xref{Creating an Info File}.)
The split-off files are called the indirect subfiles.
Info files are split to save memory. With smaller files, Emacs does not
-have make such a large buffer to hold the information.
+have to make such a large buffer to hold the information.
If an Info file has more than 30 nodes, you should also make a tag
table for it. @xref{Using @code{Info-validate}}, for information
@@ -23619,6 +22459,730 @@ by appending @samp{-} and a number to the original file name.
The primary file still functions as an Info file, but it contains just
the tag table and a directory of subfiles.
+@raisesections
+
+
+@node Global Document Commands
+@appendix Global Document Commands
+@cindex Global Document Commands
+
+Here are additional commands which affect the document as a whole. Nearly all
+of these commands are for customizing the appearance of the printed output when
+processing with @TeX{}. They are generally all given before the Top node, if
+they are given at all.
+
+@menu
+* @code{@@setchapternewpage}:: Start chapters on right-hand pages.
+* Headings:: Page headings.
+* @code{@@paragraphindent}:: Specify paragraph indentation.
+* @code{@@firstparagraphindent}:: Suppressing first paragraph indentation.
+* @code{@@exampleindent}:: Specify environment indentation.
+* @code{@@smallbook}:: How to print small format books and manuals.
+* A4 Paper:: How to print on A4, A5 or B6 paper.
+* @code{@@pagesizes}:: How to print with customized page sizes.
+* Magnification:: How to print scaled up output.
+@end menu
+
+@node @code{@@setchapternewpage}
+@section @code{@@setchapternewpage}: Blank Pages Before Chapters
+
+@anchor{setchapternewpage}@c old name
+@findex setchapternewpage
+@cindex Starting chapters
+@cindex Pages, starting odd
+
+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
+preceding chapter, after a small amount of vertical whitespace.
+
+You can use the @code{@@setchapternewpage} command with various
+arguments to specify how @TeX{} should start chapters and whether it
+should format headers for printing on one or both sides of the paper
+(single-sided or double-sided printing).
+
+Write the @code{@@setchapternewpage} command at the beginning of a
+line followed by its argument. For example, you would write the
+following to cause each chapter to start on a fresh odd-numbered page:
+
+@example
+@@setchapternewpage odd
+@end example
+
+You can specify one of three alternatives with the
+@code{@@setchapternewpage} command:
+
+@table @asis
+
+@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
+format page headers for single-sided printing.
+
+@item @code{@@setchapternewpage on}
+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 or personal printing. This is the default.
+
+@item @code{@@setchapternewpage odd}
+Cause @TeX{} to start new chapters on new, odd-numbered pages
+(right-handed pages) and to typeset for double-sided printing. This is
+the form most often used for books and manuals.
+@end table
+
+Texinfo does not have a @code{@@setchapternewpage even} command,
+because there is no printing tradition of starting chapters or books on
+an even-numbered page.
+
+If you don't like the default headers that @code{@@setchapternewpage}
+sets, you can explicit control them with the @code{@@headings} command.
+@xref{@code{@@headings}}.
+
+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. By
+convention, table of contents and frontmatter pages are numbered with
+roman numerals and not in sequence with the rest of the document.
+
+The @code{@@setchapternewpage} has no effect in output formats that do
+not have pages, such as Info and HTML.
+
+We recommend not including any @code{@@setchapternewpage} command in
+your document source at all, since such desired pagination is not
+intrinsic to the document. For a particular hard copy run, if you
+don't want the default output (no blank pages, same headers on all
+pages) use the @option{--texinfo} option to @command{texi2dvi} to
+specify the output you want.
+
+
+
+@node Headings
+@section Page Headings
+@anchor{Headings Introduced}@c old name
+@cindex Headings
+@cindex Footings
+@cindex Page numbering
+@cindex Page headings
+@cindex Formatting headings and footings
+
+Most printed manuals contain headings along the top of every page
+except the title and copyright pages. Some manuals also contain
+footings. @c HTML output also supports something like these, but in a
+@c completely different way: @pxref{Customizing HTML Page Layout}.
+Headings and footings have no meaning in Info or the other output
+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
+on both sides of the paper.
+By default, nothing is specified for the footing of a Texinfo file,
+so the footing remains blank.
+
+Texinfo also has several heading and footing commands that you
+can use to generate your own heading and footing formats.
+
+In Texinfo, headings and footings are single lines at the tops and
+bottoms of pages; you cannot create multiline headings or footings.
+Each header or footer line is divided into three parts: a left part, a
+middle part, and a right part. Any part, or a whole line, may be left
+blank. Text for the left part of a header or footer line is set
+flushleft; text for the middle part is centered; and, text for the
+right part is set flushright.
+
+@menu
+* @code{@@headings}:: An option for turning headings on and off
+ and double or single sided printing.
+* Heading Format:: Standard page heading formats.
+* Custom Headings:: How to create your own headings and footings.
+@end menu
+
+@node @code{@@headings}
+@subsection The @code{@@headings} Command
+
+@anchor{headings on off}@c old name
+@findex headings
+
+The @code{@@headings} command is rarely used. It specifies what kinds of
+page headings and footings to print on each page. Usually, this is
+controlled by the @code{@@setchapternewpage} command. You need the
+@code{@@headings} command only if the @code{@@setchapternewpage} command
+does not do what you want, or if you want to turn off predefined page
+headings prior to defining your own. Write a @code{@@headings} command
+immediately after the @code{@@end titlepage} command.
+
+You can use @code{@@headings} as follows:
+
+@table @code
+@item @@headings off
+Turn off printing of page headings.
+
+@item @@headings single
+Turn on page headings appropriate for single-sided printing.
+
+@item @@headings double
+Turn on page headings appropriate for double-sided printing.
+
+@item @@headings singleafter
+@itemx @@headings doubleafter
+Turn on @code{single} or @code{double} headings, respectively, after the
+current page is output.
+
+@item @@headings on
+Turn on page headings: @code{single} if @samp{@@setchapternewpage
+on}, @code{double} otherwise.
+@end table
+
+For example, suppose you write @code{@@setchapternewpage off} before the
+@code{@@titlepage} command to tell @TeX{} to start a new chapter on the
+same page as the end of the last chapter. This command also causes
+@TeX{} to typeset page headers for single-sided printing. To cause
+@TeX{} to typeset for double-sided printing, write @code{@@headings
+double} after the @code{@@end titlepage} command.
+
+You can stop @TeX{} from generating any page headings at all by
+writing @code{@@headings off} on a line of its own immediately after the
+line containing the @code{@@end titlepage} command, like this:
+
+@example
+@@end titlepage
+@@headings off
+@end example
+
+@noindent
+The @code{@@headings off} command overrides the @code{@@end titlepage}
+command, which would otherwise cause @TeX{} to print page headings.
+
+
+@node Heading Format
+@subsection 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
+on both sides of the paper.
+
+By default, nothing is specified for the footing of a Texinfo file,
+so the footing remains blank.
+
+The standard format for single-sided printing consists of a header
+line in which the left-hand part contains the name of the chapter, the
+central part is blank, and the right-hand part contains the page
+number.
+
+@need 950
+A single-sided page looks like this:
+
+@example
+@group
+ _______________________
+ | |
+ | chapter page number |
+ | |
+ | Start of text ... |
+ | ... |
+ | |
+@end group
+@end example
+
+The standard format for two-sided printing depends on whether the page
+number is even or odd. By convention, even-numbered pages are on the
+left- and odd-numbered pages are on the right. (@TeX{} will adjust the
+widths of the left- and right-hand margins. Usually, widths are
+correct, but during double-sided printing, it is wise to check that
+pages will bind properly---sometimes a printer will produce output in
+which the even-numbered pages have a larger right-hand margin than the
+odd-numbered pages.)
+
+In the standard double-sided format, the left part of the left-hand
+(even-numbered) page contains the page number, the central part is
+blank, and the right part contains the title (specified by the
+@code{@@settitle} command). The left part of the right-hand
+(odd-numbered) page contains the name of the chapter, the central part
+is blank, and the right part contains the page number.
+
+@need 750
+Two pages, side by side as in an open book, look like this:
+
+@example
+@group
+ _______________________ _______________________
+ | | | |
+ | page number title | | chapter page number |
+ | | | |
+ | Start of text ... | | More text ... |
+ | ... | | ... |
+ | | | |
+@end group
+@end example
+
+@noindent
+The chapter name is preceded by the word ``Chapter'', the chapter number
+and a colon. This makes it easier to keep track of where you are in the
+manual.
+
+
+@node Custom Headings
+@subsection 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.
+
+Texinfo provides six commands for specifying headings and
+footings:
+@itemize @bullet
+@item
+@code{@@everyheading} and @code{@@everyfooting} generate page headers and
+footers that are the same for both even- and odd-numbered pages.
+@item
+@code{@@evenheading} and @code{@@evenfooting} commands 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. You must cancel the
+predefined heading commands with the @code{@@headings off} command
+before defining your own specifications.
+
+@need 1000
+Here is how to tell @TeX{} to place the chapter name at the left, the
+page number in the center, and the date at the right of every header
+for both even- and odd-numbered pages:
+
+@example
+@group
+@@headings off
+@@everyheading @@thischapter @@| @@thispage @@| @@today@{@}
+@end group
+@end example
+
+@noindent
+You need to divide the left part from the central part and the central
+part from the right part by inserting @samp{@@|} between parts.
+Otherwise, the specification command will not be able to tell where
+the text for one part ends and the next part begins.
+
+Each part can contain text or @@-commands. The text is printed as if
+the part were within an ordinary paragraph in the body of the page.
+The @@-commands replace themselves with the page number, date, chapter
+name, or whatever.
+
+@need 950
+Here are the six heading and footing commands:
+
+@table @code
+@item @@everyheading @var{left} @@| @var{center} @@| @var{right}
+@itemx @@everyfooting @var{left} @@| @var{center} @@| @var{right}
+@findex everyheading
+@findex everyfooting
+The `every' commands specify the format for both even- and odd-numbered
+pages. These commands are for documents that are printed on one side
+of each sheet of paper, or for documents in which you want symmetrical
+headers or footers.
+
+@item @@evenheading @var{left} @@| @var{center} @@| @var{right}
+@itemx @@oddheading @var{left} @@| @var{center} @@| @var{right}
+@itemx @@evenfooting @var{left} @@| @var{center} @@| @var{right}
+@itemx @@oddfooting @var{left} @@| @var{center} @@| @var{right}
+@findex evenheading
+@findex evenfooting
+@findex oddheading
+@findex oddfooting
+The `even' and `odd' commands specify the format for even-numbered
+pages and odd-numbered pages. These commands are for books and
+manuals that are printed on both sides of each sheet of paper.
+@end table
+
+Use the @samp{@@this@dots{}} series of @@-commands to
+provide the names of chapters
+and sections and the page number. You can use the
+@samp{@@this@dots{}} commands in the left, center, or right portions
+of headers and footers, or anywhere else in a Texinfo file so long as
+they are between @code{@@iftex} and @code{@@end iftex} commands.
+
+@need 1000
+Here are the @samp{@@this@dots{}} commands:
+
+@table @code
+@item @@thispage
+@findex thispage
+Expands to the current page number.
+
+@item @@thissectionname
+@findex thissectionname
+Expands to the name of the current section.
+
+@item @@thissectionnum
+@findex thissectionnum
+Expands to the number of the current section.
+
+@item @@thissection
+@findex thissection
+Expands to the number and name of the current section, in the format
+`Section 1: Title'.
+
+@item @@thischaptername
+@findex thischaptername
+Expands to the name of the current chapter.
+
+@item @@thischapternum
+@findex thischapternum
+Expands to the number of the current chapter, or letter of the current
+appendix.
+
+@item @@thischapter
+@findex thischapter
+Expands to the number and name of the current
+chapter, in the format `Chapter 1: Title'.
+
+@item @@thistitle
+@findex thistitle
+Expands to the name of the document, as specified by the
+@code{@@settitle} command.
+
+@item @@thisfile
+@findex thisfile
+For @code{@@include} files only: expands to the name of the current
+@code{@@include} file. If the current Texinfo source file is not an
+@code{@@include} file, this command has no effect. This command does
+@emph{not} provide the name of the current Texinfo source file unless
+it is an @code{@@include} file. (@xref{Include Files}, for more
+information about @code{@@include} files.)
+@end table
+
+@noindent
+You can also use the @code{@@today@{@}} command, which expands to the
+current date, in `1 Jan 1900' format.
+@findex today
+
+Other @@-commands and text are printed in a header or footer just as
+if they were in the body of a page. It is useful to incorporate text,
+particularly when you are writing drafts:
+
+@example
+@group
+@@headings off
+@@everyheading @@emph@{Draft!@} @@| @@thispage @@| @@thischapter
+@@everyfooting @@| @@| Version: 0.27: @@today@{@}
+@end group
+@end example
+
+Beware of overlong titles: they may overlap another part of the
+header or footer and blot it out.
+
+If you have very short chapters and/or sections, several of them can
+appear on a single page. You can specify which chapters and sections
+you want @code{@@thischapter}, @code{@@thissection} and other such
+macros to refer to on such pages as follows:
+
+@table @code
+@item @@everyheadingmarks @var{ref}
+@itemx @@everyfootingmarks @var{ref}
+@findex everyheadingmarks
+@findex everyfootingmarks
+The @var{ref} argument can be either @code{top} (the @code{@@this...}
+commands will refer to the chapter/section at the top of a page) or
+@code{bottom} (the commands will reflect the situation at the bottom
+of a page). These @samp{@@every...} commands specify what to do on
+both even- and odd-numbered pages.
+
+@item @@evenheadingmarks @var{ref}
+@itemx @@oddheadingmarks @var{ref}
+@itemx @@evenfootingmarks @var{ref}
+@itemx @@oddfootingmarks @var{ref}
+@findex evenheadingmarks
+@findex oddheadingmarks
+@findex evenfootingmarks
+@findex oddfootingmarks
+These @samp{@@even...} and @samp{@@odd...} commands specify what to do
+on only even- or odd-numbered pages, respectively. The @var{ref}
+argument is the same as with the @samp{@@every...} commands.
+@end table
+
+Write these commands immediately after the @code{@@...contents}
+commands, or after the @code{@@end titlepage} command if you don't
+have a table of contents or if it is printed at the end of your
+manual.
+
+By default the @code{@@this...} commands reflect the situation at the
+bottom of a page both in headings and in footings.
+
+
+@node @code{@@paragraphindent}
+@section @code{@@paragraphindent}: Controlling Paragraph Indentation
+
+@anchor{paragraphindent}@c old name
+@findex paragraphindent
+@cindex Indenting paragraphs, control of
+@cindex Paragraph indentation control
+
+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 a @code{@@paragraphindent} command at the beginning of a line
+followed by either @samp{asis} or a number:
+
+@example
+@@paragraphindent @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 @code{none}
+@itemx 0
+Omit all indentation.
+
+@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 3. @code{@@paragraphindent} is
+ignored for HTML output.
+
+It is best to write the @code{@@paragraphindent} command before the
+end-of-header line at the beginning of a Texinfo file, so the region
+formatting commands indent paragraphs as specified. @xref{Start of
+Header}.
+
+
+@node @code{@@firstparagraphindent}
+@section @code{@@firstparagraphindent}: Indenting After Headings
+
+@anchor{firstparagraphindent}@c old name
+@findex firstparagraphindent
+@cindex First paragraph, suppressing indentation of
+@cindex Suppressing first paragraph indentation
+@cindex Preventing first paragraph indentation
+@cindex Indenting, suppressing of first paragraph
+@cindex Headings, indentation after
+
+As you can see in the present manual, the first paragraph in any
+section is not indented by default. Typographically, indentation is a
+paragraph separator, which means that it is unnecessary when a new
+section begins. This indentation is controlled with the
+@code{@@firstparagraphindent} command:
+
+@example
+@@firstparagraphindent @var{word}
+@end example
+
+The first paragraph after a heading is indented according to the value
+of @var{word}:
+
+@table @asis
+@item @code{none}
+Prevents the first paragraph from being indented (default).
+This option is ignored by @command{makeinfo} if
+@code{@@paragraphindent asis} is in effect.
+
+@item @code{insert}
+Include normal paragraph indentation. This respects the paragraph
+indentation set by a @code{@@paragraphindent} command
+(@pxref{@code{@@paragraphindent}}).
+@end table
+
+@code{@@firstparagraphindent} is ignored for HTML and DocBook output.
+
+It is best to write the @code{@@firstparagraphindent} command before the
+end-of-header line at the beginning of a Texinfo file, so the region
+formatting commands indent paragraphs as specified. @xref{Start of
+Header}.
+
+
+@node @code{@@exampleindent}
+@section @code{@@exampleindent}: Environment Indenting
+
+@anchor{exampleindent}@c old name
+@findex exampleindent
+@cindex Indenting environments
+@cindex Environment indentation
+@cindex Example indentation
+
+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 spaces in Info, and 0.4@dmn{in}
+in @TeX{}, which is somewhat less. (The reduction is to help @TeX{}
+fit more characters onto physical lines.)
+
+It is best to write the @code{@@exampleindent} command before the
+end-of-header line at the beginning of a Texinfo file, so the region
+formatting commands indent paragraphs as specified. @xref{Start of
+Header}.
+
+
+@node @code{@@smallbook}
+@section @code{@@smallbook}: Printing ``Small'' Books
+
+@anchor{smallbook}@c old name
+@findex smallbook
+@cindex Small book size
+@cindex Book, printing small
+@cindex Page sizes for books
+@cindex Size of printed book
+
+By default, @TeX{} typesets pages for printing in an 8.5 by 11 inch
+format. However, you can direct @TeX{} to typeset a document in a 7 by
+9.25 inch format that is suitable for bound books by inserting the
+following command on a line by itself at the beginning of the Texinfo
+file, before the title page:
+
+@example
+@@smallbook
+@end example
+
+@noindent
+(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}).
+
+@xref{Format with @command{texi2dvi}}, and @ref{Preparing for @TeX{}},
+for other ways to format with @code{@@smallbook} that do not require
+changing the source file.
+
+
+@node A4 Paper
+@section Printing on A4 Paper
+@cindex A4 paper, printing on
+@cindex Paper size, A4
+@cindex European A4 paper
+@findex afourpaper
+You can tell @TeX{} to format a document for printing on ISO 216
+A4 paper size with the @code{@@afourpaper} command. Write the command on
+a line by itself near the beginning of the Texinfo file, before the
+title page.
+
+@cindex A5 paper, printing on
+@findex afourlatex
+@findex afourwide
+@findex afivepaper
+@findex bsixpaper
+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, @code{@@afivepaper} for A5 paper, and @code{@@bsixpaper} for
+B6 paper.
+
+@xref{Format with @command{texi2dvi}} and @ref{Preparing for @TeX{}},
+for other ways to format for different paper sizes that do not require
+changing the source file.
+
+
+@node @code{@@pagesizes}
+@section @code{@@pagesizes} [@var{width}][, @var{height}]: Custom Page Sizes
+@anchor{pagesizes}@c old node name
+
+@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}.
+
+@xref{Format with @command{texi2dvi}}, and @ref{Preparing for @TeX{}},
+for other ways to specify @code{@@pagesizes} that do not require
+changing the source file.
+
+
+@node Magnification
+@section Magnification
+@anchor{Cropmarks and Magnification} @c old name
+
+@findex \mag @r{(raw @TeX{} magnification)}
+@cindex Magnified printing
+@cindex Larger or smaller pages
+You can attempt to direct @TeX{} to typeset pages larger or smaller
+than usual with the @code{\mag} @TeX{} command. Everything that is
+typeset is scaled proportionally larger or smaller. (@code{\mag}
+stands for ``magnification''.) This is @emph{not} a Texinfo
+@@-command, but is a raw @TeX{} command that is prefixed with a
+backslash. You have to write this command between @code{@@tex} and
+@code{@@end tex} (@pxref{Raw Formatter Commands}).
+
+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:
+
+@example
+@group
+@@tex
+\global\mag=1200
+@@end tex
+@end group
+@end example
+
+With some printing technologies, you can print normal-sized copies that
+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, DVI files prepared with a
+nonstandard-@code{\mag} may not print or may print only with certain
+magnifications. Be prepared to experiment.
+
@node Info Format Specification
@appendix Info Format Specification
@@ -23690,7 +23254,7 @@ This section describes the overall layout of Info manuals.
@node Info Format Whole Manual
-@subheading Info Format: A Whole Manual
+@subsection Info Format: A Whole Manual
@cindex Nonsplit manuals, Info format of
@cindex Split manuals, Info format of
@@ -23734,7 +23298,7 @@ with the indirect table to deduce which subfile a particular node is in.
@node Info Format Preamble
-@subheading Info Format: Preamble
+@subsection Info Format: Preamble
@cindex Preamble, in Info format
@@ -23769,7 +23333,7 @@ commands present in the manual (@pxref{Installing Dir Entries}).
@node Info Format Indirect Table
-@subheading Info Format: Indirect Table
+@subsection Info Format: Indirect Table
@cindex Indirect table, in Info format
@@ -23812,7 +23376,7 @@ giving up immediately if the position is not exactly at a node beginning.
@node Info Format Tag Table
-@subheading Info Format: Tag Table
+@subsection Info Format: Tag Table
@cindex Tag table, in Info format
@@ -23864,7 +23428,7 @@ table entry.
@node Info Format Local Variables
-@subheading Info Format: Local Variables
+@subsection Info Format: Local Variables
@cindex Local variable section, in Info format
@@ -23883,7 +23447,7 @@ End:
@node Info Format Regular Nodes
-@subheading Info Format: Regular Nodes
+@subsection Info Format: Regular Nodes
@cindex Info nodes, in Info format
@@ -23984,7 +23548,7 @@ be displayed as part of the menu, as-is (@pxref{Writing a Menu}).
@node Info Format Image
@subsection Info Format: Image
-@cindex Images, in Info format
+@cindex Images @subentry in Info format
The @code{@@image} command results in the following special directive
within the Info file (@pxref{Images}):
@@ -24088,7 +23652,7 @@ text>} is descriptive text.
In both forms the @t{<id>} refers to a node or anchor, in the same way
as a reference in the node information line does (@pxref{Info Format
Regular Nodes}). The optional parenthesized @samp{<infofile>} is the
-filename of the manual being referenced, and the @t{<nodename>} is the
+name of the manual being referenced, and the @t{<nodename>} is the
node or anchor within that manual,
The second form has a descriptive label. A cross-reference in this form