Mercurial > hg > xemacs-beta
changeset 5926:da02ba75e50a cygwin
merge heads 3
| author | Henry Thompson <ht@markup.co.uk> |
|---|---|
| date | Fri, 27 Feb 2015 17:48:44 +0000 |
| parents | 08cfc8f77fb6 (current diff) 4b055de36bb9 (diff) |
| children | b58b74274fa2 2f34b59f451a |
| files | |
| diffstat | 3 files changed, 24531 insertions(+), 3 deletions(-) [+] |
line wrap: on
line diff
--- a/man/ChangeLog Fri Feb 27 17:41:20 2015 +0000 +++ b/man/ChangeLog Fri Feb 27 17:48:44 2015 +0000 @@ -1,3 +1,9 @@ +2015-02-23 Mike Kupfer <mike.kupfer@xemacs.org> + + * internals/internals.texi (The Redisplay Mechanism): + Add notes about pixel_to_glyph_translation and related code. + (pixel_to_glyph_translation): New section. + 2014-03-28 Jerry James <james@xemacs.org> * Makefile.in: Do not build texinfo files.
--- a/man/internals/internals.texi Fri Feb 27 17:41:20 2015 +0000 +++ b/man/internals/internals.texi Fri Feb 27 17:48:44 2015 +0000 @@ -625,6 +625,7 @@ * Critical Redisplay Sections:: * Line Start Cache:: * Redisplay Piece by Piece:: +* pixel_to_glyph_translation:: * Modules for the Redisplay Mechanism:: * Modules for other Display-Related Lisp Objects:: @@ -19049,12 +19050,18 @@ @chapter The Redisplay Mechanism @cindex redisplay mechanism, the - The redisplay mechanism is one of the most complicated sections of + The redisplay mechanism is responsible for updating the display, +such as after an edit or a highlighting change. It is one of the most +complicated sections of XEmacs, especially from a conceptual standpoint. This is doubly so because, unlike for the basic aspects of the Lisp interpreter, the computer science theories of how to efficiently handle redisplay are not well-developed. + The redisplay code also provides a low-level operation to +map window system coordinates to XEmacs objects. This is used +elsewhere in XEmacs, most notably for dealing with mouse events. + When working with the redisplay mechanism, remember the Golden Rules of Redisplay: @@ -19071,6 +19078,7 @@ * Critical Redisplay Sections:: * Line Start Cache:: * Redisplay Piece by Piece:: +* pixel_to_glyph_translation:: * Modules for the Redisplay Mechanism:: * Modules for other Display-Related Lisp Objects:: @end menu @@ -19485,7 +19493,7 @@ In case you're wondering, the Second Golden Rule of Redisplay is not applicable. -@node Redisplay Piece by Piece, Modules for the Redisplay Mechanism, Line Start Cache, The Redisplay Mechanism +@node Redisplay Piece by Piece, pixel_to_glyph_translation, Line Start Cache, The Redisplay Mechanism @section Redisplay Piece by Piece @cindex redisplay piece by piece @@ -19582,7 +19590,30 @@ @code{ensure_face_cachel_complete}, with the actual work being done by @code{ensure_face_cachel_contains_charset}. -@node Modules for the Redisplay Mechanism, Modules for other Display-Related Lisp Objects, Redisplay Piece by Piece, The Redisplay Mechanism +@node pixel_to_glyph_translation, Modules for the Redisplay Mechanism, Redisplay Piece by Piece, The Redisplay Mechanism +@section pixel_to_glyph_translation +@cindex pixel_to_glyph_translation +@cindex events, mouse motion +@cindex mouse motion events + +The data structures described in @ref{Redisplay Piece by Piece} are +also the basis for mapping native window system coordinates to +higher-level objects, such as a toolbar button, a modeline character, +a glyph, or a text character. @code{pixel_to_glyph_translation} does +the bulk of this translation, with some further tweaking done by the +functions in @file{events.c}. + +@code{pixel_to_glyph_translation} is called very frequently when +XEmacs is processing mouse-motion events. To improve performance, +@code{pixel_to_glyph_translation} caches the most recently returned +values. The cache includes the pixel coordinate boundaries for which +the cached results are valid. So if the next event is within those +boundaries, @code{pixel_to_glyph_translation} returns the cached +results (fast path). Otherwise, @code{pixel_to_glyph_translation} +walks through the redisplay data structures, then updates the cache +with the new results (slow path). + +@node Modules for the Redisplay Mechanism, Modules for other Display-Related Lisp Objects, pixel_to_glyph_translation, The Redisplay Mechanism @section Modules for the Redisplay Mechanism @cindex modules for the redisplay mechanism @cindex redisplay mechanism, modules for the
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/man/texinfo/texinfo.texi Fri Feb 27 17:48:44 2015 +0000 @@ -0,0 +1,24491 @@ +\input texinfo.tex @c -*-texinfo-*- +@c $Id$ + +@c Everything between the start/end of header lines will be passed by +@c XEmacs's {texinfo,makeinfo}-format region commands. See the `start of +@c header' node for more info. +@c %**start of header +@c Synced up with: Texinfo 5.2 of 26 Sep 2013. +@c Synced by: Jerry James, 11 Feb 2014. + +@c makeinfo and texinfo.tex ignore all text before @setfilename. +@setfilename texinfo.info + +@c Automake automatically updates version.texi to @set VERSION and +@c @set UPDATED to appropriate values. +@include version.texi +@c XEmacs: @settitle Texinfo @value{edition} +@settitle GNU Texinfo @value{VERSION} + +@c Define a new index for command-line options. +@defcodeindex op + +@c Put everything except function (command, in this case) names in one +@c index (arbitrarily chosen to be the concept index). +@syncodeindex op cp +@syncodeindex vr cp +@syncodeindex pg cp + +@paragraphindent 2 +@c finalout + +@comment %**end of header + +@copying +This manual is for GNU Texinfo (version @value{VERSION}, @value{UPDATED}), +a documentation system that can produce both online information and a +printed manual from a single source using semantic markup. + +Copyright @copyright{} 1988, 1990, 1991, 1992, 1993, 1995, 1996, 1997, +1998, 1999, 2001, 2001, 2003, 2004, 2005, 2006, 2007, 2008, 2009, +2010, 2011, 2012, 2013 Free Software Foundation, Inc. + +@quotation +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.'' +@end quotation +@end copying + +@dircategory Texinfo documentation system +@direntry +* 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. +@end direntry + +@c Before release, run C-u C-c C-u C-a (texinfo-all-menus-update with a +@c prefix arg). This updates the node pointers, which texinfmt.el needs. + +@c Set smallbook if printing in smallbook format so the example of the +@c smallbook font is actually written using smallbook; in bigbook, a kludge +@c is used for TeX output. Do this through the -t option to texi2dvi, +@c so this same source can be used for other paper sizes as well. +@c smallbook +@c set smallbook +@c @@clear smallbook + +@c If you like blank pages, add through texi2dvi -t. +@c setchapternewpage odd + + +@shorttitlepage GNU Texinfo + +@titlepage +@title Texinfo +@subtitle The GNU Documentation Format +@subtitle for Texinfo version @value{VERSION}, @value{UPDATED} + +@author Robert J. Chassell +@author Richard M. Stallman + +@c Include the Distribution inside the titlepage so +@c that headings are turned off. + +@page +@vskip 0pt plus 1filll +@insertcopying + +@sp 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. +@c ISBN 1-882114-65-5 is for version 3.12, March 1998. +@c ISBN 1-882114-64-7 is for edition 2.24 of November 1996. +@c ISBN 1-882114-63-9 is for edition 2.20 of 28 February 1995. + +@sp 1 +Cover art by Etienne Suvasa. +@end titlepage + + +@summarycontents +@contents + + +@ifnottex +@node Top +@top 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. +@end ifnottex + +@menu +* Copying Conditions:: Your rights. +* Overview:: Texinfo in brief. +* Texinfo Mode:: Using the XEmacs 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. +@c * 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. + +@detailmenu + --- 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. +* XEmacs Editing:: Texinfo mode adds to XEmacs' 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. + +@code{@@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{@@small@dots{}}:: 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. + +@code{@@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 @@ @{@} , \ # +* 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 @@ @{@} , \ # + +* Inserting an Atsign:: @code{@@@@}, @code{@@atchar@{@}}. +* Inserting Braces:: @code{@@@{ @@@}}, @code{@@l rbracechar@{@}}. +* Inserting a Comma:: , and @code{@@comma@{@}}. +* Inserting a Backslash:: \ and @code{@@backslashchar@{@}}. +* Inserting a Hashsign:: # and @code{@@hashchar@{@}}. + +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. + +@code{@@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 XEmacs:: How to format and print from an XEmacs shell. +* Texinfo Mode Printing:: How to format and print in Texinfo mode. +* Compile-Command:: How to print using XEmacs'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{}. + +@code{texi2any}: 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 XEmacs:: How to run @code{makeinfo} from XEmacs. +* @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 XEmacs 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. +@end detailmenu +@end menu + +@c Reward readers for getting to the end of the menu :). +@c Contributed by Arnold Robbins. +@quotation +Documentation is like sex: when it is good, it is very, very good; and +when it is bad, it is better than nothing. +---Dick Brandon +@end quotation + + +@node Copying Conditions +@unnumbered Texinfo Copying Conditions +@cindex Copying conditions +@cindex Conditions for copying Texinfo +@cindex Free software +@cindex 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}). + + +@node Overview +@chapter Overview of Texinfo +@cindex Overview of Texinfo +@cindex Texinfo overview + +@dfn{Texinfo} 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. + +@cindex 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. + +@cindex 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. + +@cindex Pronounciation of Texinfo +@cindex 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 + +@menu +* 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. +@end menu + + +@node Reporting Bugs +@section Reporting Bugs + +@cindex Bugs, reporting +@cindex Suggestions for Texinfo, making +@cindex 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}. + +@cindex Checklist for bug reports +For bug reports, please include enough information for the maintainers +to reproduce the problem. Generally speaking, that means: + +@itemize @bullet +@item The version number of Texinfo and the program(s) or manual(s) involved. +@item The contents of any input files necessary to reproduce the bug. +@item Precisely how you ran any program(s) involved. +@item A description of the problem and samples of any erroneous output. +@item Hardware and operating system names and versions. +@item Anything else that you think would be helpful. +@end itemize + +When in doubt whether something is needed or not, include it. It's +better to include too much than to leave out something important. + +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.) + +@cindex Patches, contributing +Patches are most welcome; if possible, please make them with +@samp{@w{diff -c}} (@pxref{Top,,, diff, Comparing and Merging Files}) +and include @file{ChangeLog} entries (@pxref{Change Log,,, xemacs, +XEmacs User's Manual}), and follow the existing coding style. + + +@node Using Texinfo +@section Using Texinfo + +@cindex Using Texinfo in general +@cindex Texinfo, introduction to +@cindex Introduction to Texinfo + +Using Texinfo, you can create a printed document (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. + +@TeX{} 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. + +@cindex 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 +XEmacs 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}. + + +@node Output Formats +@section Output Formats +@cindex Output formats +@cindex Back-end output formats + +Here is a brief overview of the output formats currently supported by +Texinfo. + +@table @asis +@item Info +@cindex 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 XEmacs Info subsystem +(@pxref{Top,,Getting Started,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}. + +@item Plain text +@cindex Plain text output, overview +(Generated via @command{makeinfo --plaintext}.) This is almost the +same as Info output with the navigational control characters are +omitted. + +@item HTML +@cindex HTML output, overview +@cindex W3 consortium +@cindex Mozilla +@cindex Lynx +@cindex XEmacs-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 XEmacs-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 +@uref{http://www.w3.org/MarkUp/}. @xref{Generating HTML}. + +@item DVI +@cindex DVI output, overview +@pindex dvips +@pindex 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{}, +Con@TeX{}t, etc.) + +@item PostScript +@cindex 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 +@command{dvips} program to convert @TeX{}'s DVI output to PostScript. +@xref{Top,,, dvips, Dvips}. + +@item PDF +@cindex PDF output, overview +@cindex 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; +@uref{http://en.wikipedia.org/wiki/Portable_Document_Format} and +@uref{http://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 +@uref{http://tug.org/applications/pdftex}. @xref{PDF Output}. + +@item Docbook +@cindex Docbook output, overview +@cindex XML Docbook output, overview +(Generated via @command{makeinfo --docbook}.) This is an XML-based +format developed some years ago, primarily for technical +documentation. It therefore bears some resemblance, in broad +outline, to Texinfo. See @uref{http://www.docbook.org}. Various +converters from Docbook @emph{to} Texinfo have also been developed; +see the Texinfo web pages. + +@item XML +@cindex XML Texinfo output, overview +@cindex Texinfo XML output, overview +@cindex DTD, for Texinfo XML +@pindex texinfo.dtd +@pindex txixml2texi +(Generated via @command{makeinfo --xml}.) XML is a generic syntax +specification usable for any sort of content (a reference is at +@uref{http://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 +@file{txixml2texi} to do that backward transformation. +@end table + + +@node Adding Output Formats +@section Adding Output Formats +@cindex 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. + +@cindex 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. + +@pindex help2man +@cindex O'Dea, Brendan +As an alternative way to support man pages, you may find the program +@command{help2man} 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 +@uref{http://www.gnu.org/software/help2man}. + +@cindex Output formats, supporting more +@cindex SGML-tools output format +If you are a programmer and would like to contribute to the GNU +project by implementing additional output formats for Texinfo, that +would be excellent. 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 +@file{tp/Texinfo/Convert/Converter.pm} is a good place to start. +@xref{Generic Translator @t{texi2any}}. + +Another viable approach is use the Texinfo XML output from +@command{texi2any} as your input. This XML is an essentially complete +representation of the input, but without the Texinfo syntax and option +peculiarities, as described above. + +@cindex 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. + + +@node Texinfo Document Structure +@section Texinfo Document Structure +@cindex Texinfo document structure +@cindex Document structure, of Texinfo +@cindex Structure, of Texinfo documents +@cindex Double structure, of Texinfo documents + +@anchor{Two Paths}@c node name +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. + + +@node Info Files +@section Info Files +@cindex 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; +@pxref{Generic 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. + +@cindex 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 +XEmacs/W3, for example: +@example +info:xemacs#Dissociated%20Press +info:///usr/info/xemacs#Dissociated%20Press +info://localhost/usr/info/xemacs#Dissociated%20Press +@end example + +The @command{info} program itself does not follow URIs of any kind. + + +@node Printed Books +@section Printed Books +@cindex Printed book and manual characteristics +@cindex Manual characteristics, printed +@cindex Book characteristics, printed +@cindex Texinfo printed book characteristics +@cindex Characteristics, printed books or manuals + +@cindex Knuth, Donald +A Texinfo file can be formatted and typeset as a printed book or +manual. To do this, you need @TeX{}, a sophisticated typesetting +program written by Donald Knuth of Stanford University. + +A Texinfo-based book is similar to any other typeset, printed work: it +can have a title page, copyright page, table of contents, and preface, +as well as chapters, numbered or unnumbered sections and subsections, +page headers, cross references, footnotes, and indices. + +@TeX{} is a general purpose typesetting program. Texinfo provides a +file @file{texinfo.tex} that contains information (definitions or +@dfn{macros}) that @TeX{} uses when it typesets a Texinfo file. +(@file{texinfo.tex} tells @TeX{} how to convert the Texinfo @@-commands +to @TeX{} commands, which @TeX{} can then process to create the typeset +document.) @file{texinfo.tex} contains the specifications for printing +a document. You can get the latest version of @file{texinfo.tex} from +the Texinfo home page, @uref{http://www.gnu.org/software/texinfo/}. + +In the United States, documents are most often printed on 8.5 inch by +11 inch pages (216@dmn{mm} by 280@dmn{mm}); this is the default size. +But you can also print for 7 inch by 9.25 inch pages (178@dmn{mm} by +235@dmn{mm}, the @code{@@smallbook} size; or on A4 or A5 size paper +(@code{@@afourpaper}, @code{@@afivepaper}). +@xref{@t{@@smallbook}}, and @ref{A4 Paper}. + +@cindex Literate programming +@TeX{} is freely distributable. It is written in a superset of Pascal +for literate programming called WEB and can be compiled either in +Pascal or (by using a conversion program that comes with the @TeX{} +distribution) in C. + +@TeX{} is very powerful and has a great many features. Because a +Texinfo file must be able to present information both on a +character-only terminal in Info form and in a typeset book, the +formatting commands that Texinfo supports are necessarily limited. + +@xref{Obtaining @TeX{}}, for information on acquiring @TeX{}. It is +not part of the Texinfo distribution. + + +@node Formatting Commands +@section @@-commands +@cindex @@-commands +@cindex Formatting commands + +In a Texinfo file, the commands you write to describe the contents of +the manual are preceded by an @samp{@@} character; they are called +@dfn{@@-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 arguments@footnote{The word +@dfn{argument} comes from the way it is used in mathematics and does not +refer to a dispute between two people; it refers to the information +presented to the command. According to the @cite{Oxford English +Dictionary}, the word derives from the Latin for @dfn{to make clear, +prove}; thus it came to mean `the evidence offered as proof', which is +to say, `the information offered', which led to its mathematical +meaning. In its other thread of derivation, the word came to mean `to +assert in a manner against which others may make counter assertions', +which led to the meaning of `argument' as a dispute.} they take, you +need to write @@-commands on lines of their own or as part of +sentences: + +@itemize @bullet +@item +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). + +@item +Some commands can appear anywhere, generally within a sentence, and +are followed by empty braces, such as @code{@@dots@{@}} (which creates +an ellipsis @dots{}). + +@item +Some commands can appear anywhere, generally within a sentence, and +are followed by the argument text in braces, such as +@code{@@code@{a+1@}} (which marks text as being code, @code{a+1} being +the argument in this case). + +@item +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}. +@end itemize + +@noindent +@cindex 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. + + +@node Conventions +@section General Syntactic Conventions +@cindex General syntactic conventions +@cindex Syntactic conventions +@cindex Conventions, syntactic +@cindex Characters, basic input + +This section describes the general conventions used in all Texinfo documents. + +@itemize @bullet +@item +@cindex Source files, characters used +All printable ASCII characters except @samp{@@}, @samp{@{} and +@samp{@}} can appear in a Texinfo file and stand for themselves. +@samp{@@} is the escape character which introduces commands, while +@samp{@{} and @samp{@}} 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{@@@@}, +@samp{@@@{}, and @samp{@@@}}. + +@item +Texinfo supports the usual quotation marks used in English and in +other languages; see @ref{Inserting Quotation Marks}. + +@item +@cindex Multiple dashes in source +@cindex Dashes in source +@cindex Hyphens in source, two or three in a row +@cindex Em dash, producing +@cindex 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 +@dfn{en 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}. + +@item +@cindex Form feed characters +@cindex @kbd{CTRL-l} +Form feed (@kbd{CTRL-l}) characters in the input are handled as +follows: + +@table @asis +@item PDF/DVI +In normal text, treated as ending any open paragraph; essentially +ignored between paragraphs. + +@item 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). + +@item HTML +Written as a numeric entity except contexts where spaces are ignored; +for example, in @samp{@@footnote@{ ^L foo@}}, the form feed is +ignored. + +@item XML +Keep them everywhere; in attributes, escaped as @samp{\f}; also, +@samp{\} is escaped as @samp{\\} and newline as @samp{\n}. + +@item Docbook +Completely removed, as they are not allowed. +@end table + +As you can see, because of these differing requirements of the output +formats, it's not possible to use form feeds completely portably. + +@item +@cindex Tabs; don't use! +@strong{Caution:} Last, do not use tab characters in a Texinfo file! +(Except perhaps in verbatim modes.) @TeX{} uses variable-width fonts, +which means that it is impractical at best to define a tab to work in +all circumstances. Consequently, @TeX{} treats tabs like single +spaces, and that is not what they look like in the source. +Furthermore, @code{makeinfo} does nothing special with tabs, and thus +a tab character in your input file will usually have a different +appearance in the output. + +@noindent +To avoid this problem, Texinfo mode in XEmacs inserts +multiple spaces when you press the @key{TAB} key. Also, you can run +@code{untabify} in XEmacs to convert tabs in a region to multiple +spaces, or use the @code{unexpand} command from the shell. +@end itemize + + +@node Comments +@section Comments + +@cindex Comments +@findex comment +@findex 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 +@code{@@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. + +@findex DEL @r{(comment character)} +@cindex 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. + +@cindex Ignored text +@cindex Unprocessed text +@findex 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}.) + + +@node Minimum +@section What a Texinfo File Must Have +@cindex Minimal Texinfo file (requirements) +@cindex Must have in Texinfo file +@cindex Required in Texinfo file +@cindex Texinfo file minimum + +By convention, the name of a Texinfo file ends with (in order of +preference) one of the extensions @file{.texinfo}, @file{.texi}, +@file{.txi}, 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: + +@example +@group +\input texinfo +@@setfilename @var{info-file-name} +@@settitle @var{name-of-manual} +@end group +@end example + +@noindent +The contents of the file follow this beginning, and then you +@emph{must} end the Texinfo source with a line like this: + +@example +@@bye +@end example + +@findex \input @r{(raw @TeX{} startup)} +@noindent +Here's an explanation: + +@itemize @bullet +@item +The @samp{\input texinfo} line tells @TeX{} to use the +@file{texinfo.tex} file, which tells @TeX{} how to translate the Texinfo +@@-commands into @TeX{} typesetting commands. (Note the use of the +backslash, @samp{\}; this is correct for @TeX{}.) + +@item +The @code{@@setfilename} line provides a name for the Info file and +tells @TeX{} to open auxiliary files. @strong{All text before +@code{@@setfilename} is ignored!} + +@item +The @code{@@settitle} line specifies a title for the page headers (or +footers) of the printed manual, and the default title and document +description for the @samp{<head>} in HTML@. Strictly speaking, +@code{@@settitle} is optional---if you don't mind your document being +titled `Untitled'. + +@item +The @code{@@bye} line at the end of the file on a line of its own tells +the formatters that the file is ended and to stop formatting. +@end itemize + +If you use XEmacs, 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: + +@example +@group +\input texinfo @@c -*-texinfo-*- +@@c %**start of header +@@setfilename @var{info-file-name} +@@settitle @var{name-of-manual} +@@c %**end of header +@end group +@end example + +@noindent +In the first line, @samp{-*-texinfo-*-} causes XEmacs to switch into +Texinfo mode when you edit the file. + +The @code{@@c ...header} lines above which surround the +@code{@@setfilename} and @code{@@settitle} lines allow you to process, +within XEmacs, 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. + + +@node Six Parts +@section 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. + +@table @r +@item 1. Header +The @dfn{Header} names the file, tells @TeX{} which definitions file to +use, and other such housekeeping tasks. + +@item 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. + +@item 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 +@code{@@titlepage} and @code{@@end titlepage} commands. The title and +copyright page appear only in the printed manual. + +@item 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. + +@item 5. Body +The @dfn{Body} of the document is typically structured like a +traditional book or encyclopedia, but it may be free form. + +@item 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. +@end table + + +@node Short Sample +@section A Short Sample Texinfo File +@cindex 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 +@samp{\input 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. + +@xref{Beginning 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 +@ref{Short Sample Texinfo File}. + +@subheading Part 1: Header + +@noindent +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. + +@example +@group +\input texinfo @@c -*-texinfo-*- +@@c %**start of header +@@setfilename sample.info +@@settitle Sample Manual 1.0 +@@c %**end of header +@end group +@end example + +@subheading Part 2: Summary Description and Copyright + +@noindent +A real manual includes more text here, according to the license under +which it is distributed. @xref{GNU Sample Texts}. + +@example +@group +@@copying +This is a short example of a complete Texinfo file, version 1.0. + +Copyright @@copyright@{@} 2013 Free Software Foundation, Inc. +@@end copying +@end group +@end example + +@subheading Part 3: Titlepage, Contents, Copyright + +@noindent +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 +@code{@@contents} command generates a table of contents. + +@example +@group +@@titlepage +@@title Sample Title +@end group + +@group +@@c The following two commands start the copyright page. +@@page +@@vskip 0pt plus 1filll +@@insertcopying +@@end titlepage +@end group + +@@c Output the table of contents at the beginning. +@@contents +@end example + +@subheading Part 4: `Top' Node and Master Menu + +@noindent +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. + +@example +@@ifnottex +@@node Top +@@top Short Sample + +This is a short sample Texinfo file. +@@end ifnottex + +@group +@@menu +* First Chapter:: The first chapter is the + only chapter in this sample. +* Index:: Complete index. +@@end menu +@end group +@end example + + +@subheading Part 5: The Body of the Document + +@noindent +The body segment contains all the text of the document, but not the +indices or table of contents. This example illustrates a node and a +chapter containing an enumerated list. + +@example +@group +@@node First Chapter +@@chapter First Chapter + +@@cindex chapter, first +@end group + +@group +This is the first chapter. +@@cindex index entry, another +@end group + +@group +Here is a numbered list. + +@@enumerate +@@item +This is the first item. + +@@item +This is the second item. +@@end enumerate +@end group +@end example + + +@subheading Part 6: The End of the Document + +@noindent +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. + +@example +@group +@@node Index +@@unnumbered Index +@end group + +@group +@@printindex cp + +@@bye +@end group +@end example + + +@subheading Some Results + +Here is what the contents of the first chapter of the sample look like: + +@sp 1 +@need 700 +@quotation +This is the first chapter. + +Here is a numbered list. + +@enumerate +@item +This is the first item. + +@item +This is the second item. +@end enumerate +@end quotation + + +@node History +@section History + +@cindex Stallman, Richard M. +@cindex Chassell, Robert J. +@cindex Fox, Brian +@cindex Berry, Karl +Richard M. Stallman invented the Texinfo format, wrote the initial +processors, and created Edition 1.0 of this manual. Robert@tie{}J. +Chassell greatly revised and extended the manual, starting with +Edition 1.1. Brian Fox was responsible for the standalone Texinfo +distribution until version 3.8, and originally wrote the standalone +@command{makeinfo} and @command{info} programs. Karl Berry has +continued maintenance since Texinfo 3.8 (manual edition 2.22). + +@cindex Pinard, Fran@,{c}ois +@cindex Schwab, Andreas +@cindex Weinberg, Zack +@cindex Weisshaus, Melissa +@cindex Zaretskii, Eli +@cindex 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 David@tie{}D. Zuhn, +tirelessly recorded and reported mistakes and obscurities. Zack +Weinberg did the impossible by implementing the macro syntax in +@file{texinfo.tex}. 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 +@file{ChangeLog} file. Our mistakes are our own. + +@cindex History of Texinfo +@cindex Texinfo history +@subheading Beginnings + +@cindex Scribe +@cindex 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. + +@cindex Bolio +@cindex Bo@TeX{} +Meanwhile, people at MIT developed another, not too dissimilar format +called Bolio. This then was converted to using @TeX{} as its typesetting +language: Bo@TeX{}. The earliest Bo@TeX{} version seems to have been +0.02 on October 31, 1984. + +Bo@TeX{} could only be used as a markup language for documents to be +printed, not for online documents. Richard Stallman (RMS) worked on +both Bolio and Bo@TeX{}. He also developed a nifty on-line help format +called Info, and then combined Bo@TeX{} and Info to create Texinfo, a +mark up language for text that is intended to be read both 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 +@code{texinfo-format-buffer} and other functions. In the early 1990s, +Brian Fox reimplemented the conversion program in C, now called +@command{makeinfo}. + +@subheading Reimplementing in Perl + +@cindex Cons, Lionel +@cindex 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 +@command{texi2html}, 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 +@command{texi2html} code. That implementation, however, was abandoned +in favor of the current program, which parses the Texinfo input into a +tree for processing. It still supports nearly all the features of +@command{texi2html}. + +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: + +@itemize @bullet +@item HTML customization. Many GNU and other free software packages +had been happily using the HTML customization features in +@command{texi2html} 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. + +@item 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. + +@item 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: + +@item 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. +@end itemize + +@xref{Reference Implementation}, for more on the rationale for and +role of @command{texi2any}. + + +@node Texinfo Mode +@chapter Using Texinfo Mode +@cindex Texinfo mode +@cindex Mode, using Texinfo +@cindex XEmacs +@cindex 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, XEmacs +comes with a special mode, called Texinfo mode, that provides XEmacs +commands and tools to help ease your work. + +This chapter describes features of XEmacs' 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. + +@menu +* Texinfo Mode Overview:: How Texinfo mode can help you. +* XEmacs Editing:: Texinfo mode adds to XEmacs' 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. +@end menu + +@node Texinfo Mode Overview +@section Texinfo Mode Overview + +Texinfo mode provides special features for working with Texinfo files. +You can: + +@itemize @bullet +@item +Insert frequently used @@-commands. + +@item +Automatically create @code{@@node} lines. + +@item +Show the structure of a Texinfo source file. + +@item +Automatically create or update the `Next', +`Previous', and `Up' pointers of a node. + +@item +Automatically create or update menus. + +@item +Automatically create a master menu. + +@item +Format a part or all of a file for Info. + +@item +Typeset and print part or all of a file. +@end itemize + +Perhaps the two most helpful features are those for inserting frequently +used @@-commands and for creating node pointers and menus. + +@node XEmacs Editing +@section The Usual XEmacs 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 XEmacs' 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 +@kbd{C-x ]} (@code{forward-page}) and @kbd{C-x [} +(@code{backward-page}) commands and narrow to a chapter with the +@kbd{C-x n p} (@code{narrow-to-page}) command. (@xref{Pages, , ,xemacs, +XEmacs User's 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 +@file{.texinfo}, @file{.texi}, @file{.txi}, or @file{.tex}. A longer +extension is preferred, since it is explicit, but a shorter extension +may be necessary for operating systems that limit the length of file +names. XEmacs automatically enters Texinfo mode when you visit a +file with a @file{.texinfo}, @file{.texi} or @file{.txi} +extension. Also, XEmacs 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 XEmacs 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. + +@node Inserting +@section Inserting Frequently Used Commands +@cindex Inserting frequently used commands +@cindex Frequently used commands, inserting +@cindex 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: + +@table @kbd +@item C-c C-c c +@itemx M-x texinfo-insert-@@code +@findex texinfo-insert-@@code +Insert @code{@@code@{@}} and put the +cursor between the braces. + +@item C-c C-c d +@itemx M-x texinfo-insert-@@dfn +@findex texinfo-insert-@@dfn +Insert @code{@@dfn@{@}} and put the +cursor between the braces. + +@item C-c C-c e +@itemx M-x texinfo-insert-@@end +@findex 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.) + +@item C-c C-c i +@itemx M-x texinfo-insert-@@item +@findex texinfo-insert-@@item +Insert @code{@@item} and put the +cursor at the beginning of the next line. + +@item C-c C-c k +@itemx M-x texinfo-insert-@@kbd +@findex texinfo-insert-@@kbd +Insert @code{@@kbd@{@}} and put the +cursor between the braces. + +@item C-c C-c n +@itemx M-x texinfo-insert-@@node +@findex 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}. + +@item C-c C-c o +@itemx M-x texinfo-insert-@@noindent +@findex texinfo-insert-@@noindent +Insert @code{@@noindent} and put the +cursor at the beginning of the next line. + +@item C-c C-c s +@itemx M-x texinfo-insert-@@samp +@findex texinfo-insert-@@samp +Insert @code{@@samp@{@}} and put the +cursor between the braces. + +@item C-c C-c t +@itemx M-x texinfo-insert-@@table +@findex texinfo-insert-@@table +Insert @code{@@table} followed by a @key{SPC} +and leave the cursor after the @key{SPC}. + +@item C-c C-c v +@itemx M-x texinfo-insert-@@var +@findex texinfo-insert-@@var +Insert @code{@@var@{@}} and put the +cursor between the braces. + +@item C-c C-c x +@itemx M-x texinfo-insert-@@example +@findex texinfo-insert-@@example +Insert @code{@@example} and put the +cursor at the beginning of the next line. + +@c M-@{ was the binding for texinfo-insert-braces; +@c in Emacs 19, backward-paragraph will take this binding. +@item C-c C-c @{ +@itemx M-x texinfo-insert-braces +@findex texinfo-insert-braces +Insert @code{@{@}} and put the cursor between the braces. + +@item C-c @} +@itemx C-c ] +@itemx M-x up-list +@findex 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}.) +@end table + +To put a command such as @w{@code{@@code@{@dots{}@}}} around an +@emph{existing} word, position the cursor in front of the word and type +@kbd{C-u 1 C-c C-c c}. This makes it easy to edit existing plain text. +The value of the prefix argument tells XEmacs how many words following +point to include between braces---@samp{1} 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, XEmacs 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{XEmacs User's +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}. + +@findex texinfo-start-menu-description +@cindex Menu description, start +@cindex Description for menu, start +@kbd{C-c 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. +@xref{Menu 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. + +@node Showing the Structure +@section Showing the Sectioning Structure of a File +@cindex Showing the sectioning structure of a file +@cindex Sectioning structure of a file, showing +@cindex Structure of a file, showing +@cindex Outline of file structure, showing +@cindex Contents-like outline of file structure +@cindex File sectioning structure, showing +@cindex Texinfo file sectioning structure, showing + +You can show the sectioning structure of a Texinfo file by using the +@kbd{C-c C-s} command (@code{texinfo-show-structure}). This command +lists the lines that begin with the @@-commands for @code{@@chapter}, +@code{@@section}, and the like. It constructs what amounts to a table +of contents. These lines are displayed in another buffer called the +@samp{*Occur*} 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. + +@table @kbd +@item C-c C-s +@itemx M-x texinfo-show-structure +@findex texinfo-show-structure +Show the @code{@@chapter}, @code{@@section}, and such lines of a +Texinfo file. + +@item C-c C-c +@itemx M-x occur-mode-goto-occurrence +@findex occur-mode-goto-occurrence +Go to the line in the Texinfo file corresponding to the line under the +cursor in the @file{*Occur*} buffer. +@end table + +If you call @code{texinfo-show-structure} with a prefix argument by +typing @w{@kbd{C-u C-c C-s}}, it will list not only those lines with the +@@-commands for @code{@@chapter}, @code{@@section}, and the like, but +also the @code{@@node} lines. 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 +@kbd{C-x n n} (@code{narrow-to-region}) command and +@code{texinfo-show-structure} will work on only that region. To see +the whole buffer again, use @w{@kbd{C-x n w}} (@code{widen}). +(@xref{Narrowing, , , xemacs, XEmacs User's Manual}, for more +information about the narrowing commands.) + +@vindex page-delimiter +@cindex 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 +@kbd{C-x n p} (@code{narrow-to-page}) command to narrow to a chapter. +@xref{Pages, , , xemacs, XEmacs User's Manual}, for more information +about the page commands. + + +@node Updating Nodes and Menus +@section Updating Nodes and Menus + +@cindex Updating nodes and menus +@cindex Create nodes, menus automatically +@cindex Insert nodes, menus automatically +@cindex 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. + +@menu +* 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. +@end menu + +@node Updating Commands +@subsection The Updating Commands + +You can use the updating commands to: + +@itemize @bullet +@item +insert or update the `Next', `Previous', and `Up' pointers of a node, + +@item +insert or update the menu for a section, and + +@item +create a master menu for a Texinfo source file. +@end 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 +@code{@@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: + +@table @kbd +@item C-c C-u m +@itemx M-x texinfo-master-menu +@findex 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: + +@example +C-u M-x texinfo-master-menu +@exdent or +C-u C-c C-u m +@end example + +@noindent +This updates all the nodes and menus completely and all at once. +@end table + +The other major updating commands do smaller jobs and are designed for +the person who updates nodes and menus as he or she writes a Texinfo +file. + +@need 1000 +The commands are: + +@table @kbd +@item C-c C-u C-n +@itemx M-x texinfo-update-node +@findex 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 +@code{@@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). + +@item C-c C-u C-m +@itemx M-x texinfo-make-menu +@findex 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. + +@item C-c C-u C-e +@itemx M-x texinfo-every-node-update +@findex texinfo-every-node-update +Insert or update the `Next', `Previous', and `Up' pointers for every +node in the buffer. + +@item C-c C-u C-a +@itemx M-x texinfo-all-menus-update +@findex 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: + +@example +C-u C-c C-u C-a +@exdent or +C-u M-x texinfo-all-menus-update +@end example + +@noindent +This updates all the nodes and menus. +@end 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,,, +xemacs, XEmacs User's Manual}) or with the @kbd{M-x set-variable} +command (@pxref{Examining, , Examining and Setting Variables, xemacs, +XEmacs User's Manual}). + +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.) + +@node Updating Requirements +@subsection Updating Requirements +@cindex Updating requirements +@cindex 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 +@code{@@chapter}, @code{@@section}, or +@code{@@unnumberedsubsec}. + +Each @code{@@node} line/structuring-command line combination +must look either like this: + +@example +@group +@@node Comments, Minimum, Conventions, Overview +@@comment node-name, next, previous, up +@@section Comments +@end group +@end example + +or like this (without the @code{@@comment} line): + +@example +@group +@@node Comments, Minimum, Conventions, Overview +@@section Comments +@end group +@end example + +or like this (without the explicit node pointers): + +@example +@group +@@node Comments +@@section Comments +@end group +@end example + +@noindent +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 +@code{@@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 +@code{makeinfo}.) However, both @code{makeinfo} and the +@code{texinfo-format-@dots{}} commands require that you insert menus in +the file. + + +@node Other Updating Commands +@subsection Other Updating Commands + +In addition to the five major updating commands, Texinfo mode +possesses several less frequently used updating commands: + +@table @kbd +@item M-x texinfo-insert-node-lines +@findex texinfo-insert-node-lines +Insert @code{@@node} lines before the @code{@@chapter}, +@code{@@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 +command @code{texinfo-insert-node-lines} not only inserts +@code{@@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 +@code{@@node} lines and titles throughout: + +@example +C-x h C-u M-x texinfo-insert-node-lines +@end example + +This command inserts titles as node names in @code{@@node} lines; the +@code{texinfo-start-menu-description} command (@pxref{Inserting, +Inserting Frequently Used Commands}) inserts titles as descriptions in +menu entries, a different action. However, in both cases, you need to +edit the inserted text. + +@item M-x texinfo-multiple-files-update +@findex texinfo-multiple-files-update @r{(in brief)} +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. +@xref{@t{texinfo-multiple-files-update}}. + +@item M-x texinfo-indent-menu-description +@findex 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. + +@item M-x texinfo-sequential-node-update +@findex 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. +@end table + +@node Info Formatting +@section Formatting for Info +@cindex Formatting for Info +@cindex Running an Info formatter +@cindex 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 +@code{makeinfo-region} command to format a region: + +@table @kbd +@findex texinfo-format-region +@item C-c C-e C-r +@itemx M-x texinfo-format-region +@itemx C-c C-m C-r +@itemx M-x makeinfo-region +Format the current region for Info. +@end table + +You can use either the @code{texinfo-format-buffer} or the +@code{makeinfo-buffer} command to format a whole buffer: + +@table @kbd +@findex texinfo-format-buffer +@item C-c C-e C-b +@itemx M-x texinfo-format-buffer +@itemx C-c C-m C-b +@itemx M-x makeinfo-buffer +Format the current buffer for Info. +@end table + +@need 1000 +For example, after writing a Texinfo file, you can type the following: + +@example +C-u C-c C-u m +@exdent or +C-u M-x texinfo-master-menu +@end example + +@noindent +This updates all the nodes and menus. Then type the following to create +an Info file: + +@example +C-c C-m C-b +@exdent or +M-x makeinfo-buffer +@end example + +For @TeX{} or the Info formatting commands to work, the file @emph{must} +include a line that has @code{@@setfilename} in its header. + +@xref{Creating an Info File}, for details about Info formatting. + +@node Printing +@comment node-name, next, previous, up +@section Printing +@cindex Formatting for printing +@cindex Printing a region or buffer +@cindex Region formatting and printing +@cindex Buffer formatting and printing +@cindex 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 +@code{tex} 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 +@t{texi2dvi}}). + +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 +@code{texinfo-tex-region} and related commands for this purpose. Use +the @code{texinfo-tex-buffer} command to format all of a +buffer. + +@table @kbd +@item C-c C-t C-b +@itemx M-x texinfo-tex-buffer +@findex 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. + +@item C-c C-t C-r +@itemx M-x texinfo-tex-region +@findex texinfo-tex-region +Run @TeX{} on the region. + +@item C-c C-t C-i +@itemx M-x texinfo-texindex +Run @code{texindex} to sort the indices of a Texinfo file formatted with +@code{texinfo-tex-region}. 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.) + +@item C-c C-t C-p +@itemx M-x texinfo-tex-print +@findex texinfo-tex-print +Print the file (or the part of the file) previously formatted with +@code{texinfo-tex-buffer} or @code{texinfo-tex-region}. +@end 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.) + +@xref{Hardcopy}, for a description of the other @TeX{} related +commands, such as @code{tex-show-print-queue}. + +@node Texinfo Mode Summary +@section 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. + +@subheading 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 +@kbd{C-c C-c} is quick to type.) + +@example +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.} + +@group +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.} +@end group +@end example + +@subheading Show Structure + +The @code{texinfo-show-structure} command is often used within a +narrowed region. + +@example +C-c C-s @r{List all the headings.} +@end example + +@subheading 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. + +@c Probably should use @tables in this section. +@example +@group +C-c C-u m +M-x texinfo-master-menu + @r{Create or update a master menu.} +@end group + +@group +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.} +@end group +@end example + +@subheading 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 +@code{texinfo-every-node-update}. + +@example +C-c C-u C-n @r{Update a node.} +C-c C-u C-e @r{Update every node in the buffer.} +@end example + +@subheading 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 +@kbd{C-a} 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}. + +@example +C-c C-u C-m @r{Make or update a menu.} + +@group +C-c C-u C-a @r{Make or update all} + @r{menus in a buffer.} +@end group + +@group +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.} +@end group +@end example + +@subheading 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 +@code{makeinfo} 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. + +@need 800 +@noindent +Use the @code{texinfo-format@dots{}} commands: + +@example +@group +C-c C-e C-r @r{Format the region.} +C-c C-e C-b @r{Format the buffer.} +@end group +@end example + +@need 750 +@noindent +Use @code{makeinfo}: + +@example +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.} +@end example + +@subheading Typeset and Print + +The @TeX{} typesetting and printing commands are invoked by typing +@kbd{C-c C-t} and then another control command: @kbd{C-r} for +@code{texinfo-tex-region}, @kbd{C-b} for @code{texinfo-tex-buffer}, +and so on. + +@example +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.} +@end example + +@subheading Other Updating Commands + +The remaining updating commands do not have standard keybindings because +they are rarely used. + +@example +@group +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.} +@end group + +@group +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.} +@end group + +@group +M-x texinfo-indent-menu-description + @r{Indent descriptions.} +@end group + +@group +M-x texinfo-sequential-node-update + @r{Insert node pointers in strict sequence.} +@end group +@end example + + +@node Beginning a File +@chapter Beginning a Texinfo File +@cindex Beginning a Texinfo file +@cindex Texinfo file beginning +@cindex 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. + +@cindex Frontmatter, text in +Straight text outside of any command before the Top node should be +avoided. Such text is treated differently in the different output +formats: at the time of writing, it is visible in @TeX{} and HTML, by +default not shown in Info readers, and so on. + +@menu +* Sample Beginning:: A sample beginning for a Texinfo file. +* Texinfo File Header:: The first lines. +* Document Permissions:: Ensuring your manual is free. +* Titlepage & Copyright Page:: Creating the title and copyright pages. +* Contents:: How to create a table of contents. +* The Top Node:: Creating the `Top' node and master menu. +* Global Document Commands:: Affecting formatting throughout. +@end menu + + +@node Sample Beginning +@section Sample Texinfo File Beginning + +@cindex Example beginning of Texinfo file + +The following sample shows what is needed. The elements given here are +explained in more detail in the following sections. Other commands are +often included at the beginning of Texinfo files, but the ones here are +the most critical. + +@xref{GNU Sample Texts}, for the full texts to be used in GNU manuals. + +@example +\input texinfo @@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 @@copyright@{@} @var{years} @var{copyright-owner}. + +@group +@@quotation +Permission is granted to @dots{} +@@end quotation +@@end copying +@end group + +@group +@@titlepage +@@title @var{name-of-manual-when-printed} +@@subtitle @var{subtitle-if-any} +@@subtitle @var{second-subtitle} +@@author @var{author} +@end group + +@group +@@c The following two commands +@@c start the copyright page. +@@page +@@vskip 0pt plus 1filll +@@insertcopying +@end group + +Published by @dots{} +@@end titlepage + +@@c So the toc is printed at the start. +@@contents + +@@ifnottex +@@node Top +@@top @var{title} + +This manual is for @var{program}, version @var{version}. +@@end ifnottex + +@group +@@menu +* First Chapter:: Getting started @dots{} +* Second Chapter:: @dots{} + @dots{} +* Copying:: Your rights and freedoms. +@@end menu +@end group + +@group +@@node First Chapter +@@chapter First Chapter + +@@cindex first chapter +@@cindex chapter, first +@dots{} +@end group +@end example + + +@node Texinfo File Header +@section Texinfo File Header +@cindex Header for Texinfo files +@cindex 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 +@code{@@setfilename} line. + +Also, if you want to format just part of the Texinfo file in XEmacs, +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} (@pxref{@t{@@synindex}}), +for instance, is another command often included in the header. + +Thus, the beginning of a Texinfo file generally looks approximately +like this: + +@example +@group +\input texinfo @@c -*-texinfo-*- +@@c %**start of header +@@setfilename sample.info +@@settitle Sample Manual 1.0 +@@c %**end of header +@end group +@end example + +(@xref{GNU Sample Texts}, for complete sample texts.) + +@menu +* 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. +@end menu + + +@node First Line +@subsection The First Line of a Texinfo File +@cindex First line of a Texinfo file +@cindex Beginning line of a Texinfo file +@cindex 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: + +@example +\input texinfo @@c -*-texinfo-*- +@end example + +@noindent +This line serves two functions: + +@enumerate +@item +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. + +@item +When the file is edited in XEmacs, the @samp{-*-texinfo-*-} mode +specification tells XEmacs to use Texinfo mode. +@end enumerate + + +@node Start of Header +@subsection Start of Header +@cindex Start of header line + +A start-of-header line is a Texinfo comment that looks like this: + +@example +@@c %**start of header +@end 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 +@code{@@settitle} lines and, optionally, with other commands that +globally affect the document formatting, such as @code{@@synindex} or +@code{@@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. @xref{@t{texinfo-format} 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 +@code{tex-end-of-header} XEmacs variables. @xref{Texinfo Mode Printing}. + + +@node @t{@@setfilename} +@subsection @code{@@setfilename}: Set the Output File Name + +@anchor{setfilename}@c old name +@findex setfilename +@cindex Texinfo requires @code{@@setfilename} +@cindex Output file name, required + +The first Texinfo command (that is, after the @code{\input texinfo}) +in a document is generally @code{@@setfilename}: + +@example +@@setfilename @var{info-file-name} +@end example + +This command is required for @TeX{}, and very strongly recommended for +@code{makeinfo}. + +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. + +@cindex Ignored before @code{@@setfilename} +@cindex @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. + +@cindex Length of file names +@cindex File name collision +@cindex 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}, +@samp{-2}, @dots{}, @samp{-10}, @samp{-11}, and so on, to the original +file name. (@xref{Tag and Split Files}.) The subfile name +@file{texinfo.info-10}, 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 +@code{makeinfo} 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. + +@pindex 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 +@file{texinfo.cnf} 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 added---@code{.html} 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}}. + + +@node @t{@@settitle} +@subsection @code{@@settitle}: Set the Document Title + +@anchor{settitle}@c old name +@findex settitle +@cindex Document title, specifying + +A Texinfo file should contain a line that looks like this: + +@example +@@settitle @var{title} +@end 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}. + +@cindex @code{<title>} HTML tag +In the HTML file produced by @command{makeinfo}, @var{title} serves as +the document @samp{<title>}. It also becomes the default document +description in the @samp{<head>} part +(@pxref{@t{@@documentdescription}}). + +When the title page is used in the output, the title in the +@code{@@settitle} command does not affect the title as it appears on +the title page. Thus, the two do not need not to 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}. @xref{@t{@@titlepage}}. + + +@node End of Header +@subsection End of Header +@cindex End of header line + +Follow the header lines with an @w{end-of-header} line, which is a +Texinfo comment that looks like this: + +@example +@@c %**end of header +@end example + +@xref{Start of Header}. + + +@node Document Permissions +@section Document Permissions +@cindex Document Permissions +@cindex 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. + +@anchor{Software Copying Permissions}@c old node name +This section is about the license of the Texinfo document. If the +document is a software manual, the software is typically under a +different license---for GNU and many other free software packages, +software is usually released under the GNU GPL, and manuals are +released under the GNU FDL@. It is helpful to state the license of +the software of the manual, but giving the complete text of the +software license is not necessarily required. + +@menu +* @t{@@copying}:: Declare the document's copying permissions. +* @t{@@insertcopying}:: Where to insert the permissions. +@end menu + + +@node @t{@@copying} +@subsection @code{@@copying}: Declare Copying Permissions + +@anchor{copying}@c old name +@findex 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: + +@example +@@copying +This manual is for @var{program} (version @var{version}, updated +@var{date}), which @dots{} + +Copyright @@copyright@{@} @var{years} @var{copyright-owner}. + +@@quotation +Permission is granted to @dots{} +@@end quotation +@@end copying +@end 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. + +@findex copyright +The @code{@@copyright@{@}} 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: + +@example +Copyright @copyright{} @var{years} @var{copyright-owner}. +@end example + +@cindex 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. + +@cindex 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. + +@cindex Copyright holder for FSF works +@cindex Holder of copyright for FSF works +@cindex 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. + +@xref{Copyright 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. + + +@node @t{@@insertcopying} +@subsection @code{@@insertcopying}: Include Permissions Text + +@anchor{insertcopying}@c old name +@findex insertcopying +@cindex Copying text, including +@cindex Permissions text, including +@cindex Including permissions text + +The @code{@@insertcopying} command is simply written on a line by +itself, like this: + +@example +@@insertcopying +@end 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. + + +@node Titlepage & Copyright Page +@section Title and Copyright Pages + +In hard copy output, the manual's name and author are usually printed on +a title page. Copyright information is usually printed on the back of +the title page. + +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. + +@menu +* @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. +@end menu + + +@node @t{@@titlepage} +@subsection @code{@@titlepage} + +@anchor{titlepage}@c old name +@cindex Title page +@findex titlepage + +Start the material for the title page and following copyright page +with @code{@@titlepage} on a line by itself and end it with +@code{@@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 +@code{@@setcontentsaftertitlepage} command (@pxref{Contents}). + +@findex page@r{, within @code{@@titlepage}} +By using the @code{@@page} command you can force a page break within the +region delineated by the @code{@@titlepage} and @code{@@end titlepage} +commands and thereby create more than one unnumbered page. This is how +the copyright page is produced. (The @code{@@titlepage} command might +perhaps have been better named the @code{@@titleandadditionalpages} +command, but that would have been rather long!) + +When you write a manual about a computer program, you should write the +version of the program to which the manual applies on the title page. +If the manual changes more frequently than the program or is independent +of it, you should also include an edition number@footnote{We have found +that it is helpful to refer to versions of 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 +@ref{The Top Node}.) + +Texinfo provides two main methods for creating a title page. One method +uses the @code{@@titlefont}, @code{@@sp}, and @code{@@center} commands +to generate a title page in which the words on the page are +centered. + +The second method uses the @code{@@title}, @code{@@subtitle}, and +@code{@@author} commands to create a title page with black rules under +the title and author lines and the subtitle text set flush to the +right hand side of the page. With this method, you do not specify any +of the actual formatting of the title page. You specify the text +you want, and Texinfo does the formatting. + +You may use either method, or you may combine them; see the examples in +the sections below. + +@findex shorttitlepage +@cindex Bastard title page +@cindex Title page, bastard +For sufficiently simple documents, and for the bastard title page in +traditional book frontmatter, Texinfo also provides a command +@code{@@shorttitlepage} which takes the rest of the line as the title. +The argument is typeset on a page by itself and followed by a blank +page. + + +@node @t{@@titlefont @@center @@sp} +@subsection @code{@@titlefont}, @code{@@center}, and @code{@@sp} + +@anchor{titlefont center sp}@c old name +@findex titlefont +@findex center +@findex sp @r{(titlepage line spacing)} + +You can use the @code{@@titlefont}, @code{@@sp}, and @code{@@center} +commands to create a title page for a printed document. (This is the +first of the two methods for creating a title page in Texinfo.) + +Use the @code{@@titlefont} command to select a large font suitable for +the title itself. You can use @code{@@titlefont} more than once if you +have an especially long title. + +For HTML output, each @code{@@titlefont} command produces an +@code{<h1>} heading, but the HTML document @code{<title>} is not +affected. For that, you must put an @code{@@settitle} command before +the @code{@@titlefont} command (@pxref{@t{@@settitle}}). + +@need 700 +For example: + +@example +@@titlefont@{Texinfo@} +@end example + +Use the @code{@@center} command at the beginning of a line to center +the remaining text on that line. Thus, + +@example +@@center @@titlefont@{Texinfo@} +@end example + +@noindent +centers the title, which in this example is ``Texinfo'' printed +in the title font. + +Use the @code{@@sp} command to insert vertical space. For example: + +@example +@@sp 2 +@end example + +@noindent +This inserts two blank lines on the printed page. +(@xref{@t{@@sp}}, for more information about the @code{@@sp} +command.) + +A template for this method looks like this: + +@example +@group +@@titlepage +@@sp 10 +@@center @@titlefont@{@var{name-of-manual-when-printed}@} +@@sp 2 +@@center @var{subtitle-if-any} +@@sp 2 +@@center @var{author} +@dots{} +@@end titlepage +@end group +@end example + +The spacing of the example fits an 8.5 by 11 inch manual. + +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. + +@node @t{@@title @@subtitle @@author} +@subsection @code{@@title}, @code{@@subtitle}, and @code{@@author} + +@anchor{title subtitle author}@c old name +@findex title +@findex subtitle +@findex 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 (@pxref{@t{@@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: + +@example +@@title This Long Title@@inlinefmt@{tex,@@*@} Is Broken in @@TeX@{@} +@end 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: + +@example +@@author by Jane Smith and John Doe +@end example + +@noindent +or you can write the names one above each other by using multiple +@code{@@author} commands: + +@example +@group +@@author Jane Smith +@@author John Doe +@end group +@end example + +@need 950 +A template for this method looks like this: + +@example +@group +@@titlepage +@@title @var{name-of-manual-when-printed} +@@subtitle @var{subtitle-if-any} +@@subtitle @var{second-subtitle} +@@author @var{author} +@@page +@dots{} +@@end titlepage +@end group +@end example + + +@node Copyright +@subsection Copyright Page +@cindex Copyright page +@cindex Printed permissions +@cindex 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. + +@findex vskip @r{@TeX{} vertical skip} +@findex filll @r{@TeX{} 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}: + +@example +@@vskip 0pt plus 1filll +@end example + +@noindent +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 +@samp{filll}; this is correct. + +To insert the copyright text itself, write @code{@@insertcopying} +next (@pxref{Document Permissions}): + +@example +@@insertcopying +@end 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: + +@example +@@titlepage +@dots{} +@@page +@@vskip 0pt plus 1filll +@@insertcopying + +Published by @dots{} + +Cover art by @dots{} +@@end titlepage +@end 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: + +@example +@@ifplaintext +@@insertcopying +@@end ifplaintext +@end example + +You could include other title-like information for the plain text +output in the same place. + + + +@node Heading Generation +@subsection Heading Generation + +@anchor{end titlepage}@c old name +@cindex Headings, page, begin to appear +@cindex Titlepage end starts headings +@cindex End titlepage starts headings +@cindex Generating page headings + +Like all @code{@@end} commands (@pxref{Quotations and Examples}), the +@code{@@end titlepage} command must be written at the beginning of a +line by itself, with only one space between the @code{@@end} and the +@code{titlepage}. 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: + +@itemize @bullet +@item +The conventional way is to write an @code{@@setchapternewpage} command +before the title page commands, if required, and then have the +@code{@@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 +@code{@@setchapternewpage} command for single-sided printing +(@pxref{@t{@@setchapternewpage}}). + +@item +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}. @xref{@t{@@headings}}. + +@item +Or, you may specify your own page heading and footing format. +@xref{Headings}. +@end itemize + + +@node Contents +@section Generating a Table of Contents +@cindex Table of contents +@cindex Contents, table of +@cindex Short table of contents +@findex contents +@findex summarycontents +@findex shortcontents + +The @code{@@chapter}, @code{@@section}, and other structuring commands +(@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 +@code{@@summarycontents} command(s). + +@table @code +@item @@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}, +@code{@@chapheading}, and the other @code{@@@dots{}heading} commands +do not appear in the table of contents (@pxref{Structuring Command +Types}). + +@item @@shortcontents +@itemx @@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. +@end 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} (@pxref{@t{@@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. + +@findex setcontentsaftertitlepage +@findex setshortcontentsaftertitlepage +@cindex Contents, after title page +@cindex Table of contents, after title page +However, since many existing Texinfo documents still do have the +@code{@@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 +@code{@@setcontentsaftertitlepage} and/or +@code{@@setshortcontentsaftertitlepage}. The first prints only the +main contents after the @code{@@end titlepage}; the second prints both +the short contents and the main contents. In either case, any +subsequent @code{@@contents} or @code{@@shortcontents} is ignored. + +You need to include the @code{@@set@dots{}contentsaftertitlepage} +commands early in the document (just after @code{@@setfilename}, for +example). We recommend using @command{texi2dvi} (@pxref{Format with +@t{texi2dvi}}) to specify this without altering the source file at +all. For example: + +@example +texi2dvi --texinfo=@@setcontentsaftertitlepage foo.texi +@end example + +An alternative invocation, using @command{texi2any}: + +@example +texi2any --dvi --Xopt --texinfo=@@setcontentsaftertitlepage foo.texi +@end example + + + +@node The Top Node +@section The `Top' Node and Master Menu +@cindex Top node +@cindex 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. + +@findex 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 (@pxref{@t{@@top} Command}). + +The contents of the `Top' node should appear only in the online output; +none of it should appear in printed output, so enclose it between +@code{@@ifnottex} and @code{@@end ifnottex} commands. (@TeX{} does not +print either an @code{@@node} line or a menu; they appear only in Info; +strictly speaking, you are not required to enclose these parts between +@code{@@ifnottex} and @code{@@end ifnottex}, but it is simplest to do +so. @xref{Conditionals, , Conditionally Visible Text}.) + +@menu +* Top Node Example:: +* Master Menu Parts:: +@end menu + + +@node Top Node Example +@subsection Top Node Example + +@cindex Top node example + +Here is an example of a Top node. + +@example +@group +@@ifnottex +@@node Top +@@top Sample Title + +@@insertcopying +@@end ifnottex +@end group + +Additional general information. + +@group +@@menu +* First Chapter:: +* Second Chapter:: +@dots{} +* Index:: +@end group +@@end menu +@end example + + +@node Master Menu Parts +@subsection Parts of a Master Menu +@cindex Master menu +@cindex Menu, master +@cindex 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 +@code{@@end menu} and does not appear in the printed output. + +Generally, a master menu is divided into parts. + +@itemize @bullet +@item +The first part contains the major nodes in the Texinfo file: the nodes +for the chapters, chapter-like sections, and the appendices. + +@item +The second part contains nodes for the indices. + +@item +@findex detailmenu +@cindex Detailed menu +The third and subsequent parts contain a listing of the other, +lower-level nodes, often ordered by chapter. This way, rather than go +through an intermediary menu, an inquirer can go directly to a +particular node when searching for specific information. These menu +items are not required; add them if you think they are a convenience. +If you do use them, put @code{@@detailmenu} before the first one, and +@code{@@end detailmenu} after the last; otherwise, @code{makeinfo} +will get confused. +@end itemize + +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): + +@example +@group +@@menu +* Copying Conditions:: Your rights. +* Overview:: Texinfo in brief. +@dots{} +@end group +@group +* Command and Variable Index:: +* General Index:: +@end group + +@group +@@detailmenu +--- The Detailed Node Listing --- + +Overview of Texinfo + +* Reporting Bugs:: @dots{} +@dots{} +@end group + +@group +Beginning a Texinfo File + +* Sample Beginning:: @dots{} +@dots{} +@@end detailmenu +@@end menu +@end group +@end example + + +@node Global Document Commands +@section Global Document Commands +@cindex Global Document Commands + +Besides the basic commands mentioned in the previous sections, here are +additional commands which affect the document as a whole. They are +generally all given before the Top node, if they are given at all. + +@menu +* @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. +@end menu + + +@node @t{@@documentdescription} +@subsection @code{@@documentdescription}: Summary Text +@anchor{documentdescription}@c old name + +@cindex Document description +@cindex Description of document +@cindex Summary of document +@cindex Abstract of document +@cindex <meta> HTML tag, and document description +@findex documentdescription + +When producing HTML output for a document, @command{makeinfo} writes a +@samp{<meta>} element in the @samp{<head>} to give some idea of the +content of the document. By default, this @dfn{description} is the +title of the document, taken from the @code{@@settitle} command +(@pxref{@t{@@settitle}}). To change this, use the +@code{@@documentdescription} environment, as in: + +@example +@@documentdescription +descriptive text. +@@end documentdescription +@end example + +@noindent +This will produce the following output in the @samp{<head>} of the HTML: + +@example +<meta name=description content="descriptive text."> +@end example + +@code{@@documentdescription} must be specified before the first node of +the document. + + +@node @t{@@setchapternewpage} +@subsection @code{@@setchapternewpage}: Blank Pages Before Chapters + +@anchor{setchapternewpage}@c old name +@findex setchapternewpage +@cindex Starting chapters +@cindex Pages, starting odd + +In an officially bound book, text is usually printed on both sides of +the paper, chapters start on right-hand pages, and right-hand pages have +odd numbers. But in short reports, text often is printed only on one +side of the paper. Also in short reports, chapters sometimes do not +start on new pages, but are printed on the same page as the end of the +preceding chapter, after a small amount of vertical whitespace. + +You can use the @code{@@setchapternewpage} command with various +arguments to specify how @TeX{} should start chapters and whether it +should format headers for printing on one or both sides of the paper +(single-sided or double-sided printing). + +Write the @code{@@setchapternewpage} command at the beginning of a +line followed by its argument. + +For example, you would write the following to cause each chapter to +start on a fresh odd-numbered page: + +@example +@@setchapternewpage odd +@end example + +You can specify one of three alternatives with the +@code{@@setchapternewpage} command: + +@table @asis + +@item @code{@@setchapternewpage off} +Cause @TeX{} to typeset a new chapter on the same page as the last +chapter, after skipping some vertical whitespace. Also, cause @TeX{} to +format page headers for single-sided printing. + +@item @code{@@setchapternewpage on} +Cause @TeX{} to start new chapters on new pages and to format page +headers for single-sided printing. This is the form most often used for +short reports or personal printing. This is the default. + +@item @code{@@setchapternewpage odd} +Cause @TeX{} to start new chapters on new, odd-numbered pages +(right-handed pages) and to typeset for double-sided printing. This is +the form most often used for books and manuals. +@end table + +Texinfo does not have 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. +@xref{@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. + + +@node @t{@@headings} +@subsection The @code{@@headings} Command + +@anchor{headings on off}@c old name +@findex headings + +The @code{@@headings} command is rarely used. It specifies what kind of +page headings and footings to print on each page. Usually, this is +controlled by the @code{@@setchapternewpage} command. You need the +@code{@@headings} command only if the @code{@@setchapternewpage} command +does not do what you want, or if you want to turn off predefined page +headings prior to defining your own. Write an @code{@@headings} command +immediately after the @code{@@end titlepage} command. + +You can use @code{@@headings} as follows: + +@table @code +@item @@headings off +Turn off printing of page headings. + +@item @@headings single +Turn on page headings appropriate for single-sided printing. + +@item @@headings double +Turn on page headings appropriate for double-sided printing. + +@item @@headings singleafter +@itemx @@headings doubleafter +Turn on @code{single} or @code{double} headings, respectively, after the +current page is output. + +@item @@headings on +Turn on page headings: @code{single} if @samp{@@setchapternewpage +on}, @code{double} otherwise. +@end table + +For example, suppose you write @code{@@setchapternewpage off} before the +@code{@@titlepage} command to tell @TeX{} to start a new chapter on the +same page as the end of the last chapter. This command also causes +@TeX{} to typeset page headers for single-sided printing. To cause +@TeX{} to typeset for double sided printing, write @code{@@headings +double} after the @code{@@end titlepage} command. + +You can stop @TeX{} from generating any page headings at all by +writing @code{@@headings off} on a line of its own immediately after the +line containing the @code{@@end titlepage} command, like this: + +@example +@@end titlepage +@@headings off +@end example + +@noindent +The @code{@@headings off} command overrides the @code{@@end titlepage} +command, which would otherwise cause @TeX{} to print page headings. + +You can also specify your own style of page heading and footing. +@xref{Headings, , Page Headings}, for more information. + + +@node @t{@@paragraphindent} +@subsection @code{@@paragraphindent}: Controlling Paragraph Indentation + +@anchor{paragraphindent}@c old name +@findex paragraphindent +@cindex Indenting paragraphs, control of +@cindex Paragraph indentation control + +The Texinfo processors may insert whitespace at the beginning of the +first line of each paragraph, thereby indenting that paragraph. You can +use the @code{@@paragraphindent} command to specify this indentation. +Write an @code{@@paragraphindent} command at the beginning of a line +followed by either @samp{asis} or a number: + +@example +@@paragraphindent @var{indent} +@end example + +The indentation is according to the value of @var{indent}: + +@table @asis +@item @code{asis} +Do not change the existing indentation (not implemented in @TeX{}). + +@item @code{none} +@itemx 0 +Omit all indentation. + +@item @var{n} +Indent by @var{n} space characters in Info output, by @var{n} ems in +@TeX{}. + +@end table + +The default value of @var{indent} is 3. @code{@@paragraphindent} is +ignored for HTML output. + +It is best to write the @code{@@paragraphindent} command before the +end-of-header line at the beginning of a Texinfo file, so the region +formatting commands indent paragraphs as specified. @xref{Start of +Header}. + +A peculiarity of the @code{texinfo-format-buffer} and +@code{texinfo-format-region} commands is that they do not indent (nor +fill) paragraphs that contain @code{@@w} or @code{@@*} commands. + + +@node @t{@@firstparagraphindent} +@subsection @code{@@firstparagraphindent}: Indenting After Headings + +@anchor{firstparagraphindent}@c old name +@findex firstparagraphindent +@cindex First paragraph, suppressing indentation of +@cindex Suppressing first paragraph indentation +@cindex Preventing first paragraph indentation +@cindex Indenting, suppressing of first paragraph +@cindex Headings, indentation after + +As you can see in the present manual, the first paragraph in any +section is not indented by default. Typographically, indentation is a +paragraph separator, which means that it is unnecessary when a new +section begins. This indentation is controlled with the +@code{@@firstparagraphindent} command: + +@example +@@firstparagraphindent @var{word} +@end example + +The first paragraph after a heading is indented according to the value +of @var{word}: + +@table @asis +@item @code{none} +Prevents the first paragraph from being indented (default). +This option is ignored by @command{makeinfo} if +@code{@@paragraphindent asis} is in effect. + +@item @code{insert} +Include normal paragraph indentation. This respects the paragraph +indentation set by an @code{@@paragraphindent} command +(@pxref{@t{@@paragraphindent}}). +@end table + +@code{@@firstparagraphindent} is ignored for HTML and Docbook output. + +It is best to write the @code{@@firstparagraphindent} command before the +end-of-header line at the beginning of a Texinfo file, so the region +formatting commands indent paragraphs as specified. @xref{Start of +Header}. + + +@node @t{@@exampleindent} +@subsection @code{@@exampleindent}: Environment Indenting + +@anchor{exampleindent}@c old name +@findex exampleindent +@cindex Indenting environments +@cindex Environment indentation +@cindex Example indentation + +The Texinfo processors indent each line of @code{@@example} and similar +environments. You can use the @code{@@exampleindent} command to specify +this indentation. Write an @code{@@exampleindent} command at the +beginning of a line followed by either @samp{asis} or a number: + +@example +@@exampleindent @var{indent} +@end example + +The indentation is according to the value of @var{indent}: + +@table @asis +@item @code{asis} +Do not change the existing indentation (not implemented in @TeX{}). + +@item 0 +Omit all indentation. + +@item @var{n} +Indent environments by @var{n} space characters in Info output, by +@var{n} ems in @TeX{}. + +@end table + +The default value of @var{indent} is 5 spaces in Info, and 0.4@dmn{in} +in @TeX{}, which is somewhat less. (The reduction is to help @TeX{} +fit more characters onto physical lines.) + +It is best to write the @code{@@exampleindent} command before the +end-of-header line at the beginning of a Texinfo file, so the region +formatting commands indent paragraphs as specified. @xref{Start of +Header}. + + +@node Ending a File +@chapter Ending a Texinfo File +@cindex Ending a Texinfo file +@cindex Texinfo file ending +@cindex File ending +@findex 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: + +@example +@@node Index +@@unnumbered Index + +@@printindex cp + +@@bye +@end example + +@menu +* 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. +@end menu + + +@node Printing Indices & Menus +@section Printing Indices and Menus +@cindex Printing an index +@cindex Indices, printing and menus +@cindex Generating menus with indices +@cindex 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 +@code{texindex} (@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 +@code{@@printindex} command. + +@findex printindex +@code{@@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 +@code{@@unnumbered}) to supply the chapter heading and put the index +into the table of contents. Precede the chapter heading with an +@code{@@node} line as usual. + +For example: + +@smallexample +@group +@@node Variable Index +@@unnumbered Variable Index + +@@printindex vr +@end group + +@group +@@node Concept Index +@@unnumbered Concept Index + +@@printindex cp +@end group +@end smallexample + +If you have more than one index, we recommend placing the concept index last. + +@itemize +@item +In printed output, @code{@@printindex} produces a traditional +two-column index, with dot leaders between the index terms and page +numbers. + +@item +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: + +@smallexample +* First index entry: Top. (line 7) +@end smallexample + +@noindent The actual number of spaces is variable, to right-justify +the line number; it's been reduced here to make the line fit in the +printed manual. + +@item +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. + +@item +In HTML output, @code{@@printindex} produces links to the index +entries. + +@item +In XML and Docbook output, it simply records the index to be printed. +@end itemize + + +@node File End +@section @code{@@bye} File Ending +@findex 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 XEmacs, most typically a @samp{compile-command} +(@pxref{Compile-Command,, Using the Local Variables List}). + + +@node Chapter Structuring +@chapter Chapter Structuring +@anchor{Structuring}@c old name +@cindex Chapter structuring +@cindex Structuring of chapters +@cindex 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 +(@pxref{@t{makeinfo} 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. + +@menu +* 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. +@end menu + + +@node Tree Structuring +@section Tree Structure of Sections +@cindex 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. + +@example +@group + 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 + +@end group +@end 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: + +@example +@group +@@node Chapter 2 +@@chapter Chapter 2 +@end group +@end example + +@noindent +But for purposes of example, here is how it would be written with +explicit node pointers: + +@example +@group +@@node Chapter 2, Chapter 3, Chapter 1, Top +@@chapter Chapter 2 +@end group +@end example + +The chapter structuring commands are described in the sections that +follow; the @code{@@node} command is described in +the following chapter (@pxref{Nodes}). + + +@node Structuring Command Types +@section Structuring Command Types + +The chapter structuring commands fall into four groups or series, each +of which contains structuring commands corresponding to the +hierarchical levels of chapters, sections, subsections, and +subsubsections. + +The four groups of commands are the @code{@@chapter} series, the +@code{@@unnumbered} series, the @code{@@appendix} series, and the +@code{@@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: + +@itemize @bullet +@item +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. + +@item +The @code{@@unnumbered} series of commands produce unnumbered entries +both in the body of a document and in its table of contents. The +@code{@@top} command, which has a special use, is a member of this +series (@pxref{@t{@@top} Command}). An @code{@@unnumbered} section +is a normal part of the document structure. + +@item +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. +@end itemize + +When an @code{@@setchapternewpage} command says to do so, the +@code{@@chapter}, @code{@@unnumbered}, and @code{@@appendix} commands +start new pages in the printed manual; the @code{@@heading} commands +do not. @xref{@t{@@setchapternewpage}}. + +Here is a summary: + +@tex +{\globaldefs=1 \smallfonts \rm} +@end tex + +@multitable @columnfractions .19 .30 .29 .22 +@item @tab @tab @tab No new page +@item @i{Numbered} @tab @i{Unnumbered} @tab @i{Lettered/numbered} @tab @i{Unnumbered} +@item In contents @tab In contents @tab In contents @tab Not in contents +@item @tab @code{@@top} @tab @tab @code{@@majorheading} +@item @code{@@chapter} @tab @code{@@unnumbered} @tab @code{@@appendix} @tab @code{@@chapheading} +@item @code{@@section} @tab @code{@@unnumberedsec} @tab @code{@@appendixsec} @tab @code{@@heading} +@item @code{@@subsection} @tab @code{@@unnumberedsubsec} @tab @code{@@appendixsubsec} @tab @code{@@subheading} +@item @code{@@subsubsection} @tab @code{@@unnumberedsubsubsec} @tab @code{@@appendixsubsubsec} @tab @code{@@subsubheading} +@end multitable +@tex +{\globaldefs=1 \textfonts \rm} +@end tex + + +@node @t{@@chapter} +@section @code{@@chapter}: Chapter Structuring + +@anchor{chapter}@c old name +@findex chapter + +@code{@@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 +from@tie{}1. + +For example, the present chapter in this manual is entitled +``@code{@@chapter}: Chapter Structuring''; the @code{@@chapter} line +looks like this: + +@example +@@chapter @@code@{@@@@chapter@}: Chapter Structuring +@end 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: + +@example +@group +5 Chapter Structuring +********************* +@end group +@end 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. + + +@node @t{@@unnumbered @@appendix} +@section @code{@@unnumbered}, @code{@@appendix}: Chapters with Other Labeling + +@anchor{unnumbered & appendix}@c old name +@findex unnumbered +@findex appendix + +Use the @code{@@unnumbered} command to start a chapter-level element +that appears without chapter numbers of any kind. Use the +@code{@@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}. + +@findex 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. It may be suitable for short documents. +@c but the Hacker's Dictionary wanted it, before they quit Texinfo. + +@cindex Docbook and prefatory sections +@cindex Preface, etc., and Docbook +With @code{@@unnumbered}, if the name of the associated node is one of +these English words (case-insensitive): + +@example +Acknowledgements Colophon Dedication Preface +@end example + +@cindex @code{<acknowledgements>} Docbook tag +@cindex @code{<colophon>} Docbook tag +@cindex @code{<dedication>} Docbook tag +@cindex @code{<preface>} Docbook tag +@cindex @code{<chapter>} Docbook tag +@cindex @code{<title>} Docbook tag +@noindent then the Docbook output uses corresponding special tags +(@code{<preface>}, etc.)@: instead of the default @code{<chapter>}. +The argument to @code{@@unnumbered} itself can be anything, and is +output as the following @code{<title>} text as usual. + + +@node @t{@@majorheading @@chapheading} +@section @code{@@majorheading}, @code{@@chapheading}: Chapter-level Headings + +@anchor{majorheading & chapheading}@c old name +@findex majorheading +@findex 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 +@code{@@chapheading} commands produce the same output as +@code{@@chapter}: the title is printed on a line by itself with a line +of asterisks underneath. Similarly for HTML@. The only difference is +the lack of numbering and the lack of any association with nodes. +@xref{@t{@@chapter}}. + + +@node @t{@@section} +@section @code{@@section}: Sections Below Chapters + +@anchor{section}@c old name +@findex section + +An @code{@@section} command identifies a section within a chapter +unit, whether created with @code{@@chapter}, @code{@@unnumbered}, or +@code{@@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, + +@example +@@section This is a section +@end example + +@noindent +might produce the following in Info: + +@example +@group +5.7 This is a section +===================== +@end group +@end 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''; @pxref{@t{@@chapter}}. + + +@node @t{@@unnumberedsec @@appendixsec @@heading} +@section @code{@@unnumberedsec}, @code{@@appendixsec}, @code{@@heading} + +@anchor{unnumberedsec appendixsec heading}@c old name +@findex unnumberedsec +@findex appendixsec +@findex 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). + +@code{@@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. + +@table @code +@item @@unnumberedsec +The @code{@@unnumberedsec} command may be used within an unnumbered +chapter or within a regular chapter or appendix to produce an +unnumbered section. + +@item @@appendixsec +@itemx @@appendixsection +@findex appendixsection +@findex appendixsec +@code{@@appendixsection} is a longer spelling of the +@code{@@appendixsec} command; the two are synonymous. + +Conventionally, the @code{@@appendixsec} or @code{@@appendixsection} +command is used only within appendices. + +@item @@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. +@end table + + +@node @t{@@subsection} +@section @code{@@subsection}: Subsections Below Sections + +@anchor{subsection}@c old name +@findex subsection + +Subsections are to sections as sections are to chapters; +@pxref{@t{@@section}}. In Info and plain text, subsection titles +are underlined with @samp{-}. For example, + +@example +@@subsection This is a subsection +@end example + +@noindent +might produce + +@example +@group +1.2.3 This is a subsection +-------------------------- +@end group +@end 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''; +@pxref{@t{@@chapter}}. + + +@node @t{@@unnumberedsubsec @@appendixsubsec @@subheading} +@section The @code{@@subsection}-like Commands + +@anchor{unnumberedsubsec appendixsubsec subheading}@c old name +@findex unnumberedsubsec +@findex appendixsubsec +@findex subheading +@cindex Subsection-like commands + +The @code{@@unnumberedsubsec}, @code{@@appendixsubsec}, and +@code{@@subheading} commands are, respectively, the unnumbered, +appendix-like, and heading-like equivalents of the @code{@@subsection} +command. (@xref{@t{@@subsection}}.) + +@code{@@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 +@code{@@appendix} chapters (@pxref{@t{@@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 +@code{@@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. + + +@node @t{@@subsubsection} +@section @code{@@subsection} and Other Subsub Commands + +@anchor{subsubsection}@c old name +@findex subsubsection +@findex unnumberedsubsubsec +@findex appendixsubsubsec +@findex subsubheading +@cindex Subsub sectioning commands + +The fourth and lowest level sectioning commands in Texinfo are the +`subsub' commands. They are: + +@table @code +@item @@subsubsection +Subsubsections are to subsections as subsections are to sections. +(@xref{@t{@@subsection}}.) Subsubsection titles appear in the +table of contents. + +@item @@unnumberedsubsubsec +Unnumbered subsubsection titles appear in the table of contents, +but lack numbers. Otherwise, unnumbered subsubsections are the same +as subsubsections. + +@item @@appendixsubsubsec +Conventionally, appendix commands are used only for appendices and are +lettered and numbered appropriately. They also appear in the table +of contents. + +@item @@subsubheading +The @code{@@subsubheading} command may be used anywhere that you want +a small heading that will not appear in the table of contents. +@end table + +As with subsections, @code{@@unnumberedsubsubsec} and +@code{@@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 +(@pxref{@t{@@section}}). + +In Info, `subsub' titles are underlined with periods. For example, + +@example +@@subsubsection This is a subsubsection +@end example + +@noindent +might produce + +@example +@group +1.2.3.4 This is a subsubsection +............................... +@end group +@end example + +The @TeX{}, HTML, Docbook, and XML output is all analogous to the +chapter-level output, just ``three levels down''; @pxref{@t{@@chapter}}. + + +@node @t{@@part} +@section @code{@@part}: Groups of Chapters +@findex part +@cindex 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: + +@example +@@part Part I:@@* The beginning +@end 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: + +@example +@@part Part I:@@* The beginning + +@@node Introduction +@@chapter Introduction +... +@end 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 +@code{@@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 +(@pxref{@t{@@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. + +@code{@@part} is ignored when raising or lowering sections (see next +section). That is, it is never lowered and nothing can be raised to it. + + +@node Raise/lower sections +@section Raise/lower Sections: @code{@@raisesections} and @code{@@lowersections} +@findex raisesections +@findex lowersections +@cindex Raising and lowering sections +@cindex Lowering and raising sections +@cindex 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 +@code{@@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. + +@cindex 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: + +@example +@@lowersections +@@include somefile.texi +@@raisesections +@end example + +@noindent (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 (@pxref{@t{@@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 +@command{makeinfo}'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. + + +@node Nodes +@chapter Nodes + +@dfn{Nodes} 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. +@xref{HTML Xref Link Preservation}. + +@menu +* @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. +@end menu + + +@node @t{@@node} +@section The @code{@@node} Command + +@anchor{node}@c node +@findex node +@cindex 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 (@pxref{@t{makeinfo} +Pointer Creation}). You may insert spaces before or after each name +on the @code{@@node} line if you wish; such spaces are ignored. + +@opindex accesskey@r{, 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 +@samp{u} respectively. This allows people using web browsers to +follow the navigation using (typically) @kbd{M-@var{letter}}, e.g., +@kbd{M-n} for the `Next' node, from anywhere within the node. + +Usually, you write one of the chapter-structuring command lines +immediately after an @code{@@node} line---for example, an +@code{@@section} or @code{@@subsection} line. @xref{Structuring +Command Types}. + +@TeX{} uses both @code{@@node} names and chapter-structuring names in +the output for cross references. For this reason, you must write +@code{@@node} lines in a Texinfo file that you intend to format for +printing, even if you do not intend to format it for Info; 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} +(@pxref{@t{@@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}. + +@menu +* 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. +@end menu + + +@node Node Names +@subsection Choosing Node and Pointer Names + +@cindex Node names, choosing +The name of a node identifies the node. For all the details of node +names, @pxref{Node Line Requirements}). + +@anchor{Node Line Tips}@c previous node name +Here are some suggestions for node names: + +@itemize @bullet +@item +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.) + +@item +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. + +@item +Conventionally, node names are capitalized in the same way as section +and chapter titles. In this manual, initial and significant words are +capitalized; others are not. In other manuals, just initial words and +proper nouns are capitalized. Either way is fine; we recommend just +being consistent. +@end 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 +(@pxref{@t{makeinfo} 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. + + +@node Writing a Node +@subsection Writing an @code{@@node} Line +@cindex Writing an @code{@@node} line +@cindex @code{@@node} line writing +@cindex 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: + +@example +@@node @var{node-name} +@end example + +If you are using XEmacs, you can use the update node commands +provided by Texinfo mode to insert the names of the pointers; or +(recommended), you can leave the pointers out of the Texinfo file and +let @code{makeinfo} insert node pointers into the Info file it +creates. (@xref{Texinfo Mode}, and @ref{@t{makeinfo} Pointer +Creation}.) + +Alternatively, you can insert the `Next', `Previous', and `Up' +pointers yourself. If you do this, you may find it helpful to use the +Texinfo mode keyboard command @kbd{C-c C-c n}. This command inserts +@samp{@@node} and a comment line listing the names of the pointers in +their proper order. The comment line helps you keep track of which +arguments are for which pointers. This comment line is especially useful +if you are not familiar with Texinfo. + +The template for a fully-written-out node line with `Next', `Previous', +and `Up' pointers looks like this: + +@example +@@node @var{node-name}, @var{next}, @var{previous}, @var{up} +@end example + +The @var{node-name} argument must be present, but the others are +optional. If you wish to specify some but not others, just insert +commas as needed, as in: @samp{@@node mynode,,,uppernode}. However, +we recommend leaving off all the pointers and letting @code{makeinfo} +determine them, 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. + + +@node Node Line Requirements +@subsection @code{@@node} Line Requirements + +@cindex Node line requirements +@cindex Restrictions on node names + +Names used with @code{@@node} have several requirements: + +@itemize @bullet +@item +@cindex Unique node names requirement +@cindex 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. + +@item +The next/previous/up pointers on @code{@@node} lines must be the names +of nodes. (It's recommended to leave out these explicit node pointer +names, which automatically avoids any problem here; @pxref{@t{makeinfo} +Pointer Creation}.) + +@item +@cindex Commands in node names +@cindex @@-commands in node names +Node names can contain @@-commands. The output is generally the +natural result of the command; for example, using @code{@@TeX@{@}} in a +node name results in the @TeX{} logo being output, as it would be in +normal text. Cross references should use @code{@@TeX@{@}} just as the +node name does. + +For Info and HTML output, especially, it is necessary to expand +commands to some sequence of plain characters; for instance, +@code{@@TeX@{@}} 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 +@command{makeinfo}). Now it is part of the language. + +@item +@cindex Colon in node name +@cindex Comma in node name +@cindex Parentheses in node name +@cindex Period in node name +@cindex Characters, invalid in node name +@cindex Invalid characters in node names +@cindex Node names, invalid characters in +Unfortunately, you cannot reliably use periods, commas, or colons +within a node name; these can 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.) + +@command{makeinfo} warns about such problematic usage in node names, +menu items, and cross references. If you don't want to see the +warnings, you can set the customization variable +@code{INFO_SPECIAL_CHARS_WARNING} to @samp{0} (@pxref{Other +Customization Variables}). + +Also, 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} +(@pxref{@t{@@asis}}). For example: + +@example +@@node foo@@asis@{::@}bar +@end example + +As an example of avoiding the special characters, the following is a +section title in this manual: + +@smallexample +@@section @@code@{@@@@unnumbered@}, @@code@{@@@@appendix@}: ... +@end smallexample + +@noindent +But the corresponding node name lacks the commas and the subtitle: + +@smallexample +@@node @t{@@unnumbered @@appendix} +@end smallexample + +@cindex Case in node name +@item +Case is significant in node names. + +@cindex White space in node name +@cindex 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: + +@example +@@node foo bar, +@@node foo bar , +@@node foo bar, +@@node foo bar , +@end example + +@noindent all define the same node, namely @samp{foo bar}. References +to the node should all use that name, with no leading or trailing +spaces, and a single internal space. +@end itemize + + +@node First Node +@subsection The First Node +@cindex Top node is first +@cindex First node + +The first node of a Texinfo file is the @dfn{Top} node, except in an +included file (@pxref{Include Files}). The Top node should contain a +short summary, copying permissions, and a master menu. @xref{The Top +Node}, for more information on the Top node contents and examples. + +Here is a description of the node pointers to be used in the Top node: + +@itemize @bullet +@item +@cindex Up node of Top node +@cindex (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 +@samp{(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. + +@item +@cindex Next node of Top node +The `Next' node of the Top node should be the first chapter in your +document. + +@end itemize + +@xref{Installing 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: + +@example +@@node Top +@end example + + +@node @t{@@top} Command +@subsection The @code{@@top} Sectioning Command + +@anchor{top command}@c old name +@anchor{makeinfo top}@c another old name +@anchor{makeinfo top command}@c yet another name +@findex 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} +(@pxref{@t{@@unnumbered @@appendix}}). + +The @code{@@top} node is conventionally wrapped in an +@code{@@ifnottex} conditional so that it will not appear in @TeX{} +output (@pxref{Conditionals}). +Thus, in practice, a Top node usually looks like this: + +@example +@@ifnottex +@@node Top +@@top @var{your-manual-title} + +@var{very-high-level-summary} +@@end ifnottex +@end example + +@code{@@top} is ignored when raising or lowering sections. That is, +it is never lowered and nothing can be raised to it +(@pxref{Raise/lower sections}). + + +@node @t{makeinfo} Pointer Creation +@section @code{makeinfo} Pointer Creation + +@cindex Creating pointers with @code{makeinfo} +@cindex Pointer creation with @code{makeinfo} +@cindex Automatic pointer creation with @code{makeinfo} +@cindex Implicit pointer creation with @code{makeinfo} + +The @code{makeinfo} program can automatically determine node pointers +for a hierarchically organized document. This implicit node pointer +creation feature in @code{makeinfo} relieves you from the need to +update menus and pointers manually or with Texinfo mode commands. +(@xref{Updating Nodes and Menus}.) We highly recommend taking +advantage of this. + +To do so, write your @code{@@node} lines with just the name of the +node: + +@example +@@node My Node +@end example + +@noindent +You do not need to write out the `Next', `Previous', and `Up' +pointers. + +Then, you must write a sectioning command, such as @code{@@chapter} +or @code{@@section}, on the line immediately following each truncated +@code{@@node} line (except that comment lines may intervene). This is +where it normally goes. + +Also, you must write the name of each node (except for the `Top' node) +in a menu that is one or more hierarchical levels above the node's +level. + +Finally, you must follow the `Top' @code{@@node} line with a line +beginning with @code{@@top} to mark the top-level node in the file. +@xref{@t{@@top} Command}. + +@cindex Detail menu +@findex detailmenu +If you use a detailed menu in your master menu (@pxref{Master Menu +Parts}), mark it with the @code{@@detailmenu @dots{} @@end +detailmenu} environment, or @command{makeinfo} will get confused, +typically about the last and/or first node in the document. + +In most cases, you will want to take advantage of this feature and not +redundantly specify node pointers that the programs can determine. +However, Texinfo documents are not required to be organized +hierarchically or in fact to contain sectioning commands at all (for +example, if you never intend the document to be printed), so node +pointers may still be specified explicitly, in full generality. + + +@node @t{@@anchor} +@section @code{@@anchor}: Defining Arbitrary Cross Reference Targets + +@anchor{anchor}@c old name +@findex anchor +@cindex Anchors +@cindex Cross reference targets, arbitrary +@cindex Targets for cross references, arbitrary + +An @dfn{anchor} is a position in your document, labeled so that cross +references can refer to it, just as they can to nodes. You create an +anchor with the @code{@@anchor} command, and give the label as a +normal brace-delimited argument. For example: + +@example +This marks the @@anchor@{x-spot@}spot. +@dots{} +@@xref@{x-spot,,the spot@}. +@end example + +@noindent produces: + +@example +This marks the spot. +@dots{} +See [the spot], page 1. +@end example + +As you can see, the @code{@@anchor} command itself produces no output. +This example defines an anchor `x-spot' just before the word `spot'. +You can refer to it later with an @code{@@xref} or other cross +reference command, as shown (@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 +@code{goto-node} 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}). + +@cindex 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. + + +@node Node Menu Illustration +@section Node and Menu Illustration + +Here is a copy of the diagram shown earlier that illustrates a Texinfo +file with three chapters, each of which contains two sections. + +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. + +@example +@group + 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 +@end group +@end example + +Using explicit pointers (not recommended, but for shown for purposes +of the example), the fully-written command to start Chapter@tie{}2 +would be this: + +@example +@group +@@node Chapter 2, Chapter 3, Chapter 1, Top +@@comment node-name, next, previous, up +@end group +@end example + +@noindent +This @code{@@node} line says that the name of this node is +``Chapter@tie{}2'', the name of the `Next' node is ``Chapter 3'', the +name of the `Previous' node is ``Chapter@tie{}1'', and the name of the +`Up' node is ``Top''. You can (and should) omit writing out these +node names if your document is hierarchically organized +(@pxref{@t{makeinfo} Pointer Creation}), but the pointer +relationships still obtain. + +@quotation 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.) +@end 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: + +@example +@group + @@menu + * Sect. 2.1:: Description of this section. + * Sect. 2.2:: Description. + @@end menu +@end group +@end example + +Using explicit pointers, the node for Sect.@: 2.1 is written like this: + +@example +@group +@@node Sect. 2.1, Sect. 2.2, Chapter 2, Chapter 2 +@@comment node-name, next, previous, up +@end group +@end 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 +@code{@@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 +@code{@@chapter} line, and then by indexing lines. The manual uses +implictly determined node pointers; therefore, nothing else is needed +on the @code{@@node} line. + +@example +@group +@@node Ending a File +@@chapter Ending a Texinfo File +@@cindex Ending a Texinfo file +@@cindex Texinfo file ending +@@cindex File ending +@end group +@end example + +An earlier version of the manual used explicit node pointers. Here is +the beginning of the same chapter for that case. This shows an +@code{@@node} line followed by a comment line, an @code{@@chapter} +line, and then by indexing lines. + +@example +@group +@@node Ending a File, Structuring, Beginning a File, Top +@@comment node-name, next, previous, up +@@chapter Ending a Texinfo File +@@cindex Ending a Texinfo file +@dots{} +@end group +@end example + + +@node Menus +@chapter Menus +@cindex Menus +@findex menu + +@dfn{Menus} 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. + +@menu +* 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. +@end menu + + +@node Menu Location +@section Menu Location +@cindex Menu location +@cindex 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. + +@cindex 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. + +@cindex 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 (@pxref{@t{makeinfo} Pointer Creation}) and +XEmacs 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. + +Years ago, 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 it 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. + + +@node Writing a Menu +@section Writing a Menu +@cindex Writing a menu +@cindex 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 +@code{@@end menu} command on a line by itself. + +A menu looks like this: + +@example +@group +@@menu +Larger Units of Text + +* Files:: All about handling files. +* Multiples: Buffers. Multiple buffers; editing + several files at once. +@@end menu +@end group +@end example + +@cindex Spaces, in menus +In a menu, every line that begins with an @w{@samp{* }} is a @dfn{menu +entry}. (Note the space after the asterisk.) A line that does not +start with an @w{@samp{* }} may also appear in a menu. Such a line is +not a menu entry but rather a @dfn{menu comment} line that appears in +the Info file. In the example above, the line @samp{Larger Units of +Text} is such a menu comment line; the two lines starting with +@w{@samp{* }} are menu entries. Space characters in a menu are +preserved as-is in the Info output; this allows you to format the menu +as you wish. + +@opindex accesskey@r{, in HTML output of menus} +In the HTML output from @command{makeinfo}, the @code{accesskey} +attribute is used with the values @samp{1}@dots{}@samp{9} for the +first nine entries. This allows people using web browsers to follow +the first menu entries using (typically) @kbd{M-@var{digit}}, e.g., +@kbd{M-1} for the first entry. + + +@node Menu Parts +@section The Parts of a Menu +@cindex Parts of a menu +@cindex Menu parts +@cindex @code{@@menu} parts + +A menu entry has three parts, only the second of which is required: + +@enumerate +@item +The menu entry name (optional). + +@item +The name of the node (required). + +@item +A description of the item (optional). +@end enumerate + +The template for a generic menu entry looks like this (but see the +next section for one more possibility): + +@example +* @var{menu-entry-name}: @var{node-name}. @var{description} +@end 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{. }). + +@command{makeinfo} warns when the text of a menu item (and node names +and cross references) contains a problematic construct that will +interfere with its parsing in Info. If you don't want to see the +warnings, you can set the customization variable +@code{INFO_SPECIAL_CHARS_WARNING} to @samp{0} (@pxref{Other +Customization Variables}). + +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. + + +@node Less Cluttered Menu Entry +@section Less Cluttered Menu Entry +@cindex Two part menu entry +@cindex Double-colon menu entries +@cindex Menu entries with two colons +@cindex Less cluttered menu entry +@cindex 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. + +@need 800 +For example, write + +@example +* Name:: @var{description} +@end example + +@need 800 +@noindent +instead of + +@example +* Name: Name. @var{description} +@end example + +We recommend using the node name for the menu entry name whenever +possible, since it reduces visual clutter in the menu. + + +@node Menu Example +@section A Menu Example +@cindex Menu example +@cindex Example menu + +A menu looks like this in Texinfo: + +@example +@group +@@menu +* menu entry name: Node name. A short description. +* Node name:: This form is preferred. +@@end menu +@end group +@end example + +@need 800 +@noindent +This produces: + +@example +@group +* menu: + +* menu entry name: Node name. A short description. +* Node name:: This form is preferred. +@end group +@end example + +@need 700 +Here is an example as you might see it in a Texinfo file: + +@example +@group +@@menu +Larger Units of Text + +* Files:: All about handling files. +* Multiples: Buffers. Multiple buffers; editing + several files at once. +@@end menu +@end group +@end example + +@need 800 +@noindent +This produces: + +@example +@group +* menu: +Larger Units of Text + +* Files:: All about handling files. +* Multiples: Buffers. Multiple buffers; editing + several files at once. +@end group +@end 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. +@samp{Multiples} is the menu entry name; it refers to the node named +@samp{Buffers}. 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 +@samp{Buffers}, they must be the names of nodes in the same Info file +(@pxref{Other Info Files, , Referring to Other Info Files}). + +@node Other Info Files +@section Referring to Other Info Files +@cindex Referring to other Info files +@cindex Nodes in other Info files +@cindex Other Info files' nodes +@cindex Going to other Info files' nodes +@cindex 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: + +@example +@group +@@menu +* @var{first-entry-name}:(@var{filename})@var{nodename}. @var{description} +* (@var{filename})@var{second-node}:: @var{description} +@@end menu +@end group +@end example + +For example, to refer directly to the @samp{Outlining} and +@samp{Rebinding} nodes in the @cite{XEmacs User's Manual}, you could write a +menu like this: + +@example +@group +@@menu +* Outlining: (xemacs)Outline Mode. The major mode for + editing outlines. +* (xemacs)Rebinding:: How to redefine the + meaning of a key. +@@end menu +@end group +@end 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: + +@example +@group +* Info: (info). Documentation browsing system. +* (xemacs):: The extensible, self-documenting + text editor. +@end group +@end example + +The XEmacs Texinfo mode menu updating commands only work with nodes +within the current buffer, so you cannot use them to create menus that +refer to other files. You must write such menus by hand. + + +@node Cross References +@chapter Cross References +@cindex Making cross references +@cindex Cross references +@cindex References + +@dfn{Cross references} are used to refer the reader to other parts of the +same or different Texinfo files. In Texinfo, nodes and anchors are the +places to which cross references can refer. + +@menu +* 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. +@end menu + + +@node References +@section 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, +@pxref{@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. + +@TeX{} 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. + +@need 800 +@node Cross Reference Commands +@section Different Cross Reference Commands +@cindex Different cross reference commands + +There are four different cross reference commands: + +@table @code +@item @@xref +Used to start a sentence in the printed manual and in HTML with +@w{`See @dots{}'} or an Info cross reference saying @samp{*Note +@var{name}: @var{node}.}. + +@item @@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). + +@item @@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'.) + +@item @@inforef +Used to make a reference to an Info file for which there is no printed +manual. +@end table + +@noindent +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. @xref{@t{@@cite}}. + + +@node Cross Reference Parts +@section Parts of a Cross Reference +@cindex Cross reference parts +@cindex 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: + +@example +@@xref@{Node name@}. +@end example + +@noindent +which produces + +@example +*Note Node name::. +@end example + +@noindent +in Info and + +@quotation +See Section @var{nnn} [Node name], page @var{ppp}. +@end quotation + +@noindent +in a printed manual. + +@need 700 +Here is an example of a full five-part cross reference: + +@example +@group +@@xref@{Node name, Cross Reference Name, Particular Topic, +info-file-name, A Printed Manual@}, for details. +@end group +@end example + +@noindent +which produces + +@example +*Note Cross Reference Name: (info-file-name)Node name, +for details. +@end example + +@noindent +in Info and + +@quotation +See section ``Particular Topic'' in @i{A Printed Manual}, for details. +@end quotation + +@noindent +in a printed book. + +The five possible arguments for a cross reference are: + +@enumerate +@item +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. + +@item +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. + +@item +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. + +@item +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. + +@item +The name of a printed manual from a different Texinfo file. +@end enumerate + +The template for a full five argument cross reference looks like +this: + +@example +@group +@@xref@{@var{node-name}, @var{cross-reference-name}, @var{title-or-topic}, +@var{info-file-name}, @var{printed-manual-title}@}. +@end group +@end 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. + +@command{makeinfo} warns when the text of a cross reference (and node +names and menu items) contains a problematic construct that will +interfere with its parsing in Info. If you don't want to see the +warnings, you can set the customization variable +@code{INFO_SPECIAL_CHARS_WARNING} to @samp{0} (@pxref{Other +Customization Variables}). + + +@node @t{@@xref} +@section @code{@@xref} + +@anchor{xref}@c old name +@findex xref +@cindex Cross references using @code{@@xref} +@cindex 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. + +@menu +* 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. +@end menu + +@node Reference Syntax +@subsection What a Reference Looks Like and Requires + +Most often, an Info cross reference looks like this: + +@example +*Note @var{node-name}::. +@end example + +@noindent +or like this + +@example +*Note @var{cross-reference-name}: @var{node-name}. +@end example + +@noindent +In @TeX{}, a cross reference looks like this: + +@quotation +See Section @var{section-number} [@var{node-name}], page @var{page}. +@end quotation + +@noindent +or like this + +@quotation +See Section @var{section-number} [@var{title-or-topic}], page @var{page}. +@end 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; +@pxref{@t{@@pxref}}.) + +@quotation Caution +A period or comma @emph{must} follow the closing brace of an +@code{@@xref}. It is required to terminate the cross reference. This +period or comma will appear in the output. +@end quotation + +@code{@@xref} must refer to a node by name. Use @code{@@node} to +define the node (@pxref{Writing a Node}), or @code{@@anchor} +(@pxref{@t{@@anchor}}). + +@code{@@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. + +@quotation 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{@@comma@{@}} may be used to +protect such commas (@pxref{Inserting a Comma}). +@end quotation + + +@node One Argument +@subsection @code{@@xref} with One Argument +@cindex 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. + +@need 700 +@noindent +For example, + +@example +@@xref@{Tropical Storms@}. +@end example + +@noindent +produces + +@example +*Note Tropical Storms::. +@end example + +@noindent +in Info and + +@quotation +See Section 3.1 [Tropical Storms], page 24. +@end quotation + +@noindent +in a printed manual. +(Note that in the preceding example the closing brace to +@code{@@xref}'s argument is followed by a period.) + +You can write a clause after the cross reference, like this: + +@example +@@xref@{Tropical Storms@}, for more info. +@end example + +@noindent +which produces + +@example +*Note Tropical Storms::, for more info. +@end example + +@noindent +in Info and + +@quotation +See Section 3.1 [Tropical Storms], page 24, for more info. +@end quotation + + +@noindent +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. + + +@node Two Arguments +@subsection @code{@@xref} with Two Arguments +@cindex 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. + +@need 750 +@noindent +The template is like this: + +@example +@@xref@{@var{node-name}, @var{cross-reference-name}@}. +@end example + +@need 700 +@noindent +For example, + +@example +@@xref@{Electrical Effects, Lightning@}. +@end example + +@noindent +produces: + +@example +*Note Lightning: Electrical Effects. +@end example + +@noindent +in Info and + +@quotation +See Section 5.2 [Electrical Effects], page 57. +@end quotation + +@noindent +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: + +@example +@@xref@{Electrical Effects, Lightning@}, for more info. +@end example + +@noindent +which produces + +@example +*Note Lightning: Electrical Effects, for more info. +@end example + +@noindent +in Info and + +@quotation +See Section 5.2 [Electrical Effects], page 57, for more info. +@end quotation + +@noindent +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.) + +The second argument to cross references must observe some of the +restrictions for node names (@pxref{Node Line Requirements}). The +most common issue is that colons cannot be used, since that interferes +with the parsing of the Info file. + + +@node Three Arguments +@subsection @code{@@xref} with Three Arguments +@cindex 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. + +Remember to write a comma or period after the closing brace of an +@code{@@xref} to terminate the cross reference. In the following +examples, a clause follows a terminating comma. + +@need 750 +@noindent +The template is like this: + +@example +@group +@@xref@{@var{node-name}, @var{cross-reference-name}, @var{title-or-topic}@}. +@end group +@end example + +@need 700 +@noindent +For example, + +@example +@group +@@xref@{Electrical Effects, Lightning, Thunder and Lightning@}, +for details. +@end group +@end example + +@noindent +produces + +@example +*Note Lightning: Electrical Effects, for details. +@end example + +@noindent +in Info and + +@quotation +See Section 5.2 [Thunder and Lightning], page 57, for details. +@end quotation + +@noindent +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.) + +@example +@group +@@xref@{Electrical Effects, , Thunder and Lightning@}, +for details. +@end group +@end example + +@noindent +produces + +@example +*Note Thunder and Lightning: Electrical Effects, for details. +@end example + +@noindent +in Info and + +@quotation +See Section 5.2 [Thunder and Lightning], page 57, for details. +@end quotation + +@noindent +in a printed manual. + +The third argument to cross references must observe some of the +restrictions for node names (@pxref{Node Line Requirements}). The +most common issue is that colons cannot be used, since that interferes +with the parsing of the Info file. + +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. + +@findex xrefautomaticsectiontitle +Texinfo offers a setting to use the section title instead of node +names by default in cross references (an explicitly specified third +argument still takes precedence): + +@example +@@xrefautomaticsectiontitle on +@end example + +Typically this line would be given near the beginning of the document +and used for the whole manual. But you can turn it off if you want +(@code{@@xrefautomaticsectiontitle off}), for example, if you're +including some other sub-document that doesn't have suitable section +names. + + +@node Four and Five Arguments +@subsection @code{@@xref} with Four and Five Arguments +@cindex 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 +@code{@@xref} command to terminate the cross reference. + +@need 800 +@noindent +The full template is: + +@example +@group +@@xref@{@var{node-name}, @var{cross-reference-name}, @var{title-or-topic}, +@var{info-file-name}, @var{printed-manual-title}@}. +@end group +@end example + +@need 700 +@noindent +For example, + +@example +@@xref@{Electrical Effects, Lightning, Thunder and Lightning, +weather, An Introduction to Meteorology@}. +@end example + +@noindent +produces this output in Info: + +@example +*Note Lightning: (weather)Electrical Effects. +@end example + +@noindent +As you can see, the name of the Info file is enclosed in parentheses +and precedes the name of the node. + +@noindent +In a printed manual, the reference looks like this: + +@quotation +See section ``Thunder and Lightning'' in @cite{An Introduction to +Meteorology}. +@end quotation + +@noindent +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, + +@example +@@xref@{Electrical Effects, , Thunder and Lightning, +weather, An Introduction to Meteorology@}. +@end example + +@noindent +produces + +@example +@group +*Note Thunder and Lightning: (weather)Electrical Effects. +@end group +@end example + +@noindent +in Info and + +@quotation +See section ``Thunder and Lightning'' in @cite{An Introduction to +Meteorology}. +@end quotation + +@noindent +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, + +@example +@@xref@{Electrical Effects,,, +weather, An Introduction to Meteorology@}. +@end example + +@noindent +produces + +@example +@group +*Note (weather)Electrical Effects::. +@end group +@end example + +@noindent +in Info and + +@quotation +See section ``Electrical Effects'' in @cite{An Introduction to +Meteorology}. +@end quotation + +@noindent +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 +@emph{except} the fourth and fifth, to refer to another manual as a +whole. See the next section. + + +@node Top Node Naming +@section Naming a `Top' Node +@cindex Naming a `Top' Node in references +@cindex `Top' node naming for references + +@cindex Manual, referring to as a whole +@cindex 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, + +@example +@@xref@{Top,,, make, The GNU Make Manual@}. +@end example + +@noindent produces + +@example +@group +*Note (make)::Top. +@end group +@end example + +@noindent and + +@quotation +See @cite{The GNU Make Manual}. +@end quotation + +@noindent +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: + +@example +@@xref@{Top,, Overview, make, The GNU Make Manual@}. +@end example + +@noindent +which produces + +@example +*Note Overview: (make)Top. +@end example + +@noindent +in Info and + +@quotation +See section ``Overview'' in @cite{The GNU Make Manual}. +@end quotation + +@noindent +in a printed manual. + +In this example, @samp{Top} is the name of the first node, and +@samp{Overview} 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. + + +@node @t{@@ref} +@section @code{@@ref} + +@anchor{ref}@c old name +@findex ref +@cindex Cross references using @code{@@ref} +@cindex References using @code{@@ref} + +@code{@@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. + +@noindent For example, + +@cindex Hurricanes +@example +For more information, @@pxref@{This@}, and @@ref@{That@}. +@end example + +@noindent +produces in Info: + +@example +For more information, *note This::, and *note That::. +@end example + +@noindent +and in printed output: + +@quotation +For more information, see Section 1.1 [This], page 1, +and Section 1.2 [That], page 2. +@end 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: + +@cindex Sea surges +@example +Sea surges are described in @@ref@{Hurricanes@}. +@end example + +@noindent +looks ok in the printed output: + +@quotation +Sea surges are described in Section 6.7 [Hurricanes], page 72. +@end quotation + +@noindent +but is awkward to read in Info, ``note'' being a verb: + +@example +Sea surges are described in *note Hurricanes::. +@end 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. + + +@node @t{@@pxref} +@section @code{@@pxref} + +@anchor{pxref}@c old name +@findex pxref +@cindex Cross references using @code{@@pxref} +@cindex 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: + +@enumerate +@item +@TeX{} typesets the reference for the printed manual with a lowercase +`see' rather than an uppercase `See'. + +@item +The Info formatting commands automatically end the reference with a +closing colon or period, if necessary. +@end enumerate + +@code{@@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. + +@noindent +With one argument, a parenthetical cross reference looks like this: + +@cindex Flooding +@example +@dots{} storms cause flooding (@@pxref@{Hurricanes@}) @dots{} +@end example + +@need 800 +@noindent +which produces + +@example +@group +@dots{} storms cause flooding (*note Hurricanes::) @dots{} +@end group +@end example + +@noindent +in Info and + +@quotation +@dots{} storms cause flooding (see Section 6.7 [Hurricanes], page 72) @dots{} +@end quotation + +@noindent +in a printed manual. + +With two arguments, a parenthetical cross reference has this template: + +@example +@dots{} (@@pxref@{@var{node-name}, @var{cross-reference-name}@}) @dots{} +@end example + +@noindent +which produces + +@example +@dots{} (*note @var{cross-reference-name}: @var{node-name}.) @dots{} +@end example + +@noindent +in Info and + +@quotation +@dots{} (see Section @var{nnn} [@var{node-name}], page @var{ppp}) @dots{} +@end quotation + +@noindent +in a printed manual. + +@code{@@pxref} can be used with up to five arguments, just like +@code{@@xref} (@pxref{@t{@@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: + +@example +@dots{} For more information, @@pxref@{More@}. +@end example + +@noindent +which outputs (in Info): + +@example +@dots{} For more information, *note More::. +@end example + +@noindent +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. + + +@node @t{@@inforef} +@section @code{@@inforef}: Cross References to Info-only Material + +@anchor{inforef}@c old name +@findex inforef +@cindex Cross references using @code{@@inforef} +@cindex References using @code{@@inforef} + +@code{@@inforef} is used for making cross references to Info +documents---even from a printed manual. This might be because you +want to refer to conditional @code{@@ifinfo} text +(@pxref{Conditionals}), or because printed output is not available +(perhaps because there is no Texinfo source), among other +possibilities. + +The command takes either two or three arguments, in the following +order: + +@enumerate +@item +The node name. + +@item +The cross reference name (optional). + +@item +The Info file name. +@end enumerate + +@noindent +Separate the arguments with commas, as with @code{@@xref}. Also, you +must terminate the reference with a comma or period after the +@samp{@}}, as you do with @code{@@xref}. + +@noindent +The template is: + +@example +@@inforef@{@var{node-name}, @var{cross-reference-name}, @var{info-file-name}@}, +@end example + +@need 800 +@noindent +For example, + +@example +@group +@@inforef@{Advanced, Advanced Info commands, info@}, +for more information. +@end group +@end example + +@need 800 +@noindent +produces (in Info): + +@example +@group +*Note Advanced Info commands: (info)Advanced, +for more information. +@end group +@end example + +@need 800 +@noindent +and (in the printed output): + +@quotation +See Info file @file{info}, node @samp{Advanced}, for more information. +@end 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. +@xref{@t{@@cite}}. + + +@node @t{@@url} +@section @code{@@url}, @code{@@uref@{@var{url}[, @var{text}][, @var{replacement}]@}} + +@anchor{uref}@c old name +@findex uref +@cindex Uniform resource locator, referring to +@cindex URL, referring to + +@cindex @code{href}, producing HTML +@code{@@uref} produces a reference to a uniform resource locator (url). +It takes one mandatory argument, the url, and two optional arguments +which control the text that is displayed. In HTML output, @code{@@uref} +produces a link you can follow. + +@anchor{url} @code{@@url} is a synonym for @code{@@uref}. +(Originally, @code{@@url} had the meaning of @code{@@indicateurl} +(@pxref{@t{@@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. + +@cindex 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. + +@cindex Line breaking, and urls +@cindex Breakpoints within urls +@TeX{} 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}). + +@findex 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: + +@vindex after@r{, value for @code{@@urefbreakstyle}} +@vindex before@r{, value for @code{@@urefbreakstyle}} +@vindex none@r{, value for @code{@@urefbreakstyle}} +@table @samp +@item after +(the default) Potentially break after the special characters. +@item before +Potentially break before the special characters. +@item none +Do not consider breaking at the special characters; any potential +breaks must be manually inserted. +@end table + +Here is an example of the simple one argument form, where the url is +both the target and the text of the link: + +@example +The official GNU ftp site is @@uref@{http://ftp.gnu.org/gnu@}. +@end example + +@noindent produces: +@display +The official GNU ftp site is @uref{http://ftp.gnu.org/gnu}. +@end display + + +An example of the two-argument form: +@example +The official @@uref@{http://ftp.gnu.org/gnu, GNU ftp site@} +holds programs and texts. +@end example + +@noindent produces: +@display +The official @uref{http://ftp.gnu.org/gnu, GNU ftp site} +holds programs and texts. +@end display + +@noindent that is, the Info output is this: +@example +The official GNU ftp site (http://ftp.gnu.org/gnu) +holds programs and texts. +@end example + +@noindent and the HTML output is this: +@example +The official <a href="http://ftp.gnu.org/gnu">GNU ftp site</a> +holds programs and texts. +@end example + + +An example of the three-argument form: +@example +The @@uref@{/man.cgi/1/ls,,ls@} program @dots{} +@end example + +@noindent produces: +@display +The @uref{/man.cgi/1/ls,,ls} program @dots{} +@end display + +@noindent but with HTML: +@example +The <a href="/man.cgi/1/ls">ls</a> program @dots{} +@end example + +Some people prefer to display urls in the unambiguous format: + +@display +<URL:http://@var{host}/@var{path}> +@end display + +@noindent +@cindex @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} (@pxref{@t{@@indicateurl}}). + + +@node @t{@@cite} +@section @code{@@cite}@{@var{reference}@} + +@anchor{cite}@c old name +@findex cite + +Use the @code{@@cite} command for the name of a book that lacks a +companion Info file. The command produces italics in the printed +manual, and quotation marks in the Info file. + +If a book is written in Texinfo, it is better to use a cross reference +command since a reader can easily follow such a reference in Info. +@xref{@t{@@xref}}. + + +@node Marking Text +@chapter Marking Text, Words and Phrases +@cindex Paragraph, marking text within +@cindex Marking words and phrases +@cindex Words and phrases, marking them +@cindex Marking text within a paragraph +@cindex Text, marking up + +In Texinfo, you can mark words and phrases in a variety of ways. +The Texinfo formatters use this information to determine how to +highlight the text. +You can specify, for example, whether a word or phrase is a +defining occurrence, a metasyntactic variable, or a symbol used in a +program. Also, you can emphasize text, in several different ways. + +@menu +* Indicating:: How to indicate definitions, files, etc. +* Emphasis:: How to emphasize text. +@end menu + + +@node Indicating +@section Indicating Definitions, Commands, etc. + +@cindex Highlighting text +@cindex Indicating commands, definitions, etc. + +Texinfo has commands for indicating just what kind of object a piece +of text refers to. For example, email addresses are marked by +@code{@@email}; that way, the result can be a live link to send email +when the output format supports it. If the email address was simply +marked as ``print in a typewriter font'', that would not be possible. + +@menu +* 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. +@end menu + + +@node Useful Highlighting +@subsection Highlighting Commands are Useful + +The commands serve a variety of purposes: + +@table @code +@item @@code@{@var{sample-code}@} +Indicate text that is a literal example of a piece of a program. +@xref{@t{@@code}}. + +@item @@kbd@{@var{keyboard-characters}@} +Indicate keyboard input. @xref{@t{@@kbd}}. + +@item @@key@{@var{key-name}@} +Indicate the conventional name for a key on a keyboard. +@xref{@t{@@key}}. + +@item @@samp@{@var{text}@} +Indicate text that is a literal example of a sequence of characters. +@xref{@t{@@samp}}. + +@item @@verb@{@var{text}@} +Write a verbatim sequence of characters. +@xref{@t{@@verb}}. + +@item @@var@{@var{metasyntactic-variable}@} +Indicate a metasyntactic variable. @xref{@t{@@var}}. + +@item @@env@{@var{environment-variable}@} +Indicate an environment variable. @xref{@t{@@env}}. + +@item @@file@{@var{file-name}@} +Indicate the name of a file. @xref{@t{@@file}}. + +@item @@command@{@var{command-name}@} +Indicate the name of a command. +@xref{@t{@@command}}. + +@item @@option@{@var{option}@} +Indicate a command-line option. +@xref{@t{@@option}}. + +@item @@dfn@{@var{term}@} +Indicate the introductory or defining use of a term. +@xref{@t{@@dfn}}. + +@item @@cite@{@var{reference}@} +Indicate the name of a book. @xref{@t{@@cite}}. + +@item @@abbr@{@var{abbreviation}@} +Indicate an abbreviation, such as `Comput.'. + +@item @@acronym@{@var{acronym}@} +Indicate an acronym. @xref{@t{@@acronym}}. + +@item @@indicateurl@{@var{uniform-resource-locator}@} +Indicate an example (that is, nonfunctional) uniform resource locator. +@xref{@t{@@indicateurl}}. (Use @code{@@url} (@pxref{@t{@@url}}) for +live urls.) + +@item @@email@{@var{email-address}[, @var{displayed-text}]@} +Indicate an electronic mail address. @xref{@t{@@email}}. + +@end table + + +@node @t{@@code} +@subsection @code{@@code}@{@var{sample-code}@} + +@anchor{code}@c old name +@findex code + +@cindex Syntactic tokens, indicating +Use the @code{@@code} command to indicate text that is a piece of a +program and which consists of entire syntactic tokens. Enclose the +text in braces. + +@cindex Expressions in a program, indicating +@cindex Keywords, indicating +@cindex Reserved words, indicating +Thus, you should use @code{@@code} for an expression in a program, for +the name of a variable or function used in a program, or for a +keyword in a programming language. + +Use @code{@@code} for command names in languages that resemble +programming languages, such as Texinfo. For example, @code{@@code} and +@code{@@samp} are produced by writing @samp{@@code@{@@@@code@}} and +@samp{@@code@{@@@@samp@}} in the Texinfo source, respectively. + +@cindex Case, not altering in @code{@@code} +It is incorrect to alter the case of a word inside an @code{@@code} +command when it appears at the beginning of a sentence. Most computer +languages are case sensitive. In C, for example, @code{Printf} is +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, + +@example +The function returns @@code@{nil@}. +@end example + +@noindent +produces this: + +@quotation +The function returns @code{nil}. +@end quotation + +Here are some cases for which it is preferable @emph{not} to use @code{@@code}: + +@itemize @bullet +@item +For shell command names such as @command{ls} (use @code{@@command}). + +@item +For environment variable such as @env{TEXINPUTS} (use @code{@@env}). + +@item +For shell options such as @samp{-c} when such options stand alone (use +@code{@@option}). + +@item +An entire shell command often looks better if written using +@code{@@samp} rather than @code{@@code}. In this case, the rule is to +choose the more pleasing format. + +@item +For a string of characters shorter than a syntactic token. For example, +if you are writing about @samp{goto-ch}, which is just a part of the +name for the @code{goto-char} Emacs Lisp function, you should use +@code{@@samp}. + +@item +In general, when writing about the characters used in a token; for +example, do not use @code{@@code} when you are explaining what letters +or printable symbols can be used in the names of functions. (Use +@code{@@samp}.) Also, you should not use @code{@@code} to mark text +that is considered input to programs unless the input is written in a +language that is like a programming language. For example, you should +not use @code{@@code} for the keystroke commands of XEmacs (use +@code{@@kbd} instead) although you may use @code{@@code} for the names +of the Emacs Lisp functions that the keystroke commands invoke. + +@end itemize + +By default, @TeX{} will consider breaking lines at @samp{-} and +@samp{_} characters within @code{@@code} and related commands. This +can be controlled with @code{@@allowcodebreaks} +(@pxref{@t{@@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 +(@pxref{@t{@@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 +@code{OPEN_QUOTE_SYMBOL} 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}). + + +@node @t{@@kbd} +@subsection @code{@@kbd}@{@var{keyboard-characters}@} + +@anchor{kbd}@c old name +@findex kbd +@cindex Keyboard input + +Use the @code{@@kbd} command for characters of input to be typed by +users. For example, to refer to the characters @kbd{M-a}, write: + +@example +@@kbd@{M-a@} +@end example + +@noindent +and to refer to the characters @kbd{M-x shell}, write: + +@example +@@kbd@{M-x shell@} +@end example + +@cindex User input +@cindex 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. + +@findex 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: + +@vindex distinct@r{, value for @code{@@kbdinputstyle}} +@vindex example@r{, value for @code{@@kbdinputstyle}} +@vindex code@r{, value for @code{@@kbdinputstyle}} +@table @samp +@item code +Always use the same font for @code{@@kbd} as @code{@@code}. +@item example +Use the distinguishing font for @code{@@kbd} only in @code{@@example} +and similar environments. +@item distinct +(the default) Always use the distinguishing font for @code{@@kbd}. +@end 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'': + +@example +@@kbd@{r @@key@{RET@}@} +@end example + +@noindent +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: + +@example +To give the @@code@{logout@} command, +type the characters @@kbd@{l o g o u t @@key@{RET@}@}. +@end example + +@noindent +This produces: + +@quotation +To give the @code{logout} command, +type the characters @kbd{l o g o u t @key{RET}}. +@end 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{@@key@{SPC@}} for it.) + + +@node @t{@@key} +@subsection @code{@@key}@{@var{key-name}@} + +@anchor{key}@c old name +@findex key + +Use the @code{@@key} command for the conventional name for a key on a +keyboard, as in: + +@example +@@key@{RET@} +@end example + +You can use the @code{@@key} command within the argument of an +@code{@@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 @kbd{M-@key{TAB}} you +would type: + +@example +@@kbd@{C-x @@key@{ESC@}@} +@@kbd@{M-@@key@{TAB@}@} +@end example + +Here is a list of the recommended names for keys: +@cindex Recommended names for keys +@cindex Keys, recommended names +@cindex Names recommended for keys +@cindex Abbreviations for keys +@cindex Control keys, specifying +@cindex Meta keys, specifying + +@quotation +@table @t +@item SPC +Space +@item RET +Return +@item LFD +Linefeed (however, since most keyboards nowadays do not have a Linefeed key, +it might be better to call this character @kbd{C-j}) +@item TAB +Tab +@item BS +Backspace +@item ESC +Escape +@item DELETE +Delete +@item SHIFT +Shift +@item CTRL +Control +@item META +Meta +@end table +@end quotation + +@cindex 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{@@kbd@{Meta-a@}} to produce @kbd{Meta-a} and +@samp{@@key@{META@}} to produce @key{META}. + +As a convention in GNU manuals, @code{@@key} should not be used in +index entries. + + +@node @t{@@samp} +@subsection @code{@@samp}@{@var{text}@} + +@anchor{samp}@c old name +@findex 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. + +@example +To match @@samp@{foo@} at the end of the line, +use the regexp @@samp@{foo$@}. +@end example + +@noindent +produces + +@quotation +To match @samp{foo} at the end of the line, use the regexp +@samp{foo$}. +@end quotation + +Any time you are referring to single characters, you should use +@code{@@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 +@code{@@code}. Basically, @code{@@samp} is a catchall for whatever is +not covered by @code{@@code}, @code{@@kbd}, @code{@@key}, +@code{@@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: + +@example +@group +In English, the vowels are @@samp@{a@}, @@samp@{e@}, +@@samp@{i@}, @@samp@{o@}, @@samp@{u@}, and sometimes +@@samp@{y@}. +@end group +@end example + +@noindent +This produces: + +@quotation +In English, the vowels are @samp{a}, @samp{e}, +@samp{i}, @samp{o}, @samp{u}, and sometimes +@samp{y}. +@end quotation + + +@node @t{@@verb} +@subsection @code{@@verb}@{@var{char}@var{text}@var{char}@} + +@anchor{verb}@c old name +@findex verb +@cindex Verbatim in-line text + +@cindex 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: + +@example +How many @@verb@{|@@|@}-escapes does one need to print this +@@verb@{.@@a @@b.@@c.@} string or @@verb@{+@@'e?`@{@}!`\+@} this? +@end example + +@noindent +produces + +@example +How many @verb{|@|}-escapes does one need to print this +@verb{.@a @b.@c.} string or @verb{+@'e?`{}!`\+} this? +@end example + +This is in contrast to @code{@@samp} (see the previous section), +@code{@@code}, and similar commands; in those cases, the argument is +normal Texinfo text, where the three characters @code{@@@{@}} 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{@@verb@{...@}} 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. + + +@node @t{@@var} +@subsection @code{@@var}@{@var{metasyntactic-variable}@} + +@anchor{var}@c old name +@findex var + +Use the @code{@@var} command to indicate metasyntactic variables. A +@dfn{metasyntactic 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 +@code{texinfo-tex-command} is not a metasyntactic variable; it is +properly formatted using @code{@@code}. + +Do not use @code{@@var} for environment variables either; @code{@@env} +is correct for them (see the next section). + +The effect of @code{@@var} in the Info file is to change the case of +the argument to all uppercase. In the printed manual and HTML +output, the argument is output in slanted type. + +@need 700 +For example, + +@example +To delete file @@var@{filename@}, +type @@samp@{rm @@var@{filename@}@}. +@end example + +@noindent +produces + +@quotation +To delete file @var{filename}, type @samp{rm @var{filename}}. +@end quotation + +@noindent +(Note that @code{@@var} may appear inside @code{@@code}, +@code{@@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: + +@example +@group +\input texinfo +@@@@setfilename @@var@{info-file-name@} +@@@@settitle @@var@{name-of-manual@} +@end group +@end example + +@noindent +This produces: + +@example +@group +\input texinfo +@@setfilename @var{info-file-name} +@@settitle @var{name-of-manual} +@end group +@end example + +In some documentation styles, metasyntactic variables are shown with +angle brackets, for example: + +@example +@dots{}, type rm <filename> +@end example + +@noindent +However, that is not the style that Texinfo uses. + +@c FIXME add a customization variable? Add an example on how to do that +@c for HTML? +@c (You can, of course, modify the sources to @file{texinfo.tex} +@c and the Info formatting commands +@c to output the @code{<@dots{}>} format if you wish.) + + +@node @t{@@env} +@subsection @code{@@env}@{@var{environment-variable}@} + +@anchor{env}@c old name +@findex env + +Use the @code{@@env} command to indicate environment variables, as +used by many operating systems, including GNU@. Do not use it for +@emph{meta}syntactic variables; use @code{@@var} for those (see the +previous section). + +@code{@@env} is equivalent to @code{@@code} in its effects. +For example: + +@example +The @@env@{PATH@} environment variable @dots{} +@end example +@noindent produces +@quotation +The @env{PATH} environment variable @dots{} +@end quotation + + +@node @t{@@file} +@subsection @code{@@file}@{@var{file-name}@} + +@anchor{file}@c old name +@findex 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}. + +@code{@@file} is equivalent to @code{code} in its effects. For +example, + +@example +The @@file@{.el@} files are in +the @@file@{/usr/local/xemacs/lisp@} directory. +@end example + +@noindent +produces + +@quotation +The @file{.el} files are in +the @file{/usr/local/xemacs/lisp} directory. +@end quotation + + +@node @t{@@command} +@subsection @code{@@command}@{@var{command-name}@} + +@anchor{command}@c old name +@findex command +@cindex Command names, indicating +@cindex Program names, indicating + +Use the @code{@@command} command to indicate command names, such as +@command{ls} or @command{cc}. + +@code{@@command} is equivalent to @code{@@code} in its effects. +For example: + +@example +The command @@command@{ls@} lists directory contents. +@end example +@noindent produces +@quotation +The command @command{ls} lists directory contents. +@end quotation + +You should write the name of a program in the ordinary text font, rather +than using @code{@@command}, if you regard it as a new English word, +such as `Emacs' or `Bison'. + +When writing an entire shell command invocation, as in @samp{ls -l}, +you should use either @code{@@samp} or @code{@@code} at your discretion. + + +@node @t{@@option} +@subsection @code{@@option}@{@var{option-name}@} + +@anchor{option}@c old name +@findex option + +Use the @code{@@option} command to indicate a command-line option; for +example, @option{-l} or @option{--version} or +@option{--output=@var{filename}}. + +@code{@@option} is equivalent to @code{@@code} in its effects. +For example: + +@example +The option @@option@{-l@} produces a long listing. +@end example +@noindent produces +@quotation +The option @option{-l} produces a long listing. +@end quotation + + +@node @t{@@dfn} +@subsection @code{@@dfn}@{@var{term}@} + +@anchor{dfn}@c old name +@findex 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: + +@example +Getting rid of a file is called @@dfn@{deleting@} it. +@end example + +@noindent +produces + +@quotation +Getting rid of a file is called @dfn{deleting} it. +@end 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. + + +@node @t{@@abbr} +@subsection @code{@@abbr}@{@var{abbreviation}[, @var{meaning}]@} + +@anchor{abbr}@c old name +@findex abbr + +@cindex Abbreviations, tagging +You can use the @code{@@abbr} command for general abbreviations. The +abbreviation is given as the single argument in braces, as in +@samp{@@abbr@{Comput.@}}. As a matter of style, or for particular +abbreviations, you may prefer to omit periods, as in +@samp{@@abbr@{Mr@} Stallman}. + +@code{@@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. + +@cindex @code{<abbr>} and @code{<abbrev>} tags +In @TeX{} and in the Info output, the first argument is printed as-is; +if the second argument is present, it is printed in parentheses after +the abbreviation. In HTML the @code{<abbr>} tag is used; in Docbook, +the @code{<abbrev>} tag is used. For instance: + +@example +@@abbr@{Comput. J., Computer Journal@} +@end example + +@noindent produces: + +@display +@abbr{Comput. J., Computer Journal} +@end 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. + + +@node @t{@@acronym} +@subsection @code{@@acronym}@{@var{acronym}[, @var{meaning}]@} + +@anchor{acronym}@c old name +@findex acronym + +@cindex NASA, as acronym +@cindex Acronyms, tagging +You can use the @code{@@acronym} command for abbreviations written in +all capital letters, such as `@acronym{NASA}'. The abbreviation is +given as the single argument in braces, as in +@samp{@@acronym@{NASA@}}. As a matter of style, or for particular +acronyms, you may prefer to use periods, as in +@samp{@@acronym@{N.A.S.A.@}}. + +@code{@@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. + +@cindex @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 +@code{@@acronym} recursively): + +@example +@@acronym@{GNU, @@acronym@{GNU@}'s Not Unix@} +@end example + +@noindent produces: + +@display +@acronym{GNU, @acronym{GNU}'s Not Unix} +@end display + +@cindex 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}). + +@code{@@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. + +@itemize @minus +@item +In common English usage, acronyms are a subset of abbreviations: they +include pronounceable words like `@acronym{NATO}', `radar', and +`snafu'; some sources also include syllable acronyms like +`Usenet', hybrids like `@acronym{SIGGRAPH}', and unpronounceable +initialisms like `@acronym{FBI}'. + +@item +In Texinfo, an acronym (but not an abbreviation) should consist only +of capital letters and periods, no lowercase. + +@item +In @TeX{}, an acronym (but not an abbreviation) is printed in a +slightly smaller font. + +@item +Some browsers place a dotted bottom border under abbreviations but not +acronyms. + +@item +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'. + +@item +In general, it's not essential to use either of these commands for all +abbreviations; use your judgment. Text is perfectly readable without +them. +@end itemize + + +@node @t{@@indicateurl} +@subsection @code{@@indicateurl}@{@var{uniform-resource-locator}@} + +@anchor{indicateurl}@c old name +@findex indicateurl +@cindex Uniform resource locator, indicating +@cindex 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 +@code{@@uref} command for that, @pxref{@t{@@url}}). +@code{@@indicateurl} is useful for urls which do not actually exist. +For example: + +@example +For example, the url might be @@indicateurl@{http://example.org/path@}. +@end example + +@noindent which produces: + +@display +For example, the url might be @indicateurl{http://example.org/path}. +@end display + +The output from @code{@@indicateurl} is more or less like that of +@code{@@samp} (@pxref{@t{@@samp}}). + + +@node @t{@@email} +@subsection @code{@@email}@{@var{email-address}[, @var{displayed-text}]@} + +@anchor{email}@c old name +@findex 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). + +@cindex 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: + +@example +Send bug reports to @@email@{bug-texinfo@@@@gnu.org@}, +suggestions to the @@email@{bug-texinfo@@@@gnu.org, same place@}. +@end example + +@noindent produces + +@display +Send bug reports to @email{bug-texinfo@@gnu.org}, +suggestions to the @email{bug-texinfo@@gnu.org, same place}. +@end display + + +@node Emphasis +@section Emphasizing Text +@cindex 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 +@code{@@r} command, has any regular use. + +@menu +* @t{@@emph @@strong}:: How to emphasize text in Texinfo. +* Smallcaps:: How to use the small caps font. +* Fonts:: Various font commands for printed output. +@end menu + + +@node @t{@@emph @@strong} +@subsection @code{@@emph}@{@var{text}@} and @code{@@strong}@{@var{text}@} + +@anchor{emph & strong}@c oldname +@findex emph +@findex strong +@cindex Emphasizing text, font for + +The @code{@@emph} and @code{@@strong} commands are for emphasis; +@code{@@strong} is stronger. In printed output, @code{@@emph} produces +@emph{italics} and @code{@@strong} produces @strong{bold}. +In the Info output, @code{@@emph} surrounds the text with underscores +(@samp{_}), and @code{@@strong} puts asterisks around the text. + +For example, + +@example +@group +@@strong@{Caution:@} @@samp@{rm *@} +removes @@emph@{all@} normal files. +@end group +@end example + +@noindent +produces the following: + +@quotation +@strong{Caution}: @samp{rm * .[^.]*} +removes @emph{all} normal files. +@end 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. + +@quotation 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{@@quotation}---@samp{Note} is allowable +there. +@end quotation + + +@node Smallcaps +@subsection @code{@@sc}@{@var{text}@}: The Small Caps Font +@cindex Small caps font +@findex 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: + +@example +Richard @@sc@{Stallman@} commenc@'{e} GNU. +@end example + +@noindent +This produces: + +@display +Richard @sc{Stallman} commenc@'{e} GNU. +@end 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. + +@cindex @code{<small>} tag +@TeX{} typesets any uppercase letters between the braces of an +@code{@@sc} command in full-size capitals; only lowercase letters are +printed in the small caps font. In the Info output, the argument to +@code{@@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. + + +@node Fonts +@subsection Fonts for Printing +@cindex Fonts for printing + +@findex fonttextsize +@cindex Font size, reducing +@cindex Reducing font size +@cindex 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: + +@example +@@fonttextsize 10 +@end example + +@cindex Printing cost, reducing +The effect is to reduce the body font to a 10@dmn{pt} size (the +default is 11@dmn{pt}). Fonts for other elements, such as sections +and chapters, are reduced accordingly. This should only be used in +conjunction with @code{@@smallbook} (@pxref{@t{@@smallbook}}) or +similar, since 10@dmn{pt} 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. + +@table @code +@item @@b +@findex b @r{(bold font)} +@cindex Bold font +selects @b{bold} face; + +@item @@i +@findex i @r{(italic font)} +@cindex Italic font +selects an @i{italic} font; + +@item @@r +@findex r @r{(roman font)} +@cindex Roman font +@cindex Default font +selects a @r{roman} font, which is the usual font in which text is +printed. It may or may not be seriffed. + +@item @@sansserif +@findex sansserif @r{(sans serif font)} +@cindex Sans serif font +selects a @sansserif{sans serif} font; + +@item @@slanted +@findex slanted @r{(slanted font)} +@cindex Slanted font +@cindex Oblique font +selects a @slanted{slanted} font; + +@item @@t +@findex t @r{(typewriter font)} +@cindex Monospace font +@cindex Fixed-width font +@cindex Typewriter font +selects the @t{fixed-width}, typewriter-style font used by @code{@@code}; + +@end 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.) + +@cindex <lineannotation> Docbook tag +The @code{@@r} command can be useful in example-like environments, to +write comments in the standard roman font instead of the fixed-width +font. This looks better in printed output, and produces a +@code{<lineannotation>} tag in Docbook output. + +For example, + +@example +@group +@@lisp +(+ 2 2) ; @@r@{Add two plus two.@} +@@end lisp +@end group +@end example + +@noindent +produces + +@lisp +(+ 2 2) ; @r{Add two plus two.} +@end 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{@@t@{foo@}} +produces @t{foo}, cf. @code{@@code@{foo@}} 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 +@code{@@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. + + +@node Quotations and Examples +@chapter Quotations and Examples + +Quotations and examples are blocks of text consisting of one or more +whole paragraphs that are set off from the bulk of the text and +treated differently. They are usually indented in the output. + +@findex 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 +@code{@@example} by itself at the beginning of a line and end the +example by writing @code{@@end example} on a line by itself, at the +beginning of that line, and with only one space between the +@code{@@end} and the @code{example}. + +@menu +* 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{@@small@dots{}}:: 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. +@end menu + + +@node Block Enclosing Commands +@section 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. + +@table @code +@item @@quotation +Indicate text that is quoted. The text is filled, indented (from both +margins), and printed in a roman font by default. + +@item @@indentedblock +Like @code{@@quotation}, but the text is indented only on the left. + +@item @@example +Illustrate code, commands, and the like. The text is printed +in a fixed-width font, and indented but not filled. + +@item @@lisp +Like @code{@@example}, but specifically for illustrating Lisp code. The +text is printed in a fixed-width font, and indented but not filled. + +@item @@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 +@code{@@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. + +@item @@display +Display illustrative text. The text is indented but not filled, and +no font is selected (so, by default, the font is roman). + +@item @@format +Like @code{@@display} (the text is not filled and no font is +selected), but the text is not indented. + +@item @@smallquotation +@itemx @@smallindentedblock +@itemx @@smallexample +@itemx @@smalllisp +@itemx @@smalldisplay +@itemx @@smallformat +These @code{@@small...} commands are just like their non-small +counterparts, except that they output text in a smaller font size, +where possible. + +@item @@flushleft +@itemx @@flushright +Text is not filled, but is set flush with the left or right margin, +respectively. + +@item @@raggedright +Text is filled, but only justified on the left, leaving the right +margin ragged. + +@item @@cartouche +Highlight text, often an example or quotation, by drawing a box with +rounded corners around it. +@end 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. + + +@node @t{@@quotation} +@section @code{@@quotation}: Block Quotations +@anchor{quotation}@c old name + +@cindex Quotations +@findex quotation + +The text of a quotation is processed like normal text (regular font, +text is filled) except that: + +@itemize @bullet +@item +both the left and right margins are closer to the center of the page, +so the whole of the quotation is indented; + +@item +the first lines of paragraphs are indented no more than other lines; and + +@item +an @code{@@author} command may be given to specify the author of the +quotation. +@end itemize + +@quotation +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. +@end 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. + +@code{@@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 +@samp{:}. For example: + +@example +@@quotation Note +This is +a foo. +@@end quotation +@end example + +@noindent +produces + +@quotation Note +This is +a foo. +@end quotation + +If the @code{@@quotation} argument is one of these English words +(case-insensitive): + +@example +Caution Important Note Tip Warning +@end example + +@cindex @code{<caution>} Docbook tag +@cindex @code{<important>} Docbook tag +@cindex @code{<note>} Docbook tag +@cindex @code{<tip>} Docbook tag +@cindex @code{<warning>} Docbook tag +@cindex @code{<blockquote>} HTML tag +@noindent 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: + +@example +@@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 +@end example + +@noindent +produces + +@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 + +@findex smallquotation +Texinfo also provides a command @code{@@smallquotation}, which is just +like @code{@@quotation} but uses a smaller font size where possible. +@xref{@t{@@small@dots{}}}. + + +@node @t{@@indentedblock} +@section @code{@@indentedblock}: Indented text blocks +@cindex Indented text block +@findex indentedblock + +The @code{@@indentedblock} environment is similar to +@code{@@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: + +@indentedblock +This is an example of text written between an @code{@@indentedblock} +command and an @code{@@end indentedblock} command. The +@code{@@indentedblock} environment can contain any text or other +commands desired. +@end indentedblock + +This is written in the Texinfo source as: + +@example +@@indentedblock +This is an example ... +@@end indentedblock +@end example + +@findex smallindentedblock +Texinfo also provides a command @code{@@smallindentedblock}, which is +just like @code{@@indentedblock} but uses a smaller font size where +possible. @xref{@t{@@small@dots{}}}. + + +@node @t{@@example} +@section @code{@@example}: Example Text + +@anchor{example}@c old name +@findex example +@cindex Examples, formatting them +@cindex Formatting examples + +The @code{@@example} environment is used to indicate an example that +is not part of the running text, such as computer input or output. +Write an @code{@@example} command at the beginning of a line by +itself. Mark the end of the example with an @code{@@end example} +command, also written at the beginning of a line by itself. + +An @code{@@example} environment has the following characteristics: + +@itemize +@item Each line in the input file is a line in the output; that is, +the source text is not filled as it normally is. +@item Extra spaces and blank lines are significant. +@item The output is indented. +@item The output uses a fixed-width font. +@item Texinfo commands @emph{are} expanded; if you want the output to +be the input verbatim, use the @code{@@verbatim} environment instead +(@pxref{@t{@@verbatim}}). +@end itemize + +For example, + +@example +@@example +cp foo @@var@{dest1@}; \ + cp foo @@var@{dest2@} +@@end example +@end example + +@noindent +produces + +@example +cp foo @var{dest1}; \ + cp foo @var{dest2} +@end example + +The lines containing @code{@@example} and @code{@@end example} will +disappear from the output. To make the output look good, you should +put a blank line before the @code{@@example} and another blank line +after the @code{@@end example}. Blank lines inside the beginning +@code{@@example} and the ending @code{@@end example}, on the other +hand, do appear in the output. + +@quotation Caution +Do not use tabs in the lines of an example! (Or anywhere else in +Texinfo, except in verbatim environments.) @TeX{} treats tabs as +single spaces, and that is not what they look like. In XEmacs, you can +use @kbd{M-x untabify} to convert tabs in a region to multiple spaces. +@end 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 (@pxref{@t{@@noindent}}. + +If you want to embed code fragments within sentences, instead of +displaying them, use the @code{@@code} command or its relatives +(@pxref{@t{@@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}). + + +@node @t{@@verbatim} +@section @code{@@verbatim}: Literal Text + +@anchor{verbatim}@c old name +@findex verbatim +@cindex 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: +@c oops, got to trick this a bit: can't use @end verbatim inside @verbatim + +@example +@exdent @t{@@verbatim} +@exdent @t{@{} +@exdent @key{TAB}@t{@@command with strange characters: @@'e} +@exdent @t{expand@key{TAB}me} +@exdent @t{@}} +@exdent @t{@@end verbatim} +@end example + +@noindent +This produces: + +@verbatim +{ + @command with strange characters: @'e +expand me +} +@end verbatim + +Since the lines containing @code{@@verbatim} and @code{@@end verbatim} +produce no output, typically you should put a blank line before the +@code{@@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. + +@cindex Verbatim, small +@cindex Small verbatim +You can get a ``small'' verbatim by enclosing the @code{@@verbatim} in +an @code{@@smallformat} environment, as shown here: + +@c more cheating ... +@smallexample +@exdent @t{@@smallformat} +@exdent @t{@@verbatim} +@exdent @t{... still verbatim, but in a smaller font ...} +@exdent @t{@@end verbatim} +@exdent @t{@@end smallformat} +@end smallexample + +Finally, a word of warning: it is not reliable to use +@code{@@verbatim} inside other Texinfo constructs. + + +@node @t{@@verbatiminclude} +@section @code{@@verbatiminclude} @var{file}: Include a File Verbatim + +@anchor{verbatiminclude}@c old name +@findex verbatiminclude +@cindex Verbatim, include file +@cindex Including a file verbatim + +You can include the exact contents of a file in the document with the +@code{@@verbatiminclude} command: + +@example +@@verbatiminclude @var{filename} +@end example + +The contents of @var{filename} is printed in a verbatim environment +(@pxref{@t{@@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 +@code{@@verbatiminclude} within @code{@@example} +(@pxref{@t{@@example}}). + +The name of the file is taken literally, with a single exception: +@code{@@value@{@var{var}@}} references are expanded. This makes it +possible to include files in other directories within a distribution, +for instance: + +@example +@@verbatiminclude @@value@{top_srcdir@}/NEWS +@end example + +@noindent (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}. + + +@node @t{@@lisp} +@section @code{@@lisp}: Marking a Lisp Example + +@anchor{lisp}@c old name +@findex lisp +@cindex Lisp example + +The @code{@@lisp} command is used for Lisp code. It is synonymous +with the @code{@@example} command. + +@lisp +This is an example of text written between an +@code{@@lisp} command and an @code{@@end lisp} command. +@end 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 +library.@footnote{It 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. + + +@node @t{@@small@dots{}} +@section @code{@@small@dots{}} Block Commands + +@anchor{small}@c old name +@findex smallexample +@findex smallformat +@findex smalllisp +@findex smallquotation +@cindex Small examples +@cindex Examples in smaller fonts +@cindex Quotations in smaller fonts +@cindex Lisp examples in smaller fonts + +In addition to the regular @code{@@example} and similar commands, +Texinfo has ``small'' example-style commands. These are +@code{@@smallquotation}, @code{@@smallindentedblock}, +@code{@@smalldisplay}, @code{@@smallexample}, @code{@@smallformat}, +and @code{@@smalllisp}. + +In Info output, the @code{@@small@dots{}} commands are equivalent to +their non-small companion commands. + +In @TeX{}, however, the @code{@@small@dots{}} 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 Texinfo@tie{}XML transliteration. + +Mark the end of an @code{@@small@dots{}} block with a corresponding +@code{@@end small@dots{}}. For example, pair @code{@@smallexample} with +@code{@@end smallexample}. + +Here is an example of the font used by the @code{@@smallexample} +command (in Info, the output will be the same as usual): + +@smallexample +@dots{} to make sure that you have the freedom to +distribute copies of free software (and charge for +this service if you wish), that you receive source +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. +@end smallexample + +The @code{@@small@dots{}} 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. + + +@node @t{@@display} +@section @code{@@display}: Examples Using the Text Font + +@anchor{display}@c old name +@findex display +@cindex Display formatting + +The @code{@@display} command begins another kind of environment, where +the font is left unchanged, not switched to typewriter as with +@code{@@example}. Each line of input still produces a line of output, +and the output is still indented. + +@display +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. +@end display + +@findex smalldisplay +Texinfo also provides the environment @code{@@smalldisplay}, which is +like @code{@@display} but uses a smaller font size. +@xref{@t{@@small@dots{}}}. + +The @code{@@table} command (@pxref{@t{@@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} (@pxref{@t{@@quotation}}) or +@code{@@indentedblock} (@pxref{@t{@@indentedblock}}). + + +@node @t{@@format} +@section @code{@@format}: Examples Using the Full Line Width + +@anchor{format}@c old name +@findex 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. + +@format +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. +@end format + +@findex smallformat +Texinfo also provides the environment @code{@@smallformat}, which is +like @code{@@format} but uses a smaller font size. +@xref{@t{@@small@dots{}}}. + + +@node @t{@@exdent} +@section @code{@@exdent}: Undoing a Line's Indentation + +@anchor{exdent}@c old name +@findex exdent +@cindex 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 +@code{@@exdent} line is printed in the roman font. + +@code{@@exdent} is usually used within examples. Thus, + +@example +@group +@@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 +@end group +@end example + +@noindent +produces + +@example +@group +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 group +@end 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. + +@code{@@exdent} has no effect in HTML output. + + +@node @t{@@flushleft @@flushright} +@section @code{@@flushleft} and @code{@@flushright} + +@anchor{flushleft & flushright}@c old name +@findex flushleft +@findex flushright +@cindex Ragged right, without filling +@cindex 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. + +@need 1500 +For example, + +@example +@group +@@flushleft +This text is +written flushleft. +@@end flushleft +@end group +@end example + +@noindent +produces + +@quotation +@flushleft +This text is +written flushleft. +@end flushleft +@end quotation + + +@code{@@flushright} produces the type of indentation often used in the +return address of letters. For example, + +@example +@group +@@flushright +Here is an example of text written +flushright. The @@code@{@@flushright@} command +right justifies every line but leaves the +left end ragged. +@@end flushright +@end group +@end example + +@noindent +produces + +@flushright +Here is an example of text written +flushright. The @code{@@flushright} command +right justifies every line but leaves the +left end ragged. +@end flushright + + +@node @t{@@raggedright} +@section @code{@@raggedright}: Ragged Right Text + +@anchor{raggedright}@c old name +@findex raggedright +@cindex 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 +@code{@@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, + +@example +@group +@@raggedright +Commands for double and single angle quotation marks: +@@code@{@@@@guillemetleft@@@{@@@}@}, @@code@{@@@@guillemetright@@@{@@@}@}, +@@code@{@@@@guillemotleft@@@{@@@}@}, @@code@{@@@@guillemotright@@@{@@@}@}, +@@code@{@@@@guilsinglleft@@@{@@@}@}, @@code@{@@@@guilsinglright@@@{@@@}@}. +@@end raggedright +@end group +@end example + +@noindent +produces + +@raggedright +Commands for double and single angle quotation marks: +@code{@@guillemetleft@{@}}, @code{@@guillemetright@{@}}, +@code{@@guillemotleft@{@}}, @code{@@guillemotright@{@}}, +@code{@@guilsinglleft@{@}}, @code{@@guilsinglright@{@}}. +@end raggedright + + +@node @t{@@noindent} +@section @code{@@noindent}: Omitting Indentation + +@anchor{noindent}@c old name +@findex noindent +@cindex Omitting indentation +@cindex Suppressing indentation +@cindex 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 +@code{@@noindent} at the beginning of a line, preceding the continuation +text. You can also disable indentation for all paragraphs globally with +@code{@@paragraphindent} (@pxref{@t{@@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. + +@need 1500 +For example: + +@example +@group +@@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 +@@code@{@@@@display@} and @@code@{@@@@end display@}.) +@end group +@end example + +@noindent produces: + +@display + +@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 +@code{@@display} and @code{@@end display}.) + +@end 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}). + + +@node @t{@@indent} +@section @code{@@indent}: Forcing Indentation + +@anchor{indent}@c old name +@findex indent +@cindex Forcing indentation +@cindex Inserting indentation +@cindex Indentation, forcing + +@indent +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 (@pxref{@t{@@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 +@code{@@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}). + + +@node @t{@@cartouche} +@section @code{@@cartouche}: Rounded Rectangles + +@anchor{cartouche}@c old name +@findex cartouche +@cindex Box with rounded corners +@cindex 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, + +@example +@@cartouche +@@example +% pwd +/usr/local/share/xemacs +@@end example +@@end cartouche +@end example + +@noindent +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): + +@cartouche +@example +% pwd +/usr/local/info +@end example +@end cartouche + +@code{@@cartouche} also implies @code{@@group} (@pxref{@t{@@group}}). + + +@node Lists and Tables +@chapter Lists and Tables +@cindex Making lists and tables +@cindex Lists and tables, making +@cindex 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. + +@menu +* 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. +@end menu + +@node Introducing Lists +@section 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. +@findex end + +Precede each element of a list with an @code{@@item} or @code{@@itemx} +command. + +@sp 1 +@noindent +Here is an itemized list of the different kinds of table and lists: + +@itemize @bullet +@item +Itemized lists with and without bullets. + +@item +Enumerated lists, using numbers or letters. + +@item +Two-column tables with highlighting. +@end itemize + +@sp 1 +@noindent +Here is an enumerated list with the same items: + +@enumerate +@item +Itemized lists with and without bullets. + +@item +Enumerated lists, using numbers or letters. + +@item +Two-column tables with highlighting. +@end enumerate + +@sp 1 +@noindent +And here is a two-column table with the same items and their +@w{@@-commands}: + +@table @code +@item @@itemize +Itemized lists with and without bullets. + +@item @@enumerate +Enumerated lists, using numbers or letters. + +@item @@table +@itemx @@ftable +@itemx @@vtable +Two-column tables, optionally with indexing. +@end table + + +@node @t{@@itemize} +@section @code{@@itemize}: Making an Itemized List + +@anchor{itemize}@c old name +@findex itemize +@cindex 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. + +@cindex @code{@@w}, for blank items +Begin an itemized list by writing @code{@@itemize} at the beginning of +a line. Follow the command, on the same line, with a character or a +Texinfo command that generates a mark. Usually, you will use +@code{@@bullet} after @code{@@itemize}, but you can use +@code{@@minus}, or any command or character that results in a single +character in the Info file. (When you write the mark command such as +@code{@@bullet} after an @code{@@itemize} command, you may omit the +@samp{@{@}}.) If you don't specify a mark command, the default is +@code{@@bullet}. If you don't want any mark at all, but still want +logical items, use @code{@@w@{@}} (in this case the braces are +required). + +@findex item +After the @code{@@itemize}, write your items, each starting with +@code{@@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 +@code{@@indentedblock}; @pxref{@t{@@indentedblock}}. + +Index entries and comments that are given before an @code{@@item} +including the first, are automatically moved (internally) to after the +@code{@@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. + +@example +@group +@@itemize @@bullet +@@item +Some text for foo. + +@@item +Some text +for bar. +@@end itemize +@end group +@end example + +@noindent +This produces: + +@quotation +@itemize @bullet +@item +Some text for foo. + +@item +Some text +for bar. +@end itemize +@end quotation + +Itemized lists may be embedded within other itemized lists. Here is a +list marked with dashes embedded in a list marked with bullets: + +@example +@group +@@itemize @@bullet +@@item +First item. + +@@itemize @@minus +@@item +Inner item. + +@@item +Second inner item. +@@end itemize + +@@item +Second outer item. +@@end itemize +@end group +@end example + +@noindent +This produces: + +@quotation +@itemize @bullet +@item +First item. + +@itemize @minus +@item +Inner item. + +@item +Second inner item. +@end itemize + +@item +Second outer item. +@end itemize +@end quotation + + +@node @t{@@enumerate} +@section @code{@@enumerate}: Making a Numbered or Lettered List + +@anchor{enumerate}@c old name +@findex enumerate +@cindex Enumeration + +@code{@@enumerate} is like @code{@@itemize} (@pxref{@t{@@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 +@samp{3}, 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 +@code{@@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. + +@need 1500 +Here is an example of @code{@@enumerate} without an argument: + +@example +@group +@@enumerate +@@item +Underlying causes. + +@@item +Proximate causes. +@@end enumerate +@end group +@end example + +@noindent +This produces: + +@enumerate +@item +Underlying causes. + +@item +Proximate causes. +@end enumerate +@sp 1 +Here is an example with an argument of @kbd{3}: +@sp 1 +@example +@group +@@enumerate 3 +@@item +Predisposing causes. + +@@item +Precipitating causes. + +@@item +Perpetuating causes. +@@end enumerate +@end group +@end example + +@noindent +This produces: + +@enumerate 3 +@item +Predisposing causes. + +@item +Precipitating causes. + +@item +Perpetuating causes. +@end enumerate +@sp 1 +Here is a brief summary of the alternatives. The summary is constructed +using @code{@@enumerate} with an argument of @kbd{a}. +@sp 1 +@enumerate a +@item +@code{@@enumerate} + +Without an argument, produce a numbered list, starting with the +number@tie{}1. + +@item +@code{@@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. + +@item +@code{@@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. + +@item +@code{@@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. +@end enumerate + +You can also nest enumerated lists, as in an outline. + + +@node Two-column Tables +@section Making a Two-column Table + +@cindex Tables, making two-column +@findex table + +@code{@@table} is similar to @code{@@itemize} +(@pxref{@t{@@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. + +@menu +* @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. +@end menu + +@node @t{@@table} +@subsection Using the @code{@@table} Command + +@anchor{table}@c old name + +@cindex 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}, +@code{@@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. + +@anchor{@t{@@asis}}@c command name with @, for consistency +@findex asis +You may also use the @code{@@asis} command as an argument to +@code{@@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 +@code{@@alias} (for a suitable predefined command) is acceptable. +@xref{Defining New Texinfo Commands}. + +@findex item +Begin each table entry with an @code{@@item} command at the beginning +of a line. Write the first column text on the same line as the +@code{@@item} command. Write the second column text on the line +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. + +@need 1500 +The following table, for example, highlights the text in the first +column with an @code{@@samp} command: + +@example +@group +@@table @@samp +@@item foo +This is the text for +@@samp@{foo@}. + +@@item bar +Text for @@samp@{bar@}. +@@end table +@end group +@end example + +@noindent +This produces: + +@table @samp +@item foo +This is the text for +@samp{foo}. +@item bar +Text for @samp{bar}. +@end table + +If you want to list two or more named items with a single block of +text, use the @code{@@itemx} command. (@xref{@t{@@itemx}}.) + + +@node @t{@@ftable @@vtable} +@subsection @code{@@ftable} and @code{@@vtable} + +@anchor{ftable vtable}@c old name +@findex ftable +@findex vtable +@cindex Tables with indexing +@cindex Indexing table entries automatically + +The @code{@@ftable} and @code{@@vtable} commands are the same as the +@code{@@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. + + +@node @t{@@itemx} +@subsection @code{@@itemx}: Second and Subsequent Items + +@anchor{itemx}@c old name +@cindex Two named items for @code{@@table} +@findex 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, + +@example +@group +@@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 +@end group +@end example + +@noindent +This produces: + +@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 + +@noindent +(Note also that this example illustrates multi-line supporting text in +a two-column table.) + + +@node Multi-column Tables +@section @code{@@multitable}: Multi-column Tables + +@findex multitable +@cindex Tables, making multi-column + +@code{@@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. + +@menu +* Multitable Column Widths:: Defining multitable column widths. +* Multitable Rows:: Defining multitable rows, with examples. +@end menu + +@node Multitable Column Widths +@subsection Multitable Column Widths +@cindex Multitable column widths +@cindex Column widths, defining for multitables +@cindex 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. + +@enumerate +@item +@findex columnfractions +@cindex Line length, column widths as fraction of +To specify column widths as fractions of the line length, write +@code{@@columnfractions} and the decimal numbers (presumably less than +1; a leading zero is allowed and ignored) after the +@code{@@multitable} command, as in: + +@example +@@multitable @@columnfractions .33 .33 .33 +@end 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. + +@item +@cindex 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: + +@example +@@multitable @{some text for column one@} @{for column two@} +@end example + +@noindent +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. + +@end enumerate + + +@node Multitable Rows +@subsection Multitable Rows + +@cindex Multitable rows +@cindex Rows, of a multitable + +@findex item +@findex tab +After the @code{@@multitable} command defining the column widths (see +the previous section), you begin each row in the body of a multitable +with @code{@@item}, and separate the column entries with @code{@@tab}. +Line breaks are not special within the table body, and you may break +input lines in your source file as necessary. + +@findex headitem +@cindex Heading row, in table +@cindex @code{<thead>} HTML/XML tag +You can also use @code{@@headitem} instead of @code{@@item} to produce +a @dfn{heading row}. The @TeX{} output for such a row is in bold, and +the HTML and Docbook output uses the @code{<thead>} tag. In Info, the +heading row is followed by a separator line made of dashes (@samp{-} +characters). + +@findex headitemfont +@cindex 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 +@cite{XEmacs User's Manual}, @pxref{Split Window,, Splitting Windows, +emacs, XEmacs User's Manual}): + +@example +@@multitable @@columnfractions .15 .45 .4 +@@headitem Key @@tab Command @@tab Description +@@item C-x 2 +@@tab @@code@{split-window-vertically@} +@@tab Split the selected window into two windows, +with one above the other. +@@item C-x 3 +@@tab @@code@{split-window-horizontally@} +@@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 +@end example + +@noindent produces: + +@multitable @columnfractions .15 .45 .4 +@headitem Key @tab Command @tab Description +@item C-x 2 +@tab @code{split-window-vertically} +@tab Split the selected window into two windows, +with one above the other. +@item C-x 3 +@tab @code{split-window-horizontally} +@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 + + +@node Special Displays +@chapter Special Displays +@cindex 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. + +@menu +* Floats:: Figures, tables, and the like. +* Images:: Including graphics and images. +* Footnotes:: Writing footnotes. +@end menu + + +@node Floats +@section Floats +@cindex 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. + +@cindex 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} (@pxref{@t{@@group}}). + +@menu +* @t{@@float}:: Producing floating material. +* @t{@@caption @@shortcaption}:: Specifying descriptions for floats. +* @t{@@listoffloats}:: A table of contents for floats. +@end menu + + +@node @t{@@float} +@subsection @code{@@float} [@var{type}][,@var{label}]: Floating Material + +@anchor{float}@c old name +@findex float +@cindex 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: + +@example +@@float Figure,fig:ex1 +This is an example float. +@@end float +@end example + +@noindent And the output: + +@float Figure,fig:ex1 +This is an example float. +@end float + +As shown in the example, @code{@@float} takes two arguments (separated +by a comma), @var{type} and @var{label}. Both are optional. + +@table @var +@item 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. + +@item label +Specifies a cross reference label for this float. If given, this +float is automatically given a number, and will appear in any +@code{@@listoffloats} output (@pxref{@t{@@listoffloats}}). Cross +references to @var{label} are allowed. + +@cindex Floats, making unnumbered +@cindex Unnumbered float, creating +On the other hand, if @var{label} is not given, then the float will +not be numbered and consequently will not appear in the +@code{@@listoffloats} output or be cross-referenceable. +@end table + +@noindent Ordinarily, you specify both @var{type} and @var{label}, to get a +labeled and numbered float. + +@cindex Floats, numbering of +@cindex Numbering of floats +In Texinfo, all floats are numbered in the same way: with the chapter +number (or appendix letter), a period, and the float number, which +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. + + +@node @t{@@caption @@shortcaption} +@subsection @code{@@caption} & @code{@@shortcaption} + +@anchor{caption shortcaption}@c old name +@findex caption +@findex shortcaption +@cindex Captions, for floats +@cindex 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: + +@example +@@float +An example float, with caption. +@@caption@{Caption for example float.@} +@@end float +@end example + +@noindent The output is: + +@float +An example float, with caption. +@caption{Caption for example float.} +@end float + +@code{@@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 +@code{@@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: + +@example +@@float +... as above ... +@@shortcaption@{Text for list of floats.@} +@@end float +@end example + +The text for @code{@@shortcaption} may not contain comments +(@code{@@c}), verbatim text (@code{@@verb}), environments such as +@code{@@example}, footnotes (@code{@@footnote}) or other complex +constructs. The same constraints apply to @code{@@caption} unless +there is an @code{@@shortcaption}. + + +@node @t{@@listoffloats} +@subsection @code{@@listoffloats}: Tables of Contents for Floats + +@anchor{listoffloats}@c old name +@findex listoffloats +@cindex List of floats +@cindex Floats, list of +@cindex Table of contents, for floats + +You can write an @code{@@listoffloats} command to generate a list of +floats for a given float type (@pxref{@t{@@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}). + +@code{@@listoffloats} takes one optional argument, the float type. +Here's an example: + +@example +@@node List of Figures +@@unnumbered List of Figures +@@listoffloats Figure +@end example + +@noindent And the output from @code{@@listoffloats}: + +@display +@listoffloats Figure +@end 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 +@code{@@float} command (@pxref{@t{@@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. + + +@node Images +@section Inserting Images + +@cindex Images, inserting +@cindex Pictures, inserting +@findex image + +You can insert an image given in an external file with the +@code{@@image} command. 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. + +@menu +* Image Syntax:: +* Image Scaling:: +@end menu + + +@node Image Syntax +@subsection Image Syntax + +Here is the synopsis of the @code{@@image} command: + +@example +@@image@{@var{filename}@r{[,} @var{width}@r{[,} @var{height}@r{[,} @var{alttext}@r{[, }@var{extension}@r{]]]]}@} +@end example + +@cindex Formats for images +@cindex Image formats +The @var{filename} argument is mandatory, and must not have an +extension, because the different processors support different formats: + +@itemize @bullet +@item +@pindex eps image format +@TeX{} (DVI output) reads the file @file{@var{filename}.eps} +(Encapsulated PostScript format). + +@item +@pindex pdftex@r{, and images} +@pindex png image format +@pindex jpeg image format +@pindex pdf image inclusions +pdf@TeX{} reads @file{@var{filename}.pdf}, @file{@var{filename}.png}, +@file{@var{filename}.jpg}, or @file{@var{filename}.jpeg} (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. + +@item +For Info, @code{makeinfo} includes @file{@var{filename}.txt} verbatim +(more or less as if it were in @code{@@verbatim}). The Info output +may also include a reference to @file{@var{filename}.png} or +@file{@var{filename}.jpg}. (See below.) + +@item +For HTML, @code{makeinfo} outputs a reference to +@file{@var{filename}.png}, @file{@var{filename}.jpg}, +@file{@var{filename}.jpeg} or @file{@var{filename}.gif} (in that +order). If none of those exist, it gives an error, and outputs a +reference to @file{@var{filename}.jpg} anyway. + +@item +@cindex SVG images, used in Docbook +For Docbook, @code{makeinfo} outputs references to +@file{@var{filename}.eps}, @file{@var{filename}.gif} +@file{@var{filename}.jpeg}, @file{@var{filename}.jpg}, +@file{@var{filename}.pdf}, @file{@var{filename}.png} and +@file{@var{filename}.svg}, for every file found. Also, +@file{@var{filename}.txt} is included verbatim, if present. (The +subsequent Docbook processor is supposed to choose the appropriate one.) + +@item +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: + +@pindex XPM image format +@example +@@image@{foo,,,,.xpm@} +@end example + +@end itemize + +If you want to install image files for use by Info readers too, we +recommend putting them in a subdirectory like @samp{@var{foo}-figures} +for a package @var{foo}. Copying the files into +@code{$(infodir)/@var{foo}-figures/} should be done in your +@code{Makefile}. + +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} +(@pxref{@t{@@titlefont @@center @@sp}}). + +@cindex Alt attribute for images +@cindex Images, alternate text for +@findex - (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 +@code{@@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 +@samp{<} 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; @pxref{@t{@@- @@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 +@samp{"} 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 @file{@var{extension}}, +@file{@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 +XEmacs 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. + +@cindex @samp{^@@^H} for images in Info +The implementation of this is to put the following construct into the +Info output: + +@example +^@@^H[image src="@var{binaryfile}" text="@var{txtfile}" + alt="@var{alttext} ... ^@@^H] +@end example + +@noindent 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. + + +@node Image Scaling +@subsection Image Scaling + +@cindex Images, scaling +@cindex Scaling images +@cindex Width of images +@cindex Height of images +@cindex Aspect ratio of images +@cindex Distorting images +The optional @var{width} and @var{height} arguments to the +@code{@@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. + +@cindex Dimensions and image sizes +The @var{width} and @var{height} may be specified using any valid @TeX{} +dimension, namely: + +@table @asis +@item pt +@cindex Points (dimension) +point (72.27pt = 1in) +@item pc +@cindex Picas +pica (1pc = 12pt) +@item bp +@cindex Big points +big point (72bp = 1in) +@item in +@cindex Inches +inch +@item cm +@cindex Centimeters +centimeter (2.54cm = 1in) +@item mm +@cindex Millimeters +millimeter (10mm = 1cm) +@item dd +@cindex Did@^ot points +did@^ot point (1157dd = 1238pt) +@item cc +@cindex Ciceros +cicero (1cc = 12dd) +@item sp +@cindex Scaled points +scaled point (65536sp = 1pt) +@end table + +@pindex ridt.eps +For example, the following will scale a file @file{ridt.eps} to one +inch vertically, with the width scaled proportionately: + +@example +@@image@{ridt,,1in@} +@end example + +@pindex epsf.tex +For @code{@@image} to work with @TeX{}, the file @file{epsf.tex} must be +installed somewhere that @TeX{} can find it. (The standard location is +@file{@var{texmf}/tex/generic/dvips/epsf.tex}, where @var{texmf} is a +root of your @TeX{} directory tree.) This file is included in the +Texinfo distribution and is also available from +@uref{ftp://tug.org/tex/epsf.tex}, among other places. + +@code{@@image} can be used within a line as well as for displayed +figures. Therefore, if you intend it to be displayed, be sure to leave +a blank line before the command, or the output will run into the +preceding text. + +Image scaling is presently implemented only in @TeX{}, not in HTML or +any other sort of output. + + +@node Footnotes +@section Footnotes +@cindex Footnotes +@findex footnote + +A @dfn{footnote} is for a reference that documents or elucidates the +primary text.@footnote{A footnote should complement or expand upon the +primary text, but a reader should not need to read a footnote to +understand the primary text. For a thorough discussion of footnotes, +see @cite{The Chicago Manual of Style}, which is published by the +University of Chicago Press.} 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. + +@menu +* Footnote Commands:: How to write a footnote in Texinfo. +* Footnote Styles:: Controlling how footnotes appear in Info. +@end menu + + +@node Footnote Commands +@subsection Footnote Commands + +In Texinfo, footnotes are created with the @code{@@footnote} command. +This command is followed immediately by a left brace, then by the text +of the footnote, and then by a terminating right brace. Footnotes may +be of any length (they will be broken across pages if necessary), but +are usually short. The template is: + +@example +ordinary text@@footnote@{@var{text of footnote}@} +@end example + +As shown here, the @code{@@footnote} command should come right after the +text being footnoted, with no intervening space; otherwise, the footnote +marker might end up starting a line. + +For example, this clause is followed by a sample footnote@footnote{Here +is the sample footnote.}; in the Texinfo source, it looks like +this: + +@example +@dots{}a sample footnote@@footnote@{Here is the sample +footnote.@}; in the Texinfo source@dots{} +@end example + +As you can see, the source includes two punctuation marks next to each +other; in this case, @samp{.@};} 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}. + + +@node Footnote Styles +@subsection Footnote Styles + +Info has two footnote styles, which determine where the text of the +footnote is located: + +@itemize @bullet +@cindex @samp{@r{End}} node footnote style +@item +In the `End' node style, all the footnotes for a single node are +placed at the end of that node. The footnotes are separated from the +rest of the node by a line of dashes with the word @samp{Footnotes} +within it. Each footnote begins with an @samp{(@var{n})} reference +mark. + +@need 700 +@noindent +Here is an example of the Info output for a single footnote in the +end-of-node style: + +@example +@group +--------- Footnotes --------- + +(1) Here is a sample footnote. +@end group +@end example + +@cindex @samp{@r{Separate}} footnote style +@item +In the `Separate' node style, all the footnotes for a single +node are placed in an automatically constructed node of +their own. In this style, a ``footnote reference'' follows +each @samp{(@var{n})} reference mark in the body of the +node. The footnote reference is actually a cross reference +which you use to reach the footnote node. + +The name of the node with the footnotes is constructed +by appending @w{@samp{-Footnotes}} to the name of the node +that contains the footnotes. (Consequently, the footnotes' +node for the @file{Footnotes} node is +@w{@file{Footnotes-Footnotes}}!) The footnotes' node has an +`Up' node pointer that leads back to its parent node. + +@noindent +Here is how the first footnote in this manual looks after being +formatted for Info in the separate node style: + +@smallexample +@group +File: texinfo.info Node: Overview-Footnotes, Up: Overview + +(1) The first syllable of "Texinfo" is pronounced like "speck", not +"hex". @dots{} +@end group +@end smallexample +@end itemize + +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. + +@findex footnotestyle +Use the @code{@@footnotestyle} command to specify an Info file's +footnote style. Write this command at the beginning of a line followed +by an argument, either @samp{end} for the end node style or +@samp{separate} for the separate node style. + +@need 700 +For example, + +@example +@@footnotestyle end +@end example +@noindent +or +@example +@@footnotestyle separate +@end example + +Write an @code{@@footnotestyle} command before or shortly after the +end-of-header line at the beginning of a Texinfo file. (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 +@samp{separate}, and the output is split, they are placed in a +separate file. + + +@node Indices +@chapter Indices +@cindex 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. + +@xref{Printing Indices & Menus}, for information on how to print +indices. + +@menu +* 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. +@end menu + + +@node Index Entries +@section Making Index Entries +@cindex Index entries, making +@cindex 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 +@emph{do 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. + +@xref{Printing Indices & Menus}, for information about printing an +index at the end of a book or creating an index menu in an Info file. + + +@node Predefined Indices +@section Predefined Indices + +Texinfo provides six predefined indices. Here are their nominal +meanings, abbreviations, and the corresponding index entry commands: + +@table @samp +@item cp +@cindex @code{cp} (concept) index +@findex cindex +(@code{@@cindex}) concept index, for general concepts. +@item fn +@cindex @code{fn} (function) index +@findex findex +(@code{@@findex}) function index, for function and function-like +names (such as entry points of libraries). +@item ky +@cindex @code{ky} (keystroke) index +@findex kindex +(@code{@@kindex}) keystroke index, for keyboard commands. +@item pg +@cindex @code{pg} (program) index +@findex pindex +(@code{@@pindex}) program index, for names of programs. +@item tp +@cindex @code{tp} (data type) index +@findex tindex +(@code{@@tindex}) data type index, for type names (such as structures +defined in header files). +@item vr +@cindex @code{vr} (variable) index +@findex vindex +(@code{@@vindex}) variable index, for variable names (such as global +variables of libraries). +@end table + +@noindent +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 +@code{@@syncodeindex} commands (@pxref{Combining Indices}). + + +@node Indexing Commands +@section Defining the Entries of an Index + +@cindex Defining indexing entries +@cindex Index entries +@cindex Entries for an index +@cindex Specifying index entries +@cindex 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: + +@example +@@cindex Defining indexing entries +@@cindex Index entries, defining +@@cindex Entries for an index +@@cindex Specifying index entries +@@cindex Creating index entries +@end example + +Each predefined index has its own indexing command---@code{@@cindex} +for the concept index, @code{@@findex} for the function index, and so +on, as listed in the previous section. + +@cindex Writing index entries +@cindex Index entries, advice on writing +@cindex Advice on writing entries +@cindex 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. + +@cindex 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: + +@example +@@cindex hello +Hello, there! +@end example + +@noindent Among other reasons, that way following indexing links (in +whatever context) ends up before the material, where readers want to +be, instead of after. + +@cindex 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 +@code{@@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}). + +@quotation 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. +@end quotation + + +@node Combining Indices +@section Combining Indices +@cindex Combining indices +@cindex 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 +@code{@@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 +@code{@@code}. + +@menu +* @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. +@end menu + + +@node @t{@@syncodeindex} +@subsection @code{@@syncodeindex}: Combining indices using @code{@@code} + +@anchor{syncodeindex}@c old name +@findex 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: + +@example +@@syncodeindex @var{from} @var{to} +@end example + +@cindex Predefined names for indices +@cindex Two letter names for indices +@cindex Indices, two letter names +@cindex Names for indices +For this purpose, the indices are given two-letter names: + +@table @samp +@item cp +concept index +@item fn +function index +@item vr +variable index +@item ky +key index +@item pg +program index +@item tp +data type index +@end 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: + +@example +@@syncodeindex fn cp +@end example + +@noindent +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: + +@example +@group +@@syncodeindex vr cp +@@syncodeindex fn cp +@end group +@end example + +@cindex 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 +@code{@@code} font as you would expect. + + +@node @t{@@synindex} +@subsection @code{@@synindex}: Combining indices + +@anchor{synindex}@c old name +@findex synindex + +The @code{@@synindex} command is nearly the same as the +@code{@@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. + +@xref{Printing Indices & Menus}, for information about printing an index +at the end of a book or creating an index menu in an Info file. + + +@node New Indices +@section Defining New Indices + +@cindex Defining new indices +@cindex Indices, defining new +@cindex New index defining +@findex defindex +@findex 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: + +@example +@@defindex @var{name} +@end example + +New index names are usually two-letter words, such as @samp{au}. +For example: + +@example +@@defindex au +@end 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. + +@example +@@section Cognitive Semantics +@@cindex kinesthetic image schemas +@@auindex Johnson, Mark +@@auindex Lakoff, George +@end example + +@noindent +(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: + +@example +@group +@@node Author Index +@@unnumbered Author Index + +@@printindex au +@end group +@end example + +The @code{@@defcodeindex} is like the @code{@@defindex} command, +except that, in the printed output, it prints entries in an +@code{@@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 +@code{@@syncodeindex} commands (@pxref{Texinfo File Header}). + +As mentioned earlier (@pxref{Predefined Indices}), we recommend having +a single index in the final document whenever possible, 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}. +@command{makeinfo} already reports an error if a new index conflicts +well-known extension name. + + +@node Insertions +@chapter Special Insertions +@cindex Inserting special characters and symbols +@cindex 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. + +@iftex +These are: + +@itemize @bullet +@item The Texinfo special characters: @samp{@@ @{@} , \ #}. +@item Whitespace within and around a sentence. +@item Accents. +@item Dots and bullets. +@item The @TeX{} logo and the copyright symbol. +@item The euro and pounds currency symbols. +@item The degrees symbol. +@item The minus sign. +@item Mathematical expressions. +@item Glyphs for examples of programming: evaluation, macros, errors, etc. +@item Footnotes. +@end itemize +@end iftex + +@menu +* Special Characters:: Inserting @@ @{@} , \ # +* 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. +@end menu + + +@node Special Characters +@section Special Characters: Inserting @@ @{@} , \ # +@anchor{Braces Atsign}@c previous names for this node +@anchor{Atsign Braces Comma} +@cindex Special characters, inserting +@cindex Commands to insert special characters + +@samp{@@} 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. + +@menu +* Inserting an Atsign:: @code{@@@@}, @code{@@atchar@{@}}. +* Inserting Braces:: @code{@@@{ @@@}}, @code{@@l rbracechar@{@}}. +* Inserting a Comma:: , and @code{@@comma@{@}}. +* Inserting a Backslash:: \ and @code{@@backslashchar@{@}}. +* Inserting a Hashsign:: # and @code{@@hashchar@{@}}. +@end menu + + +@node Inserting an Atsign +@subsection Inserting `@@' with @code{@@@@} and @code{@@atchar@{@}} +@cindex At sign, inserting +@cindex Inserting @@ @r{(literal @samp{@@})} +@findex @@ @r{(literal @samp{@@})} +@findex @@atchar@{@} @r{(literal @samp{@@})} + +@code{@@@@} produces a single @samp{@@} character in the output. Do +not put braces after an @code{@@@@} command. + +@code{@@atchar@{@}} 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). + + +@node Inserting Braces +@subsection Inserting `@{ `@}' with @code{@@@{ @@@}} and @code{@@l rbracechar@{@}} + +@findex @{ @r{(literal @samp{@{})} +@findex @} @r{(literal @samp{@}})} +@findex @@lbracechar@{@} @r{(literal @samp{@{})} +@findex @@rbracechar@{@} @r{(literal @samp{@}})} +@cindex Braces, inserting + +@code{@@@{} produces a single @samp{@{} in the output, and @code{@@@}} +produces a single @samp{@}}. Do not put braces after either an +@code{@@@{} or an @code{@@@}} command. + +@code{@@lbracechar@{@}} and @code{@@rbracechar@{@}} also produce +single @samp{@{} and @samp{@}} 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). + + +@node Inserting a Comma +@subsection Inserting `,' with @code{@@comma@{@}} + +@findex comma +@cindex 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 +@code{@@acronym} (@pxref{@t{@@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{@@comma@{@}} instead if you want +to pass an actual comma. Here are some examples: + +@example +@@acronym@{ABC, A Bizarre @@comma@{@}@} +@@xref@{Comma,, The @@comma@{@} symbol@} +@@mymac@{One argument@@comma@{@} containing a comma@} +@end example + +Although @samp{@@comma@{@}} 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.) + + +@node Inserting a Backslash +@subsection Inserting `\' with @code{@@backslashchar@{@}} + +@findex backslash +@cindex 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{@@backslashchar@{@}}. Here is an example +macro call: + +@example +@@mymac@{One argument@@backslashchar@{@} with a backslash@} +@end example + +Texinfo documents may also use \ as a command character inside +@code{@@math} (@pxref{Inserting Math}). In this case, @code{@@\} or +@code{\backslash} produces a ``math'' backslash (from the math symbol +font), while @code{@@backslashchar@{@}} produces a typewriter +backslash as usual. + +Although @samp{@@backslashchar@{@}} can be used nearly anywhere, there +is no need for it except in these unusual cases. + + +@node Inserting a Hashsign +@subsection Inserting `#' with @code{@@hashchar@{@}} + +@findex @@hashchar@{@} @r{(literal @samp{#})} +@cindex Inserting # +@cindex 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. + +@cindex Number sign, inserting +@cindex Octotherp, inserting +@cindex 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{@@hashchar@{@}} or some other construct. +Here's an example: + +@example +@@hashchar@{@} 10 "example.c" +@end example + +Although @samp{@@hashchar@{@}} can be used nearly anywhere, there +is no need for it anywhere except this unusual case. + + +@node Inserting Quote Characters +@section Inserting Quote Characters + +@cindex Inserting quote characters +@cindex Quote characters, inserting + +As explained in the early section on general Texinfo input conventions +(@pxref{Conventions}), Texinfo source files use the ASCII character +@code{`} (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: + +@ftable @code +@item @@codequoteundirected @var{on-off} +@cindex undirected single quote +causes the output for the @code{'} character in code environments to +be the undirected single quote, like this: +@set txicodequoteundirected on +@code{'}. +@set txicodequoteundirected off + +@item @@codequotebacktick @var{on-off} +@cindex backtick +@cindex grave accent, standalone +causes the output for the @code{`} character in code environments to +be the backtick character (standalone grave accent), like this: +@set txicodequotebacktick on +@code{`}. +@set txicodequotebacktick off +@end ftable + +If you want these settings for only part of the document, +@code{@@codequote... off} will restore the normal behavior, as in +@code{@@codequoteundirected off}. + +These settings affect @code{@@code}, @code{@@example}, @code{@@kbd}, +@code{@@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. + + +@node Inserting Space +@section Inserting Space + +@cindex Inserting space +@cindex Spacing, inserting +The following sections describe commands that control spacing of various +kinds within and after sentences. + +@menu +* 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. +@end menu + + +@node Multiple Spaces +@subsection Multiple Spaces + +@cindex Multiple spaces +@cindex Whitespace, inserting +@cindex Space, inserting horizontal +@findex <space> +@findex <tab> +@findex <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: +@code{@@@kbd{SPACE}}, @code{@@@kbd{TAB}}, and @code{@@@kbd{NL}}, all +of which insert a single space into the output. (Here, +@code{@@@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 +@samp{@@} is the last character on a line.) + +For example, +@example +Spacey@@ @@ @@ @@ +example. +@end example + +@noindent produces + +@example +Spacey@ @ @ @ +example. +@end example + +Other possible uses of @code{@@@kbd{SPACE}} have been subsumed by +@code{@@multitable} (@pxref{Multi-column Tables}). + +Do not follow any of these commands with braces. + +To produce a non-breakable space, see @ref{@t{@@tie}}. + + +@node Not Ending a Sentence +@subsection Not Ending a Sentence + +@cindex Not ending a sentence +@cindex Sentence non-ending punctuation +@cindex Periods, inserting +@cindex 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. + +@findex <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, +@code{@@:} should be used after the right parenthesis. Similarly for +right brackets and right quotes (both single and double). + +For example, + +@example +foo vs.@@: bar (or?)@@: baz +foo vs. bar (or?) baz +@end example + +@noindent +@ifnottex +produces +@end ifnottex +@iftex +produces the following. If you look carefully at this printed output, +you will see a bit of extraneous space after the @samp{vs.}@: and +@samp{(or?)}@: in the second line. +@end iftex + +@quotation +foo vs.@: bar (or?)@: baz@* +foo vs. bar (or?) baz +@end quotation + +@noindent +@code{@@:} 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 +@code{@@acronym} (@pxref{Useful Highlighting}). For example, in +@samp{@@code@{foo. bar@}} the period is not considered the end of a +sentence, and no extra space is inserted. + + +@node Ending a Sentence +@subsection Ending a Sentence + +@cindex Ending a Sentence +@cindex Sentence ending punctuation + +@findex . @r{(end of sentence)} +@findex ! @r{(end of sentence)} +@findex ? @r{(end of sentence)} +@cindex 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 +@emph{not} 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: + +@example +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. +@end example + +@noindent +The output follows. In printed output and Info, you can see the +desired extra whitespace after the @samp{W} in the first line. + +@quotation +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. +@end 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 XEmacs sentence motion commands +(@pxref{Sentences,,, xemacs, XEmacs User's 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{@@code@{@@@@TeX@}.}; @code{@@.} was not needed. Also +in @code{... @@var@{VARNAME@}. Text} the period after @var{VARNAME} +ends the sentence; there is no need to use @code{@@.}. + + +@node @t{@@frenchspacing} +@subsection @code{@@frenchspacing} @var{val}: Control Sentence Spacing + +@anchor{frenchspacing}@c old name +@findex frenchspacing +@cindex French spacing +@cindex Sentences, spacing after +@cindex 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: + +@example +@@frenchspacing on +This is text. Two sentences. Three sentences. French spacing. + +@@frenchspacing off +This is text. Two sentences. Three sentences. Non-French spacing. +@end example + +@noindent produces: + +@frenchspacing on +This is text. Two sentences. Three sentences. French spacing. + +@frenchspacing off +This is text. Two sentences. Three sentences. Non-French spacing. + +@code{@@frenchspacing} also affects the output after @code{@@.}, +@code{@@!}, and @code{@@?} (@pxref{Ending a Sentence}). + +@code{@@frenchspacing} has no effect on the HTML or Docbook output; +for XML, it outputs a transliteration of itself (@pxref{Output +Formats}). + + +@node @t{@@dmn} +@subsection @code{@@dmn}@{@var{dimension}@}: Format a Dimension + +@anchor{dmn}@c old name +@cindex Thin space between number, dimension +@cindex Dimension formatting +@cindex Format a dimension +@findex 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 +@code{@@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, + +@example +A4 paper is 8.27@@dmn@{in@} wide. +@end example + +@noindent +produces + +@quotation +A4 paper is 8.27@dmn{in} wide. +@end quotation + +Not everyone uses this style. Some people prefer `8.27@tie{}in.'@: or +`8.27@tie{}inches'. In these cases, however, you need to use +@code{@@tie} (@pxref{@t{@@tie}}) or @code{@@w} (@pxref{@t{@@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}. + + +@node Inserting Accents +@section Inserting Accents + +@cindex Inserting accents +@cindex Accents, inserting +@cindex 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{@@'@{e@}}), 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). + +@findex 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 +(@pxref{@t{@@documentencoding}}). In this case, you can also use +non-ASCII (e.g., pre-accented) characters in the source file. + +@findex " @r{(umlaut accent)} +@cindex Umlaut accent +@findex ' @r{(umlaut accent)} +@cindex Acute accent +@findex = @r{(macron accent)} +@cindex Macron accent +@findex ^ @r{(circumflex accent)} +@cindex Circumflex accent +@findex ` @r{(grave accent)} +@cindex Grave accent +@findex ~ @r{(tilde accent)} +@cindex Tilde accent +@findex , @r{(cedilla accent)} +@cindex Cedilla accent +@findex dotaccent +@cindex Dot accent +@findex H @r{(Hungarian umlaut accent)} +@cindex Hungarian umlaut accent +@findex ogonek +@cindex Ogonek diacritic +@findex ringaccent +@cindex Ring accent +@findex tieaccent +@cindex Tie-after accent +@findex u @r{(breve accent)} +@cindex Breve accent +@findex ubaraccent +@cindex Underbar accent +@findex udotaccent +@cindex Underdot accent +@findex v @r{(check accent)} +@cindex Hacek accent +@cindex Check accent +@cindex Caron accent +@multitable {@t{@@questiondown@{@}}} {Output} {hacek/check/caron accent} +@headitem Command @tab Output @tab What +@item @t{@@"o} @tab @"o @tab umlaut accent +@item @t{@@'o} @tab @'o @tab acute accent +@item @t{@@,@{c@}} @tab @,{c} @tab cedilla accent +@item @t{@@=o} @tab @=o @tab macron/overbar accent +@item @t{@@^o} @tab @^o @tab circumflex accent +@item @t{@@`o} @tab @`o @tab grave accent +@item @t{@@~o} @tab @~o @tab tilde accent +@item @t{@@dotaccent@{o@}} @tab @dotaccent{o} @tab overdot accent +@item @t{@@H@{o@}} @tab @H{o} @tab long Hungarian umlaut +@item @t{@@ogonek@{a@}} @tab @ogonek{a} @tab ogonek +@item @t{@@ringaccent@{o@}} @tab @ringaccent{o} @tab ring accent +@item @t{@@tieaccent@{oo@}} @tab @tieaccent{oo} @tab tie-after accent +@item @t{@@u@{o@}} @tab @u{o} @tab breve accent +@item @t{@@ubaraccent@{o@}} @tab @ubaraccent{o} @tab underbar accent +@item @t{@@udotaccent@{o@}} @tab @udotaccent{o} @tab underdot accent +@item @t{@@v@{o@}} @tab @v{o} @tab hacek/check/caron accent +@end multitable + +This table lists the Texinfo commands for inserting other characters +commonly used in languages other than English. + +@findex questiondown +@cindex @questiondown{} +@findex exclamdown +@cindex @exclamdown{} +@findex aa +@cindex @aa{} +@findex AA +@cindex @AA{} +@findex ae +@cindex @ae{} +@findex AE +@cindex @AE{} +@cindex Icelandic +@cindex Eth +@findex dh +@cindex @dh{} +@findex DH +@cindex @DH{} +@findex dotless +@cindex @dotless{i} (dotless i) +@cindex @dotless{j} (dotless j) +@cindex Dotless i, j +@findex l +@cindex @l{} +@findex L +@cindex @L{} +@findex o +@cindex @o{} +@findex O +@cindex @O{} +@findex oe +@cindex @oe{} +@findex OE +@cindex @OE{} +@cindex Romance ordinals +@cindex Ordinals, Romance +@cindex Feminine ordinal +@findex ordf +@cindex @ordf{} +@cindex Masculine ordinal +@findex ordm +@cindex @ordm{} +@findex ss +@cindex @ss{} +@cindex Es-zet +@cindex Sharp S +@cindex German S +@cindex Thorn +@findex th +@cindex @th{} +@findex TH +@cindex @TH{} +@multitable {@t{@@questiondown@{@}}} {oe OE} {es-zet or sharp S} +@item @t{@@exclamdown@{@}} @tab @exclamdown{} @tab upside-down ! +@item @t{@@questiondown@{@}} @tab @questiondown{} @tab upside-down ? +@item @t{@@aa@{@} @@AA@{@}} @tab @aa{} @AA{} @tab a,A with circle +@item @t{@@ae@{@} @@AE@{@}} @tab @ae{} @AE{} @tab ae,AE ligatures +@item @t{@@dh@{@} @@DH@{@}} @tab @dh{} @DH{} @tab Icelandic eth +@item @t{@@dotless@{i@}} @tab @dotless{i} @tab dotless i +@item @t{@@dotless@{j@}} @tab @dotless{j} @tab dotless j +@item @t{@@l@{@} @@L@{@}} @tab @l{} @L{} @tab suppressed-L,l +@item @t{@@o@{@} @@O@{@}} @tab @o{} @O{} @tab O,o with slash +@item @t{@@oe@{@} @@OE@{@}} @tab @oe{} @OE{} @tab oe,OE ligatures +@item @t{@@ordf@{@} @@ordm@{@}} @tab @ordf{} @ordm{} @tab Spanish ordinals +@item @t{@@ss@{@}} @tab @ss{} @tab es-zet or sharp S +@item @t{@@th@{@} @@TH@{@}} @tab @th{} @TH{} @tab Icelandic thorn +@end multitable + + +@node Inserting Quotation Marks +@section Inserting Quotation Marks +@cindex Inserting quotation marks +@cindex Quotation marks, inserting + +@cindex Quotation characters (`'), in source +Use doubled single-quote characters to begin and end quotations: +@w{@t{`@w{}`@dots{}'@w{}'}}. @TeX{} converts two single quotes to +left- and right-hand doubled quotation marks, +@c this comes out as "like this" in Info, which is just confusing. +@iftex +``like this'', +@end iftex +and Info converts doubled single-quote characters to ASCII +double-quotes: @w{@t{`@w{}`@dots{}'@w{}'}} becomes @w{@t{"@dots{}"}}. + +You may occasionally need to produce two consecutive single quotes; +for example, in documenting a computer language such as Maxima where +@t{'@w{}'} is a valid command. You can do this with the input +@t{'@@w@{@}'}; the empty @code{@@w} command stops the combination into +the double-quote characters. + +@cindex Unicode quotation characters +@cindex 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. + +@findex documentencoding +@cindex UTF-8 +@cindex ISO 8859-15 +@cindex Latin 9 +@cindex ISO 8859-1 +@cindex 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}. +(@xref{@t{@@documentencoding}}.) Double guillemets are also +present in ISO 8859-1 (aka Latin@tie{}1) and ISO 8859-15 (aka +Latin@tie{}9). + +@cindex European Computer Modern fonts +@cindex EC fonts +The standard @TeX{} fonts support the usual quotation marks used in +English (the ones produced with single and doubled ASCII +single-quotes). For the other quotation marks, @TeX{} uses European +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. + +@cindex CM-Super fonts +The free EC fonts are bitmap fonts created with Metafont. Especially +for on-line viewing, Type@tie{}1 (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. + +@cindex Single quotation marks +@cindex Double quotation marks +@cindex Left quotation marks +@cindex Right quotation marks +@findex quotedblleft +@cindex `@w{}` +@findex quoteleft +@cindex ` +@cindex " (undirected double quote character) +@findex quotedblright +@cindex '@w{}' +@findex quoteright +@cindex ' +@cindex Double low-9 quotation mark +@cindex Single low-9 quotation mark +@findex quotedblbase +@cindex @quotedblbase{} (double low-9 quotation mark) +@findex quotesinglbase +@cindex @quotesinglbase{} (single low-9 quotation mark) +@cindex Angle quotation marks +@cindex Guillemets +@cindex Guillemots +@cindex French quotation marks +@cindex Quotation marks, French +@cindex German quotation marks +@cindex Quotation marks, German +@cindex Double guillemets +@cindex Single guillemets +@cindex Double angle quotation marks +@cindex Single angle quotation marks +@cindex Left-pointing angle quotation marks +@cindex Right-pointing angle quotation marks +@cindex Double left-pointing angle quotation mark +@cindex Double right-pointing angle quotation mark +@cindex Single left-pointing angle quotation mark +@cindex Single right-pointing angle quotation mark +@findex guillemetleft +@findex guillemotleft +@cindex @guillemetleft{} +@findex guillemetright +@findex guillemotright +@cindex @guillemetright{} +@findex guilsinglleft +@cindex @guilsinglleft{} +@findex guilsinglright +@cindex @guilsinglright{} +@multitable {@t{@@quotedblright@{@} '@w{}'}} {Glyph} {Right-pointing double angle quotation mark (U+00BB)} +@headitem Command @tab Glyph @tab Unicode name (point) +@item @verb{.@quotedblleft{} ``.} @tab @quotedblleft{} @tab Left double quotation mark (U+201C) +@item @verb{.@quotedblright{} ''.} @tab @quotedblright{} @tab Right double quotation mark (U+201D) +@item @verb{.@quoteleft{} `.} @tab @quoteleft{} @tab Left single quotation mark (U+2018) +@item @verb{.@quoteright{} '.} @tab @quoteright{} @tab Right single quotation mark (U+2019) +@item @t{@@quotedblbase@{@}} @tab @quotedblbase{} @tab Double low-9 quotation mark (U+201E) +@item @t{@@quotesinglbase@{@}} @tab @quotesinglbase{} @tab Single low-9 quotation mark (U+201A) +@item @t{@@guillemetleft@{@}} @tab @guillemetleft{} @tab Left-pointing double angle quotation mark (U+00AB) +@item @t{@@guillemetright@{@}} @tab @guillemetright{} @tab Right-pointing double angle quotation mark (U+00BB) +@item @t{@@guilsinglleft@{@}} @tab @guilsinglleft{} @tab Single left-pointing angle quotation mark (U+2039) +@item @t{@@guilsinglright@{@}} @tab @guilsinglright{} @tab Single right-pointing angle quotation mark (U+203A) +@end multitable + +@cindex Auk, bird species +For the double angle quotation marks, Adobe and @LaTeX{} glyph names +are also supported: @code{@@guillemotleft} and +@code{@@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 (@pxref{@t{@@alias}}) can simplify the usage and make the +source code more readable. For example, in German, +@code{@@quotedblbase} is used for the left double quote, and the right +double quote is the glyph produced by @code{@@quotedblleft}, which is +counter-intuitive. Thus, in this case the following aliases would be +convenient: + +@example +@@alias lgqq = quotedblbase +@@alias rgqq = quotedblleft +@end example + + +@node Inserting Math +@section @code{@@math}: Inserting Mathematical Expressions + +@anchor{math}@c old name +@findex math +@cindex Mathematical expressions, inserting +@cindex Formulas, mathematical + +You can write a short mathematical expression with the @code{@@math} +command. Write the mathematical expression between braces, like this: + +@example +@@math@{(a + b)(a + b) = a^2 + 2ab + b^2@} +@end example + +@iftex +@noindent This produces the following in @TeX{}: + +@display +@math{(a + b)(a + b) = a^2 + 2ab + b^2} +@end display + +@noindent and the following in other formats: +@end iftex +@ifnottex +@noindent This produces the following in Info and HTML: +@end ifnottex + +@example +(a + b)(a + b) = a^2 + 2ab + b^2 +@end 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 +@samp{\}, and the plain @TeX{} math characters like @samp{^} and +@samp{_} 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 @samp{k_@{75@}}, although it complains +about such bare braces in regular input. + +Here's an example: + +@example +@@math@{\sin 2\pi \equiv \cos 3\pi@} +@end example + +@iftex +@noindent which looks like this in @TeX{}: +@display +@math{\sin 2\pi \equiv \cos 3\pi} +@end display + +@noindent and +@end iftex +@noindent which looks like the input in Info and HTML: +@example +\sin 2\pi \equiv \cos 3\pi +@end example + +@findex \ @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 +@TeX{}, but you'd get the literal two characters @samp{\\} in Info). +@code{@@\} is not defined outside of @code{@@math}, since a @samp{\} +ordinarily produces a literal (typewriter) @samp{\}. You can also use +@code{@@backslashchar@{@}} in any mode to get a typewriter backslash. +@xref{Inserting a Backslash}. + +@cindex Displayed equations +@cindex Equations, displayed +For displayed equations, you must at present use @TeX{} directly +(@pxref{Raw Formatter Commands}). + + +@node Glyphs for Text +@section Glyphs for Text + +@anchor{Glyphs}@c old name +@anchor{TeX and copyright}@c another old node, now split into two +@cindex Glyphs for text +@cindex Textual glyphs + +Texinfo has support for a few additional glyphs that are commonly used +in printed text but not available in ASCII@. 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. + +@menu +* @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. +@end menu + + +@node @t{@@TeX @@LaTeX} +@subsection @code{@@TeX}@{@} (@TeX{}) and @code{@@LaTeX}@{@} (@LaTeX{}) + +@anchor{tex}@c old name +@findex TeX +@findex LaTeX +@cindex Logos, @TeX{} +@cindex @TeX{} logo +@cindex @LaTeX{} logo + +Use the @code{@@TeX@{@}} command to generate `@TeX{}'. 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{@@LaTeX@{@}} command to generate `@LaTeX{}', +which is even more special in printed manuals (and different from the +incorrect @code{La@@TeX@{@}}. In Info, the result is just +@samp{LaTeX}. (@LaTeX{} is another macro package built on top of +@TeX{}, very loosely analogous to Texinfo in that it emphasizes +logical structure, but much (much) larger.) + +The spelling of these commands are unusual for Texinfo, in that they +use both uppercase and lowercase letters. + + +@node @t{@@copyright} +@subsection @code{@@copyright@{@}} (@copyright{}) + +@anchor{copyright symbol}@c old name +@findex copyright +@cindex Copyright symbol + +Use the @code{@@copyright@{@}} command to generate the copyright +symbol, `@copyright{}'. 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. + + +@node @t{@@registeredsymbol} +@subsection @code{@@registeredsymbol@{@}} (@registeredsymbol{}) + +@anchor{registered symbol}@c old name +@findex registeredsymbol +@cindex Registered symbol + +Use the @code{@@registeredsymbol@{@}} command to generate the +registered symbol, `@registeredsymbol{}'. Where possible, this is an +@samp{R} inside a circle; in Info, this is @samp{(R)}. + + +@node @t{@@dots} +@subsection @code{@@dots} (@dots{}) and @code{@@enddots} (@enddots{}) + +@anchor{dots}@c old name +@findex dots +@findex enddots +@cindex Inserting dots +@cindex Inserting ellipsis +@cindex Dots, inserting +@cindex Ellipsis, inserting + +@anchor{Dots Bullets}@c 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{@@dots@{@}} 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{@@enddots@{@}} 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. + + +@node @t{@@bullet} +@subsection @code{@@bullet} (@bullet{}) + +@anchor{bullet}@c old name +@findex bullet + +Use the @code{@@bullet@{@}} 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. +(@pxref{@t{@@itemize}}). + + +@node @t{@@euro} +@subsection @code{@@euro} (@euro{}): Euro Currency Symbol + +@anchor{euro}@c old name +@findex euro +@cindex Euro symbol + +Use the @code{@@euro@{@}} command to generate `@euro{}'. 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.) + +@cindex ISO 8859-15, and Euro +@cindex 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 +@code{@@documentencoding UTF-8} (@xref{@t{@@documentencoding}}.) +The Euro symbol is in ISO 8859-15 (aka Latin@tie{}9), and is +@emph{not} in the more widely-used ISO 8859-1 (Latin@tie{}1). + +@pindex feymr10 +@cindex 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. + + +@node @t{@@pounds} +@subsection @code{@@pounds} (@pounds{}): Pounds Sterling + +@anchor{pounds}@c old name +@findex pounds +@cindex Pounds symbol + +Use the @code{@@pounds@{@}} command to generate `@pounds{}'. Where +possible, this is the symbol for the pounds sterling British currency. +Otherwise, it is @samp{#}. + + +@node @t{@@textdegree} +@subsection @code{@@textdegree} (@textdegree{}): Degrees Symbol + +@anchor{textdegree}@c old name +@findex textdegree +@cindex Degree symbol + +Use the @code{@@textdegree@{@}} command to generate `@textdegree{}'. +Where possible, this is the normal symbol for degrees. Otherwise, +it is an @samp{o}. + + +@node @t{@@minus} +@subsection @code{@@minus} (@minus{}): Inserting a Minus Sign + +@anchor{minus}@c old name +@findex minus +@cindex Minus sign + +@cindex Em dash, compared to minus sign +@cindex Hyphen, compared to minus +Use the @code{@@minus@{@}} 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: + +@display +@samp{@minus{}} is a minus sign generated with @samp{@@minus@{@}}, + +`-' is a hyphen generated with the character @samp{-}, + +`---' is an em-dash for text. +@end display + +@noindent +In the fixed-width font used by Info, @code{@@minus@{@}} is the same +as a hyphen. + +You should not use @code{@@minus@{@}} inside @code{@@code} or +@code{@@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 +(@pxref{@t{@@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{@@math@{a-b@}} (@pxref{Inserting +Math}). + + +@node @t{@@geq @@leq} +@subsection @code{@@geq} (@geq{}) and @code{@@leq} (@leq{}): Inserting Relations + +@anchor{geq leq}@c old name +@findex geq +@findex leq + +Use the @code{@@geq@{@}} and @code{@@leq@{@}} commands to generate +greater-than-or-equal and less-than-equal-signs, `@geq{}' and +`@leq{}'. When those symbols are not available, the ASCII sequences +@samp{>=} and @samp{<=} are output. + + +@node Glyphs for Programming +@section Glyphs for Programming + +@cindex Glyphs for programming +@cindex Examples, glyphs for +@cindex 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 +@code{@@end lisp}. In such examples, you can indicate the results of +evaluation or an expansion using @samp{@result{}} or +@samp{@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. + +@menu +* 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. +@end menu + + +@node Glyphs Summary +@subsection Glyphs Summary + +Here is a summary of the glyph commands: + +@table @asis +@item @result{} +@code{@@result@{@}} indicates the result of an expression. + +@item @expansion{} +@code{@@expansion@{@}} indicates the results of a macro expansion. + +@item @print{} +@code{@@print@{@}} indicates printed output. + +@item @error{} +@code{@@error@{@}} indicates the following text is an error message. + +@item @equiv{} +@code{@@equiv@{@}} indicates the exact equivalence of two forms. + +@item @point{} +@code{@@point@{@}} shows the location of point. + +@item @clicksequence{A @click{} B} +@code{@@clicksequence@{A @@click@{@} B} indicates a GUI operation +sequence: first A, then clicking B, or choosing B from a menu, or +otherwise selecting it. +@end table + + +@node @t{@@result} +@subsection @code{@@result@{@}} (@result{}): Result of an Expression + +@anchor{result}@c old name +@findex result +@cindex Result of an expression +@cindex Indicating evaluation +@cindex Evaluation glyph +@cindex Value of an expression, indicating + +Use the @code{@@result@{@}} command to indicate the result of +evaluating an expression. + +The @code{@@result@{@}} command is displayed as @samp{@result{}}, +either a double stemmed arrow or (when that is not available) the +ASCII sequence @samp{=>}. + +Thus, the following, + +@lisp +(cdr '(1 2 3)) + @result{} (2 3) +@end lisp + +@noindent +may be read as ``@code{(cdr '(1 2 3))} evaluates to @code{(2 3)}''. + + +@node @t{@@expansion} +@subsection @code{@@expansion@{@}} (@expansion{}): Indicating an Expansion + +@anchor{expansion}@c old name +@cindex Expansion, indicating +@cindex Macro expansion, indicating +@findex expansion + +When an expression is a macro call, it expands into a new expression. +You can indicate the result of the expansion with the +@code{@@expansion@{@}} command. + +The @code{@@expansion@{@}} command is displayed as +@samp{@expansion{}}, either a long arrow with a flat base or (when +that is not available) the ASCII sequence @samp{==>}. + +@need 700 +For example, the following + +@example +@group +@@lisp +(third '(a b c)) + @@expansion@{@} (car (cdr (cdr '(a b c)))) + @@result@{@} c +@@end lisp +@end group +@end example + +@noindent +produces + +@lisp +@group +(third '(a b c)) + @expansion{} (car (cdr (cdr '(a b c)))) + @result{} c +@end group +@end lisp + +@noindent +which may be read as: + +@quotation +@code{(third '(a b c))} expands to @code{(car (cdr (cdr '(a b c))))}; +the result of evaluating the expression is @code{c}. +@end quotation + +@noindent +Often, as in this case, an example looks better if the +@code{@@expansion@{@}} and @code{@@result@{@}} commands are indented. + + +@node @t{@@print} +@subsection @code{@@print@{@}} (@print{}): Indicating Generated Output + +@anchor{Print Glyph}@c old name +@findex print +@cindex Printed output, indicating + +Sometimes an expression will generate output during its execution. +You can indicate such displayed output with the @code{@@print@{@}} +command. + +The @code{@@print@{@}} command is displayed as @samp{@print{}}, 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 +@samp{@print{}}, and the value of the expression follows on the +last line. + +@lisp +@group +(progn (print 'foo) (print 'bar)) + @print{} foo + @print{} bar + @result{} bar +@end group +@end lisp + +@noindent +In a Texinfo source file, this example is written as follows: + +@lisp +@group +@@lisp +(progn (print 'foo) (print 'bar)) + @@print@{@} foo + @@print@{@} bar + @@result@{@} bar +@@end lisp +@end group +@end lisp + + +@node @t{@@error} +@subsection @code{@@error@{@}} (@error{}): Indicating an Error Message + +@anchor{Error Glyph}@c old name +@cindex Error message, indicating +@findex error + +A piece of code may cause an error when you evaluate it. You can +designate the error message with the @code{@@error@{@}} command. + +The @code{@@error@{@}} command is displayed as @samp{@error{}}, 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) +@samp{error-->}. + +@need 700 +Thus, + +@example +@@lisp +(+ 23 'x) +@@error@{@} Wrong type argument: integer-or-marker-p, x +@@end lisp +@end example + +@noindent +produces + +@lisp +(+ 23 'x) +@error{} Wrong type argument: integer-or-marker-p, x +@end lisp + +@noindent +This indicates that the following error message is printed +when you evaluate the expression: + +@lisp +Wrong type argument: integer-or-marker-p, x +@end lisp + +The word @samp{@error{}} itself is not part of the error message. + + +@node @t{@@equiv} +@subsection @code{@@equiv@{@}} (@equiv{}): Indicating Equivalence + +@anchor{Equivalence}@c oldname +@cindex Equivalence, indicating +@findex equiv + +Sometimes two expressions produce identical results. You can indicate +the exact equivalence of two forms with the @code{@@equiv@{@}} +command. The @code{@@equiv@{@}} command is displayed as +@samp{@equiv{}}, either a standard mathematical equivalence sign +(three parallel horizontal lines) or (when that is not available) as +the ASCII sequence @samp{==}. + +Thus, + +@example +@@lisp +(make-sparse-keymap) @@equiv@{@} (list 'keymap) +@@end lisp +@end example + +@noindent +produces + +@lisp +(make-sparse-keymap) @equiv{} (list 'keymap) +@end lisp + +@noindent +This indicates that evaluating @code{(make-sparse-keymap)} produces +identical results to evaluating @code{(list 'keymap)}. + + +@node @t{@@point} +@subsection @code{@@point@{@}} (@point{}): Indicating Point in a Buffer + +@anchor{Point Glyph}@c old name +@cindex Point, indicating in a buffer +@findex point + +Sometimes you need to show an example of text in an XEmacs 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{@@point@{@}} 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 +@emph{between} two characters where point is located.) + +The @code{@@point@{@}} command is displayed as @samp{@point{}}, either +a pointed star or (when that is not available) the ASCII sequence +@samp{-!-}. + +The following example shows the contents of buffer @file{foo} before +and after evaluating a Lisp command to insert the word @code{changed}. + +@example +@group +---------- Buffer: foo ---------- +This is the @point{}contents of foo. +---------- Buffer: foo ---------- + +@end group +@end example + +@example +@group +(insert "changed ") + @result{} nil +---------- Buffer: foo ---------- +This is the changed @point{}contents of foo. +---------- Buffer: foo ---------- + +@end group +@end example + +In a Texinfo source file, the example is written like this: + +@example +@@example +---------- Buffer: foo ---------- +This is the @@point@{@}contents of foo. +---------- Buffer: foo ---------- + +(insert "changed ") + @@result@{@} nil +---------- Buffer: foo ---------- +This is the changed @@point@{@}contents of foo. +---------- Buffer: foo ---------- +@@end example +@end example + + +@node Click Sequences +@subsection Click Sequences + +@cindex Click sequences +@cindex Sequence of clicks +@cindex GUI click sequence + +@findex clicksequence +When documenting graphical interfaces, it is necessary to describe +sequences such as `Click on @samp{File}, then choose @samp{Open}, then +@dots{}'. Texinfo offers commands @code{@@clicksequence} and +@code{click} to represent this, typically used like this: + +@example +@dots{} @@clicksequence@{File @@click@{@} Open@} @dots{} +@end example + +@noindent +which produces: + +@display +@dots{} @clicksequence{File @click{} Open} @dots{} +@end display + +@findex click +@findex arrow +The @code{@@click} command produces a right arrow by default; this +glyph is also available independently via the command +@code{@@arrow@{@}}. + +@findex clickstyle +You can change the glyph produced by @code{@@click} with the command +@code{@@clickstyle}, which takes a command name as its single argument +on the rest of the line, much like @code{@@itemize} and friends +(@pxref{@t{@@itemize}}). The command should produce a glyph, and +the usual empty braces @samp{@{@}} are omitted. Here's an example: + +@example +@@clickstyle @@result +@dots{} @@clicksequence@{File @@click@{@} Open@} @dots{} +@end example + +@noindent +now produces: + +@display +@clickstyle @result +@dots{} @clicksequence{File @click{} Open} @dots{} +@end display + + +@node Breaks +@chapter Forcing and Preventing Breaks + +@cindex Forcing line and page breaks +@cindex Making line and page breaks +@cindex Preventing line and page breaks +@cindex Line breaks, awkward +@cindex 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. + +@menu +* 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. +@end menu + + +@node Break Commands +@section Break Commands + +The break commands create or allow line and paragraph breaks: + +@table @code +@item @@* +Force a line break. + +@item @@sp @var{n} +Skip @var{n} blank lines. + +@item @@- +Insert a discretionary hyphen. + +@item @@hyphenation@{@var{hy-phen-a-ted words}@} +Define hyphen points in @var{hy-phen-a-ted words}. +@end table + +These commands hold text together on a single line: + +@table @code +@item @@w@{@var{text}@} +Prevent @var{text} from being split and hyphenated across two lines. + +@item @@tie@{@} +Insert a normal interword space at which a line break may not occur. +@end table + +The pagination commands apply only to printed output, since other +output formats do not have pages. + +@table @code +@item @@page +Start a new page. + +@item @@group +Hold text together that must appear on one page. + +@item @@need @var{mils} +Start a new page if not enough space on this one. +@end table + + +@node Line Breaks +@section @code{@@*} and @code{@@/}: Generate and Allow Line Breaks + +@findex * @r{(force line break)} +@findex / @r{(allow line break)} +@cindex Line breaks, controlling +@cindex Controlling line breaks +@cindex Breaks in a line +@cindex Force line break +@cindex 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{@@*}: + +@example +This sentence is broken @@*into two lines. +@end example + +@noindent produces + +@example +@group +This sentence is broken +into two lines. +@end group +@end example + +The @code{@@/} command can often be useful within urls +(@pxref{@t{@@url}}), which tend to be long and are otherwise +unbreakable. For example: + +@example +The official Texinfo home page is on the GNU web site: +@@uref@{http://www.gnu.org/@@/software/@@/gnu/@@/texinfo@}. +@end example + +@noindent produces + +@quotation +The official Texinfo home page is on the GNU web site: +@uref{http://www.gnu.org/@/software/@/gnu/@/texinfo}. +@end quotation + +@noindent Without the @code{@@/} commands, @TeX{} would have nowhere to +break the url. @code{@@/} has no effect in other output formats. + + +@node @t{@@- @@hyphenation} +@section @code{@@-} and @code{@@hyphenation}: Helping @TeX{} Hyphenate + +@anchor{- and hyphenation}@c old name +@findex - @r{(discretionary hyphen)} +@findex hyphenation +@cindex Hyphenation, helping @TeX{} do +@cindex 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: + +@table @code +@item @@- +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{@@-}. + +@item @@hyphenation@{@var{hy-phen-a-ted words}@} +Tell @TeX{} how to hyphenate @var{hy-phen-a-ted words}. As shown, you +put a @samp{-} at each hyphenation point. For example: +@example +@@hyphenation@{man-u-script man-u-scripts@} +@end example +@noindent @TeX{} only uses the specified hyphenation points when the +words match exactly, so give all necessary variants, such as plurals. +@end table + +Info, HTML, and other non-@TeX{} output is not hyphenated, so none of +these commands have any effect there. + + +@node @t{@@allowcodebreaks} +@section @code{@@allowcodebreaks}: Control Line Breaks in @code{@@code} + +@anchor{allowcodebreaks}@c old name +@findex allowcodebreaks +@cindex Breaks, within @code{@@code} +@cindex -, breakpoint within @code{@@code} +@cindex Hyphen, breakpoint within @code{@@code} +@cindex Dash, breakpoint within @code{@@code} +@cindex _, breakpoint within @code{@@code} +@cindex Underscore, breakpoint within @code{@@code} + +Ordinarily, @TeX{} considers breaking lines at @samp{-} and @samp{_} +characters within @code{@@code} and related commands +(@pxref{@t{@@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: + +@example +@@allowcodebreaks false +@end example + +@noindent to prevent from breaking at @samp{-} or @samp{_} within +@code{@@code}. You can go back to allowing such breaks with +@code{@@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. + + +@node @t{@@w} +@section @code{@@w}@{@var{text}@}: Prevent Line Breaks + +@anchor{w}@c old name +@findex w @r{(prevent line break)} +@cindex Line breaks, preventing + +@code{@@w@{@var{text}@}} outputs @var{text}, while prohibiting line +breaks within @var{text}. + +@cindex Non-breakable space, fixed +@cindex Unbreakable space, fixed +Thus, you can use @code{@@w} to produce a non-breakable space, fixed at +the width of a normal interword space: + +@example +@@w@{ @} @@w@{ @} @@w@{ @} indentation. +@end example + +@noindent produces: + +@display +@w{ } @w{ } @w{ } indentation. +@end display + +The space from @code{@@w@{@w{ }@}}, 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. + +@cindex 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. + +@cindex Keyword expansion, preventing +@cindex Version control keywords, preventing expansion of +@cindex $Id expansion, preventing +You can also use @code{@@w} to avoid unwanted keyword expansion in +source control systems. For example, to literally write @t{@w{$}Id$} +in your document, use @code{@@w@{$@}Id$}. This trick isn't effective +in Info or plain text output, though. + + +@node @t{@@tie} +@section @code{@@tie@{@}}: Inserting an Unbreakable Space + +@anchor{tie}@c old name +@findex tie @r{(unbreakable interword space)} +@cindex Tied space +@cindex Non-breakable space, variable +@cindex Unbreakable space, variable + +The @code{@@tie@{@}} 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: + +@example +@@TeX@{@} was written by Donald E.@@tie@{@}Knuth. +@end example + +@noindent produces: + +@display +@TeX{} was written by Donald E.@tie{}Knuth. +@end display + +There are two important differences between @code{@@tie@{@}} and +@code{@@w@{@w{ }@}}: + +@itemize +@item +The space produced by @code{@@tie@{@}} will stretch and shrink slightly +along with the normal interword spaces in the paragraph; the space +produced by @code{@@w@{@w{ }@}} will not vary. + +@item +@code{@@tie@{@}} allows hyphenation of the surrounding words, while +@code{@@w@{@w{ }@}} inhibits hyphenation of those words (for @TeX{}nical +reasons, namely that it produces an @samp{\hbox}). + +@end itemize + + +@node @t{@@sp} +@section @code{@@sp} @var{n}: Insert Blank Lines + +@anchor{sp}@c old name +@findex sp @r{(line spacing)} +@cindex Space, inserting vertical +@cindex Blank lines +@cindex Line spacing + +A line beginning with and containing only @code{@@sp @var{n}} +generates @var{n} blank lines of space in both the printed manual and +the Info file. @code{@@sp} also forces a paragraph break. For +example, + +@example +@@sp 2 +@end example + +@noindent +generates two blank lines. + +The @code{@@sp} command is most often used in the title page. + + +@node @t{@@page} +@section @code{@@page}: Start a New Page + +@anchor{page}@c old name +@findex page +@cindex 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 +@code{@@titlepage} section of a Texinfo file to start the copyright +page. + + +@node @t{@@group} +@section @code{@@group}: Prevent Page Breaks + +@anchor{group}@c old name +@findex group +@cindex Group (hold text together vertically) +@cindex Holding text together vertically +@cindex Vertically holding text together + +The @code{@@group} command (on a line by itself) is used inside an +@code{@@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. + +@c Once said that these environments +@c turn off vertical spacing between ``paragraphs''. +@c 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}, +@code{@@format}, @code{@@flushleft} and @code{@@flushright}. +@xref{Quotations 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. + +@need 750 +This formatting requirement means that you should write: + +@example +@group +@@example +@@group +@dots{} +@@end group +@@end example +@end group +@end example + +@noindent +with the @code{@@group} and @code{@@end group} commands inside the +@code{@@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 +@code{@@end group} if you get incomprehensible error messages in +@TeX{}. + + +@node @t{@@need} +@section @code{@@need @var{mils}}: Prevent Page Breaks + +@anchor{need}@c old name +@findex need +@cindex Need space at page bottom +@cindex 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 +@var{n}. The @code{@@need} command has no effect on other output +formats since they are not paginated. + +@need 800 +This paragraph is preceded by an @code{@@need} command that tells +@TeX{} to start a new page if fewer than 800 mils (eight-tenths +inch) remain on the page. It looks like this: + +@example +@group +@@need 800 +This paragraph is preceded by @dots{} +@end group +@end example + +@cindex Orphans, preventing +The @code{@@need} command is useful for preventing orphans: single +lines at the bottoms of printed pages. + + +@node Definition Commands +@chapter Definition Commands +@cindex 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: +@code{@@deffn} enters the name into the index of functions, +@code{@@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 +@code{@@table} rather than the definition commands. + +@menu +* 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. +@end menu + + +@node Def Cmd Template +@section The Template for a Definition +@cindex Definition template +@cindex 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 +@code{@@def@dots{}} command and whatever arguments are appropriate for +that command; the body of the definition; and a corresponding +@code{@@end} line. + +The template for a definition looks like this: + +@example +@group +@@deffn @var{category} @var{name} @var{arguments}@dots{} +@var{body-of-definition} +@@end deffn +@end group +@end example + +@need 700 +@noindent +For example, + +@example +@group +@@deffn Command forward-word count +This command moves point forward @@var@{count@} words +(or backward if @@var@{count@} is negative). @dots{} +@@end deffn +@end group +@end example + +@noindent +produces + +@quotation +@deffn Command forward-word count +This command moves point forward @var{count} words +(or backward if @var{count} is negative). @dots{} +@end deffn +@end 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: + +@example +@group +@@deffn @{Interactive Command@} isearch-forward +@dots{} +@@end deffn +@end group +@end example + +@noindent +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, @samp{@{declaraci@@'on@}} if you are +writing in Spanish. + +Some of the definition commands are more general than others. The +@code{@@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. + +@xref{Sample Function Definition}, for a detailed example of a +function definition, including the use of @code{@@example} inside the +definition. + + +@node Def Cmd Continuation Lines +@section Definition Command Continuation Lines +@cindex Continuation lines in definition commands +@cindex Definition command headings, continuing +@cindex @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: + +@example +@@defun fn-name @@ + arg1 arg2 arg3 +This is the basic continued defun. +@@end defun +@end example + +@noindent produces: + +@defun fn-name arg1 arg2 arg3 +This is the basic continued defun. +@end defun + +@noindent +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. + +@cindex Whitespace, collapsed around continuations +@cindex 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: + +@example +@@deffn @{Category @@ + Name@} @dots{} +@end example + +@noindent 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. + +@code{@@} 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}). + + +@node Optional Arguments +@section Optional and Repeated Arguments +@cindex Optional and repeated arguments +@cindex Repeated and optional arguments +@cindex Arguments, repeated and optional +@cindex Syntax, optional & repeated arguments +@cindex Meta-syntactic chars for arguments + +@c This is consistent with the XEmacs 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, [@var{optional-arg}] means that @var{optional-arg} is optional +and @var{repeated-args}@samp{@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: + +@quotation +@defspec foobar (@var{var} [@var{from} @var{to} [@var{inc}]]) @var{body}@dots{} +@end defspec +@c tex +@c \vskip \parskip +@c end tex +@end quotation + +@noindent +In this example, the arguments @var{from} and @var{to} are optional, +but must both be present or both absent. If they are present, +@var{inc} 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. + +@example +@group +@@defspec foobar (@@var@{var@} [@@var@{from@} @@var@{to@} @@ + [@@var@{inc@}]]) @@var@{body@}@@dots@{@} +@end group +@end example + +@noindent +The function is listed in the Command and Variable Index under +@samp{foobar}. + + +@node @t{@@deffnx} +@section @code{@@deffnx}, et al.: Two or More `First' Lines + +@anchor{deffnx}@c old node +@findex deffnx +@cindex Two `First' Lines for @code{@@deffn} +@cindex Grouping two definitions together +@cindex 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 +@code{@@deffnx}. The @code{@@deffnx} command works exactly like +@code{@@deffn} except that it does not generate extra vertical white +space between it and the preceding line. + +@need 1000 +For example, + +@example +@group +@@deffn @{Interactive Command@} isearch-forward +@@deffnx @{Interactive Command@} isearch-backward +These two search commands are similar except @dots{} +@@end deffn +@end group +@end example + +@noindent +produces + +@deffn {Interactive Command} isearch-forward +@deffnx {Interactive Command} isearch-backward +These two search commands are similar except @dots{} +@end deffn + +Each definition command has an `x' form: @code{@@defunx}, +@code{@@defvrx}, @code{@@deftypefunx}, etc. + +The `x' forms work similarly to @code{@@itemx} +(@pxref{@t{@@itemx}}). + + +@node Def Cmds in Detail +@section 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; +@code{@@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. + +@menu +* 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. +@end menu + +@node Functions Commands +@subsection Functions and Similar Entities + +This section describes the commands for describing functions and similar +entities: + +@table @code +@findex deffn +@item @@deffn @var{category} @var{name} @var{arguments}@dots{} +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. + +@need 750 +For example, here is a definition: + +@example +@group +@@deffn Command forward-char nchars +Move point forward @@var@{nchars@} characters. +@@end deffn +@end group +@end example + +@noindent +This shows a rather terse definition for a ``command'' named +@code{forward-char} with one argument, @var{nchars}. + +@code{@@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{@@var@{nchars@}} in this way. + +In the extremely unusual case when an argument name contains +@samp{--}, 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. +@c @var also works; that's what we used to recommend. + +The template for @code{@@deffn} is: + +@example +@group +@@deffn @var{category} @var{name} @var{arguments}@dots{} +@var{body-of-definition} +@@end deffn +@end group +@end example + +@findex defun +@item @@defun @var{name} @var{arguments}@dots{} +The @code{@@defun} command is the definition command for functions. +@code{@@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: + +@example +@group +@@defun @var{function-name} @var{arguments}@dots{} +@var{body-of-definition} +@@end defun +@end group +@end example + +@findex defmac +@item @@defmac @var{name} @var{arguments}@dots{} +The @code{@@defmac} command is the definition command for macros. +@code{@@defmac} is equivalent to @samp{@@deffn Macro @dots{}} and +works like @code{@@defun}. + +@findex defspec +@item @@defspec @var{name} @var{arguments}@dots{} +The @code{@@defspec} command is the definition command for special +forms. (In Lisp, a special form is an entity much like a function; +@pxref{Special Forms,,, lispref, XEmacs Lisp Reference Manual}.) +@code{@@defspec} is equivalent to @samp{@@deffn @{Special Form@} +@dots{}} and works like @code{@@defun}. +@end table + +All these commands create entries in the index of functions. + + +@node Variables Commands +@subsection Variables and Similar Entities + +Here are the commands for defining variables and similar +entities: + +@table @code +@findex defvr +@item @@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, + +@example +@group +@@defvr @{User Option@} fill-column +This buffer-local variable specifies +the maximum width of filled lines. +@dots{} +@@end defvr +@end group +@end example + +Terminate the definition with @code{@@end defvr} on a line of its +own. + +The template is: + +@example +@group +@@defvr @var{category} @var{name} +@var{body-of-definition} +@@end defvr +@end group +@end example + +@code{@@defvr} creates an entry in the index of variables for @var{name}. + +@findex defvar +@item @@defvar @var{name} +The @code{@@defvar} command is the definition command for variables. +@code{@@defvar} is equivalent to @samp{@@defvr Variable +@dots{}}. + +@need 750 +For example: + +@example +@group +@@defvar kill-ring +@dots{} +@@end defvar +@end group +@end example + +The template is: + +@example +@group +@@defvar @var{name} +@var{body-of-definition} +@@end defvar +@end group +@end example + +@code{@@defvar} creates an entry in the index of variables for +@var{name}. + +@findex defopt +@item @@defopt @var{name} +@cindex User options, marking +The @code{@@defopt} command is the definition command for @dfn{user +options}, i.e., variables intended for users to change according to +taste; XEmacs has many such (@pxref{Variables,,, xemacs, XEmacs User's +Manual}). @code{@@defopt} is equivalent to @samp{@@defvr @{User +Option@} @dots{}} and works like @code{@@defvar}. It creates an entry +in the index of variables. +@end table + + +@node Typed Functions +@subsection Functions in Typed Languages + +@cindex Typed functions +@cindex 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++. + +@table @code +@findex deftypefn +@item @@deftypefn @var{category} @var{data-type} @var{name} @var{arguments}@dots{} +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. + +@need 800 +@noindent +For example, + +@example +@group +@@deftypefn @{Library Function@} int foobar @@ + (int @@var@{foo@}, float @@var@{bar@}) +@dots{} +@@end deftypefn +@end group +@end example + +produces: + +@quotation +@deftypefn {Library Function} int foobar (int @var{foo}, float @var{bar}) +@dots{} +@end deftypefn +@end quotation + +This means that @code{foobar} is a ``library function'' that returns an +@code{int}, and its arguments are @var{foo} (an @code{int}) and +@var{bar} (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 +@code{@@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: + +@example +@group +@@deftypefn @var{category} @var{data-type} @var{name} @var{arguments} @dots{} +@var{body-of-description} +@@end deftypefn +@end group +@end example + +@noindent +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: + +@example +@group +@@deftypefn stacks private push @@ + (@@var@{s@}:in out stack; @@ + @@var@{n@}:in integer) +@dots{} +@@end deftypefn +@end group +@end example + +@noindent +(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}.) + +@code{@@deftypefn} creates an entry in the index of functions for +@var{name}. + +@item @@deftypefun @var{data-type} @var{name} @var{arguments}@dots{} +@findex deftypefun +The @code{@@deftypefun} command is the specialized definition command +for functions in typed languages. The command is equivalent to +@samp{@@deftypefn Function @dots{}}. The template is: + +@example +@group +@@deftypefun @var{type} @var{name} @var{arguments}@dots{} +@var{body-of-description} +@@end deftypefun +@end group +@end example + +@code{@@deftypefun} creates an entry in the index of functions for +@var{name}. + +@end table + +@cindex Return type, own line for +@findex 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. + + +@node Typed Variables +@subsection Variables in Typed Languages + +@cindex Typed variables +@cindex 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 +@code{@@deftypefn} and the specialized definition command +@code{@@deftypevar} corresponds to @code{@@deftypefun}. + +@table @code +@findex deftypevr +@item @@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. + +@need 800 +@noindent +For example: + +@example +@group +@@deftypevr @{Global Flag@} int enable +@dots{} +@@end deftypevr +@end group +@end example + +@noindent +produces the following: + +@quotation +@deftypevr {Global Flag} int enable +@dots{} +@end deftypevr +@end quotation + +@need 800 +The template is: + +@example +@@deftypevr @var{category} @var{data-type} @var{name} +@var{body-of-description} +@@end deftypevr +@end example + +@findex deftypevar +@item @@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: + +@example +@group +@@deftypevar @var{data-type} @var{name} +@var{body-of-description} +@@end deftypevar +@end group +@end example +@end table + +These commands create entries in the index of variables. + + +@node Data Types +@subsection Data Types + +Here is the command for data types: + +@table @code +@findex deftp +@item @@deftp @var{category} @var{name} @var{attributes}@dots{} +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 +@code{data 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 +@sc{car} and the @sc{cdr}. Here is how you would write the first line +of a definition of @code{pair}. + +@example +@group +@@deftp @{Data type@} pair car cdr +@dots{} +@@end deftp +@end group +@end example + +@need 950 +The template is: + +@example +@group +@@deftp @var{category} @var{name-of-type} @var{attributes}@dots{} +@var{body-of-definition} +@@end deftp +@end group +@end example + +@code{@@deftp} creates an entry in the index of data types. +@end table + + +@node Abstract Objects +@subsection Object-Oriented Programming + +@cindex 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. + +@menu +* Variables: Object-Oriented Variables. +* Methods: Object-Oriented Methods. +@end menu + + +@node Object-Oriented Variables +@subsubsection Object-Oriented Variables + +@cindex Variables, object-oriented + +These commands allow you to define different sorts of variables in +object-oriented programming languages. + +@table @code +@item @@defcv @var{category} @var{class} @var{name} +@findex defcv +The @code{@@defcv} command is the general definition command for +variables associated with classes in object-oriented programming. The +@code{@@defcv} command is followed by three arguments: the category of +thing being defined, the class to which it belongs, and its +name. For instance: + +@example +@group +@@defcv @{Class Option@} Window border-pattern +@dots{} +@@end defcv +@end group +@end example + +@noindent produces: +@defcv {Class Option} Window border-pattern +@dots{} +@end defcv + +@code{@@defcv} creates an entry in the index of variables. + +@item @@deftypecv @var{category} @var{class} @var{data-type} @var{name} +@findex deftypecv +The @code{@@deftypecv} command is the definition command for typed +class variables in object-oriented programming. It is analogous to +@code{@@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 +@code{@@code}. For instance: + +@example +@group +@@deftypecv @{Class Option@} Window @@code@{int@} border-pattern +@dots{} +@@end deftypecv +@end group +@end example + +@noindent produces: + +@deftypecv {Class Option} Window @code{int} border-pattern +@dots{} +@end deftypecv + +@code{@@deftypecv} creates an entry in the index of variables. + +@item @@defivar @var{class} @var{name} +@findex defivar +The @code{@@defivar} command is the definition command for instance +variables in object-oriented programming. @code{@@defivar} is +equivalent to @samp{@@defcv @{Instance Variable@} @dots{}}. For +instance: + +@example +@group +@@defivar Window border-pattern +@dots{} +@@end defivar +@end group +@end example + +@noindent produces: + +@defivar Window border-pattern +@dots{} +@end defivar + +@code{@@defivar} creates an entry in the index of variables. + +@item @@deftypeivar @var{class} @var{data-type} @var{name} +@findex deftypeivar +The @code{@@deftypeivar} command is the definition command for typed +instance variables in object-oriented programming. It is analogous to +@code{@@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 +@code{@@code}. For instance: + +@example +@group +@@deftypeivar Window @@code@{int@} border-pattern +@dots{} +@@end deftypeivar +@end group +@end example + +@noindent produces: + +@deftypeivar Window @code{int} border-pattern +@dots{} +@end deftypeivar + +@code{@@deftypeivar} creates an entry in the index of variables. + +@end table + + +@node Object-Oriented Methods +@subsubsection Object-Oriented Methods + +@cindex 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. + +@table @code + +@findex defop +@item @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{} +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 +@code{expose} 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: + +@example +@@defop Operation windows expose +@end 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: +@example +@group +@@defop @var{category} @var{class} @var{name} @var{arguments}@dots{} +@var{body-of-definition} +@@end defop +@end group +@end example + +@code{@@defop} creates an entry, such as `@code{expose} on +@code{windows}', in the index of functions. + +@findex deftypeop +@item @@deftypeop @var{category} @var{class} @var{data-type} @var{name} @var{arguments}@dots{} +The @code{@@deftypeop} command is the definition command for typed +operations in object-oriented programming. It is similar to +@code{@@defop} with the addition of the @var{data-type} parameter to +specify the return type of the method. @code{@@deftypeop} creates an +entry in the index of functions. + +@item @@defmethod @var{class} @var{name} @var{arguments}@dots{} +@findex defmethod +The @code{@@defmethod} command is the definition command for methods +in object-oriented programming. A method is a kind of function that +implements an operation for a particular class of objects and its +subclasses. +@ignore +@c ADR: Who cares?!? +@c KB: Oh, I don't know, I think this info is crucial! +In the Lisp Machine, methods actually were functions, but +they were usually defined with @code{defmethod}. +@end ignore + +@code{@@defmethod} is equivalent to @samp{@@defop Method @dots{}}. +The command is written at the beginning of a line and is followed by +the name of the class of the method, the name of the method, and its +arguments, if any. + +@noindent +For example: +@example +@group +@@defmethod @code{bar-class} bar-method argument +@dots{} +@@end defmethod +@end group +@end example + +@noindent +illustrates the definition for a method called @code{bar-method} of +the class @code{bar-class}. The method takes an argument. + +@code{@@defmethod} creates an entry in the index of functions. + +@item @@deftypemethod @var{class} @var{data-type} @var{name} @var{arguments}@dots{} +@findex 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 +@var{data-type} parameter to specify the return type of the method. +@code{@@deftypemethod} creates an entry in the index of functions. + +@end table + +The typed commands are affected by the @code{@@deftypefnnewline} +option (@pxref{Typed Functions,, Functions in Typed Languages}). + + +@node Def Cmd Conventions +@section Conventions for Writing Definitions +@cindex Definition conventions +@cindex 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. + + +@node Sample Function Definition +@section A Sample Function Definition +@cindex Function definitions +@cindex Command definitions +@cindex Macro definitions, programming-language +@cindex Sample function definition + +A function definition uses the @code{@@defun} and @code{@@end defun} +commands. The name of the function follows immediately after the +@code{@@defun} command and it is followed, on the same line, by the +parameter list. + +Here is a definition from @ref{Calling Functions,,, lispref, XEmacs Lisp +Reference Manual}. + +@quotation +@defun apply function &rest arguments +@code{apply} calls @var{function} with @var{arguments}, just +like @code{funcall} but with one difference: the last of +@var{arguments} is a list of arguments to give to +@var{function}, rather than a single argument. We also say +that this list is @dfn{appended} to the other arguments. + +@code{apply} 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}. + +@example +(setq f 'list) + @result{} list +(apply f 'x 'y 'z) +@error{} 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) +@end example + +An interesting example of using @code{apply} is found in the description +of @code{mapcar}. +@end defun +@end quotation + +In the Texinfo source file, this example looks like this: + +@example +@group +@@defun apply function &rest arguments +@@code@{apply@} calls @@var@{function@} with +@@var@{arguments@}, just like @@code@{funcall@} but with one +difference: the last of @@var@{arguments@} is a list of +arguments to give to @@var@{function@}, rather than a single +argument. We also say that this list is @@dfn@{appended@} +to the other arguments. +@end group + +@group +@@code@{apply@} 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@}. +@end group + +@group +@@example +(setq f 'list) + @@result@{@} list +(apply f 'x 'y 'z) +@@error@{@} 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) +@@end example +@end group + +@group +An interesting example of using @@code@{apply@} is found +in the description of @@code@{mapcar@}. +@@end defun +@end group +@end example + +@noindent +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. + + +@node Internationalization +@chapter Internationalization + +@cindex 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, +@pxref{Internationalization of Document Strings}.) + +For a list of the various accented and special characters Texinfo +supports, see @ref{Inserting Accents}. + +@menu +* @t{@@documentlanguage}:: Declaring the current language. +* @t{@@documentencoding}:: Declaring the input encoding. +@end menu + + +@node @t{@@documentlanguage} +@section @code{@@documentlanguage @var{ll}[_@var{cc}]}: Set the Document Language +@anchor{documentlanguage} + +@findex documentlanguage +@cindex Language, declaring +@cindex Locale, declaring +@cindex 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} (@pxref{@t{@@setfilename}}): + +@example +@@documentlanguage @var{ll}[_@var{cc}] +@end example + +Include a two-letter ISO@tie{}639-2 language code (@var{ll}) following +the command name, optionally followed by an underscore and two-letter +ISO@tie{}3166 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). + +@cindex 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. + +@cindex @file{txi-@var{cc}.tex} +For @TeX{}, this command causes a file @file{txi-@var{locale}.tex} to +be read (if it exists). If @code{@@documentlanguage} argument +contains the optional @samp{_@var{cc}} 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. + +@cindex Hyphenation patterns, language-dependent +@code{@@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 +@command{pdftex} (PDF output). @command{texi2dvi} will use the +extended @TeX{}s if they are available (@pxref{Format with +@t{texi2dvi}}). + +In September 2006, the W3C Internationalization Activity released a +new recommendation for specifying languages: +@url{http://www.rfc-editor.org/rfc/bcp/bcp47.txt}. When Gettext +supports this new scheme, Texinfo will too. + +@cindex ISO 639-2 language codes +@cindex ISO 3166 country codes +@cindex Language codes +@cindex 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 ISO@tie{}639, +@url{http://www.loc.gov/standards/iso639-2/}. The country codes and +the official web site for ISO@tie{}3166 can be found via +@url{http://en.wikipedia.org/wiki/ISO_3166}. + + +@node @t{@@documentencoding} +@section @code{@@documentencoding @var{enc}}: Set Input Encoding + +@anchor{documentencoding}@c old name +@findex documentencoding +@cindex Encoding, declaring +@cindex Input encoding, declaring +@cindex Character set, declaring +@cindex Document input encoding + +The @code{@@documentencoding} command declares the input document +encoding. Write it on a line by itself, with a valid encoding +specification following, near the beginning of the file but after +@code{@@setfilename} (@pxref{@t{@@setfilename}}): + +@example +@@documentencoding @var{enc} +@end example + +At present, Texinfo supports only these encodings: + +@table @code +@item US-ASCII +This has no particular effect, but it's included for completeness. + +@item UTF-8 +The vast global character encoding, expressed in 8-bit bytes. + +@item ISO-8859-2 +@itemx ISO-8859-1 +@itemx 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}. + +@item koi8-r +This is the commonly used encoding for the Russian language. + +@item koi8-u +This is the commonly used encoding for the Ukrainian language. + +@end table + +Specifying an encoding @var{enc} has the following effects: + +@cindex Local Variables section, for encoding +@cindex Info output, and encoding +In Info output, a so-called `Local Variables' section (@pxref{File +Variables,,,xemacs, XEmacs User's Manual}) is output including +@var{enc}. This allows Info readers to set the encoding +appropriately. It looks like this: + +@example +Local Variables: +coding: @var{enc} +End: +@end example + +Also, in Info and plain text output, unless the option +@option{--disable-encoding} 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. + +@cindex HTML output, and encodings +@cindex @code{http-equiv}, and charset specification +@cindex @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: + +@example +<meta http-equiv="Content-Type" content="text/html; + charset=@var{enc}"> +@end 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. + +@cindex 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 +@file{texinfo.tex}, and it's not feasible to duplicate or incorporate +all that effort. Our plan to support other scripts is to create a +@LaTeX{} back-end to @command{texi2any}, where the support is already +present. + + +@node Conditionals +@chapter Conditionally Visible Text +@cindex Conditionally visible text +@cindex Text, conditionally visible +@cindex Visibility of conditional text +@cindex 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. + +@itemize @bullet +@item +Commands specific to an output format (Info, @TeX{}, HTML, @dots{}). + +@item +Commands specific to any output format @emph{excluding} a given +one (e.g., not Info, not @TeX{}, @dots{}). + +@item +`Raw' formatter text for any output format, passed straight +through with minimal (but not zero) interpretation of @@-commands. + +@item +Format-independent variable substitutions, and testing if a variable +is set or clear. + +@end itemize + +@menu +* 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. +@end menu + + +@node Conditional Commands +@section Conditional Commands + +Texinfo has an @code{@@if@var{format}} environment for each output +format, to allow conditional inclusion of text for a particular output +format. + +@findex ifinfo +@code{@@ifinfo} begins segments of text that should be ignored by +@TeX{} 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. + +@findex ifdocbook +@findex ifhtml +@findex ifplaintext +@findex iftex +@findex ifxml +The environments for the other formats are analogous, but without the +special historical case: + +@table @code +@item @@ifdocbook @dots{} @@end ifdocbook +Text to appear only in the Docbook output. + +@item @@ifhtml @dots{} @@end ifhtml +Text to appear only in the HTML output. + +@item @@ifplaintext @dots{} @@end ifplaintext +Text to appear only in the plain text output. + +@item @@iftex @dots{} @@end iftex +Text to appear only in the printed manual. + +@item @@ifxml @dots{} @@end ifxml +Text to appear only in the XML output. +@end table + +The @code{@@if@dots{}} and @code{@@end if@dots{}} 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{@@if@dots{}} 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: + +@example +@@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 XML@. +@@end ifxml +@@ifdocbook +Nevertheless, this will only appear in Docbook. +@@end ifdocbook +@end example + +@noindent +The preceding example produces the following line: + +@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 XML@. +@end ifxml +@ifdocbook +Nevertheless, this will only appear in Docbook. +@end ifdocbook + +@noindent +Notice that you only see one of the input lines, depending on which +version of the manual you are reading. + +@findex errormsg +In complex documents, you may want Texinfo to issue an error message +in some conditionals that should not ever be processed. The +@code{@@errormsg@{@var{text}@}} 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{@@errormsg@{@}} 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. +@xref{External Macro Processors}, for a caveat regarding the line +numbers which @code{@@errormsg} emits in @TeX{}. + + +@node Conditional Not Commands +@section Conditional Not Commands +@findex ifnotdocbook +@findex ifnothtml +@findex ifnotinfo +@findex ifnotplaintext +@findex ifnottex +@findex ifnotxml + +You can specify text to be included in any output format @emph{other} +than a given one with the @code{@@ifnot@dots{}} environments: + +@example +@@ifnotdocbook @dots{} @@end ifnotdocbook +@@ifnothtml @dots{} @@end ifnothtml +@@ifnotinfo @dots{} @@end ifnotinfo +@@ifnotplaintext @dots{} @@end ifnotplaintext +@@ifnottex @dots{} @@end ifnottex +@@ifnotxml @dots{} @@end ifnotxml +@end example + +@noindent +The @code{@@ifnot@dots{}} 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): +@code{@@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: + +@example +@@ifinfo +@@ifnotplaintext +This will be in Info, but not plain text. +@@end ifnotplaintext +@@end ifinfo +@end 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}). + + +@node Raw Formatter Commands +@section Raw Formatter Commands +@cindex Raw formatter commands + +@cindex @TeX{} commands, using ordinary +@cindex Ordinary @TeX{} commands, using +@cindex Commands using raw @TeX{} +@cindex Plain @TeX{} + +The @code{@@if@dots{}} conditionals just described must be used only +with normal Texinfo source. For instance, most features of plain +@TeX{} will not work within @code{@@iftex}. The purpose of +@code{@@if@dots{}} 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). + +@findex tex +@cindex Category codes, of plain @TeX{} +The first raw formatter command is @code{@@tex}. You can enter plain +@TeX{} completely, and use @samp{\} in the @TeX{} commands, by +delineating a region with the @code{@@tex} and @code{@@end tex} +commands. All plain @TeX{} commands and category codes are restored +within an @code{@@tex} region. The sole exception is that the +@code{@@} character still introduces a command, so that @code{@@end +tex} can be recognized. Texinfo processors will not output material +in such a region, unless @TeX{} output is being produced. + +@findex \gdef @r{within @code{@@tex}} +@findex \globaldefs @r{within @code{@@tex}} +In complex cases, you may wish to define new @TeX{} macros within +@code{@@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 +@code{\globaldefs=1} (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). + +@cindex Equation, displayed, in plain @TeX{} +@cindex Displayed equation, in plain @TeX{} +As an example, here is a displayed equation written in plain @TeX{}: + +@example +@@tex +$$ \chi^2 = \sum_@{i=1@}^N + \left (y_i - (a + b x_i) + \over \sigma_i\right)^2 $$ +@@end tex +@end example + +@noindent +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. + +@tex +$$ \chi^2 = \sum_{i=1}^N + \left(y_i - (a + b x_i) + \over \sigma_i\right)^2 $$ +@end tex + +@cindex HTML, including raw +@findex ifhtml +@findex html +Analogously, you can use @code{@@ifhtml @dots{} @@end ifhtml} to +delimit Texinfo source to be included in HTML output only, and +@code{@@html @dots{} @@end html} for a region of raw HTML. + +@cindex XML, including raw +@findex ifxml +@findex xml +Likewise, you can use @code{@@ifxml @dots{} @@end ifxml} to delimit +Texinfo source to be included in XML output only, and @code{@@xml +@dots{} @@end xml} for a region of raw XML@. 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: + +@example +@group +@@html +<br /> +@@end html +@end group +@end example + +@noindent +will be included in the XML output as: + +@example +@group +<html> +<br /> +</html> +@end group +@end example + +@cindex Docbook, including raw +@findex ifdocbook +@findex docbook +Again likewise, you can use @code{@@ifdocbook @dots{} @@end ifdocbook} +to delimit Texinfo source to be included in Docbook output only, and +@code{@@docbook @dots{} @@end docbook} for a region of raw Docbook. + +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, it +using the @code{@@kbdinputstyle} command inside a raw region is undefined. + +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 +@code{@@if@dots{}} conditionals and stay in Texinfo syntax. + + + +@node Inline Conditionals +@section Inline Conditionals: @code{@@inline}, @code{@@inlineifelse}, @code{@@inlineraw} +@findex inlinefmt +@findex inlinefmtifelse +@findex inlineraw +@cindex Inline conditionals +@cindex Conditional commands, inline +@cindex Brace-delimited conditional text +@cindex Newlines, avoiding in conditionals +@cindex Whitespace, controlling in conditionals + +Texinfo provides a set of conditional commands with arguments given +within braces: + +@table @code +@item @@inlinefmt@{@var{format}, @var{text}@} +Process the Texinfo @var{text} if @var{format} output is being +generated. + +@item @@inlinefmtifelse@{@var{format}, @var{then-text}, @var{else-text}@} +Process the Texinfo @var{then-text} if @var{format} output is being +generated; otherwise, process @var{else-text}. + +@item @@inlineraw@{@var{format}, @var{text}@} +Similar, but for raw @var{text} (@pxref{Raw Formatter Commands}). +@end table + +The supported @var{format} names are: + +@example +docbook html info plaintext tex xml +@end example + +For example, + +@example +@@inlinefmt@{html, @@emph@{HTML-only text@}@} +@end example + +@noindent is nearly equivalent to + +@example +@@ifhtml +@@emph@{HTML-only text@} +@@end ifhtml +@end example + +@noindent except that no whitespace is added, as happens in the latter +(environment) case. + +In these commands, whitespace is ignored after the comma separating +the arguments, as usual, but is @emph{not} ignored at the end of +@var{text}. + +To insert a literal at sign, left brace, or right brace in one of the +arguments, you must use the alphabetic commands @code{@@atchar@{@}} +(@pxref{Inserting an Atsign}), and @code{@@lbracechar@{@}} or +@code{@@rbracechar@{@}} (@pxref{Inserting Braces}), or the parsing +will become confused. + +With @code{@@inlinefmtifelse}, it is also necessary to use +@code{@@comma@{@}} to avoid mistaking a @samp{,} in the text for the +delimiter. With @code{@@inlinefmt} and @code{@@inlineraw}, +@code{@@comma@{@}} is not required (though it's fine to use it), since +these commands always have exactly two arguments. + +For @TeX{}, the processed @var{text} cannot contain newline-delimited +commands. Text to be ignored (i.e., for non-@TeX{}) can, though. + +Two other @code{@@inline...} conditionals complement the +@code{@@ifset} and @code{@@ifclear} commands; see the next section. + + +@node @t{@@set @@clear @@value} +@section Flags: @code{@@set}, @code{@@clear}, conditionals, and @code{@@value} + +@anchor{set clear value}@c 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: + +@table @code +@item @@set @var{flag} [@var{value}] +Set the variable @var{flag}, to the optional @var{value} if specified. + +@item @@clear @var{flag} +Undefine the variable @var{flag}, whether or not it was previously defined. + +@item @@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 +@code{@@end ifset} command is ignored. + +@item @@inlineifset@{@var{flag}, @var{text}@} +Brace-delimited version of @code{@@ifset}. + +@item @@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 +@code{@@end ifclear} command is formatted. + +@item @@inlineifclear@{@var{flag}, @var{text}@} +Brace-delimited version of @code{@@ifclear}. + +@end table + +@menu +* @t{@@set @@value}:: Expand a flag variable to a string. +* @t{@@ifset @@ifclear}:: Format a region if a flag is set. +* @t{@@inlineifset @@inlineifclear}:: Brace-delimited flag conditionals. +* @t{@@value} Example:: An easy way to update edition information. +@end menu + + +@node @t{@@set @@value} +@subsection @code{@@set} and @code{@@value} + +@anchor{set value}@c old name +@findex set +@findex value +@findex 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: + +@example +@@set foo This is a string. +@end example + +@noindent +This sets the value of the flag @code{foo} to ``This is a string.''. + +The Texinfo formatters then replace an @code{@@value@{@var{flag}@}} +command with the string to which @var{flag} is set. Thus, when +@code{foo} is set as shown above, the Texinfo formatters convert this: + +@example +@group +@@value@{foo@} +@exdent @r{to this:} +This is a string. +@end group +@end 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: + +@example +@@set foo +@end example + +@noindent +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{@@value@{flag@}} command will report an error. + +For example, if you set @code{foo} as follows: + +@example +@@set howmuch very, very, very +@end example + +@noindent +then the formatters transform + +@example +@group +It is a @@value@{howmuch@} wet day. +@exdent @r{into} +It is a very, very, very wet day. +@end group +@end example + +If you write + +@example +@@clear howmuch +@end example + +@noindent +then the formatters transform + +@example +@group +It is a @@value@{howmuch@} wet day. +@exdent @r{into} +It is a @{No value for "howmuch"@} wet day. +@end group +@end example + +@code{@@value} cannot be reliably used as the argument to an accent +command (@pxref{Inserting Accents}). For example, this fails: + +@example +@@set myletter a +@@'@@value@{myletter@} @c fails! +@end example + + +@node @t{@@ifset @@ifclear} +@subsection @code{@@ifset} and @code{@@ifclear} + +@anchor{ifset ifclear}@c old name +@findex 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: + +@example +@group +@@ifset @var{flag} +@var{conditional-text} +@@end ifset +@end group +@end example + +For example, you can create one document that has two variants, such as +a manual for a `large' and `small' model: + +@cindex Shrubbery +@example +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{} +@end example + +@noindent +In the example, the formatting commands will format the text between +@code{@@ifset large} and @code{@@end ifset} because the @code{large} +flag is set. + +When @var{flag} is cleared, the Texinfo formatting commands do +@emph{not} format the text between @code{@@ifset @var{flag}} and +@code{@@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{}''. + +@findex ifclear +If a flag is cleared with an @code{@@clear @var{flag}} command, then +the formatting commands format text between subsequent pairs of +@code{@@ifclear} and @code{@@end ifclear} commands. But if the flag +is set with @code{@@set @var{flag}}, then the formatting commands do +@emph{not} format text between an @code{@@ifclear} and an @code{@@end +ifclear} command; rather, they ignore that text. An @code{@@ifclear} +command looks like this: + +@example +@@ifclear @var{flag} +@end example + + +@node @t{@@inlineifset @@inlineifclear} +@subsection @code{@@inlineifset} and @code{@@inlineifclear} + +@findex inlineifset +@findex inlineifclear +@cindex Flag conditionals, brace-delimited +@cindex Brace-delimited flag conditionals + +@code{@@inlineifset} and @code{@@inlineifclear} provide +brace-delimited alternatives to the @code{@@ifset} and +@code{@@ifclear} forms, similar to the other @code{@@inline...} +Commands (@pxref{Inline Conditionals}). The same caveats about +argument parsing given there apply here too. + +@table @code +@item @@inlineifset@{@var{var}, @var{text}@} +Process the Texinfo @var{text} if the flag @var{var} is defined. + +@item @@inlineifclear@{@var{var}, @var{text}@} +Process the Texinfo @var{text} if the flag @var{var} is not defined. +@end table + +Except for the syntax, their general behavior and purposes is the same +as with @code{@@ifset} and @code{@@ifclear}, described in the previous +section. + + +@node @t{@@value} Example +@subsection @code{@@value} Example + +@anchor{value Example}@c 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. +@xref{GNU 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}. + +@enumerate +@item +Set the flags: + +@example +@group +@@set EDITION 0.35 Beta +@@set VERSION 3.63 Beta +@@set UPDATED 14 August 1992 +@@set UPDATE-MONTH August 1992 +@end group +@end example + +@item +Write text for the @code{@@copying} section (@pxref{@t{@@copying}}): + +@example +@group +@@copying +This is Edition @@value@{EDITION@}, +last updated @@value@{UPDATED@}, +of @@cite@{The GNU Make Manual@}, +for @@code@{make@}, version @@value@{VERSION@}. + +Copyright @dots{} + +Permission is granted @dots{} +@@end copying +@end group +@end example + +@item +Write text for the title page, for people reading the printed manual: + +@example +@group +@@titlepage +@@title GNU Make +@@subtitle A Program for Directing Recompilation +@@subtitle Edition @@value@{EDITION@}, @dots{} +@@subtitle @@value@{UPDATE-MONTH@} +@@page +@@insertcopying +@dots{} +@@end titlepage +@end group +@end example + +@noindent +(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.) + +@item +Write text for the Top node, for people reading the Info file: + +@example +@group +@@ifnottex +@@node Top +@@top Make + +@@insertcopying +@dots{} +@@end ifnottex +@end group +@end example + +After you format the manual, the @code{@@value} constructs have been +expanded, so the output contains text like this: + +@example +@group +This is Edition 0.35 Beta, last updated 14 August 1992, +of `The GNU Make Manual', for `make', Version 3.63 Beta. +@end group +@end example +@end enumerate + +When you update the manual, you change only the values of the flags; you +do not need to edit the three sections. + + +@node Testing for Texinfo Commands +@section Testing for Texinfo Commands: @code{@@ifcommanddefined}, @code{@@ifcommandnotdefined} + +@cindex Testing for Texinfo commands +@cindex Checking for Texinfo commands +@cindex Texinfo commands, testing for +@cindex Commands, testing for Texinfo +@cindex Versions of Texinfo, adapting to +@cindex 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 +@code{@@ifcommanddefined} and @code{@@ifcommandnotdefined} to do this. +For example: + +@example +@@ifcommanddefined node +Good, @@samp@{@@@@node@} is defined. +@@end ifcommanddefined +@end example + +@noindent 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}, +@code{@@definfoenclose}, and @code{@@def@r{(}code@r{)}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. + +@pindex @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 +Texinfo@tie{}5.0, 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: + +@example +@@ifset txicommandconditionals +@@ifcommandnotdefined foobarnode +(Good, @samp{@@foobarnode} is not defined.) +@@end ifcommandnotdefined +@@end ifset +@end 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}). + + +@node Conditional Nesting +@section Conditional Nesting +@cindex Conditionals, nested +@cindex Nesting conditionals + +Conditionals can be nested; however, the details are a little tricky. +The difficulty comes with failing conditionals, such as +@code{@@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: + +@example +@@ifset somevar +@@ifset anothervar +Both somevar and anothervar are set. +@@end ifset +@@ifclear anothervar +Somevar is set, anothervar is not. +@@end ifclear +@@end ifset +@end 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 +@emph{all} 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: + +@example +@@ifset a +@@ifset b +@@ifclear ok - ok, ignored +@@end junky - ok, ignored +@@end ifset +@@c WRONG - missing @@end ifset. +@end 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. + + +@node Defining New Texinfo Commands +@chapter Defining New Texinfo Commands + +@cindex Macros +@cindex Defining new Texinfo commands +@cindex New Texinfo commands, defining +@cindex Texinfo commands, defining new +@cindex User-defined Texinfo commands + +Texinfo provides several ways to define new commands (in all cases, +it's not recommended to try redefining existing commands): + +@itemize @bullet +@item +A Texinfo @dfn{macro} allows you to define a new Texinfo command as any +sequence of text and/or existing commands (including other macros). The +macro can have any number of @dfn{parameters}---text you supply each +time you use the macro. + +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}). + +@item +@samp{@@alias} is a convenient way to define a new name for an existing +command. + +@item +@samp{@@definfoenclose} allows you to define new commands with +customized output for all non-@TeX{} output formats. + +@end itemize + +Most generally of all (not just for defining new commands), it is +possible to invoke any 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 +@code{@@value} is the simplest approach (@pxref{@t{@@set @@clear +@@value}}). + +@menu +* 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. +@end menu + + +@node Defining Macros +@section Defining Macros +@cindex Defining macros +@cindex Macro definitions, Texinfo + +@findex macro +You use the Texinfo @code{@@macro} command to define a macro, like this: + +@example +@@macro @var{macroname}@{@var{param1}, @var{param2}, @dots{}@} +@var{text} @dots{} \@var{param1}\ @dots{} +@@end macro +@end example + +The @dfn{parameters} @var{param1}, @var{param2}, @dots{} correspond to +arguments supplied when the macro is subsequently used in the document +(described in the next section). + +@cindex Macro names, valid characters in +@cindex 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, +@command{makeinfo} 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 @{@}}) or with no braces at all (@samp{@@macro +foo}). + +@cindex 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}. + +@cindex Parameters to macros +In the macro body, instances of a parameter name surrounded by +backslashes, as in @samp{\@var{param1}\} in the example above, are +replaced by the corresponding argument from the macro invocation. You +can use parameter names any number of times in the body, including zero. + +@cindex Backslash in macros +To get a single @samp{\} in the macro expansion, use @samp{\\}. Any +other use of @samp{\} in the body yields a warning. + +@cindex Spaces in macros +@cindex Whitespace in macros +The newline characters after the @code{@@macro} line and before the +@code{@@end macro} line are ignored, that is, not included in the +macro body. All other whitespace is treated according to the usual +Texinfo rules. However, there are still undesirable and unpredictable +interactions between newlines, macros, and commands which are +line-delimited, as warned about below (@pxref{Macro Details}). + +@cindex Recursive macro invocations +@findex rmacro +To allow a macro to be used recursively, that is, in an argument to a +call to itself, you must define it with @samp{@@rmacro}, like this: + +@example +@@rmacro rmac @{arg@} +a\arg\b +@@end rmacro +@dots{} +@@rmac@{1@@rmac@{text@}2@} +@end example + +This produces the output `a1atextb2b'. With @samp{@@macro} instead of +@samp{@@rmacro}, an error message is given. + +@findex unmacro +@cindex Macros, undefining +@cindex 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: + +@example +@@unmacro foo +@end example + + +@node Invoking Macros +@section Invoking Macros + +@cindex Invoking macros +@cindex Expanding macros +@cindex Running macros +@cindex Macro invocation + +After a macro is defined (see the previous section), you can +@dfn{invoke} (use) it in your document like this: + +@example +@@@var{macroname} @{@var{arg1}, @var{arg2}, @dots{}@} +@end example + +@noindent and the result will be more or less as if you typed the body of +@var{macroname} at that spot. For example: + +@example +@@macro foo @{p, q@} +Together: \p\ & \q\. +@@end macro +@@foo@{a, b@} +@end example + +@noindent produces: + +@display +Together: a & b. +@end display + +@cindex Backslash, and macros +Thus, the arguments and parameters are separated by commas and +delimited by braces; any whitespace after (but not before) a comma is +ignored. The braces are required in the invocation even when the +macro takes no arguments, consistent with other Texinfo commands. For +example: + +@example +@@macro argless @{@} +No arguments here. +@@end macro +@@argless@{@} +@end example + +@noindent produces: + +@display +No arguments here. +@end display + +@cindex 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{@@comma@{@}} +command. For @code{makeinfo}, you can also prepend a backslash +character, as in @samp{\,}, but this does not work with @TeX{}. + +@cindex Automatic quoting of commas for some macros +@cindex 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: + +@enumerate 1 +@item If a macro takes only one argument, all commas in its invocation +are quoted by default. For example: + +@example +@group +@@macro TRYME@{text@} +@@strong@{TRYME: \text\@} +@@end macro + +@@TRYME@{A nice feature, though it can be dangerous.@} +@end group +@end example + +@noindent +will produce the following output + +@example +@strong{TRYME: A nice feature, though it can be dangerous.} +@end 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. + +@item 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 + +@example +@@say@{@@strong@{Yes, I do@}, person one@} +@end example + +the comma after @samp{Yes} is implicitly quoted. Here's another +example, with a recursive macro: + +@example +@group +@@rmacro cat@{a,b@} +\a\\b\ +@@end rmacro + +@@cat@{@@cat@{foo, bar@}, baz@} +@end group +@end example + +@noindent +will produce the string @samp{foobarbaz}. + +@item Otherwise, a comma should be explicitly quoted, as above, for it +to be treated as a part of an argument. +@end enumerate + +@cindex Braces, in macro arguments +@cindex 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: + +@example +@@@var{macname} @{\\\@{\@}\,@} +@end example + +@noindent +will pass the (almost certainly error-producing) argument +@samp{\@{@},} 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: + +@example +@@macro bar @{p@} +Twice: \p\ & \p\. +@@end macro +@@bar aah +@end example + +@noindent produces: + +@display +Twice: aah & aah. +@end 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: + +@example +@@macro bar @{p@} +Twice: \p\ & \p\. +@@end macro +@@bar@{a,b@} +@end example + +@noindent produces: + +@display +Twice: a,b & a,b. +@end 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: + +@example +@@macro addtwo @{p, q@} +Both: \p\\q\. +@@end macro +@@addtwo@{a@} +@end example + +@noindent produces simply: + +@display +Both: a. +@end display + + +@node Macro Details +@section Macro Details and Caveats +@cindex Macro details +@cindex Details of macro usage +@cindex Caveats for macro usage + +@cindex Macro expansion, contexts for +@cindex Expansion of macros, contexts for +By design, macro expansion does not happen in the following contexts +in @command{makeinfo}: + +@itemize @bullet +@item @code{@@macro} and @code{@@unmacro} lines; + +@item @code{@@if...} lines, including @code{@@ifset} and similar; + +@item @code{@@set}, @code{@@clear}, @code{@@value}; + +@item @code{@@clickstyle} lines; + +@item @code{@@end} lines. +@end itemize + +@noindent 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 +@command{texi2dvi} with the @samp{-E} option (@pxref{Format with +@t{texi2dvi}}). Or, more reliably, eschew Texinfo macros altogether +and use a language designed for macro processing, such as M4 +(@pxref{External Macro Processors}). + +@itemize @bullet +@item +As mentioned earlier, macro names must consist entirely of letters. + +@item +It is not advisable to redefine any @TeX{} primitive, plain, or +Texinfo command name as a macro. Unfortunately this is a large and +open-ended set of names, and the possible resulting errors are +unpredictable. + +@item +All macros are expanded inside at least one @TeX{} group. + +@item +Macro arguments cannot cross lines. + +@item +Macros containing a command which must be on a line by itself, such as +a conditional, cannot be invoked in the middle of a line. Similarly, +macros containing line-oriented commands or text, such as +@code{@@example} environments, may behave unpredictably in @TeX{}. + +@item +White space is ignored at the beginnings of lines. + +@item +Macros can't be reliably used in the argument to accent commands +(@pxref{Inserting Accents}). + +@item +The backslash escape for commas in macro arguments does not work; +@code{@@comma@{@}} must be used. + +@item +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: + +@example +@@macro mactwo@{argfirst, argsecond@} +\argfirst\+\argsecond\. +@@end macro +@@set fc Fran@@,cois +@@mactwo@{@@value@{fc@}@} +@end example + +@noindent produces: + +@display +Fran@,cois+. +@end display + +The natural-seeming @code{@@mactwo@{Fran@@,cois@}} 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. + +@item +It is usually best to avoid comments inside macro definitions, but +see the next item. + +@item +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: + +@example +@@macro linemac +@@cindex whatever @@c +@@end macro +... +foo +@@linemac +bar +@end 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). + +@item +In general, you can't arbitrarily substitute a macro (or +@code{@@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: + +@example +@@macro offmacro +off +@@end macro +@@headings @@offmacro +@end example + +@noindent +This looks equivalent to @code{@@headings off}, but for @TeX{}nical +reasons, it fails with a mysterious error message (namely, +@samp{Paragraph ended before @@headings was complete}). + +@item +Macros cannot define macros in the natural way. To do this, you must +use conditionals and raw @TeX{}. For example: + +@example +@@ifnottex +@@macro ctor @{name, arg@} +@@macro \name\ +something involving \arg\ somehow +@@end macro +@@end macro +@@end ifnottex +@@tex +\gdef\ctor#1@{\ctorx#1,@} +\gdef\ctorx#1,#2,@{\def#1@{something involving #2 somehow@}@} +@@end tex +@end example +@end itemize + +The @command{makeinfo} implementation also has the following +limitations (by design): + +@itemize +@item +@code{@@verbatim} and macros do not mix; for instance, you can't start +a verbatim block inside a macro and end it outside +(@pxref{@t{@@verbatim}}). Starting any environment inside a macro +and ending it outside may or may not work, for that matter. + +@item +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. +@end 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: + +@example +@@macro twolines@{@} +aaa +bbb +@@end macro +@@center @@twolines@{@} +@end example + +In the current @code{makeinfo}, this is equivalent to: + +@example +@@center aaa +bbb +@end example + +@noindent with just @samp{aaa} as the argument to @code{@@center}. In +the earlier implementation, it would have been parsed as this: + +@example +@@center aaa bbb +@end example + + +@node @t{@@alias} +@section @samp{@@alias @var{new}=@var{existing}} + +@anchor{alias}@c old name +@cindex Aliases, command +@cindex Command aliases +@findex alias + +The @samp{@@alias} command defines a new command to be just like an +existing one. This is useful for defining additional markup names, +thus preserving 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: + +@example +@@alias @var{new} = @var{existing} +@end example + +For example, if your document contains citations for both books and +some other media (movies, for example), you might like to define a +macro @code{@@moviecite@{@}} that does the same thing as an ordinary +@code{@@cite@{@}} but conveys the extra semantic information as well. +You'd do this as follows: + +@example +@@alias moviecite = cite +@end example + +Macros do not always have the same effect 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. + +@command{makeinfo} will accept the same identifiers for aliases as it +does for macro names, that is, alphanumerics and (except as the first +character) @samp{-}. + + +@node @t{@@definfoenclose} +@section @code{@@definfoenclose}: Customized Highlighting + +@anchor{definfoenclose}@c old name +@cindex Highlighting, customized +@cindex Customized highlighting +@findex definfoenclose + +An @code{@@definfoenclose} command may be used to define a +highlighting command for all the non-@TeX{} output formats. A command +defined using @code{@@definfoenclose} marks text by enclosing it in +strings that precede and follow the text. You can use this to get +closer control of your output. + +Presumably, if you define a command with @code{@@definfoenclose}, you +will create a corresponding command for @TeX{}, either in +@file{texinfo.tex}, @file{texinfo.cnf}, or within an @samp{@@iftex} of +@samp{@@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 +@code{@@definfoenclose} is the @@-command name (without the +@code{@@}); 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 +@code{@@i}), the enclosure definition will override the built-in +definition. We don't recommend this. + +An enclosure command defined this way takes one argument in braces, +since it is intended for new markup commands (@pxref{Marking Text}). + +@findex phoo +For example, you can write: + +@example +@@definfoenclose phoo,//,\\ +@end example + +@noindent +near the beginning of a Texinfo file to define @code{@@phoo} as an Info +formatting command that inserts `//' before and `\\' after the argument +to @code{@@phoo}. You can then write @code{@@phoo@{bar@}} wherever you +want `//bar\\' highlighted in Info. + +For @TeX{} formatting, you could write + +@example +@@iftex +@@global@@let@@phoo=@@i +@@end iftex +@end example + +@noindent +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 +@samp{@@iftex}. @code{@@definfoenclose} command need not be within +@samp{@@ifinfo}, unless you want to use different definitions for +different output formats. + +@findex headword +Here is another example: write + +@example +@@definfoenclose headword, , : +@end example + +@noindent +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}. + +@samp{@@definfoenclose} definitions must not be recursive, directly or +indirectly. + + +@node External Macro Processors +@section External Macro Processors: Line Directives +@cindex External macro processors +@cindex 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. + +@cindex Line numbers, in error messages +@cindex 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 +@samp{#line} directive. Texinfo supports this. + +@menu +* @t{#line} Directive:: +* TeX: @t{#line} and @TeX{}. +* Syntax: @t{#line} Syntax Details. +@end menu + + +@node @t{#line} Directive +@subsection @samp{#line} Directive + +@cindex @samp{#line} directive + +An input line such as this: + +@example +@hashchar{}line 100 "foo.ptexi" +@end example + +@noindent indicates that the next line was line 100 of the file +@file{foo.ptexi}, 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 +@ref{Preprocessor Output,,, cpp, The C Preprocessor}) can generate +such lines. + +@vindex CPP_LINE_DIRECTIVES +The @command{makeinfo} program recognizes these lines by default, +except within @code{@@verbatim} blocks (@pxref{@t{@@verbatim}}. +Their recognition can be turned off completely with +@code{CPP_LINE_DIRECTIVES} (@pxref{Other Customization Variables}), +though there is normally no reason to do so. + +For those few programs (M4, CPP, Texinfo) which need to document +@samp{#line} directives and therefore have examples which would +otherwise match the pattern, the command @code{@@hashchar@{@}} can be +used (@pxref{Inserting a Hashsign}). The example line above looks +like this in the source for this manual: + +@example +@@hashchar@{@}line 100 "foo.ptexi" +@end 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 +@code{@@value} to insert the literal @samp{#}: + +@example +@@set hash # +@@value@{hash@}line 1 "example.c" +@end 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. + + +@node @t{#line} and @TeX{} +@subsection @samp{#line} and @TeX{} + +@cindex @TeX{} and @samp{#line} directives +@cindex @samp{#line} directives, not processing with @TeX{} + +As mentioned, @command{makeinfo} recognizes the @samp{#line} +directives described in the previous section. However, +@file{texinfo.tex} 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 +@TeX{}. There are three approaches: + +@itemize @bullet +@item +If you run @command{texi2dvi} or its variants (@pxref{Format with +@t{texi2dvi}}), you can pass @option{-E} and @command{texi2dvi} +will run @command{makeinfo} first to expand macros and eliminate +@samp{#line}. + +@item +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 +@code{texi2dvi} in a separate command. + +@item +Or you can run @option{makeinfo --dvi --Xopt -E}. (Or @option{--pdf} +instead of @option{--dvi}.) @command{makeinfo} will then call +@command{texi2dvi -E}. +@end itemize + +@findex errormsg@r{, 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 +@code{@@errormsg@{@}} command (@pxref{Conditional Commands}), or by +@TeX{} 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 +@command{makeinfo} for the best diagnostics (@pxref{@t{makeinfo} +Advantages}). + + +@node @t{#line} Syntax Details +@subsection @samp{#line} Syntax Details + +@cindex @samp{#line} syntax details +@cindex Syntax details, @samp{#line} +@cindex 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: + +@example +/^\s*#\s*(line)? (\d+)(( "([^"]+)")(\s+\d+)*)?\s*$/ +@end example + +As far as we've been able to tell, the trailing integer flags only +occur in conjunction with a filename, so that is reflected in the +regular expression. + +As an example, the following is a syntactically valid @samp{#line} +directive, meaning line 1 of @file{/usr/include/stdio.h}: + +@example +@hashchar{} 1 "/usr/include/stdio.h" 2 3 4 +@end 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., + +@example +@hashchar{} 1 +@end example + +The possible solutions are described above (@pxref{@t{#line} Directive}). + + +@node Include Files +@chapter Include Files + +@cindex 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 +@code{@@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. + +@menu +* 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. +@end menu + + +@node Using Include Files +@section How to Use Include Files + +@findex include + +To include another file within a Texinfo file, write the +@code{@@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: + +@example +@@include buffers.texi +@end example + +@@-commands are expanded in file names. The one most likely to be +useful is @code{@@value} (@pxref{@t{@@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 +@code{@@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 +@code{@@setfilename} line exists in an included file, it is ignored. + + +@node @t{texinfo-multiple-files-update} +@section @code{texinfo-multiple-files-update} + +@findex texinfo-multiple-files-update + +XEmacs Texinfo mode provides the +@code{texinfo-multiple-files-update} 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: + +@table @kbd +@item M-x texinfo-multiple-files-update +Called without any arguments: + +@itemize @minus +@item +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. + +@item +Create or update the `Top' level node pointers of the outer or +overall file. + +@item +Create or update a main menu in the outer file. +@end itemize + +@item C-u M-x texinfo-multiple-files-update +Called with @kbd{C-u} as a prefix argument: + +@itemize @minus{} +@item +Create or update pointers in the first @code{@@node} line in each +included file. + +@item +Create or update the `Top' level node pointers of the outer file. + +@item +Create and insert a master menu in the outer file. The master menu +is made from all the menus in all the included files. +@end itemize + +@item C-u 8 M-x texinfo-multiple-files-update +Called with a numeric prefix argument, such as @kbd{C-u 8}: + +@itemize @minus +@item +Create or update @strong{all} the `Next', `Previous', and `Up' pointers +of all the included files. + +@item +Create or update @strong{all} the menus of all the included +files. + +@item +Create or update the `Top' level node pointers of the outer or +overall file. + +@item +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. +@end itemize +@end table + +Note the use of the prefix argument in interactive use: with a regular +prefix argument, just @w{@kbd{C-u}}, the +@code{texinfo-multiple-files-update} 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. + + +@node Include Files Requirements +@section Include Files Requirements +@cindex Include files requirements +@cindex 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 +@code{@@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 +@code{texinfo-multiple-files-update} command will not process +them. + + +@node Sample Include File +@section Sample File with @code{@@include} +@cindex Sample @code{@@include} file +@cindex Include file sample +@cindex @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: + +@example +@group +\input texinfo @@c -*-texinfo-*- +@c %**start of header +@@setfilename include-example.info +@@settitle Include Example +@c %**end of header +@end group + +... @xref{Sample Texinfo Files}, for +examples of the rest of the frontmatter ... + +@group +@@ifnottex +@@node Top +@@top Include Example +@@end ifnottex +@end group + +@group +@@include foo.texinfo +@@include bar.texinfo +@@include concept-index.texinfo +@@bye +@end group +@end example + +An included file, such as @file{foo.texinfo}, might look like this: + +@example +@group +@@node First +@@chapter First Chapter + +Contents of first chapter @dots{} +@end group +@end example + +The full contents of @file{concept-index.texinfo} might be as simple as this: + +@example +@group +@@node Concept Index +@@unnumbered Concept Index + +@@printindex cp +@end group +@end example + +The outer Texinfo source file for @cite{The XEmacs Lisp Reference +Manual} is named @file{lispref.texi}. This outer file contains a master +menu with 417 entries and a list of 41 @code{@@include} +files. + + +@node Include Files Evolution +@section Evolution of Include Files + +When Info was first created, it was customary to create many small +Info files on one subject. Each Info file was formatted from its own +Texinfo source file. This custom meant that XEmacs did not need to +make a large buffer to hold the whole of a large Info file when +someone wanted information; instead, XEmacs allocated just enough +memory for the small Info file that contained the particular +information sought. This way, XEmacs 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, , +@code{@@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 +@code{@@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 XEmacs 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. + + +@node Hardcopy +@chapter Formatting and Printing Hardcopy +@cindex Format and print hardcopy +@cindex Printing hardcopy +@cindex Hardcopy, printing it +@cindex Making a printed manual +@cindex Sorting indices +@cindex Indices, sorting +@cindex @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 XEmacs (or some other computing +environment). + +If you are using XEmacs, 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. + +@menu +* 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 XEmacs:: How to format and print from an XEmacs shell. +* Texinfo Mode Printing:: How to format and print in Texinfo mode. +* Compile-Command:: How to print using XEmacs'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{}. +@end menu + + +@node Use @TeX{} +@section Use @TeX{} + +The typesetting program called @TeX{} is used for formatting a Texinfo +file. @TeX{} is a very powerful typesetting program and, when used +correctly, does an exceptionally good job. + +@xref{Obtaining @TeX{}}, for information on how to obtain @TeX{}. It +is not included in the Texinfo package, being a vast suite of software +itself. + + +@node Format with @t{tex}/@t{texindex} +@section Format with @code{tex}/@code{texindex} + +@cindex Shell formatting with @code{tex} and @code{texindex} +@cindex Formatting with @code{tex} and @code{texindex} +@cindex DVI file + +You can format the Texinfo file with the shell command @code{tex} +followed by the name of the Texinfo file. For example: + +@example +tex foo.texi +@end example + +@noindent @TeX{} will produce a @dfn{DVI file} as well as several auxiliary +files containing information for indices, cross references, etc. The +DVI file (for @dfn{DeVice Independent} file) can be printed on virtually +any device (see the following sections). + +@pindex texindex +The @code{tex} formatting command itself does not sort the indices; it +writes an output file of unsorted index data. 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 +@command{tex} and @command{texindex} as necessary.) + +@anchor{Names of index files} +@cindex Names of index files +@cindex Index file names +@code{tex} formatting command outputs unsorted index files under names +that obey a standard convention: the name of your main input file with +any @samp{.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 +@file{foo.texinfo} would be @file{foo.cp}, @file{foo.vr}, +@file{foo.fn}, @file{foo.tp}, @file{foo.pg} and @file{foo.ky}. Those +are exactly the arguments to give to @code{texindex}. + +@need 1000 +@cindex Wildcards +@cindex Globbing +Instead of specifying all the unsorted index file names explicitly, you +can use @samp{??} as shell wildcards and give the command in this +form: + +@example +texindex foo.?? +@end example + +@noindent +This command will run @code{texindex} on all the unsorted index files, +including any two letter indices that you have defined yourself using +@code{@@defindex} or @code{@@defcodeindex}. You can safely run +@samp{texindex foo.??} even if there are files with two letter +extensions that are not index files, such as @samp{foo.el}. The +@code{texindex} command reports but otherwise ignores such files. + +For each file specified, @code{texindex} generates a sorted index file +whose name is made by appending @samp{s} to the input file name. The +@code{@@printindex} command 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: + +@enumerate +@item +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). + +@item +Run @code{texindex} on the raw index files. This creates the +corresponding sorted index files (with three letter extensions). + +@item +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. + +@item +Sort the indices again, with @code{texindex}. + +@item +Run @code{tex} one last time. This time the correct page numbers are +written for the cross references. +@end enumerate + +@pindex texi2dvi +Alternatively, it's a one-step process: run @code{texi2dvi} +(@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 +@code{texindex}. This is usually ok while you are debugging. + +@cindex Auxiliary files, avoiding +@findex novalidate +@cindex Pointer validation, suppressing +@cindex Chapters, formatting one at a time +Sometimes you may wish to print a document while you know it is +incomplete, or to print just one chapter of a document. In that case, +the usual auxiliary files that @TeX{} creates and warnings @TeX{} +gives when cross references are not satisfied are just nuisances. You +can avoid them with the @code{@@novalidate} command, which you must +give @emph{before} the @code{@@setfilename} command +(@pxref{@t{@@setfilename}}). Thus, the beginning of your file +would look approximately like this: + +@example +\input texinfo +@@novalidate +@@setfilename myfile.info +@dots{} +@end example + +@noindent @code{@@novalidate} also turns off validation in +@code{makeinfo}, just like its @code{--no-validate} option +(@pxref{Pointer Validation}). + + +@node Format with @t{texi2dvi} +@section Format with @code{texi2dvi} + +@pindex texi2dvi @r{(shell script)} + +The @code{texi2dvi} command automatically runs both @TeX{} and +@command{texindex} 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 +@code{tex}---@code{texindex}---@code{tex}---@code{tex} sequence +described in the previous section. + +To run @code{texi2dvi} on an input file @file{foo.texi}, do this (where +@samp{prompt$ } is your shell prompt): + +@example +prompt$ @kbd{texi2dvi foo.texi} +@end 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. + +@opindex --command@r{, for @command{texi2dvi}} +One useful option to @code{texi2dvi} is @samp{--command=@var{cmd}}. +This inserts @var{cmd} on a line by itself after the +@code{@@setfilename} in a temporary copy of the input file before +running @TeX{}. With this, you can specify different printing +formats, such as @code{@@smallbook} (@pxref{@t{@@smallbook}}), +@code{@@afourpaper} (@pxref{A4 Paper}), or @code{@@pagesizes} +(@pxref{@t{@@pagesizes}}), without actually changing the document +source. (You can also do this on a site-wide basis with +@file{texinfo.cnf}; @pxref{Preparing for @TeX{}}). + +@opindex --pdf@r{, for @command{texi2dvi}} +@pindex 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 +@command{texi2pdf} is an abbreviation for running @samp{texi2dvi +--pdf}. The command @command{pdftexi2dvi} is also supported as a +convenience to AUC-@TeX{} users (@pxref{Top,,, auctex, AUC-@TeX{}}, since +that program merely prepends @samp{pdf} to DVI producing tools to have +PDF producing tools. + +@opindex --dvipdf@r{, for @command{texi2dvi}} +@pindex dvipdfmx +With the @option{--dvipdf} option, @command{texi2dvi} produces PDF +output by running @TeX{} and then a DVI-to-PDF program: if the +@env{DVIPDF} environment variable is set, that value is used, else +the first extant among @code{dvipdfmx}, @code{dvipdfm}, @code{dvipdf}, +@code{dvi2pdf}, @code{dvitopdf}. This method can support CJK +typesetting better than @command{pdftex}. + +@opindex --ps@r{, for @command{texi2dvi}} +@pindex 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.) + +@cindex @LaTeX{}, processing with @command{texi2dvi} +@command{texi2dvi} can also be used to process @LaTeX{} files; simply +run @samp{texi2dvi filename.ext}. + +@opindex --language@r{, 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 +@option{--language=@var{lang}} command line option, where @var{lang} +is either @samp{latex} or @samp{texinfo}. + +@command{texi2dvi} 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}. + +@opindex --translate-file@r{, for @command{texi2dvi}} +Several options are provided for handling documents, written in +character sets other than ASCII@. The +@option{--translate-file=@var{file}} option instructs +@command{texi2dvi} 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}). + +@opindex --recode@r{, for @command{texi2dvi}} +The options @option{--recode} and @option{--recode-from=@var{enc}} +allow conversion of an input document before running @TeX{}. The +@option{--recode} option recodes the document from encoding specified +by @samp{@@documentencoding} command +(@pxref{@t{@@documentencoding}}) to plain 7-bit @samp{texinfo} +encoding. + +@opindex --recode-from@r{, for @command{texi2dvi}} +The option @option{--recode-from=@var{enc}} recodes the document from +@var{enc} encoding to the encoding specified by +@samp{@@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 @option{--recode-from=@var{enc}} use +@command{recode} utility to perform the conversion. If +@command{recode} 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 +@option{--expand}) does Texinfo macro expansion using +@command{makeinfo} instead of the @TeX{} implementation (@pxref{Macro +Details}). Each implementation has its own limitations and +advantages. If this option is used, the string +@code{@@c@tie{}_texi2dvi} must not appear at the beginning of a line +in the source file. + +For the list of all options, run @samp{texi2dvi --help}. + + +@node Print with @t{lpr} +@section Print With @code{lpr -d} From Shell + +@pindex 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}: + +@example +@group +tex bison.texinfo +texindex bison.?? +tex bison.texinfo +lpr -d bison.dvi +@end group +@end example + +@noindent +(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): + +@example +@group +texi2dvi bison.texinfo +lpr -d bison.dvi +# or perhaps dvips bison.dvi -o +@end group +@end example + +@cindex Shell printing, on MS-DOS/MS-Windows +@cindex Printing DVI files, on MS-DOS/MS-Windows +@pindex lpr@r{-d, replacements on MS-DOS/MS-Windows} +@code{lpr} is a standard program on Unix systems, but it is usually +absent on MS-DOS/MS-Windows. Some network packages come with a +program named @code{lpr}, but these are usually limited to sending files +to a print server over the network, and generally don't support the +@samp{-d} option. If you are unfortunate enough to work on one of these +systems, you have several alternative ways of printing DVI files: + +@itemize @bullet{} +@item Find and install a Unix-like @code{lpr} program, or its clone. +If you can do that, you will be able to print DVI files just like +described above. + +@item Send the DVI files to a network printer queue for DVI files. +Some network printers have special queues for printing DVI files. You +should be able to set up your network software to send files to that +queue. In some cases, the version of @code{lpr} which comes with your +network software will have a special option to send a file to specific +queues, like this: + +@example +lpr -Qdvi -hprint.server.domain bison.dvi +@end example + +@item Convert the DVI file to a Postscript or PCL file and send it to your +local printer. @xref{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}. +@end itemize + + +@node Within XEmacs +@section From an XEmacs Shell +@cindex Print, format from XEmacs shell +@cindex Format, print from XEmacs shell +@cindex Shell, format, print from +@cindex XEmacs shell, format, print from + +You can give formatting and printing commands from a shell within +XEmacs. To create a shell within XEmacs, 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 XEmacs shell. For example, +here is how to use @code{texi2dvi} to format and print @cite{Using and +Porting GNU CC} from a shell within XEmacs: + +@example +@group +texi2dvi gcc.texinfo +lpr -d gcc.dvi +@end group +@end example + +See the next section for more information about formatting +and printing in Texinfo mode. + + +@node Texinfo Mode Printing +@section Formatting and Printing in Texinfo Mode +@cindex Region printing in Texinfo mode +@cindex Format and print in Texinfo mode +@cindex 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. + +@table @kbd +@item C-c C-t C-b +@itemx M-x texinfo-tex-buffer +Run @code{texi2dvi} on the current buffer. + +@item C-c C-t C-r +@itemx M-x texinfo-tex-region +Run @TeX{} on the current region. + +@item C-c C-t C-i +@itemx M-x texinfo-texindex +Sort the indices of a Texinfo file formatted with +@code{texinfo-tex-region}. + +@item C-c C-t C-p +@itemx M-x texinfo-tex-print +Print a DVI file that was made with @code{texinfo-tex-region} or +@code{texinfo-tex-buffer}. + +@item C-c C-t C-q +@itemx M-x tex-show-print-queue +Show the print queue. + +@item C-c C-t C-d +@itemx 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}). + +@item C-c C-t C-k +@itemx M-x tex-kill-job +Kill the currently running @TeX{} job started by either +@code{texinfo-tex-region} or @code{texinfo-tex-buffer}, or any other +process running in the Texinfo shell buffer. + +@item C-c C-t C-x +@itemx 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. + +@item C-c C-t C-l +@itemx 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. +@end table + +@need 1000 +Thus, the usual sequence of commands for formatting a buffer is as +follows (with comments to the right): + +@example +@group +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.} +@end group +@end example + +The Texinfo mode @TeX{} formatting commands start a subshell in XEmacs +called the @file{*tex-shell*}. The @code{texinfo-tex-command}, +@code{texinfo-texindex-command}, 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. + +@need 1500 +The formatting and print commands depend on the values of several variables. +The default values are: + +@example +@group + @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" +@end group +@end example + +You can change the values of these variables with the @kbd{M-x +set-variable} command (@pxref{Examining, , Examining and Setting +Variables, xemacs, XEmacs User's Manual}), or with your @file{init.el} +initialization file (@pxref{Init File, , , xemacs, XEmacs User's +Manual}). + +@cindex Customize XEmacs package (@t{Development/Docs/Texinfo}) +Beginning with version 20, XEmacs offers a user-friendly interface, +called @dfn{Customize}, for changing values of user-definable variables. +@xref{Easy Customization, , Easy Customization Interface, xemacs, XEmacs +User's Manual}, for more details about this. The Texinfo variables can +be found in the @samp{Development/Docs/Texinfo} group, once you invoke +the @kbd{M-x customize} command. + + +@node Compile-Command +@section Using the Local Variables List +@cindex Local variables +@cindex Compile command for formatting +@cindex 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 XEmacs run it by typing +@kbd{M-x compile}. This creates a special shell called the +@file{*compilation*} buffer in which XEmacs runs the compile command. +For example, at the end of the @file{gdb.texinfo} file, after the +@code{@@bye}, you could put the following: + +@example +@group +Local Variables: +compile-command: "texi2dvi gdb.texinfo" +End: +@end group +@end example + +@noindent +This technique is most often used by programmers who also compile programs +this way; see @ref{Compilation, , , xemacs, XEmacs User's Manual}. + + +@node Requirements Summary +@section @TeX{} Formatting Requirements Summary +@cindex Requirements for formatting +@cindex Minimal requirements for formatting +@cindex Formatting requirements + +Every Texinfo file that is to be input to @TeX{} must begin with a +@code{\input} command and must contain an @code{@@setfilename} command: + +@example +\input texinfo +@@setfilename @var{arg-not-used-by-@TeX{}} +@end example + +@noindent +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: + +@example +@@bye +@end 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 +@code{@@bye}, the end of a file usually includes indices and a table of +contents. (And of course most manuals contain a body of text as well.) + +For more information, see: + +@itemize @bullet +@item @ref{@t{@@settitle}}. +@item @ref{@t{@@setchapternewpage}}. +@item @ref{Headings}. +@item @ref{Titlepage & Copyright Page}. +@item @ref{Printing Indices & Menus}. +@item @ref{Contents}. +@end itemize + + +@node Preparing for @TeX{} +@section Preparing for @TeX{} +@cindex Preparing for @TeX{} +@cindex @TeX{} input initialization +@cindex @b{.profile} initialization file +@cindex @b{.cshrc} initialization file +@cindex Initialization file for @TeX{} input + +@TeX{} needs to know where to find the @file{texinfo.tex} file that the +@samp{\input texinfo} command on the first line reads. The +@file{texinfo.tex} 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: +@smalldisplay +@uref{http://savannah.gnu.org/cgi-bin/viewcvs/texinfo/texinfo/doc/texinfo.tex?rev=HEAD} +@end smalldisplay + +@pindex texinfo.tex@r{, installing} + +Usually, the installer has put the @file{texinfo.tex} file in the +default directory that contains @TeX{} macros when GNU Texinfo, XEmacs 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. + +@pindex epsf.tex@r{, 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}). + +@cindex European Computer Modern fonts, installing +@cindex EC fonts, installing +@cindex 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}). + +@pindex feymr10@r{, installing} +@cindex Euro font, installing +If you intend to use the @code{@@euro} command, you should install the +Euro font, if it is not already installed. @xref{@t{@@euro}}. + +@pindex texinfo.cnf @r{installation} +@cindex Customizing of @TeX{} for Texinfo +@cindex 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 +@code{@@setfilename} command is executed (@pxref{@t{@@setfilename}}). +You can put any commands you like there, according to local site-wide +conventions. They will be read by @TeX{} when processing any Texinfo +document. For example, if @file{texinfo.cnf} contains the line +@samp{@@afourpaper} (@pxref{A4 Paper}), then all Texinfo documents +will be processed with that page size in effect. If you have nothing +to put in @file{texinfo.cnf}, you do not need to create it. + +@cindex Environment variable @code{TEXINPUTS} +@vindex TEXINPUTS +If neither of the above locations for these system files suffice for +you, you can specify the directories explicitly. For +@file{texinfo.tex}, you can do this by writing the complete path for the +file after the @code{\input} command. Another way, that works for both +@file{texinfo.tex} and @file{texinfo.cnf} (and any other file @TeX{} +might read), is to set the @code{TEXINPUTS} environment variable in your +@file{.profile} 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}, +@code{ksh}, @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: + +@example +@group +TEXINPUTS=.:/home/me/mylib: +export TEXINPUTS +@end group +@end example + +@need 1000 +While in a @file{.cshrc} file, you could use the following @code{csh} +command sequence: + +@example +setenv TEXINPUTS .:/home/me/mylib: +@end example + + +On MS-DOS/MS-Windows, you would say it like this@footnote{Note the use +of the @samp{;} character as directory separator, instead of @samp{:}.}: + +@example +@group +set TEXINPUTS=.;d:/home/me/mylib;c: +@end group +@end example + +@noindent +It is customary for DOS/Windows users to put such commands in the +@file{autoexec.bat} file, or in the Windows registry. + +@noindent +These settings would cause @TeX{} to look for @file{\input} file first +in the current directory, indicated by the @samp{.}, then in a +hypothetical user @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.) + +@cindex Dumping a .fmt file +@cindex Format file, dumping +Finally, you may wish to dump a @file{.fmt} file (@pxref{Memory dumps,,, +web2c, Web2C}) so that @TeX{} can load Texinfo faster. (The +disadvantage is that then updating @file{texinfo.tex} requires +redumping.) You can do this by running this command, assuming +@file{epsf.tex} is findable by @TeX{}: + +@example +initex texinfo @@dump +@end example + +@noindent +(@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. + + +@node Overfull hboxes +@section Overfull ``hboxes'' +@cindex Overfull @samp{hboxes} +@cindex @samp{hbox}, overfull +@cindex Final output + +@TeX{} 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: + +@example +Overfull @@hbox (20.76302pt too wide) +@end example + +@findex hbox +@noindent +(In @TeX{}, lines are in ``horizontal boxes'', hence the term, ``hbox''. +@samp{@@hbox} is a @TeX{} primitive not used in the Texinfo language.) + +@TeX{} also provides the line number in the Texinfo source file and +the text of the offending line, which is marked at all the places that +@TeX{} considered hyphenation. +@xref{Debugging 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: + +@findex \emergencystretch +@example +@@tex +\global\emergencystretch = .9\hsize +@@end tex +@end example + +@noindent +(You should adjust the fraction as needed.) This huge value for +@code{\emergencystretch} cannot be the default, since then the typeset +output would generally be of noticeably lower quality; the default +is @samp{.15\hsize}. @code{\hsize} is the @TeX{} dimension +containing the current line width. + +@cindex Black rectangle in hardcopy +@cindex Rectangle, black in hardcopy +@cindex Box, ugly black in hardcopy +@cindex Ugly black rectangles in hardcopy +For what overfull boxes you have, however, @TeX{} will print a large, +ugly, black rectangle beside the line that contains the overfull hbox +unless told otherwise. This is so you will notice the location of the +problem if you are correcting a draft. + +@findex finalout +To prevent such a monstrosity from marring your final printout, write +the following in the beginning of the Texinfo file on a line of its own, +before the @code{@@titlepage} command: + +@example +@@finalout +@end example + + +@node @t{@@smallbook} +@section @code{@@smallbook}: Printing ``Small'' Books + +@anchor{smallbook}@c old name +@findex smallbook +@cindex Small book size +@cindex Book, printing small +@cindex Page sizes for books +@cindex Size of printed book + +By default, @TeX{} typesets pages for printing in an 8.5 by 11 inch +format. However, you can direct @TeX{} to typeset a document in a 7 by +9.25 inch format that is suitable for bound books by inserting the +following command on a line by itself at the beginning of the Texinfo +file, before the title page: + +@example +@@smallbook +@end example + +@noindent +(Since many books are about 7 by 9.25 inches, this command might better +have been called the @code{@@regularbooksize} command, but it came to be +called the @code{@@smallbook} command by comparison to the 8.5 by 11 +inch format.) + +If you write the @code{@@smallbook} command between the +start-of-header and end-of-header lines, the Texinfo mode @TeX{} +region formatting command, @code{texinfo-tex-region}, will format the +region in ``small'' book size (@pxref{Start of Header}). + +@xref{@t{@@small@dots{}}}, for information about commands that make +it easier to produce examples for a smaller manual. + +@xref{Format with @t{texi2dvi}}, and @ref{Preparing for @TeX{}}, +for other ways to format with @code{@@smallbook} that do not require +changing the source file. + + +@node A4 Paper +@section Printing on A4 Paper +@cindex A4 paper, printing on +@cindex A5 paper, printing on +@cindex Paper size, A4 +@cindex European A4 paper +@findex afourpaper + +You can tell @TeX{} to format a document for printing on European size +A4 paper (or A5) with the @code{@@afourpaper} (or @code{@@afivepaper}) +command. Write the command on a line by itself near the beginning of +the Texinfo file, before the title page. For example, this is how you +would write the header for this manual: + +@example +@group +\input texinfo @@c -*-texinfo-*- +@@c %**start of header +@@setfilename texinfo +@@settitle Texinfo +@@afourpaper +@@c %**end of header +@end group +@end example + +@xref{Format 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. + +@findex afourlatex +@findex afourwide +You may or may not prefer the formatting that results from the command +@code{@@afourlatex}. There's also @code{@@afourwide} for A4 paper in +wide format. + + +@node @t{@@pagesizes} +@section @code{@@pagesizes} [@var{width}][, @var{height}]: Custom Page Sizes +@anchor{pagesizes}@c old node name + +@findex pagesizes +@cindex Custom page sizes +@cindex Page sizes, customized +@cindex Text width and height +@cindex Width of text area +@cindex Height of text area +@cindex Depth of text area + +You can explicitly specify the height and (optionally) width of the main +text area on the page with the @code{@@pagesizes} command. Write this +on a line by itself near the beginning of the Texinfo file, before the +title page. The height comes first, then the width if desired, +separated by a comma. Examples: + +@example +@@pagesizes 200mm,150mm @c for b5 paper +@end example +@noindent and +@example +@@pagesizes 11.5in @c for legal paper +@end example + +@cindex B5 paper, printing on +@cindex Legal paper, printing on +This would be reasonable for printing on B5-size paper. To emphasize, +this command specifies the size of the @emph{text area}, not the size of +the paper (which is 250@dmn{mm} by 177@dmn{mm} for B5, 14@dmn{in} by +8.5@dmn{in} for legal). + +@cindex Margins on page, not controllable +To make more elaborate changes, such as changing any of the page +margins, you must define a new command in @file{texinfo.tex} or +@file{texinfo.cnf}. + +@xref{Format with @t{texi2dvi}}, and @ref{Preparing for @TeX{}}, +for other ways to specify @code{@@pagesizes} that do not require +changing the source file. + +@code{@@pagesizes} is ignored by @code{makeinfo}. + + +@node Cropmarks and Magnification +@section Cropmarks and Magnification + +@findex cropmarks +@cindex Cropmarks for printing +@cindex Printing cropmarks +You can (attempt to) direct @TeX{} to print cropmarks at the corners +of pages with the @code{@@cropmarks} command. Write the +@code{@@cropmarks} command on a line by itself near the beginning of +the Texinfo file, before the title page, like this: + +@example +@@cropmarks +@end 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 +@file{texinfo.tex}. + +The @code{@@cropmarks} command is recognized and ignored in non-@TeX{} +output formats. + +@findex \mag @r{(raw @TeX{} magnification)} +@cindex Magnified printing +@cindex Larger or smaller pages +You can attempt to direct @TeX{} to typeset pages larger or smaller +than usual with the @code{\mag} @TeX{} command. Everything that is +typeset is scaled proportionally larger or smaller. (@code{\mag} +stands for ``magnification''.) This is @emph{not} a Texinfo +@@-command, but is a raw @TeX{} command that is prefixed with a +backslash. You have to write this command between @code{@@tex} and +@code{@@end tex} (@pxref{Raw Formatter Commands}). + +Follow the @code{\mag} command with an @samp{=} and then a number that +is 1000 times the magnification you desire. For example, to print pages +at 1.2 normal size, write the following near the beginning of the +Texinfo file, before the title page: + +@example +@group +@@tex +\mag=1200 +@@end tex +@end group +@end example + +With some printing technologies, you can print normal-sized copies that +look better than usual by giving a larger-than-normal master to your +print shop. They do the reduction, thus effectively increasing the +resolution. + +Depending on your system, DVI files prepared with a +nonstandard-@code{\mag} may not print or may print only with certain +magnifications. Be prepared to experiment. + + +@node PDF Output +@section PDF Output +@cindex PDF output + +@pindex 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}. + +@dfn{PDF} stands for `Portable Document Format'. It was invented by +Adobe Systems some years ago for document interchange, based on their +PostScript language. Related links: + +@itemize +@item +GNU GV, a @uref{http://www.gnu.org/software/gv/, Ghostscript-based PDF +reader}. (It can also preview PostScript documents.) + +@item +@code{xpdf}, a freely available standalone +@uref{http://www.foolabs.com/xpdf/, PDF reader} for the X window +system. + +@item +@uref{http://partners.adobe.com/asn/acrobat/sdk/public/docs/, PDF definition}. + +@end 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. + + +@node Obtaining @TeX{} +@section Obtaining @TeX{} +@cindex Obtaining @TeX{} +@cindex @TeX{}, how to obtain + +@TeX{} is a document formatter that is used by the FSF for its +documentation. It is the easiest way to get printed output (e.g., PDF +and PostScript) for Texinfo manuals. TeX is freely redistributable, +and you can get it over the Internet or on physical media. See +@url{http://tug.org/texlive}. + +@c please keep that text in sync with www.gnu.org/prep/FTP + + +@node Generic Translator @t{texi2any} +@chapter @code{texi2any}: The Generic Translator for Texinfo + +@command{texi2any} is the generic translator for Texinfo that can +produce different output formats and is highly customizable. It +supports these formats: + +@table @asis +@item Info (by default, or with @option{--info}), + +@item HTML (with @option{--html}), + +@item plain text (with @option{--plaintext}), + +@item Docbook (with @option{--docbook}), + +@item Texinfo XML (with @option{--xml}). +@end table + +@command{makeinfo} 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 +@command{texi2any} 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. + +@menu +* 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}. +@end menu + + +@node Reference Implementation +@section @command{texi2any}: A Texinfo Reference Implementation + +@cindex @command{texi2any}, as reference implementation +@cindex Reference implementation +@cindex Implementation, @command{texi2any} as reference + +Above, we called @command{texi2any} ``the'' translator for Texinfo +instead of just ``a'' translator, even though (of course) it's +technically and legally possible for other implementations to be +written. The reason is that alternative implementations are very +likely to have subtle, or not-so-subtle, differences in behavior, and +thus Texinfo documents would become dependent on the processor. +Therefore, it is important to have a reference implementation that +defines parts of the language not fully specified by the manual (often +intentionally so). It is equally important to have consistent +command-line options and other behavior for all processors. + +@cindex Tree representation of documents +@cindex Syntax tree representation of documents +@cindex Abstract syntax tree representation of documents +For this reason, the once-independent @command{texi2html} Perl Texinfo +processor was made compatible with the C implementation of +@command{makeinfo}, to avoid continuing with two different +implementations (@pxref{History}). The current implementation, +@command{texi2any}, serves as the reference implementation. It +inherited the design of customization and other features from +@command{texi2html} (for more on @command{texi2html} compatibility, +@pxref{@t{texi2html}}). However, @code{texi2any} is a full +reimplementation: it constructs a tree-based representation of the +input document for all back-ends to work from. + +@cindex Texinfo language tests +@cindex Tests, of Texinfo language +Extensive tests of the language were developed at the same time as +@command{texi2any}; we plead with anyone thinking of writing a program +to parse Texinfo input to at least make use of these tests. + +@cindex Examples of using @command{texi2any} +@findex Texinfo::Parser module +The @command{texi2html} wrapper script (@pxref{@t{texi2html}}) +provides a very simple example of calling @command{texi2any} from a +shell script; it's in @file{util/texi2html} in the Texinfo sources. +More consequentially, @command{texi-elements-by-size} is an example +Perl script using the @code{Texinfo::Parser} module interface; it's +also in the @file{util} source directory. (Its functionality may also +be useful to authors; @pxref{texi-elements-by-size}.) + +@cindex Future of Texinfo implementations +With the release of @command{texi2any} as the reference +implementation, development of both the C implementation of +@command{makeinfo} and @command{texi2html} has been halted. Going +forward, we ask authors of Texinfo documents to use only +@command{texi2any}. + + +@node Invoking @t{texi2any} +@section Invoking @command{texi2any}/@code{makeinfo} from a Shell + +@anchor{Invoking makeinfo} +@pindex makeinfo +@pindex texi2any + +To process a Texinfo file, invoke @command{texi2any} or +@command{makeinfo} (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: + +@example +texi2any --info bison.texinfo +@end 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. + +@anchor{@t{makeinfo} Options} +@c anchor{makeinfo options}@c prev name, but case-insensitive clash +@cindex @code{makeinfo} options +@cindex Options for @code{makeinfo} +@anchor{texi2any Options} +@cindex @code{texi2any} options +@cindex Options for @code{texi2any} + +The @command{texi2any} program accept many options. Perhaps the +most basic are those that change the output format. By default, +@command{texi2any} 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: + +@example +texi2any --fill-column=68 bison.texinfo +@end example + +You can write two or more options in sequence, like this: + +@example +texi2any --no-split --fill-column=70 @dots{} +@end example + +@noindent +(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): + +@table @code +@item --commands-in-node-names +@opindex --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.) + +@item --conf-dir=@var{path} +@opindex --conf-dir=@var{path} +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 +@c Init Files}. + +@item --css-include=@var{file} +@opindex --css-include +When producing HTML, literally include the contents of @var{file}, +which should contain W3C cascading style sheets specifications, in the +@samp{<style>} block of the HTML output. If @var{file} is @samp{-}, +read standard input. @xref{HTML CSS}. + +@item --css-ref=@var{url} +@opindex --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. + +@item -D @var{var} +@opindex -D @var{var} +Cause the Texinfo variable @var{var} to be defined. This is +equivalent to @code{@@set @var{var}} in the Texinfo file +(@pxref{@t{@@set @@clear @@value}}). + +@item --disable-encoding +@itemx --enable-encoding +@opindex --disable-encoding +@opindex --enable-encoding +By default, or with @option{--enable-encoding}, output accented and +special characters in Info and plain text output based on +@samp{@@documentencoding}. With @option{--disable-encoding}, 7-bit +ASCII transliterations are output. @xref{@t{@@documentencoding}}, +and @ref{Inserting Accents}. + +@item --docbook +@opindex --docbook +Generate Docbook output (rather than Info). + +@item --document-language=@var{lang} +@opindex --document-language +Use @var{lang} to translate Texinfo keywords which end up in the +output document. The default is the locale specified by the +@code{@@documentlanguage} command if there is one, otherwise English +(@pxref{@t{@@documentlanguage}}). + +@item --dvi +@opindex --dvi +Generate a TeX DVI file using @command{texi2dvi}, rather than Info +(@pxref{@t{texi2any} Printed Output}). + +@item --dvipdf +@opindex --dvipdf +Generate a PDF file using @command{texi2dvi --dvipdf}, rather than +Info (@pxref{@t{texi2any} Printed Output}). + +@item --error-limit=@var{limit} +@itemx -e @var{limit} +@opindex --error-limit=@var{limit} +@opindex -e @var{limit} +Report @var{LIMIT} errors before aborting (on the assumption that +continuing would be useless); default 100. + +@item --fill-column=@var{width} +@itemx -f @var{width} +@opindex --fill-column=@var{width} +@opindex -f @var{width} +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. + +@item --footnote-style=@var{style} +@itemx -s @var{style} +@opindex --footnote-style=@var{style} +@opindex -s @var{style} +Set the footnote style to @var{style}: either @samp{end} for the end +node style (the default) or @samp{separate} for the separate node +style. The value set by this option overrides the value set in a +Texinfo file 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 +@samp{separate}, and the output is split, they are placed in a +separate file. + +@item --force +@itemx -F +@opindex --force +@opindex -F +Ordinarily, if the input file has errors, the output files are not +created. With this option, they are preserved. + +@item --help +@itemx -h +@opindex --help@r{, for @command{texi2any}} +@opindex -h +Print a message with available options and basic usage, then exit +successfully. + +@item --html +@opindex --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}. + +@item -I @var{path} +@opindex -I @var{path} +Append @var{path} to the directory search list for finding files that +are included using the @code{@@include} command. By default, +@code{texi2any} searches only the current directory. If @var{path} is +not given, the current directory is appended. The @var{path} value +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). + +@item --ifdocbook +@opindex --ifdocbook +@itemx --ifhtml +@opindex --ifhtml +@itemx --ifinfo +@opindex --ifinfo +@itemx --ifplaintext +@opindex --ifplaintext +@itemx --iftex +@opindex --iftex +@itemx --ifxml +@opindex --ifxml +For the given format, process @samp{@@if@var{format}} and +@samp{@@@var{format}} commands, and do not process +@samp{@@ifnot@var{format}}, regardless of the format being output. +For instance, if @option{--iftex} is given, then @samp{@@iftex} and +@samp{@@tex} blocks will be read, and @samp{@@ifnottex} blocks will be +ignored. + +@item --info +@opindex --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} (@pxref{@t{@@setfilename}}). @xref{Tag and +Split Files}. + +@item --init-file=@var{file} +@opindex --init-file=@var{file} +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 +@code{.init} extensions for these customization files, but that is not +enforced; the @var{file} name can be anything. The +@option{--conf-dir} option (see above) can be used to add to the list +of directories in which these customization files are searched for. +@c @xref{Loading Init Files}. + +@item --internal-links=@var{file} +@opindex --internal-links=@var{file} +@cindex 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. + +@item --macro-expand=@var{file} +@itemx -E @var{file} +@opindex --macro-expand=@var{file} +@opindex -E @var{file} +Output the Texinfo source, with all Texinfo macros expanded, to +@var{file}. Normally, the result of macro expansion is used +internally by @code{makeinfo} and then discarded. + +@item --no-headers +@opindex --no-headers +@cindex Node separators, omitting with @option{--no-headers} +@cindex Generating plain text files with @option{--no-headers} +@cindex 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, +@code{@@setfilename} is ignored, and output is to standard output +unless overridden with @option{-o}. (This behavior is for backward +compatibility.) + +@cindex 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. +@xref{Generating HTML}. + +@item --no-ifdocbook +@opindex --no-ifdocbook +@itemx --no-ifhtml +@opindex --no-ifhtml +@itemx --no-ifinfo +@opindex --no-ifinfo +@itemx --no-ifplaintext +@opindex --no-ifplaintext +@itemx --no-iftex +@opindex --no-iftex +@itemx --no-ifxml +@opindex --no-ifxml +For the given format, do not process @samp{@@if@var{format}} and +@samp{@@@var{format}} commands, and do process +@samp{@@ifnot@var{format}}, 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. + +@item --no-node-files +@itemx --node-files +@opindex --no-node-files +@opindex --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. +@option{--no-node-files} suppresses the creation of redirection files +in any case. This option has no effect with any output format other +than HTML@. @xref{Generating HTML}. + +@item --no-number-footnotes +@opindex --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. + +@item --no-number-sections +@itemx --number-sections +@opindex --no-number-sections +@opindex --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 +@code{--no-number-sections} if your manual is not normally structured. + +@item --no-pointer-validate +@itemx --no-validate +@opindex --no-pointer-validate +@opindex --no-validate +@cindex 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}. + +@item --no-warn +@opindex --no-warn +Suppress warning messages (but not error messages). + +@item --output=@var{file} +@itemx -o @var{file} +@opindex --output=@var{file} +@opindex -o @var{file} +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. @xref{@t{@@setfilename}}. + +If @var{file} is @samp{-}, output goes to standard output and +@samp{--no-split} 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 +@code{@@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 +@file{bar/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, +@samp{makeinfo -o bar --html foo.texi} will write +@file{bar/index.html}, among other files. + +@item --output-indent=@var{val} +@opindex --outputindent +This option now does nothing, but remains for compatibility. (It used +to alter indentation in XML/Docbook output.) + +@item -P @var{path} +@opindex -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 +@samp{-I} above. + +@item --paragraph-indent=@var{indent} +@itemx -p @var{indent} +@opindex --paragraph-indent=@var{indent} +@opindex -p @var{indent} +Set the paragraph indentation style to @var{indent}. The value set by +this option overrides the value set in a Texinfo file by an +@code{@@paragraphindent} command (@pxref{@t{@@paragraphindent}}). +The value of @var{indent} is interpreted as follows: + +@table @asis +@item @samp{asis} +Preserve any existing indentation (or lack thereof) at the beginnings +of paragraphs. + +@item @samp{0} or @samp{none} +Delete any existing indentation. + +@item @var{num} +Indent each paragraph by @var{num} spaces. +@end table + +The default is to indent by two spaces, except for paragraphs +following a section heading, which are not indented. + +@item --pdf +@opindex --pdf +Generate a PDF file using @command{texi2dvi --pdf}, rather than Info +(@pxref{@t{texi2any} Printed Output}). + +@item --plaintext +@opindex --plaintext +@cindex Plain text output with @option{--plaintext} +@cindex ASCII text output with @option{--plaintext} +@cindex Generating plain text files with @option{--plaintext} +@cindex Node separators, omitting with @option{--plaintext} +@cindex Menus, omitting with @option{--plaintext} +@cindex @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 +@file{INSTALL} file). + +With this option, @code{@@setfilename} is ignored and the output goes +to standard output by default; this can be overridden with @option{-o}. + +@item --ps +@opindex --ps +Generate a PostScript file using @command{texi2dvi --ps}, rather than +Info (@pxref{@t{texi2any} Printed Output}). + +@item --set-customization-variable @var{var}=@var{value} +@itemx -c @var{var}=@var{value} +@opindex --set-customization-variable @var{var}=@var{value} +@opindex -c @var{var}=@var{value} +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 +@command{texi2any} 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}. + +@item --split=@var{how} +@itemx --no-split +@opindex --split=@var{how} +@opindex --no-split +@cindex Splitting of output files +@cindex Output file splitting +@anchor{Splitting Output} +@c +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, @option{--split=@var{how}} may be used to specify at +which level the HTML output should be split. The possible values for +@var{how} are: + +@table @samp +@item chapter +The output is split at @code{@@chapter} and other sectioning +@@-commands at this level (@code{@@appendix}, etc.). + +@item section +The output is split at @code{@@section} and similar. + +@item node +The output is split at every node. This is the default. +@end table + +@item --split-size=@var{num} +@opindex --split-size=@var{num} +Keep Info files to at most @var{num} characters if possible; default +is 300,000. (However, a single node will never be split across Info +files.) + +@item --transliterate-file-names +@opindex --transliterate-file-names +Enable transliteration of 8-bit characters in node names for the +purpose of file name creation. @xref{HTML Xref 8-bit Character Expansion}. + +@item -U @var{var} +Cause @var{var} to be undefined. This is equivalent to @code{@@clear +@var{var}} in the Texinfo file (@pxref{@t{@@set @@clear @@value}}). + +@item --verbose +@opindex --verbose +Cause @code{makeinfo} to display messages saying what it is doing. +Normally, @code{makeinfo} only outputs messages if there are errors or +warnings. + +@item --version +@itemx -V +@opindex --version@r{, for @command{texi2any}} +@opindex -V +Print the version number, then exit successfully. + +@item --Xopt @var{str} +@opindex --Xopt @var{str} +Pass @var{str} (a single shell word) to @command{texi2dvi}; may be +repeated (@pxref{@t{texi2any} Printed Output}). + +@item --xml +@opindex --xml +Generate Texinfo XML output (rather than Info). + +@end table + +@vindex TEXINFO_OUTPUT_FORMAT +@cindex Environment variable @code{TEXINFO_OUTPUT_FORMAT} +@command{makeinfo} also reads the environment variable +@env{TEXINFO_OUTPUT_FORMAT} to determine the output format, if not +overridden by a command line option. The value should be one of: + +@example +docbook dvi dvipdf html info pdf plaintext ps xml +@end 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}. + + +@node @t{texi2any} Printed Output +@section @command{texi2any} Printed Output + +@cindex Printed output, through @command{texi2any} +@cindex Output, printed through @command{texi2any} + +To justify the name Texinfo-to-@emph{any}, @command{texi2any} has +basic support for creating printed output in the various formats: +@TeX{} 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}, +@option{--dvipdf}, @option{--pdf}, and @option{--ps}. @xref{Format +with @t{texi2dvi}}, for more details on these options and general +@command{texi2dvi} operation. In addition, the @option{--verbose}, +@option{--silent}, 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 + +@example +texi2any --Xopt -t --Xopt @@a4paper --pdf foo.texi +@end example + +@noindent is equivalent to running + +@example +texi2dvi -t @@a4paper --pdf foo.texi +@end 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 +@code{TEXI2DVI} customization variable (@pxref{Other Customization +Variables}). As you might guess, the default is @samp{texi2dvi}. + +@command{texi2any} itself does not generate any output when it invokes +@command{texi2dvi}. + + +@node Pointer Validation +@section Pointer Validation +@cindex Pointer validation with @code{makeinfo} +@cindex Validation of pointers + +If you do not suppress pointer validation with the +@samp{--no-validate} option or the @code{@@novalidate} command in the +source file (@pxref{Use @TeX{}}), @code{makeinfo} will check the +validity of the Texinfo file. + +Most validation checks are different depending on whether node +pointers are explicitly or implicitly determined. With explicit node +pointers, here is the list of what is checked: + +@enumerate +@item +If a `Next', `Previous', or `Up' node reference is a reference to a +node in the current file and is not an external reference such as to +@file{(dir)}, then the referenced node must exist. + +@item +Every node except the `Top' node must have an `Up' pointer. + +@item +The node referenced by an `Up' pointer must itself reference the +current node through a menu item, unless the node referenced by `Up' +has the form @samp{(@var{file})}. +@end enumerate + +With implicit node pointers, the above error cannot occur, as such. +(Which is a major reason why we recommend using this feature of +@code{makeinfo}, and not specifying any node pointers yourself.) + +Instead, @code{makeinfo} checks that the tree constructed from the +document's menus matches the tree constructed from the sectioning +commands. For example, if a chapter-level menu mentions nodes +@var{n1} and @var{n2}, in that order, nodes @var{n1} and @var{n2} must +be associated with @code{@@section} commands in the chapter. + +Finally, with both explicit and implicit node pointers, +@code{makeinfo} checks that every node except the `Top' node is +referenced in a menu. + + +@node Customization Variables +@section Customization Variables + +@quotation 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. +@end quotation + +Many aspects of the behavior and output of @command{texi2any} may be +modified by modifying so-called @dfn{customization variables}. These +fall into a few general categories: + +@itemize @bullet +@item +Those associated with @@-commands; for example, +@code{@@documentlanguage}. + +@item +Those associated with command-line options; for example, the +customization variable @code{SPLIT} is associated with the +@option{--split} command-line option, and @code{TEXINFO_OUTPUT_FORMAT} +allows specifying the output format. + +@item +Those associated with customizing the HTML output. + +@item +Other ad hoc variables. +@end itemize + +Customization variables may set on the command line using +@code{--set-customization-variable '@var{var} @var{value}'} (quoting +the variable/value pair to the shell) or +@code{--set-customization-variable @var{var}=@var{value}} (using +@code{=}). 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. + +@menu +* Commands: Customization Variables for @@-Commands. +* Options: Customization Variables and Options. +* HTML: HTML Customization Variables. +* Other: Other Customization Variables. +@end menu + + +@node Customization Variables for @@-Commands +@subsection Customization Variables for @@-Commands + +@cindex Customization variables for @@-commands +@cindex @@-commands, customization variables for + +Each of the following @@-commands has an associated customization +variable with the same name (minus the leading @code{@@}): + +@smallexample +@@allowcodebreaks @@clickstyle @@codequotebacktick +@@codequoteundirected @@contents @@deftypefnnewline +@@documentdescription @@documentencoding @@documentlanguage +@@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 +@end 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}. + + +@node Customization Variables and Options +@subsection Customization Variables and Options + +@cindex Customization variables for options +@cindex 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. + +@multitable @columnfractions 0.5 0.5 +@headitem Option @tab Variable +@vindex ENABLE_ENCODING +@item @option{--enable-encoding} @tab @code{ENABLE_ENCODING} +@vindex documentlanguage +@item @option{--document-language} @tab @code{documentlanguage} +@vindex ERROR_LIMIT +@item @option{--error-limit} @tab @code{ERROR_LIMIT} +@vindex FILLCOLUMN +@item @option{--fill-column} @tab @code{FILLCOLUMN} +@vindex footnotestyle +@item @option{--footnote-style} @tab @code{footnotestyle} +@vindex FORCE +@item @option{--force} @tab @code{FORCE} +@vindex INTERNAL_LINKS +@item @option{--internal-links} @tab @code{INTERNAL_LINKS} +@vindex MACRO_EXPAND +@item @option{--macro-expand} @tab @code{MACRO_EXPAND} +@vindex HEADERS +@vindex SHOW_MENU +@item @option{--headers} @tab @code{HEADERS}, @code{SHOW_MENU} +@vindex NO_WARN +@item @option{--no-warn} @tab @code{NO_WARN} +@vindex novalidate +@item @option{--no-validate} @tab @code{novalidate} +@vindex NUMBER_FOOTNOTES +@item @option{--number-footnotes} @tab @code{NUMBER_FOOTNOTES} +@vindex NUMBER_SECTIONS +@item @option{--number-sections} @tab @code{NUMBER_SECTIONS} +@vindex NODE_FILES +@item @option{--node-files} @tab @code{NODE_FILES} +@vindex OUT +@vindex OUTFILE +@vindex SUBDIR +@item @option{--output} @tab @code{OUT}, @code{OUTFILE}, + @code{SUBDIR} +@vindex paragraphindent +@item @option{--paragraph-indent} @tab @code{paragraphindent} +@vindex SILENT +@item @option{--silent} @tab @code{SILENT} +@vindex SPLIT +@item @option{--split} @tab @code{SPLIT} +@vindex SPLIT_SIZE +@item @option{--split-size} @tab @code{SPLIT_SIZE} +@vindex TRANSLITERATE_FILE_NAMES +@item @option{--transliterate-file-names} @tab @code{TRANSLITERATE_FILE_NAMES} +@vindex VERBOSE +@item @option{--verbose} @tab @code{VERBOSE} +@end multitable + +Setting such a customization variable to a value @samp{foo} is +essentially the same as specifying the @code{--@var{opt}=foo} if the +option takes an argument, or @code{--@var{opt}} if not. + +@vindex 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: + +@ftable @samp +@item docbook +@itemx dvi +@itemx dvipdf +@itemx html +@itemx info +@itemx pdf +@itemx plaintext +@itemx ps +@itemx xml +These correspond to the command-line options (and +@code{TEXINFO_OUTPUT_FORMAT} environment variable values) of the same +name. @xref{Invoking @t{texi2any}}. + +@item debugcount +Instead of generating a regular output format, output the count of +bytes and lines obtained when converting to Info, and other information. + +@item debugtree +@cindex tree representation, for debugging +@cindex 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. + +@item parse +Do only Texinfo source parsing; there is no output. + +@item plaintexinfo +Output the Texinfo source with all the macros, @code{@@include} and +@code{@@value@{@}} expanded. This is similar to setting +@option{--macro-expand}, but instead of being output in addition to +the normal conversion, output of Texinfo is the main output. + +@item rawtext +@cindex 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. + +@item structure +Do only Texinfo source parsing and determination of the document +structure; there is no output. + +@item texinfosxml +@cindex SXML output +@cindex S-expressions, output format +Output the document in TexinfoSXML representation, a syntax for +writing XML data using Lisp S-expressions. + +@item textcontent +@cindex spell checking +@cindex word counting +@pindex detexinfo +@cindex stripping Texinfo commands +Output the text content only, stripped of commands; this is useful for +spell checking or word counting, for example. The trivial +@code{detexinfo} script setting this is in the @file{util} directory +of the Texinfo source as an example. It's one line: + +@example +exec texi2any -c TEXINPUT_OUTPUT_FORMAT=textcontent "$@@" +@end example +@end ftable + + +@node HTML Customization Variables +@subsection HTML Customization Variables + +This table gives the customization variables which apply to HTML +output only. A few other customization variable apply to both HTML +and other output formats; those are given in the next section. + +@vtable @code +@item AVOID_MENU_REDUNDANCY +For HTML@. If set, and the menu entry and menu description are the +same, then do not print the menu description; default false. + +@item AFTER_BODY_OPEN +For HTML@. If set, the corresponding text will appear at the +beginning of each HTML file; default unset. + +@item 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. + +@item AFTER_OVERVIEW +@itemx AFTER_TOC_LINES +For HTML@. 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 +@code{AFTER_OVERVIEW} is set, and you should set +@code{BEFORE_TOC_LINES} if @code{AFTER_TOC_LINES} is set. + + +@item BASEFILENAME_LENGTH +For HTML@. 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}). + +@item BEFORE_OVERVIEW +@itemx BEFORE_TOC_LINES +For HTML@. 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 +@code{BEFORE_OVERVIEW} is set, and you should set +@code{AFTER_TOC_LINES} if @code{BEFORE_TOC_LINES} is set. + + +@item BIG_RULE +For HTML@. Rule used after and before the top element and before +special elements, but not for footers and headers; default +@code{<hr>}. + +@item BODYTEXT +@cindex @code{<body>} text, customizing +For HTML, the text appearing in @code{<body>}. By default, set +automatically, taking into account the document language +(@pxref{@t{@@documentlanguage}}). + +@item CASE_INSENSITIVE_FILENAMES +For HTML@. Construct output file names as if the filesystem were case +insensitive (@pxref{HTML Splitting}); default false. + +@item CHAPTER_HEADER_LEVEL +For HTML@. Header formatting level used for chapter level sectioning +commands; default @samp{2}. + +@item CHECK_HTMLXREF +For HTML@. Check that manuals which are the target of external +cross references (@pxref{Four and Five Arguments}) are present in +@file{htmlxref.cnf} (@pxref{HTML Xref Configuration}); default false. + +@item COMPLEX_FORMAT_IN_TABLE +For HTML@. If set, use tables for indentation of complex formats; default +false. + +@item CSS_LINES +For HTML@. CSS output, automatically determined by default (@pxref{HTML CSS}). + +@item DATE_IN_HEADER +For HTML@. Put the document generation date in the header; off by default. + +@item DEF_TABLE +For HTML@. 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. + +@item DEFAULT_RULE +For HTML@. Rule used between element, except before and after the +top element, and before special elements, and for footers and headers; +default @code{<hr>}. + +@item DO_ABOUT +For HTML@. If set to 0 never do an About special element; +if set to 1 always do an About special element; +default 0. +@c @xref{Output Elements Defined}. + +@item EXTERNAL_DIR +For HTML@. 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. + +@item EXTRA_HEAD +For HTML@. Additional text appearing within @code{<head>}; default unset. + +@item FOOTNOTE_END_HEADER_LEVEL +For HTML@. Header formatting level used for the footnotes header with +the `end' footnotestyle; default @samp{4}. @xref{Footnote Styles}. + +@item FOOTNOTE_SEPARATE_HEADER_LEVEL +For HTML@. Header formatting level used for the footnotes header with +the `separate' footnotestyle; default @samp{4}. @xref{Footnote +Styles}. + +@item FRAMES +For HTML@. If set, a file describing the frame layout is generated, +together with a file with the short table of contents; default false. + +@item FRAMESET_DOCTYPE +For HTML@. Same as DOCTYPE, but for the file containing the frame +description. + +@item HEADER_IN_TABLE +For HTML@. Use tables for header formatting rather than a simple +@code{<div>} element; default false. + +@item ICONS +For HTML@. Use icons for the navigation panel; default false. + +@item IMAGE_LINK_PREFIX +For HTML@. If set, the associated value is prepended to the image file +links; default unset. + +@item INLINE_CONTENTS +For HTML@. If set, output the contents where the @code{@@contents} and +similar @@-commands are located; default true. This is ignored if +@code{@@set*contentsaftertitlepage} is set (@pxref{Contents}). + +@item INLINE_CSS_STYLE +For HTML@. Put CSS directly in HTML elements rather than at the +beginning of the output; default false. + +@item KEEP_TOP_EXTERNAL_REF +For HTML@. If set, do not ignore @samp{Top} as the first +argument for an external ref to a manual, as is done by default. +@xref{Top Node Naming}. + +@item L2H +For HTML@. If set, @command{latex2html} is used to convert @code{@@math} +and @code{@@tex} sections; default false. Best used with @option{--iftex}. + +@item L2H_CLEAN +(Relevant only if @code{L2H} is set.) If set, the intermediate files +generated in relation with @command{latex2html} are removed; default +true. + +@item L2H_FILE +(Relevant only if @code{L2H} is set.) If set, the given file is used +as @command{latex2html}'s init file; default unset. + +@item L2H_HTML_VERSION +(Relevant only if @code{L2H} is set.) The HTML version used in the +@command{latex2html} call; default unset. + +@item L2H_L2H +(Relevant only if @code{L2H} is set.) The program invoked as +@command{latex2html}; default is @code{latex2html}. + +@item 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 +@samp{undef}. + +@item 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. + +@item MAX_HEADER_LEVEL +For HTML@. Maximum header formatting level used (higher header +formatting level numbers correspond to lower sectioning levels); +default @samp{4}. + +@item MENU_SYMBOL +For HTML@. Symbol used in front of menu entries when node names are used +for menu entries formatting; default @samp{•}. + +@item MONOLITHIC +For HTML@. Output only one file including the table of contents. Set +by default, but only relevant when the output is not split. + +@item NO_CSS +For HTML@. Do not use CSS; default false. @xref{HTML CSS}. + +@item NODE_FILE_EXTENSION +For HTML@. Extension for node files if @code{NODE_FILENAMES} is set; +default @samp{html}. + +@item 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. + +@item PRE_BODY_CLOSE +For HTML@. If set, the given text will appear at the footer of each +HTML file; default unset. + +@item PROGRAM_NAME_IN_FOOTER +For HTML@. If set, output the program name and miscellaneous related +information in the page footers; default false. + +@item SHORTEXTN +For HTML@. If set, use @samp{.htm} as extension; default false. + +@item SHOW_TITLE +For HTML@. If set, output the title at the beginning of the document; +default true. + +@item SIMPLE_MENU +For HTML@. If set, use a simple preformatted style for the menu, +instead of breaking down the different parts of the menu; default false. +@xref{Menu Parts}. + +@item TOC_LINKS +For HTML@. If set, links from headings to toc entries are created; +default false. + +@item 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 HTML@. + +@item TOP_NODE_FILE +For HTML@. File name used for the Top node, if @code{NODE_FILENAMES} +is set; default is @code{index}. + +@item TOP_NODE_FILE_TARGET +For HTML@. File name used for the Top node in cross references; +default is @code{index}. + +@item TOP_NODE_UP_URL +For HTML@. The url used for the Up pointer of the Top node; default +@code{undef}, meaning no link is generated. + +@item USE_ACCESSKEY +@cindex @code{accesskey}, customization variable for +For HTML@. Use @code{accesskey} in cross references; default true. + +@item USE_ISO +For HTML@. Use entities for doubled single-quote characters +(@pxref{Inserting Quotation Marks}), and @samp{---} and @samp{--} +(@pxref{Conventions}); default true. + +@item USE_LINKS +@cindex @code{<link>} HTML tag, in @code{<head>} +@cindex @code{<head>} HTML tag, and @code{<link>} +For HTML@. Generate @code{<link>} elements in the HTML @code{<head>} +output; default true. + +@item USE_REL_REV +For HTML@. Use @code{rel} in cross references; default true. + +@item VERTICAL_HEAD_NAVIGATION +For HTML@. If set, a vertical navigation panel is used; default false. + +@item WORDS_IN_PAGE +@cindex 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. + +@item XREF_USE_FLOAT_LABEL +For HTML@. If set, for the float name in cross references, use the +float label instead of the type followed by the float number +(@pxref{@t{@@float}}). The default is off. + +@item XREF_USE_NODE_NAME_ARG +For HTML@. Only relevant for cross reference commands with no cross +reference name (second argument). If set to@tie{}1, use the node name +(first) argument in cross reference @@-commands for the text displayed +as the hyperlink. If set to@tie{}0, use the node name if +@code{USE_NODES} is set, otherwise the section name. If set to +@samp{undef}, use the first argument in preformatted environments, +otherwise use the node name or section name depending on +@code{USE_NODES}. The default is @samp{undef}. + +@end vtable + + +@node Other Customization Variables +@subsection 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. + +@vtable @code +@item 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). + +@c @item COMPLETE_IMAGE_PATHS +@c If set, the image files are computed to be relative from the document +@c directory to the source manual directory, and then to the image. + +@item CPP_LINE_DIRECTIVES +Recognize @code{#line} directives in a ``preprocessing'' pass +(@pxref{External Macro Processors}); on by default. + +@item DEBUG +If set, debugging output is generated; default is off (zero). +@c The integer value specifies what kinds of debugging output are +@c generated. It is a bitmask. Setting it to 255 ensures having all +@c available debugging output. + +@item DOCTYPE +@vindex SystemLiteral +For Docbook, HTML, XML@. Specifies the @code{SystemLiteral}, the +entity's system identifier. This is a URI which may be used to +retrieve the entity, and identifies the canonical DTD for the +document. The default value is different for each of HTML, Docbook +and Texinfo@tie{}XML. + +@item 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. + +@item DUMP_TREE +For debugging. If set, the tree constructed upon parsing a Texinfo +document is output to standard error; default false. + +@item ENABLE_ENCODING_USE_ENTITY +For HTML, XML@. 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. + +@item 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}. + +@item EXTENSION +The extension added to the output file name. The default is different +for each output format. + +@item 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. + +@c @item IDX_SUMMARY +@c If set, for each @code{@@printindex} a file named +@c @file{@var{docname}_@var{idxname}.idx} is created, containing lines of +@c the form: +@c +@c @example +@c @var{key} @var{reference} +@c @end example +@c +@c @noindent sorted alphabetically (case matters). + +@item IGNORE_BEFORE_SETFILENAME +If set, begin outputting at @code{@@setfilename}, if +@code{@@setfilename} is present; default true. + +@item IGNORE_SPACE_AFTER_BRACED_COMMAND_NAME +If set, spaces are ignored after an @@-command that takes braces. +Default true, matching the @TeX{} behavior. + +@item INDEX_ENTRY_COLON +Symbol used between the index entry and the associated node or section; +default @samp{:}. + +@item INFO_SPECIAL_CHARS_WARNING +If set, warn about problematic constructs for Info output (such as the +string @samp{::}) in node names, menu items, and cross references; +default true. Do not warn about index entries, since parsing problems +there don't prevent navigation; readers can still relatively easily +find their way to the node in question. + +@item INLINE_INSERTCOPYING +If set, @code{@@insertcopying} is replaced by the @code{@@copying} +content (@pxref{@t{@@copying}}) as if @code{@@insertcopying} were a +user-defined macro; default false. + +@item 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 +@code{@@documentencoding} (@pxref{@t{@@documentencoding}}). + +@item 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} +(@pxref{@t{@@documentencoding}}). + +@item 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. + +@item MAX_MACRO_CALL_NESTING +The maximal number of recursive calls of @@-commands defined through +@code{@@rmacro}; default 100000. The purpose of this variable is to +avoid infinite recursions. + +@item MENU_ENTRY_COLON +Symbol used between the menu entry and the description; default +@samp{:}. + +@item NO_USE_SETFILENAME +If set, do not use @code{@@setfilename} to set the document name; +instead, base the output document name only on the input file name. +The default is false. + +@item 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. + +@item NODE_NAME_IN_INDEX +If set, use node names in index entries, otherwise prefer section names; +default true. + +@item NODE_NAME_IN_MENU +If set, use node names in menu entries, otherwise prefer section names; +default true. + +@item OPEN_QUOTE_SYMBOL +When an opening quote is needed, e.g., for @samp{@@samp} output, use +the specified character; default @code{‘} for HTML, +@code{‘} for Docbook. For Info, the default depends on the +enabled document encoding (@pxref{@t{@@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. + +@item 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 +@code{@@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 +@code{utf-8} for @code{OUTPUT_ENCODING_NAME} if the encoding is not +otherwise specified. @xref{@t{@@documentencoding}}. + +@item OVERVIEW_LINK_TO_TOC +If set, the cross references in the Overview link to the corresponding +Table of Contents entries; default true. + +@item PACKAGE +@itemx PACKAGE_VERSION +@itemx PACKAGE_AND_VERSION +@itemx PACKAGE_URL +@itemx 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}. + +@item 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 +(@pxref{@t{@@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. + +@item PROGRAM +Name of the program used. By default, it is set to the name of the +program launched, with a trailing @samp{.pl} removed. + +@item RENAMED_NODES_FILE +If set, use the value for the renamed nodes description file. If not +set, the file is @file{@var{doc_basename}-noderename.cnf}. +@xref{HTML Xref Link Preservation}. + +@item RENAMED_NODES_REDIRECTIONS +If set, create redirection files for renamed nodes. Set by default +when generating HTML@. + +@item SHOW_MENU +@opindex --no-headers +If set, Texinfo menus are output. By default, it is set unless +generating Docbook or if @option{--no-headers} is specified. + +@item SORT_ELEMENT_COUNT +@pindex texi-elements-by-size +@cindex Longest nodes, finding +@cindex 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}). + +@item SORT_ELEMENT_COUNT_WORDS +When dumping the elements-by-size file (see preceding item), use word +counts instead of line counts; default false. + +@c @item SPLIT_INDEX +@c For HTML@. If set, the output is split, and the output from +@c @code{@@printindex} happens in a sectioning element at the level of +@c splitting, then split index pages at the next letter after they have +@c more than that many entries. If set to 0, no index splitting. + +@item TEST +If set to true, some variables which are normally dynamically +generated anew for each run (date, program name, version) are set to +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. + +@item TEXI2DVI +Name of the command used to produce PostScript, PDF, and DVI; default +@samp{texi2dvi}. @xref{@t{texi2any} Printed Output}. + +@item TEXI2HTML +@cindex compatibility, with @command{texi2html} +Generate HTML and try to be as compatible as possible with +@command{texi2html}; default false. + +@item TEXINFO_COLUMN_FOR_DESCRIPTION +Used with the @code{indent_menu_descriptions} tree transformation, +described below; default 32 (matching +@code{texinfo-column-for-description} in XEmacs)). + +@item TEXINFO_DTD_VERSION +For XML@. Version of the DTD used in the XML output preamble. The +default is set based on a variable in @file{configure.ac}. + +@item TEXTCONTENT_COMMENT +For stripped text content output (i.e., when +@code{TEXINFO_OUTPUT_FORMAT} is set to @code{textcontent}). If set, +also output comments. Default false. + +@item TOP_NODE_UP +Up node for the Top node; default @samp{(dir)}. + +@item 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 +@samp{move_index_entries_after_items} for HTML and Docbook output. +Here's an example of updating the master menu in a document: + +@example +makeinfo \ + -c TREE_TRANSFORMATIONS=regenerate_master_menu \ + -c PLAINTEXINFO=1 \ + mydoc.texi \ + -o /tmp/out +@end example + +@noindent (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; +@pxref{Invoking @t{pod2texi}}): + +@ftable @samp +@item complete_tree_nodes_menus +Add menu entries or whole menus for nodes associated with sections of +any level, based on the sectioning tree. + +@item fill_gaps_in_sectioning +Adds empty @code{@@unnumbered...} sections in a tree to fill gaps in +sectioning. For example, an @code{@@unnumberedsec} will be inserted +if an @code{@@chapter} is followed by an @code{@@subsection}. + +@item indent_menu_descriptions +Reformat menus so that descriptions start at column +@code{TEXINFO_COLUMN_DESCRIPTION}. + +@item insert_nodes_for_sectioning_commands +Insert nodes for sectioning commands lacking a corresponding node. + +@item move_index_entries_after_items +In @code{@@enumerate} and @code{@@itemize}, move index entries +appearing just before an @code{@@item} to just after the +@code{@@item}. Comment lines between index entries are moved too. As +mentioned, this is always done for HTML and Docbook output. + +@item regenerate_master_menu +Update the Top node master menu, either replacing the (first) +@code{@@detailmenu} in the Top node menu, or creating it at the end of +the Top node menu. + +@item 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 +@code{SIMPLE_MENU} only has an effect in HTML output. + +@end ftable + +@item 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. + +@item USE_NODE_TARGET +If set, use the node associated with a section for the section target +in cross references; default true. + +@item USE_NUMERIC_ENTITY +For HTML and XML@. If set, use numeric entities instead of ASCII +characters when there is no named entity. By default, set to true for +HTML. + +@item 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. + +@item 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. + +@item USE_TITLEPAGE_FOR_TITLE +Use the full @code{@@titlepage} as the title, not a simple title string; +default false. + +@item USE_UNIDECODE +@pindex Text::Unidecode +If set to false, do not use the @code{Text::Unidecode} Perl module to +transliterate more characters; default true. + +@end vtable + + +@node Internationalization of Document Strings +@section Internationalization of Document Strings + +@cindex I18n, of document strings +@cindex Internationalization of document strings +@cindex Document strings, internationalization of +@cindex Output document strings, internationalization of +@cindex Translating strings in output documents + +@vindex documentlanguage @r{customization variable} +@command{texi2any} 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 (@pxref{@t{@@documentlanguage}}, for the Texinfo +command interface). + +@pindex 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 +@code{gettext} 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). + +@vindex texinfo_document @r{Gettext domain} +@cindex 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 +@samp{@{arg_name@}}. (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, @samp{@{section@}} will be replaced by the section name: + +@example +see @{section@} +@end example + +These Perl-style brace format strings are used for two reasons: first, +changing the order of @code{printf} arguments is only available since +Perl@tie{}5.8.0; 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: + +@enumerate +@item First, the string is translated. The locale +is @var{@@documentlanguage}@code{.}@var{@@documentencoding}. + +@cindex @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 Latin@tie{}1 characters have associated +@@-commands. On the other hand, Japanese has only a translation +@code{ja.utf-8}, since there are no @@-commands for Japanese +characters. + +@item Next, the string is expanded as Texinfo, and converted. +The arguments are substituted; for example, @samp{@{arg_name@}} is +replaced by the corresponding actual argument. + +@end enumerate + +In the following example, @samp{@{date@}}, @samp{@{program_homepage@}} +and @samp{@{program@}} are the arguments of the string. Since they +are used in @code{@@uref}, their order is not predictable. +@samp{@{date@}}, @samp{@{program_homepage@}} and @samp{@{program@}} are +substituted after the expansion: + +@example +Generated on @@emph@{@{date@}@} using +@@uref@{@{program_homepage@}, @@emph@{@{program@}@}@}. +@end 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 +@samp{@@pxref} translation string can be like this: + +@example +see @{node_file_href@} section `@{section@}\' in @@cite@{@{book@}@} +@end example + +@noindent +which allows for specifying a string independently of the output +format, while nevertheless with rich formatting it may be translated +appropriately in many languages. + + +@node Invoking @t{pod2texi} +@section Invoking @t{pod2texi}: Convert POD to Texinfo + +@pindex pod2texi +@cindex Invoking @code{pod2texi} +@cindex POD, converting to Texinfo +@cindex 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 +@url{http://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 +@url{http://svn.savannah.gnu.org/viewvc/trunk/contrib/perldoc-all/?root=texinfo, +@file{contrib/perldoc-all}} in the Texinfo source distribution (the +output is available at @url{http://www.gnu.org/software/perl/manual}). + + +@node @t{texi2html} +@section @code{texi2html}: Ancestor of @code{texi2any} + +@pindex texi2html + +@cindex Cons, Lionel +Conceptually, the @command{texi2html} program is the parent of today's +@command{texi2any} program. @command{texi2html} was developed +independently, originally by Lionel Cons in 1998; at the time, +@command{makeinfo} could not generate HTML@. Many other people +contributed to @command{texi2html} over the years. + +The present @command{texi2any} uses little of the actual code of +@command{texi2html}, 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 +@command{texi2html} 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): + +@example +texi2any --set-customization-variable TEXI2HTML=1 ... +@end example + +@noindent but, to emphasize, this is @emph{not} a drop-in replacement +for the previous @command{texi2html}. Here are the biggest differences: + +@itemize @bullet +@item 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. + +@item The program-level customization API is very different in +@command{texi2any}. + +@item Indices cannot be split. + +@item Translated strings cannot be customized; we hope to introduce +this feature in @command{texi2any} in the future. + +@end 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. + +@cindex Options of @command{texi2html} +@cindex Command-line options of @command{texi2html} +Here is the table showing @command{texi2html} options and +corresponding @command{texi2any} customization variables. +@c (@pxref{texi2any Output Customization,, @command{texi2any} Output +@c Customization}). + +@multitable {@option{--ignore-preamble-text}} {@code{IGNORE_PREAMBLE_TEXT}} +@item @option{--toc-links} @tab @code{TOC_LINKS} +@item @option{--short-ext} @tab @code{SHORTEXTN} +@item @option{--prefix} @tab @code{PREFIX} +@item @option{--short-ref} @tab @code{SHORT_REF} +@item @option{--idx-sum} @tab @code{IDX_SUMMARY} +@item @option{--def-table} @tab @code{DEF_TABLE} +@item @option{--ignore-preamble-text} @tab @code{IGNORE_PREAMBLE_TEXT} +@item @option{--html-xref-prefix} @tab @code{EXTERNAL_DIR} +@item @option{--l2h} @tab @code{L2H} +@item @option{--l2h-l2h} @tab @code{L2H_L2H} +@item @option{--l2h-skip} @tab @code{L2H_SKIP} +@item @option{--l2h-tmp} @tab @code{L2H_TMP} +@item @option{--l2h-file} @tab @code{L2H_FILE} +@item @option{--l2h-clean} @tab @code{L2H_CLEAN} +@item @option{--use-nodes} @tab @code{USE_NODES} +@item @option{--monolithic} @tab @code{MONOLITHIC} +@item @option{--top-file} @tab @code{TOP_FILE} +@item @option{--toc-file} @tab @code{TOC_FILE} +@item @option{--frames} @tab @code{FRAMES} +@item @option{--menu} @tab @code{SHOW_MENU} +@item @option{--debug} @tab @code{DEBUG} +@item @option{--doctype} @tab @code{DOCTYPE} +@item @option{--frameset-doctype} @tab @code{FRAMESET_DOCTYPE} +@item @option{--test} @tab @code{TEST} +@end multitable + +@cindex @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. + + +@node Creating and Installing Info Files +@chapter Creating and Installing Info Files + +This chapter describes how to create and install Info files. +@xref{Info Files}, for general information about the file format +itself. + +@menu +* Creating an Info File:: +* Installing an Info File:: +@end menu + + +@node Creating an Info File +@section Creating an Info File +@cindex Creating an Info file +@cindex Info, creating an online file +@cindex Formatting a file for Info + +@code{makeinfo} is a program that converts a Texinfo file into an Info +file, HTML file, or plain text. @code{texinfo-format-region} and +@code{texinfo-format-buffer} are XEmacs functions that convert +Texinfo to Info. + +For information on installing the Info file in the Info system, +@pxref{Installing an Info File}. + +@menu +* @t{makeinfo} Advantages:: @code{makeinfo} provides better error checking. +* @t{makeinfo} in XEmacs:: How to run @code{makeinfo} from XEmacs. +* @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 XEmacs Batch mode. +* Tag and Split Files:: How tagged and split files help Info + to run better. +@end menu + + +@node @t{makeinfo} Advantages +@subsection @code{makeinfo} Advantages + +@anchor{makeinfo advantages}@c old name + +The @code{makeinfo} utility creates an Info file from a Texinfo source +providing better error messages than either of the XEmacs formatting +commands. We recommend it. The @code{makeinfo} program is +independent of XEmacs. You can run @code{makeinfo} in any of three +ways: from an operating system shell, from a shell inside XEmacs, 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 XEmacs. + +The @code{texinfo-format-region} and the @code{texinfo-format-buffer} +commands may be useful if you cannot run @code{makeinfo}. + + +@node @t{makeinfo} in XEmacs +@subsection Running @code{makeinfo} Within XEmacs + +@c anchor{makeinfo in XEmacs}@c prev name +@cindex Running @code{makeinfo} in XEmacs +@cindex @code{makeinfo} inside XEmacs +@cindex Shell, running @code{makeinfo} in + +You can run @code{makeinfo} in XEmacs Texinfo mode by using either the +@code{makeinfo-region} 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. + +@table @kbd +@item C-c C-m C-r +@itemx M-x makeinfo-region +Format the current region for Info. +@findex makeinfo-region + +@item C-c C-m C-b +@itemx M-x makeinfo-buffer +Format the current buffer for Info. +@findex makeinfo-buffer +@end 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} (@pxref{@t{@@setfilename}}). + +The XEmacs @code{makeinfo-region} and @code{makeinfo-buffer} commands +run the @code{makeinfo} program in a temporary shell buffer. If +@code{makeinfo} finds any errors, XEmacs displays the error messages in +the temporary buffer. + +@cindex Errors, parsing +@cindex Parsing errors +@findex next-error +You can parse the error messages by typing @kbd{C-x `} +(@code{next-error}). This causes XEmacs to go to and position the +cursor on the line in the Texinfo source that @code{makeinfo} thinks +caused the error. @xref{Compilation, , Running @code{make} or +Compilers Generally, xemacs, XEmacs User's Manual}, for more +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. + +@table @kbd +@item C-c C-m C-k +@itemx M-x makeinfo-kill-job +@findex makeinfo-kill-job +Kill the current running @code{makeinfo} job +(from @code{makeinfo-region} or @code{makeinfo-buffer}). + +@item C-c C-m C-l +@itemx M-x makeinfo-recenter-output-buffer +@findex makeinfo-recenter-output-buffer +Redisplay the @code{makeinfo} shell buffer to display its most recent +output. +@end table + +@noindent +(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 +@code{makeinfo-options} variable with either the @kbd{M-x +customize} or the @kbd{M-x set-variable} command, or by setting the +variable in your @file{init.el} initialization file. + +For example, you could write the following in your @file{init.el} file: + +@example +@group +(setq makeinfo-options + "--paragraph-indent=0 --no-split + --fill-column=70 --verbose") +@end group +@end example + +@noindent +@c Writing these three cross references using xref results in +@c three references to the same named manual, which looks strange. +@iftex +For more information, see @ref{@t{makeinfo} Options}, as well as +``Easy Customization Interface,'' ``Examining and Setting Variables,'' +and ``Init File'' in @cite{XEmacs User's Manual}. +@end iftex +@ifnottex +For more information, see@* +@ref{Easy Customization, , Easy Customization Interface, xemacs, XEmacs User's Manual},@* +@ref{Examining, , Examining and Setting Variables, xemacs, XEmacs User's Manual},@* +@ref{Init File, , , xemacs, XEmacs User's Manual}, and@* +@ref{@t{makeinfo} Options}. +@end ifnottex + + +@node @t{texinfo-format} commands +@subsection The @code{texinfo-format@dots{}} Commands + +@c anchor{texinfo-format commands}@c prev name + +In XEmacs 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 +@code{texinfo-format-buffer} 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 +@code{@@setfilename} line which must be near the beginning of the +Texinfo file. + +@table @kbd +@item C-c C-e C-r +@itemx @code{texinfo-format-region} +@findex texinfo-format-region +Format the current region for Info. + +@item C-c C-e C-b +@itemx @code{texinfo-format-buffer} +@findex texinfo-format-buffer +Format the current buffer for Info. +@end 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 +(@pxref{@t{makeinfo} in XEmacs}). + + +@node Batch Formatting +@subsection Batch Formatting +@cindex Batch formatting for Info +@cindex Info batch formatting + +You can format Texinfo files for Info using @code{batch-texinfo-format} +and XEmacs Batch mode. You can run XEmacs in Batch mode from any shell, +including a shell inside of XEmacs. (@xref{Command Arguments,,, +xemacs, XEmacs User's Manual}.) + +Here is a shell command to format all the files that end in +@file{.texinfo} in the current directory: + +@example +xemacs -batch -funcall batch-texinfo-format *.texinfo +@end example + +@noindent +XEmacs 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 XEmacs in Batch mode as shown; +it is not interactive. It kills the Batch mode XEmacs on completion. + +@code{batch-texinfo-format} 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 XEmacs process. This frees your current XEmacs, so +you can continue working in it. (When you run +@code{texinfo-format-region} or @code{texinfo-format-buffer}, you cannot +use that XEmacs for anything else until the command finishes.) + +@node Tag and Split Files +@subsection Tag Files and Split Files +@cindex Making a tag table automatically +@cindex Tag table, making automatically + +If a Texinfo file has more than 30,000 bytes, +@code{texinfo-format-buffer} 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. + +@cindex 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 XEmacs does +not need to make a large buffer to hold the whole of a large Info +file; instead, XEmacs allocates just enough memory for the small, split-off +file that is needed at the time. This way, XEmacs avoids wasting +memory when you run Info. (Before splitting was implemented, Info +files were always kept short and @dfn{include files} were designed as +a way to create a single, large printed manual out of the smaller Info +files. @xref{Include Files}, for more information. Include files are +still used for very large documents, such as @cite{The XEmacs Lisp +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 +@dfn{indirect} files. + +The split-off files have names that are created by appending @w{@samp{-1}}, +@w{@samp{-2}}, @w{@samp{-3}} and so on to the file name specified by the +@code{@@setfilename} command. The shortened version of the original file +continues to have the name specified by @code{@@setfilename}. + +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: + +@example +@group +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 +@end group +@group +test-texinfo-3: 101300 +^_^L +Tag table: +(Indirect) +Node: overview^?104 +Node: info file^?1271 +@end group +@group +Node: printed manual^?4853 +Node: conventions^?6855 +@dots{} +@end group +@end example + +@noindent +(But @file{test-texinfo} had far more nodes than are shown here.) Each of +the split-off, indirect files, @file{test-texinfo-1}, +@file{test-texinfo-2}, and @file{test-texinfo-3}, is listed in this file +after the line that says @samp{Indirect:}. The tag table is listed after +the line that says @samp{Tag table:}. + +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 +@code{makeinfo} 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 +@t{Info-validate}}. + + +@node Installing an Info File +@section Installing an Info File +@cindex Installing an Info file +@cindex Info file installation +@cindex @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 XEmacs. (@xref{Top,,, info, Info}, for an introduction to +Info.) + +@menu +* 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. +@end menu + + +@node Directory File +@subsection The Directory File @file{dir} + +For Info to work, the @file{info} directory must contain a file that +serves as a top level directory for the Info system. By convention, +this file is called @file{dir}. (You can find the location of this file +within XEmacs by typing @kbd{C-h i} to enter Info and then typing +@kbd{C-x C-f} to see the pathname to the @file{info} directory.) + +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: + +@example +@group +* Menu: +* Info: (info). Documentation browsing system. +* XEmacs: (xemacs). The extensible, self-documenting + text editor. +* Texinfo: (texinfo). With one source file, make + either a printed manual using + @@TeX@{@} or an Info file. +@dots{} +@end group +@end 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 +@file{info} file and the @samp{XEmacs} entry points to the `Top' node +of the @file{xemacs} 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: + +@example +File: xemacs Node: Top, Up: (DIR), Next: Distrib +@end example + +@noindent +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}. + + +@node New Info File +@subsection Listing a New Info File +@cindex Adding a new Info file +@cindex Listing a new Info file +@cindex New Info file, listing it in @file{dir} file +@cindex Info file, listing a new +@cindex @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: + +@example +* GDB: (gdb). The source-level C debugger. +@end example + +@noindent +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 @file{.info}@footnote{On MS-DOS/MS-Windows systems, Info will +try the @file{.inf} extension as well.}; so it is better to avoid +clutter and not to write @samp{.info} explicitly in the menu entry. For +example, the GDB menu entry should use just @samp{gdb} for the file +name, not @samp{gdb.info}. + + +@node Other Info Directories +@subsection Info Files in Other Directories +@cindex Installing Info in another directory +@cindex Info installed in another directory +@cindex Another Info directory +@cindex @file{dir} files and Info directories + +If an Info file is not in the @file{info} directory, there are three +ways to specify its location: + +@enumerate +@item +Write the pathname in the @file{dir} file as the second part of the menu. + +@item +Specify the Info directory name in the @code{INFOPATH} environment +variable in your @file{.profile} or @file{.cshrc} initialization file. +(Only you and others who set this environment variable will be able to +find Info files whose location is specified this way.) + +@item +If you are using XEmacs, 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 +@code{Info-directory-list} variable in your personal or site +initialization file. + +This variable tells XEmacs where to look for @file{dir} files (the files +must be named @file{dir}). XEmacs merges the files named @file{dir} from +each of the listed directories. (In XEmacs version 18, you can set the +@code{Info-directory} variable to the name of only one +directory.) +@end 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: + +@example +* Test: (/home/bob/info/info-test). Bob's own test file. +@end example + +@noindent +In this case, the absolute file name of the @file{info-test} file is +written as the second part of the menu entry. + +@vindex INFOPATH +@cindex 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 XEmacs and +standalone Info readers. + +Specifically, if you use a Bourne-compatible shell such as @code{sh} +or @code{bash} for your shell command interpreter, you set the +@code{INFOPATH} environment variable in the @file{.profile} +initialization file; but if you use @code{csh} or @code{tcsh}, you set +the variable in the @file{.cshrc} initialization file. On +MS-DOS/MS-Windows systems, you must set @code{INFOPATH} in your +@file{autoexec.bat} file or in the registry. Each type of shell uses +a different syntax. + +@itemize @bullet +@item +In a @file{.cshrc} file, you could set the @code{INFOPATH} +variable as follows: + +@smallexample +setenv INFOPATH .:~/info:/usr/local/xemacs/info +@end smallexample + +@item +In a @file{.profile} file, you would achieve the same effect by writing: + +@smallexample +INFOPATH=.:$HOME/info:/usr/local/xemacs/info +export INFOPATH +@end smallexample + +@item +@pindex autoexec.bat +In a @file{autoexec.bat} file, you write this command (note the +use of @samp{;} as the directory separator, and a different syntax for +using values of other environment variables): + +@smallexample +set INFOPATH=.;%HOME%/info;c:/usr/local/Xemacs/info +@end smallexample +@end itemize + +@noindent +The @samp{.} indicates the current directory as usual. XEmacs uses the +@code{INFOPATH} environment variable to initialize the value of XEmacs's +own @code{Info-directory-list} variable. The standalone Info reader +merges any files named @file{dir} in any directory listed in the +@env{INFOPATH} variable into a single menu presented to you in the node +called @samp{(dir)Top}. + +@cindex 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): + +@example +INFOPATH=/home/bob/info: +export INFOPATH +@end example + +@noindent +will search @file{/home/bob/info} first, then the standard directories. +Leading or doubled colons are not treated specially. + +@cindex @file{dir} file, creating your own +When you create your own @file{dir} file for use with +@code{Info-directory-list} or @env{INFOPATH}, it's easiest to start by +copying an existing @file{dir} file and replace all the text after the +@samp{* Menu:} with your desired entries. That way, the punctuation +and special @kbd{CTRL-_} characters that Info needs will be present. + +As one final alternative, which works only with XEmacs Info, you can +change the @code{Info-directory-list} variable. For example: + +@example +(add-hook 'Info-mode-hook '(lambda () + (add-to-list 'Info-directory-list + (expand-file-name "~/info")))) +@end example + + +@node Installing Dir Entries +@subsection Installing Info Directory Files + +When you install an Info file onto your system, you can use the program +@code{install-info} to update the Info directory file @file{dir}. +Normally the makefile for the package runs @code{install-info}, just +after copying the Info file into its proper installed location. + +@findex dircategory +@findex direntry +In order for the Info file to work with @code{install-info}, you include +the commands @code{@@dircategory} and +@code{@@direntry}@dots{}@code{@@end direntry} in the Texinfo source +file. Use @code{@@direntry} to specify the menu entries to add to the +Info directory file, and use @code{@@dircategory} to specify which part +of the Info directory to put it in. Here is how these commands are used +in this manual: + +@smallexample +@@dircategory Texinfo documentation system +@@direntry +* Texinfo: (texinfo). The GNU documentation format. +* install-info: (texinfo)Invoking install-info. @dots{} +@dots{} +@@end direntry +@end smallexample + +Here's what this produces in the Info file: + +@smallexample +INFO-DIR-SECTION Texinfo documentation system +START-INFO-DIR-ENTRY +* Texinfo: (texinfo). The GNU documentation format. +* install-info: (texinfo)Invoking install-info. @dots{} +@dots{} +END-INFO-DIR-ENTRY +@end smallexample + +@noindent +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. + +@code{install-info} 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 +@code{what-cursor-position} in XEmacs). 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 +@ref{Invoking @t{install-info}}. + +If you use @code{@@dircategory} more than once in the Texinfo source, +each usage specifies the `current' category; any subsequent +@code{@@direntry} commands will add to that category. + +@cindex Free Software Directory +@cindex Dir categories, choosing +@cindex 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): + +@display +XEmacs +Localization +Printing +Software development +Software libraries +Text creation and manipulation +@end display + +@cindex 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. + + +@node Invoking @t{install-info} +@subsection Invoking @command{install-info} + +@pindex install-info + +@code{install-info} inserts menu entries from an Info file into the +top-level @file{dir} file in the Info system (see the previous sections +for an explanation of how the @file{dir} file works). @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: + +@example +install-info [@var{option}]@dots{} [@var{info-file} [@var{dir-file}]] +@end example + +If @var{info-file} or @var{dir-file} are not specified, the options +(described below) that define them must be. There are no compile-time +defaults, and standard input is never used. @code{install-info} can +read only one Info file and write only one @file{dir} file per invocation. + +@cindex @file{dir}, created by @code{install-info} +If @var{dir-file} (however specified) does not exist, +@code{install-info} creates it if possible (with no entries). + +@cindex Compressed dir files, reading +@cindex XZ-compressed dir files, reading +@cindex Bzipped dir files, reading +@cindex Lzip-compressed dir files, reading +@cindex LZMA-compressed dir files, reading +@cindex 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 +@var{dir-file} itself does not exist, @code{install-info} tries to +open @file{@var{dir-file}.gz}, @file{@var{dir-file}.xz}, +@file{@var{dir-file}.bz2}, @file{@var{dir-file}.lz}, and +@file{@var{dir-file}.lzma}, in that order. + +Options: + +@table @code +@item --add-once +@opindex --add-once@r{, for @command{install-info}} +Specifies that the entry or entries will only be put into a single section. + +@item --align=@var{column} +@opindex --align=@var{column}@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 +@samp{35}. It is used in conjunction with the @samp{--max-width} option. +@var{column} starts counting at 1. + +@item --append-new-sections +@opindex --append-new-sections@r{, for @command{install-info}} +Instead of alphabetizing new sections, place them at the end of the DIR file. + +@item --calign=@var{column} +@opindex --calign=@var{column}@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. +@var{column} starts counting at 1. + +@item --debug +@opindex --debug@r{, for @command{install-info}} +Report what is being done. + +@item --delete +@opindex --delete@r{, 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. + +@item --description=@var{text} +@opindex --description=@var{text}@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. + +@item --dir-file=@var{name} +@opindex --dir-file=@var{name}@r{, for @command{install-info}} +Specify file name of the Info directory file. This is equivalent to +using the @var{dir-file} argument. + +@item --dry-run +@opindex --dry-run@r{, for @command{install-info}} +Same as @samp{--test}. + +@item --entry=@var{text} +@opindex --entry=@var{text}@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. + +@item --help +@opindex --help@r{, for @command{texindex}} +Display a usage message with basic usage and all available options, +then exit successfully. + +@item --info-file=@var{file} +@opindex --info-file=@var{file}@r{, for @command{install-info}} +Specify Info file to install in the directory. This is +equivalent to using the @var{info-file} argument. + +@item --info-dir=@var{dir} +@opindex --info-dir=@var{dir}@r{, for @command{install-info}} +Specify the directory where the directory file @file{dir} resides. +Equivalent to @samp{--dir-file=@var{dir}/dir}. + +@item --infodir=@var{dir} +@opindex --infodir=@var{dir}@r{, for @command{install-info}} +Same as @samp{--info-dir}. + +@item --item=@var{text} +@opindex --item=@var{text}@r{, for @command{install-info}} +Same as @samp{--entry=@var{text}}. An Info directory entry is actually +a menu item. + +@item --keep-old +@opindex --keep-old@r{, 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. + +@item --max-width=@var{column} +@opindex --max-width=@var{column}@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. + +@item --maxwidth=@var{column} +@opindex --maxwidth=@var{column}@r{, for @command{install-info}} +Same as @samp{--max-width}. + +@item --menuentry=@var{text} +@opindex --menuentry=@var{text}@r{, for @command{install-info}} +Same as @samp{--name}. + +@item --name=@var{text} +@opindex --name=@var{text}@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 +@samp{--entry}, @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. + +@item --no-indent +@opindex --no-indent@r{, for @command{install-info}} +Suppress formatting of new entries into the @file{dir} file. + +@item --quiet +@itemx --silent +@opindex --quiet@r{, for @command{install-info}} +@opindex --silent@r{, for @command{install-info}} +Suppress warnings, etc., for silent operation. + +@item --remove +@opindex --remove@r{, for @command{install-info}} +Same as @samp{--delete}. + +@item --remove-exactly +@opindex --remove-exactly@r{, 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 +@emph{not} ignored. + +@item --section=@var{sec} +@opindex --section=@var{sec}@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. + +@item --section @var{regex} @var{sec} +@opindex --section @var{regex} @var{sec}@r{, for @command{install-info}} +Same as @samp{--regex=@var{regex} --section=@var{sec} --add-once}. + +@code{install-info} tries to detect when this alternate syntax is used, +but does not always guess correctly. Here is the heuristic that +@code{install-info} uses: +@enumerate +@item +If the second argument to @code{--section} starts with a hyphen, the +original syntax is presumed. + +@item +If the second argument to @code{--section} is a file that can be +opened, the original syntax is presumed. + +@item +Otherwise the alternate syntax is used. +@end enumerate + +When the heuristic fails because your section title starts with a +hyphen, or it happens to be a filename that can be opened, the syntax +should be changed to @samp{--regex=@var{regex} --section=@var{sec} +--add-once}. + +@item --regex=@var{regex} +@opindex --regex=@var{regex}@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. + +@item --test +@opindex --test@r{, for @command{install-info}} +Suppress updating of the directory file. + +@item --version +@opindex --version@r{, for @command{install-info}} +@cindex Version number, for install-info +Display version information and exit successfully. + +@end table + + +@node Generating HTML +@chapter Generating HTML + +@cindex Generating HTML +@cindex Outputting HTML + +@command{makeinfo} generates Info output by default, but given the +@option{--html} option, it will generate HTML, for web browsers and +other programs. This chapter gives some details on such HTML output. + +@command{makeinfo} has many user-definable customization variables +with which you can influence the HTML output. @xref{Customization +Variables}. + +@command{makeinfo} can also produce output in XML and Docbook formats, +but we do not as yet describe these in detail. @xref{Output Formats}, +for a brief overview of all the output formats. + +@menu +* 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. +@end menu + + +@node HTML Translation +@section HTML Translation + +@command{makeinfo} will include segments of Texinfo source between +@code{@@ifhtml} and @code{@@end ifhtml} in the HTML output (but not +any of the other conditionals, by default). Source between +@code{@@html} and @code{@@end html} is passed without change to the +output (i.e., suppressing the normal escaping of input @samp{<}, +@samp{>} and @samp{&} characters which have special significance in +HTML). @xref{Conditional Commands}. + +@cindex 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{XEmacs W3} which implement +this HTML@tie{}1.0 feature. + +@cindex 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 +@samp{separate}, and the output is split, they are placed in a +separate file. @xref{Footnote Styles}. + +@cindex HTML output, browser compatibility of +The HTML generated is standard HTML@tie{}4. It also tries to be as +compatible as possible with earlier standards (e.g., HTML@tie{}2.0, +RFC-1866). Some minor exceptions: 1)@tie{}HTML@tie{}3.2 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 HTML@tie{}4 @samp{lang} attribute on the +@samp{<html>} attribute is used; 3)@tie{} Entities that are not in the +HTML@tie{}3.2 standard are also used. 4)@tie{} CSS is used +(@pxref{HTML CSS}). 5)@tie{} A few HTML@tie{}4 elements are used +(@code{thead}, @code{abbr}, @code{acronym}). + +Using @samp{--init-file=html32.pm} produces strict HTML@tie{}3.2 +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}). + + +@node HTML Splitting +@section HTML Splitting +@cindex Split HTML output +@cindex HTML output, split + +When splitting output at nodes (which is the default), +@command{makeinfo} 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 +@samp{-}'s and special characters changed to @samp{_} followed by +their code point in hex (@pxref{HTML Xref}). This is to make it +portable and easy to use as a filename. In the unusual case of two +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., +@samp{index} 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 +@code{CASE_INSENSITIVE_FILENAMES}. + +It is also possible to split at chapters or sections with +@option{--split} (@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 +@option{--no-node-files} 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: + +@enumerate +@item +@command{makeinfo} 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/}. + +@item +If that directory cannot be created for any reason, then +@command{makeinfo} tries appending @samp{.html} to the directory name. +For example, output for @code{@@setfilename texinfo} would be written +to @samp{texinfo.html/}. + +@item +If the @samp{@var{name}.html} directory can't be created either, +@code{makeinfo} gives up. + +@end enumerate + +@noindent 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 +@code{@@setfilename} (with any @samp{.info} extension is replaced with +@samp{.html}), @code{--output} (the argument is used literally), or +based on the input file name as a last resort +(@pxref{@t{@@setfilename}}). + + +@node HTML CSS +@section HTML CSS +@cindex HTML, and CSS +@cindex CSS, and HTML output +@cindex Cascading Style Sheets, and HTML output + +Cascading Style Sheets (CSS for short) is an Internet standard for +influencing the display of HTML documents: see +@uref{http://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: + +@example +pre.display @{ font-family:inherit @} +pre.smalldisplay @{ font-family:inherit; font-size:smaller @} +@end example + +A full explanation of CSS is (far) beyond this manual; please see the +reference above. In brief, however, the above tells the web browser +to use a `smaller' font size for @code{@@smalldisplay} text, and to +use the same font as the main document for both @code{@@smalldisplay} +and @code{@@display}. By default, the HTML @samp{<pre>} command uses +a monospaced font. + +You can influence the CSS in the HTML output with two +@command{makeinfo} options: @option{--css-include=@var{file}} and +@option{--css-ref=@var{url}}. + +@pindex texinfo-bright-colors.css +@cindex Visualizing Texinfo CSS +The option @option{--css-ref=@var{url}} 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 +@file{texi2html/examples/texinfo-bright-colors.css} useful for +visualizing the CSS elements in Texinfo output. + +The option @option{--css-include=@var{file}} includes the contents +@var{file} in the HTML output, as you might expect. However, the +details are somewhat tricky, as described in the following, to provide +maximum flexibility. + +@cindex @@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. + +@cindex 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 +@command{makeinfo}'s behavior, it just copies the @samp{@@charset} if +present.) Comments in CSS files are delimited by @samp{/* ... */}, as +in C@. An @samp{@@import} directive must be in one of these two forms: + +@example +@@import url(http://example.org/foo.css); +@@import "http://example.net/bar.css"; +@end 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 +@samp{@@}-directive into the output, as follows: + +@itemize +@item If @var{file} contains only normal CSS declarations, it is +included after @command{makeinfo}'s default CSS, thus overriding it. + +@item 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: +@example +pre.smallexample @{ font-size: inherit ! important @} +@end example + +@item If @var{file} contains both @samp{@@import} and inline CSS +specifications, the @samp{@@import}'s are included first, then +@command{makeinfo}'s defaults, and lastly the inline CSS from +@var{file}. + +@item 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. +@end 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 +@samp{@@} 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}. + + +@node HTML Xref +@section HTML Cross References +@cindex HTML cross references +@cindex 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 +@command{texi2html}, 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}.) + +@cindex Dumas, Patrice +The algorithm was primarily devised by Patrice Dumas in 2003--04. + +@menu +* 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. +@end menu + + +@node HTML Xref Link Basics +@subsection HTML Cross Reference Link Basics +@cindex 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: + +@example +http://@var{host}/@var{dir}/@var{file}.html#@var{target} +@end 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 +@var{manual} is either available as a monolithic file +@file{@var{manual}.html}, or a split subdirectory +@file{@var{manual}/*.html}. Here are the cases: + +@itemize @bullet +@item +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). + +@item +If the present manual is split, and the referent manual is mono, the +directory is @samp{../} and the file is @file{@var{referent}.html}. + +@item +If the present manual is mono, and the referent manual is split, the +directory is @file{@var{referent}/} and the file is the expanded node +name. + +@item +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 +@file{@var{referent}.html}. + +@end itemize + +@vindex 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{@@xref@{,,,../foo@}} and +@code{@@xref@{,,,foo@}} both use @samp{foo} as the manual name. This +is because any such attempted hardwiring of the directory is very +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 +@option{--no-split} 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}. + + +@node HTML Xref Node Name Expansion +@subsection HTML Cross Reference Node Name Expansion +@cindex HTML cross reference node name expansion +@cindex node name expansion, in HTML cross references +@cindex expansion, of node names in HTML cross references + +As mentioned in the previous section, the key part of the HTML cross +reference algorithm is the conversion of node names in the Texinfo +source into strings suitable for XHTML identifiers and filenames. The +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 +(@pxref{@t{@@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): + +@example +@@xref@{Top,,, xemacs, XEmacs User's Manual@}. +@result{} <a href="xemacs/index.html#Top"> +@end example + +@enumerate +@item +The standard ASCII letters (a-z and A-Z) are not modified. All other +characters may be changed as specified below. + +@item +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. + +@item +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.) + +@item +Leading and trailing spaces are removed. + +@item +After the above has been applied, each remaining space character is +converted into a @samp{-} character. + +@item +Other ASCII 7-bit characters are transformed into @samp{_00@var{xx}}, +where @var{xx} is the ASCII character code in (lowercase) hexadecimal. +This includes @samp{_}, which is mapped to @samp{_005f}. + +@item +If the node name does not begin with a letter, the literal string +@samp{g_t} 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. + +@end enumerate + +For example: + +@example +@@node A node --- with _'% +@result{} A-node-_002d_002d_002d-with-_005f_0027_0025 +@end example + +Notice in particular: + +@itemize @bullet +@item @samp{_} @result{} @samp{_005f} +@item @samp{-} @result{} @samp{_002d} +@item @samp{A node} @result{} @samp{A-node} +@end 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 +@file{index.html}. Fortunately, the targets serve to distinguish +these cases, since HTML target names are always case-sensitive, +independent of operating system. + + +@node HTML Xref Command Expansion +@subsection HTML Cross Reference Command Expansion +@cindex 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 (@pxref{@t{@@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: + +@example +@@asis @@b @@cite @@code @@command @@dfn @@dmn @@dotless +@@emph @@env @@file @@i @@indicateurl @@kbd @@key +@@samp @@sansserif @@sc @@slanted @@strong @@t @@var @@verb @@w +@end example + +@noindent 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 +@code{@@TeX@{bad@}}, 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 `U+@var{hhhh}' 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. + +@multitable @columnfractions .3 .5 +@item @code{@@(newline)} @tab (space) +@item @code{@@(space)} @tab (space) +@item @code{@@(tab)} @tab (space) +@item @code{@@!} @tab @samp{!} +@item @code{@@*} @tab (space) +@item @code{@@-} @tab (nothing) +@item @code{@@.} @tab @samp{.} +@item @code{@@:} @tab (nothing) +@item @code{@@?} @tab @samp{?} +@item @code{@@@@} @tab @samp{@@} +@item @code{@@@{} @tab @samp{@{} +@item @code{@@@}} @tab @samp{@}} +@item @code{@@LaTeX} @tab @samp{LaTeX} +@item @code{@@TeX} @tab @samp{TeX} +@item @code{@@arrow} @tab U+2192 +@item @code{@@bullet} @tab U+2022 +@item @code{@@comma} @tab @samp{,} +@item @code{@@copyright} @tab U+00A9 +@item @code{@@dots} @tab U+2026 +@item @code{@@enddots} @tab @samp{...} +@item @code{@@equiv} @tab U+2261 +@item @code{@@error} @tab @samp{error-->} +@item @code{@@euro} @tab U+20AC +@item @code{@@exclamdown} @tab U+00A1 +@item @code{@@expansion} @tab U+21A6 +@item @code{@@geq} @tab U+2265 +@item @code{@@leq} @tab U+2264 +@item @code{@@minus} @tab U+2212 +@item @code{@@ordf} @tab U+00AA +@item @code{@@ordm} @tab U+00BA +@item @code{@@point} @tab U+2605 +@item @code{@@pounds} @tab U+00A3 +@item @code{@@print} @tab U+22A3 +@item @code{@@questiondown} @tab U+00BF +@item @code{@@registeredsymbol} @tab U+00AE +@item @code{@@result} @tab U+21D2 +@item @code{@@textdegree} @tab U+00B0 +@item @code{@@tie} @tab (space) +@end multitable + +Quotation mark @@-commands (@code{@@quotedblright@{@}} and the like), +are likewise replaced by their Unicode values. Normal quotation +@emph{characters} (e.g., ASCII ` and ') are not altered. +@xref{Inserting Quotation Marks}. + +Any @code{@@acronym}, @code{@@abbr}, @code{@@email}, and +@code{@@image} commands are replaced by their first argument. (For +these commands, all subsequent arguments are optional, and ignored +here.) @xref{@t{@@acronym}}, and @ref{@t{@@email}}, and @ref{Images}. + +Any other command is an error, and the result is unspecified. + + +@node HTML Xref 8-bit Character Expansion +@subsection HTML Cross Reference 8-bit Character Expansion +@cindex HTML cross reference 8-bit character expansion +@cindex 8-bit characters, in HTML cross references +@cindex Expansion of 8-bit characters in HTML cross references +@cindex Transliteration of 8-bit characters in HTML cross references + +Usually, characters other than plain 7-bit ASCII are transformed into +the corresponding Unicode code point(s) in Normalization Form@tie{}C, +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 @samp{_@var{hhhh}}, where @var{hhhh} is the code point in hex. + +For example, combining this rule and the previous section: + +@example +@@node @@b@{A@} @@TeX@{@} @@u@{B@} @@point@{@}@@enddots@{@} +@result{} A-TeX-B_0306-_2605_002e_002e_002e +@end example + +Notice: 1)@tie{}@code{@@enddots} expands to three periods which in +turn expands to three @samp{_002e}'s; 2)@tie{}@code{@@u@{B@}} 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 @samp{__@var{xxxxxx}}, 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 @samp{_@var{xxxx}} notations, which is inconvenient and +all but unreadable. + +To handle such cases, @command{makeinfo} offers the +@option{--transliterate-file-names} command line option. This option +enables @dfn{transliteration} of node names into ASCII characters for +the purposes of file name creation and referencing. The +transliteration is based on phonetic principles, which makes the +generated file names more easily understanable. + +@cindex Normalization Form C, Unicode +For the definition of Unicode Normalization Form@tie{}C, see Unicode +report UAX#15, @uref{http://www.unicode.org/reports/tr15/}. Many +related documents and implementations are available elsewhere on the +web. + + +@node HTML Xref Mismatch +@subsection HTML Cross Reference Mismatch +@cindex HTML cross reference mismatch +@cindex Mismatched HTML cross reference source and target + +As mentioned earlier (@pxref{HTML Xref Link Basics}), the generating +software may need to guess whether a given manual being cross +referenced is available in split or monolithic form---and, inevitably, +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 +@file{manual/} 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 +@file{manual.html} to the different @file{manual/node.html} files. +Here's an example: + +@example +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:; + @} +@} +@end example + +Then, in the @code{<body>} tag of @file{manual.html}: + +@example +<body onLoad="redirect();"> +@end example + +Once again, this is something the software which generated the +@emph{referent} manual has to do in advance, it's not something the +software generating the cross reference in the present manual can +control. + + +@node HTML Xref Configuration +@subsection HTML Cross Reference Configuration: @file{htmlxref.cnf} + +@pindex htmlxref.cnf +@cindex HTML cross reference configuration +@cindex Cross reference configuration, for HTML +@cindex Configuration, for HTML cross-manual references + +@command{makeinfo} 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: + +@table @file +@item ./ +(the current directory) + +@item ./.texinfo/ +(under the current directory) + +@item ~/.texinfo/ +(where @code{~} is the current user's home directory) + +@item @var{sysconfdir}/texinfo/ +(where @var{sysconfdir} is the system configuration directory +specified at compile-time, e.g., @file{/usr/local/etc}) + +@item @var{datadir}/texinfo/ +(likewise specified at compile time, e.g., @file{/usr/local/share}) +@end 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., @file{@var{datadir}/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: + +@example +@var{varname} = @var{varvalue} +@end example + +Whitespace around the @samp{=} is optional and ignored. The +@var{varname} should consist of letters; case is significant. The +@var{varvalue} is an arbitrary string, continuing to the end of the +line. Variables are then referenced with @samp{$@{@var{varname}@}}; +variable references can occur in the @var{varvalue}. + +A manual information line looks like this: + +@example +@var{manual} @var{keyword} @var{urlprefix} +@end example + +@noindent +with @var{manual} the short identifier for a manual, @var{keyword} +being one of: @code{mono}, @code{node}, @code{section}, +@code{chapter}, and @var{urlprefix} described below. Variable +references can occur only in the @var{urlprefix}. For example (used +in the canonical @file{htmlxref.cnf}): + +@smallexample +G = http://www.gnu.org +GS = $@{G@}/software +hello mono $@{GS@}/hello/manual/hello.html +hello chapter $@{GS@}/hello/manual/html_chapter/ +hello section $@{GS@}/hello/manual/html_section/ +hello node $@{GS@}/hello/manual/html_node/ +@end smallexample + +@cindex 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. + +@cindex split manuals, for HTML cross references +If the keyword is @code{node}, @code{section}, or @code{chapter}, +@var{urlprefix} 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: + +@smallexample +node @result{} node, section, chapter, mono +section @result{} section, chapter, node, mono +chapter @result{} chapter, section, node, mono +mono @result{} mono, chapter, section, node +@end smallexample + +@opindex --node-files@r{, 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 +@url{http://ftpmirror.gnu.org/@/texinfo/@/htmlxref.cnf}. + + +@node HTML Xref Link Preservation +@subsection HTML Cross Reference Link Preservation: @var{manual}@file{-noderename.cnf} + +@pindex noderename.cnf +@pindex @var{manual}-noderename.cnf +@cindex HTML cross reference link preservation +@cindex Preserving HTML links to old nodes +@cindex Old nodes, preserving links to +@cindex Renaming nodes, and preserving links +@cindex Links, preserving to renamed nodes +@cindex 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. + +@vindex 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 @var{manual}@file{-noderename.cnf}, where +@var{manual} is the base name of the manual. For example, the manual +@file{texinfo.texi} would be supplemented by a file +@file{texinfo-noderename}.cnf. (This name can be overridden by +setting the @file{RENAMED_NODES_FILE} customization variable; +@pxref{Customization Variables}). + +The file is read in pairs of lines, as follows: + +@example +@var{old-node-name} +@@@@@{@} @var{new-node-name} +@end example + +The usual conversion from Texinfo node names to HTML names is applied; +see this entire section for details (@pxref{HTML Xref}). The unusual +@samp{@@@@@{@}} 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 +@var{old-node-name} 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 (@pxref{@t{@@anchor}}). There is no effective +difference between the two approaches. + + +@node Command List +@appendix @@-Command List +@cindex Alphabetical @@-command list +@cindex List of @@-commands +@cindex @@-command list +@cindex Reference to @@-commands + +Here is an alphabetical list of the @@-commands in Texinfo. Square +brackets, @t{[}@w{ }@t{]}, indicate optional arguments; an ellipsis, +@samp{@dots{}}, indicates repeated text. + +More specifics on the general syntax of different @@-commands are +given in the section below. + +@menu +* Command Syntax:: General syntax for varieties of @@-commands. +* Command Contexts:: Guidelines for which commands can be used where. +@end menu + +@sp 1 +@table @code +@item @@@var{whitespace} +An @code{@@} followed by a space, tab, or newline produces a normal, +stretchable, interword space. @xref{Multiple Spaces}. + +@item @@! +Produce an exclamation point that ends a sentence (usually after an +end-of-sentence capital letter). @xref{Ending a Sentence}. + +@item @@" +@itemx @@' +Generate an umlaut or acute accent, respectively, over the next +character, as in @"o and @'o. @xref{Inserting Accents}. + +@item @@* +Force a line break. @xref{Line Breaks}. + +@item @@,@{@var{c}@} +Generate a cedilla accent under @var{c}, as in @,{c}. @xref{Inserting +Accents}. + +@item @@- +Insert a discretionary hyphenation point. @xref{@t{@@- @@hyphenation}}. + +@item @@. +Produce a period that ends a sentence (usually after an +end-of-sentence capital letter). @xref{Ending a Sentence}. + +@item @@/ +Produces no output, but allows a line break. @xref{Line Breaks}. + +@item @@: +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}. + +@item @@= +Generate a macron (bar) accent over the next character, as in @=o. +@xref{Inserting Accents}. + +@item @@? +Produce a question mark that ends a sentence (usually after an +end-of-sentence capital letter). @xref{Ending a Sentence}. + +@item @@@@ +@itemx @@atchar@{@} +Insert an at sign, @samp{@@}. @xref{Inserting an Atsign}. + +@item @@\ +@itemx @@backslashchar@{@} +Insert a backslash, @samp{\}; @code{@@backslashchar@{@}} works +anywhere, while @code{@@\} works only inside @code{@@math}. +@xref{Inserting a Backslash}, and @ref{Inserting Math}. + +@item @@^ +@itemx @@` +Generate a circumflex (hat) or grave accent, respectively, over the next +character, as in @^o and @`e. +@xref{Inserting Accents}. + +@item @@@{ +@itemx @@lbracechar@{@} +Insert a left brace, @samp{@{}. @xref{Inserting Braces}. + +@item @@@} +@itemx @@rbracechar@{@} +Insert a right brace, @samp{@}}. @xref{Inserting Braces}. + +@item @@~ +Generate a tilde accent over the next character, as in @~N. +@xref{Inserting Accents}. + +@item @@AA@{@} +@itemx @@aa@{@} +Generate the uppercase and lowercase Scandinavian A-ring letters, +respectively: @AA{}, @aa{}. @xref{Inserting Accents}. + +@item @@abbr@{@var{abbreviation}@} +Indicate a general abbreviation, such as `Comput.'. +@xref{@t{@@abbr}}. + +@item @@acronym@{@var{acronym}@} +Indicate an acronym in all capital letters, such as `NASA'. +@xref{@t{@@acronym}}. + +@item @@AE@{@} +@itemx @@ae@{@} +Generate the uppercase and lowercase AE ligatures, respectively: +@AE{}, @ae{}. @xref{Inserting Accents}. + +@item @@afivepaper +Change page dimensions for the A5 paper size. @xref{A4 Paper}. + +@item @@afourlatex +@itemx @@afourpaper +@itemx @@afourwide +Change page dimensions for the A4 paper size. @xref{A4 Paper}. + +@item @@alias @var{new}=@var{existing} +Make the command @samp{@@@var{new}} a synonym for the existing command +@samp{@@@var{existing}}. @xref{@t{@@alias}}. + +@item @@allowcodebreaks @var{true-false} +Control breaking at @samp{-} and @samp{_} in @TeX{}. +@xref{@t{@@allowcodebreaks}}. + +@item @@anchor@{@var{name}@} +Define @var{name} as the current location for use as a cross reference +target. @xref{@t{@@anchor}}. + +@item @@appendix @var{title} +Begin an appendix. The title appears in the table of contents. In +Info, the title is underlined with asterisks. +@xref{@t{@@unnumbered @@appendix}}. + +@item @@appendixsec @var{title} +@itemx @@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. @xref{@t{@@unnumberedsec +@@appendixsec @@heading}}. + +@item @@appendixsubsec @var{title} +Begin an appendix subsection. The title appears in the table of +contents. In Info, the title is underlined with hyphens. +@xref{@t{@@unnumberedsubsec @@appendixsubsec @@subheading}}. + +@item @@appendixsubsubsec @var{title} +Begin an appendix subsubsection. The title appears in the table of +contents. In Info, the title is underlined with periods. +@xref{@t{@@subsubsection}}. + +@item @@arrow@{@} +Generate a right arrow glyph: @samp{@arrow{}}. Used by default +for @code{@@click}. @xref{Click Sequences}. + +@item @@asis +Used following @code{@@table}, @code{@@ftable}, and @code{@@vtable} to +print the table's first column without highlighting (``as is''). +@xref{@t{@@asis}}. + +@item @@author @var{author} +Typeset @var{author} flushleft and underline it. @xref{@t{@@title +@@subtitle @@author}}. + +@item @@b@{@var{text}@} +Set @var{text} in a @b{bold} font. No effect in Info. @xref{Fonts}. + +@item @@bullet@{@} +Generate a large round dot, @bullet{} (@samp{*} in Info). Often used +with @code{@@table}. @xref{@t{@@bullet}}. + +@item @@bye +Stop formatting a file. The formatters do not see anything in the +input file following @code{@@bye}. @xref{Ending a File}. + +@item @@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}. + +@item @@caption +Define the full caption for an @code{@@float}. @xref{@t{@@caption +@@shortcaption}}. + +@item @@cartouche +Highlight an example or quotation by drawing a box with rounded +corners around it. Pair with @code{@@end cartouche}. No effect in +Info. @xref{@t{@@cartouche}}. + +@item @@center @var{line-of-text} +Center the line of text following the command. +@xref{@t{@@titlefont @@center @@sp}}. + +@item @@centerchap @var{line-of-text} +Like @code{@@chapter}, but centers the chapter title. @xref{@t{@@chapter}}. + +@item @@chapheading @var{title} +Print an unnumbered chapter-like heading, but omit from the table of +contents. In Info, the title is underlined with asterisks. +@xref{@t{@@majorheading @@chapheading}}. + +@item @@chapter @var{title} +Begin a numbered chapter. The chapter title appears in the table of +contents. In Info, the title is underlined with asterisks. +@xref{@t{@@chapter}}. + +@item @@cindex @var{entry} +Add @var{entry} to the index of concepts. @xref{Index Entries, , +Defining the Entries of an Index}. + +@item @@cite@{@var{reference}@} +Highlight the name of a book or other reference that has no companion +Info file. @xref{@t{@@cite}}. + +@item @@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 +@code{@@value@{@var{flag}@}} from expanding to the value to which +@var{flag} is set. @xref{@t{@@set @@clear @@value}}. + +@item @@click@{@} +Represent a single ``click'' in a GUI@. Used within +@code{@@clicksequence}. @xref{Click Sequences}. + +@item @@clicksequence@{@var{action} @@click@{@} @var{action}@} +Represent a sequence of clicks in a GUI@. @xref{Click Sequences}. + +@item @@clickstyle @@@var{cmd} +Execute @@@var{cmd} for each @code{@@click}; the default is +@code{@@arrow}. The usual following empty braces on @@@var{cmd} are +omitted. @xref{Click Sequences}. + +@item @@code@{@var{sample-code}@} +Indicate an expression, a syntactically complete token of a program, +or a program name. Unquoted in Info output. @xref{@t{@@code}}. + +@item @@codequotebacktick @var{on-off} +@itemx @@codequoteundirected @var{on-off} +Control output of @code{`} and @code{'} in code examples. +@xref{Inserting Quote Characters}. + +@item @@comma@{@} +Insert a comma `,' character; only needed when a literal comma would +be taken as an argument separator. @xref{Inserting a Comma}. + +@item @@command@{@var{command-name}@} +Indicate a command name, such as @command{ls}. @xref{@t{@@command}}. + +@item @@comment @var{comment} +Begin a comment in Texinfo. The rest of the line does not appear in +any output. A synonym for @code{@@c}. +@xref{Comments}. + +@item @@contents +Print a complete table of contents. Has no effect in Info, which uses +menus instead. @xref{Contents, , Generating a Table of Contents}. + +@item @@copying +Specify copyright holders and copying conditions for the document Pair +with @code{@@end cartouche}. @xref{@t{@@copying}}. + +@item @@copyright@{@} +Generate the copyright symbol @copyright{}. +@xref{@t{@@copyright}}. + +@item @@defcodeindex @var{index-name} +Define a new index and its indexing command. Print entries in an +@code{@@code} font. @xref{New Indices, , Defining New Indices}. + +@item @@defcv @var{category} @var{class} @var{name} +@itemx @@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. +@xref{Definition Commands}. + +@item @@deffn @var{category} @var{name} @var{arguments}@dots{} +@itemx @@deffnx @var{category} @var{name} @var{arguments}@dots{} +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}. + +@item @@defindex @var{index-name} +Define a new index and its indexing command. Print entries in a roman +font. @xref{New Indices, , Defining New Indices}. + +@item @@definfoenclose @var{newcmd}, @var{before}, @var{after} +Must be used within @code{@@ifinfo}; create a new command +@code{@@@var{newcmd}} for Info that marks text by enclosing it in +strings that precede and follow the text. +@xref{@t{@@definfoenclose}}. + +@item @@defivar @var{class} @var{instance-variable-name} +@itemx @@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 +Variable@} @dots{}}. @xref{Definition Commands}. + +@item @@defmac @var{macroname} @var{arguments}@dots{} +@itemx @@defmacx @var{macroname} @var{arguments}@dots{} +Format a description for a macro; equivalent to @samp{@@deffn Macro +@dots{}}. @xref{Definition Commands}. + +@item @@defmethod @var{class} @var{method-name} @var{arguments}@dots{} +@itemx @@defmethodx @var{class} @var{method-name} @var{arguments}@dots{} +Format a description for a method in object-oriented programming; +equivalent to @samp{@@defop Method @dots{}}. @xref{Definition +Commands}. + +@item @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{} +@itemx @@defopx @var{category} @var{class} @var{name} @var{arguments}@dots{} +Format a description for an operation in object-oriented programming. +@code{@@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 +@ref{Abstract Objects}. + +@item @@defopt @var{option-name} +@itemx @@defoptx @var{option-name} +Format a description for a user option; equivalent to @samp{@@defvr +@{User Option@} @dots{}}. @xref{Definition Commands}. + +@item @@defspec @var{special-form-name} @var{arguments}@dots{} +@itemx @@defspecx @var{special-form-name} @var{arguments}@dots{} +Format a description for a special form; equivalent to @samp{@@deffn +@{Special Form@} @dots{}}. @xref{Definition Commands}. + +@item @@deftp @var{category} @var{name-of-type} @var{attributes}@dots{} +@itemx @@deftpx @var{category} @var{name-of-type} @var{attributes}@dots{} +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 +@ref{Data Types}. + +@item @@deftypecv @var{category} @var{class} @var{data-type} @var{name} +@itemx @@deftypecvx @var{category} @var{class} @var{data-type} @var{name} +Format a description for a typed class variable in object-oriented programming. +@xref{Definition Commands}, and @ref{Abstract Objects}. + +@item @@deftypefn @var{category} @var{data-type} @var{name} @var{arguments}@dots{} +@itemx @@deftypefnx @var{category} @var{data-type} @var{name} @var{arguments}@dots{} +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}. + +@item @@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}. + +@item @@deftypefun @var{data-type} @var{function-name} @var{arguments}@dots{} +@itemx @@deftypefunx @var{data-type} @var{function-name} @var{arguments}@dots{} +Format a description for a function in a typed language. +The command is equivalent to @samp{@@deftypefn Function @dots{}}. +@xref{Definition Commands}. + +@item @@deftypeivar @var{class} @var{data-type} @var{variable-name} +@itemx @@deftypeivarx @var{class} @var{data-type} @var{variable-name} +Format a description for a typed instance variable in object-oriented +programming. @xref{Definition Commands}, and @ref{Abstract Objects}. + +@item @@deftypemethod @var{class} @var{data-type} @var{method-name} @var{arguments}@dots{} +@itemx @@deftypemethodx @var{class} @var{data-type} @var{method-name} @var{arguments}@dots{} +Format a description for a typed method in object-oriented programming. +@xref{Definition Commands}. + +@item @@deftypeop @var{category} @var{class} @var{data-type} @var{name} @var{arguments}@dots{} +@itemx @@deftypeopx @var{category} @var{class} @var{data-type} @var{name} @var{arguments}@dots{} +Format a description for a typed operation in object-oriented programming. +@xref{Definition Commands}, and @ref{Abstract Objects}. + +@item @@deftypevar @var{data-type} @var{variable-name} +@itemx @@deftypevarx @var{data-type} @var{variable-name} +Format a description for a variable in a typed language. The command is +equivalent to @samp{@@deftypevr Variable @dots{}}. @xref{Definition +Commands}. + +@item @@deftypevr @var{category} @var{data-type} @var{name} +@itemx @@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}. + +@item @@defun @var{function-name} @var{arguments}@dots{} +@itemx @@defunx @var{function-name} @var{arguments}@dots{} +Format a description for a function; equivalent to +@samp{@@deffn Function @dots{}}. @xref{Definition Commands}. + +@item @@defvar @var{variable-name} +@itemx @@defvarx @var{variable-name} +Format a description for a variable; equivalent to @samp{@@defvr +Variable @dots{}}. @xref{Definition Commands}. + +@item @@defvr @var{category} @var{name} +@itemx @@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. +@xref{Definition Commands}. + +@item @@detailmenu +Mark the (optional) detailed node listing in a master menu. +@xref{Master Menu Parts}. + +@item @@dfn@{@var{term}@} +Indicate the introductory or defining use of a term. @xref{@t{@@dfn}}. + +@item @@DH@{@} +@itemx @@dh@{@} +Generate the uppercase and lowercase Icelandic letter eth, respectively: +@DH{}, @dh{}. @xref{Inserting Accents}. + +@item @@dircategory @var{dirpart} +Specify a part of the Info directory menu where this file's entry should +go. @xref{Installing Dir Entries}. + +@item @@direntry +Begin the Info directory menu entry for this file. Pair with +@code{@@end direntry}. @xref{Installing Dir Entries}. + +@item @@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}. +@xref{@t{@@display}}. + +@item @@dmn@{@var{dimension}@} +Format a unit of measure, as in 12@dmn{pt}. Causes @TeX{} to insert a +thin space before @var{dimension}. No effect in Info. +@xref{@t{@@dmn}}. + +@item @@docbook +Enter Docbook completely. Pair with @code{@@end docbook}. @xref{Raw +Formatter Commands}. + +@item @@documentdescription +Set the document description text, included in the HTML output. Pair +with @code{@@end documentdescription}. @xref{@t{@@documentdescription}}. + +@item @@documentencoding @var{enc} +Declare the input encoding to be @var{enc}. +@xref{@t{@@documentencoding}}. + +@item @@documentlanguage @var{CC} +Declare the document language as the two-character ISO-639 abbreviation +@var{CC}. @xref{@t{@@documentlanguage}}. + +@item @@dotaccent@{@var{c}@} +Generate a dot accent over the character @var{c}, as in @dotaccent{o}. +@xref{Inserting Accents}. + +@item @@dotless@{@var{i-or-j}@} +Generate dotless i (`@dotless{i}') and dotless j (`@dotless{j}'). +@xref{Inserting Accents}. + +@item @@dots@{@} +Generate an ellipsis, @samp{@dots{}}. +@xref{@t{@@dots}}. + +@item @@email@{@var{address}[, @var{displayed-text}]@} +Indicate an electronic mail address. @xref{@t{@@email}}. + +@item @@emph@{@var{text}@} +Emphasize @var{text}, by using @emph{italics} where possible, and +enclosing in asterisks in Info. @xref{Emphasis, , Emphasizing Text}. + +@item @@end @var{environment} +Ends @var{environment}, as in @samp{@@end example}. @xref{Formatting +Commands,,@@-commands}. + +@item @@enddots@{@} +Generate an end-of-sentence ellipsis, like this: @enddots{} +@xref{@t{@@dots}}. + +@item @@enumerate [@var{number-or-letter}] +Begin a numbered list, using @code{@@item} for each entry. +Optionally, start list with @var{number-or-letter}. Pair with +@code{@@end enumerate}. @xref{@t{@@enumerate}}. + +@item @@env@{@var{environment-variable}@} +Indicate an environment variable name, such as @env{PATH}. +@xref{@t{@@env}}. + +@item @@equiv@{@} +Indicate to the reader the exact equivalence of two forms with a +glyph: @samp{@equiv{}}. @xref{@t{@@equiv}}. + +@item @@error@{@} +Indicate to the reader with a glyph that the following text is +an error message: @samp{@error{}}. @xref{@t{@@error}}. + +@item @@errormsg@{@var{msg}@} +Report @var{msg} as an error to standard error, and exit unsuccessfully. +Texinfo commands within @var{msg} are expanded to plain text. +@xref{Conditionals}, and @ref{External Macro Processors}. + +@item @@euro@{@} +Generate the Euro currency sign. @xref{@t{@@euro}}. + +@item @@evenfooting [@var{left}] @@| [@var{center}] @@| [@var{right}] +@itemx @@evenheading [@var{left}] @@| [@var{center}] @@| [@var{right}] +Specify page footings resp.@: headings for even-numbered (left-hand) +pages. @xref{Custom Headings, , +How to Make Your Own Headings}. + +@item @@everyfooting [@var{left}] @@| [@var{center}] @@| [@var{right}] +@itemx @@everyheading [@var{left}] @@| [@var{center}] @@| [@var{right}] +Specify page footings resp.@: headings for every page. Not relevant to +Info. @xref{Custom Headings, , How to Make Your Own Headings}. + +@item @@example +Begin an example. Indent text, do not fill, and select fixed-width +font. Pair with @code{@@end example}. @xref{@t{@@example}}. + +@item @@exampleindent @var{indent} +Indent example-like environments by @var{indent} number of spaces +(perhaps 0). @xref{@t{@@exampleindent}}. + +@item @@exclamdown@{@} +Generate an upside-down exclamation point. @xref{Inserting Accents}. + +@item @@exdent @var{line-of-text} +Remove any indentation a line might have. @xref{@t{@@exdent}}. + +@item @@expansion@{@} +Indicate the result of a macro expansion to the reader with a special +glyph: @samp{@expansion{}}. @xref{@t{@@expansion}}. + +@item @@file@{@var{filename}@} +Highlight the name of a file, buffer, node, directory, etc. +@xref{@t{@@file}}. + +@item @@finalout +Prevent @TeX{} from printing large black warning rectangles beside +over-wide lines. @xref{Overfull hboxes}. + +@item @@findex @var{entry} +Add @var{entry} to the index of functions. @xref{Index Entries, , +Defining the Entries of an Index}. + +@item @@firstparagraphindent @var{word} +Control indentation of the first paragraph after section headers +according to @var{word}, one of `none' or `insert'. +@xref{@t{@@firstparagraphindent}}. + +@item @@float +Environment to define floating material. Pair with @code{@@end float}. +@xref{Floats}. + +@item @@flushleft +@itemx @@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}). @xref{@t{@@flushleft +@@flushright}}. + +@item @@fonttextsize @var{10-11} +Change the size of the main body font in the @TeX{} output. +@xref{Fonts}. + +@item @@footnote@{@var{text-of-footnote}@} +Enter a footnote. Footnote text is printed at the bottom of the page +by @TeX{}; Info may format in either `End' node or `Separate' node style. +@xref{Footnotes}. + +@item @@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. +@xref{Footnotes}. + +@item @@format +Begin a kind of example. Like @code{@@display}, but do not indent. +Pair with @code{@@end format}. @xref{@t{@@example}}. + +@item @@frenchspacing @var{on-off} +Control spacing after punctuation. @xref{@t{@@frenchspacing}}. + +@item @@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 +@code{@@table}, except for indexing. @xref{@t{@@ftable @@vtable}}. + +@item @@geq@{@} +Generate a greater-than-or-equal sign, `@geq{}'. @xref{@t{@@geq @@leq}}. + +@item @@group +Disallow page breaks within following text. Pair with @code{@@end +group}. Ignored in Info. @xref{@t{@@group}}. + +@item @@guillemetleft@{@} +@itemx @@guillemetright@{@} +@item @@guillemotleft@{@} +@itemx @@guillemotright@{@} +@itemx @@guilsinglleft@{@} +@itemx @@guilsinglright@{@} +Double and single angle quotation marks: @guillemetleft{} +@guillemetright{} @guilsinglleft{} @guilsinglright{}. +@code{@@guillemotleft} and @code{@@guillemotright} are synonyms for +@code{@@guillemetleft} and @code{@@guillemetright}. @xref{Inserting +Quotation Marks}. + +@item @@H@{@var{c}@} +Generate the long Hungarian umlaut accent over @var{c}, as in @H{o}. + +@item @@hashchar@{@} +Insert a hash `#' character; only needed when a literal hash would +introduce @code{#line} directive. @xref{Inserting a Hashsign}, and +@ref{External Macro Processors}. + +@item @@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. +@xref{@t{@@unnumberedsec @@appendixsec @@heading}}. + +@item @@headings @var{on-off-single-double} +Turn page headings on or off, and/or specify single-sided or double-sided +page headings for printing. @xref{@t{@@headings}}. + +@item @@headitem +Begin a heading row in a multitable. @xref{Multitable Rows}. + +@item @@headitemfont@{@var{text}@} +Set @var{text} in the font used for multitable heading rows; mostly +useful in multitable templates. @xref{Multitable Rows}. + +@item @@html +Enter HTML completely. Pair with @code{@@end html}. @xref{Raw +Formatter Commands}. + +@item @@hyphenation@{@var{hy-phen-a-ted words}@} +Explicitly define hyphenation points. @xref{@t{@@- @@hyphenation}}. + +@item @@i@{@var{text}@} +Set @var{text} in an @i{italic} font. No effect in Info. @xref{Fonts}. + +@item @@ifclear @var{txivar} +If the Texinfo variable @var{txivar} is not set, format the following +text. Pair with @code{@@end ifclear}. @xref{@t{@@set @@clear +@@value}}. + +@item @@ifcommanddefined @var{txicmd} +@itemx @@ifcommandnotdefined @var{txicmd} +If the Texinfo code @samp{@@@var{txicmd}} is (not) defined, format the +follow text. Pair with the corresponding @code{@@end ifcommand...}. +@xref{Testing for Texinfo Commands}. + +@item @@ifdocbook +@itemx @@ifhtml +@itemx @@ifinfo +Begin text that will appear only in the given output format. +@code{@@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}. +@xref{Conditionals}. + +@item @@ifnotdocbook +@itemx @@ifnothtml +@itemx @@ifnotplaintext +@itemx @@ifnottex +@itemx @@ifnotxml +Begin text to be ignored in one output format but not the others. +@code{@@ifnothtml} text is omitted from HTML output, etc. Pair with +the corresponding @code{@@end ifnot@var{format}}. +@xref{Conditionals}. + +@item @@ifnotinfo +Begin text to appear in output other than Info and (for historical +compatibility) plain text. Pair with @code{@@end ifnotinfo}. +@xref{Conditionals}. + +@item @@ifplaintext +Begin text that will appear only in the plain text output. +Pair with @code{@@end ifplaintext}. @xref{Conditionals}. + +@item @@ifset @var{txivar} +If the Texinfo variable @var{txivar} is set, format the following +text. Pair with @code{@@end ifset}. @xref{@t{@@set @@clear +@@value}}. + +@item @@iftex +Begin text to appear only in the @TeX{} output. Pair with @code{@@end +iftex}. @xref{Conditionals, , Conditionally Visible Text}. + +@item @@ifxml +Begin text that will appear only in the XML output. Pair with +@code{@@end ifxml}. @xref{Conditionals}. + +@item @@ignore +Begin text that will not appear in any output. Pair with @code{@@end +ignore}. @xref{Comments, , Comments and Ignored Text}. + +@item @@image@{@var{filename}, [@var{width}], [@var{height}], [@var{alt}], [@var{ext}]@} +Include graphics image in external @var{filename} scaled to the given +@var{width} and/or @var{height}, using @var{alt} text and looking for +@samp{@var{filename}.@var{ext}} in HTML@. @xref{Images}. + +@item @@include @var{filename} +Read the contents of Texinfo source file @var{filename}. @xref{Include Files}. + +@item @@indent +Insert paragraph indentation. @xref{@t{@@indent}}. + +@item @@indentedblock +Indent a block of arbitary text on the left. Pair with @code{@@end +indentedblock}. @xref{@t{@@indentedblock}}. + +@item @@indicateurl@{@var{indicateurl}@} +Indicate text that is a uniform resource locator for the World Wide +Web. @xref{@t{@@indicateurl}}. + +@item @@inforef@{@var{node-name}, [@var{entry-name}], @var{info-file-name}@} +Make a cross reference to an Info file for which there is no printed +manual. @xref{@t{@@inforef}}. + +@item @@inlinefmt@{@var{fmt}, @var{text}@} +Insert @var{text} only if the output format is @var{fmt}. +@xref{Inline Conditionals}. + +@item @@inlinefmtifelse@{@var{fmt}, @var{text}, @var{else-text}@} +Insert @var{text} if the output format is @var{fmt}, else @var{else-text}. + +@item @@inlineifclear@{@var{var}, @var{text}@} +@itemx @@inlineifset@{@var{var}, @var{text}@} +Insert @var{text} only if the Texinfo variable @var{var} is (not) set. + +@item @@inlineraw@{@var{fmt}, @var{raw-text}@} +Insert @var{text} as in a raw conditional, only if the output format +is @var{fmt}. + +@item \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 +@file{texinfo} macro definitions file. The @code{\} in @code{\input} +is used instead of an @code{@@} because @TeX{} does not recognize +@code{@@} until after it has read the definitions file. @xref{Texinfo +File Header}. + +@item @@insertcopying +Insert the text previously defined with the @code{@@copying} +environment. @xref{@t{@@insertcopying}}. + +@item @@item +Indicate the beginning of a marked paragraph for @code{@@itemize} and +@code{@@enumerate}; indicate the beginning of the text of a first column +entry for @code{@@table}, @code{@@ftable}, and @code{@@vtable}. +@xref{Lists and Tables}. + +@item @@itemize @var{mark-generating-character-or-command} +Begin an unordered list: indented paragraphs with a mark, such as +@code{@@bullet}, inside the left margin at the beginning of each item. +Pair with @code{@@end itemize}. @xref{@t{@@itemize}}. + +@item @@itemx +Like @code{@@item} but do not generate extra vertical space above the +item text. Thus, when several items have the same description, use +@code{@@item} for the first and @code{@@itemx} for the others. +@xref{@t{@@itemx}}. + +@item @@kbd@{@var{keyboard-characters}@} +Indicate characters of input to be typed by users. @xref{@t{@@kbd}}. + +@item @@kbdinputstyle @var{style} +Specify when @code{@@kbd} should use a font distinct from +@code{@@code} according to @var{style}: @code{code}, @code{distinct}, +@code{example}. @xref{@t{@@kbd}}. + +@item @@key@{@var{key-name}@} +Indicate the name of a key on a keyboard. @xref{@t{@@key}}. + +@item @@kindex @var{entry} +Add @var{entry} to the index of keys. +@xref{Index Entries, , Defining the Entries of an Index}. + +@item @@L@{@} +@itemx @@l@{@} +Generate the uppercase and lowercase Polish suppressed-L letters, +respectively: @L{}, @l{}. + +@item @@LaTeX@{@} +Generate the @LaTeX{} logo. @xref{@t{@@TeX @@LaTeX}}. + +@item @@leq@{@} +Generate a less-than-or-equal sign, `@leq{}'. @xref{@t{@@geq @@leq}}. + +@item @@lisp +Begin an example of Lisp code. Indent text, do not fill, and select +fixed-width font. Pair with @code{@@end lisp}. @xref{@t{@@lisp}}. + +@item @@listoffloats +Produce a table-of-contents-like listing of @code{@@float}s. +@xref{@t{@@listoffloats}}. + +@item @@lowersections +Change subsequent chapters to sections, sections to subsections, and so +on. @xref{Raise/lower sections, , @code{@@raisesections} and +@code{@@lowersections}}. + +@item @@macro @var{macroname} @{@var{params}@} +Define a new Texinfo command @code{@@@var{macroname}@{@var{params}@}}. +Pair with @code{@@end macro}. @xref{Defining Macros}. + +@item @@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. @xref{@t{@@majorheading +@@chapheading}}. + +@item @@math@{@var{mathematical-expression}@} +Format a mathematical expression. @xref{Inserting Math}. + +@item @@menu +Mark the beginning of a menu of nodes. No effect in a printed manual. +Pair with @code{@@end menu}. @xref{Menus}. + +@item @@minus@{@} +Generate a minus sign, `@minus{}'. @xref{@t{@@minus}}. + +@item @@multitable @var{column-width-spec} +Begin a multi-column table. Begin each row with @code{@@item} or +@code{@@headitem}, and separate columns with @code{@@tab}. Pair with +@code{@@end multitable}. @xref{Multitable Column Widths}. + +@item @@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. +@xref{@t{@@need}}. + +@item @@node @var{name}, @var{next}, @var{previous}, @var{up} +Begin a new node. @xref{@t{@@node}}. + +@item @@noindent +Prevent text from being indented as if it were a new paragraph. +@xref{@t{@@noindent}}. + +@item @@novalidate +Suppress validation of node references and omit creation of auxiliary +files with @TeX{}. Use before @code{@@setfilename}. @xref{Pointer +Validation}. + +@item @@O@{@} +@itemx @@o@{@} +Generate the uppercase and lowercase O-with-slash letters, respectively: +@O{}, @o{}. + +@item @@oddfooting [@var{left}] @@| [@var{center}] @@| [@var{right}] +@itemx @@oddheading [@var{left}] @@| [@var{center}] @@| [@var{right}] +Specify page footings resp.@: headings for odd-numbered (right-hand) +pages. @xref{Custom Headings, , +How to Make Your Own Headings}. + +@item @@OE@{@} +@itemx @@oe@{@} +Generate the uppercase and lowercase OE ligatures, respectively: +@OE{}, @oe{}. @xref{Inserting Accents}. + +@item @@ogonek@{@var{c}@} +Generate an ogonek diacritic under the next character, as in +@ogonek{a}. @xref{Inserting Accents}. + +@item @@option@{@var{option-name}@} +Indicate a command-line option, such as @option{-l} or +@option{--help}. @xref{@t{@@option}}. + +@item @@ordf@{@} +@itemx @@ordm@{@} +Generate the feminine and masculine Spanish ordinals, respectively: +@ordf{}, @ordm{}. @xref{Inserting Accents}. + +@item @@page +Start a new page in a printed manual. No effect in Info. +@xref{@t{@@page}}. + +@item @@pagesizes [@var{width}][, @var{height}] +Change page dimensions. @xref{pagesizes}. + +@item @@paragraphindent @var{indent} +Indent paragraphs by @var{indent} number of spaces (perhaps 0); preserve +source file indentation if @var{indent} is @code{asis}. +@xref{@t{@@paragraphindent}}. + +@item @@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. +@xref{@t{@@part}}. + +@item @@pindex @var{entry} +Add @var{entry} to the index of programs. @xref{Index Entries, , Defining +the Entries of an Index}. + +@item @@point@{@} +Indicate the position of point in a buffer to the reader with a glyph: +@samp{@point{}}. @xref{@t{@@point}}. + +@item @@pounds@{@} +Generate the pounds sterling currency sign. +@xref{@t{@@pounds}}. + +@item @@print@{@} +Indicate printed output to the reader with a glyph: @samp{@print{}}. +@xref{@t{@@print}}. + +@item @@printindex @var{index-name} +Generate the alphabetized index for @var{index-name} (using two +columns in a printed manual). @xref{Printing Indices & Menus}. + +@item @@pxref@{@var{node}, [@var{entry}], [@var{node-title}], [@var{info-file}], [@var{manual}]@} +Make a reference that starts with a lowercase `see' in a printed +manual. Use within parentheses only. Only the first argument is +mandatory. @xref{@t{@@pxref}}. + +@item @@questiondown@{@} +Generate an upside-down question mark. @xref{Inserting Accents}. + +@item @@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}. @xref{@t{@@quotation}}. + +@item @@quotedblleft@{@} +@itemx @@quotedblright@{@} +@itemx @@quoteleft@{@} +@itemx @@quoteright@{@} +@itemx @@quotedblbase@{@} +@itemx @@quotesinglbase@{@} +Produce various quotation marks: @quotedblleft{} @quotedblright{} +@quoteleft{} @quoteright{} @quotedblbase{} @quotesinglbase{}. +@xref{Inserting Quotation Marks}. + +@item @@r@{@var{text}@} +Set @var{text} in the regular @r{roman} font. No effect in Info. +@xref{Fonts}. + +@item @@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. @xref{@t{@@raggedright}}. + +@item @@raisesections +Change subsequent sections to chapters, subsections to sections, and so +on. @xref{Raise/lower sections}. + +@item @@ref@{@var{node}, [@var{entry}], [@var{node-title}], [@var{info-file}], [@var{manual}]@} +Make a plain reference that does not start with any special text. +Follow command with a punctuation mark. Only the first argument is +mandatory. @xref{@t{@@ref}}. + +@item @@refill +@findex refill +This command used to refill and indent the paragraph after all the +other processing has been done. It is no longer needed, since all +formatters now automatically refill as needed, but you may still see +it in the source to some manuals, as it does no harm. + +@item @@registeredsymbol@{@} +Generate the legal symbol @registeredsymbol{}. +@xref{@t{@@registeredsymbol}}. + +@item @@result@{@} +Indicate the result of an expression to the reader with a special +glyph: @samp{@result{}}. @xref{@t{@@result}}. + +@item @@ringaccent@{@var{c}@} +Generate a ring accent over the next character, as in @ringaccent{o}. +@xref{Inserting Accents}. + +@item @@samp@{@var{text}@} +Indicate a literal example of a sequence of characters, in general. +Quoted in Info output. @xref{@t{@@samp}}. + +@item @@sansserif@{@var{text}@} +Set @var{text} in a @sansserif{sans serif} font if possible. No +effect in Info. @xref{Fonts}. + +@item @@sc@{@var{text}@} +Set @var{text} in a small caps font in printed output, and uppercase +in Info. @xref{Smallcaps}. + +@item @@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. +@xref{@t{@@section}}. + +@item @@set @var{txivar} [@var{string}] +Define the Texinfo variable @var{txivar}, optionally to the value +@var{string}. @xref{@t{@@set @@clear @@value}}. + +@item @@setchapternewpage @var{on-off-odd} +Specify whether chapters start on new pages, and if so, whether on +odd-numbered (right-hand) new pages. @xref{@t{@@setchapternewpage}}. + +@item @@setcontentsaftertitlepage +Put the table of contents after the @samp{@@end titlepage} even if the +@code{@@contents} command is at the end. @xref{Contents}. + +@item @@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. @xref{@t{@@setfilename}}. + +@item @@setshortcontentsaftertitlepage +Place the short table of contents after the @samp{@@end titlepage} +command even if the @code{@@shortcontents} command is at the end. +@xref{Contents}. + +@item @@settitle @var{title} +Specify the title for page headers in a printed manual, and the +default document title for HTML @samp{<head>}. +@xref{@t{@@settitle}}. + +@item @@shortcaption +Define the short caption for an @code{@@float}. @xref{@t{@@caption +@@shortcaption}}. + +@item @@shortcontents +Print a short table of contents, with chapter-level entries only. Not +relevant to Info, which uses menus rather than tables of contents. +@xref{Contents, , Generating a Table of Contents}. + +@item @@shorttitlepage @var{title} +Generate a minimal title page. @xref{@t{@@titlepage}}. + +@item @@slanted@{@var{text}@} +Set @var{text} in a @slanted{slanted} font if possible. No effect +in Info. @xref{Fonts}. + +@item @@smallbook +Cause @TeX{} to produce a printed manual in a 7 by 9.25 inch format +rather than the regular 8.5 by 11 inch format. +@xref{@t{@@smallbook}}. Also, see @ref{@t{@@small@dots{}}}. + +@item @@smalldisplay +Begin a kind of example. Like @code{@@display}, but use a smaller +font size where possible. Pair with @code{@@end smalldisplay}. +@xref{@t{@@small@dots{}}}. + +@item @@smallexample +Begin an example. Like @code{@@example}, but use a smaller font size +where possible. Pair with @code{@@end smallexample}. +@xref{@t{@@small@dots{}}}. + +@item @@smallformat +Begin a kind of example. Like @code{@@format}, but use a smaller font +size where possible. Pair with @code{@@end smallformat}. +@xref{@t{@@small@dots{}}}. + +@item @@smallindentedblock +Like @code{@@indentedblock}, but use a smaller font size where +possible. Pair with @code{@@end smallindentedblock}. +@xref{@t{@@small@dots{}}}. + +@item @@smalllisp +Begin an example of Lisp code. Same as @code{@@smallexample}. Pair +with @code{@@end smalllisp}. @xref{@t{@@small@dots{}}}. + +@item @@smallquotation +Like @code{@@quotation}, but use a smaller font size where possible. +Pair with @code{@@end smallquotation}. @xref{@t{@@small@dots{}}}. + +@item @@sp @var{n} +Skip @var{n} blank lines. @xref{@t{@@sp}}. + +@item @@ss@{@} +Generate the German sharp-S es-zet letter, @ss{}. @xref{Inserting Accents}. + +@item @@strong @{@var{text}@} +Emphasize @var{text} more strongly than @code{@@emph}, by using +@strong{boldface} where possible; enclosed in asterisks in Info. +@xref{emph & strong, , Emphasizing Text}. + +@item @@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. @xref{@t{@@unnumberedsubsec @@appendixsubsec @@subheading}}. + +@item @@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}. +@xref{@t{@@subsection}}. + +@item @@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. @xref{@t{@@subsubsection}}. + +@item @@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}. +@xref{@t{@@subsubsection}}. + +@item @@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. @xref{@t{@@title @@subtitle @@author}}. + +@item @@summarycontents +Print a short table of contents. Synonym for @code{@@shortcontents}. +@xref{Contents, , Generating a Table of Contents}. + +@item @@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 +@code{@@code}. @xref{Combining Indices}. + +@item @@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}. + +@item @@t@{@var{text}@} +Set @var{text} in a @t{fixed-width}, typewriter-like font. No effect +in Info. @xref{Fonts}. + +@item @@tab +Separate columns in a row of a multitable. @xref{Multitable Rows}. + +@item @@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 +@code{@@item}. First column entries are printed in the font resulting +from @var{formatting-command}. Pair with @code{@@end table}. +@xref{Two-column Tables, , Making a Two-column Table}. Also see +@ref{@t{@@ftable @@vtable}}, and @ref{@t{@@itemx}}. + +@item @@TeX@{@} +Generate the @TeX{} logo. @xref{@t{@@TeX @@LaTeX}}. + +@item @@tex +Enter @TeX{} completely. Pair with @code{@@end tex}. @xref{Raw +Formatter Commands}. + +@item @@textdegree@{@} +Generate the degree symbol. @xref{@t{@@textdegree}}. + +@item @@thischapter +@itemx @@thischaptername +@itemx @@thischapternum +@itemx @@thisfile +@itemx @@thispage +@itemx @@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}. + +@item @@TH@{@} +@itemx @@th@{@} +Generate the uppercase and lowercase Icelandic letter thorn, respectively: +@TH{}, @th{}. @xref{Inserting Accents}. + +@item @@tie@{@} +Generate a normal interword space at which a line break is not +allowed. @xref{@t{@@tie}}. + +@item @@tieaccent@{@var{cc}@} +Generate a tie-after accent over the next two characters @var{cc}, as in +`@tieaccent{oo}'. @xref{Inserting Accents}. + +@item @@tindex @var{entry} +Add @var{entry} to the index of data types. @xref{Index Entries, , +Defining the Entries of an Index}. + +@item @@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. +@xref{@t{@@title @@subtitle @@author}}. + +@item @@titlefont@{@var{text}@} +In a printed manual, print @var{text} in a larger than normal font. +@xref{@t{@@titlefont @@center @@sp}}. + +@item @@titlepage +Begin the title page. Write the command on a line of its own, paired +with @code{@@end titlepage}. Nothing between @code{@@titlepage} and +@code{@@end titlepage} appears in Info. @xref{@t{@@titlepage}}. + +@item @@today@{@} +Insert the current date, in `1 Jan 1900' style. @xref{Custom +Headings, , How to Make Your Own Headings}. + +@item @@top @var{title} +Mark the topmost @code{@@node} in the file, which must be defined on +the line immediately preceding the @code{@@top} command. The title is +formatted as a chapter-level heading. The entire top node, including +the @code{@@node} and @code{@@top} lines, are normally enclosed with +@code{@@ifnottex ... @@end ifnottex}. In @TeX{} and +@code{texinfo-format-buffer}, the @code{@@top} command is merely a +synonym for @code{@@unnumbered}. @xref{@t{makeinfo} Pointer +Creation}. + +@item @@u@{@var{c}@} +@itemx @@ubaraccent@{@var{c}@} +@itemx @@udotaccent@{@var{c}@} +Generate a breve, underbar, or underdot accent, respectively, over or +under the character @var{c}, as in @u{o}, @ubaraccent{o}, +@udotaccent{o}. @xref{Inserting Accents}. + +@item @@unmacro @var{macroname} +Undefine the macro @code{@@@var{macroname}} if it has been defined. +@xref{Defining Macros}. + +@item @@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. @xref{@t{@@unnumbered @@appendix}}. + +@item @@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. @xref{@t{@@unnumberedsec +@@appendixsec @@heading}}. + +@item @@unnumberedsubsec @var{title} +Begin an unnumbered subsection. The title appears in the table of +contents. In Info, the title is underlined with hyphens. +@xref{@t{@@unnumberedsubsec @@appendixsubsec @@subheading}}. + +@item @@unnumberedsubsubsec @var{title} +Begin an unnumbered subsubsection. The title appears in the table of +contents. In Info, the title is underlined with periods. +@xref{@t{@@subsubsection}}. + +@item @@uref@{@var{url}[, @var{displayed-text}][, @var{replacement}@} +@itemx @@url@{@var{url}[, @var{displayed-text}][, @var{replacement}@} +Define a cross reference to an external uniform resource locator, +e.g., for the World Wide Web. @xref{@t{@@url}}. + +@item @@urefbreakstyle @var{style} +Specify how @code{@@uref}/@code{@@url} should break at special +characters: @code{after}, @code{before}, @code{none}. +@xref{@t{@@url}}. + +@item @@v@{@var{c}@} +Generate check accent over the character @var{c}, as in @v{o}. +@xref{Inserting Accents}. + +@item @@value@{@var{txivar}@} +Insert the value, if any, of the Texinfo variable @var{txivar}, +previously defined by @code{@@set}. @xref{@t{@@set @@clear +@@value}}. + +@item @@var@{@var{metasyntactic-variable}@} +Highlight a metasyntactic variable, which is something that stands for +another piece of text. @xref{@t{@@var}}. + +@item @@verb@{@var{delim} @var{literal} @var{delim}@} +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. @xref{@t{@@verb}}. + +@item @@verbatim +Output the text of the environment exactly as is (in the fixed-width +font). Pair with @code{@@end verbatim}. @xref{@t{@@verbatim}}. + +@item @@verbatiminclude @var{filename} +Output the contents of @var{filename} exactly as is (in the +fixed-width font). @xref{@t{@@verbatiminclude}}. + +@item @@vindex @var{entry} +Add @var{entry} to the index of variables. @xref{Index Entries, , +Defining the Entries of an Index}. + +@item @@vskip @var{amount} +In a printed manual, insert whitespace so as to push text on the +remainder of the page towards the bottom of the page. Used in +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}. + +@item @@vtable @var{formatting-command} +Begin a two-column table, using @code{@@item} for each entry. +Automatically enter each of the items in the first column into the +index of variables. Pair with @code{@@end vtable}. The same as +@code{@@table}, except for indexing. @xref{@t{@@ftable @@vtable}}. + +@item @@w@{@var{text}@} +Disallow line breaks within @var{text}. @xref{@t{@@w}}. + +@item @@xml +Enter XML completely. Pair with @code{@@end xml}. @xref{Raw +Formatter Commands}. + +@item @@xref@{@var{node}, [@var{entry}], [@var{node-title}], [@var{info-file}], [@var{manual}]@} +Make a reference that starts with `See' in a printed manual. Follow +command with a punctuation mark. Only the first argument is +mandatory. @xref{@t{@@xref}}. + +@item @@xrefautomaticsectiontitle @var{on-off} +By default, use the section title instead of the node name in cross +references. @xref{Three Arguments}. + +@end table + + +@node Command Syntax +@section @@-Command Syntax +@cindex @@-command syntax +@cindex Syntax, of @@-commands +@cindex 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: + +@table @asis +@item 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{@@@}}, +@code{@@.}, @code{@@@kbd{SPACE}}, most of the accent commands, and +many more. + +@item 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: +@code{@@dots@{@}} @result{} @samp{@dots{}}, @code{@@equiv@{@}} +@result{} @samp{@equiv{}}, @code{@@TeX@{@}} @result{} `@TeX{}', and +@code{@@bullet@{@}} @result{} @samp{@bullet{}}. + +@item 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 @@dfn@{mark-up@} commands.} + +@item 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. +@end 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. + +@cindex 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 +and@tie{}4 is to make Texinfo files easier to read, and also to help +the XEmacs 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 XEmacs 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. + + +@node Command Contexts +@section @@-Command Contexts + +@cindex 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}, +@code{@@node}, and @code{@@setfilename}. + +@code{@@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 +@code{@@float} but may contain general text. @code{@@footnote} +content likewise. + +@@-commands with braces marking text (such as @code{@@strong}, +@code{@@sc}, @code{@@asis}) may contain raw formatter commands such as +@code{@@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}, +@code{@@exdent} and @code{@@item} in @code{@@table} lines, @@-commands +that makes only sense in a paragraph are not accepted, such as +@code{@@indent}. + +In addition to the above, sectioning commands cannot contain +@code{@@anchor}, @code{@@footnote} or @code{@@verb}. + +In addition to the above, remaining commands (@code{@@node}, +@code{@@anchor}, @code{@@printindex}, @code{@@ref}, @code{@@math}, +@code{@@cindex}, @code{@@url}, @code{@@image}, and so on) cannot +contain cross reference commands (@code{@@ref}, @code{@@xref}, +@code{@@pxref} and @code{@@inforef}). In one last addition, +@code{@@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. + + +@node Tips +@appendix Tips and Hints + +Here are some tips for writing Texinfo documentation: + +@cindex Tips +@cindex Usage tips +@cindex Hints +@itemize @bullet +@item +Write in the present tense, not in the past or the future. + +@item +Write actively! For example, write ``We recommend that @dots{}'' rather +than ``It is recommended that @dots{}''. + +@item +Use 70 or 72 as your fill column. Longer lines are hard to read. + +@item +Include a copyright notice and copying permissions. +@end itemize + + +@subsubheading 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: + +@itemize @bullet +@item +Write each index entry differently, so each entry refers to a different +place in the document. + +@item +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. + +@item +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. + +@item +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. + +@item +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'': + +@example +@group +@@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. +@end group +@end example + +@noindent +(Note that the example shows entries for the same concept that are +written in different ways---@samp{Lazy dog}, and @samp{Dog, lazy}---so +readers can look up the concept in different ways.) +@end itemize + + +@subsubheading Blank Lines + +@itemize @bullet +@item +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. + +@item +Always insert a blank line before an @code{@@table} command and after an +@code{@@end table} command; but never insert a blank line after an +@code{@@table} command. + +@need 1000 +For example, + +@example +@group +Types of fox: + +@@table @@samp +@@item Quick +Jump over lazy dogs. +@end group + +@group +@@item Brown +Also jump over lazy dogs. +@@end table + +@end group +@group +@@noindent +On the other hand, @dots{} +@end group +@end example + +Insert blank lines before and after @code{@@itemize} @dots{} @code{@@end +itemize} and @code{@@enumerate} @dots{} @code{@@end enumerate} in the +same way. +@end itemize + + +@subsubheading Complete Phrases + +Complete phrases are easier to read than @dots{} + +@itemize @bullet +@item +Write entries in an itemized list as complete sentences; or at least, as +complete phrases. Incomplete expressions @dots{} awkward @dots{} like +this. + +@item +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. +@end itemize + + +@subsubheading Editions, Dates and Versions + +Include edition numbers, version numbers, and dates in the +@code{@@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}. @xref{@t{@@value} Example}, and @ref{GNU +Sample Texts}. + + +@subsubheading Definition Commands + +Definition commands are @code{@@deffn}, @code{@@defun}, +@code{@@defmac}, and the like, and enable you to write descriptions in +a uniform format. + +@itemize @bullet +@item +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. + +@item +Use @code{@@table} @dots{} @code{@@end table} in an appendix that +contains a summary of functions, not @code{@@deffn} or other definition +commands. +@end itemize + + +@subsubheading Capitalization + +@itemize @bullet +@item +Capitalize ``Texinfo''; it is a name. Do not write the @samp{x} or +@samp{i} in uppercase. + +@item +Capitalize ``Info''; it is a name. + +@item +Write @TeX{} using the @code{@@TeX@{@}} command. Note the uppercase +@samp{T} and @samp{X}. This command causes the formatters to +typeset the name according to the wishes of Donald Knuth, who wrote +@TeX{}. (Likewise @code{@@LaTeX@{@}} for @LaTeX{}.) +@end itemize + + +@subsubheading Spaces + +Do not use spaces to format a Texinfo file, except inside of +@code{@@example} @dots{} @code{@@end example} and other literal +environments and commands. + +@need 700 +For example, @TeX{} fills the following: + +@example +@group + @@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. +@end group +@end example + +@need 950 +@noindent +so it looks like this: + +@iftex +@quotation + @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. +@end quotation +@end iftex +@ifnottex +@quotation +`C-x v' `M-x vc-next-action' Perform the next logical operation on the +version-controlled file corresponding to the current buffer. +@end quotation +@end ifnottex + +@noindent +In this case, the text should be formatted with +@code{@@table}, @code{@@item}, and @code{@@itemx}, to create a table. + + +@subsubheading @@code, @@samp, @@var, and @samp{---} + +@itemize @bullet +@item +Use @code{@@code} around Lisp symbols, including command names. +For example, + +@example +The main function is @@code@{vc-next-action@}, @dots{} +@end example + +@item +Avoid putting letters such as @samp{s} immediately after an +@samp{@@code}. Such letters look bad. + +@item +Use @code{@@var} around meta-variables. Do not write angle brackets +around them. + +@item +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. +@end itemize + + +@subsubheading 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: + +@example +Evidently, @samp{au} is an abbreviation for ``author''. +@end example + +@noindent +since @samp{au} does @emph{not} serve as an abbreviation for +@samp{author.} (with a period following the word). + + +@subsubheading Introducing New Terms + +@itemize @bullet +@item +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. + +@quotation +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. +@end quotation + +@item +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. +@end itemize + + +@subsubheading Program Invocation Nodes + +You can invoke programs such as XEmacs, 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 XEmacs'; this way, users can +find the section easily. + + +@subsubheading ANSI C Syntax + +When you use @code{@@example} to describe a C function's calling +conventions, use the ANSI C syntax, like this: + +@example +void dld_init (char *@@var@{path@}); +@end example + +@noindent +And in the subsequent discussion, refer to the argument values by +writing the same argument names, again highlighted with +@code{@@var}. + +@need 800 +Avoid the obsolete style that looks like this: + +@example +#include <dld.h> + +dld_init (path) + char *path; +@end 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 +@code{#include} 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. + +@anchor{texi-elements-by-size} +@subsubheading 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 +@file{util/} subdirectory of the Texinfo sources. + + +@subsubheading Bad Examples + +Here are several examples of bad writing to avoid: + +In this example, say, `` @dots{} you must @code{@@dfn}@{check +in@} the new version.'' That flows better. + +@quotation +When you are done editing the file, you must perform a +@code{@@dfn}@{check in@}. +@end quotation + +In the following example, say, ``@dots{} makes a unified interface such as VC +mode possible.'' + +@quotation +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). +@end quotation + +And in this example, you should specify what `it' refers to: + +@quotation +If you are working with other people, it assists in coordinating +everyone's changes so they do not step on each other. +@end quotation + + +@subsubheading And Finally @dots{} + +@itemize @bullet +@item +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''. + +@item +Write notes for yourself at the very end of a Texinfo file after the +@code{@@bye}. None of the formatters process text after the +@code{@@bye}; it is as if the text were within @code{@@ignore} @dots{} +@code{@@end ignore}. +@end itemize + + +@node Sample Texinfo Files +@appendix Sample Texinfo Files +@cindex 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. + +@menu +* Short Sample Texinfo File:: +* GNU Sample Texts:: +* Verbatim Copying License:: +* All-permissive Copying License:: +@end menu + + +@node Short Sample Texinfo File +@section Short Sample +@cindex Sample Texinfo file, no comments + +Here is a complete, short sample Texinfo file, 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. + + +@sp 1 +@example +\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 @@copyright@{@} 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 +@end example + + +@node GNU Sample Texts +@section GNU Sample Texts + +@cindex GNU sample texts +@cindex Sample texts, GNU +@cindex 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. + +@xref{Short Sample}, for a minimal example of a Texinfo file. +@xref{Beginning a File}, for a full explanation of that minimal +example. + +Here are some notes on the example: + +@itemize @bullet +@item +@cindex $Id +@cindex CVS $Id +@cindex RCS $Id +@cindex Documentation identification +@cindex Identification of documentation +The @samp{$Id:} comment is for the CVS (@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: + +@example +$Id$ +@end example + +(This is potentially useful in all sources that use version control, +not just manuals.) You may wish to include the @samp{$Id:} comment in +the @code{@@copying} text, if you want a completely unambiguous +reference to the documentation source version. + +If you want to literally write @t{@w{$}Id$}, use @code{@@w}: +@code{@@w@{$@}Id$}. Unfortunately, this technique does not work in +plain text output, where it's not clear what should be done. + +@item +@pindex automake@r{, and version info} +@vindex UPDATED @r{Automake variable} +@vindex VERSION @r{Automake variable} +@pindex 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 XEmacs, you may +find the time-stamp.el package helpful (@pxref{Time Stamps,,, xemacs, +XEmacs User's Manual}). + +@item +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. + +@item +The @code{@@dircategory} is for constructing the Info directory. +@xref{Installing Dir Entries}, which includes a variety of recommended +category names. + +@item +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}. + +@item +@cindex GNU Free Documentation License, including entire +@cindex Free Documentation License, including entire +It is best to include the entire GNU Free Documentation License in a GNU +manual, unless the manual is only a few pages long. Of course this +sample is even shorter than that, but it includes the FDL anyway in +order to show one conventional way to do so. The @file{fdl.texi} file +is available on the GNU machines and in the Texinfo and other GNU +source distributions. + +The FDL provides for omitting itself under certain conditions, but in +that case the sample texts given here have to be modified. @xref{GNU +Free Documentation License}. + +@item +If the FSF is not the copyright holder, then use the appropriate name. + +@item +If your manual is published on paper by the FSF or is longer than 400 +pages, you should include the standard FSF cover texts (@pxref{License +Notices for Documentation,,, maintain, GNU Maintainer Information}). + +@item +For documents that express your personal views, feelings or +experiences, it is more appropriate to use a license permitting only +verbatim copying, rather than the FDL@. @xref{Verbatim Copying +License}. + +@end itemize + +Here is the sample document: + +@verbatim +\input texinfo @c -*-texinfo-*- +@comment $Id@w{$} +@comment %**start of header +@setfilename sample.info +@include version.texi +@settitle GNU Sample @value{VERSION} +@syncodeindex pg cp +@comment %**end of header +@copying +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. + +@quotation +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''. +@end quotation +@end copying + +@dircategory Texinfo documentation system +@direntry +* sample: (sample)Invoking sample. +@end direntry + +@titlepage +@title GNU Sample +@subtitle for version @value{VERSION}, @value{UPDATED} +@author A.U. Thor (@email{bug-sample@@gnu.org}) +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@contents + +@ifnottex +@node Top +@top GNU Sample + +This manual is for GNU Sample (version @value{VERSION}, @value{UPDATED}). +@end ifnottex + +@menu +* Invoking sample:: +* GNU Free Documentation License:: +* Index:: +@end menu + + +@node Invoking sample +@chapter Invoking sample + +@pindex sample +@cindex 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. + + +@node GNU Free Documentation License +@appendix GNU Free Documentation License + +@include fdl.texi + + +@node Index +@unnumbered Index + +@printindex cp + +@bye +@end verbatim + + +@node Verbatim Copying License +@section Verbatim Copying License + +@cindex Verbatim copying license +@cindex 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. + +@verbatim +@copying +This document is a sample for allowing verbatim copying only. + +Copyright @copyright{} 2013 Free Software Foundation, Inc. + +@quotation +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. +@end quotation +@end copying +@end verbatim + + +@node All-permissive Copying License +@section All-permissive Copying License + +@cindex All-permissive copying license +@cindex 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. + +@example +Copyright @@copyright@{@} 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. +@end example + + +@node Headings +@appendix Page Headings +@cindex Headings +@cindex Footings +@cindex Page numbering +@cindex Page headings +@cindex Formatting headings and footings + +Most printed manuals contain headings along the top of every page +except the title and copyright pages. Some manuals also contain +footings. @c HTML output also supports something like these, but in a +@c completely different way: @pxref{Customizing HTML Page Layout}. +Headings and footings have no meaning in Info or the other output +formats. + +@menu +* Headings Introduced:: Conventions for using page headings. +* Heading Format:: Standard page heading formats. +* Heading Choice:: How to specify the type of page heading. +* Custom Headings:: How to create your own headings and footings. +@end menu + +@node Headings Introduced +@section Headings Introduced + +Texinfo provides standard page heading formats for manuals that are +printed on one side of each sheet of paper and for manuals that are +printed on both sides of the paper. Typically, you will use these +formats, but you can specify your own format if you wish. + +In addition, you can specify whether chapters should begin on a new +page, or merely continue the same page as the previous chapter; and if +chapters begin on new pages, you can specify whether they must be +odd-numbered pages. + +By convention, a book is printed on both sides of each sheet of paper. +When you open a book, the right-hand page is odd-numbered, and +chapters begin on right-hand pages---a preceding left-hand page is +left blank if necessary. Reports, however, are often printed on just +one side of paper, and chapters begin on a fresh page immediately +following the end of the preceding chapter. In short or informal +reports, chapters often do not begin on a new page at all, but are +separated from the preceding text by a small amount of whitespace. + +The @code{@@setchapternewpage} command controls whether chapters begin +on new pages, and whether one of the standard heading formats is used. +In addition, Texinfo has several heading and footing commands that you +can use to generate your own heading and footing formats. + +In Texinfo, headings and footings are single lines at the tops and +bottoms of pages; you cannot create multiline headings or footings. +Each header or footer line is divided into three parts: a left part, a +middle part, and a right part. Any part, or a whole line, may be left +blank. Text for the left part of a header or footer line is set +flushleft; text for the middle part is centered; and, text for the +right part is set flushright. + + +@node Heading Format +@section Standard Heading Formats + +Texinfo provides two standard heading formats, one for manuals printed +on one side of each sheet of paper, and the other for manuals printed +on both sides of the paper. + +By default, nothing is specified for the footing of a Texinfo file, +so the footing remains blank. + +The standard format for single-sided printing consists of a header +line in which the left-hand part contains the name of the chapter, the +central part is blank, and the right-hand part contains the page +number. + +@need 950 +A single-sided page looks like this: + +@example +@group + _______________________ + | | + | chapter page number | + | | + | Start of text ... | + | ... | + | | +@end group +@end example + +The standard format for two-sided printing depends on whether the page +number is even or odd. By convention, even-numbered pages are on the +left- and odd-numbered pages are on the right. (@TeX{} will adjust the +widths of the left- and right-hand margins. Usually, widths are +correct, but during double-sided printing, it is wise to check that +pages will bind properly---sometimes a printer will produce output in +which the even-numbered pages have a larger right-hand margin than the +odd-numbered pages.) + +In the standard double-sided format, the left part of the left-hand +(even-numbered) page contains the page number, the central part is +blank, and the right part contains the title (specified by the +@code{@@settitle} command). The left part of the right-hand +(odd-numbered) page contains the name of the chapter, the central part +is blank, and the right part contains the page number. + +@need 750 +Two pages, side by side as in an open book, look like this: + +@example +@group + _______________________ _______________________ + | | | | + | page number title | | chapter page number | + | | | | + | Start of text ... | | More text ... | + | ... | | ... | + | | | | +@end group +@end example + +@noindent +The chapter name is preceded by the word ``Chapter'', the chapter number +and a colon. This makes it easier to keep track of where you are in the +manual. + +@node Heading Choice +@section Specifying the Type of Heading + +@TeX{} does not begin to generate page headings for a standard Texinfo +file until it reaches the @code{@@end titlepage} command. Thus, the +title and copyright pages are not numbered. The @code{@@end +titlepage} command causes @TeX{} to begin to generate page headings +according to a standard format specified by the +@code{@@setchapternewpage} command that precedes the +@code{@@titlepage} section. + +@need 1000 +There are four possibilities: + +@table @asis +@item No @code{@@setchapternewpage} command +Cause @TeX{} to specify the single-sided heading format, with chapters +on new pages. This is the same as @code{@@setchapternewpage on}. + +@item @code{@@setchapternewpage on} +Specify the single-sided heading format, with chapters on new pages. + +@item @code{@@setchapternewpage off} +Cause @TeX{} to start a new chapter on the same page as the last page +of the preceding chapter, after skipping some vertical whitespace. +Also cause @TeX{} to typeset for single-sided printing. (You can +override the headers format with the @code{@@headings double} command; +@pxref{@t{@@headings}}.) + +@item @code{@@setchapternewpage odd} +Specify the double-sided heading format, with chapters on new pages. +@end table + +@noindent +Texinfo lacks an @code{@@setchapternewpage even} command. + + +@node Custom Headings +@section How to Make Your Own Headings + +You can use the standard headings provided with Texinfo or specify +your own. By default, Texinfo has no footers, so if you specify them, +the available page size for the main text will be slightly reduced. + +Texinfo provides six commands for specifying headings and +footings: +@itemize @bullet +@item +@code{@@everyheading} and @code{@@everyfooting} generate page headers and +footers that are the same for both even- and odd-numbered pages. +@item +@code{@@evenheading} and @code{@@evenfooting} command generate headers +and footers for even-numbered (left-hand) pages. +@item +@code{@@oddheading} and @code{@@oddfooting} generate headers and footers +for odd-numbered (right-hand) pages. +@end itemize + +Write custom heading specifications in the Texinfo file immediately +after the @code{@@end titlepage} command. You must cancel the +predefined heading commands with the @code{@@headings off} command +before defining your own specifications. + +@need 1000 +Here is how to tell @TeX{} to place the chapter name at the left, the +page number in the center, and the date at the right of every header +for both even- and odd-numbered pages: + +@example +@group +@@headings off +@@everyheading @@thischapter @@| @@thispage @@| @@today@{@} +@end group +@end example + +@noindent +You need to divide the left part from the central part and the central +part from the right part by inserting @samp{@@|} between parts. +Otherwise, the specification command will not be able to tell where +the text for one part ends and the next part begins. + +Each part can contain text or @@-commands. The text is printed as if +the part were within an ordinary paragraph in the body of the page. +The @@-commands replace themselves with the page number, date, chapter +name, or whatever. + +@need 950 +Here are the six heading and footing commands: + +@table @code +@item @@everyheading @var{left} @@| @var{center} @@| @var{right} +@itemx @@everyfooting @var{left} @@| @var{center} @@| @var{right} +@findex everyheading +@findex everyfooting +The `every' commands specify the format for both even- and odd-numbered +pages. These commands are for documents that are printed on one side +of each sheet of paper, or for documents in which you want symmetrical +headers or footers. + +@item @@evenheading @var{left} @@| @var{center} @@| @var{right} +@itemx @@oddheading @var{left} @@| @var{center} @@| @var{right} +@itemx @@evenfooting @var{left} @@| @var{center} @@| @var{right} +@itemx @@oddfooting @var{left} @@| @var{center} @@| @var{right} +@findex evenheading +@findex evenfooting +@findex oddheading +@findex oddfooting +The `even' and `odd' commands specify the format for even-numbered +pages and odd-numbered pages. These commands are for books and +manuals that are printed on both sides of each sheet of paper. +@end table + +Use the @samp{@@this@dots{}} series of @@-commands to +provide the names of chapters +and sections and the page number. You can use the +@samp{@@this@dots{}} commands in the left, center, or right portions +of headers and footers, or anywhere else in a Texinfo file so long as +they are between @code{@@iftex} and @code{@@end iftex} commands. + +@need 1000 +Here are the @samp{@@this@dots{}} commands: + +@table @code +@item @@thispage +@findex thispage +Expands to the current page number. + +@item @@thissectionname +@findex thissectionname +Expands to the name of the current section. + +@item @@thissectionnum +@findex thissectionnum +Expands to the number of the current section. + +@item @@thissection +@findex thissection +Expands to the number and name of the current section, in the format +`Section 1: Title'. + +@item @@thischaptername +@findex thischaptername +Expands to the name of the current chapter. + +@item @@thischapternum +@findex thischapternum +Expands to the number of the current chapter, or letter of the current +appendix. + +@item @@thischapter +@findex thischapter +Expands to the number and name of the current +chapter, in the format `Chapter 1: Title'. + +@item @@thistitle +@findex thistitle +Expands to the name of the document, as specified by the +@code{@@settitle} command. + +@item @@thisfile +@findex thisfile +For @code{@@include} files only: expands to the name of the current +@code{@@include} file. If the current Texinfo source file is not an +@code{@@include} file, this command has no effect. This command does +@emph{not} provide the name of the current Texinfo source file unless +it is an @code{@@include} file. (@xref{Include Files}, for more +information about @code{@@include} files.) +@end table + +@noindent +You can also use the @code{@@today@{@}} command, which expands to the +current date, in `1 Jan 1900' format. +@findex today + +Other @@-commands and text are printed in a header or footer just as +if they were in the body of a page. It is useful to incorporate text, +particularly when you are writing drafts: + +@example +@group +@@headings off +@@everyheading @@emph@{Draft!@} @@| @@thispage @@| @@thischapter +@@everyfooting @@| @@| Version: 0.27: @@today@{@} +@end group +@end example + +Beware of overlong titles: they may overlap another part of the +header or footer and blot it out. + +If you have very short chapters and/or sections, several of them can +appear on a single page. You can specify which chapters and sections +you want @code{@@thischapter}, @code{@@thissection} and other such +macros to refer to on such pages as follows: + +@table @code +@item @@everyheadingmarks @var{ref} +@itemx @@everyfootingmarks @var{ref} +@findex everyheadingmarks +@findex everyfootingmarks +The @var{ref} argument can be either @code{top} (the @code{@@this...} +commands will refer to the chapter/section at the top of a page) or +@code{bottom} (the commands will reflect the situation at the bottom +of a page). These @samp{@@every...} commands specify what to do on +both even- and odd-numbered pages. + +@item @@evenheadingmarks @var{ref} +@itemx @@oddheadingmarks @var{ref} +@itemx @@evenfootingmarks @var{ref} +@itemx @@oddfootingmarks @var{ref} +@findex evenheadingmarks +@findex oddheadingmarks +@findex evenfootingmarks +@findex oddfootingmarks +These @samp{@@even...} and @samp{@@odd...} commands specify what to do +on only even- or odd-numbered pages, respectively. The @var{ref} +argument is the same as with the @samp{@@every...} commands. +@end table + +Write these commands immediately after the @code{@@...contents} +commands, or after the @code{@@end titlepage} command if you don't +have a table of contents or if it is printed at the end of your +manual. + +By default the @code{@@this...} commands reflect the situation at the +bottom of a page both in headings and in footings. + + +@node Catching Mistakes +@appendix Catching Mistakes +@cindex Structure, catching mistakes in +@cindex Nodes, catching mistakes +@cindex Catching mistakes +@cindex Correcting mistakes +@cindex Mistakes, catching +@cindex Problems, catching +@cindex 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. + +XEmacs 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 +@kbd{C-c C-s} (@code{texinfo-show-structure}) and the related @code{occur} +command and you can use the @kbd{M-x Info-validate} command. + +@menu +* @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. +@end menu + + +@node @t{makeinfo} Preferred +@section @code{makeinfo} Preferred + +@c anchor{makeinfo Preferred}@c prev name + +The @code{makeinfo} program does an excellent job of catching errors +and reporting them---far better than @code{texinfo-format-region} or +@code{texinfo-format-buffer}. 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 +@code{makeinfo-buffer}) to format your file and check for other +errors. This is the best way to work with Texinfo. But if you +cannot use @code{makeinfo}, or your problem is very puzzling, then you +may want to use the tools described in this appendix. + + +@node Debugging with Info +@section Catching Errors with Info Formatting +@cindex Catching errors with Info formatting +@cindex Debugging with Info formatting + +After you have written part of a Texinfo file, you can use the +@code{texinfo-format-region} 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 +@code{texinfo-format-region}. + +If you have made a mistake with an @@-command, +@code{texinfo-format-region} 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: + +@example +@@end menus is not handled by texinfo +@end example + +@noindent +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: + +@example +@group +---------- 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 +@point{} +---------- Buffer: *Info Region* ---------- +@end group +@end example + +The @code{texinfo-format-region} command sometimes provides slightly +odd error messages. For example, the following cross reference fails to format: + +@example +(@@xref@{Catching Mistakes, for more info.) +@end example + +@noindent +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: + +@example +(@@xref@{Catching Mistakes), for more info.@} +@end example + +@noindent +Formatting produces: +@example +(*Note for more info.: Catching Mistakes) +@end example + +The only way for you to detect this error is to realize that the +reference should have looked like this: + +@example +(*Note Catching Mistakes::, for more info.) +@end example + +Incidentally, if you are reading this node in Info and type @kbd{f +@key{RET}} (@code{Info-follow-reference}), you will generate an error +message that says: + +@example +No such node: "Catching Mistakes) The only way @dots{} +@end example + +@noindent +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}).) + + +@node Debugging with @TeX{} +@section Debugging with @TeX{} +@cindex Catching errors with @TeX{} formatting +@cindex 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 +@code{texinfo-format-buffer} (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: + +@example +---------- Buffer: texinfo.texi ---------- +name of the Texinfo file as an extension. The +@@samp@{??@} are `wildcards' that cause the shell to +substitute all the raw index files. (@@xref@{sorting +indices, for more information about sorting +indices.)@@refill +---------- Buffer: texinfo.texi ---------- +@end example + +@noindent +(The cross reference lacks a closing brace.) +@TeX{} produced the following output, after which it stopped: + +@example +---------- Buffer: *tex-shell* ---------- +Runaway argument? +@{sorting 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* ---------- +@end example + +In this case, @TeX{} produced an accurate and +understandable error message: + +@example +Paragraph ended before @@xref was complete. +@end example + +@noindent +@samp{@@par} is an internal @TeX{} command of no relevance to Texinfo. +@samp{l.27} 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. + +@enumerate +@item +You can tell @TeX{} to continue running and ignore just this error by +typing @key{RET} at the @samp{?} prompt. + +@item +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 +@kbd{C-c C-c}, if you are running a shell inside XEmacs). + +@item +You can tell @TeX{} to stop this run by typing @kbd{x @key{RET}} +at the @samp{?} prompt. +@end enumerate + +If you are running @TeX{} inside XEmacs, 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 +@TeX{} will give you is the somewhat mysterious comment: + +@example +(@@end occurred inside a group at level 1) +@end example + +@noindent +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 +@code{@@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, +@TeX{} 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. + +@example +This is TeX, Version 3.14159 (Web2c 7.0) +(test.texinfo [1]) +* +@end example + +@noindent +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.) + +@node Using @t{texinfo-show-structure} +@section Using @code{texinfo-show-structure} + +@cindex Showing the structure of a file +@findex 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 XEmacs, 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}, +@code{@@appendix}, and so on. With an argument (@w{@kbd{C-u}} +as prefix argument, if interactive), +the command also shows the @code{@@node} lines. The +@code{texinfo-show-structure} 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: + +@example +@group +Lines matching "^@@\\(chapter \\|sect\\|subs\\|subh\\| +unnum\\|major\\|chapheading \\|heading \\|appendix\\)" +in buffer texinfo.texi. +@dots{} +4177:@@chapter Nodes +4198: @@heading Two Paths +4231: @@section Node and Menu Illustration +4337: @@section The @@code@{@@@@node@} Command +4393: @@subheading Choosing Node and Pointer Names +4417: @@subsection How to Write an @@code@{@@@@node@} Line +4469: @@subsection @@code@{@@@@node@} Line Tips +@dots{} +@end group +@end 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 +@kbd{C-c C-c} command (@code{occur-mode-goto-occurrence}), to jump to +the corresponding spot in the Texinfo file. @xref{Other Repeating +Search, , Using Occur, xemacs, XEmacs User's Manual}, for more +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. +@xref{Regexps, , Using Regular Expressions, xemacs, XEmacs User's Manual}, +for more information. + +When you invoke the @code{texinfo-show-structure} command, XEmacs will +display the structure of the whole buffer. If you want to see the +structure of just a part of the buffer, of one chapter, for example, +use the @kbd{C-x n n} (@code{narrow-to-region}) command to mark the +region. (@xref{Narrowing, , , xemacs, XEmacs User's Manual}.) This is +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 @w{@kbd{C-u C-c C-s}}, it will list lines beginning with +@code{@@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. + +@node Using @t{occur} +@section Using @code{occur} + +@cindex Occurrences, listing with @code{@@occur} +@findex 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 +@code{texinfo-show-structure}. In this case, you can use the @code{occur} +command directly. To do this, type: + +@example +@kbd{M-x occur} +@end example + +@noindent +and then, when prompted, type a @dfn{regexp}, a regular expression for +the pattern you want to match. (@xref{Regexps, , Regular Expressions, +xemacs, XEmacs User's Manual}.) The @code{occur} command works from +the current location of the cursor in the buffer to the end of the +buffer. If you want to run @code{occur} on the whole buffer, place +the cursor at the beginning of the buffer. + +For example, to see all the lines that contain the word +@samp{@@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 +@samp{@@chapter}, type @samp{^@@chapter} when prompted by +@code{occur}. If you want to see all the lines that end with a word +or phrase, end the last word with a @samp{$}; for example, +@samp{catching 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. + +@xref{Other Repeating Search, , Using Occur, xemacs, XEmacs User's Manual}, +for more information. + + +@node Running @t{Info-validate} +@section Finding Badly Referenced Nodes + +@anchor{Running Info-Validate}@c old name +@findex Info-validate +@cindex Nodes, checking for badly referenced +@cindex Checking for badly referenced nodes +@cindex Looking for badly referenced nodes +@cindex Finding badly referenced nodes +@cindex 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 +@code{makeinfo}. 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. + +@menu +* 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. +@end menu + + +@node Using @t{Info-validate} +@subsection Using @code{Info-validate} + +@cindex Using @code{Info-validate} +@cindex Info validating a large file +@cindex Validating a large file + +To use @code{Info-validate}, visit the Info file you wish to check and +type: + +@example +M-x Info-validate +@end example + +@noindent +Note that the @code{Info-validate} command requires an uppercase +`I'@. You may also need to create a tag table before running +@code{Info-validate}. @xref{Tagifying}. + +If your file is valid, you will receive a message that says ``File appears +valid''. However, if you have a pointer that does not point to a node, +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: + +@example +In node "Overview", invalid Next: Texinfo Mode +@end example + +@noindent +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: + +@example +In node "Texinfo Mode", should have Previous: Overview +@end example + +@noindent +This is because every `Next' pointer should be matched by a +`Previous' (in the node where the `Next' points) which points back. + +@code{Info-validate} also checks that all menu entries and cross references +point to actual nodes. + +@code{Info-validate} requires a tag table and does not work with files +that have been split. (The @code{texinfo-format-buffer} command +automatically splits large files.) In order to use @code{Info-validate} +on a large file, you must run @code{texinfo-format-buffer} with an +argument so that it does not split the Info file; and you must create a +tag table for the unsplit file. + +@node Unsplit +@subsection Creating an Unsplit File +@cindex Creating an unsplit file +@cindex 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 +@code{texinfo-format-buffer} 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 +@code{texinfo-format-buffer} from splitting a Texinfo file into +smaller Info files, give a prefix to the @kbd{M-x +texinfo-format-buffer} command: + +@example +C-u M-x texinfo-format-buffer +@end example + +@noindent +or else + +@example +C-u C-c C-e C-b +@end example + +@noindent +When you do this, Texinfo will not split the file and will not create +a tag table for it. +@cindex Making a tag table manually +@cindex Tag table, making manually + +@node Tagifying +@subsection Tagifying a File + +After creating an unsplit Info file, you must create a tag table for +it. Visit the Info file you wish to tagify and type: + +@example +M-x Info-tagify +@end example + +@noindent +(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: + +@example +M-x Info-validate +@end example + +@noindent +(Note the uppercase @samp{I} in @code{Info-validate}.) +In brief, the steps are: + +@example +@group +C-u M-x texinfo-format-buffer +M-x Info-tagify +M-x Info-validate +@end group +@end example + +After you have validated the node structure, you can rerun +@code{texinfo-format-buffer} 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. + +@node Splitting +@subsection Splitting a File Manually +@cindex Splitting an Info file manually +@cindex Info file, splitting manually + +You should split a large file or else let the +@code{texinfo-format-buffer} or @code{makeinfo-buffer} command do it +for you automatically. (Generally you will let one of the formatting +commands do this job for you. @xref{Creating an Info File}.) + +The split-off files are called the indirect subfiles. + +Info files are split to save memory. With smaller files, XEmacs does not +have to make such a large buffer to hold the information. + +If an Info file has more than 30 nodes, you should also make a tag +table for it. @xref{Using @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 +@code{Info-validate}.) + +Visit the Info file you wish to tagify and split and type the two +commands: + +@example +M-x Info-tagify +M-x Info-split +@end example + +@noindent +(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. + + +@node Info Format Specification +@appendix Info Format Specification + +@cindex Info format specification +@cindex Specification of Info format +@cindex 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 @samp{^@var{x}} means the single +character @samp{CTRL-@var{x}}, for any @var{x}. + +@menu +* General: Info Format General Layout. +* Text: Info Format Text Constructs. +@end menu + + +@node Info Format General Layout +@section Info Format General Layout + +This section describes the overall layout of Info manuals. + +@menu +* 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. +@end menu + + +@node Info Format Whole Manual +@subheading Info Format: A Whole Manual + +@cindex Nonsplit manuals, Info format of +@cindex Split manuals, Info format of +@cindex 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: + +@example + <nonsplit info file> = +<preamble> +<node>* +<tag table> +(<local variables>)? +@end 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: + +@example + <split info main file> = +<preamble> +<indirect table> +<tag table> +(<local variables>)? +@end example + +The subfiles in a split manual have the following syntax: + +@example + <split info subfile> = +<preamble> +<node>* +@end example + + +@node Info Format Preamble +@subheading Info Format: Preamble + +@cindex 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. + +@example + <preamble> = +<identification> # "This is FILENAME, produced by ..." +<copying text> # Expansion of @@copying text. +<dir entries> # Derived from @@dircategory and @@direntry. +@end example + +These pieces are: + +@table @t +@item <identification line> +An arbitrary string beginning the output file, followed by a blank +line. + +@item <copying text> +The expansion of an @code{@@copying} environment, if the manual has +one (@pxref{@t{@@copying}}). + +@item <dir entries> +The result of any @code{@@dircategory} and @code{@@direntry} +commands present in the manual (@pxref{Installing Dir Entries}). + +@end table + + +@node Info Format Indirect Tag Table +@subheading Info Format: Indirect Tag Table + +@cindex 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): + +@example + <indirect table> = +^_ +Indirect: +(<filename>: <bytepos>)* +@end 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: + +@example +^_ +Indirect: +gdb.info-1: 1878 +gdb.info-2: 295733 +... +@end 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 +@file{gdb.info} files were appended to @file{gdb.info-1}, including +their preambles. + + +@node Info Format Tag Table +@subheading Info Format: Tag Table + +@cindex 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. + +@example + <tag table> = +^_ +Tag Table: +<lparen>Indirect<rparen> # this line appears in split output only +(Node|Ref): <nodeid>^?<bytepos> +^_ +End Tag Table +@end 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 +@samp{Top} starts at byte 1647 while @samp{Ref: +Overview-Footnote-1^?30045} says that the anchor named +@samp{Overview-Footnote-1} 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: + +@example +^_ +Tag Table: +Node: Top^_89 +Node: Ch1^_292 +^_ +End Tag Table +@end 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. + + +@node Info Format Local Variables +@subheading Info Format: Local Variables + +@cindex 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. + +@example + <local variables> = +^_ +Local Variables: +coding: <encoding> +End: +@end example + +@xref{@t{@@documentencoding}}. + + +@node Info Format Regular Nodes +@subheading Info Format: Regular Nodes + +@cindex Info nodes, in Info format + +Regular nodes look like this: + +@example + <node> = +^_ +File: <fn>, Node: <id1>, (Next: <id2>, )? (Prev: <id3>, )? Up: <id4> + +<general text, until the next ^_ or end-of-file> +@end 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. + + +@node Info Format Text Constructs +@section Info Format Text Constructs + +@cindex Info format text constructs +@cindex text constructs, Info format + +These special Info constructs can appear within the text of a node. + +@menu +* Menu: Info Format Menu. +* Image: Info Format Image. +* Printindex: Info Format Printindex. +* Xref: Info Format Cross Reference. +@end menu + + +@node Info Format Menu +@subsection Info Format: Menu + +@cindex Menus, in Info format + +Conventionally menus appear at the end of nodes, but the Info format +places no restrictions on their location. + +@example + <menu> = +* Menu: +(<menu entry> | <menu comment>)* +@end 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}). + + +@node Info Format Image +@subsection Info Format: Image + +@cindex Images, in Info format + +The @code{@@image} command results in the following special directive +within the Info file (@pxref{Images}): + +@example + <image> = +^@@^H[image src="<image file>" + (text="<txt file contents>")? + (alt="<alt text>")? +^@@^H] +@end 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 +@samp{\\}. 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 +@t{<image file>}, the @t{<alt text>} or @t{<txt file contents>}. + + +@node Info Format Printindex +@subsection Info Format: Printindex + +@cindex 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: + +@example + <printindex> = +^@@^H[index^@@^H] +* Menu: + +<index entry>* +@end 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: + +@example + <index entry> = +* <entry text>: <entry node>. <lparen>line <lineno><rparen> +@end example + +@noindent +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: + +@example +^@@^H[index^@@^H] +* Menu: + +* thunder: Weather Phenomena. (line 5) +@end example + +This means that an index entry for `thunder' appears at line 5 of the +node `Weather Phenomena'. + + +@node Info Format Cross Reference +@subsection Info Format: Cross Reference + +@cindex Cross references, in Info format + +A general cross reference in Info format is written as follows: + +@example + <cross-reference> = +* (N|n)ote (<id>:: | <label>:(<lparen><infofile><rparen>)?<id>(.|,)) +@end 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 +@samp{(<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: + +@example +*note GNU Free Documentation License:: +*note Tag table: Info Format Tag Table, for details. +*Note Overview: (make)Top. +@end 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 +@samp{make}, with `Overview' being the label for this cross reference. + +@xref{Cross References}. + + +@c The simple description in the command summary seems sufficient to me +@c these days, so ignore this appendix. --karl, 13mar04. +@c +@c @node Refilling Paragraphs +@c @appendix Refilling Paragraphs +@c @cindex Refilling paragraphs +@c @cindex Filling paragraphs +@c @cindex Paragraphs, filling +@c @findex refill +@c +@c The @code{@@refill} command refills and, optionally, indents the first +@c line of a paragraph.@footnote{Perhaps the command should have been +@c called the @code{@@refillandindent} command, but @code{@@refill} is +@c shorter and the name was chosen before indenting was possible.} The +@c @code{@@refill} command is no longer important, but we describe it here +@c because you once needed it. You will see it in many old Texinfo +@c files. +@c +@c Without refilling, paragraphs containing long @@-constructs may look +@c bad after formatting because the formatter removes @@-commands and +@c shortens some lines more than others. In the past, neither the +@c @code{texinfo-format-region} command nor the +@c @code{texinfo-format-buffer} command refilled paragraphs +@c automatically. The @code{@@refill} command had to be written at the +@c end of every paragraph to cause these formatters to fill them. (Both +@c @TeX{} and @code{makeinfo} have always refilled paragraphs +@c automatically.) Now, all the Info formatters automatically fill and +@c indent those paragraphs that need to be filled and indented. +@c +@c The @code{@@refill} command causes @code{texinfo-format-region} and +@c @code{texinfo-format-buffer} to refill a paragraph in the Info file +@c @emph{after} all the other processing has been done. For this reason, +@c you can not use @code{@@refill} with a paragraph containing either +@c @code{@@*} or @code{@@w@{ @dots{} @}} since the refilling action will +@c override those two commands. +@c +@c The @code{texinfo-format-region} and @code{texinfo-format-buffer} +@c commands now automatically append @code{@@refill} to the end of each +@c paragraph that should be filled. They do not append @code{@@refill} to +@c the ends of paragraphs that contain @code{@@*} or @w{@code{@@w@{ @dots{}@}}} +@c and therefore do not refill or indent them. + + +@c These are no longer ``new'', and the explanations +@c are all given elsewhere anyway. So ignore the entire appendix. +@c --karl, 25apr97. +@c node New Features, Command and Variable Index, Obtaining TeX, Top +@c appendix Second Edition Features + +@c @tex +@c % Widen the space for the first column so three control-character % +@c strings fit in the first column. Switched back to default .8in % +@c value at end of chapter. \global\tableindent=1.0in +@c @end tex +@c +@c The second edition of the Texinfo manual describes more than 20 new +@c Texinfo mode commands and more than 50 previously undocumented Texinfo +@c @@-commands. This edition is more than twice the length of the first +@c edition. +@c +@c Here is a brief description of the new commands. +@c +@c @c menu +@c * New Texinfo Mode Commands:: The updating commands are especially useful. +@c * New Commands:: Many newly described @@-commands. +@c @c end menu +@c +@c @c node New Texinfo Mode Commands, New Commands, Obtaining TeX, Obtaining TeX +@c @c appendixsec New Texinfo Mode Commands +@c +@c Texinfo mode provides commands and features especially designed for +@c working with Texinfo files. More than 20 new commands have been +@c added, including commands for automatically creating and updating +@c both nodes and menus. This is a tedious task when done by hand. +@c +@c The keybindings are intended to be somewhat mnemonic. +@c +@c @c subheading Update all nodes and menus +@c +@c The @code{texinfo-master-menu} command is the primary command: +@c +@c @table @kbd +@c @item C-c C-u m +@c @itemx M-x texinfo-master-menu +@c Create or update a master menu. +@c With @kbd{C-u} as a prefix argument, +@c first create or update all nodes +@c and regular menus. +@c @end table +@c +@c @c subheading Update Pointers +@c +@c @noindent +@c Create or update `Next', `Previous', and `Up' node pointers. +@c +@c @noindent +@c @xref{Updating Nodes and Menus}. +@c +@c @table @kbd +@c @item C-c C-u C-n +@c @itemx M-x texinfo-update-node +@c Update a node. +@c +@c @item C-c C-u C-e +@c @itemx M-x texinfo-every-node-update +@c Update every node in the buffer. +@c @end table +@c +@c @c subheading Update Menus +@c +@c @noindent +@c Create or update menus. +@c +@c @noindent +@c @xref{Updating Nodes and Menus}. +@c +@c @table @kbd +@c @item C-c C-u C-m +@c @itemx M-x texinfo-make-menu +@c Make or update a menu. +@c +@c @item C-c C-u C-a +@c @itemx M-x texinfo-all-menus-update +@c Make or update all the menus in a buffer. +@c With @kbd{C-u} as a prefix argument, +@c first update all the nodes. +@c @end table +@c +@c @c subheading Insert Title as Description +@c +@c @noindent +@c Insert a node's chapter or section title in the space for the +@c description in a menu entry line; position point so you can edit the +@c insert. (This command works somewhat differently than the other +@c insertion commands, which insert only a predefined string.) +@c +@c @noindent +@c @xref{Inserting, Inserting Frequently Used Commands}. +@c +@c @table @kbd +@c @item C-c C-c C-d +@c Insert title. +@c @end table +@c +@c @c subheading Format for Info +@c +@c @noindent +@c Provide keybindings both for the Info formatting commands that are +@c written in Emacs Lisp and for @code{makeinfo} that is written in +@c C. +@c +@c @noindent +@c @xref{Info Formatting}. +@c +@c @noindent +@c Use the Emacs lisp @code{texinfo-format@dots{}} commands: +@c +@c @table @kbd +@c @item C-c C-e C-r +@c Format the region. +@c +@c @item C-c C-e C-b +@c Format the buffer. +@c @end table +@c +@c @noindent +@c Use @code{makeinfo}: +@c +@c @table @kbd +@c @item C-c C-m C-r +@c Format the region. +@c +@c @item C-c C-m C-b +@c Format the buffer. +@c +@c @item C-c C-m C-l +@c Recenter the @code{makeinfo} output buffer. +@c +@c @item C-c C-m C-k +@c Kill the @code{makeinfo} formatting job. +@c @end table +@c +@c @c subheading Typeset and Print +@c +@c @noindent +@c Typeset and print Texinfo documents from within XEmacs. +@c +@c @noindent +@c @xref{Printing}. +@c +@c @table @kbd +@c @item C-c C-t C-b +@c Run @code{texi2dvi} on the buffer. +@c +@c @item C-c C-t C-r +@c Run @TeX{} on the region. +@c +@c @item C-c C-t C-i +@c Run @code{texindex}. +@c +@c @item C-c C-t C-p +@c Print the DVI file. +@c +@c @item C-c C-t C-q +@c Show the print queue. +@c +@c @item C-c C-t C-d +@c Delete a job from the print queue. +@c +@c @item C-c C-t C-k +@c Kill the current @TeX{} formatting job. +@c +@c @item C-c C-t C-x +@c Quit a currently stopped @TeX{} formatting job. +@c +@c @item C-c C-t C-l +@c Recenter the output buffer. +@c @end table +@c +@c @c subheading Other Updating Commands +@c +@c @noindent +@c The ``other updating commands'' do not have standard keybindings because +@c they are used less frequently. +@c +@c @noindent +@c @xref{Other Updating Commands}. +@c +@c @table @kbd +@c @item M-x texinfo-insert-node-lines +@c Insert missing @code{@@node} lines using +@c section titles as node names. +@c +@c @item M-x texinfo-multiple-files-update +@c Update a multi-file document. +@c With a numeric prefix, such as @kbd{C-u 8}, +@c update @strong{every} pointer and +@c menu in @strong{all} the files and +@c then insert a master menu. +@c +@c @item M-x texinfo-indent-menu-description +@c Indent descriptions in menus. +@c +@c @item M-x texinfo-sequential-node-update +@c Insert node pointers in strict sequence. +@c @end table +@c +@c @c no.de New Commands, , New Texinfo Mode Commands, Obtaining TeX +@c @c appendix.sec New Texinfo @@-Commands +@c +@c The second edition of the Texinfo manual describes more than 50 +@c commands that were not described in the first edition. A third or so +@c of these commands existed in Texinfo but were not documented in the +@c manual; the others are new. Here is a listing, with brief +@c descriptions of them: +@c +@c @c subheading Indexing +@c +@c @noindent +@c Create your own index, and merge indices. +@c +@c @noindent +@c @xref{Indices}. +@c +@c @table @kbd +@c @item @@defindex @var{index-name} +@c Define a new index and its indexing command. +@c See also the @code{@@defcodeindex} command. +@c +@c @c written verbosely to avoid overfull hbox +@c @item @@synindex @var{from-index} @var{into-index} +@c Merge the @var{from-index} index into the @var{into-index} index. +@c See also the @code{@@syncodeindex} command. +@c @end table +@c +@c @c subheading Definitions +@c +@c @noindent +@c Describe functions, variables, macros, +@c commands, user options, special forms, and other such artifacts in a +@c uniform format. +@c +@c @noindent +@c @xref{Definition Commands}. +@c +@c @table @kbd +@c @item @@deffn @var{category} @var{name} @var{arguments}@dots{} +@c Format a description for functions, interactive +@c commands, and similar entities. +@c +@c @item @@defvr, @@defop, @dots{} +@c 15 other related commands. +@c @end table +@c +@c @c subheading Glyphs +@c +@c @noindent +@c Indicate the results of evaluation, expansion, +@c printed output, an error message, equivalence of expressions, and the +@c location of point. +@c +@c @noindent +@c @xref{Glyphs}. +@c +@c @table @kbd +@c @item @@equiv@{@} +@c @itemx @equiv{} +@c Equivalence: +@c +@c @item @@error@{@} +@c @itemx @error{} +@c Error message +@c +@c @item @@expansion@{@} +@c @itemx @expansion{} +@c Macro expansion +@c +@c @item @@point@{@} +@c @itemx @point{} +@c Position of point +@c +@c @item @@print@{@} +@c @itemx @print{} +@c Printed output +@c +@c @item @@result@{@} +@c @itemx @result{} +@c Result of an expression +@c @end table +@c +@c @c subheading Page Headings +@c +@c @noindent +@c Customize page headings. +@c +@c @noindent +@c @xref{Headings}. +@c +@c @table @kbd +@c @item @@headings @var{on-off-single-double} +@c Headings on or off, single, or double-sided. +@c +@c @item @@evenfooting [@var{left}] @@| [@var{center}] @@| [@var{right}] +@c Footings for even-numbered (left-hand) pages. +@c +@c @item @@evenheading, @@everyheading, @@oddheading, @dots{} +@c Five other related commands. +@c +@c @item @@thischapter +@c Insert name of chapter and chapter number. +@c +@c @item @@thischaptername, @@thisfile, @@thistitle, @@thispage +@c Related commands. +@c @end table +@c +@c @c subheading Formatting +@c +@c @noindent +@c Format blocks of text. +@c +@c @noindent +@c @xref{Quotations and Examples}, and@* +@c @ref{Lists and Tables, , Making Lists and Tables}. +@c +@c @table @kbd +@c @item @@cartouche +@c Draw rounded box surrounding text (no effect in Info). +@c +@c @item @@enumerate @var{optional-arg} +@c Enumerate a list with letters or numbers. +@c +@c @item @@exdent @var{line-of-text} +@c Remove indentation. +@c +@c @item @@flushleft +@c Left justify. +@c +@c @item @@flushright +@c Right justify. +@c +@c @item @@format +@c Do not narrow nor change font. +@c +@c @item @@ftable @var{formatting-command} +@c @itemx @@vtable @var{formatting-command} +@c Two-column table with indexing. +@c +@c @item @@lisp +@c For an example of Lisp code. +@c +@c @item @@smallexample +@c @itemx @@smalllisp +@c Like @@table and @@lisp, but for (originally) @@smallbook. +@c @end table +@c +@c @c subheading Conditionals +@c +@c @noindent +@c Conditionally format text. +@c +@c @noindent +@c @xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}. +@c +@c @table @kbd +@c @item @@set @var{flag} [@var{string}] +@c Set a flag. Optionally, set value +@c of @var{flag} to @var{string}. +@c +@c @item @@clear @var{flag} +@c Clear a flag. +@c +@c @item @@value@{@var{flag}@} +@c Replace with value to which @var{flag} is set. +@c +@c @item @@ifset @var{flag} +@c Format, if @var{flag} is set. +@c +@c @item @@ifclear @var{flag} +@c Ignore, if @var{flag} is set. +@c @end table +@c +@c @c subheading @@heading series for Titles +@c +@c @noindent +@c Produce unnumbered headings that do not appear in a table of contents. +@c +@c @noindent +@c @xref{Structuring}. +@c +@c @table @kbd +@c @item @@heading @var{title} +@c Unnumbered section-like heading not listed +@c in the table of contents of a printed manual. +@c +@c @item @@chapheading, @@majorheading, @@c subheading, @@subsubheading +@c Related commands. +@c @end table +@c +@c @need 1000 +@c @c subheading Font commands +@c +@c @need 1000 +@c @noindent +@c @xref{Smallcaps}, and @* +@c @ref{Fonts}. +@c +@c @table @kbd +@c @item @@r@{@var{text}@} +@c Print in roman font. +@c +@c @item @@sc@{@var{text}@} +@c Print in @sc{small caps} font. +@c @end table +@c +@c @c subheading Miscellaneous +@c +@c @noindent +@c See @ref{title subtitle author, , @code{@@title} @code{@@subtitle} and @code{@@author} Commands},@* +@c see @ref{Customized Highlighting},@* +@c see @ref{Overfull hboxes},@* +@c see @ref{Footnotes},@* +@c see @ref{dmn, , Format a Dimension},@* +@c see @ref{Raise/lower sections, , @code{@@raisesections} and @code{@@lowersections}},@* +@c see @ref{math, , @code{@@math}: Inserting Mathematical Expressions}.@* +@c see @ref{minus, , Inserting a Minus Sign},@* +@c see @ref{paragraphindent, , Paragraph Indenting},@* +@c see @ref{Cross Reference Commands},@* +@c see @ref{title subtitle author, , @code{@@title} @code{@@subtitle} and @code{@@author}}, and@* +@c see @ref{Custom Headings, , How to Make Your Own Headings}. +@c +@c @table @kbd +@c @item @@author @var{author} +@c Typeset author's name. +@c +@c @c @item @@definfoenclose @var{new-command}, @var{before}, @var{after}, +@c @c Define a highlighting command for Info. (Info only.) +@c +@c @item @@finalout +@c Produce cleaner printed output. +@c +@c @item @@footnotestyle @var{end-or-separate} +@c Specify footnote style, either @samp{end} or @samp{separate}. +@c @xref{Footnote Styles}. +@c +@c @item @@dmn@{@var{dimension}@} +@c Format a dimension. +@c +@c @item @@global@@let@var{new-cmd}=@var{existing-cmd} +@c Define a highlighting command for @TeX{}. (@TeX{} only.) +@c +@c @item @@lowersections +@c Reduce hierarchical level of sectioning commands. +@c +@c @item @@math@{@var{mathematical-expression}@} +@c Format a mathematical expression. +@c +@c @item @@minus@{@} +@c Generate a minus sign. +@c +@c @item @@paragraphindent @var{asis-or-number} +@c Specify amount of paragraph indentation. +@c +@c @item @@raisesections +@c Raise hierarchical level of sectioning commands. +@c +@c @item @@ref@{@var{node-name}, @r{[}@var{entry}@r{]}, @r{[}@var{topic-or-title}@r{]}, @r{[}@var{info-file}@r{]}, @r{[}@var{manual}@r{]}@} +@c Make a reference. In the printed manual, the +@c reference does not start with the word `see'. +@c +@c @item @@title @var{title} +@c Typeset @var{title} in the alternative +@c title page format. +@c +@c @item @@subtitle @var{subtitle} +@c Typeset @var{subtitle} in the alternative +@c title page format. +@c +@c @item @@today@{@} +@c Insert the current date. +@c @end table +@c @tex +@c % Switch width of first column of tables back to default value +@c \global\tableindent=.8in +@c @end tex + + +@node GNU Free Documentation License +@appendix GNU Free Documentation License + +@include fdl.texi + + +@node Command and Variable Index +@unnumbered Command and Variable Index + +This is an alphabetical list of all the @@-commands, assorted XEmacs Lisp +functions, and several variables. To make the list easier to use, the +commands are listed without their preceding @samp{@@}. + +@printindex fn + + +@node General Index +@unnumbered General Index + +@printindex cp + + +@bye