[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[5316] texinfo.txi -> texinfo.texi to placate automake 1.14
|
From: |
karl |
|
Subject: |
[5316] texinfo.txi -> texinfo.texi to placate automake 1.14 |
|
Date: |
Thu, 15 Aug 2013 17:38:20 +0000 |
Revision: 5316
http://svn.sv.gnu.org/viewvc/?view=rev&root=texinfo&revision=5316
Author: karl
Date: 2013-08-15 17:38:19 +0000 (Thu, 15 Aug 2013)
Log Message:
-----------
texinfo.txi -> texinfo.texi to placate automake 1.14
Modified Paths:
--------------
trunk/configure.ac
trunk/doc/Makefile.am
trunk/doc/version.texi
Added Paths:
-----------
trunk/doc/texinfo.texi
Removed Paths:
-------------
trunk/doc/texinfo.txi
Modified: trunk/configure.ac
===================================================================
--- trunk/configure.ac 2013-08-15 17:29:30 UTC (rev 5315)
+++ trunk/configure.ac 2013-08-15 17:38:19 UTC (rev 5316)
@@ -18,7 +18,8 @@
AC_CONFIG_AUX_DIR([build-aux])
dnl tar-ustar because we have long filenames for some test files.
dnl parallel-tests as recommended by stefano.
-AM_INIT_AUTOMAKE([1.12 tar-ustar parallel-tests readme-alpha dist-xz])
+AM_INIT_AUTOMAKE([1.13 dist-xz
+ info-in-builddir parallel-tests readme-alpha tar-ustar])
# Where to generate output; srcdir location.
AC_CONFIG_HEADERS([config.h:config.in])dnl Keep filename to 8.3 for MS-DOS.
Modified: trunk/doc/Makefile.am
===================================================================
--- trunk/doc/Makefile.am 2013-08-15 17:29:30 UTC (rev 5315)
+++ trunk/doc/Makefile.am 2013-08-15 17:38:19 UTC (rev 5316)
@@ -15,7 +15,7 @@
SUBDIRS = tp_api
# Put texinfo.txi first because that's the most important.
-info_TEXINFOS = texinfo.txi info-stnd.texi info.texi
+info_TEXINFOS = texinfo.texi info-stnd.texi info.texi
DISTCLEANFILES = texinfo texinfo-* info*.info*
# Use the programs built in our distribution, taking account of possible
Copied: trunk/doc/texinfo.texi (from rev 5312, trunk/doc/texinfo.txi)
===================================================================
--- trunk/doc/texinfo.texi (rev 0)
+++ trunk/doc/texinfo.texi 2013-08-15 17:38:19 UTC (rev 5316)
@@ -0,0 +1,24385 @@
+\input texinfo.tex @c -*-texinfo-*-
address@hidden $Id$
address@hidden Ordinarily, Texinfo files have the extension .texi. But
texinfo.texi
address@hidden clashes with texinfo.tex on 8.3 filesystems, so we use
texinfo.txi.
+
address@hidden Everything between the start/end of header lines will be passed
by
address@hidden Emacs's {texinfo,makeinfo}-format region commands. See the
`start of
address@hidden header' node for more info.
address@hidden %**start of header
+
address@hidden makeinfo and texinfo.tex ignore all text before @setfilename.
address@hidden
address@hidden Ordinarily, the setfilename argument ends with .info. But
address@hidden texinfo.info-13 is too long for 14-character filesystems.
address@hidden texinfo
+
address@hidden Automake automatically updates version.texi to @set VERSION and
address@hidden @set UPDATED to appropriate values.
address@hidden version.texi
address@hidden GNU Texinfo @value{VERSION}
+
address@hidden Define a new index for command-line options.
address@hidden op
+
address@hidden Put everything except function (command, in this case) names in
one
address@hidden index (arbitrarily chosen to be the concept index).
address@hidden op cp
address@hidden vr cp
address@hidden pg cp
+
address@hidden 2
address@hidden finalout
+
address@hidden %**end of header
+
address@hidden
+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 Free Software Foundation, Inc.
+
address@hidden
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover Texts being ``A GNU Manual'',
+and with the Back-Cover Texts as in (a) below. A copy of the license
+is included in the section entitled ``GNU Free Documentation
+License''.
+
+(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
+modify this GNU manual. Buying copies from the FSF supports it in
+developing GNU and promoting software freedom.''
address@hidden quotation
address@hidden copying
+
address@hidden Texinfo documentation system
address@hidden
+* Texinfo: (texinfo). The GNU documentation format.
+* install-info: (texinfo)Invoking install-info. Update info/dir entries.
+* makeinfo: (texinfo)Invoking makeinfo. Translate Texinfo source.
+* pod2texi: (pod2texi)Invoking pod2texi. Translate Perl POD to Texinfo.
+* texi2dvi: (texinfo)Format with texi2dvi. Print Texinfo documents.
+* texi2pdf: (texinfo)PDF Output. PDF output for Texinfo.
+* pdftexi2dvi: (texinfo)PDF Output. PDF output for Texinfo.
+* texindex: (texinfo)Format with tex/texindex. Sort Texinfo index files.
address@hidden direntry
+
address@hidden Before release, run C-u C-c C-u C-a (texinfo-all-menus-update
with a
address@hidden prefix arg). This updates the node pointers, which texinfmt.el
needs.
+
address@hidden Set smallbook if printing in smallbook format so the example of
the
address@hidden smallbook font is actually written using smallbook; in bigbook,
a kludge
address@hidden is used for TeX output. Do this through the -t option to
texi2dvi,
address@hidden so this same source can be used for other paper sizes as well.
address@hidden smallbook
address@hidden set smallbook
address@hidden @@clear smallbook
+
address@hidden If you like blank pages, add through texi2dvi -t.
address@hidden setchapternewpage odd
+
+
address@hidden GNU Texinfo
+
address@hidden
address@hidden Texinfo
address@hidden The GNU Documentation Format
address@hidden for Texinfo version @value{VERSION}, @value{UPDATED}
+
address@hidden Robert J. Chassell
address@hidden Richard M. Stallman
+
address@hidden Include the Distribution inside the titlepage so
address@hidden that headings are turned off.
+
address@hidden
address@hidden 0pt plus 1filll
address@hidden
+
address@hidden 1
+Published by the Free Software Foundation @*
+51 Franklin St, Fifth Floor @*
+Boston, MA 02110-1301 @*
+USA @*
+ISBN 1-882114-67-1 @c for version 4.0, September 1999.
address@hidden ISBN 1-882114-65-5 is for version 3.12, March 1998.
address@hidden ISBN 1-882114-64-7 is for edition 2.24 of November 1996.
address@hidden ISBN 1-882114-63-9 is for edition 2.20 of 28 February 1995.
+
address@hidden 1
+Cover art by Etienne Suvasa.
address@hidden titlepage
+
+
address@hidden
address@hidden
+
+
address@hidden
address@hidden Top
address@hidden Texinfo
+
+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.
+
+The first part of this master menu lists the major nodes in this Info
+document, including the @@-command and concept indices. The rest of
+the menu lists all the lower level nodes in the document.
address@hidden ifnottex
+
address@hidden
+* Copying Conditions:: Your rights.
+* Overview:: Texinfo in brief.
+* Texinfo Mode:: Using the GNU Emacs Texinfo mode.
+* Beginning a File:: What is at the beginning of a Texinfo file?
+* Ending a File:: What is at the end of a Texinfo file?
+* Chapter Structuring:: Creating chapters, sections, appendices, etc.
+* Nodes:: Writing nodes, the basic unit of Texinfo.
+* Menus:: Writing menus.
+* Cross References:: Writing cross references.
+* Marking Text:: Marking words and phrases as code,
+ keyboard input, meta-syntactic
+ variables, and the like.
+* Quotations and Examples:: Block quotations, examples, etc.
+* Lists and Tables:: Itemized or numbered lists, and tables.
+* Special Displays:: Floating figures and footnotes.
+* Indices:: Creating indices.
+* Insertions:: Inserting @@-signs, braces, etc.
+* Breaks:: Forcing or preventing line and page breaks.
+* Definition Commands:: Describing functions and the like uniformly.
+* Internationalization:: Supporting languages other than English.
+* Conditionals:: Specifying text for only some output cases.
+* Defining New Texinfo Commands:: User-defined macros and aliases.
+* Include Files:: How to incorporate other Texinfo files.
+
+* Hardcopy:: Output for paper, with @TeX{}.
+* Generic Translator @t{texi2any}:: @command{texi2any}, an all-purpose
converter.
+* Creating and Installing Info Files:: Details on Info output.
+* Generating HTML:: Details on HTML output.
address@hidden * texi2any Output Customization:: Fine tuning with
initialization files.
+
+* Command List:: All the Texinfo @@-commands.
+* Tips:: Hints on how to write a Texinfo document.
+* Sample Texinfo Files:: Complete examples, including full texts.
+* Headings:: How to write page headings and footings.
+* Catching Mistakes:: How to find mistakes in formatting.
+* 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.
+* General Index:: A menu covering many topics.
+
address@hidden
+ --- The Detailed Node Listing ---
+
+Overview of Texinfo
+
+* Reporting Bugs:: Submitting effective bug reports.
+* Using Texinfo:: Create printed or online output.
+* Output Formats:: Overview of the supported output formats.
+* Adding Output Formats:: Man pages and implementing new formats.
+* Texinfo Document Structure:: How Texinfo manuals are usually arranged.
+* Info Files:: What is an Info file?
+* Printed Books:: Characteristics of a printed book or manual.
+* Formatting Commands:: @@-commands are used for formatting.
+* Conventions:: General rules for writing a Texinfo file.
+* Comments:: Writing comments and ignored text in general.
+* Minimum:: What a Texinfo file must have.
+* Six Parts:: Usually, a Texinfo file has six parts.
+* Short Sample:: A short sample Texinfo file.
+* History:: Acknowledgements, contributors and genesis.
+
+Using Texinfo Mode
+
+* Texinfo Mode Overview:: How Texinfo mode can help you.
+* Emacs Editing:: Texinfo mode adds to GNU Emacs' general
+ purpose editing features.
+* Inserting:: How to insert frequently used @@-commands.
+* Showing the Structure:: How to show the structure of a file.
+* Updating Nodes and Menus:: How to update or create new nodes and menus.
+* 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.
+
+Updating Nodes and Menus
+
+* Updating Commands:: Five major updating commands.
+* Updating Requirements:: How to structure a Texinfo file for
+ using the updating command.
+* Other Updating Commands:: How to indent descriptions, insert
+ missing nodes lines, and update
+ nodes in sequence.
+
+Beginning a Texinfo File
+
+* 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.
+
+Texinfo File Header
+
+* First Line:: The first line of a Texinfo file.
+* Start of Header:: Formatting a region requires this.
+* @t{@@setfilename}:: Tell Info the name of the Info file.
+* @t{@@settitle}:: Create a title for the printed work.
+* End of Header:: Formatting a region requires this.
+
+Document Permissions
+
+* @t{@@copying}:: Declare the document's copying
permissions.
+* @t{@@insertcopying}:: Where to insert the permissions.
+
+Title and Copyright Pages
+
+* @t{@@titlepage}:: Create a title for the printed document.
+* @t{@@titlefont @@center @@sp}:: The @code{@@titlefont}, @code{@@center},
+ and @code{@@sp} commands.
+* @t{@@title @@subtitle @@author}:: The @code{@@title}, @code{@@subtitle},
+ and @code{@@author} commands.
+* Copyright:: How to write the copyright notice and
+ include copying permissions.
+* Heading Generation:: Turn on page headings after the title and
+ copyright pages.
+
+The `Top' Node and Master Menu
+
+* Top Node Example::
+* Master Menu Parts::
+
+Global Document Commands
+
+* @t{@@documentdescription}:: Document summary for the HTML output.
+* @t{@@setchapternewpage}:: Start chapters on right-hand pages.
+* @t{@@headings}:: An option for turning headings on and off
+ and double or single sided printing.
+* @t{@@paragraphindent}:: Specify paragraph indentation.
+* @t{@@firstparagraphindent}:: Suppressing first paragraph indentation.
+* @t{@@exampleindent}:: Specify environment indentation.
+
+Ending a Texinfo File
+
+* Printing Indices & Menus:: How to print an index in hardcopy and
+ generate index menus in Info.
+* File End:: How to mark the end of a file.
+
+Chapter Structuring
+
+* Tree Structuring:: A manual is like an upside down tree @dots{}
+* Structuring Command Types:: How to divide a manual into parts.
+* @t{@@chapter}:: Chapter structuring.
+* @t{@@unnumbered @@appendix}::
+* @t{@@majorheading @@chapheading}::
+* @t{@@section}::
+* @t{@@unnumberedsec @@appendixsec @@heading}::
+* @t{@@subsection}::
+* @t{@@unnumberedsubsec @@appendixsubsec @@subheading}::
+* @t{@@subsubsection}:: Commands for the lowest level sections.
+* @t{@@part}:: Collections of chapters.
+* Raise/lower sections:: How to change commands' hierarchical level.
+
+Nodes
+
+* @t{@@node}:: Creating nodes, in detail.
+* @t{makeinfo} Pointer Creation:: Letting makeinfo determine node pointers.
+* @t{@@anchor}:: Defining arbitrary cross reference
targets.
+* Node Menu Illustration:: A diagram, and sample nodes and menus.
+
+The @code{@@node} Command
+
+* Node Names:: How to choose node and pointer 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.
+* @t{@@top} Command:: How to use the @code{@@top} command.
+
+Menus
+
+* Menu Location:: Menus go at the ends of nodes.
+* Writing a Menu:: What is a menu?
+* Menu Parts:: A menu entry has three parts.
+* Less Cluttered Menu Entry:: Two part menu entry.
+* Menu Example:: Two and three part menu entries.
+* Other Info Files:: How to refer to a different Info file.
+
+Cross References
+
+* References:: What cross references are for.
+* Cross Reference Commands:: A summary of the different commands.
+* Cross Reference Parts:: A cross reference has several parts.
+* @t{@@xref}:: Begin a reference with `See' @dots{}
+* Top Node Naming:: How to refer to the beginning of another file.
+* @t{@@ref}:: A reference for the last part of a
sentence.
+* @t{@@pxref}:: How to write a parenthetical cross
reference.
+* @t{@@inforef}:: How to refer to an Info-only file.
+* @t{@@url}:: How to refer to a uniform resource
locator.
+* @t{@@cite}:: How to refer to books not in the Info
system.
+
address@hidden@@xref}
+
+* Reference Syntax:: What a reference looks like and requires.
+* One Argument:: @code{@@xref} with one argument.
+* Two Arguments:: @code{@@xref} with two arguments.
+* Three Arguments:: @code{@@xref} with three arguments.
+* Four and Five Arguments:: @code{@@xref} with four and five arguments.
+
+Marking Text, Words and Phrases
+
+* Indicating:: How to indicate definitions, files, etc.
+* Emphasis:: How to emphasize text.
+
+Indicating Definitions, Commands, etc.
+
+* Useful Highlighting:: Highlighting provides useful information.
+* @t{@@code}:: Indicating program code.
+* @t{@@kbd}:: Showing keyboard input.
+* @t{@@key}:: Specifying keys.
+* @t{@@samp}:: Indicating a literal sequence of
characters.
+* @t{@@verb}:: Indicating a verbatim sequence of
characters.
+* @t{@@var}:: Indicating metasyntactic variables.
+* @t{@@env}:: Indicating environment variables.
+* @t{@@file}:: Indicating file names.
+* @t{@@command}:: Indicating command names.
+* @t{@@option}:: Indicating option names.
+* @t{@@dfn}:: Specifying definitions.
+* @t{@@abbr}:: Indicating abbreviations.
+* @t{@@acronym}:: Indicating acronyms.
+* @t{@@indicateurl}:: Indicating an example url.
+* @t{@@email}:: Indicating an electronic mail address.
+
+Emphasizing Text
+
+* @t{@@emph @@strong}:: How to emphasize text in Texinfo.
+* Smallcaps:: How to use the small caps font.
+* Fonts:: Various font commands for printed output.
+
+Quotations and Examples
+
+* Block Enclosing Commands:: Different constructs for different purposes.
+* @t{@@quotation}:: Writing a quotation.
+* @t{@@indentedblock}:: Block of text indented on left.
+* @t{@@example}:: Writing an example in a fixed-width font.
+* @t{@@verbatim}:: Writing a verbatim example.
+* @t{@@verbatiminclude}:: Including a file verbatim.
+* @t{@@lisp}:: Illustrating Lisp code.
+* @t{@@address@hidden:: Examples in a smaller font.
+* @t{@@display}:: Writing an example in the current font.
+* @t{@@format}:: Writing an example without narrowed
margins.
+* @t{@@exdent}:: Undo indentation on a line.
+* @t{@@flushleft @@flushright}:: Pushing text flush left or flush right.
+* @t{@@raggedright}:: Avoiding justification on the right.
+* @t{@@noindent}:: Preventing paragraph indentation.
+* @t{@@indent}:: Forcing paragraph indentation.
+* @t{@@cartouche}:: Drawing rounded rectangles around text.
+
+Lists and Tables
+
+* Introducing Lists:: Texinfo formats lists for you.
+* @t{@@itemize}:: How to construct a simple list.
+* @t{@@enumerate}:: How to construct a numbered list.
+* Two-column Tables:: How to construct a two-column table.
+* Multi-column Tables:: How to construct generalized tables.
+
+Making a Two-column Table
+
+* @t{@@table}:: How to construct a two-column table.
+* @t{@@ftable @@vtable}:: Automatic indexing for two-column tables.
+* @t{@@itemx}:: How to put more entries in the first
column.
+
address@hidden@@multitable}: Multi-column Tables
+
+* Multitable Column Widths:: Defining multitable column widths.
+* Multitable Rows:: Defining multitable rows, with examples.
+
+Special Displays
+
+* Floats:: Figures, tables, and the like.
+* Images:: Including graphics and images.
+* Footnotes:: Writing footnotes.
+
+Floats
+
+* @t{@@float}:: Producing floating material.
+* @t{@@caption @@shortcaption}:: Specifying descriptions for floats.
+* @t{@@listoffloats}:: A table of contents for floats.
+
+Inserting Images
+
+* Image Syntax::
+* Image Scaling::
+
+Footnotes
+
+* Footnote Commands:: How to write a footnote in Texinfo.
+* Footnote Styles:: Controlling how footnotes appear in Info.
+
+Indices
+
+* Index Entries:: Choose different words for index entries.
+* Predefined Indices:: Use different indices for different kinds
+ of entries.
+* Indexing Commands:: How to make an index entry.
+* Combining Indices:: How to combine indices.
+* New Indices:: How to define your own indices.
+
+Combining Indices
+
+* @t{@@syncodeindex}:: How to merge two indices, using
@code{@@code}
+ font for the merged-from index.
+* @t{@@synindex}:: How to merge two indices, using the
+ roman font for the merged-from index.
+
+Special Insertions
+
+* Special Characters:: Inserting @@ @address@hidden , \ #
+* Inserting Quote Characters:: Inserting left and right quotes, in code.
+* Inserting Space:: Inserting the right amount of whitespace.
+* Inserting Accents:: Inserting accents and special characters.
+* Inserting Quotation Marks:: Inserting quotation marks.
+* Inserting Math:: Formatting mathematical expressions.
+* Glyphs for Text:: Inserting Dots, bullets, currencies, etc.
+* Glyphs for Programming:: Indicating results of evaluation,
+ expansion of macros, errors, etc.
+
+Special Characters: Inserting @@ @address@hidden , \ #
+
+* Inserting an Atsign:: @code{@@@@}, @code{@@address@hidden@}}.
+* Inserting Braces:: @code{@@@{ @@@}}, @code{@@l address@hidden@}}.
+* Inserting a Comma:: , and @code{@@address@hidden@}}.
+* Inserting a Backslash:: \ and @code{@@address@hidden@}}.
+* Inserting a Hashsign:: # and @code{@@address@hidden@}}.
+
+Inserting Space
+
+* Multiple Spaces:: Inserting multiple spaces.
+* Not Ending a Sentence:: Sometimes a . doesn't end a sentence.
+* Ending a Sentence:: Sometimes it does.
+* @t{@@frenchspacing}:: Specifying end-of-sentence spacing.
+* @t{@@dmn}:: Formatting a dimension.
+
+Glyphs for Text
+
+* @t{@@TeX @@LaTeX}:: The @TeX{} logos.
+* @t{@@copyright}:: The copyright symbol (c in a circle).
+* @t{@@registeredsymbol}:: The registered symbol (R in a circle).
+* @t{@@dots}:: How to insert ellipses: @dots{} and
@enddots{}
+* @t{@@bullet}:: How to insert a bullet: @bullet{}
+* @t{@@euro}:: How to insert the euro currency symbol.
+* @t{@@pounds}:: How to insert the pounds currency symbol.
+* @t{@@textdegree}:: How to insert the degrees symbol.
+* @t{@@minus}:: How to insert a minus sign.
+* @t{@@geq @@leq}:: How to insert greater/less-than-or-equal
signs.
+
+Glyphs for Programming
+
+* Glyphs Summary::
+* @t{@@result}:: How to show the result of expression.
+* @t{@@expansion}:: How to indicate an expansion.
+* @t{@@print}:: How to indicate generated output.
+* @t{@@error}:: How to indicate an error message.
+* @t{@@equiv}:: How to indicate equivalence.
+* @t{@@point}:: How to indicate the location of point.
+* Click Sequences:: Inserting GUI usage sequences.
+
+Forcing and Preventing Breaks
+
+* Break Commands:: Summary of break-related commands.
+* Line Breaks:: Forcing line breaks.
+* @t{@@- @@hyphenation}:: Helping @TeX{} with hyphenation points.
+* @t{@@allowcodebreaks}:: Controlling line breaks within @@code
text.
+* @t{@@w}:: Preventing unwanted line breaks in text.
+* @t{@@tie}:: Inserting an unbreakable but varying
space.
+* @t{@@sp}:: Inserting blank lines.
+* @t{@@page}:: Forcing the start of a new page.
+* @t{@@group}:: Preventing unwanted page breaks.
+* @t{@@need}:: Another way to prevent unwanted page
breaks.
+
+Definition Commands
+
+* Def Cmd Template:: Writing descriptions using definition commands.
+* Def Cmd Continuation Lines:: Continuing the heading over source lines.
+* Optional Arguments:: Handling optional and repeated arguments.
+* @t{@@deffnx}:: Group two or more `first' lines.
+* Def Cmds in Detail:: Reference for all the definition commands.
+* Def Cmd Conventions:: Conventions for writing definitions.
+* Sample Function Definition:: An example.
+
+The Definition Commands
+
+* Functions Commands:: Commands for functions and similar entities.
+* Variables Commands:: Commands for variables and similar entities.
+* Typed Functions:: Commands for functions in typed languages.
+* Typed Variables:: Commands for variables in typed languages.
+* Data Types:: The definition command for data types.
+* Abstract Objects:: Commands for object-oriented programming.
+
+Object-Oriented Programming
+
+* Variables: Object-Oriented Variables.
+* Methods: Object-Oriented Methods.
+
+Internationalization
+
+* @t{@@documentlanguage}:: Declaring the current language.
+* @t{@@documentencoding}:: Declaring the input encoding.
+
+Conditionally Visible Text
+
+* Conditional Commands:: Text for a given format.
+* Conditional Not Commands:: Text for any format other than a given one.
+* Raw Formatter Commands:: Using raw formatter commands.
+* Inline Conditionals:: Brace-delimited conditional text.
+* @t{@@set @@clear @@value}:: Variable tests and substitutions.
+* Testing for Texinfo Commands:: Testing if a Texinfo command is available.
+* Conditional Nesting:: Using conditionals inside conditionals.
+
address@hidden@@set}, @code{@@clear}, and @code{@@value}
+
+* @t{@@set @@value}:: Expand a flag variable to a string.
+* @t{@@ifset @@ifclear}:: Format a region if a flag is set.
+* @t{@@value} Example:: An easy way to update edition information.
+
+Defining New Texinfo Commands
+
+* Defining Macros:: Defining and undefining new commands.
+* Invoking Macros:: Using a macro, once you've defined it.
+* Macro Details:: Limitations of Texinfo macros.
+* @t{@@alias}:: Command aliases.
+* @t{@@definfoenclose}:: Customized highlighting.
+* External Macro Processors:: @code{#line} directives.
+
+External Macro Processors: Line Directives
+
+* @t{#line} Directive::
+* TeX: @t{#line} and @TeX{}.
+* Syntax: @t{#line} Syntax Details.
+
+Include Files
+
+* Using Include Files:: How to use the @code{@@include} command.
+* @t{texinfo-multiple-files-update}:: How to create and update nodes and
+ menus when using included 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
+
+* Use @TeX{}:: Use @TeX{} to format for hardcopy.
+* Format with @t{tex}/@t{texindex}:: How to format with explicit shell
commands.
+* Format with @t{texi2dvi}:: A simpler way to format.
+* Print with @t{lpr}:: How to print.
+* Within Emacs:: How to format and print from an Emacs shell.
+* Texinfo Mode Printing:: How to format and print in Texinfo mode.
+* Compile-Command:: How to print using Emacs's compile command.
+* Requirements Summary:: @TeX{} formatting requirements summary.
+* Preparing for @TeX{}:: What to do before you use @TeX{}.
+* Overfull hboxes:: What are and what to do with overfull hboxes.
+* @t{@@smallbook}:: How to print small format books and
manuals.
+* A4 Paper:: How to print on A4 or A5 paper.
+* @t{@@pagesizes}:: How to print with customized page sizes.
+* Cropmarks and Magnification:: How to print marks to indicate the size
+ of pages and how to print scaled up output.
+* PDF Output:: Portable Document Format output.
+* Obtaining @TeX{}:: How to obtain @TeX{}.
+
address@hidden: The Generic Translator for Texinfo
+
+* Reference Implementation:: @command{texi2any}: the reference
implementation.
+* Invoking @t{texi2any}:: Running the translator from a shell.
+* @t{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 @t{pod2texi}:: Translating Perl pod to Texinfo.
+* @t{texi2html}:: An ancestor of @command{texi2any}.
+
+Customization Variables
+
+* Commands: Customization Variables for @@-Commands.
+* Options: Customization Variables and Options.
+* Other: Other Customization Variables.
+
+Creating and Installing Info Files
+
+* Creating an Info File::
+* Installing an Info File::
+
+Creating an Info File
+
+* @t{makeinfo} Advantages:: @code{makeinfo} provides better error
checking.
+* @t{makeinfo} in Emacs:: How to run @code{makeinfo} from Emacs.
+* @t{texinfo-format} commands:: Two Info formatting commands written
+ in Emacs Lisp are an alternative
+ to @code{makeinfo}.
+* Batch Formatting:: How to format for Info in Emacs Batch mode.
+* Tag and Split Files:: How tagged and split files help Info
+ to run better.
+
+Installing an Info File
+
+* 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.
+* Installing Dir Entries:: How to specify what menu entry to add
+ to the Info directory.
+* Invoking @t{install-info}:: @code{install-info} options.
+
+Generating HTML
+
+* HTML Translation:: Details of the HTML output.
+* HTML Splitting:: How HTML output is split.
+* HTML CSS:: Influencing HTML output with Cascading Style
Sheets.
+* HTML Xref:: Cross references in HTML output.
+
+HTML Cross References
+
+* Link Basics: HTML Xref Link Basics.
+* Node Expansion: HTML Xref Node Name Expansion.
+* Command Expansion: HTML Xref Command Expansion.
+* 8-bit Expansion: HTML Xref 8-bit Character Expansion.
+* Mismatch: HTML Xref Mismatch.
+* Configuration: HTML Xref Configuration. htmlxref.cnf.
+* Preserving links: HTML Xref Link Preservation. MANUAL-noderename.cnf.
+
+@@-Command List
+
+* Command Syntax:: General syntax for varieties of @@-commands.
+* Command Contexts:: Guidelines for which commands can be used where.
+
+Sample Texinfo Files
+
+* Short Sample Texinfo File::
+* GNU Sample Texts::
+* Verbatim Copying License::
+* All-permissive Copying License::
+
+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
+
+* @t{makeinfo} Preferred:: @code{makeinfo} finds errors.
+* Debugging with Info:: How to catch errors with Info formatting.
+* Debugging with @TeX{}:: How to catch errors with @TeX{} formatting.
+* Using @t{texinfo-show-structure}:: How to use @code{texinfo-show-structure}.
+* Using @t{occur}:: How to list all lines containing a pattern.
+* Running @t{Info-validate}:: How to find badly referenced nodes.
+
+Finding Badly Referenced Nodes
+
+* Using @t{Info-validate}:: How to run @code{Info-validate}.
+* Unsplit:: How to create an unsplit file.
+* Tagifying:: How to tagify a file.
+* Splitting:: How to split a file manually.
+
+Info Format Specification
+
+* General: Info Format General Layout.
+* Text: 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 Tag Table.
+* Tag table: Info Format Tag Table.
+* Local variables: Info Format Local Variables.
+* Regular nodes: Info Format Regular Nodes.
+
+Info Format Text Constructs
+
+* Menu: Info Format Menu.
+* Image: Info Format Image.
+* Printindex: Info Format Printindex.
+* Xref: Info Format Cross Reference.
address@hidden detailmenu
address@hidden menu
+
address@hidden Reward readers for getting to the end of the menu :).
address@hidden Contributed by Arnold Robbins.
address@hidden
+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
address@hidden quotation
+
+
address@hidden Copying Conditions
address@hidden Texinfo Copying Conditions
address@hidden Copying conditions
address@hidden Conditions for copying Texinfo
address@hidden Free software
address@hidden Libre software
+
+GNU Texinfo is @dfn{free software}; this means that everyone is free
+to use it and free to redistribute it on certain conditions. Texinfo
+is not in the public domain; it is copyrighted and there are
+restrictions on its distribution, but these restrictions are designed
+to permit everything that a good cooperating citizen would want to do.
+What is not allowed is to try to prevent others from further sharing
+any version of Texinfo that they might get from you.
+
+Specifically, we want to make sure that you have the right to give away
+copies of the programs that relate to Texinfo, that you receive source
+code or else can get it if you want it, that you can change these
+programs or use pieces of them in new free programs, and that you know
+you can do these things.
+
+To make sure that everyone has such rights, we have to forbid you to
+deprive anyone else of these rights. For example, if you distribute
+copies of the Texinfo related programs, you must give the recipients all
+the rights that you have. You must make sure that they, too, receive or
+can get the source code. And you must tell them their rights.
+
+Also, for our own protection, we must make certain that everyone finds
+out that there is no warranty for the programs that relate to Texinfo.
+If these programs are modified by someone else and passed on, we want
+their recipients to know that what they have is not what we distributed,
+so that any problems introduced by others will not reflect on our
+reputation.
+
+The precise conditions of the licenses for the programs currently
+being distributed that relate to Texinfo are found in the General
+Public Licenses that accompany them. This manual is covered by the
+GNU Free Documentation License (@pxref{GNU Free Documentation
+License}).
+
+
address@hidden Overview
address@hidden Overview of Texinfo
address@hidden Overview of Texinfo
address@hidden Texinfo overview
+
address@hidden is a documentation system that uses a single source file
+to produce both online information and printed output. This means
+that instead of writing two different documents, one for the online
+information and the other for a printed work, you need write only one
+document. Therefore, when the work is revised, you need revise only
+that one document.
+
address@hidden Semantic markup
+Texinfo's markup commands are almost entirely @dfn{semantic}; that is,
+they specify the intended meaning of text in the document, rather than
+physical formatting instructions.
+
address@hidden Limited scope of Texinfo
+Texinfo was devised for the purpose of writing software documentation
+and manuals. It is not, and was never intended to be, a
+general-purpose formatting program. If you need to lay out a
+newspaper, devise a glossy magazine ad, or follow the exact formatting
+requirements of a publishing house, Texinfo is not the simplest tool.
+On the other hand, if you want to write a good manual for your
+program, Texinfo has many features that will make your job easier.
+Overall, it's intended to let you concentrate on the content, and thus
+provides almost no commands for controlling the final formatting.
+
address@hidden Pronounciation of Texinfo
address@hidden Spelling of Texinfo
+The first syllable of ``Texinfo'' is pronounced like ``speck'', not
+``hex''. This odd pronunciation is derived from, but is not the same
+as, the pronunciation of @TeX{}. In the word @TeX{}, the @samp{X} is
+actually the Greek letter ``chi'' rather than the English letter
+``ex''. Pronounce @TeX{} as if the @samp{X} were the last sound in
+the name `Bach'; but pronounce Texinfo as if the @samp{x} were a `k'.
+Spell ``Texinfo'' with a capital ``T'' and the other letters in
+lowercase.
+
+Manuals for most GNU packages are written in Texinfo, and available
+online at @url{http://www.gnu.org/doc}. The Texinfo
+
address@hidden
+* Reporting Bugs:: Submitting effective bug reports.
+* Using Texinfo:: Create printed or online output.
+* Output Formats:: Overview of the supported output formats.
+* Adding Output Formats:: Man pages and implementing new formats.
+* Texinfo Document Structure:: How Texinfo manuals are usually arranged.
+* Info Files:: What is an Info file?
+* Printed Books:: Characteristics of a printed book or manual.
+* Formatting Commands:: @@-commands are used for formatting.
+* Conventions:: General rules for writing a Texinfo file.
+* Comments:: Writing comments and ignored text in general.
+* Minimum:: What a Texinfo file must have.
+* Six Parts:: Usually, a Texinfo file has six parts.
+* Short Sample:: A short sample Texinfo file.
+* History:: Acknowledgements, contributors and genesis.
address@hidden menu
+
+
address@hidden Reporting Bugs
address@hidden Reporting Bugs
+
address@hidden Bugs, reporting
address@hidden Suggestions for Texinfo, making
address@hidden Reporting bugs
+We welcome bug reports and suggestions for any aspect of the Texinfo
+system: programs, documentation, installation, etc. Please email them
+to @email{bug-texinfo@@gnu.org}. You can get the latest version of
+Texinfo via its home page, @uref{http://www.gnu.org/software/texinfo}.
+
address@hidden Checklist for bug reports
+For bug reports, please include enough information for the maintainers
+to reproduce the problem. Generally speaking, that means:
+
address@hidden @bullet
address@hidden The version number of Texinfo and the program(s) or manual(s)
involved.
address@hidden The contents of any input files necessary to reproduce the bug.
address@hidden Precisely how you ran any program(s) involved.
address@hidden A description of the problem and samples of any erroneous output.
address@hidden Hardware and operating system names and versions.
address@hidden Anything else that you think would be helpful.
address@hidden itemize
+
+When in doubt whether something is needed or not, include it. It's
+better to include too much than to leave out something important.
+
+It is critical to send an actual input file that reproduces the
+problem. What's not critical is to ``narrow down'' the example to the
+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.)
+
address@hidden Patches, contributing
+Patches are most welcome; if possible, please make them with
address@hidden@w{diff -c}} (@pxref{Top,,, diff, Comparing and Merging Files})
+and include @file{ChangeLog} entries (@pxref{Change Log,,, emacs, The
+GNU Emacs Manual}), and follow the existing coding style.
+
+
address@hidden Using Texinfo
address@hidden Using Texinfo
+
address@hidden Using Texinfo in general
address@hidden Texinfo, introduction to
address@hidden Introduction to Texinfo
+
+Using Texinfo, you can create a printed document (via the @TeX{}
+typesetting system) with the normal features of a book, including
+chapters, sections, cross references, and indices. From the same
+Texinfo source file, you can create an Info file with special features
+to make documentation browsing easy. You can also create from that
+same source file an HTML output file suitable for use with a web
+browser, a Docbook file, or a transliteration in XML format. See the
+next section (@pxref{Output Formats}) for details and sample commands
+to generate output from the source.
+
address@hidden works with virtually all printers; Info works with virtually
+all computer terminals; the HTML output works with virtually all web
+browsers. Thus Texinfo and its output can be used by almost any
+computer user.
+
address@hidden Source file format
+A Texinfo source file is a plain ASCII file containing text
+interspersed with @dfn{@@-commands} (words preceded by an @samp{@@})
+that tell the Texinfo processors what to do. You can edit a Texinfo
+file with any text editor, but it is especially convenient to use GNU
+Emacs since that editor has a special mode, called Texinfo mode, that
+provides various Texinfo-related features. (@xref{Texinfo Mode}.)
+
+Texinfo is the official documentation format of the GNU project. More
+information is available at the @uref{http://www.gnu.org/doc/, GNU
+documentation web page}.
+
+
address@hidden Output Formats
address@hidden Output Formats
address@hidden Output formats
address@hidden Back-end output formats
+
+Here is a brief overview of the output formats currently supported by
+Texinfo.
+
address@hidden @asis
address@hidden Info
address@hidden Info output, overview
+(Generated via @command{makeinfo}.) Info format is mostly a plain
+text transliteration of the Texinfo source. It adds a few control
+characters to separate nodes and provide navigational information for
+menus, cross references, indices, and so on. The Emacs Info subsystem
+(@pxref{Top,,, info, Info}), and the standalone @command{info} program
+(@pxref{Top,,, info-stnd, GNU Info}), among others, can read these
+files. @xref{Info Files}, and @ref{Creating and Installing Info
+Files}.
+
address@hidden Plain text
address@hidden Plain text output, overview
+(Generated via @command{makeinfo --plaintext}.) This is almost the
+same as Info output with the navigational control characters are
+omitted.
+
address@hidden HTML
address@hidden HTML output, overview
address@hidden W3 consortium
address@hidden Mozilla
address@hidden Lynx
address@hidden Emacs-W3
+(Generated via @command{makeinfo --html}.) HTML, standing for Hyper
+Text Markup Language, has become the most commonly used language for
+writing documents on the World Wide Web. Web browsers, such as
+Mozilla, Lynx, and Emacs-W3, can render this language online. There
+are many versions of HTML; @command{makeinfo} tries to use a subset of
+the language that can be interpreted by any common browser. For
+details of the HTML language and much related information, see
address@hidden://www.w3.org/MarkUp/}. @xref{Generating HTML}.
+
address@hidden DVI
address@hidden DVI output, overview
address@hidden dvips
address@hidden xdvi
+(Generated via @command{texi2dvi}.) The DeVIce Independent binary
+format is output by the @TeX{} typesetting program
+(@uref{http://tug.org}). This is then read by a DVI `driver', which
+knows the actual device-specific commands that can be viewed or
+printed, notably Dvips for translation to PostScript (@pxref{Top,,,
+dvips, Dvips}) and Xdvi for viewing on an X display
+(@uref{http://sourceforge.net/projects/xdvi/}). @xref{Hardcopy}.
+(Be aware that the Texinfo language is very different from and much
+stricter than @TeX{}'s usual languages: plain @TeX{}, @LaTeX{},
address@hidden, etc.)
+
address@hidden PostScript
address@hidden PostScript output, overview
+(Generated via @command{texi2dvi --ps}.) PostScript is a page
+description language that became widely used around 1985 and is still
+used today. @uref{http://en.wikipedia.org/wiki/PostScript} gives a
+basic description and more preferences. By default, Texinfo uses the
address@hidden program to convert @TeX{}'s DVI output to PostScript.
address@hidden,,, dvips, Dvips}.
+
address@hidden PDF
address@hidden PDF output, overview
address@hidden Beebe, Nelson
+(Generated via @command{texi2dvi --pdf} or @command{texi2pdf}.) This
+format was developed by Adobe Systems for portable document
+interchange, based on their previous PostScript language. It can
+represent the exact appearance of a document, including fonts and
+graphics, and supporting arbitrary scaling. It is intended to be
+platform-independent and easily viewable, among other design goals;
address@hidden://en.wikipedia.org/wiki/Portable_Document_Format} and
address@hidden://tug.org/TUGboat/tb22-3/tb72beebe-pdf.pdf} have some
+background. By default, Texinfo uses the @command{pdftex} program, an
+extension of @TeX{}, to output PDF; see
address@hidden://tug.org/applications/pdftex}. @xref{PDF Output}.
+
address@hidden Docbook
address@hidden Docbook output, overview
address@hidden 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;
+see the Texinfo web pages.
+
address@hidden XML
address@hidden XML Texinfo output, overview
address@hidden Texinfo XML output, overview
address@hidden DTD, for Texinfo XML
address@hidden texinfo.dtd
address@hidden txixml2texi
+(Generated via @command{makeinfo --xml}.) XML is a generic syntax
+specification usable for any sort of content (a reference is at
address@hidden://www.w3.org/XML}). The @command{makeinfo} XML output,
+unlike all the other output formats, is a transliteration of the
+Texinfo source rather than processed output. That is, it translates
+the Texinfo markup commands into XML syntax, for further processing by
+XML tools. The details of the output are defined in an XML DTD as
+usual, which is contained in a file @file{texinfo.dtd} included in the
+Texinfo source distribution and available via the Texinfo web pages.
+The XML contains enough information to recreate the original content,
+except for syntactic constructs such as Texinfo macros and
+conditionals. The Texinfo source distribution includes a utility script
address@hidden to do that backward transformation.
address@hidden table
+
+
address@hidden Adding Output Formats
address@hidden Adding Output Formats
address@hidden Additional output formats
+
+The output formats in the previous section handle a wide variety of
+usage, but of course there is always room for more.
+
address@hidden Man page output, not supported
+From time to time, proposals are made to generate traditional Unix man
+pages from Texinfo source. However, because man pages have a strict
+conventional format, creating a good man page requires a completely
+different source than the typical Texinfo applications of writing a
+good user tutorial and/or a good reference manual. This makes
+generating man pages incompatible with the Texinfo design goal of not
+having to document the same information in different ways for
+different output formats. You might as well write the man page
+directly.
+
address@hidden help2man
address@hidden O'Dea, Brendan
+As an alternative way to support man pages, you may find the program
address@hidden to be useful. It generates a traditional man page
+from the @samp{--help} output of a program. In fact, the man pages
+for the programs in the Texinfo distribution are generated with this.
+It is GNU software written by Brendan O'Dea, available from
address@hidden://www.gnu.org/software/help2man}.
+
address@hidden Output formats, supporting more
address@hidden SGML-tools output format
+If you are a programmer and would like to contribute to the GNU
+project by implementing additional output formats for Texinfo, that
+would be excellent. The way to do this that would be most useful is
+to write a new back-end for @command{texi2any}, our reference
+implementation of a Texinfo parser; it creates a tree representation
+of the Texinfo input that you can use for the conversion. The
+documentation in the source file
address@hidden/Texinfo/Convert/Converter.pm} is a good place to start.
address@hidden Translator @t{texi2any}}.
+
+Another viable approach is use the Texinfo XML output from
address@hidden as your input. This XML is an essentially complete
+representation of the input, but without the Texinfo syntax and option
+peculiarities, as described above.
+
address@hidden Texinfo parsers, discouraging more
+If you still cannot resist the temptation of writing a new program
+that reads Texinfo source directly, let us give some more caveats:
+please do not underestimate the amount of work required. Texinfo is
+by no means a simple language to parse correctly, and remains under
+development, so you would be committing to an ongoing task. At a
+minimum, please check that the extensive tests of the language that
+come with @command{texi2any} give correct results with your new
+program.
+
+
address@hidden Texinfo Document Structure
address@hidden Texinfo Document Structure
address@hidden Texinfo document structure
address@hidden Document structure, of Texinfo
address@hidden Structure, of Texinfo documents
address@hidden Double structure, of Texinfo documents
+
address@hidden address@hidden node name
+Texinfo documents most usefully have a double structure, reflecting
+the double purposes of printed and online output. For printed output
+(DVI, PDF, @dots{}), with physical pages, there are chapters,
+sections, subsections, etc. For online output (Info, HTML, @dots{}),
+with interactive navigation and no physical pages, there are so-called
+``nodes''.
+
+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.
+
+Each @dfn{node} has a name, and contains the discussion of one topic.
+Along with the text for the user to read, each node also has pointers
+to other nodes, identified in turn by their own names. Info readers
+display one node at a time, and provide commands for the user to move
+to related nodes. The HTML output can be similarly navigated.
+
+The names of child nodes are listed in a @dfn{menu} 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.
+
+In addition, nodes at the same level are formed into a chain with
+`Next' and `Previous' pointers. As you might imagine, the `Next'
+pointer links to the next node (section), and the `Previous' pointer
+links to the previous node (section). 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 parent chapter. Each child node records the
+parent node name as its `Up' pointer. The last child has no `Next'
+pointer, and the first child has the parent both as its `Previous' and
+as its `Up' pointer.
+
+In addition to menus and `Next', `Previous', and `Up' pointers,
+Texinfo provides pointers of another kind for cross references, that
+can be sprinkled throughout the text. This is usually the best way to
+represent links that do not fit a hierarchical structure.
+
+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.
+
+
address@hidden Info Files
address@hidden Info Files
address@hidden Info files
+
+As mentioned above, Info format is mostly a plain text transliteration
+of the Texinfo source, with the addition of a few control characters
+to separate nodes and provide navigational information, so that
+Info-reading programs can operate on it.
+
+Info files are nearly always created by processing a Texinfo source
+document. @command{makeinfo}, also known as @command{texi2any}, is
+the principal command that converts a Texinfo file into an Info file;
address@hidden Translator @t{texi2any}}.
+
+Generally, you enter an Info file through a node that by convention is
+named `Top'. This node normally contains just a brief summary of the
+file's purpose, and a large menu through which the rest of the file is
+reached. From this node, you can either traverse the file
+systematically by going from node to node, or you can go to a specific
+node listed in the main menu, or you can search the index menus and then
+go directly to the node that has the information you want. Alternatively,
+with the standalone Info program, you can specify specific menu items on
+the command line (@pxref{Top,,, info, Info}).
+
+If you want to read through an Info file in sequence, as if it were a
+printed manual, you can hit @key{SPC} repeatedly, or you get the whole
+file with the advanced Info command @kbd{g *}. (@xref{Advanced,,
+Advanced Info commands, info, Info}.)
+
+The @file{dir} file in the @file{info} directory serves as the
+departure point for the whole Info system. From it, you can reach the
+`Top' nodes of each of the documents in a complete Info system.
+
address@hidden URI syntax for Info
+If you wish to refer to an Info file via a URI, you can use the
+(unofficial) syntax exemplified by the following. This works with
+Emacs/W3, for example:
address@hidden
+info:emacs#Dissociated%20Press
+info:///usr/info/emacs#Dissociated%20Press
+info://localhost/usr/info/emacs#Dissociated%20Press
address@hidden example
+
+The @command{info} program itself does not follow URIs of any kind.
+
+
address@hidden Printed Books
address@hidden Printed Books
address@hidden Printed book and manual characteristics
address@hidden Manual characteristics, printed
address@hidden Book characteristics, printed
address@hidden Texinfo printed book characteristics
address@hidden Characteristics, printed books or manuals
+
address@hidden 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.
+
+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.
+
address@hidden is a general purpose typesetting program. Texinfo provides a
+file @file{texinfo.tex} that contains information (definitions or
address@hidden) 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 (address@hidden by address@hidden); this is the default size.
+But you can also print for 7 inch by 9.25 inch pages (address@hidden by
address@hidden, the @code{@@smallbook} size; or on A4 or A5 size paper
+(@code{@@afourpaper}, @code{@@afivepaper}).
address@hidden@t{@@smallbook}}, and @ref{A4 Paper}.
+
address@hidden Literate programming
address@hidden 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.
+
address@hidden is very powerful and has a great many features. 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.
+
address@hidden @TeX{}}, for information on acquiring @TeX{}. It is
+not part of the Texinfo distribution.
+
+
address@hidden Formatting Commands
address@hidden @@-commands
address@hidden @@-commands
address@hidden 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
address@hidden@@-commands}. For example, @code{@@node} is the command to
+indicate a node and @code{@@chapter} is the command to indicate the
+start of a chapter. Almost all @@ command names are entirely
+lowercase.
+
+Texinfo's @@-commands are a strictly limited set of constructs. The
+strict limits are primarily intended to ``force'' you, the author, to
+concentrate on the writing and the content of your manual, rather than
+the details of the formatting.
+
+Depending on what they do or what address@hidden word
address@hidden comes from the way it is used in mathematics and does not
+refer to a dispute between two people; it refers to the information
+presented to the command. According to the @cite{Oxford English
+Dictionary}, the word derives from the Latin for @dfn{to make clear,
+prove}; thus it came to mean `the evidence offered as proof', which is
+to say, `the information offered', which led to its mathematical
+meaning. In its other thread of derivation, the word came to mean `to
+assert in a manner against which others may make counter assertions',
+which led to the meaning of `argument' as a dispute.} they take, you
+need to write @@-commands on lines of their own or as part of
+sentences:
+
address@hidden @bullet
address@hidden
+Some commands are written at the start of a line and the rest of the
+line comprises the argument text, such as @code{@@chapter} (which
+creates chapter titles).
+
address@hidden
+Some commands can appear anywhere, generally within a sentence, and
+are followed by empty braces, such as @code{@@address@hidden@}} (which creates
+an ellipsis @dots{}).
+
address@hidden
+Some commands can appear anywhere, generally within a sentence, and
+are followed by the argument text in braces, such as
address@hidden@@address@hidden@}} (which marks text as being code, @code{a+1}
being
+the argument in this case).
+
address@hidden
+Some commands are written at the start of a line, with general text on
+following lines, terminated by a matching @code{@@end} command on a
+line of its own. For example, @code{@@example}, then the lines of a
+coding example, then @code{@@end example}.
address@hidden itemize
+
address@hidden
address@hidden Braces, when to use
+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 own. The
+non-alphabetic commands, such as @code{@@:}, are exceptions to the
+rule; they do not need braces.
+
+As you gain experience with Texinfo, you will rapidly learn how to
+write the different commands: the different ways to write commands
+actually make it easier to write and read Texinfo files than if all
+commands followed exactly the same syntax. @xref{Command Syntax, ,
+@@-Command Syntax}, for all the details.
+
+
address@hidden Conventions
address@hidden General Syntactic Conventions
address@hidden General syntactic conventions
address@hidden Syntactic conventions
address@hidden Conventions, syntactic
address@hidden Characters, basic input
+
+This section describes the general conventions used in all Texinfo documents.
+
address@hidden @bullet
address@hidden
address@hidden Source files, characters used
+All printable ASCII characters except @samp{@@}, @address@hidden and
address@hidden@}} can appear in a Texinfo file and stand for themselves.
address@hidden@@} is the escape character which introduces commands, while
address@hidden@{} and @address@hidden are used to surround arguments to certain
+commands. To put one of these special characters into the document, put
+an @samp{@@} character in front of it, like this: @samp{@@@@},
address@hidden@@@{}, and @samp{@@@}}.
+
address@hidden
address@hidden Paragraph separator
address@hidden Blank lines, as paragraph separator
address@hidden Newlines, as blank lines
+Separate paragraphs with one or more blank lines. Currently Texinfo
+only recognizes newline characters as end of line, not the CRLF
+sequence used on some systems; so a @dfn{blank line} means exactly two
+consecutive newlines. Sometimes blank lines are useful or convenient
+in other cases as well; you can use the @code{@@noindent} to inhibit
+paragraph indentation if required (@address@hidden@@noindent}}).
+
address@hidden
+Texinfo supports the usual quotation marks used in English and in
+other languages; see @ref{Inserting Quotation Marks}.
+
address@hidden
address@hidden Multiple dashes in source
address@hidden Dashes in source
address@hidden Hyphens in source, two or three in a row
address@hidden Em dash, producing
address@hidden En dash, producing
+Use three hyphens in a row, @samp{---}, to produce a long dash---like
+this (called an @dfn{em dash}), used for punctuation in sentences.
+Use two hyphens, @samp{--}, to produce a medium dash (called an
address@hidden dash}), used primarily for numeric ranges, as in ``June
+25--26''. Use a single hyphen, @samp{-}, to produce a standard hyphen
+used in compound words. For display on the screen, Info reduces three
+hyphens to two and two hyphens to one (not transitively!). Of course,
+any number of hyphens in the source remain as they are in literal
+contexts, such as @code{@@code} and @code{@@example}.
+
address@hidden
address@hidden Form feed characters
address@hidden @kbd{CTRL-l}
+Form feed (@kbd{CTRL-l}) characters in the input are handled as
+follows:
+
address@hidden @asis
address@hidden PDF/DVI
+In normal text, treated as ending any open paragraph; essentially
+ignored between paragraphs.
+
address@hidden Info
+Output as-is between paragraphs (their most common use); in other
+contexts, they may be treated as regular spaces (and thus consolidated
+with surrounding whitespace).
+
address@hidden HTML
+Written as a numeric entity except contexts where spaces are ignored;
+for example, in @samp{@@address@hidden ^L address@hidden, the form feed is
+ignored.
+
address@hidden XML
+Keep them everywhere; in attributes, escaped as @samp{\f}; also,
address@hidden is escaped as @samp{\\} and newline as @samp{\n}.
+
address@hidden Docbook
+Completely removed, as they are not allowed.
address@hidden table
+
+As you can see, because of these differing requirements of the output
+formats, it's not possible to use form feeds completely portably.
+
address@hidden
address@hidden Tabs; don't use!
address@hidden:} 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.
+
address@hidden
+To avoid this problem, Texinfo mode in GNU Emacs inserts
+multiple spaces when you press the @key{TAB} key. Also, you can run
address@hidden in Emacs to convert tabs in a region to multiple
+spaces, or use the @code{unexpand} command from the shell.
address@hidden itemize
+
+
address@hidden Comments
address@hidden Comments
+
address@hidden Comments
address@hidden comment
address@hidden c @r{(comment)}
+
+You can write comments in a Texinfo file by using the @code{@@comment}
+command, which may be abbreviated to @code{@@c}. Such comments are
+for a person looking at the Texinfo source file. All the text on a
+line that follows either @code{@@comment} or @code{@@c} is a comment;
+the rest of the line does not appear in the visible output.
+
+Often, you can write the @code{@@comment} or @code{@@c} in the middle
+of a line, and only the text that follows after the @code{@@comment}
+or @code{@@c} command does not appear; but some commands, such as
address@hidden@@settitle} and @code{@@setfilename}, work on a whole line. You
+cannot use @code{@@comment} or @code{@@c} within a line beginning with
+such a command.
+
address@hidden DEL @r{(comment character)}
address@hidden Catcode for comments in @TeX{}
+In cases of nested command invocations, complicated macro definitions,
+etc., @code{@@c} and @code{@@comment} may provoke an error when
+processing with @TeX{}. Therefore, you can also use the @kbd{DEL}
+character (ASCII 127 decimal, 0x7f hex, 0177 octal) as a true @TeX{}
+comment character (catcode 14, in @TeX{} internals). Everything on
+the line after the @kbd{DEL} will be ignored.
+
address@hidden Ignored text
address@hidden Unprocessed text
address@hidden ignore
+You can also have long stretches of text to be ignored by the Texinfo
+processors with the @code{@@ignore} and @code{@@end ignore} commands.
+Write each of these commands on a line of its own, starting each
+command at the beginning of the line. Text between these two commands
+does not appear in the processed output. You can use @code{@@ignore}
+and @code{@@end ignore} for writing comments. (For some technical
+caveats regarding nesting of such commands, @pxref{Conditional
+Nesting}.)
+
+
address@hidden Minimum
address@hidden What a Texinfo File Must Have
address@hidden Minimal Texinfo file (requirements)
address@hidden Must have in Texinfo file
address@hidden Required in Texinfo file
address@hidden Texinfo file minimum
+
+By convention, the name of a Texinfo file ends with (in order of
+preference) one of the extensions @file{.texinfo}, @file{.texi},
address@hidden, or @file{.tex}. The longer extensions are preferred
+since they describe more clearly to a human reader the nature of the
+file. The shorter extensions are for operating systems that cannot
+handle long file names.
+
+In order to be made into a good printed manual and other output
+formats, a Texinfo file @emph{must} begin with lines like this:
+
address@hidden
address@hidden
+\input texinfo
+@@setfilename @var{info-file-name}
+@@settitle @var{name-of-manual}
address@hidden group
address@hidden example
+
address@hidden
+The contents of the file follow this beginning, and then you
address@hidden end the Texinfo source with a line like this:
+
address@hidden
+@@bye
address@hidden example
+
address@hidden \input @r{(raw @TeX{} startup)}
address@hidden
+Here's an explanation:
+
address@hidden @bullet
address@hidden
+The @samp{\input texinfo} line tells @TeX{} to use the
address@hidden 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{}.)
+
address@hidden
+The @code{@@setfilename} line provides a name for the Info file and
+tells @TeX{} to open auxiliary files. @strong{All text before
address@hidden@@setfilename} is ignored!}
+
address@hidden
+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 address@hidden Strictly speaking,
address@hidden@@settitle} is optional---if you don't mind your document being
+titled `Untitled'.
+
address@hidden
+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.
address@hidden itemize
+
+If you use Emacs, it is also useful to include mode setting and
+start-of-header and end-of-header lines at the beginning of a Texinfo
+file, like this:
+
address@hidden
address@hidden
+\input texinfo @@c -*-texinfo-*-
+@@c %**start of header
+@@setfilename @var{info-file-name}
+@@settitle @var{name-of-manual}
+@@c %**end of header
address@hidden group
address@hidden example
+
address@hidden
+In the first line, @samp{-*-texinfo-*-} causes Emacs to switch into
+Texinfo mode when you edit the file.
+
+The @code{@@c ...header} lines above which surround the
address@hidden@@setfilename} and @code{@@settitle} lines allow you to process,
+within Emacs, just part of the Texinfo source. (@xref{Start of
+Header}.)
+
+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
+the minimum, which can be useful for short documents, is just the three
+lines at the beginning and the one line at the end.
+
+
address@hidden Six Parts
address@hidden Six Parts of a Texinfo File
+
+Generally, a Texinfo file contains more than the minimal beginning and
+end described in the previous section---it usually contains the six
+parts listed below. These are described fully in the following sections.
+
address@hidden @r
address@hidden 1. Header
+The @dfn{Header} names the file, tells @TeX{} which definitions file to
+use, and other such housekeeping tasks.
+
address@hidden 2. Summary and Copyright
+The @dfn{Summary and Copyright} segment describes the document and
+contains the copyright notice and copying permissions. This is done
+with the @code{@@copying} command.
+
address@hidden 3. Title and Copyright
+The @dfn{Title and Copyright} segment contains the title and copyright
+pages for the printed manual. The segment must be enclosed between
address@hidden@@titlepage} and @code{@@end titlepage} commands. The title and
+copyright page appear only in the printed manual.
+
address@hidden 4. `Top' Node and Master Menu
+The `Top' node starts off the online output; it does not appear in the
+printed manual. We recommend including the copying permissions here as
+well as the segments above. And it contains at least a top-level menu
+listing the chapters, and possibly a @dfn{Master Menu} listing all the
+nodes in the entire document.
+
address@hidden 5. Body
+The @dfn{Body} of the document is typically structured like a
+traditional book or encyclopedia, but it may be free form.
+
address@hidden 6. End
+The @dfn{End} segment may contain commands for printing indices, and
+closes with the @code{@@bye} command on a line of its own.
address@hidden table
+
+
address@hidden Short Sample
address@hidden A Short Sample Texinfo File
address@hidden Sample Texinfo file, with comments
+
+Here is a very short but complete Texinfo file, in the six conventional
+parts enumerated in the previous section, so you can see how Texinfo
+source appears in practice. The first three parts of the file, from
address@hidden texinfo} through to @samp{@@end titlepage}, look more
+intimidating than they are: most of the material is standard
+boilerplate; when writing a manual, you simply change the names as
+appropriate.
+
address@hidden a File}, for full documentation on the commands listed
+here. @xref{GNU Sample Texts}, for the full texts to be used in GNU
+manuals.
+
+In the following, the sample text is @emph{indented}; comments on it are
+not. The complete file, without interspersed comments, is shown in
address@hidden Sample Texinfo File}.
+
address@hidden Part 1: Header
+
address@hidden
+The header does not appear in either the Info file or the
+printed output. It sets various parameters, including the
+name of the Info file and the title used in the header.
+
address@hidden
address@hidden
+\input texinfo @@c -*-texinfo-*-
+@@c %**start of header
+@@setfilename sample.info
+@@settitle Sample Manual 1.0
+@@c %**end of header
address@hidden group
address@hidden example
+
address@hidden Part 2: Summary Description and Copyright
+
address@hidden
+A real manual includes more text here, according to the license under
+which it is distributed. @xref{GNU Sample Texts}.
+
address@hidden
address@hidden
+@@copying
+This is a short example of a complete Texinfo file, version 1.0.
+
+Copyright @@address@hidden@} 2013 Free Software Foundation, Inc.
+@@end copying
address@hidden group
address@hidden example
+
address@hidden Part 3: Titlepage, Contents, Copyright
+
address@hidden
+The titlepage segment does not appear in the online output, only in the
+printed manual. 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
address@hidden@@contents} command generates a table of contents.
+
address@hidden
address@hidden
+@@titlepage
+@@title Sample Title
address@hidden group
+
address@hidden
+@@c The following two commands start the copyright page.
+@@page
+@@vskip 0pt plus 1filll
+@@insertcopying
+@@end titlepage
address@hidden group
+
+@@c Output the table of contents at the beginning.
+@@contents
address@hidden example
+
address@hidden Part 4: `Top' Node and Master Menu
+
address@hidden
+The `Top' node contains the master menu for the Info file. Since the
+printed manual uses a table of contents rather than a menu, it
+excludes the `Top' node. 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.
+
address@hidden
+@@ifnottex
+@@node Top
+@@top Short Sample
+
+This is a short sample Texinfo file.
+@@end ifnottex
+
address@hidden
+@@menu
+* First Chapter:: The first chapter is the
+ only chapter in this sample.
+* Index:: Complete index.
+@@end menu
address@hidden group
address@hidden example
+
+
address@hidden Part 5: The Body of the Document
+
address@hidden
+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.
+
address@hidden
address@hidden
+@@node First Chapter
+@@chapter First Chapter
+
+@@cindex chapter, first
address@hidden group
+
address@hidden
+This is the first chapter.
+@@cindex index entry, another
address@hidden group
+
address@hidden
+Here is a numbered list.
+
+@@enumerate
+@@item
+This is the first item.
+
+@@item
+This is the second item.
+@@end enumerate
address@hidden group
address@hidden example
+
+
address@hidden Part 6: The End of the Document
+
address@hidden
+The end segment contains commands for generating an index in a node and
+unnumbered chapter of its own, and the @code{@@bye} command that marks
+the end of the document.
+
address@hidden
address@hidden
+@@node Index
+@@unnumbered Index
address@hidden group
+
address@hidden
+@@printindex cp
+
+@@bye
address@hidden group
address@hidden example
+
+
address@hidden Some Results
+
+Here is what the contents of the first chapter of the sample look like:
+
address@hidden 1
address@hidden 700
address@hidden
+This is the first chapter.
+
+Here is a numbered list.
+
address@hidden
address@hidden
+This is the first item.
+
address@hidden
+This is the second item.
address@hidden enumerate
address@hidden quotation
+
+
address@hidden History
address@hidden History
+
address@hidden Stallman, Richard M.
address@hidden Chassell, Robert J.
address@hidden Fox, Brian
address@hidden Berry, Karl
+Richard M. Stallman invented the Texinfo format, wrote the initial
+processors, and created Edition 1.0 of this manual. address@hidden
+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
address@hidden and @command{info} programs. Karl Berry has
+continued maintenance since Texinfo 3.8 (manual edition 2.22).
+
address@hidden Pinard, Fran@,{c}ois
address@hidden Schwab, Andreas
address@hidden Weinberg, Zack
address@hidden Weisshaus, Melissa
address@hidden Zaretskii, Eli
address@hidden Zuhn, David D.
+Our thanks go out to all who helped improve this work, particularly
+the indefatigable Eli Zaretskii and Andreas Schwab, who have provided
+patches beyond counting. Fran@,{c}ois Pinard and address@hidden Zuhn,
+tirelessly recorded and reported mistakes and obscurities. Zack
+Weinberg did the impossible by implementing the macro syntax in
address@hidden Thanks to Melissa Weisshaus for her frequent
+reviews of nearly similar editions. Dozens of others have contributed
+patches and suggestions, they are gratefully acknowledged in the
address@hidden file. Our mistakes are our own.
+
address@hidden History of Texinfo
address@hidden Texinfo history
address@hidden Beginnings
+
address@hidden Scribe
address@hidden Reid, Brian
+In the 1970's at CMU, Brian Reid developed a program and format named
+Scribe to mark up documents for printing. It used the @code{@@}
+character to introduce commands, as Texinfo does. Much more
+consequentially, it strove to describe document contents rather than
+formatting, an idea wholeheartedly adopted by Texinfo.
+
address@hidden Bolio
address@hidden address@hidden
+Meanwhile, people at MIT developed another, not too dissimilar format
+called Bolio. This then was converted to using @TeX{} as its typesetting
+language: address@hidden The earliest address@hidden version seems to have
been
+0.02 on October 31, 1984.
+
address@hidden could only be used as a markup language for documents to be
+printed, not for online documents. Richard Stallman (RMS) worked on
+both Bolio and address@hidden He also developed a nifty on-line help format
+called Info, and then combined address@hidden and Info to create Texinfo, a
+mark up language for text that is intended to be read both online and
+as printed hard copy.
+
+Moving forward, the original translator to create Info was written
+(primarily by RMS and Bob Chassell) in Emacs Lisp, namely the
address@hidden and other functions. In the early 1990s,
+Brian Fox reimplemented the conversion program in C, now called
address@hidden
+
address@hidden Reimplementing in Perl
+
address@hidden Cons, Lionel
address@hidden Dumas, Patrice
+In 2012, the C @command{makeinfo} was itself replaced by a Perl
+implementation generically called @command{texi2any}. This version
+supports the same level of output customization as
address@hidden, an independent program originally written by
+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
address@hidden 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
address@hidden
+
+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
+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
+styles, back-end output formats, and all other customizations.
+In more detail:
+
address@hidden @bullet
address@hidden HTML customization. Many GNU and other free software packages
+had been happily using the HTML customization features in
address@hidden for years. Thus, in effect two independent
+implementations of the Texinfo language had developed, and keeping
+them in sync was not simple. Adding the HTML customization possible
+in @command{texi2html} to a C program would have been an
+enormous effort.
+
address@hidden Unicode, and multilingual support generally, especially of east
+Asian languages. Although of course it's perfectly plausible to write
+such support in C, in the particular case of @command{makeinfo}, it
+would have been tantamount to rewriting the entire program. In Perl,
+much of that comes essentially for free.
+
address@hidden Additional back-ends. The @command{makeinfo} code had become
+convoluted to the point where adding a new back-end was quite complex,
+requiring complex interactions with existing back-ends. In contrast,
+our Perl implementation provides a clean tree-based representation for
+all back-ends to work from. People have requested numerous different
+back-ends (@LaTeX{}, the latest (X)HTML, @dots{}), and they will now
+be much more feasible to implement. Which leads to the last item:
+
address@hidden Making contributions easier. In general, due to the cleaner
+structure, the Perl program should be considerably easier than the C
+for anyone to read and contribute to, with the resulting obvious
+benefits.
address@hidden itemize
+
address@hidden Implementation}, for more on the rationale for and
+role of @command{texi2any}.
+
+
address@hidden Texinfo Mode
address@hidden Using Texinfo Mode
address@hidden Texinfo mode
address@hidden Mode, using Texinfo
address@hidden GNU Emacs
address@hidden Emacs
+
+You may edit a Texinfo file with any text editor you choose. A Texinfo
+file is no different from any other ASCII file. However, GNU Emacs
+comes with a special mode, called Texinfo mode, that provides Emacs
+commands and tools to help ease your work.
+
+This chapter describes features of GNU Emacs' Texinfo mode but not any
+features of the Texinfo formatting language. So if you are reading this
+manual straight through from the beginning, you may want to skim through
+this chapter briefly and come back to it after reading succeeding
+chapters which describe the Texinfo formatting language in detail.
+
address@hidden
+* Texinfo Mode Overview:: How Texinfo mode can help you.
+* Emacs Editing:: Texinfo mode adds to GNU Emacs' general
+ purpose editing features.
+* Inserting:: How to insert frequently used @@-commands.
+* Showing the Structure:: How to show the structure of a file.
+* Updating Nodes and Menus:: How to update or create new nodes and menus.
+* 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.
address@hidden menu
+
address@hidden Texinfo Mode Overview
address@hidden Texinfo Mode Overview
+
+Texinfo mode provides special features for working with Texinfo files.
+You can:
+
address@hidden @bullet
address@hidden
+Insert frequently used @@-commands.
+
address@hidden
+Automatically create @code{@@node} lines.
+
address@hidden
+Show the structure of a Texinfo source file.
+
address@hidden
+Automatically create or update the `Next',
+`Previous', and `Up' pointers of a node.
+
address@hidden
+Automatically create or update menus.
+
address@hidden
+Automatically create a master menu.
+
address@hidden
+Format a part or all of a file for Info.
+
address@hidden
+Typeset and print part or all of a file.
address@hidden itemize
+
+Perhaps the two most helpful features are those for inserting frequently
+used @@-commands and for creating node pointers and menus.
+
address@hidden Emacs Editing
address@hidden The Usual GNU Emacs Editing Commands
+
+In most cases, the usual Text mode commands work the same in Texinfo
+mode as they do in Text mode. Texinfo mode adds new editing commands
+and tools to GNU Emacs' general purpose editing features. The major
+difference concerns filling. In Texinfo mode, the paragraph
+separation variable and syntax table are redefined so that Texinfo
+commands that should be on lines of their own are not inadvertently
+included in paragraphs. Thus, the @kbd{M-q} (@code{fill-paragraph})
+command will refill a paragraph but not mix an indexing command on a
+line adjacent to it into the paragraph.
+
+In addition, Texinfo mode sets the @code{page-delimiter} variable to
+the value of @code{texinfo-chapter-level-regexp}; by default, this is
+a regular expression matching the commands for chapters and their
+equivalents, such as appendices. With this value for the page
+delimiter, you can jump from chapter title to chapter title with the
address@hidden ]} (@code{forward-page}) and @kbd{C-x [}
+(@code{backward-page}) commands and narrow to a chapter with the
address@hidden n p} (@code{narrow-to-page}) command. (@xref{Pages, , ,emacs,
+The GNU Emacs Manual}, for details about the page commands.)
+
+You may name a Texinfo file however you wish, but the convention is to
+end a Texinfo file name with one of the extensions
address@hidden, @file{.texi}, @file{.txi}, or @file{.tex}. A longer
+extension is preferred, since it is explicit, but a shorter extension
+may be necessary for operating systems that limit the length of file
+names. GNU Emacs automatically enters Texinfo mode when you visit a
+file with a @file{.texinfo}, @file{.texi} or @file{.txi}
+extension. Also, Emacs switches to Texinfo mode
+when you visit a
+file that has @samp{-*-texinfo-*-} in its first line. If ever you are
+in another mode and wish to switch to Texinfo mode, type @code{M-x
+texinfo-mode}.
+
+Like all other Emacs features, you can customize or enhance Texinfo
+mode as you wish. In particular, the keybindings are very easy to
+change. The keybindings described here are the default or standard
+ones.
+
address@hidden Inserting
address@hidden Inserting Frequently Used Commands
address@hidden Inserting frequently used commands
address@hidden Frequently used commands, inserting
address@hidden Commands, inserting them
+
+Texinfo mode provides commands to insert various frequently used
+@@-commands into the buffer. You can use these commands to save
+keystrokes.
+
+The insert commands are invoked by typing @kbd{C-c} twice and then the
+first letter of the @@-command:
+
address@hidden @kbd
address@hidden C-c C-c c
address@hidden M-x texinfo-insert-@@code
address@hidden texinfo-insert-@@code
+Insert @code{@@address@hidden@}} and put the
+cursor between the braces.
+
address@hidden C-c C-c d
address@hidden M-x texinfo-insert-@@dfn
address@hidden texinfo-insert-@@dfn
+Insert @code{@@address@hidden@}} and put the
+cursor between the braces.
+
address@hidden C-c C-c e
address@hidden M-x texinfo-insert-@@end
address@hidden texinfo-insert-@@end
+Insert @code{@@end} and attempt to insert the correct following word,
+such as @samp{example} or @samp{table}. (This command does not handle
+nested lists correctly, but inserts the word appropriate to the
+immediately preceding list.)
+
address@hidden C-c C-c i
address@hidden M-x texinfo-insert-@@item
address@hidden texinfo-insert-@@item
+Insert @code{@@item} and put the
+cursor at the beginning of the next line.
+
address@hidden C-c C-c k
address@hidden M-x texinfo-insert-@@kbd
address@hidden texinfo-insert-@@kbd
+Insert @code{@@address@hidden@}} and put the
+cursor between the braces.
+
address@hidden C-c C-c n
address@hidden M-x texinfo-insert-@@node
address@hidden texinfo-insert-@@node
+Insert @code{@@node} and a comment line
+listing the sequence for the `Next',
+`Previous', and `Up' nodes.
+Leave point after the @code{@@node}.
+
address@hidden C-c C-c o
address@hidden M-x texinfo-insert-@@noindent
address@hidden texinfo-insert-@@noindent
+Insert @code{@@noindent} and put the
+cursor at the beginning of the next line.
+
address@hidden C-c C-c s
address@hidden M-x texinfo-insert-@@samp
address@hidden texinfo-insert-@@samp
+Insert @code{@@address@hidden@}} and put the
+cursor between the braces.
+
address@hidden C-c C-c t
address@hidden M-x texinfo-insert-@@table
address@hidden texinfo-insert-@@table
+Insert @code{@@table} followed by a @key{SPC}
+and leave the cursor after the @key{SPC}.
+
address@hidden C-c C-c v
address@hidden M-x texinfo-insert-@@var
address@hidden texinfo-insert-@@var
+Insert @code{@@address@hidden@}} and put the
+cursor between the braces.
+
address@hidden C-c C-c x
address@hidden M-x texinfo-insert-@@example
address@hidden texinfo-insert-@@example
+Insert @code{@@example} and put the
+cursor at the beginning of the next line.
+
address@hidden address@hidden was the binding for texinfo-insert-braces;
address@hidden in Emacs 19, backward-paragraph will take this binding.
address@hidden C-c C-c @{
address@hidden M-x texinfo-insert-braces
address@hidden texinfo-insert-braces
+Insert @address@hidden@}} and put the cursor between the braces.
+
address@hidden C-c @}
address@hidden C-c ]
address@hidden M-x up-list
address@hidden up-list
+Move from between a pair of braces forward past the closing brace.
+Typing @kbd{C-c ]} is easier than typing @kbd{C-c @}}, which
+is, however, more mnemonic; hence the two keybindings. (Also, you can
+move out from between braces by typing @kbd{C-f}.)
address@hidden table
+
+To put a command such as @address@hidden@@address@hidden@address@hidden around
an
address@hidden word, position the cursor in front of the word and type
address@hidden 1 C-c C-c c}. This makes it easy to edit existing plain text.
+The value of the prefix argument tells Emacs how many words following
+point to include between address@hidden for one word, @samp{2} for
+two words, and so on. Use a negative argument to enclose the previous
+word or words. If you do not specify a prefix argument, Emacs inserts
+the @@-command string and positions the cursor between the braces. This
+feature works only for those @@-commands that operate on a word or words
+within one line, such as @code{@@kbd} and @code{@@var}.
+
+This set of insert commands was created after analyzing the frequency
+with which different @@-commands are used in the @cite{GNU Emacs
+Manual} and the @cite{GDB Manual}. If you wish to add your own insert
+commands, you can bind a keyboard macro to a key, use abbreviations,
+or extend the code in @file{texinfo.el}.
+
address@hidden texinfo-start-menu-description
address@hidden Menu description, start
address@hidden Description for menu, start
address@hidden C-c C-d} (@code{texinfo-start-menu-description}) is an insert
+command that works differently from the other insert commands. It
+inserts a node's section or chapter title in the space for the
+description in a menu entry line. (A menu entry has three parts, the
+entry name, the node name, and the description. Only the node name is
+required, but a description helps explain what the node is about.
address@hidden Parts, , The Parts of a Menu}.)
+
+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
+can edit it. The function does not insert the title if the menu entry
+line already contains a description.
+
+This command is only an aid to writing descriptions; it does not do the
+whole job. You must edit the inserted text since a title tends to use
+the same words as a node name but a useful description uses different
+words.
+
address@hidden Showing the Structure
address@hidden Showing the Sectioning Structure of a File
address@hidden Showing the sectioning structure of a file
address@hidden Sectioning structure of a file, showing
address@hidden Structure of a file, showing
address@hidden Outline of file structure, showing
address@hidden Contents-like outline of file structure
address@hidden File sectioning structure, showing
address@hidden Texinfo file sectioning structure, showing
+
+You can show the sectioning structure of a Texinfo file by using the
address@hidden C-s} command (@code{texinfo-show-structure}). This command
+lists the lines that begin with the @@-commands for @code{@@chapter},
address@hidden@@section}, and the like. It constructs what amounts to a table
+of contents. These lines are displayed in another buffer called the
address@hidden buffer. In that buffer, you can position the cursor
+over one of the lines and use the @kbd{C-c C-c} command
+(@code{occur-mode-goto-occurrence}), to jump to the corresponding spot
+in the Texinfo file.
+
address@hidden @kbd
address@hidden C-c C-s
address@hidden M-x texinfo-show-structure
address@hidden texinfo-show-structure
+Show the @code{@@chapter}, @code{@@section}, and such lines of a
+Texinfo file.
+
address@hidden C-c C-c
address@hidden M-x occur-mode-goto-occurrence
address@hidden occur-mode-goto-occurrence
+Go to the line in the Texinfo file corresponding to the line under the
+cursor in the @file{*Occur*} buffer.
address@hidden table
+
+If you call @code{texinfo-show-structure} with a prefix argument by
+typing @address@hidden C-c C-s}}, it will list not only those lines with the
+@@-commands for @code{@@chapter}, @code{@@section}, and the like, but
+also the @code{@@node} lines. You can use @code{texinfo-show-structure}
+with a prefix argument to check whether the `Next', `Previous', and `Up'
+pointers of an @code{@@node} line are correct.
+
+Often, when you are working on a manual, you will be interested only
+in the structure of the current chapter. In this case, you can mark
+off the region of the buffer that you are interested in by using the
address@hidden n n} (@code{narrow-to-region}) command and
address@hidden will work on only that region. To see
+the whole buffer again, use @address@hidden n w}} (@code{widen}).
+(@xref{Narrowing, , , emacs, The GNU Emacs Manual}, for more
+information about the narrowing commands.)
+
address@hidden page-delimiter
address@hidden Page delimiter in Texinfo mode
+In addition to providing the @code{texinfo-show-structure} command,
+Texinfo mode sets the value of the page delimiter variable to match
+the chapter-level @@-commands. This enables you to use the @kbd{C-x
+]} (@code{forward-page}) and @kbd{C-x [} (@code{backward-page})
+commands to move forward and backward by chapter, and to use the
address@hidden n p} (@code{narrow-to-page}) command to narrow to a chapter.
address@hidden, , , emacs, The GNU Emacs Manual}, for more information
+about the page commands.
+
+
address@hidden Updating Nodes and Menus
address@hidden Updating Nodes and Menus
+
address@hidden Updating nodes and menus
address@hidden Create nodes, menus automatically
address@hidden Insert nodes, menus automatically
address@hidden Automatically insert nodes, menus
+
+Texinfo mode provides commands for automatically creating or updating
+menus and node pointers. The commands are called ``update'' commands
+because their most frequent use is for updating a Texinfo file after you
+have worked on it; but you can use them to insert the `Next',
+`Previous', and `Up' pointers into an @code{@@node} line that has none
+and to create menus in a file that has none.
+
+If you do not use any updating commands, you need to write menus and
+node pointers by hand, which is a tedious task.
+
address@hidden
+* Updating Commands:: Five major updating commands.
+* Updating Requirements:: How to structure a Texinfo file for
+ using the updating command.
+* Other Updating Commands:: How to indent descriptions, insert
+ missing nodes lines, and update
+ nodes in sequence.
address@hidden menu
+
address@hidden Updating Commands
address@hidden The Updating Commands
+
+You can use the updating commands to:
+
address@hidden @bullet
address@hidden
+insert or update the `Next', `Previous', and `Up' pointers of a node,
+
address@hidden
+insert or update the menu for a section, and
+
address@hidden
+create a master menu for a Texinfo source file.
address@hidden itemize
+
+You can also use the commands to update all the nodes and menus in a
+region or in a whole Texinfo file.
+
+The updating commands work only with conventional Texinfo files, which
+are structured hierarchically like books. In such files, a structuring
+command line must follow closely after each @code{@@node} line, except
+for the `Top' @code{@@node} line. (A @dfn{structuring command line} is
+a line beginning with @code{@@chapter}, @code{@@section}, or other
+similar command.)
+
+You can write the structuring command line on the line that follows
+immediately after an @code{@@node} line or else on the line that
+follows after a single @code{@@comment} line or a single
address@hidden@@ifinfo} line. You cannot interpose more than one line between
+the @code{@@node} line and the structuring command line; and you may
+interpose only an @code{@@comment} line or an @code{@@ifinfo} line.
+
+Commands which work on a whole buffer require that the `Top' node be
+followed by a node with an @code{@@chapter} or equivalent-level command.
+The menu updating commands will not create a main or master menu for a
+Texinfo file that has only @code{@@chapter}-level nodes! The menu
+updating commands only create menus @emph{within} nodes for lower level
+nodes. To create a menu of chapters, you must provide a `Top'
+node.
+
+The menu updating commands remove menu entries that refer to other Info
+files since they do not refer to nodes within the current buffer. This
+is a deficiency. Rather than use menu entries, you can use cross
+references to refer to other Info files. None of the updating commands
+affect cross references.
+
+Texinfo mode has five updating commands that are used most often: two
+are for updating the node pointers or menu of a single node (or a
+region); two are for updating every node pointer and menu in a file;
+and one, the @code{texinfo-master-menu} command, is for creating a
+master menu for a complete file, and optionally, for updating every
+node and menu in the whole Texinfo file.
+
+The @code{texinfo-master-menu} command is the primary command:
+
address@hidden @kbd
address@hidden C-c C-u m
address@hidden M-x texinfo-master-menu
address@hidden texinfo-master-menu
+Create or update a master menu that includes all the other menus
+(incorporating the descriptions from pre-existing menus, if
+any).
+
+With an argument (prefix argument, @kbd{C-u,} if interactive), first create or
+update all the nodes and all the regular menus in the buffer before
+constructing the master menu. (@xref{The Top Node, , The Top Node and
+Master Menu}, for more about a master menu.)
+
+For @code{texinfo-master-menu} to work, the Texinfo file must have a
+`Top' node and at least one subsequent node.
+
+After extensively editing a Texinfo file, you can type the following:
+
address@hidden
+C-u M-x texinfo-master-menu
address@hidden or
+C-u C-c C-u m
address@hidden example
+
address@hidden
+This updates all the nodes and menus completely and all at once.
address@hidden table
+
+The other major updating commands do smaller jobs and are designed for
+the person who updates nodes and menus as he or she writes a Texinfo
+file.
+
address@hidden 1000
+The commands are:
+
address@hidden @kbd
address@hidden C-c C-u C-n
address@hidden M-x texinfo-update-node
address@hidden texinfo-update-node
+Insert the `Next', `Previous', and `Up' pointers for the node that point is
+within (i.e., for the @code{@@node} line preceding point). If the
address@hidden@@node} line has pre-existing `Next', `Previous', or `Up'
+pointers in it, the old pointers are removed and new ones inserted.
+With an argument (prefix argument, @kbd{C-u}, if interactive), this command
+updates all @code{@@node} lines in the region (which is the text
+between point and mark).
+
address@hidden C-c C-u C-m
address@hidden M-x texinfo-make-menu
address@hidden texinfo-make-menu
+Create or update the menu in the node that point is within.
+With an argument (@kbd{C-u} as prefix argument, if
+interactive), the command makes or updates menus for the
+nodes which are either within or a part of the
+region.
+
+Whenever @code{texinfo-make-menu} updates an existing menu, the
+descriptions from that menu are incorporated into the new menu. This
+is done by copying descriptions from the existing menu to the entries
+in the new menu that have the same node names. If the node names are
+different, the descriptions are not copied to the new menu.
+
address@hidden C-c C-u C-e
address@hidden M-x texinfo-every-node-update
address@hidden texinfo-every-node-update
+Insert or update the `Next', `Previous', and `Up' pointers for every
+node in the buffer.
+
address@hidden C-c C-u C-a
address@hidden M-x texinfo-all-menus-update
address@hidden texinfo-all-menus-update
+Create or update all the menus in the buffer. With an argument
+(@kbd{C-u} as prefix argument, if interactive), first insert
+or update all the node
+pointers before working on the menus.
+
+If a master menu exists, the @code{texinfo-all-menus-update} command
+updates it; but the command does not create a new master menu if none
+already exists. (Use the @code{texinfo-master-menu} command for
+that.)
+
+When working on a document that does not merit a master menu, you can
+type the following:
+
address@hidden
+C-u C-c C-u C-a
address@hidden or
+C-u M-x texinfo-all-menus-update
address@hidden example
+
address@hidden
+This updates all the nodes and menus.
address@hidden table
+
+The @code{texinfo-column-for-description} variable specifies the
+column to which menu descriptions are indented. By default, the value
+is 32 although it can be useful to reduce it to as low as 24. You
+can set the variable via customization (@pxref{Changing an Option,,,
+emacs, The GNU Emacs Manual}) or with the @kbd{M-x set-variable}
+command (@pxref{Examining, , Examining and Setting Variables, emacs,
+The GNU Emacs Manual}).
+
+Also, the @code{texinfo-indent-menu-description} command may be used to
+indent existing menu descriptions to a specified column. Finally, if
+you wish, you can use the @code{texinfo-insert-node-lines} command to
+insert missing @code{@@node} lines into a file. (@xref{Other Updating
+Commands}, for more information.)
+
address@hidden Updating Requirements
address@hidden Updating Requirements
address@hidden Updating requirements
address@hidden Requirements for updating commands
+
+To use the updating commands, you must organize the Texinfo file
+hierarchically with chapters, sections, subsections, and the like.
+When you construct the hierarchy of the manual, do not `jump down'
+more than one level at a time: you can follow the `Top' node with a
+chapter, but not with a section; you can follow a chapter with a
+section, but not with a subsection. However, you may `jump up' any
+number of levels at one time---for example, from a subsection to a
+chapter.
+
+Each @code{@@node} line, with the exception of the line for the `Top'
+node, must be followed by a line with a structuring command such as
address@hidden@@chapter}, @code{@@section}, or
address@hidden@@unnumberedsubsec}.
+
+Each @code{@@node} line/structuring-command line combination
+must look either like this:
+
address@hidden
address@hidden
+@@node Comments, Minimum, Conventions, Overview
+@@comment node-name, next, previous, up
+@@section Comments
address@hidden group
address@hidden example
+
+or like this (without the @code{@@comment} line):
+
address@hidden
address@hidden
+@@node Comments, Minimum, Conventions, Overview
+@@section Comments
address@hidden group
address@hidden example
+
+or like this (without the explicit node pointers):
+
address@hidden
address@hidden
+@@node Comments
+@@section Comments
address@hidden group
address@hidden example
+
address@hidden
+In this example, `Comments' is the name of both the node and the
+section. The next node is called `Minimum' and the previous node is
+called `Conventions'. The `Comments' section is within the `Overview'
+node, which is specified by the `Up' pointer. (Instead of an
address@hidden@@comment} line, you may also write an @code{@@ifinfo} line.)
+
+If a file has a `Top' node, it must be called @samp{top} or @samp{Top}
+and be the first node in the file.
+
+The menu updating commands create a menu of sections within a chapter,
+a menu of subsections within a section, and so on. This means that
+you must have a `Top' node if you want a menu of chapters.
+
+Incidentally, the @code{makeinfo} command will create an Info file for a
+hierarchically organized Texinfo file that lacks `Next', `Previous' and
+`Up' pointers. Thus, if you can be sure that your Texinfo file will be
+formatted with @code{makeinfo}, you have no need for the update node
+commands. (@xref{Creating an Info File}, for more information about
address@hidden) However, both @code{makeinfo} and the
address@hidden@dots{}} commands require that you insert menus in
+the file.
+
+
address@hidden Other Updating Commands
address@hidden Other Updating Commands
+
+In addition to the five major updating commands, Texinfo mode
+possesses several less frequently used updating commands:
+
address@hidden @kbd
address@hidden M-x texinfo-insert-node-lines
address@hidden texinfo-insert-node-lines
+Insert @code{@@node} lines before the @code{@@chapter},
address@hidden@@section}, and other sectioning commands wherever they are
+missing throughout a region in a Texinfo file.
+
+With an argument (@kbd{C-u} as prefix argument, if interactive), the
address@hidden command not only inserts
address@hidden@@node} lines but also inserts the chapter or section titles as
+the names of the corresponding nodes. In addition, it inserts the
+titles as node names in pre-existing @code{@@node} lines that lack
+names. Since node names should be more concise than section or
+chapter titles, you must manually edit node names so inserted.
+
+For example, the following marks a whole buffer as a region and inserts
address@hidden@@node} lines and titles throughout:
+
address@hidden
+C-x h C-u M-x texinfo-insert-node-lines
address@hidden example
+
+This command inserts titles as node names in @code{@@node} lines; the
address@hidden command (@pxref{Inserting,
+Inserting Frequently Used Commands}) inserts titles as descriptions in
+menu entries, a different action. However, in both cases, you need to
+edit the inserted text.
+
address@hidden M-x texinfo-multiple-files-update
address@hidden texinfo-multiple-files-update @r{(in brief)}
+Update nodes and menus in a document built from several separate files.
+With @kbd{C-u} as a prefix argument, create and insert a master menu in
+the outer file. With a numeric prefix argument, such as @kbd{C-u 2}, first
+update all the menus and all the `Next', `Previous', and `Up' pointers
+of all the included files before creating and inserting a master menu in
+the outer file. The @code{texinfo-multiple-files-update} command is
+described in the appendix on @code{@@include} files.
address@hidden@t{texinfo-multiple-files-update}}.
+
address@hidden M-x texinfo-indent-menu-description
address@hidden texinfo-indent-menu-description
+Indent every description in the menu following point to the specified
+column. You can use this command to give yourself more space for
+descriptions. With an argument (@kbd{C-u} as prefix argument, if
+interactive), the @code{texinfo-indent-menu-description} command indents
+every description in every menu in the region. However, this command
+does not indent the second and subsequent lines of a multi-line
+description.
+
address@hidden M-x texinfo-sequential-node-update
address@hidden texinfo-sequential-node-update
+Insert the names of the nodes immediately following and preceding the
+current node as the `Next' or `Previous' pointers regardless of those
+nodes' hierarchical level. This means that the `Next' node of a
+subsection may well be the next chapter. Sequentially ordered nodes are
+useful for novels and other documents that you read through
+sequentially. (However, in Info, the @kbd{g *} command lets
+you look through the file sequentially, so sequentially ordered nodes
+are not strictly necessary.) With an argument (prefix argument, if
+interactive), the @code{texinfo-sequential-node-update} command
+sequentially updates all the nodes in the region.
address@hidden table
+
address@hidden Info Formatting
address@hidden Formatting for Info
address@hidden Formatting for Info
address@hidden Running an Info formatter
address@hidden Info formatting
+
+Texinfo mode provides several commands for formatting part or all of a
+Texinfo file for Info. Often, when you are writing a document, you
+want to format only part of a file---that is, a region.
+
+You can use either the @code{texinfo-format-region} or the
address@hidden command to format a region:
+
address@hidden @kbd
address@hidden texinfo-format-region
address@hidden C-c C-e C-r
address@hidden M-x texinfo-format-region
address@hidden C-c C-m C-r
address@hidden M-x makeinfo-region
+Format the current region for Info.
address@hidden table
+
+You can use either the @code{texinfo-format-buffer} or the
address@hidden command to format a whole buffer:
+
address@hidden @kbd
address@hidden texinfo-format-buffer
address@hidden C-c C-e C-b
address@hidden M-x texinfo-format-buffer
address@hidden C-c C-m C-b
address@hidden M-x makeinfo-buffer
+Format the current buffer for Info.
address@hidden table
+
address@hidden 1000
+For example, after writing a Texinfo file, you can type the following:
+
address@hidden
+C-u C-c C-u m
address@hidden or
+C-u M-x texinfo-master-menu
address@hidden example
+
address@hidden
+This updates all the nodes and menus. Then type the following to create
+an Info file:
+
address@hidden
+C-c C-m C-b
address@hidden or
+M-x makeinfo-buffer
address@hidden example
+
+For @TeX{} or the Info formatting commands to work, the file @emph{must}
+include a line that has @code{@@setfilename} in its header.
+
address@hidden an Info File}, for details about Info formatting.
+
address@hidden Printing
address@hidden node-name, next, previous, up
address@hidden Printing
address@hidden Formatting for printing
address@hidden Printing a region or buffer
address@hidden Region formatting and printing
address@hidden Buffer formatting and printing
address@hidden Part of file formatting and printing
+
+Typesetting and printing a Texinfo file is a multi-step process in
+which you first create a file for printing (called a DVI file), and
+then print the file. Optionally, you may also create indices. To do
+this, you must run the @code{texindex} command after first running the
address@hidden typesetting command; and then you must run the @code{tex}
+command again. Or else run the @code{texi2dvi} command which
+automatically creates indices as needed (@pxref{Format with
address@hidden).
+
+Often, when you are writing a document, you want to typeset and print
+only part of a file to see what it will look like. You can use the
address@hidden and related commands for this purpose. Use
+the @code{texinfo-tex-buffer} command to format all of a
+buffer.
+
address@hidden @kbd
address@hidden C-c C-t C-b
address@hidden M-x texinfo-tex-buffer
address@hidden texinfo-tex-buffer
+Run @code{texi2dvi} on the buffer. In addition to running @TeX{} on the
+buffer, this command automatically creates or updates indices as
+needed.
+
address@hidden C-c C-t C-r
address@hidden M-x texinfo-tex-region
address@hidden texinfo-tex-region
+Run @TeX{} on the region.
+
address@hidden C-c C-t C-i
address@hidden M-x texinfo-texindex
+Run @code{texindex} to sort the indices of a Texinfo file formatted with
address@hidden The @code{texinfo-tex-region} command does
+not run @code{texindex} automatically; it only runs the @code{tex}
+typesetting command. You must run the @code{texinfo-tex-region} command
+a second time after sorting the raw index files with the @code{texindex}
+command. (Usually, you do not format an index when you format a region,
+only when you format a buffer. Now that the @code{texi2dvi} command
+exists, there is little or no need for this command.)
+
address@hidden C-c C-t C-p
address@hidden M-x texinfo-tex-print
address@hidden texinfo-tex-print
+Print the file (or the part of the file) previously formatted with
address@hidden or @code{texinfo-tex-region}.
address@hidden table
+
+For @code{texinfo-tex-region} or @code{texinfo-tex-buffer} to work, the
+file @emph{must} start with a @samp{\input texinfo} line and must
+include an @code{@@settitle} line. The file must end with @code{@@bye}
+on a line by itself. (When you use @code{texinfo-tex-region}, you must
+surround the @code{@@settitle} line with start-of-header and
+end-of-header lines.)
+
address@hidden, for a description of the other @TeX{} related
+commands, such as @code{tex-show-print-queue}.
+
address@hidden Texinfo Mode Summary
address@hidden Texinfo Mode Summary
+
+In Texinfo mode, each set of commands has default keybindings that
+begin with the same keys. All the commands that are custom-created
+for Texinfo mode begin with @kbd{C-c}. The keys are somewhat
+mnemonic.
+
address@hidden Insert Commands
+
+The insert commands are invoked by typing @kbd{C-c} twice and then the
+first letter of the @@-command to be inserted. (It might make more
+sense mnemonically to use @kbd{C-c C-i}, for `custom insert', but
address@hidden C-c} is quick to type.)
+
address@hidden
+C-c C-c c @r{Insert} @samp{@@code}.
+C-c C-c d @r{Insert} @samp{@@dfn}.
+C-c C-c e @r{Insert} @samp{@@end}.
+C-c C-c i @r{Insert} @samp{@@item}.
+C-c C-c n @r{Insert} @samp{@@node}.
+C-c C-c s @r{Insert} @samp{@@samp}.
+C-c C-c v @r{Insert} @samp{@@var}.
+C-c @{ @r{Insert braces.}
+C-c ]
+C-c @} @r{Move out of enclosing braces.}
+
address@hidden
+C-c C-c C-d @r{Insert a node's section title}
+ @r{in the space for the description}
+ @r{in a menu entry line.}
address@hidden group
address@hidden example
+
address@hidden Show Structure
+
+The @code{texinfo-show-structure} command is often used within a
+narrowed region.
+
address@hidden
+C-c C-s @r{List all the headings.}
address@hidden example
+
address@hidden The Master Update Command
+
+The @code{texinfo-master-menu} command creates a master menu; and can
+be used to update every node and menu in a file as well.
+
address@hidden Probably should use @tables in this section.
address@hidden
address@hidden
+C-c C-u m
+M-x texinfo-master-menu
+ @r{Create or update a master menu.}
address@hidden group
+
address@hidden
+C-u C-c C-u m @r{With @kbd{C-u} as a prefix argument, first}
+ @r{create or update all nodes and regular}
+ @r{menus, and then create a master menu.}
address@hidden group
address@hidden example
+
address@hidden Update Pointers
+
+The update pointer commands are invoked by typing @kbd{C-c C-u} and
+then either @kbd{C-n} for @code{texinfo-update-node} or @kbd{C-e} for
address@hidden
+
address@hidden
+C-c C-u C-n @r{Update a node.}
+C-c C-u C-e @r{Update every node in the buffer.}
address@hidden example
+
address@hidden Update Menus
+
+Invoke the update menu commands by typing @kbd{C-c C-u}
+and then either @kbd{C-m} for @code{texinfo-make-menu} or
address@hidden for @code{texinfo-all-menus-update}. To update
+both nodes and menus at the same time, precede @kbd{C-c C-u
+C-a} with @kbd{C-u}.
+
address@hidden
+C-c C-u C-m @r{Make or update a menu.}
+
address@hidden
+C-c C-u C-a @r{Make or update all}
+ @r{menus in a buffer.}
address@hidden group
+
address@hidden
+C-u C-c C-u C-a @r{With @kbd{C-u} as a prefix argument,}
+ @r{first create or update all nodes and}
+ @r{then create or update all menus.}
address@hidden group
address@hidden example
+
address@hidden Format for Info
+
+The Info formatting commands that are written in Emacs Lisp are
+invoked by typing @kbd{C-c C-e} and then either @kbd{C-r} for a region
+or @kbd{C-b} for the whole buffer.
+
+The Info formatting commands that are written in C and based on the
address@hidden program are invoked by typing @kbd{C-c C-m} and then
+either @kbd{C-r} for a region or @kbd{C-b} for the whole buffer.
+
address@hidden 800
address@hidden
+Use the @address@hidden commands:
+
address@hidden
address@hidden
+C-c C-e C-r @r{Format the region.}
+C-c C-e C-b @r{Format the buffer.}
address@hidden group
address@hidden example
+
address@hidden 750
address@hidden
+Use @code{makeinfo}:
+
address@hidden
+C-c C-m C-r @r{Format the region.}
+C-c C-m C-b @r{Format the buffer.}
+C-c C-m C-l @r{Recenter the @code{makeinfo} output buffer.}
+C-c C-m C-k @r{Kill the @code{makeinfo} formatting job.}
address@hidden example
+
address@hidden Typeset and Print
+
+The @TeX{} typesetting and printing commands are invoked by typing
address@hidden C-t} and then another control command: @kbd{C-r} for
address@hidden, @kbd{C-b} for @code{texinfo-tex-buffer},
+and so on.
+
address@hidden
+C-c C-t C-r @r{Run @TeX{} on the region.}
+C-c C-t C-b @r{Run} @code{texi2dvi} @r{on the buffer.}
+C-c C-t C-i @r{Run} @code{texindex}.
+C-c C-t C-p @r{Print the DVI file.}
+C-c C-t C-q @r{Show the print queue.}
+C-c C-t C-d @r{Delete a job from the print queue.}
+C-c C-t C-k @r{Kill the current @TeX{} formatting job.}
+C-c C-t C-x @r{Quit a currently stopped @TeX{} formatting job.}
+C-c C-t C-l @r{Recenter the output buffer.}
address@hidden example
+
address@hidden Other Updating Commands
+
+The remaining updating commands do not have standard keybindings because
+they are rarely used.
+
address@hidden
address@hidden
+M-x texinfo-insert-node-lines
+ @r{Insert missing @code{@@node} lines in region.}
+ @r{With @kbd{C-u} as a prefix argument,}
+ @r{use section titles as node names.}
address@hidden group
+
address@hidden
+M-x texinfo-multiple-files-update
+ @r{Update a multi-file document.}
+ @r{With @kbd{C-u 2} as a prefix argument,}
+ @r{create or update all nodes and menus}
+ @r{in all included files first.}
address@hidden group
+
address@hidden
+M-x texinfo-indent-menu-description
+ @r{Indent descriptions.}
address@hidden group
+
address@hidden
+M-x texinfo-sequential-node-update
+ @r{Insert node pointers in strict sequence.}
address@hidden group
address@hidden example
+
+
address@hidden Beginning a File
address@hidden Beginning a Texinfo File
address@hidden Beginning a Texinfo file
address@hidden Texinfo file beginning
address@hidden File beginning
+
+Certain pieces of information must be provided at the beginning of a
+Texinfo file, such as the name for the output file(s), the title of the
+document, and the Top node. A table of contents is also generally
+produced here.
+
+This chapter expands on the minimal complete Texinfo source file
+previously given (@pxref{Six Parts}). It describes the numerous
+commands for handling the traditional frontmatter items in Texinfo.
+
address@hidden 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.
+
address@hidden
+* 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.
address@hidden menu
+
+
address@hidden Sample Beginning
address@hidden Sample Texinfo File Beginning
+
address@hidden 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.
+
address@hidden Sample Texts}, for the full texts to be used in GNU manuals.
+
address@hidden
+\input texinfo @@c -*-texinfo-*-
+@@c %**start of header
+@@setfilename @var{infoname}.info
+@@settitle @var{name-of-manual} @var{version}
+@@c %**end of header
+
+@@copying
+This manual is for @var{program}, version @var{version}.
+
+Copyright @@address@hidden@} @var{years} @var{copyright-owner}.
+
address@hidden
+@@quotation
+Permission is granted to @dots{}
+@@end quotation
+@@end copying
address@hidden group
+
address@hidden
+@@titlepage
+@@title @var{name-of-manual-when-printed}
+@@subtitle @var{subtitle-if-any}
+@@subtitle @var{second-subtitle}
+@@author @var{author}
address@hidden group
+
address@hidden
+@@c The following two commands
+@@c start the copyright page.
+@@page
+@@vskip 0pt plus 1filll
+@@insertcopying
address@hidden 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
+
address@hidden
+@@menu
+* First Chapter:: Getting started @dots{}
+* Second Chapter:: @dots{}
+ @dots{}
+* Copying:: Your rights and freedoms.
+@@end menu
address@hidden group
+
address@hidden
+@@node First Chapter
+@@chapter First Chapter
+
+@@cindex first chapter
+@@cindex chapter, first
address@hidden
address@hidden group
address@hidden example
+
+
address@hidden Texinfo File Header
address@hidden Texinfo File Header
address@hidden Header for Texinfo files
address@hidden Texinfo file header
+
+Texinfo files start with at least three lines that provide Texinfo
+translators with necessary information. These are the @code{\input
+texinfo} line, the @code{@@settitle} line, and the
address@hidden@@setfilename} line.
+
+Also, if you want to format just part of the Texinfo file in Emacs,
+you must write the @code{@@settitle} and @code{@@setfilename} lines
+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} (@address@hidden@@synindex}}),
+for instance, is another command often included in the header.
+
+Thus, the beginning of a Texinfo file generally looks approximately
+like this:
+
address@hidden
address@hidden
+\input texinfo @@c -*-texinfo-*-
+@@c %**start of header
+@@setfilename sample.info
+@@settitle Sample Manual 1.0
+@@c %**end of header
address@hidden group
address@hidden example
+
+(@xref{GNU Sample Texts}, for complete sample texts.)
+
address@hidden
+* First Line:: The first line of a Texinfo file.
+* Start of Header:: Formatting a region requires this.
+* @t{@@setfilename}:: Tell Info the name of the Info file.
+* @t{@@settitle}:: Create a title for the printed work.
+* End of Header:: Formatting a region requires this.
address@hidden menu
+
+
address@hidden First Line
address@hidden The First Line of a Texinfo File
address@hidden First line of a Texinfo file
address@hidden Beginning line of a Texinfo file
address@hidden Header of a Texinfo file
+
+Every Texinfo file that is to be the top-level input to @TeX{} must begin
+with a line that looks like this:
+
address@hidden
+\input texinfo @@c -*-texinfo-*-
address@hidden example
+
address@hidden
+This line serves two functions:
+
address@hidden
address@hidden
+When the file is processed by @TeX{}, the @samp{\input texinfo} command
+tells @TeX{} to load the macros needed for processing a Texinfo file.
+These are in a file called @file{texinfo.tex}, which should have been
+installed on your system along with either the @TeX{} or Texinfo
+software. @TeX{} uses the backslash, @samp{\}, to mark the beginning of
+a command, exactly as Texinfo uses @samp{@@}. The @file{texinfo.tex}
+file causes the switch from @samp{\} to @samp{@@}; before the switch
+occurs, @TeX{} requires @samp{\}, which is why it appears at the
+beginning of the file.
+
address@hidden
+When the file is edited in GNU Emacs, the @samp{-*-texinfo-*-} mode
+specification tells Emacs to use Texinfo mode.
address@hidden enumerate
+
+
address@hidden Start of Header
address@hidden Start of Header
address@hidden Start of header line
+
+A start-of-header line is a Texinfo comment that looks like this:
+
address@hidden
+@@c %**start of header
address@hidden example
+
+Write the start-of-header line on the second line of a Texinfo file.
+Follow the start-of-header line with @code{@@setfilename} and
address@hidden@@settitle} lines and, optionally, with other commands that
+globally affect the document formatting, such as @code{@@synindex} or
address@hidden@@footnotestyle}; and then by an end-of-header line (@pxref{End of
+Header}).
+
+The start- and end-of-header lines allow you to format only part of a
+Texinfo file for Info or printing. @address@hidden commands}.
+
+The odd string of characters, @samp{%**}, is to ensure that no other
+comment is accidentally taken for a start-of-header line. You can
+change it if you wish by setting the @code{tex-start-of-header} and/or
address@hidden Emacs variables. @xref{Texinfo Mode Printing}.
+
+
address@hidden @t{@@setfilename}
address@hidden @code{@@setfilename}: Set the Output File Name
+
address@hidden@c old name
address@hidden setfilename
address@hidden Texinfo requires @code{@@setfilename}
address@hidden Output file name, required
+
+The first Texinfo command (that is, after the @code{\input texinfo})
+in a document is generally @code{@@setfilename}:
+
address@hidden
+@@setfilename @var{info-file-name}
address@hidden example
+
+This command is required for @TeX{}, and very strongly recommended for
address@hidden
+
+Write the @code{@@setfilename} command at the beginning of a line and
+follow it on the same line by the Info file name. Do not write
+anything else on the line.
+
address@hidden Ignored before @code{@@setfilename}
address@hidden @samp{\input} source line ignored
+When an @code{@@setfilename} line is present, the Texinfo processors
+ignore everything written before the @code{@@setfilename} line. This
+is why the very first line of the file (the @code{\input} line) does
+not show up in the output.
+
+The @code{@@setfilename} line specifies the name of the output file to
+be generated. This name must be different from the name of the
+Texinfo file. There are two conventions for choosing the name: you
+can either remove the extension (such as @samp{.texi}) entirely from
+the input file name, or (recommended) replace it with the @samp{.info}
+extension.
+
address@hidden Length of file names
address@hidden File name collision
address@hidden Info file name, choosing
+Although an explicit @samp{.info} extension is preferable, some
+operating systems cannot handle long file names. You can run into a
+problem even when the file name you specify is itself short enough.
+This occurs because the Info formatters split a long Info file into
+short indirect subfiles, and name them by appending @samp{-1},
address@hidden, @dots{}, @samp{-10}, @samp{-11}, and so on, to the original
+file name. (@xref{Tag and Split Files}.) The subfile name
address@hidden, for example, is too long for old systems with
+a 14-character limit on filenames; so the Info file name for this
+document is @file{texinfo} rather than @file{texinfo.info}. When
address@hidden is running on operating systems such as MS-DOS which
+impose severe limits on file names, it may remove some characters from
+the original file name to leave enough space for the subfile suffix,
+thus producing files named @file{texin-10}, @file{gcc.i12}, etc.
+
+When producing another output format, @code{makeinfo} will replace any
+final extension with the output format-specific extension (@samp{html}
+when generating HTML, for example), or add a dot followed by the
+extension (@samp{.html} for HTML) if the given name has no extension.
+
address@hidden texinfo.cnf
+The @code{@@setfilename} line produces no output when you typeset a
+manual with @TeX{}, but it is nevertheless essential: it opens the
+index and other auxiliary files used by Texinfo, and also reads
address@hidden if that file is present on your system
+(@pxref{Preparing for @TeX{}}).
+
+If there is no @code{@@setfilename} line, @code{makeinfo} uses the
+input file name to determine the output name: first, any of the
+extensions @code{.texi}, @code{.tex}, @code{.txi} or @code{.texinfo}
+is removed from the input file name; then, the output format specific
+extension is address@hidden when generating HTML, @code{.info}
+when generating Info, etc. The @code{\input} line is still ignored in
+this processing, as well as leading blank lines.
+
+See also the @option{--output} option in @ref{Invoking @t{texi2any}}.
+
+
address@hidden @t{@@settitle}
address@hidden @code{@@settitle}: Set the Document Title
+
address@hidden@c old name
address@hidden settitle
address@hidden Document title, specifying
+
+A Texinfo file should contain a line that looks like this:
+
address@hidden
+@@settitle @var{title}
address@hidden example
+
+Write the @code{@@settitle} command at the beginning of a line and
+follow it on the same line by the title. Do not write anything else
+on the line. The @code{@@settitle} command should precede everything
+that generates actual output. The best place for it is right after
+the @code{@@setfilename} command (described in the previous section).
+
+This command tells @TeX{} the title to use in a header or footer
+for double-sided output, in case such headings are output. For
+more on headings for @TeX{}, see @ref{Heading Generation}.
+
address@hidden @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
+(@address@hidden@@documentdescription}}).
+
+When the title page is used in the output, the title in the
address@hidden@@settitle} command does not affect the title as it appears on
+the title page. Thus, the two do not need not match exactly. A
+practice we recommend is to include the version or edition number of
+the manual in the @code{@@settitle} title; on the title page, the
+version number generally appears as an @code{@@subtitle} so it would
+be omitted from the @code{@@title}. @address@hidden@@titlepage}}.
+
+
address@hidden End of Header
address@hidden End of Header
address@hidden End of header line
+
+Follow the header lines with an @w{end-of-header} line, which is a
+Texinfo comment that looks like this:
+
address@hidden
+@@c %**end of header
address@hidden example
+
address@hidden of Header}.
+
+
address@hidden Document Permissions
address@hidden Document Permissions
address@hidden Document Permissions
address@hidden Copying Permissions
+
+The copyright notice and copying permissions for a document need to
+appear in several places in the various Texinfo output formats.
+Therefore, Texinfo provides a command (@code{@@copying}) to declare
+this text once, and another command (@code{@@insertcopying}) to
+insert the text at appropriate points.
+
address@hidden Copying address@hidden 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
+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 address@hidden It is helpful to state the license of
+the software of the manual, but giving the complete text of the
+software license is not necessarily required.
+
address@hidden
+* @t{@@copying}:: Declare the document's copying
permissions.
+* @t{@@insertcopying}:: Where to insert the permissions.
address@hidden menu
+
+
address@hidden @t{@@copying}
address@hidden @code{@@copying}: Declare Copying Permissions
+
address@hidden@c old name
address@hidden copying
+
+The @code{@@copying} command should be given very early in the document;
+the recommended location is right after the header material
+(@pxref{Texinfo File Header}). It conventionally consists of a sentence
+or two about what the program is, identification of the documentation
+itself, the legal copyright line, and the copying permissions. Here is
+a skeletal example:
+
address@hidden
+@@copying
+This manual is for @var{program} (version @var{version}, updated
address@hidden), which @dots{}
+
+Copyright @@address@hidden@} @var{years} @var{copyright-owner}.
+
+@@quotation
+Permission is granted to @dots{}
+@@end quotation
+@@end copying
address@hidden example
+
+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, and XML 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.
+
address@hidden copyright
+The @code{@@address@hidden@}} command generates a @samp{c} inside a
+circle when the output format supports this glyph (print and HTML
+always do, for instance). When the glyph is not supported in the
+output, it generates the three-character sequence @samp{(C)}.
+
+The copyright notice itself has the following legally-prescribed
+form:
+
address@hidden
+Copyright @copyright{} @var{years} @var{copyright-owner}.
address@hidden example
+
address@hidden Copyright word, always in English
+The word `Copyright' must always be written in English, even if the
+document is otherwise written in another language. This is due to
+international law.
+
address@hidden Years, in copyright line
+The list of years should include all years in which a version was
+completed (even if it was released in a subsequent year). It is
+simplest for each year to be written out individually and in full,
+separated by commas.
+
address@hidden Copyright holder for FSF works
address@hidden Holder of copyright for FSF works
address@hidden Owner of copyright for FSF works
+The copyright owner (or owners) is whoever holds legal copyright on the
+work. In the case of works assigned to the FSF, the owner is `Free
+Software Foundation, Inc.'.
+
+The copyright `line' may actually be split across multiple lines, both
+in the source document and in the output. This often happens for
+documents with a long history, having many different years of
+publication. If you do use several lines, do not indent any of them
+(or anything else in the @code{@@copying} block) in the source file.
+
address@hidden Notices,,, maintain, GNU Maintainer Information}, for
+additional information. @xref{GNU Sample Texts}, for the full text to
+be used in GNU manuals. @xref{GNU Free Documentation License}, for
+the license itself under which GNU and other free manuals are
+distributed.
+
+
address@hidden @t{@@insertcopying}
address@hidden @code{@@insertcopying}: Include Permissions Text
+
address@hidden@c old name
address@hidden insertcopying
address@hidden Copying text, including
address@hidden Permissions text, including
address@hidden Including permissions text
+
+The @code{@@insertcopying} command is simply written on a line by
+itself, like this:
+
address@hidden
+@@insertcopying
address@hidden example
+
+This inserts the text previously defined by @code{@@copying}. To meet
+legal requirements, it must be used on the copyright page in the printed
+manual (@pxref{Copyright}).
+
+The @code{@@copying} command itself causes the permissions text to
+appear in an Info file @emph{before} the first node. The text is also
+copied into the beginning of each split Info output file, as is legally
+necessary. This location implies a human reading the manual using Info
+does @emph{not} see this text (except when using the advanced Info
+command @kbd{g *}), but this does not matter for legal purposes,
+because the text is present.
+
+Similarly, the @code{@@copying} text is automatically included at the
+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.
+
+
address@hidden Titlepage & Copyright Page
address@hidden 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.
+
+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.
+
address@hidden
+* @t{@@titlepage}:: Create a title for the printed document.
+* @t{@@titlefont @@center @@sp}:: The @code{@@titlefont}, @code{@@center},
+ and @code{@@sp} commands.
+* @t{@@title @@subtitle @@author}:: The @code{@@title}, @code{@@subtitle},
+ and @code{@@author} commands.
+* Copyright:: How to write the copyright notice and
+ include copying permissions.
+* Heading Generation:: Turn on page headings after the title and
+ copyright pages.
address@hidden menu
+
+
address@hidden @t{@@titlepage}
address@hidden @code{@@titlepage}
+
address@hidden@c old name
address@hidden Title page
address@hidden titlepage
+
+Start the material for the title page and following copyright page
+with @code{@@titlepage} on a line by itself and end it with
address@hidden@@end titlepage} on a line by itself.
+
+The @code{@@end titlepage} command starts a new page and turns on page
+numbering (@pxref{Heading Generation}). All the
+material that you want to appear on unnumbered pages should be put
+between the @code{@@titlepage} and @code{@@end titlepage} commands.
+You can force the table of contents to appear there with the
address@hidden@@setcontentsaftertitlepage} command (@pxref{Contents}).
+
address@hidden address@hidden, within @code{@@titlepage}}
+By using the @code{@@page} command you can force a page break within the
+region delineated by the @code{@@titlepage} and @code{@@end titlepage}
+commands and thereby create more than one unnumbered page. This is how
+the copyright page is produced. (The @code{@@titlepage} command might
+perhaps have been better named the @code{@@titleandadditionalpages}
+command, but that would have been rather long!)
+
+When you write a manual about a computer program, you should write the
+version of the program to which the manual applies on the title page.
+If the manual changes more frequently than the program or is independent
+of it, you should also include an edition address@hidden have found
+that it is helpful to refer to versions of independent manuals as
+`editions' and versions of programs as `versions'; otherwise, we find we
+are liable to confuse each other in conversation by referring to both
+the documentation and the software with the same words.} for the manual.
+This helps readers keep track of which manual is for which version of
+the program. (The `Top' node should also contain this information; see
address@hidden 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
address@hidden@@author} commands to create a title page with black rules under
+the title and author lines and the subtitle text set flush to the
+right hand side of the page. With this method, you do not specify any
+of the actual formatting of the title page. You specify the text
+you want, and Texinfo does the formatting.
+
+You may use either method, or you may combine them; see the examples in
+the sections below.
+
address@hidden shorttitlepage
address@hidden Bastard title page
address@hidden Title page, bastard
+For sufficiently simple documents, and for the bastard title page in
+traditional book frontmatter, Texinfo also provides a command
address@hidden@@shorttitlepage} which takes the rest of the line as the title.
+The argument is typeset on a page by itself and followed by a blank
+page.
+
+
address@hidden @t{@@titlefont @@center @@sp}
address@hidden @code{@@titlefont}, @code{@@center}, and @code{@@sp}
+
address@hidden center address@hidden old name
address@hidden titlefont
address@hidden center
address@hidden 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
address@hidden<h1>} heading, but the HTML document @code{<title>} is not
+affected. For that, you must put an @code{@@settitle} command before
+the @code{@@titlefont} command (@address@hidden@@settitle}}).
+
address@hidden 700
+For example:
+
address@hidden
+@@address@hidden@}
address@hidden example
+
+Use the @code{@@center} command at the beginning of a line to center
+the remaining text on that line. Thus,
+
address@hidden
+@@center @@address@hidden@}
address@hidden example
+
address@hidden
+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:
+
address@hidden
+@@sp 2
address@hidden example
+
address@hidden
+This inserts two blank lines on the printed page.
+(@address@hidden@@sp}}, for more information about the @code{@@sp}
+command.)
+
+A template for this method looks like this:
+
address@hidden
address@hidden
+@@titlepage
+@@sp 10
+@@center @@address@hidden@address@hidden
+@@sp 2
+@@center @var{subtitle-if-any}
+@@sp 2
+@@center @var{author}
address@hidden
+@@end titlepage
address@hidden group
address@hidden example
+
+The spacing of the example fits an 8.5 by 11 inch manual.
+
+You can in fact use these commands anywhere, not just on a title page,
+but since they are not logical markup commands, we don't recommend
+them.
+
address@hidden @t{@@title @@subtitle @@author}
address@hidden @code{@@title}, @code{@@subtitle}, and @code{@@author}
+
address@hidden subtitle address@hidden old name
address@hidden title
address@hidden subtitle
address@hidden author
+
+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.
+
+Write the @code{@@title}, @code{@@subtitle}, or @code{@@author}
+commands at the beginning of a line followed by the title, subtitle,
+or author. The @code{@@author} command may be used for a quotation in
+an @code{@@quotation} block (@address@hidden@@quotation}});
+except for that, it is an error to use any of these commands outside
+of @code{@@titlepage}.
+
+The @code{@@title} command produces a line in which the title is set
+flush to the left-hand side of the page in a larger than normal font.
+The title is underlined with a black rule. The title must be given on
+a single line in the source file; it will be broken into multiple
+lines of output is needed.
+
+For long titles, the @code{@@*} command may be used to specify the
+line breaks in long titles if the automatic breaks do not suit. Such
+explicit line breaks are generally reflected in all output formats; if
+you only want to specify them for the printed output, use a
+conditional (@pxref{Conditionals}). For example:
+
address@hidden
+@@title This Long Title@@address@hidden,@@address@hidden Is Broken in
@@address@hidden@}
address@hidden example
+
+The @code{@@subtitle} command sets subtitles in a normal-sized font
+flush to the right-hand side of the page.
+
+The @code{@@author} command sets the names of the author or authors in
+a middle-sized font flush to the left-hand side of the page on a line
+near the bottom of the title page. The names are followed by a black
+rule that is thinner than the rule that underlines the title.
+
+There are two ways to use the @code{@@author} command: you can write
+the name or names on the remaining part of the line that starts with
+an @code{@@author} command:
+
address@hidden
+@@author by Jane Smith and John Doe
address@hidden example
+
address@hidden
+or you can write the names one above each other by using multiple
address@hidden@@author} commands:
+
address@hidden
address@hidden
+@@author Jane Smith
+@@author John Doe
address@hidden group
address@hidden example
+
address@hidden 950
+A template for this method looks like this:
+
address@hidden
address@hidden
+@@titlepage
+@@title @var{name-of-manual-when-printed}
+@@subtitle @var{subtitle-if-any}
+@@subtitle @var{second-subtitle}
+@@author @var{author}
+@@page
address@hidden
+@@end titlepage
address@hidden group
address@hidden example
+
+
address@hidden Copyright
address@hidden Copyright Page
address@hidden Copyright page
address@hidden Printed permissions
address@hidden Permissions, printed
+
+By international treaty, the copyright notice for a book must be either
+on the title page or on the back of the title page. When the copyright
+notice is on the back of the title page, that page is customarily not
+numbered. Therefore, in Texinfo, the information on the copyright page
+should be within @code{@@titlepage} and @code{@@end titlepage}
+commands.
+
address@hidden vskip @address@hidden vertical skip}
address@hidden filll @address@hidden dimension}
+Use the @code{@@page} command to cause a page break. To push the
+copyright notice and the other text on the copyright page towards the
+bottom of the page, use the following incantation after @code{@@page}:
+
address@hidden
+@@vskip 0pt plus 1filll
address@hidden example
+
address@hidden
+The @code{@@vskip} command inserts whitespace in the @TeX{} output; it
+is ignored in all other output formats. The @samp{0pt plus 1filll}
+means to put in zero points of mandatory whitespace, and as much
+optional whitespace as needed to push the following text to the bottom
+of the page. Note the use of three @samp{l}s in the word
address@hidden; this is correct.
+
+To insert the copyright text itself, write @code{@@insertcopying}
+next (@pxref{Document Permissions}):
+
address@hidden
+@@insertcopying
address@hidden example
+
+Follow the copying text by the publisher, ISBN numbers, cover art
+credits, and other such information.
+
+Here is an example putting all this together:
+
address@hidden
+@@titlepage
address@hidden
+@@page
+@@vskip 0pt plus 1filll
+@@insertcopying
+
+Published by @dots{}
+
+Cover art by @dots{}
+@@end titlepage
address@hidden example
+
+We have one more special case to consider: for plain text output, you
+must insert the copyright information explicitly if you want it to
+appear. For instance, you could have the following after the copyright
+page:
+
address@hidden
+@@ifplaintext
+@@insertcopying
+@@end ifplaintext
address@hidden example
+
+You could include other title-like information for the plain text
+output in the same place.
+
+
+
address@hidden Heading Generation
address@hidden Heading Generation
+
address@hidden address@hidden old name
address@hidden Headings, page, begin to appear
address@hidden Titlepage end starts headings
address@hidden End titlepage starts headings
address@hidden Generating page headings
+
+Like all @code{@@end} commands (@pxref{Quotations and Examples}), the
address@hidden@@end titlepage} command must be written at the beginning of a
+line by itself, with only one space between the @code{@@end} and the
address@hidden It not only marks the end of the title and
+copyright pages, but also causes @TeX{} to start generating page
+headings and page numbers.
+
+Texinfo has two standard page heading formats, one for documents
+printed on one side of each sheet of paper (single-sided printing),
+and the other for documents printed on both sides of each sheet
+(double-sided printing).
+
+In full generality, you can control the headings in different ways:
+
address@hidden @bullet
address@hidden
+The conventional way is to write an @code{@@setchapternewpage} command
+before the title page commands, if required, and then have the
address@hidden@@end titlepage} command start generating page headings in the
+manner desired.
+
+Most documents are formatted with the standard single-sided or
+double-sided headings, (sometimes) using @code{@@setchapternewpage
+odd} for double-sided printing and (almost always) no
address@hidden@@setchapternewpage} command for single-sided printing
+(@address@hidden@@setchapternewpage}}).
+
address@hidden
+Alternatively, you can use the @code{@@headings} command to prevent
+page headings from being generated or to start them for either single
+or double-sided printing. Write an @code{@@headings} command
+immediately after the @code{@@end titlepage} command. To turn off
+headings, write @code{@@headings off}. @address@hidden@@headings}}.
+
address@hidden
+Or, you may specify your own page heading and footing format.
address@hidden
address@hidden itemize
+
+
address@hidden Contents
address@hidden Generating a Table of Contents
address@hidden Table of contents
address@hidden Contents, table of
address@hidden Short table of contents
address@hidden contents
address@hidden summarycontents
address@hidden shortcontents
+
+The @code{@@chapter}, @code{@@section}, and other structuring commands
+(@pxref{Chapter Structuring}) supply the information to make up a
+table of contents, but they do not cause an actual table to appear in
+the manual. To do this, you must use the @code{@@contents} and/or
address@hidden@@summarycontents} command(s).
+
address@hidden @code
address@hidden @@contents
+Generates a table of contents in a printed manual, including all
+chapters, sections, subsections, etc., as well as appendices and
+unnumbered chapters. Headings generated by @code{@@majorheading},
address@hidden@@chapheading}, and the other @code{@@@dots{}heading} commands
+do not appear in the table of contents (@pxref{Structuring Command
+Types}).
+
address@hidden @@shortcontents
address@hidden @@summarycontents
+(@code{@@summarycontents} is a synonym for @code{@@shortcontents}.)
+
+Generates a short or summary table of contents that lists only the
+chapters, appendices, and unnumbered chapters. Sections, subsections
+and subsubsections are omitted. Only a long manual needs a short
+table of contents in addition to the full table of contents.
address@hidden table
+
+Both contents commands should be written on a line by themselves, and
+placed near the beginning of the file, after the @code{@@end
+titlepage} (@address@hidden@@titlepage}}), before any sectioning
+command. The contents commands automatically generate a chapter-like
+heading at the top of the first table of contents page, so don't
+include any sectioning command such as @code{@@unnumbered} before
+them.
+
+Since an Info file uses menus instead of tables of contents, the Info
+formatting commands ignore the contents commands. But the contents
+are included in plain text output (generated by @code{makeinfo
+--plaintext}) and in other output formats, such as HTML.
+
+When @code{makeinfo} writes a short table of contents while producing
+HTML output, the links in the short table of contents point to
+corresponding entries in the full table of contents rather than the text
+of the document. The links in the full table of contents point to the
+main text of the document.
+
+In the past, the contents commands were sometimes placed at the end of
+the file, after any indices and just before the @code{@@bye}, but we
+no longer recommend this.
+
address@hidden setcontentsaftertitlepage
address@hidden setshortcontentsaftertitlepage
address@hidden Contents, after title page
address@hidden Table of contents, after title page
+However, since many existing Texinfo documents still do have the
address@hidden@@contents} at the end of the manual, if you are a user printing
+a manual, you may wish to force the contents to be printed after the
+title page. You can do this by specifying
address@hidden@@setcontentsaftertitlepage} and/or
address@hidden@@setshortcontentsaftertitlepage}. The first prints only the
+main contents after the @code{@@end titlepage}; the second prints both
+the short contents and the main contents. In either case, any
+subsequent @code{@@contents} or @code{@@shortcontents} is ignored.
+
+You need to include the @code{@@address@hidden
+commands early in the document (just after @code{@@setfilename}, for
+example). We recommend using @command{texi2dvi} (@pxref{Format with
address@hidden) to specify this without altering the source file at
+all. For example:
+
address@hidden
+texi2dvi --texinfo=@@setcontentsaftertitlepage foo.texi
address@hidden example
+
+An alternative invocation, using @command{texi2any}:
+
address@hidden
+texi2any --dvi --Xopt --texinfo=@@setcontentsaftertitlepage foo.texi
address@hidden example
+
+
+
address@hidden The Top Node
address@hidden The `Top' Node and Master Menu
address@hidden Top node
address@hidden Node, `Top'
+
+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.
+
address@hidden top
+It is conventional and desirable to write an @code{@@top} sectioning
+command line containing the title of the document immediately after
+the @code{@@node Top} line (@address@hidden@@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
address@hidden@@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
address@hidden@@ifnottex} and @code{@@end ifnottex}, but it is simplest to do
+so. @xref{Conditionals, , Conditionally Visible Text}.)
+
address@hidden
+* Top Node Example::
+* Master Menu Parts::
address@hidden menu
+
+
address@hidden Top Node Example
address@hidden Top Node Example
+
address@hidden Top node example
+
+Here is an example of a Top node.
+
address@hidden
address@hidden
+@@ifnottex
+@@node Top
+@@top Sample Title
+
+@@insertcopying
+@@end ifnottex
address@hidden group
+
+Additional general information.
+
address@hidden
+@@menu
+* First Chapter::
+* Second Chapter::
address@hidden
+* Index::
address@hidden group
+@@end menu
address@hidden example
+
+
address@hidden Master Menu Parts
address@hidden Parts of a Master Menu
address@hidden Master menu
address@hidden Menu, master
address@hidden Parts of a master menu
+
+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
address@hidden@@end menu} and does not appear in the printed output.
+
+Generally, a master menu is divided into parts.
+
address@hidden @bullet
address@hidden
+The first part contains the major nodes in the Texinfo file: the nodes
+for the chapters, chapter-like sections, and the appendices.
+
address@hidden
+The second part contains nodes for the indices.
+
address@hidden
address@hidden detailmenu
address@hidden 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
address@hidden@@end detailmenu} after the last; otherwise, @code{makeinfo}
+will get confused.
address@hidden itemize
+
+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
+treated as a menu entry. (@xref{Writing a Menu}, for more
+information.)
+
+For example, the master menu for this manual looks like the following
+(but has many more entries):
+
address@hidden
address@hidden
+@@menu
+* Copying Conditions:: Your rights.
+* Overview:: Texinfo in brief.
address@hidden
address@hidden group
address@hidden
+* Command and Variable Index::
+* General Index::
address@hidden group
+
address@hidden
+@@detailmenu
+--- The Detailed Node Listing ---
+
+Overview of Texinfo
+
+* Reporting Bugs:: @dots{}
address@hidden
address@hidden group
+
address@hidden
+Beginning a Texinfo File
+
+* Sample Beginning:: @dots{}
address@hidden
+@@end detailmenu
+@@end menu
address@hidden group
address@hidden example
+
+
address@hidden Global Document Commands
address@hidden Global Document Commands
address@hidden 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.
+
address@hidden
+* @t{@@documentdescription}:: Document summary for the HTML output.
+* @t{@@setchapternewpage}:: Start chapters on right-hand pages.
+* @t{@@headings}:: An option for turning headings on and off
+ and double or single sided printing.
+* @t{@@paragraphindent}:: Specify paragraph indentation.
+* @t{@@firstparagraphindent}:: Suppressing first paragraph indentation.
+* @t{@@exampleindent}:: Specify environment indentation.
address@hidden menu
+
+
address@hidden @t{@@documentdescription}
address@hidden @code{@@documentdescription}: Summary Text
address@hidden@c old name
+
address@hidden Document description
address@hidden Description of document
address@hidden Summary of document
address@hidden Abstract of document
address@hidden <meta> HTML tag, and document description
address@hidden documentdescription
+
+When producing HTML output for a document, @command{makeinfo} writes a
address@hidden<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
+(@address@hidden@@settitle}}). To change this, use the
address@hidden@@documentdescription} environment, as in:
+
address@hidden
+@@documentdescription
+descriptive text.
+@@end documentdescription
address@hidden example
+
address@hidden
+This will produce the following output in the @samp{<head>} of the HTML:
+
address@hidden
+<meta name=description content="descriptive text.">
address@hidden example
+
address@hidden@@documentdescription} must be specified before the first node of
+the document.
+
+
address@hidden @t{@@setchapternewpage}
address@hidden @code{@@setchapternewpage}: Blank Pages Before Chapters
+
address@hidden@c old name
address@hidden setchapternewpage
address@hidden Starting chapters
address@hidden 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:
+
address@hidden
+@@setchapternewpage odd
address@hidden example
+
+You can specify one of three alternatives with the
address@hidden@@setchapternewpage} command:
+
address@hidden @asis
+
address@hidden @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.
+
address@hidden @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.
+
address@hidden @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.
address@hidden table
+
+Texinfo does not have an @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.
address@hidden@t{@@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.
+
+
address@hidden @t{@@headings}
address@hidden The @code{@@headings} Command
+
address@hidden on address@hidden old name
address@hidden 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
address@hidden@@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 an @code{@@headings} command
+immediately after the @code{@@end titlepage} command.
+
+You can use @code{@@headings} as follows:
+
address@hidden @code
address@hidden @@headings off
+Turn off printing of page headings.
+
address@hidden @@headings single
+Turn on page headings appropriate for single-sided printing.
+
address@hidden @@headings double
+Turn on page headings appropriate for double-sided printing.
+
address@hidden @@headings singleafter
address@hidden @@headings doubleafter
+Turn on @code{single} or @code{double} headings, respectively, after the
+current page is output.
+
address@hidden @@headings on
+Turn on page headings: @code{single} if @samp{@@setchapternewpage
+on}, @code{double} otherwise.
address@hidden table
+
+For example, suppose you write @code{@@setchapternewpage off} before the
address@hidden@@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
address@hidden to typeset page headers for single-sided printing. To cause
address@hidden 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:
+
address@hidden
+@@end titlepage
+@@headings off
address@hidden example
+
address@hidden
+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.
address@hidden, , Page Headings}, for more information.
+
+
address@hidden @t{@@paragraphindent}
address@hidden @code{@@paragraphindent}: Controlling Paragraph Indentation
+
address@hidden@c old name
address@hidden paragraphindent
address@hidden Indenting paragraphs, control of
address@hidden 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 an @code{@@paragraphindent} command at the beginning of a line
+followed by either @samp{asis} or a number:
+
address@hidden
+@@paragraphindent @var{indent}
address@hidden example
+
+The indentation is according to the value of @var{indent}:
+
address@hidden @asis
address@hidden @code{asis}
+Do not change the existing indentation (not implemented in @TeX{}).
+
address@hidden @code{none}
address@hidden 0
+Omit all indentation.
+
address@hidden @var{n}
+Indent by @var{n} space characters in Info output, by @var{n} ems in
address@hidden
+
address@hidden 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}.
+
+A peculiarity of the @code{texinfo-format-buffer} and
address@hidden commands is that they do not indent (nor
+fill) paragraphs that contain @code{@@w} or @code{@@*} commands.
+
+
address@hidden @t{@@firstparagraphindent}
address@hidden @code{@@firstparagraphindent}: Indenting After Headings
+
address@hidden@c old name
address@hidden firstparagraphindent
address@hidden First paragraph, suppressing indentation of
address@hidden Suppressing first paragraph indentation
address@hidden Preventing first paragraph indentation
address@hidden Indenting, suppressing of first paragraph
address@hidden 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
address@hidden@@firstparagraphindent} command:
+
address@hidden
+@@firstparagraphindent @var{word}
address@hidden example
+
+The first paragraph after a heading is indented according to the value
+of @var{word}:
+
address@hidden @asis
address@hidden @code{none}
+Prevents the first paragraph from being indented (default).
+This option is ignored by @command{makeinfo} if
address@hidden@@paragraphindent asis} is in effect.
+
address@hidden @code{insert}
+Include normal paragraph indentation. This respects the paragraph
+indentation set by an @code{@@paragraphindent} command
+(@address@hidden@@paragraphindent}}).
address@hidden table
+
address@hidden@@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}.
+
+
address@hidden @t{@@exampleindent}
address@hidden @code{@@exampleindent}: Environment Indenting
+
address@hidden@c old name
address@hidden exampleindent
address@hidden Indenting environments
address@hidden Environment indentation
address@hidden 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:
+
address@hidden
+@@exampleindent @var{indent}
address@hidden example
+
+The indentation is according to the value of @var{indent}:
+
address@hidden @asis
address@hidden @code{asis}
+Do not change the existing indentation (not implemented in @TeX{}).
+
address@hidden 0
+Omit all indentation.
+
address@hidden @var{n}
+Indent environments by @var{n} space characters in Info output, by
address@hidden ems in @TeX{}.
+
address@hidden table
+
+The default value of @var{indent} is 5 spaces in Info, and address@hidden
+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}.
+
+
address@hidden Ending a File
address@hidden Ending a Texinfo File
address@hidden Ending a Texinfo file
address@hidden Texinfo file ending
address@hidden File ending
address@hidden bye
+
+The end of a Texinfo file should include commands to create indices,
+and the @code{@@bye} command to mark the last line to be processed.
+For example:
+
address@hidden
+@@node Index
+@@unnumbered Index
+
+@@printindex cp
+
+@@bye
address@hidden example
+
address@hidden
+* Printing Indices & Menus:: How to print an index in hardcopy and
+ generate index menus in Info.
+* File End:: How to mark the end of a file.
address@hidden menu
+
+
address@hidden Printing Indices & Menus
address@hidden Printing Indices and Menus
address@hidden Printing an index
address@hidden Indices, printing and menus
address@hidden Generating menus with indices
address@hidden Menus generated with indices
+
+To print an index means to include it as part of a manual or Info file.
+This does not happen automatically just because you use @code{@@cindex}
+or other index-entry generating commands in the Texinfo file; those just
+cause the raw data for the index to be accumulated. To generate an
+index, you must include the @code{@@printindex} command at the place in
+the document where you want the index to appear. Also, as part of the
+process of creating a printed manual, you must run a program called
address@hidden (@pxref{Hardcopy}) to sort the raw data to produce a
+sorted index file. The sorted index file is what is actually used to
+print the index.
+
+Texinfo offers six separate types of predefined index, which suffice
+in most cases. @xref{Indices}, for information on this, as well
+defining your own new indices, combining indices, and, most
+importantly advice on writing the actual index entries. This section
+focuses on printing indices, which is done with the
address@hidden@@printindex} command.
+
address@hidden printindex
address@hidden@@printindex} takes one argument, a two-letter index
+abbreviation. It reads the corresponding sorted index file (for
+printed output), and formats it appropriately into an index.
+
+The @code{@@printindex} command does not generate a chapter heading
+for the index, since different manuals have different needs.
+Consequently, you should precede the @code{@@printindex} command with
+a suitable section or chapter command (usually @code{@@appendix} or
address@hidden@@unnumbered}) to supply the chapter heading and put the index
+into the table of contents. Precede the chapter heading with an
address@hidden@@node} line as usual.
+
+For example:
+
address@hidden
address@hidden
+@@node Variable Index
+@@unnumbered Variable Index
+
+@@printindex vr
address@hidden group
+
address@hidden
+@@node Concept Index
+@@unnumbered Concept Index
+
+@@printindex cp
address@hidden group
address@hidden smallexample
+
+If you have more than one index, we recommend placing the concept index last.
+
address@hidden
address@hidden
+In printed output, @code{@@printindex} produces a traditional
+two-column index, with dot leaders between the index terms and page
+numbers.
+
address@hidden
+In Info output, @code{@@printindex} produces a special menu containing
+the line number of the entry, relative to the start of the node. Info
+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:
+
address@hidden
+* First index entry: Top. (line 7)
address@hidden smallexample
+
address@hidden 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
+printed manual.
+
address@hidden
+In plain text output, @code{@@printindex} produces the same menu, but
+the line numbers are relative to the start of the file, since that's
+more convenient for that format.
+
address@hidden
+In HTML output, @code{@@printindex} produces links to the index
+entries.
+
address@hidden
+In XML and Docbook output, it simply records the index to be printed.
address@hidden itemize
+
+
address@hidden File End
address@hidden @code{@@bye} File Ending
address@hidden bye
+
+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.
+
+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}).
+
+
address@hidden Chapter Structuring
address@hidden Chapter Structuring
address@hidden@c old name
address@hidden Chapter structuring
address@hidden Structuring of chapters
address@hidden Sectioning
+
+Texinfo's @dfn{chapter structuring} commands (could more generally be
+called @dfn{sectioning structuring}, but that is awkward) divide a
+document into a hierarchy of chapters, sections, subsections, and
+subsubsections. These commands generate large headings in the text,
+like the one above. They also provide information for generating the
+table of contents (@pxref{Contents,, Generating a Table of Contents}),
+and for implicitly determining node pointers, as is recommended
+(@address@hidden Pointer Creation}).
+
+The chapter structuring commands do not create a node structure, so
+normally you put an @code{@@node} command immediately before each
+chapter structuring command (@pxref{Nodes}). The only time you are
+likely to use the chapter structuring commands without also using
+nodes is if you are writing a document that contains no cross
+references and will only be printed, not transformed into Info, HTML,
+or other formats.
+
address@hidden
+* Tree Structuring:: A manual is like an upside down tree @dots{}
+* Structuring Command Types:: How to divide a manual into parts.
+* @t{@@chapter}:: Chapter structuring.
+* @t{@@unnumbered @@appendix}::
+* @t{@@majorheading @@chapheading}::
+* @t{@@section}::
+* @t{@@unnumberedsec @@appendixsec @@heading}::
+* @t{@@subsection}::
+* @t{@@unnumberedsubsec @@appendixsubsec @@subheading}::
+* @t{@@subsubsection}:: Commands for the lowest level sections.
+* @t{@@part}:: Collections of chapters.
+* Raise/lower sections:: How to change commands' hierarchical level.
address@hidden menu
+
+
address@hidden Tree Structuring
address@hidden Tree Structure of Sections
address@hidden Tree structuring
+
+A Texinfo file is usually structured like a book with chapters,
+sections, subsections, and the like. This structure can be visualized
+as a tree (or rather as an upside-down tree) with the root at the top
+and the levels corresponding to chapters, sections, subsection, and
+subsubsections.
+
+Here is a diagram that shows a Texinfo file with three chapters, each
+with two sections.
+
address@hidden
address@hidden
+ Top
+ |
+ -------------------------------------
+ | | |
+ Chapter 1 Chapter 2 Chapter 3
+ | | |
+ -------- -------- --------
+ | | | | | |
+Section Section Section Section Section Section
+ 1.1 1.2 2.1 2.2 3.1 3.2
+
address@hidden group
address@hidden example
+
+In a Texinfo file that has this structure, the beginning of Chapter 2
+would normally (with implicitly-determined node pointers) be written
+like this:
+
address@hidden
address@hidden
+@@node Chapter 2
+@@chapter Chapter 2
address@hidden group
address@hidden example
+
address@hidden
+But for purposes of example, here is how it would be written with
+explicit node pointers:
+
address@hidden
address@hidden
+@@node Chapter 2, Chapter 3, Chapter 1, Top
+@@chapter Chapter 2
address@hidden group
address@hidden example
+
+The chapter structuring commands are described in the sections that
+follow; the @code{@@node} command is described in
+the following chapter (@pxref{Nodes}).
+
+
address@hidden Structuring Command Types
address@hidden Structuring Command Types
+
+The chapter structuring commands fall into four groups or series, each
+of which contains structuring commands corresponding to the
+hierarchical levels of chapters, sections, subsections, and
+subsubsections.
+
+The four groups of commands are the @code{@@chapter} series, the
address@hidden@@unnumbered} series, the @code{@@appendix} series, and the
address@hidden@@heading} series. Each command produces a title with a
+different appearance in the body of the document. Some of the
+commands list their titles in the tables of contents, while others do
+not. Here are the details:
+
address@hidden @bullet
address@hidden
+The @code{@@chapter} and @code{@@appendix} series of commands produce
+numbered or lettered entries both in the body of a document and in its
+table of contents.
+
address@hidden
+The @code{@@unnumbered} series of commands produce unnumbered entries
+both in the body of a document and in its table of contents. The
address@hidden@@top} command, which has a special use, is a member of this
+series (@address@hidden@@top} Command}). An @code{@@unnumbered} section
+is a normal part of the document structure.
+
address@hidden
+The @code{@@heading} series of commands produce simple unnumbered
+headings that do not appear in a table of contents, are not associated
+with nodes, and cannot be cross-referenced. These heading commands
+never start a new page.
address@hidden itemize
+
+When an @code{@@setchapternewpage} command says to do so, the
address@hidden@@chapter}, @code{@@unnumbered}, and @code{@@appendix} commands
+start new pages in the printed manual; the @code{@@heading} commands
+do not. @address@hidden@@setchapternewpage}}.
+
+Here is a summary:
+
address@hidden
+{\globaldefs=1 \smallfonts \rm}
address@hidden tex
+
address@hidden @columnfractions .19 .30 .29 .22
address@hidden @tab @tab
@tab No new page
address@hidden @i{Numbered} @tab @i{Unnumbered} @tab
@i{Lettered/numbered} @tab @i{Unnumbered}
address@hidden In contents @tab In contents @tab In
contents @tab Not in contents
address@hidden @tab @code{@@top} @tab
@tab @code{@@majorheading}
address@hidden @code{@@chapter} @tab @code{@@unnumbered} @tab
@code{@@appendix} @tab @code{@@chapheading}
address@hidden @code{@@section} @tab @code{@@unnumberedsec} @tab
@code{@@appendixsec} @tab @code{@@heading}
address@hidden @code{@@subsection} @tab @code{@@unnumberedsubsec} @tab
@code{@@appendixsubsec} @tab @code{@@subheading}
address@hidden @code{@@subsubsection} @tab @code{@@unnumberedsubsubsec} @tab
@code{@@appendixsubsubsec} @tab @code{@@subsubheading}
address@hidden multitable
address@hidden
+{\globaldefs=1 \textfonts \rm}
address@hidden tex
+
+
address@hidden @t{@@chapter}
address@hidden @code{@@chapter}: Chapter Structuring
+
address@hidden@c old name
address@hidden chapter
+
address@hidden@@chapter} identifies a chapter in the document--the highest
+level of the normal document structuring hierarchy. Write the command
+at the beginning of a line and follow it on the same line by the title
+of the chapter. The chapter is numbered automatically, starting
address@hidden
+
+For example, the present chapter in this manual is entitled
address@hidden@@chapter}: Chapter Structuring''; the @code{@@chapter} line
+looks like this:
+
address@hidden
+@@chapter @@address@hidden@@@@address@hidden: Chapter Structuring
address@hidden example
+
+In @TeX{}, the @code{@@chapter} command produces a chapter heading in
+the document.
+
+In Info and plain text output, the @code{@@chapter} command causes the
+title to appear on a line by itself, with a line of asterisks inserted
+underneath. So, the above example produces the following output:
+
address@hidden
address@hidden
+5 Chapter Structuring
+*********************
address@hidden group
address@hidden example
+
+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
+that includes all the following sections, up to the next chapter.
+
+
address@hidden @t{@@unnumbered @@appendix}
address@hidden @code{@@unnumbered}, @code{@@appendix}: Chapters with Other
Labeling
+
address@hidden & address@hidden old name
address@hidden unnumbered
address@hidden appendix
+
+Use the @code{@@unnumbered} command to start a chapter-level element
+that appears without chapter numbers of any kind. Use the
address@hidden@@appendix} command to start an appendix that is labeled by
+letter (`A', `B', @dots{}) instead of by number; appendices are also
+at the chapter level of structuring.
+
+Write an @code{@@appendix} or @code{@@unnumbered} command at the
+beginning of a line and follow it on the same line by the title,
+just as with @code{@@chapter}.
+
address@hidden centerchap
+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.
address@hidden but the Hacker's Dictionary wanted it, before they quit Texinfo.
+
+
address@hidden @t{@@majorheading @@chapheading}
address@hidden @code{@@majorheading}, @code{@@chapheading}: Chapter-level
Headings
+
address@hidden & address@hidden old name
address@hidden majorheading
address@hidden chapheading
+
+The @code{@@majorheading} and @code{@@chapheading} commands produce
+chapter-like headings in the body of a document.
+
+However, neither command produces an entry in the table of contents,
+and neither command causes @TeX{} to start a new page in a printed
+manual.
+
+In @TeX{}, an @code{@@majorheading} command generates a larger vertical
+whitespace before the heading than an @code{@@chapheading} command but
+is otherwise the same.
+
+In Info and plain text, the @code{@@majorheading} and
address@hidden@@chapheading} commands produce the same output as
address@hidden@@chapter}: the title is printed on a line by itself with a line
+of asterisks underneath. Similarly for address@hidden The only difference is
+the lack of numbering and the lack of any association with nodes.
address@hidden@t{@@chapter}}.
+
+
address@hidden @t{@@section}
address@hidden @code{@@section}: Sections Below Chapters
+
address@hidden@c old name
address@hidden section
+
+An @code{@@section} command identifies a section within a chapter
+unit, whether created with @code{@@chapter}, @code{@@unnumbered}, or
address@hidden@@appendix}, following the numbering scheme of the chapter-level
+command. Thus, within an @code{@@chapter} chapter numbered `1', the
+sections are numbered `1.1', `1.2', etc.; within an @code{@@appendix}
+``chapter'' labeled `A', the sections are numbered `A.1', `A.2', etc.;
+within an @code{@@unnumbered} chapter, the section gets no number.
+The output is underlined with @samp{=} in Info and plain text.
+
+To make a section, write the @code{@@section} command at the
+beginning of a line and follow it on the same line by the section
+title. For example,
+
address@hidden
+@@section This is a section
address@hidden example
+
address@hidden
+might produce the following in Info:
+
address@hidden
address@hidden
+5.7 This is a section
+=====================
address@hidden group
address@hidden example
+
+Section titles are listed in the table of contents.
+
+The @TeX{}, HTML, Docbook, and XML output is all analogous to the
+chapter-level output, just ``one level down''; @address@hidden@@chapter}}.
+
+
address@hidden @t{@@unnumberedsec @@appendixsec @@heading}
address@hidden @code{@@unnumberedsec}, @code{@@appendixsec}, @code{@@heading}
+
address@hidden appendixsec address@hidden old name
address@hidden unnumberedsec
address@hidden appendixsec
address@hidden heading
+
+The @code{@@unnumberedsec}, @code{@@appendixsec}, and @code{@@heading}
+commands are, respectively, the unnumbered, appendix-like, and
+heading-like equivalents of the @code{@@section} command (see the
+previous section).
+
address@hidden@@unnumberedsec} and @code{@@appendixsec} do not need to be used
+in ordinary circumstances, because @code{@@section} may also be used
+within @code{@@unnumbered} and @code{@@appendix} chapters; again, see
+the previous section.
+
address@hidden @code
address@hidden @@unnumberedsec
+The @code{@@unnumberedsec} command may be used within an unnumbered
+chapter or within a regular chapter or appendix to produce an
+unnumbered section.
+
address@hidden @@appendixsec
address@hidden @@appendixsection
address@hidden appendixsection
address@hidden appendixsec
address@hidden@@appendixsection} is a longer spelling of the
address@hidden@@appendixsec} command; the two are synonymous.
+
+Conventionally, the @code{@@appendixsec} or @code{@@appendixsection}
+command is used only within appendices.
+
address@hidden @@heading
+You may use the @code{@@heading} command anywhere you wish for a
+section-style heading that will not appear in the table of contents.
address@hidden table
+
+
address@hidden @t{@@subsection}
address@hidden @code{@@subsection}: Subsections Below Sections
+
address@hidden@c old name
address@hidden subsection
+
+Subsections are to sections as sections are to chapters;
address@hidden@t{@@section}}. In Info and plain text, subsection titles
+are underlined with @samp{-}. For example,
+
address@hidden
+@@subsection This is a subsection
address@hidden example
+
address@hidden
+might produce
+
address@hidden
address@hidden
+1.2.3 This is a subsection
+--------------------------
address@hidden group
address@hidden example
+
+Subsection titles are listed in the table of contents.
+
+The @TeX{}, HTML, Docbook, and XML output is all analogous to the
+chapter-level output, just ``two levels down'';
address@hidden@t{@@chapter}}.
+
+
address@hidden @t{@@unnumberedsubsec @@appendixsubsec @@subheading}
address@hidden The @code{@@subsection}-like Commands
+
address@hidden appendixsubsec address@hidden old name
address@hidden unnumberedsubsec
address@hidden appendixsubsec
address@hidden subheading
address@hidden Subsection-like commands
+
+The @code{@@unnumberedsubsec}, @code{@@appendixsubsec}, and
address@hidden@@subheading} commands are, respectively, the unnumbered,
+appendix-like, and heading-like equivalents of the @code{@@subsection}
+command. (@address@hidden@@subsection}}.)
+
address@hidden@@unnumberedsubsec} and @code{@@appendixsubsec} do not need to
+be used in ordinary circumstances, because @code{@@subsection} may
+also be used within sections of @code{@@unnumbered} and
address@hidden@@appendix} chapters (@address@hidden@@section}}).
+
+An @code{@@subheading} command produces a heading like that of a
+subsection except that it is not numbered and does not appear in the
+table of contents. Similarly, an @code{@@unnumberedsubsec} command
+produces an unnumbered heading like that of a subsection and an
address@hidden@@appendixsubsec} command produces a subsection-like heading
+labeled with a letter and numbers; both of these commands produce
+headings that appear in the table of contents. In Info and plain
+text, the @code{@@subsection}-like commands generate a title
+underlined with hyphens.
+
+
address@hidden @t{@@subsubsection}
address@hidden @code{@@subsection} and Other Subsub Commands
+
address@hidden@c old name
address@hidden subsubsection
address@hidden unnumberedsubsubsec
address@hidden appendixsubsubsec
address@hidden subsubheading
address@hidden Subsub sectioning commands
+
+The fourth and lowest level sectioning commands in Texinfo are the
+`subsub' commands. They are:
+
address@hidden @code
address@hidden @@subsubsection
+Subsubsections are to subsections as subsections are to sections.
+(@address@hidden@@subsection}}.) Subsubsection titles appear in the
+table of contents.
+
address@hidden @@unnumberedsubsubsec
+Unnumbered subsubsection titles appear in the table of contents,
+but lack numbers. Otherwise, unnumbered subsubsections are the same
+as subsubsections.
+
address@hidden @@appendixsubsubsec
+Conventionally, appendix commands are used only for appendices and are
+lettered and numbered appropriately. They also appear in the table
+of contents.
+
address@hidden @@subsubheading
+The @code{@@subsubheading} command may be used anywhere that you want
+a small heading that will not appear in the table of contents.
address@hidden table
+
+As with subsections, @code{@@unnumberedsubsubsec} and
address@hidden@@appendixsubsubsec} do not need to be used in ordinary
+circumstances, because @code{@@subsubsection} may also be used within
+subsections of @code{@@unnumbered} and @code{@@appendix} chapters
+(@address@hidden@@section}}).
+
+In Info, `subsub' titles are underlined with periods. For example,
+
address@hidden
+@@subsubsection This is a subsubsection
address@hidden example
+
address@hidden
+might produce
+
address@hidden
address@hidden
+1.2.3.4 This is a subsubsection
+...............................
address@hidden group
address@hidden example
+
+The @TeX{}, HTML, Docbook, and XML output is all analogous to the
+chapter-level output, just ``three levels down''; @address@hidden@@chapter}}.
+
+
address@hidden @t{@@part}
address@hidden @code{@@part}: Groups of Chapters
address@hidden part
address@hidden Part pages
+
+The final sectioning command is @code{@@part}, to mark a @dfn{part} of
+a manual, that is, a group of chapters or (rarely) appendices. This
+behaves quite differently from the other sectioning commands, to fit
+with the way such ``parts'' are conventionally used in books.
+
+No @code{@@node} command is associated with @code{@@part}. Just write
+the command on a line by itself, including the part title, at the
+place in the document you want to mark off as starting that part. For
+example:
+
address@hidden
+@@part Part I:@@* The beginning
address@hidden example
+
+As can be inferred from this example, no automatic numbering or
+labeling of the @code{@@part} text is done. The text is taken as-is.
+
+Because parts are not associated with nodes, no general text can
+follow the @code{@@part} line. To produce the intended output, it
+must be followed by a chapter-level command (including its node).
+Thus, to continue the example:
+
address@hidden
+@@part Part I:@@* The beginning
+
+@@node Introduction
+@@chapter Introduction
+...
address@hidden example
+
+In the @TeX{} output, the @code{@@part} text is included in both the
+normal and short tables of contents (@pxref{Contents}), without a page
+number (since that is the normal convention). In addition, a ``part
+page'' is output in the body of the document, with just the
address@hidden@@part} text. In the example above, the @code{@@*} causes a
+line break on the part page (but is replaced with a space in the
+tables of contents). This part page is always forced to be on an odd
+(right-hand) page, regardless of the chapter pagination
+(@address@hidden@@setchapternewpage}}).
+
+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
+the following chapters, up to the next @code{<part>}. A @code{<part>}
+containing chapters is also closed at an appendix.
+
+In the Info and plain text output, @code{@@part} has no effect.
+
address@hidden@@part} is ignored when raising or lowering sections (see next
+section). That is, it is never lowered and nothing can be raised to it.
+
+
address@hidden Raise/lower sections
address@hidden Raise/lower Sections: @code{@@raisesections} and
@code{@@lowersections}
address@hidden raisesections
address@hidden lowersections
address@hidden Raising and lowering sections
address@hidden Lowering and raising sections
address@hidden Sections, raising and lowering
+
+The @code{@@raisesections} and @code{@@lowersections} commands
+implicitly raise and lower the hierarchical level of following
+chapters, sections and the other sectioning commands (excluding parts).
+
+That is, the @code{@@raisesections} command changes sections to
+chapters, subsections to sections, and so on. Conversely, the
address@hidden@@lowersections} command changes chapters to sections, sections
+to subsections, and so on. Thus, an @code{@@lowersections} command
+cancels an @code{@@raisesections} command, and vice versa.
+
address@hidden Include files, and section levels
+You can use @code{@@lowersections} to include text written as an outer
+or standalone Texinfo file in another Texinfo file as an inner,
+included file (@pxref{Include Files}). Typical usage looks like this:
+
address@hidden
+@@lowersections
+@@include somefile.texi
+@@raisesections
address@hidden example
+
address@hidden (Without the @code{@@raisesections}, all the subsequent
+sections in the main file would also be lowered.)
+
+If the included file being lowered has an @code{@@top} node, you'll
+need to conditionalize its inclusion with a flag (@address@hidden@@set
+@@value}}).
+
+Another difficulty can arise with documents that use the (recommended)
+feature of @command{makeinfo} for implicitly determining node
+pointers. Since @command{makeinfo} must assume a hierarchically
+organized document to determine the pointers, you cannot just
+arbitrarily sprinkle @code{@@raisesections} and @code{@@lowersections}
+commands throughout the document. The final result has to have menus
+that take the raising and lowering into account. So, as a practical
+matter, you generally only want to raise or lower large chunks,
+usually in external files as shown above.
+
+Repeated use of the commands continues to raise or lower the
+hierarchical level a step at a time. An attempt to raise above
+`chapter' reproduces chapter commands; an attempt to lower below
+`subsubsection' reproduces subsubsection commands. Also, lowered
+subsubsections and raised chapters will not work with
address@hidden's feature of implicitly determining node pointers,
+since the menu structure cannot be represented correctly.
+
+Write each @code{@@raisesections} and @code{@@lowersections} command
+on a line of its own.
+
+
address@hidden Nodes
address@hidden Nodes
+
address@hidden are the primary segments of a Texinfo file. They do not
+in and of themselves impose a hierarchical or any other kind of
+structure on a file. Nodes contain @dfn{node pointers} that name
+other nodes, and can contain @dfn{menus} which are lists of nodes. In
+Info, the movement commands can carry you to a pointed-to node or to a
+node listed in a menu.
+
+Node 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}.
+
+Because node names are used in cross references, it is not desirable
+to casually change them once published. Such name changes invalidate
+references from other manuals, from mail archives, and so on.
address@hidden Xref Link Preservation}.
+
address@hidden
+* @t{@@node}:: Creating nodes, in detail.
+* @t{makeinfo} Pointer Creation:: Letting makeinfo determine node pointers.
+* @t{@@anchor}:: Defining arbitrary cross reference
targets.
+* Node Menu Illustration:: A diagram, and sample nodes and menus.
address@hidden menu
+
+
address@hidden @t{@@node}
address@hidden The @code{@@node} Command
+
address@hidden@c node
address@hidden node
address@hidden Node, defined
+
+A @dfn{node} is a stretch of text that begins at an @code{@@node}
+command and continues until the next @code{@@node} command. The
+definition of node is different from that for chapter or section. A
+chapter may contain sections and a section may contain subsections,
+but a node cannot contain subnodes: the text of a node continues only
+until the next @code{@@node} command in the file. A node usually
+contains only one chapter structuring command, immediately following
+the @code{@@node} line.
+
+To specify a node, write an @code{@@node} command at the beginning of
+a line, and follow it with up to four arguments, separated by commas,
+on the rest of the same line. The first argument is required; it is
+the name of this node (for details of node names, @pxref{Node Line
+Requirements}). The subsequent arguments are optional---they are the
+names of the `Next', `Previous', and `Up' pointers, in that order. We
+strongly recommend omitting them if your Texinfo document is
+hierarchically organized, as virtually all are (@address@hidden
+Pointer Creation}). You may insert spaces before or after each name
+on the @code{@@node} line if you wish; such spaces are ignored.
+
address@hidden address@hidden, in HTML output of nodes}
+Whether the node pointers are specified implicitly or explicitly, 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
address@hidden respectively. This allows people using web browsers to
+follow the navigation using (typically) @address@hidden, e.g.,
address@hidden for the `Next' node, from anywhere within the node.
+
+Usually, you write one of the chapter-structuring command lines
+immediately after an @code{@@node} line---for example, an
address@hidden@@section} or @code{@@subsection} line. @xref{Structuring
+Command Types}.
+
address@hidden uses both @code{@@node} names and chapter-structuring names in
+the output for cross references. For this reason, you must write
address@hidden@@node} lines in a Texinfo file that you intend to format for
+printing, even if you do not intend to format it for Info; and you
+must include a chapter-structuring command after a node for it to be a
+valid cross reference target (to @TeX{}). You can use @code{@@anchor}
+(@address@hidden@@anchor}}) to make cross references to an arbitrary
+position in a document.
+
+Cross references, such as the one at the end of this sentence, are
+made with @code{@@xref} and related commands; see @ref{Cross
+References}.
+
address@hidden
+* Node Names:: How to choose node and pointer 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.
+* @t{@@top} Command:: How to use the @code{@@top} command.
address@hidden menu
+
+
address@hidden Node Names
address@hidden Choosing Node and Pointer Names
+
address@hidden Node names, choosing
+The name of a node identifies the node. For all the details of node
+names, @pxref{Node Line Requirements}).
+
address@hidden Line address@hidden previous node name
+Here are some suggestions for node names:
+
address@hidden @bullet
address@hidden
+Try to pick node names that are informative but short.
+
+In the Info file, the file name, node name, and pointer names are all
+inserted on one line, which may run into the right edge of the window.
+(This does not cause a problem with Info, but is ugly.)
+
address@hidden
+Try to pick node names that differ from each other near the beginnings
+of their names. This way, it is easy to use automatic name completion in
+Info.
+
address@hidden
+By convention, node names are capitalized just as they would be for
+section or chapter titles. In this manual, initial and significant
+words are capitalized; others are not.
address@hidden itemize
+
+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
+(@address@hidden Pointer Creation}).
+
+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
+of the node that follows the present node in that menu and its
+`Previous' pointer contains the name of the node that precedes it in
+that menu. When a node's `Previous' node is the same as its `Up'
+node, both pointers name the same node.
+
+Usually, the first node of a Texinfo file is the `Top' node, and its
+`Up' pointer points to the @file{dir} file, which contains the main menu
+for all of Info.
+
+
address@hidden Writing a Node
address@hidden Writing an @code{@@node} Line
address@hidden Writing an @code{@@node} line
address@hidden @code{@@node} line writing
address@hidden Node line writing
+
+The easiest and preferred 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:
+
address@hidden
+@@node @var{node-name}
address@hidden example
+
+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 @address@hidden 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
address@hidden@@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.
+
+The template for a fully-written-out node line with `Next', `Previous',
+and `Up' pointers looks like this:
+
address@hidden
+@@node @var{node-name}, @var{next}, @var{previous}, @var{up}
address@hidden 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, as described above.
+
+It's, 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.
+
+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.
+
+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.
+
+
address@hidden Node Line Requirements
address@hidden @code{@@node} Line Requirements
+
address@hidden Node line requirements
address@hidden Restrictions on node names
+
+Names used with @code{@@node} have several requirements:
+
address@hidden @bullet
address@hidden
address@hidden Unique node names requirement
address@hidden Node names must be unique
+All the node names in a single Texinfo file must be unique.
+
+This means, for example, that if you end every chapter with a summary,
+you must name each summary node differently. You cannot just call
+them all ``Summary''. You may, however, duplicate the titles of
+chapters, sections, and the like. Thus you can end each chapter with
+a section called ``Summary'', so long as the node names for those
+sections are all different.
+
address@hidden
+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; @address@hidden
+Pointer Creation}.)
+
address@hidden
address@hidden Commands in node names
address@hidden @@-commands in node names
+Node names can contain @@-commands. The output is generally the
+natural result of the command; for example, using @code{@@address@hidden@}} in
a
+node name results in the @TeX{} logo being output, as it would be in
+normal text. Cross references should use @code{@@address@hidden@}} just as the
+node name does.
+
+For Info and HTML output, especially, it is necessary to expand
+commands to some sequence of characters; for instance,
address@hidden@@address@hidden@}} expands to the three letters @samp{TeX} in
the Info
+node name. (However, cross references to the node should not take the
+``shortcut'' of using @samp{TeX}; stick to the actual node name,
+commands and all.)
+
+Some commands do not make sense in node names; for instance,
+environments (e.g., @code{@@quotation}), commands that read a whole
+line as their argument (e.g., @code{@@sp}), and plenty of others.
+
+For the complete list of commands that are allowed, and their
+expansion for HTML identifiers and file names, @pxref{HTML Xref
+Command Expansion}. The expansions for Info are generally given with
+main the description of the command.
+
+Prior to the Texinfo 5 release in 2013, this feature was supported in
+an ad hoc way (the @option{--commands-in-node-names} option to
address@hidden). Now it is part of the language.
+
address@hidden
address@hidden Colon in node name
address@hidden Comma in node name
address@hidden Parentheses in node name
address@hidden Period in node name
address@hidden Characters, invalid in node name
address@hidden Invalid characters in node names
address@hidden Node names, invalid characters in
+Unfortunately, you cannot reliably use periods, commas, or colons
+within a node name; these confuse the Info reader. Also, a node name
+may not start with a left parenthesis preceding a right parenthesis,
+as in @code{(not)allowed}, since this syntax is used to specify an
+external manual. (Perhaps these limitations will be removed some day.)
+
+If you insist on using these characters in node names, accepting the
+resulting substandard Info output, in order not to confuse the Texinfo
+processors, you must still escape those characters, by using either
+special insertions (@pxref{Inserting a Comma}) or @code{@@asis}
+(@address@hidden@@asis}}). For example:
+
address@hidden
+@@node foo@@address@hidden::@}bar
address@hidden example
+
+As an example of avoiding the special characters, the following is a
+section title in this manual:
+
address@hidden
+@@address@hidden@@@@address@hidden, @@address@hidden@@@@address@hidden,
@@address@hidden@@@@address@hidden
address@hidden smallexample
+
address@hidden
+But the corresponding node name lacks the commas (and the @code{@@}'s,
+but that is historical):
+
address@hidden
+unnumberedsec appendixsec heading
address@hidden smallexample
+
address@hidden Case in node name
address@hidden
+Case is significant in node names.
+
address@hidden White space in node name
address@hidden Spaces in node name
+Spaces before and after names on the @samp{@@node} line are ignored.
+Multiple whitespace characters ``inside'' a name are collapsed to a
+single space. For example:
+
address@hidden
+@@node foo bar,
+@@node foo bar ,
+@@node foo bar,
+@@node foo bar ,
address@hidden example
+
address@hidden all define the same node, namely @samp{foo bar}. References
+to the node should all use that name, with no leading or trailing
+spaces a single internal space.
address@hidden itemize
+
+
address@hidden First Node
address@hidden The First Node
address@hidden Top node is first
address@hidden 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.
+
+Here is a description of the node pointers to be used in the Top node:
+
address@hidden @bullet
address@hidden
address@hidden Up node of Top node
address@hidden (dir) as Up node of Top node
+The Top node (which must be named @samp{top} or @samp{Top}) should have
+as its `Up' node the name of a node in another file, where there is a
+menu that leads to this file. Specify the file name in parentheses.
+
+Usually, all Info files are installed in one system-wide Info tree
+(often constructed from multiple directories). In this case, use
address@hidden(dir)} as the parent of the Top node; this specifies the
+top-level node in the @file{dir} file, which contains the main menu
+for the Info system as a whole.
+
address@hidden
address@hidden Next node of Top node
+The `Next' node of the Top node should be the first chapter in your
+document.
+
address@hidden itemize
+
address@hidden an Info File}, for more information about installing
+an Info file in the @file{info} directory.
+
+It is usually best to leave the pointers off entirely and let the
+tools implicitly define them, with this simple result:
+
address@hidden
+@@node Top
address@hidden example
+
+
address@hidden @t{@@top} Command
address@hidden The @code{@@top} Sectioning Command
+
address@hidden address@hidden old name
address@hidden address@hidden another old name
address@hidden top address@hidden yet another name
address@hidden top
+
+The @code{@@top} command is a special sectioning command that you
+should only use after an @samp{@@node Top} line at the beginning of a
+Texinfo file. The @code{@@top} command tells the @code{makeinfo}
+formatter which node is to be used as the root of the node tree
+(needed if your manual uses implicit node pointers).
+
+It produces the same sort of output as @code{@@unnumbered}
+(@address@hidden@@unnumbered @@appendix}}).
+
+The @code{@@top} node is conventionally wrapped in an
address@hidden@@ifnottex} conditional so that it will not appear in @TeX{}
+output (@pxref{Conditionals}).
+Thus, in practice, a Top node usually looks like this:
+
address@hidden
+@@ifnottex
+@@node Top
+@@top @var{your-manual-title}
+
address@hidden
+@@end ifnottex
address@hidden example
+
address@hidden@@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}).
+
+
address@hidden @t{makeinfo} Pointer Creation
address@hidden @code{makeinfo} Pointer Creation
+
address@hidden Creating pointers with @code{makeinfo}
address@hidden Pointer creation with @code{makeinfo}
address@hidden Automatic pointer creation with @code{makeinfo}
address@hidden 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:
+
address@hidden
+@@node My Node
address@hidden example
+
address@hidden
+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
address@hidden@@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.
address@hidden@t{@@top} Command}.
+
address@hidden Detail menu
address@hidden 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.
+
+
address@hidden @t{@@anchor}
address@hidden @code{@@anchor}: Defining Arbitrary Cross Reference Targets
+
address@hidden@c old name
address@hidden anchor
address@hidden Anchors
address@hidden Cross reference targets, arbitrary
address@hidden Targets for cross references, arbitrary
+
+An @dfn{anchor} is a position in your document, labeled so that cross
+references can refer to it, just as they can to nodes. You create an
+anchor with the @code{@@anchor} command, and give the label as a
+normal brace-delimited argument. For example:
+
address@hidden
+This marks the @@address@hidden@}spot.
address@hidden
+@@address@hidden,,the address@hidden
address@hidden example
+
address@hidden produces:
+
address@hidden
+This marks the spot.
address@hidden
+See [the spot], page 1.
address@hidden example
+
+As you can see, the @code{@@anchor} command itself produces no output.
+This example defines an anchor `x-spot' just before the word `spot'.
+You can refer to it later with an @code{@@xref} or other cross
+reference command, as shown (@pxref{Cross References}).
+
+It is best to put @code{@@anchor} commands just before the position you
+wish to refer to; that way, the reader's eye is led on to the correct
+text when they jump to the anchor. You can put the @code{@@anchor}
+command on a line by itself if that helps readability of the source.
+Whitespace (including newlines) is ignored after @code{@@anchor}.
+
+Anchor names and node names may not conflict. Anchors and nodes are
+given similar treatment in some ways; for example, the
address@hidden command takes either an anchor name or a node name as
+an argument. (@xref{Go to node,,, info, Info}.)
+
+Also like node names, anchor names cannot include some characters
+(@pxref{Node Line Requirements}).
+
address@hidden Nodes, deleting or renaming
+Because of this duality, when you delete or rename a node, it is
+usually a good idea to define an @code{@@anchor} with the old name.
+That way, any links to the old node, whether from other Texinfo
+manuals or general web pages, keep working. You can also do this with
+the @file{RENAMED_NODES_FILE} feature of @command{makeinfo}
+(@pxref{HTML Xref Link Preservation}). Both methods keep links
+on the web working; the only substantive difference is that defining
+anchors also makes the old node names available when reading the
+document in Info.
+
+
address@hidden Node Menu Illustration
address@hidden Node and Menu Illustration
+
+Here is a copy of the diagram shown earlier that illustrates a Texinfo
+file with three chapters, each of which contains two sections.
+
+The ``root'' is at the top of the diagram and the ``leaves'' are at
+the bottom. This is how such a diagram is drawn conventionally; it
+illustrates an upside-down tree. For this reason, the root node is
+called the `Top' node, and `Up' node pointers carry you closer to the
+root.
+
address@hidden
address@hidden
+ Top
+ |
+ -------------------------------------
+ | | |
+ Chapter 1 Chapter 2 Chapter 3
+ | | |
+ -------- -------- --------
+ | | | | | |
+Section Section Section Section Section Section
+ 1.1 1.2 2.1 2.2 3.1 3.2
address@hidden group
address@hidden example
+
+Using explicit pointers (not recommended, but for shown for purposes
+of the example), the fully-written command to start address@hidden
+would be this:
+
address@hidden
address@hidden
+@@node Chapter 2, Chapter 3, Chapter 1, Top
+@@comment node-name, next, previous, up
address@hidden group
address@hidden example
+
address@hidden
+This @code{@@node} line says that the name of this node is
address@hidden'', the name of the `Next' node is ``Chapter 3'', the
+name of the `Previous' node is address@hidden'', 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
+(@address@hidden Pointer Creation}), but the pointer
+relationships still obtain.
+
address@hidden Note
+`Next' and `Previous' refer to nodes at the @emph{same hierarchical
+level} in the manual, not necessarily to the next node within the
+Texinfo file. In the Texinfo file, the subsequent node may be at a
+lower level---a section-level node most often follows a chapter-level
+node, for example. (The `Top' node contains the exception to this
+rule. Since the `Top' node is the only node at that level, `Next'
+refers to the first following node, which is almost always a chapter
+or chapter-level node.)
address@hidden quotation
+
+To go to Sections 2.1 and 2.2 using Info, you need a menu inside
+Chapter 2. (@xref{Menus}.) You would write the menu just before the
+beginning of Section 2.1, like this:
+
address@hidden
address@hidden
+ @@menu
+ * Sect. 2.1:: Description of this section.
+ * Sect. 2.2:: Description.
+ @@end menu
address@hidden group
address@hidden example
+
+Using explicit pointers, the node for Sect.@: 2.1 is written like this:
+
address@hidden
address@hidden
+@@node Sect. 2.1, Sect. 2.2, Chapter 2, Chapter 2
+@@comment node-name, next, previous, up
address@hidden group
address@hidden example
+
+In Info format, the `Next' and `Previous' pointers of a node usually
+lead to other nodes at the same level---from chapter to chapter or
+from section to section (sometimes, as shown, the `Previous' pointer
+points up); an `Up' pointer usually leads to a node at the level above
+(closer to the `Top' node); and a `Menu' leads to nodes at a level
+below (closer to `leaves'). (A cross reference can point to a node at
+any level; see @ref{Cross References}.)
+
+Usually, an @code{@@node} command and a chapter structuring command
+are conventionally used together, in that order, often followed by
+indexing commands. (As shown in the example above, you may follow the
address@hidden@@node} line with a comment line, e.g., to show which pointer is
+which if explicit pointers are used.) The Texinfo processors use this
+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
address@hidden@@chapter} line, and then by indexing lines. The manual uses
+implictly determined node pointers; therefore, nothing else is needed
+on the @code{@@node} line.
+
address@hidden
address@hidden
+@@node Ending a File
+@@chapter Ending a Texinfo File
+@@cindex Ending a Texinfo file
+@@cindex Texinfo file ending
+@@cindex File ending
address@hidden group
address@hidden 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
address@hidden@@node} line followed by a comment line, an @code{@@chapter}
+line, and then by indexing lines.
+
address@hidden
address@hidden
+@@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
address@hidden
address@hidden group
address@hidden example
+
+
address@hidden Menus
address@hidden Menus
address@hidden Menus
address@hidden menu
+
address@hidden contain pointers to subordinate nodes. In online output,
+you use menus to go to such nodes. Menus have no effect in printed
+manuals and do not appear in them.
+
+It's usually best if a node with a menu does not contain much text.
+If you find yourself with a lot of text before a menu, we generally
+recommend moving all but a couple of paragraphs into a new subnode.
+Otherwise, it is easy for readers to miss the menu.
+
address@hidden
+* Menu Location:: Menus go at the ends of nodes.
+* Writing a Menu:: What is a menu?
+* Menu Parts:: A menu entry has three parts.
+* Less Cluttered Menu Entry:: Two part menu entry.
+* Menu Example:: Two and three part menu entries.
+* Other Info Files:: How to refer to a different Info file.
address@hidden menu
+
+
address@hidden Menu Location
address@hidden Menu Location
address@hidden Menu location
address@hidden Location of menus
+
+There may be at most one menu in a node. A menu is conventionally
+located at the end of a node, without any regular text or additional
+commands between the @code{@@end menu} and the beginning of the next
+node.
+
address@hidden Info format, and menus
+This convention is useful, since a reader who uses the menu could
+easily miss any such text. Also, any such post-menu text will be
+considered part of the menu in Info output (which has no marker for
+the end of a menu). Thus, a line beginning with @samp{* } will likely
+be incorrectly handled.
+
address@hidden Hierarchical documents, and menus
+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 (@address@hidden Pointer Creation}) 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.
+
+In the past, we recommended using an @samp{@@heading} command within
+an @code{@@ifinfo} conditional instead of the normal sectioning
+commands after a very short node with a menu. This had the advantage
+of making the printed output look better, because there was no very
+short text between two headings on the page. But this also does not
+work with @command{makeinfo}'s implicit pointer creation, and it also
+makes the XML output incorrect, since it does not reflect the true
+document structure. So, we no longer recommend this.
+
+
address@hidden Writing a Menu
address@hidden Writing a Menu
address@hidden Writing a menu
address@hidden Menu writing
+
+A menu consists of an @code{@@menu} command on a line by itself
+followed by menu entry lines or menu comment lines and then by an
address@hidden@@end menu} command on a line by itself.
+
+A menu looks like this:
+
address@hidden
address@hidden
+@@menu
+Larger Units of Text
+
+* Files:: All about handling files.
+* Multiples: Buffers. Multiple buffers; editing
+ several files at once.
+@@end menu
address@hidden group
address@hidden example
+
+In a menu, every line that begins with an @address@hidden }} is a @dfn{menu
+entry}. (Note the space after the asterisk.) A line that does not
+start with an @address@hidden }} may also appear in a menu. Such a line is
+not a menu entry but is a menu comment line that appears in the Info
+file. In the example above, the line @samp{Larger Units of Text} is a
+menu comment line; the two lines starting with @address@hidden }} are menu
address@hidden Spaces, in menus
+entries. Space characters in a menu are preserved as-is; this allows
+you to format the menu as you wish.
+
address@hidden address@hidden, in HTML output of menus}
+In the HTML output from @command{makeinfo}, the @code{accesskey}
+attribute is used with the values @address@hidden@samp{9} for the
+first nine entries. This allows people using web browsers to follow
+the first menu entries using (typically) @address@hidden, e.g.,
address@hidden for the first entry.
+
+
address@hidden Menu Parts
address@hidden The Parts of a Menu
address@hidden Parts of a menu
address@hidden Menu parts
address@hidden @code{@@menu} parts
+
+A menu entry has three parts, only the second of which is required:
+
address@hidden
address@hidden
+The menu entry name (optional).
+
address@hidden
+The name of the node (required).
+
address@hidden
+A description of the item (optional).
address@hidden enumerate
+
+The template for a generic menu entry looks like this (but see the
+next section for one more possibility):
+
address@hidden
+* @var{menu-entry-name}: @var{node-name}. @var{description}
address@hidden example
+
+Follow the menu entry name with a single colon and follow the node name
+with tab, comma, newline, or the two characters period and space
+(@samp{. }).
+
+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.
+
+The third part of a menu entry is a descriptive phrase or sentence.
+Menu entry names and node names are often short; the description
+explains to the reader what the node is about. A useful description
+complements the node name rather than repeats it. The description,
+which is optional, can spread over multiple lines; if it does, some
+authors prefer to indent the second line while others prefer to align
+it with the first (and all others). It's up to you. An empty line,
+or the next menu entry, ends a description.
+
+
address@hidden Less Cluttered Menu Entry
address@hidden Less Cluttered Menu Entry
address@hidden Two part menu entry
address@hidden Double-colon menu entries
address@hidden Menu entries with two colons
address@hidden Less cluttered menu entry
address@hidden Uncluttered menu entry
+
+When the menu entry name and node name are the same, you can write
+the name immediately after the asterisk and space at the beginning of
+the line and follow the name with two colons.
+
address@hidden 800
+For example, write
+
address@hidden
+* Name:: @var{description}
address@hidden example
+
address@hidden 800
address@hidden
+instead of
+
address@hidden
+* Name: Name. @var{description}
address@hidden example
+
+You should indeed use the node name for the menu entry name whenever
+possible, since it reduces visual clutter in the menu.
+
+
address@hidden Menu Example
address@hidden A Menu Example
address@hidden Menu example
address@hidden Example menu
+
+A menu looks like this in Texinfo:
+
address@hidden
address@hidden
+@@menu
+* menu entry name: Node name. A short description.
+* Node name:: This form is preferred.
+@@end menu
address@hidden group
address@hidden example
+
address@hidden 800
address@hidden
+This produces:
+
address@hidden
address@hidden
+* menu:
+
+* menu entry name: Node name. A short description.
+* Node name:: This form is preferred.
address@hidden group
address@hidden example
+
address@hidden 700
+Here is an example as you might see it in a Texinfo file:
+
address@hidden
address@hidden
+@@menu
+Larger Units of Text
+
+* Files:: All about handling files.
+* Multiples: Buffers. Multiple buffers; editing
+ several files at once.
+@@end menu
address@hidden group
address@hidden example
+
address@hidden 800
address@hidden
+This produces:
+
address@hidden
address@hidden
+* menu:
+Larger Units of Text
+
+* Files:: All about handling files.
+* Multiples: Buffers. Multiple buffers; editing
+ several files at once.
address@hidden group
address@hidden example
+
+In this example, the menu has two entries. @samp{Files} is both a menu
+entry name and the name of the node referred to by that name.
address@hidden is the menu entry name; it refers to the node named
address@hidden The line @samp{Larger Units of Text} is a comment; it
+appears in the menu, but is not an entry.
+
+Since no file name is specified with either @samp{Files} or
address@hidden, they must be the names of nodes in the same Info file
+(@pxref{Other Info Files, , Referring to Other Info Files}).
+
address@hidden Other Info Files
address@hidden Referring to Other Info Files
address@hidden Referring to other Info files
address@hidden Nodes in other Info files
address@hidden Other Info files' nodes
address@hidden Going to other Info files' nodes
address@hidden Info; other files' nodes
+
+You can create a menu entry that enables a reader in Info to go to a
+node in another Info file by writing the file name in parentheses just
+before the node name. Some examples:
+
address@hidden
address@hidden
+@@menu
+* @var{first-entry-name}:(@var{filename})@var{nodename}. @var{description}
+* (@var{filename})@var{second-node}:: @var{description}
+@@end menu
address@hidden group
address@hidden example
+
+For example, to refer directly to the @samp{Outlining} and
address@hidden nodes in the @cite{Emacs Manual}, you could write a
+menu like this:
+
address@hidden
address@hidden
+@@menu
+* Outlining: (emacs)Outline Mode. The major mode for
+ editing outlines.
+* (emacs)Rebinding:: How to redefine the
+ meaning of a key.
+@@end menu
address@hidden group
address@hidden example
+
+If you do not list the node name, but only name the file, then Info
+presumes that you are referring to the `Top' node. Examples:
+
address@hidden
address@hidden
+* Info: (info). Documentation browsing system.
+* (emacs):: The extensible, self-documenting
+ text editor.
address@hidden group
address@hidden example
+
+The GNU Emacs Texinfo mode menu updating commands only work with nodes
+within the current buffer, so you cannot use them to create menus that
+refer to other files. You must write such menus by hand.
+
+
address@hidden Cross References
address@hidden Cross References
address@hidden Making cross references
address@hidden Cross references
address@hidden References
+
address@hidden references} are used to refer the reader to other parts of the
+same or different Texinfo files. In Texinfo, nodes and anchors are the
+places to which cross references can refer.
+
address@hidden
+* References:: What cross references are for.
+* Cross Reference Commands:: A summary of the different commands.
+* Cross Reference Parts:: A cross reference has several parts.
+* @t{@@xref}:: Begin a reference with `See' @dots{}
+* Top Node Naming:: How to refer to the beginning of another file.
+* @t{@@ref}:: A reference for the last part of a
sentence.
+* @t{@@pxref}:: How to write a parenthetical cross
reference.
+* @t{@@inforef}:: How to refer to an Info-only file.
+* @t{@@url}:: How to refer to a uniform resource
locator.
+* @t{@@cite}:: How to refer to books not in the Info
system.
address@hidden menu
+
address@hidden References
address@hidden What References Are For
+
+Often, but not always, a printed document should be designed so that
+it can be read sequentially. People tire of flipping back and forth
+to find information that should be presented to them as they need
+it.
+
+However, in any document, some information will be too detailed for
+the current context, or incidental to it; use cross references to
+provide access to such information. Also, an 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
+have read.
+
+In a printed manual, a cross reference results in a page reference,
+unless it is to another manual altogether, in which case the cross
+reference names that manual.
+
+In Info, a cross reference results in an entry that you can follow
+using the Info @samp{f} command. (@xref{Help-Xref,, Following
+cross-references, info, Info}.)
+
+In HTML, a cross reference results in an hyperlink.
+
+The various cross reference commands use nodes (or anchors,
address@hidden@t{@@anchor}}) to define cross reference locations. This is
+evident in Info and HTML, in which a cross reference takes you to the
+specified location.
+
address@hidden also needs nodes to define cross reference locations, but the
+action is less obvious. When @TeX{} generates a DVI file, it records
+each node's page number and uses the page numbers in making
+references. Thus, even if you are writing a manual that will only be
+printed, and not used online, you must nonetheless write @code{@@node}
+lines in order to name the places to which you make cross references.
+
address@hidden 800
address@hidden Cross Reference Commands
address@hidden Different Cross Reference Commands
address@hidden Different cross reference commands
+
+There are four different cross reference commands:
+
address@hidden @code
address@hidden @@xref
+Used to start a sentence in the printed manual and in HTML with
address@hidden @dots{}'} or an Info cross reference saying @samp{*Note
address@hidden: @var{node}.}.
+
address@hidden @@ref
+Used within or, more often, at the end of a sentence; produces just
+the reference in the printed manual and in HTML without the preceding
+`See' (same as @code{@@xref} for Info).
+
address@hidden @@pxref
+Used within parentheses, at the end of a sentence, or otherwise before
+punctuation, to make a reference. Its output starts with a lowercase
+`see' in the printed manual and in HTML, and a lowercase @samp{*note}
+in Info. (@samp{p} is for `parenthesis'.)
+
address@hidden @@inforef
+Used to make a reference to an Info file for which there is no printed
+manual.
address@hidden table
+
address@hidden
+The @code{@@cite} command is used to make references to books and
+manuals for which there is no corresponding Info file and, therefore,
+no node to which to point. @address@hidden@@cite}}.
+
+
address@hidden Cross Reference Parts
address@hidden Parts of a Cross Reference
address@hidden Cross reference parts
address@hidden Parts of a cross reference
+
+A cross reference command to a node requires only one argument, which
+is the name of the node to which it refers. But a cross reference
+command may contain up to four additional arguments. By using these
+arguments, you can provide a cross reference name, a topic description
+or section title for the printed output, the name of a different
+manual file, and the name of a different printed manual. To refer
+to another manual as a whole, the manual file and/or the name of the
+printed manual are the only required arguments (@pxref{Top Node
+Naming}).
+
+Here is a simple cross reference example:
+
address@hidden
+@@address@hidden address@hidden
address@hidden example
+
address@hidden
+which produces
+
address@hidden
+*Note Node name::.
address@hidden example
+
address@hidden
+in Info and
+
address@hidden
+See Section @var{nnn} [Node name], page @var{ppp}.
address@hidden quotation
+
address@hidden
+in a printed manual.
+
address@hidden 700
+Here is an example of a full five-part cross reference:
+
address@hidden
address@hidden
+@@address@hidden name, Cross Reference Name, Particular Topic,
+info-file-name, A Printed address@hidden, for details.
address@hidden group
address@hidden example
+
address@hidden
+which produces
+
address@hidden
+*Note Cross Reference Name: (info-file-name)Node name,
+for details.
address@hidden example
+
address@hidden
+in Info and
+
address@hidden
+See section ``Particular Topic'' in @i{A Printed Manual}, for details.
address@hidden quotation
+
address@hidden
+in a printed book.
+
+The five possible arguments for a cross reference are:
+
address@hidden
address@hidden
+The node or anchor name (required, except for reference to whole
+manuals). This is the location to which the cross reference takes
+you. In a printed document, the location of the node provides the
+page reference only for references within the same document.
+
address@hidden
+The cross reference name. If you include this argument, it becomes
+the first part of the cross reference. It is usually omitted; then
+the topic description (third argument) is used if it was specified;
+if that was omitted as well, the node name is used.
+
address@hidden
+A topic description or section name. Often, this is the title of the
+section. This is used as the name of the reference in the printed
+manual. If omitted, the node name is used.
+
address@hidden
+The name of the manual file in which the reference is located, if it is
+different from the current file. This name is used both for Info and
+HTML.
+
address@hidden
+The name of a printed manual from a different Texinfo file.
address@hidden enumerate
+
+The template for a full five argument cross reference looks like
+this:
+
address@hidden
address@hidden
+@@address@hidden@var{node-name}, @var{cross-reference-name},
@var{title-or-topic},
address@hidden, @address@hidden
address@hidden group
address@hidden example
+
+Cross references with one, two, three, four, and five arguments are
+described separately following the description of @code{@@xref}.
+
+Write a node name in a cross reference in exactly the same way as in
+the @code{@@node} line, including the same capitalization; otherwise, the
+formatters may not find the reference.
+
+
address@hidden @t{@@xref}
address@hidden @code{@@xref}
+
address@hidden@c old name
address@hidden xref
address@hidden Cross references using @code{@@xref}
address@hidden References using @code{@@xref}
+
+The @code{@@xref} command generates a cross reference for the
+beginning of a sentence. The Info formatting commands convert it into
+an Info cross reference, which the Info @samp{f} command can use to
+bring you directly to another node. The @TeX{} typesetting commands
+convert it into a page reference, or a reference to another book or
+manual. In the HTML output format the cross reference is output
+as a hyperlink.
+
address@hidden
+* Reference Syntax:: What a reference looks like and requires.
+* One Argument:: @code{@@xref} with one argument.
+* Two Arguments:: @code{@@xref} with two arguments.
+* Three Arguments:: @code{@@xref} with three arguments.
+* Four and Five Arguments:: @code{@@xref} with four and five arguments.
address@hidden menu
+
address@hidden Reference Syntax
address@hidden What a Reference Looks Like and Requires
+
+Most often, an Info cross reference looks like this:
+
address@hidden
+*Note @var{node-name}::.
address@hidden example
+
address@hidden
+or like this
+
address@hidden
+*Note @var{cross-reference-name}: @var{node-name}.
address@hidden example
+
address@hidden
+In @TeX{}, a cross reference looks like this:
+
address@hidden
+See Section @var{section-number} address@hidden, page @var{page}.
address@hidden quotation
+
address@hidden
+or like this
+
address@hidden
+See Section @var{section-number} address@hidden, page @var{page}.
address@hidden quotation
+
+The @code{@@xref} command does not generate a period or comma to end
+the cross reference automatically. You must write that period or
+comma yourself; otherwise, Info will not recognize the end of the
+reference. (The @code{@@pxref} command works differently;
address@hidden@t{@@pxref}}.)
+
address@hidden Caution
+A period or comma @emph{must} follow the closing brace of an
address@hidden@@xref}. It is required to terminate the cross reference. This
+period or comma will appear in the output.
address@hidden quotation
+
address@hidden@@xref} must refer to a node by name. Use @code{@@node} to
+define the node (@pxref{Writing a Node}), or @code{@@anchor}
+(@address@hidden@@anchor}}).
+
address@hidden@@xref} is followed by several arguments inside braces,
+separated by commas. Whitespace before and after these commas is
+ignored.
+
+A cross reference to a node within the current file requires only the
+name of a node; but it may contain up to four additional arguments.
+Each of these variations produces a cross reference that looks
+somewhat different. A cross reference to another manual as a whole
+only requires the fourth or fifth argument.
+
address@hidden Note
+Commas separate arguments in a cross reference, so you must not
+include a comma in the title or any other part lest the formatters
+mistake them for separators. @code{@@address@hidden@}} may be used to
+protect such commas (@pxref{Inserting a Comma}).
address@hidden quotation
+
+
address@hidden One Argument
address@hidden @code{@@xref} with One Argument
address@hidden One-argument form of cross references
+
+The simplest form of @code{@@xref} takes one argument, the name of
+another node in the same Texinfo file. The Info formatters produce
+output that the Info readers can use to jump to the reference; @TeX{}
+produces output that specifies the page and section number for you;
+the HTML output is a normal hyperlink.
+
address@hidden 700
address@hidden
+For example,
+
address@hidden
+@@address@hidden address@hidden
address@hidden example
+
address@hidden
+produces
+
address@hidden
+*Note Tropical Storms::.
address@hidden example
+
address@hidden
+in Info and
+
address@hidden
+See Section 3.1 [Tropical Storms], page 24.
address@hidden quotation
+
address@hidden
+in a printed manual.
+(Note that in the preceding example the closing brace to
address@hidden@@xref}'s argument is followed by a period.)
+
+You can write a clause after the cross reference, like this:
+
address@hidden
+@@address@hidden address@hidden, for more info.
address@hidden example
+
address@hidden
+which produces
+
address@hidden
+*Note Tropical Storms::, for more info.
address@hidden example
+
address@hidden
+in Info and
+
address@hidden
+See Section 3.1 [Tropical Storms], page 24, for more info.
address@hidden quotation
+
+
address@hidden
+in a printed manual. Note that in the preceding example the closing
+brace to @code{@@xref} is followed by a comma, then the additional
+text. It's a common mistake to follow an @code{@@xref} command with a
+space, but this is never correct.
+
+
address@hidden Two Arguments
address@hidden @code{@@xref} with Two Arguments
address@hidden Two-argument form of cross references
+
+With two arguments, the second is used as the name of the cross
+reference, while the first is still the name of the node to which the
+cross reference points.
+
address@hidden 750
address@hidden
+The template is like this:
+
address@hidden
+@@address@hidden@var{node-name}, @address@hidden
address@hidden example
+
address@hidden 700
address@hidden
+For example,
+
address@hidden
+@@address@hidden Effects, address@hidden
address@hidden example
+
address@hidden
+produces:
+
address@hidden
+*Note Lightning: Electrical Effects.
address@hidden example
+
address@hidden
+in Info and
+
address@hidden
+See Section 5.2 [Electrical Effects], page 57.
address@hidden quotation
+
address@hidden
+in a printed manual.
+(Note that in the preceding example the closing brace is followed by a
+period; and that the node name is printed, not the cross reference name.)
+
+You can write a clause after the cross reference, like this:
+
address@hidden
+@@address@hidden Effects, address@hidden, for more info.
address@hidden example
+
address@hidden
+which produces
+
address@hidden
+*Note Lightning: Electrical Effects, for more info.
address@hidden example
+
address@hidden
+in Info and
+
address@hidden
+See Section 5.2 [Electrical Effects], page 57, for more info.
address@hidden quotation
+
address@hidden
+in a printed manual.
+(Note that in the preceding example the closing brace is followed by a
+comma, and then by the clause, which is followed by a period.)
+
+
address@hidden Three Arguments
address@hidden @code{@@xref} with Three Arguments
address@hidden Three-argument form of cross references
+
+A third argument replaces the node name in the @TeX{} output. The third
+argument should be the name of the section in the printed output, or
+else state the topic discussed by that section. Often, you will want to
+use initial uppercase letters so it will be easier to read when the
+reference is printed. Use a third argument when the node name is
+unsuitable because of syntax or meaning.
+
+The third argument to the xref commands must observe the same
+restrictions as node names described in @ref{Node Line Requirements}.
+The issue you're most likely to run into is that commas, periods, and
+colons cannot be used.
+
+Also, remember to write a comma or period after the closing brace of an
address@hidden@@xref} to terminate the cross reference. In the following
+examples, a clause follows a terminating comma.
+
address@hidden 750
address@hidden
+The template is like this:
+
address@hidden
address@hidden
+@@address@hidden@var{node-name}, @var{cross-reference-name}, @address@hidden
address@hidden group
address@hidden example
+
address@hidden 700
address@hidden
+For example,
+
address@hidden
address@hidden
+@@address@hidden Effects, Lightning, Thunder and address@hidden,
+for details.
address@hidden group
address@hidden example
+
address@hidden
+produces
+
address@hidden
+*Note Lightning: Electrical Effects, for details.
address@hidden example
+
address@hidden
+in Info and
+
address@hidden
+See Section 5.2 [Thunder and Lightning], page 57, for details.
address@hidden quotation
+
address@hidden
+in a printed manual.
+
+If a third argument is given and the second one is empty, then the
+third argument serves for both. (Note how two commas, side by side, mark
+the empty second argument.)
+
address@hidden
address@hidden
+@@address@hidden Effects, , Thunder and address@hidden,
+for details.
address@hidden group
address@hidden example
+
address@hidden
+produces
+
address@hidden
+*Note Thunder and Lightning: Electrical Effects, for details.
address@hidden example
+
address@hidden
+in Info and
+
address@hidden
+See Section 5.2 [Thunder and Lightning], page 57, for details.
address@hidden quotation
+
address@hidden
+in a printed manual.
+
+As a practical matter, it is often best to write cross references with
+just the first argument if the node name and the section title are the
+same (or nearly so), and with the first and third arguments only if the
+node name and title are different.
+
address@hidden xrefautomaticsectiontitle
+If you want the section title to be used by default instead of
+node names in cross references (an explicitly specified third argument
+still takes precedence), Texinfo can do this automatically:
+
address@hidden
+@@xrefautomaticsectiontitle on
address@hidden example
+
+Typically this line would be given near the beginning of the document
+and used for the whole thing. 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.
+
+
address@hidden Four and Five Arguments
address@hidden @code{@@xref} with Four and Five Arguments
address@hidden Four- and five argument forms of cross references
+
+In a cross reference, a fourth argument specifies the name of another
+Info file, different from the file in which the reference appears, and
+a fifth argument specifies its title as a printed manual.
+
+Remember that a comma or period must follow the closing brace of an
address@hidden@@xref} command to terminate the cross reference.
+
address@hidden 800
address@hidden
+The full template is:
+
address@hidden
address@hidden
+@@address@hidden@var{node-name}, @var{cross-reference-name},
@var{title-or-topic},
address@hidden, @address@hidden
address@hidden group
address@hidden example
+
address@hidden 700
address@hidden
+For example,
+
address@hidden
+@@address@hidden Effects, Lightning, Thunder and Lightning,
+weather, An Introduction to address@hidden
address@hidden example
+
address@hidden
+produces this output in Info:
+
address@hidden
+*Note Lightning: (weather)Electrical Effects.
address@hidden example
+
address@hidden
+As you can see, the name of the Info file is enclosed in parentheses
+and precedes the name of the node.
+
address@hidden
+In a printed manual, the reference looks like this:
+
address@hidden
+See section ``Thunder and Lightning'' in @cite{An Introduction to
+Meteorology}.
address@hidden quotation
+
address@hidden
+The title of the printed manual is typeset like @code{@@cite}; and the
+reference lacks a page number since @TeX{} cannot know to which page a
+reference refers when that reference is to another manual.
+
+Next case: often, you will leave out the second argument when you use
+the long version of @code{@@xref}. In this case, the third argument,
+the topic description, will be used as the cross reference name in
+Info. For example,
+
address@hidden
+@@address@hidden Effects, , Thunder and Lightning,
+weather, An Introduction to address@hidden
address@hidden example
+
address@hidden
+produces
+
address@hidden
address@hidden
+*Note Thunder and Lightning: (weather)Electrical Effects.
address@hidden group
address@hidden example
+
address@hidden
+in Info and
+
address@hidden
+See section ``Thunder and Lightning'' in @cite{An Introduction to
+Meteorology}.
address@hidden quotation
+
address@hidden
+in a printed manual.
+
+Next case: If the node name and the section title are the same in the
+other manual, you may also leave out the section title. In this case,
+the node name is used in both instances. For example,
+
address@hidden
+@@address@hidden Effects,,,
+weather, An Introduction to address@hidden
address@hidden example
+
address@hidden
+produces
+
address@hidden
address@hidden
+*Note (weather)Electrical Effects::.
address@hidden group
address@hidden example
+
address@hidden
+in Info and
+
address@hidden
+See section ``Electrical Effects'' in @cite{An Introduction to
+Meteorology}.
address@hidden quotation
+
address@hidden
+in a printed manual.
+
+A very unusual case: you may want to refer to another manual file that
+is within a single printed manual---when multiple Texinfo files are
+incorporated into the same @TeX{} run but can create separate Info or
+HTML output files. In this case, you need to specify only the fourth
+argument, and not the fifth.
+
+Finally, it's also allowed to leave out all the arguments
address@hidden the fourth and fifth, to refer to another manual as a
+whole. See the next section.
+
+
address@hidden Top Node Naming
address@hidden Naming a `Top' Node
address@hidden Naming a `Top' Node in references
address@hidden `Top' node naming for references
+
address@hidden Manual, referring to as a whole
address@hidden Referring to an entire manual
+
+Ordinarily, you must always name a node in a cross reference.
+However, it's not unusual to want to refer to another manual as a
+whole, rather than a particular section within it. In this case,
+giving any section name is an unnecessary distraction.
+
+So, with cross references to other manuals (@pxref{Four and Five
+Arguments}), if the first argument is either @samp{Top} (capitalized
+just that way) or omitted entirely, and the third argument is omitted,
+the printed output includes no node or section name. (The Info output
+includes @samp{Top} if it was given.) For example,
+
address@hidden
+@@address@hidden,,, make, The GNU Make address@hidden
address@hidden example
+
address@hidden produces
+
address@hidden
address@hidden
+*Note (make)::Top.
address@hidden group
address@hidden example
+
address@hidden and
+
address@hidden
+See @cite{The GNU Make Manual}.
address@hidden quotation
+
address@hidden
+Info readers will go to the Top node of the manual whether
+or not the `Top' node is explicitly specified.
+
+It's also possible (and is historical practice) to refer to a whole
+manual by specifying the `Top' node and an appropriate entry for the
+third argument to the @code{@@xref} command. Using this idiom, to
+make a cross reference to @cite{The GNU Make Manual}, you would write:
+
address@hidden
+@@address@hidden,, Overview, make, The GNU Make address@hidden
address@hidden example
+
address@hidden
+which produces
+
address@hidden
+*Note Overview: (make)Top.
address@hidden example
+
address@hidden
+in Info and
+
address@hidden
+See section ``Overview'' in @cite{The GNU Make Manual}.
address@hidden quotation
+
address@hidden
+in a printed manual.
+
+In this example, @samp{Top} is the name of the first node, and
address@hidden is the name of the first section of the manual. There
+is no widely-used convention for naming the first section in a printed
+manual, this is just what the Make manual happens to use. This
+arbitrariness of the first name is a principal reason why omitting the
+third argument in whole-manual cross references is preferable.
+
+
address@hidden @t{@@ref}
address@hidden @code{@@ref}
+
address@hidden@c old name
address@hidden ref
address@hidden Cross references using @code{@@ref}
address@hidden References using @code{@@ref}
+
address@hidden@@ref} is nearly the same as @code{@@xref} except that it does
+not generate a `See' in the printed output, just the reference itself.
+This makes it useful as the last part of a sentence.
+
address@hidden For example,
+
address@hidden Hurricanes
address@hidden
+For more information, @@address@hidden@}, and @@address@hidden@}.
address@hidden example
+
address@hidden
+produces in Info:
+
address@hidden
+For more information, *note This::, and *note That::.
address@hidden example
+
address@hidden
+and in printed output:
+
address@hidden
+For more information, see Section 1.1 [This], page 1,
+and Section 1.2 [That], page 2.
address@hidden quotation
+
+The @code{@@ref} command can tempt writers to express themselves in a
+manner that is suitable for a printed manual but looks awkward in the
+Info format. Bear in mind that your audience could be using both the
+printed and the Info format. For example:
+
address@hidden Sea surges
address@hidden
+Sea surges are described in @@address@hidden@}.
address@hidden example
+
address@hidden
+looks ok in the printed output:
+
address@hidden
+Sea surges are described in Section 6.7 [Hurricanes], page 72.
address@hidden quotation
+
address@hidden
+but is awkward to read in Info, ``note'' being a verb:
+
address@hidden
+Sea surges are described in *note Hurricanes::.
address@hidden example
+
+You should write a period or comma immediately after an @code{@@ref}
+command with two or more arguments. If there is no such following
+punctuation, @command{makeinfo} will generate a (grammatically
+incorrect) period in the Info output; otherwise, the cross reference
+would fail completely, due to the current syntax of Info format.
+
+In general, it is best to use @code{@@ref} only when you need some
+word other than ``see'' to precede the reference. When ``see'' (or
+``See'') is ok, @code{@@xref} and @code{@@pxref} are preferable.
+
+
address@hidden @t{@@pxref}
address@hidden @code{@@pxref}
+
address@hidden@c old name
address@hidden pxref
address@hidden Cross references using @code{@@pxref}
address@hidden References using @code{@@pxref}
+
+The parenthetical reference command, @code{@@pxref}, is nearly the
+same as @code{@@xref}, but it is best used at the end of a sentence or
+before a closing parenthesis. The command differs from @code{@@xref}
+in two ways:
+
address@hidden
address@hidden
address@hidden typesets the reference for the printed manual with a lowercase
+`see' rather than an uppercase `See'.
+
address@hidden
+The Info formatting commands automatically end the reference with a
+closing colon or period, if necessary.
address@hidden enumerate
+
address@hidden@@pxref} is designed so that the output looks right and works
+right at the end of a sentence or parenthetical phrase, both in
+printed output and in an Info file. In a printed manual, a closing
+comma or period should not follow a cross reference within
+parentheses; such punctuation is wrong. But in an Info file, suitable
+closing punctuation must follow the cross reference so Info can
+recognize its end. @code{@@pxref} spares you the need to use
+complicated methods to put a terminator into one form of the output
+and not the other.
+
address@hidden
+With one argument, a parenthetical cross reference looks like this:
+
address@hidden Flooding
address@hidden
address@hidden storms cause flooding (@@address@hidden@}) @dots{}
address@hidden example
+
address@hidden 800
address@hidden
+which produces
+
address@hidden
address@hidden
address@hidden storms cause flooding (*note Hurricanes::) @dots{}
address@hidden group
address@hidden example
+
address@hidden
+in Info and
+
address@hidden
address@hidden storms cause flooding (see Section 6.7 [Hurricanes], page 72)
@dots{}
address@hidden quotation
+
address@hidden
+in a printed manual.
+
+With two arguments, a parenthetical cross reference has this template:
+
address@hidden
address@hidden (@@address@hidden@var{node-name}, @address@hidden) @dots{}
address@hidden example
+
address@hidden
+which produces
+
address@hidden
address@hidden (*note @var{cross-reference-name}: @var{node-name}.) @dots{}
address@hidden example
+
address@hidden
+in Info and
+
address@hidden
address@hidden (see Section @var{nnn} address@hidden, page @var{ppp}) @dots{}
address@hidden quotation
+
address@hidden
+in a printed manual.
+
address@hidden@@pxref} can be used with up to five arguments, just like
address@hidden@@xref} (@address@hidden@@xref}}).
+
+In past versions of Texinfo, it was not allowed to write punctuation
+after an @code{@@pxref}, so it could be used @emph{only} before a
+right parenthesis. This is no longer the case, so now it can be used
+(for example) at the end of a sentence, where a lowercase ``see''
+works best. For instance:
+
address@hidden
address@hidden For more information, @@address@hidden@}.
address@hidden example
+
address@hidden
+which outputs (in Info):
+
address@hidden
address@hidden For more information, *note More::.
address@hidden example
+
address@hidden
+In general, @code{@@pxref} should only be followed by a comma, period,
+or right parenthesis; in other cases, @command{makeinfo} has to insert
+a period to make the cross reference work correctly in Info, and that
+period looks wrong.
+
+As a matter of style, @code{@@pxref} is best used at the ends of
+sentences. Although it technically works in the middle of a sentence,
+that location breaks up the flow of reading.
+
+
address@hidden @t{@@inforef}
address@hidden @code{@@inforef}: Cross References to Info-only Material
+
address@hidden@c old name
address@hidden inforef
address@hidden Cross references using @code{@@inforef}
address@hidden References using @code{@@inforef}
+
address@hidden@@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.
+
+The command takes either two or three arguments, in the following
+order:
+
address@hidden
address@hidden
+The node name.
+
address@hidden
+The cross reference name (optional).
+
address@hidden
+The Info file name.
address@hidden enumerate
+
address@hidden
+Separate the arguments with commas, as with @code{@@xref}. Also, you
+must terminate the reference with a comma or period after the
address@hidden@}}, as you do with @code{@@xref}.
+
address@hidden
+The template is:
+
address@hidden
+@@address@hidden@var{node-name}, @var{cross-reference-name}, @address@hidden,
address@hidden example
+
address@hidden 800
address@hidden
+For example,
+
address@hidden
address@hidden
+@@address@hidden, Advanced Info commands, address@hidden,
+for more information.
address@hidden group
address@hidden example
+
address@hidden 800
address@hidden
+produces (in Info):
+
address@hidden
address@hidden
+*Note Advanced Info commands: (info)Advanced,
+for more information.
address@hidden group
address@hidden example
+
address@hidden 800
address@hidden
+and (in the printed output):
+
address@hidden
+See Info file @file{info}, node @samp{Advanced}, for more information.
address@hidden quotation
+
+(This particular example is not realistic, since the Info manual is
+written in Texinfo, so all formats are available. In fact, we don't
+know of any extant Info-only manuals.)
+
+The converse of @code{@@inforef} is @code{@@cite}, which is used to
+refer to printed works for which no Info form exists.
address@hidden@t{@@cite}}.
+
+
address@hidden @t{@@url}
address@hidden @code{@@url}, @code{@@address@hidden@var{url}[, @var{text}][,
@address@hidden
+
address@hidden@c old name
address@hidden uref
address@hidden Uniform resource locator, referring to
address@hidden URL, referring to
+
address@hidden @code{href}, producing HTML
address@hidden@@uref} produces a reference to a uniform resource locator (url).
+It takes one mandatory argument, the url, and two optional arguments
+which control the text that is displayed. In HTML output, @code{@@uref}
+produces a link you can follow.
+
address@hidden @code{@@url} is a synonym for @code{@@uref}.
+(Originally, @code{@@url} had the meaning of @code{@@indicateurl}
+(@address@hidden@@indicateurl}}), but in practice it was almost always
+misused. So we've changed the meaning.)
+
+The second argument, if specified, is the text to display (the default
+is the url itself); in Info and DVI output, but not in HTML output, the
+url is output in addition to this text.
+
address@hidden Man page, reference to
+The third argument, if specified, is the text to display, but in this
+case the url is not output in any format. This is useful when the
+text is already sufficiently referential, as in a man page. If the
+third argument is given, the second argument is ignored.
+
address@hidden Line breaking, and urls
address@hidden Breakpoints within urls
address@hidden allows line breaking within urls at only a few characters
+(which are special in urls): @samp{&}, @samp{.}, @samp{#}, @samp{?},
+and @samp{/} (but not between @samp{/} characters). A tiny amount of
+stretchable space is also inserted around these characters to help
+with line breaking. For HTML output, modern browsers will also do
+line breaking within displayed urls. If you need to allow breaks at
+other characters you can insert @code{@@/} as needed (@pxref{Line
+Breaks}).
+
address@hidden urefbreakstyle
+By default, any such breaks at special characters will occur after the
+character. Some people prefer such breaks to happen after the special
+character. This can be controlled with the @code{@@urefbreakstyle}
+command (this command has effect only in @TeX{}):
+
+Write this command at the
+beginning of a line with a single word as an argument, one of the
+following:
+
address@hidden address@hidden, value for @code{@@urefbreakstyle}}
address@hidden address@hidden, value for @code{@@urefbreakstyle}}
address@hidden address@hidden, value for @code{@@urefbreakstyle}}
address@hidden @samp
address@hidden after
+(the default) Potentially break after the special characters.
address@hidden before
+Potentially break before the special characters.
address@hidden none
+Do not consider breaking at the special characters; any potential
+breaks must be manually inserted.
address@hidden table
+
+Here is an example of the simple one argument form, where the url is
+both the target and the text of the link:
+
address@hidden
+The official GNU ftp site is @@address@hidden://ftp.gnu.org/address@hidden
address@hidden example
+
address@hidden produces:
address@hidden
+The official GNU ftp site is @uref{http://ftp.gnu.org/gnu}.
address@hidden display
+
+
+An example of the two-argument form:
address@hidden
+The official @@address@hidden://ftp.gnu.org/gnu, GNU ftp address@hidden
+holds programs and texts.
address@hidden example
+
address@hidden produces:
address@hidden
+The official @uref{http://ftp.gnu.org/gnu, GNU ftp site}
+holds programs and texts.
address@hidden display
+
address@hidden that is, the Info output is this:
address@hidden
+The official GNU ftp site (http://ftp.gnu.org/gnu)
+holds programs and texts.
address@hidden example
+
address@hidden and the HTML output is this:
address@hidden
+The official <a href="http://ftp.gnu.org/gnu";>GNU ftp site</a>
+holds programs and texts.
address@hidden example
+
+
+An example of the three-argument form:
address@hidden
+The @@address@hidden/man.cgi/1/ls,,address@hidden program @dots{}
address@hidden example
+
address@hidden produces:
address@hidden
+The @uref{/man.cgi/1/ls,,ls} program @dots{}
address@hidden display
+
address@hidden but with HTML:
address@hidden
+The <a href="/man.cgi/1/ls">ls</a> program @dots{}
address@hidden example
+
+Some people prefer to display urls in the unambiguous format:
+
address@hidden
+<URL:http://@var{host}/@var{path}>
address@hidden display
+
address@hidden
address@hidden @code{<URL...>} convention, not used
+You can use this form in the input file if you wish. We feel it's not
+necessary to include the @samp{<URL:} and @samp{>} in the output,
+since any software that tries to detect urls in text already has to
+detect them without the @samp{<URL:} to be useful.
+
+To merely indicate a url without creating a link people can follow,
+use @code{@@indicateurl} (@address@hidden@@indicateurl}}).
+
+
address@hidden @t{@@cite}
address@hidden @code{@@address@hidden@address@hidden
+
address@hidden@c old name
address@hidden cite
+
+Use the @code{@@cite} command for the name of a book that lacks a
+companion Info file. The command produces italics in the printed
+manual, and quotation marks in the Info file.
+
+If a book is written in Texinfo, it is better to use a cross reference
+command since a reader can easily follow such a reference in Info.
address@hidden@t{@@xref}}.
+
+
address@hidden Marking Text
address@hidden Marking Text, Words and Phrases
address@hidden Paragraph, marking text within
address@hidden Marking words and phrases
address@hidden Words and phrases, marking them
address@hidden Marking text within a paragraph
address@hidden Text, marking up
+
+In Texinfo, you can mark words and phrases in a variety of ways.
+The Texinfo formatters use this information to determine how to
+highlight the text.
+You can specify, for example, whether a word or phrase is a
+defining occurrence, a metasyntactic variable, or a symbol used in a
+program. Also, you can emphasize text, in several different ways.
+
address@hidden
+* Indicating:: How to indicate definitions, files, etc.
+* Emphasis:: How to emphasize text.
address@hidden menu
+
+
address@hidden Indicating
address@hidden Indicating Definitions, Commands, etc.
+
address@hidden Highlighting text
address@hidden Indicating commands, definitions, etc.
+
+Texinfo has commands for indicating just what kind of object a piece of
+text refers to. For example, metasyntactic variables are marked by
address@hidden@@var}, and code by @code{@@code}. Since the pieces of text are
+labeled by commands that tell what kind of object they are, it is easy
+to change the way the Texinfo formatters prepare such text. (Texinfo is
+an @emph{intentional} formatting language rather than a @emph{typesetting}
+formatting language.)
+
+For example, in a printed manual,
+code is usually illustrated in a typewriter font;
address@hidden@@code} tells @TeX{} to typeset this text in this font. But it
+would be easy to change the way @TeX{} highlights code to use another
+font, and this change would not affect how keystroke examples are
+highlighted. If straight typesetting commands were used in the body
+of the file and you wanted to make a change, you would need to check
+every single occurrence to make sure that you were changing code and
+not something else that should not be changed.
+
address@hidden
+* Useful Highlighting:: Highlighting provides useful information.
+* @t{@@code}:: Indicating program code.
+* @t{@@kbd}:: Showing keyboard input.
+* @t{@@key}:: Specifying keys.
+* @t{@@samp}:: Indicating a literal sequence of
characters.
+* @t{@@verb}:: Indicating a verbatim sequence of
characters.
+* @t{@@var}:: Indicating metasyntactic variables.
+* @t{@@env}:: Indicating environment variables.
+* @t{@@file}:: Indicating file names.
+* @t{@@command}:: Indicating command names.
+* @t{@@option}:: Indicating option names.
+* @t{@@dfn}:: Specifying definitions.
+* @t{@@abbr}:: Indicating abbreviations.
+* @t{@@acronym}:: Indicating acronyms.
+* @t{@@indicateurl}:: Indicating an example url.
+* @t{@@email}:: Indicating an electronic mail address.
address@hidden menu
+
+
address@hidden Useful Highlighting
address@hidden Highlighting Commands are Useful
+
+The commands serve a variety of purposes:
+
address@hidden @code
address@hidden @@address@hidden@address@hidden
+Indicate text that is a literal example of a piece of a program.
address@hidden@t{@@code}}.
+
address@hidden @@address@hidden@address@hidden
+Indicate keyboard input. @address@hidden@@kbd}}.
+
address@hidden @@address@hidden@address@hidden
+Indicate the conventional name for a key on a keyboard.
address@hidden@t{@@key}}.
+
address@hidden @@address@hidden@address@hidden
+Indicate text that is a literal example of a sequence of characters.
address@hidden@t{@@samp}}.
+
address@hidden @@address@hidden@address@hidden
+Write a verbatim sequence of characters.
address@hidden@t{@@verb}}.
+
address@hidden @@address@hidden@address@hidden
+Indicate a metasyntactic variable. @address@hidden@@var}}.
+
address@hidden @@address@hidden@address@hidden
+Indicate an environment variable. @address@hidden@@env}}.
+
address@hidden @@address@hidden@address@hidden
+Indicate the name of a file. @address@hidden@@file}}.
+
address@hidden @@address@hidden@address@hidden
+Indicate the name of a command.
address@hidden@t{@@command}}.
+
address@hidden @@address@hidden@address@hidden
+Indicate a command-line option.
address@hidden@t{@@option}}.
+
address@hidden @@address@hidden@address@hidden
+Indicate the introductory or defining use of a term.
address@hidden@t{@@dfn}}.
+
address@hidden @@address@hidden@address@hidden
+Indicate the name of a book. @address@hidden@@cite}}.
+
address@hidden @@address@hidden@address@hidden
+Indicate an abbreviation, such as `Comput.'.
+
address@hidden @@address@hidden@address@hidden
+Indicate an acronym. @address@hidden@@acronym}}.
+
address@hidden @@address@hidden@address@hidden
+Indicate an example (that is, nonfunctional) uniform resource locator.
address@hidden@t{@@indicateurl}}. (Use @code{@@url} (@address@hidden@@url}})
for
+live urls.)
+
address@hidden @@address@hidden@var{email-address}[, @address@hidden
+Indicate an electronic mail address. @address@hidden@@email}}.
+
address@hidden table
+
+
address@hidden @t{@@code}
address@hidden @code{@@address@hidden@address@hidden
+
address@hidden@c old name
address@hidden code
+
address@hidden Syntactic tokens, indicating
+Use the @code{@@code} command to indicate text that is a piece of a
+program and which consists of entire syntactic tokens. Enclose the
+text in braces.
+
address@hidden Expressions in a program, indicating
address@hidden Keywords, indicating
address@hidden Reserved words, indicating
+Thus, you should use @code{@@code} for an expression in a program, for
+the name of a variable or function used in a program, or for a
+keyword in a programming language.
+
+Use @code{@@code} for command names in languages that resemble
+programming languages, such as Texinfo. For example, @code{@@code} and
address@hidden@@samp} are produced by writing
@samp{@@address@hidden@@@@address@hidden and
address@hidden@@address@hidden@@@@address@hidden in the Texinfo source,
respectively.
+
address@hidden Case, not altering in @code{@@code}
+It is incorrect to alter the case of a word inside an @code{@@code}
+command when it appears at the beginning of a sentence. Most computer
+languages are case sensitive. In C, for example, @code{Printf} is
+different from the identifier @code{printf}, and most likely is a
+misspelling of it. Even in languages which are not case sensitive, it
+is confusing to a human reader to see identifiers spelled in different
+ways. Pick one spelling and always use that. If you do not want to
+start a sentence with a command name written all in lowercase, you
+should rearrange the sentence.
+
+In the Info output, @code{@@code} results in single quotation marks
+around the text. In other formats, @code{@@code} argument is typeset
+in a typewriter (monospace) font. For example,
+
address@hidden
+The function returns @@address@hidden@}.
address@hidden example
+
address@hidden
+produces this:
+
address@hidden
+The function returns @code{nil}.
address@hidden quotation
+
+Here are some cases for which it is preferable @emph{not} to use @code{@@code}:
+
address@hidden @bullet
address@hidden
+For shell command names such as @command{ls} (use @code{@@command}).
+
address@hidden
+For environment variable such as @env{TEXINPUTS} (use @code{@@env}).
+
address@hidden
+For shell options such as @samp{-c} when such options stand alone (use
address@hidden@@option}).
+
address@hidden
+An entire shell command often looks better if written using
address@hidden@@samp} rather than @code{@@code}. In this case, the rule is to
+choose the more pleasing format.
+
address@hidden
+For a string of characters shorter than a syntactic token. For example,
+if you are writing about @samp{goto-ch}, which is just a part of the
+name for the @code{goto-char} Emacs Lisp function, you should use
address@hidden@@samp}.
+
address@hidden
+In general, when writing about the characters used in a token; for
+example, do not use @code{@@code} when you are explaining what letters
+or printable symbols can be used in the names of functions. (Use
address@hidden@@samp}.) Also, you should not use @code{@@code} to mark text
+that is considered input to programs unless the input is written in a
+language that is like a programming language. For example, you should
+not use @code{@@code} for the keystroke commands of GNU Emacs (use
address@hidden@@kbd} instead) although you may use @code{@@code} for the names
+of the Emacs Lisp functions that the keystroke commands invoke.
+
address@hidden itemize
+
+By default, @TeX{} will consider breaking lines at @samp{-} and
address@hidden characters within @code{@@code} and related commands. This
+can be controlled with @code{@@allowcodebreaks}
+(@address@hidden@@allowcodebreaks}}). The HTML output attempts to
+respect this for @samp{-}, but ultimately it is up to the browser's
+behavior. For Info, it seems better never to make such breaks.
+
+For Info, the quotes are omitted in the output of the @code{@@code}
+command and related commands (e.g., @code{@@kbd}, @code{@@command}),
+in typewriter-like contexts such as the @code{@@example} environment
+(@address@hidden@@example}}) and @code{@@code} itself, etc.
+
+To control which quoting characters are implicitly inserted by Texinfo
+processors in the output of @samp{@@code}, etc., see the
address@hidden and @code{CLOSE_QUOTE_SYMBOL} customization
+variables (@pxref{Other Customization Variables}). This is separate
+from how actual quotation characters in the input document are handled
+(@pxref{Inserting Quote Characters}).
+
+
address@hidden @t{@@kbd}
address@hidden @code{@@address@hidden@address@hidden
+
address@hidden@c old name
address@hidden kbd
address@hidden Keyboard input
+
+Use the @code{@@kbd} command for characters of input to be typed by
+users. For example, to refer to the characters @kbd{M-a}, write:
+
address@hidden
+@@address@hidden@}
address@hidden example
+
address@hidden
+and to refer to the characters @kbd{M-x shell}, write:
+
address@hidden
+@@address@hidden address@hidden
address@hidden example
+
address@hidden User input
address@hidden Slanted typewriter font, for @code{@@kbd}
+By default, the @code{@@kbd} command produces a different font
+(slanted typewriter instead of normal typewriter),
+so users can distinguish the characters that they are supposed
+to type from those that the computer outputs.
+
address@hidden kbdinputstyle
+Since the usage of @code{@@kbd} varies from manual to manual, you can
+control the font switching with the @code{@@kbdinputstyle} command.
+This command has no effect on Info output. Write this command at the
+beginning of a line with a single word as an argument, one of the
+following:
+
address@hidden address@hidden, value for @code{@@kbdinputstyle}}
address@hidden address@hidden, value for @code{@@kbdinputstyle}}
address@hidden address@hidden, value for @code{@@kbdinputstyle}}
address@hidden @samp
address@hidden code
+Always use the same font for @code{@@kbd} as @code{@@code}.
address@hidden example
+Use the distinguishing font for @code{@@kbd} only in @code{@@example}
+and similar environments.
address@hidden distinct
+(the default) Always use the distinguishing font for @code{@@kbd}.
address@hidden table
+
+You can embed another @@-command inside the braces of an @code{@@kbd}
+command. Here, for example, is the way to describe a command that
+would be described more verbosely as ``press the @samp{r} key and then
+press the @key{RETURN} key'':
+
address@hidden
+@@address@hidden @@address@hidden@address@hidden
address@hidden example
+
address@hidden
+This produces: @kbd{r @key{RET}}. (The present manual uses the
+default for @code{@@kbdinputstyle}.)
+
+You also use the @code{@@kbd} command if you are spelling out the letters
+you type; for example:
+
address@hidden
+To give the @@address@hidden@} command,
+type the characters @@address@hidden o g o u t @@address@hidden@address@hidden
address@hidden example
+
address@hidden
+This produces:
+
address@hidden
+To give the @code{logout} command,
+type the characters @kbd{l o g o u t @key{RET}}.
address@hidden quotation
+
+(Also, this example shows that you can add spaces for clarity. If you
+explicitly want to mention a space character as one of the characters of
+input, write @kbd{@@address@hidden@}} for it.)
+
+
address@hidden @t{@@key}
address@hidden @code{@@address@hidden@address@hidden
+
address@hidden@c old name
address@hidden key
+
+Use the @code{@@key} command for the conventional name for a key on a
+keyboard, as in:
+
address@hidden
+@@address@hidden@}
address@hidden example
+
+You can use the @code{@@key} command within the argument of an
address@hidden@@kbd} command when the sequence of characters to be typed
+includes one or more keys that are described by name.
+
+For example, to produce @kbd{C-x @key{ESC}} and @address@hidden you
+would type:
+
address@hidden
+@@address@hidden @@address@hidden@address@hidden
+@@address@hidden@@address@hidden@address@hidden
address@hidden example
+
+Here is a list of the recommended names for keys:
address@hidden Recommended names for keys
address@hidden Keys, recommended names
address@hidden Names recommended for keys
address@hidden Abbreviations for keys
address@hidden Control keys, specifying
address@hidden Meta keys, specifying
+
address@hidden
address@hidden @t
address@hidden SPC
+Space
address@hidden RET
+Return
address@hidden LFD
+Linefeed (however, since most keyboards nowadays do not have a Linefeed key,
+it might be better to call this character @kbd{C-j})
address@hidden TAB
+Tab
address@hidden BS
+Backspace
address@hidden ESC
+Escape
address@hidden DELETE
+Delete
address@hidden SHIFT
+Shift
address@hidden CTRL
+Control
address@hidden META
+Meta
address@hidden table
address@hidden quotation
+
address@hidden META key
+There are subtleties to handling words like `meta' or `ctrl' that are
+names of modifier keys. When mentioning a character in which the
+modifier key is used, such as @kbd{Meta-a}, use the @code{@@kbd} command
+alone; do not use the @code{@@key} command; but when you are referring
+to the modifier key in isolation, use the @code{@@key} command. For
+example, write @samp{@@address@hidden@}} to produce @kbd{Meta-a} and
address@hidden@@address@hidden@}} to produce @key{META}.
+
+As a convention in GNU manuals, @code{@@key} should not be used in
+index entries.
+
+
address@hidden @t{@@samp}
address@hidden @code{@@address@hidden@address@hidden
+
address@hidden@c old name
address@hidden samp
+
+Use the @code{@@samp} command to indicate text that is a literal example
+or `sample' of a sequence of characters in a file, string, pattern, etc.
+Enclose the text in braces. The argument appears within single
+quotation marks in both the Info file and the printed manual; in
+addition, it is printed in a fixed-width font.
+
address@hidden
+To match @@address@hidden@} at the end of the line,
+use the regexp @@address@hidden@}.
address@hidden example
+
address@hidden
+produces
+
address@hidden
+To match @samp{foo} at the end of the line, use the regexp
address@hidden
address@hidden quotation
+
+Any time you are referring to single characters, you should use
address@hidden@@samp} unless @code{@@kbd} or @code{@@key} is more appropriate.
+Also, you may use @code{@@samp} for entire statements in C and for entire
+shell commands---in this case, @code{@@samp} often looks better than
address@hidden@@code}. Basically, @code{@@samp} is a catchall for whatever is
+not covered by @code{@@code}, @code{@@kbd}, @code{@@key},
address@hidden@@command}, etc.
+
+Only include punctuation marks within braces if they are part of the
+string you are specifying. Write punctuation marks outside the braces
+if those punctuation marks are part of the English text that surrounds
+the string. In the following sentence, for example, the commas and
+period are outside of the braces:
+
address@hidden
address@hidden
+In English, the vowels are @@address@hidden@}, @@address@hidden@},
+@@address@hidden@}, @@address@hidden@}, @@address@hidden@}, and sometimes
+@@address@hidden@}.
address@hidden group
address@hidden example
+
address@hidden
+This produces:
+
address@hidden
+In English, the vowels are @samp{a}, @samp{e},
address@hidden, @samp{o}, @samp{u}, and sometimes
address@hidden
address@hidden quotation
+
+
address@hidden @t{@@verb}
address@hidden @code{@@address@hidden@address@hidden@address@hidden
+
address@hidden@c old name
address@hidden verb
address@hidden Verbatim in-line text
+
address@hidden Delimiter character, for verbatim
+Use the @code{@@verb} command to print a verbatim sequence of
+characters.
+
+Like @LaTeX{}'s @code{\verb} command, the verbatim text can be quoted using
+any unique delimiter character. Enclose the verbatim text, including the
+delimiters, in braces. Text is printed in a fixed-width font:
+
address@hidden
+How many @@address@hidden|@@|@}-escapes does one need to print this
+@@address@hidden@@a @@b.@@address@hidden string or
@@address@hidden@@'address@hidden@address@hidden this?
address@hidden example
+
address@hidden
+produces
+
address@hidden
+How many @verb{|@|}-escapes does one need to print this
address@hidden@a @address@hidden string or @verb{+@'e?`{}!`\+} this?
address@hidden example
+
+This is in contrast to @code{@@samp} (see the previous section),
address@hidden@@code}, and similar commands; in those cases, the argument is
+normal Texinfo text, where the three characters @code{@@@address@hidden are
+special, as usual. With @code{@@verb}, nothing is special except the
+delimiter character you choose.
+
+The delimiter character itself may appear inside the verbatim text, as
+shown above. As another example, @samp{@@address@hidden@}} prints a single
+(fixed-width) period.
+
+It is not reliable to use @code{@@verb} inside other Texinfo
+constructs. In particular, it does not work to use @code{@@verb} in
+anything related to cross referencing, such as section titles or
+figure captions.
+
+
address@hidden @t{@@var}
address@hidden @code{@@address@hidden@address@hidden
+
address@hidden@c old name
address@hidden var
+
+Use the @code{@@var} command to indicate metasyntactic variables. A
address@hidden variable} is something that stands for another
+piece of text. For example, you should use a metasyntactic variable
+in the documentation of a function to describe the arguments that are
+passed to that function.
+
+Do not use @code{@@var} for the names of normal variables in computer
+programs. These are specific names, so @code{@@code} is correct for
+them (@t{@@code}). For example, the Emacs Lisp variable
address@hidden is not a metasyntactic variable; it is
+properly formatted using @code{@@code}.
+
+Do not use @code{@@var} for environment variables either; @code{@@env}
+is correct for them (see the next section).
+
+The effect of @code{@@var} in the Info file is to change the case of
+the argument to all uppercase. In the printed manual and HTML
+output, the argument is output in slanted type.
+
address@hidden 700
+For example,
+
address@hidden
+To delete file @@address@hidden@},
+type @@address@hidden @@address@hidden@address@hidden
address@hidden example
+
address@hidden
+produces
+
address@hidden
+To delete file @var{filename}, type @samp{rm @var{filename}}.
address@hidden quotation
+
address@hidden
+(Note that @code{@@var} may appear inside @code{@@code},
address@hidden@@samp}, @code{@@file}, etc.)
+
+Write a metasyntactic variable all in lowercase without spaces, and
+use hyphens to make it more readable. Thus, the Texinfo source for
+the illustration of how to begin a Texinfo manual looks like
+this:
+
address@hidden
address@hidden
+\input texinfo
+@@@@setfilename @@address@hidden@}
+@@@@settitle @@address@hidden@}
address@hidden group
address@hidden example
+
address@hidden
+This produces:
+
address@hidden
address@hidden
+\input texinfo
+@@setfilename @var{info-file-name}
+@@settitle @var{name-of-manual}
address@hidden group
address@hidden example
+
+In some documentation styles, metasyntactic variables are shown with
+angle brackets, for example:
+
address@hidden
address@hidden, type rm <filename>
address@hidden example
+
address@hidden
+However, that is not the style that Texinfo uses.
+
address@hidden FIXME add a customization variable? Add an example on how to do
that
address@hidden for HTML?
address@hidden (You can, of course, modify the sources to @file{texinfo.tex}
address@hidden and the Info formatting commands
address@hidden to output the @code{<@dots{}>} format if you wish.)
+
+
address@hidden @t{@@env}
address@hidden @code{@@address@hidden@address@hidden
+
address@hidden@c old name
address@hidden env
+
+Use the @code{@@env} command to indicate environment variables, as
+used by many operating systems, including address@hidden Do not use it for
address@hidden variables; use @code{@@var} for those (see the
+previous section).
+
address@hidden@@env} is equivalent to @code{@@code} in its effects.
+For example:
+
address@hidden
+The @@address@hidden@} environment variable @dots{}
address@hidden example
address@hidden produces
address@hidden
+The @env{PATH} environment variable @dots{}
address@hidden quotation
+
+
address@hidden @t{@@file}
address@hidden @code{@@address@hidden@address@hidden
+
address@hidden@c old name
address@hidden file
+
+Use the @code{@@file} command to indicate text that is the name of a
+file, buffer, or directory, or is the name of a node in Info. You can
+also use the command for file name suffixes. Do not use @code{@@file}
+for symbols in a programming language; use @code{@@code}.
+
address@hidden@@file} is equivalent to @code{code} in its effects. For
+example,
+
address@hidden
+The @@address@hidden@} files are in
+the @@address@hidden/usr/local/emacs/address@hidden directory.
address@hidden example
+
address@hidden
+produces
+
address@hidden
+The @file{.el} files are in
+the @file{/usr/local/emacs/lisp} directory.
address@hidden quotation
+
+
address@hidden @t{@@command}
address@hidden @code{@@address@hidden@address@hidden
+
address@hidden@c old name
address@hidden command
address@hidden Command names, indicating
address@hidden Program names, indicating
+
+Use the @code{@@command} command to indicate command names, such as
address@hidden or @command{cc}.
+
address@hidden@@command} is equivalent to @code{@@code} in its effects.
+For example:
+
address@hidden
+The command @@address@hidden@} lists directory contents.
address@hidden example
address@hidden produces
address@hidden
+The command @command{ls} lists directory contents.
address@hidden quotation
+
+You should write the name of a program in the ordinary text font, rather
+than using @code{@@command}, if you regard it as a new English word,
+such as `Emacs' or `Bison'.
+
+When writing an entire shell command invocation, as in @samp{ls -l},
+you should use either @code{@@samp} or @code{@@code} at your discretion.
+
+
address@hidden @t{@@option}
address@hidden @code{@@address@hidden@address@hidden
+
address@hidden@c old name
address@hidden option
+
+Use the @code{@@option} command to indicate a command-line option; for
+example, @option{-l} or @option{--version} or
address@hidden@var{filename}}.
+
address@hidden@@option} is equivalent to @code{@@code} in its effects.
+For example:
+
address@hidden
+The option @@address@hidden@} produces a long listing.
address@hidden example
address@hidden produces
address@hidden
+The option @option{-l} produces a long listing.
address@hidden quotation
+
+
address@hidden @t{@@dfn}
address@hidden @code{@@address@hidden@address@hidden
+
address@hidden@c old name
address@hidden dfn
+
+Use the @code{@@dfn} command to identify the introductory or defining
+use of a technical term. Use the command only in passages whose
+purpose is to introduce a term which will be used again or which the
+reader ought to know. Mere passing mention of a term for the first
+time does not deserve @code{@@dfn}. The command generates italics in
+the printed manual, and double quotation marks in the Info file. For
+example:
+
address@hidden
+Getting rid of a file is called @@address@hidden@} it.
address@hidden example
+
address@hidden
+produces
+
address@hidden
+Getting rid of a file is called @dfn{deleting} it.
address@hidden quotation
+
+As a general rule, a sentence containing the defining occurrence of a
+term should be a definition of the term. The sentence does not need
+to say explicitly that it is a definition, but it should contain the
+information of a definition---it should make the meaning clear.
+
+
address@hidden @t{@@abbr}
address@hidden @code{@@address@hidden@var{abbreviation}[, @address@hidden
+
address@hidden@c old name
address@hidden abbr
+
address@hidden Abbreviations, tagging
+You can use the @code{@@abbr} command for general abbreviations. The
+abbreviation is given as the single argument in braces, as in
address@hidden@@address@hidden@}}. As a matter of style, or for particular
+abbreviations, you may prefer to omit periods, as in
address@hidden@@address@hidden@} Stallman}.
+
address@hidden@@abbr} accepts an optional second argument, intended to be used
+for the meaning of the abbreviation.
+
+If the abbreviation ends with a lowercase letter and a period, and is
+not at the end of a sentence, and has no second argument, remember to
+use the @code{@@.} command (@pxref{Ending a Sentence}) to get the
+correct spacing. However, you do not have to use @code{@@.} within
+the abbreviation itself; Texinfo automatically assumes periods within
+the abbreviation do not end a sentence.
+
address@hidden @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 @code{<abbrev>} tag is used. For instance:
+
address@hidden
+@@address@hidden J., Computer address@hidden
address@hidden example
+
address@hidden produces:
+
address@hidden
address@hidden J., Computer Journal}
address@hidden display
+
+For abbreviations consisting of all capital letters, you may prefer to
+use the @code{@@acronym} command instead. See the next section for
+more on the usage of these two commands.
+
+
address@hidden @t{@@acronym}
address@hidden @code{@@address@hidden@var{acronym}[, @address@hidden
+
address@hidden@c old name
address@hidden acronym
+
address@hidden NASA, as acronym
address@hidden Acronyms, tagging
+You can use the @code{@@acronym} command for abbreviations written in
+all capital letters, such as address@hidden'. The abbreviation is
+given as the single argument in braces, as in
address@hidden@@address@hidden@}}. As a matter of style, or for particular
+acronyms, you may prefer to use periods, as in
address@hidden@@address@hidden@}}.
+
address@hidden@@acronym} accepts an optional second argument, intended to be
+used for the meaning of the acronym.
+
+If the acronym is at the end of a sentence, and if there is no second
+argument, remember to use the @code{@@.} or similar command
+(@pxref{Ending a Sentence}) to get the correct spacing.
+
address@hidden @code{<acronym>} tag
+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.
+
+For instance (since GNU is a recursive acronym, we use
address@hidden@@acronym} recursively):
+
address@hidden
+@@address@hidden, @@address@hidden@}'s Not address@hidden
address@hidden example
+
address@hidden produces:
+
address@hidden
address@hidden, @acronym{GNU}'s Not Unix}
address@hidden display
+
address@hidden Family names, in all capitals
+In some circumstances, it is conventional to print family names in all
+capitals. Don't use @code{@@acronym} for this, since a name is not an
+acronym. Use @code{@@sc} instead (@pxref{Smallcaps}).
+
address@hidden@@abbr} and @code{@@acronym} are closely related commands: they
+both signal to the reader that a shortened form is being used, and
+possibly give a meaning. When choosing whether to use these two
+commands, please bear the following in mind.
+
address@hidden @minus
address@hidden
+In common English usage, acronyms are a subset of abbreviations: they
+include pronounceable words like address@hidden', `radar', and
+`snafu'; some sources also include syllable acronyms like
+`Usenet', hybrids like address@hidden', and unpronounceable
+initialisms like address@hidden'.
+
address@hidden
+In Texinfo, an acronym (but not an abbreviation) should consist only
+of capital letters and periods, no lowercase.
+
address@hidden
+In @TeX{}, an acronym (but not an abbreviation) is printed in a
+slightly smaller font.
+
address@hidden
+Some browsers place a dotted bottom border under abbreviations but not
+acronyms.
+
address@hidden
+It usually turns out to be quite difficult and/or time-consuming to
+consistently use @code{@@acronym} for all sequences of uppercase
+letters. Furthermore, it looks strange for some acronyms to be in the
+normal font size and others to be smaller. Thus, a simpler approach
+you may wish to consider is to avoid @code{@@acronym} and just typeset
+everything as normal text in all capitals: @samp{GNU}, producing the
+output `GNU'.
+
address@hidden
+In general, it's not essential to use either of these commands for all
+abbreviations; use your judgment. Text is perfectly readable without
+them.
address@hidden itemize
+
+
address@hidden @t{@@indicateurl}
address@hidden @code{@@address@hidden@address@hidden
+
address@hidden@c old name
address@hidden indicateurl
address@hidden Uniform resource locator, indicating
address@hidden URL, indicating
+
+Use the @code{@@indicateurl} command to indicate a uniform resource
+locator on the World Wide Web. This is purely for markup purposes and
+does not produce a link you can follow (use the @code{@@url} or
address@hidden@@uref} command for that, @address@hidden@@url}}).
address@hidden@@indicateurl} is useful for urls which do not actually exist.
+For example:
+
address@hidden
+For example, the url might be @@address@hidden://example.org/address@hidden
address@hidden example
+
address@hidden which produces:
+
address@hidden
+For example, the url might be @indicateurl{http://example.org/path}.
address@hidden display
+
+The output from @code{@@indicateurl} is more or less like that of
address@hidden@@samp} (@address@hidden@@samp}}).
+
+
address@hidden @t{@@email}
address@hidden @code{@@address@hidden@var{email-address}[, @address@hidden
+
address@hidden@c old name
address@hidden email
+
+Use the @code{@@email} command to indicate an electronic mail address.
+It takes one mandatory argument, the address, and one optional argument, the
+text to display (the default is the address itself).
+
address@hidden Mailto link
+In Info, the address is shown in angle brackets, preceded by the text
+to display if any. In @TeX{}, the angle brackets are omitted. In
+HTML output, @code{@@email} produces a @samp{mailto} link that usually
+brings up a mail composition window. For example:
+
address@hidden
+Send bug reports to @@address@hidden@@@@address@hidden,
+suggestions to the @@address@hidden@@@@gnu.org, same address@hidden
address@hidden example
+
address@hidden produces
+
address@hidden
+Send bug reports to @email{bug-texinfo@@gnu.org},
+suggestions to the @email{bug-texinfo@@gnu.org, same place}.
address@hidden display
+
+
address@hidden Emphasis
address@hidden Emphasizing Text
address@hidden Emphasizing text
+
+Usually, Texinfo changes the font to mark words in the text according
+to the category the words belong to; an example is the @code{@@code}
+command. Most often, this is the best way to mark words. However,
+sometimes you will want to emphasize text without indicating a
+category. Texinfo has two commands to do this. Also, Texinfo has
+several commands that specify the font in which text will be output.
+These commands have no effect in Info and only one of them, the
address@hidden@@r} command, has any regular use.
+
address@hidden
+* @t{@@emph @@strong}:: How to emphasize text in Texinfo.
+* Smallcaps:: How to use the small caps font.
+* Fonts:: Various font commands for printed output.
address@hidden menu
+
+
address@hidden @t{@@emph @@strong}
address@hidden @code{@@address@hidden@address@hidden and
@code{@@address@hidden@address@hidden
+
address@hidden & address@hidden oldname
address@hidden emph
address@hidden strong
address@hidden Emphasizing text, font for
+
+The @code{@@emph} and @code{@@strong} commands are for emphasis;
address@hidden@@strong} is stronger. In printed output, @code{@@emph} produces
address@hidden and @code{@@strong} produces @strong{bold}.
+In the Info output, @code{@@emph} surrounds the text with underscores
+(@samp{_}), and @code{@@strong} puts asterisks around the text.
+
+For example,
+
address@hidden
address@hidden
+@@address@hidden:@} @@address@hidden address@hidden
+removes @@address@hidden@} normal files.
address@hidden group
address@hidden example
+
address@hidden
+produces the following:
+
address@hidden
address@hidden: @samp{rm * .[^.]*}
+removes @emph{all} normal files.
address@hidden quotation
+
+The @code{@@strong} command is seldom used except to mark what is, in
+effect, a typographical element, such as the word `Caution' in the
+preceding example.
+
address@hidden Caution
+Do not use @code{@@strong} with the word @samp{Note} followed by a
+space; Info will mistake the combination for a cross reference. Use a
+phrase such as @strong{Please notice} or @strong{Caution} instead, or
+the optional argument to @code{@@address@hidden is allowable
+there.
address@hidden quotation
+
+
address@hidden Smallcaps
address@hidden @code{@@address@hidden@address@hidden: The Small Caps Font
address@hidden Small caps font
address@hidden sc @r{(small caps font)}
+
+Use the @samp{@@sc} command to set text in @sc{a small caps font}
+(where possible). Write the text you want to be in small caps between
+braces in lowercase, like this:
+
address@hidden
+Richard @@address@hidden@} commenc@'{e} GNU.
address@hidden example
+
address@hidden
+This produces:
+
address@hidden
+Richard @sc{Stallman} commenc@'{e} GNU.
address@hidden display
+
+As shown here, we recommend reserving @code{@@sc} for special cases
+where you want typographic small caps; family names are one such,
+especially in languages other than English, though there are no
+hard-and-fast rules about such things.
+
address@hidden @code{<small>} tag
address@hidden typesets any uppercase letters between the braces of an
address@hidden@@sc} command in full-size capitals; only lowercase letters are
+printed in the small caps font. In the Info output, the argument to
address@hidden@@sc} is printed in all uppercase. In HTML, the argument is
+uppercased and the output marked with the @code{<small>} tag to reduce
+the font size, since HTML cannot easily represent true small caps.
+
+Overall, we recommend using standard upper- and lowercase letters
+wherever possible.
+
+
address@hidden Fonts
address@hidden Fonts for Printing
address@hidden Fonts for printing
+
address@hidden fonttextsize
address@hidden Font size, reducing
address@hidden Reducing font size
address@hidden Smaller fonts
+Texinfo provides one command to change the size of the main body font
+in the @TeX{} output for a document: @code{@@fonttextsize}. It has no
+effect in other output. It takes a single argument on the remainder
+of the line, which must be either @samp{10} or @samp{11}. For
+example:
+
address@hidden
+@@fonttextsize 10
address@hidden example
+
address@hidden Printing cost, reducing
+The effect is to reduce the body font to a address@hidden size (the
+default is address@hidden). Fonts for other elements, such as sections
+and chapters, are reduced accordingly. This should only be used in
+conjunction with @code{@@smallbook} (@address@hidden@@smallbook}}) or
+similar, since address@hidden fonts on standard paper (8.5x11 or A4) are
+too small. One reason to use this command is to save pages, and hence
+printing cost, for physical books.
+
+Texinfo does not at present have commands to switch the font family
+to use, or more general size-changing commands.
+
+Texinfo also provides a number of font commands that specify font
+changes in the printed manual and (where possible) in the HTML output.
+They have no effect in Info. All the commands apply to a following
+argument surrounded by braces.
+
address@hidden @code
address@hidden @@b
address@hidden b @r{(bold font)}
address@hidden Bold font
+selects @b{bold} face;
+
address@hidden @@i
address@hidden i @r{(italic font)}
address@hidden Italic font
+selects an @i{italic} font;
+
address@hidden @@r
address@hidden r @r{(roman font)}
address@hidden Roman font
address@hidden Default font
+selects a @r{roman} font, which is the usual font in which text is
+printed. It may or may not be seriffed.
+
address@hidden @@sansserif
address@hidden sansserif @r{(sans serif font)}
address@hidden Sans serif font
+selects a @sansserif{sans serif} font;
+
address@hidden @@slanted
address@hidden slanted @r{(slanted font)}
address@hidden Slanted font
address@hidden Oblique font
+selects a @slanted{slanted} font;
+
address@hidden @@t
address@hidden t @r{(typewriter font)}
address@hidden Monospace font
address@hidden Fixed-width font
address@hidden Typewriter font
+selects the @t{fixed-width}, typewriter-style font used by @code{@@code};
+
address@hidden table
+
+(The commands with longer names were invented much later than the
+others, at which time it did not seem desirable to use very short
+names for such infrequently needed features.)
+
address@hidden <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
address@hidden<lineannotation>} tag in Docbook output.
+
+For example,
+
address@hidden
address@hidden
+@@lisp
+(+ 2 2) ; @@address@hidden two plus address@hidden
+@@end lisp
address@hidden group
address@hidden example
+
address@hidden
+produces
+
address@hidden
+(+ 2 2) ; @r{Add two plus two.}
address@hidden lisp
+
+The @code{@@t} command can occasionally be useful to produce output in
+a typewriter font where that is supported (e.g., HTML and PDF), but no
+distinction is needed in Info or plain text: @code{@@address@hidden@}}
+produces @t{foo}, cf. @code{@@address@hidden@}} producing @code{foo}.
+
+For example, we use @code{@@t} in the @code{@@node} commands for this
+manual to specify the Texinfo command names, because the quotes which
address@hidden@@code} outputs look extraneous in that particular context.
+
+In general, the other font commands are unlikely to be useful; they
+exist primarily to make it possible to document the functionality of
+specific font effects, such as in @TeX{} and related packages.
+
+
address@hidden Quotations and Examples
address@hidden Quotations and Examples
+
+Quotations and examples are blocks of text consisting of one or more
+whole paragraphs that are set off from the bulk of the text and
+treated differently. They are usually indented in the output.
+
address@hidden end
+In Texinfo, you always begin a quotation or example by writing an
+@@-command at the beginning of a line by itself, and end it by writing
+an @code{@@end} command that is also at the beginning of a line by
+itself. For instance, you begin an example by writing
address@hidden@@example} by itself at the beginning of a line and end the
+example by writing @code{@@end example} on a line by itself, at the
+beginning of that line, and with only one space between the
address@hidden@@end} and the @code{example}.
+
address@hidden
+* Block Enclosing Commands:: Different constructs for different purposes.
+* @t{@@quotation}:: Writing a quotation.
+* @t{@@indentedblock}:: Block of text indented on left.
+* @t{@@example}:: Writing an example in a fixed-width font.
+* @t{@@verbatim}:: Writing a verbatim example.
+* @t{@@verbatiminclude}:: Including a file verbatim.
+* @t{@@lisp}:: Illustrating Lisp code.
+* @t{@@address@hidden:: Examples in a smaller font.
+* @t{@@display}:: Writing an example in the current font.
+* @t{@@format}:: Writing an example without narrowed
margins.
+* @t{@@exdent}:: Undo indentation on a line.
+* @t{@@flushleft @@flushright}:: Pushing text flush left or flush right.
+* @t{@@raggedright}:: Avoiding justification on the right.
+* @t{@@noindent}:: Preventing paragraph indentation.
+* @t{@@indent}:: Forcing paragraph indentation.
+* @t{@@cartouche}:: Drawing rounded rectangles around text.
address@hidden menu
+
+
address@hidden Block Enclosing Commands
address@hidden Block Enclosing Commands
+
+Here is a summary of commands that enclose blocks of text, also known
+as @dfn{environments}. They're explained further in the following
+sections.
+
address@hidden @code
address@hidden @@quotation
+Indicate text that is quoted. The text is filled, indented (from both
+margins), and printed in a roman font by default.
+
address@hidden @@indentedblock
+Like @code{@@quotation}, but the text is indented only on the left.
+
address@hidden @@example
+Illustrate code, commands, and the like. The text is printed
+in a fixed-width font, and indented but not filled.
+
address@hidden @@lisp
+Like @code{@@example}, but specifically for illustrating Lisp code. The
+text is printed in a fixed-width font, and indented but not filled.
+
address@hidden @@verbatim
+Mark a piece of text that is to be printed verbatim; no character
+substitutions are made and all commands are ignored, until the next
address@hidden@@end verbatim}. The text is printed in a fixed-width font,
+and not indented or filled. Extra spaces and blank lines are
+significant, and tabs are expanded.
+
address@hidden @@display
+Display illustrative text. The text is indented but not filled, and
+no font is selected (so, by default, the font is roman).
+
address@hidden @@format
+Like @code{@@display} (the text is not filled and no font is
+selected), but the text is not indented.
+
address@hidden @@smallquotation
address@hidden @@smallindentedblock
address@hidden @@smallexample
address@hidden @@smalllisp
address@hidden @@smalldisplay
address@hidden @@smallformat
+These @code{@@small...} commands are just like their non-small
+counterparts, except that they output text in a smaller font size,
+where possible.
+
address@hidden @@flushleft
address@hidden @@flushright
+Text is not filled, but is set flush with the left or right margin,
+respectively.
+
address@hidden @@raggedright
+Text is filled, but only justified on the left, leaving the right
+margin ragged.
+
address@hidden @@cartouche
+Highlight text, often an example or quotation, by drawing a box with
+rounded corners around it.
address@hidden table
+
+The @code{@@exdent} command is used within the above constructs to
+undo the indentation of a line.
+
+The @code{@@noindent} command may be used after one of the above
+constructs (or anywhere) to prevent the following text from being
+indented as a new paragraph.
+
+
address@hidden @t{@@quotation}
address@hidden @code{@@quotation}: Block Quotations
address@hidden@c old name
+
address@hidden Quotations
address@hidden quotation
+
+The text of a quotation is processed like normal text (regular font,
+text is filled) except that:
+
address@hidden @bullet
address@hidden
+both the left and right margins are closer to the center of the page,
+so the whole of the quotation is indented;
+
address@hidden
+the first lines of paragraphs are indented no more than other lines; and
+
address@hidden
+an @code{@@author} command may be given to specify the author of the
+quotation.
address@hidden itemize
+
address@hidden
+This is an example of text written between an @code{@@quotation}
+command and an @code{@@end quotation} command. An @code{@@quotation}
+command is most often used to indicate text that is excerpted from
+another (real or hypothetical) printed work.
address@hidden quotation
+
+Write an @code{@@quotation} command as text on a line by itself. This
+line will disappear from the output. Mark the end of the quotation
+with a line beginning with and containing only @code{@@end quotation}.
+The @code{@@end quotation} line will likewise disappear from the
+output.
+
address@hidden@@quotation} takes one optional argument, given on the remainder
+of the line. This text, if present, is included at the beginning of
+the quotation in bold or otherwise emphasized, and followed with a
address@hidden:}. For example:
+
address@hidden
+@@quotation Note
+This is
+a foo.
+@@end quotation
address@hidden example
+
address@hidden
+produces
+
address@hidden Note
+This is
+a foo.
address@hidden quotation
+
+If the @code{@@quotation} argument is exactly one of these English words:
+
address@hidden
+Caution Important Note Tip Warning
address@hidden example
+
address@hidden @code{<note>} Docbook tag
address@hidden @code{<blockquote>} HTML tag
address@hidden then the Docbook output uses corresponding special tags
+(@code{<note>}, etc.) instead of the default @code{<blockquote>}.
+HTML output always uses @code{<blockquote>}.
+
+If the author of the quotation is specified in the @code{@@quotation}
+block with the @code{@@author} command, a line with the author name is
+displayed after the quotation:
+
address@hidden
+@@quotation
+People sometimes ask me if it is a sin in the Church of Emacs to use
+vi. Using a free version of vi is not a sin; it is a penance. So happy
+hacking.
+
+@@author Richard Stallman
+@@end quotation
address@hidden example
+
address@hidden
+produces
+
address@hidden
+People sometimes ask me if it is a sin in the Church of Emacs to use
+vi. Using a free version of vi is not a sin; it is a penance. So happy
+hacking.
+
address@hidden Richard Stallman
address@hidden quotation
+
address@hidden smallquotation
+Texinfo also provides a command @code{@@smallquotation}, which is just
+like @code{@@quotation} but uses a smaller font size where possible.
address@hidden@t{@@address@hidden
+
+
address@hidden @t{@@indentedblock}
address@hidden @code{@@indentedblock}: Indented text blocks
address@hidden Indented text block
address@hidden indentedblock
+
+The @code{@@indentedblock} environment is similar to
address@hidden@@quotation}, except that text is only indented on the left (and
+there is no optional argument for an author). Thus, the text font
+remains unchanged, and text is gathered and filled as usual, but the
+left margin is increased. For example:
+
address@hidden
+This is an example of text written between an @code{@@indentedblock}
+command and an @code{@@end indentedblock} command. The
address@hidden@@indentedblock} environment can contain any text or other
+commands desired.
address@hidden indentedblock
+
+This is written in the Texinfo source as:
+
address@hidden
+@@indentedblock
+This is an example ...
+@@end indentedblock
address@hidden example
+
address@hidden smallindentedblock
+Texinfo also provides a command @code{@@smallindentedblock}, which is
+just like @code{@@indentedblock} but uses a smaller font size where
+possible. @address@hidden@@address@hidden
+
+
address@hidden @t{@@example}
address@hidden @code{@@example}: Example Text
+
address@hidden@c old name
address@hidden example
address@hidden Examples, formatting them
address@hidden 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:
+
address@hidden
address@hidden Each line in the input file is a line in the output; that is,
+the source text is not filled as it normally is.
address@hidden Extra spaces and blank lines are significant.
address@hidden The output is indented.
address@hidden The output uses a fixed-width font.
address@hidden Texinfo commands @emph{are} expanded; if you want the output to
+be the input verbatim, use the @code{@@verbatim} environment instead
+(@address@hidden@@verbatim}}).
address@hidden itemize
+
+For example,
+
address@hidden
+@@example
+cp foo @@address@hidden@}; \
+ cp foo @@address@hidden@}
+@@end example
address@hidden example
+
address@hidden
+produces
+
address@hidden
+cp foo @var{dest1}; \
+ cp foo @var{dest2}
address@hidden 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
address@hidden@@example} and the ending @code{@@end example}, on the other
+hand, do appear in the output.
+
address@hidden 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.
address@hidden quotation
+
+Examples are often, logically speaking, ``in the middle'' of a
+paragraph, and the text that continues afterwards should not be
+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 (@address@hidden@@noindent}}.
+
+If you want to embed code fragments within sentences, instead of
+displaying them, use the @code{@@code} command or its relatives
+(@address@hidden@@code}}).
+
+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}).
+
+
address@hidden @t{@@verbatim}
address@hidden @code{@@verbatim}: Literal Text
+
address@hidden@c old name
address@hidden verbatim
address@hidden Verbatim environment
+
+Use the @code{@@verbatim} environment for printing of text that may
+contain special characters or commands that should not be interpreted,
+such as computer input or output (@code{@@example} interprets its text
+as regular Texinfo commands). This is especially useful for including
automatically
+generated files in a Texinfo manual.
+
+In general, the output will be just the same as the input. No
+character substitutions are made, e.g., all spaces and blank lines are
+significant, including tabs. In the printed manual, the text is
+typeset in a fixed-width font, and not indented or filled.
+
+Write an @code{@@verbatim} command at the beginning of a line by
+itself. This line will disappear from the output. Mark the end of
+the verbatim block with an @code{@@end verbatim} command, also written
+at the beginning of a line by itself. The @code{@@end verbatim} will
+also disappear from the output.
+
+For example:
address@hidden oops, got to trick this a bit: can't use @end verbatim inside
@verbatim
+
address@hidden
address@hidden @t{@@verbatim}
address@hidden @address@hidden
address@hidden @address@hidden@@command with strange characters: @@'e}
address@hidden @address@hidden
address@hidden @address@hidden
address@hidden @t{@@end verbatim}
address@hidden example
+
address@hidden
+This produces:
+
address@hidden
+{
+ @command with strange characters: @'e
+expand me
+}
address@hidden verbatim
+
+Since the lines containing @code{@@verbatim} and @code{@@end verbatim}
+produce no output, typically you should put a blank line before the
address@hidden@@verbatim} and another blank line after the @code{@@end
+verbatim}. Blank lines between the beginning @code{@@verbatim} and
+the ending @code{@@end verbatim} will appear in the output.
+
address@hidden Verbatim, small
address@hidden Small verbatim
+You can get a ``small'' verbatim by enclosing the @code{@@verbatim} in
+an @code{@@smallformat} environment, as shown here:
+
address@hidden more cheating ...
address@hidden
address@hidden @t{@@smallformat}
address@hidden @t{@@verbatim}
address@hidden @t{... still verbatim, but in a smaller font ...}
address@hidden @t{@@end verbatim}
address@hidden @t{@@end smallformat}
address@hidden smallexample
+
+Finally, a word of warning: it is not reliable to use
address@hidden@@verbatim} inside other Texinfo constructs.
+
+
address@hidden @t{@@verbatiminclude}
address@hidden @code{@@verbatiminclude} @var{file}: Include a File Verbatim
+
address@hidden@c old name
address@hidden verbatiminclude
address@hidden Verbatim, include file
address@hidden Including a file verbatim
+
+You can include the exact contents of a file in the document with the
address@hidden@@verbatiminclude} command:
+
address@hidden
+@@verbatiminclude @var{filename}
address@hidden example
+
+The contents of @var{filename} is printed in a verbatim environment
+(@address@hidden@@verbatim}}). Generally, the file is printed exactly
+as it is, with all special characters and white space retained. No
+indentation is added; if you want indentation, enclose the
address@hidden@@verbatiminclude} within @code{@@example}
+(@address@hidden@@example}}).
+
+The name of the file is taken literally, with a single exception:
address@hidden@@address@hidden@address@hidden references are expanded. This
makes it
+possible to include files in other directories within a distribution,
+for instance:
+
address@hidden
+@@verbatiminclude @@address@hidden@}/NEWS
address@hidden example
+
address@hidden (You still have to get @code{top_srcdir} defined in the
+first place.)
+
+For a method on printing the file contents in a smaller font size, see
+the end of the previous section on @code{@@verbatim}.
+
+
address@hidden @t{@@lisp}
address@hidden @code{@@lisp}: Marking a Lisp Example
+
address@hidden@c old name
address@hidden lisp
address@hidden Lisp example
+
+The @code{@@lisp} command is used for Lisp code. It is synonymous
+with the @code{@@example} command.
+
address@hidden
+This is an example of text written between an
address@hidden@@lisp} command and an @code{@@end lisp} command.
address@hidden lisp
+
+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
address@hidden would be straightforward to extend Texinfo to work
+in a similar fashion for C, Fortran, or other languages.}
+
+Mark the end of @code{@@lisp} with @code{@@end lisp} on a line by
+itself.
+
+
address@hidden @t{@@address@hidden
address@hidden @code{@@address@hidden Block Commands
+
address@hidden@c old name
address@hidden smallexample
address@hidden smallformat
address@hidden smalllisp
address@hidden smallquotation
address@hidden Small examples
address@hidden Examples in smaller fonts
address@hidden Quotations in smaller fonts
address@hidden Lisp examples in smaller fonts
+
+In addition to the regular @code{@@example} and similar commands,
+Texinfo has ``small'' example-style commands. These are
address@hidden@@smallquotation}, @code{@@smallindentedblock},
address@hidden@@smalldisplay}, @code{@@smallexample}, @code{@@smallformat},
+and @code{@@smalllisp}.
+
+In Info output, the @code{@@address@hidden commands are equivalent to
+their non-small companion commands.
+
+In @TeX{}, however, the @code{@@address@hidden commands typeset text in
+a smaller font than the non-small example commands. Thus, for
+instance, code examples can contain longer lines and still fit on a
+page without needing to be rewritten.
+
+A smaller font size is also requested in HTML output, and (as usual)
+retained in the address@hidden transliteration.
+
+Mark the end of an @code{@@address@hidden block with a corresponding
address@hidden@@end address@hidden For example, pair @code{@@smallexample} with
address@hidden@@end smallexample}.
+
+Here is an example of the font used by the @code{@@smallexample}
+command (in Info, the output will be the same as usual):
+
address@hidden
address@hidden to make sure that you have the freedom to
+distribute copies of free software (and charge for
+this service if you wish), that you receive source
+code or can get it if you want it, that you can
+change the software or use pieces of it in new free
+programs; and that you know you can do these things.
address@hidden smallexample
+
+The @code{@@address@hidden commands use the same font style as their
+normal counterparts: @code{@@smallexample} and @code{@@smalllisp} use
+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.
+
+
address@hidden @t{@@display}
address@hidden @code{@@display}: Examples Using the Text Font
+
address@hidden@c old name
address@hidden display
address@hidden Display formatting
+
+The @code{@@display} command begins another kind of environment, where
+the font is left unchanged, not switched to typewriter as with
address@hidden@@example}. Each line of input still produces a line of output,
+and the output is still indented.
+
address@hidden
+This is an example of text written between an @code{@@display} command
+and an @code{@@end display} command. The @code{@@display} command
+indents the text, but does not fill it.
address@hidden display
+
address@hidden smalldisplay
+Texinfo also provides the environment @code{@@smalldisplay}, which is
+like @code{@@display} but uses a smaller font size.
address@hidden@t{@@address@hidden
+
+The @code{@@table} command (@address@hidden@@table}}) is not supported
+inside @code{@@display}. Since @code{@@display} is line-oriented, it
+doesn't make sense to use them together. If you want to indent a
+table, try @code{@@quotation} (@address@hidden@@quotation}}) or
address@hidden@@indentedblock} (@address@hidden@@indentedblock}}).
+
+
address@hidden @t{@@format}
address@hidden @code{@@format}: Examples Using the Full Line Width
+
address@hidden@c old name
address@hidden format
+
+The @code{@@format} command is similar to @code{@@display}, except it
+leaves the text unindented. Like @code{@@display}, it does not select
+the fixed-width font.
+
address@hidden
+This is an example of text written between an @code{@@format} command
+and an @code{@@end format} command. As you can see
+from this example,
+the @code{@@format} command does not fill the text.
address@hidden format
+
address@hidden smallformat
+Texinfo also provides the environment @code{@@smallformat}, which is
+like @code{@@format} but uses a smaller font size.
address@hidden@t{@@address@hidden
+
+
address@hidden @t{@@exdent}
address@hidden @code{@@exdent}: Undoing a Line's Indentation
+
address@hidden@c old name
address@hidden exdent
address@hidden Indentation undoing
+
+The @code{@@exdent} command removes any indentation a line might have.
+The command is written at the beginning of a line and applies only to
+the text that follows the command that is on the same line. Do not use
+braces around the text. In a printed manual, the text on an
address@hidden@@exdent} line is printed in the roman font.
+
address@hidden@@exdent} is usually used within examples. Thus,
+
address@hidden
address@hidden
+@@example
+This line follows an @@@@example command.
+@@exdent This line is exdented.
+This line follows the exdented line.
+The @@@@end example comes on the next line.
+@@end example
address@hidden group
address@hidden example
+
address@hidden
+produces
+
address@hidden
address@hidden
+This line follows an @@example command.
address@hidden This line is exdented.
+This line follows the exdented line.
+The @@end example comes on the next line.
address@hidden group
address@hidden example
+
+In practice, the @code{@@exdent} command is rarely used. Usually, you
+un-indent text by ending the example and returning the page to its
+normal width.
+
address@hidden@@exdent} has no effect in HTML output.
+
+
address@hidden @t{@@flushleft @@flushright}
address@hidden @code{@@flushleft} and @code{@@flushright}
+
address@hidden & address@hidden old name
address@hidden flushleft
address@hidden flushright
address@hidden Ragged right, without filling
address@hidden Ragged left, without filling
+
+The @code{@@flushleft} and @code{@@flushright} commands line up the
+ends of lines on the left and right margins of a page,
+but do not fill the text. The commands are written on lines of their
+own, without braces. The @code{@@flushleft} and @code{@@flushright}
+commands are ended by @code{@@end flushleft} and @code{@@end
+flushright} commands on lines of their own.
+
address@hidden 1500
+For example,
+
address@hidden
address@hidden
+@@flushleft
+This text is
+written flushleft.
+@@end flushleft
address@hidden group
address@hidden example
+
address@hidden
+produces
+
address@hidden
address@hidden
+This text is
+written flushleft.
address@hidden flushleft
address@hidden quotation
+
+
address@hidden@@flushright} produces the type of indentation often used in the
+return address of letters. For example,
+
address@hidden
address@hidden
+@@flushright
+Here is an example of text written
+flushright. The @@address@hidden@@address@hidden command
+right justifies every line but leaves the
+left end ragged.
+@@end flushright
address@hidden group
address@hidden example
+
address@hidden
+produces
+
address@hidden
+Here is an example of text written
+flushright. The @code{@@flushright} command
+right justifies every line but leaves the
+left end ragged.
address@hidden flushright
+
+
address@hidden @t{@@raggedright}
address@hidden @code{@@raggedright}: Ragged Right Text
+
address@hidden@c old name
address@hidden raggedright
address@hidden Ragged right, with filling
+
+The @code{@@raggedright} fills text as usual, but the text is only
+justified on the left; the right margin is ragged. The command is
+written on a line of its own, without braces. The
address@hidden@@raggedright} command is ended by @code{@@end raggedright} on a
+line of its own. This command has no effect in Info and HTML output,
+where text is always set ragged right.
+
+The @code{@@raggedright} command can be useful with paragraphs
+containing lists of commands with long names, when it is known in
+advance that justifying the text on both margins will make the
+paragraph look bad.
+
+For example,
+
address@hidden
address@hidden
+@@raggedright
+Commands for double and single angle quotation marks:
+@@address@hidden@@@@guillemetleft@@@{@@@address@hidden,
@@address@hidden@@@@guillemetright@@@{@@@address@hidden,
+@@address@hidden@@@@guillemotleft@@@{@@@address@hidden,
@@address@hidden@@@@guillemotright@@@{@@@address@hidden,
+@@address@hidden@@@@guilsinglleft@@@{@@@address@hidden,
@@address@hidden@@@@guilsinglright@@@{@@@address@hidden
+@@end raggedright
address@hidden group
address@hidden example
+
address@hidden
+produces
+
address@hidden
+Commands for double and single angle quotation marks:
address@hidden@@address@hidden@}}, @code{@@address@hidden@}},
address@hidden@@address@hidden@}}, @code{@@address@hidden@}},
address@hidden@@address@hidden@}}, @code{@@address@hidden@}}.
address@hidden raggedright
+
+
address@hidden @t{@@noindent}
address@hidden @code{@@noindent}: Omitting Indentation
+
address@hidden@c old name
address@hidden noindent
address@hidden Omitting indentation
address@hidden Suppressing indentation
address@hidden Indentation, omitting
+
+An example or other inclusion can break a paragraph into segments.
+Ordinarily, the formatters indent text that follows an example as a new
+paragraph. You can prevent this on a case-by-case basis by writing
address@hidden@@noindent} at the beginning of a line, preceding the continuation
+text. You can also disable indentation for all paragraphs globally with
address@hidden@@paragraphindent} (@address@hidden@@paragraphindent}}).
+
+It is best to write @code{@@noindent} on a line by itself, since in most
+environments, spaces following the command will not be ignored. It's ok
+to use it at the beginning of a line, with text following, outside of
+any environment.
+
address@hidden 1500
+For example:
+
address@hidden
address@hidden
+@@example
+This is an example
+@@end example
+
+@@noindent
+This line is not indented. As you can see, the
+beginning of the line is fully flush left with the line
+that follows after it. (This whole example is between
+@@address@hidden@@@@address@hidden and @@address@hidden@@@@end address@hidden)
address@hidden group
address@hidden example
+
address@hidden produces:
+
address@hidden
+
address@hidden
+This is an example
address@hidden example
+
address@hidden
+This line is not indented. As you can see, the
+beginning of the line is fully flush left with the line
+that follows after it. (This whole example is between
address@hidden@@display} and @code{@@end display}.)
+
address@hidden display
+
+To adjust the number of blank lines properly in the Info file output,
+remember that the line containing @code{@@noindent} does not generate a
+blank line, and neither does the @code{@@end example} line.
+
+In the Texinfo source file for this manual, each line that says
+`produces' is preceded by @code{@@noindent}.
+
+Do not put braces after an @code{@@noindent} command; they are not
+necessary, since @code{@@noindent} is a command used outside of
+paragraphs (@pxref{Command Syntax}).
+
+
address@hidden @t{@@indent}
address@hidden @code{@@indent}: Forcing Indentation
+
address@hidden@c old name
address@hidden indent
address@hidden Forcing indentation
address@hidden Inserting indentation
address@hidden Indentation, forcing
+
address@hidden
+To complement the @code{@@noindent} command (see the previous
+section), Texinfo provides the @code{@@indent} command that forces a
+paragraph to be indented. This paragraph, for instance, is indented
+using an @code{@@indent} command. The first paragraph of a section is
+the most likely place to use @code{@@indent}, to override the normal
+behavior of no indentation there (@address@hidden@@paragraphindent}}).
+
+It is best to write @code{@@indent} on a line by itself, since in most
+environments, spaces following the command will not be ignored. The
address@hidden@@indent} line will not generate a blank line in the Info output
+within an environment.
+
+However, it is ok to use it at the beginning of a line, with text
+following, outside of any environment.
+
+Do not put braces after an @code{@@indent} command; they are not
+necessary, since @code{@@indent} is a command used outside of
+paragraphs (@pxref{Command Syntax}).
+
+
address@hidden @t{@@cartouche}
address@hidden @code{@@cartouche}: Rounded Rectangles
+
address@hidden@c old name
address@hidden cartouche
address@hidden Box with rounded corners
address@hidden Rounded rectangles, around text
+
+In a printed manual, the @code{@@cartouche} command draws a box with
+rounded corners around its contents. In HTML, a normal rectangle is
+drawn. @code{@@cartouche} has no effect in Info output.
+
+You can use this command to further highlight an example or quotation.
+For instance, you could write a manual in which one type of example is
+surrounded by a cartouche for emphasis.
+
+For example,
+
address@hidden
+@@cartouche
+@@example
+% pwd
+/usr/local/share/emacs
+@@end example
+@@end cartouche
address@hidden example
+
address@hidden
+surrounds the two-line example with a box with rounded corners, in the
+printed manual.
+
+The output from the example looks like this (if you're reading this in
+Info, you'll see the @code{@@cartouche} had no effect):
+
address@hidden
address@hidden
+% pwd
+/usr/local/info
address@hidden example
address@hidden cartouche
+
address@hidden@@cartouche} also implies @code{@@group}
(@address@hidden@@group}}).
+
+
address@hidden Lists and Tables
address@hidden Lists and Tables
address@hidden Making lists and tables
address@hidden Lists and tables, making
address@hidden Tables and lists, making
+
+Texinfo has several ways of making lists and tables. Lists can be
+bulleted or numbered; two-column tables can highlight the items in
+the first column; multi-column tables are also supported.
+
address@hidden
+* Introducing Lists:: Texinfo formats lists for you.
+* @t{@@itemize}:: How to construct a simple list.
+* @t{@@enumerate}:: How to construct a numbered list.
+* Two-column Tables:: How to construct a two-column table.
+* Multi-column Tables:: How to construct generalized tables.
address@hidden menu
+
address@hidden Introducing Lists
address@hidden Introducing Lists
+
+Texinfo automatically indents the text in lists or tables, and numbers
+an enumerated list. This last feature is useful if you modify the
+list, since you do not need to renumber it yourself.
+
+Numbered lists and tables begin with the appropriate @@-command at the
+beginning of a line, and end with the corresponding @code{@@end}
+command on a line by itself. The table and itemized-list commands
+also require that you write formatting information on the same line as
+the beginning @@-command.
+
+Begin an enumerated list, for example, with an @code{@@enumerate}
+command and end the list with an @code{@@end enumerate} command.
+Begin an itemized list with an @code{@@itemize} command, followed on
+the same line by a formatting command such as @code{@@bullet}, and end
+the list with an @code{@@end itemize} command.
address@hidden end
+
+Precede each element of a list with an @code{@@item} or @code{@@itemx}
+command.
+
address@hidden 1
address@hidden
+Here is an itemized list of the different kinds of table and lists:
+
address@hidden @bullet
address@hidden
+Itemized lists with and without bullets.
+
address@hidden
+Enumerated lists, using numbers or letters.
+
address@hidden
+Two-column tables with highlighting.
address@hidden itemize
+
address@hidden 1
address@hidden
+Here is an enumerated list with the same items:
+
address@hidden
address@hidden
+Itemized lists with and without bullets.
+
address@hidden
+Enumerated lists, using numbers or letters.
+
address@hidden
+Two-column tables with highlighting.
address@hidden enumerate
+
address@hidden 1
address@hidden
+And here is a two-column table with the same items and their
address@hidden@@-commands}:
+
address@hidden @code
address@hidden @@itemize
+Itemized lists with and without bullets.
+
address@hidden @@enumerate
+Enumerated lists, using numbers or letters.
+
address@hidden @@table
address@hidden @@ftable
address@hidden @@vtable
+Two-column tables, optionally with indexing.
address@hidden table
+
+
address@hidden @t{@@itemize}
address@hidden @code{@@itemize}: Making an Itemized List
+
address@hidden@c old name
address@hidden itemize
address@hidden Itemization
+
+The @code{@@itemize} command produces a sequence of ``items'', each
+starting with a bullet or other mark inside the left margin, and
+generally indented.
+
address@hidden @code{@@w}, for blank items
+Begin an itemized list by writing @code{@@itemize} at the beginning of
+a line. Follow the command, on the same line, with a character or a
+Texinfo command that generates a mark. Usually, you will use
address@hidden@@bullet} after @code{@@itemize}, but you can use
address@hidden@@minus}, or any command or character that results in a single
+character in the Info file. (When you write the mark command such as
address@hidden@@bullet} after an @code{@@itemize} command, you may omit the
address@hidden@address@hidden) If you don't specify a mark command, the
default is
address@hidden@@bullet}. If you don't want any mark at all, but still want
+logical items, use @code{@@address@hidden@}} (in this case the braces are
+required).
+
address@hidden item
+After the @code{@@itemize}, write your items, each starting with
address@hidden@@item}. Text can follow on the same line as the @code{@@item}.
+The text of an item can continue for more than one paragraph.
+
+There should be at least one @code{@@item} inside the @code{@@itemize}
+environment. If none are present, @code{makeinfo} gives a warning.
+If you just want indented text and not a list of items, use
address@hidden@@indentedblock}; @address@hidden@@indentedblock}}.
+
+Index entries and comments that are given before an @code{@@item}
+including the first, are automatically moved (internally) to after the
address@hidden@@item}, so the output is as expected. Historically this has
+been a common practice.
+
+Usually, you should put a blank line between items. This puts a blank
+line in the Info file. (@TeX{} inserts the proper vertical space in
+any case.) Except when the entries are very brief, these blank lines
+make the list look better.
+
+Here is an example of the use of @code{@@itemize}, followed by the
+output it produces. @code{@@bullet} produces an @samp{*} in Info and
+a round dot in other output formats.
+
address@hidden
address@hidden
+@@itemize @@bullet
+@@item
+Some text for foo.
+
+@@item
+Some text
+for bar.
+@@end itemize
address@hidden group
address@hidden example
+
address@hidden
+This produces:
+
address@hidden
address@hidden @bullet
address@hidden
+Some text for foo.
+
address@hidden
+Some text
+for bar.
address@hidden itemize
address@hidden quotation
+
+Itemized lists may be embedded within other itemized lists. Here is a
+list marked with dashes embedded in a list marked with bullets:
+
address@hidden
address@hidden
+@@itemize @@bullet
+@@item
+First item.
+
+@@itemize @@minus
+@@item
+Inner item.
+
+@@item
+Second inner item.
+@@end itemize
+
+@@item
+Second outer item.
+@@end itemize
address@hidden group
address@hidden example
+
address@hidden
+This produces:
+
address@hidden
address@hidden @bullet
address@hidden
+First item.
+
address@hidden @minus
address@hidden
+Inner item.
+
address@hidden
+Second inner item.
address@hidden itemize
+
address@hidden
+Second outer item.
address@hidden itemize
address@hidden quotation
+
+
address@hidden @t{@@enumerate}
address@hidden @code{@@enumerate}: Making a Numbered or Lettered List
+
address@hidden@c old name
address@hidden enumerate
address@hidden Enumeration
+
address@hidden@@enumerate} is like @code{@@itemize}
(@address@hidden@@itemize}}),
+except that the labels on the items are successive integers or letters
+instead of bullets.
+
+Write the @code{@@enumerate} command at the beginning of a line. The
+command does not require an argument, but accepts either a number or a
+letter as an option. Without an argument, @code{@@enumerate} starts the
+list with the number @samp{1}. With a numeric argument, such as
address@hidden, the command starts the list with that number. With an upper-
+or lowercase letter, such as @samp{a} or @samp{A}, the command starts
+the list with that letter.
+
+Write the text of the enumerated list in the same way as an itemized
+list: write a line starting with @code{@@item} at the beginning of
+each item in the enumeration. It is ok to have text following the
address@hidden@@item}, and the text for an item can continue for several
+paragraphs.
+
+You should put a blank line between entries in the list.
+This generally makes it easier to read the Info file.
+
address@hidden 1500
+Here is an example of @code{@@enumerate} without an argument:
+
address@hidden
address@hidden
+@@enumerate
+@@item
+Underlying causes.
+
+@@item
+Proximate causes.
+@@end enumerate
address@hidden group
address@hidden example
+
address@hidden
+This produces:
+
address@hidden
address@hidden
+Underlying causes.
+
address@hidden
+Proximate causes.
address@hidden enumerate
address@hidden 1
+Here is an example with an argument of @kbd{3}:
address@hidden 1
address@hidden
address@hidden
+@@enumerate 3
+@@item
+Predisposing causes.
+
+@@item
+Precipitating causes.
+
+@@item
+Perpetuating causes.
+@@end enumerate
address@hidden group
address@hidden example
+
address@hidden
+This produces:
+
address@hidden 3
address@hidden
+Predisposing causes.
+
address@hidden
+Precipitating causes.
+
address@hidden
+Perpetuating causes.
address@hidden enumerate
address@hidden 1
+Here is a brief summary of the alternatives. The summary is constructed
+using @code{@@enumerate} with an argument of @kbd{a}.
address@hidden 1
address@hidden a
address@hidden
address@hidden@@enumerate}
+
+Without an argument, produce a numbered list, starting with the
address@hidden
+
address@hidden
address@hidden@@enumerate @var{positive-integer}}
+
+With a (positive) numeric argument, start a numbered list with that
+number. You can use this to continue a list that you interrupted with
+other text.
+
address@hidden
address@hidden@@enumerate @var{upper-case-letter}}
+
+With an uppercase letter as argument, start a list
+in which each item is marked
+by a letter, beginning with that uppercase letter.
+
address@hidden
address@hidden@@enumerate @var{lower-case-letter}}
+
+With a lowercase letter as argument, start a list
+in which each item is marked by
+a letter, beginning with that lowercase letter.
address@hidden enumerate
+
+You can also nest enumerated lists, as in an outline.
+
+
address@hidden Two-column Tables
address@hidden Making a Two-column Table
+
address@hidden Tables, making two-column
address@hidden table
+
address@hidden@@table} is similar to @code{@@itemize}
+(@address@hidden@@itemize}}), but allows you to specify a name or
+heading line for each item. The @code{@@table} command is used to
+produce two-column tables, and is especially useful for glossaries,
+explanatory exhibits, and command-line option summaries.
+
address@hidden
+* @t{@@table}:: How to construct a two-column table.
+* @t{@@ftable @@vtable}:: Automatic indexing for two-column tables.
+* @t{@@itemx}:: How to put more entries in the first
column.
address@hidden menu
+
address@hidden @t{@@table}
address@hidden Using the @code{@@table} Command
+
address@hidden@c old name
+
address@hidden Definition lists, typesetting
+Use the @code{@@table} command to produce two-column tables. It is
+typically used when you have a list of items and a brief text with
+each one, such as ``definition lists''.
+
+Write the @code{@@table} command at the beginning of a line, after a
+blank line, and follow it on the same line with an argument that is a
+Texinfo ``indicating'' command such as @code{@@code}, @code{@@samp},
address@hidden@@var}, @code{@@option}, or @code{@@kbd} (@pxref{Indicating}).
+
+This command will be applied to the text that goes into the first
+column of each item and thus determines how it will be highlighted.
+For example, @code{@@table @@code} will cause the text in the first
+column to be output as if it had been the argument to an @code{@@code}
+command.
+
address@hidden@t{@@address@hidden command name with @, for consistency
address@hidden asis
+You may also use the @code{@@asis} command as an argument to
address@hidden@@table}. @code{@@asis} is a command that does nothing; if you
+use this command after @code{@@table}, the first column entries are
+output without added highlighting (``as is'').
+
+The @code{@@table} command works with other commands besides those
+explicitly mentioned here. However, you can only use predefined
+Texinfo commands that normally take an argument in braces. You cannot
+reliably use a new command defined with @code{@@macro}, but an
address@hidden@@alias} (for a suitable predefined command) is acceptable.
address@hidden New Texinfo Commands}.
+
address@hidden item
+Begin each table entry with an @code{@@item} command at the beginning
+of a line. Write the first column text on the same line as the
address@hidden@@item} command. Write the second column text on the line
+following the @code{@@item} line and on subsequent lines. (You do not
+need to type anything for an empty second column entry.) You may
+write as many lines of supporting text as you wish, even several
+paragraphs. But only the text on the same line as the @code{@@item}
+will be placed in the first column (including any footnotes).
+
+Normally, you should put a blank line before an @code{@@item} line
+(except the first one). This puts a blank line in the Info file.
+Except when the entries are very brief, a blank line looks better.
+
+End the table with a line consisting of @code{@@end table}, followed
+by a blank line. @TeX{} will always start a new paragraph after the
+table, so the blank line is needed for the Info output to be analogous.
+
address@hidden 1500
+The following table, for example, highlights the text in the first
+column with an @code{@@samp} command:
+
address@hidden
address@hidden
+@@table @@samp
+@@item foo
+This is the text for
+@@address@hidden@}.
+
+@@item bar
+Text for @@address@hidden@}.
+@@end table
address@hidden group
address@hidden example
+
address@hidden
+This produces:
+
address@hidden @samp
address@hidden foo
+This is the text for
address@hidden
address@hidden bar
+Text for @samp{bar}.
address@hidden table
+
+If you want to list two or more named items with a single block of
+text, use the @code{@@itemx} command. (@address@hidden@@itemx}}.)
+
+
address@hidden @t{@@ftable @@vtable}
address@hidden @code{@@ftable} and @code{@@vtable}
+
address@hidden address@hidden old name
address@hidden ftable
address@hidden vtable
address@hidden Tables with indexing
address@hidden Indexing table entries automatically
+
+The @code{@@ftable} and @code{@@vtable} commands are the same as the
address@hidden@@table} command except that @code{@@ftable} automatically enters
+each of the items in the first column of the table into the index of
+functions and @code{@@vtable} automatically enters each of the items in
+the first column of the table into the index of variables. This
+simplifies the task of creating indices. Only the items on the same
+line as the @code{@@item} commands are indexed, and they are indexed in
+exactly the form that they appear on that line. @xref{Indices},
+for more information about indices.
+
+Begin a two-column table using @code{@@ftable} or @code{@@vtable} by
+writing the @@-command at the beginning of a line, followed on the same
+line by an argument that is a Texinfo command such as @code{@@code},
+exactly as you would for an @code{@@table} command; and end the table
+with an @code{@@end ftable} or @code{@@end vtable} command on a line by
+itself.
+
+See the example for @code{@@table} in the previous section.
+
+
address@hidden @t{@@itemx}
address@hidden @code{@@itemx}: Second and Subsequent Items
+
address@hidden@c old name
address@hidden Two named items for @code{@@table}
address@hidden itemx
+
+Use the @code{@@itemx} command inside a table when you have two or more
+first column entries for the same item, each of which should appear on a
+line of its own.
+
+Use @code{@@item} for the first entry, and @code{@@itemx} for all
+subsequent entries; @code{@@itemx} must always follow an @code{@@item}
+command, with no blank line intervening.
+
+The @code{@@itemx} command works exactly like @code{@@item} except
+that it does not generate extra vertical space above the first column
+text. If you have multiple consecutive @code{@@itemx} commands, do
+not insert any blank lines between them.
+
+For example,
+
address@hidden
address@hidden
+@@table @@code
+@@item upcase
+@@itemx downcase
+These two functions accept a character or a string as
+argument, and return the corresponding uppercase (lowercase)
+character or string.
+@@end table
address@hidden group
address@hidden example
+
address@hidden
+This produces:
+
address@hidden @code
address@hidden upcase
address@hidden downcase
+These two functions accept a character or a string as
+argument, and return the corresponding uppercase (lowercase)
+character or string.
address@hidden table
+
address@hidden
+(Note also that this example illustrates multi-line supporting text in
+a two-column table.)
+
+
address@hidden Multi-column Tables
address@hidden @code{@@multitable}: Multi-column Tables
+
address@hidden multitable
address@hidden Tables, making multi-column
+
address@hidden@@multitable} allows you to construct tables with any number of
+columns, with each column having any width you like.
+
+You define the column widths on the @code{@@multitable} line itself, and
+write each row of the actual table following an @code{@@item} command,
+with columns separated by an @code{@@tab} command. Finally, @code{@@end
+multitable} completes the table. Details in the sections below.
+
address@hidden
+* Multitable Column Widths:: Defining multitable column widths.
+* Multitable Rows:: Defining multitable rows, with examples.
address@hidden menu
+
address@hidden Multitable Column Widths
address@hidden Multitable Column Widths
address@hidden Multitable column widths
address@hidden Column widths, defining for multitables
address@hidden Widths, defining multitable column
+
+You can define the column widths for a multitable in two ways: as
+fractions of the line length; or with a prototype row. Mixing the two
+methods is not supported. In either case, the widths are defined
+entirely on the same line as the @code{@@multitable} command.
+
address@hidden
address@hidden
address@hidden columnfractions
address@hidden Line length, column widths as fraction of
+To specify column widths as fractions of the line length, write
address@hidden@@columnfractions} and the decimal numbers (presumably less than
+1; a leading zero is allowed and ignored) after the
address@hidden@@multitable} command, as in:
+
address@hidden
+@@multitable @@columnfractions .33 .33 .33
address@hidden example
+
+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.
+
address@hidden
address@hidden Prototype row, column widths defined by
+To specify a prototype row, write the longest entry for each column
+enclosed in braces after the @code{@@multitable} command. For example:
+
address@hidden
+@@multitable @{some text for column address@hidden @{for column address@hidden
address@hidden example
+
address@hidden
+The first column will then have the width of the typeset `some text for
+column one', and the second column the width of `for column two'.
+
+The prototype entries need not appear in the table itself.
+
+Although we used simple text in this example, the prototype entries can
+contain Texinfo commands; markup commands such as @code{@@code} are
+particularly likely to be useful.
+
address@hidden enumerate
+
+
address@hidden Multitable Rows
address@hidden Multitable Rows
+
address@hidden Multitable rows
address@hidden Rows, of a multitable
+
address@hidden item
address@hidden tab
+After the @code{@@multitable} command defining the column widths (see
+the previous section), you begin each row in the body of a multitable
+with @code{@@item}, and separate the column entries with @code{@@tab}.
+Line breaks are not special within the table body, and you may break
+input lines in your source file as necessary.
+
address@hidden headitem
address@hidden Heading row, in table
address@hidden @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
+heading row is followed by a separator line made of dashes (@samp{-}
+characters).
+
address@hidden headitemfont
address@hidden Font for multitable heading rows
+The command @code{@@headitemfont} can be used in templates when the
+entries in an @code{@@headitem} row need to be used in a template. It
+is a synonym for @code{@@b}, but using @code{@@headitemfont} avoids
+any dependency on that particular font style, in case we provide a way
+to change it in the future.
+
+Here is a complete example of a multi-column table (the text is from
address@hidden GNU Emacs Manual}, @pxref{Split Window,, Splitting Windows,
+emacs, The GNU Emacs Manual}):
+
address@hidden
+@@multitable @@columnfractions .15 .45 .4
+@@headitem Key @@tab Command @@tab Description
+@@item C-x 2
+@@tab @@address@hidden@}
+@@tab Split the selected window into two windows,
+with one above the other.
+@@item C-x 3
+@@tab @@address@hidden@}
+@@tab Split the selected window into two windows
+positioned side by side.
+@@item C-Mouse-2
+@@tab
+@@tab In the mode line or scroll bar of a window,
+split that window.
+@@end multitable
address@hidden example
+
address@hidden produces:
+
address@hidden @columnfractions .15 .45 .4
address@hidden Key @tab Command @tab Description
address@hidden C-x 2
address@hidden @code{split-window-vertically}
address@hidden Split the selected window into two windows,
+with one above the other.
address@hidden C-x 3
address@hidden @code{split-window-horizontally}
address@hidden Split the selected window into two windows
+positioned side by side.
address@hidden C-Mouse-2
address@hidden
address@hidden In the mode line or scroll bar of a window,
+split that window.
address@hidden multitable
+
+
address@hidden Special Displays
address@hidden Special Displays
address@hidden Special displays
+
+The commands in this chapter allow you to write text that is specially
+displayed (output format permitting), outside of the normal document
+flow.
+
+One set of such commands is for creating ``floats'', that is, figures,
+tables, and the like, set off from the main text, possibly numbered,
+captioned, and/or referred to from elsewhere in the document. Images
+are often included in these displays.
+
+Another group of commands is for creating footnotes in Texinfo.
+
address@hidden
+* Floats:: Figures, tables, and the like.
+* Images:: Including graphics and images.
+* Footnotes:: Writing footnotes.
address@hidden menu
+
+
address@hidden Floats
address@hidden Floats
address@hidden Floats, in general
+
+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
+some similar type.
+
address@hidden Floating, not yet implemented
+A float is so-named because, in principle, it can be moved to the
+bottom or top of the current page, or to a following page, in the
+printed output. (Floating does not make sense in other output
+formats.) In the present version of Texinfo, however, this floating
+is unfortunately not yet implemented. Instead, the floating material
+is simply output at the current location, more or less as if it were
+an @code{@@group} (@address@hidden@@group}}).
+
address@hidden
+* @t{@@float}:: Producing floating material.
+* @t{@@caption @@shortcaption}:: Specifying descriptions for floats.
+* @t{@@listoffloats}:: A table of contents for floats.
address@hidden menu
+
+
address@hidden @t{@@float}
address@hidden @code{@@float} address@hidden,@var{label}]: Floating Material
+
address@hidden@c old name
address@hidden float
address@hidden Float environment
+
+To produce floating material, enclose the material you want to be
+displayed separate between @code{@@float} and @code{@@end float}
+commands, on lines by themselves.
+
+Floating material often uses @code{@@image} to display an
+already-existing graphic (@pxref{Images}), or @code{@@multitable} to
+display a table (@pxref{Multi-column Tables}). However, the contents
+of the float can be anything. Here's an example with simple text:
+
address@hidden
+@@float Figure,fig:ex1
+This is an example float.
+@@end float
address@hidden example
+
address@hidden And the output:
+
address@hidden Figure,fig:ex1
+This is an example float.
address@hidden float
+
+As shown in the example, @code{@@float} takes two arguments (separated
+by a comma), @var{type} and @var{label}. Both are optional.
+
address@hidden @var
address@hidden type
+Specifies the sort of float this is; typically a word such as
+``Figure'', ``Table'', etc. If this is not given, and @var{label} is,
+any cross referencing will simply use a bare number.
+
address@hidden label
+Specifies a cross reference label for this float. If given, this
+float is automatically given a number, and will appear in any
address@hidden@@listoffloats} output (@address@hidden@@listoffloats}}). Cross
+references to @var{label} are allowed.
+
address@hidden Floats, making unnumbered
address@hidden 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
address@hidden@@listoffloats} output or be cross-referenceable.
address@hidden table
+
address@hidden Ordinarily, you specify both @var{type} and @var{label}, to get a
+labeled and numbered float.
+
address@hidden Floats, numbering of
address@hidden 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
+simply counts 1, 2, 3, @dots{}, and is reset at each chapter. Each
+float type is counted independently.
+
+Floats within an @code{@@unnumbered}, or outside of any chapter, are
+simply numbered consecutively from 1.
+
+These numbering conventions are not, at present, changeable.
+
+
address@hidden @t{@@caption @@shortcaption}
address@hidden @code{@@caption} & @code{@@shortcaption}
+
address@hidden address@hidden old name
address@hidden caption
address@hidden shortcaption
address@hidden Captions, for floats
address@hidden Short captions, for lists of floats
+
+You may write an @code{@@caption} anywhere within an @code{@@float}
+environment, to define a caption for the float. It is not allowed in
+any other context. @code{@@caption} takes a single argument, enclosed
+in braces. Here's an example:
+
address@hidden
+@@float
+An example float, with caption.
+@@address@hidden for example address@hidden
+@@end float
address@hidden example
+
address@hidden The output is:
+
address@hidden
+An example float, with caption.
address@hidden for example float.}
address@hidden float
+
address@hidden@@caption} can appear anywhere within the float; it is not
+processed until the @code{@@end float}. The caption text is usually a
+sentence or two, but may consist of several paragraphs if necessary.
+
+In the output, the caption always appears below the float; this is not
+currently changeable. It is preceded by the float type and/or number,
+as specified to the @code{@@float} command (see the previous section).
+
+The @code{@@shortcaption} command likewise may be used only within
address@hidden@@float}, and takes a single argument in braces. The short
+caption text is used instead of the caption text in a list of floats
+(see the next section). Thus, you can write a long caption for the
+main document, and a short title to appear in the list of floats. For
+example:
+
address@hidden
+@@float
+... as above ...
+@@address@hidden for list of address@hidden
+@@end float
address@hidden example
+
+The text for @code{@@shortcaption} may not contain comments
+(@code{@@c}), verbatim text (@code{@@verb}), environments such as
address@hidden@@example}, footnotes (@code{@@footnote}) or other complex
+constructs. The same constraints apply to @code{@@caption} unless
+there is an @code{@@shortcaption}.
+
+
address@hidden @t{@@listoffloats}
address@hidden @code{@@listoffloats}: Tables of Contents for Floats
+
address@hidden@c old name
address@hidden listoffloats
address@hidden List of floats
address@hidden Floats, list of
address@hidden Table of contents, for floats
+
+You can write an @code{@@listoffloats} command to generate a list of
+floats for a given float type (@address@hidden@@float}}), analogous to
+the document's overall table of contents. Typically, it is written in
+its own @code{@@unnumbered} node to provide a heading and structure,
+rather like @code{@@printindex} (@pxref{Printing Indices & Menus}).
+
address@hidden@@listoffloats} takes one optional argument, the float type.
+Here's an example:
+
address@hidden
+@@node List of Figures
+@@unnumbered List of Figures
+@@listoffloats Figure
address@hidden example
+
address@hidden And the output from @code{@@listoffloats}:
+
address@hidden
address@hidden Figure
address@hidden display
+
+Without any argument, @code{@@listoffloats} generates a list of floats
+for which no float type was specified, i.e., no first argument to the
address@hidden@@float} command (@address@hidden@@float}}).
+
+Each line in the list of floats contains the float type (if any),
+the float number, and the caption, if any---the @code{@@shortcaption}
+argument, if it was specified, else the @code{@@caption} argument.
+In Info, the result is a menu where each float can be selected. In
+HTML, each line is a link to the float. In printed output, the page
+number is included.
+
+Unnumbered floats (those without cross reference labels) are omitted
+from the list of floats.
+
+
address@hidden Images
address@hidden Inserting Images
+
address@hidden Images, inserting
address@hidden Pictures, inserting
address@hidden image
+
+You can insert an image given in an external file with the
address@hidden@@image} command. Although images can be used anywhere,
+including the middle of a paragraph, we describe them in this chapter
+since they are most often part of a displayed figure or example.
+
address@hidden
+* Image Syntax::
+* Image Scaling::
address@hidden menu
+
+
address@hidden Image Syntax
address@hidden Image Syntax
+
+Here is the synopsis of the @code{@@image} command:
+
address@hidden
+@@address@hidden@address@hidden,} @address@hidden,} @address@hidden,}
@address@hidden, address@hidden@address@hidden
address@hidden example
+
address@hidden Formats for images
address@hidden Image formats
+The @var{filename} argument is mandatory, and must not have an
+extension, because the different processors support different formats:
+
address@hidden @bullet
address@hidden
address@hidden eps image format
address@hidden (DVI output) reads the file @address@hidden
+(Encapsulated PostScript format).
+
address@hidden
address@hidden address@hidden, and images}
address@hidden png image format
address@hidden jpeg image format
address@hidden pdf image inclusions
address@hidden reads @address@hidden, @address@hidden,
address@hidden@var{filename}.jpg}, or @address@hidden (in that
+order). It also tries uppercase versions of the extensions. The PDF
+format does not support EPS images, so such must be converted first.
+
address@hidden
+For Info, @code{makeinfo} includes @address@hidden verbatim
+(more or less as if it were in @code{@@verbatim}). The Info output
+may also include a reference to @address@hidden or
address@hidden@var{filename}.jpg}. (See below.)
+
address@hidden
+For HTML, @code{makeinfo} outputs a reference to
address@hidden@var{filename}.png}, @address@hidden,
address@hidden@var{filename}.jpeg} or @address@hidden (in that
+order). If none of those exist, it gives an error, and outputs a
+reference to @address@hidden anyway.
+
address@hidden
address@hidden SVG images, used in Docbook
+For Docbook, @code{makeinfo} outputs references to
address@hidden@var{filename}.eps}, @address@hidden
address@hidden@var{filename}.jpg}, @address@hidden,
address@hidden@var{filename}.png} and @address@hidden, for every
+file found. Also, @address@hidden is included verbatim, if
+present.
+
address@hidden
+For Info and HTML output, @code{makeinfo} uses the optional fifth
+argument @var{extension} to @code{@@image} for the filename extension,
+if it is specified and the file is found. Any leading period should
+be included in @var{extension}. For example:
+
address@hidden XPM image format
address@hidden
+@@address@hidden,,,,address@hidden
address@hidden example
+
address@hidden itemize
+
+If you want to install image files for use by Info readers too, we
+recommend putting them in a subdirectory like @address@hidden
+for a package @var{foo}. Copying the files into
address@hidden(infodir)/@var{foo}-figures/} should be done in your
address@hidden
+
+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}
+(@address@hidden@@titlefont @@center @@sp}}).
+
address@hidden Alt attribute for images
address@hidden Images, alternate text for
address@hidden - (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
address@hidden@@image}, if supplied. If not supplied, @code{makeinfo} uses
+the full file name of the image being displayed. The @var{alttext} is
+processed as Texinfo text, so special characters such as @samp{"} and
address@hidden<} and @samp{&} are escaped in the HTML output; also, you can
+get an empty @code{alt} string with @code{@@-} (a command that
+produces no output; @address@hidden@@- @@hyphenation}}).
+
+For Info output, the @code{alt} string is also processed as Texinfo
+text and output. In this case, @samp{\} is escaped as @samp{\\} and
address@hidden"} as @samp{\"}; no other escapes are done.
+
+In Info output, @code{makeinfo} writes a reference to the binary image
+file (trying @var{filename} suffixed with @address@hidden,
address@hidden@var{.extension}}, @file{.png}, or @file{.jpg}, in that order)
+if one exists. It also literally includes the @file{.txt} file if one
+exists. This way, Info readers which can display images (such as the
+Emacs Info browser, running under X) can do so, whereas Info readers
+which can only use text (such as the standalone Info reader) can
+display the textual version.
+
address@hidden @samp{^@@^H} for images in Info
+The implementation of this is to put the following construct into the
+Info output:
+
address@hidden
+^@@^H[image src="@var{binaryfile}" text="@var{txtfile}"
+ alt="@var{alttext} ... ^@@^H]
address@hidden example
+
address@hidden where @samp{^@@} and @samp{^H} stand for the actual null and
+backspace control characters. If one of the files is not present, the
+corresponding argument is omitted.
+
+The reason for mentioning this here is that older Info browsers (this
+feature was introduced in Texinfo version 4.6) will display the above
+literally, which, although not pretty, should not be harmful.
+
+
address@hidden Image Scaling
address@hidden Image Scaling
+
address@hidden Images, scaling
address@hidden Scaling images
address@hidden Width of images
address@hidden Height of images
address@hidden Aspect ratio of images
address@hidden Distorting images
+The optional @var{width} and @var{height} arguments to the
address@hidden@@image} command (see the previous section) specify the size to
+which to scale the image. They are only taken into account in @TeX{}.
+If neither is specified, the image is presented in its natural size
+(given in the file); if only one is specified, the other is scaled
+proportionately; and if both are specified, both are respected, thus
+likely distorting the original image by changing its aspect ratio.
+
address@hidden Dimensions and image sizes
+The @var{width} and @var{height} may be specified using any valid @TeX{}
+dimension, namely:
+
address@hidden @asis
address@hidden pt
address@hidden Points (dimension)
+point (72.27pt = 1in)
address@hidden pc
address@hidden Picas
+pica (1pc = 12pt)
address@hidden bp
address@hidden Big points
+big point (72bp = 1in)
address@hidden in
address@hidden Inches
+inch
address@hidden cm
address@hidden Centimeters
+centimeter (2.54cm = 1in)
address@hidden mm
address@hidden Millimeters
+millimeter (10mm = 1cm)
address@hidden dd
address@hidden address@hidden points
address@hidden point (1157dd = 1238pt)
address@hidden cc
address@hidden Ciceros
+cicero (1cc = 12dd)
address@hidden sp
address@hidden Scaled points
+scaled point (65536sp = 1pt)
address@hidden table
+
address@hidden ridt.eps
+For example, the following will scale a file @file{ridt.eps} to one
+inch vertically, with the width scaled proportionately:
+
address@hidden
+@@address@hidden,,address@hidden
address@hidden example
+
address@hidden epsf.tex
+For @code{@@image} to work with @TeX{}, the file @file{epsf.tex} must be
+installed somewhere that @TeX{} can find it. (The standard location is
address@hidden@var{texmf}/tex/generic/dvips/epsf.tex}, where @var{texmf} is a
+root of your @TeX{} directory tree.) This file is included in the
+Texinfo distribution and is also available from
address@hidden://tug.org/tex/epsf.tex}, among other places.
+
address@hidden@@image} can be used within a line as well as for displayed
+figures. Therefore, if you intend it to be displayed, be sure to leave
+a blank line before the command, or the output will run into the
+preceding text.
+
+Image scaling is presently implemented only in @TeX{}, not in HTML or
+any other sort of output.
+
+
address@hidden Footnotes
address@hidden Footnotes
address@hidden Footnotes
address@hidden footnote
+
+A @dfn{footnote} is for a reference that documents or elucidates the
+primary address@hidden footnote should complement or expand upon the
+primary text, but a reader should not need to read a footnote to
+understand the primary text. For a thorough discussion of footnotes,
+see @cite{The Chicago Manual of Style}, which is published by the
+University of Chicago Press.} Footnotes are distracting; use them
+sparingly at most, and it is best to avoid them completely. Standard
+bibliographical references are better placed in a bibliography at the
+end of a document instead of in footnotes throughout.
+
address@hidden
+* Footnote Commands:: How to write a footnote in Texinfo.
+* Footnote Styles:: Controlling how footnotes appear in Info.
address@hidden menu
+
+
address@hidden Footnote Commands
address@hidden Footnote Commands
+
+In Texinfo, footnotes are created with the @code{@@footnote} command.
+This command is followed immediately by a left brace, then by the text
+of the footnote, and then by a terminating right brace. Footnotes may
+be of any length (they will be broken across pages if necessary), but
+are usually short. The template is:
+
address@hidden
+ordinary text@@address@hidden@var{text of address@hidden
address@hidden example
+
+As shown here, the @code{@@footnote} command should come right after the
+text being footnoted, with no intervening space; otherwise, the footnote
+marker might end up starting a line.
+
+For example, this clause is followed by a sample address@hidden
+is the sample footnote.}; in the Texinfo source, it looks like
+this:
+
address@hidden
address@hidden sample footnote@@address@hidden is the sample
address@hidden; in the Texinfo address@hidden
address@hidden example
+
+As you can see, the source includes two punctuation marks next to each
+other; in this case, @address@hidden;} is the sequence. This is normal (the
+first ends the footnote and the second belongs to the sentence being
+footnoted), so don't worry that it looks odd.
+
+In a printed manual or book, the reference mark for a footnote is a
+small, superscripted number; the text of the footnote appears at the
+bottom of the page, below a horizontal line.
+
+In Info, the reference mark for a footnote is a pair of parentheses
+with the footnote number between them, like this: @samp{(1)}. The
+reference mark is followed by a cross reference link to the footnote
+text if footnotes are put in separate nodes (@pxref{Footnote Styles}).
+
+In the HTML output, footnote references are generally marked with a
+small, superscripted number which is rendered as a hypertext link to
+the footnote text.
+
+By the way, footnotes in the argument of an @code{@@item} command for
+an @code{@@table} must be on the same line as the @code{@@item} (as
+usual). @xref{Two-column Tables}.
+
+
address@hidden Footnote Styles
address@hidden Footnote Styles
+
+Info has two footnote styles, which determine where the text of the
+footnote is located:
+
address@hidden @bullet
address@hidden @address@hidden node footnote style
address@hidden
+In the `End' node style, all the footnotes for a single node are
+placed at the end of that node. The footnotes are separated from the
+rest of the node by a line of dashes with the word @samp{Footnotes}
+within it. Each footnote begins with an @samp{(@var{n})} reference
+mark.
+
address@hidden 700
address@hidden
+Here is an example of the Info output for a single footnote in the
+end-of-node style:
+
address@hidden
address@hidden
+--------- Footnotes ---------
+
+(1) Here is a sample footnote.
address@hidden group
address@hidden example
+
address@hidden @address@hidden footnote style
address@hidden
+In the `Separate' node style, all the footnotes for a single
+node are placed in an automatically constructed node of
+their own. In this style, a ``footnote reference'' follows
+each @samp{(@var{n})} reference mark in the body of the
+node. The footnote reference is actually a cross reference
+which you use to reach the footnote node.
+
+The name of the node with the footnotes is constructed
+by appending @address@hidden to the name of the node
+that contains the footnotes. (Consequently, the footnotes'
+node for the @file{Footnotes} node is
address@hidden@file{Footnotes-Footnotes}}!) The footnotes' node has an
+`Up' node pointer that leads back to its parent node.
+
address@hidden
+Here is how the first footnote in this manual looks after being
+formatted for Info in the separate node style:
+
address@hidden
address@hidden
+File: texinfo.info Node: Overview-Footnotes, Up: Overview
+
+(1) The first syllable of "Texinfo" is pronounced like "speck", not
+"hex". @dots{}
address@hidden group
address@hidden smallexample
address@hidden itemize
+
+Unless your document has long and important footnotes (as in, say,
+Gibbon's @cite{Decline and Fall @dots{}}), we recommend the @samp{end}
+style, as it is simpler for readers to follow.
+
address@hidden footnotestyle
+Use the @code{@@footnotestyle} command to specify an Info file's
+footnote style. Write this command at the beginning of a line followed
+by an argument, either @samp{end} for the end node style or
address@hidden for the separate node style.
+
address@hidden 700
+For example,
+
address@hidden
+@@footnotestyle end
address@hidden example
address@hidden
+or
address@hidden
+@@footnotestyle separate
address@hidden example
+
+Write an @code{@@footnotestyle} command before or shortly after the
+end-of-header line at the beginning of a Texinfo file. (You should
+include any @code{@@footnotestyle} command between the start-of-header
+and end-of-header lines, so the region formatting commands will format
+footnotes as specified.)
+
+In HTML, when the footnote style is @samp{end}, or if the output is
+not split, footnotes are put at the end of the output. If set to
address@hidden, and the output is split, they are placed in a
+separate file.
+
+
address@hidden Indices
address@hidden Indices
address@hidden Indices
+
+Using Texinfo, you can generate indices without having to sort and
+collate entries manually. In an index, the entries are listed in
+alphabetical order, together with information on how to find the
+discussion of each entry. In a printed manual, this information
+consists of page numbers. In an Info file, this information is a menu
+entry leading to the first node referenced.
+
+Texinfo provides several predefined kinds of index: an index for
+functions, an index for variables, an index for concepts, and so on.
+You can combine indices or use them for other than their canonical
+purpose. Lastly, you can define your own new indices.
+
address@hidden Indices & Menus}, for information on how to print
+indices.
+
address@hidden
+* Index Entries:: Choose different words for index entries.
+* Predefined Indices:: Use different indices for different kinds
+ of entries.
+* Indexing Commands:: How to make an index entry.
+* Combining Indices:: How to combine indices.
+* New Indices:: How to define your own indices.
address@hidden menu
+
+
address@hidden Index Entries
address@hidden Making Index Entries
address@hidden Index entries, making
address@hidden Entries, making index
+
+When you are making index entries, it is good practice to think of the
+different ways people may look for something. Different people
address@hidden not} think of the same words when they look something up. A
+helpful index will have items indexed under all the different words
+that people may use. For example, one reader may think it obvious
+that the two-letter names for indices should be listed under
+``Indices, two-letter names, since ``Indices'' are the general
+concept. But another reader may remember the specific concept of
+two-letter names and search for the entry listed as ``Two letter names
+for indices''. A good index will have both entries and will help both
+readers.
+
+Like typesetting, the construction of an index is a skilled art, the
+subtleties of which may not be appreciated until you need to do it
+yourself.
+
address@hidden Indices & Menus}, for information about printing an
+index at the end of a book or creating an index menu in an Info file.
+
+
address@hidden Predefined Indices
address@hidden Predefined Indices
+
+Texinfo provides six predefined indices. Here are their nominal
+meanings, abbreviations, and the corresponding index entry commands:
+
address@hidden @samp
address@hidden cp
address@hidden @code{cp} (concept) index
address@hidden cindex
+(@code{@@cindex}) concept index, for general concepts.
address@hidden fn
address@hidden @code{fn} (function) index
address@hidden findex
+(@code{@@findex}) function index, for function and function-like
+names (such as entry points of libraries).
address@hidden ky
address@hidden @code{ky} (keystroke) index
address@hidden kindex
+(@code{@@kindex}) keystroke index, for keyboard commands.
address@hidden pg
address@hidden @code{pg} (program) index
address@hidden pindex
+(@code{@@pindex}) program index, for names of programs.
address@hidden tp
address@hidden @code{tp} (data type) index
address@hidden tindex
+(@code{@@tindex}) data type index, for type names (such as structures
+defined in header files).
address@hidden vr
address@hidden @code{vr} (variable) index
address@hidden vindex
+(@code{@@vindex}) variable index, for variable names (such as global
+variables of libraries).
address@hidden table
+
address@hidden
+Not every manual needs all of these, and most manuals use only two or
+three at most. The present manual, for example, has two indices: a
+concept index and an @@-command index (that is actually the function
+index but is called a command index in the chapter heading).
+
+You are not required to use the predefined indices strictly for their
+canonical purposes. For example, suppose you wish to index some C
+preprocessor macros. You could put them in the function index along
+with actual functions, just by writing @code{@@findex} commands for
+them; then, when you print the ``Function Index'' as an unnumbered
+chapter, you could give it the title `Function and Macro Index' and
+all will be consistent for the reader.
+
+On the other hand, it is best not to stray too far from the meaning of
+the predefined indices. Otherwise, in the event that your text is
+combined with other text from other manuals, the index entries will
+not match up. Instead, define your own new index (@pxref{New
+Indices}).
+
+We recommend having a single index in the final document whenever
+possible, however many source indices you use, since then readers have
+only one place to look. Two or more source indices can be combined
+into one output index using the @code{@@synindex} or
address@hidden@@syncodeindex} commands (@pxref{Combining Indices}).
+
+
address@hidden Indexing Commands
address@hidden Defining the Entries of an Index
+
address@hidden Defining indexing entries
address@hidden Index entries
address@hidden Entries for an index
address@hidden Specifying index entries
address@hidden Creating index entries
+
+The data to make an index come from many individual indexing commands
+scattered throughout the Texinfo source file. Each command says to add
+one entry to a particular index; after formatting, the index will give
+the current page number or node name as the reference.
+
+An index entry consists of an indexing command at the beginning of a
+line followed, on the rest of the line, by the entry.
+
+For example, this section begins with the following five entries for
+the concept index:
+
address@hidden
+@@cindex Defining indexing entries
+@@cindex Index entries, defining
+@@cindex Entries for an index
+@@cindex Specifying index entries
+@@cindex Creating index entries
address@hidden example
+
+Each predefined index has its own indexing address@hidden@@cindex}
+for the concept index, @code{@@findex} for the function index, and so
+on, as listed in the previous section.
+
address@hidden Writing index entries
address@hidden Index entries, advice on writing
address@hidden Advice on writing entries
address@hidden Capitalization of index entries
+Concept index entries consist of text. The best way to write an index
+is to devise entries which are terse yet clear. If you can do this,
+the index usually looks better if the entries are written just as they
+would appear in the middle of a sentence, that is, capitalizing only
+proper names and acronyms that always call for uppercase letters.
+This is the case convention we use in most GNU manuals' indices.
+
+If you don't see how to make an entry terse yet clear, make it longer
+and clear---not terse and confusing. If many of the entries are
+several words long, the index may look better if you use a different
+convention: to capitalize the first word of each entry. Whichever
+case convention you use, use it consistently.
+
+In any event, do not ever capitalize a case-sensitive name such as a C
+or Lisp function name or a shell command; that would be a spelling
+error. Entries in indices other than the concept index are symbol
+names in programming languages, or program names; these names are
+usually case-sensitive, so likewise use upper- and lowercase as
+required.
+
address@hidden Unique index entries
+It is a good idea to make index entries unique wherever feasible.
+That way, people using the printed output or online completion of
+index entries don't see undifferentiated lists. Consider this an
+opportunity to make otherwise-identical index entries be more
+specific, so readers can more easily find the exact place they are
+looking for.
+
+Index entries should precede the visible material that is being
+indexed. For instance:
+
address@hidden
+@@cindex hello
+Hello, there!
address@hidden example
+
address@hidden Among other reasons, that way following indexing links (in
+whatever context) ends up before the material, where readers want to
+be, instead of after.
+
address@hidden Index font types
+By default, entries for a concept index are printed in a small roman
+font and entries for the other indices are printed in a small
address@hidden@@code} font. You may change the way part of an entry is
+printed with the usual Texinfo commands, such as @code{@@file} for
+file names (@pxref{Marking Text}), and @code{@@r} for the normal roman
+font (@pxref{Fonts}).
+
address@hidden Caution
+Do not use a colon in an index entry. In Info, a colon separates the
+menu entry name from the node name, so a colon in the entry itself
+confuses Info. @xref{Menu Parts}, for more information about the
+structure of a menu entry.
address@hidden quotation
+
+
address@hidden Combining Indices
address@hidden Combining Indices
address@hidden Combining indices
address@hidden Indices, combining them
+
+Sometimes you will want to combine two disparate indices such as
+functions and concepts, perhaps because you have few enough entries
+that a separate index would look silly.
+
+You could put functions into the concept index by writing
address@hidden@@cindex} commands for them instead of @code{@@findex} commands,
+and produce a consistent manual by printing the concept index with the
+title `Function and Concept Index' and not printing the `Function
+Index' at all; but this is not a robust procedure. It works only if
+your document is never included as part of another document that is
+designed to have a separate function index; if your document were to
+be included with such a document, the functions from your document and
+those from the other would not end up together. Also, to make your
+function names appear in the right font in the concept index, you
+would need to enclose every one of them between the braces of
address@hidden@@code}.
+
address@hidden
+* @t{@@syncodeindex}:: How to merge two indices, using
@code{@@code}
+ font for the merged-from index.
+* @t{@@synindex}:: How to merge two indices, using the
+ roman font for the merged-from index.
address@hidden menu
+
+
address@hidden @t{@@syncodeindex}
address@hidden @code{@@syncodeindex}: Combining indices using @code{@@code}
+
address@hidden@c old name
address@hidden syncodeindex
+
+When you want to combine functions and concepts into one index, you
+should index the functions with @code{@@findex} and index the concepts
+with @code{@@cindex}, and use the @code{@@syncodeindex} command to
+redirect the function index entries into the concept index.
+
+The @code{@@syncodeindex} command takes two arguments; they are the name
+of the index to redirect, and the name of the index to redirect it to.
+The template looks like this:
+
address@hidden
+@@syncodeindex @var{from} @var{to}
address@hidden example
+
address@hidden Predefined names for indices
address@hidden Two letter names for indices
address@hidden Indices, two letter names
address@hidden Names for indices
+For this purpose, the indices are given two-letter names:
+
address@hidden @samp
address@hidden cp
+concept index
address@hidden fn
+function index
address@hidden vr
+variable index
address@hidden ky
+key index
address@hidden pg
+program index
address@hidden tp
+data type index
address@hidden table
+
+Write an @code{@@syncodeindex} command before or shortly after the
+end-of-header line at the beginning of a Texinfo file. For example,
+to merge a function index with a concept index, write the
+following:
+
address@hidden
+@@syncodeindex fn cp
address@hidden example
+
address@hidden
+This will cause 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
+index, write the following:
+
address@hidden
address@hidden
+@@syncodeindex vr cp
+@@syncodeindex fn cp
address@hidden group
address@hidden example
+
address@hidden Fonts for indices
+The @code{@@syncodeindex} command puts all the entries from the `from'
+index (the redirected index) into the @code{@@code} font, overriding
+whatever default font is used by the index to which the entries are
+now directed. This way, if you direct function names from a function
+index into a concept index, all the function names are printed in the
address@hidden@@code} font as you would expect.
+
+
address@hidden @t{@@synindex}
address@hidden @code{@@synindex}: Combining indices
+
address@hidden@c old name
address@hidden synindex
+
+The @code{@@synindex} command is nearly the same as the
address@hidden@@syncodeindex} command, except that it does not put the `from'
+index entries into the @code{@@code} font; rather it puts them in the
+roman font. Thus, you use @code{@@synindex} when you merge a concept
+index into a function index.
+
address@hidden Indices & Menus}, for information about printing an index
+at the end of a book or creating an index menu in an Info file.
+
+
address@hidden New Indices
address@hidden Defining New Indices
+
address@hidden Defining new indices
address@hidden Indices, defining new
address@hidden New index defining
address@hidden defindex
address@hidden defcodeindex
+
+In addition to the predefined indices (@pxref{Predefined Indices}),
+you may use the @code{@@defindex} and @code{@@defcodeindex} commands
+to define new indices. These commands create new indexing @@-commands
+with which you mark index entries. The @code{@@defindex} command is
+used like this:
+
address@hidden
+@@defindex @var{name}
address@hidden example
+
+New index names are usually two-letter words, such as @samp{au}.
+For example:
+
address@hidden
+@@defindex au
address@hidden example
+
+This defines a new index, called the @samp{au} index. At the same
+time, it creates a new indexing command, @code{@@auindex}, that you
+can use to make index entries. Use this new indexing command just as
+you would use a predefined indexing command.
+
+For example, here is a section heading followed by a concept index
+entry and two @samp{au} index entries.
+
address@hidden
+@@section Cognitive Semantics
+@@cindex kinesthetic image schemas
+@@auindex Johnson, Mark
+@@auindex Lakoff, George
address@hidden example
+
address@hidden
+(Evidently, @samp{au} serves here as an abbreviation for ``author''.)
+
+Texinfo constructs the new indexing command by concatenating the name
+of the index with @samp{index}; thus, defining an @samp{xy} index
+leads to the automatic creation of an @code{@@xyindex} command.
+
+Use the @code{@@printindex} command to print the index, as you do with
+the predefined indices. For example:
+
address@hidden
address@hidden
+@@node Author Index
+@@unnumbered Author Index
+
+@@printindex au
address@hidden group
address@hidden example
+
+The @code{@@defcodeindex} is like the @code{@@defindex} command,
+except that, in the printed output, it prints entries in an
address@hidden@@code} font by default instead of a roman font.
+
+You should define new indices before the end-of-header line of a
+Texinfo file, and (of course) before any @code{@@synindex} or
address@hidden@@syncodeindex} commands (@pxref{Texinfo File Header}).
+
+As mentioned earlier (@pxref{Predefined Indices}), we recommend having
+a single index in the final document whenever possible, however many
+source indices you use, since then readers have only one place to
+look.
+
+When creating an index, @TeX{} creates a file whose extension is the
+name of the index (@pxref{Names of index files}). Therefore you
+should avoid using index names that collide with extensions used for
+other purposes, such as @samp{.aux} or @samp{.xml}.
address@hidden already reports an error if a new index conflicts
+well-known extension name.
+
+
address@hidden Insertions
address@hidden Special Insertions
address@hidden Inserting special characters and symbols
address@hidden Special insertions
+
+Texinfo provides several commands for inserting characters that have
+special meaning in Texinfo, such as braces, and for other graphic
+elements that do not correspond to simple characters you can type.
+
address@hidden
+These are:
+
address@hidden @bullet
address@hidden The Texinfo special characters: @samp{@@ @address@hidden , \ #}.
address@hidden Whitespace within and around a sentence.
address@hidden Accents.
address@hidden Dots and bullets.
address@hidden The @TeX{} logo and the copyright symbol.
address@hidden The euro and pounds currency symbols.
address@hidden The degrees symbol.
address@hidden The minus sign.
address@hidden Mathematical expressions.
address@hidden Glyphs for examples of programming: evaluation, macros, errors,
etc.
address@hidden Footnotes.
address@hidden itemize
address@hidden iftex
+
address@hidden
+* Special Characters:: Inserting @@ @address@hidden , \ #
+* Inserting Quote Characters:: Inserting left and right quotes, in code.
+* Inserting Space:: Inserting the right amount of whitespace.
+* Inserting Accents:: Inserting accents and special characters.
+* Inserting Quotation Marks:: Inserting quotation marks.
+* Inserting Math:: Formatting mathematical expressions.
+* Glyphs for Text:: Inserting Dots, bullets, currencies, etc.
+* Glyphs for Programming:: Indicating results of evaluation,
+ expansion of macros, errors, etc.
address@hidden menu
+
+
address@hidden Special Characters
address@hidden Special Characters: Inserting @@ @address@hidden , \ #
address@hidden address@hidden previous names for this node
address@hidden Braces Comma}
address@hidden Special characters, inserting
address@hidden Commands to insert special characters
+
address@hidden@@} and curly braces are the basic special characters in
+Texinfo. To insert these characters so they appear in text, you must
+put an @samp{@@} in front of these characters to prevent Texinfo from
+misinterpreting them. Alphabetic commands are also provided.
+
+The other characters (comma, backslash, hash) are special only in
+restricted contexts, as explained in the respective sections.
+
address@hidden
+* Inserting an Atsign:: @code{@@@@}, @code{@@address@hidden@}}.
+* Inserting Braces:: @code{@@@{ @@@}}, @code{@@l address@hidden@}}.
+* Inserting a Comma:: , and @code{@@address@hidden@}}.
+* Inserting a Backslash:: \ and @code{@@address@hidden@}}.
+* Inserting a Hashsign:: # and @code{@@address@hidden@}}.
address@hidden menu
+
+
address@hidden Inserting an Atsign
address@hidden Inserting `@@' with @code{@@@@} and @code{@@address@hidden@}}
address@hidden At sign, inserting
address@hidden Inserting @@ @r{(literal @samp{@@})}
address@hidden @@ @r{(literal @samp{@@})}
address@hidden @@address@hidden@} @r{(literal @samp{@@})}
+
address@hidden@@@@} produces a single @samp{@@} character in the output. Do
+not put braces after an @code{@@@@} command.
+
address@hidden@@address@hidden@}} also produces a single @samp{@@} character in
the
+output. It does need following braces, as usual for alphabetic
+commands. In inline conditionals (@pxref{Inline Conditionals}), it
+can be necessary to avoid using the literal @samp{@@} character in the
+source (and may be clearer in other contexts).
+
+
address@hidden Inserting Braces
address@hidden Inserting address@hidden address@hidden' with @code{@@@{ @@@}}
and @code{@@l address@hidden@}}
+
address@hidden @{ @r{(literal @address@hidden)}
address@hidden @} @r{(literal @address@hidden)}
address@hidden @@address@hidden@} @r{(literal @address@hidden)}
address@hidden @@address@hidden@} @r{(literal @address@hidden)}
address@hidden Braces, inserting
+
address@hidden@@@{} produces a single @address@hidden in the output, and
@code{@@@}}
+produces a single @address@hidden Do not put braces after either an
address@hidden@@@{} or an @code{@@@}} command.
+
address@hidden@@address@hidden@}} and @code{@@address@hidden@}} also produce
+single @address@hidden and @address@hidden characters in the output. They do
need
+following braces, as usual for alphabetic commands. In inline
+conditionals (@pxref{Inline Conditionals}), it can be
+necessary to avoid using literal brace characters in the source (and
+may be clearer in other contexts).
+
+
address@hidden Inserting a Comma
address@hidden Inserting `,' with @code{@@address@hidden@}}
+
address@hidden comma
address@hidden Comma, inserting
+
+Ordinarily, a comma `,' is a normal character that can be simply typed
+in your input where you need it.
+
+However, Texinfo uses the comma as a special character only in one
+context: to separate arguments to those Texinfo commands, such as
address@hidden@@acronym} (@address@hidden@@acronym}}) and @code{@@xref}
+(@pxref{Cross References}), as well as user-defined macros
+(@pxref{Defining Macros}), which take more than one argument.
+
+Since a comma character would confuse Texinfo's parsing for these
+commands, you must use the command @samp{@@address@hidden@}} instead if you
want
+to pass an actual comma. Here are some examples:
+
address@hidden
+@@address@hidden, A Bizarre @@address@hidden@address@hidden
+@@address@hidden,, The @@address@hidden@} address@hidden
+@@address@hidden argument@@address@hidden@} containing a address@hidden
address@hidden example
+
+Although @samp{@@address@hidden@}} can be used nearly anywhere, there is no
+need for it anywhere except in this unusual case.
+
+(Incidentally, the name @samp{@@comma} lacks the @samp{char} suffix used
+in its companion commands only for historical reasons. It didn't seem
+important enough to define a synonym.)
+
+
address@hidden Inserting a Backslash
address@hidden Inserting `\' with @code{@@address@hidden@}}
+
address@hidden backslash
address@hidden Backslash, inserting
+
+Ordinarily, a backslash `\' is a normal character in Texinfo that can
+be simply typed in your input where you need it. The result is to
+typeset the backslash from the typewriter font.
+
+However, Texinfo uses the backslash as a special character in one
+restricted context: to delimit formal arguments in the bodies of
+user-defined macros (@pxref{Defining Macros}).
+
+Due to the vagaries of macro argument parsing, it is more reliable to
+pass an alphabetic command that produces a backslash instead of using
+a literal \. Hence @code{@@address@hidden@}}. Here is an example
+macro call:
+
address@hidden
+@@address@hidden argument@@address@hidden@} with a address@hidden
address@hidden example
+
+Texinfo documents may also use \ as a command character inside
address@hidden@@math} (@pxref{Inserting Math}). In this case, @code{@@\} or
address@hidden produces a ``math'' backslash (from the math symbol
+font), while @code{@@address@hidden@}} produces a typewriter
+backslash as usual.
+
+Although @samp{@@address@hidden@}} can be used nearly anywhere, there
+is no need for it except in these unusual cases.
+
+
address@hidden Inserting a Hashsign
address@hidden Inserting `#' with @code{@@address@hidden@}}
+
address@hidden @@address@hidden@} @r{(literal @samp{#})}
address@hidden Inserting #
address@hidden Hash sign, inserting
+
+Ordinarily, a hash `#' is a normal character in Texinfo that can be
+simply typed in your input where you need it. The result is to
+typeset the hash character from the current font.
+
address@hidden Number sign, inserting
address@hidden Octotherp, inserting
address@hidden Sharp sign (not), inserting
+This character has many other names, varying by locale, such as
+``number sign'', ``pound'', and ``octothorp''. It is also sometimes
+called ``sharp'' or ``sharp sign'' since it vaguely resembles the
+musical symbol by that name. In situations where Texinfo is used,
+``hash'' is the most common in our experience.
+
+However, Texinfo uses the hash character as a special character in one
+restricted context: to introduce the so-called @code{#line} directive
+and variants (@pxref{External Macro Processors}).
+
+So, in order to typeset an actual hash character in such a place (for
+example, in a program that needs documentation about @code{#line}),
+it's necessary to use @code{@@address@hidden@}} or some other construct.
+Here's an example:
+
address@hidden
+@@address@hidden@} 10 "example.c"
address@hidden example
+
+Although @samp{@@address@hidden@}} can be used nearly anywhere, there
+is no need for it anywhere except this unusual case.
+
+
address@hidden Inserting Quote Characters
address@hidden Inserting Quote Characters
+
address@hidden Inserting quote characters
address@hidden Quote characters, inserting
+
+As explained in the early section on general Texinfo input conventions
+(@pxref{Conventions}), Texinfo source files use the ASCII character
address@hidden (96 decimal) to produce a left quote (`), and ASCII @code{'}
+(39 decimal) to produce a right quote ('). Doubling these input
+characters (@code{``} and @code{''}) produces double quotes (`` and
+''). These are the conventions used by @TeX{}.
+
+This works all right for text. However, in examples of computer code,
+readers are especially likely to cut and paste the text
+verbatim---and, unfortunately, some document viewers will mangle these
+characters. (The free PDF reader @command{xpdf} works fine, but other
+PDF readers, both free and nonfree, have problems.)
+
+If this is a concern for you, Texinfo provides these two commands:
+
address@hidden @code
address@hidden @@codequoteundirected @var{on-off}
address@hidden undirected single quote
+causes the output for the @code{'} character in code environments to
+be the undirected single quote, like this:
address@hidden txicodequoteundirected on
address@hidden'}.
address@hidden txicodequoteundirected off
+
address@hidden @@codequotebacktick @var{on-off}
address@hidden backtick
address@hidden grave accent, standalone
+causes the output for the @code{`} character in code environments to
+be the backtick character (standalone grave accent), like this:
address@hidden txicodequotebacktick on
address@hidden
address@hidden txicodequotebacktick off
address@hidden ftable
+
+If you want these settings for only part of the document,
address@hidden@@codequote... off} will restore the normal behavior, as in
address@hidden@@codequoteundirected off}.
+
+These settings affect @code{@@code}, @code{@@example}, @code{@@kbd},
address@hidden@@samp}, @code{@@verb}, and @code{@@verbatim}. @xref{Useful
+Highlighting}.
+
+This feature used to be controlled by @code{@@set} variable names;
+they are still supported, but the command interface is preferred.
+
+
address@hidden Inserting Space
address@hidden Inserting Space
+
address@hidden Inserting space
address@hidden Spacing, inserting
+The following sections describe commands that control spacing of various
+kinds within and after sentences.
+
address@hidden
+* Multiple Spaces:: Inserting multiple spaces.
+* Not Ending a Sentence:: Sometimes a . doesn't end a sentence.
+* Ending a Sentence:: Sometimes it does.
+* @t{@@frenchspacing}:: Specifying end-of-sentence spacing.
+* @t{@@dmn}:: Formatting a dimension.
address@hidden menu
+
+
address@hidden Multiple Spaces
address@hidden Multiple Spaces
+
address@hidden Multiple spaces
address@hidden Whitespace, inserting
address@hidden Space, inserting horizontal
address@hidden <space>
address@hidden <tab>
address@hidden <newline>
+
+Ordinarily, multiple whitespace characters (space, tab, and newline)
+are collapsed into a single space.
+
+Occasionally, you may want to produce several consecutive spaces,
+either for purposes of example (e.g., what your program does with
+multiple spaces as input), or merely for purposes of appearance in
+headings or lists. Texinfo supports three commands:
address@hidden@@@kbd{SPACE}}, @code{@@@kbd{TAB}}, and @code{@@@kbd{NL}}, all
+of which insert a single space into the output. (Here,
address@hidden@@@kbd{SPACE}} represents an @samp{@@} character followed by a
+space, i.e., @samp{@@ }, @kbd{TAB} represents an actual tab character,
+and @kbd{NL} represent the tab character and end-of-line, i.e., when
address@hidden@@} is the last character on a line.)
+
+For example,
address@hidden
+Spacey@@ @@ @@ @@
+example.
address@hidden example
+
address@hidden produces
+
address@hidden
+Spacey@ @ @ @
+example.
address@hidden example
+
+Other possible uses of @code{@@@kbd{SPACE}} have been subsumed by
address@hidden@@multitable} (@pxref{Multi-column Tables}).
+
+Do not follow any of these commands with braces.
+
+To produce a non-breakable space, see @address@hidden@@tie}}.
+
+
address@hidden Not Ending a Sentence
address@hidden Not Ending a Sentence
+
address@hidden Not ending a sentence
address@hidden Sentence non-ending punctuation
address@hidden Periods, inserting
address@hidden Spacing, in the middle of sentences
+Depending on whether a period or exclamation point or question mark is
+inside or at the end of a sentence, slightly less or more space is
+inserted after a period in a typeset manual. Since it is not always
+possible to determine automatically when a period ends a sentence,
+special commands are needed in some circumstances. Usually, Texinfo
+can guess how to handle periods, so you do not need to use the special
+commands; you just enter a period as you would if you were using a
+typewriter: put two spaces after the period, question mark, or
+exclamation mark that ends a sentence.
+
address@hidden <colon> @r{(suppress end-of-sentence space)}
+Use the @code{@@:}@: command after a period, question mark,
+exclamation mark, or colon that should not be followed by extra space.
+For example, use @code{@@:}@: after periods that end (lowercase)
+abbreviations which are not at the ends of sentences.
+
+Also, when a parenthetical remark in the middle of a sentence (like
+this one!)@: ends with a period, exclamation point, or question mark,
address@hidden@@:} should be used after the right parenthesis. Similarly for
+right brackets and right quotes (both single and double).
+
+For example,
+
address@hidden
+foo vs.@@: bar (or?)@@: baz
+foo vs. bar (or?) baz
address@hidden example
+
address@hidden
address@hidden
+produces
address@hidden ifnottex
address@hidden
+produces the following. If you look carefully at this printed output,
+you will see a bit of extraneous space after the @samp{vs.}@: and
address@hidden(or?)}@: in the second line.
address@hidden iftex
+
address@hidden
+foo vs.@: bar (or?)@: address@hidden
+foo vs. bar (or?) baz
address@hidden quotation
+
address@hidden
address@hidden@@:} has no effect on the HTML or Docbook output.
+
+Do not put braces after @code{@@:} (or any non-alphabetic command).
+
+A few Texinfo commands force normal interword spacing, so that you
+don't have to insert @code{@@:} where you otherwise would. These are
+the code-like highlighting commands, @code{@@var}, @code{@@abbr}, and
address@hidden@@acronym} (@pxref{Useful Highlighting}). For example, in
address@hidden@@address@hidden address@hidden the period is not considered the
end of a
+sentence, and no extra space is inserted.
+
+
address@hidden Ending a Sentence
address@hidden Ending a Sentence
+
address@hidden Ending a Sentence
address@hidden Sentence ending punctuation
+
address@hidden . @r{(end of sentence)}
address@hidden ! @r{(end of sentence)}
address@hidden ? @r{(end of sentence)}
address@hidden Spacing, at ends of sentences
+As mentioned above, Texinfo normally inserts additional space after
+the end of a sentence. It uses a simple heuristic for this: a
+sentence ends with a period, exclamation point, or question mark
+followed by optional closing punctuation and then whitespace, and
address@hidden preceded by a capital letter.
+
+Use @code{@@.}@: instead of a period, @code{@@!}@: instead of an
+exclamation point, and @code{@@?}@: instead of a question mark at the
+end of a sentence that does end with a capital letter. For example:
+
address@hidden
+Give it to M.I.B. and to M.E.W@@. Also, give it to R.J.C@@.
+Give it to M.I.B. and to M.E.W. Also, give it to R.J.C.
address@hidden example
+
address@hidden
+The output follows. In printed output and Info, you can see the
+desired extra whitespace after the @samp{W} in the first line.
+
address@hidden
+Give it to M.I.B. and to address@hidden Also, give it to address@hidden@*
+Give it to M.I.B. and to M.E.W. Also, give it to R.J.C.
address@hidden quotation
+
+In the HTML output, @code{@@.}@: is equivalent to a simple @samp{.};
+likewise for @code{@@!}@: and @code{@@?}@:.
+
+The meanings of @code{@@:} and @code{@@.}, etc.@: in Texinfo are
+designed to work well with the Emacs sentence motion commands
+(@pxref{Sentences,,, emacs, The GNU Emacs Manual}).
+
+Do not put braces after any of these commands.
+
+A few Texinfo commands are not considered as being an abbreviation,
+even though they may end with a capital letter when expanded, so that
+you don't have to insert @code{@@.} and companions. This is the case
+for code-like highlighting commands, @code{@@var} arguments ending
+with a capital letter, and @code{@@TeX}. For example, that sentence
+ended with @samp{@@address@hidden@@@@address@hidden; @code{@@.} was not
needed. Also
+in @code{... @@address@hidden@}. Text} the period after @var{VARNAME}
+ends the sentence; there is no need to use @code{@@.}.
+
+
address@hidden @t{@@frenchspacing}
address@hidden @code{@@frenchspacing} @var{val}: Control Sentence Spacing
+
address@hidden@c old name
address@hidden frenchspacing
address@hidden French spacing
address@hidden Sentences, spacing after
address@hidden Space, after sentences
+
+In American typography, it is traditional and correct to put extra
+space at the end of a sentence. This is the default in Texinfo
+(implemented in Info and printed output; for HTML, we don't try to
+override the browser). In French typography (and others), this extra
+space is wrong; all spaces are uniform.
+
+Therefore Texinfo provides the @code{@@frenchspacing} command to
+control the spacing after punctuation. It reads the rest of the line
+as its argument, which must be the single word @samp{on} or @samp{off}
+(always these words, regardless of the language of the document).
+Here is an example:
+
address@hidden
+@@frenchspacing on
+This is text. Two sentences. Three sentences. French spacing.
+
+@@frenchspacing off
+This is text. Two sentences. Three sentences. Non-French spacing.
address@hidden example
+
address@hidden produces:
+
address@hidden on
+This is text. Two sentences. Three sentences. French spacing.
+
address@hidden off
+This is text. Two sentences. Three sentences. Non-French spacing.
+
address@hidden@@frenchspacing} also affects the output after @code{@@.},
address@hidden@@!}, and @code{@@?} (@pxref{Ending a Sentence}).
+
address@hidden@@frenchspacing} has no effect on the HTML or Docbook output;
+for XML, it outputs a transliteration of itself (@pxref{Output
+Formats}).
+
+
address@hidden @t{@@dmn}
address@hidden @code{@@address@hidden@address@hidden: Format a Dimension
+
address@hidden@c old name
address@hidden Thin space between number, dimension
address@hidden Dimension formatting
address@hidden Format a dimension
address@hidden dmn
+
+You can use the @code{@@dmn} command to format a dimension with a
+little extra space in the printed output. That is, on seeing
address@hidden@@dmn}, @TeX{} inserts just enough space for proper typesetting;
+in other output formats, the formatting commands insert no space at
+all.
+
+To use the @code{@@dmn} command, write the number and then follow it
+immediately, with no intervening space, by @code{@@dmn}, and then by
+the dimension within braces. For example,
+
address@hidden
+A4 paper is 8.27@@address@hidden@} wide.
address@hidden example
+
address@hidden
+produces
+
address@hidden
+A4 paper is address@hidden wide.
address@hidden quotation
+
+Not everyone uses this style. Some people prefer address@hidden'@: or
address@hidden'. In these cases, however, you need to use
address@hidden@@tie} (@address@hidden@@tie}}) or @code{@@w}
(@address@hidden@@w}})
+so that no line break can occur between the number and the dimension.
+Also, if you write a period after an abbreviation within a sentence
+(as with the `in.'@: above), you should write @samp{@@:} after the
+period to prevent @TeX{} from inserting extra whitespace, as shown
+here. @xref{Not Ending a Sentence}.
+
+
address@hidden Inserting Accents
address@hidden Inserting Accents
+
address@hidden Inserting accents
address@hidden Accents, inserting
address@hidden Floating accents, inserting
+
+Here is a table with the commands Texinfo provides for inserting
+floating accents. They all need an argument, the character to accent,
+which can either be given in braces as usual (@code{@@'@address@hidden), or, as
+a special case, the braces can be omitted, in which case the argument
+is the next character (@code{@@'e}). This is to make the source as
+convenient as possible to type and read, since accented characters are
+very common in some languages.
+
+If the command is alphabetic, such as @code{@@dotaccent}, then there
+must be a space between the command name and argument if braces are
+not used. If the command is non-alphabetic, such as @code{@@'}, then
+there must @emph{not} be a space; the argument is the very next
+character.
+
+Exception: the argument to @code{@@tieaccent} must be enclosed in
+braces (since it is two characters instead of one).
+
address@hidden documentencoding
+To get the true accented characters output in Info, not just the ASCII
+transliterations, it is necessary to specify @code{@@documentencoding}
+with an encoding which supports the required characters
+(@address@hidden@@documentencoding}}). In this case, you can also use
+non-ASCII (e.g., pre-accented) characters in the source file.
+
address@hidden " @r{(umlaut accent)}
address@hidden Umlaut accent
address@hidden ' @r{(umlaut accent)}
address@hidden Acute accent
address@hidden = @r{(macron accent)}
address@hidden Macron accent
address@hidden ^ @r{(circumflex accent)}
address@hidden Circumflex accent
address@hidden ` @r{(grave accent)}
address@hidden Grave accent
address@hidden ~ @r{(tilde accent)}
address@hidden Tilde accent
address@hidden , @r{(cedilla accent)}
address@hidden Cedilla accent
address@hidden dotaccent
address@hidden Dot accent
address@hidden H @r{(Hungarian umlaut accent)}
address@hidden Hungarian umlaut accent
address@hidden ogonek
address@hidden Ogonek diacritic
address@hidden ringaccent
address@hidden Ring accent
address@hidden tieaccent
address@hidden Tie-after accent
address@hidden u @r{(breve accent)}
address@hidden Breve accent
address@hidden ubaraccent
address@hidden Underbar accent
address@hidden udotaccent
address@hidden Underdot accent
address@hidden v @r{(check accent)}
address@hidden Hacek accent
address@hidden Check accent
address@hidden Caron accent
address@hidden address@hidden@@address@hidden@}}} {Output} {hacek/check/caron
accent}
address@hidden Command @tab Output @tab What
address@hidden @t{@@"o} @tab @"o @tab umlaut accent
address@hidden @t{@@'o} @tab @'o @tab acute accent
address@hidden @t{@@,@address@hidden @tab @,{c} @tab cedilla
accent
address@hidden @t{@@=o} @tab @=o @tab macron/overbar
accent
address@hidden @t{@@^o} @tab @^o @tab circumflex accent
address@hidden @t{@@`o} @tab @`o @tab grave accent
address@hidden @t{@@~o} @tab @~o @tab tilde accent
address@hidden @t{@@address@hidden@}} @tab @dotaccent{o} @tab overdot accent
address@hidden @t{@@address@hidden@}} @tab @H{o} @tab long
Hungarian umlaut
address@hidden @t{@@address@hidden@}} @tab @ogonek{a} @tab ogonek
address@hidden @t{@@address@hidden@}} @tab @ringaccent{o} @tab ring accent
address@hidden @t{@@address@hidden@}} @tab @tieaccent{oo} @tab tie-after accent
address@hidden @t{@@address@hidden@}} @tab @u{o} @tab breve
accent
address@hidden @t{@@address@hidden@}} @tab @ubaraccent{o} @tab underbar accent
address@hidden @t{@@address@hidden@}} @tab @udotaccent{o} @tab underdot accent
address@hidden @t{@@address@hidden@}} @tab @v{o} @tab
hacek/check/caron accent
address@hidden multitable
+
+This table lists the Texinfo commands for inserting other characters
+commonly used in languages other than English.
+
address@hidden questiondown
address@hidden @questiondown{}
address@hidden exclamdown
address@hidden @exclamdown{}
address@hidden aa
address@hidden @aa{}
address@hidden AA
address@hidden @AA{}
address@hidden ae
address@hidden @ae{}
address@hidden AE
address@hidden @AE{}
address@hidden Icelandic
address@hidden Eth
address@hidden dh
address@hidden @dh{}
address@hidden DH
address@hidden @DH{}
address@hidden dotless
address@hidden @dotless{i} (dotless i)
address@hidden @dotless{j} (dotless j)
address@hidden Dotless i, j
address@hidden l
address@hidden @l{}
address@hidden L
address@hidden @L{}
address@hidden o
address@hidden @o{}
address@hidden O
address@hidden @O{}
address@hidden oe
address@hidden @oe{}
address@hidden OE
address@hidden @OE{}
address@hidden Romance ordinals
address@hidden Ordinals, Romance
address@hidden Feminine ordinal
address@hidden ordf
address@hidden @ordf{}
address@hidden Masculine ordinal
address@hidden ordm
address@hidden @ordm{}
address@hidden ss
address@hidden @ss{}
address@hidden Es-zet
address@hidden Sharp S
address@hidden German S
address@hidden Thorn
address@hidden th
address@hidden @th{}
address@hidden TH
address@hidden @TH{}
address@hidden address@hidden@@address@hidden@}}} {oe OE} {es-zet or sharp S}
address@hidden @t{@@address@hidden@}} @tab @exclamdown{} @tab
upside-down !
address@hidden @t{@@address@hidden@}} @tab @questiondown{} @tab upside-down ?
address@hidden @t{@@address@hidden@} @@address@hidden@}} @tab @aa{} @AA{}
@tab a,A with circle
address@hidden @t{@@address@hidden@} @@address@hidden@}} @tab @ae{} @AE{}
@tab ae,AE ligatures
address@hidden @t{@@address@hidden@} @@address@hidden@}} @tab @dh{} @DH{}
@tab Icelandic eth
address@hidden @t{@@address@hidden@}} @tab @dotless{i} @tab dotless i
address@hidden @t{@@address@hidden@}} @tab @dotless{j} @tab dotless j
address@hidden @t{@@address@hidden@} @@address@hidden@}} @tab @l{} @L{}
@tab suppressed-L,l
address@hidden @t{@@address@hidden@} @@address@hidden@}} @tab @o{} @O{}
@tab O,o with slash
address@hidden @t{@@address@hidden@} @@address@hidden@}} @tab @oe{} @OE{}
@tab oe,OE ligatures
address@hidden @t{@@address@hidden@} @@address@hidden@}} @tab @ordf{} @ordm{}
@tab Spanish ordinals
address@hidden @t{@@address@hidden@}} @tab @ss{} @tab
es-zet or sharp S
address@hidden @t{@@address@hidden@} @@address@hidden@}} @tab @th{} @TH{}
@tab Icelandic thorn
address@hidden multitable
+
+
address@hidden Inserting Quotation Marks
address@hidden Inserting Quotation Marks
address@hidden Inserting quotation marks
address@hidden Quotation marks, inserting
+
address@hidden Quotation characters (`'), in source
+Use doubled single-quote characters to begin and end quotations:
address@hidden@address@hidden@dots{}'@w{}'}}. @TeX{} converts two single
quotes to
+left- and right-hand doubled quotation marks,
address@hidden this comes out as "like this" in Info, which is just confusing.
address@hidden
+``like this'',
address@hidden iftex
+and Info converts doubled single-quote characters to ASCII
+double-quotes: @address@hidden@address@hidden'@w{}'}} becomes
@address@hidden"@dots{}"}}.
+
+You may occasionally need to produce two consecutive single quotes;
+for example, in documenting a computer language such as Maxima where
address@hidden'@w{}'} is a valid command. You can do this with the input
address@hidden'@@address@hidden@}'}; the empty @code{@@w} command stops the
combination into
+the double-quote characters.
+
address@hidden Unicode quotation characters
address@hidden Grave accent, 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.
+
+Texinfo supports several other quotation marks used in languages other
+than English. Below is a table with the commands Texinfo provides for
+inserting quotation marks.
+
address@hidden documentencoding
address@hidden UTF-8
address@hidden ISO 8859-15
address@hidden Latin 9
address@hidden ISO 8859-1
address@hidden Latin 1
+In order to get the symbols for the quotation marks in encoded Info
+output, it is necessary to specify @code{@@documentencoding UTF-8}.
+(@address@hidden@@documentencoding}}.) Double guillemets are also
+present in ISO 8859-1 (aka address@hidden) and ISO 8859-15 (aka
address@hidden).
+
address@hidden European Computer Modern fonts
address@hidden 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
+Computer Modern (EC) fonts (@file{ecrm1000} and other variants).
+These fonts are freely available, of course; you can download them
+from @url{http://@/www.ctan.org/@/tex-archive/@/fonts/ec}, among other
+places.
+
address@hidden CM-Super fonts
+The free EC fonts are bitmap fonts created with Metafont. Especially
+for on-line viewing, address@hidden (vector) versions of the fonts are
+preferable; these are available in the CM-Super font package
+(@url{http://@/www.ctan.org/@/tex-archive/@/fonts/@/ps-type1/@/cm-super}).
+
+Both distributions include installation instructions.
+
address@hidden Single quotation marks
address@hidden Double quotation marks
address@hidden Left quotation marks
address@hidden Right quotation marks
address@hidden quotedblleft
address@hidden address@hidden
address@hidden quoteleft
address@hidden `
address@hidden " (undirected double quote character)
address@hidden quotedblright
address@hidden '@w{}'
address@hidden quoteright
address@hidden '
address@hidden Double low-9 quotation mark
address@hidden Single low-9 quotation mark
address@hidden quotedblbase
address@hidden @quotedblbase{} (double low-9 quotation mark)
address@hidden quotesinglbase
address@hidden @quotesinglbase{} (single low-9 quotation mark)
address@hidden Angle quotation marks
address@hidden Guillemets
address@hidden Guillemots
address@hidden French quotation marks
address@hidden Quotation marks, French
address@hidden German quotation marks
address@hidden Quotation marks, German
address@hidden Double guillemets
address@hidden Single guillemets
address@hidden Double angle quotation marks
address@hidden Single angle quotation marks
address@hidden Left-pointing angle quotation marks
address@hidden Right-pointing angle quotation marks
address@hidden Double left-pointing angle quotation mark
address@hidden Double right-pointing angle quotation mark
address@hidden Single left-pointing angle quotation mark
address@hidden Single right-pointing angle quotation mark
address@hidden guillemetleft
address@hidden guillemotleft
address@hidden @guillemetleft{}
address@hidden guillemetright
address@hidden guillemotright
address@hidden @guillemetright{}
address@hidden guilsinglleft
address@hidden @guilsinglleft{}
address@hidden guilsinglright
address@hidden @guilsinglright{}
address@hidden address@hidden@@address@hidden@} '@w{}'}} {Glyph}
{Right-pointing double angle quotation mark (U+00BB)}
address@hidden Command @tab Glyph @tab Unicode
name (point)
address@hidden @address@hidden ``.} @tab @quotedblleft{} @tab Left double
quotation mark (U+201C)
address@hidden @address@hidden ''.} @tab @quotedblright{} @tab Right double
quotation mark (U+201D)
address@hidden @address@hidden `.} @tab @quoteleft{} @tab Left
single quotation mark (U+2018)
address@hidden @address@hidden '.} @tab @quoteright{} @tab Right
single quotation mark (U+2019)
address@hidden @t{@@address@hidden@}} @tab @quotedblbase{} @tab
Double low-9 quotation mark (U+201E)
address@hidden @t{@@address@hidden@}} @tab @quotesinglbase{} @tab Single
low-9 quotation mark (U+201A)
address@hidden @t{@@address@hidden@}} @tab @guillemetleft{} @tab
Left-pointing double angle quotation mark (U+00AB)
address@hidden @t{@@address@hidden@}} @tab @guillemetright{} @tab
Right-pointing double angle quotation mark (U+00BB)
address@hidden @t{@@address@hidden@}} @tab @guilsinglleft{} @tab Single
left-pointing angle quotation mark (U+2039)
address@hidden @t{@@address@hidden@}} @tab @guilsinglright{} @tab Single
right-pointing angle quotation mark (U+203A)
address@hidden multitable
+
address@hidden Auk, bird species
+For the double angle quotation marks, Adobe and @LaTeX{} glyph names
+are also supported: @code{@@guillemotleft} and
address@hidden@@guillemotright}. These names are incorrect; a
+``guillemot'' is a bird species (a type of auk).
+
+Traditions for quotation mark usage vary to a great extent between
+languages
+(@url{http://@/en.wikipedia.org/@/wiki/@/Quotation_mark%2C_non-English_usage@/#Overview}).
+Texinfo does not provide commands for typesetting quotation marks
+according to the numerous traditions. Therefore, you have to choose
+the commands appropriate for the language of your manual. Sometimes
+aliases (@address@hidden@@alias}}) can simplify the usage and make the
+source code more readable. For example, in German,
address@hidden@@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
+convenient:
+
address@hidden
+@@alias lgqq = quotedblbase
+@@alias rgqq = quotedblleft
address@hidden example
+
+
address@hidden Inserting Math
address@hidden @code{@@math}: Inserting Mathematical Expressions
+
address@hidden@c old name
address@hidden math
address@hidden Mathematical expressions, inserting
address@hidden Formulas, mathematical
+
+You can write a short mathematical expression with the @code{@@math}
+command. Write the mathematical expression between braces, like this:
+
address@hidden
+@@address@hidden(a + b)(a + b) = a^2 + 2ab + address@hidden
address@hidden example
+
address@hidden
address@hidden This produces the following in @TeX{}:
+
address@hidden
address@hidden(a + b)(a + b) = a^2 + 2ab + b^2}
address@hidden display
+
address@hidden and the following in other formats:
address@hidden iftex
address@hidden
address@hidden This produces the following in Info and HTML:
address@hidden ifnottex
+
address@hidden
+(a + b)(a + b) = a^2 + 2ab + b^2
address@hidden example
+
+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 produce good mathematical formatting in any
+way.
+
+However, as far as the @TeX{} output is concerned, plain @TeX{}
+mathematical commands are allowed in @code{@@math}, starting with
address@hidden, and the plain @TeX{} math characters like @samp{^} and
address@hidden are also recognized. In essence, @code{@@math} drops you
+into plain @TeX{} math mode.
+
+This allows you to conveniently write superscripts and subscripts (as
+in the above example), and also 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.
+
+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} allows input with matching (but
+unescaped) braces, such as @address@hidden@}}, although it complains
+about such bare braces in regular input.
+
+Here's an example:
+
address@hidden
+@@address@hidden 2\pi \equiv \cos address@hidden
address@hidden example
+
address@hidden
address@hidden which looks like this in @TeX{}:
address@hidden
address@hidden 2\pi \equiv \cos 3\pi}
address@hidden display
+
address@hidden and
address@hidden iftex
address@hidden which looks like the input in Info and HTML:
address@hidden
+\sin 2\pi \equiv \cos 3\pi
address@hidden example
+
address@hidden \ @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
address@hidden, but you'd get the literal two characters @samp{\\} in Info).
address@hidden@@\} is not defined outside of @code{@@math}, since a @samp{\}
+ordinarily produces a literal (typewriter) @samp{\}. You can also use
address@hidden@@address@hidden@}} in any mode to get a typewriter backslash.
address@hidden a Backslash}.
+
address@hidden Displayed equations
address@hidden Equations, displayed
+For displayed equations, you must at present use @TeX{} directly
+(@pxref{Raw Formatter Commands}).
+
+
address@hidden Glyphs for Text
address@hidden Glyphs for Text
+
address@hidden@c old name
address@hidden and address@hidden another old node, now split into two
address@hidden Glyphs for text
address@hidden Textual glyphs
+
+Texinfo has support for a few additional glyphs that are commonly used
+in printed text but not available in address@hidden Of course, there are
+many thousands more. It is possible to use Unicode characters as-is
+as far as @code{makeinfo} is concerned, but @TeX{} is not so lucky.
+
address@hidden
+* @t{@@TeX @@LaTeX}:: The @TeX{} logos.
+* @t{@@copyright}:: The copyright symbol (c in a circle).
+* @t{@@registeredsymbol}:: The registered symbol (R in a circle).
+* @t{@@dots}:: How to insert ellipses: @dots{} and
@enddots{}
+* @t{@@bullet}:: How to insert a bullet: @bullet{}
+* @t{@@euro}:: How to insert the euro currency symbol.
+* @t{@@pounds}:: How to insert the pounds currency symbol.
+* @t{@@textdegree}:: How to insert the degrees symbol.
+* @t{@@minus}:: How to insert a minus sign.
+* @t{@@geq @@leq}:: How to insert greater/less-than-or-equal
signs.
address@hidden menu
+
+
address@hidden @t{@@TeX @@LaTeX}
address@hidden @code{@@address@hidden@} (@TeX{}) and @code{@@address@hidden@}
(@LaTeX{})
+
address@hidden@c old name
address@hidden TeX
address@hidden LaTeX
address@hidden Logos, @TeX{}
address@hidden @TeX{} logo
address@hidden @LaTeX{} logo
+
+Use the @code{@@address@hidden@}} command to generate address@hidden'. In a
printed
+manual, this is a special logo that is different from three ordinary
+letters. In Info, it just looks like @samp{TeX}.
+
+Similarly, use the @code{@@address@hidden@}} command to generate
address@hidden',
+which is even more special in printed manuals (and different from the
+incorrect @code{La@@address@hidden@}}. In Info, the result is just
address@hidden (@LaTeX{} is another macro package built on top of
address@hidden, 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
+use both uppercase and lowercase letters.
+
+
address@hidden @t{@@copyright}
address@hidden @code{@@address@hidden@}} (@copyright{})
+
address@hidden address@hidden old name
address@hidden copyright
address@hidden Copyright symbol
+
+Use the @code{@@address@hidden@}} command to generate the copyright
+symbol, address@hidden'. Where possible, this is a @samp{c} inside a
+circle; in Info, this is @samp{(C)}.
+
+Legally, it's not necessary to use the copyright symbol; the English
+word `Copyright' suffices, according to international treaty.
+
+
address@hidden @t{@@registeredsymbol}
address@hidden @code{@@address@hidden@}} (@registeredsymbol{})
+
address@hidden address@hidden old name
address@hidden registeredsymbol
address@hidden Registered symbol
+
+Use the @code{@@address@hidden@}} command to generate the
+registered symbol, address@hidden'. Where possible, this is an
address@hidden inside a circle; in Info, this is @samp{(R)}.
+
+
address@hidden @t{@@dots}
address@hidden @code{@@dots} (@dots{}) and @code{@@enddots} (@enddots{})
+
address@hidden@c old name
address@hidden dots
address@hidden enddots
address@hidden Inserting dots
address@hidden Inserting ellipsis
address@hidden Dots, inserting
address@hidden Ellipsis, inserting
+
address@hidden address@hidden old name
+
+An @dfn{ellipsis} (a sequence of dots) would be spaced wrong when
+typeset as a string of periods, so a special command is used in
+Texinfo: use the @code{@@address@hidden@}} command to generate a normal
+ellipsis, which is three dots in a row, appropriately spaced @dots{}
+like so. To emphasize: do not simply write three periods in the input
+file; that would work for the Info file output, but would produce the
+wrong amount of space between the periods in the printed manual.
+
+The @code{@@address@hidden@}} command generates an end-of-sentence
+ellipsis, which also has three dots, but with different spacing
+afterwards, @enddots{} Look closely to see the difference.
+
+Here is an ellipsis: @dots{}
+Here are three periods in a row: ...
+
+In printed (and usually HTML) output, the three periods in a row are
+much closer together than the dots in the ellipsis.
+
+
address@hidden @t{@@bullet}
address@hidden @code{@@bullet} (@bullet{})
+
address@hidden@c old name
address@hidden bullet
+
+Use the @code{@@address@hidden@}} command to generate a large round dot, or
+the closest possible thing to one. In Info, an asterisk is used.
+Here is a bullet: @bullet{}
+
+When you use @code{@@bullet} in @code{@@itemize}, you do not need to
+type the braces, because @code{@@itemize} supplies them.
+(@address@hidden@@itemize}}).
+
+
address@hidden @t{@@euro}
address@hidden @code{@@euro} (@euro{}): Euro Currency Symbol
+
address@hidden@c old name
address@hidden euro
address@hidden Euro symbol
+
+Use the @code{@@address@hidden@}} command to generate address@hidden'. Where
+possible, this is the symbol for the Euro currency. Otherwise, the
+word @samp{Euro} is used.
+
+Texinfo cannot magically synthesize support for the Euro symbol where
+the underlying system (fonts, software, whatever) does not support it.
+Therefore, you may find it preferable to use the word ``Euro''. (In
+banking contexts, the abbreviation for the Euro is EUR.)
+
address@hidden ISO 8859-15, and Euro
address@hidden Latin 9, and Euro
+In order to get the Euro symbol in encoded Info output, for example,
+it is necessary to specify @code{@@documentencoding ISO-8859-15} or
address@hidden@@documentencoding UTF-8} (@address@hidden@@documentencoding}}.)
+The Euro symbol is in ISO 8859-15 (aka address@hidden), and is
address@hidden in the more widely-used ISO 8859-1 (address@hidden).
+
address@hidden feymr10
address@hidden Euro font
+The Euro symbol does not exist in the standard @TeX{} fonts (which
+were designed before the Euro was legislated into existence).
+Therefore, @TeX{} uses an additional font, named @code{feymr10} (along
+with other variables). It is freely available, of course; you can
+download it from @url{http://www.ctan.org/tex-archive/fonts/eurosym},
+among other places. The distribution includes installation
+instructions.
+
+
address@hidden @t{@@pounds}
address@hidden @code{@@pounds} (@pounds{}): Pounds Sterling
+
address@hidden@c old name
address@hidden pounds
address@hidden Pounds symbol
+
+Use the @code{@@address@hidden@}} command to generate address@hidden'. Where
+possible, this is the symbol for the pounds sterling British currency.
+Otherwise, it is @samp{#}.
+
+
address@hidden @t{@@textdegree}
address@hidden @code{@@textdegree} (@textdegree{}): Degrees Symbol
+
address@hidden@c old name
address@hidden textdegree
address@hidden Degree symbol
+
+Use the @code{@@address@hidden@}} command to generate address@hidden'.
+Where possible, this is the normal symbol for degrees. Otherwise,
+it is an @samp{o}.
+
+
address@hidden @t{@@minus}
address@hidden @code{@@minus} (@minus{}): Inserting a Minus Sign
+
address@hidden@c old name
address@hidden minus
address@hidden Minus sign
+
address@hidden Em dash, compared to minus sign
address@hidden Hyphen, compared to minus
+Use the @code{@@address@hidden@}} command to generate a minus sign. In a
+fixed-width font, this is a single hyphen, but in a proportional font,
+the symbol is the customary length for a minus sign---a little longer
+than a hyphen, shorter than an em-dash:
+
address@hidden
address@hidden@minus{}} is a minus sign generated with
@samp{@@address@hidden@}},
+
+`-' is a hyphen generated with the character @samp{-},
+
+`---' is an em-dash for text.
address@hidden display
+
address@hidden
+In the fixed-width font used by Info, @code{@@address@hidden@}} is the same
+as a hyphen.
+
+You should not use @code{@@address@hidden@}} inside @code{@@code} or
address@hidden@@example} because the width distinction is not made in the
+fixed-width font they use.
+
+When you use @code{@@minus} to specify the mark beginning each entry
+in an itemized list, you do not need to type the braces
+(@address@hidden@@itemize}}).
+
+If you actually want to typeset some math that does a subtraction, it
+is better to use @code{@@math}. Then the regular @samp{-} character
+produces a minus sign, as in @code{@@address@hidden@}} (@pxref{Inserting
+Math}).
+
+
address@hidden @t{@@geq @@leq}
address@hidden @code{@@geq} (@geq{}) and @code{@@leq} (@leq{}): Inserting
Relations
+
address@hidden address@hidden old name
address@hidden geq
address@hidden leq
+
+Use the @code{@@address@hidden@}} and @code{@@address@hidden@}} commands to
generate
+greater-than-or-equal and less-than-equal-signs, address@hidden' and
address@hidden'. When those symbols are not available, the ASCII sequences
address@hidden>=} and @samp{<=} are output.
+
+
address@hidden Glyphs for Programming
address@hidden Glyphs for Programming
+
address@hidden Glyphs for programming
address@hidden Examples, glyphs for
address@hidden Programming, glyphs for
+
+In Texinfo, code is often illustrated in examples that are delimited
+by @code{@@example} and @code{@@end example}, or by @code{@@lisp} and
address@hidden@@end lisp}. In such examples, you can indicate the results of
+evaluation or an expansion using @address@hidden or
address@hidden@expansion{}}. Likewise, there are commands to insert glyphs to
+indicate printed output, error messages, equivalence of expressions,
+the location of point in an editor, and GUI operation sequences.
+
+The glyph-insertion commands do not need to be used within an example,
+but most often they are. All glyph-insertion commands are followed by
+empty braces.
+
address@hidden
+* Glyphs Summary::
+* @t{@@result}:: How to show the result of expression.
+* @t{@@expansion}:: How to indicate an expansion.
+* @t{@@print}:: How to indicate generated output.
+* @t{@@error}:: How to indicate an error message.
+* @t{@@equiv}:: How to indicate equivalence.
+* @t{@@point}:: How to indicate the location of point.
+* Click Sequences:: Inserting GUI usage sequences.
address@hidden menu
+
+
address@hidden Glyphs Summary
address@hidden Glyphs Summary
+
+Here is a summary of the glyph commands:
+
address@hidden @asis
address@hidden @result{}
address@hidden@@address@hidden@}} indicates the result of an expression.
+
address@hidden @expansion{}
address@hidden@@address@hidden@}} indicates the results of a macro expansion.
+
address@hidden @print{}
address@hidden@@address@hidden@}} indicates printed output.
+
address@hidden @error{}
address@hidden@@address@hidden@}} indicates the following text is an error
message.
+
address@hidden @equiv{}
address@hidden@@address@hidden@}} indicates the exact equivalence of two forms.
+
address@hidden @point{}
address@hidden@@address@hidden@}} shows the location of point.
+
address@hidden @clicksequence{A @click{} B}
address@hidden@@address@hidden @@address@hidden@} B} indicates a GUI operation
+sequence: first A, then clicking B, or choosing B from a menu, or
+otherwise selecting it.
address@hidden table
+
+
address@hidden @t{@@result}
address@hidden @code{@@address@hidden@}} (@result{}): Result of an Expression
+
address@hidden@c old name
address@hidden result
address@hidden Result of an expression
address@hidden Indicating evaluation
address@hidden Evaluation glyph
address@hidden Value of an expression, indicating
+
+Use the @code{@@address@hidden@}} command to indicate the result of
+evaluating an expression.
+
+The @code{@@address@hidden@}} command is displayed as @address@hidden,
+either a double stemmed arrow or (when that is not available) the
+ASCII sequence @samp{=>}.
+
+Thus, the following,
+
address@hidden
+(cdr '(1 2 3))
+ @result{} (2 3)
address@hidden lisp
+
address@hidden
+may be read as address@hidden(cdr '(1 2 3))} evaluates to @code{(2 3)}''.
+
+
address@hidden @t{@@expansion}
address@hidden @code{@@address@hidden@}} (@expansion{}): Indicating an Expansion
+
address@hidden@c old name
address@hidden Expansion, indicating
address@hidden Macro expansion, indicating
address@hidden expansion
+
+When an expression is a macro call, it expands into a new expression.
+You can indicate the result of the expansion with the
address@hidden@@address@hidden@}} command.
+
+The @code{@@address@hidden@}} command is displayed as
address@hidden@expansion{}}, either a long arrow with a flat base or (when
+that is not available) the ASCII sequence @samp{==>}.
+
address@hidden 700
+For example, the following
+
address@hidden
address@hidden
+@@lisp
+(third '(a b c))
+ @@address@hidden@} (car (cdr (cdr '(a b c))))
+ @@address@hidden@} c
+@@end lisp
address@hidden group
address@hidden example
+
address@hidden
+produces
+
address@hidden
address@hidden
+(third '(a b c))
+ @expansion{} (car (cdr (cdr '(a b c))))
+ @result{} c
address@hidden group
address@hidden lisp
+
address@hidden
+which may be read as:
+
address@hidden
address@hidden(third '(a b c))} expands to @code{(car (cdr (cdr '(a b c))))};
+the result of evaluating the expression is @code{c}.
address@hidden quotation
+
address@hidden
+Often, as in this case, an example looks better if the
address@hidden@@address@hidden@}} and @code{@@address@hidden@}} commands are
indented.
+
+
address@hidden @t{@@print}
address@hidden @code{@@address@hidden@}} (@print{}): Indicating Generated Output
+
address@hidden address@hidden old name
address@hidden print
address@hidden Printed output, indicating
+
+Sometimes an expression will generate output during its execution.
+You can indicate such displayed output with the @code{@@address@hidden@}}
+command.
+
+The @code{@@address@hidden@}} command is displayed as @address@hidden, either
+a horizontal dash butting against a vertical bar or (when that is not
+available) the ASCII sequence @samp{-|}.
+
+In the following example, the printed text is indicated with
address@hidden@print{}}, and the value of the expression follows on the
+last line.
+
address@hidden
address@hidden
+(progn (print 'foo) (print 'bar))
+ @print{} foo
+ @print{} bar
+ @result{} bar
address@hidden group
address@hidden lisp
+
address@hidden
+In a Texinfo source file, this example is written as follows:
+
address@hidden
address@hidden
+@@lisp
+(progn (print 'foo) (print 'bar))
+ @@address@hidden@} foo
+ @@address@hidden@} bar
+ @@address@hidden@} bar
+@@end lisp
address@hidden group
address@hidden lisp
+
+
address@hidden @t{@@error}
address@hidden @code{@@address@hidden@}} (@error{}): Indicating an Error Message
+
address@hidden address@hidden old name
address@hidden Error message, indicating
address@hidden error
+
+A piece of code may cause an error when you evaluate it. You can
+designate the error message with the @code{@@address@hidden@}} command.
+
+The @code{@@address@hidden@}} command is displayed as @address@hidden, either
+the word `error' in a box in the printed output, the word error
+followed by an arrow in other formats or (when no arrow is available)
address@hidden>}.
+
address@hidden 700
+Thus,
+
address@hidden
+@@lisp
+(+ 23 'x)
+@@address@hidden@} Wrong type argument: integer-or-marker-p, x
+@@end lisp
address@hidden example
+
address@hidden
+produces
+
address@hidden
+(+ 23 'x)
address@hidden Wrong type argument: integer-or-marker-p, x
address@hidden lisp
+
address@hidden
+This indicates that the following error message is printed
+when you evaluate the expression:
+
address@hidden
+Wrong type argument: integer-or-marker-p, x
address@hidden lisp
+
+The word @address@hidden itself is not part of the error message.
+
+
address@hidden @t{@@equiv}
address@hidden @code{@@address@hidden@}} (@equiv{}): Indicating Equivalence
+
address@hidden@c oldname
address@hidden Equivalence, indicating
address@hidden equiv
+
+Sometimes two expressions produce identical results. You can indicate
+the exact equivalence of two forms with the @code{@@address@hidden@}}
+command. The @code{@@address@hidden@}} command is displayed as
address@hidden@equiv{}}, either a standard mathematical equivalence sign
+(three parallel horizontal lines) or (when that is not available) as
+the ASCII sequence @samp{==}.
+
+Thus,
+
address@hidden
+@@lisp
+(make-sparse-keymap) @@address@hidden@} (list 'keymap)
+@@end lisp
address@hidden example
+
address@hidden
+produces
+
address@hidden
+(make-sparse-keymap) @equiv{} (list 'keymap)
address@hidden lisp
+
address@hidden
+This indicates that evaluating @code{(make-sparse-keymap)} produces
+identical results to evaluating @code{(list 'keymap)}.
+
+
address@hidden @t{@@point}
address@hidden @code{@@address@hidden@}} (@point{}): Indicating Point in a
Buffer
+
address@hidden address@hidden old name
address@hidden Point, indicating in a buffer
address@hidden point
+
+Sometimes you need to show an example of text in an Emacs buffer. In
+such examples, the convention is to include the entire contents of the
+buffer in question between two lines of dashes containing the buffer
+name.
+
+You can use the @samp{@@address@hidden@}} command to show the location of
+point in the text in the buffer. (The symbol for point, of course, is
+not part of the text in the buffer; it indicates the place
address@hidden two characters where point is located.)
+
+The @code{@@address@hidden@}} command is displayed as @address@hidden, either
+a pointed star or (when that is not available) the ASCII sequence
address@hidden
+
+The following example shows the contents of buffer @file{foo} before
+and after evaluating a Lisp command to insert the word @code{changed}.
+
address@hidden
address@hidden
+---------- Buffer: foo ----------
+This is the @point{}contents of foo.
+---------- Buffer: foo ----------
+
address@hidden group
address@hidden example
+
address@hidden
address@hidden
+(insert "changed ")
+ @result{} nil
+---------- Buffer: foo ----------
+This is the changed @point{}contents of foo.
+---------- Buffer: foo ----------
+
address@hidden group
address@hidden example
+
+In a Texinfo source file, the example is written like this:
+
address@hidden
+@@example
+---------- Buffer: foo ----------
+This is the @@address@hidden@}contents of foo.
+---------- Buffer: foo ----------
+
+(insert "changed ")
+ @@address@hidden@} nil
+---------- Buffer: foo ----------
+This is the changed @@address@hidden@}contents of foo.
+---------- Buffer: foo ----------
+@@end example
address@hidden example
+
+
address@hidden Click Sequences
address@hidden Click Sequences
+
address@hidden Click sequences
address@hidden Sequence of clicks
address@hidden GUI click sequence
+
address@hidden clicksequence
+When documenting graphical interfaces, it is necessary to describe
+sequences such as `Click on @samp{File}, then choose @samp{Open}, then
address@hidden'. Texinfo offers commands @code{@@clicksequence} and
address@hidden to represent this, typically used like this:
+
address@hidden
address@hidden @@address@hidden @@address@hidden@} address@hidden @dots{}
address@hidden example
+
address@hidden
+which produces:
+
address@hidden
address@hidden @clicksequence{File @click{} Open} @dots{}
address@hidden display
+
address@hidden click
address@hidden arrow
+The @code{@@click} command produces a right arrow by default; this
+glyph is also available independently via the command
address@hidden@@address@hidden@}}.
+
address@hidden clickstyle
+You can change the glyph produced by @code{@@click} with the command
address@hidden@@clickstyle}, which takes a command name as its single argument
+on the rest of the line, much like @code{@@itemize} and friends
+(@address@hidden@@itemize}}). The command should produce a glyph, and
+the usual empty braces @address@hidden@}} are omitted. Here's an example:
+
address@hidden
+@@clickstyle @@result
address@hidden @@address@hidden @@address@hidden@} address@hidden @dots{}
address@hidden example
+
address@hidden
+now produces:
+
address@hidden
address@hidden @result
address@hidden @clicksequence{File @click{} Open} @dots{}
address@hidden display
+
+
address@hidden Breaks
address@hidden Forcing and Preventing Breaks
+
address@hidden Forcing line and page breaks
address@hidden Making line and page breaks
address@hidden Preventing line and page breaks
address@hidden Line breaks, awkward
address@hidden Page breaks, awkward
+
+Line and page breaks can sometimes occur in the `wrong' place in one
+or another form of output. It's up to you to ensure that text looks
+right in all the output formats.
+
+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.
+
+You can use the break, break prevention, or pagination commands to fix
+problematic line and page breaks.
+
address@hidden
+* Break Commands:: Summary of break-related commands.
+* Line Breaks:: Forcing line breaks.
+* @t{@@- @@hyphenation}:: Helping @TeX{} with hyphenation points.
+* @t{@@allowcodebreaks}:: Controlling line breaks within @@code
text.
+* @t{@@w}:: Preventing unwanted line breaks in text.
+* @t{@@tie}:: Inserting an unbreakable but varying
space.
+* @t{@@sp}:: Inserting blank lines.
+* @t{@@page}:: Forcing the start of a new page.
+* @t{@@group}:: Preventing unwanted page breaks.
+* @t{@@need}:: Another way to prevent unwanted page
breaks.
address@hidden menu
+
+
address@hidden Break Commands
address@hidden Break Commands
+
+The break commands create or allow line and paragraph breaks:
+
address@hidden @code
address@hidden @@*
+Force a line break.
+
address@hidden @@sp @var{n}
+Skip @var{n} blank lines.
+
address@hidden @@-
+Insert a discretionary hyphen.
+
address@hidden @@address@hidden@var{hy-phen-a-ted address@hidden
+Define hyphen points in @var{hy-phen-a-ted words}.
address@hidden table
+
+These commands hold text together on a single line:
+
address@hidden @code
address@hidden @@address@hidden@address@hidden
+Prevent @var{text} from being split and hyphenated across two lines.
+
address@hidden @@address@hidden@}
+Insert a normal interword space at which a line break may not occur.
address@hidden table
+
+The pagination commands apply only to printed output, since other
+output formats do not have pages.
+
address@hidden @code
address@hidden @@page
+Start a new page.
+
address@hidden @@group
+Hold text together that must appear on one page.
+
address@hidden @@need @var{mils}
+Start a new page if not enough space on this one.
address@hidden table
+
+
address@hidden Line Breaks
address@hidden @code{@@*} and @code{@@/}: Generate and Allow Line Breaks
+
address@hidden * @r{(force line break)}
address@hidden / @r{(allow line break)}
address@hidden Line breaks, controlling
address@hidden Controlling line breaks
address@hidden Breaks in a line
address@hidden Force line break
address@hidden Allow line break
+
+The @code{@@*} command forces a line break in all output formats.
+The @code{@@/} command allows a line break (printed manual only).
+
+Here is an example with @code{@@*}:
+
address@hidden
+This sentence is broken @@*into two lines.
address@hidden example
+
address@hidden produces
+
address@hidden
address@hidden
+This sentence is broken
+into two lines.
address@hidden group
address@hidden example
+
+The @code{@@/} command can often be useful within urls
+(@address@hidden@@url}}), which tend to be long and are otherwise
+unbreakable. For example:
+
address@hidden
+The official Texinfo home page is on the GNU web site:
+@@address@hidden://www.gnu.org/@@/software/@@/gnu/@@/address@hidden
address@hidden example
+
address@hidden produces
+
address@hidden
+The official Texinfo home page is on the GNU web site:
address@hidden://www.gnu.org/@/software/@/gnu/@/texinfo}.
address@hidden quotation
+
address@hidden Without the @code{@@/} commands, @TeX{} would have nowhere to
+break the url. @code{@@/} has no effect in other output formats.
+
+
address@hidden @t{@@- @@hyphenation}
address@hidden @code{@@-} and @code{@@hyphenation}: Helping @TeX{} Hyphenate
+
address@hidden and address@hidden old name
address@hidden - @r{(discretionary hyphen)}
address@hidden hyphenation
address@hidden Hyphenation, helping @TeX{} do
address@hidden Fine-tuning, and hyphenation
+
+Although @TeX{}'s hyphenation algorithm is generally pretty good, it
+does miss useful hyphenation points from time to time. (Or, far more
+rarely, insert an incorrect hyphenation.) So, for documents with an
+unusual vocabulary or when fine-tuning for a printed edition, you may
+wish to help @TeX{} out. Texinfo supports two commands for this:
+
address@hidden @code
address@hidden @@-
+Insert a discretionary hyphen, i.e., a place where @TeX{} can (but does
+not have to) hyphenate. This is especially useful when you notice an
+overfull hbox is due to @TeX{} missing a hyphenation (@pxref{Overfull
+hboxes}). @TeX{} will not insert any hyphenation points itself into a
+word containing @code{@@-}.
+
address@hidden @@address@hidden@var{hy-phen-a-ted address@hidden
+Tell @TeX{} how to hyphenate @var{hy-phen-a-ted words}. As shown, you
+put a @samp{-} at each hyphenation point. For example:
address@hidden
+@@address@hidden address@hidden
address@hidden example
address@hidden @TeX{} only uses the specified hyphenation points when the
+words match exactly, so give all necessary variants, such as plurals.
address@hidden table
+
+Info, HTML, and other address@hidden output is not hyphenated, so none of
+these commands have any effect there.
+
+
address@hidden @t{@@allowcodebreaks}
address@hidden @code{@@allowcodebreaks}: Control Line Breaks in @code{@@code}
+
address@hidden@c old name
address@hidden allowcodebreaks
address@hidden Breaks, within @code{@@code}
address@hidden -, breakpoint within @code{@@code}
address@hidden Hyphen, breakpoint within @code{@@code}
address@hidden Dash, breakpoint within @code{@@code}
address@hidden _, breakpoint within @code{@@code}
address@hidden Underscore, breakpoint within @code{@@code}
+
+Ordinarily, @TeX{} considers breaking lines at @samp{-} and @samp{_}
+characters within @code{@@code} and related commands
+(@address@hidden@@code}}), more or less as if they were ``empty''
+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
+line break at the underscore in, for example, @code{SIZE_MAX}, or even
+worse, after any of the four underscores in @code{__typeof__}.
+
+So Texinfo provides this command:
+
address@hidden
+@@allowcodebreaks false
address@hidden example
+
address@hidden to prevent from breaking at @samp{-} or @samp{_} within
address@hidden@@code}. You can go back to allowing such breaks with
address@hidden@@allowcodebreaks true}. Write these commands on lines by
+themselves.
+
+These commands can be given anywhere in the document. For example,
+you may have just one problematic paragraph where you need to turn off
+the breaks, but want them in general, or vice versa.
+
+This command has no effect except in HTML and @TeX{} output.
+
+
address@hidden @t{@@w}
address@hidden @code{@@address@hidden@address@hidden: Prevent Line Breaks
+
address@hidden@c old name
address@hidden w @r{(prevent line break)}
address@hidden Line breaks, preventing
+
address@hidden@@address@hidden@address@hidden outputs @var{text}, while
prohibiting line
+breaks within @var{text}.
+
address@hidden Non-breakable space, fixed
address@hidden Unbreakable space, fixed
+Thus, you can use @code{@@w} to produce a non-breakable space, fixed at
+the width of a normal interword space:
+
address@hidden
+@@address@hidden @} @@address@hidden @} @@address@hidden @} indentation.
address@hidden example
+
address@hidden produces:
+
address@hidden
address@hidden } @w{ } @w{ } indentation.
address@hidden display
+
+The space from @code{@@address@hidden@w{ address@hidden, as well as being
non-breakable,
+also will not stretch or shrink. Sometimes that is what you want, for
+instance if you're doing manual indenting. However, usually you want
+a normal interword space that does stretch and shrink (in the printed
+output); for that, see the @code{@@tie} command in the next section.
+
address@hidden Hyphenation, preventing
+You can also use the @code{@@w} command to prevent @TeX{} from
+automatically hyphenating a long name or phrase that happens to fall
+near the end of a line. @command{makeinfo} does not ever hyphenate
+words.
+
address@hidden Keyword expansion, preventing
address@hidden Version control keywords, preventing expansion of
address@hidden $Id expansion, preventing
+You can also use @code{@@w} to avoid unwanted keyword expansion in
+source control systems. For example, to literally write @address@hidden
+in your document, use @code{@@address@hidden@}Id$}. This trick isn't effective
+in Info or plain text output, though.
+
+
address@hidden @t{@@tie}
address@hidden @code{@@address@hidden@}}: Inserting an Unbreakable Space
+
address@hidden@c old name
address@hidden tie @r{(unbreakable interword space)}
address@hidden Tied space
address@hidden Non-breakable space, variable
address@hidden Unbreakable space, variable
+
+The @code{@@address@hidden@}} command produces a normal interword space at
which
+a line break may not occur. Always write it with following (empty)
+braces, as usual for commands used within a paragraph. Here's an
+example:
+
address@hidden
+@@address@hidden@} was written by Donald E.@@address@hidden@}Knuth.
address@hidden example
+
address@hidden produces:
+
address@hidden
address@hidden was written by Donald address@hidden
address@hidden display
+
+There are two important differences between @code{@@address@hidden@}} and
address@hidden@@address@hidden@w{ address@hidden:
+
address@hidden
address@hidden
+The space produced by @code{@@address@hidden@}} will stretch and shrink
slightly
+along with the normal interword spaces in the paragraph; the space
+produced by @code{@@address@hidden@w{ address@hidden will not vary.
+
address@hidden
address@hidden@@address@hidden@}} allows hyphenation of the surrounding words,
while
address@hidden@@address@hidden@w{ address@hidden inhibits hyphenation of those
words (for @TeX{}nical
+reasons, namely that it produces an @samp{\hbox}).
+
address@hidden itemize
+
+
address@hidden @t{@@sp}
address@hidden @code{@@sp} @var{n}: Insert Blank Lines
+
address@hidden@c old name
address@hidden sp @r{(line spacing)}
address@hidden Space, inserting vertical
address@hidden Blank lines
address@hidden Line spacing
+
+A line beginning with and containing only @code{@@sp @var{n}}
+generates @var{n} blank lines of space in both the printed manual and
+the Info file. @code{@@sp} also forces a paragraph break. For
+example,
+
address@hidden
+@@sp 2
address@hidden example
+
address@hidden
+generates two blank lines.
+
+The @code{@@sp} command is most often used in the title page.
+
+
address@hidden @t{@@page}
address@hidden @code{@@page}: Start a New Page
+
address@hidden@c old name
address@hidden page
address@hidden Page breaks, forcing
+
+A line containing only @code{@@page} starts a new page in a printed
+manual. In other formats, without the concept of pages, it starts a
+new paragraph. An @code{@@page} command is often used in the
address@hidden@@titlepage} section of a Texinfo file to start the copyright
+page.
+
+
address@hidden @t{@@group}
address@hidden @code{@@group}: Prevent Page Breaks
+
address@hidden@c old name
address@hidden group
address@hidden Group (hold text together vertically)
address@hidden Holding text together vertically
address@hidden Vertically holding text together
+
+The @code{@@group} command (on a line by itself) is used inside an
address@hidden@@example} or similar construct to begin an unsplittable vertical
+group, which will appear entirely on one page in the printed output.
+The group is terminated by a line containing only @code{@@end group}.
+These two lines produce no output of their own, and in the Info file
+output they have no effect at all.
+
address@hidden Once said that these environments
address@hidden turn off vertical spacing between ``paragraphs''.
address@hidden Also, quotation used to work, but doesn't in texinfo-2.72
+Although @code{@@group} would make sense conceptually in a wide
+variety of contexts, its current implementation works reliably only
+within @code{@@example} and variants, and within @code{@@display},
address@hidden@@format}, @code{@@flushleft} and @code{@@flushright}.
address@hidden and Examples}. (What all these commands have in
+common is that each line of input produces a line of output.) In
+other contexts, @code{@@group} can cause anomalous vertical
+spacing.
+
address@hidden 750
+This formatting requirement means that you should write:
+
address@hidden
address@hidden
+@@example
+@@group
address@hidden
+@@end group
+@@end example
address@hidden group
address@hidden example
+
address@hidden
+with the @code{@@group} and @code{@@end group} commands inside the
address@hidden@@example} and @code{@@end example} commands.
+
+The @code{@@group} command is most often used to hold an example
+together on one page. In this Texinfo manual, more than 100 examples
+contain text that is enclosed between @code{@@group} and @code{@@end
+group}.
+
+If you forget to end a group, you may get strange and unfathomable
+error messages when you run @TeX{}. This is because @TeX{} keeps
+trying to put the rest of the Texinfo file onto the one page and does
+not start to generate error messages until it has processed
+considerable text. It is a good rule of thumb to look for a missing
address@hidden@@end group} if you get incomprehensible error messages in
address@hidden
+
+
address@hidden @t{@@need}
address@hidden @code{@@need @var{mils}}: Prevent Page Breaks
+
address@hidden@c old name
address@hidden need
address@hidden Need space at page bottom
address@hidden Mils, argument to @code{@@need}
+
+A line containing only @code{@@need @var{n}} starts a new page in a
+printed manual if fewer than @var{n} mils (thousandths of an inch)
+remain on the current page. Do not use braces around the argument
address@hidden The @code{@@need} command has no effect on other output
+formats since they are not paginated.
+
address@hidden 800
+This paragraph is preceded by an @code{@@need} command that tells
address@hidden to start a new page if fewer than 800 mils (eight-tenths
+inch) remain on the page. It looks like this:
+
address@hidden
address@hidden
+@@need 800
+This paragraph is preceded by @dots{}
address@hidden group
address@hidden example
+
address@hidden Orphans, preventing
+The @code{@@need} command is useful for preventing orphans: single
+lines at the bottoms of printed pages.
+
+
address@hidden Definition Commands
address@hidden Definition Commands
address@hidden Definition commands
+
+The @code{@@deffn} command and the other @dfn{definition commands}
+enable you to describe functions, variables, macros, commands, user
+options, special forms and other such artifacts in a uniform
+format.
+
+In the Info file, a definition causes the entity
+category---`Function', `Variable', or whatever---to appear at the
+beginning of the first line of the definition, followed by the
+entity's name and arguments. In the printed manual, the command
+causes @TeX{} to print the entity's name and its arguments on the left
+margin and print the category next to the right margin. In both
+output formats, the body of the definition is indented. Also, the
+name of the entity is entered into the appropriate index:
address@hidden@@deffn} enters the name into the index of functions,
address@hidden@@defvr} enters it into the index of variables, and so
+on (@pxref{Predefined Indices}).
+
+A manual need not and should not contain more than one definition for
+a given name. An appendix containing a summary should use
address@hidden@@table} rather than the definition commands.
+
address@hidden
+* Def Cmd Template:: Writing descriptions using definition commands.
+* Def Cmd Continuation Lines:: Continuing the heading over source lines.
+* Optional Arguments:: Handling optional and repeated arguments.
+* @t{@@deffnx}:: Group two or more `first' lines.
+* Def Cmds in Detail:: Reference for all the definition commands.
+* Def Cmd Conventions:: Conventions for writing definitions.
+* Sample Function Definition:: An example.
address@hidden menu
+
+
address@hidden Def Cmd Template
address@hidden The Template for a Definition
address@hidden Definition template
address@hidden Template for a definition
+
+The @code{@@deffn} command is used for definitions of entities that
+resemble functions. To write a definition using the @code{@@deffn}
+command, write the @code{@@deffn} command at the beginning of a line
+and follow it on the same line by the category of the entity, the name
+of the entity itself, and its arguments (if any). Then write the body
+of the definition on succeeding lines. (You may embed examples in the
+body.) Finally, end the definition with an @code{@@end deffn} command
+written on a line of its own.
+
+The other definition commands follow the same format: a line with the
address@hidden@@address@hidden command and whatever arguments are appropriate
for
+that command; the body of the definition; and a corresponding
address@hidden@@end} line.
+
+The template for a definition looks like this:
+
address@hidden
address@hidden
+@@deffn @var{category} @var{name} @address@hidden
address@hidden
+@@end deffn
address@hidden group
address@hidden example
+
address@hidden 700
address@hidden
+For example,
+
address@hidden
address@hidden
+@@deffn Command forward-word count
+This command moves point forward @@address@hidden@} words
+(or backward if @@address@hidden@} is negative). @dots{}
+@@end deffn
address@hidden group
address@hidden example
+
address@hidden
+produces
+
address@hidden
address@hidden Command forward-word count
+This command moves point forward @var{count} words
+(or backward if @var{count} is negative). @dots{}
address@hidden deffn
address@hidden quotation
+
+Capitalize the category name like a title. If the name of the
+category contains spaces, as in the phrase `Interactive Command',
+enclose it in braces. For example:
+
address@hidden
address@hidden
+@@deffn @{Interactive address@hidden isearch-forward
address@hidden
+@@end deffn
address@hidden group
address@hidden example
+
address@hidden
+Otherwise, the second word will be mistaken for the name of the
+entity. As a general rule, when any of the arguments in the heading
+line @emph{except} the last one are more than one word, you need to
+enclose them in braces. This may also be necessary if the text
+contains commands, for example, @address@hidden@@'address@hidden if you are
+writing in Spanish.
+
+Some of the definition commands are more general than others. The
address@hidden@@deffn} command, for example, is the general definition command
+for functions and the like---for entities that may take arguments.
+When you use this command, you specify the category to which the
+entity belongs. Three predefined, specialized variations
+(@code{@@defun}, @code{@@defmac}, and @code{@@defspec}) specify the
+category for you: ``Function'', ``Macro'', and ``Special Form''
+respectively. (In Lisp, a special form is an entity much like a
+function.) Similarly, the general @code{@@defvr} command is
+accompanied by several specialized variations for describing
+particular kinds of variables.
+
address@hidden Function Definition}, for a detailed example of a
+function definition, including the use of @code{@@example} inside the
+definition.
+
+
address@hidden Def Cmd Continuation Lines
address@hidden Definition Command Continuation Lines
address@hidden Continuation lines in definition commands
address@hidden Definition command headings, continuing
address@hidden @samp{@@} as continuation in definition commands
+
+The heading line of a definition command can get very long.
+Therefore, Texinfo has a special syntax allowing them to be continued
+over multiple lines of the source file: a lone @samp{@@} at the end of
+each line to be continued. Here's an example:
+
address@hidden
+@@defun fn-name @@
+ arg1 arg2 arg3
+This is the basic continued defun.
+@@end defun
address@hidden example
+
address@hidden produces:
+
address@hidden fn-name arg1 arg2 arg3
+This is the basic continued defun.
address@hidden defun
+
address@hidden
+As you can see, the continued lines are combined, as if they had been
+typed on one source line.
+
+Although this example only shows a one-line continuation,
+continuations may extend over any number of lines, in the same way;
+put an @code{@@} at the end of each line to be continued.
+
address@hidden Whitespace, collapsed around continuations
address@hidden Collapsing whitespace around continuations
+In general, any number of spaces or tabs before the @code{@@}
+continuation character are collapsed into a single space. There is one
+exception: the Texinfo processors will not fully collapse whitespace
+around a continuation inside braces. For example:
+
address@hidden
+@@deffn @{Category @@
+ address@hidden @dots{}
address@hidden example
+
address@hidden The output (not shown) has excess space between `Category'
+and `Name'. To avoid this, elide the unwanted whitespace in your
+input, or put the continuation @code{@@} outside braces.
+
address@hidden@@} does not function as a continuation character in @emph{any}
+other context. Ordinarily, @samp{@@} followed by a whitespace
+character (space, tab, newline) produces a normal interword space
+(@pxref{Multiple Spaces}).
+
+
address@hidden Optional Arguments
address@hidden Optional and Repeated Arguments
address@hidden Optional and repeated arguments
address@hidden Repeated and optional arguments
address@hidden Arguments, repeated and optional
address@hidden Syntax, optional & repeated arguments
address@hidden Meta-syntactic chars for arguments
+
address@hidden This is consistent with the Emacs Lisp Reference Manual.
+Some entities take optional or repeated arguments, conventionally
+specified by using square brackets and ellipses: an argument enclosed
+within square brackets is optional, and an argument followed by an
+ellipsis is optional and may be repeated more than once.
+
+Thus, address@hidden means that @var{optional-arg} is optional
+and @address@hidden@dots{}} stands for zero or more
+arguments. Parentheses are used when several arguments are grouped
+into additional levels of list structure in Lisp.
+
+Here is the @code{@@defspec} line of an example of an imaginary
+(complicated) special form:
+
address@hidden
address@hidden foobar (@var{var} address@hidden @var{to} address@hidden)
@address@hidden
address@hidden defspec
address@hidden tex
address@hidden \vskip \parskip
address@hidden end tex
address@hidden quotation
+
address@hidden
+In this example, the arguments @var{from} and @var{to} are optional,
+but must both be present or both absent. If they are present,
address@hidden may optionally be specified as well. These arguments are
+grouped with the argument @var{var} into a list, to distinguish them
+from @var{body}, which includes all remaining elements of the
+form.
+
+In a Texinfo source file, this @code{@@defspec} line is written like
+this, including a continuation to avoid a long source line.
+
address@hidden
address@hidden
+@@defspec foobar (@@address@hidden@} [@@address@hidden@} @@address@hidden@} @@
+ [@@address@hidden@}]]) @@address@hidden@}@@address@hidden@}
address@hidden group
address@hidden example
+
address@hidden
+The function is listed in the Command and Variable Index under
address@hidden
+
+
address@hidden @t{@@deffnx}
address@hidden @code{@@deffnx}, et al.: Two or More `First' Lines
+
address@hidden@c old node
address@hidden deffnx
address@hidden Two `First' Lines for @code{@@deffn}
address@hidden Grouping two definitions together
address@hidden Definitions grouped together
+
+To create two or more `first' or header lines for a definition, follow
+the first @code{@@deffn} line by a line beginning with
address@hidden@@deffnx}. The @code{@@deffnx} command works exactly like
address@hidden@@deffn} except that it does not generate extra vertical white
+space between it and the preceding line.
+
address@hidden 1000
+For example,
+
address@hidden
address@hidden
+@@deffn @{Interactive address@hidden isearch-forward
+@@deffnx @{Interactive address@hidden isearch-backward
+These two search commands are similar except @dots{}
+@@end deffn
address@hidden group
address@hidden example
+
address@hidden
+produces
+
address@hidden {Interactive Command} isearch-forward
address@hidden {Interactive Command} isearch-backward
+These two search commands are similar except @dots{}
address@hidden deffn
+
+Each definition command has an `x' form: @code{@@defunx},
address@hidden@@defvrx}, @code{@@deftypefunx}, etc.
+
+The `x' forms work similarly to @code{@@itemx}
+(@address@hidden@@itemx}}).
+
+
address@hidden Def Cmds in Detail
address@hidden The Definition Commands
+
+Texinfo provides more than a dozen definition commands, all of which
+are described in this section.
+
+The definition commands automatically enter the name of the entity in
+the appropriate index: for example, @code{@@deffn}, @code{@@defun},
+and @code{@@defmac} enter function names in the index of functions;
address@hidden@@defvr} and @code{@@defvar} enter variable names in the index
+of variables.
+
+Although the examples that follow mostly illustrate Lisp, the commands
+can be used for other programming languages.
+
address@hidden
+* Functions Commands:: Commands for functions and similar entities.
+* Variables Commands:: Commands for variables and similar entities.
+* Typed Functions:: Commands for functions in typed languages.
+* Typed Variables:: Commands for variables in typed languages.
+* Data Types:: The definition command for data types.
+* Abstract Objects:: Commands for object-oriented programming.
address@hidden menu
+
address@hidden Functions Commands
address@hidden Functions and Similar Entities
+
+This section describes the commands for describing functions and similar
+entities:
+
address@hidden @code
address@hidden deffn
address@hidden @@deffn @var{category} @var{name} @address@hidden
+The @code{@@deffn} command is the general definition command for
+functions, interactive commands, and similar entities that may take
+arguments. You must choose a term to describe the category of entity
+being defined; for example, ``Function'' could be used if the entity is
+a function. The @code{@@deffn} command is written at the beginning of a
+line and is followed on the same line by the category of entity being
+described, the name of this particular entity, and its arguments, if
+any. Terminate the definition with @code{@@end deffn} on a line of its
+own.
+
address@hidden 750
+For example, here is a definition:
+
address@hidden
address@hidden
+@@deffn Command forward-char nchars
+Move point forward @@address@hidden@} characters.
+@@end deffn
address@hidden group
address@hidden example
+
address@hidden
+This shows a rather terse definition for a ``command'' named
address@hidden with one argument, @var{nchars}.
+
address@hidden@@deffn} prints argument names such as @var{nchars} in slanted
+type in the printed output, because we think of these names as
+metasyntactic variables---they stand for the actual argument values.
+Within the text of the description, however, write an argument name
+explicitly with @code{@@var} to refer to the value of the argument.
+In the example above, we used @samp{@@address@hidden@}} in this way.
+
+In the extremely unusual case when an argument name contains
address@hidden, or another character sequence which is treated specially
+(@pxref{Conventions}), use @code{@@code} around the special
+characters. This avoids the conversion to typographic en-dashes and
+em-dashes.
address@hidden @var also works; that's what we used to recommend.
+
+The template for @code{@@deffn} is:
+
address@hidden
address@hidden
+@@deffn @var{category} @var{name} @address@hidden
address@hidden
+@@end deffn
address@hidden group
address@hidden example
+
address@hidden defun
address@hidden @@defun @var{name} @address@hidden
+The @code{@@defun} command is the definition command for functions.
address@hidden@@defun} is equivalent to @samp{@@deffn Function @dots{}}.
+Terminate the definition with @code{@@end defun} on a line of its own.
+Thus, the template is:
+
address@hidden
address@hidden
+@@defun @var{function-name} @address@hidden
address@hidden
+@@end defun
address@hidden group
address@hidden example
+
address@hidden defmac
address@hidden @@defmac @var{name} @address@hidden
+The @code{@@defmac} command is the definition command for macros.
address@hidden@@defmac} is equivalent to @samp{@@deffn Macro @dots{}} and
+works like @code{@@defun}.
+
address@hidden defspec
address@hidden @@defspec @var{name} @address@hidden
+The @code{@@defspec} command is the definition command for special
+forms. (In Lisp, a special form is an entity much like a function;
address@hidden Forms,,, elisp, GNU Emacs Lisp Reference Manual}.)
address@hidden@@defspec} is equivalent to @samp{@@deffn @{Special address@hidden
address@hidden and works like @code{@@defun}.
address@hidden table
+
+All these commands create entries in the index of functions.
+
+
address@hidden Variables Commands
address@hidden Variables and Similar Entities
+
+Here are the commands for defining variables and similar
+entities:
+
address@hidden @code
address@hidden defvr
address@hidden @@defvr @var{category} @var{name}
+The @code{@@defvr} command is a general definition command for
+something like a variable---an entity that records a value. You must
+choose a term to describe the category of entity being defined; for
+example, ``Variable'' could be used if the entity is a variable.
+Write the @code{@@defvr} command at the beginning of a line and
+follow it on the same line by the category of the entity and the
+name of the entity.
+
+We recommend capitalizing the category name like a title. If the name
+of the category contains spaces, as in the name ``User Option'',
+enclose it in braces. Otherwise, the second word will be mistaken for
+the name of the entity. For example,
+
address@hidden
address@hidden
+@@defvr @{User address@hidden fill-column
+This buffer-local variable specifies
+the maximum width of filled lines.
address@hidden
+@@end defvr
address@hidden group
address@hidden example
+
+Terminate the definition with @code{@@end defvr} on a line of its
+own.
+
+The template is:
+
address@hidden
address@hidden
+@@defvr @var{category} @var{name}
address@hidden
+@@end defvr
address@hidden group
address@hidden example
+
address@hidden@@defvr} creates an entry in the index of variables for
@var{name}.
+
address@hidden defvar
address@hidden @@defvar @var{name}
+The @code{@@defvar} command is the definition command for variables.
address@hidden@@defvar} is equivalent to @samp{@@defvr Variable
address@hidden
+
address@hidden 750
+For example:
+
address@hidden
address@hidden
+@@defvar kill-ring
address@hidden
+@@end defvar
address@hidden group
address@hidden example
+
+The template is:
+
address@hidden
address@hidden
+@@defvar @var{name}
address@hidden
+@@end defvar
address@hidden group
address@hidden example
+
address@hidden@@defvar} creates an entry in the index of variables for
address@hidden
+
address@hidden defopt
address@hidden @@defopt @var{name}
address@hidden User options, marking
+The @code{@@defopt} command is the definition command for @dfn{user
+options}, i.e., variables intended for users to change according to
+taste; Emacs has many such (@pxref{Variables,,, emacs, The GNU Emacs
+Manual}). @code{@@defopt} is equivalent to @samp{@@defvr @{User
address@hidden @dots{}} and works like @code{@@defvar}. It creates an entry
+in the index of variables.
address@hidden table
+
+
address@hidden Typed Functions
address@hidden Functions in Typed Languages
+
address@hidden Typed functions
address@hidden Functions, in typed languages
+
+The @code{@@deftypefn} command and its variations are for describing
+functions in languages in which you must declare types of variables
+and functions, such as C and C++.
+
address@hidden @code
address@hidden deftypefn
address@hidden @@deftypefn @var{category} @var{data-type} @var{name}
@address@hidden
+The @code{@@deftypefn} command is the general definition command for
+functions and similar entities that may take arguments and that are
+typed. The @code{@@deftypefn} command is written at the beginning of
+a line and is followed on the same line by the category of entity
+being described, the type of the returned value, the name of this
+particular entity, and its arguments, if any.
+
address@hidden 800
address@hidden
+For example,
+
address@hidden
address@hidden
+@@deftypefn @{Library address@hidden int foobar @@
+ (int @@address@hidden@}, float @@address@hidden@})
address@hidden
+@@end deftypefn
address@hidden group
address@hidden example
+
+produces:
+
address@hidden
address@hidden {Library Function} int foobar (int @var{foo}, float @var{bar})
address@hidden
address@hidden deftypefn
address@hidden quotation
+
+This means that @code{foobar} is a ``library function'' that returns an
address@hidden, and its arguments are @var{foo} (an @code{int}) and
address@hidden (a @code{float}).
+
+Since in typed languages, the actual names of the arguments are
+typically scattered among data type names and keywords, Texinfo cannot
+find them without help. You can either (a)@tie{}write everything as
+straight text, and it will be printed in slanted type; (b)@tie{}use
address@hidden@@var} for the variable names, which will uppercase the variable
+names in Info and use the slanted typewriter font in printed output;
+(c)@tie{}use @code{@@var} for the variable names and @code{@@code} for
+the type names and keywords, which will be dutifully obeyed.
+
+The template for @code{@@deftypefn} is:
+
address@hidden
address@hidden
+@@deftypefn @var{category} @var{data-type} @var{name} @var{arguments} @dots{}
address@hidden
+@@end deftypefn
address@hidden group
address@hidden example
+
address@hidden
+Note that if the @var{category} or @var{data type} is more than one
+word then it must be enclosed in braces to make it a single argument.
+
+If you are describing a procedure in a language that has packages,
+such as Ada, you might consider using @code{@@deftypefn} in a manner
+somewhat contrary to the convention described in the preceding
+paragraphs. For example:
+
address@hidden
address@hidden
+@@deftypefn stacks private push @@
+ (@@address@hidden@}:in out stack; @@
+ @@address@hidden@}:in integer)
address@hidden
+@@end deftypefn
address@hidden group
address@hidden example
+
address@hidden
+(In these examples the @code{@@deftypefn} arguments are shown using
+continuations (@pxref{Def Cmd Continuation Lines}), but could be on a
+single line.)
+
+In this instance, the procedure is classified as belonging to the
+package @code{stacks} rather than classified as a `procedure' and its
+data type is described as @code{private}. (The name of the procedure
+is @code{push}, and its arguments are @var{s} and @var{n}.)
+
address@hidden@@deftypefn} creates an entry in the index of functions for
address@hidden
+
address@hidden @@deftypefun @var{data-type} @var{name} @address@hidden
address@hidden deftypefun
+The @code{@@deftypefun} command is the specialized definition command
+for functions in typed languages. The command is equivalent to
address@hidden@@deftypefn Function @dots{}}. The template is:
+
address@hidden
address@hidden
+@@deftypefun @var{type} @var{name} @address@hidden
address@hidden
+@@end deftypefun
address@hidden group
address@hidden example
+
address@hidden@@deftypefun} creates an entry in the index of functions for
address@hidden
+
address@hidden table
+
address@hidden Return type, own line for
address@hidden deftypefnnewline
+Ordinarily, the return type is printed on the same line as the
+function name and arguments, as shown above. In source code, GNU
+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
+section, and the analogous commands for object-oriented languages,
+namely @code{@@deftypeop} and @code{@@deftypemethod}
+(@pxref{Object-Oriented Methods}).
+
+Specifying @code{@@deftypefnnewline off} reverts to the default.
+
+
address@hidden Typed Variables
address@hidden Variables in Typed Languages
+
address@hidden Typed variables
address@hidden Variables, in typed languages
+
+Variables in typed languages are handled in a manner similar to
+functions in typed languages. @xref{Typed Functions}. The general
+definition command @code{@@deftypevr} corresponds to
address@hidden@@deftypefn} and the specialized definition command
address@hidden@@deftypevar} corresponds to @code{@@deftypefun}.
+
address@hidden @code
address@hidden deftypevr
address@hidden @@deftypevr @var{category} @var{data-type} @var{name}
+The @code{@@deftypevr} command is the general definition command for
+something like a variable in a typed language---an entity that records
+a value. You must choose a term to describe the category of the
+entity being defined; for example, ``Variable'' could be used if the
+entity is a variable.
+
+The @code{@@deftypevr} command is written at the beginning of a line
+and is followed on the same line by the category of the entity
+being described, the data type, and the name of this particular
+entity.
+
address@hidden 800
address@hidden
+For example:
+
address@hidden
address@hidden
+@@deftypevr @{Global address@hidden int enable
address@hidden
+@@end deftypevr
address@hidden group
address@hidden example
+
address@hidden
+produces the following:
+
address@hidden
address@hidden {Global Flag} int enable
address@hidden
address@hidden deftypevr
address@hidden quotation
+
address@hidden 800
+The template is:
+
address@hidden
+@@deftypevr @var{category} @var{data-type} @var{name}
address@hidden
+@@end deftypevr
address@hidden example
+
address@hidden deftypevar
address@hidden @@deftypevar @var{data-type} @var{name}
+The @code{@@deftypevar} command is the specialized definition command
+for variables in typed languages. @code{@@deftypevar} is equivalent
+to @samp{@@deftypevr Variable @dots{}}. The template is:
+
address@hidden
address@hidden
+@@deftypevar @var{data-type} @var{name}
address@hidden
+@@end deftypevar
address@hidden group
address@hidden example
address@hidden table
+
+These commands create entries in the index of variables.
+
+
address@hidden Data Types
address@hidden Data Types
+
+Here is the command for data types:
+
address@hidden @code
address@hidden deftp
address@hidden @@deftp @var{category} @var{name} @address@hidden
+The @code{@@deftp} command is the generic definition command for data
+types. The command is written at the beginning of a line and is
+followed on the same line by the category, by the name of the type
+(which is a word like @code{int} or @code{float}), and then by names of
+attributes of objects of that type. Thus, you could use this command
+for describing @code{int} or @code{float}, in which case you could use
address@hidden type} as the category. (A data type is a category of
+certain objects for purposes of deciding which operations can be
+performed on them.)
+
+In Lisp, for example, @dfn{pair} names a particular data
+type, and an object of that type has two slots called the
address@hidden and the @sc{cdr}. Here is how you would write the first line
+of a definition of @code{pair}.
+
address@hidden
address@hidden
+@@deftp @{Data address@hidden pair car cdr
address@hidden
+@@end deftp
address@hidden group
address@hidden example
+
address@hidden 950
+The template is:
+
address@hidden
address@hidden
+@@deftp @var{category} @var{name-of-type} @address@hidden
address@hidden
+@@end deftp
address@hidden group
address@hidden example
+
address@hidden@@deftp} creates an entry in the index of data types.
address@hidden table
+
+
address@hidden Abstract Objects
address@hidden Object-Oriented Programming
+
address@hidden Object-oriented programming
+
+Here are the commands for formatting descriptions about abstract
+objects, such as are used in object-oriented programming. A class is
+a defined type of abstract object. An instance of a class is a
+particular object that has the type of the class. An instance
+variable is a variable that belongs to the class but for which each
+instance has its own value.
+
address@hidden
+* Variables: Object-Oriented Variables.
+* Methods: Object-Oriented Methods.
address@hidden menu
+
+
address@hidden Object-Oriented Variables
address@hidden Object-Oriented Variables
+
address@hidden Variables, object-oriented
+
+These commands allow you to define different sorts of variables in
+object-oriented programming languages.
+
address@hidden @code
address@hidden @@defcv @var{category} @var{class} @var{name}
address@hidden defcv
+The @code{@@defcv} command is the general definition command for
+variables associated with classes in object-oriented programming. The
address@hidden@@defcv} command is followed by three arguments: the category of
+thing being defined, the class to which it belongs, and its
+name. For instance:
+
address@hidden
address@hidden
+@@defcv @{Class address@hidden Window border-pattern
address@hidden
+@@end defcv
address@hidden group
address@hidden example
+
address@hidden produces:
address@hidden {Class Option} Window border-pattern
address@hidden
address@hidden defcv
+
address@hidden@@defcv} creates an entry in the index of variables.
+
address@hidden @@deftypecv @var{category} @var{class} @var{data-type} @var{name}
address@hidden deftypecv
+The @code{@@deftypecv} command is the definition command for typed
+class variables in object-oriented programming. It is analogous to
address@hidden@@defcv} with the addition of the @var{data-type} parameter to
+specify the type of the instance variable. Ordinarily, the data type
+is a programming language construct that should be marked with
address@hidden@@code}. For instance:
+
address@hidden
address@hidden
+@@deftypecv @{Class address@hidden Window @@address@hidden@} border-pattern
address@hidden
+@@end deftypecv
address@hidden group
address@hidden example
+
address@hidden produces:
+
address@hidden {Class Option} Window @code{int} border-pattern
address@hidden
address@hidden deftypecv
+
address@hidden@@deftypecv} creates an entry in the index of variables.
+
address@hidden @@defivar @var{class} @var{name}
address@hidden defivar
+The @code{@@defivar} command is the definition command for instance
+variables in object-oriented programming. @code{@@defivar} is
+equivalent to @samp{@@defcv @{Instance address@hidden @dots{}}. For
+instance:
+
address@hidden
address@hidden
+@@defivar Window border-pattern
address@hidden
+@@end defivar
address@hidden group
address@hidden example
+
address@hidden produces:
+
address@hidden Window border-pattern
address@hidden
address@hidden defivar
+
address@hidden@@defivar} creates an entry in the index of variables.
+
address@hidden @@deftypeivar @var{class} @var{data-type} @var{name}
address@hidden deftypeivar
+The @code{@@deftypeivar} command is the definition command for typed
+instance variables in object-oriented programming. It is analogous to
address@hidden@@defivar} with the addition of the @var{data-type} parameter to
+specify the type of the instance variable. Ordinarily, the data type
+is a programming language construct that should be marked with
address@hidden@@code}. For instance:
+
address@hidden
address@hidden
+@@deftypeivar Window @@address@hidden@} border-pattern
address@hidden
+@@end deftypeivar
address@hidden group
address@hidden example
+
address@hidden produces:
+
address@hidden Window @code{int} border-pattern
address@hidden
address@hidden deftypeivar
+
address@hidden@@deftypeivar} creates an entry in the index of variables.
+
address@hidden table
+
+
address@hidden Object-Oriented Methods
address@hidden Object-Oriented Methods
+
address@hidden Methods, object-oriented
+
+These commands allow you to define different sorts of function-like
+entities resembling methods in object-oriented programming languages.
+These entities take arguments, as functions do, but are associated with
+particular classes of objects.
+
address@hidden @code
+
address@hidden defop
address@hidden @@defop @var{category} @var{class} @var{name} @address@hidden
+The @code{@@defop} command is the general definition command for these
+method-like entities.
+
+For example, some systems have constructs called @dfn{wrappers} that
+are associated with classes as methods are, but that act more like
+macros than like functions. You could use @code{@@defop Wrapper} to
+describe one of these.
+
+Sometimes it is useful to distinguish methods and @dfn{operations}.
+You can think of an operation as the specification for a method.
+Thus, a window system might specify that all window classes have a
+method named @code{expose}; we would say that this window system
+defines an @code{expose} operation on windows in general. Typically,
+the operation has a name and also specifies the pattern of arguments;
+all methods that implement the operation must accept the same
+arguments, since applications that use the operation do so without
+knowing which method will implement it.
+
+Often it makes more sense to document operations than methods. For
+example, window application developers need to know about the
address@hidden operation, but need not be concerned with whether a
+given class of windows has its own method to implement this operation.
+To describe this operation, you would write:
+
address@hidden
+@@defop Operation windows expose
address@hidden example
+
+The @code{@@defop} command is written at the beginning of a line and
+is followed on the same line by the overall name of the category of
+operation, the name of the class of the operation, the name of the
+operation, and its arguments, if any.
+
+The template is:
address@hidden
address@hidden
+@@defop @var{category} @var{class} @var{name} @address@hidden
address@hidden
+@@end defop
address@hidden group
address@hidden example
+
address@hidden@@defop} creates an entry, such as address@hidden on
address@hidden', in the index of functions.
+
address@hidden deftypeop
address@hidden @@deftypeop @var{category} @var{class} @var{data-type}
@var{name} @address@hidden
+The @code{@@deftypeop} command is the definition command for typed
+operations in object-oriented programming. It is similar to
address@hidden@@defop} with the addition of the @var{data-type} parameter to
+specify the return type of the method. @code{@@deftypeop} creates an
+entry in the index of functions.
+
address@hidden @@defmethod @var{class} @var{name} @address@hidden
address@hidden defmethod
+The @code{@@defmethod} command is the definition command for methods
+in object-oriented programming. A method is a kind of function that
+implements an operation for a particular class of objects and its
+subclasses.
address@hidden
address@hidden ADR: Who cares?!?
address@hidden KB: Oh, I don't know, I think this info is crucial!
+In the Lisp Machine, methods actually were functions, but
+they were usually defined with @code{defmethod}.
address@hidden ignore
+
address@hidden@@defmethod} is equivalent to @samp{@@defop Method @dots{}}.
+The command is written at the beginning of a line and is followed by
+the name of the class of the method, the name of the method, and its
+arguments, if any.
+
address@hidden
+For example:
address@hidden
address@hidden
+@@defmethod @code{bar-class} bar-method argument
address@hidden
+@@end defmethod
address@hidden group
address@hidden example
+
address@hidden
+illustrates the definition for a method called @code{bar-method} of
+the class @code{bar-class}. The method takes an argument.
+
address@hidden@@defmethod} creates an entry in the index of functions.
+
address@hidden @@deftypemethod @var{class} @var{data-type} @var{name}
@address@hidden
address@hidden defmethod
+The @code{@@deftypemethod} command is the definition command for methods
+in object-oriented typed languages, such as C++ and Java. It is similar
+to the @code{@@defmethod} command with the addition of the
address@hidden parameter to specify the return type of the method.
address@hidden@@deftypemethod} creates an entry in the index of functions.
+
address@hidden table
+
+The typed commands are affected by the @code{@@deftypefnnewline}
+option (@pxref{Typed Functions,, Functions in Typed Languages}).
+
+
address@hidden Def Cmd Conventions
address@hidden Conventions for Writing Definitions
address@hidden Definition conventions
address@hidden Conventions for writing definitions
+
+When you write a definition using @code{@@deffn}, @code{@@defun}, or
+one of the other definition commands, please take care to use
+arguments that indicate the meaning, as with the @var{count} argument
+to the @code{forward-word} function. Also, if the name of an argument
+contains the name of a type, such as @var{integer}, take care that the
+argument actually is of that type.
+
+
address@hidden Sample Function Definition
address@hidden A Sample Function Definition
address@hidden Function definitions
address@hidden Command definitions
address@hidden Macro definitions, programming-language
address@hidden Sample function definition
+
+A function definition uses the @code{@@defun} and @code{@@end defun}
+commands. The name of the function follows immediately after the
address@hidden@@defun} command and it is followed, on the same line, by the
+parameter list.
+
+Here is a definition from @ref{Calling Functions,,, elisp, The GNU Emacs
+Lisp Reference Manual}.
+
address@hidden
address@hidden apply function &rest arguments
address@hidden calls @var{function} with @var{arguments}, just
+like @code{funcall} but with one difference: the last of
address@hidden is a list of arguments to give to
address@hidden, rather than a single argument. We also say
+that this list is @dfn{appended} to the other arguments.
+
address@hidden returns the result of calling @var{function}.
+As with @code{funcall}, @var{function} must either be a Lisp
+function or a primitive function; special forms and macros
+do not make sense in @code{apply}.
+
address@hidden
+(setq f 'list)
+ @result{} list
+(apply f 'x 'y 'z)
address@hidden Wrong type argument: listp, z
+(apply '+ 1 2 '(3 4))
+ @result{} 10
+(apply '+ '(1 2 3 4))
+ @result{} 10
+
+(apply 'append '((a b c) nil (x y z) nil))
+ @result{} (a b c x y z)
address@hidden example
+
+An interesting example of using @code{apply} is found in the description
+of @code{mapcar}.
address@hidden defun
address@hidden quotation
+
+In the Texinfo source file, this example looks like this:
+
address@hidden
address@hidden
+@@defun apply function &rest arguments
+@@address@hidden@} calls @@address@hidden@} with
+@@address@hidden@}, just like @@address@hidden@} but with one
+difference: the last of @@address@hidden@} is a list of
+arguments to give to @@address@hidden@}, rather than a single
+argument. We also say that this list is @@address@hidden@}
+to the other arguments.
address@hidden group
+
address@hidden
+@@address@hidden@} returns the result of calling
+@@address@hidden@}. As with @@address@hidden@},
+@@address@hidden@} must either be a Lisp function or a
+primitive function; special forms and macros do not make
+sense in @@address@hidden@}.
address@hidden group
+
address@hidden
+@@example
+(setq f 'list)
+ @@address@hidden@} list
+(apply f 'x 'y 'z)
+@@address@hidden@} Wrong type argument: listp, z
+(apply '+ 1 2 '(3 4))
+ @@address@hidden@} 10
+(apply '+ '(1 2 3 4))
+ @@address@hidden@} 10
+
+(apply 'append '((a b c) nil (x y z) nil))
+ @@address@hidden@} (a b c x y z)
+@@end example
address@hidden group
+
address@hidden
+An interesting example of using @@address@hidden@} is found
+in the description of @@address@hidden@}.
+@@end defun
address@hidden group
address@hidden example
+
address@hidden
+In this manual, this function is listed in the Command and Variable
+Index under @code{apply}.
+
+Ordinary variables and user options are described using a format like
+that for functions except that variables do not take arguments.
+
+
address@hidden Internationalization
address@hidden Internationalization
+
address@hidden Internationalization
+Texinfo has some support for writing in languages other than English,
+although this area still needs considerable work. (If you are
+yourself helping to translate the fixed strings written to documents,
address@hidden of Document Strings}.)
+
+For a list of the various accented and special characters Texinfo
+supports, see @ref{Inserting Accents}.
+
address@hidden
+* @t{@@documentlanguage}:: Declaring the current language.
+* @t{@@documentencoding}:: Declaring the input encoding.
address@hidden menu
+
+
address@hidden @t{@@documentlanguage}
address@hidden @code{@@documentlanguage @address@hidden: Set the Document
Language
address@hidden
+
address@hidden documentlanguage
address@hidden Language, declaring
address@hidden Locale, declaring
address@hidden Document language, declaring
+
+The @code{@@documentlanguage} command declares the current document
+locale. Write it on a line by itself, near the beginning of the file,
+but after @code{@@setfilename} (@address@hidden@@setfilename}}):
+
address@hidden
+@@documentlanguage @address@hidden
address@hidden example
+
+Include a two-letter address@hidden language code (@var{ll}) following
+the command name, optionally followed by an underscore and two-letter
address@hidden two-letter country code (@var{cc}). If you have a
+multilingual document, the intent is to be able to use this command
+multiple times, to declare each language change. If the command is
+not used at all, the default is @code{en_US} for US English.
+
+As with GNU Gettext (@pxref{Top,,, gettext, Gettext}), if the country
+code is omitted, the main dialect is assumed where possible. For
+example, @code{de} is equivalent to @code{de_DE} (German as spoken in
+Germany).
+
address@hidden Document strings, translation of
+For Info and other online output, this command changes the translation
+of various @dfn{document strings} such as ``see'' in cross references
+(@pxref{Cross References}), ``Function' in defuns (@pxref{Definition
+Commands}), and so on. Some strings, such as ``Node:'', ``Next:'',
+``Menu:'', etc., are keywords in Info output, so are not translated
+there; they are translated in other output formats.
+
address@hidden @address@hidden
+For @TeX{}, this command causes a file @address@hidden to
+be read (if it exists). If @code{@@documentlanguage} argument
+contains the optional @address@hidden suffix, this is tried first.
+For example, with @code{@@documentlanguage de_DE}, @TeX{} first looks
+for @file{txi-de_DE.tex}, then @file{txi-de.tex}.
+
+Such a @file{txi-*} file is intended to redefine the various English
+words used in @TeX{} output, such as `Chapter', `See', and so on. We
+are aware that individual words like these cannot always be translated
+in isolation, and that a very different strategy would be required for
+ideographic (among other) scripts. Help in improving Texinfo's
+language support is welcome.
+
address@hidden Hyphenation patterns, language-dependent
address@hidden@@documentlanguage} also changes @TeX{}'s current hyphenation
+patterns, if the @TeX{} program being run has the necessary support
+included. This will generally not be the case for @command{tex}
+itself, but will usually be the case for up-to-date distributions of
+the extended @TeX{} programs @command{etex} (DVI output) and
address@hidden (PDF output). @command{texi2dvi} will use the
+extended @TeX{}s if they are available (@pxref{Format with
address@hidden).
+
+In September 2006, the W3C Internationalization Activity released a
+new recommendation for specifying languages:
address@hidden://www.rfc-editor.org/rfc/bcp/bcp47.txt}. When Gettext
+supports this new scheme, Texinfo will too.
+
address@hidden ISO 639-2 language codes
address@hidden ISO 3166 country codes
address@hidden Language codes
address@hidden Country codes
+Since the lists of language codes and country codes are updated
+relatively frequently, we don't attempt to list them here. The valid
+language codes are on the official home page for address@hidden,
address@hidden://www.loc.gov/standards/iso639-2/}. The country codes and
+the official web site for address@hidden can be found via
address@hidden://en.wikipedia.org/wiki/ISO_3166}.
+
+
address@hidden @t{@@documentencoding}
address@hidden @code{@@documentencoding @var{enc}}: Set Input Encoding
+
address@hidden@c old name
address@hidden documentencoding
address@hidden Encoding, declaring
address@hidden Input encoding, declaring
address@hidden Character set, declaring
address@hidden Document input encoding
+
+The @code{@@documentencoding} command declares the input document
+encoding. Write it on a line by itself, with a valid encoding
+specification following, near the beginning of the file but after
address@hidden@@setfilename} (@address@hidden@@setfilename}}):
+
address@hidden
+@@documentencoding @var{enc}
address@hidden example
+
+At present, Texinfo supports only these encodings:
+
address@hidden @code
address@hidden US-ASCII
+This has no particular effect, but it's included for completeness.
+
address@hidden UTF-8
+The vast global character encoding, expressed in 8-bit bytes.
+
address@hidden ISO-8859-2
address@hidden ISO-8859-1
address@hidden ISO-8859-15
+These specify the standard encodings for Western European (the first
+two) and Eastern European languages (the third), respectively. ISO
+8859-15 replaces some little-used characters from 8859-1 (e.g.,
+precomposed fractions) with more commonly needed ones, such as the
+Euro symbol (@euro{}).
+
+A full description of the encodings is beyond our scope here;
+one useful reference is @uref{http://czyborra.com/charsets/iso8859.html}.
+
address@hidden koi8-r
+This is the commonly used encoding for the Russian language.
+
address@hidden koi8-u
+This is the commonly used encoding for the Ukrainian language.
+
address@hidden table
+
+Specifying an encoding @var{enc} has the following effects:
+
address@hidden Local Variables section, for encoding
address@hidden Info output, and encoding
+In Info output, a so-called `Local Variables' section (@pxref{File
+Variables,,,emacs, The GNU Emacs Manual}) is output including
address@hidden This allows Info readers to set the encoding
+appropriately. It looks like this:
+
address@hidden
+Local Variables:
+coding: @var{enc}
+End:
address@hidden example
+
+Also, in Info and plain text output, unless the option
address@hidden is given to @command{makeinfo}, accent
+constructs and special characters, such as @code{@@'e}, are output as
+the actual 8-bit or UTF-8 character in the given encoding where
+possible.
+
address@hidden HTML output, and encodings
address@hidden @code{http-equiv}, and charset specification
address@hidden @code{<meta>} HTML tag, and charset specification
+In HTML output, a @samp{<meta>} tag is output, in the @samp{<head>}
+section of the HTML, that specifies @var{enc}. Web servers and
+browsers cooperate to use this information so the correct encoding is
+used to display the page, if supported by the system. That looks like
+this:
+
address@hidden
+<meta http-equiv="Content-Type" content="text/html;
+ address@hidden">
address@hidden example
+
+In XML and Docbook output, UTF-8 is always used for the output file,
+since all XML processors are supposed to be able to process that
+encoding.
+
address@hidden Computer Modern fonts
+In @TeX{} output, the characters which are supported in the standard
+Computer Modern fonts are output accordingly. (For example, this
+means using constructed accents rather than precomposed glyphs.)
+Using a missing character generates a warning message, as does
+specifying an unimplemented encoding.
+
+Although modern @TeX{} systems support nearly every script in use in
+the world, this wide-ranging support is not available in
address@hidden, and it's not feasible to duplicate or incorporate
+all that effort. Our plan to support other scripts is to create a
address@hidden back-end to @command{texi2any}, where the support is already
+present.
+
+
address@hidden Conditionals
address@hidden Conditionally Visible Text
address@hidden Conditionally visible text
address@hidden Text, conditionally visible
address@hidden Visibility of conditional text
address@hidden If text conditionally visible
+
+The @dfn{conditional commands} allow you to use different text for
+different output formats, or for general conditions that you define.
+For example, you can use them to specify different text for the
+printed manual and the Info output.
+
+The conditional commands comprise the following categories.
+
address@hidden @bullet
address@hidden
+Commands specific to an output format (Info, @TeX{}, HTML, @dots{}).
+
address@hidden
+Commands specific to any output format @emph{excluding} a given
+one (e.g., not Info, not @TeX{}, @dots{}).
+
address@hidden
+`Raw' formatter text for any output format, passed straight
+through with minimal (but not zero) interpretation of @@-commands.
+
address@hidden
+Format-independent variable substitutions, and testing if a variable
+is set or clear.
+
address@hidden itemize
+
address@hidden
+* Conditional Commands:: Text for a given format.
+* Conditional Not Commands:: Text for any format other than a given one.
+* Raw Formatter Commands:: Using raw formatter commands.
+* Inline Conditionals:: Brace-delimited conditional text.
+* @t{@@set @@clear @@value}:: Variable tests and substitutions.
+* Testing for Texinfo Commands:: Testing if a Texinfo command is available.
+* Conditional Nesting:: Using conditionals inside conditionals.
address@hidden menu
+
+
address@hidden Conditional Commands
address@hidden Conditional Commands
+
+Texinfo has an @code{@@address@hidden environment for each output
+format, to allow conditional inclusion of text for a particular output
+format.
+
address@hidden ifinfo
address@hidden@@ifinfo} begins segments of text that should be ignored by
address@hidden when it typesets the printed manual, and by @command{makeinfo}
+when not producing Info output. The segment of text appears only in
+the Info file and, for historical compatibility, the plain text
+output.
+
address@hidden ifdocbook
address@hidden ifhtml
address@hidden ifplaintext
address@hidden iftex
address@hidden ifxml
+The environments for the other formats are analogous, but without the
+special historical case:
+
address@hidden @code
address@hidden @@ifdocbook @dots{} @@end ifdocbook
+Text to appear only in the Docbook output.
+
address@hidden @@ifhtml @dots{} @@end ifhtml
+Text to appear only in the HTML output.
+
address@hidden @@ifplaintext @dots{} @@end ifplaintext
+Text to appear only in the plain text output.
+
address@hidden @@iftex @dots{} @@end iftex
+Text to appear only in the printed manual.
+
address@hidden @@ifxml @dots{} @@end ifxml
+Text to appear only in the XML output.
address@hidden table
+
+The @code{@@address@hidden and @code{@@end address@hidden commands must appear
+on lines by themselves in your source file. The newlines following
+the commands are (more or less) treated as whitespace, so that the
+conditional text is flowed normally into a surrounding paragraph.
+
+The @code{@@address@hidden constructs are intended to conditionalize
+normal Texinfo source; @pxref{Raw Formatter Commands}, for using
+underlying format commands directly.
+
+Here is an example showing all these conditionals:
+
address@hidden
+@@iftex
+This text will appear only in the printed manual.
+@@end iftex
+@@ifinfo
+However, this text will appear only in Info and plain text.
+@@end ifinfo
+@@ifhtml
+And this text will only appear in HTML.
+@@end ifhtml
+@@ifplaintext
+Whereas this text will only appear in plain text.
+@@end ifplaintext
+@@ifxml
+Notwithstanding that this will only appear in address@hidden
+@@end ifxml
+@@ifdocbook
+Nevertheless, this will only appear in Docbook.
+@@end ifdocbook
address@hidden example
+
address@hidden
+The preceding example produces the following line:
+
address@hidden
+This text will appear only in the printed manual.
address@hidden iftex
address@hidden
+However, this text will appear only in Info and plain text.
address@hidden ifinfo
address@hidden
+And this text will only appear in HTML.
address@hidden ifhtml
address@hidden
+Whereas this text will only appear in plain text.
address@hidden ifplaintext
address@hidden
+Notwithstanding that this will only appear in address@hidden
address@hidden ifxml
address@hidden
+Nevertheless, this will only appear in Docbook.
address@hidden ifdocbook
+
address@hidden
+Notice that you only see one of the input lines, depending on which
+version of the manual you are reading.
+
address@hidden errormsg
+In complex documents, you may want Texinfo to issue an error message
+in some conditionals that should not ever be processed. The
address@hidden@@address@hidden@address@hidden command will do this; it takes one
+argument, the text of the error message, which is expanded more or
+less as if it were Info text.
+
+We mention @code{@@address@hidden@}} here even though it is not strictly
+related to conditionals, since in practice it is most likely to be
+useful in that context. Technically, it can be used anywhere.
address@hidden Macro Processors}, for a caveat regarding the line
+numbers which @code{@@errormsg} emits in @TeX{}.
+
+
address@hidden Conditional Not Commands
address@hidden Conditional Not Commands
address@hidden ifnotdocbook
address@hidden ifnothtml
address@hidden ifnotinfo
address@hidden ifnotplaintext
address@hidden ifnottex
address@hidden ifnotxml
+
+You can specify text to be included in any output format @emph{other}
+than a given one with the @code{@@address@hidden environments:
+
address@hidden
+@@ifnotdocbook @dots{} @@end ifnotdocbook
+@@ifnothtml @dots{} @@end ifnothtml
+@@ifnotinfo @dots{} @@end ifnotinfo
+@@ifnotplaintext @dots{} @@end ifnotplaintext
+@@ifnottex @dots{} @@end ifnottex
+@@ifnotxml @dots{} @@end ifnotxml
address@hidden example
+
address@hidden
+The @code{@@address@hidden command and the @code{@@end} command must
+appear on lines by themselves in your actual source file.
+
+If the output file is being made in the given format, the
+region is @emph{ignored}. Otherwise, it is included.
+
+There is one exception (for historical compatibility):
address@hidden@@ifnotinfo} text is omitted for both Info and plain text
+output, not just Info. To specify text which appears only in Info and
+not in plain text, use @code{@@ifnotplaintext}, like this:
+
address@hidden
+@@ifinfo
+@@ifnotplaintext
+This will be in Info, but not plain text.
+@@end ifnotplaintext
+@@end ifinfo
address@hidden example
+
+The regions delimited by these commands are ordinary Texinfo source as
+with @code{@@iftex}, not raw formatter source as with @code{@@tex}
+(@pxref{Raw Formatter Commands}).
+
+
address@hidden Raw Formatter Commands
address@hidden Raw Formatter Commands
address@hidden Raw formatter commands
+
address@hidden @TeX{} commands, using ordinary
address@hidden Ordinary @TeX{} commands, using
address@hidden Commands using raw @TeX{}
address@hidden Plain @TeX{}
+
+The @code{@@address@hidden conditionals just described must be used only
+with normal Texinfo source. For instance, most features of plain
address@hidden will not work within @code{@@iftex}. The purpose of
address@hidden@@address@hidden is to provide conditional processing for Texinfo
+source, not provide access to underlying formatting features. For
+that, Texinfo provides so-called @dfn{raw formatter commands}. They
+should only be used when truly required (most documents do not need
+them).
+
address@hidden tex
address@hidden Category codes, of plain @TeX{}
+The first raw formatter command is @code{@@tex}. You can enter plain
address@hidden completely, and use @samp{\} in the @TeX{} commands, by
+delineating a region with the @code{@@tex} and @code{@@end tex}
+commands. All plain @TeX{} commands and category codes are restored
+within an @code{@@tex} region. The sole exception is that the
address@hidden@@} 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.
+
address@hidden \gdef @r{within @code{@@tex}}
address@hidden \globaldefs @r{within @code{@@tex}}
+In complex cases, you may wish to define new @TeX{} macros within
address@hidden@@tex}. You must use @code{\gdef} to do this, not @code{\def},
+because @code{@@tex} regions are processed in a @TeX{} group. If you
+need to make several definitions, you may wish to set
address@hidden (its value will be restored to zero as usual when
+the group ends at @code{@@end tex}, so it won't cause problems with
+the rest of the document).
+
address@hidden Equation, displayed, in plain @TeX{}
address@hidden Displayed equation, in plain @TeX{}
+As an example, here is a displayed equation written in plain @TeX{}:
+
address@hidden
+@@tex
+$$ \chi^2 = address@hidden@}^N
+ \left (y_i - (a + b x_i)
+ \over \sigma_i\right)^2 $$
+@@end tex
address@hidden example
+
address@hidden
+The output of this example will appear only in a printed manual. If
+you are reading this in a format not generated by @TeX{}, you will not
+see the equation that appears in the printed manual.
+
address@hidden
+$$ \chi^2 = \sum_{i=1}^N
+ \left(y_i - (a + b x_i)
+ \over \sigma_i\right)^2 $$
address@hidden tex
+
address@hidden HTML, including raw
address@hidden ifhtml
address@hidden html
+Analogously, you can use @code{@@ifhtml @dots{} @@end ifhtml} to
+delimit Texinfo source to be included in HTML output only, and
address@hidden@@html @dots{} @@end html} for a region of raw HTML.
+
address@hidden XML, including raw
address@hidden ifxml
address@hidden xml
+Likewise, you can use @code{@@ifxml @dots{} @@end ifxml} to delimit
+Texinfo source to be included in XML output only, and @code{@@xml
address@hidden @@end xml} for a region of raw address@hidden Regions of raw
text in
+other formats will also be present in the XML output, but with
+protection of XML characters and within corresponding elements. For
+example, the raw HTML text:
+
address@hidden
address@hidden
+@@html
+<br />
+@@end html
address@hidden group
address@hidden example
+
address@hidden
+will be included in the XML output as:
+
address@hidden
address@hidden
+<html>
+<br />
+</html>
address@hidden group
address@hidden example
+
address@hidden Docbook, including raw
address@hidden ifdocbook
address@hidden docbook
+Again likewise, you can use @code{@@ifdocbook @dots{} @@end ifdocbook}
+to delimit Texinfo source to be included in Docbook output only, and
address@hidden@@docbook @dots{} @@end docbook} for a region of raw Docbook.
+
+The behavior of newlines in raw regions is unspecified.
+
+In all cases, in raw processing, @code{@@} retains the same meaning as
+in the remainder of the document. Thus, the Texinfo processors
+recognize and even execute, to some extent, the contents of the raw
+regions, regardless of the final output format. Therefore, specifying
+changes that globally affect the document inside a raw region leads to
+unpredictable and generally undesirable behavior. For example,
+giving the @code{@@kbdinputstyle} command inside a raw region.
+
+The remedy is simple: don't do that. Use the raw formatter commands
+for their intended purpose, of providing material directly in the
+underlying format. When you simply want to give different Texinfo
+specifications for different output formats, use the
address@hidden@@address@hidden conditionals and stay in Texinfo syntax.
+
+
+
address@hidden Inline Conditionals
address@hidden Inline Conditionals: @code{@@inline}, @code{@@inlineraw}
address@hidden inlinefmt
address@hidden inlineraw
address@hidden Inline conditionals
address@hidden Conditional commands, inline
address@hidden Brace-delimited conditional text
address@hidden Newlines, avoiding in conditionals
address@hidden Whitespace, controlling in conditionals
+
+Texinfo provides two conditional commands with arguments given within
+braces:
+
address@hidden @code
address@hidden @@address@hidden@var{format}, @address@hidden
+Process the Texinfo @var{text} if @var{format} output is being
+generated.
+
address@hidden @@address@hidden@var{format}, @address@hidden
+Similar, but for raw @var{text} (@pxref{Raw Formatter Commands}).
address@hidden table
+
+For example,
+
address@hidden
+@@address@hidden, @@address@hidden address@hidden@}
address@hidden example
+
address@hidden is nearly equivalent to
+
address@hidden
+@@ifhtml
+@@address@hidden address@hidden
+@@end ifhtml
address@hidden example
+
address@hidden except that no whitespace is added, as happens in the latter
+(environment) case.
+
+In these commands, whitespace is ignored after the comma separating
+the two arguments, as usual, but is @emph{not} ignored at the end of
address@hidden
+
+In the case of @code{@@inlineraw}, to insert a literal at sign, left
+brace, or right brace, you must use the alphabetic commands
address@hidden@@address@hidden@}} (@pxref{Inserting an Atsign}), and
address@hidden@@address@hidden@}} or @code{@@address@hidden@}} (@pxref{Inserting
+Braces}), or the parsing will become confused. (By the way, it is not
+necessary to use @code{@@address@hidden@}}, since these commands always have
+exactly two arguments, so a @samp{,} cannot be mistaken for an
+argument separator.)
+
+
address@hidden @t{@@set @@clear @@value}
address@hidden @code{@@set}, @code{@@clear}, and @code{@@value}
+
address@hidden clear address@hidden old name
+You can direct the Texinfo formatting commands to format or ignore parts
+of a Texinfo file with the @code{@@set}, @code{@@clear}, @code{@@ifset},
+and @code{@@ifclear} commands.
+
+Here are brief descriptions of these commands, see the following
+sections for more details:
+
address@hidden @code
address@hidden @@set @var{flag} address@hidden
+Set the variable @var{flag}, to the optional @var{value} if specified.
+
address@hidden @@clear @var{flag}
+Undefine the variable @var{flag}, whether or not it was previously defined.
+
address@hidden @@ifset @var{flag}
+If @var{flag} is set, text through the next @code{@@end ifset} command
+is formatted. If @var{flag} is clear, text through the following
address@hidden@@end ifset} command is ignored.
+
address@hidden @@ifclear @var{flag}
+If @var{flag} is set, text through the next @code{@@end ifclear} command
+is ignored. If @var{flag} is clear, text through the following
address@hidden@@end ifclear} command is formatted.
address@hidden table
+
address@hidden
+* @t{@@set @@value}:: Expand a flag variable to a string.
+* @t{@@ifset @@ifclear}:: Format a region if a flag is set.
+* @t{@@value} Example:: An easy way to update edition information.
address@hidden menu
+
+
address@hidden @t{@@set @@value}
address@hidden @code{@@set} and @code{@@value}
+
address@hidden address@hidden old name
address@hidden set
address@hidden value
address@hidden clear
+
+You use the @code{@@set} command to specify a value for a flag, which
+is later expanded by the @code{@@value} command.
+
+A @dfn{flag} (aka @dfn{variable}) name is an identifier starting with
+an alphanumeric, @samp{-}, or @samp{_}. Subsequent characters, if
+any, may not be whitespace, @samp{@@}, braces, angle brackets, or any
+of @samp{~`^+|}; other characters, such as @samp{%}, may work.
+However, it is best to use only letters and numerals in a flag name,
+not @samp{-} or @samp{_} or others---they will work in some contexts,
+but not all, due to limitations in @TeX{}.
+
+The value is the remainder of the input line, and can contain anything.
+However, unlike most other commands which take the rest of the line as
+a value, @code{@@set} need not appear at the beginning of a line.
+
+Write the @code{@@set} command like this:
+
address@hidden
+@@set foo This is a string.
address@hidden example
+
address@hidden
+This sets the value of the flag @code{foo} to ``This is a string.''.
+
+The Texinfo formatters then replace an @code{@@address@hidden@address@hidden
+command with the string to which @var{flag} is set. Thus, when
address@hidden is set as shown above, the Texinfo formatters convert this:
+
address@hidden
address@hidden
+@@address@hidden@}
address@hidden @r{to this:}
+This is a string.
address@hidden group
address@hidden example
+
+You can write an @code{@@value} command within a paragraph; but you
+must write an @code{@@set} command on a line of its own.
+
+If you write the @code{@@set} command like this:
+
address@hidden
+@@set foo
address@hidden example
+
address@hidden
+without specifying a string, the value of @code{foo} is the empty string.
+
+If you clear a previously set flag with @code{@@clear @var{flag}}, a
+subsequent @code{@@address@hidden@}} command will report an error.
+
+For example, if you set @code{foo} as follows:
+
address@hidden
+@@set howmuch very, very, very
address@hidden example
+
address@hidden
+then the formatters transform
+
address@hidden
address@hidden
+It is a @@address@hidden@} wet day.
address@hidden @r{into}
+It is a very, very, very wet day.
address@hidden group
address@hidden example
+
+If you write
+
address@hidden
+@@clear howmuch
address@hidden example
+
address@hidden
+then the formatters transform
+
address@hidden
address@hidden
+It is a @@address@hidden@} wet day.
address@hidden @r{into}
+It is a @{No value for "howmuch"@} wet day.
address@hidden group
address@hidden example
+
address@hidden@@value} cannot be reliably used as the argument to an accent
+command (@pxref{Inserting Accents}). For example, this fails:
+
address@hidden
+@@set myletter a
+@@'@@address@hidden@} @c fails!
address@hidden example
+
+
address@hidden @t{@@ifset @@ifclear}
address@hidden @code{@@ifset} and @code{@@ifclear}
+
address@hidden address@hidden old name
address@hidden ifset
+
+When a @var{flag} is set, the Texinfo formatting commands format text
+between subsequent pairs of @code{@@ifset @var{flag}} and @code{@@end
+ifset} commands. When the @var{flag} is cleared, the Texinfo formatting
+commands do @emph{not} format the text. @code{@@ifclear} operates
+analogously.
+
+Write the conditionally formatted text between @code{@@ifset @var{flag}}
+and @code{@@end ifset} commands, like this:
+
address@hidden
address@hidden
+@@ifset @var{flag}
address@hidden
+@@end ifset
address@hidden group
address@hidden example
+
+For example, you can create one document that has two variants, such as
+a manual for a `large' and `small' model:
+
address@hidden Shrubbery
address@hidden
+You can use this machine to dig up shrubs
+without hurting them.
+
+@@set large
+
+@@ifset large
+It can also dig up fully grown trees.
+@@end ifset
+
+Remember to replant promptly @dots{}
address@hidden example
+
address@hidden
+In the example, the formatting commands will format the text between
address@hidden@@ifset large} and @code{@@end ifset} because the @code{large}
+flag is set.
+
+When @var{flag} is cleared, the Texinfo formatting commands do
address@hidden format the text between @code{@@ifset @var{flag}} and
address@hidden@@end ifset}; that text is ignored and does not appear in either
+printed or Info output.
+
+For example, if you clear the flag of the preceding example by writing
+an @code{@@clear large} command after the @code{@@set large} command
+(but before the conditional text), then the Texinfo formatting commands
+ignore the text between the @code{@@ifset large} and @code{@@end ifset}
+commands. In the formatted output, that text does not appear; in both
+printed and Info output, you see only the lines that say, ``You can use
+this machine to dig up shrubs without hurting them. Remember to replant
+promptly @dots{}''.
+
address@hidden ifclear
+If a flag is cleared with an @code{@@clear @var{flag}} command, then
+the formatting commands format text between subsequent pairs of
address@hidden@@ifclear} and @code{@@end ifclear} commands. But if the flag
+is set with @code{@@set @var{flag}}, then the formatting commands do
address@hidden format text between an @code{@@ifclear} and an @code{@@end
+ifclear} command; rather, they ignore that text. An @code{@@ifclear}
+command looks like this:
+
address@hidden
+@@ifclear @var{flag}
address@hidden example
+
+
address@hidden @t{@@value} Example
address@hidden @code{@@value} Example
+
address@hidden address@hidden old name
+
+You can use the @code{@@value} command to minimize the number of
+places you need to change when you record an update to a manual.
address@hidden Sample Texts}, for the full text of an example of using this
+to work with Automake distributions.
+
+This example is adapted from @ref{Top,,, make, The GNU Make Manual}.
+
address@hidden
address@hidden
+Set the flags:
+
address@hidden
address@hidden
+@@set EDITION 0.35 Beta
+@@set VERSION 3.63 Beta
+@@set UPDATED 14 August 1992
+@@set UPDATE-MONTH August 1992
address@hidden group
address@hidden example
+
address@hidden
+Write text for the @code{@@copying} section (@address@hidden@@copying}}):
+
address@hidden
address@hidden
+@@copying
+This is Edition @@address@hidden@},
+last updated @@address@hidden@},
+of @@address@hidden GNU Make address@hidden,
+for @@address@hidden@}, version @@address@hidden@}.
+
+Copyright @dots{}
+
+Permission is granted @dots{}
+@@end copying
address@hidden group
address@hidden example
+
address@hidden
+Write text for the title page, for people reading the printed manual:
+
address@hidden
address@hidden
+@@titlepage
+@@title GNU Make
+@@subtitle A Program for Directing Recompilation
+@@subtitle Edition @@address@hidden@}, @dots{}
+@@subtitle @@address@hidden@}
+@@page
+@@insertcopying
address@hidden
+@@end titlepage
address@hidden group
address@hidden example
+
address@hidden
+(On a printed cover, a date listing the month and the year looks less
+fussy than a date listing the day as well as the month and year.)
+
address@hidden
+Write text for the Top node, for people reading the Info file:
+
address@hidden
address@hidden
+@@ifnottex
+@@node Top
+@@top Make
+
+@@insertcopying
address@hidden
+@@end ifnottex
address@hidden group
address@hidden example
+
+After you format the manual, the @code{@@value} constructs have been
+expanded, so the output contains text like this:
+
address@hidden
address@hidden
+This is Edition 0.35 Beta, last updated 14 August 1992,
+of `The GNU Make Manual', for `make', Version 3.63 Beta.
address@hidden group
address@hidden example
address@hidden enumerate
+
+When you update the manual, you change only the values of the flags; you
+do not need to edit the three sections.
+
+
address@hidden Testing for Texinfo Commands
address@hidden Testing for Texinfo Commands: @code{@@ifcommanddefined},
@code{@@ifcommandnotdefined}
+
address@hidden Testing for Texinfo commands
address@hidden Checking for Texinfo commands
address@hidden Texinfo commands, testing for
address@hidden Commands, testing for Texinfo
address@hidden Versions of Texinfo, adapting to
address@hidden Features of Texinfo, adapting to
+
+Occasionally, you may want to arrange for your manual to test if a
+given Texinfo command is available and (presumably) do some sort of
+fallback formatting if not. There are conditionals
address@hidden@@ifcommanddefined} and @code{@@ifcommandnotdefined} to do this.
+For example:
+
address@hidden
+@@ifcommanddefined node
+Good, @@address@hidden@@@@address@hidden is defined.
+@@end ifcommanddefined
address@hidden example
+
address@hidden will output the expected `Good, @samp{@@node} is defined.'.
+
+This conditional will also consider true any new commands defined by
+the document via @code{@@macro}, @code{@@alias},
address@hidden@@definfoenclose}, and
@code{@@address@hidden(address@hidden)}index}
+(@pxref{Defining New Texinfo Commands}). Caveat: the @TeX{}
+implementation reports internal @TeX{} commands, in addition to all
+the Texinfo commands, as being ``defined''; the @code{makeinfo}
+implementation is reliable in this regard, however.
+
address@hidden @file{NEWS} file for Texinfo
+You can check the @file{NEWS} file in the Texinfo source distribution
+and linked from the Texinfo home page
+(@url{http://www.gnu.org/software/texinfo}) to see when a particular
+command was added.
+
+These command-checking conditionals themselves were added in
address@hidden, released in 2013---decades after Texinfo's
+inception. In order to test if they themselves are available,
+the predefined flag @code{txicommandconditionals} can be tested, like
+this:
+
address@hidden
+@@ifset txicommandconditionals
+@@ifcommandnotdefined foobarnode
+(Good, @samp{@@foobarnode} is not defined.)
+@@end ifcommandnotdefined
+@@end ifset
address@hidden example
+
+Since flags (see the previous section) were added early in the
+existence of Texinfo, there is no problem with assuming they are
+available.
+
+We recommend avoiding these tests whenever possible---which is usually
+the case. For many software packages, it is reasonable for all
+developers to have a given version of Texinfo (or newer) installed,
+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.
+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
+general, to avoid unnecessary dependencies between packages
+(@pxref{Releases,,, standard, GNU Coding Standards}).
+
+
address@hidden Conditional Nesting
address@hidden Conditional Nesting
address@hidden Conditionals, nested
address@hidden Nesting conditionals
+
+Conditionals can be nested; however, the details are a little tricky.
+The difficulty comes with failing conditionals, such as
address@hidden@@ifhtml} when HTML is not being produced, where the included
+text is to be ignored. However, it is not to be @emph{completely}
+ignored, since it is useful to have one @code{@@ifset} inside another,
+for example---that is a way to include text only if two conditions are
+met. Here's an example:
+
address@hidden
+@@ifset somevar
+@@ifset anothervar
+Both somevar and anothervar are set.
+@@end ifset
+@@ifclear anothervar
+Somevar is set, anothervar is not.
+@@end ifclear
+@@end ifset
address@hidden example
+
+Technically, Texinfo requires that for a failing conditional, the
+ignored text must be properly nested with respect to that failing
+conditional. Unfortunately, it's not always feasible to check that
address@hidden conditionals are properly nested, because then the
+processors could have to fully interpret the ignored text, which
+defeats the purpose of the command. Here's an example illustrating
+these rules:
+
address@hidden
+@@ifset a
+@@ifset b
+@@ifclear ok - ok, ignored
+@@end junky - ok, ignored
+@@end ifset
+@@c WRONG - missing @@end ifset.
address@hidden example
+
+Finally, as mentioned above, all conditional commands must be on lines
+by themselves, with no text (even spaces) before or after. Otherwise,
+the processors cannot reliably determine which commands to consider
+for nesting purposes.
+
+
address@hidden Defining New Texinfo Commands
address@hidden Defining New Texinfo Commands
+
address@hidden Macros
address@hidden Defining new Texinfo commands
address@hidden New Texinfo commands, defining
address@hidden Texinfo commands, defining new
address@hidden User-defined Texinfo commands
+
+Texinfo provides several ways to define new commands:
+
address@hidden @bullet
address@hidden
+A Texinfo @dfn{macro} allows you to define a new Texinfo command as any
+sequence of text and/or existing commands (including other macros). The
+macro can have any number of @dfn{parameters}---text you supply each
+time you use the macro.
+
+Incidentally, these macros have nothing to do with the @code{@@defmac}
+command, which is for documenting macros in the subject area of the
+manual (@pxref{Def Cmd Template}).
+
address@hidden
address@hidden@@alias} is a convenient way to define a new name for an existing
+command.
+
address@hidden
address@hidden@@definfoenclose} allows you to define new commands with
+customized output for all address@hidden output formats.
+
address@hidden itemize
+
+Most generally of all, not just for defining new commands, it is
+possible to invoke an external macro processor and have Texinfo
+recognize so-called @code{#line} directives for error reporting.
+
+If you want to do simple text substitution, @code{@@set} and
address@hidden@@value} is the simplest approach (@address@hidden@@set @@clear
+@@value}}).
+
address@hidden
+* Defining Macros:: Defining and undefining new commands.
+* Invoking Macros:: Using a macro, once you've defined it.
+* Macro Details:: Limitations of Texinfo macros.
+* @t{@@alias}:: Command aliases.
+* @t{@@definfoenclose}:: Customized highlighting.
+* External Macro Processors:: @code{#line} directives.
address@hidden menu
+
+
address@hidden Defining Macros
address@hidden Defining Macros
address@hidden Defining macros
address@hidden Macro definitions, Texinfo
+
address@hidden macro
+You use the Texinfo @code{@@macro} command to define a macro, like this:
+
address@hidden
+@@macro @address@hidden@var{param1}, @var{param2}, @address@hidden
address@hidden @dots{} address@hidden @dots{}
+@@end macro
address@hidden example
+
+The @dfn{parameters} @var{param1}, @var{param2}, @dots{} correspond to
+arguments supplied when the macro is subsequently used in the document
+(described in the next section).
+
address@hidden Macro names, valid characters in
address@hidden Names of macros, valid characters of
+For a macro to work consistently with @TeX{}, @var{macroname} must
+consist entirely of letters: no digits, hyphens, underscores, or other
+special characters. So, we recommend using only letters. However,
address@hidden will accept anything consisting of alphanumerics,
+and (except as the first character) @samp{-}. The @samp{_} character
+is excluded so that macros can be called inside @code{@@math} without
+a following space (@pxref{Inserting Math}).
+
+If a macro needs no parameters, you can define it either with an empty
+list (@samp{@@macro foo @address@hidden) or with no braces at all
(@samp{@@macro
+foo}).
+
address@hidden Body of a macro
+The definition or @dfn{body} of the macro can contain most Texinfo
+commands, including macro invocations. However, a macro definition
+that defines another macro does not work in @TeX{} due to limitations
+in the design of @code{@@macro}.
+
address@hidden Parameters to macros
+In the macro body, instances of a parameter name surrounded by
+backslashes, as in @address@hidden in the example above, are
+replaced by the corresponding argument from the macro invocation. You
+can use parameter names any number of times in the body, including zero.
+
address@hidden Backslash in macros
+To get a single @samp{\} in the macro expansion, use @samp{\\}. Any
+other use of @samp{\} in the body yields a warning.
+
address@hidden Spaces in macros
address@hidden Whitespace in macros
+The newline characters after the @code{@@macro} line and before the
address@hidden@@end macro} line are ignored, that is, not included in the
+macro body. All other whitespace is treated according to the usual
+Texinfo rules. However, there are still undesirable and unpredictable
+interactions between newlines, macros, and commands which are
+line-delimited, as warned about below (@pxref{Macro Details}).
+
address@hidden Recursive macro invocations
address@hidden rmacro
+To allow a macro to be used recursively, that is, in an argument to a
+call to itself, you must define it with @samp{@@rmacro}, like this:
+
address@hidden
+@@rmacro rmac @address@hidden
+a\arg\b
+@@end rmacro
address@hidden
+@@address@hidden@@address@hidden@address@hidden
address@hidden example
+
+This produces the output `a1atextb2b'. With @samp{@@macro} instead of
address@hidden@@rmacro}, an error message is given.
+
address@hidden unmacro
address@hidden Macros, undefining
address@hidden Undefining macros
+You can undefine a macro @var{foo} with @code{@@unmacro @var{foo}}.
+It is not an error to undefine a macro that is already undefined.
+For example:
+
address@hidden
+@@unmacro foo
address@hidden example
+
+
address@hidden Invoking Macros
address@hidden Invoking Macros
+
address@hidden Invoking macros
address@hidden Expanding macros
address@hidden Running macros
address@hidden Macro invocation
+
+After a macro is defined (see the previous section), you can
address@hidden (use) it in your document like this:
+
address@hidden
+@@@var{macroname} @address@hidden, @var{arg2}, @address@hidden
address@hidden example
+
address@hidden and the result will be more or less as if you typed the body of
address@hidden at that spot. For example:
+
address@hidden
+@@macro foo @{p, address@hidden
+Together: \p\ & \q\.
+@@end macro
+@@address@hidden, address@hidden
address@hidden example
+
address@hidden produces:
+
address@hidden
+Together: a & b.
address@hidden display
+
address@hidden Backslash, and macros
+Thus, the arguments and parameters are separated by commas and
+delimited by braces; any whitespace after (but not before) a comma is
+ignored. The braces are required in the invocation even when the
+macro takes no arguments, consistent with other Texinfo commands. For
+example:
+
address@hidden
+@@macro argless @address@hidden
+No arguments here.
+@@end macro
+@@address@hidden@}
address@hidden example
+
address@hidden produces:
+
address@hidden
+No arguments here.
address@hidden display
+
address@hidden Comma, in macro arguments
+Passing macro arguments containing commas requires special care, since
+commas also separate the arguments. To include a comma character in
+an argument, the most reliable method is to use the @code{@@address@hidden@}}
+command. For @code{makeinfo}, you can also prepend a backslash
+character, as in @samp{\,}, but this does not work with @TeX{}.
+
address@hidden Automatic quoting of commas for some macros
address@hidden Quoting, automatic for some macros
+It's not always necessary to worry about commas. To facilitate use of
+macros, @command{makeinfo} implements two rules for @dfn{automatic
+quoting} in some circumstances:
+
address@hidden 1
address@hidden If a macro takes only one argument, all commas in its invocation
+are quoted by default. For example:
+
address@hidden
address@hidden
+@@macro address@hidden@}
+@@address@hidden: address@hidden
+@@end macro
+
+@@address@hidden nice feature, though it can be address@hidden
address@hidden group
address@hidden example
+
address@hidden
+will produce the following output
+
address@hidden
address@hidden: A nice feature, though it can be dangerous.}
address@hidden example
+
+And indeed, it can. Namely, @command{makeinfo} does not control the
+number of arguments passed to one-argument macros, so be careful when
+you invoke them.
+
address@hidden If a macro invocation includes another command (including a
+recursive invocation of itself), any commas in the nested command
+invocation(s) are quoted by default. For example, in
+
address@hidden
+@@address@hidden@@address@hidden, I address@hidden, person address@hidden
address@hidden example
+
+the comma after @samp{Yes} is implicitly quoted. Here's another
+example, with a recursive macro:
+
address@hidden
address@hidden
+@@rmacro address@hidden,address@hidden
+\a\\b\
+@@end rmacro
+
+@@address@hidden@@address@hidden, address@hidden, address@hidden
address@hidden group
address@hidden example
+
address@hidden
+will produce the string @samp{foobarbaz}.
+
address@hidden Otherwise, a comma should be explicitly quoted, as above, for it
+to be treated as a part of an argument.
address@hidden enumerate
+
address@hidden Braces, in macro arguments
address@hidden Backslash, in macro arguments
+In addition to the comma, characters that need to be quoted in macro
+arguments are curly braces and backslash. For example:
+
address@hidden
+@@@var{macname} @address@hidden@}\,@}
address@hidden example
+
address@hidden
+will pass the (almost certainly error-producing) argument
address@hidden@address@hidden,} to @var{macname}.
+
+Unfortunately, this has not been reliably implemented in @TeX{}. When
+macros are used in the argument to other commands, for example, errors
+or incorrect output (the @samp{\} ``escape'' being included literally)
+are likely to result.
+
+If a macro is defined to take exactly one argument, it can (but need
+not) be invoked without any braces; then the entire rest of the line
+after the macro name is used as the argument. (Braces around the
+argument(s) are required in all other cases, i.e., if the macro takes
+either zero or more than one argument.) For example:
+
address@hidden
+@@macro bar @address@hidden
+Twice: \p\ & \p\.
+@@end macro
+@@bar aah
address@hidden example
+
address@hidden produces:
+
address@hidden
+Twice: aah & aah.
address@hidden display
+
+Likewise, if a macro is defined to take exactly one argument, and is
+invoked with braces, the braced text is passed as the argument, also
+regardless of commas. For example:
+
address@hidden
+@@macro bar @address@hidden
+Twice: \p\ & \p\.
+@@end macro
+@@address@hidden,address@hidden
address@hidden example
+
address@hidden produces:
+
address@hidden
+Twice: a,b & a,b.
address@hidden display
+
+If a macro is defined to take more than one argument, but is called
+with only one (in braces), the remaining arguments are set to the
+empty string, and no error is given. For example:
+
address@hidden
+@@macro addtwo @{p, address@hidden
+Both: \p\\q\.
+@@end macro
+@@address@hidden@}
address@hidden example
+
address@hidden produces simply:
+
address@hidden
+Both: a.
address@hidden display
+
+
address@hidden Macro Details
address@hidden Macro Details and Caveats
address@hidden Macro details
address@hidden Details of macro usage
address@hidden Caveats for macro usage
+
address@hidden Macro expansion, contexts for
address@hidden Expansion of macros, contexts for
+By design, macro expansion does not happen in the following contexts
+in @command{makeinfo}:
+
address@hidden @bullet
address@hidden @code{@@macro} and @code{@@unmacro} lines;
+
address@hidden @code{@@if...} lines, including @code{@@ifset} and similar;
+
address@hidden @code{@@set}, @code{@@clear}, @code{@@value};
+
address@hidden @code{@@clickstyle} lines;
+
address@hidden @code{@@end} lines.
address@hidden itemize
+
address@hidden Unfortunately, @TeX{} may do some expansion in these situations,
+possibly yielding errors.
+
+Also, quite a few macro-related constructs cause problems with @TeX{};
+some of the caveats are listed below. Thus, if you get macro-related
+errors when producing the printed version of a manual, you might try
+expanding the macros with @command{makeinfo} by invoking
address@hidden with the @samp{-E} option (@pxref{Format with
address@hidden). Or, more reliably, eschew Texinfo macros altogether
+and use a language designed for macro processing, such as M4
+(@pxref{External Macro Processors}).
+
address@hidden @bullet
address@hidden
+As mentioned earlier, macro names must consist entirely of letters.
+
address@hidden
+It is not advisable to redefine any @TeX{} primitive, plain, or
+Texinfo command name as a macro. Unfortunately this is a large and
+open-ended set of names, and the possible resulting errors are
+unpredictable.
+
address@hidden
+All macros are expanded inside at least one @TeX{} group.
+
address@hidden
+Macro arguments cannot cross lines.
+
address@hidden
+Macros containing a command which must be on a line by itself, such as
+a conditional, cannot be invoked in the middle of a line. Similarly,
+macros containing line-oriented commands or text, such as
address@hidden@@example} environments, may behave unpredictably in @TeX{}.
+
address@hidden
+White space is ignored at the beginnings of lines.
+
address@hidden
+Macros can't be reliably used in the argument to accent commands
+(@pxref{Inserting Accents}).
+
address@hidden
+The backslash escape for commas in macro arguments does not work;
address@hidden@@address@hidden@}} must be used.
+
address@hidden
+As a consequence, if a macro takes two or more arguments, and you want
+to pass an argument with the Texinfo command @code{@@,} (to produce a
+cedilla, @pxref{Inserting Accents}), you have to use @code{@@value} or
+another work-around. Otherwise, @TeX{} takes the comma as separating
+the arguments. Example:
+
address@hidden
+@@macro address@hidden, address@hidden
+\argfirst\+\argsecond\.
+@@end macro
+@@set fc Fran@@,cois
+@@address@hidden@@address@hidden@address@hidden
address@hidden example
+
address@hidden produces:
+
address@hidden
+Fran@,cois+.
address@hidden display
+
+The natural-seeming @code{@@address@hidden@@,address@hidden passes the two
+arguments @samp{Fran@@} and @samp{cois} to the macro, and nothing good
+results. And, as just mentioned, although the comma can be escaped
+with a backslash for @code{makeinfo} (@samp{@@\,}), that doesn't work
+in @TeX{}, so there is no other solution.
+
address@hidden
+It is usually best to avoid comments inside macro definitions, but
+see the next item.
+
address@hidden
+In general, the interaction of newlines in the macro definitions and
+invocations depends on the precise commands and context,
+notwithstanding the previous statements. You may be able to work
+around some problems with judicious use of @code{@@c}. Suppose you
+define a macro that is always used on a line by itself:
+
address@hidden
+@@macro linemac
+@@cindex whatever @@c
+@@end macro
+...
+foo
+@@linemac
+bar
address@hidden example
+
+Without the @code{@@c}, there will be a unwanted blank line between
+the @samp{@@cindex whatever} and the @samp{bar} (one newline comes
+from the macro definition, one from after the invocation), causing an
+unwanted paragraph break.
+
+On the other hand, you wouldn't want the @code{@@c} if the macro was
+sometimes invoked in the middle of a line (the text after the
+invocation would be treated as a comment).
+
address@hidden
+In general, you can't arbitrarily substitute a macro (or
address@hidden@@value}) call for Texinfo command arguments, even when the text
+is the same. Texinfo is not M4 (or even plain @TeX{}). It might work
+with some commands, it fails with others. Best not to do it at all.
+For instance, this fails:
+
address@hidden
+@@macro offmacro
+off
+@@end macro
+@@headings @@offmacro
address@hidden example
+
address@hidden
+This looks equivalent to @code{@@headings off}, but for @TeX{}nical
+reasons, it fails with a mysterious error message (namely,
address@hidden ended before @@headings was complete}).
+
address@hidden
+Macros cannot define macros in the natural way. To do this, you must
+use conditionals and raw @TeX{}. For example:
+
address@hidden
+@@ifnottex
+@@macro ctor @{name, address@hidden
+@@macro \name\
+something involving \arg\ somehow
+@@end macro
+@@end macro
+@@end ifnottex
+@@tex
address@hidden,@}
+\gdef\ctorx#1,#2,@address@hidden involving #2 address@hidden@}
+@@end tex
address@hidden example
address@hidden itemize
+
+The @command{makeinfo} implementation also has the following
+limitations (by design):
+
address@hidden
address@hidden
address@hidden@@verbatim} and macros do not mix; for instance, you can't start
+a verbatim block inside a macro and end it outside
+(@address@hidden@@verbatim}}). Starting any environment inside a macro
+and ending it outside may or may not work, for that matter.
+
address@hidden
+Macros that completely define macros are ok, but it's not possible to
+have incompletely nested macro definitions. That is, @code{@@macro}
+and @code{@@end macro} (likewise for @code{@@rmacro}) must be
+correctly paired. For example, you cannot start a macro definition
+within a macro, and then end that nested definition outside the macro.
address@hidden itemize
+
+In the @code{makeinfo} implementation before Texinfo 5.0, ends of
+lines from expansion of an @code{@@macro} definition did not end an
+@@-command line-delimited argument (@code{@@chapter}, @code{@@center},
+etc.). This is no longer the case. For example:
+
address@hidden
+@@macro address@hidden@}
+aaa
+bbb
+@@end macro
+@@center @@address@hidden@}
address@hidden example
+
+In the current @code{makeinfo}, this is equivalent to:
+
address@hidden
+@@center aaa
+bbb
address@hidden example
+
address@hidden with just @samp{aaa} as the argument to @code{@@center}. In
+the earlier implementation, it would have been parsed as this:
+
address@hidden
+@@center aaa bbb
address@hidden example
+
+
address@hidden @t{@@alias}
address@hidden @samp{@@alias @address@hidden
+
address@hidden@c old name
address@hidden Aliases, command
address@hidden Command aliases
address@hidden alias
+
+The @samp{@@alias} command defines a new command to be just like an
+existing one. This is useful for defining additional markup names,
+thus preserving additional semantic information in the input even
+though the output result may be the same.
+
+Write the @samp{@@alias} command on a line by itself, followed by the
+new command name, an equals sign, and the existing command name.
+Whitespace around the equals sign is optional and ignored if present.
+Thus:
+
address@hidden
+@@alias @var{new} = @var{existing}
address@hidden example
+
+For example, if your document contains citations for both books and
+some other media (movies, for example), you might like to define a
+macro @code{@@address@hidden@}} that does the same thing as an ordinary
address@hidden@@address@hidden@}} but conveys the extra semantic information as
well.
+You'd do this as follows:
+
address@hidden
+@@alias moviecite = cite
address@hidden example
+
+Macros do not always have the same effect as aliases, due to vagaries
+of argument parsing. Also, aliases are much simpler to define than
+macros. So the command is not redundant.
+
+Unfortunately, it's not possible to alias Texinfo environments; for
+example, @code{@@alias lang=example} is an error.
+
+Aliases must not be recursive, directly or indirectly.
+
+It is not advisable to redefine any @TeX{} primitive, plain @TeX{}, or
+Texinfo command name as an alias. Unfortunately this is a very large
+set of names, and the possible resulting errors from @TeX{} are
+unpredictable.
+
address@hidden will accept the same identifiers for aliases as it
+does for macro names, that is, alphanumerics and (except as the first
+character) @samp{-}.
+
+
address@hidden @t{@@definfoenclose}
address@hidden @code{@@definfoenclose}: Customized Highlighting
+
address@hidden@c old name
address@hidden Highlighting, customized
address@hidden Customized highlighting
address@hidden definfoenclose
+
+An @code{@@definfoenclose} command may be used to define a
+highlighting command for all the address@hidden 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.
+
+Presumably, if you define a command with @code{@@definfoenclose}, you
+will create a corresponding command for @TeX{}, either in
address@hidden, @file{texinfo.cnf}, or within an @samp{@@iftex} of
address@hidden@@tex} in your document.
+
+Write an @code{@@definfoenclose} command at the beginning of a line
+followed by three comma-separated arguments. The first argument to
address@hidden@@definfoenclose} is the @@-command name (without the
address@hidden@@}); the second argument is the start delimiter string; and the
+third argument is the end delimiter string. The latter two arguments
+enclose the highlighted text in the output.
+
+A delimiter string may contain spaces. Neither the start nor end
+delimiter is required. If you do not want a start delimiter but do
+want an end delimiter, you must follow the command name with two
+commas in a row; otherwise, the end delimiter string you intended will
+naturally be (mis)interpreted as the start delimiter string.
+
+If you do an @code{@@definfoenclose} on the name of a predefined
+command (such as @code{@@emph}, @code{@@strong}, @code{@@t}, or
address@hidden@@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}).
+
address@hidden phoo
+For example, you can write:
+
address@hidden
+@@definfoenclose phoo,//,\\
address@hidden example
+
address@hidden
+near the beginning of a Texinfo file to define @code{@@phoo} as an Info
+formatting command that inserts `//' before and `\\' after the argument
+to @code{@@phoo}. You can then write @code{@@address@hidden@}} wherever you
+want `//bar\\' highlighted in Info.
+
+For @TeX{} formatting, you could write
+
address@hidden
+@@iftex
+@@global@@let@@phoo=@@i
+@@end iftex
address@hidden example
+
address@hidden
+to define @code{@@phoo} as a command that causes @TeX{} to typeset the
+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
address@hidden@@iftex}. @code{@@definfoenclose} command need not be within
address@hidden@@ifinfo}, unless you want to use different definitions for
+different output formats.
+
address@hidden headword
+Here is another example: write
+
address@hidden
+@@definfoenclose headword, , :
address@hidden example
+
address@hidden
+near the beginning of the file, to define @code{@@headword} as an Info
+formatting command that inserts nothing before and a colon after the
+argument to @code{@@headword}.
+
address@hidden@@definfoenclose} definitions must not be recursive, directly or
+indirectly.
+
+
address@hidden External Macro Processors
address@hidden External Macro Processors: Line Directives
address@hidden External macro processors
address@hidden Macro processors, external
+
+Texinfo macros (and its other text substitution facilities) work fine
+in straightforward cases. If your document needs unusually complex
+processing, however, their fragility and limitations can be a problem.
+In this case, you may want to use a different macro processor
+altogether, such as M4 (@pxref{Top,,, m4, M4}) or CPP (@pxref{Top,,,
+cpp, The C Preprocessor}).
+
+With one exception, Texinfo does not need to know whether its input is
+``original'' source or preprocessed from some other source file.
+Therefore, you can arrange your build system to invoke whatever
+programs you like to handle macro expansion or other preprocessing
+needs. Texinfo does not offer built-in support for any particular
+preprocessor, since no one program seemed likely to suffice for the
+requirements of all documents.
+
address@hidden Line numbers, in error messages
address@hidden Error messages, line numbers in
+The one exception is line numbers in error messages. In that case,
+the line number should refer to the original source file, whatever it
+may be. There's a well-known mechanism for this: the so-called
address@hidden directive. Texinfo supports this.
+
address@hidden
+* @t{#line} Directive::
+* TeX: @t{#line} and @TeX{}.
+* Syntax: @t{#line} Syntax Details.
address@hidden menu
+
+
address@hidden @t{#line} Directive
address@hidden @samp{#line} Directive
+
address@hidden @samp{#line} directive
+
+An input line such as this:
+
address@hidden
address@hidden 100 "foo.ptexi"
address@hidden example
+
address@hidden indicates that the next line was line 100 of the file
address@hidden, and so that's what an error message should refer to.
+Both M4 (@pxref{Preprocessor features,,, m4, GNU M4}) and CPP
+(@pxref{Line Control,,, cpp, The C Preprocessor}, and
address@hidden Output,,, cpp, The C Preprocessor}) can generate
+such lines.
+
address@hidden CPP_LINE_DIRECTIVES
+The @command{makeinfo} program recognizes these lines by default,
+except within @code{@@verbatim} blocks (@address@hidden@@verbatim}}.
+Their recognition can be turned off completely with
address@hidden (@pxref{Other Customization Variables}),
+though there is normally no reason to do so.
+
+For those few programs (M4, CPP, Texinfo) which need to document
address@hidden directives and therefore have examples which would
+otherwise match the pattern, the command @code{@@address@hidden@}} can be
+used (@pxref{Inserting a Hashsign}). The example line above looks
+like this in the source for this manual:
+
address@hidden
+@@address@hidden@}line 100 "foo.ptexi"
address@hidden example
+
+The @code{@@hashchar} command was added to Texinfo in 2013. If you
+don't want to rely on it, you can also use @code{@@set} and
address@hidden@@value} to insert the literal @samp{#}:
+
address@hidden
+@@set hash #
+@@address@hidden@}line 1 "example.c"
address@hidden example
+
+Or, if suitable, an @code{@@verbatim} environment can be used instead
+of @code{@@example}. As mentioned above, @code{#line}-recognition is
+disabled inside verbatim blocks.
+
+
address@hidden @t{#line} and @TeX{}
address@hidden @samp{#line} and @TeX{}
+
address@hidden @TeX{} and @samp{#line} directives
address@hidden @samp{#line} directives, not processing with @TeX{}
+
+As mentioned, @command{makeinfo} recognizes the @samp{#line}
+directives described in the previous section. However,
address@hidden does not and cannot. Therefore, such a line will
+be incorrectly typeset verbatim if @TeX{} sees it. The solution is to
+use @command{makeinfo}'s macro expansion options before running
address@hidden There are three approaches:
+
address@hidden @bullet
address@hidden
+If you run @command{texi2dvi} or its variants (@pxref{Format with
address@hidden), you can pass @option{-E} and @command{texi2dvi}
+will run @command{makeinfo} first to expand macros and eliminate
address@hidden
+
address@hidden
+If you run @command{makeinfo} or its variants (@pxref{Generic
+Translator @t{texi2any}}), you can specify @option{--no-ifinfo
+--iftex -E somefile.out}, and then give @file{somefile.out} to
address@hidden in a separate command.
+
address@hidden
+Or you can run @option{makeinfo --dvi --Xopt -E}. (Or @option{--pdf}
+instead of @option{--dvi}.) @command{makeinfo} will then call
address@hidden -E}.
address@hidden itemize
+
address@hidden address@hidden, and line numbers in @TeX{}}
+One last caveat regarding use with @TeX{}: since the @code{#line}
+directives are not recognized, the line numbers emitted by the
address@hidden@@address@hidden@}} command (@pxref{Conditional Commands}), or by
address@hidden itself, are the (incorrect) line numbers from the derived file
+which @TeX{} is reading, rather than the preprocessor-specified line
+numbers. This is another example of why we recommend running
address@hidden for the best diagnostics (@address@hidden
+Advantages}).
+
+
address@hidden @t{#line} Syntax Details
address@hidden @samp{#line} Syntax Details
+
address@hidden @samp{#line} syntax details
address@hidden Syntax details, @samp{#line}
address@hidden Regular expression, for @samp{#line}
+
+Syntax details for the @samp{#line} directive: the @samp{#} character
+can be preceded or followed by whitespace, the word @samp{line} is
+optional, and the file name can be followed by a whitespace-separated
+list of integers (these are so-called ``flags'' output by CPP in some
+cases). For those who like to know the gory details, the actual
+(Perl) regular expression which is matched is this:
+
address@hidden
+/^\s*#\s*(line)? (\d+)(( "([^"]+)")(\s+\d+)*)?\s*$/
address@hidden 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
+regular expression.
+
+As an example, the following is a syntactically valid @samp{#line}
+directive, meaning line 1 of @file{/usr/include/stdio.h}:
+
address@hidden
address@hidden 1 "/usr/include/stdio.h" 2 3 4
address@hidden example
+
+Unfortunately, the quoted filename (@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.,
+
address@hidden
address@hidden 1
address@hidden example
+
+The possible solutions are described above (@address@hidden Directive}).
+
+
address@hidden Include Files
address@hidden Include Files
+
address@hidden Include files
+
+When a Texinfo processor sees an @code{@@include} command in a Texinfo
+file, it processes the contents of the file named by the
address@hidden@@include} and incorporates them into the output files being
+created. Include files thus let you keep a single large document as a
+collection of conveniently small parts.
+
address@hidden
+* Using Include Files:: How to use the @code{@@include} command.
+* @t{texinfo-multiple-files-update}:: How to create and update nodes and
+ menus when using included 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.
address@hidden menu
+
+
address@hidden Using Include Files
address@hidden How to Use Include Files
+
address@hidden include
+
+To include another file within a Texinfo file, write the
address@hidden@@include} command at the beginning of a line and follow it on
+the same line by the name of a file to be included. For example:
+
address@hidden
+@@include buffers.texi
address@hidden example
+
+@@-commands are expanded in file names. The one most likely to be
+useful is @code{@@value} (@address@hidden@@set @@value}}), and even then
+only in complicated situations.
+
+An included file should simply be a segment of text that you expect to
+be included as is into the overall or @dfn{outer} Texinfo file; it
+should not contain the standard beginning and end parts of a Texinfo
+file. In particular, you should not start an included file with a
+line saying @samp{\input texinfo}; if you do, that text is inserted
+into the output file literally. Likewise, you should not end an
+included file with an @code{@@bye} command; nothing after @code{@@bye}
+is formatted.
+
+In the long-ago past, you were required to write an
address@hidden@@setfilename} line at the beginning of an included file, but no
+longer. Now, it does not matter whether you write such a line. If an
address@hidden@@setfilename} line exists in an included file, it is ignored.
+
+
address@hidden @t{texinfo-multiple-files-update}
address@hidden @code{texinfo-multiple-files-update}
+
address@hidden texinfo-multiple-files-update
+
+GNU Emacs Texinfo mode provides the
address@hidden command. This command creates or
+updates `Next', `Previous', and `Up' pointers of included files as
+well as those in the outer or overall Texinfo file, and it creates or
+updates a main menu in the outer file. Depending on whether you call
+it with optional arguments, the command updates only the pointers in
+the first @code{@@node} line of the included files or all of them:
+
address@hidden @kbd
address@hidden M-x texinfo-multiple-files-update
+Called without any arguments:
+
address@hidden @minus
address@hidden
+Create or update the `Next', `Previous', and `Up' pointers of the
+first @code{@@node} line in each file included in an outer or overall
+Texinfo file.
+
address@hidden
+Create or update the `Top' level node pointers of the outer or
+overall file.
+
address@hidden
+Create or update a main menu in the outer file.
address@hidden itemize
+
address@hidden C-u M-x texinfo-multiple-files-update
+Called with @kbd{C-u} as a prefix argument:
+
address@hidden @minus{}
address@hidden
+Create or update pointers in the first @code{@@node} line in each
+included file.
+
address@hidden
+Create or update the `Top' level node pointers of the outer file.
+
address@hidden
+Create and insert a master menu in the outer file. The master menu
+is made from all the menus in all the included files.
address@hidden itemize
+
address@hidden C-u 8 M-x texinfo-multiple-files-update
+Called with a numeric prefix argument, such as @kbd{C-u 8}:
+
address@hidden @minus
address@hidden
+Create or update @strong{all} the `Next', `Previous', and `Up' pointers
+of all the included files.
+
address@hidden
+Create or update @strong{all} the menus of all the included
+files.
+
address@hidden
+Create or update the `Top' level node pointers of the outer or
+overall file.
+
address@hidden
+And then create a master menu in the outer file. This is similar to
+invoking @code{texinfo-master-menu} with an argument when you are
+working with just one file.
address@hidden itemize
address@hidden table
+
+Note the use of the prefix argument in interactive use: with a regular
+prefix argument, just @address@hidden, the
address@hidden command inserts a master menu;
+with a numeric prefix argument, such as @kbd{C-u 8}, the command
+updates @strong{every} pointer and menu in @strong{all} the files and
+then inserts a master menu.
+
+
address@hidden Include Files Requirements
address@hidden Include Files Requirements
address@hidden Include files requirements
address@hidden Requirements for include files
+
+If you plan to use the @code{texinfo-multiple-files-update} command,
+the outer Texinfo file that lists included files within it should
+contain nothing but the beginning and end parts of a Texinfo file, and
+a number of @code{@@include} commands listing the included files. It
+should not even include indices, which should be listed in an included
+file of their own.
+
+Moreover, each of the included files must contain exactly one highest
+level node (conventionally, @code{@@chapter} or equivalent),
+and this node must be the first node in the included file.
+Furthermore, each of these highest level nodes in each included file
+must be at the same hierarchical level in the file structure.
+Usually, each is an @code{@@chapter}, an @code{@@appendix}, or an
address@hidden@@unnumbered} node. Thus, normally, each included file contains
+one, and only one, chapter or equivalent-level node.
+
+The outer file should contain only @emph{one} node, the `Top' node. It
+should @emph{not} contain any nodes besides the single `Top' node. The
address@hidden command will not process
+them.
+
+
address@hidden Sample Include File
address@hidden Sample File with @code{@@include}
address@hidden Sample @code{@@include} file
address@hidden Include file sample
address@hidden @code{@@include} file sample
+
+Here is an example of an outer Texinfo file with @code{@@include} files
+within it before running @code{texinfo-multiple-files-update}, which
+would insert a main or master menu:
+
address@hidden
address@hidden
+\input texinfo @@c -*-texinfo-*-
address@hidden %**start of header
+@@setfilename include-example.info
+@@settitle Include Example
address@hidden %**end of header
address@hidden group
+
+... @xref{Sample Texinfo Files}, for
+examples of the rest of the frontmatter ...
+
address@hidden
+@@ifnottex
+@@node Top
+@@top Include Example
+@@end ifnottex
address@hidden group
+
address@hidden
+@@include foo.texinfo
+@@include bar.texinfo
+@@include concept-index.texinfo
+@@bye
address@hidden group
address@hidden example
+
+An included file, such as @file{foo.texinfo}, might look like this:
+
address@hidden
address@hidden
+@@node First
+@@chapter First Chapter
+
+Contents of first chapter @dots{}
address@hidden group
address@hidden example
+
+The full contents of @file{concept-index.texinfo} might be as simple as this:
+
address@hidden
address@hidden
+@@node Concept Index
+@@unnumbered Concept Index
+
+@@printindex cp
address@hidden group
address@hidden example
+
+The outer Texinfo source file for @cite{The GNU Emacs Lisp Reference
+Manual} is named @file{elisp.texi}. This outer file contains a master
+menu with 417 entries and a list of 41 @code{@@include}
+files.
+
+
address@hidden Include Files Evolution
address@hidden Evolution of Include Files
+
+When Info was first created, it was customary to create many small
+Info files on one subject. Each Info file was formatted from its own
+Texinfo source file. This custom meant that Emacs did not need to
+make a large buffer to hold the whole of a large Info file when
+someone wanted information; instead, Emacs allocated just enough
+memory for the small Info file that contained the particular
+information sought. This way, Emacs could avoid wasting memory.
+
+References from one file to another were made by referring to the file
+name as well as the node name. (@xref{Other Info Files, , Referring to
+Other Info Files}. Also, see @ref{Four and Five Arguments, ,
address@hidden@@xref} with Four and Five Arguments}.)
+
+Include files were designed primarily as a way to create a single,
+large printed manual out of several smaller Info files. In a printed
+manual, all the references were within the same document, so @TeX{}
+could automatically determine the references' page numbers. The Info
+formatting commands used include files only for creating joint
+indices; each of the individual Texinfo files had to be formatted for
+Info individually. (Each, therefore, required its own
address@hidden@@setfilename} line.)
+
+However, because large Info files are now split automatically, it is
+no longer necessary to keep them small.
+
+Nowadays, multiple Texinfo files are used mostly for large documents,
+such as @cite{The GNU Emacs Lisp Reference Manual}, and for projects
+in which several different people write different sections of a
+document simultaneously.
+
+In addition, the Info formatting commands have been extended to work
+with the @code{@@include} command so as to create a single large Info
+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.
+
+
address@hidden Hardcopy
address@hidden Formatting and Printing Hardcopy
address@hidden Format and print hardcopy
address@hidden Printing hardcopy
address@hidden Hardcopy, printing it
address@hidden Making a printed manual
address@hidden Sorting indices
address@hidden Indices, sorting
address@hidden @TeX{} index sorting
+
+Running the @command{texi2dvi} or @command{texi2pdf} command is the
+simplest way to create printable output. These commands are installed
+as part of the Texinfo package.
+
+More specifically, three major shell commands are used to print
+formatted output from a Texinfo manual: one converts the Texinfo
+source into something printable, a second sorts indices, and a third
+actually prints the formatted document. When you use the shell
+commands, you can either work directly in the operating system shell
+or work within a shell inside GNU Emacs (or some other computing
+environment).
+
+If you are using GNU Emacs, you can use commands provided by Texinfo
+mode instead of shell commands. In addition to the three commands to
+format a file, sort the indices, and print the result, Texinfo mode
+offers key bindings for commands to recenter the output buffer, show the
+print queue, and delete a job from the print queue.
+
+Details are in the following sections.
+
address@hidden
+* Use @TeX{}:: Use @TeX{} to format for hardcopy.
+* Format with @t{tex}/@t{texindex}:: How to format with explicit shell
commands.
+* Format with @t{texi2dvi}:: A simpler way to format.
+* Print with @t{lpr}:: How to print.
+* Within Emacs:: How to format and print from an Emacs shell.
+* Texinfo Mode Printing:: How to format and print in Texinfo mode.
+* Compile-Command:: How to print using Emacs's compile command.
+* Requirements Summary:: @TeX{} formatting requirements summary.
+* Preparing for @TeX{}:: What to do before you use @TeX{}.
+* Overfull hboxes:: What are and what to do with overfull hboxes.
+* @t{@@smallbook}:: How to print small format books and
manuals.
+* A4 Paper:: How to print on A4 or A5 paper.
+* @t{@@pagesizes}:: How to print with customized page sizes.
+* Cropmarks and Magnification:: How to print marks to indicate the size
+ of pages and how to print scaled up output.
+* PDF Output:: Portable Document Format output.
+* Obtaining @TeX{}:: How to obtain @TeX{}.
address@hidden menu
+
+
address@hidden Use @TeX{}
address@hidden Use @TeX{}
+
+The typesetting program called @TeX{} is used for formatting a Texinfo
+file. @TeX{} is a very powerful typesetting program and, when used
+correctly, does an exceptionally good job.
+
address@hidden @TeX{}}, for information on how to obtain @TeX{}. It
+is not included in the Texinfo package, being a vast suite of software
+itself.
+
+
address@hidden Format with @t{tex}/@t{texindex}
address@hidden Format with @code{tex}/@code{texindex}
+
address@hidden Shell formatting with @code{tex} and @code{texindex}
address@hidden Formatting with @code{tex} and @code{texindex}
address@hidden DVI file
+
+You can format the Texinfo file with the shell command @code{tex}
+followed by the name of the Texinfo file. For example:
+
address@hidden
+tex foo.texi
address@hidden example
+
address@hidden @TeX{} will produce a @dfn{DVI file} as well as several auxiliary
+files containing information for indices, cross references, etc. The
+DVI file (for @dfn{DeVice Independent} file) can be printed on virtually
+any device (see the following sections).
+
address@hidden texindex
+The @code{tex} formatting command itself does not sort the indices; it
+writes an output file of unsorted index data. To generate a printed
+index after running the @command{tex} command, you first need a sorted
+index to work from. The @command{texindex} command sorts indices.
+(The source file @file{texindex.c} comes as part of the standard
+Texinfo distribution, among other places.) (@command{texi2dvi} runs
address@hidden and @command{texindex} as necessary.)
+
address@hidden of index files}
address@hidden Names of index files
address@hidden Index file names
address@hidden formatting command outputs unsorted index files under names
+that obey a standard convention: the name of your main input file with
+any @samp{.texinfo} (or similar, @pxref{Minimum,, What a Texinfo File
+Must Have}), followed by the two letter names of indices. For
+example, the raw index output files for the input file
address@hidden would be @file{foo.cp}, @file{foo.vr},
address@hidden, @file{foo.tp}, @file{foo.pg} and @file{foo.ky}. Those
+are exactly the arguments to give to @code{texindex}.
+
address@hidden 1000
address@hidden Wildcards
address@hidden Globbing
+Instead of specifying all the unsorted index file names explicitly, you
+can use @samp{??} as shell wildcards and give the command in this
+form:
+
address@hidden
+texindex foo.??
address@hidden example
+
address@hidden
+This command will run @code{texindex} on all the unsorted index files,
+including any two letter indices that you have defined yourself using
address@hidden@@defindex} or @code{@@defcodeindex}. You can safely run
address@hidden foo.??} even if there are files with two letter
+extensions that are not index files, such as @samp{foo.el}. The
address@hidden command reports but otherwise ignores such files.
+
+For each file specified, @code{texindex} generates a sorted index file
+whose name is made by appending @samp{s} to the input file name. The
address@hidden@@printindex} command looks for a file with that name
+(@pxref{Printing Indices & Menus}). @code{texindex} does not alter the
+raw index output file.
+
+After you have sorted the indices, you need to rerun @code{tex} on the
+Texinfo file. This regenerates the DVI file, this time with
+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:
+
address@hidden
address@hidden
+Run @code{tex} on your Texinfo file. This generates a DVI file (with
+undefined cross references and no indices), and the raw index files
+(with two letter extensions).
+
address@hidden
+Run @code{texindex} on the raw index files. This creates the
+corresponding sorted index files (with three letter extensions).
+
address@hidden
+Run @code{tex} again on your Texinfo file. This regenerates the DVI
+file, this time with indices and defined cross references, but with
+page numbers for the cross references from the previous run, generally
+incorrect.
+
address@hidden
+Sort the indices again, with @code{texindex}.
+
address@hidden
+Run @code{tex} one last time. This time the correct page numbers are
+written for the cross references.
address@hidden enumerate
+
address@hidden texi2dvi
+Alternatively, it's a one-step process: run @code{texi2dvi}
+(@pxref{Format with @t{texi2dvi}}).
+
+You need not run @code{texindex} each time after you run @code{tex}. If
+you do not, on the next run, the @code{tex} formatting command will use
+whatever sorted index files happen to exist from the previous use of
address@hidden This is usually ok while you are debugging.
+
address@hidden Auxiliary files, avoiding
address@hidden novalidate
address@hidden Pointer validation, suppressing
address@hidden Chapters, formatting one at a time
+Sometimes you may wish to print a document while you know it is
+incomplete, or to print just one chapter of a document. In that case,
+the usual auxiliary files that @TeX{} creates and warnings @TeX{}
+gives when cross references are not satisfied are just nuisances. You
+can avoid them with the @code{@@novalidate} command, which you must
+give @emph{before} the @code{@@setfilename} command
+(@address@hidden@@setfilename}}). Thus, the beginning of your file
+would look approximately like this:
+
address@hidden
+\input texinfo
+@@novalidate
+@@setfilename myfile.info
address@hidden
address@hidden example
+
address@hidden @code{@@novalidate} also turns off validation in
address@hidden, just like its @code{--no-validate} option
+(@pxref{Pointer Validation}).
+
+
address@hidden Format with @t{texi2dvi}
address@hidden Format with @code{texi2dvi}
+
address@hidden texi2dvi @r{(shell script)}
+
+The @code{texi2dvi} command automatically runs both @TeX{} and
address@hidden as many times as necessary to produce a DVI file
+with sorted indices and all cross references resolved. It is
+therefore simpler than manually executing the
address@hidden@address@hidden@code{tex} sequence
+described in the previous section.
+
+To run @code{texi2dvi} on an input file @file{foo.texi}, do this (where
address@hidden } is your shell prompt):
+
address@hidden
+prompt$ @kbd{texi2dvi foo.texi}
address@hidden example
+
+As shown in this example, the input filenames to @code{texi2dvi} must
+include any extension (@samp{.texi}, @samp{.texinfo}, etc.). Under
+MS-DOS and perhaps in other circumstances, you may need to run @samp{sh
+texi2dvi foo.texi} instead of relying on the operating system to invoke
+the shell on the @samp{texi2dvi} script.
+
address@hidden address@hidden, for @command{texi2dvi}}
+One useful option to @code{texi2dvi} is @address@hidden
+This inserts @var{cmd} on a line by itself after the
address@hidden@@setfilename} in a temporary copy of the input file before
+running @TeX{}. With this, you can specify different printing
+formats, such as @code{@@smallbook} (@address@hidden@@smallbook}}),
address@hidden@@afourpaper} (@pxref{A4 Paper}), or @code{@@pagesizes}
+(@address@hidden@@pagesizes}}), without actually changing the document
+source. (You can also do this on a site-wide basis with
address@hidden; @pxref{Preparing for @TeX{}}).
+
address@hidden address@hidden, for @command{texi2dvi}}
address@hidden pdftexi2dvi
+With the @option{--pdf} option, @command{texi2dvi} produces PDF output
+instead of DVI (@pxref{PDF Output}), by running @command{pdftex}
+instead of @command{tex}. Alternatively, the command
address@hidden is an abbreviation for running @samp{texi2dvi
+--pdf}. The command @command{pdftexi2dvi} is also supported as a
+convenience to address@hidden users (@pxref{Top,,, auctex, address@hidden,
since
+that program merely prepends @samp{pdf} to DVI producing tools to have
+PDF producing tools.
+
address@hidden address@hidden, for @command{texi2dvi}}
address@hidden dvipdfmx
+With the @option{--dvipdf} option, @command{texi2dvi} produces PDF
+output by running @TeX{} and then a DVI-to-PDF program: if the
address@hidden environment variable is set, that value is used, else
+the first extant among @code{dvipdfmx}, @code{dvipdfm}, @code{dvipdf},
address@hidden, @code{dvitopdf}. This method can support CJK
+typesetting better than @command{pdftex}.
+
address@hidden address@hidden, for @command{texi2dvi}}
address@hidden dvips
+With the @option{--ps} option, @command{texi2dvi} produces PostScript
+instead of DVI, by running @command{tex} and then @command{dvips}
+(@pxref{Top,,, dvips, Dvips}). (Or the value of the @env{DVIPS}
+environment variable, if set.)
+
address@hidden @LaTeX{}, processing with @command{texi2dvi}
address@hidden can also be used to process @LaTeX{} files; simply
+run @samp{texi2dvi filename.ext}.
+
address@hidden address@hidden, for @command{texi2dvi}}
+Normally @command{texi2dvi} is able to guess the input file language
+by its contents and file name suffix. If, however, it fails to do so
+you can specify the input language using
address@hidden@var{lang}} command line option, where @var{lang}
+is either @samp{latex} or @samp{texinfo}.
+
address@hidden will use @command{etex} (or @command{pdfetex}) if
+they are available; these extended versions of @TeX{} are not
+required, and the DVI (or PDF) output is identical, but they simplify
+the @TeX{} programming in some cases, and provide additional tracing
+information when debugging @file{texinfo.tex}.
+
address@hidden address@hidden, for @command{texi2dvi}}
+Several options are provided for handling documents, written in
+character sets other than address@hidden The
address@hidden@var{file}} option instructs
address@hidden to translate input into internal @TeX{} character
+set using @dfn{translation file} @var{file} (@pxref{TCX files, TCX
+files, TCX files: Character translations, web2c, Web2c: A @TeX{}
+implementation}).
+
address@hidden address@hidden, for @command{texi2dvi}}
+The options @option{--recode} and @address@hidden
+allow conversion of an input document before running @TeX{}. The
address@hidden option recodes the document from encoding specified
+by @samp{@@documentencoding} command
+(@address@hidden@@documentencoding}}) to plain 7-bit @samp{texinfo}
+encoding.
+
address@hidden address@hidden, for @command{texi2dvi}}
+The option @address@hidden recodes the document from
address@hidden encoding to the encoding specified by
address@hidden@@documentencoding}. This is useful, for example, if the
+document is written in @samp{UTF-8} encoding and an equivalent 8-bit
+encoding is supported by @command{makeinfo}.
+
+Both @option{--recode} and @address@hidden use
address@hidden utility to perform the conversion. If
address@hidden fails to process the file, @command{texi2dvi} prints
+a warning and continues, using the unmodified input file.
+
+The option @option{-E} (equivalently, @option{-e} and
address@hidden) does Texinfo macro expansion using
address@hidden instead of the @TeX{} implementation (@pxref{Macro
+Details}). Each implementation has its own limitations and
+advantages. If this option is used, the string
address@hidden@@address@hidden must not appear at the beginning of a line
+in the source file.
+
+For the list of all options, run @samp{texi2dvi --help}.
+
+
address@hidden Print with @t{lpr}
address@hidden Print With @code{lpr -d} From Shell
+
address@hidden lpr @r{(DVI print command)}
+
+The precise command to print a DVI file depends on your system
+installation. Two common ones are @samp{dvips foo.dvi -o} and @samp{lpr
+-d foo.dvi}.
+
+For example, the following commands will (perhaps) suffice to sort the
+indices, format, and print the @cite{Bison Manual}:
+
address@hidden
address@hidden
+tex bison.texinfo
+texindex bison.??
+tex bison.texinfo
+lpr -d bison.dvi
address@hidden group
address@hidden example
+
address@hidden
+(Remember that the shell commands may be different at your site; but
+these are commonly used versions.)
+
+Using the @code{texi2dvi} shell script (see the previous section):
+
address@hidden
address@hidden
+texi2dvi bison.texinfo
+lpr -d bison.dvi
+# or perhaps dvips bison.dvi -o
address@hidden group
address@hidden example
+
address@hidden Shell printing, on MS-DOS/MS-Windows
address@hidden Printing DVI files, on MS-DOS/MS-Windows
address@hidden address@hidden, replacements on MS-DOS/MS-Windows}
address@hidden is a standard program on Unix systems, but it is usually
+absent on MS-DOS/MS-Windows. Some network packages come with a
+program named @code{lpr}, but these are usually limited to sending files
+to a print server over the network, and generally don't support the
address@hidden option. If you are unfortunate enough to work on one of these
+systems, you have several alternative ways of printing DVI files:
+
address@hidden @bullet{}
address@hidden Find and install a Unix-like @code{lpr} program, or its clone.
+If you can do that, you will be able to print DVI files just like
+described above.
+
address@hidden Send the DVI files to a network printer queue for DVI files.
+Some network printers have special queues for printing DVI files. You
+should be able to set up your network software to send files to that
+queue. In some cases, the version of @code{lpr} which comes with your
+network software will have a special option to send a file to specific
+queues, like this:
+
address@hidden
+lpr -Qdvi -hprint.server.domain bison.dvi
address@hidden example
+
address@hidden Convert the DVI file to a Postscript or PCL file and send it to
your
+local printer. @xref{Invoking Dvips,,, dvips, Dvips}, and the man
+pages for @code{dvilj}, for detailed description of these tools. Once
+the DVI file is converted to the format your local printer understands
+directly, just send it to the appropriate port, usually @samp{PRN}.
address@hidden itemize
+
+
address@hidden Within Emacs
address@hidden From an Emacs Shell
address@hidden Print, format from Emacs shell
address@hidden Format, print from Emacs shell
address@hidden Shell, format, print from
address@hidden Emacs shell, format, print from
address@hidden GNU Emacs shell, format, print from
+
+You can give formatting and printing commands from a shell within GNU
+Emacs. To create a shell within Emacs, type @kbd{M-x shell}. In this
+shell, you can format and print the document. @xref{Hardcopy, , Format
+and Print Hardcopy}, for details.
+
+You can switch to and from the shell buffer while @code{tex} is
+running and do other editing. If you are formatting a long document
+on a slow machine, this can be very convenient.
+
+You can also use @code{texi2dvi} from an Emacs shell. For example,
+here is how to use @code{texi2dvi} to format and print @cite{Using and
+Porting GNU CC} from a shell within Emacs:
+
address@hidden
address@hidden
+texi2dvi gcc.texinfo
+lpr -d gcc.dvi
address@hidden group
address@hidden example
+
+See the next section for more information about formatting
+and printing in Texinfo mode.
+
+
address@hidden Texinfo Mode Printing
address@hidden Formatting and Printing in Texinfo Mode
address@hidden Region printing in Texinfo mode
address@hidden Format and print in Texinfo mode
address@hidden Print and format in Texinfo mode
+
+Texinfo mode provides several predefined key commands for @TeX{}
+formatting and printing. These include commands for sorting indices,
+looking at the printer queue, killing the formatting job, and
+recentering the display of the buffer in which the operations
+occur.
+
address@hidden @kbd
address@hidden C-c C-t C-b
address@hidden M-x texinfo-tex-buffer
+Run @code{texi2dvi} on the current buffer.
+
address@hidden C-c C-t C-r
address@hidden M-x texinfo-tex-region
+Run @TeX{} on the current region.
+
address@hidden C-c C-t C-i
address@hidden M-x texinfo-texindex
+Sort the indices of a Texinfo file formatted with
address@hidden
+
address@hidden C-c C-t C-p
address@hidden M-x texinfo-tex-print
+Print a DVI file that was made with @code{texinfo-tex-region} or
address@hidden
+
address@hidden C-c C-t C-q
address@hidden M-x tex-show-print-queue
+Show the print queue.
+
address@hidden C-c C-t C-d
address@hidden M-x texinfo-delete-from-print-queue
+Delete a job from the print queue; you will be prompted for the job
+number shown by a preceding @kbd{C-c C-t C-q} command
+(@code{texinfo-show-tex-print-queue}).
+
address@hidden C-c C-t C-k
address@hidden M-x tex-kill-job
+Kill the currently running @TeX{} job started by either
address@hidden or @code{texinfo-tex-buffer}, or any other
+process running in the Texinfo shell buffer.
+
address@hidden C-c C-t C-x
address@hidden M-x texinfo-quit-job
+Quit a @TeX{} formatting job that has stopped because of an error by
+sending an @key{x} to it. When you do this, @TeX{} preserves a record
+of what it did in a @file{.log} file.
+
address@hidden C-c C-t C-l
address@hidden M-x tex-recenter-output-buffer
+Redisplay the shell buffer in which the @TeX{} printing and formatting
+commands are run to show its most recent output.
address@hidden table
+
address@hidden 1000
+Thus, the usual sequence of commands for formatting a buffer is as
+follows (with comments to the right):
+
address@hidden
address@hidden
+C-c C-t C-b @r{Run @code{texi2dvi} on the buffer.}
+C-c C-t C-p @r{Print the DVI file.}
+C-c C-t C-q @r{Display the printer queue.}
address@hidden group
address@hidden example
+
+The Texinfo mode @TeX{} formatting commands start a subshell in Emacs
+called the @file{*tex-shell*}. The @code{texinfo-tex-command},
address@hidden, and @code{tex-dvi-print-command}
+commands are all run in this shell.
+
+You can watch the commands operate in the @samp{*tex-shell*} buffer,
+and you can switch to and from and use the @samp{*tex-shell*} buffer
+as you would any other shell buffer.
+
address@hidden 1500
+The formatting and print commands depend on the values of several variables.
+The default values are:
+
address@hidden
address@hidden
+ @r{Variable} @r{Default value}
+
+texinfo-texi2dvi-command "texi2dvi"
+texinfo-tex-command "tex"
+texinfo-texindex-command "texindex"
+texinfo-delete-from-print-queue-command "lprm"
+texinfo-tex-trailer "@@bye"
+tex-start-of-header "%**start"
+tex-end-of-header "%**end"
+tex-dvi-print-command "lpr -d"
+tex-show-queue-command "lpq"
address@hidden group
address@hidden example
+
+You can change the values of these variables with the @kbd{M-x
+set-variable} command (@pxref{Examining, , Examining and Setting
+Variables, emacs, The GNU Emacs Manual}), or with your @file{.emacs}
+initialization file (@pxref{Init File, , , emacs, The GNU Emacs
+Manual}).
+
address@hidden Customize Emacs package (@t{Development/Docs/Texinfo})
+Beginning with version 20, GNU Emacs offers a user-friendly interface,
+called @dfn{Customize}, for changing values of user-definable variables.
address@hidden Customization, , Easy Customization Interface, emacs, The GNU
+Emacs Manual}, for more details about this. The Texinfo variables can
+be found in the @samp{Development/Docs/Texinfo} group, once you invoke
+the @kbd{M-x customize} command.
+
+
address@hidden Compile-Command
address@hidden Using the Local Variables List
address@hidden Local variables
address@hidden Compile command for formatting
address@hidden Format with the compile command
+
+Yet another way to apply the @TeX{} formatting command to a Texinfo file
+is to put that command in a @dfn{local variables list} at the end of the
+Texinfo file. You can then specify the @code{tex} or @code{texi2dvi}
+commands as a @code{compile-command} and have Emacs run it by typing
address@hidden compile}. This creates a special shell called the
address@hidden buffer in which Emacs runs the compile command.
+For example, at the end of the @file{gdb.texinfo} file, after the
address@hidden@@bye}, you could put the following:
+
address@hidden
address@hidden
+Local Variables:
+compile-command: "texi2dvi gdb.texinfo"
+End:
address@hidden group
address@hidden example
+
address@hidden
+This technique is most often used by programmers who also compile programs
+this way; see @ref{Compilation, , , emacs, The GNU Emacs Manual}.
+
+
address@hidden Requirements Summary
address@hidden @TeX{} Formatting Requirements Summary
address@hidden Requirements for formatting
address@hidden Minimal requirements for formatting
address@hidden Formatting requirements
+
+Every Texinfo file that is to be input to @TeX{} must begin with a
address@hidden command and must contain an @code{@@setfilename} command:
+
address@hidden
+\input texinfo
+@@setfilename @address@hidden
address@hidden example
+
address@hidden
+The first command instructs @TeX{} to load the macros it needs to
+process a Texinfo file and the second command opens auxiliary files.
+
+Every Texinfo file must end with a line that terminates @TeX{}'s
+processing and forces out unfinished pages:
+
address@hidden
+@@bye
address@hidden example
+
+Strictly speaking, these lines are all a Texinfo file needs to be
+processed successfully by @TeX{}.
+
+Usually, however, the beginning includes an @code{@@settitle} command to
+define the title of the printed manual, an @code{@@setchapternewpage}
+command, a title page, a copyright page, and permissions. Besides an
address@hidden@@bye}, the end of a file usually includes indices and a table of
+contents. (And of course most manuals contain a body of text as well.)
+
+For more information, see:
+
address@hidden @bullet
address@hidden @address@hidden@@settitle}}.
address@hidden @address@hidden@@setchapternewpage}}.
address@hidden @ref{Headings}.
address@hidden @ref{Titlepage & Copyright Page}.
address@hidden @ref{Printing Indices & Menus}.
address@hidden @ref{Contents}.
address@hidden itemize
+
+
address@hidden Preparing for @TeX{}
address@hidden Preparing for @TeX{}
address@hidden Preparing for @TeX{}
address@hidden @TeX{} input initialization
address@hidden @b{.profile} initialization file
address@hidden @b{.cshrc} initialization file
address@hidden Initialization file for @TeX{} input
+
address@hidden needs to know where to find the @file{texinfo.tex} file that the
address@hidden texinfo} command on the first line reads. The
address@hidden file tells @TeX{} how to handle @@-commands; it is
+included in all standard GNU distributions. The latest version is
+always available from the Texinfo source repository:
address@hidden
address@hidden://savannah.gnu.org/cgi-bin/viewcvs/texinfo/texinfo/doc/texinfo.tex?rev=HEAD}
address@hidden smalldisplay
+
address@hidden address@hidden, installing}
+
+Usually, the installer has put the @file{texinfo.tex} file in the
+default directory that contains @TeX{} macros when GNU Texinfo, Emacs or
+other GNU software is installed. In this case, @TeX{} will find the
+file and you do not need to do anything special. If this has not been
+done, you can put @file{texinfo.tex} in the current directory when you
+run @TeX{}, and @TeX{} will find it there.
+
address@hidden address@hidden, installing}
+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}).
+
address@hidden European Computer Modern fonts, installing
address@hidden EC fonts, installing
address@hidden CM-Super fonts, installing
+To be able to use quotation marks other than those used in English
+you'll need to install European Computer Modern fonts and optionally
+CM-Super fonts, unless they are already installed (@pxref{Inserting
+Quotation Marks}).
+
address@hidden address@hidden, installing}
address@hidden Euro font, installing
+If you intend to use the @code{@@euro} command, you should install the
+Euro font, if it is not already installed. @address@hidden@@euro}}.
+
address@hidden texinfo.cnf @r{installation}
address@hidden Customizing of @TeX{} for Texinfo
address@hidden Site-wide Texinfo configuration file
+Optionally, you may create a file @file{texinfo.cnf} for site
+configuration. This file is read by @TeX{} when the
address@hidden@@setfilename} command is executed
(@address@hidden@@setfilename}}).
+You can put any commands you like there, according to local site-wide
+conventions. They will be read by @TeX{} when processing any Texinfo
+document. For example, if @file{texinfo.cnf} contains the line
address@hidden@@afourpaper} (@pxref{A4 Paper}), then all Texinfo documents
+will be processed with that page size in effect. If you have nothing
+to put in @file{texinfo.cnf}, you do not need to create it.
+
address@hidden Environment variable @code{TEXINPUTS}
address@hidden TEXINPUTS
+If neither of the above locations for these system files suffice for
+you, you can specify the directories explicitly. For
address@hidden, you can do this by writing the complete path for the
+file after the @code{\input} command. Another way, that works for both
address@hidden and @file{texinfo.cnf} (and any other file @TeX{}
+might read), is to set the @code{TEXINPUTS} environment variable in your
address@hidden or @file{.cshrc} file.
+
+Whether you use @file{.profile} or @file{.cshrc} depends on
+whether you use a Bourne shell-compatible (@code{sh}, @code{bash},
address@hidden, @dots{}) or C shell-compatible (@code{csh}, @code{tcsh})
+command interpreter, respeictvely.
+
+In a @file{.profile} file, you could use the following @code{sh} command
+sequence:
+
address@hidden
address@hidden
+TEXINPUTS=.:/home/me/mylib:
+export TEXINPUTS
address@hidden group
address@hidden example
+
address@hidden 1000
+While in a @file{.cshrc} file, you could use the following @code{csh}
+command sequence:
+
address@hidden
+setenv TEXINPUTS .:/home/me/mylib:
address@hidden example
+
+
+On MS-DOS/MS-Windows, you would say it like address@hidden the use
+of the @samp{;} character as directory separator, instead of @samp{:}.}:
+
address@hidden
address@hidden
+set TEXINPUTS=.;d:/home/me/mylib;c:
address@hidden group
address@hidden example
+
address@hidden
+It is customary for DOS/Windows users to put such commands in the
address@hidden file, or in the Windows registry.
+
address@hidden
+These settings would cause @TeX{} to look for @file{\input} file first
+in the current directory, indicated by the @samp{.}, then in a
+hypothetical user @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.)
+
address@hidden Dumping a .fmt file
address@hidden Format file, dumping
+Finally, you may wish to dump a @file{.fmt} file (@pxref{Memory dumps,,,
+web2c, Web2C}) so that @TeX{} can load Texinfo faster. (The
+disadvantage is that then updating @file{texinfo.tex} requires
+redumping.) You can do this by running this command, assuming
address@hidden is findable by @TeX{}:
+
address@hidden
+initex texinfo @@dump
address@hidden example
+
address@hidden
+(@code{dump} is a @TeX{} primitive.) Then, move @file{texinfo.fmt} to
+wherever your @code{.fmt} files are found; typically, this will be in the
+subdirectory @file{web2c} of your @TeX{} installation.
+
+
address@hidden Overfull hboxes
address@hidden Overfull ``hboxes''
address@hidden Overfull @samp{hboxes}
address@hidden @samp{hbox}, overfull
address@hidden Final output
+
address@hidden is sometimes unable to typeset a line without extending it into
+the right margin. This can occur when @TeX{} comes upon what it
+interprets as a long word that it cannot hyphenate, such as an
+electronic mail network address or a very long title. When this
+happens, @TeX{} prints an error message like this:
+
address@hidden
+Overfull @@hbox (20.76302pt too wide)
address@hidden example
+
address@hidden hbox
address@hidden
+(In @TeX{}, lines are in ``horizontal boxes'', hence the term, ``hbox''.
address@hidden@@hbox} is a @TeX{} primitive not used in the Texinfo language.)
+
address@hidden also provides the line number in the Texinfo source file and
+the text of the offending line, which is marked at all the places that
address@hidden considered hyphenation.
address@hidden with @TeX{}},
+for more information about typesetting errors.
+
+If the Texinfo file has an overfull hbox, you can rewrite the sentence
+so the overfull hbox does not occur, or you can decide to leave it. A
+small excursion into the right margin often does not matter and may not
+even be noticeable.
+
+If you have many overfull boxes and/or an antipathy to rewriting, you
+can coerce @TeX{} into greatly increasing the allowable interword
+spacing, thus (if you're lucky) avoiding many of the bad line breaks,
+like this:
+
address@hidden \emergencystretch
address@hidden
+@@tex
+\global\emergencystretch = .9\hsize
+@@end tex
address@hidden example
+
address@hidden
+(You should adjust the fraction as needed.) This huge value for
address@hidden cannot be the default, since then the typeset
+output would generally be of noticeably lower quality; the default
+is @samp{.15\hsize}. @code{\hsize} is the @TeX{} dimension
+containing the current line width.
+
address@hidden Black rectangle in hardcopy
address@hidden Rectangle, black in hardcopy
address@hidden Box, ugly black in hardcopy
address@hidden Ugly black rectangles in hardcopy
+For what overfull boxes you have, however, @TeX{} will print a large,
+ugly, black rectangle beside the line that contains the overfull hbox
+unless told otherwise. This is so you will notice the location of the
+problem if you are correcting a draft.
+
address@hidden finalout
+To prevent such a monstrosity from marring your final printout, write
+the following in the beginning of the Texinfo file on a line of its own,
+before the @code{@@titlepage} command:
+
address@hidden
+@@finalout
address@hidden example
+
+
address@hidden @t{@@smallbook}
address@hidden @code{@@smallbook}: Printing ``Small'' Books
+
address@hidden@c old name
address@hidden smallbook
address@hidden Small book size
address@hidden Book, printing small
address@hidden Page sizes for books
address@hidden 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:
+
address@hidden
+@@smallbook
address@hidden example
+
address@hidden
+(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}).
+
address@hidden@t{@@address@hidden, for information about commands that make
+it easier to produce examples for a smaller manual.
+
address@hidden with @t{texi2dvi}}, and @ref{Preparing for @TeX{}},
+for other ways to format with @code{@@smallbook} that do not require
+changing the source file.
+
+
address@hidden A4 Paper
address@hidden Printing on A4 Paper
address@hidden A4 paper, printing on
address@hidden A5 paper, printing on
address@hidden Paper size, A4
address@hidden European A4 paper
address@hidden afourpaper
+
+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:
+
address@hidden
address@hidden
+\input texinfo @@c -*-texinfo-*-
+@@c %**start of header
+@@setfilename texinfo
+@@settitle Texinfo
+@@afourpaper
+@@c %**end of header
address@hidden group
address@hidden example
+
address@hidden with @t{texi2dvi}}, and @ref{Preparing for @TeX{}},
+for other ways to format for different paper sizes that do not require
+changing the source file.
+
address@hidden afourlatex
address@hidden afourwide
+You may or may not prefer the formatting that results from the command
address@hidden@@afourlatex}. There's also @code{@@afourwide} for A4 paper in
+wide format.
+
+
address@hidden @t{@@pagesizes}
address@hidden @code{@@pagesizes} address@hidden, @var{height}]: Custom Page
Sizes
address@hidden@c old node name
+
address@hidden pagesizes
address@hidden Custom page sizes
address@hidden Page sizes, customized
address@hidden Text width and height
address@hidden Width of text area
address@hidden Height of text area
address@hidden 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:
+
address@hidden
+@@pagesizes 200mm,150mm @c for b5 paper
address@hidden example
address@hidden and
address@hidden
+@@pagesizes 11.5in @c for legal paper
address@hidden example
+
address@hidden B5 paper, printing on
address@hidden 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 address@hidden by address@hidden for B5, address@hidden by
address@hidden for legal).
+
address@hidden 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
address@hidden
+
address@hidden with @t{texi2dvi}}, and @ref{Preparing for @TeX{}},
+for other ways to specify @code{@@pagesizes} that do not require
+changing the source file.
+
address@hidden@@pagesizes} is ignored by @code{makeinfo}.
+
+
address@hidden Cropmarks and Magnification
address@hidden Cropmarks and Magnification
+
address@hidden cropmarks
address@hidden Cropmarks for printing
address@hidden Printing cropmarks
+You can (attempt to) direct @TeX{} to print cropmarks at the corners
+of pages with the @code{@@cropmarks} command. Write the
address@hidden@@cropmarks} command on a line by itself near the beginning of
+the Texinfo file, before the title page, like this:
+
address@hidden
+@@cropmarks
address@hidden example
+
+This command is mainly for printers that typeset several pages on one
+sheet of film; but you can attempt to use it to mark the corners of a
+book set to 7 by 9.25 inches with the @code{@@smallbook} command.
+(Printers will not produce cropmarks for regular sized output that is
+printed on regular sized paper.) Since different printing machines
+work in different ways, you should explore the use of this command
+with a spirit of adventure. You may have to redefine the command in
address@hidden
+
+The @code{@@cropmarks} command is recognized and ignored in address@hidden
+output formats.
+
address@hidden \mag @r{(raw @TeX{} magnification)}
address@hidden Magnified printing
address@hidden 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
address@hidden@@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:
+
address@hidden
address@hidden
+@@tex
+\mag=1200
+@@end tex
address@hidden group
address@hidden 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
address@hidden may not print or may print only with certain
+magnifications. Be prepared to experiment.
+
+
address@hidden PDF Output
address@hidden PDF Output
address@hidden PDF output
+
address@hidden pdftex
+The simplest way to generate PDF output from Texinfo source is to run
+the convenience script @command{texi2pdf} (or @command{pdftexi2dvi});
+this executes the @command{texi2dvi} script with the @option{--pdf}
+option (@pxref{Format with @t{texi2dvi}}). If for some reason you
+want to process the document by hand, you can run the @command{pdftex}
+program instead of plain @command{tex}. That is, run @samp{pdftex
+foo.texi} instead of @samp{tex foo.texi}.
+
address@hidden stands for `Portable Document Format'. It was invented by
+Adobe Systems some years ago for document interchange, based on their
+PostScript language. Related links:
+
address@hidden
address@hidden
+GNU GV, a @uref{http://www.gnu.org/software/gv/, Ghostscript-based PDF
+reader}. (It can also preview PostScript documents.)
+
address@hidden
address@hidden, a freely available standalone
address@hidden://www.foolabs.com/xpdf/, PDF reader} for the X window
+system.
+
address@hidden
address@hidden://partners.adobe.com/asn/acrobat/sdk/public/docs/, PDF
definition}.
+
address@hidden itemize
+
+At present, Texinfo does not provide @samp{@@ifpdf} or @samp{@@pdf}
+commands as for the other output formats, since PDF documents contain
+many internal low-level offsets and references that would be hard or
+impossible to get right at the Texinfo source level.
+
+PDF files require dedicated software to be displayed, unlike the plain
+ASCII formats (Info, HTML) that Texinfo supports. They also tend to
+be much larger than the DVI files output by @TeX{} by default.
+Nevertheless, a PDF file does define an actual typeset document in a
+self-contained file, so it has its place.
+
+
address@hidden Obtaining @TeX{}
address@hidden Obtaining @TeX{}
address@hidden Obtaining @TeX{}
address@hidden @TeX{}, how to obtain
+
address@hidden 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
address@hidden://tug.org/texlive}.
+
address@hidden please keep that text in sync with www.gnu.org/prep/FTP
+
+
address@hidden Generic Translator @t{texi2any}
address@hidden @code{texi2any}: The Generic Translator for Texinfo
+
address@hidden is the generic translator for Texinfo that can
+produce different output formats and is highly customizable. It
+supports these formats:
+
address@hidden @asis
address@hidden Info (by default, or with @option{--info}),
+
address@hidden HTML (with @option{--html}),
+
address@hidden plain text (with @option{--plaintext}),
+
address@hidden Docbook (with @option{--docbook}),
+
address@hidden Texinfo XML (with @option{--xml}).
address@hidden table
+
address@hidden is an alias for @command{texi2any}. By default,
+both @command{texi2any} and @command{makeinfo} generate Info output;
+indeed, there are no differences in behavior based on the name.
+
+Beside these default formats, command line options to
address@hidden can change many aspects of the output. Beyond
+that, initialization files provide even more control over the final
+output---nearly anything not specified in the Texinfo input file.
+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.
+
address@hidden
+* Reference Implementation:: @command{texi2any}: the reference
implementation.
+* Invoking @t{texi2any}:: Running the translator from a shell.
+* @t{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 @t{pod2texi}:: Translating Perl pod to Texinfo.
+* @t{texi2html}:: An ancestor of @command{texi2any}.
address@hidden menu
+
+
address@hidden Reference Implementation
address@hidden @command{texi2any}: A Texinfo Reference Implementation
+
address@hidden @command{texi2any}, as reference implementation
address@hidden Reference implementation
address@hidden 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 highly
+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 processors.
+
address@hidden Tree representation of documents
address@hidden Syntax tree representation of documents
address@hidden 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
address@hidden, to avoid continuing with two different
+implementations (@pxref{History}). The current reference
+implementation, @command{texi2any}, inherited the design of
+customization and other features from @command{texi2html} (for more on
address@hidden compatibility, @address@hidden).
+However, @code{texi2any} is a full reimplementation: it constructs a
+tree-based representation of the input document for all back-ends to
+work from.
+
address@hidden Texinfo language tests
address@hidden Tests, of Texinfo language
+Extensive tests of the language were developed at the same time as
address@hidden; we plead with anyone thinking of writing a program
+to parse Texinfo input to at least make use of these tests.
+
address@hidden Examples of using @command{texi2any}
address@hidden Texinfo::Parser module
+The @command{texi2html} wrapper script (@address@hidden)
+provides a 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 in
address@hidden/texi-elements-by-size}. (Its functionality may also be
+useful to authors; @pxref{texi-elements-by-size}.)
+
address@hidden Future of Texinfo implementations
+With the release of @command{texi2any} as the reference
+implementation, development of both the C implementation of
address@hidden and @command{texi2html} has been halted. Going
+forward, we ask authors of Texinfo documents to use only
address@hidden
+
+
address@hidden Invoking @t{texi2any}
address@hidden Invoking @command{texi2any}/@code{makeinfo} from a Shell
+
address@hidden makeinfo}
address@hidden makeinfo
address@hidden texi2any
+
+To process a Texinfo file, invoke @command{texi2any} or
address@hidden (the two names are synonyms for the same program;
+we'll use the names interchangeably) followed by the name of the
+Texinfo file. Also select the format you want to output with the
+appropriate command line option (default is Info). Thus, to create
+the Info file for Bison, type the following to the shell:
+
address@hidden
+texi2any --info bison.texinfo
address@hidden example
+
+You can specify more than one input file name; each is processed in
+turn. If an input file name is @samp{-}, standard input is read.
+
address@hidden@t{makeinfo} Options}
address@hidden anchor{makeinfo address@hidden prev name, but case-insensitive
clash
address@hidden @code{makeinfo} options
address@hidden Options for @code{makeinfo}
address@hidden Options}
address@hidden @code{texi2any} options
address@hidden Options for @code{texi2any}
+
+The @command{texi2any} program accept many options. Perhaps the
+most basic are those that change the output format. By default,
address@hidden outputs Info.
+
+Each command line option is either a long name preceded by @samp{--}
+or a single letter preceded by @samp{-}. You can use abbreviations
+for the long option names as long as they are unique.
+
+For example, you could use the following shell command to create an
+Info file for @file{bison.texinfo} in which lines are filled to only
+68 columns:
+
address@hidden
+texi2any --fill-column=68 bison.texinfo
address@hidden example
+
+You can write two or more options in sequence, like this:
+
address@hidden
+texi2any --no-split --fill-column=70 @dots{}
address@hidden example
+
address@hidden
+(This would keep the Info file together as one possibly very long
+file and would also set the fill column to 70.)
+
+The options are (approximately in alphabetical order):
+
address@hidden @code
address@hidden --commands-in-node-names
address@hidden --commands-in-node-names
+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.)
+
address@hidden address@hidden
address@hidden address@hidden
+Prepend @var{path} 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
+several directories separated by the usual path separator character
+(@samp{:} on Unix-like systems, @samp{;} on Windows). @c @xref{Loading
address@hidden Init Files}.
+
address@hidden address@hidden
address@hidden --css-include
+When producing HTML, literally include the contents of @var{file},
+which should contain W3C cascading style sheets specifications, in the
address@hidden<style>} block of the HTML output. If @var{file} is @samp{-},
+read standard input. @xref{HTML CSS}.
+
address@hidden address@hidden
address@hidden --css-ref
+When producing HTML, add a @samp{<link>} tag to the output which
+references a cascading style sheet at @var{url}. This allows using
+standalone style sheets.
+
address@hidden -D @var{var}
address@hidden -D @var{var}
+Cause the Texinfo variable @var{var} to be defined. This is
+equivalent to @code{@@set @var{var}} in the Texinfo file
+(@address@hidden@@set @@clear @@value}}).
+
address@hidden --disable-encoding
address@hidden --enable-encoding
address@hidden --disable-encoding
address@hidden --enable-encoding
+By default, or with @option{--enable-encoding}, output accented and
+special characters in Info and plain text output based on
address@hidden@@documentencoding}. With @option{--disable-encoding}, 7-bit
+ASCII transliterations are output. @address@hidden@@documentencoding}},
+and @ref{Inserting Accents}.
+
address@hidden --docbook
address@hidden --docbook
+Generate Docbook output (rather than Info).
+
address@hidden address@hidden
address@hidden --document-language
+Use @var{lang} to translate Texinfo keywords which end up in the
+output document. The default is the locale specified by the
address@hidden@@documentlanguage} command if there is one, otherwise English
+(@address@hidden@@documentlanguage}}).
+
address@hidden --dvi
address@hidden --dvi
+Generate a TeX DVI file using @command{texi2dvi}, rather than Info
+(@address@hidden Printed Output}).
+
address@hidden --dvipdf
address@hidden --dvipdf
+Generate a PDF file using @command{texi2dvi --dvipdf}, rather than
+Info (@address@hidden Printed Output}).
+
address@hidden address@hidden
address@hidden -e @var{limit}
address@hidden address@hidden
address@hidden -e @var{limit}
+Report @var{LIMIT} errors before aborting (on the assumption that
+continuing would be useless); default 100.
+
address@hidden address@hidden
address@hidden -f @var{width}
address@hidden address@hidden
address@hidden -f @var{width}
+Specify the maximum number of columns in a line; this is the
+right-hand edge of a line. Paragraphs that are filled will be filled
+to this width. (Filling is the process of breaking up and connecting
+lines so that lines are the same length as or shorter than the number
+specified as the fill column. Lines are broken between words.) The
+default value is 72.
+
address@hidden address@hidden
address@hidden -s @var{style}
address@hidden address@hidden
address@hidden -s @var{style}
+Set the footnote style to @var{style}: either @samp{end} for the end
+node style (the default) or @samp{separate} for the separate node
+style. The value set by this option overrides the value set in a
+Texinfo file by an @code{@@footnotestyle} command (@pxref{Footnote
+Styles}).
+
+When the footnote style is @samp{separate}, @code{makeinfo} makes a
+new node containing the footnotes found in the current node. When the
+footnote style is @samp{end}, @code{makeinfo} places the footnote
+references at the end of the current node.
+
+In HTML, when the footnote style is @samp{end}, or if the output is
+not split, footnotes are put at the end of the output. If set to
address@hidden, and the output is split, they are placed in a
+separate file.
+
address@hidden --force
address@hidden -F
address@hidden --force
address@hidden -F
+Ordinarily, if the input file has errors, the output files are not
+created. With this option, they are preserved.
+
address@hidden --help
address@hidden -h
address@hidden address@hidden, for @command{texi2any}}
address@hidden -h
+Print a message with available options and basic usage, then exit
+successfully.
+
address@hidden --html
address@hidden --html
+Generate HTML output (rather than Info). By default, the HTML output
+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}.
+
address@hidden -I @var{path}
address@hidden -I @var{path}
+Append @var{path} to the directory search list for finding files that
+are included using the @code{@@include} command. By default,
address@hidden searches only the current directory. If @var{path} is
+not given, the current directory is appended. The @var{path} value
+can be a single directory or a list of several directories separated
+by the usual path separator character (@samp{:} on Unix-like systems,
address@hidden;} on Windows).
+
address@hidden --ifdocbook
address@hidden --ifdocbook
address@hidden --ifhtml
address@hidden --ifhtml
address@hidden --ifinfo
address@hidden --ifinfo
address@hidden --ifplaintext
address@hidden --ifplaintext
address@hidden --iftex
address@hidden --iftex
address@hidden --ifxml
address@hidden --ifxml
+For the given format, process @samp{@@address@hidden and
address@hidden@@@var{format}} commands, and do not process
address@hidden@@address@hidden, regardless of the format being output.
+For instance, if @option{--iftex} is given, then @samp{@@iftex} and
address@hidden@@tex} blocks will be read, and @samp{@@ifnottex} blocks will be
+ignored.
+
address@hidden --info
address@hidden --info
+Generate Info output. By default, if the output file contains more
+than about 300,000 bytes, it is split into shorter subfiles of about
+that size. The name of the output file and any subfiles is determined
+by @code{@@setfilename} (@address@hidden@@setfilename}}). @xref{Tag and
+Split Files}.
+
address@hidden address@hidden
address@hidden address@hidden
+Load @var{file} as code to modify the behavior and output of the
+generated manual. It is customary to use the @code{.pm} or the
address@hidden extensions for these customization files, but that is not
+enforced; the @var{file} name can be anything. The
address@hidden option (see above) can be used to add to the list
+of directories in which these customization files are searched for.
address@hidden @xref{Loading Init Files}.
+
address@hidden address@hidden
address@hidden address@hidden
address@hidden Internal links, of HTML
+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
+the term which was indexed or entered. The items are in the natural
+sorting order for the given element. This dump can be useful for
+post-processors.
+
address@hidden address@hidden
address@hidden -E @var{file}
address@hidden address@hidden
address@hidden -E @var{file}
+Output the Texinfo source, with all Texinfo macros expanded, to
address@hidden Normally, the result of macro expansion is used
+internally by @code{makeinfo} and then discarded.
+
address@hidden --no-headers
address@hidden --no-headers
address@hidden Node separators, omitting with @option{--no-headers}
address@hidden Generating plain text files with @option{--no-headers}
address@hidden Menus, omitting with @option{--no-headers}
+Do not include menus or node separator lines in the output.
+
+When generating Info, this is the same as using @option{--plaintext},
+resulting in a simple plain text file. Furthermore,
address@hidden@@setfilename} is ignored, and output is to standard output
+unless overridden with @option{-o}. (This behavior is for backward
+compatibility.)
+
address@hidden Navigation links, omitting
+When generating HTML, and output is split, also output navigation
+links only at the beginning of each file. If output is not split, do
+not include navigation links at the top of each node at all.
address@hidden HTML}.
+
address@hidden --no-ifdocbook
address@hidden --no-ifdocbook
address@hidden --no-ifhtml
address@hidden --no-ifhtml
address@hidden --no-ifinfo
address@hidden --no-ifinfo
address@hidden --no-ifplaintext
address@hidden --no-ifplaintext
address@hidden --no-iftex
address@hidden --no-iftex
address@hidden --no-ifxml
address@hidden --no-ifxml
+For the given format, do not process @samp{@@address@hidden and
address@hidden@@@var{format}} commands, and do process
address@hidden@@address@hidden, regardless of the format being output.
+For instance, if @option{--no-ifhtml} is given, then @samp{@@ifhtml}
+and @samp{@@html} blocks will not be read, and @samp{@@ifnothtml}
+blocks will be.
+
address@hidden --no-node-files
address@hidden --node-files
address@hidden --no-node-files
address@hidden --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
+for section- and chapter-level cross-manual references to succeed
+(@pxref{HTML Xref Configuration}).
+
+If the output is split, this is enabled by default. If the output is
+not split, @option{--node-files} enables the creation of the
+redirection files, in addition to the monolithic main output file.
address@hidden suppresses the creation of redirection files
+in any case. This option has no effect with any output format other
+than address@hidden @xref{Generating HTML}.
+
address@hidden --no-number-footnotes
address@hidden --no-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.
+
address@hidden --no-number-sections
address@hidden --number-sections
address@hidden --no-number-sections
address@hidden --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
address@hidden if your manual is not normally structured.
+
address@hidden --no-pointer-validate
address@hidden --no-validate
address@hidden --no-pointer-validate
address@hidden --no-validate
address@hidden Pointer validation, suppressing from command line
+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}.
+
address@hidden --no-warn
address@hidden --no-warn
+Suppress warning messages (but not error messages).
+
address@hidden address@hidden
address@hidden -o @var{file}
address@hidden address@hidden
address@hidden -o @var{file}
+Specify that the output should be directed to @var{file}. This
+overrides any file name specified in an @code{@@setfilename} command
+found in the Texinfo source. If neither @code{@@setfilename} nor this
+option are specified, the input file name is used to determine the
+output name. @address@hidden@@setfilename}}.
+
+If @var{file} is @samp{-}, output goes to standard output and
address@hidden is implied.
+
+If @var{file} is a directory or ends with a @samp{/} the usual rules
+are used to determine the output file name (namely, use
address@hidden@@setfilename} or the input file name) but the files are written
+to the @var{file} directory. For example, @samp{makeinfo -o bar/
+foo.texi}, with or without @option{--no-split}, will write
address@hidden/foo.info}, and possibly other files, under @file{bar/}.
+
+When generating HTML and output is split, @var{file} is used as the
+name for the directory into which all files are written. For example,
address@hidden -o bar --html foo.texi} will write
address@hidden/index.html}, among other files.
+
address@hidden address@hidden
address@hidden --outputindent
+This option now does nothing, but remains for compatibility. (It used
+to alter indentation in XML/Docbook output.)
+
address@hidden -P @var{path}
address@hidden -P @var{path}
+Prepend @var{path} to the directory search list for @code{@@include}.
+If @var{path} is not given, the current directory is prepended. See
address@hidden above.
+
address@hidden address@hidden
address@hidden -p @var{indent}
address@hidden address@hidden
address@hidden -p @var{indent}
+Set the paragraph indentation style to @var{indent}. The value set by
+this option overrides the value set in a Texinfo file by an
address@hidden@@paragraphindent} command (@address@hidden@@paragraphindent}}).
+The value of @var{indent} is interpreted as follows:
+
address@hidden @asis
address@hidden @samp{asis}
+Preserve any existing indentation (or lack thereof) at the beginnings
+of paragraphs.
+
address@hidden @samp{0} or @samp{none}
+Delete any existing indentation.
+
address@hidden @var{num}
+Indent each paragraph by @var{num} spaces.
address@hidden table
+
+The default is to indent by two spaces, except for paragraphs
+following a section heading, which are not indented.
+
address@hidden --pdf
address@hidden --pdf
+Generate a PDF file using @command{texi2dvi --pdf}, rather than Info
+(@address@hidden Printed Output}).
+
address@hidden --plaintext
address@hidden --plaintext
address@hidden Plain text output with @option{--plaintext}
address@hidden ASCII text output with @option{--plaintext}
address@hidden Generating plain text files with @option{--plaintext}
address@hidden Node separators, omitting with @option{--plaintext}
address@hidden Menus, omitting with @option{--plaintext}
address@hidden @file{INSTALL} file, generating
+Output a plain text file (rather than Info): do not include menus or
+node separator lines in the output. This results in a straightforward
+plain text file that you can (for example) send in email without
+complications, or include in a distribution (for example, an
address@hidden file).
+
+With this option, @code{@@setfilename} is ignored and the output goes
+to standard output by default; this can be overridden with @option{-o}.
+
address@hidden --ps
address@hidden --ps
+Generate a PostScript file using @command{texi2dvi --ps}, rather than
+Info (@address@hidden Printed Output}).
+
address@hidden --set-customization-variable @address@hidden
address@hidden -c @address@hidden
address@hidden --set-customization-variable @address@hidden
address@hidden -c @address@hidden
+Set the customization variable @var{var} to @var{value}. The @code{=}
+is optional, but both @var{var} and @var{value} must be quoted to the
+shell as necessary so the result is a single word. Many aspects of
address@hidden behavior and output may be controlled by
+customization variables, beyond what can be set in the document by
+@@-commands and with other command line switches. @xref{Customization
+Variables}.
+
address@hidden address@hidden
address@hidden --no-split
address@hidden address@hidden
address@hidden --no-split
address@hidden Splitting of output files
address@hidden Output file splitting
address@hidden Output}
address@hidden
+When generating Info, by default large output files are split into
+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.
+
+Alternatively, @address@hidden may be used to specify at
+which level the HTML output should be split. The possible values for
address@hidden are:
+
address@hidden @samp
address@hidden chapter
+The output is split at @code{@@chapter} and other sectioning
+@@-commands at this level (@code{@@appendix}, etc.).
+
address@hidden section
+The output is split at @code{@@section} and similar.
+
address@hidden node
+The output is split at every node. This is the default.
address@hidden table
+
address@hidden address@hidden
address@hidden address@hidden
+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.)
+
address@hidden --transliterate-file-names
address@hidden --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}.
+
address@hidden -U @var{var}
+Cause @var{var} to be undefined. This is equivalent to @code{@@clear
address@hidden in the Texinfo file (@address@hidden@@set @@clear @@value}}).
+
address@hidden --verbose
address@hidden --verbose
+Cause @code{makeinfo} to display messages saying what it is doing.
+Normally, @code{makeinfo} only outputs messages if there are errors or
+warnings.
+
address@hidden --version
address@hidden -V
address@hidden address@hidden, for @command{texi2any}}
address@hidden -V
+Print the version number, then exit successfully.
+
address@hidden --Xopt @var{str}
address@hidden --Xopt @var{str}
+Pass @var{str} (a single shell word) to @command{texi2dvi}; may be
+repeated (@address@hidden Printed Output}).
+
address@hidden --xml
address@hidden --xml
+Generate Texinfo XML output (rather than Info).
+
address@hidden table
+
address@hidden TEXINFO_OUTPUT_FORMAT
address@hidden Environment variable @code{TEXINFO_OUTPUT_FORMAT}
address@hidden also reads the environment variable
address@hidden to determine the output format, if not
+overridden by a command line option. The value should be one of:
+
address@hidden
+docbook dvi dvipdf html info pdf plaintext ps xml
address@hidden example
+
+If not set or otherwise specified, Info output is the default.
+
+The customization variable of the same name is also read; if set, that
+overrides an environment variable setting, but not a command-line
+option. @xref{Customization Variables for @@-Commands}.
+
+
address@hidden @t{texi2any} Printed Output
address@hidden @command{texi2any} Printed Output
+
address@hidden Printed output, through @command{texi2any}
address@hidden Output, printed through @command{texi2any}
+
+To justify the name address@hidden, @command{texi2any} has
+basic support for creating printed output in the various formats:
address@hidden DVI, PDF, and PostScript. This is done via the simple method
+of executing the @command{texi2dvi} program when those outputs are
+requested.
+
+The output format options for this are @option{--dvi},
address@hidden, @option{--pdf}, and @option{--ps}. @xref{Format
+with @t{texi2dvi}}, for more details on these options and general
address@hidden operation. In addition, the @option{--verbose},
address@hidden, and @option{--quiet} options are passed on if
+specified; the @option{-I} and @option{-o} options are likewise passed
+on with their arguments, and @option{--debug} without its argument.
+
+The only option remaining that is related to the @command{texi2dvi}
+invocation is @option{--Xopt}. Here, just the argument is passed on
+and multiple @option{--Xopt} options accumulate. This provides a way
+to construct an arbitrary command line for @command{texi2dvi}. For
+example, running
+
address@hidden
+texi2any --Xopt -t --Xopt @@a4paper --pdf foo.texi
address@hidden example
+
address@hidden is equivalent to running
+
address@hidden
+texi2dvi -t @@a4paper --pdf foo.texi
address@hidden example
+
+Although one might wish that other options to @command{texi2any} would
+take effect, they don't. For example, running @samp{texi2any
+--no-number-sections --dvi foo.texi} still results in a DVI file with
+numbered sections. (Perhaps this could be improved in the future, if
+requests are received.)
+
+The actual name of the command that is invoked is specified by the
address@hidden customization variable (@pxref{Other Customization
+Variables}). As you might guess, the default is @samp{texi2dvi}.
+
address@hidden itself does not generate any output when it invokes
address@hidden
+
+
address@hidden Pointer Validation
address@hidden Pointer Validation
address@hidden Pointer validation with @code{makeinfo}
address@hidden Validation of pointers
+
+If you do not suppress pointer validation with the
address@hidden 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:
+
address@hidden
address@hidden
+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
address@hidden(dir)}, then the referenced node must exist.
+
address@hidden
+Every node except the `Top' node must have an `Up' pointer.
+
address@hidden
+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})}.
address@hidden enumerate
+
+With implicit node pointers, the above error cannot occur, as such.
+(Which is a major reason why we recommend using this feature of
address@hidden, 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
address@hidden 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,
address@hidden checks that every node except the `Top' node is
+referenced in a menu.
+
+
address@hidden Customization Variables
address@hidden Customization Variables
+
address@hidden Warning
+These customization variable names and meanings may change in any
+Texinfo release. We always try to avoid incompatible changes, but we
+cannot absolutely promise, since needs change over time.
address@hidden quotation
+
+Many aspects of the behavior and output of @command{texi2any} may be
+modified by modifying so-called @dfn{customization variables}. These
+fall into four general categories:
+
address@hidden @bullet
address@hidden
+Those associated with @@-commands; for example,
address@hidden@@documentlanguage}.
+
address@hidden
+Those associated with command-line options; for example, the
+customization variable @code{SPLIT} is associated with the
address@hidden command-line option, and @code{TEXINFO_OUTPUT_FORMAT}
+allows specifying the output format.
+
address@hidden
+Other ad hoc variables.
address@hidden itemize
+
+Customization variables may set on the command line using
address@hidden '@var{var} @var{value}'} (quoting
+the variable/value pair to the shell) or
address@hidden @address@hidden (using
address@hidden). A special @var{value} is @samp{undef}, which sets the
+variable to this special ``undefined'' Perl value.
+
+The sections below give the details for each of these.
+
address@hidden
+* Commands: Customization Variables for @@-Commands.
+* Options: Customization Variables and Options.
+* HTML: HTML Customization Variables.
+* Other: Other Customization Variables.
address@hidden menu
+
+
address@hidden Customization Variables for @@-Commands
address@hidden Customization Variables for @@-Commands
+
address@hidden Customization variables for @@-commands
address@hidden @@-commands, customization variables for
+
+Each of the following @@-commands has an associated customization
+variable with the same name (minus the leading @code{@@}):
+
address@hidden
+@@allowcodebreaks @@clickstyle @@codequotebacktick
+@@codequoteundirected @@contents @@deftypefnnewline
+@@documentdescription @@documentencoding @@documentlanguage
+@@evenfooting @@evenfootingmarks
+@@evenheading @@evenheadingmarks
+@@everyfooting @@everyfootingmarks
+@@everyheading @@everyheadingmarks
+@@exampleindent @@firstparagraphindent
+@@fonttextsize @@footnotestyle @@frenchspacing @@headings
+@@kbdinputstyle @@novalidate
+@@oddfooting @@oddfootingmarks
+@@oddheading @@oddheadingmarks
+@@pagesizes @@paragraphindent
+@@setchapternewpage @@setcontentsaftertitlepage
+@@setfilename
+@@setshortcontentsaftertitlepage @@shortcontents
+@@urefbreakstyle @@xrefautomaticsectiontitle
address@hidden smallexample
+
+Setting such a customization variable to a value @samp{foo} is similar
+to executing @code{@@@var{cmd} foo}. It is not exactly the same,
+though, since any side effects of parsing the Texinfo source are not
+redone. Also, some variables do not take Texinfo code when generating
+particular formats, but an argument that is already formatted. This
+is the case, for example, for HTML for @code{documentdescription}.
+
+
address@hidden Customization Variables and Options
address@hidden Customization Variables and Options
+
address@hidden Customization variables for options
address@hidden Options, customization variables for
+
+The following table gives the customization variables associated with
+some command line options. @xref{Invoking @t{texi2any}}, for the
+meaning of the options.
+
address@hidden @columnfractions 0.5 0.5
address@hidden Option @tab Variable
address@hidden ENABLE_ENCODING
address@hidden @option{--enable-encoding} @tab @code{ENABLE_ENCODING}
address@hidden documentlanguage
address@hidden @option{--document-language} @tab @code{documentlanguage}
address@hidden ERROR_LIMIT
address@hidden @option{--error-limit} @tab @code{ERROR_LIMIT}
address@hidden FILLCOLUMN
address@hidden @option{--fill-column} @tab @code{FILLCOLUMN}
address@hidden footnotestyle
address@hidden @option{--footnote-style} @tab @code{footnotestyle}
address@hidden FORCE
address@hidden @option{--force} @tab @code{FORCE}
address@hidden INTERNAL_LINKS
address@hidden @option{--internal-links} @tab @code{INTERNAL_LINKS}
address@hidden MACRO_EXPAND
address@hidden @option{--macro-expand} @tab @code{MACRO_EXPAND}
address@hidden HEADERS
address@hidden SHOW_MENU
address@hidden @option{--headers} @tab @code{HEADERS},
@code{SHOW_MENU}
address@hidden NO_WARN
address@hidden @option{--no-warn} @tab @code{NO_WARN}
address@hidden novalidate
address@hidden @option{--no-validate} @tab @code{novalidate}
address@hidden NUMBER_FOOTNOTES
address@hidden @option{--number-footnotes} @tab @code{NUMBER_FOOTNOTES}
address@hidden NUMBER_SECTIONS
address@hidden @option{--number-sections} @tab @code{NUMBER_SECTIONS}
address@hidden NODE_FILES
address@hidden @option{--node-files} @tab @code{NODE_FILES}
address@hidden OUT
address@hidden OUTFILE
address@hidden SUBDIR
address@hidden @option{--output} @tab @code{OUT}, @code{OUTFILE},
+ @code{SUBDIR}
address@hidden paragraphindent
address@hidden @option{--paragraph-indent} @tab @code{paragraphindent}
address@hidden SILENT
address@hidden @option{--silent} @tab @code{SILENT}
address@hidden SPLIT
address@hidden @option{--split} @tab @code{SPLIT}
address@hidden SPLIT_SIZE
address@hidden @option{--split-size} @tab @code{SPLIT_SIZE}
address@hidden TRANSLITERATE_FILE_NAMES
address@hidden @option{--transliterate-file-names} @tab
@code{TRANSLITERATE_FILE_NAMES}
address@hidden VERBOSE
address@hidden @option{--verbose} @tab @code{VERBOSE}
address@hidden multitable
+
+Setting such a customization variable to a value @samp{foo} is
+essentially the same as specifying the @address@hidden if the
+option takes an argument, or @address@hidden if not.
+
address@hidden TEXINFO_OUTPUT_FORMAT
+In addition, the customization variable @code{TEXINFO_OUTPUT_FORMAT}
+allows specifying what @code{makeinfo} outputs, either one of the usual
+output formats that can be specified with options, or various other
+forms:
+
address@hidden @samp
address@hidden docbook
address@hidden dvi
address@hidden dvipdf
address@hidden html
address@hidden info
address@hidden pdf
address@hidden plaintext
address@hidden ps
address@hidden xml
+These correspond to the command-line options (and
address@hidden environment variable values) of the same
+name. @xref{Invoking @t{texi2any}}.
+
address@hidden debugcount
+Instead of generating a regular output format, output the count of
+bytes and lines obtained when converting to Info, and other information.
+
address@hidden debugtree
address@hidden tree representation, for debugging
address@hidden debugging document, with tree representation
+Instead of generating a regular output format, output a text representation
+of the tree obtained by parsing the input texinfo document.
+
address@hidden parse
+Do only Texinfo source parsing; there is no output.
+
address@hidden plaintexinfo
+Output the Texinfo source with all the macros, @code{@@include} and
address@hidden@@address@hidden@}} expanded. This is similar to setting
address@hidden, but instead of being output in addition to
+the normal conversion, output of Texinfo is the main output.
+
address@hidden rawtext
address@hidden raw text output
+Output raw text, with minimal formatting. For example, footnotes are
+ignored and there is no paragraph filling. This is used by the parser
+for file names and copyright text in HTML comments, for example.
+
address@hidden structure
+Do only Texinfo source parsing and determination of the document
+structure; there is no output.
+
address@hidden texinfosxml
address@hidden SXML output
address@hidden S-expressions, output format
+Output the document in TexinfoSXML representation, a syntax for
+writing XML data using Lisp S-expressions.
+
address@hidden textcontent
address@hidden spell checking
address@hidden word counting
address@hidden detexinfo
address@hidden stripping Texinfo commands
+Output the text content only, stripped of commands; this is useful for
+spell checking or word counting, for example. The trivial
address@hidden script setting this is in the @file{util} directory
+of the Texinfo source as an example. It's one line:
+
address@hidden
+exec texi2any -c TEXINPUT_OUTPUT_FORMAT=textcontent "$@@"
address@hidden example
address@hidden ftable
+
+
address@hidden HTML Customization Variables
address@hidden HTML Customization Variables
+
+This table gives the customization variables which apply to HTML
+output only. A few other customization variable apply to both HTML
+and other output formats; those are given in the next section.
+
address@hidden @code
address@hidden AVOID_MENU_REDUNDANCY
+For address@hidden If set, and the menu entry and menu description are the
+same, then do not print the menu description; default false.
+
address@hidden AFTER_BODY_OPEN
+For address@hidden If set, the corresponding text will appear at the
+beginning of each HTML file; default unset.
+
address@hidden AFTER_ABOUT
+For HTML, when an About-element is output. If set, the corresponding
+text will appear at the end of the About element; default unset.
+
address@hidden AFTER_OVERVIEW
address@hidden AFTER_TOC_LINES
+For address@hidden If set, the corresponding text is output after the short
+table of contents for @code{AFTER_OVERVIEW} and after the table of
+contents for @code{AFTER_TOC_LINES}; otherwise, a default string is
+used. At the time of writing, a @code{</div>} element is closed.
+
+In general, you should set @code{BEFORE_OVERVIEW} if
address@hidden is set, and you should set
address@hidden if @code{AFTER_TOC_LINES} is set.
+
+
address@hidden BASEFILENAME_LENGTH
+For address@hidden The maximum length of the base filenames; default 245.
+Changing this would make cross-manual references to such long node
+names invalid (@pxref{HTML Xref Link Basics}).
+
address@hidden BEFORE_OVERVIEW
address@hidden BEFORE_TOC_LINES
+For address@hidden If set, the corresponding text is output before the short
+table of contents for @code{BEFORE_OVERVIEW} and before the table of
+contents for @code{BEFORE_TOC_LINES}, otherwise a default string is
+used. At the time of writing, a @code{<div ...>} element is opened.
+
+In general you should set @code{AFTER_OVERVIEW} if
address@hidden is set, and you should set
address@hidden if @code{BEFORE_TOC_LINES} is set.
+
+
address@hidden BIG_RULE
+For address@hidden Rule used after and before the top element and before
+special elements, but not for footers and headers; default
address@hidden<hr>}.
+
address@hidden BODYTEXT
address@hidden @code{<body>} text, customizing
+For HTML, the text appearing in @code{<body>}. By default, set
+automatically, taking into account the document language
+(@address@hidden@@documentlanguage}}).
+
address@hidden CASE_INSENSITIVE_FILENAMES
+For address@hidden Construct output file names as if the filesystem were case
+insensitive (@pxref{HTML Splitting}); default false.
+
address@hidden CHAPTER_HEADER_LEVEL
+For address@hidden Header formatting level used for chapter level sectioning
+commands; default @samp{2}.
+
address@hidden CHECK_HTMLXREF
+For address@hidden Check that manuals which are the target of external
+cross references (@pxref{Four and Five Arguments}) are present in
address@hidden (@pxref{HTML Xref Configuration}); default false.
+
address@hidden COMPLEX_FORMAT_IN_TABLE
+For address@hidden If set, use tables for indentation of complex formats;
default
+false.
+
address@hidden CSS_LINES
+For address@hidden CSS output, automatically determined by default
(@pxref{HTML CSS}).
+
address@hidden DATE_IN_HEADER
+For address@hidden Put the document generation date in the header; off by
default.
+
address@hidden DEF_TABLE
+For address@hidden If set, a @code{<table>} construction for @code{@@deffn}
+and similar @@-commands is used (looking more like the @TeX{} output),
+instead of definition lists; default false.
+
address@hidden DEFAULT_RULE
+For address@hidden Rule used between element, except before and after the
+top element, and before special elements, and for footers and headers;
+default @code{<hr>}.
+
address@hidden DO_ABOUT
+For address@hidden If set to 0 never do an About special element;
+if set to 1 always do an About special element;
+default 0.
address@hidden @xref{Output Elements Defined}.
+
address@hidden EXTERNAL_DIR
+For address@hidden Base directory for external manuals; default none. It is
+better to use the general external cross reference mechanism
+(@pxref{HTML Xref Configuration}) than this variable.
+
address@hidden EXTRA_HEAD
+For address@hidden Additional text appearing within @code{<head>}; default
unset.
+
address@hidden FOOTNOTE_END_HEADER_LEVEL
+For address@hidden Header formatting level used for the footnotes header with
+the `end' footnotestyle; default @samp{4}. @xref{Footnote Styles}.
+
address@hidden FOOTNOTE_SEPARATE_HEADER_LEVEL
+For address@hidden Header formatting level used for the footnotes header with
+the `separate' footnotestyle; default @samp{4}. @xref{Footnote
+Styles}.
+
address@hidden FRAMES
+For address@hidden If set, a file describing the frame layout is generated,
+together with a file with the short table of contents; default false.
+
address@hidden FRAMESET_DOCTYPE
+For address@hidden Same as DOCTYPE, but for the file containing the frame
+description.
+
address@hidden HEADER_IN_TABLE
+For address@hidden Use tables for header formatting rather than a simple
address@hidden<div>} element; default false.
+
address@hidden ICONS
+For address@hidden Use icons for the navigation panel; default false.
+
address@hidden IMAGE_LINK_PREFIX
+For address@hidden If set, the associated value is prepended to the image file
+links; default unset.
+
address@hidden INLINE_CSS_STYLE
+For address@hidden Put CSS directly in HTML elements rather than at the
+beginning of the output; default false.
+
address@hidden KEEP_TOP_EXTERNAL_REF
+For address@hidden If set, do not ignore @samp{Top} as the first
+argument for an external ref to a manual, as is done by default.
address@hidden Node Naming}.
+
address@hidden L2H
+For address@hidden If set, @command{latex2html} is used to convert
@code{@@math}
+and @code{@@tex} sections; default false. Best used with @option{--iftex}.
+
address@hidden L2H_CLEAN
+(Relevant only if @code{L2H} is set.) If set, the intermediate files
+generated in relation with @command{latex2html} are removed; default
+true.
+
address@hidden L2H_FILE
+(Relevant only if @code{L2H} is set.) If set, the given file is used
+as @command{latex2html}'s init file; default unset.
+
address@hidden L2H_HTML_VERSION
+(Relevant only if @code{L2H} is set.) The HTML version used in the
address@hidden call; default unset.
+
address@hidden L2H_L2H
+(Relevant only if @code{L2H} is set.) The program invoked as
address@hidden; default is @code{latex2html}.
+
address@hidden L2H_SKIP
+(Relevant only if @code{L2H} is set.) If set to a true value, the
+actual call to @command{latex2html} is skipped; previously generated
+content is reused instead. If set to 0, the cache is not used at all.
+If set to @samp{undef}, the cache is used for as many @TeX{} fragments as
+possible and for any remaining the command is run. The default is
address@hidden
+
address@hidden L2H_TMP
+(Relevant only if @code{L2H} is set.) Set the directory used for
+temporary files. None of the file name components in this directory
+name may start with @samp{.}; otherwise, @command{latex2html} will
+fail (because of @command{dvips}). The default is the empty string,
+which means the current directory.
+
address@hidden MAX_HEADER_LEVEL
+For address@hidden Maximum header formatting level used (higher header
+formatting level numbers correspond to lower sectioning levels);
+default @samp{4}.
+
address@hidden MENU_SYMBOL
+For address@hidden Symbol used in front of menu entries when node names are
used
+for menu entries formatting; default @samp{•}.
+
address@hidden MONOLITHIC
+For address@hidden Output only one file including the table of contents. Set
+by default, but only relevant when the output is not split.
+
address@hidden NO_CSS
+For address@hidden Do not use CSS; default false. @xref{HTML CSS}.
+
address@hidden NODE_FILE_EXTENSION
+For address@hidden Extension for node files if @code{NODE_FILENAMES} is set;
+default @samp{html}.
+
address@hidden PRE_ABOUT
+For HTML, when an About element is output. If set to a text string,
+this text will appear at the beginning of the About element. If set
+to a reference on a subroutine, the result of the subroutine call will
+appear at the beginning of the About element. If not set (the
+default), default text is used.
+
address@hidden PRE_BODY_CLOSE
+For address@hidden If set, the given text will appear at the footer of each
+HTML file; default unset.
+
address@hidden PROGRAM_NAME_IN_FOOTER
+For address@hidden If set, output the program name and miscellaneous related
+information in the page footers; default false.
+
address@hidden SHORTEXTN
+For address@hidden If set, use @samp{.htm} as extension; default false.
+
address@hidden SHOW_TITLE
+For address@hidden If set, output the title at the beginning of the document;
+default true.
+
address@hidden SIMPLE_MENU
+For address@hidden If set, use a simple preformatted style for the menu,
+instead of breaking down the different parts of the menu; default false.
address@hidden Parts}.
+
address@hidden TOC_LINKS
+For address@hidden If set, links from headings to toc entries are created;
+default false.
+
address@hidden TOP_FILE
+This file name may be used for the top-level file. The extension is
+set appropriately, if necessary. This is used to override the default,
+and is, in general, only taken into account when output is split, and
+for address@hidden
+
address@hidden TOP_NODE_FILE
+For address@hidden File name used for the Top node, if @code{NODE_FILENAMES}
+is set; default is @code{index}.
+
address@hidden TOP_NODE_FILE_TARGET
+For address@hidden File name used for the Top node in cross references;
+default is @code{index}.
+
address@hidden TOP_NODE_UP_URL
+For address@hidden The url used for the Up pointer of the Top node; default
address@hidden, meaning no link is generated.
+
address@hidden USE_ACCESSKEY
address@hidden @code{accesskey}, customization variable for
+For address@hidden Use @code{accesskey} in cross references; default true.
+
address@hidden USE_ISO
+For address@hidden Use entities for doubled single-quote characters
+(@pxref{Inserting Quotation Marks}), and @samp{---} and @samp{--}
+(@pxref{Conventions}); default true.
+
address@hidden USE_LINKS
address@hidden @code{<link>} HTML tag, in @code{<head>}
address@hidden @code{<head>} HTML tag, and @code{<link>}
+For address@hidden Generate @code{<link>} elements in the HTML @code{<head>}
+output; default true.
+
address@hidden USE_REL_REV
+For address@hidden Use @code{rel} in cross references; default true.
+
address@hidden VERTICAL_HEAD_NAVIGATION
+For address@hidden If set, a vertical navigation panel is used; default false.
+
address@hidden WORDS_IN_PAGE
address@hidden Navigation panel, bottom of page
+For HTML, with output split at nodes. Specifies the approximate
+minimum page length at which a navigation panel is placed at the
+bottom of a page. To avoid ever having the navigation buttons at the
+bottom of a page, set this to a sufficiently large number. The
+default is 300.
+
address@hidden XREF_USE_FLOAT_LABEL
+For address@hidden If set, for the float name in cross references, use the
+float label instead of the type followed by the float number
+(@address@hidden@@float}}). The default is off.
+
address@hidden XREF_USE_NODE_NAME_ARG
+For address@hidden Only relevant for cross reference commands with no cross
+reference name (second argument). If set address@hidden, use the node name
+(first) argument in cross reference @@-commands for the text displayed
+as the hyperlink. If set address@hidden, use the node name if
address@hidden is set, otherwise the section name. If set to
address@hidden, use the first argument in preformatted environments,
+otherwise use the node name or section name depending on
address@hidden The default is @samp{undef}.
+
address@hidden vtable
+
+
address@hidden Other Customization Variables
address@hidden Other Customization Variables
+
+This table gives the remaining customization variables, which apply to
+multiple formats, or affect global behavior, or otherwise don't fit
+into the categories of the previous sections.
+
address@hidden @code
address@hidden CLOSE_QUOTE_SYMBOL
+When a closing quote is needed, use this character; default @code{’}
+in HTML, @code{’} in Docbook. The default for Info is the same
+as @code{OPEN_QUOTE_SYMBOL} (see below).
+
address@hidden @item COMPLETE_IMAGE_PATHS
address@hidden If set, the image files are computed to be relative from the
document
address@hidden directory to the source manual directory, and then to the image.
+
address@hidden CPP_LINE_DIRECTIVES
+Recognize @code{#line} directives in a ``preprocessing'' pass
+(@pxref{External Macro Processors}); on by default.
+
address@hidden DEBUG
+If set, debugging output is generated; default is off (zero).
address@hidden The integer value specifies what kinds of debugging output are
address@hidden generated. It is a bitmask. Setting it to 255 ensures having
all
address@hidden available debugging output.
+
address@hidden DOCTYPE
address@hidden SystemLiteral
+For Docbook, HTML, address@hidden 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
+and address@hidden
+
address@hidden DUMP_TEXI
+For debugging. If set, no conversion is done, only parsing and macro
+expansion. If the option @option{--macro-expand} is set, the Texinfo
+source is also expanded to the corresponding file. Default false.
+
address@hidden DUMP_TREE
+For debugging. If set, the tree constructed upon parsing a Texinfo
+document is output to standard error; default false.
+
address@hidden ENABLE_ENCODING_USE_ENTITY
+For HTML, address@hidden If @option{--enable-encoding} is set, and there is an
+entity corresponding with the letter or the symbol being output,
+prefer the entity. Set by default for HTML, but not XML.
+
address@hidden EXTERNAL_CROSSREF_SPLIT
+For cross references to other manuals, this determines if the other
+manual is considered to be split or monolithic. By default, it is set
+based on the value of @code{SPLIT}. @xref{HTML Xref}, and @pxref{HTML
+Xref Configuration}.
+
address@hidden EXTENSION
+The extension added to the output file name. The default is different
+for each output format.
+
address@hidden FIX_TEXINFO
+For ``plain Texinfo'' (see the @code{PLAINTEXINFO} item). If set to
+false, the resulting Texinfo does not have all errors corrected, such
+as missing @samp{@@end}; default true. This variable is only
+relevant when expanding Texinfo; other converters always try to
+output something sane even if the input is erroneous.
+
address@hidden @item IDX_SUMMARY
address@hidden If set, for each @code{@@printindex} a file named
address@hidden @address@hidden@var{idxname}.idx} is created, containing lines of
address@hidden the form:
address@hidden
address@hidden @example
address@hidden @var{key} @var{reference}
address@hidden @end example
address@hidden
address@hidden @noindent sorted alphabetically (case matters).
+
address@hidden IGNORE_BEFORE_SETFILENAME
+If set, begin outputting at @code{@@setfilename}, if
address@hidden@@setfilename} is present; default true.
+
address@hidden IGNORE_SPACE_AFTER_BRACED_COMMAND_NAME
+If set, spaces are ignored after an @@-command that takes braces.
+Default on, matching the @TeX{} behavior.
+
address@hidden INDEX_ENTRY_COLON
+Symbol used between the index entry and the associated node or section;
+default @samp{:}.
+
address@hidden INLINE_CONTENTS
+For address@hidden If set, output the contents where the @code{@@contents} and
+similar @@-commands are located; default true. This is Ignored if
address@hidden@@set*contentsaftertitlepage} is set (@pxref{Contents}).
+
address@hidden INLINE_INSERTCOPYING
+If set, @code{@@insertcopying} is replaced by the @code{@@copying}
+content (@address@hidden@@copying}}) as if @code{@@insertcopying} were a
+user-defined macro; default false.
+
address@hidden INPUT_ENCODING_NAME
+Normalized encoding name suitable for output. Should be a usable
+charset name in HTML, typically one of the preferred IANA encoding
+names. You should not need to use this variable, since it is set by
address@hidden@@documentencoding} (@address@hidden@@documentencoding}}).
+
address@hidden INPUT_PERL_ENCODING
+Perl encoding used to process the Texinfo source. You should not need
+to use that variable, since it is set by @code{@@documentencoding}
+(@address@hidden@@documentencoding}}).
+
address@hidden MACRO_BODY_IGNORES_LEADING_SPACE
+Ignore white space at the beginning of user defined macro body line,
+mimicking a @TeX{} limitation (@pxref{Macro Details}). Default off.
+
address@hidden MAX_MACRO_CALL_NESTING
+The maximal number of recursive calls of @@-commands defined through
address@hidden@@rmacro}; default 100000. The purpose of this variable is to
+avoid infinite recursions.
+
address@hidden MENU_ENTRY_COLON
+Symbol used between the menu entry and the description; default
address@hidden:}.
+
address@hidden 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.
+The default is false.
+
address@hidden NODE_FILENAMES
+If set, node names are used to construct file names. By default, it
+is set if the output is split by node, or if @code{NODE_FILES} is set
+and the output is split in any way.
+
address@hidden NODE_NAME_IN_INDEX
+If set, use node names in index entries, otherwise prefer section names;
+default true.
+
address@hidden NODE_NAME_IN_MENU
+If set, use node names in menu entries, otherwise prefer section names;
+default true.
+
address@hidden OPEN_QUOTE_SYMBOL
+When an opening quote is needed, e.g., for @samp{@@samp} output, use
+the specified character; default @code{‘} for HTML,
address@hidden‘} for Docbook. For Info, the default depends on the
+enabled document encoding (@address@hidden@@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
+on modern systems. If the document encoding is Unicode, the Info
+output uses a Unicode left quote.
+
address@hidden OUTPUT_ENCODING_NAME
+Normalized encoding name used for output files. Should be a usable
+charset name in HTML, typically one of the preferred IANA encoding
+names. By default, if an input encoding is set (typically through
address@hidden@@documentencoding} or @code{INPUT_ENCODING_NAME}), this
+information is used to set the output encoding name. If no input
+encoding is specified, the default output encoding name may be set by
+the output format. In particular, the XML-based formats use
address@hidden for @code{OUTPUT_ENCODING_NAME} if the encoding is not
+otherwise specified. @address@hidden@@documentencoding}}.
+
address@hidden OVERVIEW_LINK_TO_TOC
+If set, the cross references in the Overview link to the corresponding
+Table of Contents entries; default true.
+
address@hidden PACKAGE
address@hidden PACKAGE_VERSION
address@hidden PACKAGE_AND_VERSION
address@hidden PACKAGE_URL
address@hidden PACKAGE_NAME
+The implementation's short package name, package version, package name
+and version concatenated, package url, and full package name,
+respectively. By default, these variables are all set through
+Autoconf, Automake, and @code{configure}.
+
address@hidden PREFIX
+The output file prefix, which is prepended to some output file names.
+By default it is set by @code{@@setfilename} or from the input file
+(@address@hidden@@setfilename}}). How this value is used depends on the
+value of other customization variables or command line options, such
+as whether the output is split and @code{NODE_FILENAMES}. The default
+is unset.
+
address@hidden PROGRAM
+Name of the program used. By default, it is set to the name of the
+program launched, with a trailing @samp{.pl} removed.
+
address@hidden RENAMED_NODES_FILE
+If set, use the value for the renamed nodes description file. If not
+set, the file is @address@hidden
address@hidden Xref Link Preservation}.
+
address@hidden RENAMED_NODES_REDIRECTIONS
+If set, create redirection files for renamed nodes. Set by default
+when generating address@hidden
+
address@hidden SHOW_MENU
address@hidden --no-headers
+If set, Texinfo menus are output. By default, it is set unless
+generating Docbook or if @option{--no-headers} is specified.
+
address@hidden SORT_ELEMENT_COUNT
address@hidden texi-elements-by-size
address@hidden Longest nodes, finding
address@hidden Sorting nodes by size
+If set, the name of a file to which a list of elements (nodes or
+sections, depending on the output format) is dumped, sorted by the
+number of lines they contain after removal of @@-commands; default
+unset. This is used by the program @code{texi-elements-by-size} in
+the @file{util/} directory of the Texinfo source distribution
+(@pxref{texi-elements-by-size}).
+
address@hidden SORT_ELEMENT_COUNT_WORDS
+When dumping the elements-by-size file (see preceding item), use word
+counts instead of line counts; default false.
+
address@hidden @item SPLIT_INDEX
address@hidden For address@hidden If set, the output is split, and the output
from
address@hidden @code{@@printindex} happens in a sectioning element at the level
of
address@hidden splitting, then split index pages at the next letter after they
have
address@hidden more than that many entries. If set to 0, no index splitting.
+
address@hidden TEST
+If set to true, some variables which are normally dynamically
+generated anew for each run (date, program name, version) are set to
+fixed and given values. This is useful to compare the output to a
+reference file, as is done for the tests. The default is false.
+
address@hidden TEXI2DVI
+Name of the command used to produce PostScript, PDF, and DVI; default
address@hidden @address@hidden Printed Output}.
+
address@hidden TEXI2HTML
address@hidden compatibility, with @command{texi2html}
+Generate HTML and try to be as compatible as possible with
address@hidden; default false.
+
address@hidden TEXINFO_COLUMN_FOR_DESCRIPTION
+Used with the @code{indent_menu_descriptions} tree transformation,
+described below; default 32 (matching
address@hidden in Emacs)).
+
address@hidden TEXINFO_DTD_VERSION
+For address@hidden Version of the DTD used in the XML output preamble. The
+default is set based on a variable in @file{configure.ac}.
+
address@hidden TEXTCONTENT_COMMENT
+For stripped text content output (i.e., when
address@hidden is set to @code{textcontent}). If set,
+also output comments. Default false.
+
address@hidden TOP_NODE_UP
+Up node for the Top node; default @samp{(dir)}.
+
address@hidden TREE_TRANSFORMATIONS
+The associated value is a comma separated list of transformations that
+can be applied to the Texinfo tree prior to outputting the result. If
+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
address@hidden for HTML and Docbook output.
+Here's an example of updating the master menu in a document:
+
address@hidden
+makeinfo \
+ -c TREE_TRANSFORMATIONS=regenerate_master_menu \
+ -c PLAINTEXINFO=1 \
+ mydoc.texi \
+ -o /tmp/out
address@hidden example
+
address@hidden (Caveat: Since @code{PLAINTEXINFO} output does expand
+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.)
+
+The following transformations are currently supported (many are used
+in the @code{pod2texi} utility distributed with Texinfo):
+
address@hidden @samp
address@hidden complete_tree_nodes_menus
+Add menu entries or whole menus for nodes associated with sections of
+any level, based on the sectioning tree.
+
address@hidden fill_gaps_in_sectioning
+Adds empty @code{@@unnumbered} in a tree to fill gaps in sectioning.
+For example, an @code{@@unnumberedsec} will be inserted if an
address@hidden@@chapter} is followed by an @code{@@subsection}.
+
address@hidden indent_menu_descriptions
+Reformat menus so that descriptions start at column
address@hidden
+
address@hidden insert_nodes_for_sectioning_commands
+Insert nodes for sectioning commands lacking a corresponding node.
+
address@hidden move_index_entries_after_items
+In @code{@@enumerate} and @code{@@itemize}, move index entries
+appearing just before an @code{@@item} to just after the
address@hidden@@item}. Comment lines between index entries are moved too. As
+mentioned, this is always done for HTML and Docbook output.
+
address@hidden regenerate_master_menu
+Update the Top node master menu, either replacing the (first)
address@hidden@@detailmenu} in the Top node menu, or creating it at the end of
+the Top node menu.
+
address@hidden simple_menu
+Mostly the same as @code{SIMPLE_MENU}: use a simple preformatted style
+for the menu. It differs from setting @code{SIMPLE_MENU} in that
address@hidden only has an effect in HTML output.
+
address@hidden ftable
+
address@hidden USE_NODES
+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.
+
address@hidden USE_NODE_TARGET
+If set, use the node associated with a section for the section target
+in cross references; default true.
+
address@hidden USE_NUMERIC_ENTITY
+For HTML and address@hidden If set, use numeric entities instead of ASCII
+characters when there is no named entity. By default, set to true for
+HTML.
+
address@hidden USE_UP_NODE_FOR_ELEMENT_UP
+Fill in up sectioning direction with node direction when there is no
+sectioning up direction. In practice this can only happen when there
+is no @@top section. Not set by default.
+
address@hidden USE_SETFILENAME_EXTENSION
+Default is on for Info, off for other output. If set, use exactly
+what @code{@@setfilename} gives for the output file name, including
+the extension. You should not need to explicitly set this variable.
+
address@hidden USE_TITLEPAGE_FOR_TITLE
+Use the full @code{@@titlepage} as the title, not a simple title string;
+default false.
+
address@hidden USE_UNIDECODE
address@hidden Text::Unidecode
+If set to false, do not use the @code{Text::Unidecode} Perl module to
+transliterate more characters; default true.
+
address@hidden vtable
+
+
address@hidden Internationalization of Document Strings
address@hidden Internationalization of Document Strings
+
address@hidden I18n, of document strings
address@hidden Internationalization of document strings
address@hidden Document strings, internationalization of
address@hidden Output document strings, internationalization of
address@hidden Translating strings in output documents
+
address@hidden documentlanguage @r{customization variable}
address@hidden writes fixed strings into the output document at
+various places: cross references, page footers, the help page,
+alternate text for images, and so on. The string chosen depends on
+the value of the @code{documentlanguage} at the time of the string
+being output (@address@hidden@@documentlanguage}}, for the Texinfo
+command interface).
+
address@hidden libintl-perl @r{Gettext implementation}
+The Gettext framework is used for those strings (@pxref{Top,,,
+gettext, Gettext}). The @code{libintl-perl} package is used as the
address@hidden implementation; more specifically, the pure Perl
+implementation is used, so Texinfo can support consistent behavior
+across all platforms and installations, which would not otherwise be
+possible. @code{libintl-perl} is included in the Texinfo distribution
+and always installed, to ensure that it is available if needed. It is
+also possible to use the system @code{gettext} (the choice can be made
+at build-time).
+
address@hidden texinfo_document @r{Gettext domain}
address@hidden Perl format strings for translation
+The Gettext domain @samp{texinfo_document} is used for the strings.
+Translated strings are written as Texinfo, and may include
+@@-commands. In translated strings, the varying parts of the string
+are not usually denoted by @code{%s} and the like, but by
address@hidden@address@hidden (This convention is common for @code{gettext} in
+Perl and is fully supported in GNU Gettext; @pxref{perl-format,, Perl
+Format Strings, gettext, GNU Gettext}.) For example, in the
+following, @address@hidden@}} will be replaced by the section name:
+
address@hidden
+see @address@hidden
address@hidden example
+
+These Perl-style brace format strings are used for two reasons: first,
+changing the order of @code{printf} arguments is only available since
address@hidden; second, and more importantly, the order of arguments
+is unpredictable, since @@-command expansion may lead to different
+orders depending on the output format.
+
+The expansion of a translation string is done like this:
+
address@hidden
address@hidden First, the string is translated. The locale
+is @var{@@address@hidden@var{@@documentencoding}.
+
address@hidden @code{us-ascii} encoding, and translations
+If the @var{@@documentlanguage} has the form @samp{ll_CC}, that is
+tried first, and then just @samp{ll}. If that does not exist, and the
+encoding is not @code{us-ascii}, then @code{us-ascii} is tried.
+
+The idea is that if there is a @code{us-ascii} encoding, it means that
+all the characters in the charset may be expressed as @@-commands.
+For example, there is a @code{fr.us-ascii} locale that can accommodate
+any encoding, since all the address@hidden characters have associated
+@@-commands. On the other hand, Japanese has only a translation
address@hidden, since there are no @@-commands for Japanese
+characters.
+
address@hidden Next, the string is expanded as Texinfo, and converted.
+The arguments are substituted; for example, @address@hidden@}} is
+replaced by the corresponding actual argument.
+
address@hidden enumerate
+
+In the following example, @address@hidden@}}, @address@hidden@}}
+and @address@hidden@}} are the arguments of the string. Since they
+are used in @code{@@uref}, their order is not predictable.
address@hidden@address@hidden, @address@hidden@}} and @address@hidden@}} are
+substituted after the expansion:
+
address@hidden
+Generated on @@address@hidden@address@hidden@} using
+@@address@hidden@address@hidden, @@address@hidden@address@hidden@address@hidden
address@hidden example
+
+This approach is admittedly a bit complicated. Its usefulness is that
+it supports having translations available in different encodings for
+encodings which can be covered by @@-commands, and also specifying how
+the formatting for some commands is done, independently of the output
+format---yet still be language-dependent. For example, the
address@hidden@@pxref} translation string can be like this:
+
address@hidden
+see @address@hidden section address@hidden@}\' in
@@address@hidden@address@hidden@}
address@hidden example
+
address@hidden
+which allows for specifying a string independently of the output
+format, while nevertheless with rich formatting it may be translated
+appropriately in many languages.
+
+
address@hidden Invoking @t{pod2texi}
address@hidden Invoking @t{pod2texi}:
+
address@hidden pod2texi
address@hidden Invoking @code{pod2texi}
address@hidden POD, converting to Texinfo
address@hidden Perl POD, converting to Texinfo
+
+The @code{pod2texi} program translates Perl pod documentation file(s)
+to Texinfo. There are two basic modes of operation: generating a
+standalone manual from each input pod, or (if @code{--base-level=1} or
+higher is given) generating Texinfo subfiles suitable for use
+with @code{@@include}.
+
+Although ordinarily this documentation in the Texinfo manual would be
+the best place to look, in this case we have documented all the
+options and examples in the @code{pod2texi} program itself, since it
+may be useful outside of the rest of Texinfo. Thus, please see the
+output of @code{pod2texi --help}, the version on the web at
address@hidden://www.gnu.org/software/texinfo/manual/pod2texi.html}, etc.
+
+For an example of using @code{pod2texi} to make Texinfo out of the
+Perl documentation itself, see
address@hidden://svn.savannah.gnu.org/viewvc/trunk/contrib/perldoc-all/?root=texinfo,
address@hidden/perldoc-all}} in the Texinfo source distribution (the
+output is available at @url{http://www.gnu.org/software/perl/manual}).
+
+
address@hidden @t{texi2html}
address@hidden @code{texi2html}: Ancestor of @code{texi2any}
+
address@hidden texi2html
+
address@hidden Cons, Lionel
+Conceptually, the @command{texi2html} program is the parent of today's
address@hidden program. @command{texi2html} was developed
+independently, originally by Lionel Cons in 1998; at the time,
address@hidden could not generate address@hidden Many other people
+contributed to @command{texi2html} over the years.
+
+The present @command{texi2any} uses little of the actual code of
address@hidden, and has quite a different basic approach to the
+implementation (namely, parsing the Texinfo document into a tree), but
+still, there is a family resemblance.
+
+By design, @command{texi2any} supports nearly all the features of
address@hidden in some way. However, we did not attempt to
+maintain strict compatibility, so no @command{texi2html} executable is
+installed by the Texinfo package. An approximation can be run with an
+invocation like this (available as @file{util/texi2html} in the
+Texinfo source):
+
address@hidden
+texi2any --set-customization-variable TEXI2HTML=1 ...
address@hidden example
+
address@hidden but, to emphasize, this is @emph{not} a drop-in replacement
+for the previous @command{texi2html}. Here are the biggest differences:
+
address@hidden @bullet
address@hidden Most blatantly, the command line options of @command{texi2html}
+are now customization variables, for the most part. A table of
+approximate equivalents is given below.
+
address@hidden The program-level customization API is very different in
address@hidden
+
address@hidden Indices cannot be split.
+
address@hidden Translated strings cannot be customized; we hope to introduce
+this feature in @command{texi2any} in the future.
+
address@hidden itemize
+
+Aside from the last, we do not intend to reimplement these
+differences. Therefore, the route forward for authors is alter
+manuals and build processes as necessary to use the new features and
+methods of @command{texi2any}. The @command{texi2html} maintainers
+(one of whom is the principal author of @command{texi2any}) do not
+intend to make further releases.
+
address@hidden Options of @command{texi2html}
address@hidden Command-line options of @command{texi2html}
+Here is the table showing @command{texi2html} options and
+corresponding @command{texi2any} customization variables.
address@hidden (@pxref{texi2any Output Customization,, @command{texi2any} Output
address@hidden Customization}).
+
address@hidden address@hidden address@hidden
address@hidden @option{--toc-links} @tab @code{TOC_LINKS}
address@hidden @option{--short-ext} @tab @code{SHORTEXTN}
address@hidden @option{--prefix} @tab @code{PREFIX}
address@hidden @option{--short-ref} @tab @code{SHORT_REF}
address@hidden @option{--idx-sum} @tab @code{IDX_SUMMARY}
address@hidden @option{--def-table} @tab @code{DEF_TABLE}
address@hidden @option{--ignore-preamble-text} @tab @code{IGNORE_PREAMBLE_TEXT}
address@hidden @option{--html-xref-prefix} @tab @code{EXTERNAL_DIR}
address@hidden @option{--l2h} @tab @code{L2H}
address@hidden @option{--l2h-l2h} @tab @code{L2H_L2H}
address@hidden @option{--l2h-skip} @tab @code{L2H_SKIP}
address@hidden @option{--l2h-tmp} @tab @code{L2H_TMP}
address@hidden @option{--l2h-file} @tab @code{L2H_FILE}
address@hidden @option{--l2h-clean} @tab @code{L2H_CLEAN}
address@hidden @option{--use-nodes} @tab @code{USE_NODES}
address@hidden @option{--monolithic} @tab @code{MONOLITHIC}
address@hidden @option{--top-file} @tab @code{TOP_FILE}
address@hidden @option{--toc-file} @tab @code{TOC_FILE}
address@hidden @option{--frames} @tab @code{FRAMES}
address@hidden @option{--menu} @tab @code{SHOW_MENU}
address@hidden @option{--debug} @tab @code{DEBUG}
address@hidden @option{--doctype} @tab @code{DOCTYPE}
address@hidden @option{--frameset-doctype} @tab @code{FRAMESET_DOCTYPE}
address@hidden @option{--test} @tab @code{TEST}
address@hidden multitable
+
address@hidden @file{texi2oldapi.texi}, for @command{texi2any}
+Finally, any @command{texi2html} users seeking more detailed
+information can check the draft file @file{doc/texi2oldapi.texi} in
+the Texinfo source repository. It consists mainly of very rough
+notes, but may still be useful to some.
+
+
address@hidden Creating and Installing Info Files
address@hidden Creating and Installing Info Files
+
+This chapter describes how to create and install Info files.
address@hidden Files}, for general information about the file format
+itself.
+
address@hidden
+* Creating an Info File::
+* Installing an Info File::
address@hidden menu
+
+
address@hidden Creating an Info File
address@hidden Creating an Info File
address@hidden Creating an Info file
address@hidden Info, creating an online file
address@hidden Formatting a file for Info
+
address@hidden is a program that converts a Texinfo file into an Info
+file, HTML file, or plain text. @code{texinfo-format-region} and
address@hidden are GNU Emacs functions that convert
+Texinfo to Info.
+
+For information on installing the Info file in the Info system,
address@hidden an Info File}.
+
address@hidden
+* @t{makeinfo} Advantages:: @code{makeinfo} provides better error
checking.
+* @t{makeinfo} in Emacs:: How to run @code{makeinfo} from Emacs.
+* @t{texinfo-format} commands:: Two Info formatting commands written
+ in Emacs Lisp are an alternative
+ to @code{makeinfo}.
+* Batch Formatting:: How to format for Info in Emacs Batch mode.
+* Tag and Split Files:: How tagged and split files help Info
+ to run better.
address@hidden menu
+
+
address@hidden @t{makeinfo} Advantages
address@hidden @code{makeinfo} Advantages
+
address@hidden address@hidden old name
+
+The @code{makeinfo} utility creates an Info file from a Texinfo source
+providing better error messages than either of the Emacs formatting
+commands. We recommend it. The @code{makeinfo} program is
+independent of Emacs. You can run @code{makeinfo} in any of three
+ways: from an operating system shell, from a shell inside Emacs, or by
+typing the @kbd{C-c C-m C-r} or the @kbd{C-c C-m C-b} command in
+Texinfo mode in Emacs.
+
+The @code{texinfo-format-region} and the @code{texinfo-format-buffer}
+commands may be useful if you cannot run @code{makeinfo}.
+
+
address@hidden @t{makeinfo} in Emacs
address@hidden Running @code{makeinfo} Within Emacs
+
address@hidden anchor{makeinfo in address@hidden prev name
address@hidden Running @code{makeinfo} in Emacs
address@hidden @code{makeinfo} inside Emacs
address@hidden Shell, running @code{makeinfo} in
+
+You can run @code{makeinfo} in GNU Emacs Texinfo mode by using either the
address@hidden or the @code{makeinfo-buffer} commands. In
+Texinfo mode, the commands are bound to @kbd{C-c C-m C-r} and @kbd{C-c
+C-m C-b} by default.
+
address@hidden @kbd
address@hidden C-c C-m C-r
address@hidden M-x makeinfo-region
+Format the current region for Info.
address@hidden makeinfo-region
+
address@hidden C-c C-m C-b
address@hidden M-x makeinfo-buffer
+Format the current buffer for Info.
address@hidden makeinfo-buffer
address@hidden table
+
+When you invoke @code{makeinfo-region} the output goes to a temporary
+buffer. When you invoke @code{makeinfo-buffer} output goes to the
+file set with @code{@@setfilename} (@address@hidden@@setfilename}}).
+
+The Emacs @code{makeinfo-region} and @code{makeinfo-buffer} commands
+run the @code{makeinfo} program in a temporary shell buffer. If
address@hidden finds any errors, Emacs displays the error messages in
+the temporary buffer.
+
address@hidden Errors, parsing
address@hidden Parsing errors
address@hidden next-error
+You can parse the error messages by typing @kbd{C-x `}
+(@code{next-error}). This causes Emacs to go to and position the
+cursor on the line in the Texinfo source that @code{makeinfo} thinks
+caused the error. @xref{Compilation, , Running @code{make} or
+Compilers Generally, emacs, The GNU Emacs Manual}, for more
+information about using the @code{next-error} command.
+
+In addition, you can kill the shell in which the @code{makeinfo}
+command is running or make the shell buffer display its most recent
+output.
+
address@hidden @kbd
address@hidden C-c C-m C-k
address@hidden M-x makeinfo-kill-job
address@hidden makeinfo-kill-job
+Kill the current running @code{makeinfo} job
+(from @code{makeinfo-region} or @code{makeinfo-buffer}).
+
address@hidden C-c C-m C-l
address@hidden M-x makeinfo-recenter-output-buffer
address@hidden makeinfo-recenter-output-buffer
+Redisplay the @code{makeinfo} shell buffer to display its most recent
+output.
address@hidden table
+
address@hidden
+(Note that the parallel commands for killing and recentering a @TeX{}
+job are @kbd{C-c C-t C-k} and @kbd{C-c C-t C-l}. @xref{Texinfo Mode
+Printing}.)
+
+You can specify options for @code{makeinfo} by setting the
address@hidden variable with either the @kbd{M-x
+customize} or the @kbd{M-x set-variable} command, or by setting the
+variable in your @file{.emacs} initialization file.
+
+For example, you could write the following in your @file{.emacs} file:
+
address@hidden
address@hidden
+(setq makeinfo-options
+ "--paragraph-indent=0 --no-split
+ --fill-column=70 --verbose")
address@hidden group
address@hidden example
+
address@hidden
address@hidden Writing these three cross references using xref results in
address@hidden three references to the same named manual, which looks strange.
address@hidden
+For more information, see @address@hidden Options}, as well as
+``Easy Customization Interface,'' ``Examining and Setting Variables,''
+and ``Init File'' in @cite{The GNU Emacs Manual}.
address@hidden iftex
address@hidden
+For more information, address@hidden
address@hidden Customization, , Easy Customization Interface, emacs, The GNU
Emacs Manual},@*
address@hidden, , Examining and Setting Variables, emacs, The GNU Emacs
Manual},@*
address@hidden File, , , emacs, The GNU Emacs Manual}, address@hidden
address@hidden@t{makeinfo} Options}.
address@hidden ifnottex
+
+
address@hidden @t{texinfo-format} commands
address@hidden The @address@hidden Commands
+
address@hidden anchor{texinfo-format address@hidden prev name
+
+In GNU Emacs in Texinfo mode, you can format part or all of a Texinfo
+file with the @code{texinfo-format-region} command. This formats the
+current region and displays the formatted text in a temporary buffer
+called @samp{*Info Region*}.
+
+Similarly, you can format a buffer with the
address@hidden command. This command creates a new
+buffer and generates the Info file in it. Typing @kbd{C-x C-s} will
+save the Info file under the name specified by the
address@hidden@@setfilename} line which must be near the beginning of the
+Texinfo file.
+
address@hidden @kbd
address@hidden C-c C-e C-r
address@hidden @code{texinfo-format-region}
address@hidden texinfo-format-region
+Format the current region for Info.
+
address@hidden C-c C-e C-b
address@hidden @code{texinfo-format-buffer}
address@hidden texinfo-format-buffer
+Format the current buffer for Info.
address@hidden table
+
+The @code{texinfo-format-region} and @code{texinfo-format-buffer}
+commands provide you with some error checking, and other functions can
+provide you with further help in finding formatting errors. These
+procedures are described in an appendix; see @ref{Catching Mistakes}.
+However, the @code{makeinfo} program provides better error checking
+(@address@hidden in Emacs}).
+
+
address@hidden Batch Formatting
address@hidden Batch Formatting
address@hidden Batch formatting for Info
address@hidden Info batch formatting
+
+You can format Texinfo files for Info using @code{batch-texinfo-format}
+and Emacs Batch mode. You can run Emacs in Batch mode from any shell,
+including a shell inside of Emacs. (@xref{Command Arguments,,,
+emacs, The GNU Emacs Manual}.)
+
+Here is a shell command to format all the files that end in
address@hidden in the current directory:
+
address@hidden
+emacs -batch -funcall batch-texinfo-format *.texinfo
address@hidden example
+
address@hidden
+Emacs processes all the files listed on the command line, even if an
+error occurs while attempting to format some of them.
+
+Run @code{batch-texinfo-format} only with Emacs in Batch mode as shown;
+it is not interactive. It kills the Batch mode Emacs on completion.
+
address@hidden is convenient if you lack @code{makeinfo}
+and want to format several Texinfo files at once. When you use Batch
+mode, you create a new Emacs process. This frees your current Emacs, so
+you can continue working in it. (When you run
address@hidden or @code{texinfo-format-buffer}, you cannot
+use that Emacs for anything else until the command finishes.)
+
address@hidden Tag and Split Files
address@hidden Tag Files and Split Files
address@hidden Making a tag table automatically
address@hidden Tag table, making automatically
+
+If a Texinfo file has more than 30,000 bytes,
address@hidden automatically creates a tag table
+for its Info file; @code{makeinfo} always creates a tag table. With
+a @dfn{tag table}, Info can jump to new nodes more quickly than it can
+otherwise.
+
address@hidden Indirect subfiles
+In addition, if the Texinfo file contains more than about 300,000
+bytes, @code{texinfo-format-buffer} and @code{makeinfo} split the
+large Info file into shorter @dfn{indirect} subfiles of about 300,000
+bytes each. Big files are split into smaller files so that Emacs does
+not need to make a large buffer to hold the whole of a large Info
+file; instead, Emacs allocates just enough memory for the small, split-off
+file that is needed at the time. This way, Emacs avoids wasting
+memory when you run Info. (Before splitting was implemented, Info
+files were always kept short and @dfn{include files} were designed as
+a way to create a single, large printed manual out of the smaller Info
+files. @xref{Include Files}, for more information. Include files are
+still used for very large documents, such as @cite{The Emacs Lisp
+Reference Manual}, in which each chapter is a separate file.)
+
+When a file is split, Info itself makes use of a shortened version of
+the original file that contains just the tag table and references to
+the files that were split off. The split-off files are called
address@hidden files.
+
+The split-off files have names that are created by appending @address@hidden,
address@hidden@samp{-2}}, @address@hidden and so on to the file name specified
by the
address@hidden@@setfilename} command. The shortened version of the original
file
+continues to have the name specified by @code{@@setfilename}.
+
+At one stage in writing this document, for example, the Info file was saved
+as the file @file{test-texinfo} and that file looked like this:
+
address@hidden
address@hidden
+Info file: test-texinfo, -*-Text-*-
+produced by texinfo-format-buffer
+from file: new-texinfo-manual.texinfo
+
+^_
+Indirect:
+test-texinfo-1: 102
+test-texinfo-2: 50422
address@hidden group
address@hidden
+test-texinfo-3: 101300
+^_^L
+Tag table:
+(Indirect)
+Node: overview^?104
+Node: info file^?1271
address@hidden group
address@hidden
+Node: printed manual^?4853
+Node: conventions^?6855
address@hidden
address@hidden group
address@hidden example
+
address@hidden
+(But @file{test-texinfo} had far more nodes than are shown here.) Each of
+the split-off, indirect files, @file{test-texinfo-1},
address@hidden, and @file{test-texinfo-3}, is listed in this file
+after the line that says @samp{Indirect:}. The tag table is listed after
+the line that says @samp{Tag table:}.
+
+In the list of indirect files, the number following the file name
+records the cumulative number of bytes in the preceding indirect
+files, not counting the file list itself, the tag table, or any
+permissions text in the first file. In the tag table, the number
+following the node name records the location of the beginning of the
+node, in bytes from the beginning of the (unsplit) output.
+
+If you are using @code{texinfo-format-buffer} to create Info files,
+you may want to run the @code{Info-validate} command. (The
address@hidden command does such a good job on its own, you do not
+need @code{Info-validate}.) However, you cannot run the @kbd{M-x
+Info-validate} node-checking command on indirect files. For
+information on how to prevent files from being split and how to
+validate the structure of the nodes, see @ref{Using
address@hidden
+
+
address@hidden Installing an Info File
address@hidden Installing an Info File
address@hidden Installing an Info file
address@hidden Info file installation
address@hidden @file{dir} directory for Info installation
+
+Info files are usually kept in the @file{info} directory. You can
+read Info files using the standalone Info program or the Info reader
+built into Emacs. (@xref{Top,,, info, Info}, for an introduction to
+Info.)
+
address@hidden
+* 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.
+* Installing Dir Entries:: How to specify what menu entry to add
+ to the Info directory.
+* Invoking @t{install-info}:: @code{install-info} options.
address@hidden menu
+
+
address@hidden Directory File
address@hidden 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,
+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
address@hidden C-f} to see the pathname to the @file{info} directory.)
+
+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:
+
address@hidden
address@hidden
+* Menu:
+* Info: (info). Documentation browsing system.
+* Emacs: (emacs). The extensible, self-documenting
+ text editor.
+* Texinfo: (texinfo). With one source file, make
+ either a printed manual using
+ @@address@hidden@} or an Info file.
address@hidden
address@hidden group
address@hidden example
+
+Each of these menu entries points to the `Top' node of the Info file
+that is named in parentheses. (The menu entry does not need to
+specify the `Top' node, since Info goes to the `Top' node if no node
+name is mentioned. @xref{Other Info Files, , Nodes in Other Info
+Files}.)
+
+Thus, the @samp{Info} entry points to the `Top' node of the
address@hidden file and the @samp{Emacs} entry points to the `Top' node
+of the @file{emacs} file.
+
+In each of the Info files, the `Up' pointer of the `Top' node refers
+back to the @code{dir} file. For example, the line for the `Top'
+node of the Emacs manual looks like this in Info:
+
address@hidden
+File: emacs Node: Top, Up: (DIR), Next: Distrib
address@hidden example
+
address@hidden
+In this case, the @file{dir} file name is written in uppercase
+letters---it can be written in either upper- or lowercase. This is not
+true in general, it is a special case for @file{dir}.
+
+
address@hidden New Info File
address@hidden Listing a New Info File
address@hidden Adding a new Info file
address@hidden Listing a new Info file
address@hidden New Info file, listing it in @file{dir} file
address@hidden Info file, listing a new
address@hidden @file{dir} file listing
+
+To add a new Info file to your system, you must write a menu entry to
+add to the menu in the @file{dir} file in the @file{info} directory.
+For example, if you were adding documentation for GDB, you would write
+the following new entry:
+
address@hidden
+* GDB: (gdb). The source-level C debugger.
address@hidden example
+
address@hidden
+The first part of the menu entry is the menu entry name, followed by a
+colon. The second part is the name of the Info file, in parentheses,
+followed by a period. The third part is the description.
+
+The name of an Info file often has a @file{.info} extension. Thus, the
+Info file for GDB might be called either @file{gdb} or @file{gdb.info}.
+The Info reader programs automatically try the file name both with and
+without @address@hidden MS-DOS/MS-Windows systems, Info will
+try the @file{.inf} extension as well.}; so it is better to avoid
+clutter and not to write @samp{.info} explicitly in the menu entry. For
+example, the GDB menu entry should use just @samp{gdb} for the file
+name, not @samp{gdb.info}.
+
+
address@hidden Other Info Directories
address@hidden Info Files in Other Directories
address@hidden Installing Info in another directory
address@hidden Info installed in another directory
address@hidden Another Info directory
address@hidden @file{dir} files and Info directories
+
+If an Info file is not in the @file{info} directory, there are three
+ways to specify its location:
+
address@hidden
address@hidden
+Write the pathname in the @file{dir} file as the second part of the menu.
+
address@hidden
+Specify the Info directory name in the @code{INFOPATH} environment
+variable in your @file{.profile} or @file{.cshrc} initialization file.
+(Only you and others who set this environment variable will be able to
+find Info files whose location is specified this way.)
+
address@hidden
+If you are using Emacs, list the name of the file in a second @file{dir}
+file, in its directory; and then add the name of that directory to the
address@hidden variable in your personal or site
+initialization file.
+
+This variable tells Emacs where to look for @file{dir} files (the files
+must be named @file{dir}). Emacs merges the files named @file{dir} from
+each of the listed directories. (In Emacs version 18, you can set the
address@hidden variable to the name of only one
+directory.)
address@hidden enumerate
+
+For example, to reach a test file in the @file{/home/bob/info}
+directory, you could add an entry like this to the menu in the
+standard @file{dir} file:
+
address@hidden
+* Test: (/home/bob/info/info-test). Bob's own test file.
address@hidden example
+
address@hidden
+In this case, the absolute file name of the @file{info-test} file is
+written as the second part of the menu entry.
+
address@hidden INFOPATH
address@hidden Environment variable @code{INFOPATH}
+If you don't want to edit the system @file{dir} file, you can tell
+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
address@hidden 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
address@hidden file or in the registry. Each type of shell uses
+a different syntax.
+
address@hidden @bullet
address@hidden
+In a @file{.cshrc} file, you could set the @code{INFOPATH}
+variable as follows:
+
address@hidden
+setenv INFOPATH .:~/info:/usr/local/emacs/info
address@hidden smallexample
+
address@hidden
+In a @file{.profile} file, you would achieve the same effect by writing:
+
address@hidden
+INFOPATH=.:$HOME/info:/usr/local/emacs/info
+export INFOPATH
address@hidden smallexample
+
address@hidden
address@hidden 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):
+
address@hidden
+set INFOPATH=.;%HOME%/info;c:/usr/local/emacs/info
address@hidden smallexample
address@hidden itemize
+
address@hidden
+The @samp{.} indicates the current directory as usual. Emacs uses the
address@hidden 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
address@hidden variable into a single menu presented to you in the node
+called @samp{(dir)Top}.
+
address@hidden Colon, last in @env{INFOPATH}
+However you set @env{INFOPATH}, if its last character is a colon (on
+MS-DOS/MS-Windows systems, use a semicolon instead), this is replaced
+by the default (compiled-in) path. This gives you a way to augment
+the default path with new directories without having to list all the
+standard places. For example (using @code{sh} syntax):
+
address@hidden
+INFOPATH=/home/bob/info:
+export INFOPATH
address@hidden example
+
address@hidden
+will search @file{/home/bob/info} first, then the standard directories.
+Leading or doubled colons are not treated specially.
+
address@hidden @file{dir} file, creating your own
+When you create your own @file{dir} file for use with
address@hidden or @env{INFOPATH}, it's easiest to start by
+copying an existing @file{dir} file and replace all the text after the
address@hidden Menu:} with your desired entries. That way, the punctuation
+and special @kbd{CTRL-_} characters that Info needs will be present.
+
+As one final alternative, which works only with Emacs Info, you can
+change the @code{Info-directory-list} variable. For example:
+
address@hidden
+(add-hook 'Info-mode-hook '(lambda ()
+ (add-to-list 'Info-directory-list
+ (expand-file-name "~/info"))))
address@hidden example
+
+
address@hidden Installing Dir Entries
address@hidden Installing Info Directory Files
+
+When you install an Info file onto your system, you can use the program
address@hidden to update the Info directory file @file{dir}.
+Normally the makefile for the package runs @code{install-info}, just
+after copying the Info file into its proper installed location.
+
address@hidden dircategory
address@hidden direntry
+In order for the Info file to work with @code{install-info}, you include
+the commands @code{@@dircategory} and
address@hidden@@address@hidden@code{@@end direntry} in the Texinfo source
+file. Use @code{@@direntry} to specify the menu entries to add to the
+Info directory file, and use @code{@@dircategory} to specify which part
+of the Info directory to put it in. Here is how these commands are used
+in this manual:
+
address@hidden
+@@dircategory Texinfo documentation system
+@@direntry
+* Texinfo: (texinfo). The GNU documentation format.
+* install-info: (texinfo)Invoking install-info. @dots{}
address@hidden
+@@end direntry
address@hidden smallexample
+
+Here's what this produces in the Info file:
+
address@hidden
+INFO-DIR-SECTION Texinfo documentation system
+START-INFO-DIR-ENTRY
+* Texinfo: (texinfo). The GNU documentation format.
+* install-info: (texinfo)Invoking install-info. @dots{}
address@hidden
+END-INFO-DIR-ENTRY
address@hidden smallexample
+
address@hidden
+The @code{install-info} program sees these lines in the Info file, and
+that is how it knows what to do.
+
+Always use the @code{@@direntry} and @code{@@dircategory} commands near
+the beginning of the Texinfo input, before the first @code{@@node}
+command. If you use them later on in the input, @code{install-info}
+will not notice them.
+
address@hidden will automatically reformat the description of the
+menu entries it is adding. As a matter of convention, the description
+of the main entry (above, @samp{The GNU documentation format}) should
+start at column 32, starting at zero (as in
address@hidden in Emacs). This will make it align with
+most others. Description for individual utilities best start in
+column 48, where possible. For more information about formatting see
+the @samp{--calign}, @samp{--align}, and @samp{--max-width} options in
address@hidden @t{install-info}}.
+
+If you use @code{@@dircategory} more than once in the Texinfo source,
+each usage specifies the `current' category; any subsequent
address@hidden@@direntry} commands will add to that category.
+
address@hidden Free Software Directory
address@hidden Dir categories, choosing
address@hidden Categories, choosing
+When choosing a category name for the @code{@@dircategory} command, we
+recommend consulting the @uref{http://www.gnu.org/directory,
+Free Software Directory}. If your program is not listed there,
+or listed incorrectly or incompletely, please report the situation to
+the directory maintainers (@email{bug-directory@@gnu.org}) so that the
+category names can be kept in sync.
+
+Here are a few examples (see the @file{util/dir-example} file in the
+Texinfo distribution for large sample @code{dir} file):
+
address@hidden
+Emacs
+Localization
+Printing
+Software development
+Software libraries
+Text creation and manipulation
address@hidden display
+
address@hidden Invoking nodes, including in dir file
+Each `Invoking' node for every program installed should have a
+corresponding @code{@@direntry}. This lets users easily find the
+documentation for the different programs they can run, as with the
+traditional @command{man} system.
+
+
address@hidden Invoking @t{install-info}
address@hidden Invoking @command{install-info}
+
address@hidden install-info
+
address@hidden inserts menu entries from an Info file into the
+top-level @file{dir} file in the Info system (see the previous sections
+for an explanation of how the @file{dir} file works). @code{install-info}
+also removes menu entries from the @file{dir} file. It's most often
+run as part of software installation, or when constructing a @file{dir} file
+for all manuals on a system. Synopsis:
+
address@hidden
+install-info address@hidden@dots{} address@hidden address@hidden
address@hidden example
+
+If @var{info-file} or @var{dir-file} are not specified, the options
+(described below) that define them must be. There are no compile-time
+defaults, and standard input is never used. @code{install-info} can
+read only one Info file and write only one @file{dir} file per invocation.
+
address@hidden @file{dir}, created by @code{install-info}
+If @var{dir-file} (however specified) does not exist,
address@hidden creates it if possible (with no entries).
+
address@hidden Compressed dir files, reading
address@hidden XZ-compressed dir files, reading
address@hidden Bzipped dir files, reading
address@hidden Lzip-compressed dir files, reading
address@hidden LZMA-compressed dir files, reading
address@hidden Dir files, compressed
+If any input file is compressed with @code{gzip} (@pxref{Top,,, gzip,
+Gzip}), @code{install-info} automatically uncompresses it for reading.
+And if @var{dir-file} is compressed, @code{install-info} also
+automatically leaves it compressed after writing any changes. If
address@hidden itself does not exist, @code{install-info} tries to
+open @address@hidden, @address@hidden,
address@hidden@var{dir-file}.bz2}, @address@hidden, and
address@hidden@var{dir-file}.lzma}, in that order.
+
+Options:
+
address@hidden @code
address@hidden --add-once
address@hidden address@hidden, for @command{install-info}}
+Specifies that the entry or entries will only be put into a single section.
+
address@hidden address@hidden
address@hidden address@hidden@r{, for @command{install-info}}
+Specifies the column that the second and subsequent lines of menu entry's
+description will be formatted to begin at. The default for this option is
address@hidden It is used in conjunction with the @samp{--max-width} option.
address@hidden starts counting at 1.
+
address@hidden --append-new-sections
address@hidden address@hidden, for @command{install-info}}
+Instead of alphabetizing new sections, place them at the end of the DIR file.
+
address@hidden address@hidden
address@hidden address@hidden@r{, for @command{install-info}}
+Specifies the column that the first line of menu entry's description will
+be formatted to begin at. The default for this option is @samp{33}. It is
+used in conjunction with the @samp{--max-width} option.
+When the name of the menu entry exceeds this column, entry's description
+will start on the following line.
address@hidden starts counting at 1.
+
address@hidden --debug
address@hidden address@hidden, for @command{install-info}}
+Report what is being done.
+
address@hidden --delete
address@hidden address@hidden, for @command{install-info}}
+Delete the entries in @var{info-file} from @var{dir-file}. The file
+name in the entry in @var{dir-file} must be @var{info-file} (except for
+an optional @samp{.info} in either one). Don't insert any new entries.
+Any empty sections that result from the removal are also removed.
+
address@hidden address@hidden
address@hidden address@hidden@r{, for @command{install-info}}
+Specify the explanatory portion of the menu entry. If you don't specify
+a description (either via @samp{--entry}, @samp{--item} or this option),
+the description is taken from the Info file itself.
+
address@hidden address@hidden
address@hidden address@hidden@r{, for @command{install-info}}
+Specify file name of the Info directory file. This is equivalent to
+using the @var{dir-file} argument.
+
address@hidden --dry-run
address@hidden address@hidden, for @command{install-info}}
+Same as @samp{--test}.
+
address@hidden address@hidden
address@hidden address@hidden@r{, for @command{install-info}}
+Insert @var{text} as an Info directory entry; @var{text} should have the
+form of an Info menu item line plus zero or more extra lines starting
+with whitespace. If you specify more than one entry, they are all
+added. If you don't specify any entries, they are determined from
+information in the Info file itself.
+
address@hidden --help
address@hidden address@hidden, for @command{texindex}}
+Display a usage message with basic usage and all available options,
+then exit successfully.
+
address@hidden address@hidden
address@hidden address@hidden@r{, for @command{install-info}}
+Specify Info file to install in the directory. This is
+equivalent to using the @var{info-file} argument.
+
address@hidden address@hidden
address@hidden address@hidden@r{, for @command{install-info}}
+Specify the directory where the directory file @file{dir} resides.
+Equivalent to @address@hidden/dir}.
+
address@hidden address@hidden
address@hidden address@hidden@r{, for @command{install-info}}
+Same as @samp{--info-dir}.
+
address@hidden address@hidden
address@hidden address@hidden@r{, for @command{install-info}}
+Same as @address@hidden An Info directory entry is actually
+a menu item.
+
address@hidden --keep-old
address@hidden address@hidden, for @command{install-info}}
+Do not replace pre-existing menu entries. When @samp{--remove} is specified,
+this option means that empty sections are not removed.
+
address@hidden address@hidden
address@hidden address@hidden@r{, for @command{install-info}}
+Specifies the column that the menu entry's description will be word-wrapped
+at. @var{column} starts counting at 1.
+
address@hidden address@hidden
address@hidden address@hidden@r{, for @command{install-info}}
+Same as @samp{--max-width}.
+
address@hidden address@hidden
address@hidden address@hidden@r{, for @command{install-info}}
+Same as @samp{--name}.
+
address@hidden address@hidden
address@hidden address@hidden@r{, for @command{install-info}}
+Specify the name portion of the menu entry. If the @var{text} does
+not start with an asterisk @samp{*}, it is presumed to be the text
+after the @samp{*} and before the parentheses that specify the Info
+file. Otherwise @var{text} is taken verbatim, and is taken as
+defining the text up to and including the first period (a space is
+appended if necessary). If you don't specify the name (either via
address@hidden, @samp{--item} or this option), it is taken from the
+Info file itself. If the Info does not contain the name, the basename
+of the Info file is used.
+
address@hidden --no-indent
address@hidden address@hidden, for @command{install-info}}
+Suppress formatting of new entries into the @file{dir} file.
+
address@hidden --quiet
address@hidden --silent
address@hidden address@hidden, for @command{install-info}}
address@hidden address@hidden, for @command{install-info}}
+Suppress warnings, etc., for silent operation.
+
address@hidden --remove
address@hidden address@hidden, for @command{install-info}}
+Same as @samp{--delete}.
+
address@hidden --remove-exactly
address@hidden address@hidden, for @command{install-info}}
+Also like @samp{--delete}, but only entries if the Info file name
+matches exactly; @code{.info} and/or @code{.gz} suffixes are
address@hidden ignored.
+
address@hidden address@hidden
address@hidden address@hidden@r{, for @command{install-info}}
+Put this file's entries in section @var{sec} of the directory. If you
+specify more than one section, all the entries are added in each of the
+sections. If you don't specify any sections, they are determined from
+information in the Info file itself. If the Info file doesn't specify
+a section, the menu entries are put into the Miscellaneous section.
+
address@hidden --section @var{regex} @var{sec}
address@hidden --section @var{regex} @address@hidden, for
@command{install-info}}
+Same as @address@hidden address@hidden --add-once}.
+
address@hidden tries to detect when this alternate syntax is used,
+but does not always guess correctly. Here is the heuristic that
address@hidden uses:
address@hidden
address@hidden
+If the second argument to @code{--section} starts with a hyphen, the
+original syntax is presumed.
+
address@hidden
+If the second argument to @code{--section} is a file that can be
+opened, the original syntax is presumed.
+
address@hidden
+Otherwise the alternate syntax is used.
address@hidden 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
+should be changed to @address@hidden address@hidden
+--add-once}.
+
address@hidden address@hidden
address@hidden address@hidden@r{, for @command{install-info}}
+Put this file's entries into any section that matches @var{regex}. If
+more than one section matches, all of the entries are added in each of the
+sections. Specify @var{regex} using basic regular expression syntax, more
+or less as used with @command{grep}, for example.
+
address@hidden --test
address@hidden address@hidden, for @command{install-info}}
+Suppress updating of the directory file.
+
address@hidden --version
address@hidden address@hidden, for @command{install-info}}
address@hidden Version number, for install-info
+Display version information and exit successfully.
+
address@hidden table
+
+
address@hidden Generating HTML
address@hidden Generating HTML
+
address@hidden Generating HTML
address@hidden Outputting HTML
+
address@hidden generates Info output by default, but given the
address@hidden option, it will generate HTML, for web browsers and
+other programs. This chapter gives some details on such HTML output.
+
address@hidden has many user-definable customization variables
+with which you can influence the HTML output. @xref{Customization
+Variables}.
+
address@hidden 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.
+
address@hidden
+* HTML Translation:: Details of the HTML output.
+* HTML Splitting:: How HTML output is split.
+* HTML CSS:: Influencing HTML output with Cascading Style Sheets.
+* HTML Xref:: Cross references in HTML output.
address@hidden menu
+
+
address@hidden HTML Translation
address@hidden HTML Translation
+
address@hidden will include segments of Texinfo source between
address@hidden@@ifhtml} and @code{@@end ifhtml} in the HTML output (but not
+any of the other conditionals, by default). Source between
address@hidden@@html} and @code{@@end html} is passed without change to the
+output (i.e., suppressing the normal escaping of input @samp{<},
address@hidden>} and @samp{&} characters which have special significance in
+HTML). @xref{Conditional Commands}.
+
address@hidden Navigation bar, in HTML output
+By default, a navigation bar is inserted at the start of each node,
+analogous to Info output. If the @samp{--no-headers} option is used,
+the navigation bar is only inserted at the beginning of split files.
+Header @code{<link>} elements in split output can support Info-like
+navigation with browsers like Lynx and @w{Emacs W3} which implement
+this address@hidden feature.
+
address@hidden Footnote styles, in HTML
+In HTML, when the footnote style is @samp{end}, or if the output is
+not split, footnotes are put at the end of the output. If set to
address@hidden, and the output is split, they are placed in a
+separate file. @xref{Footnote Styles}.
+
address@hidden HTML output, browser compatibility of
+The HTML generated is standard address@hidden It also tries to be as
+compatible as possible with earlier standards (e.g., address@hidden,
+RFC-1866). Some minor exceptions: 1)@address@hidden tables are
+generated for the @code{@@multitable} command (@pxref{Multi-column
+Tables}), but they should degrade reasonably in browsers without table
+support; 2)@tie{}The address@hidden @samp{lang} attribute on the
address@hidden<html>} attribute is used; 3)@tie{} Entities that are not in the
address@hidden standard are also used. 4)@tie{} CSS is used
+(@pxref{HTML CSS}). 5)@tie{} A few address@hidden elements are used
+(@code{thead}, @code{abbr}, @code{acronym}).
+
+Using @samp{--init-file=html32.pm} produces strict address@hidden
+output (@pxref{Invoking @t{texi2any}}).
+
+Please report output from an error-free run of @code{makeinfo} which
+has browser portability problems as a bug (@pxref{Reporting Bugs}).
+
+
address@hidden HTML Splitting
address@hidden HTML Splitting
address@hidden Split HTML output
address@hidden HTML output, split
+
+When splitting output at nodes (which is the default),
address@hidden writes HTML output into (basically) one output file
+per Texinfo source @code{@@node}.
+
+Each output file name is the node name with spaces replaced by
address@hidden'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
+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.
+
+If @command{makeinfo} is run on a system which does not distinguish
+case in file names, nodes which are the same except for case (e.g.,
address@hidden and @samp{Index}) will also be folded into the same
+output file with anchors. You can also pretend to be on a case
+insensitive filesystem by setting the customization variable
address@hidden
+
+It is also possible to split at chapters or sections with
address@hidden (@pxref{Invoking @t{texi2any}}). In that case,
+the file names are constructed after the name of the node associated
+with the relevant sectioning command. Also, unless
address@hidden is specified, a redirection file is output
+for every node in order to more reliably support cross references to
+that manual (@pxref{HTML Xref}).
+
+When splitting, the HTML output files are written into a subdirectory,
+with the name chosen as follows:
+
address@hidden
address@hidden
address@hidden first tries the subdirectory with the base name
+from @code{@@setfilename} (that is, any extension is removed). For
+example, HTML output for @code{@@setfilename gcc.info} would be
+written into a subdirectory named @samp{gcc/}.
+
address@hidden
+If that directory cannot be created for any reason, then
address@hidden tries appending @samp{.html} to the directory name.
+For example, output for @code{@@setfilename texinfo} would be written
+to @samp{texinfo.html/}.
+
address@hidden
+If the @address@hidden directory can't be created either,
address@hidden gives up.
+
address@hidden enumerate
+
address@hidden In any case, the top-level output file within the directory
+is always named @samp{index.html}.
+
+Monolithic output (@code{--no-split}) is named according to
address@hidden@@setfilename} (with any @samp{.info} extension is replaced with
address@hidden), @code{--output} (the argument is used literally), or
+based on the input file name as a last resort
+(@address@hidden@@setfilename}}).
+
+
address@hidden HTML CSS
address@hidden HTML CSS
address@hidden HTML, and CSS
address@hidden CSS, and HTML output
address@hidden Cascading Style Sheets, and HTML output
+
+Cascading Style Sheets (CSS for short) is an Internet standard for
+influencing the display of HTML documents: see
address@hidden://www.w3.org/Style/CSS/}.
+
+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:
+
address@hidden
+pre.display @{ font-family:inherit @}
+pre.smalldisplay @{ font-family:inherit; font-size:smaller @}
address@hidden 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.
+
+You can influence the CSS in the HTML output with two
address@hidden options: @address@hidden and
address@hidden@var{url}}.
+
address@hidden texinfo-bright-colors.css
address@hidden Visualizing Texinfo CSS
+The option @address@hidden adds to each output HTML file
+a @samp{<link>} tag referencing a CSS at the given @var{url}. This
+allows using external style sheets. You may find the file
address@hidden/examples/texinfo-bright-colors.css} useful for
+visualizing the CSS elements in Texinfo output.
+
+The option @address@hidden includes the contents
address@hidden in the HTML output, as you might expect. However, the
+details are somewhat tricky, as described in the following, to provide
+maximum flexibility.
+
address@hidden @@import specifications, in CSS files
+The CSS file may begin with so-called @samp{@@import} directives,
+which link to external CSS specifications for browsers to use when
+interpreting the document. Again, a full description is beyond our
+scope here, but we'll describe how they work syntactically, so we can
+explain how @command{makeinfo} handles them.
+
address@hidden Comments, in CSS files
+There can be more than one @samp{@@import}, but they have to come
+first in the file, with only whitespace and comments interspersed, no
+normal definitions. (Technical exception: an @samp{@@charset}
+directive may precede the @samp{@@import}'s. This does not alter
address@hidden's behavior, it just copies the @samp{@@charset} if
+present.) Comments in CSS files are delimited by @samp{/* ... */}, as
+in address@hidden An @samp{@@import} directive must be in one of these two
forms:
+
address@hidden
+@@import url(http://example.org/foo.css);
+@@import "http://example.net/bar.css";;
address@hidden example
+
+As far as @command{makeinfo} is concerned, the crucial characters are
+the @samp{@@} at the beginning and the semicolon terminating the
+directive. When reading the CSS file, it simply copies any such
address@hidden@@}-directive into the output, as follows:
+
address@hidden
address@hidden If @var{file} contains only normal CSS declarations, it is
+included after @command{makeinfo}'s default CSS, thus overriding it.
+
address@hidden If @var{file} begins with @samp{@@import} specifications (see
+below), then the @samp{import}'s are included first (they have to come
+first, according to the standard), and then @command{makeinfo}'s
+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:
address@hidden
+pre.smallexample @{ font-size: inherit ! important @}
address@hidden example
+
address@hidden If @var{file} contains both @samp{@@import} and inline CSS
+specifications, the @samp{@@import}'s are included first, then
address@hidden's defaults, and lastly the inline CSS from
address@hidden
+
address@hidden Any @@-directive other than @samp{@@import} and @samp{@@charset}
+is treated as a CSS declaration, meaning @command{makeinfo} includes
+its default CSS and then the rest of the file.
address@hidden itemize
+
+If the CSS file is malformed or erroneous, @command{makeinfo}'s output
+is unspecified. @command{makeinfo} does not try to interpret the
+meaning of the CSS file in any way; it just looks for the special
address@hidden@@} and @samp{;} characters and blindly copies the text into the
+output. Comments in the CSS file may or may not be included in the
+output.
+
+In addition to the possibilities offered by CSS, @command{makeinfo}
+has many user-definable customization variables with which you can
+influence the HTML output. @xref{Customization Variables}.
+
+
address@hidden HTML Xref
address@hidden HTML Cross References
address@hidden HTML cross references
address@hidden Cross references, in HTML output
+
+Cross references between Texinfo manuals in HTML format become, in the
+end, a standard HTML @code{<a>} link, but the details are
+unfortunately complex. This section describes the algorithm used in
+detail, so that Texinfo can cooperate with other programs, such as
address@hidden, by writing mutually compatible HTML files.
+
+This algorithm may or may not be used for links @emph{within} HTML
+output for a Texinfo file. Since no issues of compatibility arise in
+such cases, we do not need to specify this.
+
+We try to support references to such ``external'' manuals in both
+monolithic and split forms. A @dfn{monolithic} (mono) manual is
+entirely contained in one file, and a @dfn{split} manual has a file
+for each node. (@xref{HTML Splitting}.)
+
address@hidden Dumas, Patrice
+The algorithm was primarily devised by Patrice Dumas in 2003--04.
+
address@hidden
+* Link Basics: HTML Xref Link Basics.
+* Node Expansion: HTML Xref Node Name Expansion.
+* Command Expansion: HTML Xref Command Expansion.
+* 8-bit Expansion: HTML Xref 8-bit Character Expansion.
+* Mismatch: HTML Xref Mismatch.
+* Configuration: HTML Xref Configuration. htmlxref.cnf.
+* Preserving links: HTML Xref Link Preservation. MANUAL-noderename.cnf.
address@hidden menu
+
+
address@hidden HTML Xref Link Basics
address@hidden HTML Cross Reference Link Basics
address@hidden HTML cross reference 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
+always assume the @code{http} protocol. For example:
+
address@hidden
+http://@var{host}/@var{dir}/@address@hidden
address@hidden example
+
+The information to construct a link comes from the node name and
+manual name in the cross reference command in the Texinfo source
+(@pxref{Cross References}), and from @dfn{external information}
+(@pxref{HTML Xref Configuration}).
+
+We now consider each part in turn.
+
+The @var{host} is hardwired to be the local host. This could either
+be the literal string @samp{localhost}, or, according to the rules for
+HTML links, the @samp{http://localhost/} could be omitted entirely.
+
+The @var{dir} and @var{file} parts are more complicated, and depend on
+the relative split/mono nature of both the manual being processed and
+the manual that the cross reference refers to. The underlying idea is
+that there is one directory for Texinfo manuals in HTML, and a given
address@hidden is either available as a monolithic file
address@hidden@var{manual}.html}, or a split subdirectory
address@hidden@var{manual}/*.html}. Here are the cases:
+
address@hidden @bullet
address@hidden
+If the present manual is split, and the referent manual is also split,
+the directory is @samp{../@var{referent/}} and the file is the
+expanded node name (described later).
+
address@hidden
+If the present manual is split, and the referent manual is mono, the
+directory is @samp{../} and the file is @address@hidden
+
address@hidden
+If the present manual is mono, and the referent manual is split, the
+directory is @address@hidden/} and the file is the expanded node
+name.
+
address@hidden
+If the present manual is mono, and the referent manual is also mono,
+the directory is @file{./} (or just the empty string), and the file is
address@hidden@var{referent}.html}.
+
address@hidden itemize
+
address@hidden BASEFILENAME_LENGTH
+Another rule, that only holds for filenames, is that base filenames
+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
+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
+reference command is ignored. Thus,
@code{@@address@hidden,,,../address@hidden and
address@hidden@@address@hidden,,,address@hidden both use @samp{foo} as the
manual name. This
+is because any such attempted hardwiring of the directory is very
+unlikely to be useful for both Info and HTML output.
+
+Finally, the @var{target} part is always the expanded node name.
+
+Whether the present manual is split or mono is determined by user
+option; @command{makeinfo} defaults to split, with the
address@hidden option overriding this.
+
+Whether the referent manual is split or mono, however, is another bit
+of the external information (@pxref{HTML Xref Configuration}). By
+default, @command{makeinfo} uses the same form of the referent manual
+as the present manual.
+
+Thus, there can be a mismatch between the format of the referent
+manual that the generating software assumes, and the format it's
+actually present in. @xref{HTML Xref Mismatch}.
+
+
address@hidden HTML Xref Node Name Expansion
address@hidden HTML Cross Reference Node Name Expansion
address@hidden HTML cross reference node name expansion
address@hidden node name expansion, in HTML cross references
address@hidden 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
+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
+restrictive.)
+
+Cross references in Texinfo can refer either to nodes or anchors
+(@address@hidden@@anchor}}). However, anchors are treated identically
+to nodes in this context, so we'll continue to say ``node'' names for
+simplicity.
+
+A special exception: the Top node (@pxref{The Top Node}) is always
+mapped to the file @file{index.html}, to match web server software.
+However, the HTML @emph{target} is @samp{Top}. Thus (in the split case):
+
address@hidden
+@@address@hidden,,, emacs, The GNU Emacs address@hidden
address@hidden <a href="emacs/index.html#Top">
address@hidden example
+
address@hidden
address@hidden
+The standard ASCII letters (a-z and A-Z) are not modified. All other
+characters may be changed as specified below.
+
address@hidden
+The standard ASCII numbers (0-9) are not modified except when a number
+is the first character of the node name. In that case, see below.
+
address@hidden
+Multiple consecutive space, tab and newline characters are transformed
+into just one space. (It's not possible to have newlines in node
+names with the current implementation, but we specify it anyway, just
+in case.)
+
address@hidden
+Leading and trailing spaces are removed.
+
address@hidden
+After the above has been applied, each remaining space character is
+converted into a @samp{-} character.
+
address@hidden
+Other ASCII 7-bit characters are transformed into @address@hidden,
+where @var{xx} is the ASCII character code in (lowercase) hexadecimal.
+This includes @samp{_}, which is mapped to @samp{_005f}.
+
address@hidden
+If the node name does not begin with a letter, the literal string
address@hidden is prefixed to the result. (Due to the rules above, that
+string can never occur otherwise; it is an arbitrary choice, standing
+for ``GNU Texinfo''.) This is necessary because XHTML requires that
+identifiers begin with a letter.
+
address@hidden enumerate
+
+For example:
+
address@hidden
+@@node A node --- with _'%
address@hidden A-node-_002d_002d_002d-with-_005f_0027_0025
address@hidden example
+
+Notice in particular:
+
address@hidden @bullet
address@hidden @samp{_} @result{} @samp{_005f}
address@hidden @samp{-} @result{} @samp{_002d}
address@hidden @samp{A node} @result{} @samp{A-node}
address@hidden itemize
+
+On case-folding computer systems, nodes differing only by case will be
+mapped to the same file. In particular, as mentioned above, Top
+always maps to the file @file{index.html}. Thus, on a case-folding
+system, Top and a node named `Index' will both be written to
address@hidden Fortunately, the targets serve to distinguish
+these cases, since HTML target names are always case-sensitive,
+independent of operating system.
+
+
address@hidden HTML Xref Command Expansion
address@hidden HTML Cross Reference Command Expansion
address@hidden HTML cross reference command expansion
+
+Node names may contain @@-commands (@pxref{Node Line Requirements}).
+This section describes how they are handled.
+
+First, comments are removed.
+
+Next, any @code{@@value} commands (@address@hidden@@set @@value}}) and
+macro invocations (@pxref{Invoking Macros}) are fully expanded.
+
+Then, for the following commands, the command name and braces are removed,
+and the text of the argument is recursively transformed:
+
address@hidden
+@@asis @@b @@cite @@code @@command @@dfn @@dmn @@dotless
+@@emph @@env @@file @@i @@indicateurl @@kbd @@key
+@@samp @@sansserif @@sc @@slanted @@strong @@t @@var @@verb @@w
address@hidden example
+
address@hidden For @code{@@sc}, any letters are capitalized.
+
+In addition, the following commands are replaced by constant text, as
+shown below. If any of these commands have non-empty arguments, as in
address@hidden@@address@hidden@}}, it is an error, and the result is
unspecified.
+In this table, `(space)' means a space character and `(nothing)' means
+the empty string. The notation address@hidden' means Unicode code
+point @var{hhhh} (in hex, as usual). There are further
+transformations of many of these expansions for the final file or
+target name, such as space characters to @samp{-}, etc., according to
+the other rules.
+
address@hidden @columnfractions .3 .5
address@hidden @code{@@(newline)} @tab (space)
address@hidden @code{@@(space)} @tab (space)
address@hidden @code{@@(tab)} @tab (space)
address@hidden @code{@@!} @tab @samp{!}
address@hidden @code{@@*} @tab (space)
address@hidden @code{@@-} @tab (nothing)
address@hidden @code{@@.} @tab @samp{.}
address@hidden @code{@@:} @tab (nothing)
address@hidden @code{@@?} @tab @samp{?}
address@hidden @code{@@@@} @tab @samp{@@}
address@hidden @code{@@@{} @tab @address@hidden
address@hidden @code{@@@}} @tab @address@hidden
address@hidden @code{@@LaTeX} @tab @samp{LaTeX}
address@hidden @code{@@TeX} @tab @samp{TeX}
address@hidden @code{@@arrow} @tab U+2192
address@hidden @code{@@bullet} @tab U+2022
address@hidden @code{@@comma} @tab @samp{,}
address@hidden @code{@@copyright} @tab U+00A9
address@hidden @code{@@dots} @tab U+2026
address@hidden @code{@@enddots} @tab @samp{...}
address@hidden @code{@@equiv} @tab U+2261
address@hidden @code{@@error} @tab @samp{error-->}
address@hidden @code{@@euro} @tab U+20AC
address@hidden @code{@@exclamdown} @tab U+00A1
address@hidden @code{@@expansion} @tab U+21A6
address@hidden @code{@@geq} @tab U+2265
address@hidden @code{@@leq} @tab U+2264
address@hidden @code{@@minus} @tab U+2212
address@hidden @code{@@ordf} @tab U+00AA
address@hidden @code{@@ordm} @tab U+00BA
address@hidden @code{@@point} @tab U+2605
address@hidden @code{@@pounds} @tab U+00A3
address@hidden @code{@@print} @tab U+22A3
address@hidden @code{@@questiondown} @tab U+00BF
address@hidden @code{@@registeredsymbol} @tab U+00AE
address@hidden @code{@@result} @tab U+21D2
address@hidden @code{@@textdegree} @tab U+00B0
address@hidden @code{@@tie} @tab (space)
address@hidden multitable
+
+Quotation mark @@-commands (@code{@@address@hidden@}} and the like),
+are likewise replaced by their Unicode values. Normal quotation
address@hidden (e.g., ASCII ` and ') are not altered.
address@hidden Quotation Marks}.
+
+Any @code{@@acronym}, @code{@@abbr}, @code{@@email}, and
address@hidden@@image} commands are replaced by their first argument. (For
+these commands, all subsequent arguments are optional, and ignored
+here.) @address@hidden@@acronym}}, and @address@hidden@@email}}, and
@ref{Images}.
+
+Any other command is an error, and the result is unspecified.
+
+
address@hidden HTML Xref 8-bit Character Expansion
address@hidden HTML Cross Reference 8-bit Character Expansion
address@hidden HTML cross reference 8-bit character expansion
address@hidden 8-bit characters, in HTML cross references
address@hidden Expansion of 8-bit characters in HTML cross references
address@hidden Transliteration of 8-bit characters in HTML cross references
+
+Usually, characters other than plain 7-bit ASCII are transformed into
+the corresponding Unicode code point(s) in Normalization address@hidden,
+which uses precomposed characters where available. (This is the
+normalization form recommended by the W3C and other bodies.) This
+holds when that code point is @code{0xffff} or less, as it almost
+always is.
+
+These will then be further transformed by the rules above into the
+string @address@hidden, where @var{hhhh} is the code point in hex.
+
+For example, combining this rule and the previous section:
+
address@hidden
+@@node @@address@hidden@} @@address@hidden@} @@address@hidden@}
@@address@hidden@}@@address@hidden@}
address@hidden A-TeX-B_0306-_2605_002e_002e_002e
address@hidden example
+
+Notice: 1)@address@hidden@@enddots} expands to three periods which in
+turn expands to three @samp{_002e}'s; 2)@address@hidden@@address@hidden@}} is
a `B'
+with a breve accent, which does not exist as a pre-accented Unicode
+character, therefore expands to @samp{B_0306} (B with combining
+breve).
+
+When the Unicode code point is above @code{0xffff}, the transformation
+is @address@hidden, that is, two leading underscores followed by
+six hex digits. Since Unicode has declared that their highest code
+point is @code{0x10ffff}, this is sufficient. (We felt it was better
+to define this extra escape than to always use six hex digits, since
+the first two would nearly always be zeros.)
+
+This method works fine if the node name consists mostly of ASCII
+characters and contains only few 8-bit ones. If the document is
+written in a language whose script is not based on the Latin alphabet
+(for example, Ukrainian), it will create file names consisting
+entirely of @address@hidden notations, which is inconvenient and
+all but unreadable.
+
+To handle such cases, @command{makeinfo} offers the
address@hidden 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.
+
address@hidden Normalization Form C, Unicode
+For the definition of Unicode Normalization address@hidden, see Unicode
+report UAX#15, @uref{http://www.unicode.org/reports/tr15/}. Many
+related documents and implementations are available elsewhere on the
+web.
+
+
address@hidden HTML Xref Mismatch
address@hidden HTML Cross Reference Mismatch
address@hidden HTML cross reference mismatch
address@hidden 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,
+it might guess wrong. However, when the @emph{referent} manual is
+generated, it is possible to handle at least some mismatches.
+
+In the case where we assume the referent is split, but it is actually
+available in mono, the only recourse would be to generate a
address@hidden/} subdirectory full of HTML files which redirect back to
+the monolithic @file{manual.html}. Since this is essentially the same
+as a split manual in the first place, it's not very appealing.
+
+On the other hand, in the case where we assume the referent is mono,
+but it is actually available in split, it is possible to use
+JavaScript to redirect from the putatively monolithic
address@hidden to the different @file{manual/node.html} files.
+Here's an example:
+
address@hidden
+function redirect() @{
+ switch (location.hash) @{
+ case "#Node1":
+ location.replace("manual/Node1.html#Node1"); break;
+ case "#Node2" :
+ location.replace("manual/Node2.html#Node2"); break;
+ @dots{}
+ default:;
+ @}
address@hidden
address@hidden example
+
+Then, in the @code{<body>} tag of @file{manual.html}:
+
address@hidden
+<body onLoad="redirect();">
address@hidden example
+
+Once again, this is something the software which generated the
address@hidden manual has to do in advance, it's not something the
+software generating the cross reference in the present manual can
+control.
+
+
address@hidden HTML Xref Configuration
address@hidden HTML Cross Reference Configuration: @file{htmlxref.cnf}
+
address@hidden htmlxref.cnf
address@hidden HTML cross reference configuration
address@hidden Cross reference configuration, for HTML
address@hidden Configuration, for HTML cross-manual references
+
address@hidden reads a file named @file{htmlxref.cnf} to gather
+information for cross references to other manuals in HTML output. It
+is looked for in the following directories:
+
address@hidden @file
address@hidden ./
+(the current directory)
+
address@hidden ./.texinfo/
+(under the current directory)
+
address@hidden ~/.texinfo/
+(where @code{~} is the current user's home directory)
+
address@hidden @var{sysconfdir}/texinfo/
+(where @var{sysconfdir} is the system configuration directory
+specified at compile-time, e.g., @file{/usr/local/etc})
+
address@hidden @var{datadir}/texinfo/
+(likewise specified at compile time, e.g., @file{/usr/local/share})
address@hidden table
+
+All files found are used, with earlier entries overriding later ones.
+The Texinfo distribution includes a default file which handles many
+GNU manuals; it is installed in the last of the above directories,
+i.e., @address@hidden/texinfo/htmlxref.cnf}.
+
+The file is line-oriented. Lines consisting only of whitespace are
+ignored. Comments are indicated with a @samp{#} at the beginning of a
+line, optionally preceded by whitespace. Since @samp{#} can occur in
+urls (like almost any character), it does not otherwise start a
+comment.
+
+Each non-blank non-comment line must be either a @dfn{variable
+assignment} or @dfn{manual information}.
+
+A variable assignment line looks like this:
+
address@hidden
address@hidden = @var{varvalue}
address@hidden example
+
+Whitespace around the @samp{=} is optional and ignored. The
address@hidden should consist of letters; case is significant. The
address@hidden is an arbitrary string, continuing to the end of the
+line. Variables are then referenced with @address@hidden@address@hidden;
+variable references can occur in the @var{varvalue}.
+
+A manual information line looks like this:
+
address@hidden
address@hidden @var{keyword} @var{urlprefix}
address@hidden example
+
address@hidden
+with @var{manual} the short identifier for a manual, @var{keyword}
+being one of: @code{mono}, @code{node}, @code{section},
address@hidden, and @var{urlprefix} described below. Variable
+references can occur only in the @var{urlprefix}. For example (used
+in the canonical @file{htmlxref.cnf}):
+
address@hidden
+G = http://www.gnu.org
+GS = address@hidden@}/software
+hello mono address@hidden@}/hello/manual/hello.html
+hello chapter address@hidden@}/hello/manual/html_chapter/
+hello section address@hidden@}/hello/manual/html_section/
+hello node address@hidden@}/hello/manual/html_node/
address@hidden smallexample
+
address@hidden monolithic manuals, for HTML cross references
+If the keyword is @code{mono}, @var{urlprefix} gives the host,
+directory, and file name for @var{manual} as one monolithic file.
+
address@hidden split manuals, for HTML cross references
+If the keyword is @code{node}, @code{section}, or @code{chapter},
address@hidden gives the host and directory for @var{manual} split
+into nodes, sections, or chapters, respectively.
+
+When available, @command{makeinfo} will use the ``corresponding''
+value for cross references between manuals. That is, when generating
+monolithic output (@option{--no-split}), the @code{mono} url will be
+used, when generating output that is split by node, the @code{node}
+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:
+
address@hidden
+node @result{} node, section, chapter, mono
+section @result{} section, chapter, node, mono
+chapter @result{} chapter, section, node, mono
+mono @result{} mono, chapter, section, node
address@hidden smallexample
+
address@hidden address@hidden, and HTML cross references}
+These section- and chapter-level cross-manual references can succeed
+only when the target manual was created using @option{--node-files};
+this is the default for split output.
+
+If you have additions or corrections to the @file{htmlxref.cnf}
+distributed with Texinfo, please email @email{bug-texinfo@@gnu.org} as
+usual. You can get the latest version from
address@hidden://ftpmirror.gnu.org/@/texinfo/@/htmlxref.cnf}.
+
+
address@hidden HTML Xref Link Preservation
address@hidden HTML Cross Reference Link Preservation: @address@hidden
+
address@hidden noderename.cnf
address@hidden @var{manual}-noderename.cnf
address@hidden HTML cross reference link preservation
address@hidden Preserving HTML links to old nodes
address@hidden Old nodes, preserving links to
address@hidden Renaming nodes, and preserving links
address@hidden Links, preserving to renamed nodes
address@hidden Node renaming, and preserving links
+
+Occasionally changes in a program require removing (or renaming) nodes
+in the manual in order to have the best documentation. Given the
+nature of the web, however, links may exist anywhere to such a removed
+node (renaming appears the same as removal for this purpose), and it's
+not ideal for those links to simply break.
+
address@hidden RENAMED_NODES_FILE
+Therefore, Texinfo provides a way for manual authors to specify old
+node names and the new nodes to which the old names should be
+redirected, via the file @address@hidden, where
address@hidden is the base name of the manual. For example, the manual
address@hidden would be supplemented by a file
address@hidden (This name can be overridden by
+setting the @file{RENAMED_NODES_FILE} customization variable;
address@hidden Variables}).
+
+The file is read in pairs of lines, as follows:
+
address@hidden
address@hidden
+@@@@@address@hidden @var{new-node-name}
address@hidden example
+
+The usual conversion from Texinfo node names to HTML names is applied;
+see this entire section for details (@pxref{HTML Xref}). The unusual
address@hidden@@@@@address@hidden separator is used because it is not a valid
Texinfo
+construct, so can't appear in the node names.
+
+The effect is that @command{makeinfo} generates a redirect from
address@hidden to @var{new-node-name} when producing HTML output.
+Thus, external links to the old node are preserved.
+
+Lines consisting only of whitespace are ignored. Comments are
+indicated with an @samp{@@c} at the beginning of a line, optionally
+preceded by whitespace.
+
+Another approach to preserving links to deleted or renamed nodes is to
+use anchors (@address@hidden@@anchor}}). There is no effective
+difference between the two approaches.
+
+
address@hidden Command List
address@hidden @@-Command List
address@hidden Alphabetical @@-command list
address@hidden List of @@-commands
address@hidden @@-command list
address@hidden Reference to @@-commands
+
+Here is an alphabetical list of the @@-commands in Texinfo. Square
+brackets, @address@hidden address@hidden, indicate optional arguments; an
ellipsis,
address@hidden@dots{}}, indicates repeated text.
+
+More specifics on the general syntax of different @@-commands are
+given in the section below.
+
address@hidden
+* Command Syntax:: General syntax for varieties of @@-commands.
+* Command Contexts:: Guidelines for which commands can be used where.
address@hidden menu
+
address@hidden 1
address@hidden @code
address@hidden @@@var{whitespace}
+An @code{@@} followed by a space, tab, or newline produces a normal,
+stretchable, interword space. @xref{Multiple Spaces}.
+
address@hidden @@!
+Produce an exclamation point that ends a sentence (usually after an
+end-of-sentence capital letter). @xref{Ending a Sentence}.
+
address@hidden @@"
address@hidden @@'
+Generate an umlaut or acute accent, respectively, over the next
+character, as in @"o and @'o. @xref{Inserting Accents}.
+
address@hidden @@*
+Force a line break. @xref{Line Breaks}.
+
address@hidden @@,@address@hidden@}
+Generate a cedilla accent under @var{c}, as in @,{c}. @xref{Inserting
+Accents}.
+
address@hidden @@-
+Insert a discretionary hyphenation point. @address@hidden@@- @@hyphenation}}.
+
address@hidden @@.
+Produce a period that ends a sentence (usually after an
+end-of-sentence capital letter). @xref{Ending a Sentence}.
+
address@hidden @@/
+Produces no output, but allows a line break. @xref{Line Breaks}.
+
address@hidden @@:
+Tell @TeX{} to refrain from inserting extra whitespace after an
+immediately preceding period, question mark, exclamation mark, or
+colon, as @TeX{} normally would. @xref{Not Ending a Sentence}.
+
address@hidden @@=
+Generate a macron (bar) accent over the next character, as in @=o.
address@hidden Accents}.
+
address@hidden @@?
+Produce a question mark that ends a sentence (usually after an
+end-of-sentence capital letter). @xref{Ending a Sentence}.
+
address@hidden @@@@
address@hidden @@address@hidden@}
+Insert an at sign, @samp{@@}. @xref{Inserting an Atsign}.
+
address@hidden @@\
address@hidden @@address@hidden@}
+Insert a backslash, @samp{\}; @code{@@address@hidden@}} works
+anywhere, while @code{@@\} works only inside @code{@@math}.
address@hidden a Backslash}, and @ref{Inserting Math}.
+
address@hidden @@^
address@hidden @@`
+Generate a circumflex (hat) or grave accent, respectively, over the next
+character, as in @^o and @`e.
address@hidden Accents}.
+
address@hidden @@@{
address@hidden @@address@hidden@}
+Insert a left brace, @address@hidden @xref{Inserting Braces}.
+
address@hidden @@@}
address@hidden @@address@hidden@}
+Insert a right brace, @address@hidden @xref{Inserting Braces}.
+
address@hidden @@~
+Generate a tilde accent over the next character, as in @~N.
address@hidden Accents}.
+
address@hidden @@address@hidden@}
address@hidden @@address@hidden@}
+Generate the uppercase and lowercase Scandinavian A-ring letters,
+respectively: @AA{}, @aa{}. @xref{Inserting Accents}.
+
address@hidden @@address@hidden@address@hidden
+Indicate a general abbreviation, such as `Comput.'.
address@hidden@t{@@abbr}}.
+
address@hidden @@address@hidden@address@hidden
+Indicate an acronym in all capital letters, such as `NASA'.
address@hidden@t{@@acronym}}.
+
address@hidden @@address@hidden@}
address@hidden @@address@hidden@}
+Generate the uppercase and lowercase AE ligatures, respectively:
address@hidden, @ae{}. @xref{Inserting Accents}.
+
address@hidden @@afivepaper
+Change page dimensions for the A5 paper size. @xref{A4 Paper}.
+
address@hidden @@afourlatex
address@hidden @@afourpaper
address@hidden @@afourwide
+Change page dimensions for the A4 paper size. @xref{A4 Paper}.
+
address@hidden @@alias @address@hidden
+Make the command @samp{@@@var{new}} a synonym for the existing command
address@hidden@@@var{existing}}. @address@hidden@@alias}}.
+
address@hidden @@allowcodebreaks @var{true-false}
+Control breaking at @samp{-} and @samp{_} in @TeX{}.
address@hidden@t{@@allowcodebreaks}}.
+
address@hidden @@address@hidden@address@hidden
+Define @var{name} as the current location for use as a cross reference
+target. @address@hidden@@anchor}}.
+
address@hidden @@appendix @var{title}
+Begin an appendix. The title appears in the table of contents. In
+Info, the title is underlined with asterisks.
address@hidden@t{@@unnumbered @@appendix}}.
+
address@hidden @@appendixsec @var{title}
address@hidden @@appendixsection @var{title}
+Begin an appendix section within an appendix. The section title
+appears in the table of contents. In Info, the title is underlined
+with equal signs. @code{@@appendixsection} is a longer spelling of
+the @code{@@appendixsec} command. @address@hidden@@unnumberedsec
+@@appendixsec @@heading}}.
+
address@hidden @@appendixsubsec @var{title}
+Begin an appendix subsection. The title appears in the table of
+contents. In Info, the title is underlined with hyphens.
address@hidden@t{@@unnumberedsubsec @@appendixsubsec @@subheading}}.
+
address@hidden @@appendixsubsubsec @var{title}
+Begin an appendix subsubsection. The title appears in the table of
+contents. In Info, the title is underlined with periods.
address@hidden@t{@@subsubsection}}.
+
address@hidden @@address@hidden@}
+Generate a right arrow glyph: @address@hidden Used by default
+for @code{@@click}. @xref{Click Sequences}.
+
address@hidden @@asis
+Used following @code{@@table}, @code{@@ftable}, and @code{@@vtable} to
+print the table's first column without highlighting (``as is'').
address@hidden@t{@@asis}}.
+
address@hidden @@author @var{author}
+Typeset @var{author} flushleft and underline it. @address@hidden@@title
+@@subtitle @@author}}.
+
address@hidden @@address@hidden@address@hidden
+Set @var{text} in a @b{bold} font. No effect in Info. @xref{Fonts}.
+
address@hidden @@address@hidden@}
+Generate a large round dot, @bullet{} (@samp{*} in Info). Often used
+with @code{@@table}. @address@hidden@@bullet}}.
+
address@hidden @@bye
+Stop formatting a file. The formatters do not see anything in the
+input file following @code{@@bye}. @xref{Ending a File}.
+
address@hidden @@c @var{comment}
+Begin a comment in Texinfo. The rest of the line does not appear in
+any output. A synonym for @code{@@comment}. @kbd{DEL} also
+starts a comment. @xref{Comments}.
+
address@hidden @@caption
+Define the full caption for an @code{@@float}. @address@hidden@@caption
+@@shortcaption}}.
+
address@hidden @@cartouche
+Highlight an example or quotation by drawing a box with rounded
+corners around it. Pair with @code{@@end cartouche}. No effect in
+Info. @address@hidden@@cartouche}}.
+
address@hidden @@center @var{line-of-text}
+Center the line of text following the command.
address@hidden@t{@@titlefont @@center @@sp}}.
+
address@hidden @@centerchap @var{line-of-text}
+Like @code{@@chapter}, but centers the chapter title.
@address@hidden@@chapter}}.
+
address@hidden @@chapheading @var{title}
+Print an unnumbered chapter-like heading, but omit from the table of
+contents. In Info, the title is underlined with asterisks.
address@hidden@t{@@majorheading @@chapheading}}.
+
address@hidden @@chapter @var{title}
+Begin a numbered chapter. The chapter title appears in the table of
+contents. In Info, the title is underlined with asterisks.
address@hidden@t{@@chapter}}.
+
address@hidden @@cindex @var{entry}
+Add @var{entry} to the index of concepts. @xref{Index Entries, ,
+Defining the Entries of an Index}.
+
address@hidden @@address@hidden@address@hidden
+Highlight the name of a book or other reference that has no companion
+Info file. @address@hidden@@cite}}.
+
address@hidden @@clear @var{flag}
+Unset @var{flag}, preventing the Texinfo formatting commands from
+formatting text between subsequent pairs of @code{@@ifset @var{flag}}
+and @code{@@end ifset} commands, and preventing
address@hidden@@address@hidden@address@hidden from expanding to the value to
which
address@hidden is set. @address@hidden@@set @@clear @@value}}.
+
address@hidden @@address@hidden@}
+Represent a single ``click'' in a address@hidden Used within
address@hidden@@clicksequence}. @xref{Click Sequences}.
+
address@hidden @@address@hidden@var{action} @@address@hidden@} @address@hidden
+Represent a sequence of clicks in a address@hidden @xref{Click Sequences}.
+
address@hidden @@clickstyle @@@var{cmd}
+Execute @@@var{cmd} for each @code{@@click}; the default is
address@hidden@@arrow}. The usual following empty braces on @@@var{cmd} are
+omitted. @xref{Click Sequences}.
+
address@hidden @@address@hidden@address@hidden
+Indicate an expression, a syntactically complete token of a program,
+or a program name. Unquoted in Info output. @address@hidden@@code}}.
+
address@hidden @@codequotebacktick @var{on-off}
address@hidden @@codequoteundirected @var{on-off}
+Control output of @code{`} and @code{'} in code examples.
address@hidden Quote Characters}.
+
address@hidden @@address@hidden@}
+Insert a comma `,' character; only needed when a literal comma would
+be taken as an argument separator. @xref{Inserting a Comma}.
+
address@hidden @@address@hidden@address@hidden
+Indicate a command name, such as @command{ls}. @address@hidden@@command}}.
+
address@hidden @@comment @var{comment}
+Begin a comment in Texinfo. The rest of the line does not appear in
+any output. A synonym for @code{@@c}.
address@hidden
+
address@hidden @@contents
+Print a complete table of contents. Has no effect in Info, which uses
+menus instead. @xref{Contents, , Generating a Table of Contents}.
+
address@hidden @@copying
+Specify copyright holders and copying conditions for the document Pair
+with @code{@@end cartouche}. @address@hidden@@copying}}.
+
address@hidden @@address@hidden@}
+Generate the copyright symbol @copyright{}.
address@hidden@t{@@copyright}}.
+
address@hidden @@defcodeindex @var{index-name}
+Define a new index and its indexing command. Print entries in an
address@hidden@@code} font. @xref{New Indices, , Defining New Indices}.
+
address@hidden @@defcv @var{category} @var{class} @var{name}
address@hidden @@defcvx @var{category} @var{class} @var{name}
+Format a description for a variable associated with a class in
+object-oriented programming. Takes three arguments: the category of
+thing being defined, the class to which it belongs, and its name.
address@hidden Commands}.
+
address@hidden @@deffn @var{category} @var{name} @address@hidden
address@hidden @@deffnx @var{category} @var{name} @address@hidden
+Format a description for a function, interactive command, or similar
+entity that may take arguments. @code{@@deffn} takes as arguments the
+category of entity being described, the name of this particular
+entity, and its arguments, if any. @xref{Definition Commands}.
+
address@hidden @@defindex @var{index-name}
+Define a new index and its indexing command. Print entries in a roman
+font. @xref{New Indices, , Defining New Indices}.
+
address@hidden @@definfoenclose @var{newcmd}, @var{before}, @var{after}
+Must be used within @code{@@ifinfo}; create a new command
address@hidden@@@var{newcmd}} for Info that marks text by enclosing it in
+strings that precede and follow the text.
address@hidden@t{@@definfoenclose}}.
+
address@hidden @@defivar @var{class} @var{instance-variable-name}
address@hidden @@defivarx @var{class} @var{instance-variable-name}
+Format a description for an instance variable in object-oriented
+programming. The command is equivalent to @samp{@@defcv @{Instance
address@hidden @dots{}}. @xref{Definition Commands}.
+
address@hidden @@defmac @var{macroname} @address@hidden
address@hidden @@defmacx @var{macroname} @address@hidden
+Format a description for a macro; equivalent to @samp{@@deffn Macro
address@hidden @xref{Definition Commands}.
+
address@hidden @@defmethod @var{class} @var{method-name} @address@hidden
address@hidden @@defmethodx @var{class} @var{method-name} @address@hidden
+Format a description for a method in object-oriented programming;
+equivalent to @samp{@@defop Method @dots{}}. @xref{Definition
+Commands}.
+
address@hidden @@defop @var{category} @var{class} @var{name} @address@hidden
address@hidden @@defopx @var{category} @var{class} @var{name} @address@hidden
+Format a description for an operation in object-oriented programming.
address@hidden@@defop} takes as arguments the name of the category of
+operation, the name of the operation's class, the name of the
+operation, and its arguments, if any. @xref{Definition Commands}, and
address@hidden Objects}.
+
address@hidden @@defopt @var{option-name}
address@hidden @@defoptx @var{option-name}
+Format a description for a user option; equivalent to @samp{@@defvr
address@hidden address@hidden @dots{}}. @xref{Definition Commands}.
+
address@hidden @@defspec @var{special-form-name} @address@hidden
address@hidden @@defspecx @var{special-form-name} @address@hidden
+Format a description for a special form; equivalent to @samp{@@deffn
address@hidden address@hidden @dots{}}. @xref{Definition Commands}.
+
address@hidden @@deftp @var{category} @var{name-of-type} @address@hidden
address@hidden @@deftpx @var{category} @var{name-of-type} @address@hidden
+Format a description for a data type; its arguments are the category,
+the name of the type (e.g., @samp{int}) , and then the names of
+attributes of objects of that type. @xref{Definition Commands}, and
address@hidden Types}.
+
address@hidden @@deftypecv @var{category} @var{class} @var{data-type} @var{name}
address@hidden @@deftypecvx @var{category} @var{class} @var{data-type}
@var{name}
+Format a description for a typed class variable in object-oriented programming.
address@hidden Commands}, and @ref{Abstract Objects}.
+
address@hidden @@deftypefn @var{category} @var{data-type} @var{name}
@address@hidden
address@hidden @@deftypefnx @var{category} @var{data-type} @var{name}
@address@hidden
+Format a description for a function or similar entity that may take
+arguments and that is typed. @code{@@deftypefn} takes as arguments the
+category of entity being described, the type, the name of the
+entity, and its arguments, if any. @xref{Definition Commands}.
+
address@hidden @@deftypefnnewline @var{on-off}
+Specifies whether return types for @code{@@deftypefn} and similar are
+printed on lines by themselves; default is off. @xref{Typed
+Functions,, Functions in Typed Languages}.
+
address@hidden @@deftypefun @var{data-type} @var{function-name} @address@hidden
address@hidden @@deftypefunx @var{data-type} @var{function-name} @address@hidden
+Format a description for a function in a typed language.
+The command is equivalent to @samp{@@deftypefn Function @dots{}}.
address@hidden Commands}.
+
address@hidden @@deftypeivar @var{class} @var{data-type} @var{variable-name}
address@hidden @@deftypeivarx @var{class} @var{data-type} @var{variable-name}
+Format a description for a typed instance variable in object-oriented
+programming. @xref{Definition Commands}, and @ref{Abstract Objects}.
+
address@hidden @@deftypemethod @var{class} @var{data-type} @var{method-name}
@address@hidden
address@hidden @@deftypemethodx @var{class} @var{data-type} @var{method-name}
@address@hidden
+Format a description for a typed method in object-oriented programming.
address@hidden Commands}.
+
address@hidden @@deftypeop @var{category} @var{class} @var{data-type}
@var{name} @address@hidden
address@hidden @@deftypeopx @var{category} @var{class} @var{data-type}
@var{name} @address@hidden
+Format a description for a typed operation in object-oriented programming.
address@hidden Commands}, and @ref{Abstract Objects}.
+
address@hidden @@deftypevar @var{data-type} @var{variable-name}
address@hidden @@deftypevarx @var{data-type} @var{variable-name}
+Format a description for a variable in a typed language. The command is
+equivalent to @samp{@@deftypevr Variable @dots{}}. @xref{Definition
+Commands}.
+
address@hidden @@deftypevr @var{category} @var{data-type} @var{name}
address@hidden @@deftypevrx @var{category} @var{data-type} @var{name}
+Format a description for something like a variable in a typed
+language---an entity that records a value. Takes as arguments the
+category of entity being described, the type, and the name of the
+entity. @xref{Definition Commands}.
+
address@hidden @@defun @var{function-name} @address@hidden
address@hidden @@defunx @var{function-name} @address@hidden
+Format a description for a function; equivalent to
address@hidden@@deffn Function @dots{}}. @xref{Definition Commands}.
+
address@hidden @@defvar @var{variable-name}
address@hidden @@defvarx @var{variable-name}
+Format a description for a variable; equivalent to @samp{@@defvr
+Variable @dots{}}. @xref{Definition Commands}.
+
address@hidden @@defvr @var{category} @var{name}
address@hidden @@defvrx @var{category} @var{name}
+Format a description for any kind of variable. @code{@@defvr} takes
+as arguments the category of the entity and the name of the entity.
address@hidden Commands}.
+
address@hidden @@detailmenu
+Mark the (optional) detailed node listing in a master menu.
address@hidden Menu Parts}.
+
address@hidden @@address@hidden@address@hidden
+Indicate the introductory or defining use of a term. @address@hidden@@dfn}}.
+
address@hidden @@address@hidden@}
address@hidden @@address@hidden@}
+Generate the uppercase and lowercase Icelandic letter eth, respectively:
address@hidden, @dh{}. @xref{Inserting Accents}.
+
address@hidden @@dircategory @var{dirpart}
+Specify a part of the Info directory menu where this file's entry should
+go. @xref{Installing Dir Entries}.
+
address@hidden @@direntry
+Begin the Info directory menu entry for this file. Pair with
address@hidden@@end direntry}. @xref{Installing Dir Entries}.
+
address@hidden @@display
+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}.
address@hidden@t{@@display}}.
+
address@hidden @@address@hidden@address@hidden
+Format a unit of measure, as in address@hidden Causes @TeX{} to insert a
+thin space before @var{dimension}. No effect in Info.
address@hidden@t{@@dmn}}.
+
address@hidden @@docbook
+Enter Docbook completely. Pair with @code{@@end docbook}. @xref{Raw
+Formatter Commands}.
+
address@hidden @@documentdescription
+Set the document description text, included in the HTML output. Pair
+with @code{@@end documentdescription}. @address@hidden@@documentdescription}}.
+
address@hidden @@documentencoding @var{enc}
+Declare the input encoding to be @var{enc}.
address@hidden@t{@@documentencoding}}.
+
address@hidden @@documentlanguage @var{CC}
+Declare the document language as the two-character ISO-639 abbreviation
address@hidden @address@hidden@@documentlanguage}}.
+
address@hidden @@address@hidden@address@hidden
+Generate a dot accent over the character @var{c}, as in @dotaccent{o}.
address@hidden Accents}.
+
address@hidden @@address@hidden@address@hidden
+Generate dotless i (address@hidden') and dotless j (address@hidden').
address@hidden Accents}.
+
address@hidden @@address@hidden@}
+Generate an ellipsis, @address@hidden
address@hidden@t{@@dots}}.
+
address@hidden @@address@hidden@var{address}[, @address@hidden
+Indicate an electronic mail address. @address@hidden@@email}}.
+
address@hidden @@address@hidden@address@hidden
+Emphasize @var{text}, by using @emph{italics} where possible, and
+enclosing in asterisks in Info. @xref{Emphasis, , Emphasizing Text}.
+
address@hidden @@end @var{environment}
+Ends @var{environment}, as in @samp{@@end example}. @xref{Formatting
+Commands,,@@-commands}.
+
address@hidden @@address@hidden@}
+Generate an end-of-sentence ellipsis, like this: @enddots{}
address@hidden@t{@@dots}}.
+
address@hidden @@enumerate address@hidden
+Begin a numbered list, using @code{@@item} for each entry.
+Optionally, start list with @var{number-or-letter}. Pair with
address@hidden@@end enumerate}. @address@hidden@@enumerate}}.
+
address@hidden @@address@hidden@address@hidden
+Indicate an environment variable name, such as @env{PATH}.
address@hidden@t{@@env}}.
+
address@hidden @@address@hidden@}
+Indicate to the reader the exact equivalence of two forms with a
+glyph: @address@hidden @address@hidden@@equiv}}.
+
address@hidden @@address@hidden@}
+Indicate to the reader with a glyph that the following text is
+an error message: @address@hidden @address@hidden@@error}}.
+
address@hidden @@address@hidden@address@hidden
+Report @var{msg} as an error to standard error, and exit unsuccessfully.
+Texinfo commands within @var{msg} are expanded to plain text.
address@hidden, and @ref{External Macro Processors}.
+
address@hidden @@address@hidden@}
+Generate the Euro currency sign. @address@hidden@@euro}}.
+
address@hidden @@evenfooting address@hidden @@| address@hidden @@|
address@hidden
address@hidden @@evenheading address@hidden @@| address@hidden @@|
address@hidden
+Specify page footings resp.@: headings for even-numbered (left-hand)
+pages. @xref{Custom Headings, ,
+How to Make Your Own Headings}.
+
address@hidden @@everyfooting address@hidden @@| address@hidden @@|
address@hidden
address@hidden @@everyheading address@hidden @@| address@hidden @@|
address@hidden
+Specify page footings resp.@: headings for every page. Not relevant to
+Info. @xref{Custom Headings, , How to Make Your Own Headings}.
+
address@hidden @@example
+Begin an example. Indent text, do not fill, and select fixed-width
+font. Pair with @code{@@end example}. @address@hidden@@example}}.
+
address@hidden @@exampleindent @var{indent}
+Indent example-like environments by @var{indent} number of spaces
+(perhaps 0). @address@hidden@@exampleindent}}.
+
address@hidden @@address@hidden@}
+Generate an upside-down exclamation point. @xref{Inserting Accents}.
+
address@hidden @@exdent @var{line-of-text}
+Remove any indentation a line might have. @address@hidden@@exdent}}.
+
address@hidden @@address@hidden@}
+Indicate the result of a macro expansion to the reader with a special
+glyph: @address@hidden @address@hidden@@expansion}}.
+
address@hidden @@address@hidden@address@hidden
+Highlight the name of a file, buffer, node, directory, etc.
address@hidden@t{@@file}}.
+
address@hidden @@finalout
+Prevent @TeX{} from printing large black warning rectangles beside
+over-wide lines. @xref{Overfull hboxes}.
+
address@hidden @@findex @var{entry}
+Add @var{entry} to the index of functions. @xref{Index Entries, ,
+Defining the Entries of an Index}.
+
address@hidden @@firstparagraphindent @var{word}
+Control indentation of the first paragraph after section headers
+according to @var{word}, one of `none' or `insert'.
address@hidden@t{@@firstparagraphindent}}.
+
address@hidden @@float
+Environment to define floating material. Pair with @code{@@end float}.
address@hidden
+
address@hidden @@flushleft
address@hidden @@flushright
+Do not fill text; left (right) justify every line while leaving the
+right (left) end ragged. Leave font as is. Pair with @code{@@end
+flushleft} (@code{@@end flushright}). @address@hidden@@flushleft
+@@flushright}}.
+
address@hidden @@fonttextsize @var{10-11}
+Change the size of the main body font in the @TeX{} output.
address@hidden
+
address@hidden @@address@hidden@address@hidden
+Enter a footnote. Footnote text is printed at the bottom of the page
+by @TeX{}; Info may format in either `End' node or `Separate' node style.
address@hidden
+
address@hidden @@footnotestyle @var{style}
+Specify an Info file's footnote style, either @samp{end} for the end
+node style or @samp{separate} for the separate node style.
address@hidden
+
address@hidden @@format
+Begin a kind of example. Like @code{@@display}, but do not indent.
+Pair with @code{@@end format}. @address@hidden@@example}}.
+
address@hidden @@frenchspacing @var{on-off}
+Control spacing after punctuation. @address@hidden@@frenchspacing}}.
+
address@hidden @@ftable @var{formatting-command}
+Begin a two-column table, using @code{@@item} for each entry.
+Automatically enter each of the items in the first column into the
+index of functions. Pair with @code{@@end ftable}. The same as
address@hidden@@table}, except for indexing. @address@hidden@@ftable
@@vtable}}.
+
address@hidden @@address@hidden@}
+Generate a greater-than-or-equal sign, address@hidden'. @address@hidden@@geq
@@leq}}.
+
address@hidden @@group
+Disallow page breaks within following text. Pair with @code{@@end
+group}. Ignored in Info. @address@hidden@@group}}.
+
address@hidden @@address@hidden@}
address@hidden @@address@hidden@}
address@hidden @@address@hidden@}
address@hidden @@address@hidden@}
address@hidden @@address@hidden@}
address@hidden @@address@hidden@}
+Double and single angle quotation marks: @guillemetleft{}
address@hidden @guilsinglleft{} @guilsinglright{}.
address@hidden@@guillemotleft} and @code{@@guillemotright} are synonyms for
address@hidden@@guillemetleft} and @code{@@guillemetright}. @xref{Inserting
+Quotation Marks}.
+
address@hidden @@address@hidden@address@hidden
+Generate the long Hungarian umlaut accent over @var{c}, as in @H{o}.
+
address@hidden @@address@hidden@}
+Insert a hash `#' character; only needed when a literal hash would
+introduce @code{#line} directive. @xref{Inserting a Hashsign}, and
address@hidden Macro Processors}.
+
address@hidden @@heading @var{title}
+Print an unnumbered section-like heading, but omit from the table of
+contents. In Info, the title is underlined with equal signs.
address@hidden@t{@@unnumberedsec @@appendixsec @@heading}}.
+
address@hidden @@headings @var{on-off-single-double}
+Turn page headings on or off, and/or specify single-sided or double-sided
+page headings for printing. @address@hidden@@headings}}.
+
address@hidden @@headitem
+Begin a heading row in a multitable. @xref{Multitable Rows}.
+
address@hidden @@address@hidden@address@hidden
+Set @var{text} in the font used for multitable heading rows; mostly
+useful in multitable templates. @xref{Multitable Rows}.
+
address@hidden @@html
+Enter HTML completely. Pair with @code{@@end html}. @xref{Raw
+Formatter Commands}.
+
address@hidden @@address@hidden@var{hy-phen-a-ted address@hidden
+Explicitly define hyphenation points. @address@hidden@@- @@hyphenation}}.
+
address@hidden @@address@hidden@address@hidden
+Set @var{text} in an @i{italic} font. No effect in Info. @xref{Fonts}.
+
address@hidden @@ifclear @var{txivar}
+If the Texinfo variable @var{txivar} is not set, format the following
+text. Pair with @code{@@end ifclear}. @address@hidden@@set @@clear
+@@value}}.
+
address@hidden @@ifcommanddefined @var{txicmd}
address@hidden @@ifcommandnotdefined @var{txicmd}
+If the Texinfo code @samp{@@@var{txicmd}} is (not) defined, format the
+follow text. Pair with the corresponding @code{@@end ifcommand...}.
address@hidden for Texinfo Commands}.
+
address@hidden @@ifdocbook
address@hidden @@ifhtml
address@hidden @@ifinfo
+Begin text that will appear only in the given output format.
address@hidden@@ifinfo} output appears in both Info and (for historical
+compatibility) plain text output. Pair with @code{@@end ifdocbook}
+resp.@: @code{@@end ifhtml} resp.@: @code{@@end ifinfo}.
address@hidden
+
address@hidden @@ifnotdocbook
address@hidden @@ifnothtml
address@hidden @@ifnotplaintext
address@hidden @@ifnottex
address@hidden @@ifnotxml
+Begin text to be ignored in one output format but not the others.
address@hidden@@ifnothtml} text is omitted from HTML output, etc. Pair with
+the corresponding @code{@@end address@hidden
address@hidden
+
address@hidden @@ifnotinfo
+Begin text to appear in output other than Info and (for historical
+compatibility) plain text. Pair with @code{@@end ifnotinfo}.
address@hidden
+
address@hidden @@ifplaintext
+Begin text that will appear only in the plain text output.
+Pair with @code{@@end ifplaintext}. @xref{Conditionals}.
+
address@hidden @@ifset @var{txivar}
+If the Texinfo variable @var{txivar} is set, format the following
+text. Pair with @code{@@end ifset}. @address@hidden@@set @@clear
+@@value}}.
+
address@hidden @@iftex
+Begin text to appear only in the @TeX{} output. Pair with @code{@@end
+iftex}. @xref{Conditionals, , Conditionally Visible Text}.
+
address@hidden @@ifxml
+Begin text that will appear only in the XML output. Pair with
address@hidden@@end ifxml}. @xref{Conditionals}.
+
address@hidden @@ignore
+Begin text that will not appear in any output. Pair with @code{@@end
+ignore}. @xref{Comments, , Comments and Ignored Text}.
+
address@hidden @@address@hidden@var{filename}, address@hidden, address@hidden,
address@hidden, address@hidden@}
+Include graphics image in external @var{filename} scaled to the given
address@hidden and/or @var{height}, using @var{alt} text and looking for
address@hidden@address@hidden in address@hidden @xref{Images}.
+
address@hidden @@include @var{filename}
+Read the contents of Texinfo source file @var{filename}. @xref{Include Files}.
+
address@hidden @@indent
+Insert paragraph indentation. @address@hidden@@indent}}.
+
address@hidden @@indentedblock
+Indent a block of arbitary text on the left. Pair with @code{@@end
+indentedblock}. @address@hidden@@indentedblock}}.
+
address@hidden @@address@hidden@address@hidden
+Indicate text that is a uniform resource locator for the World Wide
+Web. @address@hidden@@indicateurl}}.
+
address@hidden @@address@hidden@var{node-name}, address@hidden, @address@hidden
+Make a cross reference to an Info file for which there is no printed
+manual. @address@hidden@@inforef}}.
+
address@hidden @@address@hidden@var{fmt}, @address@hidden
address@hidden @@address@hidden@var{fmt}, @address@hidden
+Insert (raw) @var{text} only if the output format is @var{fmt}.
address@hidden Conditionals}.
+
address@hidden \input @var{macro-definitions-file}
+Use the specified macro definitions file. This command is used only
+in the first line of a Texinfo file to cause @TeX{} to make use of the
address@hidden macro definitions file. The @code{\} in @code{\input}
+is used instead of an @code{@@} because @TeX{} does not recognize
address@hidden@@} until after it has read the definitions file. @xref{Texinfo
+File Header}.
+
address@hidden @@insertcopying
+Insert the text previously defined with the @code{@@copying}
+environment. @address@hidden@@insertcopying}}.
+
address@hidden @@item
+Indicate the beginning of a marked paragraph for @code{@@itemize} and
address@hidden@@enumerate}; indicate the beginning of the text of a first column
+entry for @code{@@table}, @code{@@ftable}, and @code{@@vtable}.
address@hidden and Tables}.
+
address@hidden @@itemize @var{mark-generating-character-or-command}
+Begin an unordered list: indented paragraphs with a mark, such as
address@hidden@@bullet}, inside the left margin at the beginning of each item.
+Pair with @code{@@end itemize}. @address@hidden@@itemize}}.
+
address@hidden @@itemx
+Like @code{@@item} but do not generate extra vertical space above the
+item text. Thus, when several items have the same description, use
address@hidden@@item} for the first and @code{@@itemx} for the others.
address@hidden@t{@@itemx}}.
+
address@hidden @@address@hidden@address@hidden
+Indicate characters of input to be typed by users. @address@hidden@@kbd}}.
+
address@hidden @@kbdinputstyle @var{style}
+Specify when @code{@@kbd} should use a font distinct from
address@hidden@@code} according to @var{style}: @code{code}, @code{distinct},
address@hidden @address@hidden@@kbd}}.
+
address@hidden @@address@hidden@address@hidden
+Indicate the name of a key on a keyboard. @address@hidden@@key}}.
+
address@hidden @@kindex @var{entry}
+Add @var{entry} to the index of keys.
address@hidden Entries, , Defining the Entries of an Index}.
+
address@hidden @@address@hidden@}
address@hidden @@address@hidden@}
+Generate the uppercase and lowercase Polish suppressed-L letters,
+respectively: @L{}, @l{}.
+
address@hidden @@address@hidden@}
+Generate the @LaTeX{} logo. @address@hidden@@TeX @@LaTeX}}.
+
address@hidden @@address@hidden@}
+Generate a less-than-or-equal sign, address@hidden'. @address@hidden@@geq
@@leq}}.
+
address@hidden @@lisp
+Begin an example of Lisp code. Indent text, do not fill, and select
+fixed-width font. Pair with @code{@@end lisp}. @address@hidden@@lisp}}.
+
address@hidden @@listoffloats
+Produce a table-of-contents-like listing of @code{@@float}s.
address@hidden@t{@@listoffloats}}.
+
address@hidden @@lowersections
+Change subsequent chapters to sections, sections to subsections, and so
+on. @xref{Raise/lower sections, , @code{@@raisesections} and
address@hidden@@lowersections}}.
+
address@hidden @@macro @var{macroname} @address@hidden@}
+Define a new Texinfo command @code{@@@address@hidden@address@hidden
+Pair with @code{@@end macro}. @xref{Defining Macros}.
+
address@hidden @@majorheading @var{title}
+Print an unnumbered chapter-like heading, but omit from the table of
+contents. This generates more vertical whitespace before the heading
+than the @code{@@chapheading} command. @address@hidden@@majorheading
+@@chapheading}}.
+
address@hidden @@address@hidden@address@hidden
+Format a mathematical expression. @xref{Inserting Math}.
+
address@hidden @@menu
+Mark the beginning of a menu of nodes. No effect in a printed manual.
+Pair with @code{@@end menu}. @xref{Menus}.
+
address@hidden @@address@hidden@}
+Generate a minus sign, address@hidden'. @address@hidden@@minus}}.
+
address@hidden @@multitable @var{column-width-spec}
+Begin a multi-column table. Begin each row with @code{@@item} or
address@hidden@@headitem}, and separate columns with @code{@@tab}. Pair with
address@hidden@@end multitable}. @xref{Multitable Column Widths}.
+
address@hidden @@need @var{n}
+Start a new page in a printed manual if fewer than @var{n} mils
+(thousandths of an inch) remain on the current page.
address@hidden@t{@@need}}.
+
address@hidden @@node @var{name}, @var{next}, @var{previous}, @var{up}
+Begin a new node. @address@hidden@@node}}.
+
address@hidden @@noindent
+Prevent text from being indented as if it were a new paragraph.
address@hidden@t{@@noindent}}.
+
address@hidden @@novalidate
+Suppress validation of node references and omit creation of auxiliary
+files with @TeX{}. Use before @code{@@setfilename}. @xref{Pointer
+Validation}.
+
address@hidden @@address@hidden@}
address@hidden @@address@hidden@}
+Generate the uppercase and lowercase O-with-slash letters, respectively:
address@hidden, @o{}.
+
address@hidden @@oddfooting address@hidden @@| address@hidden @@|
address@hidden
address@hidden @@oddheading address@hidden @@| address@hidden @@| address@hidden
+Specify page footings resp.@: headings for odd-numbered (right-hand)
+pages. @xref{Custom Headings, ,
+How to Make Your Own Headings}.
+
address@hidden @@address@hidden@}
address@hidden @@address@hidden@}
+Generate the uppercase and lowercase OE ligatures, respectively:
address@hidden, @oe{}. @xref{Inserting Accents}.
+
address@hidden @@address@hidden@address@hidden
+Generate an ogonek diacritic under the next character, as in
address@hidden @xref{Inserting Accents}.
+
address@hidden @@address@hidden@address@hidden
+Indicate a command-line option, such as @option{-l} or
address@hidden @address@hidden@@option}}.
+
address@hidden @@address@hidden@}
address@hidden @@address@hidden@}
+Generate the feminine and masculine Spanish ordinals, respectively:
address@hidden, @ordm{}. @xref{Inserting Accents}.
+
address@hidden @@page
+Start a new page in a printed manual. No effect in Info.
address@hidden@t{@@page}}.
+
address@hidden @@pagesizes address@hidden, @var{height}]
+Change page dimensions. @xref{pagesizes}.
+
address@hidden @@paragraphindent @var{indent}
+Indent paragraphs by @var{indent} number of spaces (perhaps 0); preserve
+source file indentation if @var{indent} is @code{asis}.
address@hidden@t{@@paragraphindent}}.
+
address@hidden @@part @var{title}
+Begin a group of chapters or appendixes; included in the tables of
+contents and produces a page of its own in printed output.
address@hidden@t{@@part}}.
+
address@hidden @@pindex @var{entry}
+Add @var{entry} to the index of programs. @xref{Index Entries, , Defining
+the Entries of an Index}.
+
address@hidden @@address@hidden@}
+Indicate the position of point in a buffer to the reader with a glyph:
address@hidden@point{}}. @address@hidden@@point}}.
+
address@hidden @@address@hidden@}
+Generate the pounds sterling currency sign.
address@hidden@t{@@pounds}}.
+
address@hidden @@address@hidden@}
+Indicate printed output to the reader with a glyph: @address@hidden
address@hidden@t{@@print}}.
+
address@hidden @@printindex @var{index-name}
+Generate the alphabetized index for @var{index-name} (using two
+columns in a printed manual). @xref{Printing Indices & Menus}.
+
address@hidden @@address@hidden@var{node}, address@hidden, address@hidden,
address@hidden, address@hidden@}
+Make a reference that starts with a lowercase `see' in a printed
+manual. Use within parentheses only. Only the first argument is
+mandatory. @address@hidden@@pxref}}.
+
address@hidden @@address@hidden@}
+Generate an upside-down question mark. @xref{Inserting Accents}.
+
address@hidden @@quotation
+Narrow the margins to indicate text that is quoted from another work.
+Takes optional argument specifying prefix text, e.g., an author name.
+Pair with @code{@@end quotation}. @address@hidden@@quotation}}.
+
address@hidden @@address@hidden@}
address@hidden @@address@hidden@}
address@hidden @@address@hidden@}
address@hidden @@address@hidden@}
address@hidden @@address@hidden@}
address@hidden @@address@hidden@}
+Produce various quotation marks: @quotedblleft{} @quotedblright{}
address@hidden @quoteright{} @quotedblbase{} @quotesinglbase{}.
address@hidden Quotation Marks}.
+
address@hidden @@address@hidden@address@hidden
+Set @var{text} in the regular @r{roman} font. No effect in Info.
address@hidden
+
address@hidden @@raggedright
+Fill text; left justify every line while leaving the right end ragged.
+Leave font as is. Pair with @code{@@end raggedright}. No effect in
+Info. @address@hidden@@raggedright}}.
+
address@hidden @@raisesections
+Change subsequent sections to chapters, subsections to sections, and so
+on. @xref{Raise/lower sections}.
+
address@hidden @@address@hidden@var{node}, address@hidden, address@hidden,
address@hidden, address@hidden@}
+Make a plain reference that does not start with any special text.
+Follow command with a punctuation mark. Only the first argument is
+mandatory. @address@hidden@@ref}}.
+
address@hidden @@refill
address@hidden 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.
+
address@hidden @@address@hidden@}
+Generate the legal symbol @registeredsymbol{}.
address@hidden@t{@@registeredsymbol}}.
+
address@hidden @@address@hidden@}
+Indicate the result of an expression to the reader with a special
+glyph: @address@hidden @address@hidden@@result}}.
+
address@hidden @@address@hidden@address@hidden
+Generate a ring accent over the next character, as in @ringaccent{o}.
address@hidden Accents}.
+
address@hidden @@address@hidden@address@hidden
+Indicate a literal example of a sequence of characters, in general.
+Quoted in Info output. @address@hidden@@samp}}.
+
address@hidden @@address@hidden@address@hidden
+Set @var{text} in a @sansserif{sans serif} font if possible. No
+effect in Info. @xref{Fonts}.
+
address@hidden @@address@hidden@address@hidden
+Set @var{text} in a small caps font in printed output, and uppercase
+in Info. @xref{Smallcaps}.
+
address@hidden @@section @var{title}
+Begin a section within a chapter. The section title appears in the
+table of contents. In Info, the title is underlined with equal signs.
+Within @code{@@chapter} and @code{@@appendix}, the section title is
+numbered; within @code{@@unnumbered}, the section is unnumbered.
address@hidden@t{@@section}}.
+
address@hidden @@set @var{txivar} address@hidden
+Define the Texinfo variable @var{txivar}, optionally to the value
address@hidden @address@hidden@@set @@clear @@value}}.
+
address@hidden @@setchapternewpage @var{on-off-odd}
+Specify whether chapters start on new pages, and if so, whether on
+odd-numbered (right-hand) new pages. @address@hidden@@setchapternewpage}}.
+
address@hidden @@setcontentsaftertitlepage
+Put the table of contents after the @samp{@@end titlepage} even if the
address@hidden@@contents} command is at the end. @xref{Contents}.
+
address@hidden @@setfilename @var{info-file-name}
+Provide a name to be used for the output files. This command is essential
+for @TeX{} formatting as well, even though it produces no output of
+its own. @address@hidden@@setfilename}}.
+
address@hidden @@setshortcontentsaftertitlepage
+Place the short table of contents after the @samp{@@end titlepage}
+command even if the @code{@@shortcontents} command is at the end.
address@hidden
+
address@hidden @@settitle @var{title}
+Specify the title for page headers in a printed manual, and the
+default document title for HTML @samp{<head>}.
address@hidden@t{@@settitle}}.
+
address@hidden @@shortcaption
+Define the short caption for an @code{@@float}. @address@hidden@@caption
+@@shortcaption}}.
+
address@hidden @@shortcontents
+Print a short table of contents, with chapter-level entries only. Not
+relevant to Info, which uses menus rather than tables of contents.
address@hidden, , Generating a Table of Contents}.
+
address@hidden @@shorttitlepage @var{title}
+Generate a minimal title page. @address@hidden@@titlepage}}.
+
address@hidden @@address@hidden@address@hidden
+Set @var{text} in a @slanted{slanted} font if possible. No effect
+in Info. @xref{Fonts}.
+
address@hidden @@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.
address@hidden@t{@@smallbook}}. Also, see @address@hidden@@address@hidden
+
address@hidden @@smalldisplay
+Begin a kind of example. Like @code{@@display}, but use a smaller
+font size where possible. Pair with @code{@@end smalldisplay}.
address@hidden@t{@@address@hidden
+
address@hidden @@smallexample
+Begin an example. Like @code{@@example}, but use a smaller font size
+where possible. Pair with @code{@@end smallexample}.
address@hidden@t{@@address@hidden
+
address@hidden @@smallformat
+Begin a kind of example. Like @code{@@format}, but use a smaller font
+size where possible. Pair with @code{@@end smallformat}.
address@hidden@t{@@address@hidden
+
address@hidden @@smallindentedblock
+Like @code{@@indentedblock}, but use a smaller font size where
+possible. Pair with @code{@@end smallindentedblock}.
address@hidden@t{@@address@hidden
+
address@hidden @@smalllisp
+Begin an example of Lisp code. Same as @code{@@smallexample}. Pair
+with @code{@@end smalllisp}. @address@hidden@@address@hidden
+
address@hidden @@smallquotation
+Like @code{@@quotation}, but use a smaller font size where possible.
+Pair with @code{@@end smallquotation}. @address@hidden@@address@hidden
+
address@hidden @@sp @var{n}
+Skip @var{n} blank lines. @address@hidden@@sp}}.
+
address@hidden @@address@hidden@}
+Generate the German sharp-S es-zet letter, @ss{}. @xref{Inserting Accents}.
+
address@hidden @@strong @address@hidden@}
+Emphasize @var{text} more strongly than @code{@@emph}, by using
address@hidden where possible; enclosed in asterisks in Info.
address@hidden & strong, , Emphasizing Text}.
+
address@hidden @@subheading @var{title}
+Print an unnumbered subsection-like heading, but omit from the table
+of contents of a printed manual. In Info, the title is underlined
+with hyphens. @address@hidden@@unnumberedsubsec @@appendixsubsec
@@subheading}}.
+
address@hidden @@subsection @var{title}
+Begin a subsection within a section. The subsection title appears in
+the table of contents. In Info, the title is underlined with hyphens.
+Same context-dependent numbering as @code{@@section}.
address@hidden@t{@@subsection}}.
+
address@hidden @@subsubheading @var{title}
+Print an unnumbered subsubsection-like heading, but omit from the
+table of contents of a printed manual. In Info, the title is
+underlined with periods. @address@hidden@@subsubsection}}.
+
address@hidden @@subsubsection @var{title}
+Begin a subsubsection within a subsection. The subsubsection title
+appears in the table of contents. In Info, the title is underlined
+with periods. Same context-dependent numbering as @code{@@section}.
address@hidden@t{@@subsubsection}}.
+
address@hidden @@subtitle @var{title}
+In a printed manual, set a subtitle in a normal sized font flush to
+the right-hand side of the page. Not relevant to Info, which does not
+have title pages. @address@hidden@@title @@subtitle @@author}}.
+
address@hidden @@summarycontents
+Print a short table of contents. Synonym for @code{@@shortcontents}.
address@hidden, , Generating a Table of Contents}.
+
address@hidden @@syncodeindex @var{from-index} @var{to-index}
+Merge the index named in the first argument into the index named in
+the second argument, formatting the entries from the first index with
address@hidden@@code}. @xref{Combining Indices}.
+
address@hidden @@synindex @var{from-index} @var{to-index}
+Merge the index named in the first argument into the index named in
+the second argument. Do not change the font of @var{from-index}
+entries. @xref{Combining Indices}.
+
address@hidden @@address@hidden@address@hidden
+Set @var{text} in a @t{fixed-width}, typewriter-like font. No effect
+in Info. @xref{Fonts}.
+
address@hidden @@tab
+Separate columns in a row of a multitable. @xref{Multitable Rows}.
+
address@hidden @@table @var{formatting-command}
+Begin a two-column table (description list), using @code{@@item} for
+each entry. Write each first column entry on the same line as
address@hidden@@item}. First column entries are printed in the font resulting
+from @var{formatting-command}. Pair with @code{@@end table}.
address@hidden Tables, , Making a Two-column Table}. Also see
address@hidden@t{@@ftable @@vtable}}, and @address@hidden@@itemx}}.
+
address@hidden @@address@hidden@}
+Generate the @TeX{} logo. @address@hidden@@TeX @@LaTeX}}.
+
address@hidden @@tex
+Enter @TeX{} completely. Pair with @code{@@end tex}. @xref{Raw
+Formatter Commands}.
+
address@hidden @@address@hidden@}
+Generate the degree symbol. @address@hidden@@textdegree}}.
+
address@hidden @@thischapter
address@hidden @@thischaptername
address@hidden @@thischapternum
address@hidden @@thisfile
address@hidden @@thispage
address@hidden @@thistitle
+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
+document, respectively. @xref{Custom Headings, , How to Make Your Own
+Headings}.
+
address@hidden @@address@hidden@}
address@hidden @@address@hidden@}
+Generate the uppercase and lowercase Icelandic letter thorn, respectively:
address@hidden, @th{}. @xref{Inserting Accents}.
+
address@hidden @@address@hidden@}
+Generate a normal interword space at which a line break is not
+allowed. @address@hidden@@tie}}.
+
address@hidden @@address@hidden@address@hidden
+Generate a tie-after accent over the next two characters @var{cc}, as in
address@hidden'. @xref{Inserting Accents}.
+
address@hidden @@tindex @var{entry}
+Add @var{entry} to the index of data types. @xref{Index Entries, ,
+Defining the Entries of an Index}.
+
address@hidden @@title @var{title}
+In a printed manual, set a title flush to the left-hand side of the
+page in a larger than normal font and underline it with a black rule.
+Not relevant to Info, which does not have title pages.
address@hidden@t{@@title @@subtitle @@author}}.
+
address@hidden @@address@hidden@address@hidden
+In a printed manual, print @var{text} in a larger than normal font.
address@hidden@t{@@titlefont @@center @@sp}}.
+
address@hidden @@titlepage
+Begin the title page. Write the command on a line of its own, paired
+with @code{@@end titlepage}. Nothing between @code{@@titlepage} and
address@hidden@@end titlepage} appears in Info. @address@hidden@@titlepage}}.
+
address@hidden @@address@hidden@}
+Insert the current date, in `1 Jan 1900' style. @xref{Custom
+Headings, , How to Make Your Own Headings}.
+
address@hidden @@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
address@hidden@@ifnottex ... @@end ifnottex}. In @TeX{} and
address@hidden, the @code{@@top} command is merely a
+synonym for @code{@@unnumbered}. @address@hidden Pointer
+Creation}.
+
address@hidden @@address@hidden@address@hidden
address@hidden @@address@hidden@address@hidden
address@hidden @@address@hidden@address@hidden
+Generate a breve, underbar, or underdot accent, respectively, over or
+under the character @var{c}, as in @u{o}, @ubaraccent{o},
address@hidden @xref{Inserting Accents}.
+
address@hidden @@unmacro @var{macroname}
+Undefine the macro @code{@@@var{macroname}} if it has been defined.
address@hidden Macros}.
+
address@hidden @@unnumbered @var{title}
+Begin a chapter that appears without chapter numbers of any kind. The
+title appears in the table of contents. In Info, the title is
+underlined with asterisks. @address@hidden@@unnumbered @@appendix}}.
+
address@hidden @@unnumberedsec @var{title}
+Begin a section that appears without section numbers of any kind. The
+title appears in the table of contents of a printed manual. In Info,
+the title is underlined with equal signs. @address@hidden@@unnumberedsec
+@@appendixsec @@heading}}.
+
address@hidden @@unnumberedsubsec @var{title}
+Begin an unnumbered subsection. The title appears in the table of
+contents. In Info, the title is underlined with hyphens.
address@hidden@t{@@unnumberedsubsec @@appendixsubsec @@subheading}}.
+
address@hidden @@unnumberedsubsubsec @var{title}
+Begin an unnumbered subsubsection. The title appears in the table of
+contents. In Info, the title is underlined with periods.
address@hidden@t{@@subsubsection}}.
+
address@hidden @@address@hidden@var{url}[, @var{displayed-text}][,
@address@hidden
address@hidden @@address@hidden@var{url}[, @var{displayed-text}][,
@address@hidden
+Define a cross reference to an external uniform resource locator,
+e.g., for the World Wide Web. @address@hidden@@url}}.
+
address@hidden @@urefbreakstyle @var{style}
+Specify how @code{@@uref}/@code{@@url} should break at special
+characters: @code{after}, @code{before}, @code{none}.
address@hidden@t{@@url}}.
+
address@hidden @@address@hidden@address@hidden
+Generate check accent over the character @var{c}, as in @v{o}.
address@hidden Accents}.
+
address@hidden @@address@hidden@address@hidden
+Insert the value, if any, of the Texinfo variable @var{txivar},
+previously defined by @code{@@set}. @address@hidden@@set @@clear
+@@value}}.
+
address@hidden @@address@hidden@address@hidden
+Highlight a metasyntactic variable, which is something that stands for
+another piece of text. @address@hidden@@var}}.
+
address@hidden @@address@hidden@var{delim} @var{literal} @address@hidden
+Output @var{literal}, delimited by the single character @var{delim},
+exactly as is (in the fixed-width font), including any whitespace or
+Texinfo special characters. @address@hidden@@verb}}.
+
address@hidden @@verbatim
+Output the text of the environment exactly as is (in the fixed-width
+font). Pair with @code{@@end verbatim}. @address@hidden@@verbatim}}.
+
address@hidden @@verbatiminclude @var{filename}
+Output the contents of @var{filename} exactly as is (in the
+fixed-width font). @address@hidden@@verbatiminclude}}.
+
address@hidden @@vindex @var{entry}
+Add @var{entry} to the index of variables. @xref{Index Entries, ,
+Defining the Entries of an Index}.
+
address@hidden @@vskip @var{amount}
+In a printed manual, insert whitespace so as to push text on the
+remainder of the page towards the bottom of the page. Used in
+formatting the copyright page with the argument @samp{0pt plus
+1filll}. (Note spelling of @samp{filll}.) @code{@@vskip} may be used
+only in contexts ignored for Info. @xref{Copyright}.
+
address@hidden @@vtable @var{formatting-command}
+Begin a two-column table, using @code{@@item} for each entry.
+Automatically enter each of the items in the first column into the
+index of variables. Pair with @code{@@end vtable}. The same as
address@hidden@@table}, except for indexing. @address@hidden@@ftable
@@vtable}}.
+
address@hidden @@address@hidden@address@hidden
+Disallow line breaks within @var{text}. @address@hidden@@w}}.
+
address@hidden @@xml
+Enter XML completely. Pair with @code{@@end xml}. @xref{Raw
+Formatter Commands}.
+
address@hidden @@address@hidden@var{node}, address@hidden, address@hidden,
address@hidden, address@hidden@}
+Make a reference that starts with `See' in a printed manual. Follow
+command with a punctuation mark. Only the first argument is
+mandatory. @address@hidden@@xref}}.
+
address@hidden @@xrefautomaticsectiontitle @var{on-off}
+By default, use the section title instead of the node name in cross
+references. @xref{Three Arguments}.
+
address@hidden table
+
+
address@hidden Command Syntax
address@hidden @@-Command Syntax
address@hidden @@-command syntax
address@hidden Syntax, of @@-commands
address@hidden Command syntax
+
+The character @samp{@@} is used to start all Texinfo commands. (It
+has the same meaning that @samp{\} has in plain @TeX{}.) Texinfo has
+four types of @@-command:
+
address@hidden @asis
address@hidden 1. Non-alphabetic commands.
+These 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 the text within a paragraph. The
+non-alphabetic commands include @code{@@@@}, @code{@@@{}, @code{@@@}},
address@hidden@@.}, @code{@@@kbd{SPACE}}, most of the accent commands, and
+many more.
+
address@hidden 2. Alphabetic commands that do not require arguments.
+These commands start with @@ followed by a word followed by a
+left and right- brace. These commands insert special symbols in
+the document; they do not take arguments. Some examples:
address@hidden@@address@hidden@}} @result{} @address@hidden,
@code{@@address@hidden@}}
address@hidden @address@hidden, @code{@@address@hidden@}} @result{}
address@hidden', and
address@hidden@@address@hidden@}} @result{} @address@hidden
+
address@hidden 3. Alphabetic commands that require arguments within braces.
+These commands start with @@ followed by a letter or a word, followed by an
+argument within braces. For example, the command @code{@@dfn} indicates
+the introductory or defining use of a term; it is used as follows: @samp{In
+Texinfo, @@@@-commands are @@address@hidden@} commands.}
+
address@hidden 4. Alphabetic commands that occupy an entire line.
+These commands occupy an entire line. The line starts with @@,
+followed by the name of the command (a word); for example, @code{@@center}
+or @code{@@cindex}. If no argument is needed, the word is followed by
+the end of the line. If there is an argument, it is separated from
+the command name by a space. Braces are not used.
address@hidden table
+
+Whitespace following an @@-command name are optional and (usually)
+ignored if present. The exceptions are contexts whee whitespace is
+significant, e.g., an @code{@@example} environment.
+
address@hidden Braces and argument syntax
+Thus, the alphabetic commands fall into classes that have
+different argument syntaxes. You cannot tell to which class a command
+belongs by the appearance of its name, but you can tell by the
+command's meaning: if the command stands for a glyph, it is in
+class 2 and does not require an argument; if it makes sense to use the
+command among other text as part of a paragraph, the command
+is in class 3 and must be followed by an argument in braces;
+otherwise, it is in class 4 and uses the rest of the line as its
+argument.
+
+The purpose of having a different syntax for commands of classes 3
address@hidden is to make Texinfo files easier to read, and also to help
+the GNU Emacs paragraph and filling commands work properly. There is
+only one exception to this rule: the command @code{@@refill}, which is
+always used at the end of a paragraph immediately following the final
+period or other punctuation character. @code{@@refill} takes no
+argument and does @emph{not} require braces. @code{@@refill} never
+confuses the Emacs paragraph commands because it cannot appear at the
+beginning of a line. It is also no longer needed, since all
+formatters now refill paragraphs automatically.
+
+
address@hidden Command Contexts
address@hidden @@-Command Contexts
+
address@hidden Contexts, of @@-commands
+
+Here we describe approximately which @@-commands can be used in which
+contexts. It merely gives the general idea and 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.
+
+By @dfn{general text} below, we mean anything except sectioning and
+other such outer-level document commands, such as @code{@@section},
address@hidden@@node}, and @code{@@setfilename}.
+
address@hidden@@c}, @code{@@comment} and @code{@@if ... @@end if} conditional
+commands may appear anywhere (except the conditionals must still be on
+lines by themselves). @code{@@caption} may only appear in
address@hidden@@float} but may contain general text. @code{@@footnote}
+content likewise.
+
+@@-commands with braces marking text (such as @code{@@strong},
address@hidden@@sc}, @code{@@asis}) may contain raw formatter commands such as
address@hidden@@html} but no other block commands (other commands terminated
+by @code{@@end}) and may not be split across paragraphs, but may
+otherwise contain general text.
+
+In addition to the block command restriction, on @code{@@center},
address@hidden@@exdent} and @code{@@item} in @code{@@table} lines, @@-commands
+that makes only sense in a paragraph are not accepted, such as
address@hidden@@indent}.
+
+In addition to the above, sectioning commands cannot contain
address@hidden@@anchor}, @code{@@footnote} or @code{@@verb}.
+
+In addition to the above, remaining commands (@code{@@node},
address@hidden@@anchor}, @code{@@printindex}, @code{@@ref}, @code{@@math},
address@hidden@@cindex}, @code{@@url}, @code{@@image}, and so on) cannot
+contain cross reference commands (@code{@@ref}, @code{@@xref},
address@hidden@@pxref} and @code{@@inforef}). In one last addition,
address@hidden@@shortcaption} may only appear inside @code{@@float}.
+
+For precise and complete information, we suggest looking into the
+extensive test suite in the sources, which exhaustively try
+combinations.
+
+
address@hidden Tips
address@hidden Tips and Hints
+
+Here are some tips for writing Texinfo documentation:
+
address@hidden Tips
address@hidden Usage tips
address@hidden Hints
address@hidden @bullet
address@hidden
+Write in the present tense, not in the past or the future.
+
address@hidden
+Write actively! For example, write ``We recommend that @dots{}'' rather
+than ``It is recommended that @dots{}''.
+
address@hidden
+Use 70 or 72 as your fill column. Longer lines are hard to read.
+
address@hidden
+Include a copyright notice and copying permissions.
address@hidden itemize
+
+
address@hidden Index, Index, Index!
+
+Write many index entries, in different ways.
+Readers like indices; they are helpful and convenient.
+
+Although it is easiest to write index entries as you write the body of
+the text, some people prefer to write entries afterwards. In either
+case, write an entry before the paragraph to which it applies. This
+way, an index entry points to the first page of a paragraph that is
+split across pages.
+
+Here are more index-related hints we have found valuable:
+
address@hidden @bullet
address@hidden
+Write each index entry differently, so each entry refers to a different
+place in the document.
+
address@hidden
+Write index entries only where a topic is discussed significantly. For
+example, it is not useful to index ``debugging information'' in a
+chapter on reporting bugs. Someone who wants to know about debugging
+information will certainly not find it in that chapter.
+
address@hidden
+Consistently capitalize the first word of every concept index entry,
+or else consistently use lowercase. Terse entries often call for
+lowercase; longer entries for capitalization. Whichever case
+convention you use, please use one or the other consistently! Mixing
+the two styles looks bad.
+
address@hidden
+Always capitalize or use uppercase for those words in an index for
+which this is proper, such as names of countries or acronyms. Always
+use the appropriate case for case-sensitive names, such as those in C or
+Lisp.
+
address@hidden
+Write the indexing commands that refer to a whole section immediately
+after the section command, and write the indexing commands that refer to
+a paragraph before that paragraph.
+
+In the example that follows, a blank line comes after the index
+entry for ``Leaping'':
+
address@hidden
address@hidden
+@@section The Dog and the Fox
+@@cindex Jumping, in general
+@@cindex Leaping
+
+@@cindex Dog, lazy, jumped over
+@@cindex Lazy dog jumped over
+@@cindex Fox, jumps over dog
+@@cindex Quick fox jumps over dog
+The quick brown fox jumps over the lazy dog.
address@hidden group
address@hidden example
+
address@hidden
+(Note that the example shows entries for the same concept that are
+written in different address@hidden dog}, and @samp{Dog, lazy}---so
+readers can look up the concept in different ways.)
address@hidden itemize
+
+
address@hidden Blank Lines
+
address@hidden @bullet
address@hidden
+Insert a blank line between a sectioning command and the first following
+sentence or paragraph, or between the indexing commands associated with
+the sectioning command and the first following sentence or paragraph, as
+shown in the tip on indexing. It makes the source easier to read.
+
address@hidden
+Always insert a blank line before an @code{@@table} command and after an
address@hidden@@end table} command; but never insert a blank line after an
address@hidden@@table} command.
+
address@hidden 1000
+For example,
+
address@hidden
address@hidden
+Types of fox:
+
+@@table @@samp
+@@item Quick
+Jump over lazy dogs.
address@hidden group
+
address@hidden
+@@item Brown
+Also jump over lazy dogs.
+@@end table
+
address@hidden group
address@hidden
+@@noindent
+On the other hand, @dots{}
address@hidden group
address@hidden example
+
+Insert blank lines before and after @code{@@itemize} @dots{} @code{@@end
+itemize} and @code{@@enumerate} @dots{} @code{@@end enumerate} in the
+same way.
address@hidden itemize
+
+
address@hidden Complete Phrases
+
+Complete phrases are easier to read than @dots{}
+
address@hidden @bullet
address@hidden
+Write entries in an itemized list as complete sentences; or at least, as
+complete phrases. Incomplete expressions @dots{} awkward @dots{} like
+this.
+
address@hidden
+Write the prefatory sentence or phrase for a multi-item list or table as
+a complete expression. Do not write ``You can set:''; instead, write
+``You can set these variables:''. The former expression sounds cut off.
address@hidden itemize
+
+
address@hidden Editions, Dates and Versions
+
+Include edition numbers, version numbers, and dates in the
address@hidden@@copying} text (for people reading the Texinfo file, and for the
+legal copyright in the output files). Then use @code{@@insertcopying}
+in the @code{@@titlepage} section for people reading the printed
+output (@pxref{Short Sample}).
+
+It is easiest to handle such version information using @code{@@set}
+and @code{@@value}. @address@hidden@@value} Example}, and @ref{GNU
+Sample Texts}.
+
+
address@hidden Definition Commands
+
+Definition commands are @code{@@deffn}, @code{@@defun},
address@hidden@@defmac}, and the like, and enable you to write descriptions in
+a uniform format.
+
address@hidden @bullet
address@hidden
+Write just one definition command for each entity you define with a
+definition command. The automatic indexing feature creates an index
+entry that leads the reader to the definition.
+
address@hidden
+Use @code{@@table} @dots{} @code{@@end table} in an appendix that
+contains a summary of functions, not @code{@@deffn} or other definition
+commands.
address@hidden itemize
+
+
address@hidden Capitalization
+
address@hidden @bullet
address@hidden
+Capitalize ``Texinfo''; it is a name. Do not write the @samp{x} or
address@hidden in uppercase.
+
address@hidden
+Capitalize ``Info''; it is a name.
+
address@hidden
+Write @TeX{} using the @code{@@address@hidden@}} command. Note the uppercase
address@hidden and @samp{X}. This command causes the formatters to
+typeset the name according to the wishes of Donald Knuth, who wrote
address@hidden (Likewise @code{@@address@hidden@}} for @LaTeX{}.)
address@hidden itemize
+
+
address@hidden Spaces
+
+Do not use spaces to format a Texinfo file, except inside of
address@hidden@@example} @dots{} @code{@@end example} and other literal
+environments and commands.
+
address@hidden 700
+For example, @TeX{} fills the following:
+
address@hidden
address@hidden
+ @@address@hidden address@hidden
+ @@address@hidden address@hidden
+ Perform the next logical operation
+ on the version-controlled file
+ corresponding to the current buffer.
address@hidden group
address@hidden example
+
address@hidden 950
address@hidden
+so it looks like this:
+
address@hidden
address@hidden
+ @kbd{C-x v}
+ @kbd{M-x vc-next-action}
+ Perform the next logical operation on the version-controlled file
+ corresponding to the current buffer.
address@hidden quotation
address@hidden iftex
address@hidden
address@hidden
+`C-x v' `M-x vc-next-action' Perform the next logical operation on the
+version-controlled file corresponding to the current buffer.
address@hidden quotation
address@hidden ifnottex
+
address@hidden
+In this case, the text should be formatted with
address@hidden@@table}, @code{@@item}, and @code{@@itemx}, to create a table.
+
+
address@hidden @@code, @@samp, @@var, and @samp{---}
+
address@hidden @bullet
address@hidden
+Use @code{@@code} around Lisp symbols, including command names.
+For example,
+
address@hidden
+The main function is @@address@hidden@}, @dots{}
address@hidden example
+
address@hidden
+Avoid putting letters such as @samp{s} immediately after an
address@hidden@@code}. Such letters look bad.
+
address@hidden
+Use @code{@@var} around meta-variables. Do not write angle brackets
+around them.
+
address@hidden
+Use three hyphens in a row, @samp{---}, to indicate a long dash. @TeX{}
+typesets these as a long dash and the Info formatters reduce three
+hyphens to two.
address@hidden itemize
+
+
address@hidden Periods Outside of Quotes
+
+Place periods and other punctuation marks @emph{outside} of quotations,
+unless the punctuation is part of the quotation. This practice goes
+against some publishing conventions in the United States, but enables the
+reader to distinguish between the contents of the quotation and the
+whole passage.
+
+For example, you should write the following sentence with the period
+outside the end quotation marks:
+
address@hidden
+Evidently, @samp{au} is an abbreviation for ``author''.
address@hidden example
+
address@hidden
+since @samp{au} does @emph{not} serve as an abbreviation for
address@hidden (with a period following the word).
+
+
address@hidden Introducing New Terms
+
address@hidden @bullet
address@hidden
+Introduce new terms so that a reader who does not know them can
+understand them from context; or write a definition for the term.
+
+For example, in the following, the terms ``check in'', ``register'' and
+``delta'' are all appearing for the first time; the example sentence should be
+rewritten so they are understandable.
+
address@hidden
+The major function assists you in checking in a file to your
+version control system and registering successive sets of changes to
+it as deltas.
address@hidden quotation
+
address@hidden
+Use the @code{@@dfn} command around a word being introduced, to indicate
+that the reader should not expect to know the meaning already, and
+should expect to learn the meaning from this passage.
address@hidden itemize
+
+
address@hidden Program Invocation Nodes
+
+You can invoke programs such as Emacs, GCC, and @code{gawk} from a
+shell. The documentation for each program should contain a section that
+describes this. Unfortunately, if the node names and titles for these
+sections are all different, they are difficult for users to find.
+
+So, there is a convention to name such sections with a phrase beginning
+with the word `Invoking', as in `Invoking Emacs'; this way, users can
+find the section easily.
+
+
address@hidden ANSI C Syntax
+
+When you use @code{@@example} to describe a C function's calling
+conventions, use the ANSI C syntax, like this:
+
address@hidden
+void dld_init (char *@@address@hidden@});
address@hidden example
+
address@hidden
+And in the subsequent discussion, refer to the argument values by
+writing the same argument names, again highlighted with
address@hidden@@var}.
+
address@hidden 800
+Avoid the obsolete style that looks like this:
+
address@hidden
+#include <dld.h>
+
+dld_init (path)
+ char *path;
address@hidden example
+
+Also, it is best to avoid writing @code{#include} above the
+declaration just to indicate that the function is declared in a
+header file. The practice may give the misimpression that the
address@hidden belongs near the declaration of the function. Either
+state explicitly which header file holds the declaration or, better
+yet, name the header file used for a group of functions at the
+beginning of the section that describes the functions.
+
address@hidden
address@hidden Node Length
+
+Keep nodes (sections) to a reasonable length, whatever reasonable
+might be in the given context. Don't hesitate break up long nodes
+into subnodes and have an extensive tree structure; that's what it's
+there for. Many times, readers will probably try to find a single
+specific point in the manual, using search, indexing, or just plain
+guessing, rather than reading the whole thing from beginning to end.
+
+You can use the @command{texi-elements-by-size} utility to see a list
+of all nodes (or sections) in the document, sorted by size (either
+lines or words), to find candidates for splitting. It's in the
address@hidden/} subdirectory of the Texinfo sources.
+
+
address@hidden Bad Examples
+
+Here are several examples of bad writing to avoid:
+
+In this example, say, `` @dots{} you must @code{@@address@hidden
address@hidden the new version.'' That flows better.
+
address@hidden
+When you are done editing the file, you must perform a
address@hidden@@address@hidden address@hidden
address@hidden quotation
+
+In the following example, say, address@hidden makes a unified interface such
as VC
+mode possible.''
+
address@hidden
+SCCS, RCS and other version-control systems all perform similar
+functions in broadly similar ways (it is this resemblance which makes
+a unified control mode like this possible).
address@hidden quotation
+
+And in this example, you should specify what `it' refers to:
+
address@hidden
+If you are working with other people, it assists in coordinating
+everyone's changes so they do not step on each other.
address@hidden quotation
+
+
address@hidden And Finally @dots{}
+
address@hidden @bullet
address@hidden
+Pronounce @TeX{} as if the @samp{X} were a Greek `chi', as the last
+sound in the name `Bach'. But pronounce Texinfo as in `speck':
+``teckinfo''.
+
address@hidden
+Write notes for yourself at the very end of a Texinfo file after the
address@hidden@@bye}. None of the formatters process text after the
address@hidden@@bye}; it is as if the text were within @code{@@ignore} @dots{}
address@hidden@@end ignore}.
address@hidden itemize
+
+
address@hidden Sample Texinfo Files
address@hidden Sample Texinfo Files
address@hidden Sample Texinfo files
+
+The first example is from the first chapter (@pxref{Short Sample}),
+given here in its entirety, without commentary. The second
+includes the full texts to be used in GNU manuals.
+
address@hidden
+* Short Sample Texinfo File::
+* GNU Sample Texts::
+* Verbatim Copying License::
+* All-permissive Copying License::
address@hidden menu
+
+
address@hidden Short Sample Texinfo File
address@hidden Short Sample
address@hidden Sample Texinfo file, no comments
+
+Here is a complete, short sample Texinfo file, without any commentary.
+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.
+
+
address@hidden 1
address@hidden
+\input texinfo @@c -*-texinfo-*-
+@@c %**start of header
+@@setfilename sample.info
+@@settitle Sample Manual 1.0
+@@c %**end of header
+
+@@copying
+This is a short example of a complete Texinfo file.
+
+Copyright @@address@hidden@} 2013 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
+
+@@insertcopying
+@@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
address@hidden example
+
+
address@hidden GNU Sample Texts
address@hidden GNU Sample Texts
+
address@hidden GNU sample texts
address@hidden Sample texts, GNU
address@hidden Full texts, GNU
+
+Following is a sample Texinfo document with the full texts that should
+be used (adapted as necessary) in GNU manuals.
+
+As well as the legal texts, it also serves as a practical example of how
+many elements in a GNU system can affect the manual. If you're not
+familiar with all these different elements, don't worry. They're not
+required and a perfectly good manual can be written without them.
+They're included here nonetheless because many manuals do (or could)
+benefit from them.
+
address@hidden Sample}, for a minimal example of a Texinfo file.
address@hidden a File}, for a full explanation of that minimal
+example.
+
+Here are some notes on the example:
+
address@hidden @bullet
address@hidden
address@hidden $Id
address@hidden CVS $Id
address@hidden RCS $Id
address@hidden Documentation identification
address@hidden Identification of documentation
+The @samp{$Id:} comment is for the CVS (@pxref{Top,,, cvs, Concurrent
+Versions System}), RCS (@pxref{Top,,, rcs, Revision Control System})
+and other version control systems, which expand it into a string such
+as:
+
address@hidden
+$Id$
address@hidden 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 @address@hidden, use @code{@@w}:
address@hidden@@address@hidden@}Id$}. Unfortunately, this technique does not
work in
+plain text output, where it's not clear what should be done.
+
address@hidden
address@hidden address@hidden, and version info}
address@hidden UPDATED @r{Automake variable}
address@hidden VERSION @r{Automake variable}
address@hidden time-stamp.el
+The @file{version.texi} in the @code{@@include} command is maintained
+automatically by Automake (@pxref{Top,,, automake, GNU Automake}). It
+sets the @samp{VERSION} and @samp{UPDATED} values used elsewhere. If
+your distribution doesn't use Automake, but you do use Emacs, you may
+find the time-stamp.el package helpful (@pxref{Time Stamps,,, emacs,
+The GNU Emacs Manual}).
+
address@hidden
+The @code{@@syncodeindex} command reflects the recommendation to use
+only one index where possible, to make it easier for readers to look up
+index entries.
+
address@hidden
+The @code{@@dircategory} is for constructing the Info directory.
address@hidden Dir Entries}, which includes a variety of recommended
+category names.
+
address@hidden
+The `Invoking' node is a GNU standard to help users find the basic
+information about command-line usage of a given program. @xref{Manual
+Structure Details,,, standards, GNU Coding Standards}.
+
address@hidden
address@hidden GNU Free Documentation License, including entire
address@hidden 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}.
+
address@hidden
+If the FSF is not the copyright holder, then use the appropriate name.
+
address@hidden
+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}).
+
address@hidden
+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 address@hidden @xref{Verbatim Copying
+License}.
+
address@hidden itemize
+
+Here is the sample document:
+
address@hidden
+\input texinfo @c -*-texinfo-*-
address@hidden address@hidden
address@hidden %**start of header
address@hidden sample.info
address@hidden version.texi
address@hidden GNU Sample @value{VERSION}
address@hidden pg cp
address@hidden %**end of header
address@hidden
+This manual is for GNU Sample (version @value{VERSION}, @value{UPDATED}),
+which is an example in the Texinfo documentation.
+
+Copyright @copyright{} 2013 Free Software Foundation, Inc.
+
address@hidden
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
+Texts. A copy of the license is included in the section entitled
+``GNU Free Documentation License''.
address@hidden quotation
address@hidden copying
+
address@hidden Texinfo documentation system
address@hidden
+* sample: (sample)Invoking sample.
address@hidden direntry
+
address@hidden
address@hidden GNU Sample
address@hidden for version @value{VERSION}, @value{UPDATED}
address@hidden A.U. Thor (@email{bug-sample@@gnu.org})
address@hidden
address@hidden 0pt plus 1filll
address@hidden
address@hidden titlepage
+
address@hidden
+
address@hidden
address@hidden Top
address@hidden GNU Sample
+
+This manual is for GNU Sample (version @value{VERSION}, @value{UPDATED}).
address@hidden ifnottex
+
address@hidden
+* Invoking sample::
+* GNU Free Documentation License::
+* Index::
address@hidden menu
+
+
address@hidden Invoking sample
address@hidden Invoking sample
+
address@hidden sample
address@hidden invoking @command{sample}
+
+This is a sample manual. There is no sample program to
+invoke, but if there were, you could see its basic usage
+and command line options here.
+
+
address@hidden GNU Free Documentation License
address@hidden GNU Free Documentation License
+
address@hidden fdl.texi
+
+
address@hidden Index
address@hidden Index
+
address@hidden cp
+
address@hidden
address@hidden verbatim
+
+
address@hidden Verbatim Copying License
address@hidden Verbatim Copying License
+
address@hidden Verbatim copying license
address@hidden License for verbatim copying
+
+For software manuals and other documentation, it is critical to use a
+license permitting free redistribution and updating, so that when a free
+program is changed, the documentation can be updated as well.
+
+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.
+This is just the license text itself. For a complete sample document,
+see the previous sections.
+
address@hidden
address@hidden
+This document is a sample for allowing verbatim copying only.
+
+Copyright @copyright{} 2013 Free Software Foundation, Inc.
+
address@hidden
+Permission is granted to make and distribute verbatim copies
+of this entire document without royalty provided the
+copyright notice and this permission notice are preserved.
address@hidden quotation
address@hidden copying
address@hidden verbatim
+
+
address@hidden All-permissive Copying License
address@hidden All-permissive Copying License
+
address@hidden All-permissive copying license
address@hidden License for all-permissive copying
+
+For software manuals and other documentation, it is important to use a
+license permitting free redistribution and updating, so that when a free
+program is changed, the documentation can be updated as well.
+
+On the other hand, for small supporting files, short manuals (under 300
+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
+the license text itself. For a complete sample document, see the
+previous sections.
+
address@hidden
+Copyright @@address@hidden@} 2013 Free Software Foundation, Inc.
+
+Copying and distribution of this file, with or without modification,
+are permitted in any medium without royalty provided the copyright
+notice and this notice are preserved.
address@hidden example
+
+
address@hidden Headings
address@hidden Page Headings
address@hidden Headings
address@hidden Footings
address@hidden Page numbering
address@hidden Page headings
address@hidden 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
address@hidden completely different way: @pxref{Customizing HTML Page Layout}.
+Headings and footings have no meaning in Info or the other output
+formats.
+
address@hidden
+* 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.
address@hidden menu
+
address@hidden Headings Introduced
address@hidden 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.
+
+
address@hidden Heading Format
address@hidden 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.
+
address@hidden 950
+A single-sided page looks like this:
+
address@hidden
address@hidden
+ _______________________
+ | |
+ | chapter page number |
+ | |
+ | Start of text ... |
+ | ... |
+ | |
address@hidden group
address@hidden 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
address@hidden@@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.
+
address@hidden 750
+Two pages, side by side as in an open book, look like this:
+
address@hidden
address@hidden
+ _______________________ _______________________
+ | | | |
+ | page number title | | chapter page number |
+ | | | |
+ | Start of text ... | | More text ... |
+ | ... | | ... |
+ | | | |
address@hidden group
address@hidden example
+
address@hidden
+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.
+
address@hidden Heading Choice
address@hidden Specifying the Type of Heading
+
address@hidden 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
address@hidden@@setchapternewpage} command that precedes the
address@hidden@@titlepage} section.
+
address@hidden 1000
+There are four possibilities:
+
address@hidden @asis
address@hidden 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}.
+
address@hidden @code{@@setchapternewpage on}
+Specify the single-sided heading format, with chapters on new pages.
+
address@hidden @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;
address@hidden@t{@@headings}}.)
+
address@hidden @code{@@setchapternewpage odd}
+Specify the double-sided heading format, with chapters on new pages.
address@hidden table
+
address@hidden
+Texinfo lacks an @code{@@setchapternewpage even} command.
+
+
address@hidden Custom Headings
address@hidden 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:
address@hidden @bullet
address@hidden
address@hidden@@everyheading} and @code{@@everyfooting} generate page headers
and
+footers that are the same for both even- and odd-numbered pages.
address@hidden
address@hidden@@evenheading} and @code{@@evenfooting} command generate headers
+and footers for even-numbered (left-hand) pages.
address@hidden
address@hidden@@oddheading} and @code{@@oddfooting} generate headers and footers
+for odd-numbered (right-hand) pages.
address@hidden 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.
+
address@hidden 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:
+
address@hidden
address@hidden
+@@headings off
+@@everyheading @@thischapter @@| @@thispage @@| @@address@hidden@}
address@hidden group
address@hidden example
+
address@hidden
+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.
+
address@hidden 950
+Here are the six heading and footing commands:
+
address@hidden @code
address@hidden @@everyheading @var{left} @@| @var{center} @@| @var{right}
address@hidden @@everyfooting @var{left} @@| @var{center} @@| @var{right}
address@hidden everyheading
address@hidden 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.
+
address@hidden @@evenheading @var{left} @@| @var{center} @@| @var{right}
address@hidden @@oddheading @var{left} @@| @var{center} @@| @var{right}
address@hidden @@evenfooting @var{left} @@| @var{center} @@| @var{right}
address@hidden @@oddfooting @var{left} @@| @var{center} @@| @var{right}
address@hidden evenheading
address@hidden evenfooting
address@hidden oddheading
address@hidden 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.
address@hidden table
+
+Use the @samp{@@address@hidden series of @@-commands to
+provide the names of chapters
+and sections and the page number. You can use the
address@hidden@@address@hidden 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.
+
address@hidden 1000
+Here are the @samp{@@address@hidden commands:
+
address@hidden @code
address@hidden @@thispage
address@hidden thispage
+Expands to the current page number.
+
address@hidden @@thissectionname
address@hidden thissectionname
+Expands to the name of the current section.
+
address@hidden @@thissectionnum
address@hidden thissectionnum
+Expands to the number of the current section.
+
address@hidden @@thissection
address@hidden thissection
+Expands to the number and name of the current section, in the format
+`Section 1: Title'.
+
address@hidden @@thischaptername
address@hidden thischaptername
+Expands to the name of the current chapter.
+
address@hidden @@thischapternum
address@hidden thischapternum
+Expands to the number of the current chapter, or letter of the current
+appendix.
+
address@hidden @@thischapter
address@hidden thischapter
+Expands to the number and name of the current
+chapter, in the format `Chapter 1: Title'.
+
address@hidden @@thistitle
address@hidden thistitle
+Expands to the name of the document, as specified by the
address@hidden@@settitle} command.
+
address@hidden @@thisfile
address@hidden thisfile
+For @code{@@include} files only: expands to the name of the current
address@hidden@@include} file. If the current Texinfo source file is not an
address@hidden@@include} file, this command has no effect. This command does
address@hidden 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.)
address@hidden table
+
address@hidden
+You can also use the @code{@@address@hidden@}} command, which expands to the
+current date, in `1 Jan 1900' format.
address@hidden 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:
+
address@hidden
address@hidden
+@@headings off
+@@everyheading @@address@hidden@} @@| @@thispage @@| @@thischapter
+@@everyfooting @@| @@| Version: 0.27: @@address@hidden@}
address@hidden group
address@hidden 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:
+
address@hidden @code
address@hidden @@everyheadingmarks @var{ref}
address@hidden @@everyfootingmarks @var{ref}
address@hidden everyheadingmarks
address@hidden 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
address@hidden (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.
+
address@hidden @@evenheadingmarks @var{ref}
address@hidden @@oddheadingmarks @var{ref}
address@hidden @@evenfootingmarks @var{ref}
address@hidden @@oddfootingmarks @var{ref}
address@hidden evenheadingmarks
address@hidden oddheadingmarks
address@hidden evenfootingmarks
address@hidden 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.
address@hidden 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.
+
+
address@hidden Catching Mistakes
address@hidden Catching Mistakes
address@hidden Structure, catching mistakes in
address@hidden Nodes, catching mistakes
address@hidden Catching mistakes
address@hidden Correcting mistakes
address@hidden Mistakes, catching
address@hidden Problems, catching
address@hidden Debugging the Texinfo structure
+
+Besides mistakes in the content of your documentation, there are two
+kinds of mistake you can make with Texinfo: you can make mistakes with
+@@-commands, and you can make mistakes with the structure of the nodes
+and chapters.
+
+Emacs has two tools for catching the @@-command mistakes and two for
+catching structuring mistakes.
+
+For finding problems with @@-commands, you can run @TeX{} or a region
+formatting command on the region that has a problem; indeed, you can
+run these commands on each region as you write it.
+
+For finding problems with the structure of nodes and chapters, you can use
address@hidden C-s} (@code{texinfo-show-structure}) and the related @code{occur}
+command and you can use the @kbd{M-x Info-validate} command.
+
address@hidden
+* @t{makeinfo} Preferred:: @code{makeinfo} finds errors.
+* Debugging with Info:: How to catch errors with Info formatting.
+* Debugging with @TeX{}:: How to catch errors with @TeX{} formatting.
+* Using @t{texinfo-show-structure}:: How to use @code{texinfo-show-structure}.
+* Using @t{occur}:: How to list all lines containing a pattern.
+* Running @t{Info-validate}:: How to find badly referenced nodes.
address@hidden menu
+
+
address@hidden @t{makeinfo} Preferred
address@hidden @code{makeinfo} Preferred
+
address@hidden anchor{makeinfo address@hidden prev name
+
+The @code{makeinfo} program does an excellent job of catching errors
+and reporting them---far better than @code{texinfo-format-region} or
address@hidden In addition, the various functions for
+automatically creating and updating node pointers and menus remove
+many opportunities for human error.
+
+If you can, use the updating commands to create and insert pointers
+and menus. These prevent many errors. Then use @code{makeinfo} (or
+its Texinfo mode manifestations, @code{makeinfo-region} and
address@hidden) 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.
+
+
address@hidden Debugging with Info
address@hidden Catching Errors with Info Formatting
address@hidden Catching errors with Info formatting
address@hidden Debugging with Info formatting
+
+After you have written part of a Texinfo file, you can use the
address@hidden or the @code{makeinfo-region} command to
+see whether the region formats properly.
+
+Most likely, however, you are reading this section because for some
+reason you cannot use the @code{makeinfo-region} command; therefore, the
+rest of this section presumes that you are using
address@hidden
+
+If you have made a mistake with an @@-command,
address@hidden will stop processing at or after the
+error and display an error message. To see where in the buffer the
+error occurred, switch to the @samp{*Info Region*} buffer; the cursor
+will be in a position that is after the location of the error. Also,
+the text will not be formatted after the place where the error
+occurred (or more precisely, where it was detected).
+
+For example, if you accidentally end a menu with the command @code{@@end
+menus} with an `s' on the end, instead of with @code{@@end menu}, you
+will see an error message that says:
+
address@hidden
+@@end menus is not handled by texinfo
address@hidden example
+
address@hidden
+The cursor will stop at the point in the buffer where the error
+occurs, or not long after it. The buffer will look like this:
+
address@hidden
address@hidden
+---------- Buffer: *Info Region* ----------
+* Menu:
+
+* Using texinfo-show-structure:: How to use
+ `texinfo-show-structure'
+ to catch mistakes.
+* Running Info-validate:: How to check for
+ unreferenced nodes.
+@@end menus
address@hidden
+---------- Buffer: *Info Region* ----------
address@hidden group
address@hidden example
+
+The @code{texinfo-format-region} command sometimes provides slightly
+odd error messages. For example, the following cross reference fails to
format:
+
address@hidden
+(@@address@hidden Mistakes, for more info.)
address@hidden example
+
address@hidden
+In this case, @code{texinfo-format-region} detects the missing closing
+brace but displays a message that says @samp{Unbalanced parentheses}
+rather than @samp{Unbalanced braces}. This is because the formatting
+command looks for mismatches between braces as if they were
+parentheses.
+
+Sometimes @code{texinfo-format-region} fails to detect mistakes. For
+example, in the following, the closing brace is swapped with the
+closing parenthesis:
+
address@hidden
+(@@address@hidden Mistakes), for more address@hidden
address@hidden example
+
address@hidden
+Formatting produces:
address@hidden
+(*Note for more info.: Catching Mistakes)
address@hidden example
+
+The only way for you to detect this error is to realize that the
+reference should have looked like this:
+
address@hidden
+(*Note Catching Mistakes::, for more info.)
address@hidden example
+
+Incidentally, if you are reading this node in Info and type @kbd{f
address@hidden (@code{Info-follow-reference}), you will generate an error
+message that says:
+
address@hidden
+No such node: "Catching Mistakes) The only way @dots{}
address@hidden example
+
address@hidden
+This is because Info perceives the example of the error as the first
+cross reference in this node and if you type a @key{RET} immediately
+after typing the Info @kbd{f} command, Info will attempt to go to the
+referenced node. If you type @kbd{f catch @key{TAB} @key{RET}}, Info
+will complete the node name of the correctly written example and take
+you to the `Catching Mistakes' node. (If you try this, you can return
+from the `Catching Mistakes' node by typing @kbd{l}
+(@code{Info-last}).)
+
+
address@hidden Debugging with @TeX{}
address@hidden Debugging with @TeX{}
address@hidden Catching errors with @TeX{} formatting
address@hidden Debugging with @TeX{} formatting
+
+You can also catch mistakes when you format a file with @TeX{}.
+
+Usually, you will want to do this after you have run
address@hidden (or, better, @code{makeinfo-buffer}) on
+the same file, because @code{texinfo-format-buffer} sometimes displays
+error messages that make more sense than @TeX{}. (@xref{Debugging
+with Info}, for more information.)
+
+For example, @TeX{} was run on a Texinfo file, part of which is shown
+here:
+
address@hidden
+---------- Buffer: texinfo.texi ----------
+name of the Texinfo file as an extension. The
+@@address@hidden@} are `wildcards' that cause the shell to
+substitute all the raw index files. (@@address@hidden
+indices, for more information about sorting
+indices.)@@refill
+---------- Buffer: texinfo.texi ----------
address@hidden example
+
address@hidden
+(The cross reference lacks a closing brace.)
address@hidden produced the following output, after which it stopped:
+
address@hidden
+---------- Buffer: *tex-shell* ----------
+Runaway argument?
address@hidden indices, for more information about sorting
+indices.) @@refill @@ETC.
+! Paragraph ended before @@xref was complete.
+<to be read again>
+ @@par
+l.27
+
+?
+---------- Buffer: *tex-shell* ----------
address@hidden example
+
+In this case, @TeX{} produced an accurate and
+understandable error message:
+
address@hidden
+Paragraph ended before @@xref was complete.
address@hidden example
+
address@hidden
address@hidden@@par} is an internal @TeX{} command of no relevance to Texinfo.
address@hidden means that @TeX{} detected the problem on line 27 of the
+Texinfo file. The @samp{?} is the prompt @TeX{} uses in this
+circumstance.
+
+Unfortunately, @TeX{} is not always so helpful, and sometimes you must
+truly be a Sherlock Holmes to discover what went wrong.
+
+In any case, if you run into a problem like this, you can do one of three
+things.
+
address@hidden
address@hidden
+You can tell @TeX{} to continue running and ignore just this error by
+typing @key{RET} at the @samp{?} prompt.
+
address@hidden
+You can tell @TeX{} to continue running and to ignore all errors as best
+it can by typing @kbd{r @key{RET}} at the @samp{?} prompt.
+
+This is often the best thing to do. However, beware: the one error
+may produce a cascade of additional error messages as its consequences
+are felt through the rest of the file. To stop @TeX{} when it is
+producing such an avalanche of error messages, type @kbd{C-c} (or
address@hidden C-c}, if you are running a shell inside Emacs).
+
address@hidden
+You can tell @TeX{} to stop this run by typing @kbd{x @key{RET}}
+at the @samp{?} prompt.
address@hidden enumerate
+
+If you are running @TeX{} inside Emacs, you need to switch to the shell
+buffer and line at which @TeX{} offers the @samp{?} prompt.
+
+Sometimes @TeX{} will format a file without producing error messages even
+though there is a problem. This usually occurs if a command is not ended
+but @TeX{} is able to continue processing anyhow. For example, if you fail
+to end an itemized list with the @code{@@end itemize} command, @TeX{} will
+write a DVI file that you can print out. The only error message that
address@hidden will give you is the somewhat mysterious comment:
+
address@hidden
+(@@end occurred inside a group at level 1)
address@hidden example
+
address@hidden
+However, if you print the DVI file, you will find that the text
+of the file that follows the itemized list is entirely indented as if
+it were part of the last item in the itemized list. The error message
+is the way @TeX{} says that it expected to find an @code{@@end}
+command somewhere in the file; but that it could not determine where
+it was needed.
+
+Another source of notoriously hard-to-find errors is a missing
address@hidden@@end group} command. If you ever are stumped by
+incomprehensible errors, look for a missing @code{@@end group} command
+first.
+
+If the Texinfo file lacks header lines,
address@hidden may stop in the
+beginning of its run and display output that looks like the following.
+The @samp{*} indicates that @TeX{} is waiting for input.
+
address@hidden
+This is TeX, Version 3.14159 (Web2c 7.0)
+(test.texinfo [1])
+*
address@hidden example
+
address@hidden
+In this case, simply type @kbd{\end @key{RET}} after the asterisk. Then
+write the header lines in the Texinfo file and run the @TeX{} command
+again. (Note the use of the backslash, @samp{\}. @TeX{} uses @samp{\}
+instead of @samp{@@}; and in this circumstance, you are working
+directly with @TeX{}, not with Texinfo.)
+
address@hidden Using @t{texinfo-show-structure}
address@hidden Using @code{texinfo-show-structure}
+
address@hidden Showing the structure of a file
address@hidden texinfo-show-structure
+
+It is not always easy to keep track of the nodes, chapters, sections, and
+subsections of a Texinfo file. This is especially true if you are revising
+or adding to a Texinfo file that someone else has written.
+
+In GNU Emacs, in Texinfo mode, the @code{texinfo-show-structure}
+command lists all the lines that begin with the @@-commands that
+specify the structure: @code{@@chapter}, @code{@@section},
address@hidden@@appendix}, and so on. With an argument (@address@hidden
+as prefix argument, if interactive),
+the command also shows the @code{@@node} lines. The
address@hidden command is bound to @kbd{C-c C-s} in
+Texinfo mode, by default.
+
+The lines are displayed in a buffer called the @samp{*Occur*} buffer,
+indented by hierarchical level. For example, here is a part of what was
+produced by running @code{texinfo-show-structure} on this manual:
+
address@hidden
address@hidden
+Lines matching "^@@\\(chapter \\|sect\\|subs\\|subh\\|
+unnum\\|major\\|chapheading \\|heading \\|appendix\\)"
+in buffer texinfo.texi.
address@hidden
+4177:@@chapter Nodes
+4198: @@heading Two Paths
+4231: @@section Node and Menu Illustration
+4337: @@section The @@address@hidden@@@@address@hidden Command
+4393: @@subheading Choosing Node and Pointer Names
+4417: @@subsection How to Write an @@address@hidden@@@@address@hidden
Line
+4469: @@subsection @@address@hidden@@@@address@hidden Line Tips
address@hidden
address@hidden group
address@hidden example
+
+This says that lines 4337, 4393, and 4417 of @file{texinfo.texi} begin
+with the @code{@@section}, @code{@@subheading}, and @code{@@subsection}
+commands respectively. If you move your cursor into the @samp{*Occur*}
+window, you can position the cursor over one of the lines and use the
address@hidden C-c} command (@code{occur-mode-goto-occurrence}), to jump to
+the corresponding spot in the Texinfo file. @xref{Other Repeating
+Search, , Using Occur, emacs, The GNU Emacs Manual}, for more
+information about @code{occur-mode-goto-occurrence}.
+
+The first line in the @samp{*Occur*} window describes the @dfn{regular
+expression} specified by @var{texinfo-heading-pattern}. This regular
+expression is the pattern that @code{texinfo-show-structure} looks for.
address@hidden, , Using Regular Expressions, emacs, The GNU Emacs Manual},
+for more information.
+
+When you invoke the @code{texinfo-show-structure} command, Emacs will
+display the structure of the whole buffer. If you want to see the
+structure of just a part of the buffer, of one chapter, for example,
+use the @kbd{C-x n n} (@code{narrow-to-region}) command to mark the
+region. (@xref{Narrowing, , , emacs, The GNU Emacs Manual}.) This is
+how the example used above was generated. (To see the whole buffer
+again, use @kbd{C-x n w} (@code{widen}).)
+
+If you call @code{texinfo-show-structure} with a prefix argument by
+typing @address@hidden C-c C-s}}, it will list lines beginning with
address@hidden@@node} as well as the lines beginning with the @@-sign commands
+for @code{@@chapter}, @code{@@section}, and the like.
+
+You can remind yourself of the structure of a Texinfo file by looking at
+the list in the @samp{*Occur*} window; and if you have mis-named a node
+or left out a section, you can correct the mistake.
+
address@hidden Using @t{occur}
address@hidden Using @code{occur}
+
address@hidden Occurrences, listing with @code{@@occur}
address@hidden occur
+
+Sometimes the @code{texinfo-show-structure} command produces too much
+information. Perhaps you want to remind yourself of the overall structure
+of a Texinfo file, and are overwhelmed by the detailed list produced by
address@hidden In this case, you can use the @code{occur}
+command directly. To do this, type:
+
address@hidden
address@hidden occur}
address@hidden example
+
address@hidden
+and then, when prompted, type a @dfn{regexp}, a regular expression for
+the pattern you want to match. (@xref{Regexps, , Regular Expressions,
+emacs, The GNU Emacs Manual}.) The @code{occur} command works from
+the current location of the cursor in the buffer to the end of the
+buffer. If you want to run @code{occur} on the whole buffer, place
+the cursor at the beginning of the buffer.
+
+For example, to see all the lines that contain the word
address@hidden@@chapter} in them, just type @samp{@@chapter}. This will
+produce a list of the chapters. It will also list all the sentences
+with @samp{@@chapter} in the middle of the line.
+
+If you want to see only those lines that start with the word
address@hidden@@chapter}, type @samp{^@@chapter} when prompted by
address@hidden If you want to see all the lines that end with a word
+or phrase, end the last word with a @samp{$}; for example,
address@hidden mistakes$}. This can be helpful when you want to see
+all the nodes that are part of the same chapter or section and
+therefore have the same `Up' pointer.
+
address@hidden Repeating Search, , Using Occur, emacs , The GNU Emacs Manual},
+for more information.
+
+
address@hidden Running @t{Info-validate}
address@hidden Finding Badly Referenced Nodes
+
address@hidden address@hidden old name
address@hidden Info-validate
address@hidden Nodes, checking for badly referenced
address@hidden Checking for badly referenced nodes
address@hidden Looking for badly referenced nodes
address@hidden Finding badly referenced nodes
address@hidden Badly referenced nodes
+
+You can use the @code{Info-validate} command to check whether any of
+the `Next', `Previous', `Up' or other node pointers fail to point to a
+node. This command checks that every node pointer points to an
+existing node. The @code{Info-validate} command works only on Info
+files, not on Texinfo files.
+
+The @code{makeinfo} program validates pointers automatically, so you
+do not need to use the @code{Info-validate} command if you are using
address@hidden You only may need to use @code{Info-validate} if you
+are unable to run @code{makeinfo} and instead must create an Info file
+using @code{texinfo-format-region} or @code{texinfo-format-buffer}, or
+if you write an Info file from scratch.
+
address@hidden
+* Using @t{Info-validate}:: How to run @code{Info-validate}.
+* Unsplit:: How to create an unsplit file.
+* Tagifying:: How to tagify a file.
+* Splitting:: How to split a file manually.
address@hidden menu
+
+
address@hidden Using @t{Info-validate}
address@hidden Using @code{Info-validate}
+
address@hidden Using @code{Info-validate}
address@hidden Info validating a large file
address@hidden Validating a large file
+
+To use @code{Info-validate}, visit the Info file you wish to check and
+type:
+
address@hidden
+M-x Info-validate
address@hidden example
+
address@hidden
+Note that the @code{Info-validate} command requires an uppercase
+`I'@. You may also need to create a tag table before running
address@hidden @xref{Tagifying}.
+
+If your file is valid, you will receive a message that says ``File appears
+valid''. However, if you have a pointer that does not point to a node,
+error messages will be displayed in a buffer called @samp{*problems in
+info file*}.
+
+For example, @code{Info-validate} was run on a test file that contained
+only the first node of this manual. One of the messages said:
+
address@hidden
+In node "Overview", invalid Next: Texinfo Mode
address@hidden example
+
address@hidden
+This meant that the node called @samp{Overview} had a `Next' pointer that
+did not point to anything (which was true in this case, since the test file
+had only one node in it).
+
+Now suppose we add a node named @samp{Texinfo Mode} to our test case
+but we do not specify a `Previous' for this node. Then we will get
+the following error message:
+
address@hidden
+In node "Texinfo Mode", should have Previous: Overview
address@hidden example
+
address@hidden
+This is because every `Next' pointer should be matched by a
+`Previous' (in the node where the `Next' points) which points back.
+
address@hidden also checks that all menu entries and cross references
+point to actual nodes.
+
address@hidden requires a tag table and does not work with files
+that have been split. (The @code{texinfo-format-buffer} command
+automatically splits large files.) In order to use @code{Info-validate}
+on a large file, you must run @code{texinfo-format-buffer} with an
+argument so that it does not split the Info file; and you must create a
+tag table for the unsplit file.
+
address@hidden Unsplit
address@hidden Creating an Unsplit File
address@hidden Creating an unsplit file
address@hidden Unsplit file creation
+
+You can run @code{Info-validate} only on a single Info file that has a
+tag table. The command will not work on the indirect subfiles that
+are generated when a master file is split. If you have a large file
+(longer than 300,000 bytes or so), you need to run the
address@hidden or @code{makeinfo-buffer} command in such
+a way that it does not create indirect subfiles. You will also need
+to create a tag table for the Info file. After you have done this,
+you can run @code{Info-validate} and look for badly referenced
+nodes.
+
+The first step is to create an unsplit Info file. To prevent
address@hidden from splitting a Texinfo file into
+smaller Info files, give a prefix to the @kbd{M-x
+texinfo-format-buffer} command:
+
address@hidden
+C-u M-x texinfo-format-buffer
address@hidden example
+
address@hidden
+or else
+
address@hidden
+C-u C-c C-e C-b
address@hidden example
+
address@hidden
+When you do this, Texinfo will not split the file and will not create
+a tag table for it.
address@hidden Making a tag table manually
address@hidden Tag table, making manually
+
address@hidden Tagifying
address@hidden Tagifying a File
+
+After creating an unsplit Info file, you must create a tag table for
+it. Visit the Info file you wish to tagify and type:
+
address@hidden
+M-x Info-tagify
address@hidden example
+
address@hidden
+(Note the uppercase @samp{I} in @code{Info-tagify}.) This creates an
+Info file with a tag table that you can validate.
+
+The third step is to validate the Info file:
+
address@hidden
+M-x Info-validate
address@hidden example
+
address@hidden
+(Note the uppercase @samp{I} in @code{Info-validate}.)
+In brief, the steps are:
+
address@hidden
address@hidden
+C-u M-x texinfo-format-buffer
+M-x Info-tagify
+M-x Info-validate
address@hidden group
address@hidden example
+
+After you have validated the node structure, you can rerun
address@hidden in the normal way so it will construct a
+tag table and split the file automatically, or you can make the tag
+table and split the file manually.
+
address@hidden Splitting
address@hidden Splitting a File Manually
address@hidden Splitting an Info file manually
address@hidden Info file, splitting manually
+
+You should split a large file or else let the
address@hidden or @code{makeinfo-buffer} command do it
+for you automatically. (Generally you will let one of the formatting
+commands do this job for you. @xref{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.
+
+If an Info file has more than 30 nodes, you should also make a tag
+table for it. @xref{Using @t{Info-validate}}, for information
+about creating a tag table. (Again, tag tables are usually created
+automatically by the formatting command; you only need to create a tag
+table yourself if you are doing the job manually. Most likely, you
+will do this for a large, unsplit file on which you have run
address@hidden)
+
+Visit the Info file you wish to tagify and split and type the two
+commands:
+
address@hidden
+M-x Info-tagify
+M-x Info-split
address@hidden example
+
address@hidden
+(Note that the @samp{I} in @samp{Info} is uppercase.)
+
+When you use the @code{Info-split} command, the buffer is modified into a
+(small) Info file which lists the indirect subfiles. This file should be
+saved in place of the original visited file. The indirect subfiles are
+written in the same directory the original file is in, with names generated
+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.
+
+
address@hidden Info Format Specification
address@hidden Info Format Specification
+
address@hidden Info format specification
address@hidden Specification of Info format
address@hidden Definition of Info format
+
+Here we describe the technical details of the Info format.
+
+This format definition was written some 25 years after the Info format
+was first devised. So in the event of conflicts between this
+definition and actual practice, practice wins. It also assumes some
+general knowledge of Texinfo; it is meant to be a guide for
+implementors rather than a rigid technical standard. We often refer
+back to other parts of this manual for examples and definitions,
+rather than redundantly spelling out every detail.
+
+In this formal description, the characters @code{<>*()|=#} are used
+for the language of the description itself. Other characters are
+literal. The formal constructs used are typical: @code{<...>}
+indicates a metavariable name, @samp{=} means definition, @samp{*}
+repetition, @samp{?} optional, @samp{()} grouping, @samp{|}
+alternation, @samp{#} comment. Exception: @samp{*} at the beginning
+of a line is literal.
+
+We specify literal parentheses (those that are part of the Info
+format) with @t{<lparen>} and @t{<rparen>}, meaning the single
+characters @samp{(} and @samp{)} respectively.
+
+Finally, the two-character sequence @address@hidden means the single
+character @address@hidden, for any @var{x}.
+
address@hidden
+* General: Info Format General Layout.
+* Text: Info Format Text Constructs.
address@hidden menu
+
+
address@hidden Info Format General Layout
address@hidden Info Format General Layout
+
+This section describes the overall layout of Info manuals.
+
address@hidden
+* Whole: Info Format Whole Manual. Split vs.@: nonsplit manuals.
+* Preamble: Info Format Preamble.
+* Indirect: Info Format Indirect Tag Table.
+* Tag table: Info Format Tag Table.
+* Local variables: Info Format Local Variables.
+* Regular nodes: Info Format Regular Nodes.
address@hidden menu
+
+
address@hidden Info Format Whole Manual
address@hidden Info Format: A Whole Manual
+
address@hidden Nonsplit manuals, Info format of
address@hidden Split manuals, Info format of
address@hidden Whole manual, in Info format
+
+To begin, an Info manual is either @dfn{nonsplit} (contained wholly
+within a single file) or @dfn{split} (across several files).
+
+The syntax for a nonsplit manual is:
+
address@hidden
+ <nonsplit info file> =
+<preamble>
+<node>*
+<tag table>
+(<local variables>)?
address@hidden example
+
+When split, there is a @dfn{main file}, which contains only pointers
+to the nodes given in other @dfn{subfiles}. The main file looks
+like this:
+
address@hidden
+ <split info main file> =
+<preamble>
+<indirect table>
+<tag table>
+(<local variables>)?
address@hidden example
+
+The subfiles in a split manual have the following syntax:
+
address@hidden
+ <split info subfile> =
+<preamble>
+<node>*
address@hidden example
+
+
address@hidden Info Format Preamble
address@hidden Info Format: Preamble
+
address@hidden Preamble, in Info format
+
+The @t{<preamble>} is text at the beginning of all output files.
+It is not intended to be visible by default in an Info viewer, but
+may be displayed upon user request.
+
address@hidden
+ <preamble> =
+<identification> # "This is FILENAME, produced by ..."
+<copying text> # Expansion of @@copying text.
+<dir entries> # Derived from @@dircategory and @@direntry.
address@hidden example
+
+These pieces are:
+
address@hidden @t
address@hidden <identification line>
+An arbitrary string beginning the output file, followed by a blank
+line.
+
address@hidden <copying text>
+The expansion of an @code{@@copying} environment, if the manual has
+one (@address@hidden@@copying}}).
+
address@hidden <dir entries>
+The result of any @code{@@dircategory} and @code{@@direntry}
+commands present in the manual (@pxref{Installing Dir Entries}).
+
address@hidden table
+
+
address@hidden Info Format Indirect Tag Table
address@hidden Info Format: Indirect Tag Table
+
address@hidden Indirect tag table, in Info format
+
+The indirect table is written to the main file in the case of split
+output only. It specifies the starting byte position of each split
+output file (as a decimal integer):
+
address@hidden
+ <indirect table> =
+^_
+Indirect:
+(<filename>: <bytepos>)*
address@hidden example
+
+The number of preamble bytes written to each output file is included
+in the positions. Neither the preamble nor the size of the top-level
+output file is included.
+
+The first actual node of content will be pointed to by the first
+entry.
+
+Unfortunately, Info-creating programs such as @code{makeinfo} have not
+always implemented these rules perfectly, due to various bugs and
+oversights. Therefore, robust Info viewers should fall back to
+searching ``nearby'' the given position for a node, instead of just
+giving up if the position is not perfectly at a node beginning.
+
+As an example, suppose split output is generated for the GDB manual.
+The top-level file @file{gdb.info} will contain something like this:
+
address@hidden
+^_
+Indirect:
+gdb.info-1: 1878
+gdb.info-2: 295733
+...
address@hidden example
+
+This tells Info viewers that the first node of the manual occurs at
+byte 1878 (i.e., after the preamble) of the file @file{gdb.info-1}.
+The first node written to @file{gdb.info-2} would start at byte 295733
+if the subsequent @file{gdb.info-*} files (not including
address@hidden files were appended to @file{gdb.info-1}, including
+their preambles.
+
+
address@hidden Info Format Tag Table
address@hidden Info Format: Tag Table
+
address@hidden Tag table, in Info format
+
+The tag table specifies the starting byte position of each node and anchor
+in the file. It is written in the main output file only, not (in the
+case of split output) any subfiles.
+
address@hidden
+ <tag table> =
+^_
+Tag Table:
+<lparen>Indirect<rparen> # this line appears in split output only
+(Node|Ref): <nodeid>^?<bytepos>
+^_
+End Tag Table
address@hidden example
+
+The @samp{(Indirect)} line is the next line after @samp{Tag Table:}
+in the case of split output only.
+
+Each following line defines an identifier as either an anchor or a
+node, as specific. It is an error to define the same identifier both
+ways. For example, @samp{Node: Top^?1647} says that the node named
address@hidden starts at byte 1647 while @samp{Ref:
+Overview-Footnote-1^?30045} says that the anchor named
address@hidden starts at byte 30045.
+
+In the case of nonsplit output, the byte positions simply refer to the
+location in the output file. In the case of split output, the byte
+positions refer to an imaginary file created by concatenating all the
+split files (but not the top-level file). See the previous section.
+
+Here is an example:
+
address@hidden
+^_
+Tag Table:
+Node: Top^_89
+Node: Ch1^_292
+^_
+End Tag Table
address@hidden example
+
+This specifies a manual with two nodes, `Top' and `Ch1', at byte
+positions 89 and 292 respectively. Because the @samp{(Indirect)} line
+is not present, the manual is not split.
+
+
address@hidden Info Format Local Variables
address@hidden Info Format: Local Variables
+
address@hidden Local variable section, in Info format
+
+The local variables section is optional and is currently used to give the
+encoding information. It may be augmented in the future.
+
address@hidden
+ <local variables> =
+^_
+Local Variables:
+coding: <encoding>
+End:
address@hidden example
+
address@hidden@t{@@documentencoding}}.
+
+
address@hidden Info Format Regular Nodes
address@hidden Info Format: Regular Nodes
+
address@hidden Info nodes, in Info format
+
+Regular nodes look like this:
+
address@hidden
+ <node> =
+^_
+File: <fn>, Node: <id1>, (Next: <id2>, )? (Prev: <id3>, )? Up: <id4>
+
+<general text, until the next ^_ or end-of-file>
address@hidden example
+
+The @code{Next} and @code{Prev} pointers are optional. The @code{Up}
+pointer may technically also be absent, although this is most likely the
+case of a wrongly-structured Info manual. At least one space must be
+present after each colon and comma, but any number of spaces are
+ignored.
+
+This @t{<node>} defines @t{<id1>} in file @t{<fn>}, which is typically
+just @samp{manualname} or perhaps @samp{manualname.info}. Each of the
+other references @t{<id2>}, @t{<id3>}, and @t{<id4>} must be defined
+with either @samp{Node} or @samp{Ref} in the @t{<tag table>}.
+
+Conventionally the nodes are arranged to form a tree, but this is not
+a requirement of the format. Each pointer can refer to any defined
+identifier.
+
+Identifiers cannot include periods, commas, colons or parentheses
+(including @@-commands which produce any of these); these can confuse
+Info readers. @xref{Node Line Requirements}.
+
+The @t{<general text>} of the node can include the special constructs
+described next.
+
+
address@hidden Info Format Text Constructs
address@hidden Info Format Text Constructs
+
address@hidden Info format text constructs
address@hidden text constructs, Info format
+
+These special Info constructs can appear within the text of a node.
+
address@hidden
+* Menu: Info Format Menu.
+* Image: Info Format Image.
+* Printindex: Info Format Printindex.
+* Xref: Info Format Cross Reference.
address@hidden menu
+
+
address@hidden Info Format Menu
address@hidden Info Format: Menu
+
address@hidden Menus, in Info format
+
+Conventionally menus appear at the end of nodes, but the Info format
+places no restrictions on their location.
+
address@hidden
+ <menu> =
+* Menu:
+(<menu entry> | <menu comment>)*
address@hidden example
+
+The parts of a @t{<menu entry>} are described in @ref{Menu Parts}.
+
+A @t{<menu comment>} is any line not beginning with @samp{*} that
+appears either at the beginning of the menu or is separated from a
+menu entry by one or more blank lines. These comments are intended to
+be displayed as part of the menu, as-is (@pxref{Writing a Menu}).
+
+
address@hidden Info Format Image
address@hidden Info Format: Image
+
address@hidden Images, in Info format
+
+The @code{@@image} command results in the following special directive
+within the Info file (@pxref{Images}):
+
address@hidden
+ <image> =
+^@@^H[image src="<image file>"
+ (text="<txt file contents>")?
+ (alt="<alt text>")?
+^@@^H]
address@hidden example
+
+The line breaks and indentation in this description are editorial; the
+whitespace between the different parts of the directive in Info files
+is arbitrary.
+
+In the string @t{<image file>}, @t{<txt file contents>} and @t{<alt
+text>}, @samp{"} is quoted as @samp{\"} and @samp{\} is quoted as
address@hidden The text and alt specifications are optional.
+
+The @t{alt} value serves the same purpose as in HTML: A prose
+description of the image. In text-only displays or speech systems,
+for example, the @t{alt} value may be used instead of displaying the
+(typically graphical) @t{<image file>}.
+
+The @t{<txt file contents>}, if present, should be taken as an ASCII
+representation of the image, and also may be used on a text-only
+display.
+
+The format does not prescribe the choice between displaying the
address@hidden<image file>}, the @t{<alt text>} or @t{<txt file contents>}.
+
+
address@hidden Info Format Printindex
address@hidden Info Format: Printindex
+
address@hidden Indices, in Info format
+
+Indices in Info format are generally written as a menu
+(@pxref{Indices}), but with an additional directive at the beginning
+marking this as an index node:
+
address@hidden
+ <printindex> =
+^@@^H[index^@@^H]
+* Menu:
+
+<index entry>*
address@hidden example
+
+The @t{<index entry>} items are similar to normal menu entries, but
+the free-format description is replaced by the line number of where
+the entries occurs in the text:
+
address@hidden
+ <index entry> =
+* <entry text>: <entry node>. <lparen>line <lineno><rparen>
address@hidden example
+
address@hidden
+The @t{<entry text>} is the index term. The @t{<lineno>} is an
+unsigned integer, given relative to the start of the @t{<entry node>}.
+There may be arbitrary whitespace after the colon and period, as usual
+in menus. Here is an example:
+
address@hidden
+^@@^H[index^@@^H]
+* Menu:
+
+* thunder: Weather Phenomena. (line 5)
address@hidden example
+
+This means that an index entry for `thunder' appears at line 5 of the
+node `Weather Phenomena'.
+
+
address@hidden Info Format Cross Reference
address@hidden Info Format: Cross Reference
+
address@hidden Cross references, in Info format
+
+A general cross reference in Info format is written as follows:
+
address@hidden
+ <cross-reference> =
+* (N|n)ote (<id>:: | <label>:(<lparen><infofile><rparen>)?<id>(.|,))
address@hidden example
+
+Whether @samp{note} or @samp{Note} is used is not significant.
+
+The @samp{<id>::} form indicates a node or anchor reference within the
+current manual.
+
+The longer form indicates a general reference, typically used to refer
+to a node or anchor in a different manual, but possibly to the current
+manual. The @t{<label>} is descriptive text; the optional
address@hidden(<infofile>)} is the filename of the manual being referenced,
+and the @t{<id>} is the node or anchor within that manual, terminated
+by a comma or period. That final punctuation is part of the
+surrounding sentence, and should be displayed.
+
+Here are some examples:
+
address@hidden
+*note GNU Free Documentation License::
+*note Tag table: Info Format Tag Table, for details.
+*Note Overview: (make)Top.
address@hidden example
+
+The first shows the short form, a reference to a node in the current
+manual.
+
+The second also refers to a node in the current manual, namely `Info
+Format Tag Table'; the `Tag table' before the @samp{:} is only a label
+on this particular reference.
+
+The third example refers to the node `Top' in another manual, namely
address@hidden, with `Overview' being the label for this cross reference.
+
address@hidden References}.
+
+
address@hidden The simple description in the command summary seems sufficient
to me
address@hidden these days, so ignore this appendix. --karl, 13mar04.
address@hidden
address@hidden @node Refilling Paragraphs
address@hidden @appendix Refilling Paragraphs
address@hidden @cindex Refilling paragraphs
address@hidden @cindex Filling paragraphs
address@hidden @cindex Paragraphs, filling
address@hidden @findex refill
address@hidden
address@hidden The @code{@@refill} command refills and, optionally, indents the
first
address@hidden line of a address@hidden the command should have been
address@hidden called the @code{@@refillandindent} command, but @code{@@refill}
is
address@hidden shorter and the name was chosen before indenting was possible.}
The
address@hidden @code{@@refill} command is no longer important, but we describe
it here
address@hidden because you once needed it. You will see it in many old Texinfo
address@hidden files.
address@hidden
address@hidden Without refilling, paragraphs containing long @@-constructs may
look
address@hidden bad after formatting because the formatter removes @@-commands
and
address@hidden shortens some lines more than others. In the past, neither the
address@hidden @code{texinfo-format-region} command nor the
address@hidden @code{texinfo-format-buffer} command refilled paragraphs
address@hidden automatically. The @code{@@refill} command had to be written at
the
address@hidden end of every paragraph to cause these formatters to fill them.
(Both
address@hidden @TeX{} and @code{makeinfo} have always refilled paragraphs
address@hidden automatically.) Now, all the Info formatters automatically fill
and
address@hidden indent those paragraphs that need to be filled and indented.
address@hidden
address@hidden The @code{@@refill} command causes @code{texinfo-format-region}
and
address@hidden @code{texinfo-format-buffer} to refill a paragraph in the Info
file
address@hidden @emph{after} all the other processing has been done. For this
reason,
address@hidden you can not use @code{@@refill} with a paragraph containing
either
address@hidden @code{@@*} or @code{@@address@hidden @dots{} @}} since the
refilling action will
address@hidden override those two commands.
address@hidden
address@hidden The @code{texinfo-format-region} and @code{texinfo-format-buffer}
address@hidden commands now automatically append @code{@@refill} to the end of
each
address@hidden paragraph that should be filled. They do not append
@code{@@refill} to
address@hidden the ends of paragraphs that contain @code{@@*} or
@address@hidden@@address@hidden @address@hidden
address@hidden and therefore do not refill or indent them.
+
+
address@hidden These are no longer ``new'', and the explanations
address@hidden are all given elsewhere anyway. So ignore the entire appendix.
address@hidden --karl, 25apr97.
address@hidden node New Features, Command and Variable Index, Obtaining TeX, Top
address@hidden appendix Second Edition Features
+
address@hidden @tex
address@hidden % Widen the space for the first column so three
control-character %
address@hidden strings fit in the first column. Switched back to default .8in %
address@hidden value at end of chapter. \global\tableindent=1.0in
address@hidden @end tex
address@hidden
address@hidden The second edition of the Texinfo manual describes more than 20
new
address@hidden Texinfo mode commands and more than 50 previously undocumented
Texinfo
address@hidden @@-commands. This edition is more than twice the length of the
first
address@hidden edition.
address@hidden
address@hidden Here is a brief description of the new commands.
address@hidden
address@hidden @c menu
address@hidden * New Texinfo Mode Commands:: The updating commands are
especially useful.
address@hidden * New Commands:: Many newly described @@-commands.
address@hidden @c end menu
address@hidden
address@hidden @c node New Texinfo Mode Commands, New Commands, Obtaining TeX,
Obtaining TeX
address@hidden @c appendixsec New Texinfo Mode Commands
address@hidden
address@hidden Texinfo mode provides commands and features especially designed
for
address@hidden working with Texinfo files. More than 20 new commands have been
address@hidden added, including commands for automatically creating and updating
address@hidden both nodes and menus. This is a tedious task when done by hand.
address@hidden
address@hidden The keybindings are intended to be somewhat mnemonic.
address@hidden
address@hidden @c subheading Update all nodes and menus
address@hidden
address@hidden The @code{texinfo-master-menu} command is the primary command:
address@hidden
address@hidden @table @kbd
address@hidden @item C-c C-u m
address@hidden @itemx M-x texinfo-master-menu
address@hidden Create or update a master menu.
address@hidden With @kbd{C-u} as a prefix argument,
address@hidden first create or update all nodes
address@hidden and regular menus.
address@hidden @end table
address@hidden
address@hidden @c subheading Update Pointers
address@hidden
address@hidden @noindent
address@hidden Create or update `Next', `Previous', and `Up' node pointers.
address@hidden
address@hidden @noindent
address@hidden @xref{Updating Nodes and Menus}.
address@hidden
address@hidden @table @kbd
address@hidden @item C-c C-u C-n
address@hidden @itemx M-x texinfo-update-node
address@hidden Update a node.
address@hidden
address@hidden @item C-c C-u C-e
address@hidden @itemx M-x texinfo-every-node-update
address@hidden Update every node in the buffer.
address@hidden @end table
address@hidden
address@hidden @c subheading Update Menus
address@hidden
address@hidden @noindent
address@hidden Create or update menus.
address@hidden
address@hidden @noindent
address@hidden @xref{Updating Nodes and Menus}.
address@hidden
address@hidden @table @kbd
address@hidden @item C-c C-u C-m
address@hidden @itemx M-x texinfo-make-menu
address@hidden Make or update a menu.
address@hidden
address@hidden @item C-c C-u C-a
address@hidden @itemx M-x texinfo-all-menus-update
address@hidden Make or update all the menus in a buffer.
address@hidden With @kbd{C-u} as a prefix argument,
address@hidden first update all the nodes.
address@hidden @end table
address@hidden
address@hidden @c subheading Insert Title as Description
address@hidden
address@hidden @noindent
address@hidden Insert a node's chapter or section title in the space for the
address@hidden description in a menu entry line; position point so you can edit
the
address@hidden insert. (This command works somewhat differently than the other
address@hidden insertion commands, which insert only a predefined string.)
address@hidden
address@hidden @noindent
address@hidden @xref{Inserting, Inserting Frequently Used Commands}.
address@hidden
address@hidden @table @kbd
address@hidden @item C-c C-c C-d
address@hidden Insert title.
address@hidden @end table
address@hidden
address@hidden @c subheading Format for Info
address@hidden
address@hidden @noindent
address@hidden Provide keybindings both for the Info formatting commands that
are
address@hidden written in Emacs Lisp and for @code{makeinfo} that is written in
address@hidden C.
address@hidden
address@hidden @noindent
address@hidden @xref{Info Formatting}.
address@hidden
address@hidden @noindent
address@hidden Use the Emacs lisp @address@hidden commands:
address@hidden
address@hidden @table @kbd
address@hidden @item C-c C-e C-r
address@hidden Format the region.
address@hidden
address@hidden @item C-c C-e C-b
address@hidden Format the buffer.
address@hidden @end table
address@hidden
address@hidden @noindent
address@hidden Use @code{makeinfo}:
address@hidden
address@hidden @table @kbd
address@hidden @item C-c C-m C-r
address@hidden Format the region.
address@hidden
address@hidden @item C-c C-m C-b
address@hidden Format the buffer.
address@hidden
address@hidden @item C-c C-m C-l
address@hidden Recenter the @code{makeinfo} output buffer.
address@hidden
address@hidden @item C-c C-m C-k
address@hidden Kill the @code{makeinfo} formatting job.
address@hidden @end table
address@hidden
address@hidden @c subheading Typeset and Print
address@hidden
address@hidden @noindent
address@hidden Typeset and print Texinfo documents from within Emacs.
address@hidden
address@hidden @noindent
address@hidden @xref{Printing}.
address@hidden
address@hidden @table @kbd
address@hidden @item C-c C-t C-b
address@hidden Run @code{texi2dvi} on the buffer.
address@hidden
address@hidden @item C-c C-t C-r
address@hidden Run @TeX{} on the region.
address@hidden
address@hidden @item C-c C-t C-i
address@hidden Run @code{texindex}.
address@hidden
address@hidden @item C-c C-t C-p
address@hidden Print the DVI file.
address@hidden
address@hidden @item C-c C-t C-q
address@hidden Show the print queue.
address@hidden
address@hidden @item C-c C-t C-d
address@hidden Delete a job from the print queue.
address@hidden
address@hidden @item C-c C-t C-k
address@hidden Kill the current @TeX{} formatting job.
address@hidden
address@hidden @item C-c C-t C-x
address@hidden Quit a currently stopped @TeX{} formatting job.
address@hidden
address@hidden @item C-c C-t C-l
address@hidden Recenter the output buffer.
address@hidden @end table
address@hidden
address@hidden @c subheading Other Updating Commands
address@hidden
address@hidden @noindent
address@hidden The ``other updating commands'' do not have standard keybindings
because
address@hidden they are used less frequently.
address@hidden
address@hidden @noindent
address@hidden @xref{Other Updating Commands}.
address@hidden
address@hidden @table @kbd
address@hidden @item M-x texinfo-insert-node-lines
address@hidden Insert missing @code{@@node} lines using
address@hidden section titles as node names.
address@hidden
address@hidden @item M-x texinfo-multiple-files-update
address@hidden Update a multi-file document.
address@hidden With a numeric prefix, such as @kbd{C-u 8},
address@hidden update @strong{every} pointer and
address@hidden menu in @strong{all} the files and
address@hidden then insert a master menu.
address@hidden
address@hidden @item M-x texinfo-indent-menu-description
address@hidden Indent descriptions in menus.
address@hidden
address@hidden @item M-x texinfo-sequential-node-update
address@hidden Insert node pointers in strict sequence.
address@hidden @end table
address@hidden
address@hidden @c no.de New Commands, , New Texinfo Mode Commands, Obtaining
TeX
address@hidden @c appendix.sec New Texinfo @@-Commands
address@hidden
address@hidden The second edition of the Texinfo manual describes more than 50
address@hidden commands that were not described in the first edition. A third
or so
address@hidden of these commands existed in Texinfo but were not documented in
the
address@hidden manual; the others are new. Here is a listing, with brief
address@hidden descriptions of them:
address@hidden
address@hidden @c subheading Indexing
address@hidden
address@hidden @noindent
address@hidden Create your own index, and merge indices.
address@hidden
address@hidden @noindent
address@hidden @xref{Indices}.
address@hidden
address@hidden @table @kbd
address@hidden @item @@defindex @var{index-name}
address@hidden Define a new index and its indexing command.
address@hidden See also the @code{@@defcodeindex} command.
address@hidden
address@hidden @c written verbosely to avoid overfull hbox
address@hidden @item @@synindex @var{from-index} @var{into-index}
address@hidden Merge the @var{from-index} index into the @var{into-index} index.
address@hidden See also the @code{@@syncodeindex} command.
address@hidden @end table
address@hidden
address@hidden @c subheading Definitions
address@hidden
address@hidden @noindent
address@hidden Describe functions, variables, macros,
address@hidden commands, user options, special forms, and other such artifacts
in a
address@hidden uniform format.
address@hidden
address@hidden @noindent
address@hidden @xref{Definition Commands}.
address@hidden
address@hidden @table @kbd
address@hidden @item @@deffn @var{category} @var{name} @address@hidden
address@hidden Format a description for functions, interactive
address@hidden commands, and similar entities.
address@hidden
address@hidden @item @@defvr, @@defop, @dots{}
address@hidden 15 other related commands.
address@hidden @end table
address@hidden
address@hidden @c subheading Glyphs
address@hidden
address@hidden @noindent
address@hidden Indicate the results of evaluation, expansion,
address@hidden printed output, an error message, equivalence of expressions,
and the
address@hidden location of point.
address@hidden
address@hidden @noindent
address@hidden @xref{Glyphs}.
address@hidden
address@hidden @table @kbd
address@hidden @item @@address@hidden@}
address@hidden @itemx @equiv{}
address@hidden Equivalence:
address@hidden
address@hidden @item @@address@hidden@}
address@hidden @itemx @error{}
address@hidden Error message
address@hidden
address@hidden @item @@address@hidden@}
address@hidden @itemx @expansion{}
address@hidden Macro expansion
address@hidden
address@hidden @item @@address@hidden@}
address@hidden @itemx @point{}
address@hidden Position of point
address@hidden
address@hidden @item @@address@hidden@}
address@hidden @itemx @print{}
address@hidden Printed output
address@hidden
address@hidden @item @@address@hidden@}
address@hidden @itemx @result{}
address@hidden Result of an expression
address@hidden @end table
address@hidden
address@hidden @c subheading Page Headings
address@hidden
address@hidden @noindent
address@hidden Customize page headings.
address@hidden
address@hidden @noindent
address@hidden @xref{Headings}.
address@hidden
address@hidden @table @kbd
address@hidden @item @@headings @var{on-off-single-double}
address@hidden Headings on or off, single, or double-sided.
address@hidden
address@hidden @item @@evenfooting address@hidden @@| address@hidden @@|
address@hidden
address@hidden Footings for even-numbered (left-hand) pages.
address@hidden
address@hidden @item @@evenheading, @@everyheading, @@oddheading, @dots{}
address@hidden Five other related commands.
address@hidden
address@hidden @item @@thischapter
address@hidden Insert name of chapter and chapter number.
address@hidden
address@hidden @item @@thischaptername, @@thisfile, @@thistitle, @@thispage
address@hidden Related commands.
address@hidden @end table
address@hidden
address@hidden @c subheading Formatting
address@hidden
address@hidden @noindent
address@hidden Format blocks of text.
address@hidden
address@hidden @noindent
address@hidden @xref{Quotations and Examples}, address@hidden
address@hidden @ref{Lists and Tables, , Making Lists and Tables}.
address@hidden
address@hidden @table @kbd
address@hidden @item @@cartouche
address@hidden Draw rounded box surrounding text (no effect in Info).
address@hidden
address@hidden @item @@enumerate @var{optional-arg}
address@hidden Enumerate a list with letters or numbers.
address@hidden
address@hidden @item @@exdent @var{line-of-text}
address@hidden Remove indentation.
address@hidden
address@hidden @item @@flushleft
address@hidden Left justify.
address@hidden
address@hidden @item @@flushright
address@hidden Right justify.
address@hidden
address@hidden @item @@format
address@hidden Do not narrow nor change font.
address@hidden
address@hidden @item @@ftable @var{formatting-command}
address@hidden @itemx @@vtable @var{formatting-command}
address@hidden Two-column table with indexing.
address@hidden
address@hidden @item @@lisp
address@hidden For an example of Lisp code.
address@hidden
address@hidden @item @@smallexample
address@hidden @itemx @@smalllisp
address@hidden Like @@table and @@lisp, but for (originally) @@smallbook.
address@hidden @end table
address@hidden
address@hidden @c subheading Conditionals
address@hidden
address@hidden @noindent
address@hidden Conditionally format text.
address@hidden
address@hidden @noindent
address@hidden @xref{set clear value, , @code{@@set} @code{@@clear}
@code{@@value}}.
address@hidden
address@hidden @table @kbd
address@hidden @item @@set @var{flag} address@hidden
address@hidden Set a flag. Optionally, set value
address@hidden of @var{flag} to @var{string}.
address@hidden
address@hidden @item @@clear @var{flag}
address@hidden Clear a flag.
address@hidden
address@hidden @item @@address@hidden@address@hidden
address@hidden Replace with value to which @var{flag} is set.
address@hidden
address@hidden @item @@ifset @var{flag}
address@hidden Format, if @var{flag} is set.
address@hidden
address@hidden @item @@ifclear @var{flag}
address@hidden Ignore, if @var{flag} is set.
address@hidden @end table
address@hidden
address@hidden @c subheading @@heading series for Titles
address@hidden
address@hidden @noindent
address@hidden Produce unnumbered headings that do not appear in a table of
contents.
address@hidden
address@hidden @noindent
address@hidden @xref{Structuring}.
address@hidden
address@hidden @table @kbd
address@hidden @item @@heading @var{title}
address@hidden Unnumbered section-like heading not listed
address@hidden in the table of contents of a printed manual.
address@hidden
address@hidden @item @@chapheading, @@majorheading, @@c subheading,
@@subsubheading
address@hidden Related commands.
address@hidden @end table
address@hidden
address@hidden @need 1000
address@hidden @c subheading Font commands
address@hidden
address@hidden @need 1000
address@hidden @noindent
address@hidden @xref{Smallcaps}, and @*
address@hidden @ref{Fonts}.
address@hidden
address@hidden @table @kbd
address@hidden @item @@address@hidden@address@hidden
address@hidden Print in roman font.
address@hidden
address@hidden @item @@address@hidden@address@hidden
address@hidden Print in @sc{small caps} font.
address@hidden @end table
address@hidden
address@hidden @c subheading Miscellaneous
address@hidden
address@hidden @noindent
address@hidden See @ref{title subtitle author, , @code{@@title}
@code{@@subtitle} and @code{@@author} Commands},@*
address@hidden see @ref{Customized Highlighting},@*
address@hidden see @ref{Overfull hboxes},@*
address@hidden see @ref{Footnotes},@*
address@hidden see @ref{dmn, , Format a Dimension},@*
address@hidden see @ref{Raise/lower sections, , @code{@@raisesections} and
@code{@@lowersections}},@*
address@hidden see @ref{math, , @code{@@math}: Inserting Mathematical
address@hidden
address@hidden see @ref{minus, , Inserting a Minus Sign},@*
address@hidden see @ref{paragraphindent, , Paragraph Indenting},@*
address@hidden see @ref{Cross Reference Commands},@*
address@hidden see @ref{title subtitle author, , @code{@@title}
@code{@@subtitle} and @code{@@author}}, address@hidden
address@hidden see @ref{Custom Headings, , How to Make Your Own Headings}.
address@hidden
address@hidden @table @kbd
address@hidden @item @@author @var{author}
address@hidden Typeset author's name.
address@hidden
address@hidden @c @item @@definfoenclose @var{new-command}, @var{before},
@var{after},
address@hidden @c Define a highlighting command for Info. (Info only.)
address@hidden
address@hidden @item @@finalout
address@hidden Produce cleaner printed output.
address@hidden
address@hidden @item @@footnotestyle @var{end-or-separate}
address@hidden Specify footnote style, either @samp{end} or @samp{separate}.
address@hidden @xref{Footnote Styles}.
address@hidden
address@hidden @item @@address@hidden@address@hidden
address@hidden Format a dimension.
address@hidden
address@hidden @item @@global@@address@hidden@var{existing-cmd}
address@hidden Define a highlighting command for @TeX{}. (@TeX{} only.)
address@hidden
address@hidden @item @@lowersections
address@hidden Reduce hierarchical level of sectioning commands.
address@hidden
address@hidden @item @@address@hidden@address@hidden
address@hidden Format a mathematical expression.
address@hidden
address@hidden @item @@address@hidden@}
address@hidden Generate a minus sign.
address@hidden
address@hidden @item @@paragraphindent @var{asis-or-number}
address@hidden Specify amount of paragraph indentation.
address@hidden
address@hidden @item @@raisesections
address@hidden Raise hierarchical level of sectioning commands.
address@hidden
address@hidden @item @@address@hidden@var{node-name}, @address@hidden@r{]},
@address@hidden@r{]}, @address@hidden@r{]}, @address@hidden@address@hidden
address@hidden Make a reference. In the printed manual, the
address@hidden reference does not start with the word `see'.
address@hidden
address@hidden @item @@title @var{title}
address@hidden Typeset @var{title} in the alternative
address@hidden title page format.
address@hidden
address@hidden @item @@subtitle @var{subtitle}
address@hidden Typeset @var{subtitle} in the alternative
address@hidden title page format.
address@hidden
address@hidden @item @@address@hidden@}
address@hidden Insert the current date.
address@hidden @end table
address@hidden @tex
address@hidden % Switch width of first column of tables back to default value
address@hidden \global\tableindent=.8in
address@hidden @end tex
+
+
address@hidden GNU Free Documentation License
address@hidden GNU Free Documentation License
+
address@hidden fdl.texi
+
+
address@hidden Command and Variable Index
address@hidden Command and Variable Index
+
+This is an alphabetical list of all the @@-commands, assorted Emacs Lisp
+functions, and several variables. To make the list easier to use, the
+commands are listed without their preceding @samp{@@}.
+
address@hidden fn
+
+
address@hidden General Index
address@hidden General Index
+
address@hidden cp
+
+
address@hidden
Deleted: trunk/doc/texinfo.txi
===================================================================
--- trunk/doc/texinfo.txi 2013-08-15 17:29:30 UTC (rev 5315)
+++ trunk/doc/texinfo.txi 2013-08-15 17:38:19 UTC (rev 5316)
@@ -1,24385 +0,0 @@
-\input texinfo.tex @c -*-texinfo-*-
address@hidden $Id$
address@hidden Ordinarily, Texinfo files have the extension .texi. But
texinfo.texi
address@hidden clashes with texinfo.tex on 8.3 filesystems, so we use
texinfo.txi.
-
address@hidden Everything between the start/end of header lines will be passed
by
address@hidden Emacs's {texinfo,makeinfo}-format region commands. See the
`start of
address@hidden header' node for more info.
address@hidden %**start of header
-
address@hidden makeinfo and texinfo.tex ignore all text before @setfilename.
address@hidden
address@hidden Ordinarily, the setfilename argument ends with .info. But
address@hidden texinfo.info-13 is too long for 14-character filesystems.
address@hidden texinfo
-
address@hidden Automake automatically updates version.texi to @set VERSION and
address@hidden @set UPDATED to appropriate values.
address@hidden version.texi
address@hidden GNU Texinfo @value{VERSION}
-
address@hidden Define a new index for command-line options.
address@hidden op
-
address@hidden Put everything except function (command, in this case) names in
one
address@hidden index (arbitrarily chosen to be the concept index).
address@hidden op cp
address@hidden vr cp
address@hidden pg cp
-
address@hidden 2
address@hidden finalout
-
address@hidden %**end of header
-
address@hidden
-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 Free Software Foundation, Inc.
-
address@hidden
-Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.3 or
-any later version published by the Free Software Foundation; with no
-Invariant Sections, with the Front-Cover Texts being ``A GNU Manual'',
-and with the Back-Cover Texts as in (a) below. A copy of the license
-is included in the section entitled ``GNU Free Documentation
-License''.
-
-(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
-modify this GNU manual. Buying copies from the FSF supports it in
-developing GNU and promoting software freedom.''
address@hidden quotation
address@hidden copying
-
address@hidden Texinfo documentation system
address@hidden
-* Texinfo: (texinfo). The GNU documentation format.
-* install-info: (texinfo)Invoking install-info. Update info/dir entries.
-* makeinfo: (texinfo)Invoking makeinfo. Translate Texinfo source.
-* pod2texi: (pod2texi)Invoking pod2texi. Translate Perl POD to Texinfo.
-* texi2dvi: (texinfo)Format with texi2dvi. Print Texinfo documents.
-* texi2pdf: (texinfo)PDF Output. PDF output for Texinfo.
-* pdftexi2dvi: (texinfo)PDF Output. PDF output for Texinfo.
-* texindex: (texinfo)Format with tex/texindex. Sort Texinfo index files.
address@hidden direntry
-
address@hidden Before release, run C-u C-c C-u C-a (texinfo-all-menus-update
with a
address@hidden prefix arg). This updates the node pointers, which texinfmt.el
needs.
-
address@hidden Set smallbook if printing in smallbook format so the example of
the
address@hidden smallbook font is actually written using smallbook; in bigbook,
a kludge
address@hidden is used for TeX output. Do this through the -t option to
texi2dvi,
address@hidden so this same source can be used for other paper sizes as well.
address@hidden smallbook
address@hidden set smallbook
address@hidden @@clear smallbook
-
address@hidden If you like blank pages, add through texi2dvi -t.
address@hidden setchapternewpage odd
-
-
address@hidden GNU Texinfo
-
address@hidden
address@hidden Texinfo
address@hidden The GNU Documentation Format
address@hidden for Texinfo version @value{VERSION}, @value{UPDATED}
-
address@hidden Robert J. Chassell
address@hidden Richard M. Stallman
-
address@hidden Include the Distribution inside the titlepage so
address@hidden that headings are turned off.
-
address@hidden
address@hidden 0pt plus 1filll
address@hidden
-
address@hidden 1
-Published by the Free Software Foundation @*
-51 Franklin St, Fifth Floor @*
-Boston, MA 02110-1301 @*
-USA @*
-ISBN 1-882114-67-1 @c for version 4.0, September 1999.
address@hidden ISBN 1-882114-65-5 is for version 3.12, March 1998.
address@hidden ISBN 1-882114-64-7 is for edition 2.24 of November 1996.
address@hidden ISBN 1-882114-63-9 is for edition 2.20 of 28 February 1995.
-
address@hidden 1
-Cover art by Etienne Suvasa.
address@hidden titlepage
-
-
address@hidden
address@hidden
-
-
address@hidden
address@hidden Top
address@hidden Texinfo
-
-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.
-
-The first part of this master menu lists the major nodes in this Info
-document, including the @@-command and concept indices. The rest of
-the menu lists all the lower level nodes in the document.
address@hidden ifnottex
-
address@hidden
-* Copying Conditions:: Your rights.
-* Overview:: Texinfo in brief.
-* Texinfo Mode:: Using the GNU Emacs Texinfo mode.
-* Beginning a File:: What is at the beginning of a Texinfo file?
-* Ending a File:: What is at the end of a Texinfo file?
-* Chapter Structuring:: Creating chapters, sections, appendices, etc.
-* Nodes:: Writing nodes, the basic unit of Texinfo.
-* Menus:: Writing menus.
-* Cross References:: Writing cross references.
-* Marking Text:: Marking words and phrases as code,
- keyboard input, meta-syntactic
- variables, and the like.
-* Quotations and Examples:: Block quotations, examples, etc.
-* Lists and Tables:: Itemized or numbered lists, and tables.
-* Special Displays:: Floating figures and footnotes.
-* Indices:: Creating indices.
-* Insertions:: Inserting @@-signs, braces, etc.
-* Breaks:: Forcing or preventing line and page breaks.
-* Definition Commands:: Describing functions and the like uniformly.
-* Internationalization:: Supporting languages other than English.
-* Conditionals:: Specifying text for only some output cases.
-* Defining New Texinfo Commands:: User-defined macros and aliases.
-* Include Files:: How to incorporate other Texinfo files.
-
-* Hardcopy:: Output for paper, with @TeX{}.
-* Generic Translator @t{texi2any}:: @command{texi2any}, an all-purpose
converter.
-* Creating and Installing Info Files:: Details on Info output.
-* Generating HTML:: Details on HTML output.
address@hidden * texi2any Output Customization:: Fine tuning with
initialization files.
-
-* Command List:: All the Texinfo @@-commands.
-* Tips:: Hints on how to write a Texinfo document.
-* Sample Texinfo Files:: Complete examples, including full texts.
-* Headings:: How to write page headings and footings.
-* Catching Mistakes:: How to find mistakes in formatting.
-* 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.
-* General Index:: A menu covering many topics.
-
address@hidden
- --- The Detailed Node Listing ---
-
-Overview of Texinfo
-
-* Reporting Bugs:: Submitting effective bug reports.
-* Using Texinfo:: Create printed or online output.
-* Output Formats:: Overview of the supported output formats.
-* Adding Output Formats:: Man pages and implementing new formats.
-* Texinfo Document Structure:: How Texinfo manuals are usually arranged.
-* Info Files:: What is an Info file?
-* Printed Books:: Characteristics of a printed book or manual.
-* Formatting Commands:: @@-commands are used for formatting.
-* Conventions:: General rules for writing a Texinfo file.
-* Comments:: Writing comments and ignored text in general.
-* Minimum:: What a Texinfo file must have.
-* Six Parts:: Usually, a Texinfo file has six parts.
-* Short Sample:: A short sample Texinfo file.
-* History:: Acknowledgements, contributors and genesis.
-
-Using Texinfo Mode
-
-* Texinfo Mode Overview:: How Texinfo mode can help you.
-* Emacs Editing:: Texinfo mode adds to GNU Emacs' general
- purpose editing features.
-* Inserting:: How to insert frequently used @@-commands.
-* Showing the Structure:: How to show the structure of a file.
-* Updating Nodes and Menus:: How to update or create new nodes and menus.
-* 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.
-
-Updating Nodes and Menus
-
-* Updating Commands:: Five major updating commands.
-* Updating Requirements:: How to structure a Texinfo file for
- using the updating command.
-* Other Updating Commands:: How to indent descriptions, insert
- missing nodes lines, and update
- nodes in sequence.
-
-Beginning a Texinfo File
-
-* 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.
-
-Texinfo File Header
-
-* First Line:: The first line of a Texinfo file.
-* Start of Header:: Formatting a region requires this.
-* @t{@@setfilename}:: Tell Info the name of the Info file.
-* @t{@@settitle}:: Create a title for the printed work.
-* End of Header:: Formatting a region requires this.
-
-Document Permissions
-
-* @t{@@copying}:: Declare the document's copying
permissions.
-* @t{@@insertcopying}:: Where to insert the permissions.
-
-Title and Copyright Pages
-
-* @t{@@titlepage}:: Create a title for the printed document.
-* @t{@@titlefont @@center @@sp}:: The @code{@@titlefont}, @code{@@center},
- and @code{@@sp} commands.
-* @t{@@title @@subtitle @@author}:: The @code{@@title}, @code{@@subtitle},
- and @code{@@author} commands.
-* Copyright:: How to write the copyright notice and
- include copying permissions.
-* Heading Generation:: Turn on page headings after the title and
- copyright pages.
-
-The `Top' Node and Master Menu
-
-* Top Node Example::
-* Master Menu Parts::
-
-Global Document Commands
-
-* @t{@@documentdescription}:: Document summary for the HTML output.
-* @t{@@setchapternewpage}:: Start chapters on right-hand pages.
-* @t{@@headings}:: An option for turning headings on and off
- and double or single sided printing.
-* @t{@@paragraphindent}:: Specify paragraph indentation.
-* @t{@@firstparagraphindent}:: Suppressing first paragraph indentation.
-* @t{@@exampleindent}:: Specify environment indentation.
-
-Ending a Texinfo File
-
-* Printing Indices & Menus:: How to print an index in hardcopy and
- generate index menus in Info.
-* File End:: How to mark the end of a file.
-
-Chapter Structuring
-
-* Tree Structuring:: A manual is like an upside down tree @dots{}
-* Structuring Command Types:: How to divide a manual into parts.
-* @t{@@chapter}:: Chapter structuring.
-* @t{@@unnumbered @@appendix}::
-* @t{@@majorheading @@chapheading}::
-* @t{@@section}::
-* @t{@@unnumberedsec @@appendixsec @@heading}::
-* @t{@@subsection}::
-* @t{@@unnumberedsubsec @@appendixsubsec @@subheading}::
-* @t{@@subsubsection}:: Commands for the lowest level sections.
-* @t{@@part}:: Collections of chapters.
-* Raise/lower sections:: How to change commands' hierarchical level.
-
-Nodes
-
-* @t{@@node}:: Creating nodes, in detail.
-* @t{makeinfo} Pointer Creation:: Letting makeinfo determine node pointers.
-* @t{@@anchor}:: Defining arbitrary cross reference
targets.
-* Node Menu Illustration:: A diagram, and sample nodes and menus.
-
-The @code{@@node} Command
-
-* Node Names:: How to choose node and pointer 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.
-* @t{@@top} Command:: How to use the @code{@@top} command.
-
-Menus
-
-* Menu Location:: Menus go at the ends of nodes.
-* Writing a Menu:: What is a menu?
-* Menu Parts:: A menu entry has three parts.
-* Less Cluttered Menu Entry:: Two part menu entry.
-* Menu Example:: Two and three part menu entries.
-* Other Info Files:: How to refer to a different Info file.
-
-Cross References
-
-* References:: What cross references are for.
-* Cross Reference Commands:: A summary of the different commands.
-* Cross Reference Parts:: A cross reference has several parts.
-* @t{@@xref}:: Begin a reference with `See' @dots{}
-* Top Node Naming:: How to refer to the beginning of another file.
-* @t{@@ref}:: A reference for the last part of a
sentence.
-* @t{@@pxref}:: How to write a parenthetical cross
reference.
-* @t{@@inforef}:: How to refer to an Info-only file.
-* @t{@@url}:: How to refer to a uniform resource
locator.
-* @t{@@cite}:: How to refer to books not in the Info
system.
-
address@hidden@@xref}
-
-* Reference Syntax:: What a reference looks like and requires.
-* One Argument:: @code{@@xref} with one argument.
-* Two Arguments:: @code{@@xref} with two arguments.
-* Three Arguments:: @code{@@xref} with three arguments.
-* Four and Five Arguments:: @code{@@xref} with four and five arguments.
-
-Marking Text, Words and Phrases
-
-* Indicating:: How to indicate definitions, files, etc.
-* Emphasis:: How to emphasize text.
-
-Indicating Definitions, Commands, etc.
-
-* Useful Highlighting:: Highlighting provides useful information.
-* @t{@@code}:: Indicating program code.
-* @t{@@kbd}:: Showing keyboard input.
-* @t{@@key}:: Specifying keys.
-* @t{@@samp}:: Indicating a literal sequence of
characters.
-* @t{@@verb}:: Indicating a verbatim sequence of
characters.
-* @t{@@var}:: Indicating metasyntactic variables.
-* @t{@@env}:: Indicating environment variables.
-* @t{@@file}:: Indicating file names.
-* @t{@@command}:: Indicating command names.
-* @t{@@option}:: Indicating option names.
-* @t{@@dfn}:: Specifying definitions.
-* @t{@@abbr}:: Indicating abbreviations.
-* @t{@@acronym}:: Indicating acronyms.
-* @t{@@indicateurl}:: Indicating an example url.
-* @t{@@email}:: Indicating an electronic mail address.
-
-Emphasizing Text
-
-* @t{@@emph @@strong}:: How to emphasize text in Texinfo.
-* Smallcaps:: How to use the small caps font.
-* Fonts:: Various font commands for printed output.
-
-Quotations and Examples
-
-* Block Enclosing Commands:: Different constructs for different purposes.
-* @t{@@quotation}:: Writing a quotation.
-* @t{@@indentedblock}:: Block of text indented on left.
-* @t{@@example}:: Writing an example in a fixed-width font.
-* @t{@@verbatim}:: Writing a verbatim example.
-* @t{@@verbatiminclude}:: Including a file verbatim.
-* @t{@@lisp}:: Illustrating Lisp code.
-* @t{@@address@hidden:: Examples in a smaller font.
-* @t{@@display}:: Writing an example in the current font.
-* @t{@@format}:: Writing an example without narrowed
margins.
-* @t{@@exdent}:: Undo indentation on a line.
-* @t{@@flushleft @@flushright}:: Pushing text flush left or flush right.
-* @t{@@raggedright}:: Avoiding justification on the right.
-* @t{@@noindent}:: Preventing paragraph indentation.
-* @t{@@indent}:: Forcing paragraph indentation.
-* @t{@@cartouche}:: Drawing rounded rectangles around text.
-
-Lists and Tables
-
-* Introducing Lists:: Texinfo formats lists for you.
-* @t{@@itemize}:: How to construct a simple list.
-* @t{@@enumerate}:: How to construct a numbered list.
-* Two-column Tables:: How to construct a two-column table.
-* Multi-column Tables:: How to construct generalized tables.
-
-Making a Two-column Table
-
-* @t{@@table}:: How to construct a two-column table.
-* @t{@@ftable @@vtable}:: Automatic indexing for two-column tables.
-* @t{@@itemx}:: How to put more entries in the first
column.
-
address@hidden@@multitable}: Multi-column Tables
-
-* Multitable Column Widths:: Defining multitable column widths.
-* Multitable Rows:: Defining multitable rows, with examples.
-
-Special Displays
-
-* Floats:: Figures, tables, and the like.
-* Images:: Including graphics and images.
-* Footnotes:: Writing footnotes.
-
-Floats
-
-* @t{@@float}:: Producing floating material.
-* @t{@@caption @@shortcaption}:: Specifying descriptions for floats.
-* @t{@@listoffloats}:: A table of contents for floats.
-
-Inserting Images
-
-* Image Syntax::
-* Image Scaling::
-
-Footnotes
-
-* Footnote Commands:: How to write a footnote in Texinfo.
-* Footnote Styles:: Controlling how footnotes appear in Info.
-
-Indices
-
-* Index Entries:: Choose different words for index entries.
-* Predefined Indices:: Use different indices for different kinds
- of entries.
-* Indexing Commands:: How to make an index entry.
-* Combining Indices:: How to combine indices.
-* New Indices:: How to define your own indices.
-
-Combining Indices
-
-* @t{@@syncodeindex}:: How to merge two indices, using
@code{@@code}
- font for the merged-from index.
-* @t{@@synindex}:: How to merge two indices, using the
- roman font for the merged-from index.
-
-Special Insertions
-
-* Special Characters:: Inserting @@ @address@hidden , \ #
-* Inserting Quote Characters:: Inserting left and right quotes, in code.
-* Inserting Space:: Inserting the right amount of whitespace.
-* Inserting Accents:: Inserting accents and special characters.
-* Inserting Quotation Marks:: Inserting quotation marks.
-* Inserting Math:: Formatting mathematical expressions.
-* Glyphs for Text:: Inserting Dots, bullets, currencies, etc.
-* Glyphs for Programming:: Indicating results of evaluation,
- expansion of macros, errors, etc.
-
-Special Characters: Inserting @@ @address@hidden , \ #
-
-* Inserting an Atsign:: @code{@@@@}, @code{@@address@hidden@}}.
-* Inserting Braces:: @code{@@@{ @@@}}, @code{@@l address@hidden@}}.
-* Inserting a Comma:: , and @code{@@address@hidden@}}.
-* Inserting a Backslash:: \ and @code{@@address@hidden@}}.
-* Inserting a Hashsign:: # and @code{@@address@hidden@}}.
-
-Inserting Space
-
-* Multiple Spaces:: Inserting multiple spaces.
-* Not Ending a Sentence:: Sometimes a . doesn't end a sentence.
-* Ending a Sentence:: Sometimes it does.
-* @t{@@frenchspacing}:: Specifying end-of-sentence spacing.
-* @t{@@dmn}:: Formatting a dimension.
-
-Glyphs for Text
-
-* @t{@@TeX @@LaTeX}:: The @TeX{} logos.
-* @t{@@copyright}:: The copyright symbol (c in a circle).
-* @t{@@registeredsymbol}:: The registered symbol (R in a circle).
-* @t{@@dots}:: How to insert ellipses: @dots{} and
@enddots{}
-* @t{@@bullet}:: How to insert a bullet: @bullet{}
-* @t{@@euro}:: How to insert the euro currency symbol.
-* @t{@@pounds}:: How to insert the pounds currency symbol.
-* @t{@@textdegree}:: How to insert the degrees symbol.
-* @t{@@minus}:: How to insert a minus sign.
-* @t{@@geq @@leq}:: How to insert greater/less-than-or-equal
signs.
-
-Glyphs for Programming
-
-* Glyphs Summary::
-* @t{@@result}:: How to show the result of expression.
-* @t{@@expansion}:: How to indicate an expansion.
-* @t{@@print}:: How to indicate generated output.
-* @t{@@error}:: How to indicate an error message.
-* @t{@@equiv}:: How to indicate equivalence.
-* @t{@@point}:: How to indicate the location of point.
-* Click Sequences:: Inserting GUI usage sequences.
-
-Forcing and Preventing Breaks
-
-* Break Commands:: Summary of break-related commands.
-* Line Breaks:: Forcing line breaks.
-* @t{@@- @@hyphenation}:: Helping @TeX{} with hyphenation points.
-* @t{@@allowcodebreaks}:: Controlling line breaks within @@code
text.
-* @t{@@w}:: Preventing unwanted line breaks in text.
-* @t{@@tie}:: Inserting an unbreakable but varying
space.
-* @t{@@sp}:: Inserting blank lines.
-* @t{@@page}:: Forcing the start of a new page.
-* @t{@@group}:: Preventing unwanted page breaks.
-* @t{@@need}:: Another way to prevent unwanted page
breaks.
-
-Definition Commands
-
-* Def Cmd Template:: Writing descriptions using definition commands.
-* Def Cmd Continuation Lines:: Continuing the heading over source lines.
-* Optional Arguments:: Handling optional and repeated arguments.
-* @t{@@deffnx}:: Group two or more `first' lines.
-* Def Cmds in Detail:: Reference for all the definition commands.
-* Def Cmd Conventions:: Conventions for writing definitions.
-* Sample Function Definition:: An example.
-
-The Definition Commands
-
-* Functions Commands:: Commands for functions and similar entities.
-* Variables Commands:: Commands for variables and similar entities.
-* Typed Functions:: Commands for functions in typed languages.
-* Typed Variables:: Commands for variables in typed languages.
-* Data Types:: The definition command for data types.
-* Abstract Objects:: Commands for object-oriented programming.
-
-Object-Oriented Programming
-
-* Variables: Object-Oriented Variables.
-* Methods: Object-Oriented Methods.
-
-Internationalization
-
-* @t{@@documentlanguage}:: Declaring the current language.
-* @t{@@documentencoding}:: Declaring the input encoding.
-
-Conditionally Visible Text
-
-* Conditional Commands:: Text for a given format.
-* Conditional Not Commands:: Text for any format other than a given one.
-* Raw Formatter Commands:: Using raw formatter commands.
-* Inline Conditionals:: Brace-delimited conditional text.
-* @t{@@set @@clear @@value}:: Variable tests and substitutions.
-* Testing for Texinfo Commands:: Testing if a Texinfo command is available.
-* Conditional Nesting:: Using conditionals inside conditionals.
-
address@hidden@@set}, @code{@@clear}, and @code{@@value}
-
-* @t{@@set @@value}:: Expand a flag variable to a string.
-* @t{@@ifset @@ifclear}:: Format a region if a flag is set.
-* @t{@@value} Example:: An easy way to update edition information.
-
-Defining New Texinfo Commands
-
-* Defining Macros:: Defining and undefining new commands.
-* Invoking Macros:: Using a macro, once you've defined it.
-* Macro Details:: Limitations of Texinfo macros.
-* @t{@@alias}:: Command aliases.
-* @t{@@definfoenclose}:: Customized highlighting.
-* External Macro Processors:: @code{#line} directives.
-
-External Macro Processors: Line Directives
-
-* @t{#line} Directive::
-* TeX: @t{#line} and @TeX{}.
-* Syntax: @t{#line} Syntax Details.
-
-Include Files
-
-* Using Include Files:: How to use the @code{@@include} command.
-* @t{texinfo-multiple-files-update}:: How to create and update nodes and
- menus when using included 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
-
-* Use @TeX{}:: Use @TeX{} to format for hardcopy.
-* Format with @t{tex}/@t{texindex}:: How to format with explicit shell
commands.
-* Format with @t{texi2dvi}:: A simpler way to format.
-* Print with @t{lpr}:: How to print.
-* Within Emacs:: How to format and print from an Emacs shell.
-* Texinfo Mode Printing:: How to format and print in Texinfo mode.
-* Compile-Command:: How to print using Emacs's compile command.
-* Requirements Summary:: @TeX{} formatting requirements summary.
-* Preparing for @TeX{}:: What to do before you use @TeX{}.
-* Overfull hboxes:: What are and what to do with overfull hboxes.
-* @t{@@smallbook}:: How to print small format books and
manuals.
-* A4 Paper:: How to print on A4 or A5 paper.
-* @t{@@pagesizes}:: How to print with customized page sizes.
-* Cropmarks and Magnification:: How to print marks to indicate the size
- of pages and how to print scaled up output.
-* PDF Output:: Portable Document Format output.
-* Obtaining @TeX{}:: How to obtain @TeX{}.
-
address@hidden: The Generic Translator for Texinfo
-
-* Reference Implementation:: @command{texi2any}: the reference
implementation.
-* Invoking @t{texi2any}:: Running the translator from a shell.
-* @t{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 @t{pod2texi}:: Translating Perl pod to Texinfo.
-* @t{texi2html}:: An ancestor of @command{texi2any}.
-
-Customization Variables
-
-* Commands: Customization Variables for @@-Commands.
-* Options: Customization Variables and Options.
-* Other: Other Customization Variables.
-
-Creating and Installing Info Files
-
-* Creating an Info File::
-* Installing an Info File::
-
-Creating an Info File
-
-* @t{makeinfo} Advantages:: @code{makeinfo} provides better error
checking.
-* @t{makeinfo} in Emacs:: How to run @code{makeinfo} from Emacs.
-* @t{texinfo-format} commands:: Two Info formatting commands written
- in Emacs Lisp are an alternative
- to @code{makeinfo}.
-* Batch Formatting:: How to format for Info in Emacs Batch mode.
-* Tag and Split Files:: How tagged and split files help Info
- to run better.
-
-Installing an Info File
-
-* 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.
-* Installing Dir Entries:: How to specify what menu entry to add
- to the Info directory.
-* Invoking @t{install-info}:: @code{install-info} options.
-
-Generating HTML
-
-* HTML Translation:: Details of the HTML output.
-* HTML Splitting:: How HTML output is split.
-* HTML CSS:: Influencing HTML output with Cascading Style
Sheets.
-* HTML Xref:: Cross references in HTML output.
-
-HTML Cross References
-
-* Link Basics: HTML Xref Link Basics.
-* Node Expansion: HTML Xref Node Name Expansion.
-* Command Expansion: HTML Xref Command Expansion.
-* 8-bit Expansion: HTML Xref 8-bit Character Expansion.
-* Mismatch: HTML Xref Mismatch.
-* Configuration: HTML Xref Configuration. htmlxref.cnf.
-* Preserving links: HTML Xref Link Preservation. MANUAL-noderename.cnf.
-
-@@-Command List
-
-* Command Syntax:: General syntax for varieties of @@-commands.
-* Command Contexts:: Guidelines for which commands can be used where.
-
-Sample Texinfo Files
-
-* Short Sample Texinfo File::
-* GNU Sample Texts::
-* Verbatim Copying License::
-* All-permissive Copying License::
-
-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
-
-* @t{makeinfo} Preferred:: @code{makeinfo} finds errors.
-* Debugging with Info:: How to catch errors with Info formatting.
-* Debugging with @TeX{}:: How to catch errors with @TeX{} formatting.
-* Using @t{texinfo-show-structure}:: How to use @code{texinfo-show-structure}.
-* Using @t{occur}:: How to list all lines containing a pattern.
-* Running @t{Info-validate}:: How to find badly referenced nodes.
-
-Finding Badly Referenced Nodes
-
-* Using @t{Info-validate}:: How to run @code{Info-validate}.
-* Unsplit:: How to create an unsplit file.
-* Tagifying:: How to tagify a file.
-* Splitting:: How to split a file manually.
-
-Info Format Specification
-
-* General: Info Format General Layout.
-* Text: 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 Tag Table.
-* Tag table: Info Format Tag Table.
-* Local variables: Info Format Local Variables.
-* Regular nodes: Info Format Regular Nodes.
-
-Info Format Text Constructs
-
-* Menu: Info Format Menu.
-* Image: Info Format Image.
-* Printindex: Info Format Printindex.
-* Xref: Info Format Cross Reference.
address@hidden detailmenu
address@hidden menu
-
address@hidden Reward readers for getting to the end of the menu :).
address@hidden Contributed by Arnold Robbins.
address@hidden
-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
address@hidden quotation
-
-
address@hidden Copying Conditions
address@hidden Texinfo Copying Conditions
address@hidden Copying conditions
address@hidden Conditions for copying Texinfo
address@hidden Free software
address@hidden Libre software
-
-GNU Texinfo is @dfn{free software}; this means that everyone is free
-to use it and free to redistribute it on certain conditions. Texinfo
-is not in the public domain; it is copyrighted and there are
-restrictions on its distribution, but these restrictions are designed
-to permit everything that a good cooperating citizen would want to do.
-What is not allowed is to try to prevent others from further sharing
-any version of Texinfo that they might get from you.
-
-Specifically, we want to make sure that you have the right to give away
-copies of the programs that relate to Texinfo, that you receive source
-code or else can get it if you want it, that you can change these
-programs or use pieces of them in new free programs, and that you know
-you can do these things.
-
-To make sure that everyone has such rights, we have to forbid you to
-deprive anyone else of these rights. For example, if you distribute
-copies of the Texinfo related programs, you must give the recipients all
-the rights that you have. You must make sure that they, too, receive or
-can get the source code. And you must tell them their rights.
-
-Also, for our own protection, we must make certain that everyone finds
-out that there is no warranty for the programs that relate to Texinfo.
-If these programs are modified by someone else and passed on, we want
-their recipients to know that what they have is not what we distributed,
-so that any problems introduced by others will not reflect on our
-reputation.
-
-The precise conditions of the licenses for the programs currently
-being distributed that relate to Texinfo are found in the General
-Public Licenses that accompany them. This manual is covered by the
-GNU Free Documentation License (@pxref{GNU Free Documentation
-License}).
-
-
address@hidden Overview
address@hidden Overview of Texinfo
address@hidden Overview of Texinfo
address@hidden Texinfo overview
-
address@hidden is a documentation system that uses a single source file
-to produce both online information and printed output. This means
-that instead of writing two different documents, one for the online
-information and the other for a printed work, you need write only one
-document. Therefore, when the work is revised, you need revise only
-that one document.
-
address@hidden Semantic markup
-Texinfo's markup commands are almost entirely @dfn{semantic}; that is,
-they specify the intended meaning of text in the document, rather than
-physical formatting instructions.
-
address@hidden Limited scope of Texinfo
-Texinfo was devised for the purpose of writing software documentation
-and manuals. It is not, and was never intended to be, a
-general-purpose formatting program. If you need to lay out a
-newspaper, devise a glossy magazine ad, or follow the exact formatting
-requirements of a publishing house, Texinfo is not the simplest tool.
-On the other hand, if you want to write a good manual for your
-program, Texinfo has many features that will make your job easier.
-Overall, it's intended to let you concentrate on the content, and thus
-provides almost no commands for controlling the final formatting.
-
address@hidden Pronounciation of Texinfo
address@hidden Spelling of Texinfo
-The first syllable of ``Texinfo'' is pronounced like ``speck'', not
-``hex''. This odd pronunciation is derived from, but is not the same
-as, the pronunciation of @TeX{}. In the word @TeX{}, the @samp{X} is
-actually the Greek letter ``chi'' rather than the English letter
-``ex''. Pronounce @TeX{} as if the @samp{X} were the last sound in
-the name `Bach'; but pronounce Texinfo as if the @samp{x} were a `k'.
-Spell ``Texinfo'' with a capital ``T'' and the other letters in
-lowercase.
-
-Manuals for most GNU packages are written in Texinfo, and available
-online at @url{http://www.gnu.org/doc}. The Texinfo
-
address@hidden
-* Reporting Bugs:: Submitting effective bug reports.
-* Using Texinfo:: Create printed or online output.
-* Output Formats:: Overview of the supported output formats.
-* Adding Output Formats:: Man pages and implementing new formats.
-* Texinfo Document Structure:: How Texinfo manuals are usually arranged.
-* Info Files:: What is an Info file?
-* Printed Books:: Characteristics of a printed book or manual.
-* Formatting Commands:: @@-commands are used for formatting.
-* Conventions:: General rules for writing a Texinfo file.
-* Comments:: Writing comments and ignored text in general.
-* Minimum:: What a Texinfo file must have.
-* Six Parts:: Usually, a Texinfo file has six parts.
-* Short Sample:: A short sample Texinfo file.
-* History:: Acknowledgements, contributors and genesis.
address@hidden menu
-
-
address@hidden Reporting Bugs
address@hidden Reporting Bugs
-
address@hidden Bugs, reporting
address@hidden Suggestions for Texinfo, making
address@hidden Reporting bugs
-We welcome bug reports and suggestions for any aspect of the Texinfo
-system: programs, documentation, installation, etc. Please email them
-to @email{bug-texinfo@@gnu.org}. You can get the latest version of
-Texinfo via its home page, @uref{http://www.gnu.org/software/texinfo}.
-
address@hidden Checklist for bug reports
-For bug reports, please include enough information for the maintainers
-to reproduce the problem. Generally speaking, that means:
-
address@hidden @bullet
address@hidden The version number of Texinfo and the program(s) or manual(s)
involved.
address@hidden The contents of any input files necessary to reproduce the bug.
address@hidden Precisely how you ran any program(s) involved.
address@hidden A description of the problem and samples of any erroneous output.
address@hidden Hardware and operating system names and versions.
address@hidden Anything else that you think would be helpful.
address@hidden itemize
-
-When in doubt whether something is needed or not, include it. It's
-better to include too much than to leave out something important.
-
-It is critical to send an actual input file that reproduces the
-problem. What's not critical is to ``narrow down'' the example to the
-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.)
-
address@hidden Patches, contributing
-Patches are most welcome; if possible, please make them with
address@hidden@w{diff -c}} (@pxref{Top,,, diff, Comparing and Merging Files})
-and include @file{ChangeLog} entries (@pxref{Change Log,,, emacs, The
-GNU Emacs Manual}), and follow the existing coding style.
-
-
address@hidden Using Texinfo
address@hidden Using Texinfo
-
address@hidden Using Texinfo in general
address@hidden Texinfo, introduction to
address@hidden Introduction to Texinfo
-
-Using Texinfo, you can create a printed document (via the @TeX{}
-typesetting system) with the normal features of a book, including
-chapters, sections, cross references, and indices. From the same
-Texinfo source file, you can create an Info file with special features
-to make documentation browsing easy. You can also create from that
-same source file an HTML output file suitable for use with a web
-browser, a Docbook file, or a transliteration in XML format. See the
-next section (@pxref{Output Formats}) for details and sample commands
-to generate output from the source.
-
address@hidden works with virtually all printers; Info works with virtually
-all computer terminals; the HTML output works with virtually all web
-browsers. Thus Texinfo and its output can be used by almost any
-computer user.
-
address@hidden Source file format
-A Texinfo source file is a plain ASCII file containing text
-interspersed with @dfn{@@-commands} (words preceded by an @samp{@@})
-that tell the Texinfo processors what to do. You can edit a Texinfo
-file with any text editor, but it is especially convenient to use GNU
-Emacs since that editor has a special mode, called Texinfo mode, that
-provides various Texinfo-related features. (@xref{Texinfo Mode}.)
-
-Texinfo is the official documentation format of the GNU project. More
-information is available at the @uref{http://www.gnu.org/doc/, GNU
-documentation web page}.
-
-
address@hidden Output Formats
address@hidden Output Formats
address@hidden Output formats
address@hidden Back-end output formats
-
-Here is a brief overview of the output formats currently supported by
-Texinfo.
-
address@hidden @asis
address@hidden Info
address@hidden Info output, overview
-(Generated via @command{makeinfo}.) Info format is mostly a plain
-text transliteration of the Texinfo source. It adds a few control
-characters to separate nodes and provide navigational information for
-menus, cross references, indices, and so on. The Emacs Info subsystem
-(@pxref{Top,,, info, Info}), and the standalone @command{info} program
-(@pxref{Top,,, info-stnd, GNU Info}), among others, can read these
-files. @xref{Info Files}, and @ref{Creating and Installing Info
-Files}.
-
address@hidden Plain text
address@hidden Plain text output, overview
-(Generated via @command{makeinfo --plaintext}.) This is almost the
-same as Info output with the navigational control characters are
-omitted.
-
address@hidden HTML
address@hidden HTML output, overview
address@hidden W3 consortium
address@hidden Mozilla
address@hidden Lynx
address@hidden Emacs-W3
-(Generated via @command{makeinfo --html}.) HTML, standing for Hyper
-Text Markup Language, has become the most commonly used language for
-writing documents on the World Wide Web. Web browsers, such as
-Mozilla, Lynx, and Emacs-W3, can render this language online. There
-are many versions of HTML; @command{makeinfo} tries to use a subset of
-the language that can be interpreted by any common browser. For
-details of the HTML language and much related information, see
address@hidden://www.w3.org/MarkUp/}. @xref{Generating HTML}.
-
address@hidden DVI
address@hidden DVI output, overview
address@hidden dvips
address@hidden xdvi
-(Generated via @command{texi2dvi}.) The DeVIce Independent binary
-format is output by the @TeX{} typesetting program
-(@uref{http://tug.org}). This is then read by a DVI `driver', which
-knows the actual device-specific commands that can be viewed or
-printed, notably Dvips for translation to PostScript (@pxref{Top,,,
-dvips, Dvips}) and Xdvi for viewing on an X display
-(@uref{http://sourceforge.net/projects/xdvi/}). @xref{Hardcopy}.
-(Be aware that the Texinfo language is very different from and much
-stricter than @TeX{}'s usual languages: plain @TeX{}, @LaTeX{},
address@hidden, etc.)
-
address@hidden PostScript
address@hidden PostScript output, overview
-(Generated via @command{texi2dvi --ps}.) PostScript is a page
-description language that became widely used around 1985 and is still
-used today. @uref{http://en.wikipedia.org/wiki/PostScript} gives a
-basic description and more preferences. By default, Texinfo uses the
address@hidden program to convert @TeX{}'s DVI output to PostScript.
address@hidden,,, dvips, Dvips}.
-
address@hidden PDF
address@hidden PDF output, overview
address@hidden Beebe, Nelson
-(Generated via @command{texi2dvi --pdf} or @command{texi2pdf}.) This
-format was developed by Adobe Systems for portable document
-interchange, based on their previous PostScript language. It can
-represent the exact appearance of a document, including fonts and
-graphics, and supporting arbitrary scaling. It is intended to be
-platform-independent and easily viewable, among other design goals;
address@hidden://en.wikipedia.org/wiki/Portable_Document_Format} and
address@hidden://tug.org/TUGboat/tb22-3/tb72beebe-pdf.pdf} have some
-background. By default, Texinfo uses the @command{pdftex} program, an
-extension of @TeX{}, to output PDF; see
address@hidden://tug.org/applications/pdftex}. @xref{PDF Output}.
-
address@hidden Docbook
address@hidden Docbook output, overview
address@hidden 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;
-see the Texinfo web pages.
-
address@hidden XML
address@hidden XML Texinfo output, overview
address@hidden Texinfo XML output, overview
address@hidden DTD, for Texinfo XML
address@hidden texinfo.dtd
address@hidden txixml2texi
-(Generated via @command{makeinfo --xml}.) XML is a generic syntax
-specification usable for any sort of content (a reference is at
address@hidden://www.w3.org/XML}). The @command{makeinfo} XML output,
-unlike all the other output formats, is a transliteration of the
-Texinfo source rather than processed output. That is, it translates
-the Texinfo markup commands into XML syntax, for further processing by
-XML tools. The details of the output are defined in an XML DTD as
-usual, which is contained in a file @file{texinfo.dtd} included in the
-Texinfo source distribution and available via the Texinfo web pages.
-The XML contains enough information to recreate the original content,
-except for syntactic constructs such as Texinfo macros and
-conditionals. The Texinfo source distribution includes a utility script
address@hidden to do that backward transformation.
address@hidden table
-
-
address@hidden Adding Output Formats
address@hidden Adding Output Formats
address@hidden Additional output formats
-
-The output formats in the previous section handle a wide variety of
-usage, but of course there is always room for more.
-
address@hidden Man page output, not supported
-From time to time, proposals are made to generate traditional Unix man
-pages from Texinfo source. However, because man pages have a strict
-conventional format, creating a good man page requires a completely
-different source than the typical Texinfo applications of writing a
-good user tutorial and/or a good reference manual. This makes
-generating man pages incompatible with the Texinfo design goal of not
-having to document the same information in different ways for
-different output formats. You might as well write the man page
-directly.
-
address@hidden help2man
address@hidden O'Dea, Brendan
-As an alternative way to support man pages, you may find the program
address@hidden to be useful. It generates a traditional man page
-from the @samp{--help} output of a program. In fact, the man pages
-for the programs in the Texinfo distribution are generated with this.
-It is GNU software written by Brendan O'Dea, available from
address@hidden://www.gnu.org/software/help2man}.
-
address@hidden Output formats, supporting more
address@hidden SGML-tools output format
-If you are a programmer and would like to contribute to the GNU
-project by implementing additional output formats for Texinfo, that
-would be excellent. The way to do this that would be most useful is
-to write a new back-end for @command{texi2any}, our reference
-implementation of a Texinfo parser; it creates a tree representation
-of the Texinfo input that you can use for the conversion. The
-documentation in the source file
address@hidden/Texinfo/Convert/Converter.pm} is a good place to start.
address@hidden Translator @t{texi2any}}.
-
-Another viable approach is use the Texinfo XML output from
address@hidden as your input. This XML is an essentially complete
-representation of the input, but without the Texinfo syntax and option
-peculiarities, as described above.
-
address@hidden Texinfo parsers, discouraging more
-If you still cannot resist the temptation of writing a new program
-that reads Texinfo source directly, let us give some more caveats:
-please do not underestimate the amount of work required. Texinfo is
-by no means a simple language to parse correctly, and remains under
-development, so you would be committing to an ongoing task. At a
-minimum, please check that the extensive tests of the language that
-come with @command{texi2any} give correct results with your new
-program.
-
-
address@hidden Texinfo Document Structure
address@hidden Texinfo Document Structure
address@hidden Texinfo document structure
address@hidden Document structure, of Texinfo
address@hidden Structure, of Texinfo documents
address@hidden Double structure, of Texinfo documents
-
address@hidden address@hidden node name
-Texinfo documents most usefully have a double structure, reflecting
-the double purposes of printed and online output. For printed output
-(DVI, PDF, @dots{}), with physical pages, there are chapters,
-sections, subsections, etc. For online output (Info, HTML, @dots{}),
-with interactive navigation and no physical pages, there are so-called
-``nodes''.
-
-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.
-
-Each @dfn{node} has a name, and contains the discussion of one topic.
-Along with the text for the user to read, each node also has pointers
-to other nodes, identified in turn by their own names. Info readers
-display one node at a time, and provide commands for the user to move
-to related nodes. The HTML output can be similarly navigated.
-
-The names of child nodes are listed in a @dfn{menu} 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.
-
-In addition, nodes at the same level are formed into a chain with
-`Next' and `Previous' pointers. As you might imagine, the `Next'
-pointer links to the next node (section), and the `Previous' pointer
-links to the previous node (section). 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 parent chapter. Each child node records the
-parent node name as its `Up' pointer. The last child has no `Next'
-pointer, and the first child has the parent both as its `Previous' and
-as its `Up' pointer.
-
-In addition to menus and `Next', `Previous', and `Up' pointers,
-Texinfo provides pointers of another kind for cross references, that
-can be sprinkled throughout the text. This is usually the best way to
-represent links that do not fit a hierarchical structure.
-
-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.
-
-
address@hidden Info Files
address@hidden Info Files
address@hidden Info files
-
-As mentioned above, Info format is mostly a plain text transliteration
-of the Texinfo source, with the addition of a few control characters
-to separate nodes and provide navigational information, so that
-Info-reading programs can operate on it.
-
-Info files are nearly always created by processing a Texinfo source
-document. @command{makeinfo}, also known as @command{texi2any}, is
-the principal command that converts a Texinfo file into an Info file;
address@hidden Translator @t{texi2any}}.
-
-Generally, you enter an Info file through a node that by convention is
-named `Top'. This node normally contains just a brief summary of the
-file's purpose, and a large menu through which the rest of the file is
-reached. From this node, you can either traverse the file
-systematically by going from node to node, or you can go to a specific
-node listed in the main menu, or you can search the index menus and then
-go directly to the node that has the information you want. Alternatively,
-with the standalone Info program, you can specify specific menu items on
-the command line (@pxref{Top,,, info, Info}).
-
-If you want to read through an Info file in sequence, as if it were a
-printed manual, you can hit @key{SPC} repeatedly, or you get the whole
-file with the advanced Info command @kbd{g *}. (@xref{Advanced,,
-Advanced Info commands, info, Info}.)
-
-The @file{dir} file in the @file{info} directory serves as the
-departure point for the whole Info system. From it, you can reach the
-`Top' nodes of each of the documents in a complete Info system.
-
address@hidden URI syntax for Info
-If you wish to refer to an Info file via a URI, you can use the
-(unofficial) syntax exemplified by the following. This works with
-Emacs/W3, for example:
address@hidden
-info:emacs#Dissociated%20Press
-info:///usr/info/emacs#Dissociated%20Press
-info://localhost/usr/info/emacs#Dissociated%20Press
address@hidden example
-
-The @command{info} program itself does not follow URIs of any kind.
-
-
address@hidden Printed Books
address@hidden Printed Books
address@hidden Printed book and manual characteristics
address@hidden Manual characteristics, printed
address@hidden Book characteristics, printed
address@hidden Texinfo printed book characteristics
address@hidden Characteristics, printed books or manuals
-
address@hidden 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.
-
-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.
-
address@hidden is a general purpose typesetting program. Texinfo provides a
-file @file{texinfo.tex} that contains information (definitions or
address@hidden) 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 (address@hidden by address@hidden); this is the default size.
-But you can also print for 7 inch by 9.25 inch pages (address@hidden by
address@hidden, the @code{@@smallbook} size; or on A4 or A5 size paper
-(@code{@@afourpaper}, @code{@@afivepaper}).
address@hidden@t{@@smallbook}}, and @ref{A4 Paper}.
-
address@hidden Literate programming
address@hidden 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.
-
address@hidden is very powerful and has a great many features. 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.
-
address@hidden @TeX{}}, for information on acquiring @TeX{}. It is
-not part of the Texinfo distribution.
-
-
address@hidden Formatting Commands
address@hidden @@-commands
address@hidden @@-commands
address@hidden 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
address@hidden@@-commands}. For example, @code{@@node} is the command to
-indicate a node and @code{@@chapter} is the command to indicate the
-start of a chapter. Almost all @@ command names are entirely
-lowercase.
-
-Texinfo's @@-commands are a strictly limited set of constructs. The
-strict limits are primarily intended to ``force'' you, the author, to
-concentrate on the writing and the content of your manual, rather than
-the details of the formatting.
-
-Depending on what they do or what address@hidden word
address@hidden comes from the way it is used in mathematics and does not
-refer to a dispute between two people; it refers to the information
-presented to the command. According to the @cite{Oxford English
-Dictionary}, the word derives from the Latin for @dfn{to make clear,
-prove}; thus it came to mean `the evidence offered as proof', which is
-to say, `the information offered', which led to its mathematical
-meaning. In its other thread of derivation, the word came to mean `to
-assert in a manner against which others may make counter assertions',
-which led to the meaning of `argument' as a dispute.} they take, you
-need to write @@-commands on lines of their own or as part of
-sentences:
-
address@hidden @bullet
address@hidden
-Some commands are written at the start of a line and the rest of the
-line comprises the argument text, such as @code{@@chapter} (which
-creates chapter titles).
-
address@hidden
-Some commands can appear anywhere, generally within a sentence, and
-are followed by empty braces, such as @code{@@address@hidden@}} (which creates
-an ellipsis @dots{}).
-
address@hidden
-Some commands can appear anywhere, generally within a sentence, and
-are followed by the argument text in braces, such as
address@hidden@@address@hidden@}} (which marks text as being code, @code{a+1}
being
-the argument in this case).
-
address@hidden
-Some commands are written at the start of a line, with general text on
-following lines, terminated by a matching @code{@@end} command on a
-line of its own. For example, @code{@@example}, then the lines of a
-coding example, then @code{@@end example}.
address@hidden itemize
-
address@hidden
address@hidden Braces, when to use
-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 own. The
-non-alphabetic commands, such as @code{@@:}, are exceptions to the
-rule; they do not need braces.
-
-As you gain experience with Texinfo, you will rapidly learn how to
-write the different commands: the different ways to write commands
-actually make it easier to write and read Texinfo files than if all
-commands followed exactly the same syntax. @xref{Command Syntax, ,
-@@-Command Syntax}, for all the details.
-
-
address@hidden Conventions
address@hidden General Syntactic Conventions
address@hidden General syntactic conventions
address@hidden Syntactic conventions
address@hidden Conventions, syntactic
address@hidden Characters, basic input
-
-This section describes the general conventions used in all Texinfo documents.
-
address@hidden @bullet
address@hidden
address@hidden Source files, characters used
-All printable ASCII characters except @samp{@@}, @address@hidden and
address@hidden@}} can appear in a Texinfo file and stand for themselves.
address@hidden@@} is the escape character which introduces commands, while
address@hidden@{} and @address@hidden are used to surround arguments to certain
-commands. To put one of these special characters into the document, put
-an @samp{@@} character in front of it, like this: @samp{@@@@},
address@hidden@@@{}, and @samp{@@@}}.
-
address@hidden
address@hidden Paragraph separator
address@hidden Blank lines, as paragraph separator
address@hidden Newlines, as blank lines
-Separate paragraphs with one or more blank lines. Currently Texinfo
-only recognizes newline characters as end of line, not the CRLF
-sequence used on some systems; so a @dfn{blank line} means exactly two
-consecutive newlines. Sometimes blank lines are useful or convenient
-in other cases as well; you can use the @code{@@noindent} to inhibit
-paragraph indentation if required (@address@hidden@@noindent}}).
-
address@hidden
-Texinfo supports the usual quotation marks used in English and in
-other languages; see @ref{Inserting Quotation Marks}.
-
address@hidden
address@hidden Multiple dashes in source
address@hidden Dashes in source
address@hidden Hyphens in source, two or three in a row
address@hidden Em dash, producing
address@hidden En dash, producing
-Use three hyphens in a row, @samp{---}, to produce a long dash---like
-this (called an @dfn{em dash}), used for punctuation in sentences.
-Use two hyphens, @samp{--}, to produce a medium dash (called an
address@hidden dash}), used primarily for numeric ranges, as in ``June
-25--26''. Use a single hyphen, @samp{-}, to produce a standard hyphen
-used in compound words. For display on the screen, Info reduces three
-hyphens to two and two hyphens to one (not transitively!). Of course,
-any number of hyphens in the source remain as they are in literal
-contexts, such as @code{@@code} and @code{@@example}.
-
address@hidden
address@hidden Form feed characters
address@hidden @kbd{CTRL-l}
-Form feed (@kbd{CTRL-l}) characters in the input are handled as
-follows:
-
address@hidden @asis
address@hidden PDF/DVI
-In normal text, treated as ending any open paragraph; essentially
-ignored between paragraphs.
-
address@hidden Info
-Output as-is between paragraphs (their most common use); in other
-contexts, they may be treated as regular spaces (and thus consolidated
-with surrounding whitespace).
-
address@hidden HTML
-Written as a numeric entity except contexts where spaces are ignored;
-for example, in @samp{@@address@hidden ^L address@hidden, the form feed is
-ignored.
-
address@hidden XML
-Keep them everywhere; in attributes, escaped as @samp{\f}; also,
address@hidden is escaped as @samp{\\} and newline as @samp{\n}.
-
address@hidden Docbook
-Completely removed, as they are not allowed.
address@hidden table
-
-As you can see, because of these differing requirements of the output
-formats, it's not possible to use form feeds completely portably.
-
address@hidden
address@hidden Tabs; don't use!
address@hidden:} 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.
-
address@hidden
-To avoid this problem, Texinfo mode in GNU Emacs inserts
-multiple spaces when you press the @key{TAB} key. Also, you can run
address@hidden in Emacs to convert tabs in a region to multiple
-spaces, or use the @code{unexpand} command from the shell.
address@hidden itemize
-
-
address@hidden Comments
address@hidden Comments
-
address@hidden Comments
address@hidden comment
address@hidden c @r{(comment)}
-
-You can write comments in a Texinfo file by using the @code{@@comment}
-command, which may be abbreviated to @code{@@c}. Such comments are
-for a person looking at the Texinfo source file. All the text on a
-line that follows either @code{@@comment} or @code{@@c} is a comment;
-the rest of the line does not appear in the visible output.
-
-Often, you can write the @code{@@comment} or @code{@@c} in the middle
-of a line, and only the text that follows after the @code{@@comment}
-or @code{@@c} command does not appear; but some commands, such as
address@hidden@@settitle} and @code{@@setfilename}, work on a whole line. You
-cannot use @code{@@comment} or @code{@@c} within a line beginning with
-such a command.
-
address@hidden DEL @r{(comment character)}
address@hidden Catcode for comments in @TeX{}
-In cases of nested command invocations, complicated macro definitions,
-etc., @code{@@c} and @code{@@comment} may provoke an error when
-processing with @TeX{}. Therefore, you can also use the @kbd{DEL}
-character (ASCII 127 decimal, 0x7f hex, 0177 octal) as a true @TeX{}
-comment character (catcode 14, in @TeX{} internals). Everything on
-the line after the @kbd{DEL} will be ignored.
-
address@hidden Ignored text
address@hidden Unprocessed text
address@hidden ignore
-You can also have long stretches of text to be ignored by the Texinfo
-processors with the @code{@@ignore} and @code{@@end ignore} commands.
-Write each of these commands on a line of its own, starting each
-command at the beginning of the line. Text between these two commands
-does not appear in the processed output. You can use @code{@@ignore}
-and @code{@@end ignore} for writing comments. (For some technical
-caveats regarding nesting of such commands, @pxref{Conditional
-Nesting}.)
-
-
address@hidden Minimum
address@hidden What a Texinfo File Must Have
address@hidden Minimal Texinfo file (requirements)
address@hidden Must have in Texinfo file
address@hidden Required in Texinfo file
address@hidden Texinfo file minimum
-
-By convention, the name of a Texinfo file ends with (in order of
-preference) one of the extensions @file{.texinfo}, @file{.texi},
address@hidden, or @file{.tex}. The longer extensions are preferred
-since they describe more clearly to a human reader the nature of the
-file. The shorter extensions are for operating systems that cannot
-handle long file names.
-
-In order to be made into a good printed manual and other output
-formats, a Texinfo file @emph{must} begin with lines like this:
-
address@hidden
address@hidden
-\input texinfo
-@@setfilename @var{info-file-name}
-@@settitle @var{name-of-manual}
address@hidden group
address@hidden example
-
address@hidden
-The contents of the file follow this beginning, and then you
address@hidden end the Texinfo source with a line like this:
-
address@hidden
-@@bye
address@hidden example
-
address@hidden \input @r{(raw @TeX{} startup)}
address@hidden
-Here's an explanation:
-
address@hidden @bullet
address@hidden
-The @samp{\input texinfo} line tells @TeX{} to use the
address@hidden 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{}.)
-
address@hidden
-The @code{@@setfilename} line provides a name for the Info file and
-tells @TeX{} to open auxiliary files. @strong{All text before
address@hidden@@setfilename} is ignored!}
-
address@hidden
-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 address@hidden Strictly speaking,
address@hidden@@settitle} is optional---if you don't mind your document being
-titled `Untitled'.
-
address@hidden
-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.
address@hidden itemize
-
-If you use Emacs, it is also useful to include mode setting and
-start-of-header and end-of-header lines at the beginning of a Texinfo
-file, like this:
-
address@hidden
address@hidden
-\input texinfo @@c -*-texinfo-*-
-@@c %**start of header
-@@setfilename @var{info-file-name}
-@@settitle @var{name-of-manual}
-@@c %**end of header
address@hidden group
address@hidden example
-
address@hidden
-In the first line, @samp{-*-texinfo-*-} causes Emacs to switch into
-Texinfo mode when you edit the file.
-
-The @code{@@c ...header} lines above which surround the
address@hidden@@setfilename} and @code{@@settitle} lines allow you to process,
-within Emacs, just part of the Texinfo source. (@xref{Start of
-Header}.)
-
-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
-the minimum, which can be useful for short documents, is just the three
-lines at the beginning and the one line at the end.
-
-
address@hidden Six Parts
address@hidden Six Parts of a Texinfo File
-
-Generally, a Texinfo file contains more than the minimal beginning and
-end described in the previous section---it usually contains the six
-parts listed below. These are described fully in the following sections.
-
address@hidden @r
address@hidden 1. Header
-The @dfn{Header} names the file, tells @TeX{} which definitions file to
-use, and other such housekeeping tasks.
-
address@hidden 2. Summary and Copyright
-The @dfn{Summary and Copyright} segment describes the document and
-contains the copyright notice and copying permissions. This is done
-with the @code{@@copying} command.
-
address@hidden 3. Title and Copyright
-The @dfn{Title and Copyright} segment contains the title and copyright
-pages for the printed manual. The segment must be enclosed between
address@hidden@@titlepage} and @code{@@end titlepage} commands. The title and
-copyright page appear only in the printed manual.
-
address@hidden 4. `Top' Node and Master Menu
-The `Top' node starts off the online output; it does not appear in the
-printed manual. We recommend including the copying permissions here as
-well as the segments above. And it contains at least a top-level menu
-listing the chapters, and possibly a @dfn{Master Menu} listing all the
-nodes in the entire document.
-
address@hidden 5. Body
-The @dfn{Body} of the document is typically structured like a
-traditional book or encyclopedia, but it may be free form.
-
address@hidden 6. End
-The @dfn{End} segment may contain commands for printing indices, and
-closes with the @code{@@bye} command on a line of its own.
address@hidden table
-
-
address@hidden Short Sample
address@hidden A Short Sample Texinfo File
address@hidden Sample Texinfo file, with comments
-
-Here is a very short but complete Texinfo file, in the six conventional
-parts enumerated in the previous section, so you can see how Texinfo
-source appears in practice. The first three parts of the file, from
address@hidden texinfo} through to @samp{@@end titlepage}, look more
-intimidating than they are: most of the material is standard
-boilerplate; when writing a manual, you simply change the names as
-appropriate.
-
address@hidden a File}, for full documentation on the commands listed
-here. @xref{GNU Sample Texts}, for the full texts to be used in GNU
-manuals.
-
-In the following, the sample text is @emph{indented}; comments on it are
-not. The complete file, without interspersed comments, is shown in
address@hidden Sample Texinfo File}.
-
address@hidden Part 1: Header
-
address@hidden
-The header does not appear in either the Info file or the
-printed output. It sets various parameters, including the
-name of the Info file and the title used in the header.
-
address@hidden
address@hidden
-\input texinfo @@c -*-texinfo-*-
-@@c %**start of header
-@@setfilename sample.info
-@@settitle Sample Manual 1.0
-@@c %**end of header
address@hidden group
address@hidden example
-
address@hidden Part 2: Summary Description and Copyright
-
address@hidden
-A real manual includes more text here, according to the license under
-which it is distributed. @xref{GNU Sample Texts}.
-
address@hidden
address@hidden
-@@copying
-This is a short example of a complete Texinfo file, version 1.0.
-
-Copyright @@address@hidden@} 2013 Free Software Foundation, Inc.
-@@end copying
address@hidden group
address@hidden example
-
address@hidden Part 3: Titlepage, Contents, Copyright
-
address@hidden
-The titlepage segment does not appear in the online output, only in the
-printed manual. 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
address@hidden@@contents} command generates a table of contents.
-
address@hidden
address@hidden
-@@titlepage
-@@title Sample Title
address@hidden group
-
address@hidden
-@@c The following two commands start the copyright page.
-@@page
-@@vskip 0pt plus 1filll
-@@insertcopying
-@@end titlepage
address@hidden group
-
-@@c Output the table of contents at the beginning.
-@@contents
address@hidden example
-
address@hidden Part 4: `Top' Node and Master Menu
-
address@hidden
-The `Top' node contains the master menu for the Info file. Since the
-printed manual uses a table of contents rather than a menu, it
-excludes the `Top' node. 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.
-
address@hidden
-@@ifnottex
-@@node Top
-@@top Short Sample
-
-This is a short sample Texinfo file.
-@@end ifnottex
-
address@hidden
-@@menu
-* First Chapter:: The first chapter is the
- only chapter in this sample.
-* Index:: Complete index.
-@@end menu
address@hidden group
address@hidden example
-
-
address@hidden Part 5: The Body of the Document
-
address@hidden
-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.
-
address@hidden
address@hidden
-@@node First Chapter
-@@chapter First Chapter
-
-@@cindex chapter, first
address@hidden group
-
address@hidden
-This is the first chapter.
-@@cindex index entry, another
address@hidden group
-
address@hidden
-Here is a numbered list.
-
-@@enumerate
-@@item
-This is the first item.
-
-@@item
-This is the second item.
-@@end enumerate
address@hidden group
address@hidden example
-
-
address@hidden Part 6: The End of the Document
-
address@hidden
-The end segment contains commands for generating an index in a node and
-unnumbered chapter of its own, and the @code{@@bye} command that marks
-the end of the document.
-
address@hidden
address@hidden
-@@node Index
-@@unnumbered Index
address@hidden group
-
address@hidden
-@@printindex cp
-
-@@bye
address@hidden group
address@hidden example
-
-
address@hidden Some Results
-
-Here is what the contents of the first chapter of the sample look like:
-
address@hidden 1
address@hidden 700
address@hidden
-This is the first chapter.
-
-Here is a numbered list.
-
address@hidden
address@hidden
-This is the first item.
-
address@hidden
-This is the second item.
address@hidden enumerate
address@hidden quotation
-
-
address@hidden History
address@hidden History
-
address@hidden Stallman, Richard M.
address@hidden Chassell, Robert J.
address@hidden Fox, Brian
address@hidden Berry, Karl
-Richard M. Stallman invented the Texinfo format, wrote the initial
-processors, and created Edition 1.0 of this manual. address@hidden
-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
address@hidden and @command{info} programs. Karl Berry has
-continued maintenance since Texinfo 3.8 (manual edition 2.22).
-
address@hidden Pinard, Fran@,{c}ois
address@hidden Schwab, Andreas
address@hidden Weinberg, Zack
address@hidden Weisshaus, Melissa
address@hidden Zaretskii, Eli
address@hidden Zuhn, David D.
-Our thanks go out to all who helped improve this work, particularly
-the indefatigable Eli Zaretskii and Andreas Schwab, who have provided
-patches beyond counting. Fran@,{c}ois Pinard and address@hidden Zuhn,
-tirelessly recorded and reported mistakes and obscurities. Zack
-Weinberg did the impossible by implementing the macro syntax in
address@hidden Thanks to Melissa Weisshaus for her frequent
-reviews of nearly similar editions. Dozens of others have contributed
-patches and suggestions, they are gratefully acknowledged in the
address@hidden file. Our mistakes are our own.
-
address@hidden History of Texinfo
address@hidden Texinfo history
address@hidden Beginnings
-
address@hidden Scribe
address@hidden Reid, Brian
-In the 1970's at CMU, Brian Reid developed a program and format named
-Scribe to mark up documents for printing. It used the @code{@@}
-character to introduce commands, as Texinfo does. Much more
-consequentially, it strove to describe document contents rather than
-formatting, an idea wholeheartedly adopted by Texinfo.
-
address@hidden Bolio
address@hidden address@hidden
-Meanwhile, people at MIT developed another, not too dissimilar format
-called Bolio. This then was converted to using @TeX{} as its typesetting
-language: address@hidden The earliest address@hidden version seems to have
been
-0.02 on October 31, 1984.
-
address@hidden could only be used as a markup language for documents to be
-printed, not for online documents. Richard Stallman (RMS) worked on
-both Bolio and address@hidden He also developed a nifty on-line help format
-called Info, and then combined address@hidden and Info to create Texinfo, a
-mark up language for text that is intended to be read both online and
-as printed hard copy.
-
-Moving forward, the original translator to create Info was written
-(primarily by RMS and Bob Chassell) in Emacs Lisp, namely the
address@hidden and other functions. In the early 1990s,
-Brian Fox reimplemented the conversion program in C, now called
address@hidden
-
address@hidden Reimplementing in Perl
-
address@hidden Cons, Lionel
address@hidden Dumas, Patrice
-In 2012, the C @command{makeinfo} was itself replaced by a Perl
-implementation generically called @command{texi2any}. This version
-supports the same level of output customization as
address@hidden, an independent program originally written by
-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
address@hidden 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
address@hidden
-
-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
-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
-styles, back-end output formats, and all other customizations.
-In more detail:
-
address@hidden @bullet
address@hidden HTML customization. Many GNU and other free software packages
-had been happily using the HTML customization features in
address@hidden for years. Thus, in effect two independent
-implementations of the Texinfo language had developed, and keeping
-them in sync was not simple. Adding the HTML customization possible
-in @command{texi2html} to a C program would have been an
-enormous effort.
-
address@hidden Unicode, and multilingual support generally, especially of east
-Asian languages. Although of course it's perfectly plausible to write
-such support in C, in the particular case of @command{makeinfo}, it
-would have been tantamount to rewriting the entire program. In Perl,
-much of that comes essentially for free.
-
address@hidden Additional back-ends. The @command{makeinfo} code had become
-convoluted to the point where adding a new back-end was quite complex,
-requiring complex interactions with existing back-ends. In contrast,
-our Perl implementation provides a clean tree-based representation for
-all back-ends to work from. People have requested numerous different
-back-ends (@LaTeX{}, the latest (X)HTML, @dots{}), and they will now
-be much more feasible to implement. Which leads to the last item:
-
address@hidden Making contributions easier. In general, due to the cleaner
-structure, the Perl program should be considerably easier than the C
-for anyone to read and contribute to, with the resulting obvious
-benefits.
address@hidden itemize
-
address@hidden Implementation}, for more on the rationale for and
-role of @command{texi2any}.
-
-
address@hidden Texinfo Mode
address@hidden Using Texinfo Mode
address@hidden Texinfo mode
address@hidden Mode, using Texinfo
address@hidden GNU Emacs
address@hidden Emacs
-
-You may edit a Texinfo file with any text editor you choose. A Texinfo
-file is no different from any other ASCII file. However, GNU Emacs
-comes with a special mode, called Texinfo mode, that provides Emacs
-commands and tools to help ease your work.
-
-This chapter describes features of GNU Emacs' Texinfo mode but not any
-features of the Texinfo formatting language. So if you are reading this
-manual straight through from the beginning, you may want to skim through
-this chapter briefly and come back to it after reading succeeding
-chapters which describe the Texinfo formatting language in detail.
-
address@hidden
-* Texinfo Mode Overview:: How Texinfo mode can help you.
-* Emacs Editing:: Texinfo mode adds to GNU Emacs' general
- purpose editing features.
-* Inserting:: How to insert frequently used @@-commands.
-* Showing the Structure:: How to show the structure of a file.
-* Updating Nodes and Menus:: How to update or create new nodes and menus.
-* 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.
address@hidden menu
-
address@hidden Texinfo Mode Overview
address@hidden Texinfo Mode Overview
-
-Texinfo mode provides special features for working with Texinfo files.
-You can:
-
address@hidden @bullet
address@hidden
-Insert frequently used @@-commands.
-
address@hidden
-Automatically create @code{@@node} lines.
-
address@hidden
-Show the structure of a Texinfo source file.
-
address@hidden
-Automatically create or update the `Next',
-`Previous', and `Up' pointers of a node.
-
address@hidden
-Automatically create or update menus.
-
address@hidden
-Automatically create a master menu.
-
address@hidden
-Format a part or all of a file for Info.
-
address@hidden
-Typeset and print part or all of a file.
address@hidden itemize
-
-Perhaps the two most helpful features are those for inserting frequently
-used @@-commands and for creating node pointers and menus.
-
address@hidden Emacs Editing
address@hidden The Usual GNU Emacs Editing Commands
-
-In most cases, the usual Text mode commands work the same in Texinfo
-mode as they do in Text mode. Texinfo mode adds new editing commands
-and tools to GNU Emacs' general purpose editing features. The major
-difference concerns filling. In Texinfo mode, the paragraph
-separation variable and syntax table are redefined so that Texinfo
-commands that should be on lines of their own are not inadvertently
-included in paragraphs. Thus, the @kbd{M-q} (@code{fill-paragraph})
-command will refill a paragraph but not mix an indexing command on a
-line adjacent to it into the paragraph.
-
-In addition, Texinfo mode sets the @code{page-delimiter} variable to
-the value of @code{texinfo-chapter-level-regexp}; by default, this is
-a regular expression matching the commands for chapters and their
-equivalents, such as appendices. With this value for the page
-delimiter, you can jump from chapter title to chapter title with the
address@hidden ]} (@code{forward-page}) and @kbd{C-x [}
-(@code{backward-page}) commands and narrow to a chapter with the
address@hidden n p} (@code{narrow-to-page}) command. (@xref{Pages, , ,emacs,
-The GNU Emacs Manual}, for details about the page commands.)
-
-You may name a Texinfo file however you wish, but the convention is to
-end a Texinfo file name with one of the extensions
address@hidden, @file{.texi}, @file{.txi}, or @file{.tex}. A longer
-extension is preferred, since it is explicit, but a shorter extension
-may be necessary for operating systems that limit the length of file
-names. GNU Emacs automatically enters Texinfo mode when you visit a
-file with a @file{.texinfo}, @file{.texi} or @file{.txi}
-extension. Also, Emacs switches to Texinfo mode
-when you visit a
-file that has @samp{-*-texinfo-*-} in its first line. If ever you are
-in another mode and wish to switch to Texinfo mode, type @code{M-x
-texinfo-mode}.
-
-Like all other Emacs features, you can customize or enhance Texinfo
-mode as you wish. In particular, the keybindings are very easy to
-change. The keybindings described here are the default or standard
-ones.
-
address@hidden Inserting
address@hidden Inserting Frequently Used Commands
address@hidden Inserting frequently used commands
address@hidden Frequently used commands, inserting
address@hidden Commands, inserting them
-
-Texinfo mode provides commands to insert various frequently used
-@@-commands into the buffer. You can use these commands to save
-keystrokes.
-
-The insert commands are invoked by typing @kbd{C-c} twice and then the
-first letter of the @@-command:
-
address@hidden @kbd
address@hidden C-c C-c c
address@hidden M-x texinfo-insert-@@code
address@hidden texinfo-insert-@@code
-Insert @code{@@address@hidden@}} and put the
-cursor between the braces.
-
address@hidden C-c C-c d
address@hidden M-x texinfo-insert-@@dfn
address@hidden texinfo-insert-@@dfn
-Insert @code{@@address@hidden@}} and put the
-cursor between the braces.
-
address@hidden C-c C-c e
address@hidden M-x texinfo-insert-@@end
address@hidden texinfo-insert-@@end
-Insert @code{@@end} and attempt to insert the correct following word,
-such as @samp{example} or @samp{table}. (This command does not handle
-nested lists correctly, but inserts the word appropriate to the
-immediately preceding list.)
-
address@hidden C-c C-c i
address@hidden M-x texinfo-insert-@@item
address@hidden texinfo-insert-@@item
-Insert @code{@@item} and put the
-cursor at the beginning of the next line.
-
address@hidden C-c C-c k
address@hidden M-x texinfo-insert-@@kbd
address@hidden texinfo-insert-@@kbd
-Insert @code{@@address@hidden@}} and put the
-cursor between the braces.
-
address@hidden C-c C-c n
address@hidden M-x texinfo-insert-@@node
address@hidden texinfo-insert-@@node
-Insert @code{@@node} and a comment line
-listing the sequence for the `Next',
-`Previous', and `Up' nodes.
-Leave point after the @code{@@node}.
-
address@hidden C-c C-c o
address@hidden M-x texinfo-insert-@@noindent
address@hidden texinfo-insert-@@noindent
-Insert @code{@@noindent} and put the
-cursor at the beginning of the next line.
-
address@hidden C-c C-c s
address@hidden M-x texinfo-insert-@@samp
address@hidden texinfo-insert-@@samp
-Insert @code{@@address@hidden@}} and put the
-cursor between the braces.
-
address@hidden C-c C-c t
address@hidden M-x texinfo-insert-@@table
address@hidden texinfo-insert-@@table
-Insert @code{@@table} followed by a @key{SPC}
-and leave the cursor after the @key{SPC}.
-
address@hidden C-c C-c v
address@hidden M-x texinfo-insert-@@var
address@hidden texinfo-insert-@@var
-Insert @code{@@address@hidden@}} and put the
-cursor between the braces.
-
address@hidden C-c C-c x
address@hidden M-x texinfo-insert-@@example
address@hidden texinfo-insert-@@example
-Insert @code{@@example} and put the
-cursor at the beginning of the next line.
-
address@hidden address@hidden was the binding for texinfo-insert-braces;
address@hidden in Emacs 19, backward-paragraph will take this binding.
address@hidden C-c C-c @{
address@hidden M-x texinfo-insert-braces
address@hidden texinfo-insert-braces
-Insert @address@hidden@}} and put the cursor between the braces.
-
address@hidden C-c @}
address@hidden C-c ]
address@hidden M-x up-list
address@hidden up-list
-Move from between a pair of braces forward past the closing brace.
-Typing @kbd{C-c ]} is easier than typing @kbd{C-c @}}, which
-is, however, more mnemonic; hence the two keybindings. (Also, you can
-move out from between braces by typing @kbd{C-f}.)
address@hidden table
-
-To put a command such as @address@hidden@@address@hidden@address@hidden around
an
address@hidden word, position the cursor in front of the word and type
address@hidden 1 C-c C-c c}. This makes it easy to edit existing plain text.
-The value of the prefix argument tells Emacs how many words following
-point to include between address@hidden for one word, @samp{2} for
-two words, and so on. Use a negative argument to enclose the previous
-word or words. If you do not specify a prefix argument, Emacs inserts
-the @@-command string and positions the cursor between the braces. This
-feature works only for those @@-commands that operate on a word or words
-within one line, such as @code{@@kbd} and @code{@@var}.
-
-This set of insert commands was created after analyzing the frequency
-with which different @@-commands are used in the @cite{GNU Emacs
-Manual} and the @cite{GDB Manual}. If you wish to add your own insert
-commands, you can bind a keyboard macro to a key, use abbreviations,
-or extend the code in @file{texinfo.el}.
-
address@hidden texinfo-start-menu-description
address@hidden Menu description, start
address@hidden Description for menu, start
address@hidden C-c C-d} (@code{texinfo-start-menu-description}) is an insert
-command that works differently from the other insert commands. It
-inserts a node's section or chapter title in the space for the
-description in a menu entry line. (A menu entry has three parts, the
-entry name, the node name, and the description. Only the node name is
-required, but a description helps explain what the node is about.
address@hidden Parts, , The Parts of a Menu}.)
-
-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
-can edit it. The function does not insert the title if the menu entry
-line already contains a description.
-
-This command is only an aid to writing descriptions; it does not do the
-whole job. You must edit the inserted text since a title tends to use
-the same words as a node name but a useful description uses different
-words.
-
address@hidden Showing the Structure
address@hidden Showing the Sectioning Structure of a File
address@hidden Showing the sectioning structure of a file
address@hidden Sectioning structure of a file, showing
address@hidden Structure of a file, showing
address@hidden Outline of file structure, showing
address@hidden Contents-like outline of file structure
address@hidden File sectioning structure, showing
address@hidden Texinfo file sectioning structure, showing
-
-You can show the sectioning structure of a Texinfo file by using the
address@hidden C-s} command (@code{texinfo-show-structure}). This command
-lists the lines that begin with the @@-commands for @code{@@chapter},
address@hidden@@section}, and the like. It constructs what amounts to a table
-of contents. These lines are displayed in another buffer called the
address@hidden buffer. In that buffer, you can position the cursor
-over one of the lines and use the @kbd{C-c C-c} command
-(@code{occur-mode-goto-occurrence}), to jump to the corresponding spot
-in the Texinfo file.
-
address@hidden @kbd
address@hidden C-c C-s
address@hidden M-x texinfo-show-structure
address@hidden texinfo-show-structure
-Show the @code{@@chapter}, @code{@@section}, and such lines of a
-Texinfo file.
-
address@hidden C-c C-c
address@hidden M-x occur-mode-goto-occurrence
address@hidden occur-mode-goto-occurrence
-Go to the line in the Texinfo file corresponding to the line under the
-cursor in the @file{*Occur*} buffer.
address@hidden table
-
-If you call @code{texinfo-show-structure} with a prefix argument by
-typing @address@hidden C-c C-s}}, it will list not only those lines with the
-@@-commands for @code{@@chapter}, @code{@@section}, and the like, but
-also the @code{@@node} lines. You can use @code{texinfo-show-structure}
-with a prefix argument to check whether the `Next', `Previous', and `Up'
-pointers of an @code{@@node} line are correct.
-
-Often, when you are working on a manual, you will be interested only
-in the structure of the current chapter. In this case, you can mark
-off the region of the buffer that you are interested in by using the
address@hidden n n} (@code{narrow-to-region}) command and
address@hidden will work on only that region. To see
-the whole buffer again, use @address@hidden n w}} (@code{widen}).
-(@xref{Narrowing, , , emacs, The GNU Emacs Manual}, for more
-information about the narrowing commands.)
-
address@hidden page-delimiter
address@hidden Page delimiter in Texinfo mode
-In addition to providing the @code{texinfo-show-structure} command,
-Texinfo mode sets the value of the page delimiter variable to match
-the chapter-level @@-commands. This enables you to use the @kbd{C-x
-]} (@code{forward-page}) and @kbd{C-x [} (@code{backward-page})
-commands to move forward and backward by chapter, and to use the
address@hidden n p} (@code{narrow-to-page}) command to narrow to a chapter.
address@hidden, , , emacs, The GNU Emacs Manual}, for more information
-about the page commands.
-
-
address@hidden Updating Nodes and Menus
address@hidden Updating Nodes and Menus
-
address@hidden Updating nodes and menus
address@hidden Create nodes, menus automatically
address@hidden Insert nodes, menus automatically
address@hidden Automatically insert nodes, menus
-
-Texinfo mode provides commands for automatically creating or updating
-menus and node pointers. The commands are called ``update'' commands
-because their most frequent use is for updating a Texinfo file after you
-have worked on it; but you can use them to insert the `Next',
-`Previous', and `Up' pointers into an @code{@@node} line that has none
-and to create menus in a file that has none.
-
-If you do not use any updating commands, you need to write menus and
-node pointers by hand, which is a tedious task.
-
address@hidden
-* Updating Commands:: Five major updating commands.
-* Updating Requirements:: How to structure a Texinfo file for
- using the updating command.
-* Other Updating Commands:: How to indent descriptions, insert
- missing nodes lines, and update
- nodes in sequence.
address@hidden menu
-
address@hidden Updating Commands
address@hidden The Updating Commands
-
-You can use the updating commands to:
-
address@hidden @bullet
address@hidden
-insert or update the `Next', `Previous', and `Up' pointers of a node,
-
address@hidden
-insert or update the menu for a section, and
-
address@hidden
-create a master menu for a Texinfo source file.
address@hidden itemize
-
-You can also use the commands to update all the nodes and menus in a
-region or in a whole Texinfo file.
-
-The updating commands work only with conventional Texinfo files, which
-are structured hierarchically like books. In such files, a structuring
-command line must follow closely after each @code{@@node} line, except
-for the `Top' @code{@@node} line. (A @dfn{structuring command line} is
-a line beginning with @code{@@chapter}, @code{@@section}, or other
-similar command.)
-
-You can write the structuring command line on the line that follows
-immediately after an @code{@@node} line or else on the line that
-follows after a single @code{@@comment} line or a single
address@hidden@@ifinfo} line. You cannot interpose more than one line between
-the @code{@@node} line and the structuring command line; and you may
-interpose only an @code{@@comment} line or an @code{@@ifinfo} line.
-
-Commands which work on a whole buffer require that the `Top' node be
-followed by a node with an @code{@@chapter} or equivalent-level command.
-The menu updating commands will not create a main or master menu for a
-Texinfo file that has only @code{@@chapter}-level nodes! The menu
-updating commands only create menus @emph{within} nodes for lower level
-nodes. To create a menu of chapters, you must provide a `Top'
-node.
-
-The menu updating commands remove menu entries that refer to other Info
-files since they do not refer to nodes within the current buffer. This
-is a deficiency. Rather than use menu entries, you can use cross
-references to refer to other Info files. None of the updating commands
-affect cross references.
-
-Texinfo mode has five updating commands that are used most often: two
-are for updating the node pointers or menu of a single node (or a
-region); two are for updating every node pointer and menu in a file;
-and one, the @code{texinfo-master-menu} command, is for creating a
-master menu for a complete file, and optionally, for updating every
-node and menu in the whole Texinfo file.
-
-The @code{texinfo-master-menu} command is the primary command:
-
address@hidden @kbd
address@hidden C-c C-u m
address@hidden M-x texinfo-master-menu
address@hidden texinfo-master-menu
-Create or update a master menu that includes all the other menus
-(incorporating the descriptions from pre-existing menus, if
-any).
-
-With an argument (prefix argument, @kbd{C-u,} if interactive), first create or
-update all the nodes and all the regular menus in the buffer before
-constructing the master menu. (@xref{The Top Node, , The Top Node and
-Master Menu}, for more about a master menu.)
-
-For @code{texinfo-master-menu} to work, the Texinfo file must have a
-`Top' node and at least one subsequent node.
-
-After extensively editing a Texinfo file, you can type the following:
-
address@hidden
-C-u M-x texinfo-master-menu
address@hidden or
-C-u C-c C-u m
address@hidden example
-
address@hidden
-This updates all the nodes and menus completely and all at once.
address@hidden table
-
-The other major updating commands do smaller jobs and are designed for
-the person who updates nodes and menus as he or she writes a Texinfo
-file.
-
address@hidden 1000
-The commands are:
-
address@hidden @kbd
address@hidden C-c C-u C-n
address@hidden M-x texinfo-update-node
address@hidden texinfo-update-node
-Insert the `Next', `Previous', and `Up' pointers for the node that point is
-within (i.e., for the @code{@@node} line preceding point). If the
address@hidden@@node} line has pre-existing `Next', `Previous', or `Up'
-pointers in it, the old pointers are removed and new ones inserted.
-With an argument (prefix argument, @kbd{C-u}, if interactive), this command
-updates all @code{@@node} lines in the region (which is the text
-between point and mark).
-
address@hidden C-c C-u C-m
address@hidden M-x texinfo-make-menu
address@hidden texinfo-make-menu
-Create or update the menu in the node that point is within.
-With an argument (@kbd{C-u} as prefix argument, if
-interactive), the command makes or updates menus for the
-nodes which are either within or a part of the
-region.
-
-Whenever @code{texinfo-make-menu} updates an existing menu, the
-descriptions from that menu are incorporated into the new menu. This
-is done by copying descriptions from the existing menu to the entries
-in the new menu that have the same node names. If the node names are
-different, the descriptions are not copied to the new menu.
-
address@hidden C-c C-u C-e
address@hidden M-x texinfo-every-node-update
address@hidden texinfo-every-node-update
-Insert or update the `Next', `Previous', and `Up' pointers for every
-node in the buffer.
-
address@hidden C-c C-u C-a
address@hidden M-x texinfo-all-menus-update
address@hidden texinfo-all-menus-update
-Create or update all the menus in the buffer. With an argument
-(@kbd{C-u} as prefix argument, if interactive), first insert
-or update all the node
-pointers before working on the menus.
-
-If a master menu exists, the @code{texinfo-all-menus-update} command
-updates it; but the command does not create a new master menu if none
-already exists. (Use the @code{texinfo-master-menu} command for
-that.)
-
-When working on a document that does not merit a master menu, you can
-type the following:
-
address@hidden
-C-u C-c C-u C-a
address@hidden or
-C-u M-x texinfo-all-menus-update
address@hidden example
-
address@hidden
-This updates all the nodes and menus.
address@hidden table
-
-The @code{texinfo-column-for-description} variable specifies the
-column to which menu descriptions are indented. By default, the value
-is 32 although it can be useful to reduce it to as low as 24. You
-can set the variable via customization (@pxref{Changing an Option,,,
-emacs, The GNU Emacs Manual}) or with the @kbd{M-x set-variable}
-command (@pxref{Examining, , Examining and Setting Variables, emacs,
-The GNU Emacs Manual}).
-
-Also, the @code{texinfo-indent-menu-description} command may be used to
-indent existing menu descriptions to a specified column. Finally, if
-you wish, you can use the @code{texinfo-insert-node-lines} command to
-insert missing @code{@@node} lines into a file. (@xref{Other Updating
-Commands}, for more information.)
-
address@hidden Updating Requirements
address@hidden Updating Requirements
address@hidden Updating requirements
address@hidden Requirements for updating commands
-
-To use the updating commands, you must organize the Texinfo file
-hierarchically with chapters, sections, subsections, and the like.
-When you construct the hierarchy of the manual, do not `jump down'
-more than one level at a time: you can follow the `Top' node with a
-chapter, but not with a section; you can follow a chapter with a
-section, but not with a subsection. However, you may `jump up' any
-number of levels at one time---for example, from a subsection to a
-chapter.
-
-Each @code{@@node} line, with the exception of the line for the `Top'
-node, must be followed by a line with a structuring command such as
address@hidden@@chapter}, @code{@@section}, or
address@hidden@@unnumberedsubsec}.
-
-Each @code{@@node} line/structuring-command line combination
-must look either like this:
-
address@hidden
address@hidden
-@@node Comments, Minimum, Conventions, Overview
-@@comment node-name, next, previous, up
-@@section Comments
address@hidden group
address@hidden example
-
-or like this (without the @code{@@comment} line):
-
address@hidden
address@hidden
-@@node Comments, Minimum, Conventions, Overview
-@@section Comments
address@hidden group
address@hidden example
-
-or like this (without the explicit node pointers):
-
address@hidden
address@hidden
-@@node Comments
-@@section Comments
address@hidden group
address@hidden example
-
address@hidden
-In this example, `Comments' is the name of both the node and the
-section. The next node is called `Minimum' and the previous node is
-called `Conventions'. The `Comments' section is within the `Overview'
-node, which is specified by the `Up' pointer. (Instead of an
address@hidden@@comment} line, you may also write an @code{@@ifinfo} line.)
-
-If a file has a `Top' node, it must be called @samp{top} or @samp{Top}
-and be the first node in the file.
-
-The menu updating commands create a menu of sections within a chapter,
-a menu of subsections within a section, and so on. This means that
-you must have a `Top' node if you want a menu of chapters.
-
-Incidentally, the @code{makeinfo} command will create an Info file for a
-hierarchically organized Texinfo file that lacks `Next', `Previous' and
-`Up' pointers. Thus, if you can be sure that your Texinfo file will be
-formatted with @code{makeinfo}, you have no need for the update node
-commands. (@xref{Creating an Info File}, for more information about
address@hidden) However, both @code{makeinfo} and the
address@hidden@dots{}} commands require that you insert menus in
-the file.
-
-
address@hidden Other Updating Commands
address@hidden Other Updating Commands
-
-In addition to the five major updating commands, Texinfo mode
-possesses several less frequently used updating commands:
-
address@hidden @kbd
address@hidden M-x texinfo-insert-node-lines
address@hidden texinfo-insert-node-lines
-Insert @code{@@node} lines before the @code{@@chapter},
address@hidden@@section}, and other sectioning commands wherever they are
-missing throughout a region in a Texinfo file.
-
-With an argument (@kbd{C-u} as prefix argument, if interactive), the
address@hidden command not only inserts
address@hidden@@node} lines but also inserts the chapter or section titles as
-the names of the corresponding nodes. In addition, it inserts the
-titles as node names in pre-existing @code{@@node} lines that lack
-names. Since node names should be more concise than section or
-chapter titles, you must manually edit node names so inserted.
-
-For example, the following marks a whole buffer as a region and inserts
address@hidden@@node} lines and titles throughout:
-
address@hidden
-C-x h C-u M-x texinfo-insert-node-lines
address@hidden example
-
-This command inserts titles as node names in @code{@@node} lines; the
address@hidden command (@pxref{Inserting,
-Inserting Frequently Used Commands}) inserts titles as descriptions in
-menu entries, a different action. However, in both cases, you need to
-edit the inserted text.
-
address@hidden M-x texinfo-multiple-files-update
address@hidden texinfo-multiple-files-update @r{(in brief)}
-Update nodes and menus in a document built from several separate files.
-With @kbd{C-u} as a prefix argument, create and insert a master menu in
-the outer file. With a numeric prefix argument, such as @kbd{C-u 2}, first
-update all the menus and all the `Next', `Previous', and `Up' pointers
-of all the included files before creating and inserting a master menu in
-the outer file. The @code{texinfo-multiple-files-update} command is
-described in the appendix on @code{@@include} files.
address@hidden@t{texinfo-multiple-files-update}}.
-
address@hidden M-x texinfo-indent-menu-description
address@hidden texinfo-indent-menu-description
-Indent every description in the menu following point to the specified
-column. You can use this command to give yourself more space for
-descriptions. With an argument (@kbd{C-u} as prefix argument, if
-interactive), the @code{texinfo-indent-menu-description} command indents
-every description in every menu in the region. However, this command
-does not indent the second and subsequent lines of a multi-line
-description.
-
address@hidden M-x texinfo-sequential-node-update
address@hidden texinfo-sequential-node-update
-Insert the names of the nodes immediately following and preceding the
-current node as the `Next' or `Previous' pointers regardless of those
-nodes' hierarchical level. This means that the `Next' node of a
-subsection may well be the next chapter. Sequentially ordered nodes are
-useful for novels and other documents that you read through
-sequentially. (However, in Info, the @kbd{g *} command lets
-you look through the file sequentially, so sequentially ordered nodes
-are not strictly necessary.) With an argument (prefix argument, if
-interactive), the @code{texinfo-sequential-node-update} command
-sequentially updates all the nodes in the region.
address@hidden table
-
address@hidden Info Formatting
address@hidden Formatting for Info
address@hidden Formatting for Info
address@hidden Running an Info formatter
address@hidden Info formatting
-
-Texinfo mode provides several commands for formatting part or all of a
-Texinfo file for Info. Often, when you are writing a document, you
-want to format only part of a file---that is, a region.
-
-You can use either the @code{texinfo-format-region} or the
address@hidden command to format a region:
-
address@hidden @kbd
address@hidden texinfo-format-region
address@hidden C-c C-e C-r
address@hidden M-x texinfo-format-region
address@hidden C-c C-m C-r
address@hidden M-x makeinfo-region
-Format the current region for Info.
address@hidden table
-
-You can use either the @code{texinfo-format-buffer} or the
address@hidden command to format a whole buffer:
-
address@hidden @kbd
address@hidden texinfo-format-buffer
address@hidden C-c C-e C-b
address@hidden M-x texinfo-format-buffer
address@hidden C-c C-m C-b
address@hidden M-x makeinfo-buffer
-Format the current buffer for Info.
address@hidden table
-
address@hidden 1000
-For example, after writing a Texinfo file, you can type the following:
-
address@hidden
-C-u C-c C-u m
address@hidden or
-C-u M-x texinfo-master-menu
address@hidden example
-
address@hidden
-This updates all the nodes and menus. Then type the following to create
-an Info file:
-
address@hidden
-C-c C-m C-b
address@hidden or
-M-x makeinfo-buffer
address@hidden example
-
-For @TeX{} or the Info formatting commands to work, the file @emph{must}
-include a line that has @code{@@setfilename} in its header.
-
address@hidden an Info File}, for details about Info formatting.
-
address@hidden Printing
address@hidden node-name, next, previous, up
address@hidden Printing
address@hidden Formatting for printing
address@hidden Printing a region or buffer
address@hidden Region formatting and printing
address@hidden Buffer formatting and printing
address@hidden Part of file formatting and printing
-
-Typesetting and printing a Texinfo file is a multi-step process in
-which you first create a file for printing (called a DVI file), and
-then print the file. Optionally, you may also create indices. To do
-this, you must run the @code{texindex} command after first running the
address@hidden typesetting command; and then you must run the @code{tex}
-command again. Or else run the @code{texi2dvi} command which
-automatically creates indices as needed (@pxref{Format with
address@hidden).
-
-Often, when you are writing a document, you want to typeset and print
-only part of a file to see what it will look like. You can use the
address@hidden and related commands for this purpose. Use
-the @code{texinfo-tex-buffer} command to format all of a
-buffer.
-
address@hidden @kbd
address@hidden C-c C-t C-b
address@hidden M-x texinfo-tex-buffer
address@hidden texinfo-tex-buffer
-Run @code{texi2dvi} on the buffer. In addition to running @TeX{} on the
-buffer, this command automatically creates or updates indices as
-needed.
-
address@hidden C-c C-t C-r
address@hidden M-x texinfo-tex-region
address@hidden texinfo-tex-region
-Run @TeX{} on the region.
-
address@hidden C-c C-t C-i
address@hidden M-x texinfo-texindex
-Run @code{texindex} to sort the indices of a Texinfo file formatted with
address@hidden The @code{texinfo-tex-region} command does
-not run @code{texindex} automatically; it only runs the @code{tex}
-typesetting command. You must run the @code{texinfo-tex-region} command
-a second time after sorting the raw index files with the @code{texindex}
-command. (Usually, you do not format an index when you format a region,
-only when you format a buffer. Now that the @code{texi2dvi} command
-exists, there is little or no need for this command.)
-
address@hidden C-c C-t C-p
address@hidden M-x texinfo-tex-print
address@hidden texinfo-tex-print
-Print the file (or the part of the file) previously formatted with
address@hidden or @code{texinfo-tex-region}.
address@hidden table
-
-For @code{texinfo-tex-region} or @code{texinfo-tex-buffer} to work, the
-file @emph{must} start with a @samp{\input texinfo} line and must
-include an @code{@@settitle} line. The file must end with @code{@@bye}
-on a line by itself. (When you use @code{texinfo-tex-region}, you must
-surround the @code{@@settitle} line with start-of-header and
-end-of-header lines.)
-
address@hidden, for a description of the other @TeX{} related
-commands, such as @code{tex-show-print-queue}.
-
address@hidden Texinfo Mode Summary
address@hidden Texinfo Mode Summary
-
-In Texinfo mode, each set of commands has default keybindings that
-begin with the same keys. All the commands that are custom-created
-for Texinfo mode begin with @kbd{C-c}. The keys are somewhat
-mnemonic.
-
address@hidden Insert Commands
-
-The insert commands are invoked by typing @kbd{C-c} twice and then the
-first letter of the @@-command to be inserted. (It might make more
-sense mnemonically to use @kbd{C-c C-i}, for `custom insert', but
address@hidden C-c} is quick to type.)
-
address@hidden
-C-c C-c c @r{Insert} @samp{@@code}.
-C-c C-c d @r{Insert} @samp{@@dfn}.
-C-c C-c e @r{Insert} @samp{@@end}.
-C-c C-c i @r{Insert} @samp{@@item}.
-C-c C-c n @r{Insert} @samp{@@node}.
-C-c C-c s @r{Insert} @samp{@@samp}.
-C-c C-c v @r{Insert} @samp{@@var}.
-C-c @{ @r{Insert braces.}
-C-c ]
-C-c @} @r{Move out of enclosing braces.}
-
address@hidden
-C-c C-c C-d @r{Insert a node's section title}
- @r{in the space for the description}
- @r{in a menu entry line.}
address@hidden group
address@hidden example
-
address@hidden Show Structure
-
-The @code{texinfo-show-structure} command is often used within a
-narrowed region.
-
address@hidden
-C-c C-s @r{List all the headings.}
address@hidden example
-
address@hidden The Master Update Command
-
-The @code{texinfo-master-menu} command creates a master menu; and can
-be used to update every node and menu in a file as well.
-
address@hidden Probably should use @tables in this section.
address@hidden
address@hidden
-C-c C-u m
-M-x texinfo-master-menu
- @r{Create or update a master menu.}
address@hidden group
-
address@hidden
-C-u C-c C-u m @r{With @kbd{C-u} as a prefix argument, first}
- @r{create or update all nodes and regular}
- @r{menus, and then create a master menu.}
address@hidden group
address@hidden example
-
address@hidden Update Pointers
-
-The update pointer commands are invoked by typing @kbd{C-c C-u} and
-then either @kbd{C-n} for @code{texinfo-update-node} or @kbd{C-e} for
address@hidden
-
address@hidden
-C-c C-u C-n @r{Update a node.}
-C-c C-u C-e @r{Update every node in the buffer.}
address@hidden example
-
address@hidden Update Menus
-
-Invoke the update menu commands by typing @kbd{C-c C-u}
-and then either @kbd{C-m} for @code{texinfo-make-menu} or
address@hidden for @code{texinfo-all-menus-update}. To update
-both nodes and menus at the same time, precede @kbd{C-c C-u
-C-a} with @kbd{C-u}.
-
address@hidden
-C-c C-u C-m @r{Make or update a menu.}
-
address@hidden
-C-c C-u C-a @r{Make or update all}
- @r{menus in a buffer.}
address@hidden group
-
address@hidden
-C-u C-c C-u C-a @r{With @kbd{C-u} as a prefix argument,}
- @r{first create or update all nodes and}
- @r{then create or update all menus.}
address@hidden group
address@hidden example
-
address@hidden Format for Info
-
-The Info formatting commands that are written in Emacs Lisp are
-invoked by typing @kbd{C-c C-e} and then either @kbd{C-r} for a region
-or @kbd{C-b} for the whole buffer.
-
-The Info formatting commands that are written in C and based on the
address@hidden program are invoked by typing @kbd{C-c C-m} and then
-either @kbd{C-r} for a region or @kbd{C-b} for the whole buffer.
-
address@hidden 800
address@hidden
-Use the @address@hidden commands:
-
address@hidden
address@hidden
-C-c C-e C-r @r{Format the region.}
-C-c C-e C-b @r{Format the buffer.}
address@hidden group
address@hidden example
-
address@hidden 750
address@hidden
-Use @code{makeinfo}:
-
address@hidden
-C-c C-m C-r @r{Format the region.}
-C-c C-m C-b @r{Format the buffer.}
-C-c C-m C-l @r{Recenter the @code{makeinfo} output buffer.}
-C-c C-m C-k @r{Kill the @code{makeinfo} formatting job.}
address@hidden example
-
address@hidden Typeset and Print
-
-The @TeX{} typesetting and printing commands are invoked by typing
address@hidden C-t} and then another control command: @kbd{C-r} for
address@hidden, @kbd{C-b} for @code{texinfo-tex-buffer},
-and so on.
-
address@hidden
-C-c C-t C-r @r{Run @TeX{} on the region.}
-C-c C-t C-b @r{Run} @code{texi2dvi} @r{on the buffer.}
-C-c C-t C-i @r{Run} @code{texindex}.
-C-c C-t C-p @r{Print the DVI file.}
-C-c C-t C-q @r{Show the print queue.}
-C-c C-t C-d @r{Delete a job from the print queue.}
-C-c C-t C-k @r{Kill the current @TeX{} formatting job.}
-C-c C-t C-x @r{Quit a currently stopped @TeX{} formatting job.}
-C-c C-t C-l @r{Recenter the output buffer.}
address@hidden example
-
address@hidden Other Updating Commands
-
-The remaining updating commands do not have standard keybindings because
-they are rarely used.
-
address@hidden
address@hidden
-M-x texinfo-insert-node-lines
- @r{Insert missing @code{@@node} lines in region.}
- @r{With @kbd{C-u} as a prefix argument,}
- @r{use section titles as node names.}
address@hidden group
-
address@hidden
-M-x texinfo-multiple-files-update
- @r{Update a multi-file document.}
- @r{With @kbd{C-u 2} as a prefix argument,}
- @r{create or update all nodes and menus}
- @r{in all included files first.}
address@hidden group
-
address@hidden
-M-x texinfo-indent-menu-description
- @r{Indent descriptions.}
address@hidden group
-
address@hidden
-M-x texinfo-sequential-node-update
- @r{Insert node pointers in strict sequence.}
address@hidden group
address@hidden example
-
-
address@hidden Beginning a File
address@hidden Beginning a Texinfo File
address@hidden Beginning a Texinfo file
address@hidden Texinfo file beginning
address@hidden File beginning
-
-Certain pieces of information must be provided at the beginning of a
-Texinfo file, such as the name for the output file(s), the title of the
-document, and the Top node. A table of contents is also generally
-produced here.
-
-This chapter expands on the minimal complete Texinfo source file
-previously given (@pxref{Six Parts}). It describes the numerous
-commands for handling the traditional frontmatter items in Texinfo.
-
address@hidden 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.
-
address@hidden
-* 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.
address@hidden menu
-
-
address@hidden Sample Beginning
address@hidden Sample Texinfo File Beginning
-
address@hidden 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.
-
address@hidden Sample Texts}, for the full texts to be used in GNU manuals.
-
address@hidden
-\input texinfo @@c -*-texinfo-*-
-@@c %**start of header
-@@setfilename @var{infoname}.info
-@@settitle @var{name-of-manual} @var{version}
-@@c %**end of header
-
-@@copying
-This manual is for @var{program}, version @var{version}.
-
-Copyright @@address@hidden@} @var{years} @var{copyright-owner}.
-
address@hidden
-@@quotation
-Permission is granted to @dots{}
-@@end quotation
-@@end copying
address@hidden group
-
address@hidden
-@@titlepage
-@@title @var{name-of-manual-when-printed}
-@@subtitle @var{subtitle-if-any}
-@@subtitle @var{second-subtitle}
-@@author @var{author}
address@hidden group
-
address@hidden
-@@c The following two commands
-@@c start the copyright page.
-@@page
-@@vskip 0pt plus 1filll
-@@insertcopying
address@hidden 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
-
address@hidden
-@@menu
-* First Chapter:: Getting started @dots{}
-* Second Chapter:: @dots{}
- @dots{}
-* Copying:: Your rights and freedoms.
-@@end menu
address@hidden group
-
address@hidden
-@@node First Chapter
-@@chapter First Chapter
-
-@@cindex first chapter
-@@cindex chapter, first
address@hidden
address@hidden group
address@hidden example
-
-
address@hidden Texinfo File Header
address@hidden Texinfo File Header
address@hidden Header for Texinfo files
address@hidden Texinfo file header
-
-Texinfo files start with at least three lines that provide Texinfo
-translators with necessary information. These are the @code{\input
-texinfo} line, the @code{@@settitle} line, and the
address@hidden@@setfilename} line.
-
-Also, if you want to format just part of the Texinfo file in Emacs,
-you must write the @code{@@settitle} and @code{@@setfilename} lines
-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} (@address@hidden@@synindex}}),
-for instance, is another command often included in the header.
-
-Thus, the beginning of a Texinfo file generally looks approximately
-like this:
-
address@hidden
address@hidden
-\input texinfo @@c -*-texinfo-*-
-@@c %**start of header
-@@setfilename sample.info
-@@settitle Sample Manual 1.0
-@@c %**end of header
address@hidden group
address@hidden example
-
-(@xref{GNU Sample Texts}, for complete sample texts.)
-
address@hidden
-* First Line:: The first line of a Texinfo file.
-* Start of Header:: Formatting a region requires this.
-* @t{@@setfilename}:: Tell Info the name of the Info file.
-* @t{@@settitle}:: Create a title for the printed work.
-* End of Header:: Formatting a region requires this.
address@hidden menu
-
-
address@hidden First Line
address@hidden The First Line of a Texinfo File
address@hidden First line of a Texinfo file
address@hidden Beginning line of a Texinfo file
address@hidden Header of a Texinfo file
-
-Every Texinfo file that is to be the top-level input to @TeX{} must begin
-with a line that looks like this:
-
address@hidden
-\input texinfo @@c -*-texinfo-*-
address@hidden example
-
address@hidden
-This line serves two functions:
-
address@hidden
address@hidden
-When the file is processed by @TeX{}, the @samp{\input texinfo} command
-tells @TeX{} to load the macros needed for processing a Texinfo file.
-These are in a file called @file{texinfo.tex}, which should have been
-installed on your system along with either the @TeX{} or Texinfo
-software. @TeX{} uses the backslash, @samp{\}, to mark the beginning of
-a command, exactly as Texinfo uses @samp{@@}. The @file{texinfo.tex}
-file causes the switch from @samp{\} to @samp{@@}; before the switch
-occurs, @TeX{} requires @samp{\}, which is why it appears at the
-beginning of the file.
-
address@hidden
-When the file is edited in GNU Emacs, the @samp{-*-texinfo-*-} mode
-specification tells Emacs to use Texinfo mode.
address@hidden enumerate
-
-
address@hidden Start of Header
address@hidden Start of Header
address@hidden Start of header line
-
-A start-of-header line is a Texinfo comment that looks like this:
-
address@hidden
-@@c %**start of header
address@hidden example
-
-Write the start-of-header line on the second line of a Texinfo file.
-Follow the start-of-header line with @code{@@setfilename} and
address@hidden@@settitle} lines and, optionally, with other commands that
-globally affect the document formatting, such as @code{@@synindex} or
address@hidden@@footnotestyle}; and then by an end-of-header line (@pxref{End of
-Header}).
-
-The start- and end-of-header lines allow you to format only part of a
-Texinfo file for Info or printing. @address@hidden commands}.
-
-The odd string of characters, @samp{%**}, is to ensure that no other
-comment is accidentally taken for a start-of-header line. You can
-change it if you wish by setting the @code{tex-start-of-header} and/or
address@hidden Emacs variables. @xref{Texinfo Mode Printing}.
-
-
address@hidden @t{@@setfilename}
address@hidden @code{@@setfilename}: Set the Output File Name
-
address@hidden@c old name
address@hidden setfilename
address@hidden Texinfo requires @code{@@setfilename}
address@hidden Output file name, required
-
-The first Texinfo command (that is, after the @code{\input texinfo})
-in a document is generally @code{@@setfilename}:
-
address@hidden
-@@setfilename @var{info-file-name}
address@hidden example
-
-This command is required for @TeX{}, and very strongly recommended for
address@hidden
-
-Write the @code{@@setfilename} command at the beginning of a line and
-follow it on the same line by the Info file name. Do not write
-anything else on the line.
-
address@hidden Ignored before @code{@@setfilename}
address@hidden @samp{\input} source line ignored
-When an @code{@@setfilename} line is present, the Texinfo processors
-ignore everything written before the @code{@@setfilename} line. This
-is why the very first line of the file (the @code{\input} line) does
-not show up in the output.
-
-The @code{@@setfilename} line specifies the name of the output file to
-be generated. This name must be different from the name of the
-Texinfo file. There are two conventions for choosing the name: you
-can either remove the extension (such as @samp{.texi}) entirely from
-the input file name, or (recommended) replace it with the @samp{.info}
-extension.
-
address@hidden Length of file names
address@hidden File name collision
address@hidden Info file name, choosing
-Although an explicit @samp{.info} extension is preferable, some
-operating systems cannot handle long file names. You can run into a
-problem even when the file name you specify is itself short enough.
-This occurs because the Info formatters split a long Info file into
-short indirect subfiles, and name them by appending @samp{-1},
address@hidden, @dots{}, @samp{-10}, @samp{-11}, and so on, to the original
-file name. (@xref{Tag and Split Files}.) The subfile name
address@hidden, for example, is too long for old systems with
-a 14-character limit on filenames; so the Info file name for this
-document is @file{texinfo} rather than @file{texinfo.info}. When
address@hidden is running on operating systems such as MS-DOS which
-impose severe limits on file names, it may remove some characters from
-the original file name to leave enough space for the subfile suffix,
-thus producing files named @file{texin-10}, @file{gcc.i12}, etc.
-
-When producing another output format, @code{makeinfo} will replace any
-final extension with the output format-specific extension (@samp{html}
-when generating HTML, for example), or add a dot followed by the
-extension (@samp{.html} for HTML) if the given name has no extension.
-
address@hidden texinfo.cnf
-The @code{@@setfilename} line produces no output when you typeset a
-manual with @TeX{}, but it is nevertheless essential: it opens the
-index and other auxiliary files used by Texinfo, and also reads
address@hidden if that file is present on your system
-(@pxref{Preparing for @TeX{}}).
-
-If there is no @code{@@setfilename} line, @code{makeinfo} uses the
-input file name to determine the output name: first, any of the
-extensions @code{.texi}, @code{.tex}, @code{.txi} or @code{.texinfo}
-is removed from the input file name; then, the output format specific
-extension is address@hidden when generating HTML, @code{.info}
-when generating Info, etc. The @code{\input} line is still ignored in
-this processing, as well as leading blank lines.
-
-See also the @option{--output} option in @ref{Invoking @t{texi2any}}.
-
-
address@hidden @t{@@settitle}
address@hidden @code{@@settitle}: Set the Document Title
-
address@hidden@c old name
address@hidden settitle
address@hidden Document title, specifying
-
-A Texinfo file should contain a line that looks like this:
-
address@hidden
-@@settitle @var{title}
address@hidden example
-
-Write the @code{@@settitle} command at the beginning of a line and
-follow it on the same line by the title. Do not write anything else
-on the line. The @code{@@settitle} command should precede everything
-that generates actual output. The best place for it is right after
-the @code{@@setfilename} command (described in the previous section).
-
-This command tells @TeX{} the title to use in a header or footer
-for double-sided output, in case such headings are output. For
-more on headings for @TeX{}, see @ref{Heading Generation}.
-
address@hidden @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
-(@address@hidden@@documentdescription}}).
-
-When the title page is used in the output, the title in the
address@hidden@@settitle} command does not affect the title as it appears on
-the title page. Thus, the two do not need not match exactly. A
-practice we recommend is to include the version or edition number of
-the manual in the @code{@@settitle} title; on the title page, the
-version number generally appears as an @code{@@subtitle} so it would
-be omitted from the @code{@@title}. @address@hidden@@titlepage}}.
-
-
address@hidden End of Header
address@hidden End of Header
address@hidden End of header line
-
-Follow the header lines with an @w{end-of-header} line, which is a
-Texinfo comment that looks like this:
-
address@hidden
-@@c %**end of header
address@hidden example
-
address@hidden of Header}.
-
-
address@hidden Document Permissions
address@hidden Document Permissions
address@hidden Document Permissions
address@hidden Copying Permissions
-
-The copyright notice and copying permissions for a document need to
-appear in several places in the various Texinfo output formats.
-Therefore, Texinfo provides a command (@code{@@copying}) to declare
-this text once, and another command (@code{@@insertcopying}) to
-insert the text at appropriate points.
-
address@hidden Copying address@hidden 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
-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 address@hidden It is helpful to state the license of
-the software of the manual, but giving the complete text of the
-software license is not necessarily required.
-
address@hidden
-* @t{@@copying}:: Declare the document's copying
permissions.
-* @t{@@insertcopying}:: Where to insert the permissions.
address@hidden menu
-
-
address@hidden @t{@@copying}
address@hidden @code{@@copying}: Declare Copying Permissions
-
address@hidden@c old name
address@hidden copying
-
-The @code{@@copying} command should be given very early in the document;
-the recommended location is right after the header material
-(@pxref{Texinfo File Header}). It conventionally consists of a sentence
-or two about what the program is, identification of the documentation
-itself, the legal copyright line, and the copying permissions. Here is
-a skeletal example:
-
address@hidden
-@@copying
-This manual is for @var{program} (version @var{version}, updated
address@hidden), which @dots{}
-
-Copyright @@address@hidden@} @var{years} @var{copyright-owner}.
-
-@@quotation
-Permission is granted to @dots{}
-@@end quotation
-@@end copying
address@hidden example
-
-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, and XML 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.
-
address@hidden copyright
-The @code{@@address@hidden@}} command generates a @samp{c} inside a
-circle when the output format supports this glyph (print and HTML
-always do, for instance). When the glyph is not supported in the
-output, it generates the three-character sequence @samp{(C)}.
-
-The copyright notice itself has the following legally-prescribed
-form:
-
address@hidden
-Copyright @copyright{} @var{years} @var{copyright-owner}.
address@hidden example
-
address@hidden Copyright word, always in English
-The word `Copyright' must always be written in English, even if the
-document is otherwise written in another language. This is due to
-international law.
-
address@hidden Years, in copyright line
-The list of years should include all years in which a version was
-completed (even if it was released in a subsequent year). It is
-simplest for each year to be written out individually and in full,
-separated by commas.
-
address@hidden Copyright holder for FSF works
address@hidden Holder of copyright for FSF works
address@hidden Owner of copyright for FSF works
-The copyright owner (or owners) is whoever holds legal copyright on the
-work. In the case of works assigned to the FSF, the owner is `Free
-Software Foundation, Inc.'.
-
-The copyright `line' may actually be split across multiple lines, both
-in the source document and in the output. This often happens for
-documents with a long history, having many different years of
-publication. If you do use several lines, do not indent any of them
-(or anything else in the @code{@@copying} block) in the source file.
-
address@hidden Notices,,, maintain, GNU Maintainer Information}, for
-additional information. @xref{GNU Sample Texts}, for the full text to
-be used in GNU manuals. @xref{GNU Free Documentation License}, for
-the license itself under which GNU and other free manuals are
-distributed.
-
-
address@hidden @t{@@insertcopying}
address@hidden @code{@@insertcopying}: Include Permissions Text
-
address@hidden@c old name
address@hidden insertcopying
address@hidden Copying text, including
address@hidden Permissions text, including
address@hidden Including permissions text
-
-The @code{@@insertcopying} command is simply written on a line by
-itself, like this:
-
address@hidden
-@@insertcopying
address@hidden example
-
-This inserts the text previously defined by @code{@@copying}. To meet
-legal requirements, it must be used on the copyright page in the printed
-manual (@pxref{Copyright}).
-
-The @code{@@copying} command itself causes the permissions text to
-appear in an Info file @emph{before} the first node. The text is also
-copied into the beginning of each split Info output file, as is legally
-necessary. This location implies a human reading the manual using Info
-does @emph{not} see this text (except when using the advanced Info
-command @kbd{g *}), but this does not matter for legal purposes,
-because the text is present.
-
-Similarly, the @code{@@copying} text is automatically included at the
-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.
-
-
address@hidden Titlepage & Copyright Page
address@hidden 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.
-
-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.
-
address@hidden
-* @t{@@titlepage}:: Create a title for the printed document.
-* @t{@@titlefont @@center @@sp}:: The @code{@@titlefont}, @code{@@center},
- and @code{@@sp} commands.
-* @t{@@title @@subtitle @@author}:: The @code{@@title}, @code{@@subtitle},
- and @code{@@author} commands.
-* Copyright:: How to write the copyright notice and
- include copying permissions.
-* Heading Generation:: Turn on page headings after the title and
- copyright pages.
address@hidden menu
-
-
address@hidden @t{@@titlepage}
address@hidden @code{@@titlepage}
-
address@hidden@c old name
address@hidden Title page
address@hidden titlepage
-
-Start the material for the title page and following copyright page
-with @code{@@titlepage} on a line by itself and end it with
address@hidden@@end titlepage} on a line by itself.
-
-The @code{@@end titlepage} command starts a new page and turns on page
-numbering (@pxref{Heading Generation}). All the
-material that you want to appear on unnumbered pages should be put
-between the @code{@@titlepage} and @code{@@end titlepage} commands.
-You can force the table of contents to appear there with the
address@hidden@@setcontentsaftertitlepage} command (@pxref{Contents}).
-
address@hidden address@hidden, within @code{@@titlepage}}
-By using the @code{@@page} command you can force a page break within the
-region delineated by the @code{@@titlepage} and @code{@@end titlepage}
-commands and thereby create more than one unnumbered page. This is how
-the copyright page is produced. (The @code{@@titlepage} command might
-perhaps have been better named the @code{@@titleandadditionalpages}
-command, but that would have been rather long!)
-
-When you write a manual about a computer program, you should write the
-version of the program to which the manual applies on the title page.
-If the manual changes more frequently than the program or is independent
-of it, you should also include an edition address@hidden have found
-that it is helpful to refer to versions of independent manuals as
-`editions' and versions of programs as `versions'; otherwise, we find we
-are liable to confuse each other in conversation by referring to both
-the documentation and the software with the same words.} for the manual.
-This helps readers keep track of which manual is for which version of
-the program. (The `Top' node should also contain this information; see
address@hidden 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
address@hidden@@author} commands to create a title page with black rules under
-the title and author lines and the subtitle text set flush to the
-right hand side of the page. With this method, you do not specify any
-of the actual formatting of the title page. You specify the text
-you want, and Texinfo does the formatting.
-
-You may use either method, or you may combine them; see the examples in
-the sections below.
-
address@hidden shorttitlepage
address@hidden Bastard title page
address@hidden Title page, bastard
-For sufficiently simple documents, and for the bastard title page in
-traditional book frontmatter, Texinfo also provides a command
address@hidden@@shorttitlepage} which takes the rest of the line as the title.
-The argument is typeset on a page by itself and followed by a blank
-page.
-
-
address@hidden @t{@@titlefont @@center @@sp}
address@hidden @code{@@titlefont}, @code{@@center}, and @code{@@sp}
-
address@hidden center address@hidden old name
address@hidden titlefont
address@hidden center
address@hidden 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
address@hidden<h1>} heading, but the HTML document @code{<title>} is not
-affected. For that, you must put an @code{@@settitle} command before
-the @code{@@titlefont} command (@address@hidden@@settitle}}).
-
address@hidden 700
-For example:
-
address@hidden
-@@address@hidden@}
address@hidden example
-
-Use the @code{@@center} command at the beginning of a line to center
-the remaining text on that line. Thus,
-
address@hidden
-@@center @@address@hidden@}
address@hidden example
-
address@hidden
-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:
-
address@hidden
-@@sp 2
address@hidden example
-
address@hidden
-This inserts two blank lines on the printed page.
-(@address@hidden@@sp}}, for more information about the @code{@@sp}
-command.)
-
-A template for this method looks like this:
-
address@hidden
address@hidden
-@@titlepage
-@@sp 10
-@@center @@address@hidden@address@hidden
-@@sp 2
-@@center @var{subtitle-if-any}
-@@sp 2
-@@center @var{author}
address@hidden
-@@end titlepage
address@hidden group
address@hidden example
-
-The spacing of the example fits an 8.5 by 11 inch manual.
-
-You can in fact use these commands anywhere, not just on a title page,
-but since they are not logical markup commands, we don't recommend
-them.
-
address@hidden @t{@@title @@subtitle @@author}
address@hidden @code{@@title}, @code{@@subtitle}, and @code{@@author}
-
address@hidden subtitle address@hidden old name
address@hidden title
address@hidden subtitle
address@hidden author
-
-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.
-
-Write the @code{@@title}, @code{@@subtitle}, or @code{@@author}
-commands at the beginning of a line followed by the title, subtitle,
-or author. The @code{@@author} command may be used for a quotation in
-an @code{@@quotation} block (@address@hidden@@quotation}});
-except for that, it is an error to use any of these commands outside
-of @code{@@titlepage}.
-
-The @code{@@title} command produces a line in which the title is set
-flush to the left-hand side of the page in a larger than normal font.
-The title is underlined with a black rule. The title must be given on
-a single line in the source file; it will be broken into multiple
-lines of output is needed.
-
-For long titles, the @code{@@*} command may be used to specify the
-line breaks in long titles if the automatic breaks do not suit. Such
-explicit line breaks are generally reflected in all output formats; if
-you only want to specify them for the printed output, use a
-conditional (@pxref{Conditionals}). For example:
-
address@hidden
-@@title This Long Title@@address@hidden,@@address@hidden Is Broken in
@@address@hidden@}
address@hidden example
-
-The @code{@@subtitle} command sets subtitles in a normal-sized font
-flush to the right-hand side of the page.
-
-The @code{@@author} command sets the names of the author or authors in
-a middle-sized font flush to the left-hand side of the page on a line
-near the bottom of the title page. The names are followed by a black
-rule that is thinner than the rule that underlines the title.
-
-There are two ways to use the @code{@@author} command: you can write
-the name or names on the remaining part of the line that starts with
-an @code{@@author} command:
-
address@hidden
-@@author by Jane Smith and John Doe
address@hidden example
-
address@hidden
-or you can write the names one above each other by using multiple
address@hidden@@author} commands:
-
address@hidden
address@hidden
-@@author Jane Smith
-@@author John Doe
address@hidden group
address@hidden example
-
address@hidden 950
-A template for this method looks like this:
-
address@hidden
address@hidden
-@@titlepage
-@@title @var{name-of-manual-when-printed}
-@@subtitle @var{subtitle-if-any}
-@@subtitle @var{second-subtitle}
-@@author @var{author}
-@@page
address@hidden
-@@end titlepage
address@hidden group
address@hidden example
-
-
address@hidden Copyright
address@hidden Copyright Page
address@hidden Copyright page
address@hidden Printed permissions
address@hidden Permissions, printed
-
-By international treaty, the copyright notice for a book must be either
-on the title page or on the back of the title page. When the copyright
-notice is on the back of the title page, that page is customarily not
-numbered. Therefore, in Texinfo, the information on the copyright page
-should be within @code{@@titlepage} and @code{@@end titlepage}
-commands.
-
address@hidden vskip @address@hidden vertical skip}
address@hidden filll @address@hidden dimension}
-Use the @code{@@page} command to cause a page break. To push the
-copyright notice and the other text on the copyright page towards the
-bottom of the page, use the following incantation after @code{@@page}:
-
address@hidden
-@@vskip 0pt plus 1filll
address@hidden example
-
address@hidden
-The @code{@@vskip} command inserts whitespace in the @TeX{} output; it
-is ignored in all other output formats. The @samp{0pt plus 1filll}
-means to put in zero points of mandatory whitespace, and as much
-optional whitespace as needed to push the following text to the bottom
-of the page. Note the use of three @samp{l}s in the word
address@hidden; this is correct.
-
-To insert the copyright text itself, write @code{@@insertcopying}
-next (@pxref{Document Permissions}):
-
address@hidden
-@@insertcopying
address@hidden example
-
-Follow the copying text by the publisher, ISBN numbers, cover art
-credits, and other such information.
-
-Here is an example putting all this together:
-
address@hidden
-@@titlepage
address@hidden
-@@page
-@@vskip 0pt plus 1filll
-@@insertcopying
-
-Published by @dots{}
-
-Cover art by @dots{}
-@@end titlepage
address@hidden example
-
-We have one more special case to consider: for plain text output, you
-must insert the copyright information explicitly if you want it to
-appear. For instance, you could have the following after the copyright
-page:
-
address@hidden
-@@ifplaintext
-@@insertcopying
-@@end ifplaintext
address@hidden example
-
-You could include other title-like information for the plain text
-output in the same place.
-
-
-
address@hidden Heading Generation
address@hidden Heading Generation
-
address@hidden address@hidden old name
address@hidden Headings, page, begin to appear
address@hidden Titlepage end starts headings
address@hidden End titlepage starts headings
address@hidden Generating page headings
-
-Like all @code{@@end} commands (@pxref{Quotations and Examples}), the
address@hidden@@end titlepage} command must be written at the beginning of a
-line by itself, with only one space between the @code{@@end} and the
address@hidden It not only marks the end of the title and
-copyright pages, but also causes @TeX{} to start generating page
-headings and page numbers.
-
-Texinfo has two standard page heading formats, one for documents
-printed on one side of each sheet of paper (single-sided printing),
-and the other for documents printed on both sides of each sheet
-(double-sided printing).
-
-In full generality, you can control the headings in different ways:
-
address@hidden @bullet
address@hidden
-The conventional way is to write an @code{@@setchapternewpage} command
-before the title page commands, if required, and then have the
address@hidden@@end titlepage} command start generating page headings in the
-manner desired.
-
-Most documents are formatted with the standard single-sided or
-double-sided headings, (sometimes) using @code{@@setchapternewpage
-odd} for double-sided printing and (almost always) no
address@hidden@@setchapternewpage} command for single-sided printing
-(@address@hidden@@setchapternewpage}}).
-
address@hidden
-Alternatively, you can use the @code{@@headings} command to prevent
-page headings from being generated or to start them for either single
-or double-sided printing. Write an @code{@@headings} command
-immediately after the @code{@@end titlepage} command. To turn off
-headings, write @code{@@headings off}. @address@hidden@@headings}}.
-
address@hidden
-Or, you may specify your own page heading and footing format.
address@hidden
address@hidden itemize
-
-
address@hidden Contents
address@hidden Generating a Table of Contents
address@hidden Table of contents
address@hidden Contents, table of
address@hidden Short table of contents
address@hidden contents
address@hidden summarycontents
address@hidden shortcontents
-
-The @code{@@chapter}, @code{@@section}, and other structuring commands
-(@pxref{Chapter Structuring}) supply the information to make up a
-table of contents, but they do not cause an actual table to appear in
-the manual. To do this, you must use the @code{@@contents} and/or
address@hidden@@summarycontents} command(s).
-
address@hidden @code
address@hidden @@contents
-Generates a table of contents in a printed manual, including all
-chapters, sections, subsections, etc., as well as appendices and
-unnumbered chapters. Headings generated by @code{@@majorheading},
address@hidden@@chapheading}, and the other @code{@@@dots{}heading} commands
-do not appear in the table of contents (@pxref{Structuring Command
-Types}).
-
address@hidden @@shortcontents
address@hidden @@summarycontents
-(@code{@@summarycontents} is a synonym for @code{@@shortcontents}.)
-
-Generates a short or summary table of contents that lists only the
-chapters, appendices, and unnumbered chapters. Sections, subsections
-and subsubsections are omitted. Only a long manual needs a short
-table of contents in addition to the full table of contents.
address@hidden table
-
-Both contents commands should be written on a line by themselves, and
-placed near the beginning of the file, after the @code{@@end
-titlepage} (@address@hidden@@titlepage}}), before any sectioning
-command. The contents commands automatically generate a chapter-like
-heading at the top of the first table of contents page, so don't
-include any sectioning command such as @code{@@unnumbered} before
-them.
-
-Since an Info file uses menus instead of tables of contents, the Info
-formatting commands ignore the contents commands. But the contents
-are included in plain text output (generated by @code{makeinfo
---plaintext}) and in other output formats, such as HTML.
-
-When @code{makeinfo} writes a short table of contents while producing
-HTML output, the links in the short table of contents point to
-corresponding entries in the full table of contents rather than the text
-of the document. The links in the full table of contents point to the
-main text of the document.
-
-In the past, the contents commands were sometimes placed at the end of
-the file, after any indices and just before the @code{@@bye}, but we
-no longer recommend this.
-
address@hidden setcontentsaftertitlepage
address@hidden setshortcontentsaftertitlepage
address@hidden Contents, after title page
address@hidden Table of contents, after title page
-However, since many existing Texinfo documents still do have the
address@hidden@@contents} at the end of the manual, if you are a user printing
-a manual, you may wish to force the contents to be printed after the
-title page. You can do this by specifying
address@hidden@@setcontentsaftertitlepage} and/or
address@hidden@@setshortcontentsaftertitlepage}. The first prints only the
-main contents after the @code{@@end titlepage}; the second prints both
-the short contents and the main contents. In either case, any
-subsequent @code{@@contents} or @code{@@shortcontents} is ignored.
-
-You need to include the @code{@@address@hidden
-commands early in the document (just after @code{@@setfilename}, for
-example). We recommend using @command{texi2dvi} (@pxref{Format with
address@hidden) to specify this without altering the source file at
-all. For example:
-
address@hidden
-texi2dvi --texinfo=@@setcontentsaftertitlepage foo.texi
address@hidden example
-
-An alternative invocation, using @command{texi2any}:
-
address@hidden
-texi2any --dvi --Xopt --texinfo=@@setcontentsaftertitlepage foo.texi
address@hidden example
-
-
-
address@hidden The Top Node
address@hidden The `Top' Node and Master Menu
address@hidden Top node
address@hidden Node, `Top'
-
-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.
-
address@hidden top
-It is conventional and desirable to write an @code{@@top} sectioning
-command line containing the title of the document immediately after
-the @code{@@node Top} line (@address@hidden@@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
address@hidden@@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
address@hidden@@ifnottex} and @code{@@end ifnottex}, but it is simplest to do
-so. @xref{Conditionals, , Conditionally Visible Text}.)
-
address@hidden
-* Top Node Example::
-* Master Menu Parts::
address@hidden menu
-
-
address@hidden Top Node Example
address@hidden Top Node Example
-
address@hidden Top node example
-
-Here is an example of a Top node.
-
address@hidden
address@hidden
-@@ifnottex
-@@node Top
-@@top Sample Title
-
-@@insertcopying
-@@end ifnottex
address@hidden group
-
-Additional general information.
-
address@hidden
-@@menu
-* First Chapter::
-* Second Chapter::
address@hidden
-* Index::
address@hidden group
-@@end menu
address@hidden example
-
-
address@hidden Master Menu Parts
address@hidden Parts of a Master Menu
address@hidden Master menu
address@hidden Menu, master
address@hidden Parts of a master menu
-
-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
address@hidden@@end menu} and does not appear in the printed output.
-
-Generally, a master menu is divided into parts.
-
address@hidden @bullet
address@hidden
-The first part contains the major nodes in the Texinfo file: the nodes
-for the chapters, chapter-like sections, and the appendices.
-
address@hidden
-The second part contains nodes for the indices.
-
address@hidden
address@hidden detailmenu
address@hidden 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
address@hidden@@end detailmenu} after the last; otherwise, @code{makeinfo}
-will get confused.
address@hidden itemize
-
-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
-treated as a menu entry. (@xref{Writing a Menu}, for more
-information.)
-
-For example, the master menu for this manual looks like the following
-(but has many more entries):
-
address@hidden
address@hidden
-@@menu
-* Copying Conditions:: Your rights.
-* Overview:: Texinfo in brief.
address@hidden
address@hidden group
address@hidden
-* Command and Variable Index::
-* General Index::
address@hidden group
-
address@hidden
-@@detailmenu
---- The Detailed Node Listing ---
-
-Overview of Texinfo
-
-* Reporting Bugs:: @dots{}
address@hidden
address@hidden group
-
address@hidden
-Beginning a Texinfo File
-
-* Sample Beginning:: @dots{}
address@hidden
-@@end detailmenu
-@@end menu
address@hidden group
address@hidden example
-
-
address@hidden Global Document Commands
address@hidden Global Document Commands
address@hidden 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.
-
address@hidden
-* @t{@@documentdescription}:: Document summary for the HTML output.
-* @t{@@setchapternewpage}:: Start chapters on right-hand pages.
-* @t{@@headings}:: An option for turning headings on and off
- and double or single sided printing.
-* @t{@@paragraphindent}:: Specify paragraph indentation.
-* @t{@@firstparagraphindent}:: Suppressing first paragraph indentation.
-* @t{@@exampleindent}:: Specify environment indentation.
address@hidden menu
-
-
address@hidden @t{@@documentdescription}
address@hidden @code{@@documentdescription}: Summary Text
address@hidden@c old name
-
address@hidden Document description
address@hidden Description of document
address@hidden Summary of document
address@hidden Abstract of document
address@hidden <meta> HTML tag, and document description
address@hidden documentdescription
-
-When producing HTML output for a document, @command{makeinfo} writes a
address@hidden<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
-(@address@hidden@@settitle}}). To change this, use the
address@hidden@@documentdescription} environment, as in:
-
address@hidden
-@@documentdescription
-descriptive text.
-@@end documentdescription
address@hidden example
-
address@hidden
-This will produce the following output in the @samp{<head>} of the HTML:
-
address@hidden
-<meta name=description content="descriptive text.">
address@hidden example
-
address@hidden@@documentdescription} must be specified before the first node of
-the document.
-
-
address@hidden @t{@@setchapternewpage}
address@hidden @code{@@setchapternewpage}: Blank Pages Before Chapters
-
address@hidden@c old name
address@hidden setchapternewpage
address@hidden Starting chapters
address@hidden 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:
-
address@hidden
-@@setchapternewpage odd
address@hidden example
-
-You can specify one of three alternatives with the
address@hidden@@setchapternewpage} command:
-
address@hidden @asis
-
address@hidden @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.
-
address@hidden @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.
-
address@hidden @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.
address@hidden table
-
-Texinfo does not have an @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.
address@hidden@t{@@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.
-
-
address@hidden @t{@@headings}
address@hidden The @code{@@headings} Command
-
address@hidden on address@hidden old name
address@hidden 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
address@hidden@@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 an @code{@@headings} command
-immediately after the @code{@@end titlepage} command.
-
-You can use @code{@@headings} as follows:
-
address@hidden @code
address@hidden @@headings off
-Turn off printing of page headings.
-
address@hidden @@headings single
-Turn on page headings appropriate for single-sided printing.
-
address@hidden @@headings double
-Turn on page headings appropriate for double-sided printing.
-
address@hidden @@headings singleafter
address@hidden @@headings doubleafter
-Turn on @code{single} or @code{double} headings, respectively, after the
-current page is output.
-
address@hidden @@headings on
-Turn on page headings: @code{single} if @samp{@@setchapternewpage
-on}, @code{double} otherwise.
address@hidden table
-
-For example, suppose you write @code{@@setchapternewpage off} before the
address@hidden@@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
address@hidden to typeset page headers for single-sided printing. To cause
address@hidden 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:
-
address@hidden
-@@end titlepage
-@@headings off
address@hidden example
-
address@hidden
-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.
address@hidden, , Page Headings}, for more information.
-
-
address@hidden @t{@@paragraphindent}
address@hidden @code{@@paragraphindent}: Controlling Paragraph Indentation
-
address@hidden@c old name
address@hidden paragraphindent
address@hidden Indenting paragraphs, control of
address@hidden 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 an @code{@@paragraphindent} command at the beginning of a line
-followed by either @samp{asis} or a number:
-
address@hidden
-@@paragraphindent @var{indent}
address@hidden example
-
-The indentation is according to the value of @var{indent}:
-
address@hidden @asis
address@hidden @code{asis}
-Do not change the existing indentation (not implemented in @TeX{}).
-
address@hidden @code{none}
address@hidden 0
-Omit all indentation.
-
address@hidden @var{n}
-Indent by @var{n} space characters in Info output, by @var{n} ems in
address@hidden
-
address@hidden 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}.
-
-A peculiarity of the @code{texinfo-format-buffer} and
address@hidden commands is that they do not indent (nor
-fill) paragraphs that contain @code{@@w} or @code{@@*} commands.
-
-
address@hidden @t{@@firstparagraphindent}
address@hidden @code{@@firstparagraphindent}: Indenting After Headings
-
address@hidden@c old name
address@hidden firstparagraphindent
address@hidden First paragraph, suppressing indentation of
address@hidden Suppressing first paragraph indentation
address@hidden Preventing first paragraph indentation
address@hidden Indenting, suppressing of first paragraph
address@hidden 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
address@hidden@@firstparagraphindent} command:
-
address@hidden
-@@firstparagraphindent @var{word}
address@hidden example
-
-The first paragraph after a heading is indented according to the value
-of @var{word}:
-
address@hidden @asis
address@hidden @code{none}
-Prevents the first paragraph from being indented (default).
-This option is ignored by @command{makeinfo} if
address@hidden@@paragraphindent asis} is in effect.
-
address@hidden @code{insert}
-Include normal paragraph indentation. This respects the paragraph
-indentation set by an @code{@@paragraphindent} command
-(@address@hidden@@paragraphindent}}).
address@hidden table
-
address@hidden@@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}.
-
-
address@hidden @t{@@exampleindent}
address@hidden @code{@@exampleindent}: Environment Indenting
-
address@hidden@c old name
address@hidden exampleindent
address@hidden Indenting environments
address@hidden Environment indentation
address@hidden 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:
-
address@hidden
-@@exampleindent @var{indent}
address@hidden example
-
-The indentation is according to the value of @var{indent}:
-
address@hidden @asis
address@hidden @code{asis}
-Do not change the existing indentation (not implemented in @TeX{}).
-
address@hidden 0
-Omit all indentation.
-
address@hidden @var{n}
-Indent environments by @var{n} space characters in Info output, by
address@hidden ems in @TeX{}.
-
address@hidden table
-
-The default value of @var{indent} is 5 spaces in Info, and address@hidden
-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}.
-
-
address@hidden Ending a File
address@hidden Ending a Texinfo File
address@hidden Ending a Texinfo file
address@hidden Texinfo file ending
address@hidden File ending
address@hidden bye
-
-The end of a Texinfo file should include commands to create indices,
-and the @code{@@bye} command to mark the last line to be processed.
-For example:
-
address@hidden
-@@node Index
-@@unnumbered Index
-
-@@printindex cp
-
-@@bye
address@hidden example
-
address@hidden
-* Printing Indices & Menus:: How to print an index in hardcopy and
- generate index menus in Info.
-* File End:: How to mark the end of a file.
address@hidden menu
-
-
address@hidden Printing Indices & Menus
address@hidden Printing Indices and Menus
address@hidden Printing an index
address@hidden Indices, printing and menus
address@hidden Generating menus with indices
address@hidden Menus generated with indices
-
-To print an index means to include it as part of a manual or Info file.
-This does not happen automatically just because you use @code{@@cindex}
-or other index-entry generating commands in the Texinfo file; those just
-cause the raw data for the index to be accumulated. To generate an
-index, you must include the @code{@@printindex} command at the place in
-the document where you want the index to appear. Also, as part of the
-process of creating a printed manual, you must run a program called
address@hidden (@pxref{Hardcopy}) to sort the raw data to produce a
-sorted index file. The sorted index file is what is actually used to
-print the index.
-
-Texinfo offers six separate types of predefined index, which suffice
-in most cases. @xref{Indices}, for information on this, as well
-defining your own new indices, combining indices, and, most
-importantly advice on writing the actual index entries. This section
-focuses on printing indices, which is done with the
address@hidden@@printindex} command.
-
address@hidden printindex
address@hidden@@printindex} takes one argument, a two-letter index
-abbreviation. It reads the corresponding sorted index file (for
-printed output), and formats it appropriately into an index.
-
-The @code{@@printindex} command does not generate a chapter heading
-for the index, since different manuals have different needs.
-Consequently, you should precede the @code{@@printindex} command with
-a suitable section or chapter command (usually @code{@@appendix} or
address@hidden@@unnumbered}) to supply the chapter heading and put the index
-into the table of contents. Precede the chapter heading with an
address@hidden@@node} line as usual.
-
-For example:
-
address@hidden
address@hidden
-@@node Variable Index
-@@unnumbered Variable Index
-
-@@printindex vr
address@hidden group
-
address@hidden
-@@node Concept Index
-@@unnumbered Concept Index
-
-@@printindex cp
address@hidden group
address@hidden smallexample
-
-If you have more than one index, we recommend placing the concept index last.
-
address@hidden
address@hidden
-In printed output, @code{@@printindex} produces a traditional
-two-column index, with dot leaders between the index terms and page
-numbers.
-
address@hidden
-In Info output, @code{@@printindex} produces a special menu containing
-the line number of the entry, relative to the start of the node. Info
-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:
-
address@hidden
-* First index entry: Top. (line 7)
address@hidden smallexample
-
address@hidden 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
-printed manual.
-
address@hidden
-In plain text output, @code{@@printindex} produces the same menu, but
-the line numbers are relative to the start of the file, since that's
-more convenient for that format.
-
address@hidden
-In HTML output, @code{@@printindex} produces links to the index
-entries.
-
address@hidden
-In XML and Docbook output, it simply records the index to be printed.
address@hidden itemize
-
-
address@hidden File End
address@hidden @code{@@bye} File Ending
address@hidden bye
-
-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.
-
-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}).
-
-
address@hidden Chapter Structuring
address@hidden Chapter Structuring
address@hidden@c old name
address@hidden Chapter structuring
address@hidden Structuring of chapters
address@hidden Sectioning
-
-Texinfo's @dfn{chapter structuring} commands (could more generally be
-called @dfn{sectioning structuring}, but that is awkward) divide a
-document into a hierarchy of chapters, sections, subsections, and
-subsubsections. These commands generate large headings in the text,
-like the one above. They also provide information for generating the
-table of contents (@pxref{Contents,, Generating a Table of Contents}),
-and for implicitly determining node pointers, as is recommended
-(@address@hidden Pointer Creation}).
-
-The chapter structuring commands do not create a node structure, so
-normally you put an @code{@@node} command immediately before each
-chapter structuring command (@pxref{Nodes}). The only time you are
-likely to use the chapter structuring commands without also using
-nodes is if you are writing a document that contains no cross
-references and will only be printed, not transformed into Info, HTML,
-or other formats.
-
address@hidden
-* Tree Structuring:: A manual is like an upside down tree @dots{}
-* Structuring Command Types:: How to divide a manual into parts.
-* @t{@@chapter}:: Chapter structuring.
-* @t{@@unnumbered @@appendix}::
-* @t{@@majorheading @@chapheading}::
-* @t{@@section}::
-* @t{@@unnumberedsec @@appendixsec @@heading}::
-* @t{@@subsection}::
-* @t{@@unnumberedsubsec @@appendixsubsec @@subheading}::
-* @t{@@subsubsection}:: Commands for the lowest level sections.
-* @t{@@part}:: Collections of chapters.
-* Raise/lower sections:: How to change commands' hierarchical level.
address@hidden menu
-
-
address@hidden Tree Structuring
address@hidden Tree Structure of Sections
address@hidden Tree structuring
-
-A Texinfo file is usually structured like a book with chapters,
-sections, subsections, and the like. This structure can be visualized
-as a tree (or rather as an upside-down tree) with the root at the top
-and the levels corresponding to chapters, sections, subsection, and
-subsubsections.
-
-Here is a diagram that shows a Texinfo file with three chapters, each
-with two sections.
-
address@hidden
address@hidden
- Top
- |
- -------------------------------------
- | | |
- Chapter 1 Chapter 2 Chapter 3
- | | |
- -------- -------- --------
- | | | | | |
-Section Section Section Section Section Section
- 1.1 1.2 2.1 2.2 3.1 3.2
-
address@hidden group
address@hidden example
-
-In a Texinfo file that has this structure, the beginning of Chapter 2
-would normally (with implicitly-determined node pointers) be written
-like this:
-
address@hidden
address@hidden
-@@node Chapter 2
-@@chapter Chapter 2
address@hidden group
address@hidden example
-
address@hidden
-But for purposes of example, here is how it would be written with
-explicit node pointers:
-
address@hidden
address@hidden
-@@node Chapter 2, Chapter 3, Chapter 1, Top
-@@chapter Chapter 2
address@hidden group
address@hidden example
-
-The chapter structuring commands are described in the sections that
-follow; the @code{@@node} command is described in
-the following chapter (@pxref{Nodes}).
-
-
address@hidden Structuring Command Types
address@hidden Structuring Command Types
-
-The chapter structuring commands fall into four groups or series, each
-of which contains structuring commands corresponding to the
-hierarchical levels of chapters, sections, subsections, and
-subsubsections.
-
-The four groups of commands are the @code{@@chapter} series, the
address@hidden@@unnumbered} series, the @code{@@appendix} series, and the
address@hidden@@heading} series. Each command produces a title with a
-different appearance in the body of the document. Some of the
-commands list their titles in the tables of contents, while others do
-not. Here are the details:
-
address@hidden @bullet
address@hidden
-The @code{@@chapter} and @code{@@appendix} series of commands produce
-numbered or lettered entries both in the body of a document and in its
-table of contents.
-
address@hidden
-The @code{@@unnumbered} series of commands produce unnumbered entries
-both in the body of a document and in its table of contents. The
address@hidden@@top} command, which has a special use, is a member of this
-series (@address@hidden@@top} Command}). An @code{@@unnumbered} section
-is a normal part of the document structure.
-
address@hidden
-The @code{@@heading} series of commands produce simple unnumbered
-headings that do not appear in a table of contents, are not associated
-with nodes, and cannot be cross-referenced. These heading commands
-never start a new page.
address@hidden itemize
-
-When an @code{@@setchapternewpage} command says to do so, the
address@hidden@@chapter}, @code{@@unnumbered}, and @code{@@appendix} commands
-start new pages in the printed manual; the @code{@@heading} commands
-do not. @address@hidden@@setchapternewpage}}.
-
-Here is a summary:
-
address@hidden
-{\globaldefs=1 \smallfonts \rm}
address@hidden tex
-
address@hidden @columnfractions .19 .30 .29 .22
address@hidden @tab @tab
@tab No new page
address@hidden @i{Numbered} @tab @i{Unnumbered} @tab
@i{Lettered/numbered} @tab @i{Unnumbered}
address@hidden In contents @tab In contents @tab In
contents @tab Not in contents
address@hidden @tab @code{@@top} @tab
@tab @code{@@majorheading}
address@hidden @code{@@chapter} @tab @code{@@unnumbered} @tab
@code{@@appendix} @tab @code{@@chapheading}
address@hidden @code{@@section} @tab @code{@@unnumberedsec} @tab
@code{@@appendixsec} @tab @code{@@heading}
address@hidden @code{@@subsection} @tab @code{@@unnumberedsubsec} @tab
@code{@@appendixsubsec} @tab @code{@@subheading}
address@hidden @code{@@subsubsection} @tab @code{@@unnumberedsubsubsec} @tab
@code{@@appendixsubsubsec} @tab @code{@@subsubheading}
address@hidden multitable
address@hidden
-{\globaldefs=1 \textfonts \rm}
address@hidden tex
-
-
address@hidden @t{@@chapter}
address@hidden @code{@@chapter}: Chapter Structuring
-
address@hidden@c old name
address@hidden chapter
-
address@hidden@@chapter} identifies a chapter in the document--the highest
-level of the normal document structuring hierarchy. Write the command
-at the beginning of a line and follow it on the same line by the title
-of the chapter. The chapter is numbered automatically, starting
address@hidden
-
-For example, the present chapter in this manual is entitled
address@hidden@@chapter}: Chapter Structuring''; the @code{@@chapter} line
-looks like this:
-
address@hidden
-@@chapter @@address@hidden@@@@address@hidden: Chapter Structuring
address@hidden example
-
-In @TeX{}, the @code{@@chapter} command produces a chapter heading in
-the document.
-
-In Info and plain text output, the @code{@@chapter} command causes the
-title to appear on a line by itself, with a line of asterisks inserted
-underneath. So, the above example produces the following output:
-
address@hidden
address@hidden
-5 Chapter Structuring
-*********************
address@hidden group
address@hidden example
-
-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
-that includes all the following sections, up to the next chapter.
-
-
address@hidden @t{@@unnumbered @@appendix}
address@hidden @code{@@unnumbered}, @code{@@appendix}: Chapters with Other
Labeling
-
address@hidden & address@hidden old name
address@hidden unnumbered
address@hidden appendix
-
-Use the @code{@@unnumbered} command to start a chapter-level element
-that appears without chapter numbers of any kind. Use the
address@hidden@@appendix} command to start an appendix that is labeled by
-letter (`A', `B', @dots{}) instead of by number; appendices are also
-at the chapter level of structuring.
-
-Write an @code{@@appendix} or @code{@@unnumbered} command at the
-beginning of a line and follow it on the same line by the title,
-just as with @code{@@chapter}.
-
address@hidden centerchap
-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.
address@hidden but the Hacker's Dictionary wanted it, before they quit Texinfo.
-
-
address@hidden @t{@@majorheading @@chapheading}
address@hidden @code{@@majorheading}, @code{@@chapheading}: Chapter-level
Headings
-
address@hidden & address@hidden old name
address@hidden majorheading
address@hidden chapheading
-
-The @code{@@majorheading} and @code{@@chapheading} commands produce
-chapter-like headings in the body of a document.
-
-However, neither command produces an entry in the table of contents,
-and neither command causes @TeX{} to start a new page in a printed
-manual.
-
-In @TeX{}, an @code{@@majorheading} command generates a larger vertical
-whitespace before the heading than an @code{@@chapheading} command but
-is otherwise the same.
-
-In Info and plain text, the @code{@@majorheading} and
address@hidden@@chapheading} commands produce the same output as
address@hidden@@chapter}: the title is printed on a line by itself with a line
-of asterisks underneath. Similarly for address@hidden The only difference is
-the lack of numbering and the lack of any association with nodes.
address@hidden@t{@@chapter}}.
-
-
address@hidden @t{@@section}
address@hidden @code{@@section}: Sections Below Chapters
-
address@hidden@c old name
address@hidden section
-
-An @code{@@section} command identifies a section within a chapter
-unit, whether created with @code{@@chapter}, @code{@@unnumbered}, or
address@hidden@@appendix}, following the numbering scheme of the chapter-level
-command. Thus, within an @code{@@chapter} chapter numbered `1', the
-sections are numbered `1.1', `1.2', etc.; within an @code{@@appendix}
-``chapter'' labeled `A', the sections are numbered `A.1', `A.2', etc.;
-within an @code{@@unnumbered} chapter, the section gets no number.
-The output is underlined with @samp{=} in Info and plain text.
-
-To make a section, write the @code{@@section} command at the
-beginning of a line and follow it on the same line by the section
-title. For example,
-
address@hidden
-@@section This is a section
address@hidden example
-
address@hidden
-might produce the following in Info:
-
address@hidden
address@hidden
-5.7 This is a section
-=====================
address@hidden group
address@hidden example
-
-Section titles are listed in the table of contents.
-
-The @TeX{}, HTML, Docbook, and XML output is all analogous to the
-chapter-level output, just ``one level down''; @address@hidden@@chapter}}.
-
-
address@hidden @t{@@unnumberedsec @@appendixsec @@heading}
address@hidden @code{@@unnumberedsec}, @code{@@appendixsec}, @code{@@heading}
-
address@hidden appendixsec address@hidden old name
address@hidden unnumberedsec
address@hidden appendixsec
address@hidden heading
-
-The @code{@@unnumberedsec}, @code{@@appendixsec}, and @code{@@heading}
-commands are, respectively, the unnumbered, appendix-like, and
-heading-like equivalents of the @code{@@section} command (see the
-previous section).
-
address@hidden@@unnumberedsec} and @code{@@appendixsec} do not need to be used
-in ordinary circumstances, because @code{@@section} may also be used
-within @code{@@unnumbered} and @code{@@appendix} chapters; again, see
-the previous section.
-
address@hidden @code
address@hidden @@unnumberedsec
-The @code{@@unnumberedsec} command may be used within an unnumbered
-chapter or within a regular chapter or appendix to produce an
-unnumbered section.
-
address@hidden @@appendixsec
address@hidden @@appendixsection
address@hidden appendixsection
address@hidden appendixsec
address@hidden@@appendixsection} is a longer spelling of the
address@hidden@@appendixsec} command; the two are synonymous.
-
-Conventionally, the @code{@@appendixsec} or @code{@@appendixsection}
-command is used only within appendices.
-
address@hidden @@heading
-You may use the @code{@@heading} command anywhere you wish for a
-section-style heading that will not appear in the table of contents.
address@hidden table
-
-
address@hidden @t{@@subsection}
address@hidden @code{@@subsection}: Subsections Below Sections
-
address@hidden@c old name
address@hidden subsection
-
-Subsections are to sections as sections are to chapters;
address@hidden@t{@@section}}. In Info and plain text, subsection titles
-are underlined with @samp{-}. For example,
-
address@hidden
-@@subsection This is a subsection
address@hidden example
-
address@hidden
-might produce
-
address@hidden
address@hidden
-1.2.3 This is a subsection
---------------------------
address@hidden group
address@hidden example
-
-Subsection titles are listed in the table of contents.
-
-The @TeX{}, HTML, Docbook, and XML output is all analogous to the
-chapter-level output, just ``two levels down'';
address@hidden@t{@@chapter}}.
-
-
address@hidden @t{@@unnumberedsubsec @@appendixsubsec @@subheading}
address@hidden The @code{@@subsection}-like Commands
-
address@hidden appendixsubsec address@hidden old name
address@hidden unnumberedsubsec
address@hidden appendixsubsec
address@hidden subheading
address@hidden Subsection-like commands
-
-The @code{@@unnumberedsubsec}, @code{@@appendixsubsec}, and
address@hidden@@subheading} commands are, respectively, the unnumbered,
-appendix-like, and heading-like equivalents of the @code{@@subsection}
-command. (@address@hidden@@subsection}}.)
-
address@hidden@@unnumberedsubsec} and @code{@@appendixsubsec} do not need to
-be used in ordinary circumstances, because @code{@@subsection} may
-also be used within sections of @code{@@unnumbered} and
address@hidden@@appendix} chapters (@address@hidden@@section}}).
-
-An @code{@@subheading} command produces a heading like that of a
-subsection except that it is not numbered and does not appear in the
-table of contents. Similarly, an @code{@@unnumberedsubsec} command
-produces an unnumbered heading like that of a subsection and an
address@hidden@@appendixsubsec} command produces a subsection-like heading
-labeled with a letter and numbers; both of these commands produce
-headings that appear in the table of contents. In Info and plain
-text, the @code{@@subsection}-like commands generate a title
-underlined with hyphens.
-
-
address@hidden @t{@@subsubsection}
address@hidden @code{@@subsection} and Other Subsub Commands
-
address@hidden@c old name
address@hidden subsubsection
address@hidden unnumberedsubsubsec
address@hidden appendixsubsubsec
address@hidden subsubheading
address@hidden Subsub sectioning commands
-
-The fourth and lowest level sectioning commands in Texinfo are the
-`subsub' commands. They are:
-
address@hidden @code
address@hidden @@subsubsection
-Subsubsections are to subsections as subsections are to sections.
-(@address@hidden@@subsection}}.) Subsubsection titles appear in the
-table of contents.
-
address@hidden @@unnumberedsubsubsec
-Unnumbered subsubsection titles appear in the table of contents,
-but lack numbers. Otherwise, unnumbered subsubsections are the same
-as subsubsections.
-
address@hidden @@appendixsubsubsec
-Conventionally, appendix commands are used only for appendices and are
-lettered and numbered appropriately. They also appear in the table
-of contents.
-
address@hidden @@subsubheading
-The @code{@@subsubheading} command may be used anywhere that you want
-a small heading that will not appear in the table of contents.
address@hidden table
-
-As with subsections, @code{@@unnumberedsubsubsec} and
address@hidden@@appendixsubsubsec} do not need to be used in ordinary
-circumstances, because @code{@@subsubsection} may also be used within
-subsections of @code{@@unnumbered} and @code{@@appendix} chapters
-(@address@hidden@@section}}).
-
-In Info, `subsub' titles are underlined with periods. For example,
-
address@hidden
-@@subsubsection This is a subsubsection
address@hidden example
-
address@hidden
-might produce
-
address@hidden
address@hidden
-1.2.3.4 This is a subsubsection
-...............................
address@hidden group
address@hidden example
-
-The @TeX{}, HTML, Docbook, and XML output is all analogous to the
-chapter-level output, just ``three levels down''; @address@hidden@@chapter}}.
-
-
address@hidden @t{@@part}
address@hidden @code{@@part}: Groups of Chapters
address@hidden part
address@hidden Part pages
-
-The final sectioning command is @code{@@part}, to mark a @dfn{part} of
-a manual, that is, a group of chapters or (rarely) appendices. This
-behaves quite differently from the other sectioning commands, to fit
-with the way such ``parts'' are conventionally used in books.
-
-No @code{@@node} command is associated with @code{@@part}. Just write
-the command on a line by itself, including the part title, at the
-place in the document you want to mark off as starting that part. For
-example:
-
address@hidden
-@@part Part I:@@* The beginning
address@hidden example
-
-As can be inferred from this example, no automatic numbering or
-labeling of the @code{@@part} text is done. The text is taken as-is.
-
-Because parts are not associated with nodes, no general text can
-follow the @code{@@part} line. To produce the intended output, it
-must be followed by a chapter-level command (including its node).
-Thus, to continue the example:
-
address@hidden
-@@part Part I:@@* The beginning
-
-@@node Introduction
-@@chapter Introduction
-...
address@hidden example
-
-In the @TeX{} output, the @code{@@part} text is included in both the
-normal and short tables of contents (@pxref{Contents}), without a page
-number (since that is the normal convention). In addition, a ``part
-page'' is output in the body of the document, with just the
address@hidden@@part} text. In the example above, the @code{@@*} causes a
-line break on the part page (but is replaced with a space in the
-tables of contents). This part page is always forced to be on an odd
-(right-hand) page, regardless of the chapter pagination
-(@address@hidden@@setchapternewpage}}).
-
-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
-the following chapters, up to the next @code{<part>}. A @code{<part>}
-containing chapters is also closed at an appendix.
-
-In the Info and plain text output, @code{@@part} has no effect.
-
address@hidden@@part} is ignored when raising or lowering sections (see next
-section). That is, it is never lowered and nothing can be raised to it.
-
-
address@hidden Raise/lower sections
address@hidden Raise/lower Sections: @code{@@raisesections} and
@code{@@lowersections}
address@hidden raisesections
address@hidden lowersections
address@hidden Raising and lowering sections
address@hidden Lowering and raising sections
address@hidden Sections, raising and lowering
-
-The @code{@@raisesections} and @code{@@lowersections} commands
-implicitly raise and lower the hierarchical level of following
-chapters, sections and the other sectioning commands (excluding parts).
-
-That is, the @code{@@raisesections} command changes sections to
-chapters, subsections to sections, and so on. Conversely, the
address@hidden@@lowersections} command changes chapters to sections, sections
-to subsections, and so on. Thus, an @code{@@lowersections} command
-cancels an @code{@@raisesections} command, and vice versa.
-
address@hidden Include files, and section levels
-You can use @code{@@lowersections} to include text written as an outer
-or standalone Texinfo file in another Texinfo file as an inner,
-included file (@pxref{Include Files}). Typical usage looks like this:
-
address@hidden
-@@lowersections
-@@include somefile.texi
-@@raisesections
address@hidden example
-
address@hidden (Without the @code{@@raisesections}, all the subsequent
-sections in the main file would also be lowered.)
-
-If the included file being lowered has an @code{@@top} node, you'll
-need to conditionalize its inclusion with a flag (@address@hidden@@set
-@@value}}).
-
-Another difficulty can arise with documents that use the (recommended)
-feature of @command{makeinfo} for implicitly determining node
-pointers. Since @command{makeinfo} must assume a hierarchically
-organized document to determine the pointers, you cannot just
-arbitrarily sprinkle @code{@@raisesections} and @code{@@lowersections}
-commands throughout the document. The final result has to have menus
-that take the raising and lowering into account. So, as a practical
-matter, you generally only want to raise or lower large chunks,
-usually in external files as shown above.
-
-Repeated use of the commands continues to raise or lower the
-hierarchical level a step at a time. An attempt to raise above
-`chapter' reproduces chapter commands; an attempt to lower below
-`subsubsection' reproduces subsubsection commands. Also, lowered
-subsubsections and raised chapters will not work with
address@hidden's feature of implicitly determining node pointers,
-since the menu structure cannot be represented correctly.
-
-Write each @code{@@raisesections} and @code{@@lowersections} command
-on a line of its own.
-
-
address@hidden Nodes
address@hidden Nodes
-
address@hidden are the primary segments of a Texinfo file. They do not
-in and of themselves impose a hierarchical or any other kind of
-structure on a file. Nodes contain @dfn{node pointers} that name
-other nodes, and can contain @dfn{menus} which are lists of nodes. In
-Info, the movement commands can carry you to a pointed-to node or to a
-node listed in a menu.
-
-Node 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}.
-
-Because node names are used in cross references, it is not desirable
-to casually change them once published. Such name changes invalidate
-references from other manuals, from mail archives, and so on.
address@hidden Xref Link Preservation}.
-
address@hidden
-* @t{@@node}:: Creating nodes, in detail.
-* @t{makeinfo} Pointer Creation:: Letting makeinfo determine node pointers.
-* @t{@@anchor}:: Defining arbitrary cross reference
targets.
-* Node Menu Illustration:: A diagram, and sample nodes and menus.
address@hidden menu
-
-
address@hidden @t{@@node}
address@hidden The @code{@@node} Command
-
address@hidden@c node
address@hidden node
address@hidden Node, defined
-
-A @dfn{node} is a stretch of text that begins at an @code{@@node}
-command and continues until the next @code{@@node} command. The
-definition of node is different from that for chapter or section. A
-chapter may contain sections and a section may contain subsections,
-but a node cannot contain subnodes: the text of a node continues only
-until the next @code{@@node} command in the file. A node usually
-contains only one chapter structuring command, immediately following
-the @code{@@node} line.
-
-To specify a node, write an @code{@@node} command at the beginning of
-a line, and follow it with up to four arguments, separated by commas,
-on the rest of the same line. The first argument is required; it is
-the name of this node (for details of node names, @pxref{Node Line
-Requirements}). The subsequent arguments are optional---they are the
-names of the `Next', `Previous', and `Up' pointers, in that order. We
-strongly recommend omitting them if your Texinfo document is
-hierarchically organized, as virtually all are (@address@hidden
-Pointer Creation}). You may insert spaces before or after each name
-on the @code{@@node} line if you wish; such spaces are ignored.
-
address@hidden address@hidden, in HTML output of nodes}
-Whether the node pointers are specified implicitly or explicitly, 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
address@hidden respectively. This allows people using web browsers to
-follow the navigation using (typically) @address@hidden, e.g.,
address@hidden for the `Next' node, from anywhere within the node.
-
-Usually, you write one of the chapter-structuring command lines
-immediately after an @code{@@node} line---for example, an
address@hidden@@section} or @code{@@subsection} line. @xref{Structuring
-Command Types}.
-
address@hidden uses both @code{@@node} names and chapter-structuring names in
-the output for cross references. For this reason, you must write
address@hidden@@node} lines in a Texinfo file that you intend to format for
-printing, even if you do not intend to format it for Info; and you
-must include a chapter-structuring command after a node for it to be a
-valid cross reference target (to @TeX{}). You can use @code{@@anchor}
-(@address@hidden@@anchor}}) to make cross references to an arbitrary
-position in a document.
-
-Cross references, such as the one at the end of this sentence, are
-made with @code{@@xref} and related commands; see @ref{Cross
-References}.
-
address@hidden
-* Node Names:: How to choose node and pointer 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.
-* @t{@@top} Command:: How to use the @code{@@top} command.
address@hidden menu
-
-
address@hidden Node Names
address@hidden Choosing Node and Pointer Names
-
address@hidden Node names, choosing
-The name of a node identifies the node. For all the details of node
-names, @pxref{Node Line Requirements}).
-
address@hidden Line address@hidden previous node name
-Here are some suggestions for node names:
-
address@hidden @bullet
address@hidden
-Try to pick node names that are informative but short.
-
-In the Info file, the file name, node name, and pointer names are all
-inserted on one line, which may run into the right edge of the window.
-(This does not cause a problem with Info, but is ugly.)
-
address@hidden
-Try to pick node names that differ from each other near the beginnings
-of their names. This way, it is easy to use automatic name completion in
-Info.
-
address@hidden
-By convention, node names are capitalized just as they would be for
-section or chapter titles. In this manual, initial and significant
-words are capitalized; others are not.
address@hidden itemize
-
-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
-(@address@hidden Pointer Creation}).
-
-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
-of the node that follows the present node in that menu and its
-`Previous' pointer contains the name of the node that precedes it in
-that menu. When a node's `Previous' node is the same as its `Up'
-node, both pointers name the same node.
-
-Usually, the first node of a Texinfo file is the `Top' node, and its
-`Up' pointer points to the @file{dir} file, which contains the main menu
-for all of Info.
-
-
address@hidden Writing a Node
address@hidden Writing an @code{@@node} Line
address@hidden Writing an @code{@@node} line
address@hidden @code{@@node} line writing
address@hidden Node line writing
-
-The easiest and preferred 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:
-
address@hidden
-@@node @var{node-name}
address@hidden example
-
-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 @address@hidden 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
address@hidden@@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.
-
-The template for a fully-written-out node line with `Next', `Previous',
-and `Up' pointers looks like this:
-
address@hidden
-@@node @var{node-name}, @var{next}, @var{previous}, @var{up}
address@hidden 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, as described above.
-
-It's, 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.
-
-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.
-
-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.
-
-
address@hidden Node Line Requirements
address@hidden @code{@@node} Line Requirements
-
address@hidden Node line requirements
address@hidden Restrictions on node names
-
-Names used with @code{@@node} have several requirements:
-
address@hidden @bullet
address@hidden
address@hidden Unique node names requirement
address@hidden Node names must be unique
-All the node names in a single Texinfo file must be unique.
-
-This means, for example, that if you end every chapter with a summary,
-you must name each summary node differently. You cannot just call
-them all ``Summary''. You may, however, duplicate the titles of
-chapters, sections, and the like. Thus you can end each chapter with
-a section called ``Summary'', so long as the node names for those
-sections are all different.
-
address@hidden
-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; @address@hidden
-Pointer Creation}.)
-
address@hidden
address@hidden Commands in node names
address@hidden @@-commands in node names
-Node names can contain @@-commands. The output is generally the
-natural result of the command; for example, using @code{@@address@hidden@}} in
a
-node name results in the @TeX{} logo being output, as it would be in
-normal text. Cross references should use @code{@@address@hidden@}} just as the
-node name does.
-
-For Info and HTML output, especially, it is necessary to expand
-commands to some sequence of characters; for instance,
address@hidden@@address@hidden@}} expands to the three letters @samp{TeX} in
the Info
-node name. (However, cross references to the node should not take the
-``shortcut'' of using @samp{TeX}; stick to the actual node name,
-commands and all.)
-
-Some commands do not make sense in node names; for instance,
-environments (e.g., @code{@@quotation}), commands that read a whole
-line as their argument (e.g., @code{@@sp}), and plenty of others.
-
-For the complete list of commands that are allowed, and their
-expansion for HTML identifiers and file names, @pxref{HTML Xref
-Command Expansion}. The expansions for Info are generally given with
-main the description of the command.
-
-Prior to the Texinfo 5 release in 2013, this feature was supported in
-an ad hoc way (the @option{--commands-in-node-names} option to
address@hidden). Now it is part of the language.
-
address@hidden
address@hidden Colon in node name
address@hidden Comma in node name
address@hidden Parentheses in node name
address@hidden Period in node name
address@hidden Characters, invalid in node name
address@hidden Invalid characters in node names
address@hidden Node names, invalid characters in
-Unfortunately, you cannot reliably use periods, commas, or colons
-within a node name; these confuse the Info reader. Also, a node name
-may not start with a left parenthesis preceding a right parenthesis,
-as in @code{(not)allowed}, since this syntax is used to specify an
-external manual. (Perhaps these limitations will be removed some day.)
-
-If you insist on using these characters in node names, accepting the
-resulting substandard Info output, in order not to confuse the Texinfo
-processors, you must still escape those characters, by using either
-special insertions (@pxref{Inserting a Comma}) or @code{@@asis}
-(@address@hidden@@asis}}). For example:
-
address@hidden
-@@node foo@@address@hidden::@}bar
address@hidden example
-
-As an example of avoiding the special characters, the following is a
-section title in this manual:
-
address@hidden
-@@address@hidden@@@@address@hidden, @@address@hidden@@@@address@hidden,
@@address@hidden@@@@address@hidden
address@hidden smallexample
-
address@hidden
-But the corresponding node name lacks the commas (and the @code{@@}'s,
-but that is historical):
-
address@hidden
-unnumberedsec appendixsec heading
address@hidden smallexample
-
address@hidden Case in node name
address@hidden
-Case is significant in node names.
-
address@hidden White space in node name
address@hidden Spaces in node name
-Spaces before and after names on the @samp{@@node} line are ignored.
-Multiple whitespace characters ``inside'' a name are collapsed to a
-single space. For example:
-
address@hidden
-@@node foo bar,
-@@node foo bar ,
-@@node foo bar,
-@@node foo bar ,
address@hidden example
-
address@hidden all define the same node, namely @samp{foo bar}. References
-to the node should all use that name, with no leading or trailing
-spaces a single internal space.
address@hidden itemize
-
-
address@hidden First Node
address@hidden The First Node
address@hidden Top node is first
address@hidden 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.
-
-Here is a description of the node pointers to be used in the Top node:
-
address@hidden @bullet
address@hidden
address@hidden Up node of Top node
address@hidden (dir) as Up node of Top node
-The Top node (which must be named @samp{top} or @samp{Top}) should have
-as its `Up' node the name of a node in another file, where there is a
-menu that leads to this file. Specify the file name in parentheses.
-
-Usually, all Info files are installed in one system-wide Info tree
-(often constructed from multiple directories). In this case, use
address@hidden(dir)} as the parent of the Top node; this specifies the
-top-level node in the @file{dir} file, which contains the main menu
-for the Info system as a whole.
-
address@hidden
address@hidden Next node of Top node
-The `Next' node of the Top node should be the first chapter in your
-document.
-
address@hidden itemize
-
address@hidden an Info File}, for more information about installing
-an Info file in the @file{info} directory.
-
-It is usually best to leave the pointers off entirely and let the
-tools implicitly define them, with this simple result:
-
address@hidden
-@@node Top
address@hidden example
-
-
address@hidden @t{@@top} Command
address@hidden The @code{@@top} Sectioning Command
-
address@hidden address@hidden old name
address@hidden address@hidden another old name
address@hidden top address@hidden yet another name
address@hidden top
-
-The @code{@@top} command is a special sectioning command that you
-should only use after an @samp{@@node Top} line at the beginning of a
-Texinfo file. The @code{@@top} command tells the @code{makeinfo}
-formatter which node is to be used as the root of the node tree
-(needed if your manual uses implicit node pointers).
-
-It produces the same sort of output as @code{@@unnumbered}
-(@address@hidden@@unnumbered @@appendix}}).
-
-The @code{@@top} node is conventionally wrapped in an
address@hidden@@ifnottex} conditional so that it will not appear in @TeX{}
-output (@pxref{Conditionals}).
-Thus, in practice, a Top node usually looks like this:
-
address@hidden
-@@ifnottex
-@@node Top
-@@top @var{your-manual-title}
-
address@hidden
-@@end ifnottex
address@hidden example
-
address@hidden@@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}).
-
-
address@hidden @t{makeinfo} Pointer Creation
address@hidden @code{makeinfo} Pointer Creation
-
address@hidden Creating pointers with @code{makeinfo}
address@hidden Pointer creation with @code{makeinfo}
address@hidden Automatic pointer creation with @code{makeinfo}
address@hidden 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:
-
address@hidden
-@@node My Node
address@hidden example
-
address@hidden
-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
address@hidden@@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.
address@hidden@t{@@top} Command}.
-
address@hidden Detail menu
address@hidden 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.
-
-
address@hidden @t{@@anchor}
address@hidden @code{@@anchor}: Defining Arbitrary Cross Reference Targets
-
address@hidden@c old name
address@hidden anchor
address@hidden Anchors
address@hidden Cross reference targets, arbitrary
address@hidden Targets for cross references, arbitrary
-
-An @dfn{anchor} is a position in your document, labeled so that cross
-references can refer to it, just as they can to nodes. You create an
-anchor with the @code{@@anchor} command, and give the label as a
-normal brace-delimited argument. For example:
-
address@hidden
-This marks the @@address@hidden@}spot.
address@hidden
-@@address@hidden,,the address@hidden
address@hidden example
-
address@hidden produces:
-
address@hidden
-This marks the spot.
address@hidden
-See [the spot], page 1.
address@hidden example
-
-As you can see, the @code{@@anchor} command itself produces no output.
-This example defines an anchor `x-spot' just before the word `spot'.
-You can refer to it later with an @code{@@xref} or other cross
-reference command, as shown (@pxref{Cross References}).
-
-It is best to put @code{@@anchor} commands just before the position you
-wish to refer to; that way, the reader's eye is led on to the correct
-text when they jump to the anchor. You can put the @code{@@anchor}
-command on a line by itself if that helps readability of the source.
-Whitespace (including newlines) is ignored after @code{@@anchor}.
-
-Anchor names and node names may not conflict. Anchors and nodes are
-given similar treatment in some ways; for example, the
address@hidden command takes either an anchor name or a node name as
-an argument. (@xref{Go to node,,, info, Info}.)
-
-Also like node names, anchor names cannot include some characters
-(@pxref{Node Line Requirements}).
-
address@hidden Nodes, deleting or renaming
-Because of this duality, when you delete or rename a node, it is
-usually a good idea to define an @code{@@anchor} with the old name.
-That way, any links to the old node, whether from other Texinfo
-manuals or general web pages, keep working. You can also do this with
-the @file{RENAMED_NODES_FILE} feature of @command{makeinfo}
-(@pxref{HTML Xref Link Preservation}). Both methods keep links
-on the web working; the only substantive difference is that defining
-anchors also makes the old node names available when reading the
-document in Info.
-
-
address@hidden Node Menu Illustration
address@hidden Node and Menu Illustration
-
-Here is a copy of the diagram shown earlier that illustrates a Texinfo
-file with three chapters, each of which contains two sections.
-
-The ``root'' is at the top of the diagram and the ``leaves'' are at
-the bottom. This is how such a diagram is drawn conventionally; it
-illustrates an upside-down tree. For this reason, the root node is
-called the `Top' node, and `Up' node pointers carry you closer to the
-root.
-
address@hidden
address@hidden
- Top
- |
- -------------------------------------
- | | |
- Chapter 1 Chapter 2 Chapter 3
- | | |
- -------- -------- --------
- | | | | | |
-Section Section Section Section Section Section
- 1.1 1.2 2.1 2.2 3.1 3.2
address@hidden group
address@hidden example
-
-Using explicit pointers (not recommended, but for shown for purposes
-of the example), the fully-written command to start address@hidden
-would be this:
-
address@hidden
address@hidden
-@@node Chapter 2, Chapter 3, Chapter 1, Top
-@@comment node-name, next, previous, up
address@hidden group
address@hidden example
-
address@hidden
-This @code{@@node} line says that the name of this node is
address@hidden'', the name of the `Next' node is ``Chapter 3'', the
-name of the `Previous' node is address@hidden'', 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
-(@address@hidden Pointer Creation}), but the pointer
-relationships still obtain.
-
address@hidden Note
-`Next' and `Previous' refer to nodes at the @emph{same hierarchical
-level} in the manual, not necessarily to the next node within the
-Texinfo file. In the Texinfo file, the subsequent node may be at a
-lower level---a section-level node most often follows a chapter-level
-node, for example. (The `Top' node contains the exception to this
-rule. Since the `Top' node is the only node at that level, `Next'
-refers to the first following node, which is almost always a chapter
-or chapter-level node.)
address@hidden quotation
-
-To go to Sections 2.1 and 2.2 using Info, you need a menu inside
-Chapter 2. (@xref{Menus}.) You would write the menu just before the
-beginning of Section 2.1, like this:
-
address@hidden
address@hidden
- @@menu
- * Sect. 2.1:: Description of this section.
- * Sect. 2.2:: Description.
- @@end menu
address@hidden group
address@hidden example
-
-Using explicit pointers, the node for Sect.@: 2.1 is written like this:
-
address@hidden
address@hidden
-@@node Sect. 2.1, Sect. 2.2, Chapter 2, Chapter 2
-@@comment node-name, next, previous, up
address@hidden group
address@hidden example
-
-In Info format, the `Next' and `Previous' pointers of a node usually
-lead to other nodes at the same level---from chapter to chapter or
-from section to section (sometimes, as shown, the `Previous' pointer
-points up); an `Up' pointer usually leads to a node at the level above
-(closer to the `Top' node); and a `Menu' leads to nodes at a level
-below (closer to `leaves'). (A cross reference can point to a node at
-any level; see @ref{Cross References}.)
-
-Usually, an @code{@@node} command and a chapter structuring command
-are conventionally used together, in that order, often followed by
-indexing commands. (As shown in the example above, you may follow the
address@hidden@@node} line with a comment line, e.g., to show which pointer is
-which if explicit pointers are used.) The Texinfo processors use this
-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
address@hidden@@chapter} line, and then by indexing lines. The manual uses
-implictly determined node pointers; therefore, nothing else is needed
-on the @code{@@node} line.
-
address@hidden
address@hidden
-@@node Ending a File
-@@chapter Ending a Texinfo File
-@@cindex Ending a Texinfo file
-@@cindex Texinfo file ending
-@@cindex File ending
address@hidden group
address@hidden 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
address@hidden@@node} line followed by a comment line, an @code{@@chapter}
-line, and then by indexing lines.
-
address@hidden
address@hidden
-@@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
address@hidden
address@hidden group
address@hidden example
-
-
address@hidden Menus
address@hidden Menus
address@hidden Menus
address@hidden menu
-
address@hidden contain pointers to subordinate nodes. In online output,
-you use menus to go to such nodes. Menus have no effect in printed
-manuals and do not appear in them.
-
-It's usually best if a node with a menu does not contain much text.
-If you find yourself with a lot of text before a menu, we generally
-recommend moving all but a couple of paragraphs into a new subnode.
-Otherwise, it is easy for readers to miss the menu.
-
address@hidden
-* Menu Location:: Menus go at the ends of nodes.
-* Writing a Menu:: What is a menu?
-* Menu Parts:: A menu entry has three parts.
-* Less Cluttered Menu Entry:: Two part menu entry.
-* Menu Example:: Two and three part menu entries.
-* Other Info Files:: How to refer to a different Info file.
address@hidden menu
-
-
address@hidden Menu Location
address@hidden Menu Location
address@hidden Menu location
address@hidden Location of menus
-
-There may be at most one menu in a node. A menu is conventionally
-located at the end of a node, without any regular text or additional
-commands between the @code{@@end menu} and the beginning of the next
-node.
-
address@hidden Info format, and menus
-This convention is useful, since a reader who uses the menu could
-easily miss any such text. Also, any such post-menu text will be
-considered part of the menu in Info output (which has no marker for
-the end of a menu). Thus, a line beginning with @samp{* } will likely
-be incorrectly handled.
-
address@hidden Hierarchical documents, and menus
-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 (@address@hidden Pointer Creation}) 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.
-
-In the past, we recommended using an @samp{@@heading} command within
-an @code{@@ifinfo} conditional instead of the normal sectioning
-commands after a very short node with a menu. This had the advantage
-of making the printed output look better, because there was no very
-short text between two headings on the page. But this also does not
-work with @command{makeinfo}'s implicit pointer creation, and it also
-makes the XML output incorrect, since it does not reflect the true
-document structure. So, we no longer recommend this.
-
-
address@hidden Writing a Menu
address@hidden Writing a Menu
address@hidden Writing a menu
address@hidden Menu writing
-
-A menu consists of an @code{@@menu} command on a line by itself
-followed by menu entry lines or menu comment lines and then by an
address@hidden@@end menu} command on a line by itself.
-
-A menu looks like this:
-
address@hidden
address@hidden
-@@menu
-Larger Units of Text
-
-* Files:: All about handling files.
-* Multiples: Buffers. Multiple buffers; editing
- several files at once.
-@@end menu
address@hidden group
address@hidden example
-
-In a menu, every line that begins with an @address@hidden }} is a @dfn{menu
-entry}. (Note the space after the asterisk.) A line that does not
-start with an @address@hidden }} may also appear in a menu. Such a line is
-not a menu entry but is a menu comment line that appears in the Info
-file. In the example above, the line @samp{Larger Units of Text} is a
-menu comment line; the two lines starting with @address@hidden }} are menu
address@hidden Spaces, in menus
-entries. Space characters in a menu are preserved as-is; this allows
-you to format the menu as you wish.
-
address@hidden address@hidden, in HTML output of menus}
-In the HTML output from @command{makeinfo}, the @code{accesskey}
-attribute is used with the values @address@hidden@samp{9} for the
-first nine entries. This allows people using web browsers to follow
-the first menu entries using (typically) @address@hidden, e.g.,
address@hidden for the first entry.
-
-
address@hidden Menu Parts
address@hidden The Parts of a Menu
address@hidden Parts of a menu
address@hidden Menu parts
address@hidden @code{@@menu} parts
-
-A menu entry has three parts, only the second of which is required:
-
address@hidden
address@hidden
-The menu entry name (optional).
-
address@hidden
-The name of the node (required).
-
address@hidden
-A description of the item (optional).
address@hidden enumerate
-
-The template for a generic menu entry looks like this (but see the
-next section for one more possibility):
-
address@hidden
-* @var{menu-entry-name}: @var{node-name}. @var{description}
address@hidden example
-
-Follow the menu entry name with a single colon and follow the node name
-with tab, comma, newline, or the two characters period and space
-(@samp{. }).
-
-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.
-
-The third part of a menu entry is a descriptive phrase or sentence.
-Menu entry names and node names are often short; the description
-explains to the reader what the node is about. A useful description
-complements the node name rather than repeats it. The description,
-which is optional, can spread over multiple lines; if it does, some
-authors prefer to indent the second line while others prefer to align
-it with the first (and all others). It's up to you. An empty line,
-or the next menu entry, ends a description.
-
-
address@hidden Less Cluttered Menu Entry
address@hidden Less Cluttered Menu Entry
address@hidden Two part menu entry
address@hidden Double-colon menu entries
address@hidden Menu entries with two colons
address@hidden Less cluttered menu entry
address@hidden Uncluttered menu entry
-
-When the menu entry name and node name are the same, you can write
-the name immediately after the asterisk and space at the beginning of
-the line and follow the name with two colons.
-
address@hidden 800
-For example, write
-
address@hidden
-* Name:: @var{description}
address@hidden example
-
address@hidden 800
address@hidden
-instead of
-
address@hidden
-* Name: Name. @var{description}
address@hidden example
-
-You should indeed use the node name for the menu entry name whenever
-possible, since it reduces visual clutter in the menu.
-
-
address@hidden Menu Example
address@hidden A Menu Example
address@hidden Menu example
address@hidden Example menu
-
-A menu looks like this in Texinfo:
-
address@hidden
address@hidden
-@@menu
-* menu entry name: Node name. A short description.
-* Node name:: This form is preferred.
-@@end menu
address@hidden group
address@hidden example
-
address@hidden 800
address@hidden
-This produces:
-
address@hidden
address@hidden
-* menu:
-
-* menu entry name: Node name. A short description.
-* Node name:: This form is preferred.
address@hidden group
address@hidden example
-
address@hidden 700
-Here is an example as you might see it in a Texinfo file:
-
address@hidden
address@hidden
-@@menu
-Larger Units of Text
-
-* Files:: All about handling files.
-* Multiples: Buffers. Multiple buffers; editing
- several files at once.
-@@end menu
address@hidden group
address@hidden example
-
address@hidden 800
address@hidden
-This produces:
-
address@hidden
address@hidden
-* menu:
-Larger Units of Text
-
-* Files:: All about handling files.
-* Multiples: Buffers. Multiple buffers; editing
- several files at once.
address@hidden group
address@hidden example
-
-In this example, the menu has two entries. @samp{Files} is both a menu
-entry name and the name of the node referred to by that name.
address@hidden is the menu entry name; it refers to the node named
address@hidden The line @samp{Larger Units of Text} is a comment; it
-appears in the menu, but is not an entry.
-
-Since no file name is specified with either @samp{Files} or
address@hidden, they must be the names of nodes in the same Info file
-(@pxref{Other Info Files, , Referring to Other Info Files}).
-
address@hidden Other Info Files
address@hidden Referring to Other Info Files
address@hidden Referring to other Info files
address@hidden Nodes in other Info files
address@hidden Other Info files' nodes
address@hidden Going to other Info files' nodes
address@hidden Info; other files' nodes
-
-You can create a menu entry that enables a reader in Info to go to a
-node in another Info file by writing the file name in parentheses just
-before the node name. Some examples:
-
address@hidden
address@hidden
-@@menu
-* @var{first-entry-name}:(@var{filename})@var{nodename}. @var{description}
-* (@var{filename})@var{second-node}:: @var{description}
-@@end menu
address@hidden group
address@hidden example
-
-For example, to refer directly to the @samp{Outlining} and
address@hidden nodes in the @cite{Emacs Manual}, you could write a
-menu like this:
-
address@hidden
address@hidden
-@@menu
-* Outlining: (emacs)Outline Mode. The major mode for
- editing outlines.
-* (emacs)Rebinding:: How to redefine the
- meaning of a key.
-@@end menu
address@hidden group
address@hidden example
-
-If you do not list the node name, but only name the file, then Info
-presumes that you are referring to the `Top' node. Examples:
-
address@hidden
address@hidden
-* Info: (info). Documentation browsing system.
-* (emacs):: The extensible, self-documenting
- text editor.
address@hidden group
address@hidden example
-
-The GNU Emacs Texinfo mode menu updating commands only work with nodes
-within the current buffer, so you cannot use them to create menus that
-refer to other files. You must write such menus by hand.
-
-
address@hidden Cross References
address@hidden Cross References
address@hidden Making cross references
address@hidden Cross references
address@hidden References
-
address@hidden references} are used to refer the reader to other parts of the
-same or different Texinfo files. In Texinfo, nodes and anchors are the
-places to which cross references can refer.
-
address@hidden
-* References:: What cross references are for.
-* Cross Reference Commands:: A summary of the different commands.
-* Cross Reference Parts:: A cross reference has several parts.
-* @t{@@xref}:: Begin a reference with `See' @dots{}
-* Top Node Naming:: How to refer to the beginning of another file.
-* @t{@@ref}:: A reference for the last part of a
sentence.
-* @t{@@pxref}:: How to write a parenthetical cross
reference.
-* @t{@@inforef}:: How to refer to an Info-only file.
-* @t{@@url}:: How to refer to a uniform resource
locator.
-* @t{@@cite}:: How to refer to books not in the Info
system.
address@hidden menu
-
address@hidden References
address@hidden What References Are For
-
-Often, but not always, a printed document should be designed so that
-it can be read sequentially. People tire of flipping back and forth
-to find information that should be presented to them as they need
-it.
-
-However, in any document, some information will be too detailed for
-the current context, or incidental to it; use cross references to
-provide access to such information. Also, an 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
-have read.
-
-In a printed manual, a cross reference results in a page reference,
-unless it is to another manual altogether, in which case the cross
-reference names that manual.
-
-In Info, a cross reference results in an entry that you can follow
-using the Info @samp{f} command. (@xref{Help-Xref,, Following
-cross-references, info, Info}.)
-
-In HTML, a cross reference results in an hyperlink.
-
-The various cross reference commands use nodes (or anchors,
address@hidden@t{@@anchor}}) to define cross reference locations. This is
-evident in Info and HTML, in which a cross reference takes you to the
-specified location.
-
address@hidden also needs nodes to define cross reference locations, but the
-action is less obvious. When @TeX{} generates a DVI file, it records
-each node's page number and uses the page numbers in making
-references. Thus, even if you are writing a manual that will only be
-printed, and not used online, you must nonetheless write @code{@@node}
-lines in order to name the places to which you make cross references.
-
address@hidden 800
address@hidden Cross Reference Commands
address@hidden Different Cross Reference Commands
address@hidden Different cross reference commands
-
-There are four different cross reference commands:
-
address@hidden @code
address@hidden @@xref
-Used to start a sentence in the printed manual and in HTML with
address@hidden @dots{}'} or an Info cross reference saying @samp{*Note
address@hidden: @var{node}.}.
-
address@hidden @@ref
-Used within or, more often, at the end of a sentence; produces just
-the reference in the printed manual and in HTML without the preceding
-`See' (same as @code{@@xref} for Info).
-
address@hidden @@pxref
-Used within parentheses, at the end of a sentence, or otherwise before
-punctuation, to make a reference. Its output starts with a lowercase
-`see' in the printed manual and in HTML, and a lowercase @samp{*note}
-in Info. (@samp{p} is for `parenthesis'.)
-
address@hidden @@inforef
-Used to make a reference to an Info file for which there is no printed
-manual.
address@hidden table
-
address@hidden
-The @code{@@cite} command is used to make references to books and
-manuals for which there is no corresponding Info file and, therefore,
-no node to which to point. @address@hidden@@cite}}.
-
-
address@hidden Cross Reference Parts
address@hidden Parts of a Cross Reference
address@hidden Cross reference parts
address@hidden Parts of a cross reference
-
-A cross reference command to a node requires only one argument, which
-is the name of the node to which it refers. But a cross reference
-command may contain up to four additional arguments. By using these
-arguments, you can provide a cross reference name, a topic description
-or section title for the printed output, the name of a different
-manual file, and the name of a different printed manual. To refer
-to another manual as a whole, the manual file and/or the name of the
-printed manual are the only required arguments (@pxref{Top Node
-Naming}).
-
-Here is a simple cross reference example:
-
address@hidden
-@@address@hidden address@hidden
address@hidden example
-
address@hidden
-which produces
-
address@hidden
-*Note Node name::.
address@hidden example
-
address@hidden
-in Info and
-
address@hidden
-See Section @var{nnn} [Node name], page @var{ppp}.
address@hidden quotation
-
address@hidden
-in a printed manual.
-
address@hidden 700
-Here is an example of a full five-part cross reference:
-
address@hidden
address@hidden
-@@address@hidden name, Cross Reference Name, Particular Topic,
-info-file-name, A Printed address@hidden, for details.
address@hidden group
address@hidden example
-
address@hidden
-which produces
-
address@hidden
-*Note Cross Reference Name: (info-file-name)Node name,
-for details.
address@hidden example
-
address@hidden
-in Info and
-
address@hidden
-See section ``Particular Topic'' in @i{A Printed Manual}, for details.
address@hidden quotation
-
address@hidden
-in a printed book.
-
-The five possible arguments for a cross reference are:
-
address@hidden
address@hidden
-The node or anchor name (required, except for reference to whole
-manuals). This is the location to which the cross reference takes
-you. In a printed document, the location of the node provides the
-page reference only for references within the same document.
-
address@hidden
-The cross reference name. If you include this argument, it becomes
-the first part of the cross reference. It is usually omitted; then
-the topic description (third argument) is used if it was specified;
-if that was omitted as well, the node name is used.
-
address@hidden
-A topic description or section name. Often, this is the title of the
-section. This is used as the name of the reference in the printed
-manual. If omitted, the node name is used.
-
address@hidden
-The name of the manual file in which the reference is located, if it is
-different from the current file. This name is used both for Info and
-HTML.
-
address@hidden
-The name of a printed manual from a different Texinfo file.
address@hidden enumerate
-
-The template for a full five argument cross reference looks like
-this:
-
address@hidden
address@hidden
-@@address@hidden@var{node-name}, @var{cross-reference-name},
@var{title-or-topic},
address@hidden, @address@hidden
address@hidden group
address@hidden example
-
-Cross references with one, two, three, four, and five arguments are
-described separately following the description of @code{@@xref}.
-
-Write a node name in a cross reference in exactly the same way as in
-the @code{@@node} line, including the same capitalization; otherwise, the
-formatters may not find the reference.
-
-
address@hidden @t{@@xref}
address@hidden @code{@@xref}
-
address@hidden@c old name
address@hidden xref
address@hidden Cross references using @code{@@xref}
address@hidden References using @code{@@xref}
-
-The @code{@@xref} command generates a cross reference for the
-beginning of a sentence. The Info formatting commands convert it into
-an Info cross reference, which the Info @samp{f} command can use to
-bring you directly to another node. The @TeX{} typesetting commands
-convert it into a page reference, or a reference to another book or
-manual. In the HTML output format the cross reference is output
-as a hyperlink.
-
address@hidden
-* Reference Syntax:: What a reference looks like and requires.
-* One Argument:: @code{@@xref} with one argument.
-* Two Arguments:: @code{@@xref} with two arguments.
-* Three Arguments:: @code{@@xref} with three arguments.
-* Four and Five Arguments:: @code{@@xref} with four and five arguments.
address@hidden menu
-
address@hidden Reference Syntax
address@hidden What a Reference Looks Like and Requires
-
-Most often, an Info cross reference looks like this:
-
address@hidden
-*Note @var{node-name}::.
address@hidden example
-
address@hidden
-or like this
-
address@hidden
-*Note @var{cross-reference-name}: @var{node-name}.
address@hidden example
-
address@hidden
-In @TeX{}, a cross reference looks like this:
-
address@hidden
-See Section @var{section-number} address@hidden, page @var{page}.
address@hidden quotation
-
address@hidden
-or like this
-
address@hidden
-See Section @var{section-number} address@hidden, page @var{page}.
address@hidden quotation
-
-The @code{@@xref} command does not generate a period or comma to end
-the cross reference automatically. You must write that period or
-comma yourself; otherwise, Info will not recognize the end of the
-reference. (The @code{@@pxref} command works differently;
address@hidden@t{@@pxref}}.)
-
address@hidden Caution
-A period or comma @emph{must} follow the closing brace of an
address@hidden@@xref}. It is required to terminate the cross reference. This
-period or comma will appear in the output.
address@hidden quotation
-
address@hidden@@xref} must refer to a node by name. Use @code{@@node} to
-define the node (@pxref{Writing a Node}), or @code{@@anchor}
-(@address@hidden@@anchor}}).
-
address@hidden@@xref} is followed by several arguments inside braces,
-separated by commas. Whitespace before and after these commas is
-ignored.
-
-A cross reference to a node within the current file requires only the
-name of a node; but it may contain up to four additional arguments.
-Each of these variations produces a cross reference that looks
-somewhat different. A cross reference to another manual as a whole
-only requires the fourth or fifth argument.
-
address@hidden Note
-Commas separate arguments in a cross reference, so you must not
-include a comma in the title or any other part lest the formatters
-mistake them for separators. @code{@@address@hidden@}} may be used to
-protect such commas (@pxref{Inserting a Comma}).
address@hidden quotation
-
-
address@hidden One Argument
address@hidden @code{@@xref} with One Argument
address@hidden One-argument form of cross references
-
-The simplest form of @code{@@xref} takes one argument, the name of
-another node in the same Texinfo file. The Info formatters produce
-output that the Info readers can use to jump to the reference; @TeX{}
-produces output that specifies the page and section number for you;
-the HTML output is a normal hyperlink.
-
address@hidden 700
address@hidden
-For example,
-
address@hidden
-@@address@hidden address@hidden
address@hidden example
-
address@hidden
-produces
-
address@hidden
-*Note Tropical Storms::.
address@hidden example
-
address@hidden
-in Info and
-
address@hidden
-See Section 3.1 [Tropical Storms], page 24.
address@hidden quotation
-
address@hidden
-in a printed manual.
-(Note that in the preceding example the closing brace to
address@hidden@@xref}'s argument is followed by a period.)
-
-You can write a clause after the cross reference, like this:
-
address@hidden
-@@address@hidden address@hidden, for more info.
address@hidden example
-
address@hidden
-which produces
-
address@hidden
-*Note Tropical Storms::, for more info.
address@hidden example
-
address@hidden
-in Info and
-
address@hidden
-See Section 3.1 [Tropical Storms], page 24, for more info.
address@hidden quotation
-
-
address@hidden
-in a printed manual. Note that in the preceding example the closing
-brace to @code{@@xref} is followed by a comma, then the additional
-text. It's a common mistake to follow an @code{@@xref} command with a
-space, but this is never correct.
-
-
address@hidden Two Arguments
address@hidden @code{@@xref} with Two Arguments
address@hidden Two-argument form of cross references
-
-With two arguments, the second is used as the name of the cross
-reference, while the first is still the name of the node to which the
-cross reference points.
-
address@hidden 750
address@hidden
-The template is like this:
-
address@hidden
-@@address@hidden@var{node-name}, @address@hidden
address@hidden example
-
address@hidden 700
address@hidden
-For example,
-
address@hidden
-@@address@hidden Effects, address@hidden
address@hidden example
-
address@hidden
-produces:
-
address@hidden
-*Note Lightning: Electrical Effects.
address@hidden example
-
address@hidden
-in Info and
-
address@hidden
-See Section 5.2 [Electrical Effects], page 57.
address@hidden quotation
-
address@hidden
-in a printed manual.
-(Note that in the preceding example the closing brace is followed by a
-period; and that the node name is printed, not the cross reference name.)
-
-You can write a clause after the cross reference, like this:
-
address@hidden
-@@address@hidden Effects, address@hidden, for more info.
address@hidden example
-
address@hidden
-which produces
-
address@hidden
-*Note Lightning: Electrical Effects, for more info.
address@hidden example
-
address@hidden
-in Info and
-
address@hidden
-See Section 5.2 [Electrical Effects], page 57, for more info.
address@hidden quotation
-
address@hidden
-in a printed manual.
-(Note that in the preceding example the closing brace is followed by a
-comma, and then by the clause, which is followed by a period.)
-
-
address@hidden Three Arguments
address@hidden @code{@@xref} with Three Arguments
address@hidden Three-argument form of cross references
-
-A third argument replaces the node name in the @TeX{} output. The third
-argument should be the name of the section in the printed output, or
-else state the topic discussed by that section. Often, you will want to
-use initial uppercase letters so it will be easier to read when the
-reference is printed. Use a third argument when the node name is
-unsuitable because of syntax or meaning.
-
-The third argument to the xref commands must observe the same
-restrictions as node names described in @ref{Node Line Requirements}.
-The issue you're most likely to run into is that commas, periods, and
-colons cannot be used.
-
-Also, remember to write a comma or period after the closing brace of an
address@hidden@@xref} to terminate the cross reference. In the following
-examples, a clause follows a terminating comma.
-
address@hidden 750
address@hidden
-The template is like this:
-
address@hidden
address@hidden
-@@address@hidden@var{node-name}, @var{cross-reference-name}, @address@hidden
address@hidden group
address@hidden example
-
address@hidden 700
address@hidden
-For example,
-
address@hidden
address@hidden
-@@address@hidden Effects, Lightning, Thunder and address@hidden,
-for details.
address@hidden group
address@hidden example
-
address@hidden
-produces
-
address@hidden
-*Note Lightning: Electrical Effects, for details.
address@hidden example
-
address@hidden
-in Info and
-
address@hidden
-See Section 5.2 [Thunder and Lightning], page 57, for details.
address@hidden quotation
-
address@hidden
-in a printed manual.
-
-If a third argument is given and the second one is empty, then the
-third argument serves for both. (Note how two commas, side by side, mark
-the empty second argument.)
-
address@hidden
address@hidden
-@@address@hidden Effects, , Thunder and address@hidden,
-for details.
address@hidden group
address@hidden example
-
address@hidden
-produces
-
address@hidden
-*Note Thunder and Lightning: Electrical Effects, for details.
address@hidden example
-
address@hidden
-in Info and
-
address@hidden
-See Section 5.2 [Thunder and Lightning], page 57, for details.
address@hidden quotation
-
address@hidden
-in a printed manual.
-
-As a practical matter, it is often best to write cross references with
-just the first argument if the node name and the section title are the
-same (or nearly so), and with the first and third arguments only if the
-node name and title are different.
-
address@hidden xrefautomaticsectiontitle
-If you want the section title to be used by default instead of
-node names in cross references (an explicitly specified third argument
-still takes precedence), Texinfo can do this automatically:
-
address@hidden
-@@xrefautomaticsectiontitle on
address@hidden example
-
-Typically this line would be given near the beginning of the document
-and used for the whole thing. 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.
-
-
address@hidden Four and Five Arguments
address@hidden @code{@@xref} with Four and Five Arguments
address@hidden Four- and five argument forms of cross references
-
-In a cross reference, a fourth argument specifies the name of another
-Info file, different from the file in which the reference appears, and
-a fifth argument specifies its title as a printed manual.
-
-Remember that a comma or period must follow the closing brace of an
address@hidden@@xref} command to terminate the cross reference.
-
address@hidden 800
address@hidden
-The full template is:
-
address@hidden
address@hidden
-@@address@hidden@var{node-name}, @var{cross-reference-name},
@var{title-or-topic},
address@hidden, @address@hidden
address@hidden group
address@hidden example
-
address@hidden 700
address@hidden
-For example,
-
address@hidden
-@@address@hidden Effects, Lightning, Thunder and Lightning,
-weather, An Introduction to address@hidden
address@hidden example
-
address@hidden
-produces this output in Info:
-
address@hidden
-*Note Lightning: (weather)Electrical Effects.
address@hidden example
-
address@hidden
-As you can see, the name of the Info file is enclosed in parentheses
-and precedes the name of the node.
-
address@hidden
-In a printed manual, the reference looks like this:
-
address@hidden
-See section ``Thunder and Lightning'' in @cite{An Introduction to
-Meteorology}.
address@hidden quotation
-
address@hidden
-The title of the printed manual is typeset like @code{@@cite}; and the
-reference lacks a page number since @TeX{} cannot know to which page a
-reference refers when that reference is to another manual.
-
-Next case: often, you will leave out the second argument when you use
-the long version of @code{@@xref}. In this case, the third argument,
-the topic description, will be used as the cross reference name in
-Info. For example,
-
address@hidden
-@@address@hidden Effects, , Thunder and Lightning,
-weather, An Introduction to address@hidden
address@hidden example
-
address@hidden
-produces
-
address@hidden
address@hidden
-*Note Thunder and Lightning: (weather)Electrical Effects.
address@hidden group
address@hidden example
-
address@hidden
-in Info and
-
address@hidden
-See section ``Thunder and Lightning'' in @cite{An Introduction to
-Meteorology}.
address@hidden quotation
-
address@hidden
-in a printed manual.
-
-Next case: If the node name and the section title are the same in the
-other manual, you may also leave out the section title. In this case,
-the node name is used in both instances. For example,
-
address@hidden
-@@address@hidden Effects,,,
-weather, An Introduction to address@hidden
address@hidden example
-
address@hidden
-produces
-
address@hidden
address@hidden
-*Note (weather)Electrical Effects::.
address@hidden group
address@hidden example
-
address@hidden
-in Info and
-
address@hidden
-See section ``Electrical Effects'' in @cite{An Introduction to
-Meteorology}.
address@hidden quotation
-
address@hidden
-in a printed manual.
-
-A very unusual case: you may want to refer to another manual file that
-is within a single printed manual---when multiple Texinfo files are
-incorporated into the same @TeX{} run but can create separate Info or
-HTML output files. In this case, you need to specify only the fourth
-argument, and not the fifth.
-
-Finally, it's also allowed to leave out all the arguments
address@hidden the fourth and fifth, to refer to another manual as a
-whole. See the next section.
-
-
address@hidden Top Node Naming
address@hidden Naming a `Top' Node
address@hidden Naming a `Top' Node in references
address@hidden `Top' node naming for references
-
address@hidden Manual, referring to as a whole
address@hidden Referring to an entire manual
-
-Ordinarily, you must always name a node in a cross reference.
-However, it's not unusual to want to refer to another manual as a
-whole, rather than a particular section within it. In this case,
-giving any section name is an unnecessary distraction.
-
-So, with cross references to other manuals (@pxref{Four and Five
-Arguments}), if the first argument is either @samp{Top} (capitalized
-just that way) or omitted entirely, and the third argument is omitted,
-the printed output includes no node or section name. (The Info output
-includes @samp{Top} if it was given.) For example,
-
address@hidden
-@@address@hidden,,, make, The GNU Make address@hidden
address@hidden example
-
address@hidden produces
-
address@hidden
address@hidden
-*Note (make)::Top.
address@hidden group
address@hidden example
-
address@hidden and
-
address@hidden
-See @cite{The GNU Make Manual}.
address@hidden quotation
-
address@hidden
-Info readers will go to the Top node of the manual whether
-or not the `Top' node is explicitly specified.
-
-It's also possible (and is historical practice) to refer to a whole
-manual by specifying the `Top' node and an appropriate entry for the
-third argument to the @code{@@xref} command. Using this idiom, to
-make a cross reference to @cite{The GNU Make Manual}, you would write:
-
address@hidden
-@@address@hidden,, Overview, make, The GNU Make address@hidden
address@hidden example
-
address@hidden
-which produces
-
address@hidden
-*Note Overview: (make)Top.
address@hidden example
-
address@hidden
-in Info and
-
address@hidden
-See section ``Overview'' in @cite{The GNU Make Manual}.
address@hidden quotation
-
address@hidden
-in a printed manual.
-
-In this example, @samp{Top} is the name of the first node, and
address@hidden is the name of the first section of the manual. There
-is no widely-used convention for naming the first section in a printed
-manual, this is just what the Make manual happens to use. This
-arbitrariness of the first name is a principal reason why omitting the
-third argument in whole-manual cross references is preferable.
-
-
address@hidden @t{@@ref}
address@hidden @code{@@ref}
-
address@hidden@c old name
address@hidden ref
address@hidden Cross references using @code{@@ref}
address@hidden References using @code{@@ref}
-
address@hidden@@ref} is nearly the same as @code{@@xref} except that it does
-not generate a `See' in the printed output, just the reference itself.
-This makes it useful as the last part of a sentence.
-
address@hidden For example,
-
address@hidden Hurricanes
address@hidden
-For more information, @@address@hidden@}, and @@address@hidden@}.
address@hidden example
-
address@hidden
-produces in Info:
-
address@hidden
-For more information, *note This::, and *note That::.
address@hidden example
-
address@hidden
-and in printed output:
-
address@hidden
-For more information, see Section 1.1 [This], page 1,
-and Section 1.2 [That], page 2.
address@hidden quotation
-
-The @code{@@ref} command can tempt writers to express themselves in a
-manner that is suitable for a printed manual but looks awkward in the
-Info format. Bear in mind that your audience could be using both the
-printed and the Info format. For example:
-
address@hidden Sea surges
address@hidden
-Sea surges are described in @@address@hidden@}.
address@hidden example
-
address@hidden
-looks ok in the printed output:
-
address@hidden
-Sea surges are described in Section 6.7 [Hurricanes], page 72.
address@hidden quotation
-
address@hidden
-but is awkward to read in Info, ``note'' being a verb:
-
address@hidden
-Sea surges are described in *note Hurricanes::.
address@hidden example
-
-You should write a period or comma immediately after an @code{@@ref}
-command with two or more arguments. If there is no such following
-punctuation, @command{makeinfo} will generate a (grammatically
-incorrect) period in the Info output; otherwise, the cross reference
-would fail completely, due to the current syntax of Info format.
-
-In general, it is best to use @code{@@ref} only when you need some
-word other than ``see'' to precede the reference. When ``see'' (or
-``See'') is ok, @code{@@xref} and @code{@@pxref} are preferable.
-
-
address@hidden @t{@@pxref}
address@hidden @code{@@pxref}
-
address@hidden@c old name
address@hidden pxref
address@hidden Cross references using @code{@@pxref}
address@hidden References using @code{@@pxref}
-
-The parenthetical reference command, @code{@@pxref}, is nearly the
-same as @code{@@xref}, but it is best used at the end of a sentence or
-before a closing parenthesis. The command differs from @code{@@xref}
-in two ways:
-
address@hidden
address@hidden
address@hidden typesets the reference for the printed manual with a lowercase
-`see' rather than an uppercase `See'.
-
address@hidden
-The Info formatting commands automatically end the reference with a
-closing colon or period, if necessary.
address@hidden enumerate
-
address@hidden@@pxref} is designed so that the output looks right and works
-right at the end of a sentence or parenthetical phrase, both in
-printed output and in an Info file. In a printed manual, a closing
-comma or period should not follow a cross reference within
-parentheses; such punctuation is wrong. But in an Info file, suitable
-closing punctuation must follow the cross reference so Info can
-recognize its end. @code{@@pxref} spares you the need to use
-complicated methods to put a terminator into one form of the output
-and not the other.
-
address@hidden
-With one argument, a parenthetical cross reference looks like this:
-
address@hidden Flooding
address@hidden
address@hidden storms cause flooding (@@address@hidden@}) @dots{}
address@hidden example
-
address@hidden 800
address@hidden
-which produces
-
address@hidden
address@hidden
address@hidden storms cause flooding (*note Hurricanes::) @dots{}
address@hidden group
address@hidden example
-
address@hidden
-in Info and
-
address@hidden
address@hidden storms cause flooding (see Section 6.7 [Hurricanes], page 72)
@dots{}
address@hidden quotation
-
address@hidden
-in a printed manual.
-
-With two arguments, a parenthetical cross reference has this template:
-
address@hidden
address@hidden (@@address@hidden@var{node-name}, @address@hidden) @dots{}
address@hidden example
-
address@hidden
-which produces
-
address@hidden
address@hidden (*note @var{cross-reference-name}: @var{node-name}.) @dots{}
address@hidden example
-
address@hidden
-in Info and
-
address@hidden
address@hidden (see Section @var{nnn} address@hidden, page @var{ppp}) @dots{}
address@hidden quotation
-
address@hidden
-in a printed manual.
-
address@hidden@@pxref} can be used with up to five arguments, just like
address@hidden@@xref} (@address@hidden@@xref}}).
-
-In past versions of Texinfo, it was not allowed to write punctuation
-after an @code{@@pxref}, so it could be used @emph{only} before a
-right parenthesis. This is no longer the case, so now it can be used
-(for example) at the end of a sentence, where a lowercase ``see''
-works best. For instance:
-
address@hidden
address@hidden For more information, @@address@hidden@}.
address@hidden example
-
address@hidden
-which outputs (in Info):
-
address@hidden
address@hidden For more information, *note More::.
address@hidden example
-
address@hidden
-In general, @code{@@pxref} should only be followed by a comma, period,
-or right parenthesis; in other cases, @command{makeinfo} has to insert
-a period to make the cross reference work correctly in Info, and that
-period looks wrong.
-
-As a matter of style, @code{@@pxref} is best used at the ends of
-sentences. Although it technically works in the middle of a sentence,
-that location breaks up the flow of reading.
-
-
address@hidden @t{@@inforef}
address@hidden @code{@@inforef}: Cross References to Info-only Material
-
address@hidden@c old name
address@hidden inforef
address@hidden Cross references using @code{@@inforef}
address@hidden References using @code{@@inforef}
-
address@hidden@@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.
-
-The command takes either two or three arguments, in the following
-order:
-
address@hidden
address@hidden
-The node name.
-
address@hidden
-The cross reference name (optional).
-
address@hidden
-The Info file name.
address@hidden enumerate
-
address@hidden
-Separate the arguments with commas, as with @code{@@xref}. Also, you
-must terminate the reference with a comma or period after the
address@hidden@}}, as you do with @code{@@xref}.
-
address@hidden
-The template is:
-
address@hidden
-@@address@hidden@var{node-name}, @var{cross-reference-name}, @address@hidden,
address@hidden example
-
address@hidden 800
address@hidden
-For example,
-
address@hidden
address@hidden
-@@address@hidden, Advanced Info commands, address@hidden,
-for more information.
address@hidden group
address@hidden example
-
address@hidden 800
address@hidden
-produces (in Info):
-
address@hidden
address@hidden
-*Note Advanced Info commands: (info)Advanced,
-for more information.
address@hidden group
address@hidden example
-
address@hidden 800
address@hidden
-and (in the printed output):
-
address@hidden
-See Info file @file{info}, node @samp{Advanced}, for more information.
address@hidden quotation
-
-(This particular example is not realistic, since the Info manual is
-written in Texinfo, so all formats are available. In fact, we don't
-know of any extant Info-only manuals.)
-
-The converse of @code{@@inforef} is @code{@@cite}, which is used to
-refer to printed works for which no Info form exists.
address@hidden@t{@@cite}}.
-
-
address@hidden @t{@@url}
address@hidden @code{@@url}, @code{@@address@hidden@var{url}[, @var{text}][,
@address@hidden
-
address@hidden@c old name
address@hidden uref
address@hidden Uniform resource locator, referring to
address@hidden URL, referring to
-
address@hidden @code{href}, producing HTML
address@hidden@@uref} produces a reference to a uniform resource locator (url).
-It takes one mandatory argument, the url, and two optional arguments
-which control the text that is displayed. In HTML output, @code{@@uref}
-produces a link you can follow.
-
address@hidden @code{@@url} is a synonym for @code{@@uref}.
-(Originally, @code{@@url} had the meaning of @code{@@indicateurl}
-(@address@hidden@@indicateurl}}), but in practice it was almost always
-misused. So we've changed the meaning.)
-
-The second argument, if specified, is the text to display (the default
-is the url itself); in Info and DVI output, but not in HTML output, the
-url is output in addition to this text.
-
address@hidden Man page, reference to
-The third argument, if specified, is the text to display, but in this
-case the url is not output in any format. This is useful when the
-text is already sufficiently referential, as in a man page. If the
-third argument is given, the second argument is ignored.
-
address@hidden Line breaking, and urls
address@hidden Breakpoints within urls
address@hidden allows line breaking within urls at only a few characters
-(which are special in urls): @samp{&}, @samp{.}, @samp{#}, @samp{?},
-and @samp{/} (but not between @samp{/} characters). A tiny amount of
-stretchable space is also inserted around these characters to help
-with line breaking. For HTML output, modern browsers will also do
-line breaking within displayed urls. If you need to allow breaks at
-other characters you can insert @code{@@/} as needed (@pxref{Line
-Breaks}).
-
address@hidden urefbreakstyle
-By default, any such breaks at special characters will occur after the
-character. Some people prefer such breaks to happen after the special
-character. This can be controlled with the @code{@@urefbreakstyle}
-command (this command has effect only in @TeX{}):
-
-Write this command at the
-beginning of a line with a single word as an argument, one of the
-following:
-
address@hidden address@hidden, value for @code{@@urefbreakstyle}}
address@hidden address@hidden, value for @code{@@urefbreakstyle}}
address@hidden address@hidden, value for @code{@@urefbreakstyle}}
address@hidden @samp
address@hidden after
-(the default) Potentially break after the special characters.
address@hidden before
-Potentially break before the special characters.
address@hidden none
-Do not consider breaking at the special characters; any potential
-breaks must be manually inserted.
address@hidden table
-
-Here is an example of the simple one argument form, where the url is
-both the target and the text of the link:
-
address@hidden
-The official GNU ftp site is @@address@hidden://ftp.gnu.org/address@hidden
address@hidden example
-
address@hidden produces:
address@hidden
-The official GNU ftp site is @uref{http://ftp.gnu.org/gnu}.
address@hidden display
-
-
-An example of the two-argument form:
address@hidden
-The official @@address@hidden://ftp.gnu.org/gnu, GNU ftp address@hidden
-holds programs and texts.
address@hidden example
-
address@hidden produces:
address@hidden
-The official @uref{http://ftp.gnu.org/gnu, GNU ftp site}
-holds programs and texts.
address@hidden display
-
address@hidden that is, the Info output is this:
address@hidden
-The official GNU ftp site (http://ftp.gnu.org/gnu)
-holds programs and texts.
address@hidden example
-
address@hidden and the HTML output is this:
address@hidden
-The official <a href="http://ftp.gnu.org/gnu";>GNU ftp site</a>
-holds programs and texts.
address@hidden example
-
-
-An example of the three-argument form:
address@hidden
-The @@address@hidden/man.cgi/1/ls,,address@hidden program @dots{}
address@hidden example
-
address@hidden produces:
address@hidden
-The @uref{/man.cgi/1/ls,,ls} program @dots{}
address@hidden display
-
address@hidden but with HTML:
address@hidden
-The <a href="/man.cgi/1/ls">ls</a> program @dots{}
address@hidden example
-
-Some people prefer to display urls in the unambiguous format:
-
address@hidden
-<URL:http://@var{host}/@var{path}>
address@hidden display
-
address@hidden
address@hidden @code{<URL...>} convention, not used
-You can use this form in the input file if you wish. We feel it's not
-necessary to include the @samp{<URL:} and @samp{>} in the output,
-since any software that tries to detect urls in text already has to
-detect them without the @samp{<URL:} to be useful.
-
-To merely indicate a url without creating a link people can follow,
-use @code{@@indicateurl} (@address@hidden@@indicateurl}}).
-
-
address@hidden @t{@@cite}
address@hidden @code{@@address@hidden@address@hidden
-
address@hidden@c old name
address@hidden cite
-
-Use the @code{@@cite} command for the name of a book that lacks a
-companion Info file. The command produces italics in the printed
-manual, and quotation marks in the Info file.
-
-If a book is written in Texinfo, it is better to use a cross reference
-command since a reader can easily follow such a reference in Info.
address@hidden@t{@@xref}}.
-
-
address@hidden Marking Text
address@hidden Marking Text, Words and Phrases
address@hidden Paragraph, marking text within
address@hidden Marking words and phrases
address@hidden Words and phrases, marking them
address@hidden Marking text within a paragraph
address@hidden Text, marking up
-
-In Texinfo, you can mark words and phrases in a variety of ways.
-The Texinfo formatters use this information to determine how to
-highlight the text.
-You can specify, for example, whether a word or phrase is a
-defining occurrence, a metasyntactic variable, or a symbol used in a
-program. Also, you can emphasize text, in several different ways.
-
address@hidden
-* Indicating:: How to indicate definitions, files, etc.
-* Emphasis:: How to emphasize text.
address@hidden menu
-
-
address@hidden Indicating
address@hidden Indicating Definitions, Commands, etc.
-
address@hidden Highlighting text
address@hidden Indicating commands, definitions, etc.
-
-Texinfo has commands for indicating just what kind of object a piece of
-text refers to. For example, metasyntactic variables are marked by
address@hidden@@var}, and code by @code{@@code}. Since the pieces of text are
-labeled by commands that tell what kind of object they are, it is easy
-to change the way the Texinfo formatters prepare such text. (Texinfo is
-an @emph{intentional} formatting language rather than a @emph{typesetting}
-formatting language.)
-
-For example, in a printed manual,
-code is usually illustrated in a typewriter font;
address@hidden@@code} tells @TeX{} to typeset this text in this font. But it
-would be easy to change the way @TeX{} highlights code to use another
-font, and this change would not affect how keystroke examples are
-highlighted. If straight typesetting commands were used in the body
-of the file and you wanted to make a change, you would need to check
-every single occurrence to make sure that you were changing code and
-not something else that should not be changed.
-
address@hidden
-* Useful Highlighting:: Highlighting provides useful information.
-* @t{@@code}:: Indicating program code.
-* @t{@@kbd}:: Showing keyboard input.
-* @t{@@key}:: Specifying keys.
-* @t{@@samp}:: Indicating a literal sequence of
characters.
-* @t{@@verb}:: Indicating a verbatim sequence of
characters.
-* @t{@@var}:: Indicating metasyntactic variables.
-* @t{@@env}:: Indicating environment variables.
-* @t{@@file}:: Indicating file names.
-* @t{@@command}:: Indicating command names.
-* @t{@@option}:: Indicating option names.
-* @t{@@dfn}:: Specifying definitions.
-* @t{@@abbr}:: Indicating abbreviations.
-* @t{@@acronym}:: Indicating acronyms.
-* @t{@@indicateurl}:: Indicating an example url.
-* @t{@@email}:: Indicating an electronic mail address.
address@hidden menu
-
-
address@hidden Useful Highlighting
address@hidden Highlighting Commands are Useful
-
-The commands serve a variety of purposes:
-
address@hidden @code
address@hidden @@address@hidden@address@hidden
-Indicate text that is a literal example of a piece of a program.
address@hidden@t{@@code}}.
-
address@hidden @@address@hidden@address@hidden
-Indicate keyboard input. @address@hidden@@kbd}}.
-
address@hidden @@address@hidden@address@hidden
-Indicate the conventional name for a key on a keyboard.
address@hidden@t{@@key}}.
-
address@hidden @@address@hidden@address@hidden
-Indicate text that is a literal example of a sequence of characters.
address@hidden@t{@@samp}}.
-
address@hidden @@address@hidden@address@hidden
-Write a verbatim sequence of characters.
address@hidden@t{@@verb}}.
-
address@hidden @@address@hidden@address@hidden
-Indicate a metasyntactic variable. @address@hidden@@var}}.
-
address@hidden @@address@hidden@address@hidden
-Indicate an environment variable. @address@hidden@@env}}.
-
address@hidden @@address@hidden@address@hidden
-Indicate the name of a file. @address@hidden@@file}}.
-
address@hidden @@address@hidden@address@hidden
-Indicate the name of a command.
address@hidden@t{@@command}}.
-
address@hidden @@address@hidden@address@hidden
-Indicate a command-line option.
address@hidden@t{@@option}}.
-
address@hidden @@address@hidden@address@hidden
-Indicate the introductory or defining use of a term.
address@hidden@t{@@dfn}}.
-
address@hidden @@address@hidden@address@hidden
-Indicate the name of a book. @address@hidden@@cite}}.
-
address@hidden @@address@hidden@address@hidden
-Indicate an abbreviation, such as `Comput.'.
-
address@hidden @@address@hidden@address@hidden
-Indicate an acronym. @address@hidden@@acronym}}.
-
address@hidden @@address@hidden@address@hidden
-Indicate an example (that is, nonfunctional) uniform resource locator.
address@hidden@t{@@indicateurl}}. (Use @code{@@url} (@address@hidden@@url}})
for
-live urls.)
-
address@hidden @@address@hidden@var{email-address}[, @address@hidden
-Indicate an electronic mail address. @address@hidden@@email}}.
-
address@hidden table
-
-
address@hidden @t{@@code}
address@hidden @code{@@address@hidden@address@hidden
-
address@hidden@c old name
address@hidden code
-
address@hidden Syntactic tokens, indicating
-Use the @code{@@code} command to indicate text that is a piece of a
-program and which consists of entire syntactic tokens. Enclose the
-text in braces.
-
address@hidden Expressions in a program, indicating
address@hidden Keywords, indicating
address@hidden Reserved words, indicating
-Thus, you should use @code{@@code} for an expression in a program, for
-the name of a variable or function used in a program, or for a
-keyword in a programming language.
-
-Use @code{@@code} for command names in languages that resemble
-programming languages, such as Texinfo. For example, @code{@@code} and
address@hidden@@samp} are produced by writing
@samp{@@address@hidden@@@@address@hidden and
address@hidden@@address@hidden@@@@address@hidden in the Texinfo source,
respectively.
-
address@hidden Case, not altering in @code{@@code}
-It is incorrect to alter the case of a word inside an @code{@@code}
-command when it appears at the beginning of a sentence. Most computer
-languages are case sensitive. In C, for example, @code{Printf} is
-different from the identifier @code{printf}, and most likely is a
-misspelling of it. Even in languages which are not case sensitive, it
-is confusing to a human reader to see identifiers spelled in different
-ways. Pick one spelling and always use that. If you do not want to
-start a sentence with a command name written all in lowercase, you
-should rearrange the sentence.
-
-In the Info output, @code{@@code} results in single quotation marks
-around the text. In other formats, @code{@@code} argument is typeset
-in a typewriter (monospace) font. For example,
-
address@hidden
-The function returns @@address@hidden@}.
address@hidden example
-
address@hidden
-produces this:
-
address@hidden
-The function returns @code{nil}.
address@hidden quotation
-
-Here are some cases for which it is preferable @emph{not} to use @code{@@code}:
-
address@hidden @bullet
address@hidden
-For shell command names such as @command{ls} (use @code{@@command}).
-
address@hidden
-For environment variable such as @env{TEXINPUTS} (use @code{@@env}).
-
address@hidden
-For shell options such as @samp{-c} when such options stand alone (use
address@hidden@@option}).
-
address@hidden
-An entire shell command often looks better if written using
address@hidden@@samp} rather than @code{@@code}. In this case, the rule is to
-choose the more pleasing format.
-
address@hidden
-For a string of characters shorter than a syntactic token. For example,
-if you are writing about @samp{goto-ch}, which is just a part of the
-name for the @code{goto-char} Emacs Lisp function, you should use
address@hidden@@samp}.
-
address@hidden
-In general, when writing about the characters used in a token; for
-example, do not use @code{@@code} when you are explaining what letters
-or printable symbols can be used in the names of functions. (Use
address@hidden@@samp}.) Also, you should not use @code{@@code} to mark text
-that is considered input to programs unless the input is written in a
-language that is like a programming language. For example, you should
-not use @code{@@code} for the keystroke commands of GNU Emacs (use
address@hidden@@kbd} instead) although you may use @code{@@code} for the names
-of the Emacs Lisp functions that the keystroke commands invoke.
-
address@hidden itemize
-
-By default, @TeX{} will consider breaking lines at @samp{-} and
address@hidden characters within @code{@@code} and related commands. This
-can be controlled with @code{@@allowcodebreaks}
-(@address@hidden@@allowcodebreaks}}). The HTML output attempts to
-respect this for @samp{-}, but ultimately it is up to the browser's
-behavior. For Info, it seems better never to make such breaks.
-
-For Info, the quotes are omitted in the output of the @code{@@code}
-command and related commands (e.g., @code{@@kbd}, @code{@@command}),
-in typewriter-like contexts such as the @code{@@example} environment
-(@address@hidden@@example}}) and @code{@@code} itself, etc.
-
-To control which quoting characters are implicitly inserted by Texinfo
-processors in the output of @samp{@@code}, etc., see the
address@hidden and @code{CLOSE_QUOTE_SYMBOL} customization
-variables (@pxref{Other Customization Variables}). This is separate
-from how actual quotation characters in the input document are handled
-(@pxref{Inserting Quote Characters}).
-
-
address@hidden @t{@@kbd}
address@hidden @code{@@address@hidden@address@hidden
-
address@hidden@c old name
address@hidden kbd
address@hidden Keyboard input
-
-Use the @code{@@kbd} command for characters of input to be typed by
-users. For example, to refer to the characters @kbd{M-a}, write:
-
address@hidden
-@@address@hidden@}
address@hidden example
-
address@hidden
-and to refer to the characters @kbd{M-x shell}, write:
-
address@hidden
-@@address@hidden address@hidden
address@hidden example
-
address@hidden User input
address@hidden Slanted typewriter font, for @code{@@kbd}
-By default, the @code{@@kbd} command produces a different font
-(slanted typewriter instead of normal typewriter),
-so users can distinguish the characters that they are supposed
-to type from those that the computer outputs.
-
address@hidden kbdinputstyle
-Since the usage of @code{@@kbd} varies from manual to manual, you can
-control the font switching with the @code{@@kbdinputstyle} command.
-This command has no effect on Info output. Write this command at the
-beginning of a line with a single word as an argument, one of the
-following:
-
address@hidden address@hidden, value for @code{@@kbdinputstyle}}
address@hidden address@hidden, value for @code{@@kbdinputstyle}}
address@hidden address@hidden, value for @code{@@kbdinputstyle}}
address@hidden @samp
address@hidden code
-Always use the same font for @code{@@kbd} as @code{@@code}.
address@hidden example
-Use the distinguishing font for @code{@@kbd} only in @code{@@example}
-and similar environments.
address@hidden distinct
-(the default) Always use the distinguishing font for @code{@@kbd}.
address@hidden table
-
-You can embed another @@-command inside the braces of an @code{@@kbd}
-command. Here, for example, is the way to describe a command that
-would be described more verbosely as ``press the @samp{r} key and then
-press the @key{RETURN} key'':
-
address@hidden
-@@address@hidden @@address@hidden@address@hidden
address@hidden example
-
address@hidden
-This produces: @kbd{r @key{RET}}. (The present manual uses the
-default for @code{@@kbdinputstyle}.)
-
-You also use the @code{@@kbd} command if you are spelling out the letters
-you type; for example:
-
address@hidden
-To give the @@address@hidden@} command,
-type the characters @@address@hidden o g o u t @@address@hidden@address@hidden
address@hidden example
-
address@hidden
-This produces:
-
address@hidden
-To give the @code{logout} command,
-type the characters @kbd{l o g o u t @key{RET}}.
address@hidden quotation
-
-(Also, this example shows that you can add spaces for clarity. If you
-explicitly want to mention a space character as one of the characters of
-input, write @kbd{@@address@hidden@}} for it.)
-
-
address@hidden @t{@@key}
address@hidden @code{@@address@hidden@address@hidden
-
address@hidden@c old name
address@hidden key
-
-Use the @code{@@key} command for the conventional name for a key on a
-keyboard, as in:
-
address@hidden
-@@address@hidden@}
address@hidden example
-
-You can use the @code{@@key} command within the argument of an
address@hidden@@kbd} command when the sequence of characters to be typed
-includes one or more keys that are described by name.
-
-For example, to produce @kbd{C-x @key{ESC}} and @address@hidden you
-would type:
-
address@hidden
-@@address@hidden @@address@hidden@address@hidden
-@@address@hidden@@address@hidden@address@hidden
address@hidden example
-
-Here is a list of the recommended names for keys:
address@hidden Recommended names for keys
address@hidden Keys, recommended names
address@hidden Names recommended for keys
address@hidden Abbreviations for keys
address@hidden Control keys, specifying
address@hidden Meta keys, specifying
-
address@hidden
address@hidden @t
address@hidden SPC
-Space
address@hidden RET
-Return
address@hidden LFD
-Linefeed (however, since most keyboards nowadays do not have a Linefeed key,
-it might be better to call this character @kbd{C-j})
address@hidden TAB
-Tab
address@hidden BS
-Backspace
address@hidden ESC
-Escape
address@hidden DELETE
-Delete
address@hidden SHIFT
-Shift
address@hidden CTRL
-Control
address@hidden META
-Meta
address@hidden table
address@hidden quotation
-
address@hidden META key
-There are subtleties to handling words like `meta' or `ctrl' that are
-names of modifier keys. When mentioning a character in which the
-modifier key is used, such as @kbd{Meta-a}, use the @code{@@kbd} command
-alone; do not use the @code{@@key} command; but when you are referring
-to the modifier key in isolation, use the @code{@@key} command. For
-example, write @samp{@@address@hidden@}} to produce @kbd{Meta-a} and
address@hidden@@address@hidden@}} to produce @key{META}.
-
-As a convention in GNU manuals, @code{@@key} should not be used in
-index entries.
-
-
address@hidden @t{@@samp}
address@hidden @code{@@address@hidden@address@hidden
-
address@hidden@c old name
address@hidden samp
-
-Use the @code{@@samp} command to indicate text that is a literal example
-or `sample' of a sequence of characters in a file, string, pattern, etc.
-Enclose the text in braces. The argument appears within single
-quotation marks in both the Info file and the printed manual; in
-addition, it is printed in a fixed-width font.
-
address@hidden
-To match @@address@hidden@} at the end of the line,
-use the regexp @@address@hidden@}.
address@hidden example
-
address@hidden
-produces
-
address@hidden
-To match @samp{foo} at the end of the line, use the regexp
address@hidden
address@hidden quotation
-
-Any time you are referring to single characters, you should use
address@hidden@@samp} unless @code{@@kbd} or @code{@@key} is more appropriate.
-Also, you may use @code{@@samp} for entire statements in C and for entire
-shell commands---in this case, @code{@@samp} often looks better than
address@hidden@@code}. Basically, @code{@@samp} is a catchall for whatever is
-not covered by @code{@@code}, @code{@@kbd}, @code{@@key},
address@hidden@@command}, etc.
-
-Only include punctuation marks within braces if they are part of the
-string you are specifying. Write punctuation marks outside the braces
-if those punctuation marks are part of the English text that surrounds
-the string. In the following sentence, for example, the commas and
-period are outside of the braces:
-
address@hidden
address@hidden
-In English, the vowels are @@address@hidden@}, @@address@hidden@},
-@@address@hidden@}, @@address@hidden@}, @@address@hidden@}, and sometimes
-@@address@hidden@}.
address@hidden group
address@hidden example
-
address@hidden
-This produces:
-
address@hidden
-In English, the vowels are @samp{a}, @samp{e},
address@hidden, @samp{o}, @samp{u}, and sometimes
address@hidden
address@hidden quotation
-
-
address@hidden @t{@@verb}
address@hidden @code{@@address@hidden@address@hidden@address@hidden
-
address@hidden@c old name
address@hidden verb
address@hidden Verbatim in-line text
-
address@hidden Delimiter character, for verbatim
-Use the @code{@@verb} command to print a verbatim sequence of
-characters.
-
-Like @LaTeX{}'s @code{\verb} command, the verbatim text can be quoted using
-any unique delimiter character. Enclose the verbatim text, including the
-delimiters, in braces. Text is printed in a fixed-width font:
-
address@hidden
-How many @@address@hidden|@@|@}-escapes does one need to print this
-@@address@hidden@@a @@b.@@address@hidden string or
@@address@hidden@@'address@hidden@address@hidden this?
address@hidden example
-
address@hidden
-produces
-
address@hidden
-How many @verb{|@|}-escapes does one need to print this
address@hidden@a @address@hidden string or @verb{+@'e?`{}!`\+} this?
address@hidden example
-
-This is in contrast to @code{@@samp} (see the previous section),
address@hidden@@code}, and similar commands; in those cases, the argument is
-normal Texinfo text, where the three characters @code{@@@address@hidden are
-special, as usual. With @code{@@verb}, nothing is special except the
-delimiter character you choose.
-
-The delimiter character itself may appear inside the verbatim text, as
-shown above. As another example, @samp{@@address@hidden@}} prints a single
-(fixed-width) period.
-
-It is not reliable to use @code{@@verb} inside other Texinfo
-constructs. In particular, it does not work to use @code{@@verb} in
-anything related to cross referencing, such as section titles or
-figure captions.
-
-
address@hidden @t{@@var}
address@hidden @code{@@address@hidden@address@hidden
-
address@hidden@c old name
address@hidden var
-
-Use the @code{@@var} command to indicate metasyntactic variables. A
address@hidden variable} is something that stands for another
-piece of text. For example, you should use a metasyntactic variable
-in the documentation of a function to describe the arguments that are
-passed to that function.
-
-Do not use @code{@@var} for the names of normal variables in computer
-programs. These are specific names, so @code{@@code} is correct for
-them (@t{@@code}). For example, the Emacs Lisp variable
address@hidden is not a metasyntactic variable; it is
-properly formatted using @code{@@code}.
-
-Do not use @code{@@var} for environment variables either; @code{@@env}
-is correct for them (see the next section).
-
-The effect of @code{@@var} in the Info file is to change the case of
-the argument to all uppercase. In the printed manual and HTML
-output, the argument is output in slanted type.
-
address@hidden 700
-For example,
-
address@hidden
-To delete file @@address@hidden@},
-type @@address@hidden @@address@hidden@address@hidden
address@hidden example
-
address@hidden
-produces
-
address@hidden
-To delete file @var{filename}, type @samp{rm @var{filename}}.
address@hidden quotation
-
address@hidden
-(Note that @code{@@var} may appear inside @code{@@code},
address@hidden@@samp}, @code{@@file}, etc.)
-
-Write a metasyntactic variable all in lowercase without spaces, and
-use hyphens to make it more readable. Thus, the Texinfo source for
-the illustration of how to begin a Texinfo manual looks like
-this:
-
address@hidden
address@hidden
-\input texinfo
-@@@@setfilename @@address@hidden@}
-@@@@settitle @@address@hidden@}
address@hidden group
address@hidden example
-
address@hidden
-This produces:
-
address@hidden
address@hidden
-\input texinfo
-@@setfilename @var{info-file-name}
-@@settitle @var{name-of-manual}
address@hidden group
address@hidden example
-
-In some documentation styles, metasyntactic variables are shown with
-angle brackets, for example:
-
address@hidden
address@hidden, type rm <filename>
address@hidden example
-
address@hidden
-However, that is not the style that Texinfo uses.
-
address@hidden FIXME add a customization variable? Add an example on how to do
that
address@hidden for HTML?
address@hidden (You can, of course, modify the sources to @file{texinfo.tex}
address@hidden and the Info formatting commands
address@hidden to output the @code{<@dots{}>} format if you wish.)
-
-
address@hidden @t{@@env}
address@hidden @code{@@address@hidden@address@hidden
-
address@hidden@c old name
address@hidden env
-
-Use the @code{@@env} command to indicate environment variables, as
-used by many operating systems, including address@hidden Do not use it for
address@hidden variables; use @code{@@var} for those (see the
-previous section).
-
address@hidden@@env} is equivalent to @code{@@code} in its effects.
-For example:
-
address@hidden
-The @@address@hidden@} environment variable @dots{}
address@hidden example
address@hidden produces
address@hidden
-The @env{PATH} environment variable @dots{}
address@hidden quotation
-
-
address@hidden @t{@@file}
address@hidden @code{@@address@hidden@address@hidden
-
address@hidden@c old name
address@hidden file
-
-Use the @code{@@file} command to indicate text that is the name of a
-file, buffer, or directory, or is the name of a node in Info. You can
-also use the command for file name suffixes. Do not use @code{@@file}
-for symbols in a programming language; use @code{@@code}.
-
address@hidden@@file} is equivalent to @code{code} in its effects. For
-example,
-
address@hidden
-The @@address@hidden@} files are in
-the @@address@hidden/usr/local/emacs/address@hidden directory.
address@hidden example
-
address@hidden
-produces
-
address@hidden
-The @file{.el} files are in
-the @file{/usr/local/emacs/lisp} directory.
address@hidden quotation
-
-
address@hidden @t{@@command}
address@hidden @code{@@address@hidden@address@hidden
-
address@hidden@c old name
address@hidden command
address@hidden Command names, indicating
address@hidden Program names, indicating
-
-Use the @code{@@command} command to indicate command names, such as
address@hidden or @command{cc}.
-
address@hidden@@command} is equivalent to @code{@@code} in its effects.
-For example:
-
address@hidden
-The command @@address@hidden@} lists directory contents.
address@hidden example
address@hidden produces
address@hidden
-The command @command{ls} lists directory contents.
address@hidden quotation
-
-You should write the name of a program in the ordinary text font, rather
-than using @code{@@command}, if you regard it as a new English word,
-such as `Emacs' or `Bison'.
-
-When writing an entire shell command invocation, as in @samp{ls -l},
-you should use either @code{@@samp} or @code{@@code} at your discretion.
-
-
address@hidden @t{@@option}
address@hidden @code{@@address@hidden@address@hidden
-
address@hidden@c old name
address@hidden option
-
-Use the @code{@@option} command to indicate a command-line option; for
-example, @option{-l} or @option{--version} or
address@hidden@var{filename}}.
-
address@hidden@@option} is equivalent to @code{@@code} in its effects.
-For example:
-
address@hidden
-The option @@address@hidden@} produces a long listing.
address@hidden example
address@hidden produces
address@hidden
-The option @option{-l} produces a long listing.
address@hidden quotation
-
-
address@hidden @t{@@dfn}
address@hidden @code{@@address@hidden@address@hidden
-
address@hidden@c old name
address@hidden dfn
-
-Use the @code{@@dfn} command to identify the introductory or defining
-use of a technical term. Use the command only in passages whose
-purpose is to introduce a term which will be used again or which the
-reader ought to know. Mere passing mention of a term for the first
-time does not deserve @code{@@dfn}. The command generates italics in
-the printed manual, and double quotation marks in the Info file. For
-example:
-
address@hidden
-Getting rid of a file is called @@address@hidden@} it.
address@hidden example
-
address@hidden
-produces
-
address@hidden
-Getting rid of a file is called @dfn{deleting} it.
address@hidden quotation
-
-As a general rule, a sentence containing the defining occurrence of a
-term should be a definition of the term. The sentence does not need
-to say explicitly that it is a definition, but it should contain the
-information of a definition---it should make the meaning clear.
-
-
address@hidden @t{@@abbr}
address@hidden @code{@@address@hidden@var{abbreviation}[, @address@hidden
-
address@hidden@c old name
address@hidden abbr
-
address@hidden Abbreviations, tagging
-You can use the @code{@@abbr} command for general abbreviations. The
-abbreviation is given as the single argument in braces, as in
address@hidden@@address@hidden@}}. As a matter of style, or for particular
-abbreviations, you may prefer to omit periods, as in
address@hidden@@address@hidden@} Stallman}.
-
address@hidden@@abbr} accepts an optional second argument, intended to be used
-for the meaning of the abbreviation.
-
-If the abbreviation ends with a lowercase letter and a period, and is
-not at the end of a sentence, and has no second argument, remember to
-use the @code{@@.} command (@pxref{Ending a Sentence}) to get the
-correct spacing. However, you do not have to use @code{@@.} within
-the abbreviation itself; Texinfo automatically assumes periods within
-the abbreviation do not end a sentence.
-
address@hidden @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 @code{<abbrev>} tag is used. For instance:
-
address@hidden
-@@address@hidden J., Computer address@hidden
address@hidden example
-
address@hidden produces:
-
address@hidden
address@hidden J., Computer Journal}
address@hidden display
-
-For abbreviations consisting of all capital letters, you may prefer to
-use the @code{@@acronym} command instead. See the next section for
-more on the usage of these two commands.
-
-
address@hidden @t{@@acronym}
address@hidden @code{@@address@hidden@var{acronym}[, @address@hidden
-
address@hidden@c old name
address@hidden acronym
-
address@hidden NASA, as acronym
address@hidden Acronyms, tagging
-You can use the @code{@@acronym} command for abbreviations written in
-all capital letters, such as address@hidden'. The abbreviation is
-given as the single argument in braces, as in
address@hidden@@address@hidden@}}. As a matter of style, or for particular
-acronyms, you may prefer to use periods, as in
address@hidden@@address@hidden@}}.
-
address@hidden@@acronym} accepts an optional second argument, intended to be
-used for the meaning of the acronym.
-
-If the acronym is at the end of a sentence, and if there is no second
-argument, remember to use the @code{@@.} or similar command
-(@pxref{Ending a Sentence}) to get the correct spacing.
-
address@hidden @code{<acronym>} tag
-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.
-
-For instance (since GNU is a recursive acronym, we use
address@hidden@@acronym} recursively):
-
address@hidden
-@@address@hidden, @@address@hidden@}'s Not address@hidden
address@hidden example
-
address@hidden produces:
-
address@hidden
address@hidden, @acronym{GNU}'s Not Unix}
address@hidden display
-
address@hidden Family names, in all capitals
-In some circumstances, it is conventional to print family names in all
-capitals. Don't use @code{@@acronym} for this, since a name is not an
-acronym. Use @code{@@sc} instead (@pxref{Smallcaps}).
-
address@hidden@@abbr} and @code{@@acronym} are closely related commands: they
-both signal to the reader that a shortened form is being used, and
-possibly give a meaning. When choosing whether to use these two
-commands, please bear the following in mind.
-
address@hidden @minus
address@hidden
-In common English usage, acronyms are a subset of abbreviations: they
-include pronounceable words like address@hidden', `radar', and
-`snafu'; some sources also include syllable acronyms like
-`Usenet', hybrids like address@hidden', and unpronounceable
-initialisms like address@hidden'.
-
address@hidden
-In Texinfo, an acronym (but not an abbreviation) should consist only
-of capital letters and periods, no lowercase.
-
address@hidden
-In @TeX{}, an acronym (but not an abbreviation) is printed in a
-slightly smaller font.
-
address@hidden
-Some browsers place a dotted bottom border under abbreviations but not
-acronyms.
-
address@hidden
-It usually turns out to be quite difficult and/or time-consuming to
-consistently use @code{@@acronym} for all sequences of uppercase
-letters. Furthermore, it looks strange for some acronyms to be in the
-normal font size and others to be smaller. Thus, a simpler approach
-you may wish to consider is to avoid @code{@@acronym} and just typeset
-everything as normal text in all capitals: @samp{GNU}, producing the
-output `GNU'.
-
address@hidden
-In general, it's not essential to use either of these commands for all
-abbreviations; use your judgment. Text is perfectly readable without
-them.
address@hidden itemize
-
-
address@hidden @t{@@indicateurl}
address@hidden @code{@@address@hidden@address@hidden
-
address@hidden@c old name
address@hidden indicateurl
address@hidden Uniform resource locator, indicating
address@hidden URL, indicating
-
-Use the @code{@@indicateurl} command to indicate a uniform resource
-locator on the World Wide Web. This is purely for markup purposes and
-does not produce a link you can follow (use the @code{@@url} or
address@hidden@@uref} command for that, @address@hidden@@url}}).
address@hidden@@indicateurl} is useful for urls which do not actually exist.
-For example:
-
address@hidden
-For example, the url might be @@address@hidden://example.org/address@hidden
address@hidden example
-
address@hidden which produces:
-
address@hidden
-For example, the url might be @indicateurl{http://example.org/path}.
address@hidden display
-
-The output from @code{@@indicateurl} is more or less like that of
address@hidden@@samp} (@address@hidden@@samp}}).
-
-
address@hidden @t{@@email}
address@hidden @code{@@address@hidden@var{email-address}[, @address@hidden
-
address@hidden@c old name
address@hidden email
-
-Use the @code{@@email} command to indicate an electronic mail address.
-It takes one mandatory argument, the address, and one optional argument, the
-text to display (the default is the address itself).
-
address@hidden Mailto link
-In Info, the address is shown in angle brackets, preceded by the text
-to display if any. In @TeX{}, the angle brackets are omitted. In
-HTML output, @code{@@email} produces a @samp{mailto} link that usually
-brings up a mail composition window. For example:
-
address@hidden
-Send bug reports to @@address@hidden@@@@address@hidden,
-suggestions to the @@address@hidden@@@@gnu.org, same address@hidden
address@hidden example
-
address@hidden produces
-
address@hidden
-Send bug reports to @email{bug-texinfo@@gnu.org},
-suggestions to the @email{bug-texinfo@@gnu.org, same place}.
address@hidden display
-
-
address@hidden Emphasis
address@hidden Emphasizing Text
address@hidden Emphasizing text
-
-Usually, Texinfo changes the font to mark words in the text according
-to the category the words belong to; an example is the @code{@@code}
-command. Most often, this is the best way to mark words. However,
-sometimes you will want to emphasize text without indicating a
-category. Texinfo has two commands to do this. Also, Texinfo has
-several commands that specify the font in which text will be output.
-These commands have no effect in Info and only one of them, the
address@hidden@@r} command, has any regular use.
-
address@hidden
-* @t{@@emph @@strong}:: How to emphasize text in Texinfo.
-* Smallcaps:: How to use the small caps font.
-* Fonts:: Various font commands for printed output.
address@hidden menu
-
-
address@hidden @t{@@emph @@strong}
address@hidden @code{@@address@hidden@address@hidden and
@code{@@address@hidden@address@hidden
-
address@hidden & address@hidden oldname
address@hidden emph
address@hidden strong
address@hidden Emphasizing text, font for
-
-The @code{@@emph} and @code{@@strong} commands are for emphasis;
address@hidden@@strong} is stronger. In printed output, @code{@@emph} produces
address@hidden and @code{@@strong} produces @strong{bold}.
-In the Info output, @code{@@emph} surrounds the text with underscores
-(@samp{_}), and @code{@@strong} puts asterisks around the text.
-
-For example,
-
address@hidden
address@hidden
-@@address@hidden:@} @@address@hidden address@hidden
-removes @@address@hidden@} normal files.
address@hidden group
address@hidden example
-
address@hidden
-produces the following:
-
address@hidden
address@hidden: @samp{rm * .[^.]*}
-removes @emph{all} normal files.
address@hidden quotation
-
-The @code{@@strong} command is seldom used except to mark what is, in
-effect, a typographical element, such as the word `Caution' in the
-preceding example.
-
address@hidden Caution
-Do not use @code{@@strong} with the word @samp{Note} followed by a
-space; Info will mistake the combination for a cross reference. Use a
-phrase such as @strong{Please notice} or @strong{Caution} instead, or
-the optional argument to @code{@@address@hidden is allowable
-there.
address@hidden quotation
-
-
address@hidden Smallcaps
address@hidden @code{@@address@hidden@address@hidden: The Small Caps Font
address@hidden Small caps font
address@hidden sc @r{(small caps font)}
-
-Use the @samp{@@sc} command to set text in @sc{a small caps font}
-(where possible). Write the text you want to be in small caps between
-braces in lowercase, like this:
-
address@hidden
-Richard @@address@hidden@} commenc@'{e} GNU.
address@hidden example
-
address@hidden
-This produces:
-
address@hidden
-Richard @sc{Stallman} commenc@'{e} GNU.
address@hidden display
-
-As shown here, we recommend reserving @code{@@sc} for special cases
-where you want typographic small caps; family names are one such,
-especially in languages other than English, though there are no
-hard-and-fast rules about such things.
-
address@hidden @code{<small>} tag
address@hidden typesets any uppercase letters between the braces of an
address@hidden@@sc} command in full-size capitals; only lowercase letters are
-printed in the small caps font. In the Info output, the argument to
address@hidden@@sc} is printed in all uppercase. In HTML, the argument is
-uppercased and the output marked with the @code{<small>} tag to reduce
-the font size, since HTML cannot easily represent true small caps.
-
-Overall, we recommend using standard upper- and lowercase letters
-wherever possible.
-
-
address@hidden Fonts
address@hidden Fonts for Printing
address@hidden Fonts for printing
-
address@hidden fonttextsize
address@hidden Font size, reducing
address@hidden Reducing font size
address@hidden Smaller fonts
-Texinfo provides one command to change the size of the main body font
-in the @TeX{} output for a document: @code{@@fonttextsize}. It has no
-effect in other output. It takes a single argument on the remainder
-of the line, which must be either @samp{10} or @samp{11}. For
-example:
-
address@hidden
-@@fonttextsize 10
address@hidden example
-
address@hidden Printing cost, reducing
-The effect is to reduce the body font to a address@hidden size (the
-default is address@hidden). Fonts for other elements, such as sections
-and chapters, are reduced accordingly. This should only be used in
-conjunction with @code{@@smallbook} (@address@hidden@@smallbook}}) or
-similar, since address@hidden fonts on standard paper (8.5x11 or A4) are
-too small. One reason to use this command is to save pages, and hence
-printing cost, for physical books.
-
-Texinfo does not at present have commands to switch the font family
-to use, or more general size-changing commands.
-
-Texinfo also provides a number of font commands that specify font
-changes in the printed manual and (where possible) in the HTML output.
-They have no effect in Info. All the commands apply to a following
-argument surrounded by braces.
-
address@hidden @code
address@hidden @@b
address@hidden b @r{(bold font)}
address@hidden Bold font
-selects @b{bold} face;
-
address@hidden @@i
address@hidden i @r{(italic font)}
address@hidden Italic font
-selects an @i{italic} font;
-
address@hidden @@r
address@hidden r @r{(roman font)}
address@hidden Roman font
address@hidden Default font
-selects a @r{roman} font, which is the usual font in which text is
-printed. It may or may not be seriffed.
-
address@hidden @@sansserif
address@hidden sansserif @r{(sans serif font)}
address@hidden Sans serif font
-selects a @sansserif{sans serif} font;
-
address@hidden @@slanted
address@hidden slanted @r{(slanted font)}
address@hidden Slanted font
address@hidden Oblique font
-selects a @slanted{slanted} font;
-
address@hidden @@t
address@hidden t @r{(typewriter font)}
address@hidden Monospace font
address@hidden Fixed-width font
address@hidden Typewriter font
-selects the @t{fixed-width}, typewriter-style font used by @code{@@code};
-
address@hidden table
-
-(The commands with longer names were invented much later than the
-others, at which time it did not seem desirable to use very short
-names for such infrequently needed features.)
-
address@hidden <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
address@hidden<lineannotation>} tag in Docbook output.
-
-For example,
-
address@hidden
address@hidden
-@@lisp
-(+ 2 2) ; @@address@hidden two plus address@hidden
-@@end lisp
address@hidden group
address@hidden example
-
address@hidden
-produces
-
address@hidden
-(+ 2 2) ; @r{Add two plus two.}
address@hidden lisp
-
-The @code{@@t} command can occasionally be useful to produce output in
-a typewriter font where that is supported (e.g., HTML and PDF), but no
-distinction is needed in Info or plain text: @code{@@address@hidden@}}
-produces @t{foo}, cf. @code{@@address@hidden@}} producing @code{foo}.
-
-For example, we use @code{@@t} in the @code{@@node} commands for this
-manual to specify the Texinfo command names, because the quotes which
address@hidden@@code} outputs look extraneous in that particular context.
-
-In general, the other font commands are unlikely to be useful; they
-exist primarily to make it possible to document the functionality of
-specific font effects, such as in @TeX{} and related packages.
-
-
address@hidden Quotations and Examples
address@hidden Quotations and Examples
-
-Quotations and examples are blocks of text consisting of one or more
-whole paragraphs that are set off from the bulk of the text and
-treated differently. They are usually indented in the output.
-
address@hidden end
-In Texinfo, you always begin a quotation or example by writing an
-@@-command at the beginning of a line by itself, and end it by writing
-an @code{@@end} command that is also at the beginning of a line by
-itself. For instance, you begin an example by writing
address@hidden@@example} by itself at the beginning of a line and end the
-example by writing @code{@@end example} on a line by itself, at the
-beginning of that line, and with only one space between the
address@hidden@@end} and the @code{example}.
-
address@hidden
-* Block Enclosing Commands:: Different constructs for different purposes.
-* @t{@@quotation}:: Writing a quotation.
-* @t{@@indentedblock}:: Block of text indented on left.
-* @t{@@example}:: Writing an example in a fixed-width font.
-* @t{@@verbatim}:: Writing a verbatim example.
-* @t{@@verbatiminclude}:: Including a file verbatim.
-* @t{@@lisp}:: Illustrating Lisp code.
-* @t{@@address@hidden:: Examples in a smaller font.
-* @t{@@display}:: Writing an example in the current font.
-* @t{@@format}:: Writing an example without narrowed
margins.
-* @t{@@exdent}:: Undo indentation on a line.
-* @t{@@flushleft @@flushright}:: Pushing text flush left or flush right.
-* @t{@@raggedright}:: Avoiding justification on the right.
-* @t{@@noindent}:: Preventing paragraph indentation.
-* @t{@@indent}:: Forcing paragraph indentation.
-* @t{@@cartouche}:: Drawing rounded rectangles around text.
address@hidden menu
-
-
address@hidden Block Enclosing Commands
address@hidden Block Enclosing Commands
-
-Here is a summary of commands that enclose blocks of text, also known
-as @dfn{environments}. They're explained further in the following
-sections.
-
address@hidden @code
address@hidden @@quotation
-Indicate text that is quoted. The text is filled, indented (from both
-margins), and printed in a roman font by default.
-
address@hidden @@indentedblock
-Like @code{@@quotation}, but the text is indented only on the left.
-
address@hidden @@example
-Illustrate code, commands, and the like. The text is printed
-in a fixed-width font, and indented but not filled.
-
address@hidden @@lisp
-Like @code{@@example}, but specifically for illustrating Lisp code. The
-text is printed in a fixed-width font, and indented but not filled.
-
address@hidden @@verbatim
-Mark a piece of text that is to be printed verbatim; no character
-substitutions are made and all commands are ignored, until the next
address@hidden@@end verbatim}. The text is printed in a fixed-width font,
-and not indented or filled. Extra spaces and blank lines are
-significant, and tabs are expanded.
-
address@hidden @@display
-Display illustrative text. The text is indented but not filled, and
-no font is selected (so, by default, the font is roman).
-
address@hidden @@format
-Like @code{@@display} (the text is not filled and no font is
-selected), but the text is not indented.
-
address@hidden @@smallquotation
address@hidden @@smallindentedblock
address@hidden @@smallexample
address@hidden @@smalllisp
address@hidden @@smalldisplay
address@hidden @@smallformat
-These @code{@@small...} commands are just like their non-small
-counterparts, except that they output text in a smaller font size,
-where possible.
-
address@hidden @@flushleft
address@hidden @@flushright
-Text is not filled, but is set flush with the left or right margin,
-respectively.
-
address@hidden @@raggedright
-Text is filled, but only justified on the left, leaving the right
-margin ragged.
-
address@hidden @@cartouche
-Highlight text, often an example or quotation, by drawing a box with
-rounded corners around it.
address@hidden table
-
-The @code{@@exdent} command is used within the above constructs to
-undo the indentation of a line.
-
-The @code{@@noindent} command may be used after one of the above
-constructs (or anywhere) to prevent the following text from being
-indented as a new paragraph.
-
-
address@hidden @t{@@quotation}
address@hidden @code{@@quotation}: Block Quotations
address@hidden@c old name
-
address@hidden Quotations
address@hidden quotation
-
-The text of a quotation is processed like normal text (regular font,
-text is filled) except that:
-
address@hidden @bullet
address@hidden
-both the left and right margins are closer to the center of the page,
-so the whole of the quotation is indented;
-
address@hidden
-the first lines of paragraphs are indented no more than other lines; and
-
address@hidden
-an @code{@@author} command may be given to specify the author of the
-quotation.
address@hidden itemize
-
address@hidden
-This is an example of text written between an @code{@@quotation}
-command and an @code{@@end quotation} command. An @code{@@quotation}
-command is most often used to indicate text that is excerpted from
-another (real or hypothetical) printed work.
address@hidden quotation
-
-Write an @code{@@quotation} command as text on a line by itself. This
-line will disappear from the output. Mark the end of the quotation
-with a line beginning with and containing only @code{@@end quotation}.
-The @code{@@end quotation} line will likewise disappear from the
-output.
-
address@hidden@@quotation} takes one optional argument, given on the remainder
-of the line. This text, if present, is included at the beginning of
-the quotation in bold or otherwise emphasized, and followed with a
address@hidden:}. For example:
-
address@hidden
-@@quotation Note
-This is
-a foo.
-@@end quotation
address@hidden example
-
address@hidden
-produces
-
address@hidden Note
-This is
-a foo.
address@hidden quotation
-
-If the @code{@@quotation} argument is exactly one of these English words:
-
address@hidden
-Caution Important Note Tip Warning
address@hidden example
-
address@hidden @code{<note>} Docbook tag
address@hidden @code{<blockquote>} HTML tag
address@hidden then the Docbook output uses corresponding special tags
-(@code{<note>}, etc.) instead of the default @code{<blockquote>}.
-HTML output always uses @code{<blockquote>}.
-
-If the author of the quotation is specified in the @code{@@quotation}
-block with the @code{@@author} command, a line with the author name is
-displayed after the quotation:
-
address@hidden
-@@quotation
-People sometimes ask me if it is a sin in the Church of Emacs to use
-vi. Using a free version of vi is not a sin; it is a penance. So happy
-hacking.
-
-@@author Richard Stallman
-@@end quotation
address@hidden example
-
address@hidden
-produces
-
address@hidden
-People sometimes ask me if it is a sin in the Church of Emacs to use
-vi. Using a free version of vi is not a sin; it is a penance. So happy
-hacking.
-
address@hidden Richard Stallman
address@hidden quotation
-
address@hidden smallquotation
-Texinfo also provides a command @code{@@smallquotation}, which is just
-like @code{@@quotation} but uses a smaller font size where possible.
address@hidden@t{@@address@hidden
-
-
address@hidden @t{@@indentedblock}
address@hidden @code{@@indentedblock}: Indented text blocks
address@hidden Indented text block
address@hidden indentedblock
-
-The @code{@@indentedblock} environment is similar to
address@hidden@@quotation}, except that text is only indented on the left (and
-there is no optional argument for an author). Thus, the text font
-remains unchanged, and text is gathered and filled as usual, but the
-left margin is increased. For example:
-
address@hidden
-This is an example of text written between an @code{@@indentedblock}
-command and an @code{@@end indentedblock} command. The
address@hidden@@indentedblock} environment can contain any text or other
-commands desired.
address@hidden indentedblock
-
-This is written in the Texinfo source as:
-
address@hidden
-@@indentedblock
-This is an example ...
-@@end indentedblock
address@hidden example
-
address@hidden smallindentedblock
-Texinfo also provides a command @code{@@smallindentedblock}, which is
-just like @code{@@indentedblock} but uses a smaller font size where
-possible. @address@hidden@@address@hidden
-
-
address@hidden @t{@@example}
address@hidden @code{@@example}: Example Text
-
address@hidden@c old name
address@hidden example
address@hidden Examples, formatting them
address@hidden 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:
-
address@hidden
address@hidden Each line in the input file is a line in the output; that is,
-the source text is not filled as it normally is.
address@hidden Extra spaces and blank lines are significant.
address@hidden The output is indented.
address@hidden The output uses a fixed-width font.
address@hidden Texinfo commands @emph{are} expanded; if you want the output to
-be the input verbatim, use the @code{@@verbatim} environment instead
-(@address@hidden@@verbatim}}).
address@hidden itemize
-
-For example,
-
address@hidden
-@@example
-cp foo @@address@hidden@}; \
- cp foo @@address@hidden@}
-@@end example
address@hidden example
-
address@hidden
-produces
-
address@hidden
-cp foo @var{dest1}; \
- cp foo @var{dest2}
address@hidden 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
address@hidden@@example} and the ending @code{@@end example}, on the other
-hand, do appear in the output.
-
address@hidden 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.
address@hidden quotation
-
-Examples are often, logically speaking, ``in the middle'' of a
-paragraph, and the text that continues afterwards should not be
-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 (@address@hidden@@noindent}}.
-
-If you want to embed code fragments within sentences, instead of
-displaying them, use the @code{@@code} command or its relatives
-(@address@hidden@@code}}).
-
-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}).
-
-
address@hidden @t{@@verbatim}
address@hidden @code{@@verbatim}: Literal Text
-
address@hidden@c old name
address@hidden verbatim
address@hidden Verbatim environment
-
-Use the @code{@@verbatim} environment for printing of text that may
-contain special characters or commands that should not be interpreted,
-such as computer input or output (@code{@@example} interprets its text
-as regular Texinfo commands). This is especially useful for including
automatically
-generated files in a Texinfo manual.
-
-In general, the output will be just the same as the input. No
-character substitutions are made, e.g., all spaces and blank lines are
-significant, including tabs. In the printed manual, the text is
-typeset in a fixed-width font, and not indented or filled.
-
-Write an @code{@@verbatim} command at the beginning of a line by
-itself. This line will disappear from the output. Mark the end of
-the verbatim block with an @code{@@end verbatim} command, also written
-at the beginning of a line by itself. The @code{@@end verbatim} will
-also disappear from the output.
-
-For example:
address@hidden oops, got to trick this a bit: can't use @end verbatim inside
@verbatim
-
address@hidden
address@hidden @t{@@verbatim}
address@hidden @address@hidden
address@hidden @address@hidden@@command with strange characters: @@'e}
address@hidden @address@hidden
address@hidden @address@hidden
address@hidden @t{@@end verbatim}
address@hidden example
-
address@hidden
-This produces:
-
address@hidden
-{
- @command with strange characters: @'e
-expand me
-}
address@hidden verbatim
-
-Since the lines containing @code{@@verbatim} and @code{@@end verbatim}
-produce no output, typically you should put a blank line before the
address@hidden@@verbatim} and another blank line after the @code{@@end
-verbatim}. Blank lines between the beginning @code{@@verbatim} and
-the ending @code{@@end verbatim} will appear in the output.
-
address@hidden Verbatim, small
address@hidden Small verbatim
-You can get a ``small'' verbatim by enclosing the @code{@@verbatim} in
-an @code{@@smallformat} environment, as shown here:
-
address@hidden more cheating ...
address@hidden
address@hidden @t{@@smallformat}
address@hidden @t{@@verbatim}
address@hidden @t{... still verbatim, but in a smaller font ...}
address@hidden @t{@@end verbatim}
address@hidden @t{@@end smallformat}
address@hidden smallexample
-
-Finally, a word of warning: it is not reliable to use
address@hidden@@verbatim} inside other Texinfo constructs.
-
-
address@hidden @t{@@verbatiminclude}
address@hidden @code{@@verbatiminclude} @var{file}: Include a File Verbatim
-
address@hidden@c old name
address@hidden verbatiminclude
address@hidden Verbatim, include file
address@hidden Including a file verbatim
-
-You can include the exact contents of a file in the document with the
address@hidden@@verbatiminclude} command:
-
address@hidden
-@@verbatiminclude @var{filename}
address@hidden example
-
-The contents of @var{filename} is printed in a verbatim environment
-(@address@hidden@@verbatim}}). Generally, the file is printed exactly
-as it is, with all special characters and white space retained. No
-indentation is added; if you want indentation, enclose the
address@hidden@@verbatiminclude} within @code{@@example}
-(@address@hidden@@example}}).
-
-The name of the file is taken literally, with a single exception:
address@hidden@@address@hidden@address@hidden references are expanded. This
makes it
-possible to include files in other directories within a distribution,
-for instance:
-
address@hidden
-@@verbatiminclude @@address@hidden@}/NEWS
address@hidden example
-
address@hidden (You still have to get @code{top_srcdir} defined in the
-first place.)
-
-For a method on printing the file contents in a smaller font size, see
-the end of the previous section on @code{@@verbatim}.
-
-
address@hidden @t{@@lisp}
address@hidden @code{@@lisp}: Marking a Lisp Example
-
address@hidden@c old name
address@hidden lisp
address@hidden Lisp example
-
-The @code{@@lisp} command is used for Lisp code. It is synonymous
-with the @code{@@example} command.
-
address@hidden
-This is an example of text written between an
address@hidden@@lisp} command and an @code{@@end lisp} command.
address@hidden lisp
-
-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
address@hidden would be straightforward to extend Texinfo to work
-in a similar fashion for C, Fortran, or other languages.}
-
-Mark the end of @code{@@lisp} with @code{@@end lisp} on a line by
-itself.
-
-
address@hidden @t{@@address@hidden
address@hidden @code{@@address@hidden Block Commands
-
address@hidden@c old name
address@hidden smallexample
address@hidden smallformat
address@hidden smalllisp
address@hidden smallquotation
address@hidden Small examples
address@hidden Examples in smaller fonts
address@hidden Quotations in smaller fonts
address@hidden Lisp examples in smaller fonts
-
-In addition to the regular @code{@@example} and similar commands,
-Texinfo has ``small'' example-style commands. These are
address@hidden@@smallquotation}, @code{@@smallindentedblock},
address@hidden@@smalldisplay}, @code{@@smallexample}, @code{@@smallformat},
-and @code{@@smalllisp}.
-
-In Info output, the @code{@@address@hidden commands are equivalent to
-their non-small companion commands.
-
-In @TeX{}, however, the @code{@@address@hidden commands typeset text in
-a smaller font than the non-small example commands. Thus, for
-instance, code examples can contain longer lines and still fit on a
-page without needing to be rewritten.
-
-A smaller font size is also requested in HTML output, and (as usual)
-retained in the address@hidden transliteration.
-
-Mark the end of an @code{@@address@hidden block with a corresponding
address@hidden@@end address@hidden For example, pair @code{@@smallexample} with
address@hidden@@end smallexample}.
-
-Here is an example of the font used by the @code{@@smallexample}
-command (in Info, the output will be the same as usual):
-
address@hidden
address@hidden to make sure that you have the freedom to
-distribute copies of free software (and charge for
-this service if you wish), that you receive source
-code or can get it if you want it, that you can
-change the software or use pieces of it in new free
-programs; and that you know you can do these things.
address@hidden smallexample
-
-The @code{@@address@hidden commands use the same font style as their
-normal counterparts: @code{@@smallexample} and @code{@@smalllisp} use
-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.
-
-
address@hidden @t{@@display}
address@hidden @code{@@display}: Examples Using the Text Font
-
address@hidden@c old name
address@hidden display
address@hidden Display formatting
-
-The @code{@@display} command begins another kind of environment, where
-the font is left unchanged, not switched to typewriter as with
address@hidden@@example}. Each line of input still produces a line of output,
-and the output is still indented.
-
address@hidden
-This is an example of text written between an @code{@@display} command
-and an @code{@@end display} command. The @code{@@display} command
-indents the text, but does not fill it.
address@hidden display
-
address@hidden smalldisplay
-Texinfo also provides the environment @code{@@smalldisplay}, which is
-like @code{@@display} but uses a smaller font size.
address@hidden@t{@@address@hidden
-
-The @code{@@table} command (@address@hidden@@table}}) is not supported
-inside @code{@@display}. Since @code{@@display} is line-oriented, it
-doesn't make sense to use them together. If you want to indent a
-table, try @code{@@quotation} (@address@hidden@@quotation}}) or
address@hidden@@indentedblock} (@address@hidden@@indentedblock}}).
-
-
address@hidden @t{@@format}
address@hidden @code{@@format}: Examples Using the Full Line Width
-
address@hidden@c old name
address@hidden format
-
-The @code{@@format} command is similar to @code{@@display}, except it
-leaves the text unindented. Like @code{@@display}, it does not select
-the fixed-width font.
-
address@hidden
-This is an example of text written between an @code{@@format} command
-and an @code{@@end format} command. As you can see
-from this example,
-the @code{@@format} command does not fill the text.
address@hidden format
-
address@hidden smallformat
-Texinfo also provides the environment @code{@@smallformat}, which is
-like @code{@@format} but uses a smaller font size.
address@hidden@t{@@address@hidden
-
-
address@hidden @t{@@exdent}
address@hidden @code{@@exdent}: Undoing a Line's Indentation
-
address@hidden@c old name
address@hidden exdent
address@hidden Indentation undoing
-
-The @code{@@exdent} command removes any indentation a line might have.
-The command is written at the beginning of a line and applies only to
-the text that follows the command that is on the same line. Do not use
-braces around the text. In a printed manual, the text on an
address@hidden@@exdent} line is printed in the roman font.
-
address@hidden@@exdent} is usually used within examples. Thus,
-
address@hidden
address@hidden
-@@example
-This line follows an @@@@example command.
-@@exdent This line is exdented.
-This line follows the exdented line.
-The @@@@end example comes on the next line.
-@@end example
address@hidden group
address@hidden example
-
address@hidden
-produces
-
address@hidden
address@hidden
-This line follows an @@example command.
address@hidden This line is exdented.
-This line follows the exdented line.
-The @@end example comes on the next line.
address@hidden group
address@hidden example
-
-In practice, the @code{@@exdent} command is rarely used. Usually, you
-un-indent text by ending the example and returning the page to its
-normal width.
-
address@hidden@@exdent} has no effect in HTML output.
-
-
address@hidden @t{@@flushleft @@flushright}
address@hidden @code{@@flushleft} and @code{@@flushright}
-
address@hidden & address@hidden old name
address@hidden flushleft
address@hidden flushright
address@hidden Ragged right, without filling
address@hidden Ragged left, without filling
-
-The @code{@@flushleft} and @code{@@flushright} commands line up the
-ends of lines on the left and right margins of a page,
-but do not fill the text. The commands are written on lines of their
-own, without braces. The @code{@@flushleft} and @code{@@flushright}
-commands are ended by @code{@@end flushleft} and @code{@@end
-flushright} commands on lines of their own.
-
address@hidden 1500
-For example,
-
address@hidden
address@hidden
-@@flushleft
-This text is
-written flushleft.
-@@end flushleft
address@hidden group
address@hidden example
-
address@hidden
-produces
-
address@hidden
address@hidden
-This text is
-written flushleft.
address@hidden flushleft
address@hidden quotation
-
-
address@hidden@@flushright} produces the type of indentation often used in the
-return address of letters. For example,
-
address@hidden
address@hidden
-@@flushright
-Here is an example of text written
-flushright. The @@address@hidden@@address@hidden command
-right justifies every line but leaves the
-left end ragged.
-@@end flushright
address@hidden group
address@hidden example
-
address@hidden
-produces
-
address@hidden
-Here is an example of text written
-flushright. The @code{@@flushright} command
-right justifies every line but leaves the
-left end ragged.
address@hidden flushright
-
-
address@hidden @t{@@raggedright}
address@hidden @code{@@raggedright}: Ragged Right Text
-
address@hidden@c old name
address@hidden raggedright
address@hidden Ragged right, with filling
-
-The @code{@@raggedright} fills text as usual, but the text is only
-justified on the left; the right margin is ragged. The command is
-written on a line of its own, without braces. The
address@hidden@@raggedright} command is ended by @code{@@end raggedright} on a
-line of its own. This command has no effect in Info and HTML output,
-where text is always set ragged right.
-
-The @code{@@raggedright} command can be useful with paragraphs
-containing lists of commands with long names, when it is known in
-advance that justifying the text on both margins will make the
-paragraph look bad.
-
-For example,
-
address@hidden
address@hidden
-@@raggedright
-Commands for double and single angle quotation marks:
-@@address@hidden@@@@guillemetleft@@@{@@@address@hidden,
@@address@hidden@@@@guillemetright@@@{@@@address@hidden,
-@@address@hidden@@@@guillemotleft@@@{@@@address@hidden,
@@address@hidden@@@@guillemotright@@@{@@@address@hidden,
-@@address@hidden@@@@guilsinglleft@@@{@@@address@hidden,
@@address@hidden@@@@guilsinglright@@@{@@@address@hidden
-@@end raggedright
address@hidden group
address@hidden example
-
address@hidden
-produces
-
address@hidden
-Commands for double and single angle quotation marks:
address@hidden@@address@hidden@}}, @code{@@address@hidden@}},
address@hidden@@address@hidden@}}, @code{@@address@hidden@}},
address@hidden@@address@hidden@}}, @code{@@address@hidden@}}.
address@hidden raggedright
-
-
address@hidden @t{@@noindent}
address@hidden @code{@@noindent}: Omitting Indentation
-
address@hidden@c old name
address@hidden noindent
address@hidden Omitting indentation
address@hidden Suppressing indentation
address@hidden Indentation, omitting
-
-An example or other inclusion can break a paragraph into segments.
-Ordinarily, the formatters indent text that follows an example as a new
-paragraph. You can prevent this on a case-by-case basis by writing
address@hidden@@noindent} at the beginning of a line, preceding the continuation
-text. You can also disable indentation for all paragraphs globally with
address@hidden@@paragraphindent} (@address@hidden@@paragraphindent}}).
-
-It is best to write @code{@@noindent} on a line by itself, since in most
-environments, spaces following the command will not be ignored. It's ok
-to use it at the beginning of a line, with text following, outside of
-any environment.
-
address@hidden 1500
-For example:
-
address@hidden
address@hidden
-@@example
-This is an example
-@@end example
-
-@@noindent
-This line is not indented. As you can see, the
-beginning of the line is fully flush left with the line
-that follows after it. (This whole example is between
-@@address@hidden@@@@address@hidden and @@address@hidden@@@@end address@hidden)
address@hidden group
address@hidden example
-
address@hidden produces:
-
address@hidden
-
address@hidden
-This is an example
address@hidden example
-
address@hidden
-This line is not indented. As you can see, the
-beginning of the line is fully flush left with the line
-that follows after it. (This whole example is between
address@hidden@@display} and @code{@@end display}.)
-
address@hidden display
-
-To adjust the number of blank lines properly in the Info file output,
-remember that the line containing @code{@@noindent} does not generate a
-blank line, and neither does the @code{@@end example} line.
-
-In the Texinfo source file for this manual, each line that says
-`produces' is preceded by @code{@@noindent}.
-
-Do not put braces after an @code{@@noindent} command; they are not
-necessary, since @code{@@noindent} is a command used outside of
-paragraphs (@pxref{Command Syntax}).
-
-
address@hidden @t{@@indent}
address@hidden @code{@@indent}: Forcing Indentation
-
address@hidden@c old name
address@hidden indent
address@hidden Forcing indentation
address@hidden Inserting indentation
address@hidden Indentation, forcing
-
address@hidden
-To complement the @code{@@noindent} command (see the previous
-section), Texinfo provides the @code{@@indent} command that forces a
-paragraph to be indented. This paragraph, for instance, is indented
-using an @code{@@indent} command. The first paragraph of a section is
-the most likely place to use @code{@@indent}, to override the normal
-behavior of no indentation there (@address@hidden@@paragraphindent}}).
-
-It is best to write @code{@@indent} on a line by itself, since in most
-environments, spaces following the command will not be ignored. The
address@hidden@@indent} line will not generate a blank line in the Info output
-within an environment.
-
-However, it is ok to use it at the beginning of a line, with text
-following, outside of any environment.
-
-Do not put braces after an @code{@@indent} command; they are not
-necessary, since @code{@@indent} is a command used outside of
-paragraphs (@pxref{Command Syntax}).
-
-
address@hidden @t{@@cartouche}
address@hidden @code{@@cartouche}: Rounded Rectangles
-
address@hidden@c old name
address@hidden cartouche
address@hidden Box with rounded corners
address@hidden Rounded rectangles, around text
-
-In a printed manual, the @code{@@cartouche} command draws a box with
-rounded corners around its contents. In HTML, a normal rectangle is
-drawn. @code{@@cartouche} has no effect in Info output.
-
-You can use this command to further highlight an example or quotation.
-For instance, you could write a manual in which one type of example is
-surrounded by a cartouche for emphasis.
-
-For example,
-
address@hidden
-@@cartouche
-@@example
-% pwd
-/usr/local/share/emacs
-@@end example
-@@end cartouche
address@hidden example
-
address@hidden
-surrounds the two-line example with a box with rounded corners, in the
-printed manual.
-
-The output from the example looks like this (if you're reading this in
-Info, you'll see the @code{@@cartouche} had no effect):
-
address@hidden
address@hidden
-% pwd
-/usr/local/info
address@hidden example
address@hidden cartouche
-
address@hidden@@cartouche} also implies @code{@@group}
(@address@hidden@@group}}).
-
-
address@hidden Lists and Tables
address@hidden Lists and Tables
address@hidden Making lists and tables
address@hidden Lists and tables, making
address@hidden Tables and lists, making
-
-Texinfo has several ways of making lists and tables. Lists can be
-bulleted or numbered; two-column tables can highlight the items in
-the first column; multi-column tables are also supported.
-
address@hidden
-* Introducing Lists:: Texinfo formats lists for you.
-* @t{@@itemize}:: How to construct a simple list.
-* @t{@@enumerate}:: How to construct a numbered list.
-* Two-column Tables:: How to construct a two-column table.
-* Multi-column Tables:: How to construct generalized tables.
address@hidden menu
-
address@hidden Introducing Lists
address@hidden Introducing Lists
-
-Texinfo automatically indents the text in lists or tables, and numbers
-an enumerated list. This last feature is useful if you modify the
-list, since you do not need to renumber it yourself.
-
-Numbered lists and tables begin with the appropriate @@-command at the
-beginning of a line, and end with the corresponding @code{@@end}
-command on a line by itself. The table and itemized-list commands
-also require that you write formatting information on the same line as
-the beginning @@-command.
-
-Begin an enumerated list, for example, with an @code{@@enumerate}
-command and end the list with an @code{@@end enumerate} command.
-Begin an itemized list with an @code{@@itemize} command, followed on
-the same line by a formatting command such as @code{@@bullet}, and end
-the list with an @code{@@end itemize} command.
address@hidden end
-
-Precede each element of a list with an @code{@@item} or @code{@@itemx}
-command.
-
address@hidden 1
address@hidden
-Here is an itemized list of the different kinds of table and lists:
-
address@hidden @bullet
address@hidden
-Itemized lists with and without bullets.
-
address@hidden
-Enumerated lists, using numbers or letters.
-
address@hidden
-Two-column tables with highlighting.
address@hidden itemize
-
address@hidden 1
address@hidden
-Here is an enumerated list with the same items:
-
address@hidden
address@hidden
-Itemized lists with and without bullets.
-
address@hidden
-Enumerated lists, using numbers or letters.
-
address@hidden
-Two-column tables with highlighting.
address@hidden enumerate
-
address@hidden 1
address@hidden
-And here is a two-column table with the same items and their
address@hidden@@-commands}:
-
address@hidden @code
address@hidden @@itemize
-Itemized lists with and without bullets.
-
address@hidden @@enumerate
-Enumerated lists, using numbers or letters.
-
address@hidden @@table
address@hidden @@ftable
address@hidden @@vtable
-Two-column tables, optionally with indexing.
address@hidden table
-
-
address@hidden @t{@@itemize}
address@hidden @code{@@itemize}: Making an Itemized List
-
address@hidden@c old name
address@hidden itemize
address@hidden Itemization
-
-The @code{@@itemize} command produces a sequence of ``items'', each
-starting with a bullet or other mark inside the left margin, and
-generally indented.
-
address@hidden @code{@@w}, for blank items
-Begin an itemized list by writing @code{@@itemize} at the beginning of
-a line. Follow the command, on the same line, with a character or a
-Texinfo command that generates a mark. Usually, you will use
address@hidden@@bullet} after @code{@@itemize}, but you can use
address@hidden@@minus}, or any command or character that results in a single
-character in the Info file. (When you write the mark command such as
address@hidden@@bullet} after an @code{@@itemize} command, you may omit the
address@hidden@address@hidden) If you don't specify a mark command, the
default is
address@hidden@@bullet}. If you don't want any mark at all, but still want
-logical items, use @code{@@address@hidden@}} (in this case the braces are
-required).
-
address@hidden item
-After the @code{@@itemize}, write your items, each starting with
address@hidden@@item}. Text can follow on the same line as the @code{@@item}.
-The text of an item can continue for more than one paragraph.
-
-There should be at least one @code{@@item} inside the @code{@@itemize}
-environment. If none are present, @code{makeinfo} gives a warning.
-If you just want indented text and not a list of items, use
address@hidden@@indentedblock}; @address@hidden@@indentedblock}}.
-
-Index entries and comments that are given before an @code{@@item}
-including the first, are automatically moved (internally) to after the
address@hidden@@item}, so the output is as expected. Historically this has
-been a common practice.
-
-Usually, you should put a blank line between items. This puts a blank
-line in the Info file. (@TeX{} inserts the proper vertical space in
-any case.) Except when the entries are very brief, these blank lines
-make the list look better.
-
-Here is an example of the use of @code{@@itemize}, followed by the
-output it produces. @code{@@bullet} produces an @samp{*} in Info and
-a round dot in other output formats.
-
address@hidden
address@hidden
-@@itemize @@bullet
-@@item
-Some text for foo.
-
-@@item
-Some text
-for bar.
-@@end itemize
address@hidden group
address@hidden example
-
address@hidden
-This produces:
-
address@hidden
address@hidden @bullet
address@hidden
-Some text for foo.
-
address@hidden
-Some text
-for bar.
address@hidden itemize
address@hidden quotation
-
-Itemized lists may be embedded within other itemized lists. Here is a
-list marked with dashes embedded in a list marked with bullets:
-
address@hidden
address@hidden
-@@itemize @@bullet
-@@item
-First item.
-
-@@itemize @@minus
-@@item
-Inner item.
-
-@@item
-Second inner item.
-@@end itemize
-
-@@item
-Second outer item.
-@@end itemize
address@hidden group
address@hidden example
-
address@hidden
-This produces:
-
address@hidden
address@hidden @bullet
address@hidden
-First item.
-
address@hidden @minus
address@hidden
-Inner item.
-
address@hidden
-Second inner item.
address@hidden itemize
-
address@hidden
-Second outer item.
address@hidden itemize
address@hidden quotation
-
-
address@hidden @t{@@enumerate}
address@hidden @code{@@enumerate}: Making a Numbered or Lettered List
-
address@hidden@c old name
address@hidden enumerate
address@hidden Enumeration
-
address@hidden@@enumerate} is like @code{@@itemize}
(@address@hidden@@itemize}}),
-except that the labels on the items are successive integers or letters
-instead of bullets.
-
-Write the @code{@@enumerate} command at the beginning of a line. The
-command does not require an argument, but accepts either a number or a
-letter as an option. Without an argument, @code{@@enumerate} starts the
-list with the number @samp{1}. With a numeric argument, such as
address@hidden, the command starts the list with that number. With an upper-
-or lowercase letter, such as @samp{a} or @samp{A}, the command starts
-the list with that letter.
-
-Write the text of the enumerated list in the same way as an itemized
-list: write a line starting with @code{@@item} at the beginning of
-each item in the enumeration. It is ok to have text following the
address@hidden@@item}, and the text for an item can continue for several
-paragraphs.
-
-You should put a blank line between entries in the list.
-This generally makes it easier to read the Info file.
-
address@hidden 1500
-Here is an example of @code{@@enumerate} without an argument:
-
address@hidden
address@hidden
-@@enumerate
-@@item
-Underlying causes.
-
-@@item
-Proximate causes.
-@@end enumerate
address@hidden group
address@hidden example
-
address@hidden
-This produces:
-
address@hidden
address@hidden
-Underlying causes.
-
address@hidden
-Proximate causes.
address@hidden enumerate
address@hidden 1
-Here is an example with an argument of @kbd{3}:
address@hidden 1
address@hidden
address@hidden
-@@enumerate 3
-@@item
-Predisposing causes.
-
-@@item
-Precipitating causes.
-
-@@item
-Perpetuating causes.
-@@end enumerate
address@hidden group
address@hidden example
-
address@hidden
-This produces:
-
address@hidden 3
address@hidden
-Predisposing causes.
-
address@hidden
-Precipitating causes.
-
address@hidden
-Perpetuating causes.
address@hidden enumerate
address@hidden 1
-Here is a brief summary of the alternatives. The summary is constructed
-using @code{@@enumerate} with an argument of @kbd{a}.
address@hidden 1
address@hidden a
address@hidden
address@hidden@@enumerate}
-
-Without an argument, produce a numbered list, starting with the
address@hidden
-
address@hidden
address@hidden@@enumerate @var{positive-integer}}
-
-With a (positive) numeric argument, start a numbered list with that
-number. You can use this to continue a list that you interrupted with
-other text.
-
address@hidden
address@hidden@@enumerate @var{upper-case-letter}}
-
-With an uppercase letter as argument, start a list
-in which each item is marked
-by a letter, beginning with that uppercase letter.
-
address@hidden
address@hidden@@enumerate @var{lower-case-letter}}
-
-With a lowercase letter as argument, start a list
-in which each item is marked by
-a letter, beginning with that lowercase letter.
address@hidden enumerate
-
-You can also nest enumerated lists, as in an outline.
-
-
address@hidden Two-column Tables
address@hidden Making a Two-column Table
-
address@hidden Tables, making two-column
address@hidden table
-
address@hidden@@table} is similar to @code{@@itemize}
-(@address@hidden@@itemize}}), but allows you to specify a name or
-heading line for each item. The @code{@@table} command is used to
-produce two-column tables, and is especially useful for glossaries,
-explanatory exhibits, and command-line option summaries.
-
address@hidden
-* @t{@@table}:: How to construct a two-column table.
-* @t{@@ftable @@vtable}:: Automatic indexing for two-column tables.
-* @t{@@itemx}:: How to put more entries in the first
column.
address@hidden menu
-
address@hidden @t{@@table}
address@hidden Using the @code{@@table} Command
-
address@hidden@c old name
-
address@hidden Definition lists, typesetting
-Use the @code{@@table} command to produce two-column tables. It is
-typically used when you have a list of items and a brief text with
-each one, such as ``definition lists''.
-
-Write the @code{@@table} command at the beginning of a line, after a
-blank line, and follow it on the same line with an argument that is a
-Texinfo ``indicating'' command such as @code{@@code}, @code{@@samp},
address@hidden@@var}, @code{@@option}, or @code{@@kbd} (@pxref{Indicating}).
-
-This command will be applied to the text that goes into the first
-column of each item and thus determines how it will be highlighted.
-For example, @code{@@table @@code} will cause the text in the first
-column to be output as if it had been the argument to an @code{@@code}
-command.
-
address@hidden@t{@@address@hidden command name with @, for consistency
address@hidden asis
-You may also use the @code{@@asis} command as an argument to
address@hidden@@table}. @code{@@asis} is a command that does nothing; if you
-use this command after @code{@@table}, the first column entries are
-output without added highlighting (``as is'').
-
-The @code{@@table} command works with other commands besides those
-explicitly mentioned here. However, you can only use predefined
-Texinfo commands that normally take an argument in braces. You cannot
-reliably use a new command defined with @code{@@macro}, but an
address@hidden@@alias} (for a suitable predefined command) is acceptable.
address@hidden New Texinfo Commands}.
-
address@hidden item
-Begin each table entry with an @code{@@item} command at the beginning
-of a line. Write the first column text on the same line as the
address@hidden@@item} command. Write the second column text on the line
-following the @code{@@item} line and on subsequent lines. (You do not
-need to type anything for an empty second column entry.) You may
-write as many lines of supporting text as you wish, even several
-paragraphs. But only the text on the same line as the @code{@@item}
-will be placed in the first column (including any footnotes).
-
-Normally, you should put a blank line before an @code{@@item} line
-(except the first one). This puts a blank line in the Info file.
-Except when the entries are very brief, a blank line looks better.
-
-End the table with a line consisting of @code{@@end table}, followed
-by a blank line. @TeX{} will always start a new paragraph after the
-table, so the blank line is needed for the Info output to be analogous.
-
address@hidden 1500
-The following table, for example, highlights the text in the first
-column with an @code{@@samp} command:
-
address@hidden
address@hidden
-@@table @@samp
-@@item foo
-This is the text for
-@@address@hidden@}.
-
-@@item bar
-Text for @@address@hidden@}.
-@@end table
address@hidden group
address@hidden example
-
address@hidden
-This produces:
-
address@hidden @samp
address@hidden foo
-This is the text for
address@hidden
address@hidden bar
-Text for @samp{bar}.
address@hidden table
-
-If you want to list two or more named items with a single block of
-text, use the @code{@@itemx} command. (@address@hidden@@itemx}}.)
-
-
address@hidden @t{@@ftable @@vtable}
address@hidden @code{@@ftable} and @code{@@vtable}
-
address@hidden address@hidden old name
address@hidden ftable
address@hidden vtable
address@hidden Tables with indexing
address@hidden Indexing table entries automatically
-
-The @code{@@ftable} and @code{@@vtable} commands are the same as the
address@hidden@@table} command except that @code{@@ftable} automatically enters
-each of the items in the first column of the table into the index of
-functions and @code{@@vtable} automatically enters each of the items in
-the first column of the table into the index of variables. This
-simplifies the task of creating indices. Only the items on the same
-line as the @code{@@item} commands are indexed, and they are indexed in
-exactly the form that they appear on that line. @xref{Indices},
-for more information about indices.
-
-Begin a two-column table using @code{@@ftable} or @code{@@vtable} by
-writing the @@-command at the beginning of a line, followed on the same
-line by an argument that is a Texinfo command such as @code{@@code},
-exactly as you would for an @code{@@table} command; and end the table
-with an @code{@@end ftable} or @code{@@end vtable} command on a line by
-itself.
-
-See the example for @code{@@table} in the previous section.
-
-
address@hidden @t{@@itemx}
address@hidden @code{@@itemx}: Second and Subsequent Items
-
address@hidden@c old name
address@hidden Two named items for @code{@@table}
address@hidden itemx
-
-Use the @code{@@itemx} command inside a table when you have two or more
-first column entries for the same item, each of which should appear on a
-line of its own.
-
-Use @code{@@item} for the first entry, and @code{@@itemx} for all
-subsequent entries; @code{@@itemx} must always follow an @code{@@item}
-command, with no blank line intervening.
-
-The @code{@@itemx} command works exactly like @code{@@item} except
-that it does not generate extra vertical space above the first column
-text. If you have multiple consecutive @code{@@itemx} commands, do
-not insert any blank lines between them.
-
-For example,
-
address@hidden
address@hidden
-@@table @@code
-@@item upcase
-@@itemx downcase
-These two functions accept a character or a string as
-argument, and return the corresponding uppercase (lowercase)
-character or string.
-@@end table
address@hidden group
address@hidden example
-
address@hidden
-This produces:
-
address@hidden @code
address@hidden upcase
address@hidden downcase
-These two functions accept a character or a string as
-argument, and return the corresponding uppercase (lowercase)
-character or string.
address@hidden table
-
address@hidden
-(Note also that this example illustrates multi-line supporting text in
-a two-column table.)
-
-
address@hidden Multi-column Tables
address@hidden @code{@@multitable}: Multi-column Tables
-
address@hidden multitable
address@hidden Tables, making multi-column
-
address@hidden@@multitable} allows you to construct tables with any number of
-columns, with each column having any width you like.
-
-You define the column widths on the @code{@@multitable} line itself, and
-write each row of the actual table following an @code{@@item} command,
-with columns separated by an @code{@@tab} command. Finally, @code{@@end
-multitable} completes the table. Details in the sections below.
-
address@hidden
-* Multitable Column Widths:: Defining multitable column widths.
-* Multitable Rows:: Defining multitable rows, with examples.
address@hidden menu
-
address@hidden Multitable Column Widths
address@hidden Multitable Column Widths
address@hidden Multitable column widths
address@hidden Column widths, defining for multitables
address@hidden Widths, defining multitable column
-
-You can define the column widths for a multitable in two ways: as
-fractions of the line length; or with a prototype row. Mixing the two
-methods is not supported. In either case, the widths are defined
-entirely on the same line as the @code{@@multitable} command.
-
address@hidden
address@hidden
address@hidden columnfractions
address@hidden Line length, column widths as fraction of
-To specify column widths as fractions of the line length, write
address@hidden@@columnfractions} and the decimal numbers (presumably less than
-1; a leading zero is allowed and ignored) after the
address@hidden@@multitable} command, as in:
-
address@hidden
-@@multitable @@columnfractions .33 .33 .33
address@hidden example
-
-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.
-
address@hidden
address@hidden Prototype row, column widths defined by
-To specify a prototype row, write the longest entry for each column
-enclosed in braces after the @code{@@multitable} command. For example:
-
address@hidden
-@@multitable @{some text for column address@hidden @{for column address@hidden
address@hidden example
-
address@hidden
-The first column will then have the width of the typeset `some text for
-column one', and the second column the width of `for column two'.
-
-The prototype entries need not appear in the table itself.
-
-Although we used simple text in this example, the prototype entries can
-contain Texinfo commands; markup commands such as @code{@@code} are
-particularly likely to be useful.
-
address@hidden enumerate
-
-
address@hidden Multitable Rows
address@hidden Multitable Rows
-
address@hidden Multitable rows
address@hidden Rows, of a multitable
-
address@hidden item
address@hidden tab
-After the @code{@@multitable} command defining the column widths (see
-the previous section), you begin each row in the body of a multitable
-with @code{@@item}, and separate the column entries with @code{@@tab}.
-Line breaks are not special within the table body, and you may break
-input lines in your source file as necessary.
-
address@hidden headitem
address@hidden Heading row, in table
address@hidden @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
-heading row is followed by a separator line made of dashes (@samp{-}
-characters).
-
address@hidden headitemfont
address@hidden Font for multitable heading rows
-The command @code{@@headitemfont} can be used in templates when the
-entries in an @code{@@headitem} row need to be used in a template. It
-is a synonym for @code{@@b}, but using @code{@@headitemfont} avoids
-any dependency on that particular font style, in case we provide a way
-to change it in the future.
-
-Here is a complete example of a multi-column table (the text is from
address@hidden GNU Emacs Manual}, @pxref{Split Window,, Splitting Windows,
-emacs, The GNU Emacs Manual}):
-
address@hidden
-@@multitable @@columnfractions .15 .45 .4
-@@headitem Key @@tab Command @@tab Description
-@@item C-x 2
-@@tab @@address@hidden@}
-@@tab Split the selected window into two windows,
-with one above the other.
-@@item C-x 3
-@@tab @@address@hidden@}
-@@tab Split the selected window into two windows
-positioned side by side.
-@@item C-Mouse-2
-@@tab
-@@tab In the mode line or scroll bar of a window,
-split that window.
-@@end multitable
address@hidden example
-
address@hidden produces:
-
address@hidden @columnfractions .15 .45 .4
address@hidden Key @tab Command @tab Description
address@hidden C-x 2
address@hidden @code{split-window-vertically}
address@hidden Split the selected window into two windows,
-with one above the other.
address@hidden C-x 3
address@hidden @code{split-window-horizontally}
address@hidden Split the selected window into two windows
-positioned side by side.
address@hidden C-Mouse-2
address@hidden
address@hidden In the mode line or scroll bar of a window,
-split that window.
address@hidden multitable
-
-
address@hidden Special Displays
address@hidden Special Displays
address@hidden Special displays
-
-The commands in this chapter allow you to write text that is specially
-displayed (output format permitting), outside of the normal document
-flow.
-
-One set of such commands is for creating ``floats'', that is, figures,
-tables, and the like, set off from the main text, possibly numbered,
-captioned, and/or referred to from elsewhere in the document. Images
-are often included in these displays.
-
-Another group of commands is for creating footnotes in Texinfo.
-
address@hidden
-* Floats:: Figures, tables, and the like.
-* Images:: Including graphics and images.
-* Footnotes:: Writing footnotes.
address@hidden menu
-
-
address@hidden Floats
address@hidden Floats
address@hidden Floats, in general
-
-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
-some similar type.
-
address@hidden Floating, not yet implemented
-A float is so-named because, in principle, it can be moved to the
-bottom or top of the current page, or to a following page, in the
-printed output. (Floating does not make sense in other output
-formats.) In the present version of Texinfo, however, this floating
-is unfortunately not yet implemented. Instead, the floating material
-is simply output at the current location, more or less as if it were
-an @code{@@group} (@address@hidden@@group}}).
-
address@hidden
-* @t{@@float}:: Producing floating material.
-* @t{@@caption @@shortcaption}:: Specifying descriptions for floats.
-* @t{@@listoffloats}:: A table of contents for floats.
address@hidden menu
-
-
address@hidden @t{@@float}
address@hidden @code{@@float} address@hidden,@var{label}]: Floating Material
-
address@hidden@c old name
address@hidden float
address@hidden Float environment
-
-To produce floating material, enclose the material you want to be
-displayed separate between @code{@@float} and @code{@@end float}
-commands, on lines by themselves.
-
-Floating material often uses @code{@@image} to display an
-already-existing graphic (@pxref{Images}), or @code{@@multitable} to
-display a table (@pxref{Multi-column Tables}). However, the contents
-of the float can be anything. Here's an example with simple text:
-
address@hidden
-@@float Figure,fig:ex1
-This is an example float.
-@@end float
address@hidden example
-
address@hidden And the output:
-
address@hidden Figure,fig:ex1
-This is an example float.
address@hidden float
-
-As shown in the example, @code{@@float} takes two arguments (separated
-by a comma), @var{type} and @var{label}. Both are optional.
-
address@hidden @var
address@hidden type
-Specifies the sort of float this is; typically a word such as
-``Figure'', ``Table'', etc. If this is not given, and @var{label} is,
-any cross referencing will simply use a bare number.
-
address@hidden label
-Specifies a cross reference label for this float. If given, this
-float is automatically given a number, and will appear in any
address@hidden@@listoffloats} output (@address@hidden@@listoffloats}}). Cross
-references to @var{label} are allowed.
-
address@hidden Floats, making unnumbered
address@hidden 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
address@hidden@@listoffloats} output or be cross-referenceable.
address@hidden table
-
address@hidden Ordinarily, you specify both @var{type} and @var{label}, to get a
-labeled and numbered float.
-
address@hidden Floats, numbering of
address@hidden 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
-simply counts 1, 2, 3, @dots{}, and is reset at each chapter. Each
-float type is counted independently.
-
-Floats within an @code{@@unnumbered}, or outside of any chapter, are
-simply numbered consecutively from 1.
-
-These numbering conventions are not, at present, changeable.
-
-
address@hidden @t{@@caption @@shortcaption}
address@hidden @code{@@caption} & @code{@@shortcaption}
-
address@hidden address@hidden old name
address@hidden caption
address@hidden shortcaption
address@hidden Captions, for floats
address@hidden Short captions, for lists of floats
-
-You may write an @code{@@caption} anywhere within an @code{@@float}
-environment, to define a caption for the float. It is not allowed in
-any other context. @code{@@caption} takes a single argument, enclosed
-in braces. Here's an example:
-
address@hidden
-@@float
-An example float, with caption.
-@@address@hidden for example address@hidden
-@@end float
address@hidden example
-
address@hidden The output is:
-
address@hidden
-An example float, with caption.
address@hidden for example float.}
address@hidden float
-
address@hidden@@caption} can appear anywhere within the float; it is not
-processed until the @code{@@end float}. The caption text is usually a
-sentence or two, but may consist of several paragraphs if necessary.
-
-In the output, the caption always appears below the float; this is not
-currently changeable. It is preceded by the float type and/or number,
-as specified to the @code{@@float} command (see the previous section).
-
-The @code{@@shortcaption} command likewise may be used only within
address@hidden@@float}, and takes a single argument in braces. The short
-caption text is used instead of the caption text in a list of floats
-(see the next section). Thus, you can write a long caption for the
-main document, and a short title to appear in the list of floats. For
-example:
-
address@hidden
-@@float
-... as above ...
-@@address@hidden for list of address@hidden
-@@end float
address@hidden example
-
-The text for @code{@@shortcaption} may not contain comments
-(@code{@@c}), verbatim text (@code{@@verb}), environments such as
address@hidden@@example}, footnotes (@code{@@footnote}) or other complex
-constructs. The same constraints apply to @code{@@caption} unless
-there is an @code{@@shortcaption}.
-
-
address@hidden @t{@@listoffloats}
address@hidden @code{@@listoffloats}: Tables of Contents for Floats
-
address@hidden@c old name
address@hidden listoffloats
address@hidden List of floats
address@hidden Floats, list of
address@hidden Table of contents, for floats
-
-You can write an @code{@@listoffloats} command to generate a list of
-floats for a given float type (@address@hidden@@float}}), analogous to
-the document's overall table of contents. Typically, it is written in
-its own @code{@@unnumbered} node to provide a heading and structure,
-rather like @code{@@printindex} (@pxref{Printing Indices & Menus}).
-
address@hidden@@listoffloats} takes one optional argument, the float type.
-Here's an example:
-
address@hidden
-@@node List of Figures
-@@unnumbered List of Figures
-@@listoffloats Figure
address@hidden example
-
address@hidden And the output from @code{@@listoffloats}:
-
address@hidden
address@hidden Figure
address@hidden display
-
-Without any argument, @code{@@listoffloats} generates a list of floats
-for which no float type was specified, i.e., no first argument to the
address@hidden@@float} command (@address@hidden@@float}}).
-
-Each line in the list of floats contains the float type (if any),
-the float number, and the caption, if any---the @code{@@shortcaption}
-argument, if it was specified, else the @code{@@caption} argument.
-In Info, the result is a menu where each float can be selected. In
-HTML, each line is a link to the float. In printed output, the page
-number is included.
-
-Unnumbered floats (those without cross reference labels) are omitted
-from the list of floats.
-
-
address@hidden Images
address@hidden Inserting Images
-
address@hidden Images, inserting
address@hidden Pictures, inserting
address@hidden image
-
-You can insert an image given in an external file with the
address@hidden@@image} command. Although images can be used anywhere,
-including the middle of a paragraph, we describe them in this chapter
-since they are most often part of a displayed figure or example.
-
address@hidden
-* Image Syntax::
-* Image Scaling::
address@hidden menu
-
-
address@hidden Image Syntax
address@hidden Image Syntax
-
-Here is the synopsis of the @code{@@image} command:
-
address@hidden
-@@address@hidden@address@hidden,} @address@hidden,} @address@hidden,}
@address@hidden, address@hidden@address@hidden
address@hidden example
-
address@hidden Formats for images
address@hidden Image formats
-The @var{filename} argument is mandatory, and must not have an
-extension, because the different processors support different formats:
-
address@hidden @bullet
address@hidden
address@hidden eps image format
address@hidden (DVI output) reads the file @address@hidden
-(Encapsulated PostScript format).
-
address@hidden
address@hidden address@hidden, and images}
address@hidden png image format
address@hidden jpeg image format
address@hidden pdf image inclusions
address@hidden reads @address@hidden, @address@hidden,
address@hidden@var{filename}.jpg}, or @address@hidden (in that
-order). It also tries uppercase versions of the extensions. The PDF
-format does not support EPS images, so such must be converted first.
-
address@hidden
-For Info, @code{makeinfo} includes @address@hidden verbatim
-(more or less as if it were in @code{@@verbatim}). The Info output
-may also include a reference to @address@hidden or
address@hidden@var{filename}.jpg}. (See below.)
-
address@hidden
-For HTML, @code{makeinfo} outputs a reference to
address@hidden@var{filename}.png}, @address@hidden,
address@hidden@var{filename}.jpeg} or @address@hidden (in that
-order). If none of those exist, it gives an error, and outputs a
-reference to @address@hidden anyway.
-
address@hidden
address@hidden SVG images, used in Docbook
-For Docbook, @code{makeinfo} outputs references to
address@hidden@var{filename}.eps}, @address@hidden
address@hidden@var{filename}.jpg}, @address@hidden,
address@hidden@var{filename}.png} and @address@hidden, for every
-file found. Also, @address@hidden is included verbatim, if
-present.
-
address@hidden
-For Info and HTML output, @code{makeinfo} uses the optional fifth
-argument @var{extension} to @code{@@image} for the filename extension,
-if it is specified and the file is found. Any leading period should
-be included in @var{extension}. For example:
-
address@hidden XPM image format
address@hidden
-@@address@hidden,,,,address@hidden
address@hidden example
-
address@hidden itemize
-
-If you want to install image files for use by Info readers too, we
-recommend putting them in a subdirectory like @address@hidden
-for a package @var{foo}. Copying the files into
address@hidden(infodir)/@var{foo}-figures/} should be done in your
address@hidden
-
-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}
-(@address@hidden@@titlefont @@center @@sp}}).
-
address@hidden Alt attribute for images
address@hidden Images, alternate text for
address@hidden - (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
address@hidden@@image}, if supplied. If not supplied, @code{makeinfo} uses
-the full file name of the image being displayed. The @var{alttext} is
-processed as Texinfo text, so special characters such as @samp{"} and
address@hidden<} and @samp{&} are escaped in the HTML output; also, you can
-get an empty @code{alt} string with @code{@@-} (a command that
-produces no output; @address@hidden@@- @@hyphenation}}).
-
-For Info output, the @code{alt} string is also processed as Texinfo
-text and output. In this case, @samp{\} is escaped as @samp{\\} and
address@hidden"} as @samp{\"}; no other escapes are done.
-
-In Info output, @code{makeinfo} writes a reference to the binary image
-file (trying @var{filename} suffixed with @address@hidden,
address@hidden@var{.extension}}, @file{.png}, or @file{.jpg}, in that order)
-if one exists. It also literally includes the @file{.txt} file if one
-exists. This way, Info readers which can display images (such as the
-Emacs Info browser, running under X) can do so, whereas Info readers
-which can only use text (such as the standalone Info reader) can
-display the textual version.
-
address@hidden @samp{^@@^H} for images in Info
-The implementation of this is to put the following construct into the
-Info output:
-
address@hidden
-^@@^H[image src="@var{binaryfile}" text="@var{txtfile}"
- alt="@var{alttext} ... ^@@^H]
address@hidden example
-
address@hidden where @samp{^@@} and @samp{^H} stand for the actual null and
-backspace control characters. If one of the files is not present, the
-corresponding argument is omitted.
-
-The reason for mentioning this here is that older Info browsers (this
-feature was introduced in Texinfo version 4.6) will display the above
-literally, which, although not pretty, should not be harmful.
-
-
address@hidden Image Scaling
address@hidden Image Scaling
-
address@hidden Images, scaling
address@hidden Scaling images
address@hidden Width of images
address@hidden Height of images
address@hidden Aspect ratio of images
address@hidden Distorting images
-The optional @var{width} and @var{height} arguments to the
address@hidden@@image} command (see the previous section) specify the size to
-which to scale the image. They are only taken into account in @TeX{}.
-If neither is specified, the image is presented in its natural size
-(given in the file); if only one is specified, the other is scaled
-proportionately; and if both are specified, both are respected, thus
-likely distorting the original image by changing its aspect ratio.
-
address@hidden Dimensions and image sizes
-The @var{width} and @var{height} may be specified using any valid @TeX{}
-dimension, namely:
-
address@hidden @asis
address@hidden pt
address@hidden Points (dimension)
-point (72.27pt = 1in)
address@hidden pc
address@hidden Picas
-pica (1pc = 12pt)
address@hidden bp
address@hidden Big points
-big point (72bp = 1in)
address@hidden in
address@hidden Inches
-inch
address@hidden cm
address@hidden Centimeters
-centimeter (2.54cm = 1in)
address@hidden mm
address@hidden Millimeters
-millimeter (10mm = 1cm)
address@hidden dd
address@hidden address@hidden points
address@hidden point (1157dd = 1238pt)
address@hidden cc
address@hidden Ciceros
-cicero (1cc = 12dd)
address@hidden sp
address@hidden Scaled points
-scaled point (65536sp = 1pt)
address@hidden table
-
address@hidden ridt.eps
-For example, the following will scale a file @file{ridt.eps} to one
-inch vertically, with the width scaled proportionately:
-
address@hidden
-@@address@hidden,,address@hidden
address@hidden example
-
address@hidden epsf.tex
-For @code{@@image} to work with @TeX{}, the file @file{epsf.tex} must be
-installed somewhere that @TeX{} can find it. (The standard location is
address@hidden@var{texmf}/tex/generic/dvips/epsf.tex}, where @var{texmf} is a
-root of your @TeX{} directory tree.) This file is included in the
-Texinfo distribution and is also available from
address@hidden://tug.org/tex/epsf.tex}, among other places.
-
address@hidden@@image} can be used within a line as well as for displayed
-figures. Therefore, if you intend it to be displayed, be sure to leave
-a blank line before the command, or the output will run into the
-preceding text.
-
-Image scaling is presently implemented only in @TeX{}, not in HTML or
-any other sort of output.
-
-
address@hidden Footnotes
address@hidden Footnotes
address@hidden Footnotes
address@hidden footnote
-
-A @dfn{footnote} is for a reference that documents or elucidates the
-primary address@hidden footnote should complement or expand upon the
-primary text, but a reader should not need to read a footnote to
-understand the primary text. For a thorough discussion of footnotes,
-see @cite{The Chicago Manual of Style}, which is published by the
-University of Chicago Press.} Footnotes are distracting; use them
-sparingly at most, and it is best to avoid them completely. Standard
-bibliographical references are better placed in a bibliography at the
-end of a document instead of in footnotes throughout.
-
address@hidden
-* Footnote Commands:: How to write a footnote in Texinfo.
-* Footnote Styles:: Controlling how footnotes appear in Info.
address@hidden menu
-
-
address@hidden Footnote Commands
address@hidden Footnote Commands
-
-In Texinfo, footnotes are created with the @code{@@footnote} command.
-This command is followed immediately by a left brace, then by the text
-of the footnote, and then by a terminating right brace. Footnotes may
-be of any length (they will be broken across pages if necessary), but
-are usually short. The template is:
-
address@hidden
-ordinary text@@address@hidden@var{text of address@hidden
address@hidden example
-
-As shown here, the @code{@@footnote} command should come right after the
-text being footnoted, with no intervening space; otherwise, the footnote
-marker might end up starting a line.
-
-For example, this clause is followed by a sample address@hidden
-is the sample footnote.}; in the Texinfo source, it looks like
-this:
-
address@hidden
address@hidden sample footnote@@address@hidden is the sample
address@hidden; in the Texinfo address@hidden
address@hidden example
-
-As you can see, the source includes two punctuation marks next to each
-other; in this case, @address@hidden;} is the sequence. This is normal (the
-first ends the footnote and the second belongs to the sentence being
-footnoted), so don't worry that it looks odd.
-
-In a printed manual or book, the reference mark for a footnote is a
-small, superscripted number; the text of the footnote appears at the
-bottom of the page, below a horizontal line.
-
-In Info, the reference mark for a footnote is a pair of parentheses
-with the footnote number between them, like this: @samp{(1)}. The
-reference mark is followed by a cross reference link to the footnote
-text if footnotes are put in separate nodes (@pxref{Footnote Styles}).
-
-In the HTML output, footnote references are generally marked with a
-small, superscripted number which is rendered as a hypertext link to
-the footnote text.
-
-By the way, footnotes in the argument of an @code{@@item} command for
-an @code{@@table} must be on the same line as the @code{@@item} (as
-usual). @xref{Two-column Tables}.
-
-
address@hidden Footnote Styles
address@hidden Footnote Styles
-
-Info has two footnote styles, which determine where the text of the
-footnote is located:
-
address@hidden @bullet
address@hidden @address@hidden node footnote style
address@hidden
-In the `End' node style, all the footnotes for a single node are
-placed at the end of that node. The footnotes are separated from the
-rest of the node by a line of dashes with the word @samp{Footnotes}
-within it. Each footnote begins with an @samp{(@var{n})} reference
-mark.
-
address@hidden 700
address@hidden
-Here is an example of the Info output for a single footnote in the
-end-of-node style:
-
address@hidden
address@hidden
---------- Footnotes ---------
-
-(1) Here is a sample footnote.
address@hidden group
address@hidden example
-
address@hidden @address@hidden footnote style
address@hidden
-In the `Separate' node style, all the footnotes for a single
-node are placed in an automatically constructed node of
-their own. In this style, a ``footnote reference'' follows
-each @samp{(@var{n})} reference mark in the body of the
-node. The footnote reference is actually a cross reference
-which you use to reach the footnote node.
-
-The name of the node with the footnotes is constructed
-by appending @address@hidden to the name of the node
-that contains the footnotes. (Consequently, the footnotes'
-node for the @file{Footnotes} node is
address@hidden@file{Footnotes-Footnotes}}!) The footnotes' node has an
-`Up' node pointer that leads back to its parent node.
-
address@hidden
-Here is how the first footnote in this manual looks after being
-formatted for Info in the separate node style:
-
address@hidden
address@hidden
-File: texinfo.info Node: Overview-Footnotes, Up: Overview
-
-(1) The first syllable of "Texinfo" is pronounced like "speck", not
-"hex". @dots{}
address@hidden group
address@hidden smallexample
address@hidden itemize
-
-Unless your document has long and important footnotes (as in, say,
-Gibbon's @cite{Decline and Fall @dots{}}), we recommend the @samp{end}
-style, as it is simpler for readers to follow.
-
address@hidden footnotestyle
-Use the @code{@@footnotestyle} command to specify an Info file's
-footnote style. Write this command at the beginning of a line followed
-by an argument, either @samp{end} for the end node style or
address@hidden for the separate node style.
-
address@hidden 700
-For example,
-
address@hidden
-@@footnotestyle end
address@hidden example
address@hidden
-or
address@hidden
-@@footnotestyle separate
address@hidden example
-
-Write an @code{@@footnotestyle} command before or shortly after the
-end-of-header line at the beginning of a Texinfo file. (You should
-include any @code{@@footnotestyle} command between the start-of-header
-and end-of-header lines, so the region formatting commands will format
-footnotes as specified.)
-
-In HTML, when the footnote style is @samp{end}, or if the output is
-not split, footnotes are put at the end of the output. If set to
address@hidden, and the output is split, they are placed in a
-separate file.
-
-
address@hidden Indices
address@hidden Indices
address@hidden Indices
-
-Using Texinfo, you can generate indices without having to sort and
-collate entries manually. In an index, the entries are listed in
-alphabetical order, together with information on how to find the
-discussion of each entry. In a printed manual, this information
-consists of page numbers. In an Info file, this information is a menu
-entry leading to the first node referenced.
-
-Texinfo provides several predefined kinds of index: an index for
-functions, an index for variables, an index for concepts, and so on.
-You can combine indices or use them for other than their canonical
-purpose. Lastly, you can define your own new indices.
-
address@hidden Indices & Menus}, for information on how to print
-indices.
-
address@hidden
-* Index Entries:: Choose different words for index entries.
-* Predefined Indices:: Use different indices for different kinds
- of entries.
-* Indexing Commands:: How to make an index entry.
-* Combining Indices:: How to combine indices.
-* New Indices:: How to define your own indices.
address@hidden menu
-
-
address@hidden Index Entries
address@hidden Making Index Entries
address@hidden Index entries, making
address@hidden Entries, making index
-
-When you are making index entries, it is good practice to think of the
-different ways people may look for something. Different people
address@hidden not} think of the same words when they look something up. A
-helpful index will have items indexed under all the different words
-that people may use. For example, one reader may think it obvious
-that the two-letter names for indices should be listed under
-``Indices, two-letter names, since ``Indices'' are the general
-concept. But another reader may remember the specific concept of
-two-letter names and search for the entry listed as ``Two letter names
-for indices''. A good index will have both entries and will help both
-readers.
-
-Like typesetting, the construction of an index is a skilled art, the
-subtleties of which may not be appreciated until you need to do it
-yourself.
-
address@hidden Indices & Menus}, for information about printing an
-index at the end of a book or creating an index menu in an Info file.
-
-
address@hidden Predefined Indices
address@hidden Predefined Indices
-
-Texinfo provides six predefined indices. Here are their nominal
-meanings, abbreviations, and the corresponding index entry commands:
-
address@hidden @samp
address@hidden cp
address@hidden @code{cp} (concept) index
address@hidden cindex
-(@code{@@cindex}) concept index, for general concepts.
address@hidden fn
address@hidden @code{fn} (function) index
address@hidden findex
-(@code{@@findex}) function index, for function and function-like
-names (such as entry points of libraries).
address@hidden ky
address@hidden @code{ky} (keystroke) index
address@hidden kindex
-(@code{@@kindex}) keystroke index, for keyboard commands.
address@hidden pg
address@hidden @code{pg} (program) index
address@hidden pindex
-(@code{@@pindex}) program index, for names of programs.
address@hidden tp
address@hidden @code{tp} (data type) index
address@hidden tindex
-(@code{@@tindex}) data type index, for type names (such as structures
-defined in header files).
address@hidden vr
address@hidden @code{vr} (variable) index
address@hidden vindex
-(@code{@@vindex}) variable index, for variable names (such as global
-variables of libraries).
address@hidden table
-
address@hidden
-Not every manual needs all of these, and most manuals use only two or
-three at most. The present manual, for example, has two indices: a
-concept index and an @@-command index (that is actually the function
-index but is called a command index in the chapter heading).
-
-You are not required to use the predefined indices strictly for their
-canonical purposes. For example, suppose you wish to index some C
-preprocessor macros. You could put them in the function index along
-with actual functions, just by writing @code{@@findex} commands for
-them; then, when you print the ``Function Index'' as an unnumbered
-chapter, you could give it the title `Function and Macro Index' and
-all will be consistent for the reader.
-
-On the other hand, it is best not to stray too far from the meaning of
-the predefined indices. Otherwise, in the event that your text is
-combined with other text from other manuals, the index entries will
-not match up. Instead, define your own new index (@pxref{New
-Indices}).
-
-We recommend having a single index in the final document whenever
-possible, however many source indices you use, since then readers have
-only one place to look. Two or more source indices can be combined
-into one output index using the @code{@@synindex} or
address@hidden@@syncodeindex} commands (@pxref{Combining Indices}).
-
-
address@hidden Indexing Commands
address@hidden Defining the Entries of an Index
-
address@hidden Defining indexing entries
address@hidden Index entries
address@hidden Entries for an index
address@hidden Specifying index entries
address@hidden Creating index entries
-
-The data to make an index come from many individual indexing commands
-scattered throughout the Texinfo source file. Each command says to add
-one entry to a particular index; after formatting, the index will give
-the current page number or node name as the reference.
-
-An index entry consists of an indexing command at the beginning of a
-line followed, on the rest of the line, by the entry.
-
-For example, this section begins with the following five entries for
-the concept index:
-
address@hidden
-@@cindex Defining indexing entries
-@@cindex Index entries, defining
-@@cindex Entries for an index
-@@cindex Specifying index entries
-@@cindex Creating index entries
address@hidden example
-
-Each predefined index has its own indexing address@hidden@@cindex}
-for the concept index, @code{@@findex} for the function index, and so
-on, as listed in the previous section.
-
address@hidden Writing index entries
address@hidden Index entries, advice on writing
address@hidden Advice on writing entries
address@hidden Capitalization of index entries
-Concept index entries consist of text. The best way to write an index
-is to devise entries which are terse yet clear. If you can do this,
-the index usually looks better if the entries are written just as they
-would appear in the middle of a sentence, that is, capitalizing only
-proper names and acronyms that always call for uppercase letters.
-This is the case convention we use in most GNU manuals' indices.
-
-If you don't see how to make an entry terse yet clear, make it longer
-and clear---not terse and confusing. If many of the entries are
-several words long, the index may look better if you use a different
-convention: to capitalize the first word of each entry. Whichever
-case convention you use, use it consistently.
-
-In any event, do not ever capitalize a case-sensitive name such as a C
-or Lisp function name or a shell command; that would be a spelling
-error. Entries in indices other than the concept index are symbol
-names in programming languages, or program names; these names are
-usually case-sensitive, so likewise use upper- and lowercase as
-required.
-
address@hidden Unique index entries
-It is a good idea to make index entries unique wherever feasible.
-That way, people using the printed output or online completion of
-index entries don't see undifferentiated lists. Consider this an
-opportunity to make otherwise-identical index entries be more
-specific, so readers can more easily find the exact place they are
-looking for.
-
-Index entries should precede the visible material that is being
-indexed. For instance:
-
address@hidden
-@@cindex hello
-Hello, there!
address@hidden example
-
address@hidden Among other reasons, that way following indexing links (in
-whatever context) ends up before the material, where readers want to
-be, instead of after.
-
address@hidden Index font types
-By default, entries for a concept index are printed in a small roman
-font and entries for the other indices are printed in a small
address@hidden@@code} font. You may change the way part of an entry is
-printed with the usual Texinfo commands, such as @code{@@file} for
-file names (@pxref{Marking Text}), and @code{@@r} for the normal roman
-font (@pxref{Fonts}).
-
address@hidden Caution
-Do not use a colon in an index entry. In Info, a colon separates the
-menu entry name from the node name, so a colon in the entry itself
-confuses Info. @xref{Menu Parts}, for more information about the
-structure of a menu entry.
address@hidden quotation
-
-
address@hidden Combining Indices
address@hidden Combining Indices
address@hidden Combining indices
address@hidden Indices, combining them
-
-Sometimes you will want to combine two disparate indices such as
-functions and concepts, perhaps because you have few enough entries
-that a separate index would look silly.
-
-You could put functions into the concept index by writing
address@hidden@@cindex} commands for them instead of @code{@@findex} commands,
-and produce a consistent manual by printing the concept index with the
-title `Function and Concept Index' and not printing the `Function
-Index' at all; but this is not a robust procedure. It works only if
-your document is never included as part of another document that is
-designed to have a separate function index; if your document were to
-be included with such a document, the functions from your document and
-those from the other would not end up together. Also, to make your
-function names appear in the right font in the concept index, you
-would need to enclose every one of them between the braces of
address@hidden@@code}.
-
address@hidden
-* @t{@@syncodeindex}:: How to merge two indices, using
@code{@@code}
- font for the merged-from index.
-* @t{@@synindex}:: How to merge two indices, using the
- roman font for the merged-from index.
address@hidden menu
-
-
address@hidden @t{@@syncodeindex}
address@hidden @code{@@syncodeindex}: Combining indices using @code{@@code}
-
address@hidden@c old name
address@hidden syncodeindex
-
-When you want to combine functions and concepts into one index, you
-should index the functions with @code{@@findex} and index the concepts
-with @code{@@cindex}, and use the @code{@@syncodeindex} command to
-redirect the function index entries into the concept index.
-
-The @code{@@syncodeindex} command takes two arguments; they are the name
-of the index to redirect, and the name of the index to redirect it to.
-The template looks like this:
-
address@hidden
-@@syncodeindex @var{from} @var{to}
address@hidden example
-
address@hidden Predefined names for indices
address@hidden Two letter names for indices
address@hidden Indices, two letter names
address@hidden Names for indices
-For this purpose, the indices are given two-letter names:
-
address@hidden @samp
address@hidden cp
-concept index
address@hidden fn
-function index
address@hidden vr
-variable index
address@hidden ky
-key index
address@hidden pg
-program index
address@hidden tp
-data type index
address@hidden table
-
-Write an @code{@@syncodeindex} command before or shortly after the
-end-of-header line at the beginning of a Texinfo file. For example,
-to merge a function index with a concept index, write the
-following:
-
address@hidden
-@@syncodeindex fn cp
address@hidden example
-
address@hidden
-This will cause 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
-index, write the following:
-
address@hidden
address@hidden
-@@syncodeindex vr cp
-@@syncodeindex fn cp
address@hidden group
address@hidden example
-
address@hidden Fonts for indices
-The @code{@@syncodeindex} command puts all the entries from the `from'
-index (the redirected index) into the @code{@@code} font, overriding
-whatever default font is used by the index to which the entries are
-now directed. This way, if you direct function names from a function
-index into a concept index, all the function names are printed in the
address@hidden@@code} font as you would expect.
-
-
address@hidden @t{@@synindex}
address@hidden @code{@@synindex}: Combining indices
-
address@hidden@c old name
address@hidden synindex
-
-The @code{@@synindex} command is nearly the same as the
address@hidden@@syncodeindex} command, except that it does not put the `from'
-index entries into the @code{@@code} font; rather it puts them in the
-roman font. Thus, you use @code{@@synindex} when you merge a concept
-index into a function index.
-
address@hidden Indices & Menus}, for information about printing an index
-at the end of a book or creating an index menu in an Info file.
-
-
address@hidden New Indices
address@hidden Defining New Indices
-
address@hidden Defining new indices
address@hidden Indices, defining new
address@hidden New index defining
address@hidden defindex
address@hidden defcodeindex
-
-In addition to the predefined indices (@pxref{Predefined Indices}),
-you may use the @code{@@defindex} and @code{@@defcodeindex} commands
-to define new indices. These commands create new indexing @@-commands
-with which you mark index entries. The @code{@@defindex} command is
-used like this:
-
address@hidden
-@@defindex @var{name}
address@hidden example
-
-New index names are usually two-letter words, such as @samp{au}.
-For example:
-
address@hidden
-@@defindex au
address@hidden example
-
-This defines a new index, called the @samp{au} index. At the same
-time, it creates a new indexing command, @code{@@auindex}, that you
-can use to make index entries. Use this new indexing command just as
-you would use a predefined indexing command.
-
-For example, here is a section heading followed by a concept index
-entry and two @samp{au} index entries.
-
address@hidden
-@@section Cognitive Semantics
-@@cindex kinesthetic image schemas
-@@auindex Johnson, Mark
-@@auindex Lakoff, George
address@hidden example
-
address@hidden
-(Evidently, @samp{au} serves here as an abbreviation for ``author''.)
-
-Texinfo constructs the new indexing command by concatenating the name
-of the index with @samp{index}; thus, defining an @samp{xy} index
-leads to the automatic creation of an @code{@@xyindex} command.
-
-Use the @code{@@printindex} command to print the index, as you do with
-the predefined indices. For example:
-
address@hidden
address@hidden
-@@node Author Index
-@@unnumbered Author Index
-
-@@printindex au
address@hidden group
address@hidden example
-
-The @code{@@defcodeindex} is like the @code{@@defindex} command,
-except that, in the printed output, it prints entries in an
address@hidden@@code} font by default instead of a roman font.
-
-You should define new indices before the end-of-header line of a
-Texinfo file, and (of course) before any @code{@@synindex} or
address@hidden@@syncodeindex} commands (@pxref{Texinfo File Header}).
-
-As mentioned earlier (@pxref{Predefined Indices}), we recommend having
-a single index in the final document whenever possible, however many
-source indices you use, since then readers have only one place to
-look.
-
-When creating an index, @TeX{} creates a file whose extension is the
-name of the index (@pxref{Names of index files}). Therefore you
-should avoid using index names that collide with extensions used for
-other purposes, such as @samp{.aux} or @samp{.xml}.
address@hidden already reports an error if a new index conflicts
-well-known extension name.
-
-
address@hidden Insertions
address@hidden Special Insertions
address@hidden Inserting special characters and symbols
address@hidden Special insertions
-
-Texinfo provides several commands for inserting characters that have
-special meaning in Texinfo, such as braces, and for other graphic
-elements that do not correspond to simple characters you can type.
-
address@hidden
-These are:
-
address@hidden @bullet
address@hidden The Texinfo special characters: @samp{@@ @address@hidden , \ #}.
address@hidden Whitespace within and around a sentence.
address@hidden Accents.
address@hidden Dots and bullets.
address@hidden The @TeX{} logo and the copyright symbol.
address@hidden The euro and pounds currency symbols.
address@hidden The degrees symbol.
address@hidden The minus sign.
address@hidden Mathematical expressions.
address@hidden Glyphs for examples of programming: evaluation, macros, errors,
etc.
address@hidden Footnotes.
address@hidden itemize
address@hidden iftex
-
address@hidden
-* Special Characters:: Inserting @@ @address@hidden , \ #
-* Inserting Quote Characters:: Inserting left and right quotes, in code.
-* Inserting Space:: Inserting the right amount of whitespace.
-* Inserting Accents:: Inserting accents and special characters.
-* Inserting Quotation Marks:: Inserting quotation marks.
-* Inserting Math:: Formatting mathematical expressions.
-* Glyphs for Text:: Inserting Dots, bullets, currencies, etc.
-* Glyphs for Programming:: Indicating results of evaluation,
- expansion of macros, errors, etc.
address@hidden menu
-
-
address@hidden Special Characters
address@hidden Special Characters: Inserting @@ @address@hidden , \ #
address@hidden address@hidden previous names for this node
address@hidden Braces Comma}
address@hidden Special characters, inserting
address@hidden Commands to insert special characters
-
address@hidden@@} and curly braces are the basic special characters in
-Texinfo. To insert these characters so they appear in text, you must
-put an @samp{@@} in front of these characters to prevent Texinfo from
-misinterpreting them. Alphabetic commands are also provided.
-
-The other characters (comma, backslash, hash) are special only in
-restricted contexts, as explained in the respective sections.
-
address@hidden
-* Inserting an Atsign:: @code{@@@@}, @code{@@address@hidden@}}.
-* Inserting Braces:: @code{@@@{ @@@}}, @code{@@l address@hidden@}}.
-* Inserting a Comma:: , and @code{@@address@hidden@}}.
-* Inserting a Backslash:: \ and @code{@@address@hidden@}}.
-* Inserting a Hashsign:: # and @code{@@address@hidden@}}.
address@hidden menu
-
-
address@hidden Inserting an Atsign
address@hidden Inserting `@@' with @code{@@@@} and @code{@@address@hidden@}}
address@hidden At sign, inserting
address@hidden Inserting @@ @r{(literal @samp{@@})}
address@hidden @@ @r{(literal @samp{@@})}
address@hidden @@address@hidden@} @r{(literal @samp{@@})}
-
address@hidden@@@@} produces a single @samp{@@} character in the output. Do
-not put braces after an @code{@@@@} command.
-
address@hidden@@address@hidden@}} also produces a single @samp{@@} character in
the
-output. It does need following braces, as usual for alphabetic
-commands. In inline conditionals (@pxref{Inline Conditionals}), it
-can be necessary to avoid using the literal @samp{@@} character in the
-source (and may be clearer in other contexts).
-
-
address@hidden Inserting Braces
address@hidden Inserting address@hidden address@hidden' with @code{@@@{ @@@}}
and @code{@@l address@hidden@}}
-
address@hidden @{ @r{(literal @address@hidden)}
address@hidden @} @r{(literal @address@hidden)}
address@hidden @@address@hidden@} @r{(literal @address@hidden)}
address@hidden @@address@hidden@} @r{(literal @address@hidden)}
address@hidden Braces, inserting
-
address@hidden@@@{} produces a single @address@hidden in the output, and
@code{@@@}}
-produces a single @address@hidden Do not put braces after either an
address@hidden@@@{} or an @code{@@@}} command.
-
address@hidden@@address@hidden@}} and @code{@@address@hidden@}} also produce
-single @address@hidden and @address@hidden characters in the output. They do
need
-following braces, as usual for alphabetic commands. In inline
-conditionals (@pxref{Inline Conditionals}), it can be
-necessary to avoid using literal brace characters in the source (and
-may be clearer in other contexts).
-
-
address@hidden Inserting a Comma
address@hidden Inserting `,' with @code{@@address@hidden@}}
-
address@hidden comma
address@hidden Comma, inserting
-
-Ordinarily, a comma `,' is a normal character that can be simply typed
-in your input where you need it.
-
-However, Texinfo uses the comma as a special character only in one
-context: to separate arguments to those Texinfo commands, such as
address@hidden@@acronym} (@address@hidden@@acronym}}) and @code{@@xref}
-(@pxref{Cross References}), as well as user-defined macros
-(@pxref{Defining Macros}), which take more than one argument.
-
-Since a comma character would confuse Texinfo's parsing for these
-commands, you must use the command @samp{@@address@hidden@}} instead if you
want
-to pass an actual comma. Here are some examples:
-
address@hidden
-@@address@hidden, A Bizarre @@address@hidden@address@hidden
-@@address@hidden,, The @@address@hidden@} address@hidden
-@@address@hidden argument@@address@hidden@} containing a address@hidden
address@hidden example
-
-Although @samp{@@address@hidden@}} can be used nearly anywhere, there is no
-need for it anywhere except in this unusual case.
-
-(Incidentally, the name @samp{@@comma} lacks the @samp{char} suffix used
-in its companion commands only for historical reasons. It didn't seem
-important enough to define a synonym.)
-
-
address@hidden Inserting a Backslash
address@hidden Inserting `\' with @code{@@address@hidden@}}
-
address@hidden backslash
address@hidden Backslash, inserting
-
-Ordinarily, a backslash `\' is a normal character in Texinfo that can
-be simply typed in your input where you need it. The result is to
-typeset the backslash from the typewriter font.
-
-However, Texinfo uses the backslash as a special character in one
-restricted context: to delimit formal arguments in the bodies of
-user-defined macros (@pxref{Defining Macros}).
-
-Due to the vagaries of macro argument parsing, it is more reliable to
-pass an alphabetic command that produces a backslash instead of using
-a literal \. Hence @code{@@address@hidden@}}. Here is an example
-macro call:
-
address@hidden
-@@address@hidden argument@@address@hidden@} with a address@hidden
address@hidden example
-
-Texinfo documents may also use \ as a command character inside
address@hidden@@math} (@pxref{Inserting Math}). In this case, @code{@@\} or
address@hidden produces a ``math'' backslash (from the math symbol
-font), while @code{@@address@hidden@}} produces a typewriter
-backslash as usual.
-
-Although @samp{@@address@hidden@}} can be used nearly anywhere, there
-is no need for it except in these unusual cases.
-
-
address@hidden Inserting a Hashsign
address@hidden Inserting `#' with @code{@@address@hidden@}}
-
address@hidden @@address@hidden@} @r{(literal @samp{#})}
address@hidden Inserting #
address@hidden Hash sign, inserting
-
-Ordinarily, a hash `#' is a normal character in Texinfo that can be
-simply typed in your input where you need it. The result is to
-typeset the hash character from the current font.
-
address@hidden Number sign, inserting
address@hidden Octotherp, inserting
address@hidden Sharp sign (not), inserting
-This character has many other names, varying by locale, such as
-``number sign'', ``pound'', and ``octothorp''. It is also sometimes
-called ``sharp'' or ``sharp sign'' since it vaguely resembles the
-musical symbol by that name. In situations where Texinfo is used,
-``hash'' is the most common in our experience.
-
-However, Texinfo uses the hash character as a special character in one
-restricted context: to introduce the so-called @code{#line} directive
-and variants (@pxref{External Macro Processors}).
-
-So, in order to typeset an actual hash character in such a place (for
-example, in a program that needs documentation about @code{#line}),
-it's necessary to use @code{@@address@hidden@}} or some other construct.
-Here's an example:
-
address@hidden
-@@address@hidden@} 10 "example.c"
address@hidden example
-
-Although @samp{@@address@hidden@}} can be used nearly anywhere, there
-is no need for it anywhere except this unusual case.
-
-
address@hidden Inserting Quote Characters
address@hidden Inserting Quote Characters
-
address@hidden Inserting quote characters
address@hidden Quote characters, inserting
-
-As explained in the early section on general Texinfo input conventions
-(@pxref{Conventions}), Texinfo source files use the ASCII character
address@hidden (96 decimal) to produce a left quote (`), and ASCII @code{'}
-(39 decimal) to produce a right quote ('). Doubling these input
-characters (@code{``} and @code{''}) produces double quotes (`` and
-''). These are the conventions used by @TeX{}.
-
-This works all right for text. However, in examples of computer code,
-readers are especially likely to cut and paste the text
-verbatim---and, unfortunately, some document viewers will mangle these
-characters. (The free PDF reader @command{xpdf} works fine, but other
-PDF readers, both free and nonfree, have problems.)
-
-If this is a concern for you, Texinfo provides these two commands:
-
address@hidden @code
address@hidden @@codequoteundirected @var{on-off}
address@hidden undirected single quote
-causes the output for the @code{'} character in code environments to
-be the undirected single quote, like this:
address@hidden txicodequoteundirected on
address@hidden'}.
address@hidden txicodequoteundirected off
-
address@hidden @@codequotebacktick @var{on-off}
address@hidden backtick
address@hidden grave accent, standalone
-causes the output for the @code{`} character in code environments to
-be the backtick character (standalone grave accent), like this:
address@hidden txicodequotebacktick on
address@hidden
address@hidden txicodequotebacktick off
address@hidden ftable
-
-If you want these settings for only part of the document,
address@hidden@@codequote... off} will restore the normal behavior, as in
address@hidden@@codequoteundirected off}.
-
-These settings affect @code{@@code}, @code{@@example}, @code{@@kbd},
address@hidden@@samp}, @code{@@verb}, and @code{@@verbatim}. @xref{Useful
-Highlighting}.
-
-This feature used to be controlled by @code{@@set} variable names;
-they are still supported, but the command interface is preferred.
-
-
address@hidden Inserting Space
address@hidden Inserting Space
-
address@hidden Inserting space
address@hidden Spacing, inserting
-The following sections describe commands that control spacing of various
-kinds within and after sentences.
-
address@hidden
-* Multiple Spaces:: Inserting multiple spaces.
-* Not Ending a Sentence:: Sometimes a . doesn't end a sentence.
-* Ending a Sentence:: Sometimes it does.
-* @t{@@frenchspacing}:: Specifying end-of-sentence spacing.
-* @t{@@dmn}:: Formatting a dimension.
address@hidden menu
-
-
address@hidden Multiple Spaces
address@hidden Multiple Spaces
-
address@hidden Multiple spaces
address@hidden Whitespace, inserting
address@hidden Space, inserting horizontal
address@hidden <space>
address@hidden <tab>
address@hidden <newline>
-
-Ordinarily, multiple whitespace characters (space, tab, and newline)
-are collapsed into a single space.
-
-Occasionally, you may want to produce several consecutive spaces,
-either for purposes of example (e.g., what your program does with
-multiple spaces as input), or merely for purposes of appearance in
-headings or lists. Texinfo supports three commands:
address@hidden@@@kbd{SPACE}}, @code{@@@kbd{TAB}}, and @code{@@@kbd{NL}}, all
-of which insert a single space into the output. (Here,
address@hidden@@@kbd{SPACE}} represents an @samp{@@} character followed by a
-space, i.e., @samp{@@ }, @kbd{TAB} represents an actual tab character,
-and @kbd{NL} represent the tab character and end-of-line, i.e., when
address@hidden@@} is the last character on a line.)
-
-For example,
address@hidden
-Spacey@@ @@ @@ @@
-example.
address@hidden example
-
address@hidden produces
-
address@hidden
-Spacey@ @ @ @
-example.
address@hidden example
-
-Other possible uses of @code{@@@kbd{SPACE}} have been subsumed by
address@hidden@@multitable} (@pxref{Multi-column Tables}).
-
-Do not follow any of these commands with braces.
-
-To produce a non-breakable space, see @address@hidden@@tie}}.
-
-
address@hidden Not Ending a Sentence
address@hidden Not Ending a Sentence
-
address@hidden Not ending a sentence
address@hidden Sentence non-ending punctuation
address@hidden Periods, inserting
address@hidden Spacing, in the middle of sentences
-Depending on whether a period or exclamation point or question mark is
-inside or at the end of a sentence, slightly less or more space is
-inserted after a period in a typeset manual. Since it is not always
-possible to determine automatically when a period ends a sentence,
-special commands are needed in some circumstances. Usually, Texinfo
-can guess how to handle periods, so you do not need to use the special
-commands; you just enter a period as you would if you were using a
-typewriter: put two spaces after the period, question mark, or
-exclamation mark that ends a sentence.
-
address@hidden <colon> @r{(suppress end-of-sentence space)}
-Use the @code{@@:}@: command after a period, question mark,
-exclamation mark, or colon that should not be followed by extra space.
-For example, use @code{@@:}@: after periods that end (lowercase)
-abbreviations which are not at the ends of sentences.
-
-Also, when a parenthetical remark in the middle of a sentence (like
-this one!)@: ends with a period, exclamation point, or question mark,
address@hidden@@:} should be used after the right parenthesis. Similarly for
-right brackets and right quotes (both single and double).
-
-For example,
-
address@hidden
-foo vs.@@: bar (or?)@@: baz
-foo vs. bar (or?) baz
address@hidden example
-
address@hidden
address@hidden
-produces
address@hidden ifnottex
address@hidden
-produces the following. If you look carefully at this printed output,
-you will see a bit of extraneous space after the @samp{vs.}@: and
address@hidden(or?)}@: in the second line.
address@hidden iftex
-
address@hidden
-foo vs.@: bar (or?)@: address@hidden
-foo vs. bar (or?) baz
address@hidden quotation
-
address@hidden
address@hidden@@:} has no effect on the HTML or Docbook output.
-
-Do not put braces after @code{@@:} (or any non-alphabetic command).
-
-A few Texinfo commands force normal interword spacing, so that you
-don't have to insert @code{@@:} where you otherwise would. These are
-the code-like highlighting commands, @code{@@var}, @code{@@abbr}, and
address@hidden@@acronym} (@pxref{Useful Highlighting}). For example, in
address@hidden@@address@hidden address@hidden the period is not considered the
end of a
-sentence, and no extra space is inserted.
-
-
address@hidden Ending a Sentence
address@hidden Ending a Sentence
-
address@hidden Ending a Sentence
address@hidden Sentence ending punctuation
-
address@hidden . @r{(end of sentence)}
address@hidden ! @r{(end of sentence)}
address@hidden ? @r{(end of sentence)}
address@hidden Spacing, at ends of sentences
-As mentioned above, Texinfo normally inserts additional space after
-the end of a sentence. It uses a simple heuristic for this: a
-sentence ends with a period, exclamation point, or question mark
-followed by optional closing punctuation and then whitespace, and
address@hidden preceded by a capital letter.
-
-Use @code{@@.}@: instead of a period, @code{@@!}@: instead of an
-exclamation point, and @code{@@?}@: instead of a question mark at the
-end of a sentence that does end with a capital letter. For example:
-
address@hidden
-Give it to M.I.B. and to M.E.W@@. Also, give it to R.J.C@@.
-Give it to M.I.B. and to M.E.W. Also, give it to R.J.C.
address@hidden example
-
address@hidden
-The output follows. In printed output and Info, you can see the
-desired extra whitespace after the @samp{W} in the first line.
-
address@hidden
-Give it to M.I.B. and to address@hidden Also, give it to address@hidden@*
-Give it to M.I.B. and to M.E.W. Also, give it to R.J.C.
address@hidden quotation
-
-In the HTML output, @code{@@.}@: is equivalent to a simple @samp{.};
-likewise for @code{@@!}@: and @code{@@?}@:.
-
-The meanings of @code{@@:} and @code{@@.}, etc.@: in Texinfo are
-designed to work well with the Emacs sentence motion commands
-(@pxref{Sentences,,, emacs, The GNU Emacs Manual}).
-
-Do not put braces after any of these commands.
-
-A few Texinfo commands are not considered as being an abbreviation,
-even though they may end with a capital letter when expanded, so that
-you don't have to insert @code{@@.} and companions. This is the case
-for code-like highlighting commands, @code{@@var} arguments ending
-with a capital letter, and @code{@@TeX}. For example, that sentence
-ended with @samp{@@address@hidden@@@@address@hidden; @code{@@.} was not
needed. Also
-in @code{... @@address@hidden@}. Text} the period after @var{VARNAME}
-ends the sentence; there is no need to use @code{@@.}.
-
-
address@hidden @t{@@frenchspacing}
address@hidden @code{@@frenchspacing} @var{val}: Control Sentence Spacing
-
address@hidden@c old name
address@hidden frenchspacing
address@hidden French spacing
address@hidden Sentences, spacing after
address@hidden Space, after sentences
-
-In American typography, it is traditional and correct to put extra
-space at the end of a sentence. This is the default in Texinfo
-(implemented in Info and printed output; for HTML, we don't try to
-override the browser). In French typography (and others), this extra
-space is wrong; all spaces are uniform.
-
-Therefore Texinfo provides the @code{@@frenchspacing} command to
-control the spacing after punctuation. It reads the rest of the line
-as its argument, which must be the single word @samp{on} or @samp{off}
-(always these words, regardless of the language of the document).
-Here is an example:
-
address@hidden
-@@frenchspacing on
-This is text. Two sentences. Three sentences. French spacing.
-
-@@frenchspacing off
-This is text. Two sentences. Three sentences. Non-French spacing.
address@hidden example
-
address@hidden produces:
-
address@hidden on
-This is text. Two sentences. Three sentences. French spacing.
-
address@hidden off
-This is text. Two sentences. Three sentences. Non-French spacing.
-
address@hidden@@frenchspacing} also affects the output after @code{@@.},
address@hidden@@!}, and @code{@@?} (@pxref{Ending a Sentence}).
-
address@hidden@@frenchspacing} has no effect on the HTML or Docbook output;
-for XML, it outputs a transliteration of itself (@pxref{Output
-Formats}).
-
-
address@hidden @t{@@dmn}
address@hidden @code{@@address@hidden@address@hidden: Format a Dimension
-
address@hidden@c old name
address@hidden Thin space between number, dimension
address@hidden Dimension formatting
address@hidden Format a dimension
address@hidden dmn
-
-You can use the @code{@@dmn} command to format a dimension with a
-little extra space in the printed output. That is, on seeing
address@hidden@@dmn}, @TeX{} inserts just enough space for proper typesetting;
-in other output formats, the formatting commands insert no space at
-all.
-
-To use the @code{@@dmn} command, write the number and then follow it
-immediately, with no intervening space, by @code{@@dmn}, and then by
-the dimension within braces. For example,
-
address@hidden
-A4 paper is 8.27@@address@hidden@} wide.
address@hidden example
-
address@hidden
-produces
-
address@hidden
-A4 paper is address@hidden wide.
address@hidden quotation
-
-Not everyone uses this style. Some people prefer address@hidden'@: or
address@hidden'. In these cases, however, you need to use
address@hidden@@tie} (@address@hidden@@tie}}) or @code{@@w}
(@address@hidden@@w}})
-so that no line break can occur between the number and the dimension.
-Also, if you write a period after an abbreviation within a sentence
-(as with the `in.'@: above), you should write @samp{@@:} after the
-period to prevent @TeX{} from inserting extra whitespace, as shown
-here. @xref{Not Ending a Sentence}.
-
-
address@hidden Inserting Accents
address@hidden Inserting Accents
-
address@hidden Inserting accents
address@hidden Accents, inserting
address@hidden Floating accents, inserting
-
-Here is a table with the commands Texinfo provides for inserting
-floating accents. They all need an argument, the character to accent,
-which can either be given in braces as usual (@code{@@'@address@hidden), or, as
-a special case, the braces can be omitted, in which case the argument
-is the next character (@code{@@'e}). This is to make the source as
-convenient as possible to type and read, since accented characters are
-very common in some languages.
-
-If the command is alphabetic, such as @code{@@dotaccent}, then there
-must be a space between the command name and argument if braces are
-not used. If the command is non-alphabetic, such as @code{@@'}, then
-there must @emph{not} be a space; the argument is the very next
-character.
-
-Exception: the argument to @code{@@tieaccent} must be enclosed in
-braces (since it is two characters instead of one).
-
address@hidden documentencoding
-To get the true accented characters output in Info, not just the ASCII
-transliterations, it is necessary to specify @code{@@documentencoding}
-with an encoding which supports the required characters
-(@address@hidden@@documentencoding}}). In this case, you can also use
-non-ASCII (e.g., pre-accented) characters in the source file.
-
address@hidden " @r{(umlaut accent)}
address@hidden Umlaut accent
address@hidden ' @r{(umlaut accent)}
address@hidden Acute accent
address@hidden = @r{(macron accent)}
address@hidden Macron accent
address@hidden ^ @r{(circumflex accent)}
address@hidden Circumflex accent
address@hidden ` @r{(grave accent)}
address@hidden Grave accent
address@hidden ~ @r{(tilde accent)}
address@hidden Tilde accent
address@hidden , @r{(cedilla accent)}
address@hidden Cedilla accent
address@hidden dotaccent
address@hidden Dot accent
address@hidden H @r{(Hungarian umlaut accent)}
address@hidden Hungarian umlaut accent
address@hidden ogonek
address@hidden Ogonek diacritic
address@hidden ringaccent
address@hidden Ring accent
address@hidden tieaccent
address@hidden Tie-after accent
address@hidden u @r{(breve accent)}
address@hidden Breve accent
address@hidden ubaraccent
address@hidden Underbar accent
address@hidden udotaccent
address@hidden Underdot accent
address@hidden v @r{(check accent)}
address@hidden Hacek accent
address@hidden Check accent
address@hidden Caron accent
address@hidden address@hidden@@address@hidden@}}} {Output} {hacek/check/caron
accent}
address@hidden Command @tab Output @tab What
address@hidden @t{@@"o} @tab @"o @tab umlaut accent
address@hidden @t{@@'o} @tab @'o @tab acute accent
address@hidden @t{@@,@address@hidden @tab @,{c} @tab cedilla
accent
address@hidden @t{@@=o} @tab @=o @tab macron/overbar
accent
address@hidden @t{@@^o} @tab @^o @tab circumflex accent
address@hidden @t{@@`o} @tab @`o @tab grave accent
address@hidden @t{@@~o} @tab @~o @tab tilde accent
address@hidden @t{@@address@hidden@}} @tab @dotaccent{o} @tab overdot accent
address@hidden @t{@@address@hidden@}} @tab @H{o} @tab long
Hungarian umlaut
address@hidden @t{@@address@hidden@}} @tab @ogonek{a} @tab ogonek
address@hidden @t{@@address@hidden@}} @tab @ringaccent{o} @tab ring accent
address@hidden @t{@@address@hidden@}} @tab @tieaccent{oo} @tab tie-after accent
address@hidden @t{@@address@hidden@}} @tab @u{o} @tab breve
accent
address@hidden @t{@@address@hidden@}} @tab @ubaraccent{o} @tab underbar accent
address@hidden @t{@@address@hidden@}} @tab @udotaccent{o} @tab underdot accent
address@hidden @t{@@address@hidden@}} @tab @v{o} @tab
hacek/check/caron accent
address@hidden multitable
-
-This table lists the Texinfo commands for inserting other characters
-commonly used in languages other than English.
-
address@hidden questiondown
address@hidden @questiondown{}
address@hidden exclamdown
address@hidden @exclamdown{}
address@hidden aa
address@hidden @aa{}
address@hidden AA
address@hidden @AA{}
address@hidden ae
address@hidden @ae{}
address@hidden AE
address@hidden @AE{}
address@hidden Icelandic
address@hidden Eth
address@hidden dh
address@hidden @dh{}
address@hidden DH
address@hidden @DH{}
address@hidden dotless
address@hidden @dotless{i} (dotless i)
address@hidden @dotless{j} (dotless j)
address@hidden Dotless i, j
address@hidden l
address@hidden @l{}
address@hidden L
address@hidden @L{}
address@hidden o
address@hidden @o{}
address@hidden O
address@hidden @O{}
address@hidden oe
address@hidden @oe{}
address@hidden OE
address@hidden @OE{}
address@hidden Romance ordinals
address@hidden Ordinals, Romance
address@hidden Feminine ordinal
address@hidden ordf
address@hidden @ordf{}
address@hidden Masculine ordinal
address@hidden ordm
address@hidden @ordm{}
address@hidden ss
address@hidden @ss{}
address@hidden Es-zet
address@hidden Sharp S
address@hidden German S
address@hidden Thorn
address@hidden th
address@hidden @th{}
address@hidden TH
address@hidden @TH{}
address@hidden address@hidden@@address@hidden@}}} {oe OE} {es-zet or sharp S}
address@hidden @t{@@address@hidden@}} @tab @exclamdown{} @tab
upside-down !
address@hidden @t{@@address@hidden@}} @tab @questiondown{} @tab upside-down ?
address@hidden @t{@@address@hidden@} @@address@hidden@}} @tab @aa{} @AA{}
@tab a,A with circle
address@hidden @t{@@address@hidden@} @@address@hidden@}} @tab @ae{} @AE{}
@tab ae,AE ligatures
address@hidden @t{@@address@hidden@} @@address@hidden@}} @tab @dh{} @DH{}
@tab Icelandic eth
address@hidden @t{@@address@hidden@}} @tab @dotless{i} @tab dotless i
address@hidden @t{@@address@hidden@}} @tab @dotless{j} @tab dotless j
address@hidden @t{@@address@hidden@} @@address@hidden@}} @tab @l{} @L{}
@tab suppressed-L,l
address@hidden @t{@@address@hidden@} @@address@hidden@}} @tab @o{} @O{}
@tab O,o with slash
address@hidden @t{@@address@hidden@} @@address@hidden@}} @tab @oe{} @OE{}
@tab oe,OE ligatures
address@hidden @t{@@address@hidden@} @@address@hidden@}} @tab @ordf{} @ordm{}
@tab Spanish ordinals
address@hidden @t{@@address@hidden@}} @tab @ss{} @tab
es-zet or sharp S
address@hidden @t{@@address@hidden@} @@address@hidden@}} @tab @th{} @TH{}
@tab Icelandic thorn
address@hidden multitable
-
-
address@hidden Inserting Quotation Marks
address@hidden Inserting Quotation Marks
address@hidden Inserting quotation marks
address@hidden Quotation marks, inserting
-
address@hidden Quotation characters (`'), in source
-Use doubled single-quote characters to begin and end quotations:
address@hidden@address@hidden@dots{}'@w{}'}}. @TeX{} converts two single
quotes to
-left- and right-hand doubled quotation marks,
address@hidden this comes out as "like this" in Info, which is just confusing.
address@hidden
-``like this'',
address@hidden iftex
-and Info converts doubled single-quote characters to ASCII
-double-quotes: @address@hidden@address@hidden'@w{}'}} becomes
@address@hidden"@dots{}"}}.
-
-You may occasionally need to produce two consecutive single quotes;
-for example, in documenting a computer language such as Maxima where
address@hidden'@w{}'} is a valid command. You can do this with the input
address@hidden'@@address@hidden@}'}; the empty @code{@@w} command stops the
combination into
-the double-quote characters.
-
address@hidden Unicode quotation characters
address@hidden Grave accent, 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.
-
-Texinfo supports several other quotation marks used in languages other
-than English. Below is a table with the commands Texinfo provides for
-inserting quotation marks.
-
address@hidden documentencoding
address@hidden UTF-8
address@hidden ISO 8859-15
address@hidden Latin 9
address@hidden ISO 8859-1
address@hidden Latin 1
-In order to get the symbols for the quotation marks in encoded Info
-output, it is necessary to specify @code{@@documentencoding UTF-8}.
-(@address@hidden@@documentencoding}}.) Double guillemets are also
-present in ISO 8859-1 (aka address@hidden) and ISO 8859-15 (aka
address@hidden).
-
address@hidden European Computer Modern fonts
address@hidden 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
-Computer Modern (EC) fonts (@file{ecrm1000} and other variants).
-These fonts are freely available, of course; you can download them
-from @url{http://@/www.ctan.org/@/tex-archive/@/fonts/ec}, among other
-places.
-
address@hidden CM-Super fonts
-The free EC fonts are bitmap fonts created with Metafont. Especially
-for on-line viewing, address@hidden (vector) versions of the fonts are
-preferable; these are available in the CM-Super font package
-(@url{http://@/www.ctan.org/@/tex-archive/@/fonts/@/ps-type1/@/cm-super}).
-
-Both distributions include installation instructions.
-
address@hidden Single quotation marks
address@hidden Double quotation marks
address@hidden Left quotation marks
address@hidden Right quotation marks
address@hidden quotedblleft
address@hidden address@hidden
address@hidden quoteleft
address@hidden `
address@hidden " (undirected double quote character)
address@hidden quotedblright
address@hidden '@w{}'
address@hidden quoteright
address@hidden '
address@hidden Double low-9 quotation mark
address@hidden Single low-9 quotation mark
address@hidden quotedblbase
address@hidden @quotedblbase{} (double low-9 quotation mark)
address@hidden quotesinglbase
address@hidden @quotesinglbase{} (single low-9 quotation mark)
address@hidden Angle quotation marks
address@hidden Guillemets
address@hidden Guillemots
address@hidden French quotation marks
address@hidden Quotation marks, French
address@hidden German quotation marks
address@hidden Quotation marks, German
address@hidden Double guillemets
address@hidden Single guillemets
address@hidden Double angle quotation marks
address@hidden Single angle quotation marks
address@hidden Left-pointing angle quotation marks
address@hidden Right-pointing angle quotation marks
address@hidden Double left-pointing angle quotation mark
address@hidden Double right-pointing angle quotation mark
address@hidden Single left-pointing angle quotation mark
address@hidden Single right-pointing angle quotation mark
address@hidden guillemetleft
address@hidden guillemotleft
address@hidden @guillemetleft{}
address@hidden guillemetright
address@hidden guillemotright
address@hidden @guillemetright{}
address@hidden guilsinglleft
address@hidden @guilsinglleft{}
address@hidden guilsinglright
address@hidden @guilsinglright{}
address@hidden address@hidden@@address@hidden@} '@w{}'}} {Glyph}
{Right-pointing double angle quotation mark (U+00BB)}
address@hidden Command @tab Glyph @tab Unicode
name (point)
address@hidden @address@hidden ``.} @tab @quotedblleft{} @tab Left double
quotation mark (U+201C)
address@hidden @address@hidden ''.} @tab @quotedblright{} @tab Right double
quotation mark (U+201D)
address@hidden @address@hidden `.} @tab @quoteleft{} @tab Left
single quotation mark (U+2018)
address@hidden @address@hidden '.} @tab @quoteright{} @tab Right
single quotation mark (U+2019)
address@hidden @t{@@address@hidden@}} @tab @quotedblbase{} @tab
Double low-9 quotation mark (U+201E)
address@hidden @t{@@address@hidden@}} @tab @quotesinglbase{} @tab Single
low-9 quotation mark (U+201A)
address@hidden @t{@@address@hidden@}} @tab @guillemetleft{} @tab
Left-pointing double angle quotation mark (U+00AB)
address@hidden @t{@@address@hidden@}} @tab @guillemetright{} @tab
Right-pointing double angle quotation mark (U+00BB)
address@hidden @t{@@address@hidden@}} @tab @guilsinglleft{} @tab Single
left-pointing angle quotation mark (U+2039)
address@hidden @t{@@address@hidden@}} @tab @guilsinglright{} @tab Single
right-pointing angle quotation mark (U+203A)
address@hidden multitable
-
address@hidden Auk, bird species
-For the double angle quotation marks, Adobe and @LaTeX{} glyph names
-are also supported: @code{@@guillemotleft} and
address@hidden@@guillemotright}. These names are incorrect; a
-``guillemot'' is a bird species (a type of auk).
-
-Traditions for quotation mark usage vary to a great extent between
-languages
-(@url{http://@/en.wikipedia.org/@/wiki/@/Quotation_mark%2C_non-English_usage@/#Overview}).
-Texinfo does not provide commands for typesetting quotation marks
-according to the numerous traditions. Therefore, you have to choose
-the commands appropriate for the language of your manual. Sometimes
-aliases (@address@hidden@@alias}}) can simplify the usage and make the
-source code more readable. For example, in German,
address@hidden@@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
-convenient:
-
address@hidden
-@@alias lgqq = quotedblbase
-@@alias rgqq = quotedblleft
address@hidden example
-
-
address@hidden Inserting Math
address@hidden @code{@@math}: Inserting Mathematical Expressions
-
address@hidden@c old name
address@hidden math
address@hidden Mathematical expressions, inserting
address@hidden Formulas, mathematical
-
-You can write a short mathematical expression with the @code{@@math}
-command. Write the mathematical expression between braces, like this:
-
address@hidden
-@@address@hidden(a + b)(a + b) = a^2 + 2ab + address@hidden
address@hidden example
-
address@hidden
address@hidden This produces the following in @TeX{}:
-
address@hidden
address@hidden(a + b)(a + b) = a^2 + 2ab + b^2}
address@hidden display
-
address@hidden and the following in other formats:
address@hidden iftex
address@hidden
address@hidden This produces the following in Info and HTML:
address@hidden ifnottex
-
address@hidden
-(a + b)(a + b) = a^2 + 2ab + b^2
address@hidden example
-
-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 produce good mathematical formatting in any
-way.
-
-However, as far as the @TeX{} output is concerned, plain @TeX{}
-mathematical commands are allowed in @code{@@math}, starting with
address@hidden, and the plain @TeX{} math characters like @samp{^} and
address@hidden are also recognized. In essence, @code{@@math} drops you
-into plain @TeX{} math mode.
-
-This allows you to conveniently write superscripts and subscripts (as
-in the above example), and also 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.
-
-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} allows input with matching (but
-unescaped) braces, such as @address@hidden@}}, although it complains
-about such bare braces in regular input.
-
-Here's an example:
-
address@hidden
-@@address@hidden 2\pi \equiv \cos address@hidden
address@hidden example
-
address@hidden
address@hidden which looks like this in @TeX{}:
address@hidden
address@hidden 2\pi \equiv \cos 3\pi}
address@hidden display
-
address@hidden and
address@hidden iftex
address@hidden which looks like the input in Info and HTML:
address@hidden
-\sin 2\pi \equiv \cos 3\pi
address@hidden example
-
address@hidden \ @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
address@hidden, but you'd get the literal two characters @samp{\\} in Info).
address@hidden@@\} is not defined outside of @code{@@math}, since a @samp{\}
-ordinarily produces a literal (typewriter) @samp{\}. You can also use
address@hidden@@address@hidden@}} in any mode to get a typewriter backslash.
address@hidden a Backslash}.
-
address@hidden Displayed equations
address@hidden Equations, displayed
-For displayed equations, you must at present use @TeX{} directly
-(@pxref{Raw Formatter Commands}).
-
-
address@hidden Glyphs for Text
address@hidden Glyphs for Text
-
address@hidden@c old name
address@hidden and address@hidden another old node, now split into two
address@hidden Glyphs for text
address@hidden Textual glyphs
-
-Texinfo has support for a few additional glyphs that are commonly used
-in printed text but not available in address@hidden Of course, there are
-many thousands more. It is possible to use Unicode characters as-is
-as far as @code{makeinfo} is concerned, but @TeX{} is not so lucky.
-
address@hidden
-* @t{@@TeX @@LaTeX}:: The @TeX{} logos.
-* @t{@@copyright}:: The copyright symbol (c in a circle).
-* @t{@@registeredsymbol}:: The registered symbol (R in a circle).
-* @t{@@dots}:: How to insert ellipses: @dots{} and
@enddots{}
-* @t{@@bullet}:: How to insert a bullet: @bullet{}
-* @t{@@euro}:: How to insert the euro currency symbol.
-* @t{@@pounds}:: How to insert the pounds currency symbol.
-* @t{@@textdegree}:: How to insert the degrees symbol.
-* @t{@@minus}:: How to insert a minus sign.
-* @t{@@geq @@leq}:: How to insert greater/less-than-or-equal
signs.
address@hidden menu
-
-
address@hidden @t{@@TeX @@LaTeX}
address@hidden @code{@@address@hidden@} (@TeX{}) and @code{@@address@hidden@}
(@LaTeX{})
-
address@hidden@c old name
address@hidden TeX
address@hidden LaTeX
address@hidden Logos, @TeX{}
address@hidden @TeX{} logo
address@hidden @LaTeX{} logo
-
-Use the @code{@@address@hidden@}} command to generate address@hidden'. In a
printed
-manual, this is a special logo that is different from three ordinary
-letters. In Info, it just looks like @samp{TeX}.
-
-Similarly, use the @code{@@address@hidden@}} command to generate
address@hidden',
-which is even more special in printed manuals (and different from the
-incorrect @code{La@@address@hidden@}}. In Info, the result is just
address@hidden (@LaTeX{} is another macro package built on top of
address@hidden, 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
-use both uppercase and lowercase letters.
-
-
address@hidden @t{@@copyright}
address@hidden @code{@@address@hidden@}} (@copyright{})
-
address@hidden address@hidden old name
address@hidden copyright
address@hidden Copyright symbol
-
-Use the @code{@@address@hidden@}} command to generate the copyright
-symbol, address@hidden'. Where possible, this is a @samp{c} inside a
-circle; in Info, this is @samp{(C)}.
-
-Legally, it's not necessary to use the copyright symbol; the English
-word `Copyright' suffices, according to international treaty.
-
-
address@hidden @t{@@registeredsymbol}
address@hidden @code{@@address@hidden@}} (@registeredsymbol{})
-
address@hidden address@hidden old name
address@hidden registeredsymbol
address@hidden Registered symbol
-
-Use the @code{@@address@hidden@}} command to generate the
-registered symbol, address@hidden'. Where possible, this is an
address@hidden inside a circle; in Info, this is @samp{(R)}.
-
-
address@hidden @t{@@dots}
address@hidden @code{@@dots} (@dots{}) and @code{@@enddots} (@enddots{})
-
address@hidden@c old name
address@hidden dots
address@hidden enddots
address@hidden Inserting dots
address@hidden Inserting ellipsis
address@hidden Dots, inserting
address@hidden Ellipsis, inserting
-
address@hidden address@hidden old name
-
-An @dfn{ellipsis} (a sequence of dots) would be spaced wrong when
-typeset as a string of periods, so a special command is used in
-Texinfo: use the @code{@@address@hidden@}} command to generate a normal
-ellipsis, which is three dots in a row, appropriately spaced @dots{}
-like so. To emphasize: do not simply write three periods in the input
-file; that would work for the Info file output, but would produce the
-wrong amount of space between the periods in the printed manual.
-
-The @code{@@address@hidden@}} command generates an end-of-sentence
-ellipsis, which also has three dots, but with different spacing
-afterwards, @enddots{} Look closely to see the difference.
-
-Here is an ellipsis: @dots{}
-Here are three periods in a row: ...
-
-In printed (and usually HTML) output, the three periods in a row are
-much closer together than the dots in the ellipsis.
-
-
address@hidden @t{@@bullet}
address@hidden @code{@@bullet} (@bullet{})
-
address@hidden@c old name
address@hidden bullet
-
-Use the @code{@@address@hidden@}} command to generate a large round dot, or
-the closest possible thing to one. In Info, an asterisk is used.
-Here is a bullet: @bullet{}
-
-When you use @code{@@bullet} in @code{@@itemize}, you do not need to
-type the braces, because @code{@@itemize} supplies them.
-(@address@hidden@@itemize}}).
-
-
address@hidden @t{@@euro}
address@hidden @code{@@euro} (@euro{}): Euro Currency Symbol
-
address@hidden@c old name
address@hidden euro
address@hidden Euro symbol
-
-Use the @code{@@address@hidden@}} command to generate address@hidden'. Where
-possible, this is the symbol for the Euro currency. Otherwise, the
-word @samp{Euro} is used.
-
-Texinfo cannot magically synthesize support for the Euro symbol where
-the underlying system (fonts, software, whatever) does not support it.
-Therefore, you may find it preferable to use the word ``Euro''. (In
-banking contexts, the abbreviation for the Euro is EUR.)
-
address@hidden ISO 8859-15, and Euro
address@hidden Latin 9, and Euro
-In order to get the Euro symbol in encoded Info output, for example,
-it is necessary to specify @code{@@documentencoding ISO-8859-15} or
address@hidden@@documentencoding UTF-8} (@address@hidden@@documentencoding}}.)
-The Euro symbol is in ISO 8859-15 (aka address@hidden), and is
address@hidden in the more widely-used ISO 8859-1 (address@hidden).
-
address@hidden feymr10
address@hidden Euro font
-The Euro symbol does not exist in the standard @TeX{} fonts (which
-were designed before the Euro was legislated into existence).
-Therefore, @TeX{} uses an additional font, named @code{feymr10} (along
-with other variables). It is freely available, of course; you can
-download it from @url{http://www.ctan.org/tex-archive/fonts/eurosym},
-among other places. The distribution includes installation
-instructions.
-
-
address@hidden @t{@@pounds}
address@hidden @code{@@pounds} (@pounds{}): Pounds Sterling
-
address@hidden@c old name
address@hidden pounds
address@hidden Pounds symbol
-
-Use the @code{@@address@hidden@}} command to generate address@hidden'. Where
-possible, this is the symbol for the pounds sterling British currency.
-Otherwise, it is @samp{#}.
-
-
address@hidden @t{@@textdegree}
address@hidden @code{@@textdegree} (@textdegree{}): Degrees Symbol
-
address@hidden@c old name
address@hidden textdegree
address@hidden Degree symbol
-
-Use the @code{@@address@hidden@}} command to generate address@hidden'.
-Where possible, this is the normal symbol for degrees. Otherwise,
-it is an @samp{o}.
-
-
address@hidden @t{@@minus}
address@hidden @code{@@minus} (@minus{}): Inserting a Minus Sign
-
address@hidden@c old name
address@hidden minus
address@hidden Minus sign
-
address@hidden Em dash, compared to minus sign
address@hidden Hyphen, compared to minus
-Use the @code{@@address@hidden@}} command to generate a minus sign. In a
-fixed-width font, this is a single hyphen, but in a proportional font,
-the symbol is the customary length for a minus sign---a little longer
-than a hyphen, shorter than an em-dash:
-
address@hidden
address@hidden@minus{}} is a minus sign generated with
@samp{@@address@hidden@}},
-
-`-' is a hyphen generated with the character @samp{-},
-
-`---' is an em-dash for text.
address@hidden display
-
address@hidden
-In the fixed-width font used by Info, @code{@@address@hidden@}} is the same
-as a hyphen.
-
-You should not use @code{@@address@hidden@}} inside @code{@@code} or
address@hidden@@example} because the width distinction is not made in the
-fixed-width font they use.
-
-When you use @code{@@minus} to specify the mark beginning each entry
-in an itemized list, you do not need to type the braces
-(@address@hidden@@itemize}}).
-
-If you actually want to typeset some math that does a subtraction, it
-is better to use @code{@@math}. Then the regular @samp{-} character
-produces a minus sign, as in @code{@@address@hidden@}} (@pxref{Inserting
-Math}).
-
-
address@hidden @t{@@geq @@leq}
address@hidden @code{@@geq} (@geq{}) and @code{@@leq} (@leq{}): Inserting
Relations
-
address@hidden address@hidden old name
address@hidden geq
address@hidden leq
-
-Use the @code{@@address@hidden@}} and @code{@@address@hidden@}} commands to
generate
-greater-than-or-equal and less-than-equal-signs, address@hidden' and
address@hidden'. When those symbols are not available, the ASCII sequences
address@hidden>=} and @samp{<=} are output.
-
-
address@hidden Glyphs for Programming
address@hidden Glyphs for Programming
-
address@hidden Glyphs for programming
address@hidden Examples, glyphs for
address@hidden Programming, glyphs for
-
-In Texinfo, code is often illustrated in examples that are delimited
-by @code{@@example} and @code{@@end example}, or by @code{@@lisp} and
address@hidden@@end lisp}. In such examples, you can indicate the results of
-evaluation or an expansion using @address@hidden or
address@hidden@expansion{}}. Likewise, there are commands to insert glyphs to
-indicate printed output, error messages, equivalence of expressions,
-the location of point in an editor, and GUI operation sequences.
-
-The glyph-insertion commands do not need to be used within an example,
-but most often they are. All glyph-insertion commands are followed by
-empty braces.
-
address@hidden
-* Glyphs Summary::
-* @t{@@result}:: How to show the result of expression.
-* @t{@@expansion}:: How to indicate an expansion.
-* @t{@@print}:: How to indicate generated output.
-* @t{@@error}:: How to indicate an error message.
-* @t{@@equiv}:: How to indicate equivalence.
-* @t{@@point}:: How to indicate the location of point.
-* Click Sequences:: Inserting GUI usage sequences.
address@hidden menu
-
-
address@hidden Glyphs Summary
address@hidden Glyphs Summary
-
-Here is a summary of the glyph commands:
-
address@hidden @asis
address@hidden @result{}
address@hidden@@address@hidden@}} indicates the result of an expression.
-
address@hidden @expansion{}
address@hidden@@address@hidden@}} indicates the results of a macro expansion.
-
address@hidden @print{}
address@hidden@@address@hidden@}} indicates printed output.
-
address@hidden @error{}
address@hidden@@address@hidden@}} indicates the following text is an error
message.
-
address@hidden @equiv{}
address@hidden@@address@hidden@}} indicates the exact equivalence of two forms.
-
address@hidden @point{}
address@hidden@@address@hidden@}} shows the location of point.
-
address@hidden @clicksequence{A @click{} B}
address@hidden@@address@hidden @@address@hidden@} B} indicates a GUI operation
-sequence: first A, then clicking B, or choosing B from a menu, or
-otherwise selecting it.
address@hidden table
-
-
address@hidden @t{@@result}
address@hidden @code{@@address@hidden@}} (@result{}): Result of an Expression
-
address@hidden@c old name
address@hidden result
address@hidden Result of an expression
address@hidden Indicating evaluation
address@hidden Evaluation glyph
address@hidden Value of an expression, indicating
-
-Use the @code{@@address@hidden@}} command to indicate the result of
-evaluating an expression.
-
-The @code{@@address@hidden@}} command is displayed as @address@hidden,
-either a double stemmed arrow or (when that is not available) the
-ASCII sequence @samp{=>}.
-
-Thus, the following,
-
address@hidden
-(cdr '(1 2 3))
- @result{} (2 3)
address@hidden lisp
-
address@hidden
-may be read as address@hidden(cdr '(1 2 3))} evaluates to @code{(2 3)}''.
-
-
address@hidden @t{@@expansion}
address@hidden @code{@@address@hidden@}} (@expansion{}): Indicating an Expansion
-
address@hidden@c old name
address@hidden Expansion, indicating
address@hidden Macro expansion, indicating
address@hidden expansion
-
-When an expression is a macro call, it expands into a new expression.
-You can indicate the result of the expansion with the
address@hidden@@address@hidden@}} command.
-
-The @code{@@address@hidden@}} command is displayed as
address@hidden@expansion{}}, either a long arrow with a flat base or (when
-that is not available) the ASCII sequence @samp{==>}.
-
address@hidden 700
-For example, the following
-
address@hidden
address@hidden
-@@lisp
-(third '(a b c))
- @@address@hidden@} (car (cdr (cdr '(a b c))))
- @@address@hidden@} c
-@@end lisp
address@hidden group
address@hidden example
-
address@hidden
-produces
-
address@hidden
address@hidden
-(third '(a b c))
- @expansion{} (car (cdr (cdr '(a b c))))
- @result{} c
address@hidden group
address@hidden lisp
-
address@hidden
-which may be read as:
-
address@hidden
address@hidden(third '(a b c))} expands to @code{(car (cdr (cdr '(a b c))))};
-the result of evaluating the expression is @code{c}.
address@hidden quotation
-
address@hidden
-Often, as in this case, an example looks better if the
address@hidden@@address@hidden@}} and @code{@@address@hidden@}} commands are
indented.
-
-
address@hidden @t{@@print}
address@hidden @code{@@address@hidden@}} (@print{}): Indicating Generated Output
-
address@hidden address@hidden old name
address@hidden print
address@hidden Printed output, indicating
-
-Sometimes an expression will generate output during its execution.
-You can indicate such displayed output with the @code{@@address@hidden@}}
-command.
-
-The @code{@@address@hidden@}} command is displayed as @address@hidden, either
-a horizontal dash butting against a vertical bar or (when that is not
-available) the ASCII sequence @samp{-|}.
-
-In the following example, the printed text is indicated with
address@hidden@print{}}, and the value of the expression follows on the
-last line.
-
address@hidden
address@hidden
-(progn (print 'foo) (print 'bar))
- @print{} foo
- @print{} bar
- @result{} bar
address@hidden group
address@hidden lisp
-
address@hidden
-In a Texinfo source file, this example is written as follows:
-
address@hidden
address@hidden
-@@lisp
-(progn (print 'foo) (print 'bar))
- @@address@hidden@} foo
- @@address@hidden@} bar
- @@address@hidden@} bar
-@@end lisp
address@hidden group
address@hidden lisp
-
-
address@hidden @t{@@error}
address@hidden @code{@@address@hidden@}} (@error{}): Indicating an Error Message
-
address@hidden address@hidden old name
address@hidden Error message, indicating
address@hidden error
-
-A piece of code may cause an error when you evaluate it. You can
-designate the error message with the @code{@@address@hidden@}} command.
-
-The @code{@@address@hidden@}} command is displayed as @address@hidden, either
-the word `error' in a box in the printed output, the word error
-followed by an arrow in other formats or (when no arrow is available)
address@hidden>}.
-
address@hidden 700
-Thus,
-
address@hidden
-@@lisp
-(+ 23 'x)
-@@address@hidden@} Wrong type argument: integer-or-marker-p, x
-@@end lisp
address@hidden example
-
address@hidden
-produces
-
address@hidden
-(+ 23 'x)
address@hidden Wrong type argument: integer-or-marker-p, x
address@hidden lisp
-
address@hidden
-This indicates that the following error message is printed
-when you evaluate the expression:
-
address@hidden
-Wrong type argument: integer-or-marker-p, x
address@hidden lisp
-
-The word @address@hidden itself is not part of the error message.
-
-
address@hidden @t{@@equiv}
address@hidden @code{@@address@hidden@}} (@equiv{}): Indicating Equivalence
-
address@hidden@c oldname
address@hidden Equivalence, indicating
address@hidden equiv
-
-Sometimes two expressions produce identical results. You can indicate
-the exact equivalence of two forms with the @code{@@address@hidden@}}
-command. The @code{@@address@hidden@}} command is displayed as
address@hidden@equiv{}}, either a standard mathematical equivalence sign
-(three parallel horizontal lines) or (when that is not available) as
-the ASCII sequence @samp{==}.
-
-Thus,
-
address@hidden
-@@lisp
-(make-sparse-keymap) @@address@hidden@} (list 'keymap)
-@@end lisp
address@hidden example
-
address@hidden
-produces
-
address@hidden
-(make-sparse-keymap) @equiv{} (list 'keymap)
address@hidden lisp
-
address@hidden
-This indicates that evaluating @code{(make-sparse-keymap)} produces
-identical results to evaluating @code{(list 'keymap)}.
-
-
address@hidden @t{@@point}
address@hidden @code{@@address@hidden@}} (@point{}): Indicating Point in a
Buffer
-
address@hidden address@hidden old name
address@hidden Point, indicating in a buffer
address@hidden point
-
-Sometimes you need to show an example of text in an Emacs buffer. In
-such examples, the convention is to include the entire contents of the
-buffer in question between two lines of dashes containing the buffer
-name.
-
-You can use the @samp{@@address@hidden@}} command to show the location of
-point in the text in the buffer. (The symbol for point, of course, is
-not part of the text in the buffer; it indicates the place
address@hidden two characters where point is located.)
-
-The @code{@@address@hidden@}} command is displayed as @address@hidden, either
-a pointed star or (when that is not available) the ASCII sequence
address@hidden
-
-The following example shows the contents of buffer @file{foo} before
-and after evaluating a Lisp command to insert the word @code{changed}.
-
address@hidden
address@hidden
----------- Buffer: foo ----------
-This is the @point{}contents of foo.
----------- Buffer: foo ----------
-
address@hidden group
address@hidden example
-
address@hidden
address@hidden
-(insert "changed ")
- @result{} nil
----------- Buffer: foo ----------
-This is the changed @point{}contents of foo.
----------- Buffer: foo ----------
-
address@hidden group
address@hidden example
-
-In a Texinfo source file, the example is written like this:
-
address@hidden
-@@example
----------- Buffer: foo ----------
-This is the @@address@hidden@}contents of foo.
----------- Buffer: foo ----------
-
-(insert "changed ")
- @@address@hidden@} nil
----------- Buffer: foo ----------
-This is the changed @@address@hidden@}contents of foo.
----------- Buffer: foo ----------
-@@end example
address@hidden example
-
-
address@hidden Click Sequences
address@hidden Click Sequences
-
address@hidden Click sequences
address@hidden Sequence of clicks
address@hidden GUI click sequence
-
address@hidden clicksequence
-When documenting graphical interfaces, it is necessary to describe
-sequences such as `Click on @samp{File}, then choose @samp{Open}, then
address@hidden'. Texinfo offers commands @code{@@clicksequence} and
address@hidden to represent this, typically used like this:
-
address@hidden
address@hidden @@address@hidden @@address@hidden@} address@hidden @dots{}
address@hidden example
-
address@hidden
-which produces:
-
address@hidden
address@hidden @clicksequence{File @click{} Open} @dots{}
address@hidden display
-
address@hidden click
address@hidden arrow
-The @code{@@click} command produces a right arrow by default; this
-glyph is also available independently via the command
address@hidden@@address@hidden@}}.
-
address@hidden clickstyle
-You can change the glyph produced by @code{@@click} with the command
address@hidden@@clickstyle}, which takes a command name as its single argument
-on the rest of the line, much like @code{@@itemize} and friends
-(@address@hidden@@itemize}}). The command should produce a glyph, and
-the usual empty braces @address@hidden@}} are omitted. Here's an example:
-
address@hidden
-@@clickstyle @@result
address@hidden @@address@hidden @@address@hidden@} address@hidden @dots{}
address@hidden example
-
address@hidden
-now produces:
-
address@hidden
address@hidden @result
address@hidden @clicksequence{File @click{} Open} @dots{}
address@hidden display
-
-
address@hidden Breaks
address@hidden Forcing and Preventing Breaks
-
address@hidden Forcing line and page breaks
address@hidden Making line and page breaks
address@hidden Preventing line and page breaks
address@hidden Line breaks, awkward
address@hidden Page breaks, awkward
-
-Line and page breaks can sometimes occur in the `wrong' place in one
-or another form of output. It's up to you to ensure that text looks
-right in all the output formats.
-
-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.
-
-You can use the break, break prevention, or pagination commands to fix
-problematic line and page breaks.
-
address@hidden
-* Break Commands:: Summary of break-related commands.
-* Line Breaks:: Forcing line breaks.
-* @t{@@- @@hyphenation}:: Helping @TeX{} with hyphenation points.
-* @t{@@allowcodebreaks}:: Controlling line breaks within @@code
text.
-* @t{@@w}:: Preventing unwanted line breaks in text.
-* @t{@@tie}:: Inserting an unbreakable but varying
space.
-* @t{@@sp}:: Inserting blank lines.
-* @t{@@page}:: Forcing the start of a new page.
-* @t{@@group}:: Preventing unwanted page breaks.
-* @t{@@need}:: Another way to prevent unwanted page
breaks.
address@hidden menu
-
-
address@hidden Break Commands
address@hidden Break Commands
-
-The break commands create or allow line and paragraph breaks:
-
address@hidden @code
address@hidden @@*
-Force a line break.
-
address@hidden @@sp @var{n}
-Skip @var{n} blank lines.
-
address@hidden @@-
-Insert a discretionary hyphen.
-
address@hidden @@address@hidden@var{hy-phen-a-ted address@hidden
-Define hyphen points in @var{hy-phen-a-ted words}.
address@hidden table
-
-These commands hold text together on a single line:
-
address@hidden @code
address@hidden @@address@hidden@address@hidden
-Prevent @var{text} from being split and hyphenated across two lines.
-
address@hidden @@address@hidden@}
-Insert a normal interword space at which a line break may not occur.
address@hidden table
-
-The pagination commands apply only to printed output, since other
-output formats do not have pages.
-
address@hidden @code
address@hidden @@page
-Start a new page.
-
address@hidden @@group
-Hold text together that must appear on one page.
-
address@hidden @@need @var{mils}
-Start a new page if not enough space on this one.
address@hidden table
-
-
address@hidden Line Breaks
address@hidden @code{@@*} and @code{@@/}: Generate and Allow Line Breaks
-
address@hidden * @r{(force line break)}
address@hidden / @r{(allow line break)}
address@hidden Line breaks, controlling
address@hidden Controlling line breaks
address@hidden Breaks in a line
address@hidden Force line break
address@hidden Allow line break
-
-The @code{@@*} command forces a line break in all output formats.
-The @code{@@/} command allows a line break (printed manual only).
-
-Here is an example with @code{@@*}:
-
address@hidden
-This sentence is broken @@*into two lines.
address@hidden example
-
address@hidden produces
-
address@hidden
address@hidden
-This sentence is broken
-into two lines.
address@hidden group
address@hidden example
-
-The @code{@@/} command can often be useful within urls
-(@address@hidden@@url}}), which tend to be long and are otherwise
-unbreakable. For example:
-
address@hidden
-The official Texinfo home page is on the GNU web site:
-@@address@hidden://www.gnu.org/@@/software/@@/gnu/@@/address@hidden
address@hidden example
-
address@hidden produces
-
address@hidden
-The official Texinfo home page is on the GNU web site:
address@hidden://www.gnu.org/@/software/@/gnu/@/texinfo}.
address@hidden quotation
-
address@hidden Without the @code{@@/} commands, @TeX{} would have nowhere to
-break the url. @code{@@/} has no effect in other output formats.
-
-
address@hidden @t{@@- @@hyphenation}
address@hidden @code{@@-} and @code{@@hyphenation}: Helping @TeX{} Hyphenate
-
address@hidden and address@hidden old name
address@hidden - @r{(discretionary hyphen)}
address@hidden hyphenation
address@hidden Hyphenation, helping @TeX{} do
address@hidden Fine-tuning, and hyphenation
-
-Although @TeX{}'s hyphenation algorithm is generally pretty good, it
-does miss useful hyphenation points from time to time. (Or, far more
-rarely, insert an incorrect hyphenation.) So, for documents with an
-unusual vocabulary or when fine-tuning for a printed edition, you may
-wish to help @TeX{} out. Texinfo supports two commands for this:
-
address@hidden @code
address@hidden @@-
-Insert a discretionary hyphen, i.e., a place where @TeX{} can (but does
-not have to) hyphenate. This is especially useful when you notice an
-overfull hbox is due to @TeX{} missing a hyphenation (@pxref{Overfull
-hboxes}). @TeX{} will not insert any hyphenation points itself into a
-word containing @code{@@-}.
-
address@hidden @@address@hidden@var{hy-phen-a-ted address@hidden
-Tell @TeX{} how to hyphenate @var{hy-phen-a-ted words}. As shown, you
-put a @samp{-} at each hyphenation point. For example:
address@hidden
-@@address@hidden address@hidden
address@hidden example
address@hidden @TeX{} only uses the specified hyphenation points when the
-words match exactly, so give all necessary variants, such as plurals.
address@hidden table
-
-Info, HTML, and other address@hidden output is not hyphenated, so none of
-these commands have any effect there.
-
-
address@hidden @t{@@allowcodebreaks}
address@hidden @code{@@allowcodebreaks}: Control Line Breaks in @code{@@code}
-
address@hidden@c old name
address@hidden allowcodebreaks
address@hidden Breaks, within @code{@@code}
address@hidden -, breakpoint within @code{@@code}
address@hidden Hyphen, breakpoint within @code{@@code}
address@hidden Dash, breakpoint within @code{@@code}
address@hidden _, breakpoint within @code{@@code}
address@hidden Underscore, breakpoint within @code{@@code}
-
-Ordinarily, @TeX{} considers breaking lines at @samp{-} and @samp{_}
-characters within @code{@@code} and related commands
-(@address@hidden@@code}}), more or less as if they were ``empty''
-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
-line break at the underscore in, for example, @code{SIZE_MAX}, or even
-worse, after any of the four underscores in @code{__typeof__}.
-
-So Texinfo provides this command:
-
address@hidden
-@@allowcodebreaks false
address@hidden example
-
address@hidden to prevent from breaking at @samp{-} or @samp{_} within
address@hidden@@code}. You can go back to allowing such breaks with
address@hidden@@allowcodebreaks true}. Write these commands on lines by
-themselves.
-
-These commands can be given anywhere in the document. For example,
-you may have just one problematic paragraph where you need to turn off
-the breaks, but want them in general, or vice versa.
-
-This command has no effect except in HTML and @TeX{} output.
-
-
address@hidden @t{@@w}
address@hidden @code{@@address@hidden@address@hidden: Prevent Line Breaks
-
address@hidden@c old name
address@hidden w @r{(prevent line break)}
address@hidden Line breaks, preventing
-
address@hidden@@address@hidden@address@hidden outputs @var{text}, while
prohibiting line
-breaks within @var{text}.
-
address@hidden Non-breakable space, fixed
address@hidden Unbreakable space, fixed
-Thus, you can use @code{@@w} to produce a non-breakable space, fixed at
-the width of a normal interword space:
-
address@hidden
-@@address@hidden @} @@address@hidden @} @@address@hidden @} indentation.
address@hidden example
-
address@hidden produces:
-
address@hidden
address@hidden } @w{ } @w{ } indentation.
address@hidden display
-
-The space from @code{@@address@hidden@w{ address@hidden, as well as being
non-breakable,
-also will not stretch or shrink. Sometimes that is what you want, for
-instance if you're doing manual indenting. However, usually you want
-a normal interword space that does stretch and shrink (in the printed
-output); for that, see the @code{@@tie} command in the next section.
-
address@hidden Hyphenation, preventing
-You can also use the @code{@@w} command to prevent @TeX{} from
-automatically hyphenating a long name or phrase that happens to fall
-near the end of a line. @command{makeinfo} does not ever hyphenate
-words.
-
address@hidden Keyword expansion, preventing
address@hidden Version control keywords, preventing expansion of
address@hidden $Id expansion, preventing
-You can also use @code{@@w} to avoid unwanted keyword expansion in
-source control systems. For example, to literally write @address@hidden
-in your document, use @code{@@address@hidden@}Id$}. This trick isn't effective
-in Info or plain text output, though.
-
-
address@hidden @t{@@tie}
address@hidden @code{@@address@hidden@}}: Inserting an Unbreakable Space
-
address@hidden@c old name
address@hidden tie @r{(unbreakable interword space)}
address@hidden Tied space
address@hidden Non-breakable space, variable
address@hidden Unbreakable space, variable
-
-The @code{@@address@hidden@}} command produces a normal interword space at
which
-a line break may not occur. Always write it with following (empty)
-braces, as usual for commands used within a paragraph. Here's an
-example:
-
address@hidden
-@@address@hidden@} was written by Donald E.@@address@hidden@}Knuth.
address@hidden example
-
address@hidden produces:
-
address@hidden
address@hidden was written by Donald address@hidden
address@hidden display
-
-There are two important differences between @code{@@address@hidden@}} and
address@hidden@@address@hidden@w{ address@hidden:
-
address@hidden
address@hidden
-The space produced by @code{@@address@hidden@}} will stretch and shrink
slightly
-along with the normal interword spaces in the paragraph; the space
-produced by @code{@@address@hidden@w{ address@hidden will not vary.
-
address@hidden
address@hidden@@address@hidden@}} allows hyphenation of the surrounding words,
while
address@hidden@@address@hidden@w{ address@hidden inhibits hyphenation of those
words (for @TeX{}nical
-reasons, namely that it produces an @samp{\hbox}).
-
address@hidden itemize
-
-
address@hidden @t{@@sp}
address@hidden @code{@@sp} @var{n}: Insert Blank Lines
-
address@hidden@c old name
address@hidden sp @r{(line spacing)}
address@hidden Space, inserting vertical
address@hidden Blank lines
address@hidden Line spacing
-
-A line beginning with and containing only @code{@@sp @var{n}}
-generates @var{n} blank lines of space in both the printed manual and
-the Info file. @code{@@sp} also forces a paragraph break. For
-example,
-
address@hidden
-@@sp 2
address@hidden example
-
address@hidden
-generates two blank lines.
-
-The @code{@@sp} command is most often used in the title page.
-
-
address@hidden @t{@@page}
address@hidden @code{@@page}: Start a New Page
-
address@hidden@c old name
address@hidden page
address@hidden Page breaks, forcing
-
-A line containing only @code{@@page} starts a new page in a printed
-manual. In other formats, without the concept of pages, it starts a
-new paragraph. An @code{@@page} command is often used in the
address@hidden@@titlepage} section of a Texinfo file to start the copyright
-page.
-
-
address@hidden @t{@@group}
address@hidden @code{@@group}: Prevent Page Breaks
-
address@hidden@c old name
address@hidden group
address@hidden Group (hold text together vertically)
address@hidden Holding text together vertically
address@hidden Vertically holding text together
-
-The @code{@@group} command (on a line by itself) is used inside an
address@hidden@@example} or similar construct to begin an unsplittable vertical
-group, which will appear entirely on one page in the printed output.
-The group is terminated by a line containing only @code{@@end group}.
-These two lines produce no output of their own, and in the Info file
-output they have no effect at all.
-
address@hidden Once said that these environments
address@hidden turn off vertical spacing between ``paragraphs''.
address@hidden Also, quotation used to work, but doesn't in texinfo-2.72
-Although @code{@@group} would make sense conceptually in a wide
-variety of contexts, its current implementation works reliably only
-within @code{@@example} and variants, and within @code{@@display},
address@hidden@@format}, @code{@@flushleft} and @code{@@flushright}.
address@hidden and Examples}. (What all these commands have in
-common is that each line of input produces a line of output.) In
-other contexts, @code{@@group} can cause anomalous vertical
-spacing.
-
address@hidden 750
-This formatting requirement means that you should write:
-
address@hidden
address@hidden
-@@example
-@@group
address@hidden
-@@end group
-@@end example
address@hidden group
address@hidden example
-
address@hidden
-with the @code{@@group} and @code{@@end group} commands inside the
address@hidden@@example} and @code{@@end example} commands.
-
-The @code{@@group} command is most often used to hold an example
-together on one page. In this Texinfo manual, more than 100 examples
-contain text that is enclosed between @code{@@group} and @code{@@end
-group}.
-
-If you forget to end a group, you may get strange and unfathomable
-error messages when you run @TeX{}. This is because @TeX{} keeps
-trying to put the rest of the Texinfo file onto the one page and does
-not start to generate error messages until it has processed
-considerable text. It is a good rule of thumb to look for a missing
address@hidden@@end group} if you get incomprehensible error messages in
address@hidden
-
-
address@hidden @t{@@need}
address@hidden @code{@@need @var{mils}}: Prevent Page Breaks
-
address@hidden@c old name
address@hidden need
address@hidden Need space at page bottom
address@hidden Mils, argument to @code{@@need}
-
-A line containing only @code{@@need @var{n}} starts a new page in a
-printed manual if fewer than @var{n} mils (thousandths of an inch)
-remain on the current page. Do not use braces around the argument
address@hidden The @code{@@need} command has no effect on other output
-formats since they are not paginated.
-
address@hidden 800
-This paragraph is preceded by an @code{@@need} command that tells
address@hidden to start a new page if fewer than 800 mils (eight-tenths
-inch) remain on the page. It looks like this:
-
address@hidden
address@hidden
-@@need 800
-This paragraph is preceded by @dots{}
address@hidden group
address@hidden example
-
address@hidden Orphans, preventing
-The @code{@@need} command is useful for preventing orphans: single
-lines at the bottoms of printed pages.
-
-
address@hidden Definition Commands
address@hidden Definition Commands
address@hidden Definition commands
-
-The @code{@@deffn} command and the other @dfn{definition commands}
-enable you to describe functions, variables, macros, commands, user
-options, special forms and other such artifacts in a uniform
-format.
-
-In the Info file, a definition causes the entity
-category---`Function', `Variable', or whatever---to appear at the
-beginning of the first line of the definition, followed by the
-entity's name and arguments. In the printed manual, the command
-causes @TeX{} to print the entity's name and its arguments on the left
-margin and print the category next to the right margin. In both
-output formats, the body of the definition is indented. Also, the
-name of the entity is entered into the appropriate index:
address@hidden@@deffn} enters the name into the index of functions,
address@hidden@@defvr} enters it into the index of variables, and so
-on (@pxref{Predefined Indices}).
-
-A manual need not and should not contain more than one definition for
-a given name. An appendix containing a summary should use
address@hidden@@table} rather than the definition commands.
-
address@hidden
-* Def Cmd Template:: Writing descriptions using definition commands.
-* Def Cmd Continuation Lines:: Continuing the heading over source lines.
-* Optional Arguments:: Handling optional and repeated arguments.
-* @t{@@deffnx}:: Group two or more `first' lines.
-* Def Cmds in Detail:: Reference for all the definition commands.
-* Def Cmd Conventions:: Conventions for writing definitions.
-* Sample Function Definition:: An example.
address@hidden menu
-
-
address@hidden Def Cmd Template
address@hidden The Template for a Definition
address@hidden Definition template
address@hidden Template for a definition
-
-The @code{@@deffn} command is used for definitions of entities that
-resemble functions. To write a definition using the @code{@@deffn}
-command, write the @code{@@deffn} command at the beginning of a line
-and follow it on the same line by the category of the entity, the name
-of the entity itself, and its arguments (if any). Then write the body
-of the definition on succeeding lines. (You may embed examples in the
-body.) Finally, end the definition with an @code{@@end deffn} command
-written on a line of its own.
-
-The other definition commands follow the same format: a line with the
address@hidden@@address@hidden command and whatever arguments are appropriate
for
-that command; the body of the definition; and a corresponding
address@hidden@@end} line.
-
-The template for a definition looks like this:
-
address@hidden
address@hidden
-@@deffn @var{category} @var{name} @address@hidden
address@hidden
-@@end deffn
address@hidden group
address@hidden example
-
address@hidden 700
address@hidden
-For example,
-
address@hidden
address@hidden
-@@deffn Command forward-word count
-This command moves point forward @@address@hidden@} words
-(or backward if @@address@hidden@} is negative). @dots{}
-@@end deffn
address@hidden group
address@hidden example
-
address@hidden
-produces
-
address@hidden
address@hidden Command forward-word count
-This command moves point forward @var{count} words
-(or backward if @var{count} is negative). @dots{}
address@hidden deffn
address@hidden quotation
-
-Capitalize the category name like a title. If the name of the
-category contains spaces, as in the phrase `Interactive Command',
-enclose it in braces. For example:
-
address@hidden
address@hidden
-@@deffn @{Interactive address@hidden isearch-forward
address@hidden
-@@end deffn
address@hidden group
address@hidden example
-
address@hidden
-Otherwise, the second word will be mistaken for the name of the
-entity. As a general rule, when any of the arguments in the heading
-line @emph{except} the last one are more than one word, you need to
-enclose them in braces. This may also be necessary if the text
-contains commands, for example, @address@hidden@@'address@hidden if you are
-writing in Spanish.
-
-Some of the definition commands are more general than others. The
address@hidden@@deffn} command, for example, is the general definition command
-for functions and the like---for entities that may take arguments.
-When you use this command, you specify the category to which the
-entity belongs. Three predefined, specialized variations
-(@code{@@defun}, @code{@@defmac}, and @code{@@defspec}) specify the
-category for you: ``Function'', ``Macro'', and ``Special Form''
-respectively. (In Lisp, a special form is an entity much like a
-function.) Similarly, the general @code{@@defvr} command is
-accompanied by several specialized variations for describing
-particular kinds of variables.
-
address@hidden Function Definition}, for a detailed example of a
-function definition, including the use of @code{@@example} inside the
-definition.
-
-
address@hidden Def Cmd Continuation Lines
address@hidden Definition Command Continuation Lines
address@hidden Continuation lines in definition commands
address@hidden Definition command headings, continuing
address@hidden @samp{@@} as continuation in definition commands
-
-The heading line of a definition command can get very long.
-Therefore, Texinfo has a special syntax allowing them to be continued
-over multiple lines of the source file: a lone @samp{@@} at the end of
-each line to be continued. Here's an example:
-
address@hidden
-@@defun fn-name @@
- arg1 arg2 arg3
-This is the basic continued defun.
-@@end defun
address@hidden example
-
address@hidden produces:
-
address@hidden fn-name arg1 arg2 arg3
-This is the basic continued defun.
address@hidden defun
-
address@hidden
-As you can see, the continued lines are combined, as if they had been
-typed on one source line.
-
-Although this example only shows a one-line continuation,
-continuations may extend over any number of lines, in the same way;
-put an @code{@@} at the end of each line to be continued.
-
address@hidden Whitespace, collapsed around continuations
address@hidden Collapsing whitespace around continuations
-In general, any number of spaces or tabs before the @code{@@}
-continuation character are collapsed into a single space. There is one
-exception: the Texinfo processors will not fully collapse whitespace
-around a continuation inside braces. For example:
-
address@hidden
-@@deffn @{Category @@
- address@hidden @dots{}
address@hidden example
-
address@hidden The output (not shown) has excess space between `Category'
-and `Name'. To avoid this, elide the unwanted whitespace in your
-input, or put the continuation @code{@@} outside braces.
-
address@hidden@@} does not function as a continuation character in @emph{any}
-other context. Ordinarily, @samp{@@} followed by a whitespace
-character (space, tab, newline) produces a normal interword space
-(@pxref{Multiple Spaces}).
-
-
address@hidden Optional Arguments
address@hidden Optional and Repeated Arguments
address@hidden Optional and repeated arguments
address@hidden Repeated and optional arguments
address@hidden Arguments, repeated and optional
address@hidden Syntax, optional & repeated arguments
address@hidden Meta-syntactic chars for arguments
-
address@hidden This is consistent with the Emacs Lisp Reference Manual.
-Some entities take optional or repeated arguments, conventionally
-specified by using square brackets and ellipses: an argument enclosed
-within square brackets is optional, and an argument followed by an
-ellipsis is optional and may be repeated more than once.
-
-Thus, address@hidden means that @var{optional-arg} is optional
-and @address@hidden@dots{}} stands for zero or more
-arguments. Parentheses are used when several arguments are grouped
-into additional levels of list structure in Lisp.
-
-Here is the @code{@@defspec} line of an example of an imaginary
-(complicated) special form:
-
address@hidden
address@hidden foobar (@var{var} address@hidden @var{to} address@hidden)
@address@hidden
address@hidden defspec
address@hidden tex
address@hidden \vskip \parskip
address@hidden end tex
address@hidden quotation
-
address@hidden
-In this example, the arguments @var{from} and @var{to} are optional,
-but must both be present or both absent. If they are present,
address@hidden may optionally be specified as well. These arguments are
-grouped with the argument @var{var} into a list, to distinguish them
-from @var{body}, which includes all remaining elements of the
-form.
-
-In a Texinfo source file, this @code{@@defspec} line is written like
-this, including a continuation to avoid a long source line.
-
address@hidden
address@hidden
-@@defspec foobar (@@address@hidden@} [@@address@hidden@} @@address@hidden@} @@
- [@@address@hidden@}]]) @@address@hidden@}@@address@hidden@}
address@hidden group
address@hidden example
-
address@hidden
-The function is listed in the Command and Variable Index under
address@hidden
-
-
address@hidden @t{@@deffnx}
address@hidden @code{@@deffnx}, et al.: Two or More `First' Lines
-
address@hidden@c old node
address@hidden deffnx
address@hidden Two `First' Lines for @code{@@deffn}
address@hidden Grouping two definitions together
address@hidden Definitions grouped together
-
-To create two or more `first' or header lines for a definition, follow
-the first @code{@@deffn} line by a line beginning with
address@hidden@@deffnx}. The @code{@@deffnx} command works exactly like
address@hidden@@deffn} except that it does not generate extra vertical white
-space between it and the preceding line.
-
address@hidden 1000
-For example,
-
address@hidden
address@hidden
-@@deffn @{Interactive address@hidden isearch-forward
-@@deffnx @{Interactive address@hidden isearch-backward
-These two search commands are similar except @dots{}
-@@end deffn
address@hidden group
address@hidden example
-
address@hidden
-produces
-
address@hidden {Interactive Command} isearch-forward
address@hidden {Interactive Command} isearch-backward
-These two search commands are similar except @dots{}
address@hidden deffn
-
-Each definition command has an `x' form: @code{@@defunx},
address@hidden@@defvrx}, @code{@@deftypefunx}, etc.
-
-The `x' forms work similarly to @code{@@itemx}
-(@address@hidden@@itemx}}).
-
-
address@hidden Def Cmds in Detail
address@hidden The Definition Commands
-
-Texinfo provides more than a dozen definition commands, all of which
-are described in this section.
-
-The definition commands automatically enter the name of the entity in
-the appropriate index: for example, @code{@@deffn}, @code{@@defun},
-and @code{@@defmac} enter function names in the index of functions;
address@hidden@@defvr} and @code{@@defvar} enter variable names in the index
-of variables.
-
-Although the examples that follow mostly illustrate Lisp, the commands
-can be used for other programming languages.
-
address@hidden
-* Functions Commands:: Commands for functions and similar entities.
-* Variables Commands:: Commands for variables and similar entities.
-* Typed Functions:: Commands for functions in typed languages.
-* Typed Variables:: Commands for variables in typed languages.
-* Data Types:: The definition command for data types.
-* Abstract Objects:: Commands for object-oriented programming.
address@hidden menu
-
address@hidden Functions Commands
address@hidden Functions and Similar Entities
-
-This section describes the commands for describing functions and similar
-entities:
-
address@hidden @code
address@hidden deffn
address@hidden @@deffn @var{category} @var{name} @address@hidden
-The @code{@@deffn} command is the general definition command for
-functions, interactive commands, and similar entities that may take
-arguments. You must choose a term to describe the category of entity
-being defined; for example, ``Function'' could be used if the entity is
-a function. The @code{@@deffn} command is written at the beginning of a
-line and is followed on the same line by the category of entity being
-described, the name of this particular entity, and its arguments, if
-any. Terminate the definition with @code{@@end deffn} on a line of its
-own.
-
address@hidden 750
-For example, here is a definition:
-
address@hidden
address@hidden
-@@deffn Command forward-char nchars
-Move point forward @@address@hidden@} characters.
-@@end deffn
address@hidden group
address@hidden example
-
address@hidden
-This shows a rather terse definition for a ``command'' named
address@hidden with one argument, @var{nchars}.
-
address@hidden@@deffn} prints argument names such as @var{nchars} in slanted
-type in the printed output, because we think of these names as
-metasyntactic variables---they stand for the actual argument values.
-Within the text of the description, however, write an argument name
-explicitly with @code{@@var} to refer to the value of the argument.
-In the example above, we used @samp{@@address@hidden@}} in this way.
-
-In the extremely unusual case when an argument name contains
address@hidden, or another character sequence which is treated specially
-(@pxref{Conventions}), use @code{@@code} around the special
-characters. This avoids the conversion to typographic en-dashes and
-em-dashes.
address@hidden @var also works; that's what we used to recommend.
-
-The template for @code{@@deffn} is:
-
address@hidden
address@hidden
-@@deffn @var{category} @var{name} @address@hidden
address@hidden
-@@end deffn
address@hidden group
address@hidden example
-
address@hidden defun
address@hidden @@defun @var{name} @address@hidden
-The @code{@@defun} command is the definition command for functions.
address@hidden@@defun} is equivalent to @samp{@@deffn Function @dots{}}.
-Terminate the definition with @code{@@end defun} on a line of its own.
-Thus, the template is:
-
address@hidden
address@hidden
-@@defun @var{function-name} @address@hidden
address@hidden
-@@end defun
address@hidden group
address@hidden example
-
address@hidden defmac
address@hidden @@defmac @var{name} @address@hidden
-The @code{@@defmac} command is the definition command for macros.
address@hidden@@defmac} is equivalent to @samp{@@deffn Macro @dots{}} and
-works like @code{@@defun}.
-
address@hidden defspec
address@hidden @@defspec @var{name} @address@hidden
-The @code{@@defspec} command is the definition command for special
-forms. (In Lisp, a special form is an entity much like a function;
address@hidden Forms,,, elisp, GNU Emacs Lisp Reference Manual}.)
address@hidden@@defspec} is equivalent to @samp{@@deffn @{Special address@hidden
address@hidden and works like @code{@@defun}.
address@hidden table
-
-All these commands create entries in the index of functions.
-
-
address@hidden Variables Commands
address@hidden Variables and Similar Entities
-
-Here are the commands for defining variables and similar
-entities:
-
address@hidden @code
address@hidden defvr
address@hidden @@defvr @var{category} @var{name}
-The @code{@@defvr} command is a general definition command for
-something like a variable---an entity that records a value. You must
-choose a term to describe the category of entity being defined; for
-example, ``Variable'' could be used if the entity is a variable.
-Write the @code{@@defvr} command at the beginning of a line and
-follow it on the same line by the category of the entity and the
-name of the entity.
-
-We recommend capitalizing the category name like a title. If the name
-of the category contains spaces, as in the name ``User Option'',
-enclose it in braces. Otherwise, the second word will be mistaken for
-the name of the entity. For example,
-
address@hidden
address@hidden
-@@defvr @{User address@hidden fill-column
-This buffer-local variable specifies
-the maximum width of filled lines.
address@hidden
-@@end defvr
address@hidden group
address@hidden example
-
-Terminate the definition with @code{@@end defvr} on a line of its
-own.
-
-The template is:
-
address@hidden
address@hidden
-@@defvr @var{category} @var{name}
address@hidden
-@@end defvr
address@hidden group
address@hidden example
-
address@hidden@@defvr} creates an entry in the index of variables for
@var{name}.
-
address@hidden defvar
address@hidden @@defvar @var{name}
-The @code{@@defvar} command is the definition command for variables.
address@hidden@@defvar} is equivalent to @samp{@@defvr Variable
address@hidden
-
address@hidden 750
-For example:
-
address@hidden
address@hidden
-@@defvar kill-ring
address@hidden
-@@end defvar
address@hidden group
address@hidden example
-
-The template is:
-
address@hidden
address@hidden
-@@defvar @var{name}
address@hidden
-@@end defvar
address@hidden group
address@hidden example
-
address@hidden@@defvar} creates an entry in the index of variables for
address@hidden
-
address@hidden defopt
address@hidden @@defopt @var{name}
address@hidden User options, marking
-The @code{@@defopt} command is the definition command for @dfn{user
-options}, i.e., variables intended for users to change according to
-taste; Emacs has many such (@pxref{Variables,,, emacs, The GNU Emacs
-Manual}). @code{@@defopt} is equivalent to @samp{@@defvr @{User
address@hidden @dots{}} and works like @code{@@defvar}. It creates an entry
-in the index of variables.
address@hidden table
-
-
address@hidden Typed Functions
address@hidden Functions in Typed Languages
-
address@hidden Typed functions
address@hidden Functions, in typed languages
-
-The @code{@@deftypefn} command and its variations are for describing
-functions in languages in which you must declare types of variables
-and functions, such as C and C++.
-
address@hidden @code
address@hidden deftypefn
address@hidden @@deftypefn @var{category} @var{data-type} @var{name}
@address@hidden
-The @code{@@deftypefn} command is the general definition command for
-functions and similar entities that may take arguments and that are
-typed. The @code{@@deftypefn} command is written at the beginning of
-a line and is followed on the same line by the category of entity
-being described, the type of the returned value, the name of this
-particular entity, and its arguments, if any.
-
address@hidden 800
address@hidden
-For example,
-
address@hidden
address@hidden
-@@deftypefn @{Library address@hidden int foobar @@
- (int @@address@hidden@}, float @@address@hidden@})
address@hidden
-@@end deftypefn
address@hidden group
address@hidden example
-
-produces:
-
address@hidden
address@hidden {Library Function} int foobar (int @var{foo}, float @var{bar})
address@hidden
address@hidden deftypefn
address@hidden quotation
-
-This means that @code{foobar} is a ``library function'' that returns an
address@hidden, and its arguments are @var{foo} (an @code{int}) and
address@hidden (a @code{float}).
-
-Since in typed languages, the actual names of the arguments are
-typically scattered among data type names and keywords, Texinfo cannot
-find them without help. You can either (a)@tie{}write everything as
-straight text, and it will be printed in slanted type; (b)@tie{}use
address@hidden@@var} for the variable names, which will uppercase the variable
-names in Info and use the slanted typewriter font in printed output;
-(c)@tie{}use @code{@@var} for the variable names and @code{@@code} for
-the type names and keywords, which will be dutifully obeyed.
-
-The template for @code{@@deftypefn} is:
-
address@hidden
address@hidden
-@@deftypefn @var{category} @var{data-type} @var{name} @var{arguments} @dots{}
address@hidden
-@@end deftypefn
address@hidden group
address@hidden example
-
address@hidden
-Note that if the @var{category} or @var{data type} is more than one
-word then it must be enclosed in braces to make it a single argument.
-
-If you are describing a procedure in a language that has packages,
-such as Ada, you might consider using @code{@@deftypefn} in a manner
-somewhat contrary to the convention described in the preceding
-paragraphs. For example:
-
address@hidden
address@hidden
-@@deftypefn stacks private push @@
- (@@address@hidden@}:in out stack; @@
- @@address@hidden@}:in integer)
address@hidden
-@@end deftypefn
address@hidden group
address@hidden example
-
address@hidden
-(In these examples the @code{@@deftypefn} arguments are shown using
-continuations (@pxref{Def Cmd Continuation Lines}), but could be on a
-single line.)
-
-In this instance, the procedure is classified as belonging to the
-package @code{stacks} rather than classified as a `procedure' and its
-data type is described as @code{private}. (The name of the procedure
-is @code{push}, and its arguments are @var{s} and @var{n}.)
-
address@hidden@@deftypefn} creates an entry in the index of functions for
address@hidden
-
address@hidden @@deftypefun @var{data-type} @var{name} @address@hidden
address@hidden deftypefun
-The @code{@@deftypefun} command is the specialized definition command
-for functions in typed languages. The command is equivalent to
address@hidden@@deftypefn Function @dots{}}. The template is:
-
address@hidden
address@hidden
-@@deftypefun @var{type} @var{name} @address@hidden
address@hidden
-@@end deftypefun
address@hidden group
address@hidden example
-
address@hidden@@deftypefun} creates an entry in the index of functions for
address@hidden
-
address@hidden table
-
address@hidden Return type, own line for
address@hidden deftypefnnewline
-Ordinarily, the return type is printed on the same line as the
-function name and arguments, as shown above. In source code, GNU
-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
-section, and the analogous commands for object-oriented languages,
-namely @code{@@deftypeop} and @code{@@deftypemethod}
-(@pxref{Object-Oriented Methods}).
-
-Specifying @code{@@deftypefnnewline off} reverts to the default.
-
-
address@hidden Typed Variables
address@hidden Variables in Typed Languages
-
address@hidden Typed variables
address@hidden Variables, in typed languages
-
-Variables in typed languages are handled in a manner similar to
-functions in typed languages. @xref{Typed Functions}. The general
-definition command @code{@@deftypevr} corresponds to
address@hidden@@deftypefn} and the specialized definition command
address@hidden@@deftypevar} corresponds to @code{@@deftypefun}.
-
address@hidden @code
address@hidden deftypevr
address@hidden @@deftypevr @var{category} @var{data-type} @var{name}
-The @code{@@deftypevr} command is the general definition command for
-something like a variable in a typed language---an entity that records
-a value. You must choose a term to describe the category of the
-entity being defined; for example, ``Variable'' could be used if the
-entity is a variable.
-
-The @code{@@deftypevr} command is written at the beginning of a line
-and is followed on the same line by the category of the entity
-being described, the data type, and the name of this particular
-entity.
-
address@hidden 800
address@hidden
-For example:
-
address@hidden
address@hidden
-@@deftypevr @{Global address@hidden int enable
address@hidden
-@@end deftypevr
address@hidden group
address@hidden example
-
address@hidden
-produces the following:
-
address@hidden
address@hidden {Global Flag} int enable
address@hidden
address@hidden deftypevr
address@hidden quotation
-
address@hidden 800
-The template is:
-
address@hidden
-@@deftypevr @var{category} @var{data-type} @var{name}
address@hidden
-@@end deftypevr
address@hidden example
-
address@hidden deftypevar
address@hidden @@deftypevar @var{data-type} @var{name}
-The @code{@@deftypevar} command is the specialized definition command
-for variables in typed languages. @code{@@deftypevar} is equivalent
-to @samp{@@deftypevr Variable @dots{}}. The template is:
-
address@hidden
address@hidden
-@@deftypevar @var{data-type} @var{name}
address@hidden
-@@end deftypevar
address@hidden group
address@hidden example
address@hidden table
-
-These commands create entries in the index of variables.
-
-
address@hidden Data Types
address@hidden Data Types
-
-Here is the command for data types:
-
address@hidden @code
address@hidden deftp
address@hidden @@deftp @var{category} @var{name} @address@hidden
-The @code{@@deftp} command is the generic definition command for data
-types. The command is written at the beginning of a line and is
-followed on the same line by the category, by the name of the type
-(which is a word like @code{int} or @code{float}), and then by names of
-attributes of objects of that type. Thus, you could use this command
-for describing @code{int} or @code{float}, in which case you could use
address@hidden type} as the category. (A data type is a category of
-certain objects for purposes of deciding which operations can be
-performed on them.)
-
-In Lisp, for example, @dfn{pair} names a particular data
-type, and an object of that type has two slots called the
address@hidden and the @sc{cdr}. Here is how you would write the first line
-of a definition of @code{pair}.
-
address@hidden
address@hidden
-@@deftp @{Data address@hidden pair car cdr
address@hidden
-@@end deftp
address@hidden group
address@hidden example
-
address@hidden 950
-The template is:
-
address@hidden
address@hidden
-@@deftp @var{category} @var{name-of-type} @address@hidden
address@hidden
-@@end deftp
address@hidden group
address@hidden example
-
address@hidden@@deftp} creates an entry in the index of data types.
address@hidden table
-
-
address@hidden Abstract Objects
address@hidden Object-Oriented Programming
-
address@hidden Object-oriented programming
-
-Here are the commands for formatting descriptions about abstract
-objects, such as are used in object-oriented programming. A class is
-a defined type of abstract object. An instance of a class is a
-particular object that has the type of the class. An instance
-variable is a variable that belongs to the class but for which each
-instance has its own value.
-
address@hidden
-* Variables: Object-Oriented Variables.
-* Methods: Object-Oriented Methods.
address@hidden menu
-
-
address@hidden Object-Oriented Variables
address@hidden Object-Oriented Variables
-
address@hidden Variables, object-oriented
-
-These commands allow you to define different sorts of variables in
-object-oriented programming languages.
-
address@hidden @code
address@hidden @@defcv @var{category} @var{class} @var{name}
address@hidden defcv
-The @code{@@defcv} command is the general definition command for
-variables associated with classes in object-oriented programming. The
address@hidden@@defcv} command is followed by three arguments: the category of
-thing being defined, the class to which it belongs, and its
-name. For instance:
-
address@hidden
address@hidden
-@@defcv @{Class address@hidden Window border-pattern
address@hidden
-@@end defcv
address@hidden group
address@hidden example
-
address@hidden produces:
address@hidden {Class Option} Window border-pattern
address@hidden
address@hidden defcv
-
address@hidden@@defcv} creates an entry in the index of variables.
-
address@hidden @@deftypecv @var{category} @var{class} @var{data-type} @var{name}
address@hidden deftypecv
-The @code{@@deftypecv} command is the definition command for typed
-class variables in object-oriented programming. It is analogous to
address@hidden@@defcv} with the addition of the @var{data-type} parameter to
-specify the type of the instance variable. Ordinarily, the data type
-is a programming language construct that should be marked with
address@hidden@@code}. For instance:
-
address@hidden
address@hidden
-@@deftypecv @{Class address@hidden Window @@address@hidden@} border-pattern
address@hidden
-@@end deftypecv
address@hidden group
address@hidden example
-
address@hidden produces:
-
address@hidden {Class Option} Window @code{int} border-pattern
address@hidden
address@hidden deftypecv
-
address@hidden@@deftypecv} creates an entry in the index of variables.
-
address@hidden @@defivar @var{class} @var{name}
address@hidden defivar
-The @code{@@defivar} command is the definition command for instance
-variables in object-oriented programming. @code{@@defivar} is
-equivalent to @samp{@@defcv @{Instance address@hidden @dots{}}. For
-instance:
-
address@hidden
address@hidden
-@@defivar Window border-pattern
address@hidden
-@@end defivar
address@hidden group
address@hidden example
-
address@hidden produces:
-
address@hidden Window border-pattern
address@hidden
address@hidden defivar
-
address@hidden@@defivar} creates an entry in the index of variables.
-
address@hidden @@deftypeivar @var{class} @var{data-type} @var{name}
address@hidden deftypeivar
-The @code{@@deftypeivar} command is the definition command for typed
-instance variables in object-oriented programming. It is analogous to
address@hidden@@defivar} with the addition of the @var{data-type} parameter to
-specify the type of the instance variable. Ordinarily, the data type
-is a programming language construct that should be marked with
address@hidden@@code}. For instance:
-
address@hidden
address@hidden
-@@deftypeivar Window @@address@hidden@} border-pattern
address@hidden
-@@end deftypeivar
address@hidden group
address@hidden example
-
address@hidden produces:
-
address@hidden Window @code{int} border-pattern
address@hidden
address@hidden deftypeivar
-
address@hidden@@deftypeivar} creates an entry in the index of variables.
-
address@hidden table
-
-
address@hidden Object-Oriented Methods
address@hidden Object-Oriented Methods
-
address@hidden Methods, object-oriented
-
-These commands allow you to define different sorts of function-like
-entities resembling methods in object-oriented programming languages.
-These entities take arguments, as functions do, but are associated with
-particular classes of objects.
-
address@hidden @code
-
address@hidden defop
address@hidden @@defop @var{category} @var{class} @var{name} @address@hidden
-The @code{@@defop} command is the general definition command for these
-method-like entities.
-
-For example, some systems have constructs called @dfn{wrappers} that
-are associated with classes as methods are, but that act more like
-macros than like functions. You could use @code{@@defop Wrapper} to
-describe one of these.
-
-Sometimes it is useful to distinguish methods and @dfn{operations}.
-You can think of an operation as the specification for a method.
-Thus, a window system might specify that all window classes have a
-method named @code{expose}; we would say that this window system
-defines an @code{expose} operation on windows in general. Typically,
-the operation has a name and also specifies the pattern of arguments;
-all methods that implement the operation must accept the same
-arguments, since applications that use the operation do so without
-knowing which method will implement it.
-
-Often it makes more sense to document operations than methods. For
-example, window application developers need to know about the
address@hidden operation, but need not be concerned with whether a
-given class of windows has its own method to implement this operation.
-To describe this operation, you would write:
-
address@hidden
-@@defop Operation windows expose
address@hidden example
-
-The @code{@@defop} command is written at the beginning of a line and
-is followed on the same line by the overall name of the category of
-operation, the name of the class of the operation, the name of the
-operation, and its arguments, if any.
-
-The template is:
address@hidden
address@hidden
-@@defop @var{category} @var{class} @var{name} @address@hidden
address@hidden
-@@end defop
address@hidden group
address@hidden example
-
address@hidden@@defop} creates an entry, such as address@hidden on
address@hidden', in the index of functions.
-
address@hidden deftypeop
address@hidden @@deftypeop @var{category} @var{class} @var{data-type}
@var{name} @address@hidden
-The @code{@@deftypeop} command is the definition command for typed
-operations in object-oriented programming. It is similar to
address@hidden@@defop} with the addition of the @var{data-type} parameter to
-specify the return type of the method. @code{@@deftypeop} creates an
-entry in the index of functions.
-
address@hidden @@defmethod @var{class} @var{name} @address@hidden
address@hidden defmethod
-The @code{@@defmethod} command is the definition command for methods
-in object-oriented programming. A method is a kind of function that
-implements an operation for a particular class of objects and its
-subclasses.
address@hidden
address@hidden ADR: Who cares?!?
address@hidden KB: Oh, I don't know, I think this info is crucial!
-In the Lisp Machine, methods actually were functions, but
-they were usually defined with @code{defmethod}.
address@hidden ignore
-
address@hidden@@defmethod} is equivalent to @samp{@@defop Method @dots{}}.
-The command is written at the beginning of a line and is followed by
-the name of the class of the method, the name of the method, and its
-arguments, if any.
-
address@hidden
-For example:
address@hidden
address@hidden
-@@defmethod @code{bar-class} bar-method argument
address@hidden
-@@end defmethod
address@hidden group
address@hidden example
-
address@hidden
-illustrates the definition for a method called @code{bar-method} of
-the class @code{bar-class}. The method takes an argument.
-
address@hidden@@defmethod} creates an entry in the index of functions.
-
address@hidden @@deftypemethod @var{class} @var{data-type} @var{name}
@address@hidden
address@hidden defmethod
-The @code{@@deftypemethod} command is the definition command for methods
-in object-oriented typed languages, such as C++ and Java. It is similar
-to the @code{@@defmethod} command with the addition of the
address@hidden parameter to specify the return type of the method.
address@hidden@@deftypemethod} creates an entry in the index of functions.
-
address@hidden table
-
-The typed commands are affected by the @code{@@deftypefnnewline}
-option (@pxref{Typed Functions,, Functions in Typed Languages}).
-
-
address@hidden Def Cmd Conventions
address@hidden Conventions for Writing Definitions
address@hidden Definition conventions
address@hidden Conventions for writing definitions
-
-When you write a definition using @code{@@deffn}, @code{@@defun}, or
-one of the other definition commands, please take care to use
-arguments that indicate the meaning, as with the @var{count} argument
-to the @code{forward-word} function. Also, if the name of an argument
-contains the name of a type, such as @var{integer}, take care that the
-argument actually is of that type.
-
-
address@hidden Sample Function Definition
address@hidden A Sample Function Definition
address@hidden Function definitions
address@hidden Command definitions
address@hidden Macro definitions, programming-language
address@hidden Sample function definition
-
-A function definition uses the @code{@@defun} and @code{@@end defun}
-commands. The name of the function follows immediately after the
address@hidden@@defun} command and it is followed, on the same line, by the
-parameter list.
-
-Here is a definition from @ref{Calling Functions,,, elisp, The GNU Emacs
-Lisp Reference Manual}.
-
address@hidden
address@hidden apply function &rest arguments
address@hidden calls @var{function} with @var{arguments}, just
-like @code{funcall} but with one difference: the last of
address@hidden is a list of arguments to give to
address@hidden, rather than a single argument. We also say
-that this list is @dfn{appended} to the other arguments.
-
address@hidden returns the result of calling @var{function}.
-As with @code{funcall}, @var{function} must either be a Lisp
-function or a primitive function; special forms and macros
-do not make sense in @code{apply}.
-
address@hidden
-(setq f 'list)
- @result{} list
-(apply f 'x 'y 'z)
address@hidden Wrong type argument: listp, z
-(apply '+ 1 2 '(3 4))
- @result{} 10
-(apply '+ '(1 2 3 4))
- @result{} 10
-
-(apply 'append '((a b c) nil (x y z) nil))
- @result{} (a b c x y z)
address@hidden example
-
-An interesting example of using @code{apply} is found in the description
-of @code{mapcar}.
address@hidden defun
address@hidden quotation
-
-In the Texinfo source file, this example looks like this:
-
address@hidden
address@hidden
-@@defun apply function &rest arguments
-@@address@hidden@} calls @@address@hidden@} with
-@@address@hidden@}, just like @@address@hidden@} but with one
-difference: the last of @@address@hidden@} is a list of
-arguments to give to @@address@hidden@}, rather than a single
-argument. We also say that this list is @@address@hidden@}
-to the other arguments.
address@hidden group
-
address@hidden
-@@address@hidden@} returns the result of calling
-@@address@hidden@}. As with @@address@hidden@},
-@@address@hidden@} must either be a Lisp function or a
-primitive function; special forms and macros do not make
-sense in @@address@hidden@}.
address@hidden group
-
address@hidden
-@@example
-(setq f 'list)
- @@address@hidden@} list
-(apply f 'x 'y 'z)
-@@address@hidden@} Wrong type argument: listp, z
-(apply '+ 1 2 '(3 4))
- @@address@hidden@} 10
-(apply '+ '(1 2 3 4))
- @@address@hidden@} 10
-
-(apply 'append '((a b c) nil (x y z) nil))
- @@address@hidden@} (a b c x y z)
-@@end example
address@hidden group
-
address@hidden
-An interesting example of using @@address@hidden@} is found
-in the description of @@address@hidden@}.
-@@end defun
address@hidden group
address@hidden example
-
address@hidden
-In this manual, this function is listed in the Command and Variable
-Index under @code{apply}.
-
-Ordinary variables and user options are described using a format like
-that for functions except that variables do not take arguments.
-
-
address@hidden Internationalization
address@hidden Internationalization
-
address@hidden Internationalization
-Texinfo has some support for writing in languages other than English,
-although this area still needs considerable work. (If you are
-yourself helping to translate the fixed strings written to documents,
address@hidden of Document Strings}.)
-
-For a list of the various accented and special characters Texinfo
-supports, see @ref{Inserting Accents}.
-
address@hidden
-* @t{@@documentlanguage}:: Declaring the current language.
-* @t{@@documentencoding}:: Declaring the input encoding.
address@hidden menu
-
-
address@hidden @t{@@documentlanguage}
address@hidden @code{@@documentlanguage @address@hidden: Set the Document
Language
address@hidden
-
address@hidden documentlanguage
address@hidden Language, declaring
address@hidden Locale, declaring
address@hidden Document language, declaring
-
-The @code{@@documentlanguage} command declares the current document
-locale. Write it on a line by itself, near the beginning of the file,
-but after @code{@@setfilename} (@address@hidden@@setfilename}}):
-
address@hidden
-@@documentlanguage @address@hidden
address@hidden example
-
-Include a two-letter address@hidden language code (@var{ll}) following
-the command name, optionally followed by an underscore and two-letter
address@hidden two-letter country code (@var{cc}). If you have a
-multilingual document, the intent is to be able to use this command
-multiple times, to declare each language change. If the command is
-not used at all, the default is @code{en_US} for US English.
-
-As with GNU Gettext (@pxref{Top,,, gettext, Gettext}), if the country
-code is omitted, the main dialect is assumed where possible. For
-example, @code{de} is equivalent to @code{de_DE} (German as spoken in
-Germany).
-
address@hidden Document strings, translation of
-For Info and other online output, this command changes the translation
-of various @dfn{document strings} such as ``see'' in cross references
-(@pxref{Cross References}), ``Function' in defuns (@pxref{Definition
-Commands}), and so on. Some strings, such as ``Node:'', ``Next:'',
-``Menu:'', etc., are keywords in Info output, so are not translated
-there; they are translated in other output formats.
-
address@hidden @address@hidden
-For @TeX{}, this command causes a file @address@hidden to
-be read (if it exists). If @code{@@documentlanguage} argument
-contains the optional @address@hidden suffix, this is tried first.
-For example, with @code{@@documentlanguage de_DE}, @TeX{} first looks
-for @file{txi-de_DE.tex}, then @file{txi-de.tex}.
-
-Such a @file{txi-*} file is intended to redefine the various English
-words used in @TeX{} output, such as `Chapter', `See', and so on. We
-are aware that individual words like these cannot always be translated
-in isolation, and that a very different strategy would be required for
-ideographic (among other) scripts. Help in improving Texinfo's
-language support is welcome.
-
address@hidden Hyphenation patterns, language-dependent
address@hidden@@documentlanguage} also changes @TeX{}'s current hyphenation
-patterns, if the @TeX{} program being run has the necessary support
-included. This will generally not be the case for @command{tex}
-itself, but will usually be the case for up-to-date distributions of
-the extended @TeX{} programs @command{etex} (DVI output) and
address@hidden (PDF output). @command{texi2dvi} will use the
-extended @TeX{}s if they are available (@pxref{Format with
address@hidden).
-
-In September 2006, the W3C Internationalization Activity released a
-new recommendation for specifying languages:
address@hidden://www.rfc-editor.org/rfc/bcp/bcp47.txt}. When Gettext
-supports this new scheme, Texinfo will too.
-
address@hidden ISO 639-2 language codes
address@hidden ISO 3166 country codes
address@hidden Language codes
address@hidden Country codes
-Since the lists of language codes and country codes are updated
-relatively frequently, we don't attempt to list them here. The valid
-language codes are on the official home page for address@hidden,
address@hidden://www.loc.gov/standards/iso639-2/}. The country codes and
-the official web site for address@hidden can be found via
address@hidden://en.wikipedia.org/wiki/ISO_3166}.
-
-
address@hidden @t{@@documentencoding}
address@hidden @code{@@documentencoding @var{enc}}: Set Input Encoding
-
address@hidden@c old name
address@hidden documentencoding
address@hidden Encoding, declaring
address@hidden Input encoding, declaring
address@hidden Character set, declaring
address@hidden Document input encoding
-
-The @code{@@documentencoding} command declares the input document
-encoding. Write it on a line by itself, with a valid encoding
-specification following, near the beginning of the file but after
address@hidden@@setfilename} (@address@hidden@@setfilename}}):
-
address@hidden
-@@documentencoding @var{enc}
address@hidden example
-
-At present, Texinfo supports only these encodings:
-
address@hidden @code
address@hidden US-ASCII
-This has no particular effect, but it's included for completeness.
-
address@hidden UTF-8
-The vast global character encoding, expressed in 8-bit bytes.
-
address@hidden ISO-8859-2
address@hidden ISO-8859-1
address@hidden ISO-8859-15
-These specify the standard encodings for Western European (the first
-two) and Eastern European languages (the third), respectively. ISO
-8859-15 replaces some little-used characters from 8859-1 (e.g.,
-precomposed fractions) with more commonly needed ones, such as the
-Euro symbol (@euro{}).
-
-A full description of the encodings is beyond our scope here;
-one useful reference is @uref{http://czyborra.com/charsets/iso8859.html}.
-
address@hidden koi8-r
-This is the commonly used encoding for the Russian language.
-
address@hidden koi8-u
-This is the commonly used encoding for the Ukrainian language.
-
address@hidden table
-
-Specifying an encoding @var{enc} has the following effects:
-
address@hidden Local Variables section, for encoding
address@hidden Info output, and encoding
-In Info output, a so-called `Local Variables' section (@pxref{File
-Variables,,,emacs, The GNU Emacs Manual}) is output including
address@hidden This allows Info readers to set the encoding
-appropriately. It looks like this:
-
address@hidden
-Local Variables:
-coding: @var{enc}
-End:
address@hidden example
-
-Also, in Info and plain text output, unless the option
address@hidden is given to @command{makeinfo}, accent
-constructs and special characters, such as @code{@@'e}, are output as
-the actual 8-bit or UTF-8 character in the given encoding where
-possible.
-
address@hidden HTML output, and encodings
address@hidden @code{http-equiv}, and charset specification
address@hidden @code{<meta>} HTML tag, and charset specification
-In HTML output, a @samp{<meta>} tag is output, in the @samp{<head>}
-section of the HTML, that specifies @var{enc}. Web servers and
-browsers cooperate to use this information so the correct encoding is
-used to display the page, if supported by the system. That looks like
-this:
-
address@hidden
-<meta http-equiv="Content-Type" content="text/html;
- address@hidden">
address@hidden example
-
-In XML and Docbook output, UTF-8 is always used for the output file,
-since all XML processors are supposed to be able to process that
-encoding.
-
address@hidden Computer Modern fonts
-In @TeX{} output, the characters which are supported in the standard
-Computer Modern fonts are output accordingly. (For example, this
-means using constructed accents rather than precomposed glyphs.)
-Using a missing character generates a warning message, as does
-specifying an unimplemented encoding.
-
-Although modern @TeX{} systems support nearly every script in use in
-the world, this wide-ranging support is not available in
address@hidden, and it's not feasible to duplicate or incorporate
-all that effort. Our plan to support other scripts is to create a
address@hidden back-end to @command{texi2any}, where the support is already
-present.
-
-
address@hidden Conditionals
address@hidden Conditionally Visible Text
address@hidden Conditionally visible text
address@hidden Text, conditionally visible
address@hidden Visibility of conditional text
address@hidden If text conditionally visible
-
-The @dfn{conditional commands} allow you to use different text for
-different output formats, or for general conditions that you define.
-For example, you can use them to specify different text for the
-printed manual and the Info output.
-
-The conditional commands comprise the following categories.
-
address@hidden @bullet
address@hidden
-Commands specific to an output format (Info, @TeX{}, HTML, @dots{}).
-
address@hidden
-Commands specific to any output format @emph{excluding} a given
-one (e.g., not Info, not @TeX{}, @dots{}).
-
address@hidden
-`Raw' formatter text for any output format, passed straight
-through with minimal (but not zero) interpretation of @@-commands.
-
address@hidden
-Format-independent variable substitutions, and testing if a variable
-is set or clear.
-
address@hidden itemize
-
address@hidden
-* Conditional Commands:: Text for a given format.
-* Conditional Not Commands:: Text for any format other than a given one.
-* Raw Formatter Commands:: Using raw formatter commands.
-* Inline Conditionals:: Brace-delimited conditional text.
-* @t{@@set @@clear @@value}:: Variable tests and substitutions.
-* Testing for Texinfo Commands:: Testing if a Texinfo command is available.
-* Conditional Nesting:: Using conditionals inside conditionals.
address@hidden menu
-
-
address@hidden Conditional Commands
address@hidden Conditional Commands
-
-Texinfo has an @code{@@address@hidden environment for each output
-format, to allow conditional inclusion of text for a particular output
-format.
-
address@hidden ifinfo
address@hidden@@ifinfo} begins segments of text that should be ignored by
address@hidden when it typesets the printed manual, and by @command{makeinfo}
-when not producing Info output. The segment of text appears only in
-the Info file and, for historical compatibility, the plain text
-output.
-
address@hidden ifdocbook
address@hidden ifhtml
address@hidden ifplaintext
address@hidden iftex
address@hidden ifxml
-The environments for the other formats are analogous, but without the
-special historical case:
-
address@hidden @code
address@hidden @@ifdocbook @dots{} @@end ifdocbook
-Text to appear only in the Docbook output.
-
address@hidden @@ifhtml @dots{} @@end ifhtml
-Text to appear only in the HTML output.
-
address@hidden @@ifplaintext @dots{} @@end ifplaintext
-Text to appear only in the plain text output.
-
address@hidden @@iftex @dots{} @@end iftex
-Text to appear only in the printed manual.
-
address@hidden @@ifxml @dots{} @@end ifxml
-Text to appear only in the XML output.
address@hidden table
-
-The @code{@@address@hidden and @code{@@end address@hidden commands must appear
-on lines by themselves in your source file. The newlines following
-the commands are (more or less) treated as whitespace, so that the
-conditional text is flowed normally into a surrounding paragraph.
-
-The @code{@@address@hidden constructs are intended to conditionalize
-normal Texinfo source; @pxref{Raw Formatter Commands}, for using
-underlying format commands directly.
-
-Here is an example showing all these conditionals:
-
address@hidden
-@@iftex
-This text will appear only in the printed manual.
-@@end iftex
-@@ifinfo
-However, this text will appear only in Info and plain text.
-@@end ifinfo
-@@ifhtml
-And this text will only appear in HTML.
-@@end ifhtml
-@@ifplaintext
-Whereas this text will only appear in plain text.
-@@end ifplaintext
-@@ifxml
-Notwithstanding that this will only appear in address@hidden
-@@end ifxml
-@@ifdocbook
-Nevertheless, this will only appear in Docbook.
-@@end ifdocbook
address@hidden example
-
address@hidden
-The preceding example produces the following line:
-
address@hidden
-This text will appear only in the printed manual.
address@hidden iftex
address@hidden
-However, this text will appear only in Info and plain text.
address@hidden ifinfo
address@hidden
-And this text will only appear in HTML.
address@hidden ifhtml
address@hidden
-Whereas this text will only appear in plain text.
address@hidden ifplaintext
address@hidden
-Notwithstanding that this will only appear in address@hidden
address@hidden ifxml
address@hidden
-Nevertheless, this will only appear in Docbook.
address@hidden ifdocbook
-
address@hidden
-Notice that you only see one of the input lines, depending on which
-version of the manual you are reading.
-
address@hidden errormsg
-In complex documents, you may want Texinfo to issue an error message
-in some conditionals that should not ever be processed. The
address@hidden@@address@hidden@address@hidden command will do this; it takes one
-argument, the text of the error message, which is expanded more or
-less as if it were Info text.
-
-We mention @code{@@address@hidden@}} here even though it is not strictly
-related to conditionals, since in practice it is most likely to be
-useful in that context. Technically, it can be used anywhere.
address@hidden Macro Processors}, for a caveat regarding the line
-numbers which @code{@@errormsg} emits in @TeX{}.
-
-
address@hidden Conditional Not Commands
address@hidden Conditional Not Commands
address@hidden ifnotdocbook
address@hidden ifnothtml
address@hidden ifnotinfo
address@hidden ifnotplaintext
address@hidden ifnottex
address@hidden ifnotxml
-
-You can specify text to be included in any output format @emph{other}
-than a given one with the @code{@@address@hidden environments:
-
address@hidden
-@@ifnotdocbook @dots{} @@end ifnotdocbook
-@@ifnothtml @dots{} @@end ifnothtml
-@@ifnotinfo @dots{} @@end ifnotinfo
-@@ifnotplaintext @dots{} @@end ifnotplaintext
-@@ifnottex @dots{} @@end ifnottex
-@@ifnotxml @dots{} @@end ifnotxml
address@hidden example
-
address@hidden
-The @code{@@address@hidden command and the @code{@@end} command must
-appear on lines by themselves in your actual source file.
-
-If the output file is being made in the given format, the
-region is @emph{ignored}. Otherwise, it is included.
-
-There is one exception (for historical compatibility):
address@hidden@@ifnotinfo} text is omitted for both Info and plain text
-output, not just Info. To specify text which appears only in Info and
-not in plain text, use @code{@@ifnotplaintext}, like this:
-
address@hidden
-@@ifinfo
-@@ifnotplaintext
-This will be in Info, but not plain text.
-@@end ifnotplaintext
-@@end ifinfo
address@hidden example
-
-The regions delimited by these commands are ordinary Texinfo source as
-with @code{@@iftex}, not raw formatter source as with @code{@@tex}
-(@pxref{Raw Formatter Commands}).
-
-
address@hidden Raw Formatter Commands
address@hidden Raw Formatter Commands
address@hidden Raw formatter commands
-
address@hidden @TeX{} commands, using ordinary
address@hidden Ordinary @TeX{} commands, using
address@hidden Commands using raw @TeX{}
address@hidden Plain @TeX{}
-
-The @code{@@address@hidden conditionals just described must be used only
-with normal Texinfo source. For instance, most features of plain
address@hidden will not work within @code{@@iftex}. The purpose of
address@hidden@@address@hidden is to provide conditional processing for Texinfo
-source, not provide access to underlying formatting features. For
-that, Texinfo provides so-called @dfn{raw formatter commands}. They
-should only be used when truly required (most documents do not need
-them).
-
address@hidden tex
address@hidden Category codes, of plain @TeX{}
-The first raw formatter command is @code{@@tex}. You can enter plain
address@hidden completely, and use @samp{\} in the @TeX{} commands, by
-delineating a region with the @code{@@tex} and @code{@@end tex}
-commands. All plain @TeX{} commands and category codes are restored
-within an @code{@@tex} region. The sole exception is that the
address@hidden@@} 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.
-
address@hidden \gdef @r{within @code{@@tex}}
address@hidden \globaldefs @r{within @code{@@tex}}
-In complex cases, you may wish to define new @TeX{} macros within
address@hidden@@tex}. You must use @code{\gdef} to do this, not @code{\def},
-because @code{@@tex} regions are processed in a @TeX{} group. If you
-need to make several definitions, you may wish to set
address@hidden (its value will be restored to zero as usual when
-the group ends at @code{@@end tex}, so it won't cause problems with
-the rest of the document).
-
address@hidden Equation, displayed, in plain @TeX{}
address@hidden Displayed equation, in plain @TeX{}
-As an example, here is a displayed equation written in plain @TeX{}:
-
address@hidden
-@@tex
-$$ \chi^2 = address@hidden@}^N
- \left (y_i - (a + b x_i)
- \over \sigma_i\right)^2 $$
-@@end tex
address@hidden example
-
address@hidden
-The output of this example will appear only in a printed manual. If
-you are reading this in a format not generated by @TeX{}, you will not
-see the equation that appears in the printed manual.
-
address@hidden
-$$ \chi^2 = \sum_{i=1}^N
- \left(y_i - (a + b x_i)
- \over \sigma_i\right)^2 $$
address@hidden tex
-
address@hidden HTML, including raw
address@hidden ifhtml
address@hidden html
-Analogously, you can use @code{@@ifhtml @dots{} @@end ifhtml} to
-delimit Texinfo source to be included in HTML output only, and
address@hidden@@html @dots{} @@end html} for a region of raw HTML.
-
address@hidden XML, including raw
address@hidden ifxml
address@hidden xml
-Likewise, you can use @code{@@ifxml @dots{} @@end ifxml} to delimit
-Texinfo source to be included in XML output only, and @code{@@xml
address@hidden @@end xml} for a region of raw address@hidden Regions of raw
text in
-other formats will also be present in the XML output, but with
-protection of XML characters and within corresponding elements. For
-example, the raw HTML text:
-
address@hidden
address@hidden
-@@html
-<br />
-@@end html
address@hidden group
address@hidden example
-
address@hidden
-will be included in the XML output as:
-
address@hidden
address@hidden
-<html>
-<br />
-</html>
address@hidden group
address@hidden example
-
address@hidden Docbook, including raw
address@hidden ifdocbook
address@hidden docbook
-Again likewise, you can use @code{@@ifdocbook @dots{} @@end ifdocbook}
-to delimit Texinfo source to be included in Docbook output only, and
address@hidden@@docbook @dots{} @@end docbook} for a region of raw Docbook.
-
-The behavior of newlines in raw regions is unspecified.
-
-In all cases, in raw processing, @code{@@} retains the same meaning as
-in the remainder of the document. Thus, the Texinfo processors
-recognize and even execute, to some extent, the contents of the raw
-regions, regardless of the final output format. Therefore, specifying
-changes that globally affect the document inside a raw region leads to
-unpredictable and generally undesirable behavior. For example,
-giving the @code{@@kbdinputstyle} command inside a raw region.
-
-The remedy is simple: don't do that. Use the raw formatter commands
-for their intended purpose, of providing material directly in the
-underlying format. When you simply want to give different Texinfo
-specifications for different output formats, use the
address@hidden@@address@hidden conditionals and stay in Texinfo syntax.
-
-
-
address@hidden Inline Conditionals
address@hidden Inline Conditionals: @code{@@inline}, @code{@@inlineraw}
address@hidden inlinefmt
address@hidden inlineraw
address@hidden Inline conditionals
address@hidden Conditional commands, inline
address@hidden Brace-delimited conditional text
address@hidden Newlines, avoiding in conditionals
address@hidden Whitespace, controlling in conditionals
-
-Texinfo provides two conditional commands with arguments given within
-braces:
-
address@hidden @code
address@hidden @@address@hidden@var{format}, @address@hidden
-Process the Texinfo @var{text} if @var{format} output is being
-generated.
-
address@hidden @@address@hidden@var{format}, @address@hidden
-Similar, but for raw @var{text} (@pxref{Raw Formatter Commands}).
address@hidden table
-
-For example,
-
address@hidden
-@@address@hidden, @@address@hidden address@hidden@}
address@hidden example
-
address@hidden is nearly equivalent to
-
address@hidden
-@@ifhtml
-@@address@hidden address@hidden
-@@end ifhtml
address@hidden example
-
address@hidden except that no whitespace is added, as happens in the latter
-(environment) case.
-
-In these commands, whitespace is ignored after the comma separating
-the two arguments, as usual, but is @emph{not} ignored at the end of
address@hidden
-
-In the case of @code{@@inlineraw}, to insert a literal at sign, left
-brace, or right brace, you must use the alphabetic commands
address@hidden@@address@hidden@}} (@pxref{Inserting an Atsign}), and
address@hidden@@address@hidden@}} or @code{@@address@hidden@}} (@pxref{Inserting
-Braces}), or the parsing will become confused. (By the way, it is not
-necessary to use @code{@@address@hidden@}}, since these commands always have
-exactly two arguments, so a @samp{,} cannot be mistaken for an
-argument separator.)
-
-
address@hidden @t{@@set @@clear @@value}
address@hidden @code{@@set}, @code{@@clear}, and @code{@@value}
-
address@hidden clear address@hidden old name
-You can direct the Texinfo formatting commands to format or ignore parts
-of a Texinfo file with the @code{@@set}, @code{@@clear}, @code{@@ifset},
-and @code{@@ifclear} commands.
-
-Here are brief descriptions of these commands, see the following
-sections for more details:
-
address@hidden @code
address@hidden @@set @var{flag} address@hidden
-Set the variable @var{flag}, to the optional @var{value} if specified.
-
address@hidden @@clear @var{flag}
-Undefine the variable @var{flag}, whether or not it was previously defined.
-
address@hidden @@ifset @var{flag}
-If @var{flag} is set, text through the next @code{@@end ifset} command
-is formatted. If @var{flag} is clear, text through the following
address@hidden@@end ifset} command is ignored.
-
address@hidden @@ifclear @var{flag}
-If @var{flag} is set, text through the next @code{@@end ifclear} command
-is ignored. If @var{flag} is clear, text through the following
address@hidden@@end ifclear} command is formatted.
address@hidden table
-
address@hidden
-* @t{@@set @@value}:: Expand a flag variable to a string.
-* @t{@@ifset @@ifclear}:: Format a region if a flag is set.
-* @t{@@value} Example:: An easy way to update edition information.
address@hidden menu
-
-
address@hidden @t{@@set @@value}
address@hidden @code{@@set} and @code{@@value}
-
address@hidden address@hidden old name
address@hidden set
address@hidden value
address@hidden clear
-
-You use the @code{@@set} command to specify a value for a flag, which
-is later expanded by the @code{@@value} command.
-
-A @dfn{flag} (aka @dfn{variable}) name is an identifier starting with
-an alphanumeric, @samp{-}, or @samp{_}. Subsequent characters, if
-any, may not be whitespace, @samp{@@}, braces, angle brackets, or any
-of @samp{~`^+|}; other characters, such as @samp{%}, may work.
-However, it is best to use only letters and numerals in a flag name,
-not @samp{-} or @samp{_} or others---they will work in some contexts,
-but not all, due to limitations in @TeX{}.
-
-The value is the remainder of the input line, and can contain anything.
-However, unlike most other commands which take the rest of the line as
-a value, @code{@@set} need not appear at the beginning of a line.
-
-Write the @code{@@set} command like this:
-
address@hidden
-@@set foo This is a string.
address@hidden example
-
address@hidden
-This sets the value of the flag @code{foo} to ``This is a string.''.
-
-The Texinfo formatters then replace an @code{@@address@hidden@address@hidden
-command with the string to which @var{flag} is set. Thus, when
address@hidden is set as shown above, the Texinfo formatters convert this:
-
address@hidden
address@hidden
-@@address@hidden@}
address@hidden @r{to this:}
-This is a string.
address@hidden group
address@hidden example
-
-You can write an @code{@@value} command within a paragraph; but you
-must write an @code{@@set} command on a line of its own.
-
-If you write the @code{@@set} command like this:
-
address@hidden
-@@set foo
address@hidden example
-
address@hidden
-without specifying a string, the value of @code{foo} is the empty string.
-
-If you clear a previously set flag with @code{@@clear @var{flag}}, a
-subsequent @code{@@address@hidden@}} command will report an error.
-
-For example, if you set @code{foo} as follows:
-
address@hidden
-@@set howmuch very, very, very
address@hidden example
-
address@hidden
-then the formatters transform
-
address@hidden
address@hidden
-It is a @@address@hidden@} wet day.
address@hidden @r{into}
-It is a very, very, very wet day.
address@hidden group
address@hidden example
-
-If you write
-
address@hidden
-@@clear howmuch
address@hidden example
-
address@hidden
-then the formatters transform
-
address@hidden
address@hidden
-It is a @@address@hidden@} wet day.
address@hidden @r{into}
-It is a @{No value for "howmuch"@} wet day.
address@hidden group
address@hidden example
-
address@hidden@@value} cannot be reliably used as the argument to an accent
-command (@pxref{Inserting Accents}). For example, this fails:
-
address@hidden
-@@set myletter a
-@@'@@address@hidden@} @c fails!
address@hidden example
-
-
address@hidden @t{@@ifset @@ifclear}
address@hidden @code{@@ifset} and @code{@@ifclear}
-
address@hidden address@hidden old name
address@hidden ifset
-
-When a @var{flag} is set, the Texinfo formatting commands format text
-between subsequent pairs of @code{@@ifset @var{flag}} and @code{@@end
-ifset} commands. When the @var{flag} is cleared, the Texinfo formatting
-commands do @emph{not} format the text. @code{@@ifclear} operates
-analogously.
-
-Write the conditionally formatted text between @code{@@ifset @var{flag}}
-and @code{@@end ifset} commands, like this:
-
address@hidden
address@hidden
-@@ifset @var{flag}
address@hidden
-@@end ifset
address@hidden group
address@hidden example
-
-For example, you can create one document that has two variants, such as
-a manual for a `large' and `small' model:
-
address@hidden Shrubbery
address@hidden
-You can use this machine to dig up shrubs
-without hurting them.
-
-@@set large
-
-@@ifset large
-It can also dig up fully grown trees.
-@@end ifset
-
-Remember to replant promptly @dots{}
address@hidden example
-
address@hidden
-In the example, the formatting commands will format the text between
address@hidden@@ifset large} and @code{@@end ifset} because the @code{large}
-flag is set.
-
-When @var{flag} is cleared, the Texinfo formatting commands do
address@hidden format the text between @code{@@ifset @var{flag}} and
address@hidden@@end ifset}; that text is ignored and does not appear in either
-printed or Info output.
-
-For example, if you clear the flag of the preceding example by writing
-an @code{@@clear large} command after the @code{@@set large} command
-(but before the conditional text), then the Texinfo formatting commands
-ignore the text between the @code{@@ifset large} and @code{@@end ifset}
-commands. In the formatted output, that text does not appear; in both
-printed and Info output, you see only the lines that say, ``You can use
-this machine to dig up shrubs without hurting them. Remember to replant
-promptly @dots{}''.
-
address@hidden ifclear
-If a flag is cleared with an @code{@@clear @var{flag}} command, then
-the formatting commands format text between subsequent pairs of
address@hidden@@ifclear} and @code{@@end ifclear} commands. But if the flag
-is set with @code{@@set @var{flag}}, then the formatting commands do
address@hidden format text between an @code{@@ifclear} and an @code{@@end
-ifclear} command; rather, they ignore that text. An @code{@@ifclear}
-command looks like this:
-
address@hidden
-@@ifclear @var{flag}
address@hidden example
-
-
address@hidden @t{@@value} Example
address@hidden @code{@@value} Example
-
address@hidden address@hidden old name
-
-You can use the @code{@@value} command to minimize the number of
-places you need to change when you record an update to a manual.
address@hidden Sample Texts}, for the full text of an example of using this
-to work with Automake distributions.
-
-This example is adapted from @ref{Top,,, make, The GNU Make Manual}.
-
address@hidden
address@hidden
-Set the flags:
-
address@hidden
address@hidden
-@@set EDITION 0.35 Beta
-@@set VERSION 3.63 Beta
-@@set UPDATED 14 August 1992
-@@set UPDATE-MONTH August 1992
address@hidden group
address@hidden example
-
address@hidden
-Write text for the @code{@@copying} section (@address@hidden@@copying}}):
-
address@hidden
address@hidden
-@@copying
-This is Edition @@address@hidden@},
-last updated @@address@hidden@},
-of @@address@hidden GNU Make address@hidden,
-for @@address@hidden@}, version @@address@hidden@}.
-
-Copyright @dots{}
-
-Permission is granted @dots{}
-@@end copying
address@hidden group
address@hidden example
-
address@hidden
-Write text for the title page, for people reading the printed manual:
-
address@hidden
address@hidden
-@@titlepage
-@@title GNU Make
-@@subtitle A Program for Directing Recompilation
-@@subtitle Edition @@address@hidden@}, @dots{}
-@@subtitle @@address@hidden@}
-@@page
-@@insertcopying
address@hidden
-@@end titlepage
address@hidden group
address@hidden example
-
address@hidden
-(On a printed cover, a date listing the month and the year looks less
-fussy than a date listing the day as well as the month and year.)
-
address@hidden
-Write text for the Top node, for people reading the Info file:
-
address@hidden
address@hidden
-@@ifnottex
-@@node Top
-@@top Make
-
-@@insertcopying
address@hidden
-@@end ifnottex
address@hidden group
address@hidden example
-
-After you format the manual, the @code{@@value} constructs have been
-expanded, so the output contains text like this:
-
address@hidden
address@hidden
-This is Edition 0.35 Beta, last updated 14 August 1992,
-of `The GNU Make Manual', for `make', Version 3.63 Beta.
address@hidden group
address@hidden example
address@hidden enumerate
-
-When you update the manual, you change only the values of the flags; you
-do not need to edit the three sections.
-
-
address@hidden Testing for Texinfo Commands
address@hidden Testing for Texinfo Commands: @code{@@ifcommanddefined},
@code{@@ifcommandnotdefined}
-
address@hidden Testing for Texinfo commands
address@hidden Checking for Texinfo commands
address@hidden Texinfo commands, testing for
address@hidden Commands, testing for Texinfo
address@hidden Versions of Texinfo, adapting to
address@hidden Features of Texinfo, adapting to
-
-Occasionally, you may want to arrange for your manual to test if a
-given Texinfo command is available and (presumably) do some sort of
-fallback formatting if not. There are conditionals
address@hidden@@ifcommanddefined} and @code{@@ifcommandnotdefined} to do this.
-For example:
-
address@hidden
-@@ifcommanddefined node
-Good, @@address@hidden@@@@address@hidden is defined.
-@@end ifcommanddefined
address@hidden example
-
address@hidden will output the expected `Good, @samp{@@node} is defined.'.
-
-This conditional will also consider true any new commands defined by
-the document via @code{@@macro}, @code{@@alias},
address@hidden@@definfoenclose}, and
@code{@@address@hidden(address@hidden)}index}
-(@pxref{Defining New Texinfo Commands}). Caveat: the @TeX{}
-implementation reports internal @TeX{} commands, in addition to all
-the Texinfo commands, as being ``defined''; the @code{makeinfo}
-implementation is reliable in this regard, however.
-
address@hidden @file{NEWS} file for Texinfo
-You can check the @file{NEWS} file in the Texinfo source distribution
-and linked from the Texinfo home page
-(@url{http://www.gnu.org/software/texinfo}) to see when a particular
-command was added.
-
-These command-checking conditionals themselves were added in
address@hidden, released in 2013---decades after Texinfo's
-inception. In order to test if they themselves are available,
-the predefined flag @code{txicommandconditionals} can be tested, like
-this:
-
address@hidden
-@@ifset txicommandconditionals
-@@ifcommandnotdefined foobarnode
-(Good, @samp{@@foobarnode} is not defined.)
-@@end ifcommandnotdefined
-@@end ifset
address@hidden example
-
-Since flags (see the previous section) were added early in the
-existence of Texinfo, there is no problem with assuming they are
-available.
-
-We recommend avoiding these tests whenever possible---which is usually
-the case. For many software packages, it is reasonable for all
-developers to have a given version of Texinfo (or newer) installed,
-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.
-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
-general, to avoid unnecessary dependencies between packages
-(@pxref{Releases,,, standard, GNU Coding Standards}).
-
-
address@hidden Conditional Nesting
address@hidden Conditional Nesting
address@hidden Conditionals, nested
address@hidden Nesting conditionals
-
-Conditionals can be nested; however, the details are a little tricky.
-The difficulty comes with failing conditionals, such as
address@hidden@@ifhtml} when HTML is not being produced, where the included
-text is to be ignored. However, it is not to be @emph{completely}
-ignored, since it is useful to have one @code{@@ifset} inside another,
-for example---that is a way to include text only if two conditions are
-met. Here's an example:
-
address@hidden
-@@ifset somevar
-@@ifset anothervar
-Both somevar and anothervar are set.
-@@end ifset
-@@ifclear anothervar
-Somevar is set, anothervar is not.
-@@end ifclear
-@@end ifset
address@hidden example
-
-Technically, Texinfo requires that for a failing conditional, the
-ignored text must be properly nested with respect to that failing
-conditional. Unfortunately, it's not always feasible to check that
address@hidden conditionals are properly nested, because then the
-processors could have to fully interpret the ignored text, which
-defeats the purpose of the command. Here's an example illustrating
-these rules:
-
address@hidden
-@@ifset a
-@@ifset b
-@@ifclear ok - ok, ignored
-@@end junky - ok, ignored
-@@end ifset
-@@c WRONG - missing @@end ifset.
address@hidden example
-
-Finally, as mentioned above, all conditional commands must be on lines
-by themselves, with no text (even spaces) before or after. Otherwise,
-the processors cannot reliably determine which commands to consider
-for nesting purposes.
-
-
address@hidden Defining New Texinfo Commands
address@hidden Defining New Texinfo Commands
-
address@hidden Macros
address@hidden Defining new Texinfo commands
address@hidden New Texinfo commands, defining
address@hidden Texinfo commands, defining new
address@hidden User-defined Texinfo commands
-
-Texinfo provides several ways to define new commands:
-
address@hidden @bullet
address@hidden
-A Texinfo @dfn{macro} allows you to define a new Texinfo command as any
-sequence of text and/or existing commands (including other macros). The
-macro can have any number of @dfn{parameters}---text you supply each
-time you use the macro.
-
-Incidentally, these macros have nothing to do with the @code{@@defmac}
-command, which is for documenting macros in the subject area of the
-manual (@pxref{Def Cmd Template}).
-
address@hidden
address@hidden@@alias} is a convenient way to define a new name for an existing
-command.
-
address@hidden
address@hidden@@definfoenclose} allows you to define new commands with
-customized output for all address@hidden output formats.
-
address@hidden itemize
-
-Most generally of all, not just for defining new commands, it is
-possible to invoke an external macro processor and have Texinfo
-recognize so-called @code{#line} directives for error reporting.
-
-If you want to do simple text substitution, @code{@@set} and
address@hidden@@value} is the simplest approach (@address@hidden@@set @@clear
-@@value}}).
-
address@hidden
-* Defining Macros:: Defining and undefining new commands.
-* Invoking Macros:: Using a macro, once you've defined it.
-* Macro Details:: Limitations of Texinfo macros.
-* @t{@@alias}:: Command aliases.
-* @t{@@definfoenclose}:: Customized highlighting.
-* External Macro Processors:: @code{#line} directives.
address@hidden menu
-
-
address@hidden Defining Macros
address@hidden Defining Macros
address@hidden Defining macros
address@hidden Macro definitions, Texinfo
-
address@hidden macro
-You use the Texinfo @code{@@macro} command to define a macro, like this:
-
address@hidden
-@@macro @address@hidden@var{param1}, @var{param2}, @address@hidden
address@hidden @dots{} address@hidden @dots{}
-@@end macro
address@hidden example
-
-The @dfn{parameters} @var{param1}, @var{param2}, @dots{} correspond to
-arguments supplied when the macro is subsequently used in the document
-(described in the next section).
-
address@hidden Macro names, valid characters in
address@hidden Names of macros, valid characters of
-For a macro to work consistently with @TeX{}, @var{macroname} must
-consist entirely of letters: no digits, hyphens, underscores, or other
-special characters. So, we recommend using only letters. However,
address@hidden will accept anything consisting of alphanumerics,
-and (except as the first character) @samp{-}. The @samp{_} character
-is excluded so that macros can be called inside @code{@@math} without
-a following space (@pxref{Inserting Math}).
-
-If a macro needs no parameters, you can define it either with an empty
-list (@samp{@@macro foo @address@hidden) or with no braces at all
(@samp{@@macro
-foo}).
-
address@hidden Body of a macro
-The definition or @dfn{body} of the macro can contain most Texinfo
-commands, including macro invocations. However, a macro definition
-that defines another macro does not work in @TeX{} due to limitations
-in the design of @code{@@macro}.
-
address@hidden Parameters to macros
-In the macro body, instances of a parameter name surrounded by
-backslashes, as in @address@hidden in the example above, are
-replaced by the corresponding argument from the macro invocation. You
-can use parameter names any number of times in the body, including zero.
-
address@hidden Backslash in macros
-To get a single @samp{\} in the macro expansion, use @samp{\\}. Any
-other use of @samp{\} in the body yields a warning.
-
address@hidden Spaces in macros
address@hidden Whitespace in macros
-The newline characters after the @code{@@macro} line and before the
address@hidden@@end macro} line are ignored, that is, not included in the
-macro body. All other whitespace is treated according to the usual
-Texinfo rules. However, there are still undesirable and unpredictable
-interactions between newlines, macros, and commands which are
-line-delimited, as warned about below (@pxref{Macro Details}).
-
address@hidden Recursive macro invocations
address@hidden rmacro
-To allow a macro to be used recursively, that is, in an argument to a
-call to itself, you must define it with @samp{@@rmacro}, like this:
-
address@hidden
-@@rmacro rmac @address@hidden
-a\arg\b
-@@end rmacro
address@hidden
-@@address@hidden@@address@hidden@address@hidden
address@hidden example
-
-This produces the output `a1atextb2b'. With @samp{@@macro} instead of
address@hidden@@rmacro}, an error message is given.
-
address@hidden unmacro
address@hidden Macros, undefining
address@hidden Undefining macros
-You can undefine a macro @var{foo} with @code{@@unmacro @var{foo}}.
-It is not an error to undefine a macro that is already undefined.
-For example:
-
address@hidden
-@@unmacro foo
address@hidden example
-
-
address@hidden Invoking Macros
address@hidden Invoking Macros
-
address@hidden Invoking macros
address@hidden Expanding macros
address@hidden Running macros
address@hidden Macro invocation
-
-After a macro is defined (see the previous section), you can
address@hidden (use) it in your document like this:
-
address@hidden
-@@@var{macroname} @address@hidden, @var{arg2}, @address@hidden
address@hidden example
-
address@hidden and the result will be more or less as if you typed the body of
address@hidden at that spot. For example:
-
address@hidden
-@@macro foo @{p, address@hidden
-Together: \p\ & \q\.
-@@end macro
-@@address@hidden, address@hidden
address@hidden example
-
address@hidden produces:
-
address@hidden
-Together: a & b.
address@hidden display
-
address@hidden Backslash, and macros
-Thus, the arguments and parameters are separated by commas and
-delimited by braces; any whitespace after (but not before) a comma is
-ignored. The braces are required in the invocation even when the
-macro takes no arguments, consistent with other Texinfo commands. For
-example:
-
address@hidden
-@@macro argless @address@hidden
-No arguments here.
-@@end macro
-@@address@hidden@}
address@hidden example
-
address@hidden produces:
-
address@hidden
-No arguments here.
address@hidden display
-
address@hidden Comma, in macro arguments
-Passing macro arguments containing commas requires special care, since
-commas also separate the arguments. To include a comma character in
-an argument, the most reliable method is to use the @code{@@address@hidden@}}
-command. For @code{makeinfo}, you can also prepend a backslash
-character, as in @samp{\,}, but this does not work with @TeX{}.
-
address@hidden Automatic quoting of commas for some macros
address@hidden Quoting, automatic for some macros
-It's not always necessary to worry about commas. To facilitate use of
-macros, @command{makeinfo} implements two rules for @dfn{automatic
-quoting} in some circumstances:
-
address@hidden 1
address@hidden If a macro takes only one argument, all commas in its invocation
-are quoted by default. For example:
-
address@hidden
address@hidden
-@@macro address@hidden@}
-@@address@hidden: address@hidden
-@@end macro
-
-@@address@hidden nice feature, though it can be address@hidden
address@hidden group
address@hidden example
-
address@hidden
-will produce the following output
-
address@hidden
address@hidden: A nice feature, though it can be dangerous.}
address@hidden example
-
-And indeed, it can. Namely, @command{makeinfo} does not control the
-number of arguments passed to one-argument macros, so be careful when
-you invoke them.
-
address@hidden If a macro invocation includes another command (including a
-recursive invocation of itself), any commas in the nested command
-invocation(s) are quoted by default. For example, in
-
address@hidden
-@@address@hidden@@address@hidden, I address@hidden, person address@hidden
address@hidden example
-
-the comma after @samp{Yes} is implicitly quoted. Here's another
-example, with a recursive macro:
-
address@hidden
address@hidden
-@@rmacro address@hidden,address@hidden
-\a\\b\
-@@end rmacro
-
-@@address@hidden@@address@hidden, address@hidden, address@hidden
address@hidden group
address@hidden example
-
address@hidden
-will produce the string @samp{foobarbaz}.
-
address@hidden Otherwise, a comma should be explicitly quoted, as above, for it
-to be treated as a part of an argument.
address@hidden enumerate
-
address@hidden Braces, in macro arguments
address@hidden Backslash, in macro arguments
-In addition to the comma, characters that need to be quoted in macro
-arguments are curly braces and backslash. For example:
-
address@hidden
-@@@var{macname} @address@hidden@}\,@}
address@hidden example
-
address@hidden
-will pass the (almost certainly error-producing) argument
address@hidden@address@hidden,} to @var{macname}.
-
-Unfortunately, this has not been reliably implemented in @TeX{}. When
-macros are used in the argument to other commands, for example, errors
-or incorrect output (the @samp{\} ``escape'' being included literally)
-are likely to result.
-
-If a macro is defined to take exactly one argument, it can (but need
-not) be invoked without any braces; then the entire rest of the line
-after the macro name is used as the argument. (Braces around the
-argument(s) are required in all other cases, i.e., if the macro takes
-either zero or more than one argument.) For example:
-
address@hidden
-@@macro bar @address@hidden
-Twice: \p\ & \p\.
-@@end macro
-@@bar aah
address@hidden example
-
address@hidden produces:
-
address@hidden
-Twice: aah & aah.
address@hidden display
-
-Likewise, if a macro is defined to take exactly one argument, and is
-invoked with braces, the braced text is passed as the argument, also
-regardless of commas. For example:
-
address@hidden
-@@macro bar @address@hidden
-Twice: \p\ & \p\.
-@@end macro
-@@address@hidden,address@hidden
address@hidden example
-
address@hidden produces:
-
address@hidden
-Twice: a,b & a,b.
address@hidden display
-
-If a macro is defined to take more than one argument, but is called
-with only one (in braces), the remaining arguments are set to the
-empty string, and no error is given. For example:
-
address@hidden
-@@macro addtwo @{p, address@hidden
-Both: \p\\q\.
-@@end macro
-@@address@hidden@}
address@hidden example
-
address@hidden produces simply:
-
address@hidden
-Both: a.
address@hidden display
-
-
address@hidden Macro Details
address@hidden Macro Details and Caveats
address@hidden Macro details
address@hidden Details of macro usage
address@hidden Caveats for macro usage
-
address@hidden Macro expansion, contexts for
address@hidden Expansion of macros, contexts for
-By design, macro expansion does not happen in the following contexts
-in @command{makeinfo}:
-
address@hidden @bullet
address@hidden @code{@@macro} and @code{@@unmacro} lines;
-
address@hidden @code{@@if...} lines, including @code{@@ifset} and similar;
-
address@hidden @code{@@set}, @code{@@clear}, @code{@@value};
-
address@hidden @code{@@clickstyle} lines;
-
address@hidden @code{@@end} lines.
address@hidden itemize
-
address@hidden Unfortunately, @TeX{} may do some expansion in these situations,
-possibly yielding errors.
-
-Also, quite a few macro-related constructs cause problems with @TeX{};
-some of the caveats are listed below. Thus, if you get macro-related
-errors when producing the printed version of a manual, you might try
-expanding the macros with @command{makeinfo} by invoking
address@hidden with the @samp{-E} option (@pxref{Format with
address@hidden). Or, more reliably, eschew Texinfo macros altogether
-and use a language designed for macro processing, such as M4
-(@pxref{External Macro Processors}).
-
address@hidden @bullet
address@hidden
-As mentioned earlier, macro names must consist entirely of letters.
-
address@hidden
-It is not advisable to redefine any @TeX{} primitive, plain, or
-Texinfo command name as a macro. Unfortunately this is a large and
-open-ended set of names, and the possible resulting errors are
-unpredictable.
-
address@hidden
-All macros are expanded inside at least one @TeX{} group.
-
address@hidden
-Macro arguments cannot cross lines.
-
address@hidden
-Macros containing a command which must be on a line by itself, such as
-a conditional, cannot be invoked in the middle of a line. Similarly,
-macros containing line-oriented commands or text, such as
address@hidden@@example} environments, may behave unpredictably in @TeX{}.
-
address@hidden
-White space is ignored at the beginnings of lines.
-
address@hidden
-Macros can't be reliably used in the argument to accent commands
-(@pxref{Inserting Accents}).
-
address@hidden
-The backslash escape for commas in macro arguments does not work;
address@hidden@@address@hidden@}} must be used.
-
address@hidden
-As a consequence, if a macro takes two or more arguments, and you want
-to pass an argument with the Texinfo command @code{@@,} (to produce a
-cedilla, @pxref{Inserting Accents}), you have to use @code{@@value} or
-another work-around. Otherwise, @TeX{} takes the comma as separating
-the arguments. Example:
-
address@hidden
-@@macro address@hidden, address@hidden
-\argfirst\+\argsecond\.
-@@end macro
-@@set fc Fran@@,cois
-@@address@hidden@@address@hidden@address@hidden
address@hidden example
-
address@hidden produces:
-
address@hidden
-Fran@,cois+.
address@hidden display
-
-The natural-seeming @code{@@address@hidden@@,address@hidden passes the two
-arguments @samp{Fran@@} and @samp{cois} to the macro, and nothing good
-results. And, as just mentioned, although the comma can be escaped
-with a backslash for @code{makeinfo} (@samp{@@\,}), that doesn't work
-in @TeX{}, so there is no other solution.
-
address@hidden
-It is usually best to avoid comments inside macro definitions, but
-see the next item.
-
address@hidden
-In general, the interaction of newlines in the macro definitions and
-invocations depends on the precise commands and context,
-notwithstanding the previous statements. You may be able to work
-around some problems with judicious use of @code{@@c}. Suppose you
-define a macro that is always used on a line by itself:
-
address@hidden
-@@macro linemac
-@@cindex whatever @@c
-@@end macro
-...
-foo
-@@linemac
-bar
address@hidden example
-
-Without the @code{@@c}, there will be a unwanted blank line between
-the @samp{@@cindex whatever} and the @samp{bar} (one newline comes
-from the macro definition, one from after the invocation), causing an
-unwanted paragraph break.
-
-On the other hand, you wouldn't want the @code{@@c} if the macro was
-sometimes invoked in the middle of a line (the text after the
-invocation would be treated as a comment).
-
address@hidden
-In general, you can't arbitrarily substitute a macro (or
address@hidden@@value}) call for Texinfo command arguments, even when the text
-is the same. Texinfo is not M4 (or even plain @TeX{}). It might work
-with some commands, it fails with others. Best not to do it at all.
-For instance, this fails:
-
address@hidden
-@@macro offmacro
-off
-@@end macro
-@@headings @@offmacro
address@hidden example
-
address@hidden
-This looks equivalent to @code{@@headings off}, but for @TeX{}nical
-reasons, it fails with a mysterious error message (namely,
address@hidden ended before @@headings was complete}).
-
address@hidden
-Macros cannot define macros in the natural way. To do this, you must
-use conditionals and raw @TeX{}. For example:
-
address@hidden
-@@ifnottex
-@@macro ctor @{name, address@hidden
-@@macro \name\
-something involving \arg\ somehow
-@@end macro
-@@end macro
-@@end ifnottex
-@@tex
address@hidden,@}
-\gdef\ctorx#1,#2,@address@hidden involving #2 address@hidden@}
-@@end tex
address@hidden example
address@hidden itemize
-
-The @command{makeinfo} implementation also has the following
-limitations (by design):
-
address@hidden
address@hidden
address@hidden@@verbatim} and macros do not mix; for instance, you can't start
-a verbatim block inside a macro and end it outside
-(@address@hidden@@verbatim}}). Starting any environment inside a macro
-and ending it outside may or may not work, for that matter.
-
address@hidden
-Macros that completely define macros are ok, but it's not possible to
-have incompletely nested macro definitions. That is, @code{@@macro}
-and @code{@@end macro} (likewise for @code{@@rmacro}) must be
-correctly paired. For example, you cannot start a macro definition
-within a macro, and then end that nested definition outside the macro.
address@hidden itemize
-
-In the @code{makeinfo} implementation before Texinfo 5.0, ends of
-lines from expansion of an @code{@@macro} definition did not end an
-@@-command line-delimited argument (@code{@@chapter}, @code{@@center},
-etc.). This is no longer the case. For example:
-
address@hidden
-@@macro address@hidden@}
-aaa
-bbb
-@@end macro
-@@center @@address@hidden@}
address@hidden example
-
-In the current @code{makeinfo}, this is equivalent to:
-
address@hidden
-@@center aaa
-bbb
address@hidden example
-
address@hidden with just @samp{aaa} as the argument to @code{@@center}. In
-the earlier implementation, it would have been parsed as this:
-
address@hidden
-@@center aaa bbb
address@hidden example
-
-
address@hidden @t{@@alias}
address@hidden @samp{@@alias @address@hidden
-
address@hidden@c old name
address@hidden Aliases, command
address@hidden Command aliases
address@hidden alias
-
-The @samp{@@alias} command defines a new command to be just like an
-existing one. This is useful for defining additional markup names,
-thus preserving additional semantic information in the input even
-though the output result may be the same.
-
-Write the @samp{@@alias} command on a line by itself, followed by the
-new command name, an equals sign, and the existing command name.
-Whitespace around the equals sign is optional and ignored if present.
-Thus:
-
address@hidden
-@@alias @var{new} = @var{existing}
address@hidden example
-
-For example, if your document contains citations for both books and
-some other media (movies, for example), you might like to define a
-macro @code{@@address@hidden@}} that does the same thing as an ordinary
address@hidden@@address@hidden@}} but conveys the extra semantic information as
well.
-You'd do this as follows:
-
address@hidden
-@@alias moviecite = cite
address@hidden example
-
-Macros do not always have the same effect as aliases, due to vagaries
-of argument parsing. Also, aliases are much simpler to define than
-macros. So the command is not redundant.
-
-Unfortunately, it's not possible to alias Texinfo environments; for
-example, @code{@@alias lang=example} is an error.
-
-Aliases must not be recursive, directly or indirectly.
-
-It is not advisable to redefine any @TeX{} primitive, plain @TeX{}, or
-Texinfo command name as an alias. Unfortunately this is a very large
-set of names, and the possible resulting errors from @TeX{} are
-unpredictable.
-
address@hidden will accept the same identifiers for aliases as it
-does for macro names, that is, alphanumerics and (except as the first
-character) @samp{-}.
-
-
address@hidden @t{@@definfoenclose}
address@hidden @code{@@definfoenclose}: Customized Highlighting
-
address@hidden@c old name
address@hidden Highlighting, customized
address@hidden Customized highlighting
address@hidden definfoenclose
-
-An @code{@@definfoenclose} command may be used to define a
-highlighting command for all the address@hidden 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.
-
-Presumably, if you define a command with @code{@@definfoenclose}, you
-will create a corresponding command for @TeX{}, either in
address@hidden, @file{texinfo.cnf}, or within an @samp{@@iftex} of
address@hidden@@tex} in your document.
-
-Write an @code{@@definfoenclose} command at the beginning of a line
-followed by three comma-separated arguments. The first argument to
address@hidden@@definfoenclose} is the @@-command name (without the
address@hidden@@}); the second argument is the start delimiter string; and the
-third argument is the end delimiter string. The latter two arguments
-enclose the highlighted text in the output.
-
-A delimiter string may contain spaces. Neither the start nor end
-delimiter is required. If you do not want a start delimiter but do
-want an end delimiter, you must follow the command name with two
-commas in a row; otherwise, the end delimiter string you intended will
-naturally be (mis)interpreted as the start delimiter string.
-
-If you do an @code{@@definfoenclose} on the name of a predefined
-command (such as @code{@@emph}, @code{@@strong}, @code{@@t}, or
address@hidden@@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}).
-
address@hidden phoo
-For example, you can write:
-
address@hidden
-@@definfoenclose phoo,//,\\
address@hidden example
-
address@hidden
-near the beginning of a Texinfo file to define @code{@@phoo} as an Info
-formatting command that inserts `//' before and `\\' after the argument
-to @code{@@phoo}. You can then write @code{@@address@hidden@}} wherever you
-want `//bar\\' highlighted in Info.
-
-For @TeX{} formatting, you could write
-
address@hidden
-@@iftex
-@@global@@let@@phoo=@@i
-@@end iftex
address@hidden example
-
address@hidden
-to define @code{@@phoo} as a command that causes @TeX{} to typeset the
-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
address@hidden@@iftex}. @code{@@definfoenclose} command need not be within
address@hidden@@ifinfo}, unless you want to use different definitions for
-different output formats.
-
address@hidden headword
-Here is another example: write
-
address@hidden
-@@definfoenclose headword, , :
address@hidden example
-
address@hidden
-near the beginning of the file, to define @code{@@headword} as an Info
-formatting command that inserts nothing before and a colon after the
-argument to @code{@@headword}.
-
address@hidden@@definfoenclose} definitions must not be recursive, directly or
-indirectly.
-
-
address@hidden External Macro Processors
address@hidden External Macro Processors: Line Directives
address@hidden External macro processors
address@hidden Macro processors, external
-
-Texinfo macros (and its other text substitution facilities) work fine
-in straightforward cases. If your document needs unusually complex
-processing, however, their fragility and limitations can be a problem.
-In this case, you may want to use a different macro processor
-altogether, such as M4 (@pxref{Top,,, m4, M4}) or CPP (@pxref{Top,,,
-cpp, The C Preprocessor}).
-
-With one exception, Texinfo does not need to know whether its input is
-``original'' source or preprocessed from some other source file.
-Therefore, you can arrange your build system to invoke whatever
-programs you like to handle macro expansion or other preprocessing
-needs. Texinfo does not offer built-in support for any particular
-preprocessor, since no one program seemed likely to suffice for the
-requirements of all documents.
-
address@hidden Line numbers, in error messages
address@hidden Error messages, line numbers in
-The one exception is line numbers in error messages. In that case,
-the line number should refer to the original source file, whatever it
-may be. There's a well-known mechanism for this: the so-called
address@hidden directive. Texinfo supports this.
-
address@hidden
-* @t{#line} Directive::
-* TeX: @t{#line} and @TeX{}.
-* Syntax: @t{#line} Syntax Details.
address@hidden menu
-
-
address@hidden @t{#line} Directive
address@hidden @samp{#line} Directive
-
address@hidden @samp{#line} directive
-
-An input line such as this:
-
address@hidden
address@hidden 100 "foo.ptexi"
address@hidden example
-
address@hidden indicates that the next line was line 100 of the file
address@hidden, and so that's what an error message should refer to.
-Both M4 (@pxref{Preprocessor features,,, m4, GNU M4}) and CPP
-(@pxref{Line Control,,, cpp, The C Preprocessor}, and
address@hidden Output,,, cpp, The C Preprocessor}) can generate
-such lines.
-
address@hidden CPP_LINE_DIRECTIVES
-The @command{makeinfo} program recognizes these lines by default,
-except within @code{@@verbatim} blocks (@address@hidden@@verbatim}}.
-Their recognition can be turned off completely with
address@hidden (@pxref{Other Customization Variables}),
-though there is normally no reason to do so.
-
-For those few programs (M4, CPP, Texinfo) which need to document
address@hidden directives and therefore have examples which would
-otherwise match the pattern, the command @code{@@address@hidden@}} can be
-used (@pxref{Inserting a Hashsign}). The example line above looks
-like this in the source for this manual:
-
address@hidden
-@@address@hidden@}line 100 "foo.ptexi"
address@hidden example
-
-The @code{@@hashchar} command was added to Texinfo in 2013. If you
-don't want to rely on it, you can also use @code{@@set} and
address@hidden@@value} to insert the literal @samp{#}:
-
address@hidden
-@@set hash #
-@@address@hidden@}line 1 "example.c"
address@hidden example
-
-Or, if suitable, an @code{@@verbatim} environment can be used instead
-of @code{@@example}. As mentioned above, @code{#line}-recognition is
-disabled inside verbatim blocks.
-
-
address@hidden @t{#line} and @TeX{}
address@hidden @samp{#line} and @TeX{}
-
address@hidden @TeX{} and @samp{#line} directives
address@hidden @samp{#line} directives, not processing with @TeX{}
-
-As mentioned, @command{makeinfo} recognizes the @samp{#line}
-directives described in the previous section. However,
address@hidden does not and cannot. Therefore, such a line will
-be incorrectly typeset verbatim if @TeX{} sees it. The solution is to
-use @command{makeinfo}'s macro expansion options before running
address@hidden There are three approaches:
-
address@hidden @bullet
address@hidden
-If you run @command{texi2dvi} or its variants (@pxref{Format with
address@hidden), you can pass @option{-E} and @command{texi2dvi}
-will run @command{makeinfo} first to expand macros and eliminate
address@hidden
-
address@hidden
-If you run @command{makeinfo} or its variants (@pxref{Generic
-Translator @t{texi2any}}), you can specify @option{--no-ifinfo
---iftex -E somefile.out}, and then give @file{somefile.out} to
address@hidden in a separate command.
-
address@hidden
-Or you can run @option{makeinfo --dvi --Xopt -E}. (Or @option{--pdf}
-instead of @option{--dvi}.) @command{makeinfo} will then call
address@hidden -E}.
address@hidden itemize
-
address@hidden address@hidden, and line numbers in @TeX{}}
-One last caveat regarding use with @TeX{}: since the @code{#line}
-directives are not recognized, the line numbers emitted by the
address@hidden@@address@hidden@}} command (@pxref{Conditional Commands}), or by
address@hidden itself, are the (incorrect) line numbers from the derived file
-which @TeX{} is reading, rather than the preprocessor-specified line
-numbers. This is another example of why we recommend running
address@hidden for the best diagnostics (@address@hidden
-Advantages}).
-
-
address@hidden @t{#line} Syntax Details
address@hidden @samp{#line} Syntax Details
-
address@hidden @samp{#line} syntax details
address@hidden Syntax details, @samp{#line}
address@hidden Regular expression, for @samp{#line}
-
-Syntax details for the @samp{#line} directive: the @samp{#} character
-can be preceded or followed by whitespace, the word @samp{line} is
-optional, and the file name can be followed by a whitespace-separated
-list of integers (these are so-called ``flags'' output by CPP in some
-cases). For those who like to know the gory details, the actual
-(Perl) regular expression which is matched is this:
-
address@hidden
-/^\s*#\s*(line)? (\d+)(( "([^"]+)")(\s+\d+)*)?\s*$/
address@hidden 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
-regular expression.
-
-As an example, the following is a syntactically valid @samp{#line}
-directive, meaning line 1 of @file{/usr/include/stdio.h}:
-
address@hidden
address@hidden 1 "/usr/include/stdio.h" 2 3 4
address@hidden example
-
-Unfortunately, the quoted filename (@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.,
-
address@hidden
address@hidden 1
address@hidden example
-
-The possible solutions are described above (@address@hidden Directive}).
-
-
address@hidden Include Files
address@hidden Include Files
-
address@hidden Include files
-
-When a Texinfo processor sees an @code{@@include} command in a Texinfo
-file, it processes the contents of the file named by the
address@hidden@@include} and incorporates them into the output files being
-created. Include files thus let you keep a single large document as a
-collection of conveniently small parts.
-
address@hidden
-* Using Include Files:: How to use the @code{@@include} command.
-* @t{texinfo-multiple-files-update}:: How to create and update nodes and
- menus when using included 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.
address@hidden menu
-
-
address@hidden Using Include Files
address@hidden How to Use Include Files
-
address@hidden include
-
-To include another file within a Texinfo file, write the
address@hidden@@include} command at the beginning of a line and follow it on
-the same line by the name of a file to be included. For example:
-
address@hidden
-@@include buffers.texi
address@hidden example
-
-@@-commands are expanded in file names. The one most likely to be
-useful is @code{@@value} (@address@hidden@@set @@value}}), and even then
-only in complicated situations.
-
-An included file should simply be a segment of text that you expect to
-be included as is into the overall or @dfn{outer} Texinfo file; it
-should not contain the standard beginning and end parts of a Texinfo
-file. In particular, you should not start an included file with a
-line saying @samp{\input texinfo}; if you do, that text is inserted
-into the output file literally. Likewise, you should not end an
-included file with an @code{@@bye} command; nothing after @code{@@bye}
-is formatted.
-
-In the long-ago past, you were required to write an
address@hidden@@setfilename} line at the beginning of an included file, but no
-longer. Now, it does not matter whether you write such a line. If an
address@hidden@@setfilename} line exists in an included file, it is ignored.
-
-
address@hidden @t{texinfo-multiple-files-update}
address@hidden @code{texinfo-multiple-files-update}
-
address@hidden texinfo-multiple-files-update
-
-GNU Emacs Texinfo mode provides the
address@hidden command. This command creates or
-updates `Next', `Previous', and `Up' pointers of included files as
-well as those in the outer or overall Texinfo file, and it creates or
-updates a main menu in the outer file. Depending on whether you call
-it with optional arguments, the command updates only the pointers in
-the first @code{@@node} line of the included files or all of them:
-
address@hidden @kbd
address@hidden M-x texinfo-multiple-files-update
-Called without any arguments:
-
address@hidden @minus
address@hidden
-Create or update the `Next', `Previous', and `Up' pointers of the
-first @code{@@node} line in each file included in an outer or overall
-Texinfo file.
-
address@hidden
-Create or update the `Top' level node pointers of the outer or
-overall file.
-
address@hidden
-Create or update a main menu in the outer file.
address@hidden itemize
-
address@hidden C-u M-x texinfo-multiple-files-update
-Called with @kbd{C-u} as a prefix argument:
-
address@hidden @minus{}
address@hidden
-Create or update pointers in the first @code{@@node} line in each
-included file.
-
address@hidden
-Create or update the `Top' level node pointers of the outer file.
-
address@hidden
-Create and insert a master menu in the outer file. The master menu
-is made from all the menus in all the included files.
address@hidden itemize
-
address@hidden C-u 8 M-x texinfo-multiple-files-update
-Called with a numeric prefix argument, such as @kbd{C-u 8}:
-
address@hidden @minus
address@hidden
-Create or update @strong{all} the `Next', `Previous', and `Up' pointers
-of all the included files.
-
address@hidden
-Create or update @strong{all} the menus of all the included
-files.
-
address@hidden
-Create or update the `Top' level node pointers of the outer or
-overall file.
-
address@hidden
-And then create a master menu in the outer file. This is similar to
-invoking @code{texinfo-master-menu} with an argument when you are
-working with just one file.
address@hidden itemize
address@hidden table
-
-Note the use of the prefix argument in interactive use: with a regular
-prefix argument, just @address@hidden, the
address@hidden command inserts a master menu;
-with a numeric prefix argument, such as @kbd{C-u 8}, the command
-updates @strong{every} pointer and menu in @strong{all} the files and
-then inserts a master menu.
-
-
address@hidden Include Files Requirements
address@hidden Include Files Requirements
address@hidden Include files requirements
address@hidden Requirements for include files
-
-If you plan to use the @code{texinfo-multiple-files-update} command,
-the outer Texinfo file that lists included files within it should
-contain nothing but the beginning and end parts of a Texinfo file, and
-a number of @code{@@include} commands listing the included files. It
-should not even include indices, which should be listed in an included
-file of their own.
-
-Moreover, each of the included files must contain exactly one highest
-level node (conventionally, @code{@@chapter} or equivalent),
-and this node must be the first node in the included file.
-Furthermore, each of these highest level nodes in each included file
-must be at the same hierarchical level in the file structure.
-Usually, each is an @code{@@chapter}, an @code{@@appendix}, or an
address@hidden@@unnumbered} node. Thus, normally, each included file contains
-one, and only one, chapter or equivalent-level node.
-
-The outer file should contain only @emph{one} node, the `Top' node. It
-should @emph{not} contain any nodes besides the single `Top' node. The
address@hidden command will not process
-them.
-
-
address@hidden Sample Include File
address@hidden Sample File with @code{@@include}
address@hidden Sample @code{@@include} file
address@hidden Include file sample
address@hidden @code{@@include} file sample
-
-Here is an example of an outer Texinfo file with @code{@@include} files
-within it before running @code{texinfo-multiple-files-update}, which
-would insert a main or master menu:
-
address@hidden
address@hidden
-\input texinfo @@c -*-texinfo-*-
address@hidden %**start of header
-@@setfilename include-example.info
-@@settitle Include Example
address@hidden %**end of header
address@hidden group
-
-... @xref{Sample Texinfo Files}, for
-examples of the rest of the frontmatter ...
-
address@hidden
-@@ifnottex
-@@node Top
-@@top Include Example
-@@end ifnottex
address@hidden group
-
address@hidden
-@@include foo.texinfo
-@@include bar.texinfo
-@@include concept-index.texinfo
-@@bye
address@hidden group
address@hidden example
-
-An included file, such as @file{foo.texinfo}, might look like this:
-
address@hidden
address@hidden
-@@node First
-@@chapter First Chapter
-
-Contents of first chapter @dots{}
address@hidden group
address@hidden example
-
-The full contents of @file{concept-index.texinfo} might be as simple as this:
-
address@hidden
address@hidden
-@@node Concept Index
-@@unnumbered Concept Index
-
-@@printindex cp
address@hidden group
address@hidden example
-
-The outer Texinfo source file for @cite{The GNU Emacs Lisp Reference
-Manual} is named @file{elisp.texi}. This outer file contains a master
-menu with 417 entries and a list of 41 @code{@@include}
-files.
-
-
address@hidden Include Files Evolution
address@hidden Evolution of Include Files
-
-When Info was first created, it was customary to create many small
-Info files on one subject. Each Info file was formatted from its own
-Texinfo source file. This custom meant that Emacs did not need to
-make a large buffer to hold the whole of a large Info file when
-someone wanted information; instead, Emacs allocated just enough
-memory for the small Info file that contained the particular
-information sought. This way, Emacs could avoid wasting memory.
-
-References from one file to another were made by referring to the file
-name as well as the node name. (@xref{Other Info Files, , Referring to
-Other Info Files}. Also, see @ref{Four and Five Arguments, ,
address@hidden@@xref} with Four and Five Arguments}.)
-
-Include files were designed primarily as a way to create a single,
-large printed manual out of several smaller Info files. In a printed
-manual, all the references were within the same document, so @TeX{}
-could automatically determine the references' page numbers. The Info
-formatting commands used include files only for creating joint
-indices; each of the individual Texinfo files had to be formatted for
-Info individually. (Each, therefore, required its own
address@hidden@@setfilename} line.)
-
-However, because large Info files are now split automatically, it is
-no longer necessary to keep them small.
-
-Nowadays, multiple Texinfo files are used mostly for large documents,
-such as @cite{The GNU Emacs Lisp Reference Manual}, and for projects
-in which several different people write different sections of a
-document simultaneously.
-
-In addition, the Info formatting commands have been extended to work
-with the @code{@@include} command so as to create a single large Info
-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.
-
-
address@hidden Hardcopy
address@hidden Formatting and Printing Hardcopy
address@hidden Format and print hardcopy
address@hidden Printing hardcopy
address@hidden Hardcopy, printing it
address@hidden Making a printed manual
address@hidden Sorting indices
address@hidden Indices, sorting
address@hidden @TeX{} index sorting
-
-Running the @command{texi2dvi} or @command{texi2pdf} command is the
-simplest way to create printable output. These commands are installed
-as part of the Texinfo package.
-
-More specifically, three major shell commands are used to print
-formatted output from a Texinfo manual: one converts the Texinfo
-source into something printable, a second sorts indices, and a third
-actually prints the formatted document. When you use the shell
-commands, you can either work directly in the operating system shell
-or work within a shell inside GNU Emacs (or some other computing
-environment).
-
-If you are using GNU Emacs, you can use commands provided by Texinfo
-mode instead of shell commands. In addition to the three commands to
-format a file, sort the indices, and print the result, Texinfo mode
-offers key bindings for commands to recenter the output buffer, show the
-print queue, and delete a job from the print queue.
-
-Details are in the following sections.
-
address@hidden
-* Use @TeX{}:: Use @TeX{} to format for hardcopy.
-* Format with @t{tex}/@t{texindex}:: How to format with explicit shell
commands.
-* Format with @t{texi2dvi}:: A simpler way to format.
-* Print with @t{lpr}:: How to print.
-* Within Emacs:: How to format and print from an Emacs shell.
-* Texinfo Mode Printing:: How to format and print in Texinfo mode.
-* Compile-Command:: How to print using Emacs's compile command.
-* Requirements Summary:: @TeX{} formatting requirements summary.
-* Preparing for @TeX{}:: What to do before you use @TeX{}.
-* Overfull hboxes:: What are and what to do with overfull hboxes.
-* @t{@@smallbook}:: How to print small format books and
manuals.
-* A4 Paper:: How to print on A4 or A5 paper.
-* @t{@@pagesizes}:: How to print with customized page sizes.
-* Cropmarks and Magnification:: How to print marks to indicate the size
- of pages and how to print scaled up output.
-* PDF Output:: Portable Document Format output.
-* Obtaining @TeX{}:: How to obtain @TeX{}.
address@hidden menu
-
-
address@hidden Use @TeX{}
address@hidden Use @TeX{}
-
-The typesetting program called @TeX{} is used for formatting a Texinfo
-file. @TeX{} is a very powerful typesetting program and, when used
-correctly, does an exceptionally good job.
-
address@hidden @TeX{}}, for information on how to obtain @TeX{}. It
-is not included in the Texinfo package, being a vast suite of software
-itself.
-
-
address@hidden Format with @t{tex}/@t{texindex}
address@hidden Format with @code{tex}/@code{texindex}
-
address@hidden Shell formatting with @code{tex} and @code{texindex}
address@hidden Formatting with @code{tex} and @code{texindex}
address@hidden DVI file
-
-You can format the Texinfo file with the shell command @code{tex}
-followed by the name of the Texinfo file. For example:
-
address@hidden
-tex foo.texi
address@hidden example
-
address@hidden @TeX{} will produce a @dfn{DVI file} as well as several auxiliary
-files containing information for indices, cross references, etc. The
-DVI file (for @dfn{DeVice Independent} file) can be printed on virtually
-any device (see the following sections).
-
address@hidden texindex
-The @code{tex} formatting command itself does not sort the indices; it
-writes an output file of unsorted index data. To generate a printed
-index after running the @command{tex} command, you first need a sorted
-index to work from. The @command{texindex} command sorts indices.
-(The source file @file{texindex.c} comes as part of the standard
-Texinfo distribution, among other places.) (@command{texi2dvi} runs
address@hidden and @command{texindex} as necessary.)
-
address@hidden of index files}
address@hidden Names of index files
address@hidden Index file names
address@hidden formatting command outputs unsorted index files under names
-that obey a standard convention: the name of your main input file with
-any @samp{.texinfo} (or similar, @pxref{Minimum,, What a Texinfo File
-Must Have}), followed by the two letter names of indices. For
-example, the raw index output files for the input file
address@hidden would be @file{foo.cp}, @file{foo.vr},
address@hidden, @file{foo.tp}, @file{foo.pg} and @file{foo.ky}. Those
-are exactly the arguments to give to @code{texindex}.
-
address@hidden 1000
address@hidden Wildcards
address@hidden Globbing
-Instead of specifying all the unsorted index file names explicitly, you
-can use @samp{??} as shell wildcards and give the command in this
-form:
-
address@hidden
-texindex foo.??
address@hidden example
-
address@hidden
-This command will run @code{texindex} on all the unsorted index files,
-including any two letter indices that you have defined yourself using
address@hidden@@defindex} or @code{@@defcodeindex}. You can safely run
address@hidden foo.??} even if there are files with two letter
-extensions that are not index files, such as @samp{foo.el}. The
address@hidden command reports but otherwise ignores such files.
-
-For each file specified, @code{texindex} generates a sorted index file
-whose name is made by appending @samp{s} to the input file name. The
address@hidden@@printindex} command looks for a file with that name
-(@pxref{Printing Indices & Menus}). @code{texindex} does not alter the
-raw index output file.
-
-After you have sorted the indices, you need to rerun @code{tex} on the
-Texinfo file. This regenerates the DVI file, this time with
-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:
-
address@hidden
address@hidden
-Run @code{tex} on your Texinfo file. This generates a DVI file (with
-undefined cross references and no indices), and the raw index files
-(with two letter extensions).
-
address@hidden
-Run @code{texindex} on the raw index files. This creates the
-corresponding sorted index files (with three letter extensions).
-
address@hidden
-Run @code{tex} again on your Texinfo file. This regenerates the DVI
-file, this time with indices and defined cross references, but with
-page numbers for the cross references from the previous run, generally
-incorrect.
-
address@hidden
-Sort the indices again, with @code{texindex}.
-
address@hidden
-Run @code{tex} one last time. This time the correct page numbers are
-written for the cross references.
address@hidden enumerate
-
address@hidden texi2dvi
-Alternatively, it's a one-step process: run @code{texi2dvi}
-(@pxref{Format with @t{texi2dvi}}).
-
-You need not run @code{texindex} each time after you run @code{tex}. If
-you do not, on the next run, the @code{tex} formatting command will use
-whatever sorted index files happen to exist from the previous use of
address@hidden This is usually ok while you are debugging.
-
address@hidden Auxiliary files, avoiding
address@hidden novalidate
address@hidden Pointer validation, suppressing
address@hidden Chapters, formatting one at a time
-Sometimes you may wish to print a document while you know it is
-incomplete, or to print just one chapter of a document. In that case,
-the usual auxiliary files that @TeX{} creates and warnings @TeX{}
-gives when cross references are not satisfied are just nuisances. You
-can avoid them with the @code{@@novalidate} command, which you must
-give @emph{before} the @code{@@setfilename} command
-(@address@hidden@@setfilename}}). Thus, the beginning of your file
-would look approximately like this:
-
address@hidden
-\input texinfo
-@@novalidate
-@@setfilename myfile.info
address@hidden
address@hidden example
-
address@hidden @code{@@novalidate} also turns off validation in
address@hidden, just like its @code{--no-validate} option
-(@pxref{Pointer Validation}).
-
-
address@hidden Format with @t{texi2dvi}
address@hidden Format with @code{texi2dvi}
-
address@hidden texi2dvi @r{(shell script)}
-
-The @code{texi2dvi} command automatically runs both @TeX{} and
address@hidden as many times as necessary to produce a DVI file
-with sorted indices and all cross references resolved. It is
-therefore simpler than manually executing the
address@hidden@address@hidden@code{tex} sequence
-described in the previous section.
-
-To run @code{texi2dvi} on an input file @file{foo.texi}, do this (where
address@hidden } is your shell prompt):
-
address@hidden
-prompt$ @kbd{texi2dvi foo.texi}
address@hidden example
-
-As shown in this example, the input filenames to @code{texi2dvi} must
-include any extension (@samp{.texi}, @samp{.texinfo}, etc.). Under
-MS-DOS and perhaps in other circumstances, you may need to run @samp{sh
-texi2dvi foo.texi} instead of relying on the operating system to invoke
-the shell on the @samp{texi2dvi} script.
-
address@hidden address@hidden, for @command{texi2dvi}}
-One useful option to @code{texi2dvi} is @address@hidden
-This inserts @var{cmd} on a line by itself after the
address@hidden@@setfilename} in a temporary copy of the input file before
-running @TeX{}. With this, you can specify different printing
-formats, such as @code{@@smallbook} (@address@hidden@@smallbook}}),
address@hidden@@afourpaper} (@pxref{A4 Paper}), or @code{@@pagesizes}
-(@address@hidden@@pagesizes}}), without actually changing the document
-source. (You can also do this on a site-wide basis with
address@hidden; @pxref{Preparing for @TeX{}}).
-
address@hidden address@hidden, for @command{texi2dvi}}
address@hidden pdftexi2dvi
-With the @option{--pdf} option, @command{texi2dvi} produces PDF output
-instead of DVI (@pxref{PDF Output}), by running @command{pdftex}
-instead of @command{tex}. Alternatively, the command
address@hidden is an abbreviation for running @samp{texi2dvi
---pdf}. The command @command{pdftexi2dvi} is also supported as a
-convenience to address@hidden users (@pxref{Top,,, auctex, address@hidden,
since
-that program merely prepends @samp{pdf} to DVI producing tools to have
-PDF producing tools.
-
address@hidden address@hidden, for @command{texi2dvi}}
address@hidden dvipdfmx
-With the @option{--dvipdf} option, @command{texi2dvi} produces PDF
-output by running @TeX{} and then a DVI-to-PDF program: if the
address@hidden environment variable is set, that value is used, else
-the first extant among @code{dvipdfmx}, @code{dvipdfm}, @code{dvipdf},
address@hidden, @code{dvitopdf}. This method can support CJK
-typesetting better than @command{pdftex}.
-
address@hidden address@hidden, for @command{texi2dvi}}
address@hidden dvips
-With the @option{--ps} option, @command{texi2dvi} produces PostScript
-instead of DVI, by running @command{tex} and then @command{dvips}
-(@pxref{Top,,, dvips, Dvips}). (Or the value of the @env{DVIPS}
-environment variable, if set.)
-
address@hidden @LaTeX{}, processing with @command{texi2dvi}
address@hidden can also be used to process @LaTeX{} files; simply
-run @samp{texi2dvi filename.ext}.
-
address@hidden address@hidden, for @command{texi2dvi}}
-Normally @command{texi2dvi} is able to guess the input file language
-by its contents and file name suffix. If, however, it fails to do so
-you can specify the input language using
address@hidden@var{lang}} command line option, where @var{lang}
-is either @samp{latex} or @samp{texinfo}.
-
address@hidden will use @command{etex} (or @command{pdfetex}) if
-they are available; these extended versions of @TeX{} are not
-required, and the DVI (or PDF) output is identical, but they simplify
-the @TeX{} programming in some cases, and provide additional tracing
-information when debugging @file{texinfo.tex}.
-
address@hidden address@hidden, for @command{texi2dvi}}
-Several options are provided for handling documents, written in
-character sets other than address@hidden The
address@hidden@var{file}} option instructs
address@hidden to translate input into internal @TeX{} character
-set using @dfn{translation file} @var{file} (@pxref{TCX files, TCX
-files, TCX files: Character translations, web2c, Web2c: A @TeX{}
-implementation}).
-
address@hidden address@hidden, for @command{texi2dvi}}
-The options @option{--recode} and @address@hidden
-allow conversion of an input document before running @TeX{}. The
address@hidden option recodes the document from encoding specified
-by @samp{@@documentencoding} command
-(@address@hidden@@documentencoding}}) to plain 7-bit @samp{texinfo}
-encoding.
-
address@hidden address@hidden, for @command{texi2dvi}}
-The option @address@hidden recodes the document from
address@hidden encoding to the encoding specified by
address@hidden@@documentencoding}. This is useful, for example, if the
-document is written in @samp{UTF-8} encoding and an equivalent 8-bit
-encoding is supported by @command{makeinfo}.
-
-Both @option{--recode} and @address@hidden use
address@hidden utility to perform the conversion. If
address@hidden fails to process the file, @command{texi2dvi} prints
-a warning and continues, using the unmodified input file.
-
-The option @option{-E} (equivalently, @option{-e} and
address@hidden) does Texinfo macro expansion using
address@hidden instead of the @TeX{} implementation (@pxref{Macro
-Details}). Each implementation has its own limitations and
-advantages. If this option is used, the string
address@hidden@@address@hidden must not appear at the beginning of a line
-in the source file.
-
-For the list of all options, run @samp{texi2dvi --help}.
-
-
address@hidden Print with @t{lpr}
address@hidden Print With @code{lpr -d} From Shell
-
address@hidden lpr @r{(DVI print command)}
-
-The precise command to print a DVI file depends on your system
-installation. Two common ones are @samp{dvips foo.dvi -o} and @samp{lpr
--d foo.dvi}.
-
-For example, the following commands will (perhaps) suffice to sort the
-indices, format, and print the @cite{Bison Manual}:
-
address@hidden
address@hidden
-tex bison.texinfo
-texindex bison.??
-tex bison.texinfo
-lpr -d bison.dvi
address@hidden group
address@hidden example
-
address@hidden
-(Remember that the shell commands may be different at your site; but
-these are commonly used versions.)
-
-Using the @code{texi2dvi} shell script (see the previous section):
-
address@hidden
address@hidden
-texi2dvi bison.texinfo
-lpr -d bison.dvi
-# or perhaps dvips bison.dvi -o
address@hidden group
address@hidden example
-
address@hidden Shell printing, on MS-DOS/MS-Windows
address@hidden Printing DVI files, on MS-DOS/MS-Windows
address@hidden address@hidden, replacements on MS-DOS/MS-Windows}
address@hidden is a standard program on Unix systems, but it is usually
-absent on MS-DOS/MS-Windows. Some network packages come with a
-program named @code{lpr}, but these are usually limited to sending files
-to a print server over the network, and generally don't support the
address@hidden option. If you are unfortunate enough to work on one of these
-systems, you have several alternative ways of printing DVI files:
-
address@hidden @bullet{}
address@hidden Find and install a Unix-like @code{lpr} program, or its clone.
-If you can do that, you will be able to print DVI files just like
-described above.
-
address@hidden Send the DVI files to a network printer queue for DVI files.
-Some network printers have special queues for printing DVI files. You
-should be able to set up your network software to send files to that
-queue. In some cases, the version of @code{lpr} which comes with your
-network software will have a special option to send a file to specific
-queues, like this:
-
address@hidden
-lpr -Qdvi -hprint.server.domain bison.dvi
address@hidden example
-
address@hidden Convert the DVI file to a Postscript or PCL file and send it to
your
-local printer. @xref{Invoking Dvips,,, dvips, Dvips}, and the man
-pages for @code{dvilj}, for detailed description of these tools. Once
-the DVI file is converted to the format your local printer understands
-directly, just send it to the appropriate port, usually @samp{PRN}.
address@hidden itemize
-
-
address@hidden Within Emacs
address@hidden From an Emacs Shell
address@hidden Print, format from Emacs shell
address@hidden Format, print from Emacs shell
address@hidden Shell, format, print from
address@hidden Emacs shell, format, print from
address@hidden GNU Emacs shell, format, print from
-
-You can give formatting and printing commands from a shell within GNU
-Emacs. To create a shell within Emacs, type @kbd{M-x shell}. In this
-shell, you can format and print the document. @xref{Hardcopy, , Format
-and Print Hardcopy}, for details.
-
-You can switch to and from the shell buffer while @code{tex} is
-running and do other editing. If you are formatting a long document
-on a slow machine, this can be very convenient.
-
-You can also use @code{texi2dvi} from an Emacs shell. For example,
-here is how to use @code{texi2dvi} to format and print @cite{Using and
-Porting GNU CC} from a shell within Emacs:
-
address@hidden
address@hidden
-texi2dvi gcc.texinfo
-lpr -d gcc.dvi
address@hidden group
address@hidden example
-
-See the next section for more information about formatting
-and printing in Texinfo mode.
-
-
address@hidden Texinfo Mode Printing
address@hidden Formatting and Printing in Texinfo Mode
address@hidden Region printing in Texinfo mode
address@hidden Format and print in Texinfo mode
address@hidden Print and format in Texinfo mode
-
-Texinfo mode provides several predefined key commands for @TeX{}
-formatting and printing. These include commands for sorting indices,
-looking at the printer queue, killing the formatting job, and
-recentering the display of the buffer in which the operations
-occur.
-
address@hidden @kbd
address@hidden C-c C-t C-b
address@hidden M-x texinfo-tex-buffer
-Run @code{texi2dvi} on the current buffer.
-
address@hidden C-c C-t C-r
address@hidden M-x texinfo-tex-region
-Run @TeX{} on the current region.
-
address@hidden C-c C-t C-i
address@hidden M-x texinfo-texindex
-Sort the indices of a Texinfo file formatted with
address@hidden
-
address@hidden C-c C-t C-p
address@hidden M-x texinfo-tex-print
-Print a DVI file that was made with @code{texinfo-tex-region} or
address@hidden
-
address@hidden C-c C-t C-q
address@hidden M-x tex-show-print-queue
-Show the print queue.
-
address@hidden C-c C-t C-d
address@hidden M-x texinfo-delete-from-print-queue
-Delete a job from the print queue; you will be prompted for the job
-number shown by a preceding @kbd{C-c C-t C-q} command
-(@code{texinfo-show-tex-print-queue}).
-
address@hidden C-c C-t C-k
address@hidden M-x tex-kill-job
-Kill the currently running @TeX{} job started by either
address@hidden or @code{texinfo-tex-buffer}, or any other
-process running in the Texinfo shell buffer.
-
address@hidden C-c C-t C-x
address@hidden M-x texinfo-quit-job
-Quit a @TeX{} formatting job that has stopped because of an error by
-sending an @key{x} to it. When you do this, @TeX{} preserves a record
-of what it did in a @file{.log} file.
-
address@hidden C-c C-t C-l
address@hidden M-x tex-recenter-output-buffer
-Redisplay the shell buffer in which the @TeX{} printing and formatting
-commands are run to show its most recent output.
address@hidden table
-
address@hidden 1000
-Thus, the usual sequence of commands for formatting a buffer is as
-follows (with comments to the right):
-
address@hidden
address@hidden
-C-c C-t C-b @r{Run @code{texi2dvi} on the buffer.}
-C-c C-t C-p @r{Print the DVI file.}
-C-c C-t C-q @r{Display the printer queue.}
address@hidden group
address@hidden example
-
-The Texinfo mode @TeX{} formatting commands start a subshell in Emacs
-called the @file{*tex-shell*}. The @code{texinfo-tex-command},
address@hidden, and @code{tex-dvi-print-command}
-commands are all run in this shell.
-
-You can watch the commands operate in the @samp{*tex-shell*} buffer,
-and you can switch to and from and use the @samp{*tex-shell*} buffer
-as you would any other shell buffer.
-
address@hidden 1500
-The formatting and print commands depend on the values of several variables.
-The default values are:
-
address@hidden
address@hidden
- @r{Variable} @r{Default value}
-
-texinfo-texi2dvi-command "texi2dvi"
-texinfo-tex-command "tex"
-texinfo-texindex-command "texindex"
-texinfo-delete-from-print-queue-command "lprm"
-texinfo-tex-trailer "@@bye"
-tex-start-of-header "%**start"
-tex-end-of-header "%**end"
-tex-dvi-print-command "lpr -d"
-tex-show-queue-command "lpq"
address@hidden group
address@hidden example
-
-You can change the values of these variables with the @kbd{M-x
-set-variable} command (@pxref{Examining, , Examining and Setting
-Variables, emacs, The GNU Emacs Manual}), or with your @file{.emacs}
-initialization file (@pxref{Init File, , , emacs, The GNU Emacs
-Manual}).
-
address@hidden Customize Emacs package (@t{Development/Docs/Texinfo})
-Beginning with version 20, GNU Emacs offers a user-friendly interface,
-called @dfn{Customize}, for changing values of user-definable variables.
address@hidden Customization, , Easy Customization Interface, emacs, The GNU
-Emacs Manual}, for more details about this. The Texinfo variables can
-be found in the @samp{Development/Docs/Texinfo} group, once you invoke
-the @kbd{M-x customize} command.
-
-
address@hidden Compile-Command
address@hidden Using the Local Variables List
address@hidden Local variables
address@hidden Compile command for formatting
address@hidden Format with the compile command
-
-Yet another way to apply the @TeX{} formatting command to a Texinfo file
-is to put that command in a @dfn{local variables list} at the end of the
-Texinfo file. You can then specify the @code{tex} or @code{texi2dvi}
-commands as a @code{compile-command} and have Emacs run it by typing
address@hidden compile}. This creates a special shell called the
address@hidden buffer in which Emacs runs the compile command.
-For example, at the end of the @file{gdb.texinfo} file, after the
address@hidden@@bye}, you could put the following:
-
address@hidden
address@hidden
-Local Variables:
-compile-command: "texi2dvi gdb.texinfo"
-End:
address@hidden group
address@hidden example
-
address@hidden
-This technique is most often used by programmers who also compile programs
-this way; see @ref{Compilation, , , emacs, The GNU Emacs Manual}.
-
-
address@hidden Requirements Summary
address@hidden @TeX{} Formatting Requirements Summary
address@hidden Requirements for formatting
address@hidden Minimal requirements for formatting
address@hidden Formatting requirements
-
-Every Texinfo file that is to be input to @TeX{} must begin with a
address@hidden command and must contain an @code{@@setfilename} command:
-
address@hidden
-\input texinfo
-@@setfilename @address@hidden
address@hidden example
-
address@hidden
-The first command instructs @TeX{} to load the macros it needs to
-process a Texinfo file and the second command opens auxiliary files.
-
-Every Texinfo file must end with a line that terminates @TeX{}'s
-processing and forces out unfinished pages:
-
address@hidden
-@@bye
address@hidden example
-
-Strictly speaking, these lines are all a Texinfo file needs to be
-processed successfully by @TeX{}.
-
-Usually, however, the beginning includes an @code{@@settitle} command to
-define the title of the printed manual, an @code{@@setchapternewpage}
-command, a title page, a copyright page, and permissions. Besides an
address@hidden@@bye}, the end of a file usually includes indices and a table of
-contents. (And of course most manuals contain a body of text as well.)
-
-For more information, see:
-
address@hidden @bullet
address@hidden @address@hidden@@settitle}}.
address@hidden @address@hidden@@setchapternewpage}}.
address@hidden @ref{Headings}.
address@hidden @ref{Titlepage & Copyright Page}.
address@hidden @ref{Printing Indices & Menus}.
address@hidden @ref{Contents}.
address@hidden itemize
-
-
address@hidden Preparing for @TeX{}
address@hidden Preparing for @TeX{}
address@hidden Preparing for @TeX{}
address@hidden @TeX{} input initialization
address@hidden @b{.profile} initialization file
address@hidden @b{.cshrc} initialization file
address@hidden Initialization file for @TeX{} input
-
address@hidden needs to know where to find the @file{texinfo.tex} file that the
address@hidden texinfo} command on the first line reads. The
address@hidden file tells @TeX{} how to handle @@-commands; it is
-included in all standard GNU distributions. The latest version is
-always available from the Texinfo source repository:
address@hidden
address@hidden://savannah.gnu.org/cgi-bin/viewcvs/texinfo/texinfo/doc/texinfo.tex?rev=HEAD}
address@hidden smalldisplay
-
address@hidden address@hidden, installing}
-
-Usually, the installer has put the @file{texinfo.tex} file in the
-default directory that contains @TeX{} macros when GNU Texinfo, Emacs or
-other GNU software is installed. In this case, @TeX{} will find the
-file and you do not need to do anything special. If this has not been
-done, you can put @file{texinfo.tex} in the current directory when you
-run @TeX{}, and @TeX{} will find it there.
-
address@hidden address@hidden, installing}
-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}).
-
address@hidden European Computer Modern fonts, installing
address@hidden EC fonts, installing
address@hidden CM-Super fonts, installing
-To be able to use quotation marks other than those used in English
-you'll need to install European Computer Modern fonts and optionally
-CM-Super fonts, unless they are already installed (@pxref{Inserting
-Quotation Marks}).
-
address@hidden address@hidden, installing}
address@hidden Euro font, installing
-If you intend to use the @code{@@euro} command, you should install the
-Euro font, if it is not already installed. @address@hidden@@euro}}.
-
address@hidden texinfo.cnf @r{installation}
address@hidden Customizing of @TeX{} for Texinfo
address@hidden Site-wide Texinfo configuration file
-Optionally, you may create a file @file{texinfo.cnf} for site
-configuration. This file is read by @TeX{} when the
address@hidden@@setfilename} command is executed
(@address@hidden@@setfilename}}).
-You can put any commands you like there, according to local site-wide
-conventions. They will be read by @TeX{} when processing any Texinfo
-document. For example, if @file{texinfo.cnf} contains the line
address@hidden@@afourpaper} (@pxref{A4 Paper}), then all Texinfo documents
-will be processed with that page size in effect. If you have nothing
-to put in @file{texinfo.cnf}, you do not need to create it.
-
address@hidden Environment variable @code{TEXINPUTS}
address@hidden TEXINPUTS
-If neither of the above locations for these system files suffice for
-you, you can specify the directories explicitly. For
address@hidden, you can do this by writing the complete path for the
-file after the @code{\input} command. Another way, that works for both
address@hidden and @file{texinfo.cnf} (and any other file @TeX{}
-might read), is to set the @code{TEXINPUTS} environment variable in your
address@hidden or @file{.cshrc} file.
-
-Whether you use @file{.profile} or @file{.cshrc} depends on
-whether you use a Bourne shell-compatible (@code{sh}, @code{bash},
address@hidden, @dots{}) or C shell-compatible (@code{csh}, @code{tcsh})
-command interpreter, respeictvely.
-
-In a @file{.profile} file, you could use the following @code{sh} command
-sequence:
-
address@hidden
address@hidden
-TEXINPUTS=.:/home/me/mylib:
-export TEXINPUTS
address@hidden group
address@hidden example
-
address@hidden 1000
-While in a @file{.cshrc} file, you could use the following @code{csh}
-command sequence:
-
address@hidden
-setenv TEXINPUTS .:/home/me/mylib:
address@hidden example
-
-
-On MS-DOS/MS-Windows, you would say it like address@hidden the use
-of the @samp{;} character as directory separator, instead of @samp{:}.}:
-
address@hidden
address@hidden
-set TEXINPUTS=.;d:/home/me/mylib;c:
address@hidden group
address@hidden example
-
address@hidden
-It is customary for DOS/Windows users to put such commands in the
address@hidden file, or in the Windows registry.
-
address@hidden
-These settings would cause @TeX{} to look for @file{\input} file first
-in the current directory, indicated by the @samp{.}, then in a
-hypothetical user @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.)
-
address@hidden Dumping a .fmt file
address@hidden Format file, dumping
-Finally, you may wish to dump a @file{.fmt} file (@pxref{Memory dumps,,,
-web2c, Web2C}) so that @TeX{} can load Texinfo faster. (The
-disadvantage is that then updating @file{texinfo.tex} requires
-redumping.) You can do this by running this command, assuming
address@hidden is findable by @TeX{}:
-
address@hidden
-initex texinfo @@dump
address@hidden example
-
address@hidden
-(@code{dump} is a @TeX{} primitive.) Then, move @file{texinfo.fmt} to
-wherever your @code{.fmt} files are found; typically, this will be in the
-subdirectory @file{web2c} of your @TeX{} installation.
-
-
address@hidden Overfull hboxes
address@hidden Overfull ``hboxes''
address@hidden Overfull @samp{hboxes}
address@hidden @samp{hbox}, overfull
address@hidden Final output
-
address@hidden is sometimes unable to typeset a line without extending it into
-the right margin. This can occur when @TeX{} comes upon what it
-interprets as a long word that it cannot hyphenate, such as an
-electronic mail network address or a very long title. When this
-happens, @TeX{} prints an error message like this:
-
address@hidden
-Overfull @@hbox (20.76302pt too wide)
address@hidden example
-
address@hidden hbox
address@hidden
-(In @TeX{}, lines are in ``horizontal boxes'', hence the term, ``hbox''.
address@hidden@@hbox} is a @TeX{} primitive not used in the Texinfo language.)
-
address@hidden also provides the line number in the Texinfo source file and
-the text of the offending line, which is marked at all the places that
address@hidden considered hyphenation.
address@hidden with @TeX{}},
-for more information about typesetting errors.
-
-If the Texinfo file has an overfull hbox, you can rewrite the sentence
-so the overfull hbox does not occur, or you can decide to leave it. A
-small excursion into the right margin often does not matter and may not
-even be noticeable.
-
-If you have many overfull boxes and/or an antipathy to rewriting, you
-can coerce @TeX{} into greatly increasing the allowable interword
-spacing, thus (if you're lucky) avoiding many of the bad line breaks,
-like this:
-
address@hidden \emergencystretch
address@hidden
-@@tex
-\global\emergencystretch = .9\hsize
-@@end tex
address@hidden example
-
address@hidden
-(You should adjust the fraction as needed.) This huge value for
address@hidden cannot be the default, since then the typeset
-output would generally be of noticeably lower quality; the default
-is @samp{.15\hsize}. @code{\hsize} is the @TeX{} dimension
-containing the current line width.
-
address@hidden Black rectangle in hardcopy
address@hidden Rectangle, black in hardcopy
address@hidden Box, ugly black in hardcopy
address@hidden Ugly black rectangles in hardcopy
-For what overfull boxes you have, however, @TeX{} will print a large,
-ugly, black rectangle beside the line that contains the overfull hbox
-unless told otherwise. This is so you will notice the location of the
-problem if you are correcting a draft.
-
address@hidden finalout
-To prevent such a monstrosity from marring your final printout, write
-the following in the beginning of the Texinfo file on a line of its own,
-before the @code{@@titlepage} command:
-
address@hidden
-@@finalout
address@hidden example
-
-
address@hidden @t{@@smallbook}
address@hidden @code{@@smallbook}: Printing ``Small'' Books
-
address@hidden@c old name
address@hidden smallbook
address@hidden Small book size
address@hidden Book, printing small
address@hidden Page sizes for books
address@hidden 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:
-
address@hidden
-@@smallbook
address@hidden example
-
address@hidden
-(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}).
-
address@hidden@t{@@address@hidden, for information about commands that make
-it easier to produce examples for a smaller manual.
-
address@hidden with @t{texi2dvi}}, and @ref{Preparing for @TeX{}},
-for other ways to format with @code{@@smallbook} that do not require
-changing the source file.
-
-
address@hidden A4 Paper
address@hidden Printing on A4 Paper
address@hidden A4 paper, printing on
address@hidden A5 paper, printing on
address@hidden Paper size, A4
address@hidden European A4 paper
address@hidden afourpaper
-
-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:
-
address@hidden
address@hidden
-\input texinfo @@c -*-texinfo-*-
-@@c %**start of header
-@@setfilename texinfo
-@@settitle Texinfo
-@@afourpaper
-@@c %**end of header
address@hidden group
address@hidden example
-
address@hidden with @t{texi2dvi}}, and @ref{Preparing for @TeX{}},
-for other ways to format for different paper sizes that do not require
-changing the source file.
-
address@hidden afourlatex
address@hidden afourwide
-You may or may not prefer the formatting that results from the command
address@hidden@@afourlatex}. There's also @code{@@afourwide} for A4 paper in
-wide format.
-
-
address@hidden @t{@@pagesizes}
address@hidden @code{@@pagesizes} address@hidden, @var{height}]: Custom Page
Sizes
address@hidden@c old node name
-
address@hidden pagesizes
address@hidden Custom page sizes
address@hidden Page sizes, customized
address@hidden Text width and height
address@hidden Width of text area
address@hidden Height of text area
address@hidden 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:
-
address@hidden
-@@pagesizes 200mm,150mm @c for b5 paper
address@hidden example
address@hidden and
address@hidden
-@@pagesizes 11.5in @c for legal paper
address@hidden example
-
address@hidden B5 paper, printing on
address@hidden 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 address@hidden by address@hidden for B5, address@hidden by
address@hidden for legal).
-
address@hidden 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
address@hidden
-
address@hidden with @t{texi2dvi}}, and @ref{Preparing for @TeX{}},
-for other ways to specify @code{@@pagesizes} that do not require
-changing the source file.
-
address@hidden@@pagesizes} is ignored by @code{makeinfo}.
-
-
address@hidden Cropmarks and Magnification
address@hidden Cropmarks and Magnification
-
address@hidden cropmarks
address@hidden Cropmarks for printing
address@hidden Printing cropmarks
-You can (attempt to) direct @TeX{} to print cropmarks at the corners
-of pages with the @code{@@cropmarks} command. Write the
address@hidden@@cropmarks} command on a line by itself near the beginning of
-the Texinfo file, before the title page, like this:
-
address@hidden
-@@cropmarks
address@hidden example
-
-This command is mainly for printers that typeset several pages on one
-sheet of film; but you can attempt to use it to mark the corners of a
-book set to 7 by 9.25 inches with the @code{@@smallbook} command.
-(Printers will not produce cropmarks for regular sized output that is
-printed on regular sized paper.) Since different printing machines
-work in different ways, you should explore the use of this command
-with a spirit of adventure. You may have to redefine the command in
address@hidden
-
-The @code{@@cropmarks} command is recognized and ignored in address@hidden
-output formats.
-
address@hidden \mag @r{(raw @TeX{} magnification)}
address@hidden Magnified printing
address@hidden 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
address@hidden@@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:
-
address@hidden
address@hidden
-@@tex
-\mag=1200
-@@end tex
address@hidden group
address@hidden 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
address@hidden may not print or may print only with certain
-magnifications. Be prepared to experiment.
-
-
address@hidden PDF Output
address@hidden PDF Output
address@hidden PDF output
-
address@hidden pdftex
-The simplest way to generate PDF output from Texinfo source is to run
-the convenience script @command{texi2pdf} (or @command{pdftexi2dvi});
-this executes the @command{texi2dvi} script with the @option{--pdf}
-option (@pxref{Format with @t{texi2dvi}}). If for some reason you
-want to process the document by hand, you can run the @command{pdftex}
-program instead of plain @command{tex}. That is, run @samp{pdftex
-foo.texi} instead of @samp{tex foo.texi}.
-
address@hidden stands for `Portable Document Format'. It was invented by
-Adobe Systems some years ago for document interchange, based on their
-PostScript language. Related links:
-
address@hidden
address@hidden
-GNU GV, a @uref{http://www.gnu.org/software/gv/, Ghostscript-based PDF
-reader}. (It can also preview PostScript documents.)
-
address@hidden
address@hidden, a freely available standalone
address@hidden://www.foolabs.com/xpdf/, PDF reader} for the X window
-system.
-
address@hidden
address@hidden://partners.adobe.com/asn/acrobat/sdk/public/docs/, PDF
definition}.
-
address@hidden itemize
-
-At present, Texinfo does not provide @samp{@@ifpdf} or @samp{@@pdf}
-commands as for the other output formats, since PDF documents contain
-many internal low-level offsets and references that would be hard or
-impossible to get right at the Texinfo source level.
-
-PDF files require dedicated software to be displayed, unlike the plain
-ASCII formats (Info, HTML) that Texinfo supports. They also tend to
-be much larger than the DVI files output by @TeX{} by default.
-Nevertheless, a PDF file does define an actual typeset document in a
-self-contained file, so it has its place.
-
-
address@hidden Obtaining @TeX{}
address@hidden Obtaining @TeX{}
address@hidden Obtaining @TeX{}
address@hidden @TeX{}, how to obtain
-
address@hidden 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
address@hidden://tug.org/texlive}.
-
address@hidden please keep that text in sync with www.gnu.org/prep/FTP
-
-
address@hidden Generic Translator @t{texi2any}
address@hidden @code{texi2any}: The Generic Translator for Texinfo
-
address@hidden is the generic translator for Texinfo that can
-produce different output formats and is highly customizable. It
-supports these formats:
-
address@hidden @asis
address@hidden Info (by default, or with @option{--info}),
-
address@hidden HTML (with @option{--html}),
-
address@hidden plain text (with @option{--plaintext}),
-
address@hidden Docbook (with @option{--docbook}),
-
address@hidden Texinfo XML (with @option{--xml}).
address@hidden table
-
address@hidden is an alias for @command{texi2any}. By default,
-both @command{texi2any} and @command{makeinfo} generate Info output;
-indeed, there are no differences in behavior based on the name.
-
-Beside these default formats, command line options to
address@hidden can change many aspects of the output. Beyond
-that, initialization files provide even more control over the final
-output---nearly anything not specified in the Texinfo input file.
-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.
-
address@hidden
-* Reference Implementation:: @command{texi2any}: the reference
implementation.
-* Invoking @t{texi2any}:: Running the translator from a shell.
-* @t{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 @t{pod2texi}:: Translating Perl pod to Texinfo.
-* @t{texi2html}:: An ancestor of @command{texi2any}.
address@hidden menu
-
-
address@hidden Reference Implementation
address@hidden @command{texi2any}: A Texinfo Reference Implementation
-
address@hidden @command{texi2any}, as reference implementation
address@hidden Reference implementation
address@hidden 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 highly
-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 processors.
-
address@hidden Tree representation of documents
address@hidden Syntax tree representation of documents
address@hidden 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
address@hidden, to avoid continuing with two different
-implementations (@pxref{History}). The current reference
-implementation, @command{texi2any}, inherited the design of
-customization and other features from @command{texi2html} (for more on
address@hidden compatibility, @address@hidden).
-However, @code{texi2any} is a full reimplementation: it constructs a
-tree-based representation of the input document for all back-ends to
-work from.
-
address@hidden Texinfo language tests
address@hidden Tests, of Texinfo language
-Extensive tests of the language were developed at the same time as
address@hidden; we plead with anyone thinking of writing a program
-to parse Texinfo input to at least make use of these tests.
-
address@hidden Examples of using @command{texi2any}
address@hidden Texinfo::Parser module
-The @command{texi2html} wrapper script (@address@hidden)
-provides a 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 in
address@hidden/texi-elements-by-size}. (Its functionality may also be
-useful to authors; @pxref{texi-elements-by-size}.)
-
address@hidden Future of Texinfo implementations
-With the release of @command{texi2any} as the reference
-implementation, development of both the C implementation of
address@hidden and @command{texi2html} has been halted. Going
-forward, we ask authors of Texinfo documents to use only
address@hidden
-
-
address@hidden Invoking @t{texi2any}
address@hidden Invoking @command{texi2any}/@code{makeinfo} from a Shell
-
address@hidden makeinfo}
address@hidden makeinfo
address@hidden texi2any
-
-To process a Texinfo file, invoke @command{texi2any} or
address@hidden (the two names are synonyms for the same program;
-we'll use the names interchangeably) followed by the name of the
-Texinfo file. Also select the format you want to output with the
-appropriate command line option (default is Info). Thus, to create
-the Info file for Bison, type the following to the shell:
-
address@hidden
-texi2any --info bison.texinfo
address@hidden example
-
-You can specify more than one input file name; each is processed in
-turn. If an input file name is @samp{-}, standard input is read.
-
address@hidden@t{makeinfo} Options}
address@hidden anchor{makeinfo address@hidden prev name, but case-insensitive
clash
address@hidden @code{makeinfo} options
address@hidden Options for @code{makeinfo}
address@hidden Options}
address@hidden @code{texi2any} options
address@hidden Options for @code{texi2any}
-
-The @command{texi2any} program accept many options. Perhaps the
-most basic are those that change the output format. By default,
address@hidden outputs Info.
-
-Each command line option is either a long name preceded by @samp{--}
-or a single letter preceded by @samp{-}. You can use abbreviations
-for the long option names as long as they are unique.
-
-For example, you could use the following shell command to create an
-Info file for @file{bison.texinfo} in which lines are filled to only
-68 columns:
-
address@hidden
-texi2any --fill-column=68 bison.texinfo
address@hidden example
-
-You can write two or more options in sequence, like this:
-
address@hidden
-texi2any --no-split --fill-column=70 @dots{}
address@hidden example
-
address@hidden
-(This would keep the Info file together as one possibly very long
-file and would also set the fill column to 70.)
-
-The options are (approximately in alphabetical order):
-
address@hidden @code
address@hidden --commands-in-node-names
address@hidden --commands-in-node-names
-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.)
-
address@hidden address@hidden
address@hidden address@hidden
-Prepend @var{path} 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
-several directories separated by the usual path separator character
-(@samp{:} on Unix-like systems, @samp{;} on Windows). @c @xref{Loading
address@hidden Init Files}.
-
address@hidden address@hidden
address@hidden --css-include
-When producing HTML, literally include the contents of @var{file},
-which should contain W3C cascading style sheets specifications, in the
address@hidden<style>} block of the HTML output. If @var{file} is @samp{-},
-read standard input. @xref{HTML CSS}.
-
address@hidden address@hidden
address@hidden --css-ref
-When producing HTML, add a @samp{<link>} tag to the output which
-references a cascading style sheet at @var{url}. This allows using
-standalone style sheets.
-
address@hidden -D @var{var}
address@hidden -D @var{var}
-Cause the Texinfo variable @var{var} to be defined. This is
-equivalent to @code{@@set @var{var}} in the Texinfo file
-(@address@hidden@@set @@clear @@value}}).
-
address@hidden --disable-encoding
address@hidden --enable-encoding
address@hidden --disable-encoding
address@hidden --enable-encoding
-By default, or with @option{--enable-encoding}, output accented and
-special characters in Info and plain text output based on
address@hidden@@documentencoding}. With @option{--disable-encoding}, 7-bit
-ASCII transliterations are output. @address@hidden@@documentencoding}},
-and @ref{Inserting Accents}.
-
address@hidden --docbook
address@hidden --docbook
-Generate Docbook output (rather than Info).
-
address@hidden address@hidden
address@hidden --document-language
-Use @var{lang} to translate Texinfo keywords which end up in the
-output document. The default is the locale specified by the
address@hidden@@documentlanguage} command if there is one, otherwise English
-(@address@hidden@@documentlanguage}}).
-
address@hidden --dvi
address@hidden --dvi
-Generate a TeX DVI file using @command{texi2dvi}, rather than Info
-(@address@hidden Printed Output}).
-
address@hidden --dvipdf
address@hidden --dvipdf
-Generate a PDF file using @command{texi2dvi --dvipdf}, rather than
-Info (@address@hidden Printed Output}).
-
address@hidden address@hidden
address@hidden -e @var{limit}
address@hidden address@hidden
address@hidden -e @var{limit}
-Report @var{LIMIT} errors before aborting (on the assumption that
-continuing would be useless); default 100.
-
address@hidden address@hidden
address@hidden -f @var{width}
address@hidden address@hidden
address@hidden -f @var{width}
-Specify the maximum number of columns in a line; this is the
-right-hand edge of a line. Paragraphs that are filled will be filled
-to this width. (Filling is the process of breaking up and connecting
-lines so that lines are the same length as or shorter than the number
-specified as the fill column. Lines are broken between words.) The
-default value is 72.
-
address@hidden address@hidden
address@hidden -s @var{style}
address@hidden address@hidden
address@hidden -s @var{style}
-Set the footnote style to @var{style}: either @samp{end} for the end
-node style (the default) or @samp{separate} for the separate node
-style. The value set by this option overrides the value set in a
-Texinfo file by an @code{@@footnotestyle} command (@pxref{Footnote
-Styles}).
-
-When the footnote style is @samp{separate}, @code{makeinfo} makes a
-new node containing the footnotes found in the current node. When the
-footnote style is @samp{end}, @code{makeinfo} places the footnote
-references at the end of the current node.
-
-In HTML, when the footnote style is @samp{end}, or if the output is
-not split, footnotes are put at the end of the output. If set to
address@hidden, and the output is split, they are placed in a
-separate file.
-
address@hidden --force
address@hidden -F
address@hidden --force
address@hidden -F
-Ordinarily, if the input file has errors, the output files are not
-created. With this option, they are preserved.
-
address@hidden --help
address@hidden -h
address@hidden address@hidden, for @command{texi2any}}
address@hidden -h
-Print a message with available options and basic usage, then exit
-successfully.
-
address@hidden --html
address@hidden --html
-Generate HTML output (rather than Info). By default, the HTML output
-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}.
-
address@hidden -I @var{path}
address@hidden -I @var{path}
-Append @var{path} to the directory search list for finding files that
-are included using the @code{@@include} command. By default,
address@hidden searches only the current directory. If @var{path} is
-not given, the current directory is appended. The @var{path} value
-can be a single directory or a list of several directories separated
-by the usual path separator character (@samp{:} on Unix-like systems,
address@hidden;} on Windows).
-
address@hidden --ifdocbook
address@hidden --ifdocbook
address@hidden --ifhtml
address@hidden --ifhtml
address@hidden --ifinfo
address@hidden --ifinfo
address@hidden --ifplaintext
address@hidden --ifplaintext
address@hidden --iftex
address@hidden --iftex
address@hidden --ifxml
address@hidden --ifxml
-For the given format, process @samp{@@address@hidden and
address@hidden@@@var{format}} commands, and do not process
address@hidden@@address@hidden, regardless of the format being output.
-For instance, if @option{--iftex} is given, then @samp{@@iftex} and
address@hidden@@tex} blocks will be read, and @samp{@@ifnottex} blocks will be
-ignored.
-
address@hidden --info
address@hidden --info
-Generate Info output. By default, if the output file contains more
-than about 300,000 bytes, it is split into shorter subfiles of about
-that size. The name of the output file and any subfiles is determined
-by @code{@@setfilename} (@address@hidden@@setfilename}}). @xref{Tag and
-Split Files}.
-
address@hidden address@hidden
address@hidden address@hidden
-Load @var{file} as code to modify the behavior and output of the
-generated manual. It is customary to use the @code{.pm} or the
address@hidden extensions for these customization files, but that is not
-enforced; the @var{file} name can be anything. The
address@hidden option (see above) can be used to add to the list
-of directories in which these customization files are searched for.
address@hidden @xref{Loading Init Files}.
-
address@hidden address@hidden
address@hidden address@hidden
address@hidden Internal links, of HTML
-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
-the term which was indexed or entered. The items are in the natural
-sorting order for the given element. This dump can be useful for
-post-processors.
-
address@hidden address@hidden
address@hidden -E @var{file}
address@hidden address@hidden
address@hidden -E @var{file}
-Output the Texinfo source, with all Texinfo macros expanded, to
address@hidden Normally, the result of macro expansion is used
-internally by @code{makeinfo} and then discarded.
-
address@hidden --no-headers
address@hidden --no-headers
address@hidden Node separators, omitting with @option{--no-headers}
address@hidden Generating plain text files with @option{--no-headers}
address@hidden Menus, omitting with @option{--no-headers}
-Do not include menus or node separator lines in the output.
-
-When generating Info, this is the same as using @option{--plaintext},
-resulting in a simple plain text file. Furthermore,
address@hidden@@setfilename} is ignored, and output is to standard output
-unless overridden with @option{-o}. (This behavior is for backward
-compatibility.)
-
address@hidden Navigation links, omitting
-When generating HTML, and output is split, also output navigation
-links only at the beginning of each file. If output is not split, do
-not include navigation links at the top of each node at all.
address@hidden HTML}.
-
address@hidden --no-ifdocbook
address@hidden --no-ifdocbook
address@hidden --no-ifhtml
address@hidden --no-ifhtml
address@hidden --no-ifinfo
address@hidden --no-ifinfo
address@hidden --no-ifplaintext
address@hidden --no-ifplaintext
address@hidden --no-iftex
address@hidden --no-iftex
address@hidden --no-ifxml
address@hidden --no-ifxml
-For the given format, do not process @samp{@@address@hidden and
address@hidden@@@var{format}} commands, and do process
address@hidden@@address@hidden, regardless of the format being output.
-For instance, if @option{--no-ifhtml} is given, then @samp{@@ifhtml}
-and @samp{@@html} blocks will not be read, and @samp{@@ifnothtml}
-blocks will be.
-
address@hidden --no-node-files
address@hidden --node-files
address@hidden --no-node-files
address@hidden --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
-for section- and chapter-level cross-manual references to succeed
-(@pxref{HTML Xref Configuration}).
-
-If the output is split, this is enabled by default. If the output is
-not split, @option{--node-files} enables the creation of the
-redirection files, in addition to the monolithic main output file.
address@hidden suppresses the creation of redirection files
-in any case. This option has no effect with any output format other
-than address@hidden @xref{Generating HTML}.
-
address@hidden --no-number-footnotes
address@hidden --no-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.
-
address@hidden --no-number-sections
address@hidden --number-sections
address@hidden --no-number-sections
address@hidden --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
address@hidden if your manual is not normally structured.
-
address@hidden --no-pointer-validate
address@hidden --no-validate
address@hidden --no-pointer-validate
address@hidden --no-validate
address@hidden Pointer validation, suppressing from command line
-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}.
-
address@hidden --no-warn
address@hidden --no-warn
-Suppress warning messages (but not error messages).
-
address@hidden address@hidden
address@hidden -o @var{file}
address@hidden address@hidden
address@hidden -o @var{file}
-Specify that the output should be directed to @var{file}. This
-overrides any file name specified in an @code{@@setfilename} command
-found in the Texinfo source. If neither @code{@@setfilename} nor this
-option are specified, the input file name is used to determine the
-output name. @address@hidden@@setfilename}}.
-
-If @var{file} is @samp{-}, output goes to standard output and
address@hidden is implied.
-
-If @var{file} is a directory or ends with a @samp{/} the usual rules
-are used to determine the output file name (namely, use
address@hidden@@setfilename} or the input file name) but the files are written
-to the @var{file} directory. For example, @samp{makeinfo -o bar/
-foo.texi}, with or without @option{--no-split}, will write
address@hidden/foo.info}, and possibly other files, under @file{bar/}.
-
-When generating HTML and output is split, @var{file} is used as the
-name for the directory into which all files are written. For example,
address@hidden -o bar --html foo.texi} will write
address@hidden/index.html}, among other files.
-
address@hidden address@hidden
address@hidden --outputindent
-This option now does nothing, but remains for compatibility. (It used
-to alter indentation in XML/Docbook output.)
-
address@hidden -P @var{path}
address@hidden -P @var{path}
-Prepend @var{path} to the directory search list for @code{@@include}.
-If @var{path} is not given, the current directory is prepended. See
address@hidden above.
-
address@hidden address@hidden
address@hidden -p @var{indent}
address@hidden address@hidden
address@hidden -p @var{indent}
-Set the paragraph indentation style to @var{indent}. The value set by
-this option overrides the value set in a Texinfo file by an
address@hidden@@paragraphindent} command (@address@hidden@@paragraphindent}}).
-The value of @var{indent} is interpreted as follows:
-
address@hidden @asis
address@hidden @samp{asis}
-Preserve any existing indentation (or lack thereof) at the beginnings
-of paragraphs.
-
address@hidden @samp{0} or @samp{none}
-Delete any existing indentation.
-
address@hidden @var{num}
-Indent each paragraph by @var{num} spaces.
address@hidden table
-
-The default is to indent by two spaces, except for paragraphs
-following a section heading, which are not indented.
-
address@hidden --pdf
address@hidden --pdf
-Generate a PDF file using @command{texi2dvi --pdf}, rather than Info
-(@address@hidden Printed Output}).
-
address@hidden --plaintext
address@hidden --plaintext
address@hidden Plain text output with @option{--plaintext}
address@hidden ASCII text output with @option{--plaintext}
address@hidden Generating plain text files with @option{--plaintext}
address@hidden Node separators, omitting with @option{--plaintext}
address@hidden Menus, omitting with @option{--plaintext}
address@hidden @file{INSTALL} file, generating
-Output a plain text file (rather than Info): do not include menus or
-node separator lines in the output. This results in a straightforward
-plain text file that you can (for example) send in email without
-complications, or include in a distribution (for example, an
address@hidden file).
-
-With this option, @code{@@setfilename} is ignored and the output goes
-to standard output by default; this can be overridden with @option{-o}.
-
address@hidden --ps
address@hidden --ps
-Generate a PostScript file using @command{texi2dvi --ps}, rather than
-Info (@address@hidden Printed Output}).
-
address@hidden --set-customization-variable @address@hidden
address@hidden -c @address@hidden
address@hidden --set-customization-variable @address@hidden
address@hidden -c @address@hidden
-Set the customization variable @var{var} to @var{value}. The @code{=}
-is optional, but both @var{var} and @var{value} must be quoted to the
-shell as necessary so the result is a single word. Many aspects of
address@hidden behavior and output may be controlled by
-customization variables, beyond what can be set in the document by
-@@-commands and with other command line switches. @xref{Customization
-Variables}.
-
address@hidden address@hidden
address@hidden --no-split
address@hidden address@hidden
address@hidden --no-split
address@hidden Splitting of output files
address@hidden Output file splitting
address@hidden Output}
address@hidden
-When generating Info, by default large output files are split into
-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.
-
-Alternatively, @address@hidden may be used to specify at
-which level the HTML output should be split. The possible values for
address@hidden are:
-
address@hidden @samp
address@hidden chapter
-The output is split at @code{@@chapter} and other sectioning
-@@-commands at this level (@code{@@appendix}, etc.).
-
address@hidden section
-The output is split at @code{@@section} and similar.
-
address@hidden node
-The output is split at every node. This is the default.
address@hidden table
-
address@hidden address@hidden
address@hidden address@hidden
-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.)
-
address@hidden --transliterate-file-names
address@hidden --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}.
-
address@hidden -U @var{var}
-Cause @var{var} to be undefined. This is equivalent to @code{@@clear
address@hidden in the Texinfo file (@address@hidden@@set @@clear @@value}}).
-
address@hidden --verbose
address@hidden --verbose
-Cause @code{makeinfo} to display messages saying what it is doing.
-Normally, @code{makeinfo} only outputs messages if there are errors or
-warnings.
-
address@hidden --version
address@hidden -V
address@hidden address@hidden, for @command{texi2any}}
address@hidden -V
-Print the version number, then exit successfully.
-
address@hidden --Xopt @var{str}
address@hidden --Xopt @var{str}
-Pass @var{str} (a single shell word) to @command{texi2dvi}; may be
-repeated (@address@hidden Printed Output}).
-
address@hidden --xml
address@hidden --xml
-Generate Texinfo XML output (rather than Info).
-
address@hidden table
-
address@hidden TEXINFO_OUTPUT_FORMAT
address@hidden Environment variable @code{TEXINFO_OUTPUT_FORMAT}
address@hidden also reads the environment variable
address@hidden to determine the output format, if not
-overridden by a command line option. The value should be one of:
-
address@hidden
-docbook dvi dvipdf html info pdf plaintext ps xml
address@hidden example
-
-If not set or otherwise specified, Info output is the default.
-
-The customization variable of the same name is also read; if set, that
-overrides an environment variable setting, but not a command-line
-option. @xref{Customization Variables for @@-Commands}.
-
-
address@hidden @t{texi2any} Printed Output
address@hidden @command{texi2any} Printed Output
-
address@hidden Printed output, through @command{texi2any}
address@hidden Output, printed through @command{texi2any}
-
-To justify the name address@hidden, @command{texi2any} has
-basic support for creating printed output in the various formats:
address@hidden DVI, PDF, and PostScript. This is done via the simple method
-of executing the @command{texi2dvi} program when those outputs are
-requested.
-
-The output format options for this are @option{--dvi},
address@hidden, @option{--pdf}, and @option{--ps}. @xref{Format
-with @t{texi2dvi}}, for more details on these options and general
address@hidden operation. In addition, the @option{--verbose},
address@hidden, and @option{--quiet} options are passed on if
-specified; the @option{-I} and @option{-o} options are likewise passed
-on with their arguments, and @option{--debug} without its argument.
-
-The only option remaining that is related to the @command{texi2dvi}
-invocation is @option{--Xopt}. Here, just the argument is passed on
-and multiple @option{--Xopt} options accumulate. This provides a way
-to construct an arbitrary command line for @command{texi2dvi}. For
-example, running
-
address@hidden
-texi2any --Xopt -t --Xopt @@a4paper --pdf foo.texi
address@hidden example
-
address@hidden is equivalent to running
-
address@hidden
-texi2dvi -t @@a4paper --pdf foo.texi
address@hidden example
-
-Although one might wish that other options to @command{texi2any} would
-take effect, they don't. For example, running @samp{texi2any
---no-number-sections --dvi foo.texi} still results in a DVI file with
-numbered sections. (Perhaps this could be improved in the future, if
-requests are received.)
-
-The actual name of the command that is invoked is specified by the
address@hidden customization variable (@pxref{Other Customization
-Variables}). As you might guess, the default is @samp{texi2dvi}.
-
address@hidden itself does not generate any output when it invokes
address@hidden
-
-
address@hidden Pointer Validation
address@hidden Pointer Validation
address@hidden Pointer validation with @code{makeinfo}
address@hidden Validation of pointers
-
-If you do not suppress pointer validation with the
address@hidden 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:
-
address@hidden
address@hidden
-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
address@hidden(dir)}, then the referenced node must exist.
-
address@hidden
-Every node except the `Top' node must have an `Up' pointer.
-
address@hidden
-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})}.
address@hidden enumerate
-
-With implicit node pointers, the above error cannot occur, as such.
-(Which is a major reason why we recommend using this feature of
address@hidden, 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
address@hidden 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,
address@hidden checks that every node except the `Top' node is
-referenced in a menu.
-
-
address@hidden Customization Variables
address@hidden Customization Variables
-
address@hidden Warning
-These customization variable names and meanings may change in any
-Texinfo release. We always try to avoid incompatible changes, but we
-cannot absolutely promise, since needs change over time.
address@hidden quotation
-
-Many aspects of the behavior and output of @command{texi2any} may be
-modified by modifying so-called @dfn{customization variables}. These
-fall into four general categories:
-
address@hidden @bullet
address@hidden
-Those associated with @@-commands; for example,
address@hidden@@documentlanguage}.
-
address@hidden
-Those associated with command-line options; for example, the
-customization variable @code{SPLIT} is associated with the
address@hidden command-line option, and @code{TEXINFO_OUTPUT_FORMAT}
-allows specifying the output format.
-
address@hidden
-Other ad hoc variables.
address@hidden itemize
-
-Customization variables may set on the command line using
address@hidden '@var{var} @var{value}'} (quoting
-the variable/value pair to the shell) or
address@hidden @address@hidden (using
address@hidden). A special @var{value} is @samp{undef}, which sets the
-variable to this special ``undefined'' Perl value.
-
-The sections below give the details for each of these.
-
address@hidden
-* Commands: Customization Variables for @@-Commands.
-* Options: Customization Variables and Options.
-* HTML: HTML Customization Variables.
-* Other: Other Customization Variables.
address@hidden menu
-
-
address@hidden Customization Variables for @@-Commands
address@hidden Customization Variables for @@-Commands
-
address@hidden Customization variables for @@-commands
address@hidden @@-commands, customization variables for
-
-Each of the following @@-commands has an associated customization
-variable with the same name (minus the leading @code{@@}):
-
address@hidden
-@@allowcodebreaks @@clickstyle @@codequotebacktick
-@@codequoteundirected @@contents @@deftypefnnewline
-@@documentdescription @@documentencoding @@documentlanguage
-@@evenfooting @@evenfootingmarks
-@@evenheading @@evenheadingmarks
-@@everyfooting @@everyfootingmarks
-@@everyheading @@everyheadingmarks
-@@exampleindent @@firstparagraphindent
-@@fonttextsize @@footnotestyle @@frenchspacing @@headings
-@@kbdinputstyle @@novalidate
-@@oddfooting @@oddfootingmarks
-@@oddheading @@oddheadingmarks
-@@pagesizes @@paragraphindent
-@@setchapternewpage @@setcontentsaftertitlepage
-@@setfilename
-@@setshortcontentsaftertitlepage @@shortcontents
-@@urefbreakstyle @@xrefautomaticsectiontitle
address@hidden smallexample
-
-Setting such a customization variable to a value @samp{foo} is similar
-to executing @code{@@@var{cmd} foo}. It is not exactly the same,
-though, since any side effects of parsing the Texinfo source are not
-redone. Also, some variables do not take Texinfo code when generating
-particular formats, but an argument that is already formatted. This
-is the case, for example, for HTML for @code{documentdescription}.
-
-
address@hidden Customization Variables and Options
address@hidden Customization Variables and Options
-
address@hidden Customization variables for options
address@hidden Options, customization variables for
-
-The following table gives the customization variables associated with
-some command line options. @xref{Invoking @t{texi2any}}, for the
-meaning of the options.
-
address@hidden @columnfractions 0.5 0.5
address@hidden Option @tab Variable
address@hidden ENABLE_ENCODING
address@hidden @option{--enable-encoding} @tab @code{ENABLE_ENCODING}
address@hidden documentlanguage
address@hidden @option{--document-language} @tab @code{documentlanguage}
address@hidden ERROR_LIMIT
address@hidden @option{--error-limit} @tab @code{ERROR_LIMIT}
address@hidden FILLCOLUMN
address@hidden @option{--fill-column} @tab @code{FILLCOLUMN}
address@hidden footnotestyle
address@hidden @option{--footnote-style} @tab @code{footnotestyle}
address@hidden FORCE
address@hidden @option{--force} @tab @code{FORCE}
address@hidden INTERNAL_LINKS
address@hidden @option{--internal-links} @tab @code{INTERNAL_LINKS}
address@hidden MACRO_EXPAND
address@hidden @option{--macro-expand} @tab @code{MACRO_EXPAND}
address@hidden HEADERS
address@hidden SHOW_MENU
address@hidden @option{--headers} @tab @code{HEADERS},
@code{SHOW_MENU}
address@hidden NO_WARN
address@hidden @option{--no-warn} @tab @code{NO_WARN}
address@hidden novalidate
address@hidden @option{--no-validate} @tab @code{novalidate}
address@hidden NUMBER_FOOTNOTES
address@hidden @option{--number-footnotes} @tab @code{NUMBER_FOOTNOTES}
address@hidden NUMBER_SECTIONS
address@hidden @option{--number-sections} @tab @code{NUMBER_SECTIONS}
address@hidden NODE_FILES
address@hidden @option{--node-files} @tab @code{NODE_FILES}
address@hidden OUT
address@hidden OUTFILE
address@hidden SUBDIR
address@hidden @option{--output} @tab @code{OUT}, @code{OUTFILE},
- @code{SUBDIR}
address@hidden paragraphindent
address@hidden @option{--paragraph-indent} @tab @code{paragraphindent}
address@hidden SILENT
address@hidden @option{--silent} @tab @code{SILENT}
address@hidden SPLIT
address@hidden @option{--split} @tab @code{SPLIT}
address@hidden SPLIT_SIZE
address@hidden @option{--split-size} @tab @code{SPLIT_SIZE}
address@hidden TRANSLITERATE_FILE_NAMES
address@hidden @option{--transliterate-file-names} @tab
@code{TRANSLITERATE_FILE_NAMES}
address@hidden VERBOSE
address@hidden @option{--verbose} @tab @code{VERBOSE}
address@hidden multitable
-
-Setting such a customization variable to a value @samp{foo} is
-essentially the same as specifying the @address@hidden if the
-option takes an argument, or @address@hidden if not.
-
address@hidden TEXINFO_OUTPUT_FORMAT
-In addition, the customization variable @code{TEXINFO_OUTPUT_FORMAT}
-allows specifying what @code{makeinfo} outputs, either one of the usual
-output formats that can be specified with options, or various other
-forms:
-
address@hidden @samp
address@hidden docbook
address@hidden dvi
address@hidden dvipdf
address@hidden html
address@hidden info
address@hidden pdf
address@hidden plaintext
address@hidden ps
address@hidden xml
-These correspond to the command-line options (and
address@hidden environment variable values) of the same
-name. @xref{Invoking @t{texi2any}}.
-
address@hidden debugcount
-Instead of generating a regular output format, output the count of
-bytes and lines obtained when converting to Info, and other information.
-
address@hidden debugtree
address@hidden tree representation, for debugging
address@hidden debugging document, with tree representation
-Instead of generating a regular output format, output a text representation
-of the tree obtained by parsing the input texinfo document.
-
address@hidden parse
-Do only Texinfo source parsing; there is no output.
-
address@hidden plaintexinfo
-Output the Texinfo source with all the macros, @code{@@include} and
address@hidden@@address@hidden@}} expanded. This is similar to setting
address@hidden, but instead of being output in addition to
-the normal conversion, output of Texinfo is the main output.
-
address@hidden rawtext
address@hidden raw text output
-Output raw text, with minimal formatting. For example, footnotes are
-ignored and there is no paragraph filling. This is used by the parser
-for file names and copyright text in HTML comments, for example.
-
address@hidden structure
-Do only Texinfo source parsing and determination of the document
-structure; there is no output.
-
address@hidden texinfosxml
address@hidden SXML output
address@hidden S-expressions, output format
-Output the document in TexinfoSXML representation, a syntax for
-writing XML data using Lisp S-expressions.
-
address@hidden textcontent
address@hidden spell checking
address@hidden word counting
address@hidden detexinfo
address@hidden stripping Texinfo commands
-Output the text content only, stripped of commands; this is useful for
-spell checking or word counting, for example. The trivial
address@hidden script setting this is in the @file{util} directory
-of the Texinfo source as an example. It's one line:
-
address@hidden
-exec texi2any -c TEXINPUT_OUTPUT_FORMAT=textcontent "$@@"
address@hidden example
address@hidden ftable
-
-
address@hidden HTML Customization Variables
address@hidden HTML Customization Variables
-
-This table gives the customization variables which apply to HTML
-output only. A few other customization variable apply to both HTML
-and other output formats; those are given in the next section.
-
address@hidden @code
address@hidden AVOID_MENU_REDUNDANCY
-For address@hidden If set, and the menu entry and menu description are the
-same, then do not print the menu description; default false.
-
address@hidden AFTER_BODY_OPEN
-For address@hidden If set, the corresponding text will appear at the
-beginning of each HTML file; default unset.
-
address@hidden AFTER_ABOUT
-For HTML, when an About-element is output. If set, the corresponding
-text will appear at the end of the About element; default unset.
-
address@hidden AFTER_OVERVIEW
address@hidden AFTER_TOC_LINES
-For address@hidden If set, the corresponding text is output after the short
-table of contents for @code{AFTER_OVERVIEW} and after the table of
-contents for @code{AFTER_TOC_LINES}; otherwise, a default string is
-used. At the time of writing, a @code{</div>} element is closed.
-
-In general, you should set @code{BEFORE_OVERVIEW} if
address@hidden is set, and you should set
address@hidden if @code{AFTER_TOC_LINES} is set.
-
-
address@hidden BASEFILENAME_LENGTH
-For address@hidden The maximum length of the base filenames; default 245.
-Changing this would make cross-manual references to such long node
-names invalid (@pxref{HTML Xref Link Basics}).
-
address@hidden BEFORE_OVERVIEW
address@hidden BEFORE_TOC_LINES
-For address@hidden If set, the corresponding text is output before the short
-table of contents for @code{BEFORE_OVERVIEW} and before the table of
-contents for @code{BEFORE_TOC_LINES}, otherwise a default string is
-used. At the time of writing, a @code{<div ...>} element is opened.
-
-In general you should set @code{AFTER_OVERVIEW} if
address@hidden is set, and you should set
address@hidden if @code{BEFORE_TOC_LINES} is set.
-
-
address@hidden BIG_RULE
-For address@hidden Rule used after and before the top element and before
-special elements, but not for footers and headers; default
address@hidden<hr>}.
-
address@hidden BODYTEXT
address@hidden @code{<body>} text, customizing
-For HTML, the text appearing in @code{<body>}. By default, set
-automatically, taking into account the document language
-(@address@hidden@@documentlanguage}}).
-
address@hidden CASE_INSENSITIVE_FILENAMES
-For address@hidden Construct output file names as if the filesystem were case
-insensitive (@pxref{HTML Splitting}); default false.
-
address@hidden CHAPTER_HEADER_LEVEL
-For address@hidden Header formatting level used for chapter level sectioning
-commands; default @samp{2}.
-
address@hidden CHECK_HTMLXREF
-For address@hidden Check that manuals which are the target of external
-cross references (@pxref{Four and Five Arguments}) are present in
address@hidden (@pxref{HTML Xref Configuration}); default false.
-
address@hidden COMPLEX_FORMAT_IN_TABLE
-For address@hidden If set, use tables for indentation of complex formats;
default
-false.
-
address@hidden CSS_LINES
-For address@hidden CSS output, automatically determined by default
(@pxref{HTML CSS}).
-
address@hidden DATE_IN_HEADER
-For address@hidden Put the document generation date in the header; off by
default.
-
address@hidden DEF_TABLE
-For address@hidden If set, a @code{<table>} construction for @code{@@deffn}
-and similar @@-commands is used (looking more like the @TeX{} output),
-instead of definition lists; default false.
-
address@hidden DEFAULT_RULE
-For address@hidden Rule used between element, except before and after the
-top element, and before special elements, and for footers and headers;
-default @code{<hr>}.
-
address@hidden DO_ABOUT
-For address@hidden If set to 0 never do an About special element;
-if set to 1 always do an About special element;
-default 0.
address@hidden @xref{Output Elements Defined}.
-
address@hidden EXTERNAL_DIR
-For address@hidden Base directory for external manuals; default none. It is
-better to use the general external cross reference mechanism
-(@pxref{HTML Xref Configuration}) than this variable.
-
address@hidden EXTRA_HEAD
-For address@hidden Additional text appearing within @code{<head>}; default
unset.
-
address@hidden FOOTNOTE_END_HEADER_LEVEL
-For address@hidden Header formatting level used for the footnotes header with
-the `end' footnotestyle; default @samp{4}. @xref{Footnote Styles}.
-
address@hidden FOOTNOTE_SEPARATE_HEADER_LEVEL
-For address@hidden Header formatting level used for the footnotes header with
-the `separate' footnotestyle; default @samp{4}. @xref{Footnote
-Styles}.
-
address@hidden FRAMES
-For address@hidden If set, a file describing the frame layout is generated,
-together with a file with the short table of contents; default false.
-
address@hidden FRAMESET_DOCTYPE
-For address@hidden Same as DOCTYPE, but for the file containing the frame
-description.
-
address@hidden HEADER_IN_TABLE
-For address@hidden Use tables for header formatting rather than a simple
address@hidden<div>} element; default false.
-
address@hidden ICONS
-For address@hidden Use icons for the navigation panel; default false.
-
address@hidden IMAGE_LINK_PREFIX
-For address@hidden If set, the associated value is prepended to the image file
-links; default unset.
-
address@hidden INLINE_CSS_STYLE
-For address@hidden Put CSS directly in HTML elements rather than at the
-beginning of the output; default false.
-
address@hidden KEEP_TOP_EXTERNAL_REF
-For address@hidden If set, do not ignore @samp{Top} as the first
-argument for an external ref to a manual, as is done by default.
address@hidden Node Naming}.
-
address@hidden L2H
-For address@hidden If set, @command{latex2html} is used to convert
@code{@@math}
-and @code{@@tex} sections; default false. Best used with @option{--iftex}.
-
address@hidden L2H_CLEAN
-(Relevant only if @code{L2H} is set.) If set, the intermediate files
-generated in relation with @command{latex2html} are removed; default
-true.
-
address@hidden L2H_FILE
-(Relevant only if @code{L2H} is set.) If set, the given file is used
-as @command{latex2html}'s init file; default unset.
-
address@hidden L2H_HTML_VERSION
-(Relevant only if @code{L2H} is set.) The HTML version used in the
address@hidden call; default unset.
-
address@hidden L2H_L2H
-(Relevant only if @code{L2H} is set.) The program invoked as
address@hidden; default is @code{latex2html}.
-
address@hidden L2H_SKIP
-(Relevant only if @code{L2H} is set.) If set to a true value, the
-actual call to @command{latex2html} is skipped; previously generated
-content is reused instead. If set to 0, the cache is not used at all.
-If set to @samp{undef}, the cache is used for as many @TeX{} fragments as
-possible and for any remaining the command is run. The default is
address@hidden
-
address@hidden L2H_TMP
-(Relevant only if @code{L2H} is set.) Set the directory used for
-temporary files. None of the file name components in this directory
-name may start with @samp{.}; otherwise, @command{latex2html} will
-fail (because of @command{dvips}). The default is the empty string,
-which means the current directory.
-
address@hidden MAX_HEADER_LEVEL
-For address@hidden Maximum header formatting level used (higher header
-formatting level numbers correspond to lower sectioning levels);
-default @samp{4}.
-
address@hidden MENU_SYMBOL
-For address@hidden Symbol used in front of menu entries when node names are
used
-for menu entries formatting; default @samp{•}.
-
address@hidden MONOLITHIC
-For address@hidden Output only one file including the table of contents. Set
-by default, but only relevant when the output is not split.
-
address@hidden NO_CSS
-For address@hidden Do not use CSS; default false. @xref{HTML CSS}.
-
address@hidden NODE_FILE_EXTENSION
-For address@hidden Extension for node files if @code{NODE_FILENAMES} is set;
-default @samp{html}.
-
address@hidden PRE_ABOUT
-For HTML, when an About element is output. If set to a text string,
-this text will appear at the beginning of the About element. If set
-to a reference on a subroutine, the result of the subroutine call will
-appear at the beginning of the About element. If not set (the
-default), default text is used.
-
address@hidden PRE_BODY_CLOSE
-For address@hidden If set, the given text will appear at the footer of each
-HTML file; default unset.
-
address@hidden PROGRAM_NAME_IN_FOOTER
-For address@hidden If set, output the program name and miscellaneous related
-information in the page footers; default false.
-
address@hidden SHORTEXTN
-For address@hidden If set, use @samp{.htm} as extension; default false.
-
address@hidden SHOW_TITLE
-For address@hidden If set, output the title at the beginning of the document;
-default true.
-
address@hidden SIMPLE_MENU
-For address@hidden If set, use a simple preformatted style for the menu,
-instead of breaking down the different parts of the menu; default false.
address@hidden Parts}.
-
address@hidden TOC_LINKS
-For address@hidden If set, links from headings to toc entries are created;
-default false.
-
address@hidden TOP_FILE
-This file name may be used for the top-level file. The extension is
-set appropriately, if necessary. This is used to override the default,
-and is, in general, only taken into account when output is split, and
-for address@hidden
-
address@hidden TOP_NODE_FILE
-For address@hidden File name used for the Top node, if @code{NODE_FILENAMES}
-is set; default is @code{index}.
-
address@hidden TOP_NODE_FILE_TARGET
-For address@hidden File name used for the Top node in cross references;
-default is @code{index}.
-
address@hidden TOP_NODE_UP_URL
-For address@hidden The url used for the Up pointer of the Top node; default
address@hidden, meaning no link is generated.
-
address@hidden USE_ACCESSKEY
address@hidden @code{accesskey}, customization variable for
-For address@hidden Use @code{accesskey} in cross references; default true.
-
address@hidden USE_ISO
-For address@hidden Use entities for doubled single-quote characters
-(@pxref{Inserting Quotation Marks}), and @samp{---} and @samp{--}
-(@pxref{Conventions}); default true.
-
address@hidden USE_LINKS
address@hidden @code{<link>} HTML tag, in @code{<head>}
address@hidden @code{<head>} HTML tag, and @code{<link>}
-For address@hidden Generate @code{<link>} elements in the HTML @code{<head>}
-output; default true.
-
address@hidden USE_REL_REV
-For address@hidden Use @code{rel} in cross references; default true.
-
address@hidden VERTICAL_HEAD_NAVIGATION
-For address@hidden If set, a vertical navigation panel is used; default false.
-
address@hidden WORDS_IN_PAGE
address@hidden Navigation panel, bottom of page
-For HTML, with output split at nodes. Specifies the approximate
-minimum page length at which a navigation panel is placed at the
-bottom of a page. To avoid ever having the navigation buttons at the
-bottom of a page, set this to a sufficiently large number. The
-default is 300.
-
address@hidden XREF_USE_FLOAT_LABEL
-For address@hidden If set, for the float name in cross references, use the
-float label instead of the type followed by the float number
-(@address@hidden@@float}}). The default is off.
-
address@hidden XREF_USE_NODE_NAME_ARG
-For address@hidden Only relevant for cross reference commands with no cross
-reference name (second argument). If set address@hidden, use the node name
-(first) argument in cross reference @@-commands for the text displayed
-as the hyperlink. If set address@hidden, use the node name if
address@hidden is set, otherwise the section name. If set to
address@hidden, use the first argument in preformatted environments,
-otherwise use the node name or section name depending on
address@hidden The default is @samp{undef}.
-
address@hidden vtable
-
-
address@hidden Other Customization Variables
address@hidden Other Customization Variables
-
-This table gives the remaining customization variables, which apply to
-multiple formats, or affect global behavior, or otherwise don't fit
-into the categories of the previous sections.
-
address@hidden @code
address@hidden CLOSE_QUOTE_SYMBOL
-When a closing quote is needed, use this character; default @code{’}
-in HTML, @code{’} in Docbook. The default for Info is the same
-as @code{OPEN_QUOTE_SYMBOL} (see below).
-
address@hidden @item COMPLETE_IMAGE_PATHS
address@hidden If set, the image files are computed to be relative from the
document
address@hidden directory to the source manual directory, and then to the image.
-
address@hidden CPP_LINE_DIRECTIVES
-Recognize @code{#line} directives in a ``preprocessing'' pass
-(@pxref{External Macro Processors}); on by default.
-
address@hidden DEBUG
-If set, debugging output is generated; default is off (zero).
address@hidden The integer value specifies what kinds of debugging output are
address@hidden generated. It is a bitmask. Setting it to 255 ensures having
all
address@hidden available debugging output.
-
address@hidden DOCTYPE
address@hidden SystemLiteral
-For Docbook, HTML, address@hidden 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
-and address@hidden
-
address@hidden DUMP_TEXI
-For debugging. If set, no conversion is done, only parsing and macro
-expansion. If the option @option{--macro-expand} is set, the Texinfo
-source is also expanded to the corresponding file. Default false.
-
address@hidden DUMP_TREE
-For debugging. If set, the tree constructed upon parsing a Texinfo
-document is output to standard error; default false.
-
address@hidden ENABLE_ENCODING_USE_ENTITY
-For HTML, address@hidden If @option{--enable-encoding} is set, and there is an
-entity corresponding with the letter or the symbol being output,
-prefer the entity. Set by default for HTML, but not XML.
-
address@hidden EXTERNAL_CROSSREF_SPLIT
-For cross references to other manuals, this determines if the other
-manual is considered to be split or monolithic. By default, it is set
-based on the value of @code{SPLIT}. @xref{HTML Xref}, and @pxref{HTML
-Xref Configuration}.
-
address@hidden EXTENSION
-The extension added to the output file name. The default is different
-for each output format.
-
address@hidden FIX_TEXINFO
-For ``plain Texinfo'' (see the @code{PLAINTEXINFO} item). If set to
-false, the resulting Texinfo does not have all errors corrected, such
-as missing @samp{@@end}; default true. This variable is only
-relevant when expanding Texinfo; other converters always try to
-output something sane even if the input is erroneous.
-
address@hidden @item IDX_SUMMARY
address@hidden If set, for each @code{@@printindex} a file named
address@hidden @address@hidden@var{idxname}.idx} is created, containing lines of
address@hidden the form:
address@hidden
address@hidden @example
address@hidden @var{key} @var{reference}
address@hidden @end example
address@hidden
address@hidden @noindent sorted alphabetically (case matters).
-
address@hidden IGNORE_BEFORE_SETFILENAME
-If set, begin outputting at @code{@@setfilename}, if
address@hidden@@setfilename} is present; default true.
-
address@hidden IGNORE_SPACE_AFTER_BRACED_COMMAND_NAME
-If set, spaces are ignored after an @@-command that takes braces.
-Default on, matching the @TeX{} behavior.
-
address@hidden INDEX_ENTRY_COLON
-Symbol used between the index entry and the associated node or section;
-default @samp{:}.
-
address@hidden INLINE_CONTENTS
-For address@hidden If set, output the contents where the @code{@@contents} and
-similar @@-commands are located; default true. This is Ignored if
address@hidden@@set*contentsaftertitlepage} is set (@pxref{Contents}).
-
address@hidden INLINE_INSERTCOPYING
-If set, @code{@@insertcopying} is replaced by the @code{@@copying}
-content (@address@hidden@@copying}}) as if @code{@@insertcopying} were a
-user-defined macro; default false.
-
address@hidden INPUT_ENCODING_NAME
-Normalized encoding name suitable for output. Should be a usable
-charset name in HTML, typically one of the preferred IANA encoding
-names. You should not need to use this variable, since it is set by
address@hidden@@documentencoding} (@address@hidden@@documentencoding}}).
-
address@hidden INPUT_PERL_ENCODING
-Perl encoding used to process the Texinfo source. You should not need
-to use that variable, since it is set by @code{@@documentencoding}
-(@address@hidden@@documentencoding}}).
-
address@hidden MACRO_BODY_IGNORES_LEADING_SPACE
-Ignore white space at the beginning of user defined macro body line,
-mimicking a @TeX{} limitation (@pxref{Macro Details}). Default off.
-
address@hidden MAX_MACRO_CALL_NESTING
-The maximal number of recursive calls of @@-commands defined through
address@hidden@@rmacro}; default 100000. The purpose of this variable is to
-avoid infinite recursions.
-
address@hidden MENU_ENTRY_COLON
-Symbol used between the menu entry and the description; default
address@hidden:}.
-
address@hidden 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.
-The default is false.
-
address@hidden NODE_FILENAMES
-If set, node names are used to construct file names. By default, it
-is set if the output is split by node, or if @code{NODE_FILES} is set
-and the output is split in any way.
-
address@hidden NODE_NAME_IN_INDEX
-If set, use node names in index entries, otherwise prefer section names;
-default true.
-
address@hidden NODE_NAME_IN_MENU
-If set, use node names in menu entries, otherwise prefer section names;
-default true.
-
address@hidden OPEN_QUOTE_SYMBOL
-When an opening quote is needed, e.g., for @samp{@@samp} output, use
-the specified character; default @code{‘} for HTML,
address@hidden‘} for Docbook. For Info, the default depends on the
-enabled document encoding (@address@hidden@@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
-on modern systems. If the document encoding is Unicode, the Info
-output uses a Unicode left quote.
-
address@hidden OUTPUT_ENCODING_NAME
-Normalized encoding name used for output files. Should be a usable
-charset name in HTML, typically one of the preferred IANA encoding
-names. By default, if an input encoding is set (typically through
address@hidden@@documentencoding} or @code{INPUT_ENCODING_NAME}), this
-information is used to set the output encoding name. If no input
-encoding is specified, the default output encoding name may be set by
-the output format. In particular, the XML-based formats use
address@hidden for @code{OUTPUT_ENCODING_NAME} if the encoding is not
-otherwise specified. @address@hidden@@documentencoding}}.
-
address@hidden OVERVIEW_LINK_TO_TOC
-If set, the cross references in the Overview link to the corresponding
-Table of Contents entries; default true.
-
address@hidden PACKAGE
address@hidden PACKAGE_VERSION
address@hidden PACKAGE_AND_VERSION
address@hidden PACKAGE_URL
address@hidden PACKAGE_NAME
-The implementation's short package name, package version, package name
-and version concatenated, package url, and full package name,
-respectively. By default, these variables are all set through
-Autoconf, Automake, and @code{configure}.
-
address@hidden PREFIX
-The output file prefix, which is prepended to some output file names.
-By default it is set by @code{@@setfilename} or from the input file
-(@address@hidden@@setfilename}}). How this value is used depends on the
-value of other customization variables or command line options, such
-as whether the output is split and @code{NODE_FILENAMES}. The default
-is unset.
-
address@hidden PROGRAM
-Name of the program used. By default, it is set to the name of the
-program launched, with a trailing @samp{.pl} removed.
-
address@hidden RENAMED_NODES_FILE
-If set, use the value for the renamed nodes description file. If not
-set, the file is @address@hidden
address@hidden Xref Link Preservation}.
-
address@hidden RENAMED_NODES_REDIRECTIONS
-If set, create redirection files for renamed nodes. Set by default
-when generating address@hidden
-
address@hidden SHOW_MENU
address@hidden --no-headers
-If set, Texinfo menus are output. By default, it is set unless
-generating Docbook or if @option{--no-headers} is specified.
-
address@hidden SORT_ELEMENT_COUNT
address@hidden texi-elements-by-size
address@hidden Longest nodes, finding
address@hidden Sorting nodes by size
-If set, the name of a file to which a list of elements (nodes or
-sections, depending on the output format) is dumped, sorted by the
-number of lines they contain after removal of @@-commands; default
-unset. This is used by the program @code{texi-elements-by-size} in
-the @file{util/} directory of the Texinfo source distribution
-(@pxref{texi-elements-by-size}).
-
address@hidden SORT_ELEMENT_COUNT_WORDS
-When dumping the elements-by-size file (see preceding item), use word
-counts instead of line counts; default false.
-
address@hidden @item SPLIT_INDEX
address@hidden For address@hidden If set, the output is split, and the output
from
address@hidden @code{@@printindex} happens in a sectioning element at the level
of
address@hidden splitting, then split index pages at the next letter after they
have
address@hidden more than that many entries. If set to 0, no index splitting.
-
address@hidden TEST
-If set to true, some variables which are normally dynamically
-generated anew for each run (date, program name, version) are set to
-fixed and given values. This is useful to compare the output to a
-reference file, as is done for the tests. The default is false.
-
address@hidden TEXI2DVI
-Name of the command used to produce PostScript, PDF, and DVI; default
address@hidden @address@hidden Printed Output}.
-
address@hidden TEXI2HTML
address@hidden compatibility, with @command{texi2html}
-Generate HTML and try to be as compatible as possible with
address@hidden; default false.
-
address@hidden TEXINFO_COLUMN_FOR_DESCRIPTION
-Used with the @code{indent_menu_descriptions} tree transformation,
-described below; default 32 (matching
address@hidden in Emacs)).
-
address@hidden TEXINFO_DTD_VERSION
-For address@hidden Version of the DTD used in the XML output preamble. The
-default is set based on a variable in @file{configure.ac}.
-
address@hidden TEXTCONTENT_COMMENT
-For stripped text content output (i.e., when
address@hidden is set to @code{textcontent}). If set,
-also output comments. Default false.
-
address@hidden TOP_NODE_UP
-Up node for the Top node; default @samp{(dir)}.
-
address@hidden TREE_TRANSFORMATIONS
-The associated value is a comma separated list of transformations that
-can be applied to the Texinfo tree prior to outputting the result. If
-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
address@hidden for HTML and Docbook output.
-Here's an example of updating the master menu in a document:
-
address@hidden
-makeinfo \
- -c TREE_TRANSFORMATIONS=regenerate_master_menu \
- -c PLAINTEXINFO=1 \
- mydoc.texi \
- -o /tmp/out
address@hidden example
-
address@hidden (Caveat: Since @code{PLAINTEXINFO} output does expand
-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.)
-
-The following transformations are currently supported (many are used
-in the @code{pod2texi} utility distributed with Texinfo):
-
address@hidden @samp
address@hidden complete_tree_nodes_menus
-Add menu entries or whole menus for nodes associated with sections of
-any level, based on the sectioning tree.
-
address@hidden fill_gaps_in_sectioning
-Adds empty @code{@@unnumbered} in a tree to fill gaps in sectioning.
-For example, an @code{@@unnumberedsec} will be inserted if an
address@hidden@@chapter} is followed by an @code{@@subsection}.
-
address@hidden indent_menu_descriptions
-Reformat menus so that descriptions start at column
address@hidden
-
address@hidden insert_nodes_for_sectioning_commands
-Insert nodes for sectioning commands lacking a corresponding node.
-
address@hidden move_index_entries_after_items
-In @code{@@enumerate} and @code{@@itemize}, move index entries
-appearing just before an @code{@@item} to just after the
address@hidden@@item}. Comment lines between index entries are moved too. As
-mentioned, this is always done for HTML and Docbook output.
-
address@hidden regenerate_master_menu
-Update the Top node master menu, either replacing the (first)
address@hidden@@detailmenu} in the Top node menu, or creating it at the end of
-the Top node menu.
-
address@hidden simple_menu
-Mostly the same as @code{SIMPLE_MENU}: use a simple preformatted style
-for the menu. It differs from setting @code{SIMPLE_MENU} in that
address@hidden only has an effect in HTML output.
-
address@hidden ftable
-
address@hidden USE_NODES
-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.
-
address@hidden USE_NODE_TARGET
-If set, use the node associated with a section for the section target
-in cross references; default true.
-
address@hidden USE_NUMERIC_ENTITY
-For HTML and address@hidden If set, use numeric entities instead of ASCII
-characters when there is no named entity. By default, set to true for
-HTML.
-
address@hidden USE_UP_NODE_FOR_ELEMENT_UP
-Fill in up sectioning direction with node direction when there is no
-sectioning up direction. In practice this can only happen when there
-is no @@top section. Not set by default.
-
address@hidden USE_SETFILENAME_EXTENSION
-Default is on for Info, off for other output. If set, use exactly
-what @code{@@setfilename} gives for the output file name, including
-the extension. You should not need to explicitly set this variable.
-
address@hidden USE_TITLEPAGE_FOR_TITLE
-Use the full @code{@@titlepage} as the title, not a simple title string;
-default false.
-
address@hidden USE_UNIDECODE
address@hidden Text::Unidecode
-If set to false, do not use the @code{Text::Unidecode} Perl module to
-transliterate more characters; default true.
-
address@hidden vtable
-
-
address@hidden Internationalization of Document Strings
address@hidden Internationalization of Document Strings
-
address@hidden I18n, of document strings
address@hidden Internationalization of document strings
address@hidden Document strings, internationalization of
address@hidden Output document strings, internationalization of
address@hidden Translating strings in output documents
-
address@hidden documentlanguage @r{customization variable}
address@hidden writes fixed strings into the output document at
-various places: cross references, page footers, the help page,
-alternate text for images, and so on. The string chosen depends on
-the value of the @code{documentlanguage} at the time of the string
-being output (@address@hidden@@documentlanguage}}, for the Texinfo
-command interface).
-
address@hidden libintl-perl @r{Gettext implementation}
-The Gettext framework is used for those strings (@pxref{Top,,,
-gettext, Gettext}). The @code{libintl-perl} package is used as the
address@hidden implementation; more specifically, the pure Perl
-implementation is used, so Texinfo can support consistent behavior
-across all platforms and installations, which would not otherwise be
-possible. @code{libintl-perl} is included in the Texinfo distribution
-and always installed, to ensure that it is available if needed. It is
-also possible to use the system @code{gettext} (the choice can be made
-at build-time).
-
address@hidden texinfo_document @r{Gettext domain}
address@hidden Perl format strings for translation
-The Gettext domain @samp{texinfo_document} is used for the strings.
-Translated strings are written as Texinfo, and may include
-@@-commands. In translated strings, the varying parts of the string
-are not usually denoted by @code{%s} and the like, but by
address@hidden@address@hidden (This convention is common for @code{gettext} in
-Perl and is fully supported in GNU Gettext; @pxref{perl-format,, Perl
-Format Strings, gettext, GNU Gettext}.) For example, in the
-following, @address@hidden@}} will be replaced by the section name:
-
address@hidden
-see @address@hidden
address@hidden example
-
-These Perl-style brace format strings are used for two reasons: first,
-changing the order of @code{printf} arguments is only available since
address@hidden; second, and more importantly, the order of arguments
-is unpredictable, since @@-command expansion may lead to different
-orders depending on the output format.
-
-The expansion of a translation string is done like this:
-
address@hidden
address@hidden First, the string is translated. The locale
-is @var{@@address@hidden@var{@@documentencoding}.
-
address@hidden @code{us-ascii} encoding, and translations
-If the @var{@@documentlanguage} has the form @samp{ll_CC}, that is
-tried first, and then just @samp{ll}. If that does not exist, and the
-encoding is not @code{us-ascii}, then @code{us-ascii} is tried.
-
-The idea is that if there is a @code{us-ascii} encoding, it means that
-all the characters in the charset may be expressed as @@-commands.
-For example, there is a @code{fr.us-ascii} locale that can accommodate
-any encoding, since all the address@hidden characters have associated
-@@-commands. On the other hand, Japanese has only a translation
address@hidden, since there are no @@-commands for Japanese
-characters.
-
address@hidden Next, the string is expanded as Texinfo, and converted.
-The arguments are substituted; for example, @address@hidden@}} is
-replaced by the corresponding actual argument.
-
address@hidden enumerate
-
-In the following example, @address@hidden@}}, @address@hidden@}}
-and @address@hidden@}} are the arguments of the string. Since they
-are used in @code{@@uref}, their order is not predictable.
address@hidden@address@hidden, @address@hidden@}} and @address@hidden@}} are
-substituted after the expansion:
-
address@hidden
-Generated on @@address@hidden@address@hidden@} using
-@@address@hidden@address@hidden, @@address@hidden@address@hidden@address@hidden
address@hidden example
-
-This approach is admittedly a bit complicated. Its usefulness is that
-it supports having translations available in different encodings for
-encodings which can be covered by @@-commands, and also specifying how
-the formatting for some commands is done, independently of the output
-format---yet still be language-dependent. For example, the
address@hidden@@pxref} translation string can be like this:
-
address@hidden
-see @address@hidden section address@hidden@}\' in
@@address@hidden@address@hidden@}
address@hidden example
-
address@hidden
-which allows for specifying a string independently of the output
-format, while nevertheless with rich formatting it may be translated
-appropriately in many languages.
-
-
address@hidden Invoking @t{pod2texi}
address@hidden Invoking @t{pod2texi}:
-
address@hidden pod2texi
address@hidden Invoking @code{pod2texi}
address@hidden POD, converting to Texinfo
address@hidden Perl POD, converting to Texinfo
-
-The @code{pod2texi} program translates Perl pod documentation file(s)
-to Texinfo. There are two basic modes of operation: generating a
-standalone manual from each input pod, or (if @code{--base-level=1} or
-higher is given) generating Texinfo subfiles suitable for use
-with @code{@@include}.
-
-Although ordinarily this documentation in the Texinfo manual would be
-the best place to look, in this case we have documented all the
-options and examples in the @code{pod2texi} program itself, since it
-may be useful outside of the rest of Texinfo. Thus, please see the
-output of @code{pod2texi --help}, the version on the web at
address@hidden://www.gnu.org/software/texinfo/manual/pod2texi.html}, etc.
-
-For an example of using @code{pod2texi} to make Texinfo out of the
-Perl documentation itself, see
address@hidden://svn.savannah.gnu.org/viewvc/trunk/contrib/perldoc-all/?root=texinfo,
address@hidden/perldoc-all}} in the Texinfo source distribution (the
-output is available at @url{http://www.gnu.org/software/perl/manual}).
-
-
address@hidden @t{texi2html}
address@hidden @code{texi2html}: Ancestor of @code{texi2any}
-
address@hidden texi2html
-
address@hidden Cons, Lionel
-Conceptually, the @command{texi2html} program is the parent of today's
address@hidden program. @command{texi2html} was developed
-independently, originally by Lionel Cons in 1998; at the time,
address@hidden could not generate address@hidden Many other people
-contributed to @command{texi2html} over the years.
-
-The present @command{texi2any} uses little of the actual code of
address@hidden, and has quite a different basic approach to the
-implementation (namely, parsing the Texinfo document into a tree), but
-still, there is a family resemblance.
-
-By design, @command{texi2any} supports nearly all the features of
address@hidden in some way. However, we did not attempt to
-maintain strict compatibility, so no @command{texi2html} executable is
-installed by the Texinfo package. An approximation can be run with an
-invocation like this (available as @file{util/texi2html} in the
-Texinfo source):
-
address@hidden
-texi2any --set-customization-variable TEXI2HTML=1 ...
address@hidden example
-
address@hidden but, to emphasize, this is @emph{not} a drop-in replacement
-for the previous @command{texi2html}. Here are the biggest differences:
-
address@hidden @bullet
address@hidden Most blatantly, the command line options of @command{texi2html}
-are now customization variables, for the most part. A table of
-approximate equivalents is given below.
-
address@hidden The program-level customization API is very different in
address@hidden
-
address@hidden Indices cannot be split.
-
address@hidden Translated strings cannot be customized; we hope to introduce
-this feature in @command{texi2any} in the future.
-
address@hidden itemize
-
-Aside from the last, we do not intend to reimplement these
-differences. Therefore, the route forward for authors is alter
-manuals and build processes as necessary to use the new features and
-methods of @command{texi2any}. The @command{texi2html} maintainers
-(one of whom is the principal author of @command{texi2any}) do not
-intend to make further releases.
-
address@hidden Options of @command{texi2html}
address@hidden Command-line options of @command{texi2html}
-Here is the table showing @command{texi2html} options and
-corresponding @command{texi2any} customization variables.
address@hidden (@pxref{texi2any Output Customization,, @command{texi2any} Output
address@hidden Customization}).
-
address@hidden address@hidden address@hidden
address@hidden @option{--toc-links} @tab @code{TOC_LINKS}
address@hidden @option{--short-ext} @tab @code{SHORTEXTN}
address@hidden @option{--prefix} @tab @code{PREFIX}
address@hidden @option{--short-ref} @tab @code{SHORT_REF}
address@hidden @option{--idx-sum} @tab @code{IDX_SUMMARY}
address@hidden @option{--def-table} @tab @code{DEF_TABLE}
address@hidden @option{--ignore-preamble-text} @tab @code{IGNORE_PREAMBLE_TEXT}
address@hidden @option{--html-xref-prefix} @tab @code{EXTERNAL_DIR}
address@hidden @option{--l2h} @tab @code{L2H}
address@hidden @option{--l2h-l2h} @tab @code{L2H_L2H}
address@hidden @option{--l2h-skip} @tab @code{L2H_SKIP}
address@hidden @option{--l2h-tmp} @tab @code{L2H_TMP}
address@hidden @option{--l2h-file} @tab @code{L2H_FILE}
address@hidden @option{--l2h-clean} @tab @code{L2H_CLEAN}
address@hidden @option{--use-nodes} @tab @code{USE_NODES}
address@hidden @option{--monolithic} @tab @code{MONOLITHIC}
address@hidden @option{--top-file} @tab @code{TOP_FILE}
address@hidden @option{--toc-file} @tab @code{TOC_FILE}
address@hidden @option{--frames} @tab @code{FRAMES}
address@hidden @option{--menu} @tab @code{SHOW_MENU}
address@hidden @option{--debug} @tab @code{DEBUG}
address@hidden @option{--doctype} @tab @code{DOCTYPE}
address@hidden @option{--frameset-doctype} @tab @code{FRAMESET_DOCTYPE}
address@hidden @option{--test} @tab @code{TEST}
address@hidden multitable
-
address@hidden @file{texi2oldapi.texi}, for @command{texi2any}
-Finally, any @command{texi2html} users seeking more detailed
-information can check the draft file @file{doc/texi2oldapi.texi} in
-the Texinfo source repository. It consists mainly of very rough
-notes, but may still be useful to some.
-
-
address@hidden Creating and Installing Info Files
address@hidden Creating and Installing Info Files
-
-This chapter describes how to create and install Info files.
address@hidden Files}, for general information about the file format
-itself.
-
address@hidden
-* Creating an Info File::
-* Installing an Info File::
address@hidden menu
-
-
address@hidden Creating an Info File
address@hidden Creating an Info File
address@hidden Creating an Info file
address@hidden Info, creating an online file
address@hidden Formatting a file for Info
-
address@hidden is a program that converts a Texinfo file into an Info
-file, HTML file, or plain text. @code{texinfo-format-region} and
address@hidden are GNU Emacs functions that convert
-Texinfo to Info.
-
-For information on installing the Info file in the Info system,
address@hidden an Info File}.
-
address@hidden
-* @t{makeinfo} Advantages:: @code{makeinfo} provides better error
checking.
-* @t{makeinfo} in Emacs:: How to run @code{makeinfo} from Emacs.
-* @t{texinfo-format} commands:: Two Info formatting commands written
- in Emacs Lisp are an alternative
- to @code{makeinfo}.
-* Batch Formatting:: How to format for Info in Emacs Batch mode.
-* Tag and Split Files:: How tagged and split files help Info
- to run better.
address@hidden menu
-
-
address@hidden @t{makeinfo} Advantages
address@hidden @code{makeinfo} Advantages
-
address@hidden address@hidden old name
-
-The @code{makeinfo} utility creates an Info file from a Texinfo source
-providing better error messages than either of the Emacs formatting
-commands. We recommend it. The @code{makeinfo} program is
-independent of Emacs. You can run @code{makeinfo} in any of three
-ways: from an operating system shell, from a shell inside Emacs, or by
-typing the @kbd{C-c C-m C-r} or the @kbd{C-c C-m C-b} command in
-Texinfo mode in Emacs.
-
-The @code{texinfo-format-region} and the @code{texinfo-format-buffer}
-commands may be useful if you cannot run @code{makeinfo}.
-
-
address@hidden @t{makeinfo} in Emacs
address@hidden Running @code{makeinfo} Within Emacs
-
address@hidden anchor{makeinfo in address@hidden prev name
address@hidden Running @code{makeinfo} in Emacs
address@hidden @code{makeinfo} inside Emacs
address@hidden Shell, running @code{makeinfo} in
-
-You can run @code{makeinfo} in GNU Emacs Texinfo mode by using either the
address@hidden or the @code{makeinfo-buffer} commands. In
-Texinfo mode, the commands are bound to @kbd{C-c C-m C-r} and @kbd{C-c
-C-m C-b} by default.
-
address@hidden @kbd
address@hidden C-c C-m C-r
address@hidden M-x makeinfo-region
-Format the current region for Info.
address@hidden makeinfo-region
-
address@hidden C-c C-m C-b
address@hidden M-x makeinfo-buffer
-Format the current buffer for Info.
address@hidden makeinfo-buffer
address@hidden table
-
-When you invoke @code{makeinfo-region} the output goes to a temporary
-buffer. When you invoke @code{makeinfo-buffer} output goes to the
-file set with @code{@@setfilename} (@address@hidden@@setfilename}}).
-
-The Emacs @code{makeinfo-region} and @code{makeinfo-buffer} commands
-run the @code{makeinfo} program in a temporary shell buffer. If
address@hidden finds any errors, Emacs displays the error messages in
-the temporary buffer.
-
address@hidden Errors, parsing
address@hidden Parsing errors
address@hidden next-error
-You can parse the error messages by typing @kbd{C-x `}
-(@code{next-error}). This causes Emacs to go to and position the
-cursor on the line in the Texinfo source that @code{makeinfo} thinks
-caused the error. @xref{Compilation, , Running @code{make} or
-Compilers Generally, emacs, The GNU Emacs Manual}, for more
-information about using the @code{next-error} command.
-
-In addition, you can kill the shell in which the @code{makeinfo}
-command is running or make the shell buffer display its most recent
-output.
-
address@hidden @kbd
address@hidden C-c C-m C-k
address@hidden M-x makeinfo-kill-job
address@hidden makeinfo-kill-job
-Kill the current running @code{makeinfo} job
-(from @code{makeinfo-region} or @code{makeinfo-buffer}).
-
address@hidden C-c C-m C-l
address@hidden M-x makeinfo-recenter-output-buffer
address@hidden makeinfo-recenter-output-buffer
-Redisplay the @code{makeinfo} shell buffer to display its most recent
-output.
address@hidden table
-
address@hidden
-(Note that the parallel commands for killing and recentering a @TeX{}
-job are @kbd{C-c C-t C-k} and @kbd{C-c C-t C-l}. @xref{Texinfo Mode
-Printing}.)
-
-You can specify options for @code{makeinfo} by setting the
address@hidden variable with either the @kbd{M-x
-customize} or the @kbd{M-x set-variable} command, or by setting the
-variable in your @file{.emacs} initialization file.
-
-For example, you could write the following in your @file{.emacs} file:
-
address@hidden
address@hidden
-(setq makeinfo-options
- "--paragraph-indent=0 --no-split
- --fill-column=70 --verbose")
address@hidden group
address@hidden example
-
address@hidden
address@hidden Writing these three cross references using xref results in
address@hidden three references to the same named manual, which looks strange.
address@hidden
-For more information, see @address@hidden Options}, as well as
-``Easy Customization Interface,'' ``Examining and Setting Variables,''
-and ``Init File'' in @cite{The GNU Emacs Manual}.
address@hidden iftex
address@hidden
-For more information, address@hidden
address@hidden Customization, , Easy Customization Interface, emacs, The GNU
Emacs Manual},@*
address@hidden, , Examining and Setting Variables, emacs, The GNU Emacs
Manual},@*
address@hidden File, , , emacs, The GNU Emacs Manual}, address@hidden
address@hidden@t{makeinfo} Options}.
address@hidden ifnottex
-
-
address@hidden @t{texinfo-format} commands
address@hidden The @address@hidden Commands
-
address@hidden anchor{texinfo-format address@hidden prev name
-
-In GNU Emacs in Texinfo mode, you can format part or all of a Texinfo
-file with the @code{texinfo-format-region} command. This formats the
-current region and displays the formatted text in a temporary buffer
-called @samp{*Info Region*}.
-
-Similarly, you can format a buffer with the
address@hidden command. This command creates a new
-buffer and generates the Info file in it. Typing @kbd{C-x C-s} will
-save the Info file under the name specified by the
address@hidden@@setfilename} line which must be near the beginning of the
-Texinfo file.
-
address@hidden @kbd
address@hidden C-c C-e C-r
address@hidden @code{texinfo-format-region}
address@hidden texinfo-format-region
-Format the current region for Info.
-
address@hidden C-c C-e C-b
address@hidden @code{texinfo-format-buffer}
address@hidden texinfo-format-buffer
-Format the current buffer for Info.
address@hidden table
-
-The @code{texinfo-format-region} and @code{texinfo-format-buffer}
-commands provide you with some error checking, and other functions can
-provide you with further help in finding formatting errors. These
-procedures are described in an appendix; see @ref{Catching Mistakes}.
-However, the @code{makeinfo} program provides better error checking
-(@address@hidden in Emacs}).
-
-
address@hidden Batch Formatting
address@hidden Batch Formatting
address@hidden Batch formatting for Info
address@hidden Info batch formatting
-
-You can format Texinfo files for Info using @code{batch-texinfo-format}
-and Emacs Batch mode. You can run Emacs in Batch mode from any shell,
-including a shell inside of Emacs. (@xref{Command Arguments,,,
-emacs, The GNU Emacs Manual}.)
-
-Here is a shell command to format all the files that end in
address@hidden in the current directory:
-
address@hidden
-emacs -batch -funcall batch-texinfo-format *.texinfo
address@hidden example
-
address@hidden
-Emacs processes all the files listed on the command line, even if an
-error occurs while attempting to format some of them.
-
-Run @code{batch-texinfo-format} only with Emacs in Batch mode as shown;
-it is not interactive. It kills the Batch mode Emacs on completion.
-
address@hidden is convenient if you lack @code{makeinfo}
-and want to format several Texinfo files at once. When you use Batch
-mode, you create a new Emacs process. This frees your current Emacs, so
-you can continue working in it. (When you run
address@hidden or @code{texinfo-format-buffer}, you cannot
-use that Emacs for anything else until the command finishes.)
-
address@hidden Tag and Split Files
address@hidden Tag Files and Split Files
address@hidden Making a tag table automatically
address@hidden Tag table, making automatically
-
-If a Texinfo file has more than 30,000 bytes,
address@hidden automatically creates a tag table
-for its Info file; @code{makeinfo} always creates a tag table. With
-a @dfn{tag table}, Info can jump to new nodes more quickly than it can
-otherwise.
-
address@hidden Indirect subfiles
-In addition, if the Texinfo file contains more than about 300,000
-bytes, @code{texinfo-format-buffer} and @code{makeinfo} split the
-large Info file into shorter @dfn{indirect} subfiles of about 300,000
-bytes each. Big files are split into smaller files so that Emacs does
-not need to make a large buffer to hold the whole of a large Info
-file; instead, Emacs allocates just enough memory for the small, split-off
-file that is needed at the time. This way, Emacs avoids wasting
-memory when you run Info. (Before splitting was implemented, Info
-files were always kept short and @dfn{include files} were designed as
-a way to create a single, large printed manual out of the smaller Info
-files. @xref{Include Files}, for more information. Include files are
-still used for very large documents, such as @cite{The Emacs Lisp
-Reference Manual}, in which each chapter is a separate file.)
-
-When a file is split, Info itself makes use of a shortened version of
-the original file that contains just the tag table and references to
-the files that were split off. The split-off files are called
address@hidden files.
-
-The split-off files have names that are created by appending @address@hidden,
address@hidden@samp{-2}}, @address@hidden and so on to the file name specified
by the
address@hidden@@setfilename} command. The shortened version of the original
file
-continues to have the name specified by @code{@@setfilename}.
-
-At one stage in writing this document, for example, the Info file was saved
-as the file @file{test-texinfo} and that file looked like this:
-
address@hidden
address@hidden
-Info file: test-texinfo, -*-Text-*-
-produced by texinfo-format-buffer
-from file: new-texinfo-manual.texinfo
-
-^_
-Indirect:
-test-texinfo-1: 102
-test-texinfo-2: 50422
address@hidden group
address@hidden
-test-texinfo-3: 101300
-^_^L
-Tag table:
-(Indirect)
-Node: overview^?104
-Node: info file^?1271
address@hidden group
address@hidden
-Node: printed manual^?4853
-Node: conventions^?6855
address@hidden
address@hidden group
address@hidden example
-
address@hidden
-(But @file{test-texinfo} had far more nodes than are shown here.) Each of
-the split-off, indirect files, @file{test-texinfo-1},
address@hidden, and @file{test-texinfo-3}, is listed in this file
-after the line that says @samp{Indirect:}. The tag table is listed after
-the line that says @samp{Tag table:}.
-
-In the list of indirect files, the number following the file name
-records the cumulative number of bytes in the preceding indirect
-files, not counting the file list itself, the tag table, or any
-permissions text in the first file. In the tag table, the number
-following the node name records the location of the beginning of the
-node, in bytes from the beginning of the (unsplit) output.
-
-If you are using @code{texinfo-format-buffer} to create Info files,
-you may want to run the @code{Info-validate} command. (The
address@hidden command does such a good job on its own, you do not
-need @code{Info-validate}.) However, you cannot run the @kbd{M-x
-Info-validate} node-checking command on indirect files. For
-information on how to prevent files from being split and how to
-validate the structure of the nodes, see @ref{Using
address@hidden
-
-
address@hidden Installing an Info File
address@hidden Installing an Info File
address@hidden Installing an Info file
address@hidden Info file installation
address@hidden @file{dir} directory for Info installation
-
-Info files are usually kept in the @file{info} directory. You can
-read Info files using the standalone Info program or the Info reader
-built into Emacs. (@xref{Top,,, info, Info}, for an introduction to
-Info.)
-
address@hidden
-* 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.
-* Installing Dir Entries:: How to specify what menu entry to add
- to the Info directory.
-* Invoking @t{install-info}:: @code{install-info} options.
address@hidden menu
-
-
address@hidden Directory File
address@hidden 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,
-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
address@hidden C-f} to see the pathname to the @file{info} directory.)
-
-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:
-
address@hidden
address@hidden
-* Menu:
-* Info: (info). Documentation browsing system.
-* Emacs: (emacs). The extensible, self-documenting
- text editor.
-* Texinfo: (texinfo). With one source file, make
- either a printed manual using
- @@address@hidden@} or an Info file.
address@hidden
address@hidden group
address@hidden example
-
-Each of these menu entries points to the `Top' node of the Info file
-that is named in parentheses. (The menu entry does not need to
-specify the `Top' node, since Info goes to the `Top' node if no node
-name is mentioned. @xref{Other Info Files, , Nodes in Other Info
-Files}.)
-
-Thus, the @samp{Info} entry points to the `Top' node of the
address@hidden file and the @samp{Emacs} entry points to the `Top' node
-of the @file{emacs} file.
-
-In each of the Info files, the `Up' pointer of the `Top' node refers
-back to the @code{dir} file. For example, the line for the `Top'
-node of the Emacs manual looks like this in Info:
-
address@hidden
-File: emacs Node: Top, Up: (DIR), Next: Distrib
address@hidden example
-
address@hidden
-In this case, the @file{dir} file name is written in uppercase
-letters---it can be written in either upper- or lowercase. This is not
-true in general, it is a special case for @file{dir}.
-
-
address@hidden New Info File
address@hidden Listing a New Info File
address@hidden Adding a new Info file
address@hidden Listing a new Info file
address@hidden New Info file, listing it in @file{dir} file
address@hidden Info file, listing a new
address@hidden @file{dir} file listing
-
-To add a new Info file to your system, you must write a menu entry to
-add to the menu in the @file{dir} file in the @file{info} directory.
-For example, if you were adding documentation for GDB, you would write
-the following new entry:
-
address@hidden
-* GDB: (gdb). The source-level C debugger.
address@hidden example
-
address@hidden
-The first part of the menu entry is the menu entry name, followed by a
-colon. The second part is the name of the Info file, in parentheses,
-followed by a period. The third part is the description.
-
-The name of an Info file often has a @file{.info} extension. Thus, the
-Info file for GDB might be called either @file{gdb} or @file{gdb.info}.
-The Info reader programs automatically try the file name both with and
-without @address@hidden MS-DOS/MS-Windows systems, Info will
-try the @file{.inf} extension as well.}; so it is better to avoid
-clutter and not to write @samp{.info} explicitly in the menu entry. For
-example, the GDB menu entry should use just @samp{gdb} for the file
-name, not @samp{gdb.info}.
-
-
address@hidden Other Info Directories
address@hidden Info Files in Other Directories
address@hidden Installing Info in another directory
address@hidden Info installed in another directory
address@hidden Another Info directory
address@hidden @file{dir} files and Info directories
-
-If an Info file is not in the @file{info} directory, there are three
-ways to specify its location:
-
address@hidden
address@hidden
-Write the pathname in the @file{dir} file as the second part of the menu.
-
address@hidden
-Specify the Info directory name in the @code{INFOPATH} environment
-variable in your @file{.profile} or @file{.cshrc} initialization file.
-(Only you and others who set this environment variable will be able to
-find Info files whose location is specified this way.)
-
address@hidden
-If you are using Emacs, list the name of the file in a second @file{dir}
-file, in its directory; and then add the name of that directory to the
address@hidden variable in your personal or site
-initialization file.
-
-This variable tells Emacs where to look for @file{dir} files (the files
-must be named @file{dir}). Emacs merges the files named @file{dir} from
-each of the listed directories. (In Emacs version 18, you can set the
address@hidden variable to the name of only one
-directory.)
address@hidden enumerate
-
-For example, to reach a test file in the @file{/home/bob/info}
-directory, you could add an entry like this to the menu in the
-standard @file{dir} file:
-
address@hidden
-* Test: (/home/bob/info/info-test). Bob's own test file.
address@hidden example
-
address@hidden
-In this case, the absolute file name of the @file{info-test} file is
-written as the second part of the menu entry.
-
address@hidden INFOPATH
address@hidden Environment variable @code{INFOPATH}
-If you don't want to edit the system @file{dir} file, you can tell
-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
address@hidden 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
address@hidden file or in the registry. Each type of shell uses
-a different syntax.
-
address@hidden @bullet
address@hidden
-In a @file{.cshrc} file, you could set the @code{INFOPATH}
-variable as follows:
-
address@hidden
-setenv INFOPATH .:~/info:/usr/local/emacs/info
address@hidden smallexample
-
address@hidden
-In a @file{.profile} file, you would achieve the same effect by writing:
-
address@hidden
-INFOPATH=.:$HOME/info:/usr/local/emacs/info
-export INFOPATH
address@hidden smallexample
-
address@hidden
address@hidden 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):
-
address@hidden
-set INFOPATH=.;%HOME%/info;c:/usr/local/emacs/info
address@hidden smallexample
address@hidden itemize
-
address@hidden
-The @samp{.} indicates the current directory as usual. Emacs uses the
address@hidden 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
address@hidden variable into a single menu presented to you in the node
-called @samp{(dir)Top}.
-
address@hidden Colon, last in @env{INFOPATH}
-However you set @env{INFOPATH}, if its last character is a colon (on
-MS-DOS/MS-Windows systems, use a semicolon instead), this is replaced
-by the default (compiled-in) path. This gives you a way to augment
-the default path with new directories without having to list all the
-standard places. For example (using @code{sh} syntax):
-
address@hidden
-INFOPATH=/home/bob/info:
-export INFOPATH
address@hidden example
-
address@hidden
-will search @file{/home/bob/info} first, then the standard directories.
-Leading or doubled colons are not treated specially.
-
address@hidden @file{dir} file, creating your own
-When you create your own @file{dir} file for use with
address@hidden or @env{INFOPATH}, it's easiest to start by
-copying an existing @file{dir} file and replace all the text after the
address@hidden Menu:} with your desired entries. That way, the punctuation
-and special @kbd{CTRL-_} characters that Info needs will be present.
-
-As one final alternative, which works only with Emacs Info, you can
-change the @code{Info-directory-list} variable. For example:
-
address@hidden
-(add-hook 'Info-mode-hook '(lambda ()
- (add-to-list 'Info-directory-list
- (expand-file-name "~/info"))))
address@hidden example
-
-
address@hidden Installing Dir Entries
address@hidden Installing Info Directory Files
-
-When you install an Info file onto your system, you can use the program
address@hidden to update the Info directory file @file{dir}.
-Normally the makefile for the package runs @code{install-info}, just
-after copying the Info file into its proper installed location.
-
address@hidden dircategory
address@hidden direntry
-In order for the Info file to work with @code{install-info}, you include
-the commands @code{@@dircategory} and
address@hidden@@address@hidden@code{@@end direntry} in the Texinfo source
-file. Use @code{@@direntry} to specify the menu entries to add to the
-Info directory file, and use @code{@@dircategory} to specify which part
-of the Info directory to put it in. Here is how these commands are used
-in this manual:
-
address@hidden
-@@dircategory Texinfo documentation system
-@@direntry
-* Texinfo: (texinfo). The GNU documentation format.
-* install-info: (texinfo)Invoking install-info. @dots{}
address@hidden
-@@end direntry
address@hidden smallexample
-
-Here's what this produces in the Info file:
-
address@hidden
-INFO-DIR-SECTION Texinfo documentation system
-START-INFO-DIR-ENTRY
-* Texinfo: (texinfo). The GNU documentation format.
-* install-info: (texinfo)Invoking install-info. @dots{}
address@hidden
-END-INFO-DIR-ENTRY
address@hidden smallexample
-
address@hidden
-The @code{install-info} program sees these lines in the Info file, and
-that is how it knows what to do.
-
-Always use the @code{@@direntry} and @code{@@dircategory} commands near
-the beginning of the Texinfo input, before the first @code{@@node}
-command. If you use them later on in the input, @code{install-info}
-will not notice them.
-
address@hidden will automatically reformat the description of the
-menu entries it is adding. As a matter of convention, the description
-of the main entry (above, @samp{The GNU documentation format}) should
-start at column 32, starting at zero (as in
address@hidden in Emacs). This will make it align with
-most others. Description for individual utilities best start in
-column 48, where possible. For more information about formatting see
-the @samp{--calign}, @samp{--align}, and @samp{--max-width} options in
address@hidden @t{install-info}}.
-
-If you use @code{@@dircategory} more than once in the Texinfo source,
-each usage specifies the `current' category; any subsequent
address@hidden@@direntry} commands will add to that category.
-
address@hidden Free Software Directory
address@hidden Dir categories, choosing
address@hidden Categories, choosing
-When choosing a category name for the @code{@@dircategory} command, we
-recommend consulting the @uref{http://www.gnu.org/directory,
-Free Software Directory}. If your program is not listed there,
-or listed incorrectly or incompletely, please report the situation to
-the directory maintainers (@email{bug-directory@@gnu.org}) so that the
-category names can be kept in sync.
-
-Here are a few examples (see the @file{util/dir-example} file in the
-Texinfo distribution for large sample @code{dir} file):
-
address@hidden
-Emacs
-Localization
-Printing
-Software development
-Software libraries
-Text creation and manipulation
address@hidden display
-
address@hidden Invoking nodes, including in dir file
-Each `Invoking' node for every program installed should have a
-corresponding @code{@@direntry}. This lets users easily find the
-documentation for the different programs they can run, as with the
-traditional @command{man} system.
-
-
address@hidden Invoking @t{install-info}
address@hidden Invoking @command{install-info}
-
address@hidden install-info
-
address@hidden inserts menu entries from an Info file into the
-top-level @file{dir} file in the Info system (see the previous sections
-for an explanation of how the @file{dir} file works). @code{install-info}
-also removes menu entries from the @file{dir} file. It's most often
-run as part of software installation, or when constructing a @file{dir} file
-for all manuals on a system. Synopsis:
-
address@hidden
-install-info address@hidden@dots{} address@hidden address@hidden
address@hidden example
-
-If @var{info-file} or @var{dir-file} are not specified, the options
-(described below) that define them must be. There are no compile-time
-defaults, and standard input is never used. @code{install-info} can
-read only one Info file and write only one @file{dir} file per invocation.
-
address@hidden @file{dir}, created by @code{install-info}
-If @var{dir-file} (however specified) does not exist,
address@hidden creates it if possible (with no entries).
-
address@hidden Compressed dir files, reading
address@hidden XZ-compressed dir files, reading
address@hidden Bzipped dir files, reading
address@hidden Lzip-compressed dir files, reading
address@hidden LZMA-compressed dir files, reading
address@hidden Dir files, compressed
-If any input file is compressed with @code{gzip} (@pxref{Top,,, gzip,
-Gzip}), @code{install-info} automatically uncompresses it for reading.
-And if @var{dir-file} is compressed, @code{install-info} also
-automatically leaves it compressed after writing any changes. If
address@hidden itself does not exist, @code{install-info} tries to
-open @address@hidden, @address@hidden,
address@hidden@var{dir-file}.bz2}, @address@hidden, and
address@hidden@var{dir-file}.lzma}, in that order.
-
-Options:
-
address@hidden @code
address@hidden --add-once
address@hidden address@hidden, for @command{install-info}}
-Specifies that the entry or entries will only be put into a single section.
-
address@hidden address@hidden
address@hidden address@hidden@r{, for @command{install-info}}
-Specifies the column that the second and subsequent lines of menu entry's
-description will be formatted to begin at. The default for this option is
address@hidden It is used in conjunction with the @samp{--max-width} option.
address@hidden starts counting at 1.
-
address@hidden --append-new-sections
address@hidden address@hidden, for @command{install-info}}
-Instead of alphabetizing new sections, place them at the end of the DIR file.
-
address@hidden address@hidden
address@hidden address@hidden@r{, for @command{install-info}}
-Specifies the column that the first line of menu entry's description will
-be formatted to begin at. The default for this option is @samp{33}. It is
-used in conjunction with the @samp{--max-width} option.
-When the name of the menu entry exceeds this column, entry's description
-will start on the following line.
address@hidden starts counting at 1.
-
address@hidden --debug
address@hidden address@hidden, for @command{install-info}}
-Report what is being done.
-
address@hidden --delete
address@hidden address@hidden, for @command{install-info}}
-Delete the entries in @var{info-file} from @var{dir-file}. The file
-name in the entry in @var{dir-file} must be @var{info-file} (except for
-an optional @samp{.info} in either one). Don't insert any new entries.
-Any empty sections that result from the removal are also removed.
-
address@hidden address@hidden
address@hidden address@hidden@r{, for @command{install-info}}
-Specify the explanatory portion of the menu entry. If you don't specify
-a description (either via @samp{--entry}, @samp{--item} or this option),
-the description is taken from the Info file itself.
-
address@hidden address@hidden
address@hidden address@hidden@r{, for @command{install-info}}
-Specify file name of the Info directory file. This is equivalent to
-using the @var{dir-file} argument.
-
address@hidden --dry-run
address@hidden address@hidden, for @command{install-info}}
-Same as @samp{--test}.
-
address@hidden address@hidden
address@hidden address@hidden@r{, for @command{install-info}}
-Insert @var{text} as an Info directory entry; @var{text} should have the
-form of an Info menu item line plus zero or more extra lines starting
-with whitespace. If you specify more than one entry, they are all
-added. If you don't specify any entries, they are determined from
-information in the Info file itself.
-
address@hidden --help
address@hidden address@hidden, for @command{texindex}}
-Display a usage message with basic usage and all available options,
-then exit successfully.
-
address@hidden address@hidden
address@hidden address@hidden@r{, for @command{install-info}}
-Specify Info file to install in the directory. This is
-equivalent to using the @var{info-file} argument.
-
address@hidden address@hidden
address@hidden address@hidden@r{, for @command{install-info}}
-Specify the directory where the directory file @file{dir} resides.
-Equivalent to @address@hidden/dir}.
-
address@hidden address@hidden
address@hidden address@hidden@r{, for @command{install-info}}
-Same as @samp{--info-dir}.
-
address@hidden address@hidden
address@hidden address@hidden@r{, for @command{install-info}}
-Same as @address@hidden An Info directory entry is actually
-a menu item.
-
address@hidden --keep-old
address@hidden address@hidden, for @command{install-info}}
-Do not replace pre-existing menu entries. When @samp{--remove} is specified,
-this option means that empty sections are not removed.
-
address@hidden address@hidden
address@hidden address@hidden@r{, for @command{install-info}}
-Specifies the column that the menu entry's description will be word-wrapped
-at. @var{column} starts counting at 1.
-
address@hidden address@hidden
address@hidden address@hidden@r{, for @command{install-info}}
-Same as @samp{--max-width}.
-
address@hidden address@hidden
address@hidden address@hidden@r{, for @command{install-info}}
-Same as @samp{--name}.
-
address@hidden address@hidden
address@hidden address@hidden@r{, for @command{install-info}}
-Specify the name portion of the menu entry. If the @var{text} does
-not start with an asterisk @samp{*}, it is presumed to be the text
-after the @samp{*} and before the parentheses that specify the Info
-file. Otherwise @var{text} is taken verbatim, and is taken as
-defining the text up to and including the first period (a space is
-appended if necessary). If you don't specify the name (either via
address@hidden, @samp{--item} or this option), it is taken from the
-Info file itself. If the Info does not contain the name, the basename
-of the Info file is used.
-
address@hidden --no-indent
address@hidden address@hidden, for @command{install-info}}
-Suppress formatting of new entries into the @file{dir} file.
-
address@hidden --quiet
address@hidden --silent
address@hidden address@hidden, for @command{install-info}}
address@hidden address@hidden, for @command{install-info}}
-Suppress warnings, etc., for silent operation.
-
address@hidden --remove
address@hidden address@hidden, for @command{install-info}}
-Same as @samp{--delete}.
-
address@hidden --remove-exactly
address@hidden address@hidden, for @command{install-info}}
-Also like @samp{--delete}, but only entries if the Info file name
-matches exactly; @code{.info} and/or @code{.gz} suffixes are
address@hidden ignored.
-
address@hidden address@hidden
address@hidden address@hidden@r{, for @command{install-info}}
-Put this file's entries in section @var{sec} of the directory. If you
-specify more than one section, all the entries are added in each of the
-sections. If you don't specify any sections, they are determined from
-information in the Info file itself. If the Info file doesn't specify
-a section, the menu entries are put into the Miscellaneous section.
-
address@hidden --section @var{regex} @var{sec}
address@hidden --section @var{regex} @address@hidden, for
@command{install-info}}
-Same as @address@hidden address@hidden --add-once}.
-
address@hidden tries to detect when this alternate syntax is used,
-but does not always guess correctly. Here is the heuristic that
address@hidden uses:
address@hidden
address@hidden
-If the second argument to @code{--section} starts with a hyphen, the
-original syntax is presumed.
-
address@hidden
-If the second argument to @code{--section} is a file that can be
-opened, the original syntax is presumed.
-
address@hidden
-Otherwise the alternate syntax is used.
address@hidden 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
-should be changed to @address@hidden address@hidden
---add-once}.
-
address@hidden address@hidden
address@hidden address@hidden@r{, for @command{install-info}}
-Put this file's entries into any section that matches @var{regex}. If
-more than one section matches, all of the entries are added in each of the
-sections. Specify @var{regex} using basic regular expression syntax, more
-or less as used with @command{grep}, for example.
-
address@hidden --test
address@hidden address@hidden, for @command{install-info}}
-Suppress updating of the directory file.
-
address@hidden --version
address@hidden address@hidden, for @command{install-info}}
address@hidden Version number, for install-info
-Display version information and exit successfully.
-
address@hidden table
-
-
address@hidden Generating HTML
address@hidden Generating HTML
-
address@hidden Generating HTML
address@hidden Outputting HTML
-
address@hidden generates Info output by default, but given the
address@hidden option, it will generate HTML, for web browsers and
-other programs. This chapter gives some details on such HTML output.
-
address@hidden has many user-definable customization variables
-with which you can influence the HTML output. @xref{Customization
-Variables}.
-
address@hidden 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.
-
address@hidden
-* HTML Translation:: Details of the HTML output.
-* HTML Splitting:: How HTML output is split.
-* HTML CSS:: Influencing HTML output with Cascading Style Sheets.
-* HTML Xref:: Cross references in HTML output.
address@hidden menu
-
-
address@hidden HTML Translation
address@hidden HTML Translation
-
address@hidden will include segments of Texinfo source between
address@hidden@@ifhtml} and @code{@@end ifhtml} in the HTML output (but not
-any of the other conditionals, by default). Source between
address@hidden@@html} and @code{@@end html} is passed without change to the
-output (i.e., suppressing the normal escaping of input @samp{<},
address@hidden>} and @samp{&} characters which have special significance in
-HTML). @xref{Conditional Commands}.
-
address@hidden Navigation bar, in HTML output
-By default, a navigation bar is inserted at the start of each node,
-analogous to Info output. If the @samp{--no-headers} option is used,
-the navigation bar is only inserted at the beginning of split files.
-Header @code{<link>} elements in split output can support Info-like
-navigation with browsers like Lynx and @w{Emacs W3} which implement
-this address@hidden feature.
-
address@hidden Footnote styles, in HTML
-In HTML, when the footnote style is @samp{end}, or if the output is
-not split, footnotes are put at the end of the output. If set to
address@hidden, and the output is split, they are placed in a
-separate file. @xref{Footnote Styles}.
-
address@hidden HTML output, browser compatibility of
-The HTML generated is standard address@hidden It also tries to be as
-compatible as possible with earlier standards (e.g., address@hidden,
-RFC-1866). Some minor exceptions: 1)@address@hidden tables are
-generated for the @code{@@multitable} command (@pxref{Multi-column
-Tables}), but they should degrade reasonably in browsers without table
-support; 2)@tie{}The address@hidden @samp{lang} attribute on the
address@hidden<html>} attribute is used; 3)@tie{} Entities that are not in the
address@hidden standard are also used. 4)@tie{} CSS is used
-(@pxref{HTML CSS}). 5)@tie{} A few address@hidden elements are used
-(@code{thead}, @code{abbr}, @code{acronym}).
-
-Using @samp{--init-file=html32.pm} produces strict address@hidden
-output (@pxref{Invoking @t{texi2any}}).
-
-Please report output from an error-free run of @code{makeinfo} which
-has browser portability problems as a bug (@pxref{Reporting Bugs}).
-
-
address@hidden HTML Splitting
address@hidden HTML Splitting
address@hidden Split HTML output
address@hidden HTML output, split
-
-When splitting output at nodes (which is the default),
address@hidden writes HTML output into (basically) one output file
-per Texinfo source @code{@@node}.
-
-Each output file name is the node name with spaces replaced by
address@hidden'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
-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.
-
-If @command{makeinfo} is run on a system which does not distinguish
-case in file names, nodes which are the same except for case (e.g.,
address@hidden and @samp{Index}) will also be folded into the same
-output file with anchors. You can also pretend to be on a case
-insensitive filesystem by setting the customization variable
address@hidden
-
-It is also possible to split at chapters or sections with
address@hidden (@pxref{Invoking @t{texi2any}}). In that case,
-the file names are constructed after the name of the node associated
-with the relevant sectioning command. Also, unless
address@hidden is specified, a redirection file is output
-for every node in order to more reliably support cross references to
-that manual (@pxref{HTML Xref}).
-
-When splitting, the HTML output files are written into a subdirectory,
-with the name chosen as follows:
-
address@hidden
address@hidden
address@hidden first tries the subdirectory with the base name
-from @code{@@setfilename} (that is, any extension is removed). For
-example, HTML output for @code{@@setfilename gcc.info} would be
-written into a subdirectory named @samp{gcc/}.
-
address@hidden
-If that directory cannot be created for any reason, then
address@hidden tries appending @samp{.html} to the directory name.
-For example, output for @code{@@setfilename texinfo} would be written
-to @samp{texinfo.html/}.
-
address@hidden
-If the @address@hidden directory can't be created either,
address@hidden gives up.
-
address@hidden enumerate
-
address@hidden In any case, the top-level output file within the directory
-is always named @samp{index.html}.
-
-Monolithic output (@code{--no-split}) is named according to
address@hidden@@setfilename} (with any @samp{.info} extension is replaced with
address@hidden), @code{--output} (the argument is used literally), or
-based on the input file name as a last resort
-(@address@hidden@@setfilename}}).
-
-
address@hidden HTML CSS
address@hidden HTML CSS
address@hidden HTML, and CSS
address@hidden CSS, and HTML output
address@hidden Cascading Style Sheets, and HTML output
-
-Cascading Style Sheets (CSS for short) is an Internet standard for
-influencing the display of HTML documents: see
address@hidden://www.w3.org/Style/CSS/}.
-
-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:
-
address@hidden
-pre.display @{ font-family:inherit @}
-pre.smalldisplay @{ font-family:inherit; font-size:smaller @}
address@hidden 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.
-
-You can influence the CSS in the HTML output with two
address@hidden options: @address@hidden and
address@hidden@var{url}}.
-
address@hidden texinfo-bright-colors.css
address@hidden Visualizing Texinfo CSS
-The option @address@hidden adds to each output HTML file
-a @samp{<link>} tag referencing a CSS at the given @var{url}. This
-allows using external style sheets. You may find the file
address@hidden/examples/texinfo-bright-colors.css} useful for
-visualizing the CSS elements in Texinfo output.
-
-The option @address@hidden includes the contents
address@hidden in the HTML output, as you might expect. However, the
-details are somewhat tricky, as described in the following, to provide
-maximum flexibility.
-
address@hidden @@import specifications, in CSS files
-The CSS file may begin with so-called @samp{@@import} directives,
-which link to external CSS specifications for browsers to use when
-interpreting the document. Again, a full description is beyond our
-scope here, but we'll describe how they work syntactically, so we can
-explain how @command{makeinfo} handles them.
-
address@hidden Comments, in CSS files
-There can be more than one @samp{@@import}, but they have to come
-first in the file, with only whitespace and comments interspersed, no
-normal definitions. (Technical exception: an @samp{@@charset}
-directive may precede the @samp{@@import}'s. This does not alter
address@hidden's behavior, it just copies the @samp{@@charset} if
-present.) Comments in CSS files are delimited by @samp{/* ... */}, as
-in address@hidden An @samp{@@import} directive must be in one of these two
forms:
-
address@hidden
-@@import url(http://example.org/foo.css);
-@@import "http://example.net/bar.css";;
address@hidden example
-
-As far as @command{makeinfo} is concerned, the crucial characters are
-the @samp{@@} at the beginning and the semicolon terminating the
-directive. When reading the CSS file, it simply copies any such
address@hidden@@}-directive into the output, as follows:
-
address@hidden
address@hidden If @var{file} contains only normal CSS declarations, it is
-included after @command{makeinfo}'s default CSS, thus overriding it.
-
address@hidden If @var{file} begins with @samp{@@import} specifications (see
-below), then the @samp{import}'s are included first (they have to come
-first, according to the standard), and then @command{makeinfo}'s
-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:
address@hidden
-pre.smallexample @{ font-size: inherit ! important @}
address@hidden example
-
address@hidden If @var{file} contains both @samp{@@import} and inline CSS
-specifications, the @samp{@@import}'s are included first, then
address@hidden's defaults, and lastly the inline CSS from
address@hidden
-
address@hidden Any @@-directive other than @samp{@@import} and @samp{@@charset}
-is treated as a CSS declaration, meaning @command{makeinfo} includes
-its default CSS and then the rest of the file.
address@hidden itemize
-
-If the CSS file is malformed or erroneous, @command{makeinfo}'s output
-is unspecified. @command{makeinfo} does not try to interpret the
-meaning of the CSS file in any way; it just looks for the special
address@hidden@@} and @samp{;} characters and blindly copies the text into the
-output. Comments in the CSS file may or may not be included in the
-output.
-
-In addition to the possibilities offered by CSS, @command{makeinfo}
-has many user-definable customization variables with which you can
-influence the HTML output. @xref{Customization Variables}.
-
-
address@hidden HTML Xref
address@hidden HTML Cross References
address@hidden HTML cross references
address@hidden Cross references, in HTML output
-
-Cross references between Texinfo manuals in HTML format become, in the
-end, a standard HTML @code{<a>} link, but the details are
-unfortunately complex. This section describes the algorithm used in
-detail, so that Texinfo can cooperate with other programs, such as
address@hidden, by writing mutually compatible HTML files.
-
-This algorithm may or may not be used for links @emph{within} HTML
-output for a Texinfo file. Since no issues of compatibility arise in
-such cases, we do not need to specify this.
-
-We try to support references to such ``external'' manuals in both
-monolithic and split forms. A @dfn{monolithic} (mono) manual is
-entirely contained in one file, and a @dfn{split} manual has a file
-for each node. (@xref{HTML Splitting}.)
-
address@hidden Dumas, Patrice
-The algorithm was primarily devised by Patrice Dumas in 2003--04.
-
address@hidden
-* Link Basics: HTML Xref Link Basics.
-* Node Expansion: HTML Xref Node Name Expansion.
-* Command Expansion: HTML Xref Command Expansion.
-* 8-bit Expansion: HTML Xref 8-bit Character Expansion.
-* Mismatch: HTML Xref Mismatch.
-* Configuration: HTML Xref Configuration. htmlxref.cnf.
-* Preserving links: HTML Xref Link Preservation. MANUAL-noderename.cnf.
address@hidden menu
-
-
address@hidden HTML Xref Link Basics
address@hidden HTML Cross Reference Link Basics
address@hidden HTML cross reference 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
-always assume the @code{http} protocol. For example:
-
address@hidden
-http://@var{host}/@var{dir}/@address@hidden
address@hidden example
-
-The information to construct a link comes from the node name and
-manual name in the cross reference command in the Texinfo source
-(@pxref{Cross References}), and from @dfn{external information}
-(@pxref{HTML Xref Configuration}).
-
-We now consider each part in turn.
-
-The @var{host} is hardwired to be the local host. This could either
-be the literal string @samp{localhost}, or, according to the rules for
-HTML links, the @samp{http://localhost/} could be omitted entirely.
-
-The @var{dir} and @var{file} parts are more complicated, and depend on
-the relative split/mono nature of both the manual being processed and
-the manual that the cross reference refers to. The underlying idea is
-that there is one directory for Texinfo manuals in HTML, and a given
address@hidden is either available as a monolithic file
address@hidden@var{manual}.html}, or a split subdirectory
address@hidden@var{manual}/*.html}. Here are the cases:
-
address@hidden @bullet
address@hidden
-If the present manual is split, and the referent manual is also split,
-the directory is @samp{../@var{referent/}} and the file is the
-expanded node name (described later).
-
address@hidden
-If the present manual is split, and the referent manual is mono, the
-directory is @samp{../} and the file is @address@hidden
-
address@hidden
-If the present manual is mono, and the referent manual is split, the
-directory is @address@hidden/} and the file is the expanded node
-name.
-
address@hidden
-If the present manual is mono, and the referent manual is also mono,
-the directory is @file{./} (or just the empty string), and the file is
address@hidden@var{referent}.html}.
-
address@hidden itemize
-
address@hidden BASEFILENAME_LENGTH
-Another rule, that only holds for filenames, is that base filenames
-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
-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
-reference command is ignored. Thus,
@code{@@address@hidden,,,../address@hidden and
address@hidden@@address@hidden,,,address@hidden both use @samp{foo} as the
manual name. This
-is because any such attempted hardwiring of the directory is very
-unlikely to be useful for both Info and HTML output.
-
-Finally, the @var{target} part is always the expanded node name.
-
-Whether the present manual is split or mono is determined by user
-option; @command{makeinfo} defaults to split, with the
address@hidden option overriding this.
-
-Whether the referent manual is split or mono, however, is another bit
-of the external information (@pxref{HTML Xref Configuration}). By
-default, @command{makeinfo} uses the same form of the referent manual
-as the present manual.
-
-Thus, there can be a mismatch between the format of the referent
-manual that the generating software assumes, and the format it's
-actually present in. @xref{HTML Xref Mismatch}.
-
-
address@hidden HTML Xref Node Name Expansion
address@hidden HTML Cross Reference Node Name Expansion
address@hidden HTML cross reference node name expansion
address@hidden node name expansion, in HTML cross references
address@hidden 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
-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
-restrictive.)
-
-Cross references in Texinfo can refer either to nodes or anchors
-(@address@hidden@@anchor}}). However, anchors are treated identically
-to nodes in this context, so we'll continue to say ``node'' names for
-simplicity.
-
-A special exception: the Top node (@pxref{The Top Node}) is always
-mapped to the file @file{index.html}, to match web server software.
-However, the HTML @emph{target} is @samp{Top}. Thus (in the split case):
-
address@hidden
-@@address@hidden,,, emacs, The GNU Emacs address@hidden
address@hidden <a href="emacs/index.html#Top">
address@hidden example
-
address@hidden
address@hidden
-The standard ASCII letters (a-z and A-Z) are not modified. All other
-characters may be changed as specified below.
-
address@hidden
-The standard ASCII numbers (0-9) are not modified except when a number
-is the first character of the node name. In that case, see below.
-
address@hidden
-Multiple consecutive space, tab and newline characters are transformed
-into just one space. (It's not possible to have newlines in node
-names with the current implementation, but we specify it anyway, just
-in case.)
-
address@hidden
-Leading and trailing spaces are removed.
-
address@hidden
-After the above has been applied, each remaining space character is
-converted into a @samp{-} character.
-
address@hidden
-Other ASCII 7-bit characters are transformed into @address@hidden,
-where @var{xx} is the ASCII character code in (lowercase) hexadecimal.
-This includes @samp{_}, which is mapped to @samp{_005f}.
-
address@hidden
-If the node name does not begin with a letter, the literal string
address@hidden is prefixed to the result. (Due to the rules above, that
-string can never occur otherwise; it is an arbitrary choice, standing
-for ``GNU Texinfo''.) This is necessary because XHTML requires that
-identifiers begin with a letter.
-
address@hidden enumerate
-
-For example:
-
address@hidden
-@@node A node --- with _'%
address@hidden A-node-_002d_002d_002d-with-_005f_0027_0025
address@hidden example
-
-Notice in particular:
-
address@hidden @bullet
address@hidden @samp{_} @result{} @samp{_005f}
address@hidden @samp{-} @result{} @samp{_002d}
address@hidden @samp{A node} @result{} @samp{A-node}
address@hidden itemize
-
-On case-folding computer systems, nodes differing only by case will be
-mapped to the same file. In particular, as mentioned above, Top
-always maps to the file @file{index.html}. Thus, on a case-folding
-system, Top and a node named `Index' will both be written to
address@hidden Fortunately, the targets serve to distinguish
-these cases, since HTML target names are always case-sensitive,
-independent of operating system.
-
-
address@hidden HTML Xref Command Expansion
address@hidden HTML Cross Reference Command Expansion
address@hidden HTML cross reference command expansion
-
-Node names may contain @@-commands (@pxref{Node Line Requirements}).
-This section describes how they are handled.
-
-First, comments are removed.
-
-Next, any @code{@@value} commands (@address@hidden@@set @@value}}) and
-macro invocations (@pxref{Invoking Macros}) are fully expanded.
-
-Then, for the following commands, the command name and braces are removed,
-and the text of the argument is recursively transformed:
-
address@hidden
-@@asis @@b @@cite @@code @@command @@dfn @@dmn @@dotless
-@@emph @@env @@file @@i @@indicateurl @@kbd @@key
-@@samp @@sansserif @@sc @@slanted @@strong @@t @@var @@verb @@w
address@hidden example
-
address@hidden For @code{@@sc}, any letters are capitalized.
-
-In addition, the following commands are replaced by constant text, as
-shown below. If any of these commands have non-empty arguments, as in
address@hidden@@address@hidden@}}, it is an error, and the result is
unspecified.
-In this table, `(space)' means a space character and `(nothing)' means
-the empty string. The notation address@hidden' means Unicode code
-point @var{hhhh} (in hex, as usual). There are further
-transformations of many of these expansions for the final file or
-target name, such as space characters to @samp{-}, etc., according to
-the other rules.
-
address@hidden @columnfractions .3 .5
address@hidden @code{@@(newline)} @tab (space)
address@hidden @code{@@(space)} @tab (space)
address@hidden @code{@@(tab)} @tab (space)
address@hidden @code{@@!} @tab @samp{!}
address@hidden @code{@@*} @tab (space)
address@hidden @code{@@-} @tab (nothing)
address@hidden @code{@@.} @tab @samp{.}
address@hidden @code{@@:} @tab (nothing)
address@hidden @code{@@?} @tab @samp{?}
address@hidden @code{@@@@} @tab @samp{@@}
address@hidden @code{@@@{} @tab @address@hidden
address@hidden @code{@@@}} @tab @address@hidden
address@hidden @code{@@LaTeX} @tab @samp{LaTeX}
address@hidden @code{@@TeX} @tab @samp{TeX}
address@hidden @code{@@arrow} @tab U+2192
address@hidden @code{@@bullet} @tab U+2022
address@hidden @code{@@comma} @tab @samp{,}
address@hidden @code{@@copyright} @tab U+00A9
address@hidden @code{@@dots} @tab U+2026
address@hidden @code{@@enddots} @tab @samp{...}
address@hidden @code{@@equiv} @tab U+2261
address@hidden @code{@@error} @tab @samp{error-->}
address@hidden @code{@@euro} @tab U+20AC
@@ Diff output truncated at 1536000 characters. @@
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [5316] texinfo.txi -> texinfo.texi to placate automake 1.14,
karl <=