diff options
Diffstat (limited to 'Build/source/utils/texinfo/doc/texinfo.txi')
-rw-r--r-- | Build/source/utils/texinfo/doc/texinfo.txi | 21203 |
1 files changed, 0 insertions, 21203 deletions
diff --git a/Build/source/utils/texinfo/doc/texinfo.txi b/Build/source/utils/texinfo/doc/texinfo.txi deleted file mode 100644 index e3478242da6..00000000000 --- a/Build/source/utils/texinfo/doc/texinfo.txi +++ /dev/null @@ -1,21203 +0,0 @@ -\input texinfo.tex @c -*-texinfo-*- -@c $Id: texinfo.txi,v 1.220 2008/04/09 17:07:31 karl Exp $ -@c Ordinarily, Texinfo files have the extension .texi. But texinfo.texi -@c clashes with texinfo.tex on 8.3 filesystems, so we use texinfo.txi. - -@c Everything between the start/end of header lines will be passed by -@c Emacs's {texinfo,makeinfo}-format region commands. See the `start of -@c header' node for more info. -@c %**start of header - -@c makeinfo and texinfo.tex ignore all text before @setfilename. -@c -@c Ordinarily, the setfilename argument ends with .info. But -@c texinfo.info-13 is too long for 14-character filesystems. -@setfilename texinfo - -@c Automake automatically updates version.texi to @set VERSION and -@c @set UPDATED to appropriate values. -@include version.texi -@settitle GNU Texinfo @value{VERSION} - -@c Define a new index for 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. - -Copyright @copyright{} 1988, 1990, 1991, 1992, 1993, 1995, 1996, 1997, -1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 -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.2 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 are free to copy and modify -this GNU Manual. Buying copies from GNU Press supports the FSF 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. -* 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. -* makeinfo: (texinfo)Invoking makeinfo. Translate Texinfo source. -@end direntry - -@c Before release, run C-u C-c C-u C-a (texinfo-all-menus-update with a -@c prefix arg). This updates the node pointers, which texinfmt.el needs. - -@c Set smallbook if printing in smallbook format so the example of the -@c smallbook font is actually written using smallbook; in bigbook, a kludge -@c is used for TeX output. Do this through the -t option to texi2dvi, -@c 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 - -@c Currently undocumented command, 5 December 1993: -@c nwnode (Same as node, but no warnings; for `makeinfo'.) - - -@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. - -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 GNU Emacs Texinfo mode. -* Beginning a File:: What is at the beginning of a Texinfo file? -* Ending a File:: What is at the end of a Texinfo file? -* 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. -* Conditionals:: Specifying text for only some output cases. -* Internationalization:: Supporting languages other than English. -* Defining New Texinfo Commands:: User-defined macros and aliases. -* Hardcopy:: Output for paper, with @TeX{}. -* Creating and Installing Info Files:: Details on Info output. -* Generating HTML:: Details on HTML output. - -* Command List:: All the Texinfo @@-commands. -* Tips:: Hints on how to write a Texinfo document. -* Sample Texinfo Files:: Complete examples, including full texts. -* Include Files:: How to incorporate other Texinfo files. -* Headings:: How to write page headings and footings. -* Catching Mistakes:: How to find formatting mistakes. -* 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. -* Info Files:: What is an Info file? -* Printed Books:: Characteristics of a printed book or manual. -* Formatting Commands:: @@-commands are used for formatting. -* Conventions:: General rules for writing a Texinfo file. -* Comments:: Writing comments and ignored text in general. -* Minimum:: What a Texinfo file must have. -* Six Parts:: Usually, a Texinfo file has six parts. -* Short Sample:: A short sample Texinfo file. -* History:: Acknowledgements, contributors and genesis. - -Using Texinfo Mode - -* Texinfo Mode Overview:: How Texinfo mode can help you. -* Emacs Editing:: Texinfo mode adds to GNU Emacs' general - purpose editing features. -* Inserting:: How to insert frequently used @@-commands. -* Showing the Structure:: How to show the structure of a file. -* Updating Nodes and Menus:: How to update or create new nodes and menus. -* Info Formatting:: How to format for Info. -* Printing:: How to format and print part or all of a file. -* Texinfo Mode Summary:: Summary of all the Texinfo mode commands. - -Updating Nodes and Menus - -* Updating Commands:: Five major updating commands. -* Updating Requirements:: How to structure a Texinfo file for - using the updating command. -* Other Updating Commands:: How to indent descriptions, insert - missing nodes lines, and update - nodes in sequence. - -Beginning a Texinfo File - -* Sample Beginning:: A sample beginning for a Texinfo file. -* Texinfo File Header:: The first lines. -* Document Permissions:: Ensuring your manual is free. -* Titlepage & Copyright Page:: Creating the title and copyright pages. -* Contents:: How to create a table of contents. -* The Top Node:: Creating the `Top' node and master menu. -* Global Document Commands:: Affecting formatting throughout. -* Software Copying Permissions:: Ensure that you and others continue to - have the right to use and share software. - -Texinfo File Header - -* First Line:: The first line of a Texinfo file. -* Start of Header:: Formatting a region requires this. -* setfilename:: Tell Info the name of the Info file. -* settitle:: Create a title for the printed work. -* End of Header:: Formatting a region requires this. - -Document Permissions - -* copying:: Declare the document's copying permissions. -* insertcopying:: Where to insert the permissions. - -Title and Copyright Pages - -* titlepage:: Create a title for the printed document. -* titlefont center sp:: The @code{@@titlefont}, @code{@@center}, - and @code{@@sp} commands. -* title subtitle author:: The @code{@@title}, @code{@@subtitle}, - and @code{@@author} commands. -* Copyright:: How to write the copyright notice and - include copying permissions. -* end titlepage:: Turn on page headings after the title and - copyright pages. -* headings on off:: An option for turning headings on and off - and double or single sided printing. - -The `Top' Node and Master Menu - -* Top Node Example:: -* Master Menu Parts:: - -Global Document Commands - -* documentdescription:: Document summary for the HTML output. -* setchapternewpage:: Start chapters on right-hand pages. -* paragraphindent:: Specify paragraph indentation. -* firstparagraphindent:: Suppress indentation of the first paragraph. -* 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. -* makeinfo top:: The @code{@@top} command, part of the `Top' node. -* chapter:: -* unnumbered & appendix:: -* majorheading & chapheading:: -* section:: -* unnumberedsec appendixsec heading:: -* subsection:: -* unnumberedsubsec appendixsubsec subheading:: -* subsubsection:: Commands for the lowest level sections. -* Raise/lower sections:: How to change commands' hierarchical level. - -Nodes - -* Two Paths:: Different commands to structure - Info output and printed output. -* Node Menu Illustration:: A diagram, and sample nodes and menus. -* node:: Creating nodes, in detail. -* makeinfo Pointer Creation:: Letting makeinfo determine node pointers. -* anchor:: Defining arbitrary cross-reference targets. - -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 Tips:: Keep names short. -* Node Line Requirements:: Keep names unique, without @@-commands. -* First Node:: How to write a `Top' node. -* makeinfo top command:: How to use the @code{@@top} command. - -Menus - -* Menu Location:: Menus go at the ends of short 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. -* xref:: Begin a reference with `See' @dots{} -* Top Node Naming:: How to refer to the beginning of another file. -* ref:: A reference for the last part of a sentence. -* pxref:: How to write a parenthetical cross reference. -* inforef:: How to refer to an Info-only file. -* uref:: How to refer to a uniform resource locator. - -@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 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. -* code:: Indicating program code. -* kbd:: Showing keyboard input. -* key:: Specifying keys. -* samp:: A literal sequence of characters. -* verb:: A verbatim sequence of characters. -* var:: Indicating metasyntactic variables. -* env:: Indicating environment variables. -* file:: Indicating file names. -* command:: Indicating command names. -* option:: Indicating option names. -* dfn:: Specifying definitions. -* cite:: Referring to books not in the Info system. -* abbr:: Indicating abbreviations. -* acronym:: Indicating acronyms. -* indicateurl:: Indicating a World Wide Web reference. -* email:: Indicating an electronic mail address. - -Emphasizing Text - -* emph & strong:: How to emphasize text in Texinfo. -* Smallcaps:: How to use the small caps font. -* Fonts:: Various font commands for printed output. - -Quotations and Examples - -* Block Enclosing Commands:: Different constructs for different purposes. -* quotation:: Writing a quotation. -* example:: Writing an example in a fixed-width font. -* verbatim:: Writing a verbatim example. -* verbatiminclude:: Including a file verbatim. -* lisp:: Illustrating Lisp code. -* small:: Examples in a smaller font. -* display:: Writing an example in the current font. -* format:: Writing an example without narrowed margins. -* exdent:: Undo indentation on a line. -* flushleft & flushright:: Pushing text flush left or flush right. -* noindent:: Preventing paragraph indentation. -* indent:: Forcing paragraph indentation. -* cartouche:: Drawing rounded rectangles around examples. - -Lists and Tables - -* Introducing Lists:: Texinfo formats lists for you. -* itemize:: How to construct a simple list. -* 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 - -* table:: How to construct a two-column table. -* ftable vtable:: Automatic indexing for two-column tables. -* 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 - -* float:: Producing floating material. -* caption shortcaption:: Specifying descriptions for floats. -* 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 - -* syncodeindex:: How to merge two indices, using @code{@@code} - font for the merged-from index. -* synindex:: How to merge two indices, using the - default font of the merged-to index. - -Special Insertions - -* Atsign Braces Comma:: Inserting @@ and @{@} and ,. -* Inserting Quote Characters:: Inserting left and right quotes, in code. -* Inserting Space:: How to insert the right amount of space - within a sentence. -* Inserting Accents:: How to insert accents and special characters. -* Inserting Quotation Marks:: How to insert quotation marks. -* Dots Bullets:: How to insert dots and bullets. -* TeX and copyright:: How to insert the @TeX{} logo - and the copyright symbol. -* euro:: How to insert the Euro currency symbol. -* pounds:: How to insert the pounds currency symbol. -* textdegree:: How to insert the degrees symbol. -* minus:: How to insert a minus sign. -* geq leq:: How to insert greater/less-than-or-equal signs. -* math:: How to format a mathematical expression. -* Click Sequences:: Inserting GUI usage sequences. -* Glyphs:: How to indicate results of evaluation, - expansion of macros, errors, etc. - -Inserting @@ and @{@} and @comma{} - -* Inserting an Atsign:: -* Inserting Braces:: -* Inserting a Comma:: - -Inserting Space - -* Not Ending a Sentence:: Sometimes a . doesn't end a sentence. -* Ending a Sentence:: Sometimes it does. -* Multiple Spaces:: Inserting multiple spaces. -* frenchspacing:: Specifying end-of-sentence spacing. -* dmn:: How to format a dimension. - -Inserting Ellipsis and Bullets - -* dots:: How to insert dots @dots{} -* bullet:: How to insert a bullet. - -Inserting @TeX{} and Legal Symbols: @copyright{}, @registeredsymbol{} - -* tex:: The @TeX{} logos. -* copyright symbol:: The copyright symbol (c in a circle). -* registered symbol:: The registered symbol (R in a circle). - -Glyphs for Examples - -* Glyphs Summary:: -* result:: How to show the result of expression. -* expansion:: How to indicate an expansion. -* Print Glyph:: How to indicate printed output. -* Error Glyph:: How to indicate an error message. -* Equivalence:: How to indicate equivalence. -* Point Glyph:: How to indicate the location of point. - -Glyphs Summary - -* result:: -* expansion:: -* Print Glyph:: -* Error Glyph:: -* Equivalence:: -* Point Glyph:: - -Forcing and Preventing Breaks - -* Break Commands:: Summary of break-related commands. -* Line Breaks:: Forcing line breaks. -* - and hyphenation:: Helping @TeX{} with hyphenation points. -* allowcodebreaks:: Controlling line breaks within @@code text. -* w:: Preventing unwanted line breaks in text. -* tie:: Inserting an unbreakable but varying space. -* sp:: Inserting blank lines. -* page:: Forcing the start of a new page. -* group:: Preventing unwanted page breaks. -* 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. -* 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. - -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. -* set clear value:: Variable tests and substitutions. -* Conditional Nesting:: Using conditionals inside conditionals. - -@code{@@set}, @code{@@clear}, and @code{@@value} - -* set value:: Expand a flag variable to a string. -* ifset ifclear:: Format a region if a flag is set. -* value Example:: An easy way to update edition information. - -Internationalization - -* documentlanguage:: Declaring the current language. -* documentencoding:: Declaring the input encoding. - -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. -* alias:: Command aliases. -* definfoenclose:: Customized highlighting. - -Formatting and Printing Hardcopy - -* Use TeX:: Use @TeX{} to format for hardcopy. -* Format with tex/texindex:: How to format with explicit shell commands. -* Format with texi2dvi:: A simpler way to format. -* Print with lpr:: How to print. -* Within Emacs:: How to format and print from an Emacs shell. -* Texinfo Mode Printing:: How to format and print in Texinfo mode. -* Compile-Command:: How to print using Emacs's compile command. -* Requirements Summary:: @TeX{} formatting requirements summary. -* Preparing for TeX:: What to do before you use @TeX{}. -* Overfull hboxes:: What are and what to do with overfull hboxes. -* smallbook:: How to print small format books and manuals. -* A4 Paper:: How to print on A4 or A5 paper. -* pagesizes:: How to print with customized page sizes. -* Cropmarks and Magnification:: How to print marks to indicate the size - of pages and how to print scaled up output. -* PDF Output:: Portable Document Format output. -* Obtaining TeX:: How to Obtain @TeX{}. - -Creating and Installing Info Files - -* Creating an Info File:: -* Installing an Info File:: - -Creating an Info File - -* makeinfo advantages:: @code{makeinfo} provides better error checking. -* Invoking makeinfo:: How to run @code{makeinfo} from a shell. -* makeinfo options:: Specify fill-column and other options. -* Pointer Validation:: How to check that pointers point somewhere. -* makeinfo in Emacs:: How to run @code{makeinfo} from Emacs. -* texinfo-format commands:: Two Info formatting commands written - in Emacs Lisp are an alternative - to @code{makeinfo}. -* Batch Formatting:: How to format for Info in Emacs Batch mode. -* Tag and Split Files:: How tagged and split files help Info - to run better. - -Installing an Info File - -* Directory File:: The top level menu for all Info files. -* New Info File:: Listing a new Info file. -* Other Info Directories:: How to specify Info files that are - located in other directories. -* Installing Dir Entries:: How to specify what menu entry to add - to the Info directory. -* Invoking 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. - -@@-Command List - -* Command Syntax:: General syntax for varieties of @@-commands. - -Sample Texinfo Files - -* Short Sample Texinfo File:: -* GNU Sample Texts:: -* Verbatim Copying License:: -* All-permissive Copying License:: - -GNU Free Documentation License - -Include Files - -* Using Include Files:: How to use the @code{@@include} command. -* 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. - -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. - -Formatting Mistakes - -* 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 texinfo-show-structure:: How to use @code{texinfo-show-structure}. -* Using occur:: How to list all lines containing a pattern. -* Running Info-Validate:: How to find badly referenced nodes. - -Finding Badly Referenced Nodes - -* Using 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 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 - -The programs currently being distributed that relate to Texinfo include -@code{makeinfo}, @code{info}, @code{texindex}, and @file{texinfo.tex}. -These programs are @dfn{free}; this means that everyone is free to use -them and free to redistribute them on a free basis. The Texinfo-related -programs are not in the public domain; they are copyrighted and there -are restrictions on their 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 these programs 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 specifically 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}@footnote{The first syllable of ``Texinfo'' is pronounced -like ``speck'', not ``hex''. This odd pronunciation is derived from, -but is not the same as, the pronunciation of @TeX{}. In the word -@TeX{}, the @samp{X} is actually the Greek letter ``chi'' rather than -the English letter ``ex''. Pronounce @TeX{} as if the @samp{X} were the -last sound in the name `Bach'; but pronounce Texinfo as if the @samp{x} -were a `k'. Spell ``Texinfo'' with a capital ``T'' and the other -letters in lower case.} is a documentation system that uses a single -source file to produce both online information and printed output. This -means that instead of writing two different documents, one for the -online information and the other for a printed work, you need write only -one document. Therefore, when the work is revised, you need revise only -that one document. - -@menu -* Reporting Bugs:: Submitting effective bug reports. -* Using Texinfo:: Create printed or online output. -* Output Formats:: Overview of the supported output formats. -* 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, anything. Please email them to -@email{bug-texinfo@@gnu.org}. You can get the latest version of Texinfo -from @uref{ftp://ftp.gnu.org/gnu/texinfo/} and its mirrors worldwide. - -@cindex Checklist for bug reports -For bug reports, please include enough information for the maintainers -to reproduce the problem. Generally speaking, that means: - -@itemize @bullet -@item the version number of Texinfo and the program(s) or manual(s) involved. -@item hardware and operating system names and versions. -@item the contents of any input files necessary to reproduce the bug. -@item a description of the problem and samples of any erroneous output. -@item any unusual options you gave to @command{configure}. -@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. - -@cindex Patches, contributing -Patches are most welcome; if possible, please make them with -@samp{@w{diff -c}} (@pxref{Top,, Overview, diff, Comparing and Merging -Files}) and include @file{ChangeLog} entries (@pxref{Change Log,,, -emacs, The GNU Emacs 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) 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, -or an XML file. See the next section (@pxref{Output Formats}) for -details and the exact 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 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 typesetting and formatting programs what to do. You can -edit a Texinfo file with any text editor, but it is especially -convenient to use GNU Emacs since that editor has a special mode, -called Texinfo mode, that provides various Texinfo-related features. -(@xref{Texinfo Mode}.) - -You can use Texinfo to create both online help and printed manuals; -moreover, Texinfo is freely redistributable. For these reasons, Texinfo -is the official documentation format of the GNU project. More -information is available at the @uref{http://www.gnu.org/doc/, GNU -documentation web page}. - - -@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 -(Generated via @command{makeinfo}.) This format is essentially 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. See the -next section (@pxref{Info Files}) for more details on this format. -The Emacs Info subsystem (@pxref{Top,,Getting Started,info, Info}), -and the standalone @command{info} program (@pxref{Top -,, Info Standalone, info-stnd, GNU Info}), among others, can read these -files. @xref{Creating and Installing Info Files}. - -@item Plain text -@cindex Plain text output -(Generated via @command{makeinfo --no-headers}.) This is almost the -same as Info output, except the navigational control characters are -omitted. Also, standard output is used by default. - -@item HTML -@cindex HTML output -@cindex W3 consortium -@cindex Mozilla -@cindex Lynx -@cindex Emacs-W3 -(Generated via @command{makeinfo --html}.) This is the Hyper Text -Markup Language that has become the most commonly used language for -writing documents on the World Wide Web. Web browsers, such as -Mozilla, Lynx, and Emacs-W3, can render this language online. There -are many versions of HTML; @command{makeinfo} tries to use a subset -of the language that can be interpreted by any common browser. For -details of the HTML language and much related information, see -@uref{http://www.w3.org/MarkUp/}. @xref{Generating HTML}. - -@item DVI -@cindex DVI output -@pindex dvips -@pindex xdvi -(Generated via @command{texi2dvi}.) This DeVice Independent binary -format is output by the @TeX{} typesetting program -(@uref{http://tug.org}). This is then read by a DVI `driver', which -writes the actual device-specific commands that can be viewed or -printed, notably Dvips for translation to PostScript (@pxref{Invoking -Dvips,,, 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{} and @LaTeX{}. -For more information on @TeX{} in general, please see the book -@cite{@TeX{} for the Impatient}, available from -@uref{http://savannah.gnu.org/projects/teximpatient}. - -@item PDF -@cindex PDF output -@cindex Beebe, Nelson -@pindex pdftex -(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://tug.org/TUGboat/Articles/tb22-3/tb72beebe-pdf.pdf} has -some background. Texinfo uses the @command{pdftex} program, a variant -of @TeX{}, to output PDF; see -@uref{http://tug.org/applications/pdftex}. @xref{PDF Output}. - -@item XML -@cindex XML output -@cindex DTD, for Texinfo XML -@pindex texinfo.dtd -(Generated via @command{makeinfo --xml}.) XML is a generic syntax -specification usable for any sort of content (see, for example, -@uref{http://www.w3.org/XML/}). The @command{makeinfo} XML output, -unlike all the formats above, interprets very little of the Texinfo -source. Rather, it merely translates the Texinfo markup commands into -XML syntax, for processing by further XML tools. The particular -syntax output is defined in the file @file{texinfo.dtd} included in -the Texinfo source distribution. - -@item Docbook -@cindex Docbook output -(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 -outlines, to Texinfo. See @uref{http://www.docbook.org}. If you want -to convert from Docbook @emph{to} Texinfo, please see -@uref{http://docbook2X.sourceforge.net}. - -@end table - -@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 very -strict conventional format, generating 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 just write the man page -directly. - -@pindex help2man -@cindex O'Dea, Brendan -Man pages still have their place, and if you wish to support them, 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, this is currently used to generate man pages for the programs in -the Texinfo distribution. It is GNU software written by Brendan -O'Dea, available from @uref{ftp://ftp.gnu.org/gnu/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. But please do not write a separate translator texi2foo for -your favorite format foo! That is the hard way to do the job, and makes -extra work in subsequent maintenance, since the Texinfo language is -continually being enhanced and updated. Instead, the best approach is -modify @code{makeinfo} to generate the new format. - - -@node Info Files -@section Info Files -@cindex Info files - -An Info file is a Texinfo file formatted so that the Info documentation -reading program can operate on it. (@code{makeinfo} -and @code{texinfo-format-buffer} are two commands that convert a Texinfo file -into an Info file.) - -Info files are divided into pieces called @dfn{nodes}, each of which -contains the discussion of one topic. Each node has a name, and -contains both text for the user to read and pointers to other nodes, -which are identified by their names. The Info program displays one node -at a time, and provides commands with which the user can move to other -related nodes. - -@xref{Top,,, info, GNU Info}, for more information about using Info. - -Each node of an Info file may have any number of child nodes that -describe subtopics of the node's topic. The names of child -nodes are listed in a @dfn{menu} within the parent node; this -allows you to use certain Info commands to move to one of the child -nodes. Generally, an Info file is organized like a book. If a node -is at the logical level of a chapter, its child nodes are at the level -of sections; likewise, the child nodes of sections are at the level -of subsections. - -All the children of any one parent are linked together in a -bidirectional chain of `Next' and `Previous' pointers. The `Next' -pointer provides a link to the next section, and the `Previous' pointer -provides a link to the previous section. This means that all the nodes -that are at the level of sections within a chapter are linked together. -Normally the order in this chain is the same as the order of the -children in the parent's menu. 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.@footnote{In some documents, the first child has no `Previous' -pointer. Occasionally, the last child has the node name of the next -following higher level node as its `Next' pointer.} - -The book-like structuring of an Info file into nodes that correspond -to chapters, sections, and the like is a matter of convention, not a -requirement. The `Up', `Previous', and `Next' pointers of a node can -point to any other nodes, and a menu can contain any other nodes. -Thus, the node structure can be any directed graph. But it is usually -more comprehensible to follow a structure that corresponds to the -structure of chapters and sections in a printed book or report.@refill - -In addition to menus and to `Next', `Previous', and `Up' pointers, Info -provides pointers of another kind, called references, that can be -sprinkled throughout the text. This is usually the best way to -represent links that do not fit a hierarchical structure.@refill - -Usually, you will design a document so that its nodes match the -structure of chapters and sections in the printed output. But -occasionally there are times when this is not right for the material -being discussed. Therefore, Texinfo uses separate commands to specify -the node structure for the Info file and the section structure for the -printed output.@refill - -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 *}. (@inforef{Advanced, -Advanced Info commands, info}.)@refill - -@c !!! dir file may be located in one of many places: -@c /usr/local/emacs/info mentioned in info.c DEFAULT_INFOPATH -@c /usr/local/lib/emacs/info mentioned in info.c DEFAULT_INFOPATH -@c /usr/gnu/info mentioned in info.c DEFAULT_INFOPATH -@c /usr/local/info -@c /usr/local/lib/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.@refill - -@cindex URI syntax for Info -If you wish to refer to an Info file in a URI, you can use the -(unofficial) syntax exemplified in the following. This works with -Emacs/W3, for example: -@example -info:///usr/info/emacs#Dissociated%20Press -info:emacs#Dissociated%20Press -info://localhost/usr/info/emacs#Dissociated%20Press -@end example - -The @command{info} program itself does not follow 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 powerful, sophisticated typesetting -program written by Donald Knuth.@footnote{You can also use the -@pindex texi2roff@r{, unsupported software} -@uref{ftp://tug.org/texi2roff.tar.gz, @code{texi2roff}} program if you -do not have @TeX{}; since Texinfo is designed for use with @TeX{}, -@code{texi2roff} is not described here. @code{texi2roff} is not part of -the standard GNU distribution and is not maintained or up-to-date with -all the Texinfo features described in this manual.} - -A Texinfo-based book is similar to any other typeset, printed work: it -can have a title page, copyright page, table of contents, and preface, -as well as chapters, numbered or unnumbered sections and subsections, -page headers, cross references, footnotes, and indices.@refill - -You can use Texinfo to write a book without ever having the intention -of converting it into online information. You can use Texinfo for -writing a printed novel, and even to write a printed memo, although -this latter application is not recommended since electronic mail is so -much easier.@refill - -@TeX{} is a general purpose typesetting program. Texinfo provides a -file @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{smallbook, , -Printing ``Small'' Books}. Also, see @ref{A4 Paper, ,Printing on A4 -Paper}.) - -By changing the parameters in @file{texinfo.tex}, you can change the -size of the printed document. In addition, you can change the style in -which the printed document is formatted; for example, you can change the -sizes and fonts used, the amount of indentation for each paragraph, the -degree to which words are hyphenated, and the like. By changing the -specifications, you can make a book look dignified, old and serious, or -light-hearted, young and cheery. - -@TeX{} is freely distributable. It is written in a superset of Pascal -called WEB and can be compiled either in Pascal or (by using a -conversion program that comes with the @TeX{} distribution) in C. -(@xref{TeX Mode, ,@TeX{} Mode, emacs, The GNU Emacs Manual}, for information -about @TeX{}.)@refill - -@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. - -To get a copy of @TeX{}, see -@ref{Obtaining TeX, , How to Obtain @TeX{}}. - - -@node Formatting Commands -@section @@-commands -@cindex @@-commands -@cindex Formatting commands - -In a Texinfo file, the commands that tell @TeX{} how to typeset the -printed manual and tell @code{makeinfo} and -@code{texinfo-format-buffer} how to create an Info file are preceded -by @samp{@@}; 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.@refill - -@quotation Note -Almost all @@ command names are entirely lower case. -@end quotation - -The Texinfo @@-commands are a strictly limited set of constructs. The -strict limits make it possible for Texinfo files to be understood both -by @TeX{} and by the code that converts them into Info files. You can -display Info files on any terminal that displays alphabetic and -numeric characters. Similarly, you can print the output generated by -@TeX{} on a wide variety of printers.@refill - -Depending on what they do or what arguments@footnote{The word -@dfn{argument} comes from the way it is used in mathematics and does not -refer to a 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 -Write a command such as @code{@@quotation} at the beginning of a line as -the only text on the line. (@code{@@quotation} begins an indented -environment.) - -@item -Write a command such as @code{@@chapter} at the beginning of a line -followed by the command's arguments, in this case the chapter title, on -the rest of the line. (@code{@@chapter} creates chapter titles.)@refill - -@item -Write a command such as @code{@@dots@{@}} wherever you wish but usually -within a sentence. (@code{@@dots@{@}} creates an ellipsis @dots{})@refill - -@item -Write a command such as @code{@@code@{@var{sample-code}@}} wherever you -wish (but usually within a sentence) with its argument, -@var{sample-code} in this example, between the braces. (@code{@@code} -marks text as being code.)@refill - -@item -Write a command such as @code{@@example} on a line of its own; write the -body-text on following lines; and write the matching @code{@@end} -command, @code{@@end example} in this case, on a line of its own -after the body-text. (@code{@@example} @dots{} @code{@@end example} -indents and typesets body-text as an example.) It's usually ok to -indent environment commands like this, but in complicated and -hard-to-define circumstances the extra spaces cause extra space to -appear in the output, so beware. -@end itemize - -@noindent -@cindex 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 starts a line of its own. The -non-alphabetic commands, such as @code{@@:}, are exceptions to the rule; -they do not need braces.@refill - -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 -@cindex Paragraph separator -@cindex Blank lines, as paragraph separator -@cindex Newlines, as blank lines -Separate paragraphs with one or more blank lines. Currently Texinfo -only recognizes newline characters as end of line, not the CRLF -sequence used on some systems; so a @dfn{blank line} means exactly two -consecutive newlines. Sometimes blank lines are useful or convenient -in other cases as well; you can use the @code{@@noindent} to inhibit -paragraph indentation if required (@pxref{noindent,,@code{@@noindent}}). - -@item -Texinfo supports the usual quotation marks used in English, and -quotation marks used in other languages, please 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 Tabs; don't use! -@strong{Caution:} Last, do not use tab characters in a Texinfo file -(except 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 appear differently in the -output. - -@noindent -To avoid this problem, Texinfo mode in GNU Emacs inserts -multiple spaces when you press the @key{TAB} key. Also, you can run -@code{untabify} in Emacs to convert tabs in a region to multiple -spaces, or use the @code{unexpand} command from the shell. - -@end itemize - - -@node Comments -@section Comments - -@cindex Comments -@findex comment -@findex c @r{(comment)} - -You can write comments in a Texinfo file that will not appear in -either the Info file or the printed manual by using the -@code{@@comment} command (which may be abbreviated to @code{@@c}). -Such comments are for the person who revises the Texinfo file. All the -text on a line that follows either @code{@@comment} or @code{@@c} is a -comment; the rest of the line does not appear in either the Info file -or the printed manual. - -Often, you can write the @code{@@comment} or @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} in a line beginning with such -a command. - -@cindex Ignored text -@cindex Unprocessed text -@findex ignore -You can write long stretches of text that will not appear in either -the Info file or the printed manual by using 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. - -Text enclosed by @code{@@ignore} or by failing @code{@@ifset} or -@code{@@ifclear} conditions is ignored in the sense that it will not -contribute to the formatted output. However, @TeX{} and makeinfo must -still parse the ignored text, in order to understand when to @emph{stop} -ignoring text from the source file; that means that you may still get -error messages if you have invalid Texinfo commands within ignored text. - - -@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 printed manual and an Info file, a Texinfo -file @strong{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 -@strong{must} end a Texinfo file 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 document description for -the @samp{<head>} in HTML format. 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 - -Typically, you will not use quite such a spare format, but will 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 Emacs to switch into -Texinfo mode when you edit the file. - -The @code{@@c} lines which surround the @code{@@setfilename} and -@code{@@settitle} lines are optional, but you need them in order to -run @TeX{} or Info on just part of the file. (@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@{@} 2005 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 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 Zuhn, David D. -@cindex Weisshaus, Melissa -@cindex Zaretskii, Eli -@cindex Schwab, Andreas -@cindex Weinberg, Zack -Our thanks go out to all who helped improve this work, particularly 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}. Special thanks go 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 Scribe -@cindex Reid, Brian -@cindex History of Texinfo -@cindex Texinfo history -A bit of history: in the 1970's at CMU, Brian Reid developed a program -and format named Scribe to mark up documents for printing. It used the -@code{@@} character to introduce commands, as Texinfo does. 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. - - -@node Texinfo Mode -@chapter Using Texinfo Mode -@cindex Texinfo mode -@cindex Mode, using Texinfo -@cindex GNU Emacs -@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, GNU Emacs -comes with a special mode, called Texinfo mode, that provides Emacs -commands and tools to help ease your work. - -This chapter describes features of GNU Emacs' Texinfo mode but not any -features of the Texinfo formatting language. So if you are reading this -manual straight through from the beginning, you may want to skim through -this chapter briefly and come back to it after reading succeeding -chapters which describe the Texinfo formatting language in detail. - -@menu -* Texinfo Mode Overview:: How Texinfo mode can help you. -* Emacs Editing:: Texinfo mode adds to GNU Emacs' general - purpose editing features. -* Inserting:: How to insert frequently used @@-commands. -* Showing the Structure:: How to show the structure of a file. -* Updating Nodes and Menus:: How to update or create new nodes and menus. -* Info Formatting:: How to format for Info. -* Printing:: How to format and print part or all of a file. -* Texinfo Mode Summary:: Summary of all the Texinfo mode commands. -@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. @refill - -@item -Automatically create @code{@@node} lines. - -@item -Show the structure of a Texinfo source file.@refill - -@item -Automatically create or update the `Next', -`Previous', and `Up' pointers of a node. - -@item -Automatically create or update menus.@refill - -@item -Automatically create a master menu.@refill - -@item -Format a part or all of a file for Info.@refill - -@item -Typeset and print part or all of a file.@refill -@end itemize - -Perhaps the two most helpful features are those for inserting frequently -used @@-commands and for creating node pointers and menus.@refill - -@node Emacs Editing -@section The Usual GNU Emacs Editing Commands - -In most cases, the usual Text mode commands work the same in Texinfo -mode as they do in Text mode. Texinfo mode adds new editing commands -and tools to GNU Emacs' general purpose editing features. The major -difference concerns filling. In Texinfo mode, the paragraph -separation variable and syntax table are redefined so that Texinfo -commands that should be on lines of their own are not inadvertently -included in paragraphs. Thus, the @kbd{M-q} (@code{fill-paragraph}) -command will refill a paragraph but not mix an indexing command on a -line adjacent to it into the paragraph.@refill - -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, , ,emacs, -The GNU Emacs Manual}, for details about the page commands.)@refill - -You may name a Texinfo file however you wish, but the convention is to -end a Texinfo file name with one of the extensions -@file{.texinfo}, @file{.texi}, @file{.txi}, or @file{.tex}. A longer -extension is preferred, since it is explicit, but a shorter extension -may be necessary for operating systems that limit the length of file -names. GNU Emacs automatically enters Texinfo mode when you visit a -file with a @file{.texinfo}, @file{.texi} or @file{.txi} -extension. Also, Emacs switches to Texinfo mode -when you visit a -file that has @samp{-*-texinfo-*-} in its first line. If ever you are -in another mode and wish to switch to Texinfo mode, type @code{M-x -texinfo-mode}.@refill - -Like all other Emacs features, you can customize or enhance Texinfo -mode as you wish. In particular, the keybindings are very easy to -change. The keybindings described here are the default or standard -ones.@refill - -@node Inserting -@comment node-name, next, previous, up -@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.@refill - -The insert commands are invoked by typing @kbd{C-c} twice and then the -first letter of the @@-command:@refill - -@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.@refill - -@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.@refill - -@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.)@refill - -@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.@refill - -@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.@refill - -@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}.@refill - -@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.@refill - -@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.@refill - -@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}.@refill - -@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.@refill - -@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.@refill - -@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.@refill - -@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}.)@refill -@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 Emacs 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, Emacs inserts -the @@-command string and positions the cursor between the braces. This -feature works only for those @@-commands that operate on a word or words -within one line, such as @code{@@kbd} and @code{@@var}.@refill - -This set of insert commands was created after analyzing the frequency -with which different @@-commands are used in the @cite{GNU Emacs -Manual} and the @cite{GDB Manual}. If you wish to add your own insert -commands, you can bind a keyboard macro to a key, use abbreviations, -or extend the code in @file{texinfo.el}.@refill - -@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}.)@refill - -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.@refill - -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.@refill - -@node Showing the Structure -@comment node-name, next, previous, up -@section Showing the Section Structure of a File -@cindex Showing the section structure of a file -@cindex Section structure of a file, showing it -@cindex Structure of a file, showing it -@cindex Outline of file structure, showing it -@cindex Contents-like outline of file structure -@cindex File section structure, showing it -@cindex Texinfo file section structure, showing it - -You can show the section structure of a Texinfo file by using the -@kbd{C-c C-s} command (@code{texinfo-show-structure}). This command -shows the section structure of a Texinfo file by listing 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.@refill - -@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.@refill - -@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.@refill -@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, , , emacs, The GNU Emacs Manual}, for more -information about the narrowing commands.)@refill - -@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, , , emacs, The GNU Emacs Manual}, for more information -about the page commands.@refill - -@node Updating Nodes and Menus -@comment node-name, next, previous, up -@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 the updating commands, you need to write menus and -node pointers by hand, which is a tedious task.@refill - -@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:@refill - -@itemize @bullet -@item -insert or update the `Next', `Previous', and `Up' pointers of a -node,@refill - -@item -insert or update the menu for a section, and@refill - -@item -create a master menu for a Texinfo source file.@refill -@end itemize - -You can also use the commands to update all the nodes and menus in a -region or in a whole Texinfo file.@refill - -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.@refill - -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.@refill - -The @code{texinfo-master-menu} command is the primary command:@refill - -@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).@refill - -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.)@refill - -For @code{texinfo-master-menu} to work, the Texinfo file must have a -`Top' node and at least one subsequent node.@refill - -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.@refill -@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.@refill - -@need 1000 -The commands are:@refill - -@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).@refill - -@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.@refill - -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.@refill - -@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.@refill - -@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.@refill - -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.)@refill - -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.@refill -@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,,, -emacs, The GNU Emacs Manual}) or with the @kbd{M-x set-variable} -command (@pxref{Examining, , Examining and Setting Variables, emacs, -The GNU Emacs Manual}). - -Also, the @code{texinfo-indent-menu-description} command may be used to -indent existing menu descriptions to a specified column. Finally, if -you wish, you can use the @code{texinfo-insert-node-lines} command to -insert missing @code{@@node} lines into a file. (@xref{Other Updating -Commands}, for more information.)@refill - -@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.@refill - -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}.@refill - -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.@refill - -Incidentally, the @code{makeinfo} command will create an Info file for a -hierarchically organized Texinfo file that lacks `Next', `Previous' and -`Up' pointers. Thus, if you can be sure that your Texinfo file will be -formatted with @code{makeinfo}, you have no need for the update node -commands. (@xref{Creating an Info File}, for more information about -@code{makeinfo}.) However, both @code{makeinfo} and the -@code{texinfo-format-@dots{}} commands require that you insert menus in -the file. - - -@node Other Updating Commands -@subsection Other Updating Commands - -In addition to the five major updating commands, Texinfo mode -possesses several less frequently used updating commands:@refill - -@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.@refill - -With an argument (@kbd{C-u} as prefix argument, if interactive), the -@code{texinfo-insert-node-lines} command 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.@refill - -For example, the following marks a whole buffer as a region and inserts -@code{@@node} lines and titles throughout:@refill - -@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{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.@refill - -@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.@refill -@end table - -@node Info Formatting -@comment node-name, next, previous, up -@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.@refill - -You can use either the @code{texinfo-format-region} or the -@code{makeinfo-region} command to format a region:@refill - -@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.@refill -@end table - -You can use either the @code{texinfo-format-buffer} or the -@code{makeinfo-buffer} command to format a whole buffer:@refill - -@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.@refill -@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.@refill - -@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 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.@refill - -@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.@refill - -@item C-c C-t C-r -@itemx M-x texinfo-tex-region -@findex texinfo-tex-region -Run @TeX{} on the region.@refill - -@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.)@refill - -@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}.@refill -@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.)@refill - -@xref{Hardcopy}, for a description of the other @TeX{} related -commands, such as @code{tex-show-print-queue}.@refill - -@node Texinfo Mode Summary -@comment node-name, next, previous, up -@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.@refill - -@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.)@refill - -@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.@refill - -@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.@refill - -@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}.@refill - -@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}.@refill - -@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.@refill - -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.@refill - -@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.@refill - -@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: 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. -* Software Copying Permissions:: Ensure that you and others continue to - have the right to use and share software. -@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 Info and -@TeX{} 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, you must -write the @code{@@settitle} and @code{@@setfilename} lines between -start-of-header and end-of-header lines. The 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{synindex}), for -instance, is another command often included in the header. @xref{GNU -Sample Texts}, for complete sample texts. - -Thus, the beginning of a Texinfo file generally looks 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 - -@menu -* First Line:: The first line of a Texinfo file. -* Start of Header:: Formatting a region requires this. -* setfilename:: Tell Info the name of the Info file. -* 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 GNU Emacs, the @samp{-*-texinfo-*-} mode -specification tells Emacs 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{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} Emacs variables. @xref{Texinfo Mode Printing}. - - -@node setfilename -@subsection @code{@@setfilename}: Set the output file name -@findex setfilename -@cindex Texinfo requires @code{@@setfilename} - -In order to serve as the primary input file for either @code{makeinfo} -or @TeX{}, a Texinfo file must contain a line that looks like this: - -@example -@@setfilename @var{info-file-name} -@end example - -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; anything on the line after the command is considered -part of the file name, including what would otherwise be a -comment. - -@cindex Ignored before @code{@@setfilename} -@cindex @samp{\input} source line ignored -The Info formatting commands ignore everything written before the -@code{@@setfilename} line, which is why the very first line of -the file (the @code{\input} line) does not show up in the output. - -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, preferably, 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 HTML output, @code{makeinfo} will replace any extension -with @samp{html}, or add @samp{.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, cross-reference, and other auxiliary files used by Texinfo, and -also reads @file{texinfo.cnf} if that file is present on your system -(@pxref{Preparing for TeX,, Preparing for @TeX{}}). - - -@node settitle -@subsection @code{@@settitle}: Set the document title -@findex settitle - -In order to be made into a printed manual, a Texinfo file must 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. This tells @TeX{} the title to -use in a header or footer. Do not write anything else on the line; -anything on the line after the command is considered part of the title, -including what would otherwise be a comment. - -The @code{@@settitle} command should precede everything that generates -actual output. The best place for it is right after the -@code{@@setfilename} command (see the previous section). - -@cindex <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{documentdescription}). - -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 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 a @code{@@subtitle} so it would -be omitted from the @code{@@title}. @xref{titlepage}. - -Conventionally, when @TeX{} formats a Texinfo file for double-sided -output, the title is printed in the left-hand (even-numbered) page -headings and the current chapter title is printed in the right-hand -(odd-numbered) page headings. (@TeX{} learns the title of each chapter -from each @code{@@chapter} command.) By default, no page footer is -printed. - -Even if you are printing in a single-sided style, @TeX{} looks for an -@code{@@settitle} command line, in case you include the manual title -in the heading. - -@TeX{} prints page headings only for that text that comes after the -@code{@@end titlepage} command in the Texinfo file, or that comes -after an @code{@@headings} command that turns on headings. -(@xref{headings on off, , The @code{@@headings} Command}, for more -information.) - -You may, if you wish, create your own, customized headings and footings. -@xref{Headings}, for a detailed discussion of this. - - -@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. - -@menu -* copying:: Declare the document's copying permissions. -* insertcopying:: Where to insert the permissions. -@end menu - - -@node copying -@subsection @code{@@copying}: Declare Copying Permissions -@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. - -@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. You need to include -the license as an appendix to your document. - -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 -in output formats that support this (print and HTML). In the other -formats (Info and plain text), it generates @samp{(C)}. The copyright -notice itself has the following legally defined sequence: - -@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). Ranges are -not allowed; each year must 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 Maintenance Instructions}, for -additional information. - - -@node insertcopying -@subsection @code{@@insertcopying}: Include Permissions Text -@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 output file. - - -@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 the printed manual, but not in -the Info file. Because of this, it is possible to use several slightly -obscure @TeX{} typesetting commands that cannot be used in an Info file. -In addition, this part of the beginning of a Texinfo file contains the -text of the copying permissions that appears in the printed manual. - -@cindex Title page, for plain text -@cindex Copyright page, for plain text -You may wish to include titlepage-like information for plain text -output. Simply place any such leading material between -@code{@@ifplaintext} and @code{@@end ifplaintext}; @command{makeinfo} -includes this when writing plain text (@samp{--no-headers}), along with -an @code{@@insertcopying}. - -@menu -* titlepage:: Create a title for the printed document. -* titlefont center sp:: The @code{@@titlefont}, @code{@@center}, - and @code{@@sp} commands. -* title subtitle author:: The @code{@@title}, @code{@@subtitle}, - and @code{@@author} commands. -* Copyright:: How to write the copyright notice and - include copying permissions. -* end titlepage:: Turn on page headings after the title and - copyright pages. -* headings on off:: An option for turning headings on and off - and double or single sided printing. -@end menu - - -@node titlepage -@subsection @code{@@titlepage} -@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. (@xref{Headings, , Page Headings}, for details about how to -generate page headings.) All the material that you want to appear on -unnumbered pages should be put between the @code{@@titlepage} and -@code{@@end titlepage} commands. 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 extremely 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 titlefont center sp -@subsection @code{@@titlefont}, @code{@@center}, and @code{@@sp} -@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{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{sp, , -@code{@@sp}}, for more information about the @code{@@sp} -command.) - -A template for this method looks like this: - -@example -@group -@@titlepage -@@sp 10 -@@center @@titlefont@{@var{name-of-manual-when-printed}@} -@@sp 2 -@@center @var{subtitle-if-any} -@@sp 2 -@@center @var{author} -@dots{} -@@end titlepage -@end group -@end example - -The spacing of the example fits an 8.5 by 11 inch manual. - -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 title subtitle author -@subsection @code{@@title}, @code{@@subtitle}, and @code{@@author} -@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. These commands are only effective in @TeX{} output; it's -an error to use them anywhere except within @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. Only a single line is -allowed; the @code{@@*} command may not be used to break the title into -two lines. To handle very long titles, you may find it profitable to -use both @code{@@title} and @code{@@titlefont}; see the final example in -this section. - -The @code{@@subtitle} command sets subtitles in a normal-sized font -flush to the right-hand side of the page. - -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 underlined with a -black rule that is thinner than the rule that underlines the title. -(The black rule only occurs if the @code{@@author} command line is -followed by an @code{@@page} command line.) - -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 two (or more) -@code{@@author} commands: - -@example -@group -@@author Jane Smith -@@author John Doe -@end group -@end example - -@noindent -(Only the bottom name is underlined with a black rule.) - -@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 - -You may also combine the @code{@@titlefont} method described in the -previous section and @code{@@title} method described in this one. This -may be useful if you have a very long title. Here is a real-life example: - -@example -@group -@@titlepage -@@titlefont@{GNU Software@} -@@sp 1 -@@title for MS-Windows and MS-DOS -@@subtitle Edition @@value@{e@} for Release @@value@{cde@} -@@author by Daniel Hagerty, Melissa Weisshaus -@@author and Eli Zaretskii -@end group -@end example - -@noindent -(The use of @code{@@value} here is explained in @ref{value 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 -This is a @TeX{} command that is not supported by the Info formatting -commands. The @code{@@vskip} command inserts whitespace. 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 - - -@node end titlepage -@subsection Heading Generation -@findex end titlepage -@cindex Headings, page, begin to appear -@cindex Titlepage end starts headings -@cindex End titlepage starts 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. - -To repeat what is said elsewhere, Texinfo has two standard page heading -formats, one for documents which are printed on one side of each sheet of paper -(single-sided printing), and the other for documents which are printed on both -sides of each sheet (double-sided printing). -You can specify these formats in different ways: - -@itemize @bullet -@item -The conventional way is to write an @code{@@setchapternewpage} command -before the title page commands, and then have the @code{@@end -titlepage} command start generating page headings in the manner desired. -(@xref{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. @xref{headings on off, , The -@code{@@headings} Command}, for more information.)@refill - -@item -Or, you may specify your own page heading and footing format. -@xref{Headings, , Page Headings}, for detailed -information about page headings and footings. -@end itemize - -Most documents are formatted with the standard single-sided or -double-sided format, using @code{@@setchapternewpage odd} for -double-sided printing and no @code{@@setchapternewpage} command for -single-sided printing. - - -@node headings on off -@subsection The @code{@@headings} Command -@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 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{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 -are best placed near the beginning of the file, after the @code{@@end -titlepage} (@pxref{titlepage}). 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 ---no-headers}), unless @code{makeinfo} is writing its output to standard -output. - -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 -(unless, erroneously, no @code{@@end titlepage} is ever encountered). - -You need to include the @code{@@set@dots{}contentsaftertitlepage} -commands early in the document (just after @code{@@setfilename}, for -example). We recommend using @command{texi2dvi} (@pxref{Format with -texi2dvi}) to specify this without altering the source file at all. For -example: -@example -texi2dvi --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{makeinfo top command, , The -@code{@@top} Sectioning 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 a detailed main menu listing all the nodes in a -file. - -A master menu is enclosed in @code{@@menu} and @code{@@end menu} -commands and does not appear in the printed document. - -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 -* documentdescription:: Document summary for the HTML output. -* setchapternewpage:: Start chapters on right-hand pages. -* paragraphindent:: Specify paragraph indentation. -* firstparagraphindent:: Suppress indentation of the first paragraph. -* exampleindent:: Specify environment indentation. -@end menu - - -@node documentdescription -@subsection @code{@@documentdescription}: Summary Text -@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{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 setchapternewpage -@subsection @code{@@setchapternewpage}: -@cindex Starting chapters -@cindex Pages, starting odd -@findex setchapternewpage - -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{headings on off, , The @code{@@headings} Command}. - -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. - -Since an Info file does not have pages, the @code{@@setchapternewpage} -command has no effect on it. - -We recommend not including any @code{@@setchapternewpage} command in -your manual sources at all, since the desired output is not intrinsic to -the document. For a particular hard copy run, if you don't want the -default option (no blank pages, same headers on all pages) use the -@option{--texinfo} option to @command{texi2dvi} to specify the output -you want. - - -@node paragraphindent -@subsection @code{@@paragraphindent}: Paragraph Indenting -@cindex Indenting paragraphs, control of -@cindex Paragraph indentation control -@findex paragraphindent - -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 firstparagraphindent -@subsection @code{@@firstparagraphindent}: Indenting After Headings -@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 -@findex firstparagraphindent - -As you can see in the present manual, the first paragraph in any -section is not indented by default. Typographically, indentation is a -paragraph separator, which means that it is unnecessary when a new -section begins. This indentation is controlled with the -@code{@@firstparagraphindent} command: - -@example -@@firstparagraphindent @var{word} -@end example - -The first paragraph after a heading is indented according to the value -of @var{word}: - -@table @asis -@item @code{none} -Prevents the first paragraph from being indented (default). -This option is ignored by @command{makeinfo} if -@code{@@paragraphindent asis} is in effect. - -@item @code{insert} -Include normal paragraph indentation. This respects the paragraph -indentation set by a @code{@@paragraphindent} command -(@pxref{paragraphindent}). -@end table - -For HTML and XML output, the @code{@@firstparagraphindent} setting is -ignored. - -It is best to write the @code{@@paragraphindent} command before the -end-of-header line at the beginning of a Texinfo file, so the region -formatting commands indent paragraphs as specified. @xref{Start of -Header}. - - -@node exampleindent -@subsection @code{@@exampleindent}: Environment Indenting -@cindex Indenting environments -@cindex Environment indentation -@cindex Example indentation -@findex exampleindent - -The Texinfo processors indent each line of @code{@@example} and similar -environments. You can use the @code{@@exampleindent} command to specify -this indentation. Write an @code{@@exampleindent} command at the -beginning of a line followed by either @samp{asis} or a number: - -@example -@@exampleindent @var{indent} -@end example - -@code{@@exampleindent} is ignored for HTML output. Otherwise, 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 Software Copying Permissions -@section Software Copying Permissions -@cindex Software copying permissions -@cindex Copying software -@cindex Distribution -@cindex License agreement - -If the Texinfo file has a section containing the ``General Public -License'' and the distribution information and a warranty disclaimer for -the software that is documented, we recommend placing this right after -the `Top' node. The General Public License is very important to Project -GNU software. It ensures that you and others will continue to have a -right to use and share the software. - -The copying and distribution information and the disclaimer are followed -by an introduction or else by the first chapter of the manual. - -@cindex Introduction, as part of file -Although an introduction is not a required part of a Texinfo file, it -is very helpful. Ideally, it should state clearly and concisely what -the file is about and who would be interested in reading it. In -general, an introduction would follow the licensing and distribution -information, although sometimes people put it earlier in the document. - - -@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 and Docbook output, @code{@@printindex} produces links -to the index entries. - -@item -In XML output, it simply records the index to be printed. -@end itemize - -It's not possible to generate an index when writing to standard -output; @command{makeinfo} generates a warning in this case. - - -@node File End -@section @code{@@bye} File Ending -@findex bye - -An @code{@@bye} command terminates Texinfo processing. None of the -formatters read anything following @code{@@bye}. The @code{@@bye} -command should be on a line by itself. - -If you wish, you may follow the @code{@@bye} line with notes. These -notes will not be formatted and will not appear in either Info or a -printed manual; it is as if text after @code{@@bye} were within -@code{@@ignore} @dots{} @code{@@end ignore}. Also, you may follow the -@code{@@bye} line with a local variables list for Emacs. -@xref{Compile-Command, , Using Local Variables and the Compile Command}, -for more information. - - -@node Structuring -@chapter Chapter Structuring -@cindex Chapter structuring -@cindex Structuring of chapters - -The @dfn{chapter structuring} commands divide a document into a hierarchy of -chapters, sections, subsections, and subsubsections. These commands -generate large headings; they also provide information for the table -of contents of a printed manual (@pxref{Contents, , Generating a Table -of Contents}).@refill - -The chapter structuring commands do not create an Info node structure, -so normally you should 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 using the -node structuring commands is if you are writing a document that -contains no cross references and will never be transformed into Info -format.@refill - -It is unlikely that you will ever write a Texinfo file that is -intended only as an Info file and not as a printable document. If you -do, you might still use chapter structuring commands to create a -heading at the top of each node---but you don't need to.@refill - -@menu -* Tree Structuring:: A manual is like an upside down tree @dots{} -* Structuring Command Types:: How to divide a manual into parts. -* makeinfo top:: The @code{@@top} command, part of the `Top' node. -* chapter:: -* unnumbered & appendix:: -* majorheading & chapheading:: -* section:: -* unnumberedsec appendixsec heading:: -* subsection:: -* unnumberedsubsec appendixsubsec subheading:: -* subsubsection:: Commands for the lowest level sections. -* 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.@refill - -Here is a diagram that shows a Texinfo file with three chapters, -each of which has two sections.@refill - -@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 -looks like this:@refill - -@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} and @code{@@menu} commands are described in -following chapters. (@xref{Nodes}, and see @ref{Menus}.)@refill - - -@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.@refill - -The four groups are the @code{@@chapter} series, the -@code{@@unnumbered} series, the @code{@@appendix} series, and the -@code{@@heading} series.@refill - -Each command produces titles that have a different appearance on the -printed page or Info file; only some of the commands produce -titles that are listed in the table of contents of a printed book or -manual.@refill - -@itemize @bullet -@item -The @code{@@chapter} and @code{@@appendix} series of commands produce -numbered or lettered entries both in the body of a printed work and in -its table of contents.@refill - -@item -The @code{@@unnumbered} series of commands produce unnumbered entries -both in the body of a printed work and in its table of contents. The -@code{@@top} command, which has a special use, is a member of this -series (@pxref{makeinfo top, , @code{@@top}}). An @code{@@unnumbered} -section should be associated with a node and be 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. The heading commands -never start a new page. - -@item -The @code{@@majorheading} command is similar to @code{@@chapheading}, -except that it generates a larger vertical whitespace before the -heading. - -@item -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.@refill -@end itemize - -Here are the four groups of chapter structuring commands: - -@tex -{\globaldefs = 1 \smallfonts} -@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} -@end tex - - -@node makeinfo top -@section @code{@@top} - -The @code{@@top} command is a special sectioning command that you use -only after an @samp{@@node Top} line at the beginning of a Texinfo file. -The @code{@@top} command tells the @code{makeinfo} formatter which node -is the `Top' node, so it can use it as the root of the node tree if your -manual uses implicit node pointers. It has the same typesetting effect as -@code{@@unnumbered} (@pxref{unnumbered & appendix, , @code{@@unnumbered} -and @code{@@appendix}}). For detailed information, see @ref{makeinfo -top command, , The @code{@@top} Command}. - -The @code{@@top} node and its menu (if any) is conventionally wrapped in -an @code{@@ifnottex} conditional so that it will appear only in Info and -HTML output, not @TeX{}. - - -@node chapter -@comment node-name, next, previous, up -@section @code{@@chapter} -@findex chapter - -@code{@@chapter} identifies a chapter in the document. Write the -command at the beginning of a line and follow it on the same line by -the title of the chapter.@refill - -For example, this chapter in this manual is entitled ``Chapter -Structuring''; the @code{@@chapter} line looks like this:@refill - -@example -@@chapter Chapter Structuring -@end example - -In @TeX{}, the @code{@@chapter} command creates a chapter in the -document, specifying the chapter title. The chapter is numbered -automatically.@refill - -In Info, the @code{@@chapter} command causes the title to appear on a -line by itself, with a line of asterisks inserted underneath. Thus, -in Info, the above example produces the following output:@refill - -@example -Chapter Structuring -******************* -@end example - -@findex centerchap -Texinfo also provides a command @code{@@centerchap}, which is analogous -to @code{@@unnumbered}, but centers its argument in the printed output. -This kind of stylistic choice is not usually offered by Texinfo. -@c but the Hacker's Dictionary wanted it ... - - -@node unnumbered & appendix -@section @code{@@unnumbered} and @code{@@appendix} -@findex unnumbered -@findex appendix - -Use the @code{@@unnumbered} command to create a chapter that appears -in a printed manual without chapter numbers of any kind. Use the -@code{@@appendix} command to create an appendix in a printed manual -that is labelled by letter (`A', `B', @dots{}) instead of by number. - -Write an @code{@@appendix} or @code{@@unnumbered} command at the -beginning of a line and follow it on the same line by the title, as -you would if you were creating a chapter. - - -@node majorheading & chapheading -@section @code{@@majorheading}, @code{@@chapheading} -@findex majorheading -@findex chapheading - -The @code{@@majorheading} and @code{@@chapheading} commands put -chapter-like headings in the body of a document.@refill - -However, neither command causes @TeX{} to produce a numbered heading -or an entry in the table of contents; and neither command causes -@TeX{} to start a new page in a printed manual.@refill - -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, -the @code{@@majorheading} and -@code{@@chapheading} commands are equivalent to -@code{@@chapter}: the title is printed on a line by itself with a line -of asterisks underneath. (@xref{chapter, , @code{@@chapter}}.)@refill - - -@node section -@section @code{@@section} -@findex section - -A @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 a @code{@@chapter} chapter numbered `1', the -section is numbered like `1.2'; within an @code{@@appendix} -``chapter'' labeled `A', the section is numbered like `A.2'; within an -@code{@@unnumbered} chapter, the section gets no number. - -For example, this section is headed with an @code{@@section} command -and looks like this in the Texinfo file: - -@example -@@section @@code@{@@@@section@} -@end example - -To create a section, write the @code{@@section} command at the -beginning of a line and follow it on the same line by the section -title. The output is underlined with @samp{=} in Info. - -Thus, - -@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 - - -@node unnumberedsec appendixsec heading -@section @code{@@unnumberedsec}, @code{@@appendixsec}, @code{@@heading} -@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, as described -in 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 -provide an unnumbered section.@refill - -@item @@appendixsec -@itemx @@appendixsection -@code{@@appendixsection} is a longer spelling of the -@code{@@appendixsec} command; the two are synonymous.@refill -@findex appendixsection - -Conventionally, the @code{@@appendixsec} or @code{@@appendixsection} -command is used only within appendices.@refill - -@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.@refill -@end table - -@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. - - -@node subsection -@section The @code{@@subsection} Command -@findex subsection - -Subsections are to sections as sections are to chapters. -(@xref{section, , @code{@@section}}.) In Info, subsection titles are -underlined with @samp{-}. For example, - -@example -@@subsection This is a subsection -@end example - -@noindent -produces - -@example -@group -1.2.3 This is a subsection --------------------------- -@end group -@end example - -In a printed manual, subsections are listed in the table of contents -and are numbered three levels deep.@refill - - -@node unnumberedsubsec appendixsubsec subheading -@section The @code{@@subsection}-like Commands -@cindex Subsection-like commands -@findex unnumberedsubsec -@findex appendixsubsec -@findex subheading - -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{subsection, , @code{@@subsection}}.) - -In Info, the @code{@@subsection}-like commands generate a title -underlined with hyphens. In a printed manual, 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 labelled with a letter and numbers; both of -these commands produce headings that appear in the table of -contents. - -@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{section,,@code{section}}). - - -@node subsubsection -@section The `subsub' Commands -@cindex Subsub commands -@findex subsubsection -@findex unnumberedsubsubsec -@findex appendixsubsubsec -@findex subsubheading - -The fourth and lowest level sectioning commands in Texinfo are the -`subsub' commands. They are:@refill - -@table @code -@item @@subsubsection -Subsubsections are to subsections as subsections are to sections. -(@xref{subsection, , @code{@@subsection}}.) In a printed manual, -subsubsection titles appear in the table of contents and are numbered -four levels deep.@refill - -@item @@unnumberedsubsubsec -Unnumbered subsubsection titles appear in the table of contents of a -printed manual, but lack numbers. Otherwise, unnumbered -subsubsections are the same as subsubsections. In Info, unnumbered -subsubsections look exactly like ordinary subsubsections.@refill - -@item @@appendixsubsubsec -Conventionally, appendix commands are used only for appendices and are -lettered and numbered appropriately in a printed manual. They also -appear in the table of contents. In Info, appendix subsubsections look -exactly like ordinary subsubsections.@refill - -@item @@subsubheading -The @code{@@subsubheading} command may be used anywhere that you need -a small heading that will not appear in the table of contents. In -Info, subsubheadings look exactly like ordinary subsubsection -headings.@refill -@end table - -@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{section,,@code{section}}). - - -In Info, `subsub' titles are underlined with periods. -For example,@refill - -@example -@@subsubsection This is a subsubsection -@end example - -@noindent -produces - -@example -@group -1.2.3.4 This is a subsubsection -............................... -@end group -@end example - - -@node Raise/lower sections -@section @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. - -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. Typical usage looks like this: - -@example -@@lowersections -@@include somefile.texi -@@raisesections -@end example - -@noindent (Without the @code{@@raisesections}, all the subsequent -sections in the document would be lowered.) - -If the included file being lowered has a @code{@@top} node, you'll -need to conditionalize its inclusion with a flag (@pxref{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 in the document. The final result has to have menus that -take the raising and lowering into account. Therefore, 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 continue 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 won't be correct. - -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. - -Because node names are used in cross-references, it is not desirable -to casually change them. Such name changes invalidate references from -other manuals, from mail archives, and so on. - -@menu -* Two Paths:: Different commands to structure - Info output and printed output. -* Node Menu Illustration:: A diagram, and sample nodes and menus. -* node:: Creating nodes, in detail. -* makeinfo Pointer Creation:: Letting makeinfo determine node pointers. -* anchor:: Defining arbitrary cross-reference targets. -@end menu - - -@node Two Paths -@section Two Paths - -The node and menu commands and the chapter structuring commands are -technically independent of each other: - -@itemize @bullet -@item -In Info, node and menu commands provide structure. The chapter -structuring commands generate headings with different kinds of -underlining---asterisks for chapters, hyphens for sections, and so on; -they do nothing else.@refill - -@item -In @TeX{}, the chapter structuring commands generate chapter and section -numbers and tables of contents. The node and menu commands provide -information for cross references; they do nothing else.@refill -@end itemize - -You can use node pointers and menus to structure an Info file any way -you want; and you can write a Texinfo file so that its Info output has a -different structure than its printed output. However, virtually all -Texinfo files are written such that the structure for the Info output -corresponds to the structure for the printed output. It is neither -convenient nor understandable to the reader to do otherwise.@refill - -Generally, printed output is structured in a tree-like hierarchy in -which the chapters are the major limbs from which the sections branch -out. Similarly, node pointers and menus are organized to create a -matching structure in the Info output.@refill - - -@node Node Menu Illustration -@section Node and Menu Illustration - -Here is a copy of the diagram shown earlier that illustrates a Texinfo -file with three chapters, each of which contains two sections.@refill - -The ``root'' is at the top of the diagram and the ``leaves'' are at the -bottom. This is how such a diagram is drawn conventionally; it -illustrates an upside-down tree. For this reason, the root node is -called the `Top' node, and `Up' node pointers carry you closer to the -root.@refill - -@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 - -The fully-written command to start Chapter 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 -2'', the name of the `Next' node is ``Chapter 3'', the name of the -`Previous' node is ``Chapter 1'', and the name of the `Up' node is -``Top''. You can omit writing out these node names if your document is -hierarchically organized (@pxref{makeinfo Pointer Creation}), but the -pointer relationships still obtain. - -@quotation Note -@strong{Please Note:} `Next' refers to the next node at the same -hierarchical level in the manual, not necessarily to the next node -within the Texinfo file. In the Texinfo file, the subsequent node may -be at a lower level---a section-level node most often follows a -chapter-level node, for example. `Next' and `Previous' refer to nodes -at the @emph{same} hierarchical level. (The `Top' node contains the -exception to this rule. Since the `Top' node is the only node at that -level, `Next' refers to the first following node, which is almost always -a chapter or chapter-level node.)@refill -@end quotation - -To go to Sections 2.1 and 2.2 using Info, you need a menu inside Chapter -2. (@xref{Menus}.) You would write the menu just -before the beginning of Section 2.1, like this:@refill - -@example -@group - @@menu - * Sect. 2.1:: Description of this section. - * Sect. 2.2:: - @@end menu -@end group -@end example - -Write the node for Sect. 2.1 like this:@refill - -@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}.)@refill - -Usually, an @code{@@node} command and a chapter structuring command are -used in sequence, along with indexing commands. (You may follow the -@code{@@node} line with a comment line that reminds you which pointer is -which.)@refill - -Here is the beginning of the chapter in this manual called ``Ending a -Texinfo File''. This shows an @code{@@node} line followed by a comment -line, an @code{@@chapter} line, and then by indexing lines.@refill - -@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 -@@cindex Texinfo file ending -@@cindex File ending -@end group -@end example - - -@node node -@section The @code{@@node} Command - -@cindex Node, defined -@findex node - -A @dfn{node} is a segment of text that begins at an @code{@@node} -command and continues until the next @code{@@node} command. The -definition of node is different from that for chapter or section. A -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, the one that follows -the @code{@@node} line. On the other hand, in printed output nodes -are used only for cross references, so a chapter or section may -contain any number of nodes. Indeed, a chapter usually contains -several nodes, one for each section, subsection, and -subsubsection. - -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 the names of the `Next', -`Previous', and `Up' pointers, in that order, and may be omitted if -your Texinfo document is hierarchically organized (@pxref{makeinfo -Pointer Creation}). - -@opindex accesskey@r{, in HTML output} -Whether the node pointers are specified implicitly or explicitly, the -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 nagivation using (typically) @kbd{M-@var{letter}}, e.g., -@kbd{M-n} for the `Next' node, from anywhere within the node. - -You may insert spaces before each name on the @code{@@node} line if -you wish; the spaces are ignored. You must write the name of the node -and (if present) the names of the `Next', `Previous', and `Up' -pointers all on the same line. Otherwise, the formatters fail. -(@inforef{Top, info, info}, for more information about nodes in Info.) - -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 @code{@@node} lines to identify the names to use 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. (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 Tips:: Keep names short. -* Node Line Requirements:: Keep names unique, without @@-commands. -* First Node:: How to write a `Top' node. -* makeinfo 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 details of node names, -@pxref{Node Line Requirements}). The pointers enable you to reach -other nodes and consist simply of the names of those nodes. - -Normally, a node's `Up' pointer contains the name of the node whose -menu mentions that node. The node's `Next' pointer contains the name -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 node pointers name the same node. - -Usually, the first node of a Texinfo file is the `Top' node, and its -`Up' and `Previous' pointers point to the @file{dir} file, which -contains the main menu for all of Info. - -The `Top' node itself contains the main or master menu for the manual. -Also, it is helpful to include a brief description of the manual in the -`Top' node. @xref{First Node}, for information on how to write the -first node of a Texinfo file. - -Even when you explicitly specify all pointers, that does not mean you -can write the nodes in the Texinfo source file in an arbitrary order! -Because @TeX{} processes the file sequentially, irrespective of node -pointers, you must write the nodes in the order you wish them to appear -in the output. - - -@node Writing a Node -@subsection How to Write an @code{@@node} Line -@cindex Writing an @code{@@node} line -@cindex @code{@@node} line writing -@cindex Node line writing - -The easiest way to write an @code{@@node} line is to write @code{@@node} -at the beginning of a line and then the name of the node, like -this: - -@example -@@node @var{node-name} -@end example - -If you are using GNU Emacs, you can use the update node commands -provided by Texinfo mode to insert the names of the pointers; or 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{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. - -If you wish, you can ignore @code{@@node} lines altogether in your first -draft and then use the @code{texinfo-insert-node-lines} command to -create @code{@@node} lines for you. However, we do not recommend this -practice. It is better to name the node itself at the same time that -you write a segment so you can easily make cross references. A large -number of cross references are an especially important feature of a good -Info file. - -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. - - -@node Node Line Tips -@subsection @code{@@node} Line Tips - -Here are three suggestions: - -@itemize @bullet -@item -Try to pick node names that are informative but short.@refill - -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.)@refill - -@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.@refill - -@item -By convention, node names are capitalized just as they would be for -section or chapter titles---initial and significant words are -capitalized; others are not.@refill -@end itemize - - -@node Node Line Requirements -@subsection @code{@@node} Line Requirements - -@cindex Node line requirements -@cindex Restrictions on node names -Here are several requirements for @code{@@node} lines: - -@itemize @bullet -@cindex Unique nodename requirement -@cindex Node name must be unique -@item -All the node names for a single Info file must be unique. - -Duplicates confuse the Info movement commands. This means, for -example, that if you end every chapter with a summary, you must name -each summary node differently. You cannot just call each one -``Summary''. You may, however, duplicate the titles of chapters, sections, -and the like. Thus you can end each chapter in a book with a section -called ``Summary'', so long as the node names for those sections are all -different. - -@item -A pointer name must be the name of a node. - -The node to which a pointer points may come before or after the -node containing the pointer. - -@cindex @@-commands in nodename -@cindex Node name, should not contain @@-commands -@item -@@-commands in node names are not allowed. This includes punctuation -characters that are escaped with a @samp{@@}, such as @code{@@} and -@code{@{}, and accent commands such as @samp{@@'}. (For a few cases -when this is useful, Texinfo has limited support for using -@w{@@-commands} in node names; see @ref{Pointer Validation}.) Perhaps -this limitation will be removed some day. - -@item -@cindex Colon in nodename -@cindex Comma in nodename -@cindex Parentheses in nodename -@cindex Period in nodename -@cindex Characters, invalid in node name -@cindex Invalid characters in node names -@cindex Node names, invalid characters in -Unfortunately, you cannot use periods, commas, colons or parentheses -within a node name; these confuse the Texinfo processors. Perhaps -this limitation will be removed some day, too. - -@need 700 -For example, the following is a section title in this manual: - -@smallexample -@@code@{@@@@unnumberedsec@}, @@code@{@@@@appendixsec@}, @@code@{@@@@heading@} -@end smallexample - -@noindent -But the corresponding node name lacks the commas and the @@'s: - -@smallexample -unnumberedsec appendixsec heading -@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, -but spaces ``inside'' a name are significant. For example: - -@example -@@node foo bar, -@@node foo bar , -@@node foo bar , -@end example - -@noindent all define the same node, @samp{foo bar}. References to the -node should all use that name, without the leading or trailing spaces, -but with the internal spaces. -@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 the same Info directory tree; -in this case, use @samp{(dir)} as the parent of the Top node; this is -short for @samp{(dir)top}, and specifies the Top node in the @file{dir} -file, which contains the main menu for the Info system as a whole. - -@item -@cindex Prev node of Top node -The `Prev' node of the Top node should also be your @samp{(dir)} file. - -@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 makeinfo top command -@subsection The @code{@@top} Sectioning Command -@findex top @r{(@@-command)} - -A special sectioning command, @code{@@top} should be used with the -@code{@@node Top} line. The @code{@@top} sectioning command tells -@code{makeinfo} that it marks the `Top' node in the file. It provides -the information that @code{makeinfo} needs to insert node pointers -automatically. Write the @code{@@top} command at the beginning of the -line immediately following the @code{@@node Top} line. Write the title -on the remaining part of the same line as the @code{@@top} command. - -In Info, the @code{@@top} sectioning command causes the title to appear -on a line by itself, with a line of asterisks inserted underneath, as -other sectioning commands do. - -In @TeX{} and @code{texinfo-format-buffer}, the @code{@@top} -sectioning command is merely a synonym for @code{@@unnumbered}. -Neither of these formatters require an @code{@@top} command, and do -nothing special with it. You can use @code{@@chapter} or -@code{@@unnumbered} after the @code{@@node Top} line when you use -these formatters. Also, you can use @code{@@chapter} or -@code{@@unnumbered} when you use the Texinfo updating commands to -create or update pointers and menus. - -Thus, in practice, a Top node starts like this: - -@example -@@node Top -@@top Your Manual Title -@end example - - -@node makeinfo Pointer Creation -@section Creating Pointers with @code{makeinfo} -@cindex Creating pointers with @code{makeinfo} -@cindex Pointer creation with @code{makeinfo} -@cindex Automatic pointer creation with @code{makeinfo} - -The @code{makeinfo} program has a feature for automatically -determining node pointers for a hierarchically organized document. We -highly recommend using it. - -When you take advantage of this feature, you do not need to write the -`Next', `Previous', and `Up' pointers after the name of a node. -However, you must write a sectioning command, such as @code{@@chapter} -or @code{@@section}, on the line immediately following each truncated -@code{@@node} line (except that comment lines may intervene). - -In addition, you must follow the `Top' @code{@@node} line with a line -beginning with @code{@@top} to mark the `Top' node in the -file. @xref{makeinfo top, , @code{@@top}}. - -Finally, you must write the name of each node (except for the `Top' -node) in a menu that is one or more hierarchical levels above the -node's hierarchical level. - -@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. - -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}.) - -In most cases, you will want to take advantage of this feature and not -redundantly specify node pointers. 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). The special procedure for handling the short -text before a menu (@pxref{Menus}) also disables this -feature, for that group of nodes. In those cases, you will need to -explicitly specify all pointers. - -@node anchor -@section @code{@@anchor}: Defining Arbitrary Cross-reference Targets - -@findex anchor -@cindex Anchors -@cindex Cross-reference targets, arbitrary -@cindex Targets for cross-references, arbitrary - -An @dfn{anchor} is a position in your document, labeled so that -cross-references can refer to it, just as they can to nodes. You create -an anchor with the @code{@@anchor} command, and give the label as a -normal brace-delimited argument. For example: - -@example -This marks the @@anchor@{x-spot@}spot. -@dots{} -@@xref@{x-spot,,the spot@}. -@end example - -@noindent produces: - -@example -This marks the spot. -@dots{} -See [the spot], page 1. -@end example - -As you can see, the @code{@@anchor} command itself produces no output. -This example defines an anchor `x-spot' just before the word `spot'. -You can refer to it later with an @code{@@xref} or other cross-reference -command, as shown. @xref{Cross References}, for details on the -cross-reference commands. - -It is best to put @code{@@anchor} commands just before the position you -wish to refer to; that way, the reader's eye is led on to the correct -text when they jump to the anchor. You can put the @code{@@anchor} -command on a line by itself if that helps readability of the source. -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 in standalone Info takes either an anchor name or a node name as -an argument. (@xref{goto-node,,,info-stnd,GNU Info}.) - -Also like node names, anchor names cannot include some characters -(@pxref{Node Line Requirements}). - - -@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. - -A node with a menu should not contain much text. If you find yourself -writing a lot of text before a menu, we generally recommend moving -most of the text into a new subnode---all but a paragraph or two. -Otherwise, a reader with a terminal that displays only a few lines may -miss the menu and its associated text. As a practical matter, it is -best to locate a menu within 20 or so lines of the beginning of the -node. - -@menu -* Menu Location:: Menus go at the ends of short 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 - -A menu must be 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. (As a consequence, there may be at most one menu in -a node.) - -@cindex Info format, and menus -This is actually a useful restriction, since a reader who uses the -menu could easily miss any such text. Technically, it is necessary -because in Info format, there is no marker for the end of a menu, so -Info-reading programs would have no way to know when the menu ends and -normal text resumes. - -@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 ever making use of this, because the -@command{makeinfo} implicit pointer creation feature (@pxref{makeinfo -Pointer Creation}) and GNU Emacs Texinfo mode updating commands work -only to create menus of subordinate nodes in a hierarchically -structured document. Instead, use cross references to refer to -arbitrary nodes. - -In the past, we recommended using a @samp{@@heading} command within an -@code{@@ifinfo} conditional instead of the normal sectioning commands -after a very short node with a menu. This had the advantage of making -the printed output look better, because there was no very short text -between two headings on the page. But this also does not work with -@command{makeinfo}'s implicit pointer creation, and it also makes the -XML output incorrect, since it does not reflect the true document -structure. So, regrettably, we can 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 - -In a menu, every line that begins with an @w{@samp{* }} is a @dfn{menu -entry}. (Note the space after the asterisk.) A line that does not -start with an @w{@samp{* }} may also appear in a menu. Such a line is -not a menu entry but is a menu comment line that appears in the Info -file. In the example above, the line @samp{Larger Units of Text} is a -menu comment line; the two lines starting with @w{@samp{* }} are menu -@cindex Spaces, in menus -entries. Space characters in a menu are preserved as-is; this allows -you to format the menu as you wish. - -@opindex accesskey@r{, in HTML output} -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 menu entry looks like this:@refill - -@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, period, or newline.@refill - -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.@refill - -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 two or more 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. - - -@node Less Cluttered Menu Entry -@comment node-name, next, previous, up -@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.@refill - -@need 800 -For example, write - -@example -* Name:: @var{description} -@end example - -@need 800 -@noindent -instead of - -@example -* Name: Name. @var{description} -@end example - -You should use the node name for the menu entry name whenever possible, -since it reduces visual clutter in the menu.@refill - -@node Menu Example -@comment node-name, next, previous, up -@section A Menu Example -@cindex Menu example -@cindex Example menu - -A menu looks like this in Texinfo:@refill - -@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:@refill - -@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.@refill - -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}).@refill - -@node Other Info Files -@comment node-name, next, previous, up -@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. In this case, you should use the three-part menu -entry format, which saves the reader from having to type the file -name.@refill - -@need 800 -The format looks like this:@refill - -@example -@group -@@menu -* @var{first-entry-name}:(@var{filename})@var{nodename}. @var{description} -* @var{second-entry-name}:(@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{Emacs Manual}, you would write a -menu like this:@refill - -@example -@group -@@menu -* Outlining: (emacs)Outline Mode. The major mode for - editing outlines. -* Rebinding: (emacs)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.@refill - -The @file{dir} file that contains the main menu for Info has menu -entries that list only file names. These take you directly to the `Top' -nodes of each Info document. (@xref{Installing an Info File}.) - -@need 700 -For example: - -@example -@group -* Info: (info). Documentation browsing system. -* Emacs: (emacs). The extensible, self-documenting - text editor. -@end group -@end example - -@noindent -(The @file{dir} top level directory for the Info system is an Info file, -not a Texinfo file, but a menu entry looks the same in both types of -file.)@refill - -The GNU Emacs Texinfo mode menu updating commands only work with nodes -within the current buffer, so you cannot use them to create menus that -refer to other files. You must write such menus by hand. - - -@node Cross References -@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. -* xref:: Begin a reference with `See' @dots{} -* Top Node Naming:: How to refer to the beginning of another file. -* ref:: A reference for the last part of a sentence. -* pxref:: How to write a parenthetical cross reference. -* inforef:: How to refer to an Info-only file. -* uref:: How to refer to a uniform resource locator. -@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.@refill - -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.@refill - -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.@refill - -In Info, a cross reference results in an entry that you can follow -using the Info @samp{f} command. (@inforef{Help-Xref, Following -cross-references, info}.) - -The various cross reference commands use nodes (or anchors, -@pxref{anchor,,@code{@@anchor}}) to define cross reference locations. -This is evident in Info, in which a cross reference takes you to the -specified location. @TeX{} also uses nodes to define cross reference -locations, but the action is less obvious. When @TeX{} generates a DVI -file, it records each node's page number and uses the page numbers in making -references. Thus, if you are writing a manual that will only be -printed, and will not be used online, you must nonetheless write -@code{@@node} lines to name the places to which you make cross -references.@refill - -@need 800 -@node Cross Reference Commands -@comment node-name, next, previous, up -@section Different Cross Reference Commands -@cindex Different cross reference commands - -There are four different cross reference commands:@refill - -@table @code -@item @@xref -Used to start a sentence in the printed manual saying @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; same as -@code{@@xref} for Info; produces just the reference in the printed -manual without a preceding `See'.@refill - -@item @@pxref -Used within parentheses to make a reference that suits both an Info -file and a printed book. Starts with a lower case `see' within the -printed manual. (@samp{p} is for `parenthesis'.)@refill - -@item @@inforef -Used to make a reference to an Info file for which there is no printed -manual.@refill -@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{cite, , @code{@@cite}}.)@refill - -@node Cross Reference Parts -@comment node-name, next, previous, up -@section Parts of a Cross Reference -@cindex Cross reference parts -@cindex Parts of a cross reference - -A cross reference command 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 for Info, a topic -description or section title for the printed output, the name of a -different Info file, and the name of a different printed -manual.@refill - -Here is a simple cross reference example:@refill - -@example -@@xref@{Node name@}. -@end example - -@noindent -which produces - -@example -*Note Node name::. -@end example - -@noindent -and - -@quotation -See Section @var{nnn} [Node name], page @var{ppp}. -@end quotation - -@need 700 -Here is an example of a full five-part cross reference:@refill - -@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:@refill - -@enumerate -@item -The node or anchor name (required). This is the location to which the -cross reference takes you. In a printed document, the location of the -node provides the page reference only for references within the same -document.@refill - -@item -The cross reference name for the Info reference, if it is to be -different from the node name or the topic description. 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.@refill - -@item -The name of the Info file in which the reference is located, if it is -different from the current file. You need not include any @samp{.info} -suffix on the file name, since Info readers try appending it -automatically. - -@item -The name of a printed manual from a different Texinfo file.@refill -@end enumerate - -The template for a full five argument cross reference looks like -this:@refill - -@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}.@refill - -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.@refill - -You can write cross reference commands within a paragraph, but note -how Info and @TeX{} format the output of each of the various commands: -write @code{@@xref} at the beginning of a sentence; write -@code{@@pxref} only within parentheses, and so on.@refill - -@node xref -@comment node-name, next, previous, up -@section @code{@@xref} -@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.@refill - -@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:@refill - -@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 in either the Info file or the printed output. -You must write that period or comma yourself; otherwise, Info will not -recognize the end of the reference. (The @code{@@pxref} command works -differently. @xref{pxref, , @code{@@pxref}}.)@refill - -@quotation Caution -A period or comma @strong{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, both in -the Info file and in the printed manual.@refill -@end quotation - -@code{@@xref} must refer to an Info node by name. Use @code{@@node} -to define the node (@pxref{Writing a Node}).@refill - -@code{@@xref} is followed by several arguments inside braces, separated by -commas. Whitespace before and after these commas is ignored.@refill - -A cross reference 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.@refill - -@quotation Note -Commas separate arguments in a cross reference; -avoid including them in the title or other part lest the formatters -mistake them for separators.@refill -@end quotation - -@node One Argument -@subsection @code{@@xref} with One Argument - -The simplest form of @code{@@xref} takes one argument, the name of -another node in the same Info 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.@refill - -@need 700 -@noindent -For example, - -@example -@@xref@{Tropical Storms@}. -@end example - -@noindent -produces - -@example -*Note Tropical Storms::. -@end example - -@noindent -and - -@quotation -See Section 3.1 [Tropical Storms], page 24. -@end quotation - -@noindent -(Note that in the preceding example the closing brace is followed by a -period.)@refill - -You can write a clause after the cross reference, like this:@refill - -@example -@@xref@{Tropical Storms@}, for more info. -@end example - -@noindent -which produces - -@example -*Note Tropical Storms::, for more info. -@end example - -@noindent -and - -@quotation -See Section 3.1 [Tropical Storms], page 24, for more info. -@end quotation - -@noindent -(Note that in the preceding example the closing brace is followed by a -comma, and then by the clause, which is followed by a period.)@refill - -@node Two Arguments -@subsection @code{@@xref} with Two Arguments - -With two arguments, the second is used as the name of the Info cross -reference, while the first is still the name of the node to which the -cross reference points.@refill - -@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 -and - -@quotation -See Section 5.2 [Electrical Effects], page 57. -@end quotation - -@noindent -(Note that in the preceding example the closing brace is followed by a -period; and that the node name is printed, not the cross reference name.) - -You can write a clause after the cross reference, like this:@refill - -@example -@@xref@{Electrical Effects, Lightning@}, for more info. -@end example - -@noindent -which produces -@example -*Note Lightning: Electrical Effects, for more info. -@end example - -@noindent -and - -@quotation -See Section 5.2 [Electrical Effects], page 57, for more info. -@end quotation - -@noindent -(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.)@refill - -@node Three Arguments -@subsection @code{@@xref} with Three Arguments - -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 upper case 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.@refill - -Remember to avoid placing a comma within the title or topic section of -a cross reference, or within any other section. The formatters divide -cross references into arguments according to the commas; a comma -within a title or other section will divide it into two arguments. In -a reference, you need to write a title such as ``Clouds, Mist, and -Fog'' without the commas.@refill - -Also, remember to write a comma or period after the closing brace of an -@code{@@xref} to terminate the cross reference. In the following -examples, a clause follows a terminating comma.@refill - - -@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 -and - -@quotation -See Section 5.2 [Thunder and Lightning], page 57, for details. -@end quotation - -If a third argument is given and the second one is empty, then the -third argument serves both. (Note how two commas, side by side, mark -the empty second argument.)@refill - -@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 -and - -@quotation -See Section 5.2 [Thunder and Lightning], page 57, for details. -@end quotation - -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, and with the first and third arguments if the node name and title -are different.@refill - -Here are several examples from @cite{The GNU Awk User's Guide}:@refill - -@smallexample -@@xref@{Sample Program@}. -@@xref@{Glossary@}. -@@xref@{Case-sensitivity, ,Case-sensitivity in Matching@}. -@@xref@{Close Output, , Closing Output Files and Pipes@}, - for more information. -@@xref@{Regexp, , Regular Expressions as Patterns@}. -@end smallexample - -@node Four and Five Arguments -@subsection @code{@@xref} with Four and Five Arguments - -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.@refill - -Remember that a comma or period must follow the closing brace of an -@code{@@xref} command to terminate the cross reference. In the -following examples, a clause follows a terminating comma.@refill - -@need 800 -@noindent -The 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@}, for details. -@end example - -@noindent -produces - -@example -*Note Lightning: (weather)Electrical Effects, for details. -@end example - -@noindent -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:@refill - -@quotation -See section ``Thunder and Lightning'' in @i{An Introduction to -Meteorology}, for details. -@end quotation - -@noindent -The title of the printed manual is typeset in italics; and the -reference lacks a page number since @TeX{} cannot know to which page a -reference refers when that reference is to another manual.@refill - -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.@refill - -@noindent -The template looks like this: - -@example -@@xref@{@var{node-name}, , @var{title-or-topic}, @var{info-file-name}, -@var{printed-manual-title}@}, for details. -@end example - -@noindent -which produces - -@example -*Note @var{title-or-topic}: (@var{info-file-name})@var{node-name}, for details. -@end example - -@noindent -and - -@quotation -See section @var{title-or-topic} in @var{printed-manual-title}, for details. -@end quotation - -@need 700 -@noindent -For example, - -@example -@@xref@{Electrical Effects, , Thunder and Lightning, -weather, An Introduction to Meteorology@}, for details. -@end example - -@noindent -produces - -@example -@group -*Note Thunder and Lightning: (weather)Electrical Effects, -for details. -@end group -@end example - -@noindent -and - -@quotation -See section ``Thunder and Lightning'' in @i{An Introduction to -Meteorology}, for details. -@end quotation - -On rare occasions, you may want to refer to another Info file that -is within a single printed manual---when multiple Texinfo files are -incorporated into the same @TeX{} run but make separate Info files. -In this case, you need to specify only the fourth argument, and not -the fifth.@refill - -@node Top Node Naming -@section Naming a `Top' Node -@cindex Naming a `Top' Node in references -@cindex @samp{@r{Top}} node naming for references - -In a cross reference, you must always name a node. This means that in -order to refer to a whole manual, you must identify the `Top' node by -writing it as the first argument to the @code{@@xref} command. (This -is different from the way you write a menu entry; see @ref{Other Info -Files, , Referring to Other Info Files}.) At the same time, to -provide a meaningful section topic or title in the printed cross -reference (instead of the word `Top'), you must write an appropriate -entry for the third argument to the @code{@@xref} command. -@refill - -@noindent -Thus, to make a cross reference to @cite{The GNU Make Manual}, -write:@refill - -@example -@@xref@{Top, , Overview, make, The GNU Make Manual@}. -@end example - -@noindent -which produces - -@example -*Note Overview: (make)Top. -@end example - -@noindent -and - -@quotation -See section ``Overview'' in @i{The GNU Make Manual}. -@end quotation - -@noindent -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. - - -@node ref -@section @code{@@ref} -@cindex Cross references using @code{@@ref} -@cindex References using @code{@@ref} -@findex 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 sometimes tempts 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 will 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 pxref -@section @code{@@pxref} -@cindex Cross references using @code{@@pxref} -@cindex References using @code{@@pxref} -@findex 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 lower case -`see' rather than an upper case `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 -and - -@quotation -@dots{} storms cause flooding (see Section 6.7 [Hurricanes], page 72) @dots{} -@end quotation - -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 -and - -@quotation -@dots{} (see Section @var{nnn} [@var{node-name}], page @var{ppp}) @dots{} -@end quotation - -@code{@@pxref} can be used with up to five arguments, just like -@code{@@xref} (@pxref{xref, , @code{@@xref}}). - -In past versions of Texinfo, it was not allowed to write punctuation -after a @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 -This works fine. @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 general 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 inforef -@section @code{@@inforef} -@cindex Cross references using @code{@@inforef} -@cindex References using @code{@@inforef} -@findex 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:@refill - -@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}.@refill - -@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.) - -The converse of @code{@@inforef} is @code{@@cite}, which is used to -refer to printed works for which no Info form exists. @xref{cite, , -@code{@@cite}}. - - -@node uref -@section @code{@@url}, @code{@@uref@{@var{url}[, @var{text}][, @var{replacement}]@}} -@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. - -@code{@@url} is a synonym for @code{@@uref}. Originally, @code{@@url} -had the meaning of @code{@@indicateurl} -(@pxref{indicateurl,,@code{@@indicateurl}}), but in actual practice it -was misused the vast majority of the time. 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 also output. - -@cindex Man page, reference to -The third argument, if specified, is the text to display, but in this -case the url is @emph{not} output in any format. This is useful when -the text is already sufficiently referential, as in a man page. If -the third argument is given, the second argument is ignored. - -If the url is long enough to cause problems with line breaking, you -may find it useful to insert @code{@@/} at places where a line break -would be acceptable (after @samp{/} characters, for instance). This -tells @TeX{} to allow (but not force) a line break at those places. -@xref{Line Breaks}. - -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@{ftp://ftp.gnu.org/gnu@}. -@end example - -@noindent produces: -@display -The official GNU ftp site is @uref{ftp://ftp.gnu.org/gnu}. -@end display - - -An example of the two-argument form: -@example -The official @@uref@{ftp://ftp.gnu.org/gnu, GNU ftp site@} -holds programs and texts. -@end example - -@noindent produces: -@display -The official @uref{ftp://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 (ftp://ftp.gnu.org/gnu) -holds programs and texts. -@end example - -@noindent and the HTML output is this: -@example -The official <a href="ftp://ftp.gnu.org/gnu">GNU ftp site</a> -holds programs and texts. -@end example - - -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 - -To merely indicate a url without creating a link people can follow, use -@code{@@indicateurl} (@pxref{indicateurl, @code{@@indicateurl}}). - -Some people prefer to display url's in the unambiguous format: - -@display -<URL:http://@var{host}/@var{path}> -@end display - -@noindent -@cindex <URL: convention, not used -You can use this form in the input file if you wish. We feel it's not -necessary to include the @samp{<URL:} and @samp{>} in the output, -since any software that tries to detect url's in text already has to -detect them without the @samp{<URL:} to be useful. - - -@node Marking Text -@chapter Marking Words and Phrases -@cindex Paragraph, marking text within -@cindex Marking words and phrases -@cindex Words and phrases, marking them -@cindex Marking text within a paragraph -@cindex Text, marking up - -In Texinfo, you can mark words and phrases in a variety of ways. -The Texinfo formatters use this information to determine how to -highlight the text. -You can specify, for example, whether a word or phrase is a -defining occurrence, a metasyntactic variable, or a symbol used in a -program. Also, you can emphasize text, 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, metasyntactic variables are marked by -@code{@@var}, and code by @code{@@code}. Since the pieces of text are -labelled by commands that tell what kind of object they are, it is easy -to change the way the Texinfo formatters prepare such text. (Texinfo is -an @emph{intentional} formatting language rather than a @emph{typesetting} -formatting language.)@refill - -For example, in a printed manual, -code is usually illustrated in a typewriter font; -@code{@@code} tells @TeX{} to typeset this text in this font. But it -would be easy to change the way @TeX{} highlights code to use another -font, and this change would not affect how keystroke examples are -highlighted. If straight typesetting commands were used in the body -of the file and you wanted to make a change, you would need to check -every single occurrence to make sure that you were changing code and -not something else that should not be changed.@refill - -@menu -* Useful Highlighting:: Highlighting provides useful information. -* code:: Indicating program code. -* kbd:: Showing keyboard input. -* key:: Specifying keys. -* samp:: Indicating a literal sequence of characters. -* verb:: Indicating a verbatim sequence of characters. -* var:: Indicating metasyntactic variables. -* env:: Indicating environment variables. -* file:: Indicating file names. -* command:: Indicating command names. -* option:: Indicating option names. -* dfn:: Specifying definitions. -* cite:: Referring to books not in the Info system. -* abbr:: Indicating abbreviations. -* acronym:: Indicating acronyms. -* indicateurl:: Indicating an example URL. -* email:: Indicating an electronic mail address. -@end menu - - -@node Useful Highlighting -@subsection Highlighting Commands are Useful - -The highlighting commands can be used to extract useful information -from the file, such as lists of functions or file names. It is -possible, for example, to write a program in Emacs Lisp (or a keyboard -macro) to insert an index entry after every paragraph that contains -words or phrases marked by a specified command. You could do this to -construct an index of functions if you had not already made the -entries.@refill - -The commands serve a variety of purposes:@refill - -@table @code -@item @@code@{@var{sample-code}@} -Indicate text that is a literal example of a piece of a program. -@xref{code,,@code{@@code}}. - -@item @@kbd@{@var{keyboard-characters}@} -Indicate keyboard input. -@xref{kbd,,@code{@@kbd}}. - -@item @@key@{@var{key-name}@} -Indicate the conventional name for a key on a keyboard. -@xref{key,,@code{@@key}}. - -@item @@samp@{@var{text}@} -Indicate text that is a literal example of a sequence of characters. -@xref{samp,,@code{@@samp}}. - -@item @@verb@{@var{text}@} -Write a verbatim sequence of characters. -@xref{verb,,@code{@@verb}}. - -@item @@var@{@var{metasyntactic-variable}@} -Indicate a metasyntactic variable. -@xref{var,,@code{@@var}}. - -@item @@env@{@var{environment-variable}@} -Indicate an environment variable. -@xref{env,,@code{@@env}}. - -@item @@file@{@var{file-name}@} -Indicate the name of a file. -@xref{file,,@code{@@file}}. - -@item @@command@{@var{command-name}@} -Indicate the name of a command. -@xref{command,,@code{@@command}}. - -@item @@option@{@var{option}@} -Indicate a command-line option. -@xref{option,,@code{@@option}}. - -@item @@dfn@{@var{term}@} -Indicate the introductory or defining use of a term. -@xref{dfn,,@code{@@dfn}}. - -@item @@cite@{@var{reference}@} -Indicate the name of a book. -@xref{cite,,@code{@@cite}}. - -@item @@abbr@{@var{abbreviation}@} -Indicate an abbreviation. - -@item @@acronym@{@var{acronym}@} -Indicate an acronym. -@xref{acronym,,@code{@@acronym}}. - -@item @@indicateurl@{@var{uniform-resource-locator}@} -Indicate an example (that is, nonfunctional) uniform resource locator. -@xref{indicateurl,,@code{@@indicateurl}}. (Use @code{@@url} -(@pxref{uref,,@code{@@url}}) for live url's.) - -@item @@email@{@var{email-address}[, @var{displayed-text}]@} -Indicate an electronic mail address. -@xref{email,,@code{@@email}}. - -@ignore -@item @@ctrl@{@var{ctrl-char}@} -Use for an ASCII control character. -@end ignore -@end table - - -@node code -@subsection @code{@@code}@{@var{sample-code}@} -@findex code - -@cindex Syntactic tokens, indicating -Use the @code{@@code} command to indicate text that is a piece of a -program and which consists of entire syntactic tokens. Enclose the -text in braces. - -@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 lower case, you -should rearrange the sentence. - -In the printed manual, @code{@@code} causes @TeX{} to typeset the -argument in a typewriter face. In the Info file, it causes the Info -formatting commands to use single quotation marks around the text. -For example, - -@example -The function returns @@code@{nil@}. -@end example - -@noindent -produces this: - -@quotation -The function returns @code{nil}. -@end quotation - -@iftex -@noindent -and this in the Info file: -@example -The function returns `nil'. -@end example -@end iftex - -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 shell options such as @samp{-c} when such options stand alone (use -@code{@@option}). - -@item -Also, an entire shell command often looks better if written using -@code{@@samp} rather than @code{@@code}. In this case, the rule is to -choose the more pleasing format. - -@item -For environment variable such as @env{TEXINPUTS} (use @code{@@env}). - -@item -For a string of characters shorter than a syntactic token. For example, -if you are writing about @samp{goto-ch}, which is just a part of the -name for the @code{goto-char} Emacs Lisp function, you should use -@code{@@samp}. - -@item -In general, when writing about the characters used in a token; for -example, do not use @code{@@code} when you are explaining what letters -or printable symbols can be used in the names of functions. (Use -@code{@@samp}.) Also, you should not use @code{@@code} to mark text -that is considered input to programs unless the input is written in a -language that is like a programming language. For example, you should -not use @code{@@code} for the keystroke commands of GNU Emacs (use -@code{@@kbd} instead) although you may use @code{@@code} for the names -of the Emacs Lisp functions that the keystroke commands invoke. - -@end itemize - -Since @code{@@command}, @code{@@option}, and @code{@@env} were -introduced relatively recently, it is acceptable to use @code{@@code} or -@code{@@samp} for command names, options, and environment variables. -The new commands allow you to express the markup more precisely, but -there is no real harm in using the older commands, and of course the -long-standing manuals do so. - -Ordinarily, @TeX{} will consider breaking lines at @samp{-} and -@samp{_} characters within @code{@@code} and related commands. This -can be controlled with @code{@@allowcodebreaks} -(@pxref{allowcodebreaks,,@code{@@allowcodebreaks}}). - - -@node kbd -@subsection @code{@@kbd}@{@var{keyboard-characters}@} -@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) in the printed -manual, so users can distinguish the characters that they are supposed -to type from those that the computer outputs. - -In Info output, @code{@@kbd} is usually the same as @code{@@code}, -producing `quotes' around its argument. However, in typewriter-like -contexts such as the @code{@@example} environment (@pxref{example}) -and @code{@@code} command itself, the quotes are omitted, since Info -format cannot use distinguishing fonts. - -@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 accepts 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.)@refill - - -@node key -@subsection @code{@@key}@{@var{key-name}@} -@findex key - -Use the @code{@@key} command for the conventional name for a key on a -keyboard, as in:@refill - -@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.@refill - -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 - -@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 samp -@subsection @code{@@samp}@{@var{text}@} -@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.@refill - -@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$}.@refill -@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}, or @code{@@key}.@refill - -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:@refill - -@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 verb -@subsection @code{@@verb}@{<char>@var{text}<char>@} -@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 these @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. With @code{@@verb}, nothing is special except the delimiter -character you choose. - -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 var -@subsection @code{@@var}@{@var{metasyntactic-variable}@} -@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.@refill - -Do not use @code{@@var} for the names of particular variables in -programming languages. These are specific names from a program, so -@code{@@code} is correct for them (@pxref{code}). For example, the -Emacs Lisp variable @code{texinfo-tex-command} is not a metasyntactic -variable; it is properly formatted using @code{@@code}. - -Do not use @code{@@var} for environment variables either; @code{@@env} -is correct for them (see the next section). - -The effect of @code{@@var} in the Info file is to change the case of the -argument to all upper case. In the printed manual and HTML output, the -argument is printed 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.)@refill - -Write a metasyntactic variable all in lower case 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:@refill - -@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:@refill - -@example -@dots{}, type rm <filename> -@end example - -@noindent -However, that is not the style that Texinfo uses. (You can, of -course, modify the sources to @file{texinfo.tex} and the Info formatting commands -to output the @code{<@dots{}>} format if you wish.)@refill - - -@node env -@subsection @code{@@env}@{@var{environment-variable}@} -@findex env - -Use the @code{@@env} command to indicate environment variables, as used -by many operating systems, including GNU. Do not use it for -metasyntactic variables; use @code{@@var} instead (see the previous -section). - -@code{@@env} is equivalent to @code{@@code} in its effects. -For example: - -@example -The @@env@{PATH@} environment variable @dots{} -@end example -@noindent produces -@quotation -The @env{PATH} environment variable @dots{} -@end quotation - - -@node file -@subsection @code{@@file}@{@var{file-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}. - -Currently, @code{@@file} is equivalent to @code{@@samp} in its effects. -For example,@refill - -@example -The @@file@{.el@} files are in -the @@file@{/usr/local/emacs/lisp@} directory. -@end example - -@noindent -produces - -@quotation -The @file{.el} files are in -the @file{/usr/local/emacs/lisp} directory. -@end quotation - - -@node command -@subsection @code{@@command}@{@var{command-name}@} -@findex command -@cindex Command names, indicating -@cindex Program names, indicating - -Use the @code{@@command} command to indicate command names, such as -@command{ls} or @command{cc}. - -@code{@@command} is equivalent to @code{@@code} in its effects. -For example: - -@example -The command @@command@{ls@} lists directory contents. -@end example -@noindent produces -@quotation -The command @command{ls} lists directory contents. -@end quotation - -You should write the name of a program in the ordinary text font, rather -than using @code{@@command}, if you regard it as a new English word, -such as `Emacs' or `Bison'. - -When writing an entire shell command invocation, as in @samp{ls -l}, -you should use either @code{@@samp} or @code{@@code} at your discretion. - - -@node option -@subsection @code{@@option}@{@var{option-name}@} -@findex option - -Use the @code{@@option} command to indicate a command-line option; for -example, @option{-l} or @option{--version} or -@option{--output=@var{filename}}. - -@code{@@option} is equivalent to @code{@@samp} in its effects. -For example: - -@example -The option @@option@{-l@} produces a long listing. -@end example -@noindent produces -@quotation -The option @option{-l} produces a long listing. -@end quotation - -In tables, putting options inside @code{@@code} produces a -more pleasing effect. - -@node dfn -@comment node-name, next, previous, up -@subsection @code{@@dfn}@{@var{term}@} -@findex dfn - -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:@refill - -@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 cite -@subsection @code{@@cite}@{@var{reference}@} -@findex cite - -Use the @code{@@cite} command for the name of a book that lacks a -companion Info file. The command produces italics in the printed -manual, and quotation marks in the Info file. - -If a book is written in Texinfo, it is better to use a cross reference -command since a reader can easily follow such a reference in Info. -@xref{xref, , @code{@@xref}}. - - -@ignore -@c node ctrl, , cite, Indicating -@comment node-name, next, previous, up -@c subsection @code{@@ctrl}@{@var{ctrl-char}@} -@findex ctrl - -The @code{@@ctrl} command is seldom used. It describes an ASCII -control character by inserting the actual character into the Info -file. - -Usually, in Texinfo, you talk what you type as keyboard entry by -describing it with @code{@@kbd}: thus, @samp{@@kbd@{C-a@}} for -@kbd{C-a}. Use @code{@@kbd} in this way when talking about a control -character that is typed on the keyboard by the user. When talking -about a control character appearing in a file or a string, do not use -@code{@@kbd} since the control character is not typed. Also, do not -use @samp{C-} but spell out @code{control-}, as in @samp{control-a}, -to make it easier for a reader to understand.@refill - -@code{@@ctrl} is an idea from the beginnings of Texinfo which may not -really fit in to the scheme of things. But there may be times when -you want to use the command. The pattern is -@code{@@ctrl@{@var{ch}@}}, where @var{ch} is an ASCII character -whose control-equivalent is wanted. For example, to specify -@samp{control-f}, you would enter@refill - -@example -@@ctrl@{f@} -@end example - -@noindent -produces - -@quotation -@ctrl{f} -@end quotation - -In the Info file, this generates the specified control character, output -literally into the file. This is done so a user can copy the specified -control character (along with whatever else he or she wants) into another -Emacs buffer and use it. Since the `control-h',`control-i', and -`control-j' characters are formatting characters, they should not be -indicated with @code{@@ctrl}.@refill - -In a printed manual, @code{@@ctrl} generates text to describe or -identify that control character: an uparrow followed by the character -@var{ch}.@refill -@end ignore - - -@node abbr -@subsection @code{@@abbr}@{@var{abbreviation}[, @var{meaning}]@} -@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{Not 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 <abbr> tag -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 and XML, 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 acronym -@subsection @code{@@acronym}@{@var{acronym}[, @var{meaning}]@} -@findex acronym - -@cindex NASA, as acronym -@cindex Acronyms, tagging -Use the @code{@@acronym} command for abbreviations written in all -capital letters, such as `@acronym{NASA}'. The abbreviation is given as -the single argument in braces, as in @samp{@@acronym@{NASA@}}. As -a matter of style, or for particular 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 <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, Docbook, and XML, 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 - -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 standard English usage, acronyms are a subset of abbreviations: -they include pronounceable words like `@acronym{NATO}', `radar', and -`snafu', and 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's not essential to use these commands for all abbreviations. Text -is perfectly readable without them. - -@end itemize - - -@node indicateurl -@subsection @code{@@indicateurl}@{@var{uniform-resource-locator}@} -@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 analogous to @code{@@file}, -@code{@@var}, etc., and is purely for markup purposes. It does not -produce a link you can follow in HTML output (use the @code{@@uref} -command for that, @pxref{uref,, @code{@@uref}}). It is useful for -url's which do not actually exist. For example: - -@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 - - -@node email -@subsection @code{@@email}@{@var{email-address}[, @var{displayed-text}]@} -@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 -what 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 @TeX{} will typeset -text. These commands have no effect on Info and only one of them, -the @code{@@r} command, has any regular use.@refill - -@menu -* emph & strong:: How to emphasize text in Texinfo. -* Smallcaps:: How to use the small caps font. -* Fonts:: Various font commands for printed output. -@end menu - -@node emph & strong -@subsection @code{@@emph}@{@var{text}@} and @code{@@strong}@{@var{text}@} -@cindex Emphasizing text, font for -@findex emph -@findex strong - -The @code{@@emph} and @code{@@strong} commands are for emphasis; -@code{@@strong} is stronger. In printed output, @code{@@emph} produces -@emph{italics} and @code{@@strong} produces @strong{bold}. - -For example, - -@example -@group -@@strong@{Caution:@} @@samp@{rm * .[^.]*@} -removes @@emph@{all@} files in the directory. -@end group -@end example - -@noindent -produces the following in printed output and HTML: - -@quotation -@strong{Caution}: @samp{rm * .[^.]*} -removes @emph{all} files in the directory. -@end quotation - -@noindent -and the following in Info: - -@example -*Caution:* `rm * .[^.]*' removes _all_ -files in the directory. -@end example - -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. - -In the Info output, @code{@@emph} surrounds the text with underscores -(@samp{_}), and @code{@@strong} puts asterisks around the text. - -@quotation Caution -Do not use @code{@@strong} with the word @samp{Note}; Info will -mistake the combination for a cross reference. (It's usually -redundant, anyway.) 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 lower case, like this: - -@example -Richard @@sc@{Stallman@} founded @@acronym@{GNU@}. -@end example - -@noindent -This produces: - -@display -Richard @sc{Stallman} founded @acronym{GNU}. -@end display - -As shown here, we recommend using @code{@@acronym} for actual -acronyms (@pxref{acronym}), and reserving @code{@@sc} for special -cases where you want small caps. The output is not the same -(@code{@@acronym} prints in a smaller text font, not the small caps -font), but more importantly it describes the actual text more -accurately. - -Family names are one case where small capitals are sometimes desirable, -also as shown here. - -@cindex <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 upper case. In HTML, the argument is -uppercased and the output marked with the @code{<small>} tag to reduce -the font size. - -Since it's redundant to mark all-uppercase text with @code{@@sc}, -@command{makeinfo} warns about such usage. - -We recommend using regular mixed case wherever possible. - - -@node Fonts -@subsection Fonts for Printing, Not Info -@cindex Fonts for printing, not Info - -@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 at all 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{smallbook,,Printing -``Small'' Books}) 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. - -@cindex Styles, font -Texinfo also provides a number of font commands that specify font changes -in the printed manual and (where possible) in the HTML output, but -have no effect in the Info file. All the commands apply to an -argument that follows, 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 an infrequently needed feature.) - -@cindex <lineannotation> Docbook tag -Only the @code{@@r} command has much use: in example-like -environments, you can use the @code{@@r} command 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 - -In general, you should avoid using the other font commands. Some of -them are only useful when documenting 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. -* quotation:: Writing a quotation. -* example:: Writing an example in a fixed-width font. -* verbatim:: Writing a verbatim example. -* verbatiminclude:: Including a file verbatim. -* lisp:: Illustrating Lisp code. -* small:: Examples in a smaller font. -* display:: Writing an example in the current font. -* format:: Writing an example without narrowed margins. -* exdent:: Undo indentation on a line. -* flushleft & flushright:: Pushing text flush left or flush right. -* noindent:: Preventing paragraph indentation. -* indent:: Forcing paragraph indentation. -* cartouche:: Drawing rounded rectangles around examples. -@end menu - - -@node Block Enclosing Commands -@section Block Enclosing Commands - -Here are commands for quotations and examples, 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 @@example -Illustrate code, commands, and the like. 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 @@smallexample -Same as @code{@@example}, except that in @TeX{} this command typesets -text in a smaller font. - -@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 @@smalllisp -Is to @code{@@lisp} as @code{@@smallexample} is to @code{@@example}. - -@item @@display -Display illustrative text. The text is indented but not filled, and -no font is selected (so, by default, the font is roman).@refill - -@item @@smalldisplay -Is to @code{@@display} as @code{@@smallexample} is to @code{@@example}. - -@item @@format -Like @code{@@display} (the text is not filled and no font is selected), -but the text is not indented. - -@item @@smallformat -Is to @code{@@format} as @code{@@smallexample} is to @code{@@example}. -@end table - -The @code{@@exdent} command is used within the above constructs to -undo the indentation of a line. - -The @code{@@flushleft} and @code{@@flushright} commands are used to line -up the left or right margins of unfilled text.@refill - -The @code{@@noindent} command may be used after one of the above -constructs to prevent the following text from being indented as a new -paragraph. - -You can use the @code{@@cartouche} environment around one of the above -constructs to highlight the example or quotation by drawing a box with -rounded corners around it. @xref{cartouche, , Drawing Cartouches Around -Examples}. - - -@node quotation -@section @code{@@quotation}: Block quotations -@cindex Quotations -@findex quotation - -The text of a quotation is processed normally (regular font, text is -filled) except that: - -@itemize @bullet -@item -the margins are closer to the center of the page, so the whole of the -quotation is indented; - -@item -and the first lines of paragraphs are indented no more than other lines. - -@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 exactly one of these words: - -@example -Caution Important Note Tip Warning -@end example - -@cindex <note> Docbook tag -@cindex <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>}. - - -@node example -@section @code{@@example}: Example Text -@cindex Examples, formatting them -@cindex Formatting examples -@findex example - -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{verbatim,,@code{@@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 Emacs, 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{noindent,,@code{@@noindent}}. - -If you want to embed code fragments within sentences, instead of -displaying them, use the @code{@@code} command or its relatives -(@pxref{code,,@code{@@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 verbatim -@section @code{@@verbatim}: Literal Text -@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 a @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 a @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 verbatiminclude -@section @code{@@verbatiminclude} @var{file}: Include a File Verbatim -@cindex Verbatim, include file -@cindex Including a file verbatim -@findex verbatiminclude - -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{verbatim,,@code{@@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{example,,@code{@@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 lisp -@section @code{@@lisp}: Marking a Lisp Example -@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 small -@section @code{@@small@dots{}} Block Commands -@cindex Small examples -@cindex Examples in smaller fonts -@cindex Lisp examples in smaller fonts -@findex smalldisplay -@findex smallexample -@findex smallformat -@findex smalllisp - -In addition to the regular @code{@@example} and @code{@@lisp} commands, -Texinfo has ``small'' example-style commands. These are -@code{@@smalldisplay}, @code{@@smallexample}, @code{@@smallformat}, and -@code{@@smalllisp}. - -In Info, 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. Consequently, -many examples containing long lines fit on a page without needing to -be shortened. - -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{@@small@dots{}} -commands (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 make it easier to prepare manuals -without forcing you to edit examples by hand to fit them onto narrower -pages. - -As a general rule, a printed document looks much better if you use -only one of (for instance) @code{@@example} or @code{@@smallexample} -consistently within a chapter. - - -@node display -@section @code{@@display} and @code{@@smalldisplay} -@cindex Display formatting -@findex display - -The @code{@@display} command begins a kind of example, where each line -of input produces a line of output, and the output is indented. It is -thus like the @code{@@example} command except that, in a printed -manual, @code{@@display} does not select the fixed-width font. In -fact, it does not specify the font at all, so that the text appears in -the same font it would have appeared in without the @code{@@display} -command. - -@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 a command @code{@@smalldisplay}, which is like -@code{@@display} but uses a smaller font in @code{@@smallbook} format. -@xref{small}. - -The @code{@@table} command (@pxref{table}) does not work 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{quotation}). - - -@node format -@section @code{@@format} and @code{@@smallformat} -@findex format - -The @code{@@format} command is similar to @code{@@example} except -that, in the printed manual, @code{@@format} does not select the -fixed-width font and does not narrow the margins.@refill - -@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 a command @code{@@smallformat}, which is like -@code{@@format} but uses a smaller font in @code{@@smallbook} format. -@xref{small}. - - - -@node exdent -@section @code{@@exdent}: Undoing a Line's Indentation -@cindex Indentation undoing -@findex exdent - -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.@refill - -@code{@@exdent} is usually used within examples. Thus,@refill - -@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.@refill - - -@node flushleft & flushright -@section @code{@@flushleft} and @code{@@flushright} -@findex flushleft -@findex flushright -@cindex Ragged right -@cindex Ragged left - -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.@refill - -@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 noindent -@section @code{@@noindent}: Omitting Indentation -@cindex Omitting indentation -@cindex Suppressing indentation -@cindex Indentation, omitting -@findex noindent - -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{paragraphindent, Paragraph Indenting}). - -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 indent -@section @code{@@indent}: Forcing Indentation -@cindex Forcing indentation -@cindex Inserting indentation -@cindex Indentation, forcing -@findex indent - -@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{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 cartouche -@section @code{@@cartouche}: Rounded Rectangles Around Examples -@findex cartouche -@cindex Box with rounded corners -@cindex Rounded rectangles, around examples - -In a printed manual, the @code{@@cartouche} command draws a box with -rounded corners around its contents. In HTML, a normal rectangle is -drawn (that's the best HTML can do). @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/emacs -@@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 - -For proper output in HTML, it's necessary to put the -@code{@@cartouche} around the @code{@@example}, and not the other way -around. This limitation of @command{makeinfo} may be removed one day. - -@code{@@cartouche} also implies @code{@@group} (@pxref{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. -* itemize:: How to construct a simple list. -* 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.@refill - -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.@refill - -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.@refill -@findex end - -Precede each element of a list with an @code{@@item} or @code{@@itemx} -command.@refill - -@sp 1 -@noindent -Here is an itemized list of the different kinds of table and lists:@refill - -@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:@refill - -@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}:@refill - -@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 itemize -@section @code{@@itemize}: Making an Itemized List -@cindex Itemization -@findex itemize - -The @code{@@itemize} command produces sequences of indented -paragraphs, with a bullet or other mark inside the left margin -at the beginning of each paragraph for which such a mark is desired.@refill - -@cindex @code{@@w}, for blank items -Begin an itemized list by writing @code{@@itemize} at the beginning of -a line. Follow the command, on the same line, with a character or a -Texinfo command that generates a mark. Usually, you will write -@code{@@bullet} after @code{@@itemize}, but you can use -@code{@@minus}, or any command or character that results in a single -character in the Info file. If you don't want any mark at all, use -@code{@@w}. (When you write the mark command such as -@code{@@bullet} after an @code{@@itemize} command, you may omit the -@samp{@{@}}.) If you don't specify a mark command, the default is -@code{@@bullet}. - -Write the text of the indented paragraphs themselves after the -@code{@@itemize}, up to another line that says @code{@@end -itemize}.@refill - -@findex item -At the beginning of each paragraph for which a mark in the margin is -desired, write a line that starts with @code{@@item}. It is ok to -have text following the @code{@@item}. - -Usually, you should put a blank line before an @code{@@item}. This -puts a blank line in the Info file. (@TeX{} inserts the proper -interline whitespace in either case.) Except when the entries are -very brief, these blank lines make the list look better.@refill - -Here is an example of the use of @code{@@itemize}, followed by the -output it produces. @code{@@bullet} produces an @samp{*} in Info and a -round dot in @TeX{}. - -@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:@refill - -@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 enumerate -@section @code{@@enumerate}: Making a Numbered or Lettered List -@cindex Enumeration -@findex enumerate - -@code{@@enumerate} is like @code{@@itemize} (@pxref{itemize,, -@code{@@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 lower case 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 paragraph that you want enumerated. It is ok to have text -following the @code{@@item}. - -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}:@refill -@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}.@refill -@sp 1 -@enumerate a -@item -@code{@@enumerate} - -Without an argument, produce a numbered list, starting with the number -1.@refill - -@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.@refill - -@item -@code{@@enumerate @var{upper-case-letter}} - -With an upper case letter as argument, start a list -in which each item is marked -by a letter, beginning with that upper case letter.@refill - -@item -@code{@@enumerate @var{lower-case-letter}} - -With a lower case letter as argument, start a list -in which each item is marked by -a letter, beginning with that lower case letter.@refill -@end enumerate - -You can also nest enumerated lists, as in an outline.@refill - -@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{itemize,, -@code{@@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 -* table:: How to construct a two-column table. -* ftable vtable:: Automatic indexing for two-column tables. -* itemx:: How to put more entries in the first column. -@end menu - -@node table -@subsection Using the @code{@@table} Command - -@cindex Definition lists, typesetting -Use the @code{@@table} command to produce two-column tables. It is -usually listed for ``definition lists'' of various sorts, where you -have a list of terms and a brief text with each one. - -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 @code{@@code} command. - -@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 commands that -normally take arguments in braces. (In this case, however, you use -the command name without an argument, because the subsequent -@code{@@item}'s will supply the argument.) - -@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. -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{itemx,,@code{@@itemx}}.) - - -@node ftable vtable -@subsection @code{@@ftable} and @code{@@vtable} -@cindex Tables with indexes -@cindex Indexing table entries automatically -@findex ftable -@findex vtable - -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.@refill - -Begin a two-column table using @code{@@ftable} or @code{@@vtable} by -writing the @@-command at the beginning of a line, followed on the same -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 itemx -@subsection @code{@@itemx} -@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 upper case (lower -case) 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 upper case (lower -case) character or string.@refill -@end table - -@noindent -(Note also that this example illustrates multi-line supporting text in -a two-column table.)@refill - - -@node Multi-column Tables -@section @code{@@multitable}: Multi-column Tables -@cindex Tables, making multi-column -@findex multitable - -@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 <thead> HTML 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, XML, and Docbook output uses the @code{<thead>} tag. In -Info, the heading row is followed by a separator line made of dashes -(@samp{-} characters). - -Here is a complete example of a multi-column table (the text is from -@cite{The GNU Emacs Manual}, @pxref{Split Window,, Splitting Windows, -emacs, The GNU Emacs 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 labelled 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{group,,@code{@@group}}). - -@menu -* float:: Producing floating material. -* caption shortcaption:: Specifying descriptions for floats. -* listoffloats:: A table of contents for floats. -@end menu - - -@node float -@subsection @code{@@float} [@var{type}][,@var{label}]: Floating Material -@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 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 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{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 Normally, 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 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} are numbered, or outside of any -chapter, are simply numbered consecutively from 1. - -These numbering conventions are not, at present, changeable. - - -@node caption shortcaption -@subsection @code{@@caption} & @code{@@shortcaption} -@findex caption -@findex shortcaption -@cindex Captions, for floats -@cindex Short captions, for lists of floats - -You may write an @code{@@caption} anywhere within a @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{@@caption} and @code{@@shortcaption} may not -contain comments (@code{@@c}), verbatim text (@code{@@verb}), -environments such as @code{@@example}, or other complex constructs. - - -@node listoffloats -@subsection @code{@@listoffloats}: Tables of Contents for Floats -@findex listoffloats -@cindex List of floats -@cindex Floats, list of -@cindex Table of contents, for floats - -You can write a @code{@@listoffloats} command to generate a list of -floats for a given float type (@pxref{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{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{} 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}.png}, @file{@var{filename}.jpg}, -@file{@var{filename}.jpeg}, or @file{@var{filename}.pdf} (in that -order). It also tries uppercase versions of the extensions. The PDF -format cannot support EPS images, so they must be converted first. -@item -@code{makeinfo} includes @file{@var{filename}.txt} verbatim for -Info output (more or less as if it was an @code{@@example}). -@item -@code{makeinfo} uses the optional fifth argument @var{extension} to -@code{@@image} for the filename extension, if it is specified. For example: - -@pindex XPM image format -@example -@@image@{foo,,,,.xpm@} -@end example - -@noindent -will cause @code{makeinfo} to look for @file{foo.xpm} before any others. - -@end itemize - -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{titlefont center sp,,@code{@@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 -taken as Texinfo text, so special characters such as @samp{"} and -@samp{<} and @samp{&} are escaped in the HTML and XML output; also, -you can get an empty @code{alt} string with @code{@@-} (a command -that produces no output; @pxref{- and 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. - -@cindex PNG image format -@cindex JPEG image format -If you do not supply the optional @var{extension} (fifth) argument, -@code{makeinfo} first tries @file{@var{filename}.png}; if that does -not exist, it tries @file{@var{filename}.jpg}. If that does not exist -either, it complains. - -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 -Emacs Info browser, running under X) can do so, whereas Info readers -which can only use text (such as the standalone Info reader) can -display the textual version. - -@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 -scale the image to. They are ignored for Info output. If neither is -specified, the image is presented in its natural size (given in the -file); if only one is specified, the other is scaled proportionately; -and if both are specified, both are respected, thus possibly distorting -the original image by changing its aspect ratio. - -@cindex Dimensions and image sizes -The @var{width} and @var{height} may be specified using any valid @TeX{} -dimension, namely: - -@table @asis -@item pt -@cindex Points (dimension) -point (72.27pt = 1in) -@item pc -@cindex Picas -pica (1pc = 12pt) -@item bp -@cindex Big points -big point (72bp = 1in) -@item in -@cindex Inches -inch -@item cm -@cindex Centimeters -centimeter (2.54cm = 1in) -@item mm -@cindex Millimeters -millimeter (10mm = 1cm) -@item dd -@cindex Did@^ot points -did@^ot point (1157dd = 1238pt) -@item cc -@cindex Ciceros -cicero (1cc = 12dd) -@item sp -@cindex Scaled points -scaled point (65536sp = 1pt) -@end table - -@pindex ridt.eps -For example, the following will scale a file @file{ridt.eps} to one -inch vertically, with the width scaled proportionately: - -@example -@@image@{ridt,,1in@} -@end example - -@pindex epsf.tex -For @code{@@image} to work with @TeX{}, the file @file{epsf.tex} must be -installed somewhere that @TeX{} can find it. (The standard location is -@file{@var{texmf}/tex/generic/dvips/epsf.tex}, where @var{texmf} is a -root of your @TeX{} directory tree.) This file is included in the -Texinfo distribution and is 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, if at all. Standard bibliographical references are better -placed in a bibliography at the end of a document than 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's -text. - -In the HTML output, footnote references are 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 a -@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 a single footnote in the end of node style:@refill - -@example -@group ---------- Footnotes --------- - -(1) Here is a sample footnote. -@end group -@end example - -@cindex @samp{@r{Separate}} footnote style -@item -In the `Separate' node style, all the footnotes for a single -node are placed in an automatically constructed node of -their own. In this style, a ``footnote reference'' follows -each @samp{(@var{n})} reference mark in the body of the -node. The footnote reference is actually a cross reference -which you use to reach the footnote node. - -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. (If you -include the @code{@@footnotestyle} command between the start-of-header -and end-of-header lines, the region formatting commands will format -footnotes as specified.)@refill - -If you do not specify a footnote style, the formatting commands use -their default style. Currently, @code{texinfo-format-buffer} and -@code{texinfo-format-region} use the `separate' style and -@code{makeinfo} uses the `end' style. - - -@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 the word ``Index'' is 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.@refill - -Like typesetting, the construction of an index is a highly skilled, -professional art, the subtleties of which are not appreciated until you -need to do it yourself.@refill - -@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.@refill - - -@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 -(@code{@@cindex}) concept index, for general concepts. -@item fn -@cindex @code{fn} (function) index -(@code{@@findex}) function index, for function and function-like -names (such as entry points of libraries). -@item ky -@cindex @code{ky} (keystroke) index -(@code{@@kindex}) keystroke index, for keyboard commands. -@item pg -@cindex @code{pg} (program) index -(@code{@@pindex}) program index, for names of programs. -@item tp -@cindex @code{tp} (data type) index -(@code{@@tindex}) data type index, for type names (such as structures -defined in header files). -@item vr -@cindex @code{vr} (variable) index -(@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.@refill - -An index entry consists of an indexing command at the beginning of a -line followed, on the rest of the line, by the entry.@refill - -For example, this section begins with the following five entries for -the concept index:@refill - -@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 entry writing -Concept index entries consist of text. The best way to write an index -is to choose entries that are terse yet clear. If you can do this, -the index often looks better if the entries are not capitalized, but -written just as they would appear in the middle of a sentence. -(Capitalize proper names and acronyms that always call for upper case -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. But do not capitalize a -case-sensitive name such as a C or Lisp function name or a shell -command; that would be a spelling error. - -Whichever case convention you use, please use it consistently! - -Entries in indices other than the concept index are symbol names in -programming languages, or program names; these names are usually -case-sensitive, so use upper and lower case as required for them. - -@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 -* syncodeindex:: How to merge two indices, using @code{@@code} - font for the merged-from index. -* synindex:: How to merge two indices, using the - default font of the merged-to index. -@end menu - -@node syncodeindex -@subsection @code{@@syncodeindex} -@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.@refill - -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:@refill - -@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:@refill - -@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:@refill - -@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.@refill - -To merge both a variables index and a function index into a concept -index, write the following:@refill - -@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.@refill - -@node synindex -@subsection @code{@@synindex} -@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.@refill - -@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.@refill - - -@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, 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 - -The name of an index should be a two letter word, 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''.) - -In general, 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}). - - -@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 @samp{@@} and braces and commas. -@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 evaluation, macros, errors, etc. -@item Footnotes. -@item Images. -@end itemize -@end iftex - -@menu -* Atsign Braces Comma:: Inserting @@ and @{@} and ,. -* Inserting Quote Characters:: Inserting left and right quotes, in code. -* Inserting Space:: How to insert the right amount of space - within a sentence. -* Inserting Accents:: How to insert accents and special characters. -* Inserting Quotation Marks:: How to insert quotation marks. -* Dots Bullets:: How to insert dots and bullets. -* TeX and copyright:: How to insert the @TeX{} logo - and the copyright symbol. -* euro:: How to insert the Euro currency symbol. -* pounds:: How to insert the pounds currency symbol. -* textdegree:: How to insert the degrees symbol. -* minus:: How to insert a minus sign. -* geq leq:: How to insert greater/less-than-or-equal signs. -* math:: How to format a mathematical expression. -* Click Sequences:: Inserting GUI usage sequences. -* Glyphs:: How to indicate results of evaluation, - expansion of macros, errors, etc. -@end menu - - -@node Atsign Braces Comma -@section Inserting @@ and @{@} and @comma{} -@cindex Special characters, inserting -@cindex Commands to insert special characters - -@samp{@@} and curly braces are 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. - -The comma `,' is a special character only in one uncommon context: -it separates arguments to commands that take multiple arguments. - -@menu -* Inserting an Atsign:: -* Inserting Braces:: -* Inserting a Comma:: -@end menu - - -@node Inserting an Atsign -@subsection Inserting `@@' with @code{@@@@} -@findex @@ @r{(literal @samp{@@})} -@cindex Inserting @@ @r{(literal @samp{@@})} - -@code{@@@@} stands for a single @samp{@@} in either printed or Info -output. - -Do not put braces after an @code{@@@@} command. - - -@node Inserting Braces -@subsection Inserting `@{' and `@}' with @code{@@@{} and @code{@@@}} -@cindex Braces, inserting -@findex @{ @r{(literal @samp{@{})} -@findex @} @r{(literal @samp{@}})} - -@code{@@@{} stands for a single @samp{@{} in either printed or Info -output. - -@code{@@@}} stands for a single @samp{@}} in either printed or Info -output. - -Do not put braces after either an @code{@@@{} or an @code{@@@}} -command. - - -@node Inserting a Comma -@subsection Inserting `,' with @code{@@comma@{@}} -@cindex Commas, inserting -@findex comma - -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 in one uncommon -context: some commands, such as @code{@@acronym} (@pxref{acronym}) and -@code{@@xref} (@pxref{Cross References}), as well as user-defined -macros (@pxref{Defining Macros}), can take more than one argument. In -these cases, the comma character is used to separate arguments. - -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 @comma{} can be used nearly anywhere, there is no need for it -anywhere except in 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 your document, Texinfo provides two special -settings via @code{@@set}: - -@table @code -@item @@set txicodequoteundirected -causes the output for the @code{'} character to be the undirected -single quote, like this: -@set txicodequoteundirected -@code{'}. -@clear txicodequoteundirected - -@item @@set txicodequotebacktick -Cause the output for the @code{`} character to be the standalone grave -accent, like this: -@set txicodequotebacktick -@code{`}. -@clear txicodequotebacktick - -@end table - -@code{xyza`'bc} - -If you want these settings for only part of the document, -@code{@@clear} will restore the normal behavior, as in -@code{@@clear@tie{}txicodequoteundirected}. - -These settings affect @code{@@code}, @code{@@example}, and -@code{@@verbatim}; they do not affect @code{@@samp}. (@xref{Useful -Highlighting}.) - - -@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 -* Not Ending a Sentence:: Sometimes a . doesn't end a sentence. -* Ending a Sentence:: Sometimes it does. -* Multiple Spaces:: Inserting multiple spaces. -* frenchspacing:: Specifying end-of-sentence spacing. -* dmn:: How to format a dimension. -@end menu - - -@node Not Ending a Sentence -@subsection Not Ending a Sentence - -@cindex Not ending a sentence -@cindex Sentence non-ending punctuation -@cindex Periods, inserting -Depending on whether a period or exclamation point or question mark is -inside or at the end of a sentence, less or more space is inserted after -a period in a typeset manual. Since it is not always possible -to determine when a period ends a sentence and when it is used -in an abbreviation, special commands are needed in some circumstances. -Usually, Texinfo can guess how to handle periods, so you do not need to -use the special commands; you just enter a period as you would if you -were using a typewriter, which means you put two spaces after the -period, question mark, or exclamation mark that ends a sentence. - -@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 abbreviations -which are not at the ends of sentences. - -For example, - -@example -foo vs.@@: bar -foo vs. bar -@end example - -@noindent -@ifnottex -produces -@end ifnottex -@iftex -produces the following. If you look carefully at this printed output, -you will see a little extraneous space after @samp{vs.}@: in the second -line. -@end iftex - -@quotation -foo vs.@: bar @* -foo vs. bar -@end quotation - -@noindent -@code{@@:} has no effect on the Info and HTML output. In Docbook and -XML, the previous punctuation character (.?!:) is output as an entity -instead of as the normal character: @samp{. ? ! -:}. This gives further processors a chance to notice and not -add the usual extra space. - -Do not put braces after @code{@@:} (or any non-alphabetic command). - - -@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)} -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 ends with a capital letter. Otherwise, @TeX{} -will think the letter is an abbreviation and will not insert the correct -end-of-sentence spacing. Here is an 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 -@ifnottex -produces -@end ifnottex -@iftex -produces the following. If you look carefully at this printed output, -you will see a little more whitespace after the @samp{W} in the first -line. -@end iftex - -@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 Info file output, @code{@@.}@: is equivalent to a simple -@samp{.}; likewise for @code{@@!}@: and @code{@@?}@:. - -The meanings of @code{@@:} and @code{@@.}@: in Texinfo are designed to -work well with the Emacs sentence motion commands (@pxref{Sentences,,, -emacs, The GNU Emacs Manual}). - -Do not put braces after any of these commands. - - -@node Multiple Spaces -@subsection Multiple Spaces - -@cindex Multiple spaces -@cindex Whitespace, inserting -@cindex Space, inserting horizontal -@findex <space> -@findex <tab> -@findex <newline> - -Ordinarily, @TeX{} collapses multiple whitespace characters (space, tab, -and newline) into a single space. Info output, on the other hand, -preserves whitespace as you type it, except for changing a newline into -a space; this is why it is important to put two spaces at the end of -sentences in Texinfo documents. - -Occasionally, you may want to actually insert several consecutive -spaces, either for purposes of example (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{@@ }, and @kbd{TAB} 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{tie, @code{@@tie}}. - - -@node frenchspacing -@subsection @code{@@frenchspacing} @var{val}: Control sentence spacing -@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, after a semi-colon, and so on. This -is the default in Texinfo. In French typography (and many 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 (there will be no difference in Info): - -@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} mainly affects the printed output, including -the output after @code{@@.}, @code{@@!}, and @code{@@?} (@pxref{Ending -a Sentence}). - -In Info, usually space characters in the input are written unaltered -to the output, and @code{@@frenchspacing} does not change this. It -does change the one case where @command{makeinfo} outputs a space on -its own: when a sentence ends at a newline in the source. Here's an -example: - -@example -Some sentence. -Next sentence. -@end example - -@noindent produces in Info output, with @code{@@frenchspacing off} -(the default), two spaces between the sentences: - -@example -Some sentence. Next sentence. -@end example - -@noindent With @code{@@frenchspacing on}, @command{makeinfo} outputs -only a single space: - -@example -Some sentence. Next sentence. -@end example - -@code{@@frenchspacing} has no effect on the HTML or Docbook output; -for XML, it outputs a transliteration of itself (@pxref{Output -Formats}). - - -@node dmn -@subsection @code{@@dmn}@{@var{dimension}@}: Format a Dimension -@cindex Thin space between number, dimension -@cindex Dimension formatting -@cindex Format a dimension -@findex dmn - -At times, you may want to write @samp{12@dmn{pt}} or -@samp{8.5@dmn{in}} with little or no space between the number and the -abbreviation for the dimension. You can use the @code{@@dmn} command -to do this. On seeing the command, @TeX{} inserts just enough space -for proper typesetting; the Info formatting commands insert no space -at all, since the Info file does not require it. - -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 @w{@samp{8.27 in.@@:}} -or @w{@samp{8.27 inches}} to @samp{8.27@@dmn@{in@}} in the Texinfo file. -In these cases, however, the formatters may insert a line break between -the number and the dimension, so use @code{@@w} (@pxref{w}). Also, if -you write a period after an abbreviation within a sentence, you should -write @samp{@@:} after the period to prevent @TeX{} from inserting extra -whitespace, as shown here. @xref{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. The commands with non-alphabetic names do not take -braces around their argument (which is taken to be the next character). -(Exception: @code{@@,} @emph{does} take braces around its argument.) -This is so as to make the source as convenient to type and read as -possible, since accented characters are very common in some languages. - -@findex documentencoding -To get the true accented characters output in Info, and not just the -ASCII transliterations, it is necessary to specify -@code{@@documentencoding} with an encoding which supports the required -characters (@pxref{documentencoding,,@code{@@documentencoding}}). - -@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 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{@@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{} -@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 -@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{@@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 -@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{documentencoding,,@code{@@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 `` -@findex quoteleft -@cindex ` -@findex quotedblright -@cindex '' -@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 - -For the double angle quotation marks, Adobe and @LaTeX{} glyph names -are also supported: @code{@@guillemotleft} and -@code{@@guillemotright}. These names are actually 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{alias,,@code{@@alias}}) can simplify the usage and -make the source code more readable. For example, in German, -@code{@@quotedblbase} is used for the left double quote, and the right -double quote is actually @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 Dots Bullets -@section Inserting Ellipsis and Bullets -@cindex Dots, inserting -@cindex Bullets, inserting -@cindex Ellipsis, inserting -@cindex Inserting ellipsis -@cindex Inserting dots -@cindex Special typesetting commands -@cindex Typesetting commands for dots, etc. - -An @dfn{ellipsis} (a line of dots) is not typeset as a string of -periods, so a special command is used for ellipsis in Texinfo. The -@code{@@bullet} command is special, too. Each of these commands is -followed by a pair of braces, @samp{@{@}}, without any whitespace -between the name of the command and the braces. (You need to use braces -with these commands because you can use them next to other text; without -the braces, the formatters would be confused. @xref{Command Syntax, , -@@-Command Syntax}, for further information.)@refill - -@menu -* dots:: How to insert dots @dots{} -* bullet:: How to insert a bullet. -@end menu - - -@node dots -@subsection @code{@@dots}@{@} (@dots{}) and @code{@@enddots}@{@} (@enddots{}) -@findex dots -@findex enddots -@cindex Inserting dots -@cindex Dots, inserting - -Use the @code{@@dots@{@}} command to generate an ellipsis, which is -three dots in a row, appropriately spaced @dots{} like so. 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. - -Similarly, the @code{@@enddots@{@}} command generates an -end-of-sentence ellipsis, which has different spacing afterwards, -@enddots{} Look closely to see the difference. - -@iftex -Here is an ellipsis: @dots{} -Here are three periods in a row: ... - -In printed output, the three periods in a row are much closer together than -the dots in the ellipsis. -@end iftex - - -@node bullet -@subsection @code{@@bullet}@{@} (@bullet{}) -@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.@refill - -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. -(@xref{itemize, , @code{@@itemize}}.)@refill - - -@node TeX and copyright -@section Inserting @TeX{} and Legal Symbols: @copyright{}, @registeredsymbol{} - -The logo `@TeX{}' is typeset in a special fashion and it needs an -@@-command. The copyright and registered symbols, `@copyright{}' and -`@registeredsymbol{}', is also special. Each of these commands is -followed by a pair of braces, @samp{@{@}}, without any whitespace -between the name of the command and the braces. - -@menu -* tex:: The @TeX{} logos. -* copyright symbol:: The copyright symbol (c in a circle). -* registered symbol:: The registered symbol (R in a circle). -@end menu - - -@node tex -@subsection @code{@@TeX}@{@} (@TeX{}) and @code{@@LaTeX}@{@} (@LaTeX{}) -@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 among Texinfo commands in -that they use both uppercase and lowercase letters. - - -@node copyright symbol -@subsection @code{@@copyright@{@}} (@copyright{}) -@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)}. - - -@node registered symbol -@subsection @code{@@registeredsymbol@{@}} (@registeredsymbol{}) -@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 euro -@section @code{@@euro}@{@} (@euro{}): Euro Currency Symbol -@findex euro -@cindex Euro symbol - -Use the @code{@@euro@{@}} command to generate `@euro{}'. Where -possible, this is the symbol for the Euro currency, invented as part -of the European economic unification. In plain Info, it is the word -@samp{Euro }. A trailing space is included in the text -transliteration since typically no space is desired after the symbol, -so it would be inappropriate to have a space in the source document. - -Texinfo cannot magically synthesize support for the Euro symbol where -the underlying system (fonts, software, whatever) does not support -it. Therefore, in many cases it is preferable to use the word -``Euro''. (In banking circles, the abbreviation for the Euro is EUR.) - -@cindex ISO 8859-15 -@cindex Latin 9 -In order to get the Euro symbol in encoded Info output, for example, -it is necessary to specify @code{@@documentencoding ISO-8859-15}. -(@xref{documentencoding,,@code{@@documentencoding}}.) The Euro symbol -is in ISO 8859-15 (aka Latin@tie{}9), and is @emph{not} in the more -widely-used and supported 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 pounds -@section @code{@@pounds}@{@} (@pounds{}): Pounds Sterling -@findex pounds -@cindex Pounds symbol - -Use the @code{@@pounds@{@}} command to generate `@pounds{}'. Where -possible, this is the symbol for the currency pounds sterling. In -Info, it is a @samp{#}. - - -@node textdegree -@section @code{@@textdegree}@{@} (@textdegree{}): Degrees Symbol -@findex textdegree -@cindex Degree symbol - -Use the @code{@@textdegree@{@}} command to generate `@textdegree{}'. -Where possible, this is the normal symbol for degrees. In plain text -and Info output, it is an @samp{o}. - - -@node minus -@section @code{@@minus}@{@} (@minus{}): Inserting a Minus Sign -@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{itemize, , @code{@@itemize}}). - - -@node geq leq -@section @code{@@geq@{@}} (@geq{}) and @code{@@leq@{@}} (@leq{}): Inserting relations -@findex geq -@findex leq - -Use the @code{@@geq@{@}} and @code{@@geq@{@}} commands to generate -greater-than-or-equal and less-than-equal-signs, `@geq{}' and -`@leq{}'. In plain text and Info output, these are the ASCII -sequences @samp{>=} and @samp{<=}. - - -@node math -@section @code{@@math}: Inserting Mathematical Expressions -@findex math -@cindex Mathematical expressions -@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 @code{@@}-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, input with matching (but unescaped) braces, such as -@samp{k_@{75@}}, is allowed inside @code{@@math}, although -@command{makeinfo} would complain about the 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 @samp{\\} in Info). @code{@@\} is not -defined outside of @code{@@math}, since a @samp{\} ordinarily produces a -literal @samp{\}. - -@cindex Displayed equations -@cindex Equations, displayed -For displayed equations, you must at present use @TeX{} directly -(@pxref{Raw Formatter Commands}). - - -@node Click Sequences -@section 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 simple right arrow (@samp{->} in -Info) 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{itemize,,@code{@@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 Glyphs -@section Glyphs for Examples -@cindex Glyphs -@cindex Examples, 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, and the -location of point. - -The glyph-insertion commands do not need to be used within an example, but -most often they are. Every glyph-insertion command is followed by a pair of -left- and right-hand braces.@refill - -@menu -* Glyphs Summary:: -* result:: How to show the result of expression. -* expansion:: How to indicate an expansion. -* Print Glyph:: How to indicate printed output. -* Error Glyph:: How to indicate an error message. -* Equivalence:: How to indicate equivalence. -* Point Glyph:: How to indicate the location of point. -@end menu - - -@node Glyphs Summary -@subsection Glyphs Summary - -Here are the different glyph commands:@refill - -@table @asis -@item @result{} -@code{@@result@{@}} points to the result of an expression.@refill - -@item @expansion{} -@code{@@expansion@{@}} shows the results of a macro expansion.@refill - -@item @print{} -@code{@@print@{@}} indicates printed output.@refill - -@item @error{} -@code{@@error@{@}} indicates that the following text is an error -message.@refill - -@item @equiv{} -@code{@@equiv@{@}} indicates the exact equivalence of two forms.@refill - -@item @point{} -@code{@@point@{@}} shows the location of point.@refill -@end table - -@menu -* result:: -* expansion:: -* Print Glyph:: -* Error Glyph:: -* Equivalence:: -* Point Glyph:: -@end menu - - -@node result -@subsection @code{@@result@{@}} (@result{}): Indicating Evaluation -@cindex Result of an expression -@cindex Indicating evaluation -@cindex Evaluation glyph -@cindex Value of an expression, indicating -@findex result - -Use the @code{@@result@{@}} command to indicate the result of -evaluating an expression.@refill - -@iftex -The @code{@@result@{@}} command is displayed as @samp{@result{}} in -the printed output and as @samp{=>} in other formats. -@end iftex -@ifnottex -The @code{@@result@{@}} command is displayed as @samp{@result{}} in -Info and HTML and as a true double stemmed arrow in the printed output. -@end ifnottex - -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 expansion -@subsection @code{@@expansion@{@}} (@expansion{}): Indicating an Expansion -@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.@refill - -@iftex -The @code{@@expansion@{@}} command is displayed as @samp{@expansion{}} -in the printed output and as @samp{==>} in other formats. -@end iftex -@ifnottex -The @code{@@expansion@{@}} command is displayed as @samp{@expansion{}} -in Info and HTML, and as a long arrow with a flat base in the printed -output. -@end ifnottex - -@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 Print Glyph -@subsection @code{@@print@{@}} (@print{}): Indicating Printed Output -@cindex Printed output, indicating -@findex print - -Sometimes an expression will print output during its execution. You -can indicate the printed output with the @code{@@print@{@}} command.@refill - -@iftex -The @code{@@print@{@}} command is displayed as @samp{-|} in Info and -HTML and as @samp{@print{}} in the printed output. -@end iftex -@ifnottex -The @code{@@print@{@}} command is displayed as @samp{@print{}} in Info -and HTML and (similarly) as a horizontal dash butting against a -vertical bar in the printed output. -@end ifnottex - -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 Error Glyph -@subsection @code{@@error@{@}} (@error{}): Indicating an Error Message -@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.@refill - -@iftex -The @code{@@error@{@}} command is displayed as @samp{error-->} in Info -and HTML and as @samp{@error{}} in the printed output. -@end iftex -@ifnottex -The @code{@@error@{@}} command is displayed as @samp{@error{}} in Info -and HTML and as the word `error' in a box in the printed output. -@end ifnottex - -@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 - -@samp{@error{}} itself is not part of the error message. - - -@node Equivalence -@subsection @code{@@equiv@{@}} (@equiv{}): Indicating Equivalence -@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.@refill - -@iftex -The @code{@@equiv@{@}} command is displayed as @samp{==} in Info and -HTML and as @samp{@equiv{}} in the printed output. -@end iftex -@ifnottex -The @code{@@equiv@{@}} command is displayed as @samp{@equiv{}} in Info -and HTML and as a standard mathematical equivalence sign (three -parallel horizontal lines) in the printed output. -@end ifnottex - -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 Point Glyph -@subsection @code{@@point@{@}} (@point{}): Indicating Point in a Buffer -@cindex Point, indicating in a buffer -@findex point - -Sometimes you need to show an example of text in an Emacs buffer. In -such examples, the convention is to include the entire contents of the -buffer in question between two lines of dashes containing the buffer -name.@refill - -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.)@refill - -@iftex -The @code{@@point@{@}} command is displayed as @samp{-!-} in Info and -HTML and as @samp{@point{}} in the printed output. -@end iftex -@ifnottex -The @code{@@point@{@}} command is displayed as @samp{@point{}} in Info -and HTML and as a small five pointed star in the printed -output. -@end ifnottex - -The following example shows the contents of buffer @file{foo} before -and after evaluating a Lisp command to insert the word @code{changed}.@refill - -@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:@refill - -@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 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 -Usually, a Texinfo file is processed both by @TeX{} and by one of the -Info formatting commands. Line, paragraph, or page breaks sometimes -occur in the `wrong' place in one or other form of output. You must -ensure that text looks right both in the printed manual and in the -Info file. - -@cindex White space, excessive -@cindex Page breaks -For example, in a printed manual, page breaks may occur awkwardly in -the middle of an example; to prevent this, you can hold text together -using a grouping command that keeps the text from being split across -two pages. Conversely, you may want to force a page break where none -would occur normally. Fortunately, problems like these do not often -arise. When they do, use the break, break prevention, or pagination -commands. - -@menu -* Break Commands:: Summary of break-related commands. -* Line Breaks:: Forcing line breaks. -* - and hyphenation:: Helping @TeX{} with hyphenation points. -* allowcodebreaks:: Controlling line breaks within @@code text. -* w:: Preventing unwanted line breaks in text. -* tie:: Inserting an unbreakable but varying space. -* sp:: Inserting blank lines. -* page:: Forcing the start of a new page. -* group:: Preventing unwanted page breaks. -* 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 -@iftex -@sp 1 -@end iftex - -The pagination commands apply only to printed output, since Info -files do not have pages. - -@table @code -@item @@page -Start a new page in the printed manual. - -@item @@group -Hold text together that must appear on one printed page. - -@item @@need @var{mils} -Start a new printed 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 -@cindex Breaks in a line -@cindex Force line break -@cindex Allow line break - -The @code{@@*} command forces a line break in both the printed manual and -in Info. The @code{@@/} command allows a line break (printed manual only). - -Here is an example with @code{@@*}: - -@example -This line @@* is broken @@*in two places. -@end example - -@noindent produces - -@example -@group -This line -is broken -in two places. -@end group -@end example - -The @code{@@/} command can be useful within a url -(@pxref{uref,,@code{@@uref}}), 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 - -@display -The official Texinfo home page is on the GNU web site: -@uref{http://www.gnu.org/@/software/@/gnu/@/texinfo}. -@end display - -@noindent Without the @code{@@/} commands, @TeX{} would have nowhere to -break the line. @code{@@/} has no effect in the online output. - - -@node - and hyphenation -@section @code{@@-} and @code{@@hyphenation}: Helping @TeX{} Hyphenate - -@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 allowcodebreaks -@section @code{@@allowcodebreaks}: Control Line Breaks in @code{@@code} - -@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{} will consider breaking lines at @samp{-} and -@samp{_} characters within @code{@@code} and related commands -(@pxref{code,,@code{@@code}}), more or less as if they were ``empty'' -hyphenation points. - -This is necessary as many manuals, especially for Lisp-family -languages, must document very long identifiers. On the other hand, -other 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 @TeX{} 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 in Info, HTML, and other non-@TeX{} output. - - -@node w -@section @code{@@w}@{@var{text}@}: Prevent Line Breaks -@findex w @r{(prevent line break)} -@cindex Line breaks, preventing - -@code{@@w@{@var{text}@}} outputs @var{text} and prohibits line breaks -within @var{text}, for both @TeX{} and @command{makeinfo}. - -@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); 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$}. - - -@node tie -@section @code{@@tie@{@}}: Inserting an Unbreakable Space -@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 sp -@section @code{@@sp} @var{n}: Insert Blank Lines -@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.@refill - -@ignore -@c node br, page, sp, Breaks -@comment node-name, next, previous, up -@c section @code{@@br}: Generate Paragraph Breaks -@findex br @r{(paragraph breaks)} -@cindex Paragraph breaks -@cindex Breaks in a paragraph - -The @code{@@br} command forces a paragraph break. It inserts a blank -line. You can use the command within or at the end of a line. If -used within a line, the @code{@@br@{@}} command must be followed by -left and right braces (as shown here) to mark the end of the -command.@refill - -@need 700 -For example, - -@example -@group -This line @@br@{@}contains and is ended by paragraph breaks@@br -and is followed by another line. -@end group -@end example - -@noindent -produces - -@example -@group -This line - -contains and is ended by paragraph breaks - -and is followed by another line. -@end group -@end example - -The @code{@@br} command is seldom used. -@end ignore - - -@node page -@section @code{@@page}: Start a New Page -@cindex Page breaks -@findex page - -A line containing only @code{@@page} starts a new page in a printed -manual. The command has no effect on Info files since they are not -paginated. An @code{@@page} command is often used in the @code{@@titlepage} -section of a Texinfo file to start the copyright page. - - -@node group -@comment node-name, next, previous, up -@section @code{@@group}: Prevent Page Breaks -@cindex Group (hold text together vertically) -@cindex Holding text together vertically -@cindex Vertically holding text together -@findex group - -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.@refill - -@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.@refill - -@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{}.@refill - -@node need -@comment node-name, next, previous, up -@section @code{@@need @var{mils}}: Prevent Page Breaks -@cindex Need space at page bottom -@findex 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 Info files since they are not paginated.@refill - -@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:@refill - -@example -@group -@@need 800 -This paragraph is preceded by @dots{} -@end group -@end example - -The @code{@@need} command is useful for preventing orphans (single -lines at the bottoms of printed pages).@refill - - -@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.@refill - -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.@refill - -@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. -* 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. - -@cindex Macros in definition commands -Unfortunately, due to implementation difficulties, macros are not expanded -in @code{@@deffn} and all the other definition commands. - - -@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; simply put an -@code{@@} at the end of each line to be continued. - -The @code{@@} character does not have to be the last character on the -physical line: whitespace is allowed (and ignored) afterwards. - -@cindex Whitespace, collapsed around continuations -@cindex Collapsing whitespace around continuations -In general, any number of spaces or tabs around the @code{@@} -continuation character, both on the line with the @code{@@} and on the -continued line, 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'. In this case, simply elide any unwanted whitespace in -your input, or put the continuation @code{@@} outside braces. - -@code{@@} does not (currently) 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 - -Some entities take optional or repeated arguments, which may be -specified by a distinctive glyph that uses square brackets and -ellipses. For @w{example}, a special form often breaks its argument list -into separate arguments in more complicated ways than a -straightforward function. - -@c This is consistent with Emacs Lisp Reference manual -An argument enclosed within square brackets is optional. -Thus, [@var{optional-arg}] means that @var{optional-arg} is optional. -An argument followed by an ellipsis is optional -and may be repeated more than once. -@c This is consistent with Emacs Lisp Reference manual -Thus, @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 -special form: - -@quotation -@defspec foobar (@var{var} [@var{from} @var{to} [@var{inc}]]) @var{body}@dots{} -@end defspec -@tex -\vskip \parskip -@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.@refill - -In a Texinfo source file, this @code{@@defspec} line is written like -this (except it would not be split over two lines, as it is in this -example).@refill - -@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}.@refill - - -@node deffnx -@section Two or More `First' Lines -@cindex Two `First' Lines for @code{@@deffn} -@cindex Grouping two definitions together -@cindex Definitions grouped together -@findex deffnx - -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.@refill - -@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{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.@refill - -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.@refill - -Although the examples that follow mostly illustrate Lisp, the commands -can be used for other programming languages.@refill - -@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:@refill - -@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.@refill - -@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} and 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 unusual case when an argument name contains @samp{--}, or -another character sequence which is treated specially -(@pxref{Conventions}), use @code{@@var} around the argument. This -causes the name to be printed in slanted typewriter, instead of the -regular slanted font, exactly as input. -@c except for ?` and !`, but we won't explain that. - -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,,, elisp, GNU Emacs 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:@refill - -@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. - -Capitalize the category name like a title. If the name of the category -contains spaces, as in the name ``User Option'', enclose it in braces. -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.@refill - -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{}}.@refill - -@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}.@refill - -@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; Emacs has many such (@pxref{Variables,,, emacs, The GNU Emacs -Manual}). @code{@@defopt} is equivalent to @samp{@@defvr @{User -Option@} @dots{}} and works like @code{@@defvar}. It creates an entry -in the index of variables. -@end table - - -@node Typed Functions -@subsection 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.@refill - -@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 - -@need 1000 -@noindent -(where the text before the ``@dots{}'', shown above as two lines, would -actually be a single line in a real Texinfo file) produces the following -in Info: - -@smallexample -@group --- Library Function: int foobar (int FOO, float BAR) -@dots{} -@end group -@end smallexample -@iftex - -In a printed manual, it produces: - -@quotation -@deftypefn {Library Function} int foobar (int @var{foo}, float @var{bar}) -@dots{} -@end deftypefn -@end quotation -@end iftex - -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}).@refill - -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:@refill - -@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.@refill - -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 -(The @code{@@deftypefn} arguments are shown using continuations -(@pxref{Def Cmd Continuation Lines}), but could be on a single line in -a real Texinfo file.) - -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}.)@refill - -@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 - - -@node Typed Variables -@subsection 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}.@refill - -@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.@refill - -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.@refill - -@need 800 -@noindent -For example: - -@example -@group -@@deftypevr @{Global Flag@} int enable -@dots{} -@@end deftypevr -@end group -@end example - -@noindent -produces the following in Info: - -@example -@group --- Global Flag: int enable -@dots{} -@end group -@end example -@iftex - -@noindent -and the following in a printed manual: - -@quotation -@deftypevr {Global Flag} int enable -@dots{} -@end deftypevr -@end quotation -@end iftex - -@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:@refill - -@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.)@refill - -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}.@refill - -@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.@refill - -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.@refill - -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:@refill - -@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.@refill - -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.@refill - -@findex deftypeop -@item @@deftypeop @var{category} @var{class} @var{data-type} @var{name} @var{arguments}@dots{} -The @code{@@deftypeop} command is the definition command for typed -operations in object-oriented programming. It is similar to -@code{@@defop} with the addition of the @var{data-type} parameter to -specify the return type of the method. @code{@@deftypeop} creates an -entry in the index of functions. - -@item @@defmethod @var{class} @var{name} @var{arguments}@dots{} -@findex defmethod -The @code{@@defmethod} command is the definition command for methods -in object-oriented programming. A method is a kind of function that -implements an operation for a particular class of objects and its -subclasses. -@ignore -@c ADR: Who cares?!? -@c KB: Oh, I don't know, I think this info is crucial! -In the Lisp Machine, methods actually were functions, but -they were usually defined with @code{defmethod}. -@end ignore - -@code{@@defmethod} is equivalent to @samp{@@defop Method @dots{}}. -The command is written at the beginning of a line and is followed by -the name of the class of the method, the name of the method, and its -arguments, if any.@refill - -@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 - - -@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.@refill - - -@node Sample Function Definition -@section A Sample Function Definition -@cindex Function definitions -@cindex Command definitions -@cindex Macro definitions -@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.@refill - -Here is a definition from @ref{Calling Functions,,, elisp, The GNU Emacs -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}.@refill -@end defun -@end quotation - -@need 1200 -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}.@refill - -Ordinary variables and user options are described using a format like -that for functions except that variables do not take arguments. - - -@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{other} than a given -one (not Info, not @TeX{}, @dots{}). - -@item -`Raw' formatter text for any output format, passed straight -through with no 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. -* set clear value:: Variable tests and substitutions. -* 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: - -@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. - -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. - - -@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 Docbook, including raw -@cindex HTML, including raw -@cindex XML, including raw -@cindex Plain @TeX{} - -Inside a region delineated by @code{@@iftex} and @code{@@end iftex}, -you can embed some raw @TeX{} commands. The Texinfo processors will -ignore such a region unless @TeX{} output is being produced. You can -write the @TeX{} commands as you would write them in a normal @TeX{} -file, except that you must replace the @samp{\} used by @TeX{} with an -@samp{@@}. For example, in the @code{@@titlepage} section of a -Texinfo file, you can use the @TeX{} command @code{@@vskip} to format -the copyright page. (The @code{@@titlepage} command causes Info to -ignore the region automatically, as it does with the @code{@@iftex} -command.) - -However, most features of plain @TeX{} will not work within -@code{@@iftex}, as they are overridden by Texinfo features. The -purpose of @code{@@iftex} is to provide conditional processing for the -Texinfo source, not provide access to underlying formatting features. - -@findex 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 properly. As with @code{@@iftex}, Texinfo -processors will ignore such a region unless @TeX{} output is being produced. - -@findex \gdef @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. - -@cindex Mathematical expressions -As an example, here is a mathematical expression 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 Info, you will not see the equation that appears -in the printed manual. -@iftex -In a printed manual, the above expression looks like -this: -@end iftex - -@tex -$$ \chi^2 = \sum_{i=1}^N - \left(y_i - (a + b x_i) - \over \sigma_i\right)^2 $$ -@end tex - -@findex ifhtml -@findex html -Analogously, you can use @code{@@ifhtml @dots{} @@end ifhtml} to delimit -a region to be included in HTML output only, and @code{@@html @dots{} -@@end html} for a region of raw HTML. - -@findex ifxml -@findex xml -Likewise, you can use @code{@@ifxml @dots{} @@end ifxml} to delimit -a region to be included in XML output only, and @code{@@xml @dots{} -@@end xml} for a region of raw XML. - -@findex ifdocbook -@findex docbook -Again likewise, you can use @code{@@ifdocbook @dots{} @@end ifdocbook} -to delimit a region to be included in Docbook output only, and -@code{@@docbook @dots{} @@end docbook} for a region of raw Docbook. - -In all cases, the exception to the raw processing is that @code{@@} is -still an escape character, so the @code{@@end} command can be -recognized. - - -@node set clear value -@section @code{@@set}, @code{@@clear}, and @code{@@value} - -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 @@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. -@end table - -@menu -* set value:: Expand a flag variable to a string. -* ifset ifclear:: Format a region if a flag is set. -* value Example:: An easy way to update edition information. -@end menu - - -@node set value -@subsection @code{@@set} and @code{@@value} -@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}) is an identifier. It is best to use -only letters and numerals in a flag name, not @samp{-} or -@samp{_}---they will work in some contexts, but not all, due to -limitations in @TeX{}. - -The value is the remainder of the input line, and can contain anything. - -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 - - -@node ifset ifclear -@subsection @code{@@ifset} and @code{@@ifclear} - -@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 value Example -@subsection @code{@@value} Example - -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,, Overview, 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{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 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 Internationalization -@chapter Internationalization - -@cindex Internationalization -Texinfo has some support for writing in languages other than English, -although this area still needs considerable work. - -For a list of the various accented and special characters Texinfo -supports, see @ref{Inserting Accents}. - -@menu -* documentlanguage:: Declaring the current language. -* documentencoding:: Declaring the input encoding. -@end menu - - -@node documentlanguage -@section @code{@@documentlanguage @var{ll}[_@var{cc}]}: Set the Document Language - -@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{setfilename,,@code{@@setfilename}}). - -Include a two-letter ISO@tie{}639-2 language code (@var{ll}) following -the command name, optionally followed by a 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{@@setdocumentlanguage} argument -contains the optional @samp{_@var{cc}} suffix, this is tried first. -For example, with @code{@@setdocumentlanguage 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 -It would also be desirable for this command to also change @TeX{}'s -ideas of the current hyphenation patterns (via the @TeX{} primitive -@code{\language}), but this is unfortunately not currently -implemented. - -In September 2006, the W3C Internationalization Activity released a -new recommendation for specifying tags identifying language: -@example -@url{http://www.rfc-editor.org/rfc/bcp/bcp47.txt} -@end example -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 quite dynamic, -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 documentencoding -@section @code{@@documentencoding @var{enc}}: Set Input Encoding - -@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{setfilename,,@code{@@setfilename}}). - -At present, Texinfo supports only these encodings: - -@table @code -@item US-ASCII -This has no particular effect, but it's included for completeness. - -@itemx UTF-8 -The vast global character encoding, expressed in 8-bit bytes. -The Texinfo processors have no deep knowledge of Unicode; for the most -part, they just pass along the input they are given to the output. - -@itemx ISO-8859-1 -@itemx ISO-8859-15 -@item ISO-8859-2 -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: - -@opindex --enable-encoding -@cindex Local Variables: section, for encoding -@cindex Info output, and encoding -In Info output, unless the option @option{--disable-encoding} is given -to @command{makeinfo}, a so-called `Local Variables' section -(@pxref{File Variables,,,emacs,The GNU Emacs Manual}) is output -including @var{enc}. This allows Info readers to set the encoding -appropriately. - -@example -Local Variables: -coding: @var{enc} -End: -@end example - -Also, in Info and plain text output (barring -@option{--disable-encoding}), accent constructs and special -characters, such as @code{@@'e}, are output as the actual 8-bit -character in the given encoding. - -@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. - -@example -<meta http-equiv="Content-Type" content="text/html; - charset=@var{enc}"> -@end example - -In split HTML output, if @option{--transliterate-file-names} is -given (@pxref{HTML Xref 8-bit Character Expansion}), the names of HTML -files are formed by transliteration of the corresponding node names, -using the specified encoding. - -In XML and Docbook output, the given document encoding is written in -the output file as usual with those formats. - -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. - - -@node Defining New Texinfo Commands -@chapter Defining New Texinfo Commands -@cindex Macros -@cindex Defining new Texinfo commands -@cindex New Texinfo commands, defining -@cindex Texinfo commands, defining new -@cindex User-defined Texinfo commands - -Texinfo provides several ways to define new commands: - -@itemize @bullet -@item -A Texinfo @dfn{macro} allows you to define a new Texinfo command as any -sequence of text and/or existing commands (including other macros). The -macro can have any number of @dfn{parameters}---text you supply each -time you use the macro. - -Incidentally, these macros have nothing to do with the @code{@@defmac} -command, which is for documenting macros in the subject of the manual -(@pxref{Def Cmd Template}). - -@item -@samp{@@alias} is a convenient way to define a new name for an existing -command. - -@item -@samp{@@definfoenclose} allows you to define new commands with -customized output in the Info file. - -@end itemize - -@menu -* Defining Macros:: Defining and undefining new commands. -* Invoking Macros:: Using a macro, once you've defined it. -* Macro Details:: Limitations of Texinfo macros. -* alias:: Command aliases. -* definfoenclose:: Customized highlighting. -@end menu - - -@node Defining Macros -@section Defining Macros -@cindex Defining macros -@cindex Macro definitions - -@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 except @samp{@{@}_^=}; -@samp{_} and @samp{^} are excluded so that macros can be called in -@code{@@math} mode without a following space -(@pxref{math,,@code{@@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 -@cindex Mutually recursive macros -@cindex Recursion, mutual -The definition or @dfn{body} of the macro can contain most Texinfo -commands, including previously-defined macros. Not-yet-defined macro -invocations are not allowed; thus, it is not possible to have mutually -recursive Texinfo macros. Also, a macro definition that defines another -macro does not work in @TeX{} due to limitations in the design of -@code{@@macro}. - -@cindex Parameters to macros -In the macro body, instances of a parameter name surrounded by -backslashes, as in @samp{\@var{param1}\} in the example above, are -replaced by the corresponding argument from the macro invocation. You -can use parameter names any number of times in the body, including zero. - -@cindex Backslash in macros -To get a single @samp{\} in the macro expansion, use @samp{\\}. Any -other use of @samp{\} in the body yields a warning. - -@cindex Spaces in macros -@cindex Whitespace in macros -The newlines after the @code{@@macro} line and before the @code{@@end -macro} line are ignored, that is, not included in the macro body. All -other whitespace is treated according to the usual Texinfo rules. - -@cindex Recursive macro invocations -@findex rmacro -To allow a macro to be used recursively, that is, in an argument to a -call to itself, you must define it with @samp{@@rmacro}, like this: - -@example -@@rmacro rmac @{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 use -(@dfn{invoke}) it in your document like this: - -@example -@@@var{macroname} @{@var{arg1}, @var{arg2}, @dots{}@} -@end example - -@noindent and the result will be just as if you typed the body of -@var{macroname} at that spot. For example: - -@example -@@macro foo @{p, q@} -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 (but not the definition), even -when the macro takes no arguments, consistent with all other Texinfo -commands. For example: - -@example -@@macro argless @{@} -No arguments here. -@@end macro -@@argless@{@} -@end example - -@noindent produces: - -@display -No arguments here. -@end display - -@cindex Comma, in macro arguments -Passing strings containing commas as macro arguments requires special -care, since they should be properly @dfn{quoted} to prevent -@command{makeinfo} from confusing them with argument separators. To -manually quote a comma, prepend it with a backslash character, like -this: @code{\,}. Alternatively, use the @code{@@comma} command -(@pxref{Inserting a Comma}). However, to facilitate use of macros, -@command{makeinfo} implements a set of rules called @dfn{automatic -quoting}: - -@enumerate 1 -@item If a macro takes only one argument, all commas in its invocation -are quoted by default. For example: - -@example -@group -@@macro FIXME@{text@} -@@strong@{FIXME: \text\@} -@@end macro - -@@FIXME@{A nice feature, though it can be dangerous.@} -@end group -@end example - -@noindent -will produce the following output - -@example -@strong{FIXME: A nice feature, though it can be dangerous.} -@end example - -And indeed, it can. Namely, @command{makeinfo} -does not control 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, to be -treated as a part of an argument. -@end enumerate - -@cindex Braces, in macro arguments -Other 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}. However, commas in parameters, even -if escaped by a backslash, might cause trouble in @TeX{}. - -If the macro is defined to take a single argument, and is invoked -without any braces, the entire rest of the line after the macro name is -supplied as the argument. For example: - -@example -@@macro bar @{p@} -Twice: \p\ & \p\. -@@end macro -@@bar aah -@end example - -@noindent produces: - -@c Sorry for cheating, but let's not require macros to process the manual. -@display -Twice: aah & aah. -@end display - -If the macro is defined to take a single argument, and is invoked with -braces, the braced text is passed as the argument, regardless of -commas. For example: - -@example -@@macro bar @{p@} -Twice: \p\ & \p\. -@@end macro -@@bar@{a,b@} -@end example - -@noindent produces: - -@display -Twice: a,b & a,b. -@end display - - -@node Macro Details -@section Macro Details and Caveats -@cindex Macro details -@cindex Details of macro usage -@cindex Caveats for macro usage - -Due to unavoidable limitations, certain macro-related constructs cause -problems with @TeX{}. If you get macro-related errors when producing -the printed version of a manual, try expanding the macros with -@command{makeinfo} by invoking @command{texi2dvi} with the @samp{-E} -option (@pxref{Format with texi2dvi}). - -@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 very large -set of names, and the possible resulting errors are unpredictable. - -@item -All macros are expanded inside at least one @TeX{} group. This means -that @code{@@set} and other such commands have no effect inside a -macro. - -@item -Commas in macro arguments, even if escaped by a backslash, don't -always work. - -@item -Macro arguments cannot cross lines. - -@item -It is (usually) best to avoid comments inside macro definitions, but -see the next item. - -@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. In general, -the interaction of newlines in the macro definitions and invocations -depends on the precise commands and context. You may be able to work -around some problems with judicious use of @code{@@c}. Suppose you -define a macro that is always intended to be 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 an 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 a -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 call for Texinfo -command arguments, even when the text is the same. 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 -You would expect this to be equivalent to @code{@@headings off}, but -for @TeX{}nical reasons, it fails with a mysterious error message -(@code{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 limitations: - -@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. -(@xref{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 incorrectly 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 the nested definition outside the macro. - -@item -@code{@@rmacro} is a kludge. - -@end itemize - -One more limitation is common to both implementations: white space is -ignored at the beginnings of lines. - -Future major revisions of Texinfo may ease some of these limitations -(by introducing a new macro syntax). - - -@node alias -@section @samp{@@alias @var{new}=@var{existing}} -@cindex Aliases, command -@cindex Command aliases -@findex alias - -The @samp{@@alias} command defines a new command to be just like an -existing one. This is useful for defining additional markup names, thus -preserving semantic information in the input even though the output -result may be the same. - -Write the @samp{@@alias} command on a line by itself, followed by the -new command name, an equals sign, and the existing command name. -Whitespace around the equals sign is ignored. Thus: -@example -@@alias @var{new} = @var{existing} -@end example - -For example, if your document contains citations for both books and -some other media (movies, for example), you might like to define a -macro @code{@@moviecite@{@}} that does the same thing as an ordinary -@code{@@cite@{@}} but conveys the extra semantic information as well. -You'd do this as follows: - -@example -@@alias moviecite = cite -@end example - -Macros do not always have the same effect as aliases, due to vagaries -of argument parsing. Also, aliases are much simpler to define than -macros. So the command is not redundant. (It was also heavily used -in the Jargon File!) - -Aliases must not be recursive, directly or indirectly. - -It is not advisable to redefine any @TeX{} primitive, plain, or -Texinfo command name as an alias. Unfortunately this is a very large -set of names, and the possible resulting errors are completely random. - - -@node definfoenclose -@section @samp{definfoenclose}: Customized Highlighting -@cindex Highlighting, customized -@cindex Customized highlighting -@findex definfoenclose - -A @code{@@definfoenclose} command may be used to define a highlighting -command for Info, but not for @TeX{}. A command defined using -@code{@@definfoenclose} marks text by enclosing it in strings that -precede and follow the text. You can use this to get closer control of -your Info output. - -Presumably, if you define a command with @code{@@definfoenclose} for Info, -you will create a corresponding command for @TeX{}, either in -@file{texinfo.tex}, @file{texinfo.cnf}, or within an @samp{@@iftex} in -your document. - -Write a @code{@@definfoenclose} command on a line and follow it with -three arguments separated by commas. The first argument to -@code{@@definfoenclose} is the @@-command name (without the @code{@@}); -the second argument is the Info start delimiter string; and the third -argument is the Info end delimiter string. The latter two arguments -enclose the highlighted text in the Info file. A delimiter string may -contain spaces. Neither the start nor end delimiter is required. If -you do not want a start delimiter but do want an end delimiter, you must -follow the command name with two commas in a row; otherwise, the Info -formatting commands will naturally misinterpret the end delimiter string -you intended as the start delimiter string. - -If you do a @code{@@definfoenclose} on the name of a predefined macro -(such as @code{@@emph}, @code{@@strong}, @code{@@t}, or @code{@@i}), the -enclosure definition will override the built-in definition. - -An enclosure command defined this way takes one argument in braces; this -is intended for new markup commands (@pxref{Marking Text}). - -@findex phoo -For example, you can write: - -@example -@@definfoenclose phoo,//,\\ -@end example - -@noindent -near the beginning of a Texinfo file to define @code{@@phoo} as an Info -formatting command that inserts `//' before and `\\' after the argument -to @code{@@phoo}. You can then write @code{@@phoo@{bar@}} wherever you -want `//bar\\' highlighted in Info. - -Also, for @TeX{} formatting, you could write - -@example -@@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 @code{texinfo-format-buffer} or @code{texinfo-format-region}. The -@code{@@definfoenclose} command need not be within @samp{@@ifinfo}, but -the raw @TeX{} commands do need to be in @samp{@@iftex}. - -@findex headword -Here is another example: write - -@example -@@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 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 -@pindex texindex - -There are three major shell commands for making a printed manual from a -Texinfo file: one for converting the Texinfo file into a file that will be -printed, a second for sorting indices, and a third for printing the -formatted document. When you use the shell commands, you can either -work directly in the operating system shell or work within a shell -inside GNU Emacs. - -If you are using GNU Emacs, you can use commands provided by Texinfo -mode instead of shell commands. In addition to the three commands to -format a file, sort the indices, and print the result, Texinfo mode -offers key bindings for commands to recenter the output buffer, show the -print queue, and delete a job from the print queue. - -@menu -* Use TeX:: Use @TeX{} to format for hardcopy. -* Format with tex/texindex:: How to format with explicit shell commands. -* Format with texi2dvi:: A simpler way to format. -* Print with lpr:: How to print. -* Within Emacs:: How to format and print from an Emacs shell. -* Texinfo Mode Printing:: How to format and print in Texinfo mode. -* Compile-Command:: How to print using Emacs's compile command. -* Requirements Summary:: @TeX{} formatting requirements summary. -* Preparing for TeX:: What to do before you use @TeX{}. -* Overfull hboxes:: What are and what to do with overfull hboxes. -* smallbook:: How to print small format books and manuals. -* A4 Paper:: How to print on A4 or A5 paper. -* pagesizes:: How to print with customized page sizes. -* Cropmarks and Magnification:: How to print marks to indicate the size - of pages and how to print scaled up output. -* PDF Output:: Portable Document Format output. -* 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, if used correctly, -does an exceptionally good job. (@xref{Obtaining TeX, , How to Obtain -@TeX{}}, for information on how to obtain @TeX{}.) - -The standalone @code{makeinfo} program and Emacs functions -@code{texinfo-format-region} and @code{texinfo-format-buffer} commands -read the very same @@-commands in the Texinfo file as does @TeX{}, but -process them differently to make an Info file (@pxref{Creating an Info -File}). - - -@node Format with tex/texindex -@section Format with @code{tex} and @code{texindex} -@cindex Shell formatting with @code{tex} and @code{texindex} -@cindex Formatting with @code{tex} and @code{texindex} -@cindex DVI file - -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.) - -@cindex Names of index files -@cindex Index file names -The @code{tex} formatting command outputs unsorted index files under -names that obey a standard convention: the name of your main input file -with any @samp{.tex} (or similar, @pxref{tex invocation,,, web2c, -Web2c}) extension removed, 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 that you have defined yourself using @code{@@defindex} -or @code{@@defcodeindex}. (You may execute @samp{texindex foo.??} -even if there are similarly named files with two letter extensions -that are not index files, such as @samp{foo.el}. The @code{texindex} -command reports but otherwise ignores such files.) - -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 last time, generally incorrect. - -@item -Sort the indices again, with @code{texindex}. - -@item -Run @code{tex} one last time. This time the correct page numbers are -written for the cross-references. -@end enumerate - -@pindex texi2dvi -Alternatively, it's a one-step process: run @code{texi2dvi} -(@pxref{Format with texi2dvi}). - -You need not run @code{texindex} each time after you run @code{tex}. If -you do not, on the next run, the @code{tex} formatting command will use -whatever sorted index files happen to exist from the previous use of -@code{texindex}. This is usually ok while you are debugging. - -@cindex Auxiliary files, avoiding -@findex novalidate -@cindex Pointer validation, suppressing -@cindex Chapters, formatting one at a time -Sometimes you may wish to print a document while you know it is -incomplete, or to print just one chapter of a document. In that case, -the usual auxiliary files that @TeX{} creates and warnings @TeX{} gives -when cross-references are not satisfied are just nuisances. You can -avoid them with the @code{@@novalidate} command, which you must give -@emph{before} the @code{@@setfilename} command -(@pxref{setfilename,,@code{@@setfilename}}). Thus, the beginning of -your file would look approximately like this: - -@example -\input texinfo -@@novalidate -@@setfilename myfile.info -@dots{} -@end example - -@noindent @code{@@novalidate} also turns off validation in -@code{makeinfo}, just like its @code{--no-validate} option -(@pxref{Pointer Validation}). - - -@node Format with texi2dvi -@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{(@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{smallbook}), -@code{@@afourpaper} (@pxref{A4 Paper}), or @code{@@pagesizes} -(@pxref{pagesizes}), without actually changing the document source. -(You can also do this on a site-wide basis with @file{texinfo.cnf}; -@pxref{Preparing for TeX,,Preparing for @TeX{}}). - -@opindex --pdf @r{(@command{texi2dvi})} -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, since the latter merely prepends -@samp{pdf} to DVI producing tools to have PDF producing tools. - -@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{(@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{(@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{texi2dv} 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{(@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{documentencoding,,@code{documentencoding}}) to plain 7-bit -@samp{texinfo} encoding. - -@opindex --recode-from @r{(@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 unmodified input file. - -For a list of other options, run @samp{texi2dvi --help}. - - -@node Print with lpr -@section Shell Print Using @code{lpr -d} -@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 Emacs -@section From an Emacs Shell -@cindex Print, format from Emacs shell -@cindex Format, print from Emacs shell -@cindex Shell, format, print from -@cindex Emacs shell, format, print from -@cindex GNU Emacs shell, format, print from - -You can give formatting and printing commands from a shell within GNU -Emacs. To create a shell within Emacs, type @kbd{M-x shell}. In this -shell, you can format and print the document. @xref{Hardcopy, , Format -and Print Hardcopy}, for details. - -You can switch to and from the shell buffer while @code{tex} is -running and do other editing. If you are formatting a long document -on a slow machine, this can be very convenient.@refill - -You can also use @code{texi2dvi} from an Emacs shell. For example, -here is how to use @code{texi2dvi} to format and print @cite{Using and -Porting GNU CC} from a shell within Emacs: - -@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.@refill - -@table @kbd -@item C-c C-t C-b -@itemx M-x texinfo-tex-buffer -Run @code{texi2dvi} on the current buffer.@refill - -@item C-c C-t C-r -@itemx M-x texinfo-tex-region -Run @TeX{} on the current region.@refill - -@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}.@refill - -@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}.@refill - -@item C-c C-t C-q -@itemx M-x tex-show-print-queue -Show the print queue.@refill - -@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}).@refill - -@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.@refill - -@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.@refill - -@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.@refill -@end table - -@need 1000 -Thus, the usual sequence of commands for formatting a buffer is as -follows (with comments to the right):@refill - -@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 Emacs -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.@refill - -@need 1500 -The formatting and print commands depend on the values of several variables. -The default values are:@refill - -@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, emacs, The GNU Emacs Manual}), or with your @file{.emacs} -initialization file (@pxref{Init File, , , emacs, The GNU Emacs -Manual}). - -@cindex Customize Emacs package (@t{Development/Docs/Texinfo}) -Beginning with version 20, GNU Emacs offers a user-friendly interface, -called @dfn{Customize}, for changing values of user-definable variables. -@xref{Easy Customization, , Easy Customization Interface, emacs, The GNU -Emacs Manual}, for more details about this. The Texinfo variables can -be found in the @samp{Development/Docs/Texinfo} group, once you invoke -the @kbd{M-x customize} command. - - -@node Compile-Command -@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 Emacs run it by typing -@kbd{M-x compile}. This creates a special shell called the -@file{*compilation*} buffer in which Emacs runs the compile command. -For example, at the end of the @file{gdb.texinfo} file, after the -@code{@@bye}, you could put the following:@refill - -@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, , , emacs, The GNU Emacs Manual}.@refill - - -@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{settitle, , @code{@@settitle}}. -@item @ref{setchapternewpage, , @code{@@setchapternewpage}}. -@item @ref{Headings, ,Page Headings}. -@item @ref{Titlepage & Copyright Page}. -@item @ref{Printing Indices & Menus}. -@item @ref{Contents}. -@end itemize - - -@node Preparing for TeX -@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, Emacs or -other GNU software is installed. In this case, @TeX{} will find the -file and you do not need to do anything special. If this has not been -done, you can put @file{texinfo.tex} in the current directory when you -run @TeX{}, and @TeX{} will find it there. - -@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{euro}. - -@pindex texinfo.cnf @r{installation} -@cindex Customizing of @TeX{} for Texinfo -@cindex Site-wide Texinfo configuration file -Optionally, you may create an additional @file{texinfo.cnf}, and install -it as well. This file is read by @TeX{} when the @code{@@setfilename} -command is executed (@pxref{setfilename,, @code{@@setfilename}}). You can put any -commands you like there, according to local site-wide conventions. They -will be read by @TeX{} when processing any Texinfo document. For -example, if @file{texinfo.cnf} contains the line @samp{@@afourpaper} -(@pxref{A4 Paper}), then all Texinfo documents will be processed with -that page size in effect. If you have nothing to put in -@file{texinfo.cnf}, you do not need to create it. - -@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{.cshrc} or @file{.profile} file. - -Which you use of @file{.cshrc} or @file{.profile} 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. The latter read the @file{.cshrc} file for -initialization information, and the former read @file{.profile}. - -In a @file{.cshrc} file, you could use the following @code{csh} command -sequence: - -@example -setenv TEXINPUTS .:/home/me/mylib: -@end example - -@need 1000 -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 - -On MS-DOS/MS-Windows, you would say it like this@footnote{Note the use -of the @samp{;} character, instead of @samp{:}, as directory separator -on these systems.}: - -@example -@group -set TEXINPUTS=.;d:/home/me/mylib;c: -@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{hboxes}, 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 needed in the Texinfo language.) - -@TeX{} also provides the line number in the Texinfo source file and -the text of the offending line, which is marked at all the places that -@TeX{} considered hyphenation. -@xref{Debugging with TeX, , Catching Errors with @TeX{} Formatting}, -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 smallbook -@section Printing ``Small'' Books -@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:@refill - -@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}).@refill - -@xref{small}, for information about -commands that make it easier to produce examples for a smaller manual. - -@xref{Format with texi2dvi}, and @ref{Preparing for TeX,,Preparing for -@TeX{}}, for other ways to format with @code{@@smallbook} that do not -require changing the source file. - - -@node A4 Paper -@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 texi2dvi}, and @ref{Preparing for TeX,,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 pagesizes -@section @code{@@pagesizes} [@var{width}][, @var{height}]: Custom Page Sizes -@findex pagesizes -@cindex Custom page sizes -@cindex Page sizes, customized -@cindex Text width and height -@cindex Width of text area -@cindex Height of text area -@cindex Depth of text area - -You can explicitly specify the height and (optionally) width of the main -text area on the page with the @code{@@pagesizes} command. Write this -on a line by itself near the beginning of the Texinfo file, before the -title page. The height comes first, then the width if desired, -separated by a comma. Examples: - -@example -@@pagesizes 200mm,150mm @c for b5 paper -@end example -@noindent and -@example -@@pagesizes 11.5in @c for legal paper -@end example - -@cindex B5 paper, printing on -@cindex Legal paper, printing on -This would be reasonable for printing on B5-size paper. To emphasize, -this command specifies the size of the @emph{text area}, not the size of -the paper (which is 250@dmn{mm} by 177@dmn{mm} for B5, 14@dmn{in} by -8.5@dmn{in} for legal). - -@cindex Margins on page, not controllable -To make more elaborate changes, such as changing any of the page -margins, you must define a new command in @file{texinfo.tex} (or -@file{texinfo.cnf}, @pxref{Preparing for TeX,,Preparing for @TeX{}}). - -@xref{Format with texi2dvi}, and @ref{Preparing for TeX,,Preparing for -@TeX{}}, for other ways to specify @code{@@pagesizes} that do not -require changing the source file. - -@code{@@pagesizes} is ignored by @code{makeinfo}. - - -@node Cropmarks and Magnification -@section Cropmarks and Magnification -@findex cropmarks -@cindex Cropmarks for printing -@cindex Printing cropmarks -You can (attempt to) direct @TeX{} to print cropmarks at the corners of -pages with the @code{@@cropmarks} command. Write the @code{@@cropmarks} -command on a line by itself between @code{@@iftex} and @code{@@end -iftex} lines near the beginning of the Texinfo file, before the title -page, like this:@refill - -@example -@group -@@iftex -@@cropmarks -@@end iftex -@end group -@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}. - -@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 -plain @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 simply executes the @command{texi2dvi} script with the -@option{--pdf} option (@pxref{Format with texi2dvi}). If for some -reason you want to process the document by hand, simply 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.foolabs.com/xpdf/, Ghostscript-based PDF -reader}. (It can also preview PostScript documents.) - -@item -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 links that would be -hard or impossible to get right at the Texinfo source level. - -PDF files require special 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 How to Obtain @TeX{} -@cindex Obtaining @TeX{} -@cindex @TeX{}, how to obtain - -@c !!! Here is information about obtaining TeX. Update it whenever. -@c !!! Also consider updating TeX.README on ftp.gnu.org. -@c Updated by RJC on 1 March 1995, conversation with MacKay. -@c Updated by kb@cs.umb.edu on 29 July 1996. -@c Updated by kb@cs.umb.edu on 25 April 1997. -@c Updated by kb@cs.umb.edu on 27 February 1998. -@TeX{} is freely redistributable. You can obtain @TeX{} for Unix -systems via anonymous ftp or on physical media. The core material -consists of the Web2c @TeX{} distribution (@uref{http://tug.org/web2c}). - -Instructions for retrieval by anonymous ftp and information on other -available distributions: -@uref{http://tug.org/unixtex.ftp}. - -The Free Software Foundation provides a core distribution on its Source -Code CD-ROM suitable for printing Texinfo manuals. To order it, contact: - -@display -@group -Free Software Foundation, Inc. -51 Franklin St, Fifth Floor -Boston, MA @ @ 02110-1301 -USA -Telephone: @w{+1-617-542-5942} -Fax: (including Japan) @w{+1-617-542-2652} -Free Dial Fax (in Japan): -@w{ } @w{ } @w{ } 0031-13-2473 (KDD) -@w{ } @w{ } @w{ } 0066-3382-0158 (IDC) -Electronic mail: @code{gnu@@gnu.org} -@end group -@end display - -Many other @TeX{} distributions are available; see -@uref{http://tug.org/}. - - -@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 GNU Emacs functions that convert -Texinfo to Info. - -For information on installing the Info file in the Info system, -@pxref{Installing an Info File}. - -@menu -* makeinfo advantages:: @code{makeinfo} provides better error checking. -* Invoking makeinfo:: How to run @code{makeinfo} from a shell. -* makeinfo options:: Specify fill-column and other options. -* Pointer Validation:: How to check that pointers point somewhere. -* makeinfo in Emacs:: How to run @code{makeinfo} from Emacs. -* texinfo-format commands:: Two Info formatting commands written - in Emacs Lisp are an alternative - to @code{makeinfo}. -* Batch Formatting:: How to format for Info in Emacs Batch mode. -* Tag and Split Files:: How tagged and split files help Info - to run better. -@end menu - - -@node makeinfo advantages -@subsection @code{makeinfo} Preferred - -The @code{makeinfo} utility creates an Info file from a Texinfo source -file more quickly than either of the Emacs formatting commands and -provides better error messages. We recommend it. @code{makeinfo} is a -C program that is independent of Emacs. You do not need to run Emacs to -use @code{makeinfo}, which means you can use @code{makeinfo} on machines -that are too small to run Emacs. You can run @code{makeinfo} in any one -of three ways: from an operating system shell, from a shell inside -Emacs, or by typing the @kbd{C-c C-m C-r} or the @kbd{C-c C-m C-b} -command in Texinfo mode in Emacs. - -The @code{texinfo-format-region} and the @code{texinfo-format-buffer} -commands are useful if you cannot run @code{makeinfo}. Also, in some -circumstances, they format short regions or buffers more quickly than -@code{makeinfo}. - - -@node Invoking makeinfo -@subsection Running @code{makeinfo} from a Shell -@pindex makeinfo - -To create an Info file from a Texinfo file, invoke @command{makeinfo} -followed by the name of the Texinfo file. Thus, to create the Info -file for Bison, type the following to the shell: - -@example -makeinfo bison.texinfo -@end example - -(You can run a shell inside Emacs by typing @kbd{M-x shell}.) - -@command{makeinfo} has many options to control its actions and output; -see the next section. - - -@node makeinfo options -@subsection Options for @code{makeinfo} -@cindex @code{makeinfo} options -@cindex Options for @code{makeinfo} - -The @command{makeinfo} program accepts many options. Perhaps the most -commonly needed are those that change the output format. By default, -@command{makeinfo} outputs Info files. - -Each command line option is a word preceded by @samp{--} or a 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 each line is filled to only 68 -columns: - -@example -makeinfo --fill-column=68 bison.texinfo -@end example - -You can write two or more options in sequence, like this:@refill - -@example -makeinfo --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: - -@table @code - -@item -D @var{var} -@opindex -D @var{var} -Cause the variable @var{var} to be defined. This is equivalent to -@code{@@set @var{var}} in the Texinfo file (@pxref{set clear value}). - -@item --commands-in-node-names -@opindex --commands-in-node-names -Allow @code{@@}-commands in node names. This is not recommended, as it -can probably never be implemented in @TeX{}. It also makes -@code{makeinfo} much slower. Also, this option is ignored when -@samp{--no-validate} is used. @xref{Pointer Validation}, for more -details. - -@item --css-include=@var{file} -@opindex --css-include -Include the contents of @var{file}, which should contain cascading -style sheets specifications, in the @samp{<style>} block of the HTML -output. @xref{HTML CSS}. If @var{file} is @samp{-}, read standard -input. - -@item --css-ref=@var{url} -@opindex --css-ref -In HTML mode, add a @samp{<link>} tag to the HTML output which -references a cascading style sheet at @var{url}. This allows using -standalone style sheets. - -@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 or plain text output based on -@samp{@@documentencoding}. With @option{--disable-encoding}, 7-bit -ASCII transliterations are output. -@xref{documentencoding,,@code{documentencoding}}, and @ref{Inserting -Accents}. - -@item --docbook -@opindex --docbook -Generate Docbook output rather than Info. - -@item --document-language=@var{lang} -@opindex --document-language -@vindex LANG -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 -(@pxref{documentlanguage}). - -@item --error-limit=@var{limit} -@itemx -e @var{limit} -@opindex --error-limit=@var{limit} -@opindex -e @var{limit} -Set the maximum number of errors that @code{makeinfo} will report -before exiting (on the assumption that continuing would be useless); -default 100. - -@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. Ignored with @samp{--html}. - -@item --footnote-style=@var{style} -@itemx -s @var{style} -@opindex --footnote-style=@var{style} -@opindex -s @var{style} -Set the footnote style to @var{style}, either @samp{end} for the end -node style (the default) or @samp{separate} for the separate node style. -The value set by this option overrides the value set in a Texinfo file -by an @code{@@footnotestyle} command (@pxref{Footnotes}). 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. Ignored with @samp{--html}. - -@item --force -@itemx -F -@opindex --force -@opindex -F -Ordinarily, if the input file has errors, the output files are not -created. With this option, they are preserved. - -@item --help -@itemx -h -@opindex --help -@opindex -h -Print a usage message listing all available options, then exit successfully. - -@item --html -@opindex --html -Generate HTML output rather than Info. @xref{Generating HTML}. By -default, the HTML output is split into one output file per Texinfo -source node, and the split output is written into a subdirectory with -the name of the top-level info file. - -@item -I @var{dir} -@opindex -I @var{dir} -Append @var{dir} to the directory search list for finding files that -are included using the @code{@@include} command. By default, -@code{makeinfo} searches only the current directory. If @var{dir} is -not given, the current directory @file{.} is appended. Note that -@var{dir} can actually be a list of several directories separated by the -usual path separator character (@samp{:} on Unix, @samp{;} on -MS-DOS/MS-Windows). - -@item --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 specified format, process @samp{@@if@var{format}} and -@samp{@@@var{format}} commands even if not generating the given output -format. For instance, if @option{--iftex} is specified, then -@samp{@@iftex} and @samp{@@tex} blocks will be read. - -@item --macro-expand=@var{file} -@itemx -E @var{file} -@opindex --macro-expand=@var{file} -@opindex -E @var{file} -Output the Texinfo source with all the macros expanded to the named -file. Normally, the results of macro expansion are used internally by -@code{makeinfo} and then discarded. This option is used by -@command{texi2dvi}. - -@item --no-headers -@item --plaintext -@opindex --no-headers -@opindex --plaintext -@cindex Plain text output -@cindex ASCII text output -@cindex Generating plain text files -@cindex @file{INSTALL} file, generating -@cindex Node separators, omitting -@cindex Menus, omitting -Do not include menus or node separator lines in the output, and -implicitly @option{--enable-encoding} (see above). This results in a -simple plain text file that you can (for example) send in email -without complications, or include in a distribution (as in an -@file{INSTALL} file). - -@cindex Navigation links, omitting -For HTML output, likewise omit menus. And if @samp{--no-split} is also -specified, do not include a navigation links at the top of each node -(these are never included in the default case of split output). -@xref{Generating HTML}. - -In both cases, ignore @code{@@setfilename} and write to standard -output by default---can be overridden with @option{-o}. - -@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 -Do not process @samp{@@if@var{format}} and @samp{@@@var{format}} -commands, and do process @samp{@@ifnot@var{format}}, even if -generating the given format. For instance, if @option{--no-ifhtml} is -specified, then @samp{@@ifhtml} and @samp{@@html} blocks will not be -read, and @samp{@@ifnothtml} blocks will be. - -@item --no-number-footnotes -@opindex --no-number-footnotes -Suppress automatic footnote numbering. By default, @code{makeinfo} -numbers each footnote sequentially in a single node, resetting the -current footnote number to 1 at the start of each node. - -@item --no-number-sections -@opindex --no-number-sections -Do not output chapter, section, and appendix numbers. -You need to specify this if your manual is not hierarchically-structured. - -@item --no-split -@opindex --no-split -@cindex Splitting of output files -@cindex Output file splitting -Suppress the splitting stage of @code{makeinfo}. By default, large -output files (where the size is greater than 70k bytes) are split into -smaller subfiles. For Info output, each one is approximately 50k bytes. -For HTML output, each file contains one node (@pxref{Generating HTML}). - -@item --no-pointer-validate -@itemx --no-validate -@opindex --no-pointer-validate -@opindex --no-validate -@cindex Pointer validation, suppressing -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,,Use @TeX{}}). Normally, after a Texinfo file -is processed, some consistency checks are made to ensure that cross -references can be resolved, etc. @xref{Pointer Validation}. - -@item --no-warn -@opindex --no-warn -Suppress warning messages (but @emph{not} error messages). - -@item --number-sections -@opindex --number-sections -Output chapter, section, and appendix numbers as in printed manuals. -This is the default. It works only with hierarchically-structured -manuals. - -@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} and not to the -file name specified in the @code{@@setfilename} command found in the -Texinfo source (@pxref{setfilename}). If @var{file} is @samp{-}, output -goes to standard output and @samp{--no-split} is implied. For split -HTML output, @var{file} is the name for the directory into which all -HTML nodes are written (@pxref{Generating HTML}). - -@item -P @var{dir} -@opindex -P @var{dir} -Prepend @var{dir} to the directory search list for @code{@@include}. -If @var{dir} is not given, the current directory @file{.} is prepended. -See @samp{-I} for more details. - -@item --paragraph-indent=@var{indent} -@itemx -p @var{indent} -@opindex --paragraph-indent=@var{indent} -@opindex -p @var{indent} -Set the paragraph indentation style to @var{indent}. The value set by -this option overrides the value set in a Texinfo file by an -@code{@@paragraphindent} command (@pxref{paragraphindent}). The value -of @var{indent} is interpreted as follows: - -@table @asis -@item @samp{asis} -Preserve any existing indentation at the starts of paragraphs. - -@item @samp{0} or @samp{none} -Delete any existing indentation. - -@item @var{num} -Indent each paragraph by @var{num} spaces. -@end table - -@item --split-size=@var{num} -@opindex --split-size=@var{num} -Keep Info files to at most @var{num} characters; default is 300,000. - -@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{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 -@opindex -V -Print the version number, then exit successfully. - -@item --xml -@opindex --xml -Generate 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 possible values are: - -@example -docbook html info plaintext xml -@end example - -If not set, Info output is the default. - - -@node Pointer Validation -@subsection 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,,Use @TeX{}}), @code{makeinfo} will check the validity of the final -Info file. Mostly, this means ensuring that nodes you have referenced -really exist. Here is a complete list of what is checked: - -@enumerate -@item -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.@refill - -@item -In every node, if the `Previous' node is different from the `Up' node, -then the node pointed to by the `Previous' field must have a `Next' -field which points back to this node.@refill - -@item -Every node except the `Top' node must have an `Up' pointer.@refill - -@item -The node referenced by an `Up' pointer must itself reference the current -node through a menu item, unless the node referenced by `Up' -has the form `(@var{file})'. - -@item -If the `Next' reference of a node is not the same as the `Next' reference -of the `Up' reference, then the node referenced by the `Next' pointer -must have a `Previous' pointer that points back to the current node. -This rule allows the last node in a section to point to the first node -of the next chapter.@refill - -@item -Every node except `Top' should be referenced by at least one other node, -either via the `Previous' or `Next' links, or via a menu or a -cross-reference.@refill -@end enumerate - -@cindex @@-commands in @@node, limited support -Some Texinfo documents might fail during the validation phase because -they use commands like @code{@@value} and @code{@@definfoenclose} in -node definitions and cross-references inconsistently. (Your best bet -is to avoid using @@-commands in node names.) Consider the -following example: - -@example -@group -@@set nodename Node 1 - -@@node @@value@{nodename@}, Node 2, Top, Top - -This is node 1. - -@@node Node 2, , Node 1, Top - -This is node 2. -@end group -@end example - -@noindent -Here, the node ``Node 1'' was referenced both verbatim and through -@code{@@value}. - -By default, @code{makeinfo} fails such cases, because node names are not -fully expanded until they are written to the output file. You should -always try to reference nodes consistently; e.g., in the above example, -the second @code{@@node} line should have also used @code{@@value}. -However, if, for some reason, you @emph{must} reference node names -inconsistently, and @code{makeinfo} fails to validate the file, you can -use the @samp{--commands-in-node-names} option to force @code{makeinfo} -to perform the expensive expansion of all node names it finds in the -document. This might considerably slow down the program, though; -twofold increase in conversion time was measured for large documents -such as the Jargon file. - -@cindex @@value in @@node lines -The support for @code{@@}-commands in @code{@@node} directives is not -general enough to be freely used. For example, if the example above -redefined @code{nodename} somewhere in the document, @code{makeinfo} -will fail to convert it, even if invoked with the -@samp{--commands-in-node-names} option. - -@samp{--commands-in-node-names} has no effect if the @samp{--no-validate} -option is given. - - -@node makeinfo in Emacs -@subsection Running @code{makeinfo} Within Emacs -@cindex Running @code{makeinfo} in Emacs -@cindex @code{makeinfo} inside Emacs -@cindex Shell, running @code{makeinfo} in - -You can run @code{makeinfo} in GNU Emacs 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.@refill - -@table @kbd -@item C-c C-m C-r -@itemx M-x makeinfo-region -Format the current region for Info.@refill -@findex makeinfo-region - -@item C-c C-m C-b -@itemx M-x makeinfo-buffer -Format the current buffer for Info.@refill -@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{setfilename}). - -The Emacs @code{makeinfo-region} and @code{makeinfo-buffer} commands -run the @code{makeinfo} program in a temporary shell buffer. If -@code{makeinfo} finds any errors, Emacs displays the error messages in -the temporary buffer.@refill - -@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 Emacs to go to and position the -cursor on the line in the Texinfo source that @code{makeinfo} thinks -caused the error. @xref{Compilation, , Running @code{make} or -Compilers Generally, emacs, The GNU Emacs Manual}, for more -information about using the @code{next-error} command.@refill - -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.@refill - -@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}).@refill - -@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.@refill -@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}.)@refill - -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{.emacs} initialization file. - -For example, you could write the following in your @file{.emacs} file:@refill - -@example -@group -(setq makeinfo-options - "--paragraph-indent=0 --no-split - --fill-column=70 --verbose") -@end group -@end example - -@noindent -@c If you write these three cross references using xref, you see -@c three references to the same named manual, which looks strange. -@iftex -For more information, see @ref{makeinfo options, , Options for -@code{makeinfo}}, as well as ``Easy Customization Interface,'' ``Examining -and Setting Variables,'' and ``Init File'' in @cite{The GNU Emacs -Manual}. -@end iftex -@ifnottex -For more information, see@* -@ref{Easy Customization, , Easy Customization Interface, emacs, The GNU Emacs Manual},@* -@ref{Examining, , Examining and Setting Variables, emacs, The GNU Emacs Manual},@* -@ref{Init File, , , emacs, The GNU Emacs Manual}, and@* -@ref{makeinfo options, , Options for @code{makeinfo}}. -@end ifnottex - -@node texinfo-format commands -@subsection The @code{texinfo-format@dots{}} Commands - -In GNU Emacs in Texinfo mode, you can format part or all of a Texinfo -file with the @code{texinfo-format-region} command. This formats the -current region and displays the formatted text in a temporary buffer -called @samp{*Info Region*}.@refill - -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.@refill - -@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 is often faster and -provides better error checking (@pxref{makeinfo in Emacs}).@refill - -@node Batch Formatting -@comment node-name, next, previous, up -@subsection Batch Formatting -@cindex Batch formatting for Info -@cindex Info batch formatting - -You can format Texinfo files for Info using @code{batch-texinfo-format} -and Emacs Batch mode. You can run Emacs in Batch mode from any shell, -including a shell inside of Emacs. (@xref{Command Arguments,,, -emacs, The GNU Emacs Manual}.) - -Here is a shell command to format all the files that end in -@file{.texinfo} in the current directory: - -@example -emacs -batch -funcall batch-texinfo-format *.texinfo -@end example - -@noindent -Emacs processes all the files listed on the command line, even if an -error occurs while attempting to format some of them.@refill - -Run @code{batch-texinfo-format} only with Emacs in Batch mode as shown; -it is not interactive. It kills the Batch mode Emacs on completion.@refill - -@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 Emacs process. This frees your current Emacs, so -you can continue working in it. (When you run -@code{texinfo-format-region} or @code{texinfo-format-buffer}, you cannot -use that Emacs for anything else until the command finishes.)@refill - -@node Tag and Split Files -@comment node-name, next, previous, up -@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.@refill - -@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 Emacs does -not need to make a large buffer to hold the whole of a large Info -file; instead, Emacs allocates just enough memory for the small, split-off -file that is needed at the time. This way, Emacs avoids wasting -memory when you run Info. (Before splitting was implemented, Info -files were always kept short and @dfn{include files} were designed as -a way to create a single, large printed manual out of the smaller Info -files. @xref{Include Files}, for more information. Include files are -still used for very large documents, such as @cite{The Emacs Lisp -Reference Manual}, in which each chapter is a separate file.)@refill - -When a file is split, Info itself makes use of a shortened version of -the original file that contains just the tag table and references to -the files that were split off. The split-off files are called -@dfn{indirect} files.@refill - -The split-off files have names that are created by appending @w{@samp{-1}}, -@w{@samp{-2}}, @w{@samp{-3}} and so on to the file name specified by the -@code{@@setfilename} command. The shortened version of the original file -continues to have the name specified by @code{@@setfilename}.@refill - -At one stage in writing this document, for example, the Info file was saved -as the file @file{test-texinfo} and that file looked like this:@refill - -@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:}. @refill - -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 the permissions -text in each file. In the tag table, the number following the node name -records the location of the beginning of the node, in bytes from the -beginning 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 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 Emacs. (@inforef{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 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 Emacs by typing @kbd{C-h i} to enter Info and then typing -@kbd{C-x C-f} to see the pathname to the @file{info} directory.) - -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:@refill - -@example -@group -* Menu: -* Info: (info). Documentation browsing system. -* Emacs: (emacs). The extensible, self-documenting - text editor. -* Texinfo: (texinfo). With one source file, make - either a printed manual using - @@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}.)@refill - -Thus, the @samp{Info} entry points to the `Top' node of the -@file{info} file and the @samp{Emacs} entry points to the `Top' node -of the @file{emacs} file.@refill - -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:@refill - -@example -File: emacs Node: Top, Up: (DIR), Next: Distrib -@end example - -@noindent -In this case, the @file{dir} file name is written in upper case -letters---it can be written in either upper or lower case. This is not -true in general, it is a special case for @file{dir}. - - -@node New Info File -@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:@refill - -@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:@refill - -@enumerate -@item -Write the pathname in the @file{dir} file as the second part of the menu. - -@item -If you are using Emacs, list the name of the file in a second @file{dir} -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 Emacs where to look for @file{dir} files (the files -must be named @file{dir}). Emacs merges the files named @file{dir} from -each of the listed directories. (In Emacs version 18, you can set the -@code{Info-directory} variable to the name of only one -directory.)@refill - -@item -Specify the Info directory name in the @code{INFOPATH} environment -variable in your @file{.profile} or @file{.cshrc} initialization file. -(Only you and others who set this environment variable will be able to -find Info files whose location is specified this way.) -@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:@refill - -@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.@refill - -Alternatively, you could write the following in your @file{.emacs} file: - -@vindex Info-directory-list -@example -@group -(require 'info) -(setq Info-directory-list - (cons (expand-file-name "/home/bob/info") - Info-directory-list)) -@end group -@end example - -This tells Emacs to merge the system @file{dir} file with the @file{dir} -file in @file{/home/bob/info}. Thus, Info will list the -@file{/home/bob/info/info-test} file as a menu entry in the -@file{/home/bob/info/dir} file. Emacs does the merging only when -@kbd{M-x info} is first run, so if you want to set -@code{Info-directory-list} in an Emacs session where you've already run -@code{info}, you must @code{(setq Info-dir-contents nil)} to force Emacs -to recompose the @file{dir} file. - -@vindex INFOPATH -@cindex Environment variable @code{INFOPATH} -Finally, you can tell Info where to look by setting the @code{INFOPATH} -environment variable in your shell startup file, such as @file{.cshrc}, -@file{.profile} or @file{autoexec.bat}. If you use a Bourne-compatible -shell such as @code{sh} or @code{bash} for your shell command -interpreter, you set the @code{INFOPATH} environment variable in the -@file{.profile} initialization file; but if you use @code{csh} or -@code{tcsh}, you set the variable in the @file{.cshrc} initialization -file. On MS-DOS/MS-Windows systems, you must set @code{INFOPATH} in -your @file{autoexec.bat} file or in the Registry. Each type of shell -uses a different syntax. - -@itemize @bullet -@item -In a @file{.cshrc} file, you could set the @code{INFOPATH} -variable as follows:@refill - -@smallexample -setenv INFOPATH .:~/info:/usr/local/emacs/info -@end smallexample - -@item -In a @file{.profile} file, you would achieve the same effect by -writing:@refill - -@smallexample -INFOPATH=.:$HOME/info:/usr/local/emacs/info -export INFOPATH -@end smallexample - -@item -@pindex autoexec.bat -In a @file{autoexec.bat} file, you write this command@footnote{Note the -use of @samp{;} as the directory separator, and a different syntax for -using values of other environment variables.}: - -@smallexample -set INFOPATH=.;%HOME%/info;c:/usr/local/emacs/info -@end smallexample -@end itemize - -@noindent -The @samp{.} indicates the current directory as usual. Emacs uses the -@code{INFOPATH} environment variable to initialize the value of Emacs's -own @code{Info-directory-list} variable. The stand-alone Info reader -merges any files named @file{dir} in any directory listed in the -@env{INFOPATH} variable into a single menu presented to you in the node -called @samp{(dir)Top}. - -@cindex Colon, last in @env{INFOPATH} -However you set @env{INFOPATH}, if its last character is a -colon@footnote{On MS-DOS/MS-Windows systems, use semi-colon instead.}, this -is replaced by the default (compiled-in) path. This gives you a way to -augment the default path with new directories without having to list all -the standard places. For example (using @code{sh} syntax): - -@example -INFOPATH=/local/info: -export INFOPATH -@end example - -@noindent -will search @file{/local/info} first, then the standard directories. -Leading or doubled colons are not treated specially. - -@cindex @file{dir} file, creating your own -When you create your own @file{dir} file for use with -@code{Info-directory-list} or @env{INFOPATH}, it's easiest to start by -copying an existing @file{dir} file and replace all the text after the -@samp{* Menu:} with your desired entries. That way, the punctuation and -special CTRL-_ characters that Info needs will be present. - - -@node Installing Dir Entries -@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 Emacs). This will make it align with -most others. Description for individual utilities best start in -column 48, where possible. For more information about formatting see -the @samp{--calign}, @samp{--align}, and @samp{--max-width} options in -@ref{Invoking 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 -Emacs -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 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 files, reading -@cindex Dir files, compressed -If any input file is compressed with @code{gzip} (@pxref{Invoking -gzip,,,gzip, Gzip}), @code{install-info} automatically uncompresses it -for reading. And if @var{dir-file} is compressed, @code{install-info} -also automatically leaves it compressed after writing any changes. -If @var{dir-file} itself does not exist, @code{install-info} tries to -open @file{@var{dir-file}.gz}. - -Options: - -@table @code -@item --add-once -Specifies that the entry or entries will only be put into a single section. - -@item --align=@var{column} -@opindex --align=@var{column} -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 -Instead of alphabetizing new sections, place them at the end of the DIR file. - -@item --calign=@var{column} -@opindex --calign=@var{column} -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 -Report what is being done. - -@item --delete -@opindex --delete -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} -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} -Specify file name of the Info directory file. This is equivalent to -using the @var{dir-file} argument. - -@item --dry-run -@opindex --dry-run -Same as @samp{--test}. - -@item --entry=@var{text} -@opindex --entry=@var{text} -Insert @var{text} as an Info directory entry; @var{text} should have the -form of an Info menu item line plus zero or more extra lines starting -with whitespace. If you specify more than one entry, they are all -added. If you don't specify any entries, they are determined from -information in the Info file itself. - -@item --help -@opindex --help -Display a usage message with basic usage and all available options, -then exit successfully. - -@item --info-file=@var{file} -@opindex --info-file=@var{file} -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} -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} -Same as @samp{--info-dir}. - -@item --item=@var{text} -@opindex --item=@var{text} -Same as @samp{--entry=@var{text}}. An Info directory entry is actually -a menu item. - -@item --keep-old -@opindex --keep-old -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} -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} -Same as @samp{--max-width}. - -@item --menuentry=@var{text} -@opindex --menuentry=@var{text} -Same as @samp{--name}. - -@item --name=@var{text} -@opindex --name=@var{text} -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 meant to include the text up to and including the -first dot @samp{.}. 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 -Suppress formatting of new entries into the @file{dir} file. - -@item --quiet -@opindex --quiet -@itemx --silent -@opindex --silent -Suppress warnings, etc., for silent operation. - -@item --remove -@opindex --remove -Same as @samp{--delete}. - -@item --remove-exactly -@opindex --remove-exactly -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} -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} -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 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} -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 -Suppress updating of the directory file. - -@item --version -@opindex --version -@cindex Version number, for install-info -Display version information and exit successfully. - -@end table - - -@node Generating HTML -@chapter Generating HTML -@cindex HTML output - -@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} can also write in XML and Docbook format, but we do -not as yet describe these further. @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}. - -@opindex --footnote-style@r{, ignored in HTML output} -The @option{--footnote-style} option is currently ignored for HTML output; -footnotes are always linked to the end of the output file. - -@cindex Navigation bar, in HTML output -By default, a navigation bar is inserted at the start of each node, -analogous to Info output. The @samp{--no-headers} option suppresses -this if used with @samp{--no-split}. Header @code{<link>} elements in -split output can support info-like navigation with browsers like Lynx -and @w{Emacs W3} which implement this HTML@tie{}1.0 feature. - -@cindex HTML output, browser compatibility of -The HTML generated is mostly standard (i.e., HTML@tie{}2.0, RFC-1866). -One exception is that HTML@tie{}3.2 tables are generated from the -@code{@@multitable} command, but tagged to degrade as well as possible -in browsers without table support. The HTML@tie{}4 @samp{lang} -attribute on the @samp{<html>} attribute is also used. (Please report -output from an error-free run of @code{makeinfo} which has browser -portability problems as a bug.) - - -@node HTML Splitting -@section HTML Splitting -@cindex Split HTML output -@cindex HTML output, split - -When splitting output (which is the default), @command{makeinfo} -writes HTML output into (generally) one output file per Texinfo source -@code{@@node}. - -The output file name is the node name with special characters replaced -by @samp{-}'s, so it can work 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 separately. If @command{makeinfo} is run on a -system which does not distinguish case in filenames, nodes which are -the same except for case will also be folded into the same output -file. - -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}) or @code{--output} (the argument is used literally). - - -@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 of the 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, this specification tells the web -browser to use a `smaller' font size for @code{@@smalldisplay} text, -and to use the `inherited' font (generally a regular roman typeface) -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}}. - -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. - -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. - - -@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 amount, in the -end, to 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 -Acknowledgement: this 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. -@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}, which -is currently simply hardwired. In the future, it may come from an -external data file. - -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 - -One exception: the algorithm for node name expansion prefixes the -string @samp{g_t} when the node name begins with a non-letter. This -kludge (due to XHTML rules) is not necessary for filenames, and is -therefore omitted. - -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 is another bit of the -external information. For now, @command{makeinfo} simply assumes the -referent manual is the same as the present manual. - -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 actually refer either to nodes or -anchors (@pxref{anchor}), but anchors are treated identically to nodes -in this context, so we'll continue to say ``node'' names for -simplicity. - -(@@-commands and 8-bit characters are not presently handled by -@command{makeinfo} for HTML cross-references. See the next section.) - -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, Introduction,, emacs, The GNU Emacs Manual@}. -@result{} <a href="emacs/index.html#Top"> -@end example - -@enumerate -@item -The standard ASCII letters (a-z and A-Z) are not modified. All other -characters are 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 - -In standard Texinfo, node names may not contain @@-commands. -@command{makeinfo} has an option @option{--commands-in-node-names} -which partially supports it (@pxref{Invoking makeinfo}), but it is not -robust and not recommended. - -Thus, @command{makeinfo} also does not fully implement this part of -the HTML cross-reference algorithm, but it is documented here for the -sake of completeness. - -First, comments are removed. - -Next, any @code{@@value} commands (@pxref{set value}) and macro invocations -(@pxref{Invoking Macros}) are fully expanded. - -Then, for the following commands, the command name and braces are removed, -the text of the argument is recursively transformed: -@example -@@asis @@b @@cite @@code @@command @@dfn @@dmn @@dotless -@@emph @@env @@file @@indicateurl @@kbd @@key -@@samp @@sc @@slanted @@strong @@t @@var @@w -@end example - -@noindent For @code{@@sc}, any letters are capitalized. - -The following commands are replaced by constant text, as shown. If -any of these commands have non-empty arguments, as in -@code{@@TeX@{bad@}}, it is an error, and the result is unspecified. -`(space)' means a space character, `(nothing)' means the empty string, -etc. The notation `U+@var{xxxx}' means Unicode code point @var{xxxx}. -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{@@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+2192 -@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{@@tie} @tab (space) -@end multitable - -An @code{@@acronym} or @code{@@abbr} command is replaced by the first -argument, followed by the second argument in parentheses, if present. -@xref{acronym}. - -An @code{@@email} command is replaced by the @var{text} argument if -present, else the address. @xref{email}. - -An @code{@@image} command is replaced by the filename (first) -argument. @xref{Images}. - -A @code{@@verb} command is replaced by its transformed argument. -@xref{verb}. - -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 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 0xffff or less, as it almost always is. - -These will then be further transformed by the rules above into the -string @samp{_@var{xxxx}}, where @var{xxxx} 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 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 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 -(such as, e.g. Ukrainian), it will create file names consisting -entirely of @samp{_@var{xxxx}} notations, which is inconvenient. - -To handle such cases, @command{makeinfo} offers -@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 principle, which makes the -produced file names easily readable. - -For the definition of Unicode Normalization Form 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 has to guess whether a given manual being cross-referenced is -available in split or monolithic form---and, inevitably, it might -guess wrong. However, it is possible when the referent manual itself -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 actual cross-reference in the present manual -can control. - -Ultimately, we hope to allow for an external configuration file to -control which manuals are available from where, and how. - - -@ignore --- not yet -- - -external information --------------------- - -The information for the reference is searched in the file -`htmlxref.cnf' present in the following directories: -<srcdir>/.texinfo/, ~/.texinfo/, SYSCONFDIR/texinfo/, -DATADIR/texinfo/ -The first match should be used. - -The file is line-oriented, with the following format: - <manualname> <whitespace> <keyword> <whitespace> <urlprefix> -with <keyword> being "mono" or "split". Thus -texinfo split http://www.gnu.org/software/texinfo/manual/texinfo/html_node/ -texinfo mono http://www.gnu.org/software/texinfo/manual/texinfo/texinfo.html - -If the keyword is 'split', that is the target is split, the urlprefix gives -the directory and host name. -If the keyword is 'mono', that is the target is mono, the urlprefix gives -directory, host and file name. - -'#' followed by a space begins comments. '#' followed by another character -cannot begin comments as there are # in urls. - -@end ignore - - -@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. -@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 @@! -Generate an exclamation point that really does end 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{- and hyphenation}. - -@item @@. -Produce a period that really does end 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 @@? -Generate a question mark that really does end a sentence (usually after -an end-of-sentence capital letter). @xref{Ending a Sentence}. - -@item @@@@ -Stands for an at sign, @samp{@@}. -@xref{Atsign Braces Comma, , Inserting @@ and @{@} and @comma{}}. - -@item @@\ -Stands for a backslash (@samp{\}) inside @code{@@math}. -@xref{math,,@code{math}}. - -@item @@^ -@itemx @@` -Generate a circumflex (hat) or grave accent, respectively, over the next -character, as in @^o and @`e. -@xref{Inserting Accents}. - -@item @@@{ -Stands for a left brace, @samp{@{}. -@xref{Atsign Braces Comma, , Inserting @@ and @{@} and @comma{}}. - -@item @@@} -Stands for a right-hand brace, @samp{@}}.@* -@xref{Atsign Braces Comma, , Inserting @@ and @{@} and @comma{}}. - -@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}@} -Tag @var{abbreviation} as an abbreviation, such as `Comput.'. -@xref{abbr,, @code{abbr}}. - -@item @@acronym@{@var{acronym}@} -Tag @var{acronym} as an acronym, such as `NASA'. -@xref{acronym,, @code{acronym}}. - -@item @@AE@{@} -@itemx @@ae@{@} -Generate the uppercase and lowercase AE ligatures, respectively: -@AE{}, @ae{}. @xref{Inserting Accents}. - -@itemx @@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}} an alias for the existing command -@samp{@@@var{existing}}. @xref{alias}. - -@item @@anchor@{@var{name}@} -Define @var{name} as the current location for use as a cross-reference -target. @xref{anchor,, @code{@@anchor}}. - -@item @@appendix @var{title} -Begin an appendix. The title appears in the table -of contents of a printed manual. In Info, the title is -underlined with asterisks. @xref{unnumbered & appendix, , The -@code{@@unnumbered} and @code{@@appendix} Commands}.@refill - -@item @@appendixsec @var{title} -@itemx @@appendixsection @var{title} -Begin an appendix section within an appendix. The section title appears -in the table of contents of a printed manual. In Info, the title is -underlined with equal signs. @code{@@appendixsection} is a longer -spelling of the @code{@@appendixsec} command. @xref{unnumberedsec -appendixsec heading, , Section Commands}.@refill - -@item @@appendixsubsec @var{title} -Begin an appendix subsection within an appendix. The title appears -in the table of contents of a printed manual. In Info, the title is -underlined with hyphens. @xref{unnumberedsubsec appendixsubsec -subheading, , Subsection Commands}.@refill - -@item @@appendixsubsubsec @var{title} -Begin an appendix subsubsection within an appendix subsection. The -title appears in the table of contents of a printed manual. In Info, -the title is underlined with periods. @xref{subsubsection,, The -`subsub' Commands}.@refill - -@item @@arrow@{@} -Produce a normal 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{Two-column Tables}. - -@item @@author @var{author} -Typeset @var{author} flushleft and underline it. @xref{title -subtitle author, , The @code{@@title} and @code{@@author} -Commands}.@refill - -@item @@b@{@var{text}@} -Print @var{text} in @b{bold} font. No effect in Info. @xref{Fonts}.@refill - -@ignore -@item @@br -Force a paragraph break. If used within a line, follow @code{@@br} -with braces. @xref{br, , @code{@@br}}.@refill -@end ignore - -@item @@bullet@{@} -Generate a large round dot, or the closest possible -thing to one. @xref{bullet, , @code{@@bullet}}.@refill - -@item @@bye -Stop formatting a file. The formatters do not see the contents of a -file following an @code{@@bye} command. @xref{Ending a File}.@refill - -@item @@c @var{comment} -Begin a comment in Texinfo. The rest of the line does not appear in -either the Info file or the printed manual. A synonym for -@code{@@comment}. @xref{Comments}. - -@item @@caption -Define the full caption for a @code{@@float}. @xref{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{cartouche, , Drawing Cartouches Around Examples}.)@refill - -@item @@center @var{line-of-text} -Center the line of text following the command. -@xref{titlefont center sp, , @code{@@center}}.@refill - -@item @@centerchap @var{line-of-text} -Like @code{@@chapter}, but centers the chapter title. @xref{chapter,, -@code{@@chapter}}. - -@item @@chapheading @var{title} -Print a chapter-like heading in the text, but not in the table of -contents of a printed manual. In Info, the title is underlined with -asterisks. @xref{majorheading & chapheading, , @code{@@majorheading} -and @code{@@chapheading}}.@refill - -@item @@chapter @var{title} -Begin a chapter. The chapter title appears in the table of -contents of a printed manual. In Info, the title is underlined with -asterisks. @xref{chapter, , @code{@@chapter}}.@refill - -@item @@cindex @var{entry} -Add @var{entry} to the index of concepts. @xref{Index Entries, , -Defining the Entries of an Index}.@refill - -@item @@cite@{@var{reference}@} -Highlight the name of a book or other reference that lacks a -companion Info file. @xref{cite, , @code{@@cite}}.@refill - -@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 @@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{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill - -@item @@code@{@var{sample-code}@} -Highlight text that is an expression, a syntactically complete token -of a program, or a program name. @xref{code, , @code{@@code}}.@refill - -@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{command,, @code{@@command}}. - -@item @@comment @var{comment} -Begin a comment in Texinfo. The rest of the line does not appear in -either the Info file or the printed manual. A synonym for @code{@@c}. -@xref{Comments}. - -@item @@contents -Print a complete table of contents. Has no effect in Info, which uses -menus instead. @xref{Contents, , Generating a Table of -Contents}.@refill - -@item @@copyright@{@} -Generate the copyright symbol @copyright{}. @xref{copyright symbol,, -@code{@@copyright@{@}}}. - -@ignore -@item @@ctrl@{@var{ctrl-char}@} -Describe an ASCII control character. Insert actual control character -into Info file. @xref{ctrl, , @code{@@ctrl}}. -@end ignore - -@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}.@refill - -@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}, and @ref{deffnx,, Def Cmds in Detail}. - -@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}.@refill - -@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}.@refill - -@item @@definfoenclose @var{newcmd}, @var{before}, @var{after}, -Create new @@-command @var{newcmd} for Info that marks text by enclosing -it in strings that precede and follow the text. @xref{definfoenclose}. - -@item @@defivar @var{class} @var{instance-variable-name} -@itemx @@defivarx @var{class} @var{instance-variable-name} -This command formats a description for an instance variable in -object-oriented programming. The command is equivalent to @samp{@@defcv -@{Instance Variable@} @dots{}}. @xref{Definition Commands}, and -@ref{deffnx,, Def Cmds in Detail}. - -@item @@defmac @var{macroname} @var{arguments}@dots{} -@itemx @@defmacx @var{macroname} @var{arguments}@dots{} -Format a description for a macro. The command is equivalent to -@samp{@@deffn Macro @dots{}}. @xref{Definition Commands}, and -@ref{deffnx,, Def Cmds in Detail}. - -@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. The -command is equivalent to @samp{@@defop Method @dots{}}. Takes as -arguments the name of the class of the method, the name of the -method, and its arguments, if any. @xref{Definition Commands}, and -@ref{deffnx,, Def Cmds in Detail}. - -@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 overall name of the category of -operation, the name of the class of the operation, the name of the -operation, and its arguments, if any. @xref{Definition -Commands}, and @ref{Abstract Objects}. - -@item @@defopt @var{option-name} -@itemx @@defoptx @var{option-name} -Format a description for a user option. The command is equivalent to -@samp{@@defvr @{User Option@} @dots{}}. @xref{Definition Commands}, and -@ref{deffnx,, Def Cmds in Detail}. - -@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. The command is equivalent to -@samp{@@deffn @{Special Form@} @dots{}}. @xref{Definition Commands}, -and @ref{deffnx,, Def Cmds in Detail}. - -@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. @code{@@deftp} takes as arguments -the category, the name of the type (which is a word like @samp{int} or -@samp{float}), and then the names of attributes of objects of that type. -@xref{Definition Commands}, and @ref{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{classification} @var{data-type} @var{name} @var{arguments}@dots{} -@itemx @@deftypefnx @var{classification} @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 -classification of entity being described, the type, the name of the -entity, and its arguments, if any. @xref{Definition Commands}, and -@ref{deffnx,, Def Cmds in Detail}. - -@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}, and @ref{deffnx,, Def Cmds in Detail}. - -@item @@deftypeivar @var{class} @var{data-type} @var{variable-name} -@itemx @@deftypeivarx @var{class} @var{data-type} @var{variable-name} -Format a description for a typed instance variable in object-oriented -programming. @xref{Definition Commands}, and @ref{Abstract Objects}. - -@item @@deftypemethod @var{class} @var{data-type} @var{method-name} @var{arguments}@dots{} -@itemx @@deftypemethodx @var{class} @var{data-type} @var{method-name} @var{arguments}@dots{} -Format a description for a typed method in object-oriented programming. -@xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}. - -@item @@deftypeop @var{category} @var{class} @var{data-type} @var{name} @var{arguments}@dots{} -@itemx @@deftypeopx @var{category} @var{class} @var{data-type} @var{name} @var{arguments}@dots{} -Format a description for a typed operation in object-oriented programming. -@xref{Definition Commands}, and @ref{Abstract Objects}. - -@item @@deftypevar @var{data-type} @var{variable-name} -@itemx @@deftypevarx @var{data-type} @var{variable-name} -Format a description for a variable in a typed language. The command is -equivalent to @samp{@@deftypevr Variable @dots{}}. @xref{Definition -Commands}, and @ref{deffnx,, Def Cmds in Detail}. - -@item @@deftypevr @var{classification} @var{data-type} @var{name} -@itemx @@deftypevrx @var{classification} @var{data-type} @var{name} -Format a description for something like a variable in a typed -language---an entity that records a value. Takes as arguments the -classification of entity being described, the type, and the name of the -entity. @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in -Detail}. - -@item @@defun @var{function-name} @var{arguments}@dots{} -@itemx @@defunx @var{function-name} @var{arguments}@dots{} -Format a description for functions. The command is equivalent to -@samp{@@deffn Function @dots{}}. @xref{Definition Commands}, and -@ref{deffnx,, Def Cmds in Detail}. - -@item @@defvar @var{variable-name} -@itemx @@defvarx @var{variable-name} -Format a description for variables. The command is equivalent to -@samp{@@defvr Variable @dots{}}. @xref{Definition Commands}, and -@ref{deffnx,, Def Cmds in Detail}. - -@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}, -and @ref{deffnx,, Def Cmds in Detail}. - -@item @@detailmenu -Avoid @code{makeinfo} confusion stemming from the detailed node listing -in a master menu. @xref{Master Menu Parts}. - -@item @@dfn@{@var{term}@} -Highlight the introductory or defining use of a term. -@xref{dfn, , @code{@@dfn}}.@refill - -@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{display, , @code{@@display}}. - -@item @@dmn@{@var{dimension}@} -Format a unit of measure, as in 12@dmn{pt}. Causes @TeX{} to insert a -thin space before @var{dimension}. No effect in Info. -@xref{dmn, , @code{@@dmn}}. - -@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{documentdescription,, -@code{@@documentdescription}}. - -@item @@documentencoding @var{enc} -Declare the input encoding to be @var{enc}. -@xref{documentencoding,, @code{@@documentencoding}}. - -@item @@documentlanguage @var{CC} -Declare the document language as the two-character ISO-639 abbreviation -@var{CC}. @xref{documentlanguage,, @code{@@documentlanguage}}. - -@item @@dotaccent@{@var{c}@} -Generate a dot accent over the character @var{c}, as in @dotaccent{o}. -@xref{Inserting Accents}. - -@item @@dots@{@} -Insert an ellipsis: @samp{@dots{}}. -@xref{dots, , @code{@@dots}}.@refill - -@item @@email@{@var{address}[, @var{displayed-text}]@} -Indicate an electronic mail address. -@xref{email, , @code{@@email}}. - -@item @@emph@{@var{text}@} -Highlight @var{text}; text is displayed in @emph{italics} in printed -output, and surrounded by asterisks in Info. @xref{Emphasis, , -Emphasizing Text}. - -@item @@end @var{environment} -Ends @var{environment}, as in @samp{@@end example}. @xref{Formatting -Commands,,@@-commands}. - -@item @@env@{@var{environment-variable}@} -Indicate an environment variable name, such as @env{PATH}. -@xref{env,, @code{@@env}}. - -@item @@enddots@{@} -Generate an end-of-sentence of ellipsis, like this @enddots{} -@xref{dots,,@code{@@dots@{@}}}. - -@item @@enumerate [@var{number-or-letter}] -Begin a numbered list, using @code{@@item} for each entry. -Optionally, start list with @var{number-or-letter}. Pair with -@code{@@end enumerate}. @xref{enumerate, , -@code{@@enumerate}}.@refill - -@item @@equiv@{@} -Indicate to the reader the exact equivalence of two forms with a -glyph: @samp{@equiv{}}. @xref{Equivalence}.@refill - -@item @@euro@{@} -Generate the Euro currency sign. -@xref{euro,,@code{@@euro@{@}}}. - -@item @@error@{@} -Indicate to the reader with a glyph that the following text is -an error message: @samp{@error{}}. @xref{Error Glyph}.@refill - -@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}.@refill - -@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}.@refill - -@item @@example -Begin an example. Indent text, do not fill, and select fixed-width font. -Pair with @code{@@end example}. @xref{example, , -@code{@@example}}.@refill - -@item @@exampleindent @var{indent} -Indent example-like environments by @var{indent} number of spaces -(perhaps 0). @xref{exampleindent,, Paragraph Indenting}. - -@item @@exclamdown@{@} -Produce an upside-down exclamation point. @xref{Inserting Accents}. - -@item @@exdent @var{line-of-text} -Remove any indentation a line might have. @xref{exdent, , -Undoing the Indentation of a Line}.@refill - -@item @@expansion@{@} -Indicate the result of a macro expansion to the reader with a special -glyph: @samp{@expansion{}}. -@xref{expansion, , @expansion{} Indicating an Expansion}.@refill - -@item @@file@{@var{filename}@} -Highlight the name of a file, buffer, node, or directory. @xref{file, , -@code{@@file}}.@refill - -@item @@finalout -Prevent @TeX{} from printing large black warning rectangles beside -over-wide lines. @xref{Overfull hboxes}.@refill - -@item @@findex @var{entry} -Add @var{entry} to the index of functions. @xref{Index Entries, , -Defining the Entries of an Index}.@refill - -@item @@float -Environment to define floating material. Pair with @code{@@end float}. -@xref{Floats}. - -@item @@flushleft -@itemx @@flushright -Left justify every line but leave the right end ragged. -Leave font as is. Pair with @code{@@end flushleft}. -@code{@@flushright} analogous. -@xref{flushleft & flushright, , @code{@@flushleft} and -@code{@@flushright}}.@refill - -@item @@footnote@{@var{text-of-footnote}@} -Enter a footnote. Footnote text is printed at the bottom of the page -by @TeX{}; Info may format in either `End' node or `Separate' node style. -@xref{Footnotes}.@refill - -@item @@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}.@refill - -@item @@format -Begin a kind of example. Like @code{@@display}, but do not narrow the -margins. Pair with @code{@@end format}. @xref{example,, -@code{@@example}}. - -@item @@ftable @var{formatting-command} -Begin a two-column table, using @code{@@item} for each entry. -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{ftable vtable, , -@code{@@ftable} and @code{@@vtable}}.@refill - -@item @@geq@{@} -Generate a greater-than-or-equal sign, `@geq{}'. @xref{geq leq}. - -@item @@group -Hold text together that must appear on one printed page. Pair with -@code{@@end group}. Not relevant to Info. @xref{group, , -@code{@@group}}.@refill - -@item @@H@{@var{c}@} -Generate the long Hungarian umlaut accent over @var{c}, as in @H{o}. - -@item @@heading @var{title} -Print an unnumbered section-like heading in the text, but not in the -table of contents of a printed manual. In Info, the title is -underlined with equal signs. @xref{unnumberedsec appendixsec heading, -, Section Commands}.@refill - -@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{headings on off, , The -@code{@@headings} Command}. - -@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{- and hyphenation,, -@code{@@-} and @code{@@hyphenation}}. - -@item @@i@{@var{text}@} -Print @var{text} in @i{italic} font. No effect in Info. @xref{Fonts}. - -@item @@ifclear @var{flag} -If @var{flag} is cleared, the Texinfo formatting commands format text -between @code{@@ifclear @var{flag}} and the following @code{@@end -ifclear} command. -@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill - -@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 @@ifnotinfo -@itemx @@ifnotplaintext -@itemx @@ifnottex -@itemx @@ifnotxml -Begin a stretch of text that will be ignored in one output format but -not the others. The text appears in the formats not specified: -@code{@@ifnothtml} text is omitted from HTML output, etc. The exception -is @code{@@ifnotinfo} text, which is omitted from plain text output as -well as Info output. Pair with the corresponding @code{@@end -ifnot@var{format}}. @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{flag} -If @var{flag} is set, the Texinfo formatting commands format text -between @code{@@ifset @var{flag}} and the following @code{@@end ifset} -command. -@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill - -@item @@iftex -Begin text that will not appear in the Info file or other output, but -will be processed only by @TeX{}. Pair with @code{@@end iftex}. -@xref{Conditionals, , Conditionally Visible Text}.@refill - -@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} -Incorporate the contents of the file @var{filename} into the Info file -or printed document. @xref{Include Files}.@refill - -@item @@indicateurl@{@var{indicateurl}@} -Indicate text that is a uniform resource locator for the World Wide -Web. @xref{indicateurl, , @code{@@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{inforef, , Cross references using -@code{@@inforef}}.@refill - -@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 backslash 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 @@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}.@refill - -@item @@itemize @var{mark-generating-character-or-command} -Produce a sequence of indented paragraphs, with a mark inside the left -margin at the beginning of each paragraph. Pair with @code{@@end -itemize}. @xref{itemize, , @code{@@itemize}}.@refill - -@item @@itemx -Like @code{@@item} but do not generate extra vertical space above the -item text. @xref{itemx, , @code{@@itemx}}.@refill - -@item @@kbd@{@var{keyboard-characters}@} -Indicate text that is characters of input to be typed by -users. @xref{kbd, , @code{@@kbd}}.@refill - -@item @@kbdinputstyle @var{style} -Specify when @code{@@kbd} should use a font distinct from @code{@@code}. -@xref{kbd, , @code{@@kbd}}.@refill - -@item @@key@{@var{key-name}@} -Indicate a name for a key on a keyboard. -@xref{key, , @code{@@key}}.@refill - -@item @@kindex @var{entry} -Add @var{entry} to the index of keys. -@xref{Index Entries, , Defining the Entries of an Index}.@refill - -@item @@L@{@} -@itemx @@l@{@} -Generate the uppercase and lowercase Polish suppressed-L letters, -respectively: @L{}, @l{}. - -@item @@LaTeX@{@} -Insert the logo @LaTeX{}. @xref{tex, , @TeX{} and @LaTeX{}}. - -@item @@leq@{@} -Generate a less-than-or-equal sign, `@leq{}'. @xref{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{lisp, , @code{@@lisp}}. - -@item @@listoffloats -Produce a table-of-contents-like listing of @code{@@float}s. -@xref{listoffloats}. - -@item @@lowersections -Change subsequent chapters to sections, sections to subsections, and so -on. @xref{Raise/lower sections, , @code{@@raisesections} and -@code{@@lowersections}}.@refill - -@item @@macro @var{macroname} @{@var{params}@} -Define a new Texinfo command @code{@@@var{macroname}@{@var{params}@}}. -Only supported by @code{makeinfo} and @code{texi2dvi}. @xref{Defining -Macros}. - -@item @@majorheading @var{title} -Print a chapter-like heading in the text, but not in the table of -contents of a printed manual. Generate more vertical whitespace before -the heading than the @code{@@chapheading} command. @xref{majorheading & -chapheading, , @code{@@majorheading} and @code{@@chapheading}}.@refill - -@item @@math@{@var{mathematical-expression}@} -Format a mathematical expression. -@xref{math, , @code{@@math}: Inserting Mathematical Expressions}. - -@item @@menu -Mark the beginning of a menu of nodes in Info. No effect in a printed -manual. Pair with @code{@@end menu}. @xref{Menus}.@refill - -@item @@minus@{@} -Generate a minus sign, `@minus{}'. @xref{minus, , @code{@@minus}}. - -@item @@multitable @var{column-width-spec} -Begin a multi-column table. 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{need, , -@code{@@need}}. - -@item @@node @var{name}, @var{next}, @var{previous}, @var{up} -Define the beginning of a new node in Info, and serve as a locator for -references for @TeX{}. @xref{node, , @code{@@node}}. - -@item @@noindent -Prevent text from being indented as if it were a new paragraph. -@xref{noindent, , @code{@@noindent}}. - -@item @@novalidate -Suppress validation of node references, omit creation of auxiliary files -with @TeX{}. Use before @code{@@setfilename}. @xref{Pointer Validation}. - -@item @@O@{@} -@itemx @@o@{@} -Generate the uppercase and lowercase O-with-slash letters, respectively: -@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}.@refill - -@item @@OE@{@} -@itemx @@oe@{@} -Generate the uppercase and lowercase OE ligatures, respectively: -@OE{}, @oe{}. @xref{Inserting Accents}. - -@item @@option@{@var{option-name}@} -Indicate a command-line option, such as @option{-l} or @option{--help}. -@xref{option,, @code{@@option}}. - -@item @@page -Start a new page in a printed manual. No effect in Info. -@xref{page, , @code{@@page}}.@refill - -@item @@pagesizes [@var{width}][, @var{height}] -Change page dimensions. @xref{pagesizes}. - -@item @@paragraphindent @var{indent} -Indent paragraphs by @var{indent} number of spaces (perhaps 0); preserve -source file indentation if @var{indent} is @code{asis}. -@xref{paragraphindent,, Paragraph Indenting}. - -@item @@pindex @var{entry} -Add @var{entry} to the index of programs. @xref{Index Entries, , Defining -the Entries of an Index}.@refill - -@item @@point@{@} -Indicate the position of point in a buffer to the reader with a -glyph: @samp{@point{}}. @xref{Point Glyph, , Indicating -Point in a Buffer}.@refill - -@item @@pounds@{@} -Generate the pounds sterling currency sign. -@xref{pounds,,@code{@@pounds@{@}}}. - -@item @@print@{@} -Indicate printed output to the reader with a glyph: -@samp{@print{}}. @xref{Print Glyph}.@refill - -@item @@printindex @var{index-name} -Print an alphabetized two-column index in a printed manual or generate -an alphabetized menu of index entries for Info. @xref{Printing -Indices & Menus}.@refill - -@item @@pxref@{@var{node-name}, [@var{entry}], [@var{topic-or-title}], [@var{info-file}], [@var{manual}]@} -Make a reference that starts with a lower case `see' in a printed -manual. Use within parentheses only. Do not follow command with a -punctuation mark---the Info formatting commands automatically insert -terminating punctuation as needed. Only the first argument is mandatory. -@xref{pxref, , @code{@@pxref}}.@refill - -@item @@questiondown@{@} -Generate an upside-down question mark. @xref{Inserting Accents}. - -@item @@quotation -Narrow the margins to indicate text that is quoted from another real -or imaginary work. Takes optional argument of prefix text. Pair with -@code{@@end quotation}. @xref{quotation, , -@code{@@quotation}}.@refill - -@item @@r@{@var{text}@} -Print @var{text} in @r{roman} font. No effect in Info. -@xref{Fonts}.@refill - -@item @@raisesections -Change subsequent sections to chapters, subsections to sections, and so -on. @xref{Raise/lower sections, , @code{@@raisesections} and -@code{@@lowersections}}.@refill - -@item @@ref@{@var{node-name}, [@var{entry}], [@var{topic-or-title}], [@var{info-file}], [@var{manual}]@} -Make a reference. In a printed manual, the reference does not start -with a `See'. Follow command with a punctuation mark. Only the first -argument is mandatory. @xref{ref, , @code{@@ref}}.@refill - -@item @@refill -This command used to refill and indent the paragraph after all the -other processing has been done. It is no longer needed, since all -formatters now automatically refill as needed, but you may still see -it in the source to some manuals, as it does no harm. - -@item @@registeredsymbol@{@} -Generate the legal symbol @registeredsymbol{}. @xref{registered -symbol,, @code{@@registeredsymbol@{@}}}. - -@item @@result@{@} -Indicate the result of an expression to the reader with a special -glyph: @samp{@result{}}. @xref{result, , @code{@@result}}.@refill - -@item @@ringaccent@{@var{c}@} -Generate a ring accent over the next character, as in @ringaccent{o}. -@xref{Inserting Accents}. - -@item @@samp@{@var{text}@} -Highlight @var{text} that is a literal example of a sequence of -characters. Used for single characters, for statements, and often for -entire shell commands. @xref{samp, , @code{@@samp}}.@refill - -@item @@sansserif@{@var{text}@} -Print @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 printed output in @sc{the small caps font} and -set text in the Info file in uppercase letters. -@xref{Smallcaps}.@refill - -@item @@section @var{title} -Begin a section within a chapter. In a printed manual, the section -title is numbered and appears in the table of contents. In Info, the -title is underlined with equal signs. @xref{section, , -@code{@@section}}.@refill - -@item @@set @var{flag} [@var{string}] -Make @var{flag} active, causing the Texinfo formatting commands to -format text between subsequent pairs of @code{@@ifset @var{flag}} and -@code{@@end ifset} commands. Optionally, set value of @var{flag} to -@var{string}. -@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}. - -@item @@setchapternewpage @var{on-off-odd} -Specify whether chapters start on new pages, and if so, whether on -odd-numbered (right-hand) new pages. @xref{setchapternewpage, , -@code{@@setchapternewpage}}. - -@item @@setcontentsaftertitlepage -Put the table of contents after the @samp{@@end titlepage} even if the -@code{@@contents} command is not there. @xref{Contents}. - -@item @@setfilename @var{info-file-name} -Provide a name to be used by the Info file. This command is essential -for @TeX{} formatting as well, even though it produces no output. -@xref{setfilename, , @code{@@setfilename}}. - -@item @@setshortcontentsaftertitlepage -Place the short table of contents after the @samp{@@end titlepage} -command even if the @code{@@shortcontents} command is not there. -@xref{Contents}. - -@item @@settitle @var{title} -Provide a title for page headers in a printed manual, and the default -document description for HTML @samp{<head>}. -@xref{settitle, , @code{@@settitle}}.@refill - -@item @@shortcaption -Define the short caption for a @code{@@float}. @xref{caption shortcaption}. - -@item @@shortcontents -Print a short table of contents. Not relevant to Info, which uses -menus rather than tables of contents. A synonym for -@code{@@summarycontents}. @xref{Contents, , Generating a Table of -Contents}.@refill - -@item @@shorttitlepage @var{title} -Generate a minimal title page. @xref{titlepage,,@code{@@titlepage}}. - -@item @@slanted@{@var{text}@} -Print @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{smallbook, , -Printing Small Books}. Also, see @ref{small}. - -@item @@smalldisplay -Begin a kind of example. Like @code{@@smallexample} (narrow margins, no -filling), but do not select the fixed-width font. Pair with @code{@@end -smalldisplay}. @xref{small}. - -@item @@smallexample -Indent text to indicate an example. Do not fill, select fixed-width -font, narrow the margins. In printed manuals, print text in a smaller -font than with @code{@@example}. Pair with @code{@@end smallexample}. -@xref{small}. - -@item @@smallformat -Begin a kind of example. Like @code{@@smalldisplay}, but do not narrow -the margins. Pair with @code{@@end smallformat}. @xref{small}. - -@item @@smalllisp -Begin an example of Lisp code. Same as @code{@@smallexample}. Pair -with @code{@@end smalllisp}. @xref{small}. - -@item @@sp @var{n} -Skip @var{n} blank lines. @xref{sp, , @code{@@sp}}.@refill - -@item @@ss@{@} -Generate the German sharp-S es-zet letter, @ss{}. @xref{Inserting Accents}. - -@item @@strong @{@var{text}@} -Emphasize @var{text} by typesetting it in a @strong{bold} font for the -printed manual and by surrounding it with asterisks for Info. -@xref{emph & strong, , Emphasizing Text}.@refill - -@item @@subheading @var{title} -Print an unnumbered subsection-like heading in the text, but not in -the table of contents of a printed manual. In Info, the title is -underlined with hyphens. @xref{unnumberedsubsec appendixsubsec -subheading, , @code{@@unnumberedsubsec} @code{@@appendixsubsec} -@code{@@subheading}}.@refill - -@item @@subsection @var{title} -Begin a subsection within a section. In a printed manual, the -subsection title is numbered and appears in the table of contents. In -Info, the title is underlined with hyphens. @xref{subsection, , -@code{@@subsection}}.@refill - -@item @@subsubheading @var{title} -Print an unnumbered subsubsection-like heading in the text, but not in -the table of contents of a printed manual. In Info, the title is -underlined with periods. @xref{subsubsection, , The `subsub' -Commands}.@refill - -@item @@subsubsection @var{title} -Begin a subsubsection within a subsection. In a printed manual, -the subsubsection title is numbered and appears in the table of -contents. In Info, the title is underlined with periods. -@xref{subsubsection, , The `subsub' Commands}.@refill - -@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{title subtitle author, , @code{@@title} -@code{@@subtitle} and @code{@@author} Commands}.@refill - -@item @@summarycontents -Print a short table of contents. Not relevant to Info, which uses -menus rather than tables of contents. A synonym for -@code{@@shortcontents}. @xref{Contents, , Generating a Table of -Contents}.@refill - -@item @@syncodeindex @var{from-index} @var{into-index} -Merge the index named in the first argument into the index named in -the second argument, printing the entries from the first index in -@code{@@code} font. @xref{Combining Indices}.@refill - -@item @@synindex @var{from-index} @var{into-index} -Merge the index named in the first argument into the index named in -the second argument. Do not change the font of @var{from-index} -entries. @xref{Combining Indices}.@refill - -@item @@t@{@var{text}@} -Print @var{text} in a @t{fixed-width}, typewriter-like font. -No effect in Info. @xref{Fonts}.@refill - -@item @@tab -Separate columns in a multitable. @xref{Multitable Rows}. - -@item @@table @var{formatting-command} -Begin a two-column table, using @code{@@item} for each entry. Write -each first column entry on the same line as @code{@@item}. First -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{ftable vtable, , @code{@@ftable} and @code{@@vtable}}, -and @ref{itemx, , @code{@@itemx}}.@refill - -@item @@TeX@{@} -Insert the logo @TeX{}. @xref{tex, , @TeX{} and @LaTeX{}}. - -@item @@tex -Enter @TeX{} completely. Pair with @code{@@end tex}. @xref{Raw -Formatter Commands}. - -@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 @@tie@{@} -Generate a normal interword space at which a line break is not allowed. -@xref{tie,, @code{@@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}.@refill - -@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{title -subtitle author, , The @code{@@title} @code{@@subtitle} and -@code{@@author} Commands}.@refill - -@item @@titlefont@{@var{text}@} -In a printed manual, print @var{text} in a larger than normal font. -Not relevant to Info, which does not have title pages. -@xref{titlefont center sp, , The @code{@@titlefont} @code{@@center} -and @code{@@sp} Commands}.@refill - -@item @@titlepage -Indicate to Texinfo the beginning of the title page. Write command on -a line of its own. Pair with @code{@@end titlepage}. Nothing between -@code{@@titlepage} and @code{@@end titlepage} appears in Info. -@xref{titlepage, , @code{@@titlepage}}.@refill - -@item @@today@{@} -Insert the current date, in `1 Jan 1900' style. @xref{Custom -Headings, , How to Make Your Own Headings}.@refill - -@item @@top @var{title} -In a Texinfo file to be formatted with @code{makeinfo}, identify the -topmost @code{@@node} in the file, which must be written on the line -immediately preceding the @code{@@top} command. Used for -@code{makeinfo}'s node pointer insertion feature. The title is -underlined with asterisks. Both the @code{@@node} line and the @code{@@top} -line normally should be enclosed by @code{@@ifnottex} and @code{@@end -ifnottex}. In @TeX{} and @code{texinfo-format-buffer}, the @code{@@top} -command is merely a synonym for @code{@@unnumbered}. @xref{makeinfo -Pointer Creation, , Creating Pointers with @code{makeinfo}}. - -@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 @@unnumbered @var{title} -In a printed manual, begin a chapter that appears without chapter -numbers of any kind. The title appears in the table of contents of a -printed manual. In Info, the title is underlined with asterisks. -@xref{unnumbered & appendix, , @code{@@unnumbered} and -@code{@@appendix}}.@refill - -@item @@unnumberedsec @var{title} -In a printed manual, 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{unnumberedsec appendixsec heading, , Section Commands}.@refill - -@item @@unnumberedsubsec @var{title} -In a printed manual, begin an unnumbered subsection within a -chapter. The title appears in the table of contents of a printed -manual. In Info, the title is underlined with hyphens. -@xref{unnumberedsubsec appendixsubsec subheading, , -@code{@@unnumberedsubsec} @code{@@appendixsubsec} -@code{@@subheading}}.@refill - -@item @@unnumberedsubsubsec @var{title} -In a printed manual, begin an unnumbered subsubsection within a -chapter. The title appears in the table of contents of a printed -manual. In Info, the title is underlined with periods. -@xref{subsubsection, , The `subsub' Commands}.@refill - -@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 for the -World Wide Web. @xref{uref, , @code{@@uref}}. - -@item @@v@{@var{c}@} -Generate check accent over the character @var{c}, as in @v{o}. -@xref{Inserting Accents}. - -@item @@value@{@var{flag}@} -Replace @var{flag} with the value to which it is set by @code{@@set -@var{flag}}. -@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill - -@item @@var@{@var{metasyntactic-variable}@} -Highlight a metasyntactic variable, which is something that stands for -another piece of text. @xref{var, , Indicating Metasyntactic -Variables}.@refill - -@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{verb,,@code{verb}}. - -@item @@verbatim -Output the text of the environment exactly as is (in the fixed-width -font). Pair with @code{@@end verbatim}. @xref{verbatim,,@code{verbatim}}. - -@item @@verbatiminclude @var{filename} -Output the contents of @var{filename} exactly as is (in the fixed-width font). -@xref{verbatiminclude,,@code{verbatiminclude}}. - -@item @@vindex @var{entry} -Add @var{entry} to the index of variables. @xref{Index Entries, , -Defining the Entries of an Index}.@refill - -@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{ftable vtable, , -@code{@@ftable} and @code{@@vtable}}.@refill - -@item @@w@{@var{text}@} -Prevent @var{text} from being split across two lines. -@xref{w, , @code{@@w}}.@refill - -@item @@xml -Enter XML completely. Pair with @code{@@end xml}. @xref{Raw -Formatter Commands}. - -@item @@xref@{@var{node-name}, [@var{entry}], [@var{topic-or-title}], [@var{info-file}], [@var{manual}]@} -Make a reference that starts with `See' in a printed manual. Follow -command with a punctuation mark. Only the first argument is -mandatory. @xref{xref, , @code{@@xref}}.@refill -@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 special Texinfo commands. -(It has the same meaning that @samp{\} has in plain @TeX{}.) Texinfo -has four types of @@-command:@refill - -@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 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 left- and -right-hand braces. These commands insert special symbols in the -document; they do not require arguments. For example, -@code{@@dots@{@}} @result{} @samp{@dots{}}, @code{@@equiv@{@}} -@result{} @samp{@equiv{}}, @code{@@TeX@{@}} @result{} `@TeX{}', -and @code{@@bullet@{@}} @result{} @samp{@bullet{}}.@refill - -@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.}@refill - -@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.@refill -@end table - -@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 together with 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.@refill - -The purpose of having a different syntax for commands of classes 3 and -4 is to make Texinfo files easier to read, and also to help the GNU -Emacs paragraph and filling commands work properly. There is only one -exception to this rule: the command @code{@@refill}, which is always -used at the end of a paragraph immediately following the final period -or other punctuation character. @code{@@refill} takes no argument and -does @emph{not} require braces. @code{@@refill} never confuses the -Emacs paragraph commands because it cannot appear at the beginning of -a line. It is also no longer needed, since all formatters now refill -paragraphs automatically. - - -@node Tips -@appendix Tips and Hints - -Here are some tips for writing Texinfo documentation:@refill - -@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 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 lower case. Terse entries often call for -lower case; 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 upper case 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. Otherwise, a formatter may fold title and -paragraph together. - -@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 or before an @code{@@end 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) and the Top node (for people reading the online output). - -It is easiest to do this using @code{@@set} and @code{@@value}. -@xref{value Example, , @code{@@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.@refill - -@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 upper case. - -@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{}. -@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 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 @@pxref - -@c !!! maybe include this in the tips on pxref -@ignore -By the way, it is okay to use pxref with something else in front of -it within the parens, as long as the pxref is followed by the close -paren, and the material inside the parens is not part of a larger -sentence. Also, you can use xref inside parens as part of a complete -sentence so long as you terminate the cross reference with punctuation. -@end ignore -Absolutely never use @code{@@pxref} except in the special context for -which it is designed: inside parentheses, with the closing parenthesis -following immediately after the closing brace. One formatter -automatically inserts closing punctuation and the other does not. This -means that the output looks right both in printed output and in an Info -file, but only when the command is used inside parentheses. - -@subsubheading Invoking from a Shell - -You can invoke programs such as Emacs, GCC, and @code{gawk} from a -shell. The documentation for each program should contain a section that -describes this. Unfortunately, if the node names and titles for these -sections are all different, they are difficult for users to find. - -So, there is a convention to name such sections with a phrase beginning -with the word `Invoking', as in `Invoking Emacs'; this way, users can -find the section easily. - - -@subsubheading ANSI C Syntax - -When you use @code{@@example} to describe a C function's calling -conventions, use the ANSI C syntax, like this:@refill - -@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}.@refill - -@need 800 -Avoid the obsolete style that looks like this:@refill - -@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.@refill - -@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{} 2005 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 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,, Overview, cvs, -Concurrent Versions System}) or RCS -(@url{http://www.gnu.org/software/rcs}) version control systems, which -expand it into a string such as: -@example -$Id: texinfo.txi,v 1.220 2008/04/09 17:07:31 karl Exp $ -@end example -(This is 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 version. - -If you want to literally write @t{@w{$}Id$}, use @code{@@w}: -@code{@@w@{$@}Id$}. - -@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,, Introduction, automake, GNU -Automake}). It sets the @samp{VERSION} and @samp{UPDATED} values used -elsewhere. If your distribution doesn't use Automake, but you do use -Emacs, you may find the time-stamp.el package helpful (@pxref{Time -Stamps,,,emacs,The GNU Emacs Manual}). - -@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 not published on paper by the FSF, then omit the -last sentence in the Back-Cover Text that talks about copies from GNU -Press. - -@item -If your manual has Invariant Sections (again, see the license itself -for details), then change the text here accordingly. - -@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: texinfo.txi,v 1.220 2008/04/09 17:07:31 karl Exp $ -@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{} 2007 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.2 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 -* sample: (sample)Invoking sample. -@end direntry - -@titlepage -@title GNU Sample -@subtitle for version @value{VERSION}, @value{UPDATED} -@author A.U. Thor (@email{bug-texinfo@@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:: -* Copying This Manual:: -* 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 was, 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 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 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{} 2005 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{} 2005 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 Include Files -@appendix Include Files -@cindex Include files - -When @TeX{} or an Info formatting command sees an @code{@@include} -command in a Texinfo file, it processes the contents of the file named -by the command and incorporates them into the DVI or Info file being -created. Index entries from the included file are incorporated into -the indices of the output file. - -Include files 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. -* 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 - -The name of the file is taken literally, with a single exception: -@code{@@value@{@var{var}@}} references are expanded. This makes it -possible to reliably include files in other directories in a -distribution. @xref{verbatiminclude,,@code{@@verbatiminclude}}, for -an example. - -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 phrase is inserted -into the output file as is. Likewise, you should not end an included -file with an @code{@@bye} command; nothing after @code{@@bye} is -formatted. - -In the 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.@refill - -Conventionally, an included file begins with an @code{@@node} line that -is followed by an @code{@@chapter} line. Each included file is one -chapter. This makes it easy to use the regular node and menu creating -and updating commands to create the node pointers and menus within the -included file. However, the simple Emacs node and menu creating and -updating commands do not work with multiple Texinfo files. Thus you -cannot use these commands to fill in the `Next', `Previous', and `Up' -pointers of the @code{@@node} line that begins the included file. Also, -you cannot use the regular commands to create a master menu for the -whole file. Either you must insert the menus and the `Next', -`Previous', and `Up' pointers by hand, or you must use the GNU Emacs -Texinfo mode command, @code{texinfo-multiple-files-update}, that is -designed for @code{@@include} files.@refill - -When an included file does not have any node lines in it, the -multiple files update command does not try to create a menu entry -for it. Consequently, you can include any file, such as a -version or an update file without node lines, not just files that -are chapters. Small includable files like this are created by -Automake (@pxref{GNU Sample Texts}). - - -@node texinfo-multiple-files-update -@section @code{texinfo-multiple-files-update} -@findex texinfo-multiple-files-update - -GNU Emacs Texinfo mode provides the @code{texinfo-multiple-files-update} -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 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:@refill - -@table @kbd -@item M-x texinfo-multiple-files-update -Called without any arguments:@refill - -@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.@refill - -@item -Create or update the `Top' level node pointers of the outer or -overall file.@refill - -@item -Create or update a main menu in the outer file.@refill -@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.@refill -@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.@refill - -@item -Create or update @strong{all} the menus of all the included -files.@refill - -@item -Create or update the `Top' level node pointers of the outer or -overall file.@refill - -@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.@refill -@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.@refill - - -@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.@refill - -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.@refill - -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.@refill - - -@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 GNU Emacs Lisp Reference -Manual} is named @file{elisp.texi}. This outer file contains a master -menu with 417 entries and a list of 41 @code{@@include} -files. - - -@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 Emacs did not need to -make a large buffer to hold the whole of a large Info file when -someone wanted information; instead, Emacs allocated just enough -memory for the small Info file that contained the particular -information sought. This way, Emacs could avoid wasting memory.@refill - -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}.)@refill - -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.)@refill - -However, because large Info files are now split automatically, it is -no longer necessary to keep them small.@refill - -Nowadays, multiple Texinfo files are used mostly for large documents, -such as @cite{The GNU Emacs Lisp Reference Manual}, and for projects -in which several different people write different sections of a -document simultaneously.@refill - -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.@refill - - -@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. (Headings and footings have no meaning to Info, which is -not paginated.)@refill - -@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.@refill - -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.@refill - -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.@refill - -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.@refill - -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.@refill - -@node Heading Format -@comment node-name, next, previous, up -@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.@refill - -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.@refill - -@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.)@refill - -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.@refill - -@need 750 -Two pages, side by side as in an open book, look like this:@refill - -@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.@refill - -@node Heading Choice -@comment node-name, next, previous, up -@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.@refill - -@need 1000 -There are four possibilities:@refill - -@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}.@refill - -@item @code{@@setchapternewpage on} -Specify the single-sided heading format, with chapters on new pages.@refill - -@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; see -@ref{headings on off, , The @code{@@headings} Command}.)@refill - -@item @code{@@setchapternewpage odd} -Specify the double-sided heading format, with chapters on new pages.@refill -@end table - -@noindent -Texinfo lacks an @code{@@setchapternewpage even} command.@refill - -@node Custom Headings -@comment node-name, next, previous, up -@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} @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 Formatting 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. - -Emacs has two tools for catching the @@-command mistakes and two for -catching structuring mistakes.@refill - -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.@refill - -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.@refill - -@menu -* 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 texinfo-show-structure:: How to use @code{texinfo-show-structure}. -* Using occur:: How to list all lines containing a pattern. -* Running Info-Validate:: How to find badly referenced nodes. -@end menu - - -@node makeinfo Preferred -@section @code{makeinfo} Find Errors - -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.@refill - -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.@refill - -@node Debugging with Info -@comment node-name, next, previous, up -@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.@refill - -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}.@refill - -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).@refill - -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:@refill - -@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:@refill - -@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:@refill - -@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.@refill - -Sometimes @code{texinfo-format-region} fails to detect mistakes. For -example, in the following, the closing brace is swapped with the -closing parenthesis:@refill - -@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:@refill - -@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}).) - -@c !!! section on using Elisp debugger ignored. -@ignore -Sometimes @code{texinfo-format-region} will stop long after the -original error; this is because it does not discover the problem until -then. In this case, you will need to backtrack.@refill - -@c menu -@c * Using the Emacs Lisp Debugger:: How to use the Emacs Lisp debugger. -@c end menu - -@c node Using the Emacs Lisp Debugger -@c appendixsubsec Using the Emacs Lisp Debugger -@c index Using the Emacs Lisp debugger -@c index Emacs Lisp debugger -@c index Debugger, using the Emacs Lisp - -If an error is especially elusive, you can turn on the Emacs Lisp -debugger and look at the backtrace; this tells you where in the -@code{texinfo-format-region} function the problem occurred. You can -turn on the debugger with the command:@refill - -@example -M-x set-variable @key{RET} debug-on-error @key{RET} t @key{RET} -@end example - -@noindent -and turn it off with - -@example -M-x set-variable @key{RET} debug-on-error @key{RET} nil @key{RET} -@end example - -Often, when you are using the debugger, it is easier to follow what is -going on if you use the Emacs Lisp files that are not byte-compiled. -The byte-compiled sources send octal numbers to the debugger that may -look mysterious. To use the uncompiled source files, load -@file{texinfmt.el} and @file{texinfo.el} with the @kbd{M-x load-file} -command.@refill - -The debugger will not catch an error if @code{texinfo-format-region} -does not detect one. In the example shown above, -@code{texinfo-format-region} did not find the error when the whole -list was formatted, but only when part of the list was formatted. -When @code{texinfo-format-region} did not find an error, the debugger -did not find one either. @refill - -However, when @code{texinfo-format-region} did report an error, it -invoked the debugger. This is the backtrace it produced:@refill - -@example ----------- Buffer: *Backtrace* ---------- -Signalling: (search-failed "[@},]") - re-search-forward("[@},]") - (while ...) - (let ...) - texinfo-format-parse-args() - (let ...) - texinfo-format-xref() - funcall(texinfo-format-xref) - (if ...) - (let ...) - (if ...) - (while ...) - texinfo-format-scan() - (save-excursion ...) - (let ...) - texinfo-format-region(103370 103631) -* call-interactively(texinfo-format-region) ----------- Buffer: *Backtrace* ---------- -@end example - -The backtrace is read from the bottom up. -@code{texinfo-format-region} was called interactively; and it, in -turn, called various functions, including @code{texinfo-format-scan}, -@code{texinfo-format-xref} and @code{texinfo-format-parse-args}. -Inside the function @code{texinfo-format-parse-args}, the function -@code{re-search-forward} was called; it was this function that could -not find the missing right-hand brace.@refill - -@xref{Lisp Debug, , Debugging Emacs Lisp, emacs, The GNU Emacs -Manual}, for more information.@refill -@end ignore - -@node Debugging with TeX -@comment node-name, next, previous, up -@section Catching Errors with @TeX{} Formatting -@cindex Catching errors with @TeX{} formatting -@cindex Debugging with @TeX{} formatting - -You can also catch mistakes when you format a file with @TeX{}.@refill - -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.)@refill - -For example, @TeX{} was run on a Texinfo file, part of which is shown -here:@refill - -@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:@refill - -@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.@refill - -Unfortunately, @TeX{} is not always so helpful, and sometimes you must -truly be a Sherlock Holmes to discover what went wrong.@refill - -In any case, if you run into a problem like this, you can do one of three -things.@refill - -@enumerate -@item -You can tell @TeX{} to continue running and ignore just this error by -typing @key{RET} at the @samp{?} prompt.@refill - -@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.@refill - -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 Emacs). - -@item -You can tell @TeX{} to stop this run by typing @kbd{x @key{RET}} -at the @samp{?} prompt.@refill -@end enumerate - -If you are running @TeX{} inside Emacs, you need to switch to the shell -buffer and line at which @TeX{} offers the @samp{?} prompt. - -Sometimes @TeX{} will format a file without producing error messages even -though there is a problem. This usually occurs if a command is not ended -but @TeX{} is able to continue processing anyhow. For example, if you fail -to end an itemized list with the @code{@@end itemize} command, @TeX{} will -write a DVI file that you can print out. The only error message that -@TeX{} will give you is the somewhat mysterious comment that@refill - -@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.@refill - -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.@refill - -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.@refill - -@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.)@refill - -@node Using texinfo-show-structure -@comment node-name, next, previous, up -@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.@refill - -In GNU Emacs, in Texinfo mode, the @code{texinfo-show-structure} -command lists all the lines that begin with the @@-commands that -specify the structure: @code{@@chapter}, @code{@@section}, -@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.@refill - -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:@refill - -@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, emacs, The GNU Emacs Manual}, for more -information about @code{occur-mode-goto-occurrence}.@refill - -The first line in the @samp{*Occur*} window describes the @dfn{regular -expression} specified by @var{texinfo-heading-pattern}. This regular -expression is the pattern that @code{texinfo-show-structure} looks for. -@xref{Regexps, , Using Regular Expressions, emacs, The GNU Emacs Manual}, -for more information.@refill - -When you invoke the @code{texinfo-show-structure} command, Emacs will -display the structure of the whole buffer. If you want to see the -structure of just a part of the buffer, of one chapter, for example, -use the @kbd{C-x n n} (@code{narrow-to-region}) command to mark the -region. (@xref{Narrowing, , , emacs, The GNU Emacs Manual}.) This is -how the example used above was generated. (To see the whole buffer -again, use @kbd{C-x n w} (@code{widen}).)@refill - -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.@refill - -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.@refill - -@node Using occur -@comment node-name, next, previous, up -@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@refill - -@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, -emacs, The GNU Emacs Manual}.) The @code{occur} command works from -the current location of the cursor in the buffer to the end of the -buffer. If you want to run @code{occur} on the whole buffer, place -the cursor at the beginning of the buffer.@refill - -For example, to see all the lines that contain the word -@samp{@@chapter} in them, just type @samp{@@chapter}. This will -produce a list of the chapters. It will also list all the sentences -with @samp{@@chapter} in the middle of the line.@refill - -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.@refill - -@xref{Other Repeating Search, , Using Occur, emacs , The GNU Emacs Manual}, -for more information.@refill - -@node Running Info-Validate -@comment node-name, next, previous, up -@section Finding Badly Referenced Nodes -@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.@refill - -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.@refill - -@menu -* Using 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 Info-validate -@subsection Running @code{Info-validate} -@cindex Running @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:@refill - -@example -M-x Info-validate -@end example - -@noindent -Note that the @code{Info-validate} command requires an upper case -`I'. You may also need to create a tag table before running -@code{Info-validate}. @xref{Tagifying}. - -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*}.@refill - -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:@refill - -@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).@refill - -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:@refill - -@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.@refill - -@code{Info-validate} also checks that all menu entries and cross references -point to actual nodes.@refill - -@code{Info-validate} requires a tag table and does not work with files -that have been split. (The @code{texinfo-format-buffer} command -automatically splits large files.) In order to use @code{Info-validate} -on a large file, you must run @code{texinfo-format-buffer} with an -argument so that it does not split the Info file; and you must create a -tag table for the unsplit file. - -@node Unsplit -@comment node-name, next, previous, up -@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.@refill - -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:@refill - -@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. @refill -@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:@refill - -@example -M-x Info-tagify -@end example - -@noindent -(Note the upper case @samp{I} in @code{Info-tagify}.) This creates an -Info file with a tag table that you can validate.@refill - -The third step is to validate the Info file:@refill - -@example -M-x Info-validate -@end example - -@noindent -(Note the upper case @samp{I} in @code{Info-validate}.) -In brief, the steps are:@refill - -@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.@refill - -@node Splitting -@comment node-name, next, previous, up -@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}.)@refill - -The split-off files are called the indirect subfiles.@refill - -Info files are split to save memory. With smaller files, Emacs does not -have make such a large buffer to hold the information.@refill - -If an Info file has more than 30 nodes, you should also make a tag -table for it. @xref{Using 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}.)@refill - -@c Info-split is autoloaded in `loaddefs.el' in Emacs 18.51 -@ignore -Before running @code{Info-split}, you need to load the @code{info} library -into Emacs by giving the command @kbd{M-x load-library @key{RET} info -@key{RET}}. -@end ignore - -Visit the Info file you wish to tagify and split and type the two -commands:@refill - -@example -M-x Info-tagify -M-x Info-split -@end example - -@noindent -(Note that the @samp{I} in @samp{Info} is upper case.)@refill - -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.@refill - -The primary file still functions as an Info file, but it contains just -the tag table and a directory of subfiles.@refill - - -@ignore -The simple description in the command summary seems sufficient to me -these days, so ignore this appendix. --karl, 13mar04. - -@node Refilling Paragraphs -@appendix Refilling Paragraphs -@cindex Refilling paragraphs -@cindex Filling paragraphs -@cindex Paragraphs, filling -@findex refill - -The @code{@@refill} command refills and, optionally, indents the first -line of a paragraph.@footnote{Perhaps the command should have been -called the @code{@@refillandindent} command, but @code{@@refill} is -shorter and the name was chosen before indenting was possible.} The -@code{@@refill} command is no longer important, but we describe it here -because you once needed it. You will see it in many old Texinfo -files.@refill - -Without refilling, paragraphs containing long @@-constructs may look -bad after formatting because the formatter removes @@-commands and -shortens some lines more than others. In the past, neither the -@code{texinfo-format-region} command nor the -@code{texinfo-format-buffer} command refilled paragraphs -automatically. The @code{@@refill} command had to be written at the -end of every paragraph to cause these formatters to fill them. (Both -@TeX{} and @code{makeinfo} have always refilled paragraphs -automatically.) Now, all the Info formatters automatically fill and -indent those paragraphs that need to be filled and indented.@refill - -The @code{@@refill} command causes @code{texinfo-format-region} and -@code{texinfo-format-buffer} to refill a paragraph in the Info file -@emph{after} all the other processing has been done. For this reason, -you can not use @code{@@refill} with a paragraph containing either -@code{@@*} or @code{@@w@{ @dots{} @}} since the refilling action will -override those two commands.@refill - -The @code{texinfo-format-region} and @code{texinfo-format-buffer} -commands now automatically append @code{@@refill} to the end of each -paragraph that should be filled. They do not append @code{@@refill} to -the ends of paragraphs that contain @code{@@*} or @w{@code{@@w@{ @dots{}@}}} -and therefore do not refill or indent them.@refill - -@end ignore - - -@c These are no longer ``new'', and the explanations -@c are all given elsewhere anyway, I think. --karl, 25apr97. -@c So ignore the entire appendix. -@ignore -@c node New Features, Command and Variable Index, Obtaining TeX, Top -@c appendix Second Edition Features - -@tex -% Widen the space for the first column so three control-character -% strings fit in the first column. Switched back to default .8in -% value at end of chapter. -\global\tableindent=1.0in -@end tex - -The second edition of the Texinfo manual describes more than 20 new -Texinfo mode commands and more than 50 previously undocumented Texinfo -@@-commands. This edition is more than twice the length of the first -edition.@refill - -Here is a brief description of the new commands.@refill - -@c menu -* New Texinfo Mode Commands:: The updating commands are especially useful. -* New Commands:: Many newly described @@-commands. -@c end menu - -@c node New Texinfo Mode Commands, New Commands, Obtaining TeX, Obtaining TeX -@c appendixsec New Texinfo Mode Commands - -Texinfo mode provides commands and features especially designed for -working with Texinfo files. More than 20 new commands have been -added, including commands for automatically creating and updating -both nodes and menus. This is a tedious task when done by hand.@refill - -The keybindings are intended to be somewhat mnemonic.@refill - -@c subheading Update all nodes and menus - -The @code{texinfo-master-menu} command is the primary command: - -@table @kbd -@item C-c C-u m -@itemx M-x texinfo-master-menu -Create or update a master menu. -With @kbd{C-u} as a prefix argument, -first create or update all nodes -and regular menus. -@end table - -@c subheading Update Pointers - -@noindent -Create or update `Next', `Previous', and `Up' node pointers.@refill - -@noindent -@xref{Updating Nodes and Menus}. - -@table @kbd -@item C-c C-u C-n -@itemx M-x texinfo-update-node -Update a node. - -@item C-c C-u C-e -@itemx M-x texinfo-every-node-update -Update every node in the buffer. -@end table - -@c subheading Update Menus - -@noindent -Create or update menus.@refill - -@noindent -@xref{Updating Nodes and Menus}. - -@table @kbd -@item C-c C-u C-m -@itemx M-x texinfo-make-menu -Make or update a menu. - -@item C-c C-u C-a -@itemx M-x texinfo-all-menus-update -Make or update all the menus in a buffer. -With @kbd{C-u} as a prefix argument, -first update all the nodes. -@end table - -@c subheading Insert Title as Description - -@noindent -Insert a node's chapter or section title in the space for the -description in a menu entry line; position point so you can edit the -insert. (This command works somewhat differently than the other -insertion commands, which insert only a predefined string.)@refill - -@noindent -@xref{Inserting, Inserting Frequently Used Commands}. - -@table @kbd -@item C-c C-c C-d -Insert title. -@end table - -@c subheading Format for Info - -@noindent -Provide keybindings both for the Info formatting commands that are -written in Emacs Lisp and for @code{makeinfo} that is written in -C.@refill - -@noindent -@xref{Info Formatting}. - -@noindent -Use the Emacs lisp @code{texinfo-format@dots{}} commands: - -@table @kbd -@item C-c C-e C-r -Format the region. - -@item C-c C-e C-b -Format the buffer. -@end table - -@noindent -Use @code{makeinfo}: - -@table @kbd -@item C-c C-m C-r -Format the region. - -@item C-c C-m C-b -Format the buffer. - -@item C-c C-m C-l -Recenter the @code{makeinfo} output buffer. - -@item C-c C-m C-k -Kill the @code{makeinfo} formatting job. -@end table - -@c subheading Typeset and Print - -@noindent -Typeset and print Texinfo documents from within Emacs. - -@noindent -@xref{Printing}. - -@table @kbd -@item C-c C-t C-b -Run @code{texi2dvi} on the buffer. - -@item C-c C-t C-r -Run @TeX{} on the region. - -@item C-c C-t C-i -Run @code{texindex}. - -@item C-c C-t C-p -Print the DVI file. - -@item C-c C-t C-q -Show the print queue. - -@item C-c C-t C-d -Delete a job from the print queue. - -@item C-c C-t C-k -Kill the current @TeX{} formatting job. - -@item C-c C-t C-x -Quit a currently stopped @TeX{} formatting job. - -@item C-c C-t C-l -Recenter the output buffer. -@end table - -@c subheading Other Updating Commands - -@noindent -The ``other updating commands'' do not have standard keybindings because -they are used less frequently.@refill - -@noindent -@xref{Other Updating Commands}. - -@table @kbd -@item M-x texinfo-insert-node-lines -Insert missing @code{@@node} lines using -section titles as node names. - -@item M-x texinfo-multiple-files-update -Update a multi-file document. -With a numeric prefix, such as @kbd{C-u 8}, -update @strong{every} pointer and -menu in @strong{all} the files and -then insert a master menu. - -@item M-x texinfo-indent-menu-description -Indent descriptions in menus. - -@item M-x texinfo-sequential-node-update -Insert node pointers in strict sequence. -@end table - -@c no.de New Commands, , New Texinfo Mode Commands, Obtaining TeX -@c appendix.sec New Texinfo @@-Commands - -The second edition of the Texinfo manual describes more than 50 -commands that were not described in the first edition. A third or so -of these commands existed in Texinfo but were not documented in the -manual; the others are new. Here is a listing, with brief -descriptions of them:@refill - -@c subheading Indexing - -@noindent -Create your own index, and merge indices.@refill - -@noindent -@xref{Indices}. - -@table @kbd -@item @@defindex @var{index-name} -Define a new index and its indexing command. -See also the @code{@@defcodeindex} command. - -@c written verbosely to avoid overfull hbox -@item @@synindex @var{from-index} @var{into-index} -Merge the @var{from-index} index into the @var{into-index} index. -See also the @code{@@syncodeindex} command. -@end table - -@c subheading Definitions - -@noindent -Describe functions, variables, macros, -commands, user options, special forms, and other such artifacts in a -uniform format.@refill - -@noindent -@xref{Definition Commands}. - -@table @kbd -@item @@deffn @var{category} @var{name} @var{arguments}@dots{} -Format a description for functions, interactive -commands, and similar entities. - -@item @@defvr, @@defop, @dots{} -15 other related commands. -@end table - -@c subheading Glyphs - -@noindent -Indicate the results of evaluation, expansion, -printed output, an error message, equivalence of expressions, and the -location of point.@refill - -@noindent -@xref{Glyphs}. - -@table @kbd -@item @@equiv@{@} -@itemx @equiv{} -Equivalence: - -@item @@error@{@} -@itemx @error{} -Error message - -@item @@expansion@{@} -@itemx @expansion{} -Macro expansion - -@item @@point@{@} -@itemx @point{} -Position of point - -@item @@print@{@} -@itemx @print{} -Printed output - -@item @@result@{@} -@itemx @result{} -Result of an expression -@end table - -@c subheading Page Headings - -@noindent -Customize page headings. - -@noindent -@xref{Headings}. - -@table @kbd -@item @@headings @var{on-off-single-double} -Headings on or off, single, or double-sided. - -@item @@evenfooting [@var{left}] @@| [@var{center}] @@| [@var{right}] -Footings for even-numbered (left-hand) pages. - -@item @@evenheading, @@everyheading, @@oddheading, @dots{} -Five other related commands. - -@item @@thischapter -Insert name of chapter and chapter number. - -@item @@thischaptername, @@thisfile, @@thistitle, @@thispage -Related commands. -@end table - -@c subheading Formatting - -@noindent -Format blocks of text. - -@noindent -@xref{Quotations and Examples}, and@* -@ref{Lists and Tables, , Making Lists and Tables}. - -@table @kbd -@item @@cartouche -Draw rounded box surrounding text (no effect in Info). - -@item @@enumerate @var{optional-arg} -Enumerate a list with letters or numbers. - -@item @@exdent @var{line-of-text} -Remove indentation. - -@item @@flushleft -Left justify. - -@item @@flushright -Right justify. - -@item @@format -Do not narrow nor change font. - -@item @@ftable @var{formatting-command} -@itemx @@vtable @var{formatting-command} -Two-column table with indexing. - -@item @@lisp -For an example of Lisp code. - -@item @@smallexample -@itemx @@smalllisp -Like @@table and @@lisp, but for (originally) @@smallbook. -@end table - -@c subheading Conditionals - -@noindent -Conditionally format text. - -@noindent -@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill - -@table @kbd -@item @@set @var{flag} [@var{string}] -Set a flag. Optionally, set value -of @var{flag} to @var{string}. - -@item @@clear @var{flag} -Clear a flag. - -@item @@value@{@var{flag}@} -Replace with value to which @var{flag} is set. - -@item @@ifset @var{flag} -Format, if @var{flag} is set. - -@item @@ifclear @var{flag} -Ignore, if @var{flag} is set. -@end table - -@c subheading @@heading series for Titles - -@noindent -Produce unnumbered headings that do not appear in a table of contents. - -@noindent -@xref{Structuring}. - -@table @kbd -@item @@heading @var{title} -Unnumbered section-like heading not listed -in the table of contents of a printed manual. - -@item @@chapheading, @@majorheading, @@c subheading, @@subsubheading -Related commands. -@end table - -@need 1000 -@c subheading Font commands - -@need 1000 -@noindent -@xref{Smallcaps}, and @* -@ref{Fonts}. - -@table @kbd -@item @@r@{@var{text}@} -Print in roman font. - -@item @@sc@{@var{text}@} -Print in @sc{small caps} font. -@end table - -@c subheading Miscellaneous - -@noindent -See @ref{title subtitle author, , @code{@@title} @code{@@subtitle} and @code{@@author} Commands},@* -see @ref{Customized Highlighting},@* -see @ref{Overfull hboxes},@* -see @ref{Footnotes},@* -see @ref{dmn, , Format a Dimension},@* -see @ref{Raise/lower sections, , @code{@@raisesections} and @code{@@lowersections}},@* -see @ref{math, , @code{@@math}: Inserting Mathematical Expressions}.@* -see @ref{minus, , Inserting a Minus Sign},@* -see @ref{paragraphindent, , Paragraph Indenting},@* -see @ref{Cross Reference Commands},@* -see @ref{title subtitle author, , @code{@@title} @code{@@subtitle} and @code{@@author}}, and@* -see @ref{Custom Headings, , How to Make Your Own Headings}. - -@table @kbd -@item @@author @var{author} -Typeset author's name. - -@c @item @@definfoenclose @var{new-command}, @var{before}, @var{after}, -@c Define a highlighting command for Info. (Info only.) - -@item @@finalout -Produce cleaner printed output. - -@item @@footnotestyle @var{end-or-separate} -Specify footnote style. - -@item @@dmn@{@var{dimension}@} -Format a dimension. - -@item @@global@@let@var{new-cmd}=@var{existing-cmd} -Define a highlighting command for @TeX{}. (@TeX{} only.) - -@item @@lowersections -Reduce hierarchical level of sectioning commands. - -@item @@math@{@var{mathematical-expression}@} -Format a mathematical expression. - -@item @@minus@{@} -Generate a minus sign. - -@item @@paragraphindent @var{asis-or-number} -Specify paragraph indentation. - -@item @@raisesections -Raise hierarchical level of sectioning commands. - -@item @@ref@{@var{node-name}, @r{[}@var{entry}@r{]}, @r{[}@var{topic-or-title}@r{]}, @r{[}@var{info-file}@r{]}, @r{[}@var{manual}@r{]}@} -Make a reference. In the printed manual, the -reference does not start with the word `see'. - -@item @@title @var{title} -Typeset @var{title} in the alternative -title page format. - -@item @@subtitle @var{subtitle} -Typeset @var{subtitle} in the alternative -title page format. - -@item @@today@{@} -Insert the current date. -@end table -@tex -% Switch width of first column of tables back to default value -\global\tableindent=.8in -@end tex -@end ignore - - -@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 Emacs Lisp -functions, and several variables. To make the list easier to use, the -commands are listed without their preceding @samp{@@}.@refill - -@printindex fn - - -@node General Index -@unnumbered General Index - -@printindex cp - - -@bye |