diff options
Diffstat (limited to 'Master/texmf/doc/info/texinfo.info')
-rw-r--r-- | Master/texmf/doc/info/texinfo.info | 18328 |
1 files changed, 18328 insertions, 0 deletions
diff --git a/Master/texmf/doc/info/texinfo.info b/Master/texmf/doc/info/texinfo.info new file mode 100644 index 00000000000..babfcb3c651 --- /dev/null +++ b/Master/texmf/doc/info/texinfo.info @@ -0,0 +1,18328 @@ +This is texinfo.info, produced by makeinfo version 4.7 from texinfo.txi. + + This manual is for GNU Texinfo (version 4.7, 9 April 2004), a +documentation system that can produce both online information and a +printed manual from a single source. + + Copyright (C) 1988, 1990, 1991, 1992, 1993, 1995, 1996, 1997, 1998, +1999, 2000, 2001, 2002, 2003, 2004 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation License, + Version 1.1 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 freedom to copy and + modify this GNU Manual, like GNU software. Copies published by + the Free Software Foundation raise funds for GNU development." + +INFO-DIR-SECTION Texinfo documentation system +START-INFO-DIR-ENTRY +* Texinfo: (texinfo). The GNU documentation format. +* install-info: (texinfo)Invoking install-info. Update info/dir entries. +* texi2dvi: (texinfo)Format with texi2dvi. Print Texinfo documents. +* texindex: (texinfo)Format with tex/texindex. Sort Texinfo index files. +* makeinfo: (texinfo)Invoking makeinfo. Translate Texinfo source. +END-INFO-DIR-ENTRY + + +File: texinfo.info, Node: Top, Next: Copying Conditions, Up: (dir) + +Texinfo +******* + +This manual is for GNU Texinfo (version 4.7, 9 April 2004), a +documentation system that can produce both online information and a +printed manual from a single source. + + Copyright (C) 1988, 1990, 1991, 1992, 1993, 1995, 1996, 1997, 1998, +1999, 2000, 2001, 2002, 2003, 2004 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation License, + Version 1.1 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 freedom to copy and + modify this GNU Manual, like GNU software. Copies published by + the Free Software Foundation raise funds for GNU development." + + 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. + +* 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. +* Copying This Manual:: The GNU Free Documentation License. +* Command and Variable Index:: A menu containing commands and variables. +* Concept Index:: A menu covering many topics. + + --- 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 `@titlefont', `@center', + and `@sp' commands. +* title subtitle author:: The `@title', `@subtitle', + and `@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 ... +* Structuring Command Types:: How to divide a manual into parts. +* makeinfo top:: The `@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 `@node' Command + +* Node Names:: How to choose node and pointer names. +* Writing a Node:: How to write an `@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 `@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' ... +* 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. + +`@xref' + +* Reference Syntax:: What a reference looks like and requires. +* One Argument:: `@xref' with one argument. +* Two Arguments:: `@xref' with two arguments. +* Three Arguments:: `@xref' with three arguments. +* Four and Five Arguments:: `@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. +* 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. + +`@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' + 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 Space:: How to insert the right amount of space + within a sentence. +* Inserting Accents:: How to insert accents and special characters. +* Dots Bullets:: How to insert dots and bullets. +* TeX and copyright:: How to insert the TeX logo + and the copyright symbol. +* pounds:: How to insert the pounds currency symbol. +* minus:: How to insert a minus sign. +* math:: How to format a mathematical expression. +* Glyphs:: How to indicate results of evaluation, + expansion of macros, errors, etc. + +Inserting @ and {} and , + +* 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. +* dmn:: How to format a dimension. + +Inserting Ellipsis and Bullets + +* dots:: How to insert dots ... +* bullet:: How to insert a bullet. + +Inserting TeX and Legal Symbols: (C), (R) + +* 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. +* 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. + +`@set', `@clear', and `@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:: `makeinfo' provides better error checking. +* Invoking makeinfo:: How to run `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 `makeinfo' from Emacs. +* texinfo-format commands:: Two Info formatting commands written + in Emacs Lisp are an alternative + to `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:: `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:: + +Copying This Manual + +* GNU Free Documentation License:: License for copying this manual. + +Include Files + +* Using Include Files:: How to use the `@include' command. +* texinfo-multiple-files-update:: How to create and update nodes and + menus when using included files. +* Include Files Requirements:: `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 `@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:: `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 `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 `Info-validate'. +* Unsplit:: How to create an unsplit file. +* Tagifying:: How to tagify a file. +* Splitting:: How to split a file manually. + +Copying This Manual + +* GNU Free Documentation License:: License for copying this manual. + + 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 + + +File: texinfo.info, Node: Copying Conditions, Next: Overview, Prev: Top, Up: Top + +Texinfo Copying Conditions +************************** + +The programs currently being distributed that relate to Texinfo include +`makeinfo', `info', `texindex', and `texinfo.tex'. These programs are +"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 (*note GNU Free Documentation +License::). + + +File: texinfo.info, Node: Overview, Next: Texinfo Mode, Prev: Copying Conditions, Up: Top + +1 Overview of Texinfo +********************* + +"Texinfo"(1) 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. + + ---------- Footnotes ---------- + + (1) 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 `X' is actually the +Greek letter "chi" rather than the English letter "ex". Pronounce TeX +as if the `X' were the last sound in the name `Bach'; but pronounce +Texinfo as if the `x' were a `k'. Spell "Texinfo" with a capital "T" +and the other letters in lower case. + + +File: texinfo.info, Node: Reporting Bugs, Next: Using Texinfo, Up: Overview + +1.1 Reporting Bugs +================== + +We welcome bug reports and suggestions for any aspect of the Texinfo +system, programs, documentation, installation, anything. Please email +them to <bug-texinfo@gnu.org>. You can get the latest version of +Texinfo from `ftp://ftp.gnu.org/gnu/texinfo/' and its mirrors worldwide. + + For bug reports, please include enough information for the maintainers +to reproduce the problem. Generally speaking, that means: + + * the version number of Texinfo and the program(s) or manual(s) + involved. + + * hardware and operating system names and versions. + + * the contents of any input files necessary to reproduce the bug. + + * a description of the problem and samples of any erroneous output. + + * any unusual options you gave to `configure'. + + * anything else that you think would be helpful. + + When in doubt whether something is needed or not, include it. It's +better to include too much than to leave out something important. + + Patches are most welcome; if possible, please make them with +`diff -c' (*note Overview: (diff)Top.) and include `ChangeLog' entries +(*note Change Log: (emacs)Change Log.). + + When sending patches, if possible please do not encode or split them +in any way; it's much easier to deal with one plain text message, +however large, than many small ones. GNU shar +(ftp://ftp.gnu.org/gnu/sharutils/) is a convenient way of packaging +multiple and/or binary files for email. + + +File: texinfo.info, Node: Using Texinfo, Next: Output Formats, Prev: Reporting Bugs, Up: Overview + +1.2 Using 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 (*note 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. + + A Texinfo source file is a plain ASCII file containing text +interspersed with "@-commands" (words preceded by an `@') 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. (*Note 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 GNU documentation web page +(http://www.gnu.org/doc/). + + +File: texinfo.info, Node: Output Formats, Next: Info Files, Prev: Using Texinfo, Up: Overview + +1.3 Output Formats +================== + +Here is a brief overview of the output formats currently supported by +Texinfo. + +Info + (Generated via `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 (*note Info Files::) for more details on this format. The + Emacs Info subsystem (*note Getting Started: (info)Top.), and the + standalone `info' program (*note Info Standalone: + (info-stnd)Top.), among others, can read these files. *Note + Creating and Installing Info Files::. + +Plain text + (Generated via `makeinfo --no-headers'.) This is almost the same + as Info output, except the navigational control characters are + omitted. + +HTML + (Generated via `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; `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 + `http://www.w3.org/MarkUp/'. *Note Generating HTML::. + +DVI + (Generated via `texi2dvi'.) This DeVice Independent binary format + is output by the TeX typesetting program (`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 (*note Invoking Dvips: + (dvips)Invoking Dvips.) and Xdvi for viewing on an X display + (`http://sourceforge.net/projects/xdvi/'). *Note 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 `TeX for + the Impatient', available from + `http://savannah.gnu.org/projects/teximpatient'. + +PDF + (Generated via `texi2dvi --pdf'.) This format, based on + PostScript, was developed by Adobe Systems for document + interchange. It is intended to be platform-independent and easily + viewable, among other design goals; for a discussion, see + `http://tug.org/tugboat/Articles/tb22-3/tb72beebeI.pdf'. Texinfo + uses the `pdftex' program, a variant of TeX, to output pdf; see + `http://tug.org/applications/pdftex'. *Note PDF Output::. + +XML + (Generated via `makeinfo --xml'.) XML is a generic syntax + specification usable for any sort of content (see, for example, + `http://www.w3.org/XML/'). The `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 `texinfo.dtd' included in the + Texinfo source distribution. + +Docbook + (Generated via `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 `http://www.docbook.org'. If you want to convert + from Docbook _to_ Texinfo, please see + `http://docbook2X.sourceforge.net'. + + + 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. + + Man pages still have their place, and if you wish to support them, you +may find the program `help2man' to be useful; it generates a +traditional man page from the `--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 `ftp://ftp.gnu.org/gnu/help2man/'. + + 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 `makeinfo' to generate the new format. + + +File: texinfo.info, Node: Info Files, Next: Printed Books, Prev: Output Formats, Up: Overview + +1.4 Info Files +============== + +An Info file is a Texinfo file formatted so that the Info documentation +reading program can operate on it. (`makeinfo' and +`texinfo-format-buffer' are two commands that convert a Texinfo file +into an Info file.) + + Info files are divided into pieces called "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. + + *Note Top: (info)Top, 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 "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.(1) + + 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. + + 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. + + 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. + + 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 (*note Top: (info)Top.). + + If you want to read through an Info file in sequence, as if it were a +printed manual, you can hit <SPC> repeatedly, or you get the whole file +with the advanced Info command `g *'. (*note Advanced Info commands: +(info)Advanced.) + + The `dir' file in the `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. + + 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: + info:///usr/info/emacs#Dissociated%20Press + info:emacs#Dissociated%20Press + info://localhost/usr/info/emacs#Dissociated%20Press + + The `info' program itself does not follow URI's of any kind. + + ---------- Footnotes ---------- + + (1) 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. + + +File: texinfo.info, Node: Printed Books, Next: Formatting Commands, Prev: Info Files, Up: Overview + +1.5 Printed Books +================= + +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.(1) + + 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. + + 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. + + TeX is a general purpose typesetting program. Texinfo provides a +file `texinfo.tex' that contains information (definitions or "macros") +that TeX uses when it typesets a Texinfo file. (`texinfo.tex' tells +TeX how to convert the Texinfo @-commands to TeX commands, which TeX +can then process to create the typeset document.) `texinfo.tex' +contains the specifications for printing a document. You can get the +latest version of `texinfo.tex' from +`ftp://ftp.gnu.org/gnu/texinfo/texinfo.tex'. + + In the United States, documents are most often printed on 8.5 inch by +11 inch pages (216mm by 280mm); this is the default size. But you can +also print for 7 inch by 9.25 inch pages (178mm by 235mm, the +`@smallbook' size; or on A4 or A5 size paper (`@afourpaper', +`@afivepaper'). (*Note Printing "Small" Books: smallbook. Also, see +*Note Printing on A4 Paper: A4 Paper.) + + By changing the parameters in `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. (*Note +TeX Mode: (emacs)TeX Mode, for information about TeX.) + + 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 *Note How to Obtain TeX: Obtaining TeX. + + ---------- Footnotes ---------- + + (1) You can also use the `texi2roff' (ftp://tug.org/texi2roff.tar.gz) +program if you do not have TeX; since Texinfo is designed for use with +TeX, `texi2roff' is not described here. `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. + + +File: texinfo.info, Node: Formatting Commands, Next: Conventions, Prev: Printed Books, Up: Overview + +1.6 @-commands +============== + +In a Texinfo file, the commands that tell TeX how to typeset the +printed manual and tell `makeinfo' and `texinfo-format-buffer' how to +create an Info file are preceded by `@'; they are called "@-commands". +For example, `@node' is the command to indicate a node and `@chapter' +is the command to indicate the start of a chapter. + + Note: Almost all @ command names are entirely lower case. + + 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. + + Depending on what they do or what arguments(1) they take, you need to +write @-commands on lines of their own or as part of sentences: + + * Write a command such as `@quotation' at the beginning of a line as + the only text on the line. (`@quotation' begins an indented + environment.) + + * Write a command such as `@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. (`@chapter' creates chapter + titles.) + + * Write a command such as `@dots{}' wherever you wish but usually + within a sentence. (`@dots{}' creates dots ...) + + * Write a command such as `@code{SAMPLE-CODE}' wherever you wish + (but usually within a sentence) with its argument, SAMPLE-CODE in + this example, between the braces. (`@code' marks text as being + code.) + + * Write a command such as `@example' on a line of its own; write the + body-text on following lines; and write the matching `@end' + command, `@end example' in this case, on a line of its own after + the body-text. (`@example' ... `@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. + +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 `@:', are exceptions to the rule; they +do not need braces. + + As you gain experience with Texinfo, you will rapidly learn how to +write the different commands: the different ways to write commands +actually make it easier to write and read Texinfo files than if all +commands followed exactly the same syntax. *Note @-Command Syntax: +Command Syntax, for all the details. + + ---------- Footnotes ---------- + + (1) The word "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 `Oxford English +Dictionary', the word derives from the Latin for "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. + + +File: texinfo.info, Node: Conventions, Next: Comments, Prev: Formatting Commands, Up: Overview + +1.7 General Syntactic Conventions +================================= + +This section describes the general conventions used in all Texinfo +documents. + + * All printable ASCII characters except `@', `{' and `}' can appear + in a Texinfo file and stand for themselves. `@' is the escape + character which introduces commands, while `{' and `}' are used to + surround arguments to certain commands. To put one of these + special characters into the document, put an `@' character in + front of it, like this: `@@', `@{', and `@}'. + + * 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 "blank line" means + exactly two consecutive newlines. Sometimes blank lines are + useful or convenient in other cases as well; you can use the + `@noindent' to inhibit paragraph indentation if required (*note + `@noindent': noindent.). + + * Use doubled single-quote characters to begin and end quotations: + ``...''. TeX converts two single quotes to left- and right-hand + doubled quotation marks, and Info converts doubled single-quote + characters to ASCII double-quotes: ``...'' becomes "...". + + You may occasionally need to produce two consecutive single quotes; + for example, in documenting a computer language such as Maxima + where '' is a valid command. You can do this with the input + '@w{}'; the empty `@w' command stops the combination into the + double-quote characters. + + The left quote character (`, 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. We hope to eventually support the various quotation + characters in Unicode. + + * Use three hyphens in a row, `---', to produce a long dash--like + this (called an "em dash"), used for punctuation in sentences. + Use two hyphens, `--', to produce a medium dash-like this (called + an "en dash"), used to separate numeric ranges. Use a single + hyphen, `-', 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' and `@example'. + + * *Caution:* Last and most important, 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, `makeinfo' does nothing special with tabs, and thus a + tab character in your input file will usually appear differently + in the output. + + To avoid this problem, Texinfo mode causes GNU Emacs to insert + multiple spaces when you press the <TAB> key. + + Also, you can run `untabify' in Emacs to convert tabs in a region + to multiple spaces, or use the `unexpand' command from the shell. + + + +File: texinfo.info, Node: Comments, Next: Minimum, Prev: Conventions, Up: Overview + +1.8 Comments +============ + +You can write comments in a Texinfo file that will not appear in either +the Info file or the printed manual by using the `@comment' command +(which may be abbreviated to `@c'). Such comments are for the person +who revises the Texinfo file. All the text on a line that follows +either `@comment' or `@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 `@comment' or `@c' in the middle of a line, +and only the text that follows after the `@comment' or `@c' command +does not appear; but some commands, such as `@settitle' and +`@setfilename', work on a whole line. You cannot use `@comment' or +`@c' in a line beginning with such a command. + + You can write long stretches of text that will not appear in either +the Info file or the printed manual by using the `@ignore' and `@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 +`@ignore' and `@end ignore' for writing comments. + + Text enclosed by `@ignore' or by failing `@ifset' or `@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 _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. + + +File: texinfo.info, Node: Minimum, Next: Six Parts, Prev: Comments, Up: Overview + +1.9 What a Texinfo File Must Have +================================= + +By convention, the namea of a Texinfo file ends with (in order of +preference) one of the extensions `.texinfo', `.texi', `.txi', or +`.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 *must* begin with lines like this: + + \input texinfo + @setfilename INFO-FILE-NAME + @settitle NAME-OF-MANUAL + +The contents of the file follow this beginning, and then you *must* end +a Texinfo file with a line like this: + + @bye + +Here's an explanation: + + * The `\input texinfo' line tells TeX to use the `texinfo.tex' file, + which tells TeX how to translate the Texinfo @-commands into TeX + typesetting commands. (Note the use of the backslash, `\'; this + is correct for TeX.) + + * The `@setfilename' line provides a name for the Info file and + tells TeX to open auxiliary files. *All text before + `@setfilename' is ignored!* + + * The `@settitle' line specifies a title for the page headers (or + footers) of the printed manual, and the default document + description for the `<head>' in HTML format. Strictly speaking, + `@settitle' is optional--if you don't mind your document being + titled `Untitled'. + + * The `@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. + + + 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: + + \input texinfo @c -*-texinfo-*- + @c %**start of header + @setfilename INFO-FILE-NAME + @settitle NAME-OF-MANUAL + @c %**end of header + +In the first line, `-*-texinfo-*-' causes Emacs to switch into Texinfo +mode when you edit the file. + + The `@c' lines which surround the `@setfilename' and `@settitle' +lines are optional, but you need them in order to run TeX or Info on +just part of the file. (*Note 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. + + +File: texinfo.info, Node: Six Parts, Next: Short Sample, Prev: Minimum, Up: Overview + +1.10 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. + +1. Header + The "Header" names the file, tells TeX which definitions file to + use, and other such housekeeping tasks. + +2. Summary and Copyright + The "Summary and Copyright" segment describes the document and + contains the copyright notice and copying permissions. This is + done with the `@copying' command. + +3. Title and Copyright + The "Title and Copyright" segment contains the title and copyright + pages for the printed manual. The segment must be enclosed between + `@titlepage' and `@end titlepage' commands. The title and + copyright page appear only in the printed manual. + +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 + "Master Menu" listing all the nodes in the entire document. + +5. Body + The "Body" of the document is typically structured like a + traditional book or encyclopedia, but it may be free form. + +6. End + The "End" segment contains commands for printing indices and + generating the table of contents, and the `@bye' command on a line + of its own. + + +File: texinfo.info, Node: Short Sample, Next: History, Prev: Six Parts, Up: Overview + +1.11 A Short Sample Texinfo File +================================ + +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 +`\input texinfo' through to `@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. + + *Note Beginning a File::, for full documentation on the commands +listed here. *Note GNU Sample Texts::, for the full texts to be used +in GNU manuals. + + In the following, the sample text is _indented_; comments on it are +not. The complete file, without interspersed comments, is shown in +*Note Short Sample Texinfo File::. + +Part 1: Header +-------------- + +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. + + \input texinfo @c -*-texinfo-*- + @c %**start of header + @setfilename sample.info + @settitle Sample Manual 1.0 + @c %**end of header + +Part 2: Summary Description and Copyright +----------------------------------------- + +A real manual includes more text here, according to the license under +which it is distributed. *Note GNU Sample Texts::. + + @copying + This is a short example of a complete Texinfo file, version 1.0. + + Copyright @copyright{} 2004 Free Software Foundation, Inc. + @end copying + +Part 3: Titlepage, Contents, Copyright +-------------------------------------- + +The titlepage segment does not appear in the online output, only in the +printed manual. We use the `@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 `@contents' +command generates a table of contents. + + @titlepage + @title Sample Title + + @c The following two commands start the copyright page. + @page + @vskip 0pt plus 1filll + @insertcopying + @end titlepage + + @c Output the table of contents at the beginning. + @contents + +Part 4: `Top' Node and Master Menu +---------------------------------- + +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 also include the copying text again for the benefit +of online readers. Since the copying text begins with a brief +description of the manual, no other text is needed in this case. The +`@top' command itself helps `makeinfo' determine the relationships +between nodes. + + @ifnottex + @node Top + @top Short Sample + + @insertcopying + @end ifnottex + + @menu + * First Chapter:: The first chapter is the + only chapter in this sample. + * Index:: Complete index. + @end menu + +Part 5: The Body of the Document +-------------------------------- + +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. + + @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 + +Part 6: The End of the Document +------------------------------- + +The end segment contains commands for generating an index in a node and +unnumbered chapter of its own, and the `@bye' command that marks the +end of the document. + + @node Index + @unnumbered Index + + @printindex cp + + @bye + +Some Results +------------ + +Here is what the contents of the first chapter of the sample look like: + + + This is the first chapter. + + Here is a numbered list. + + 1. This is the first item. + + 2. This is the second item. + + +File: texinfo.info, Node: History, Prev: Short Sample, Up: Overview + +1.12 History +============ + +Richard M. Stallman invented the Texinfo format, wrote the initial +processors, and created Edition 1.0 of this manual. Robert J. +Chassell greatly revised and extended the manual, starting with Edition +1.1. Brian Fox was responsible for the standalone Texinfo distribution +until version 3.8, and wrote the standalone `makeinfo' and `info' +programs. Karl Berry has continued maintenance since Texinfo 3.8 +(manual edition 2.22). + + 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. Franc,ois Pinard and David D. Zuhn, +tirelessly recorded and reported mistakes and obscurities. Zack +Weinberg did the impossible by implementing the macro syntax in +`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 +`ChangeLog' file. Our mistakes are our own. + + 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 +`@' character to introduce commands, as Texinfo does. Much more +consequentially, it strived to describe document contents rather than +formatting, an idea wholeheartedly adopted by Texinfo. + + Meanwhile, people at MIT developed another, not too dissimilar format +called Bolio. This then was converted to using TeX as its typesetting +language: BoTeX. The earliest BoTeX version seems to have been 0.02 on +October 31, 1984. + + BoTeX 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 BoTeX. He also developed a nifty on-line help format +called Info, and then combined BoTeX and Info to create Texinfo, a mark +up language for text that is intended to be read both online and as +printed hard copy. + + +File: texinfo.info, Node: Texinfo Mode, Next: Beginning a File, Prev: Overview, Up: Top + +2 Using Texinfo Mode +******************** + +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. + + +File: texinfo.info, Node: Texinfo Mode Overview, Next: Emacs Editing, Up: Texinfo Mode + +2.1 Texinfo Mode Overview +========================= + +Texinfo mode provides special features for working with Texinfo files. +You can: + + * Insert frequently used @-commands. + + * Automatically create `@node' lines. + + * Show the structure of a Texinfo source file. + + * Automatically create or update the `Next', `Previous', and `Up' + pointers of a node. + + * Automatically create or update menus. + + * Automatically create a master menu. + + * Format a part or all of a file for Info. + + * Typeset and print part or all of a file. + + Perhaps the two most helpful features are those for inserting +frequently used @-commands and for creating node pointers and menus. + + +File: texinfo.info, Node: Emacs Editing, Next: Inserting, Prev: Texinfo Mode Overview, Up: Texinfo Mode + +2.2 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 `M-q' (`fill-paragraph') command will refill a +paragraph but not mix an indexing command on a line adjacent to it into +the paragraph. + + In addition, Texinfo mode sets the `page-delimiter' variable to the +value of `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 `C-x ]' +(`forward-page') and `C-x [' (`backward-page') commands and narrow to a +chapter with the `C-x p' (`narrow-to-page') command. (*Note Pages: +(emacs)Pages, for details about the page commands.) + + You may name a Texinfo file however you wish, but the convention is to +end a Texinfo file name with one of the extensions `.texinfo', `.texi', +`.txi', or `.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 `.texinfo', `.texi' or +`.txi' extension. Also, Emacs switches to Texinfo mode when you visit a +file that has `-*-texinfo-*-' in its first line. If ever you are in +another mode and wish to switch to Texinfo mode, type `M-x +texinfo-mode'. + + Like all other Emacs features, you can customize or enhance Texinfo +mode as you wish. In particular, the keybindings are very easy to +change. The keybindings described here are the default or standard +ones. + + +File: texinfo.info, Node: Inserting, Next: Showing the Structure, Prev: Emacs Editing, Up: Texinfo Mode + +2.3 Inserting Frequently Used Commands +====================================== + +Texinfo mode provides commands to insert various frequently used +@-commands into the buffer. You can use these commands to save +keystrokes. + + The insert commands are invoked by typing `C-c' twice and then the +first letter of the @-command: + +`C-c C-c c' +`M-x texinfo-insert-@code' + Insert `@code{}' and put the cursor between the braces. + +`C-c C-c d' +`M-x texinfo-insert-@dfn' + Insert `@dfn{}' and put the cursor between the braces. + +`C-c C-c e' +`M-x texinfo-insert-@end' + Insert `@end' and attempt to insert the correct following word, + such as `example' or `table'. (This command does not handle + nested lists correctly, but inserts the word appropriate to the + immediately preceding list.) + +`C-c C-c i' +`M-x texinfo-insert-@item' + Insert `@item' and put the cursor at the beginning of the next + line. + +`C-c C-c k' +`M-x texinfo-insert-@kbd' + Insert `@kbd{}' and put the cursor between the braces. + +`C-c C-c n' +`M-x texinfo-insert-@node' + Insert `@node' and a comment line listing the sequence for the + `Next', `Previous', and `Up' nodes. Leave point after the `@node'. + +`C-c C-c o' +`M-x texinfo-insert-@noindent' + Insert `@noindent' and put the cursor at the beginning of the next + line. + +`C-c C-c s' +`M-x texinfo-insert-@samp' + Insert `@samp{}' and put the cursor between the braces. + +`C-c C-c t' +`M-x texinfo-insert-@table' + Insert `@table' followed by a <SPC> and leave the cursor after the + <SPC>. + +`C-c C-c v' +`M-x texinfo-insert-@var' + Insert `@var{}' and put the cursor between the braces. + +`C-c C-c x' +`M-x texinfo-insert-@example' + Insert `@example' and put the cursor at the beginning of the next + line. + +`C-c C-c {' +`M-x texinfo-insert-braces' + Insert `{}' and put the cursor between the braces. + +`C-c C-c }' +`C-c C-c ]' +`M-x up-list' + Move from between a pair of braces forward past the closing brace. + Typing `C-c C-c ]' is easier than typing `C-c C-c }', which is, + however, more mnemonic; hence the two keybindings. (Also, you can + move out from between braces by typing `C-f'.) + + To put a command such as `@code{...}' around an _existing_ word, +position the cursor in front of the word and type `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--`1' for one word, `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 `@kbd' and `@var'. + + This set of insert commands was created after analyzing the frequency +with which different @-commands are used in the `GNU Emacs Manual' and +the `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 `texinfo.el'. + + `C-c C-c C-d' (`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. *Note The Parts of a +Menu: Menu Parts.) + + To use `texinfo-start-menu-description', position point in a menu +entry line and type `C-c C-c C-d'. The command looks for and copies +the title that goes with the node name, and inserts the title as a +description; it positions point at beginning of the inserted text so you +can edit it. The function does not insert the title if the menu entry +line already contains a description. + + This command is only an aid to writing descriptions; it does not do +the whole job. You must edit the inserted text since a title tends to +use the same words as a node name but a useful description uses +different words. + + +File: texinfo.info, Node: Showing the Structure, Next: Updating Nodes and Menus, Prev: Inserting, Up: Texinfo Mode + +2.4 Showing the Section Structure of a File +=========================================== + +You can show the section structure of a Texinfo file by using the `C-c +C-s' command (`texinfo-show-structure'). This command shows the +section structure of a Texinfo file by listing the lines that begin +with the @-commands for `@chapter', `@section', and the like. It +constructs what amounts to a table of contents. These lines are +displayed in another buffer called the `*Occur*' buffer. In that +buffer, you can position the cursor over one of the lines and use the +`C-c C-c' command (`occur-mode-goto-occurrence'), to jump to the +corresponding spot in the Texinfo file. + +`C-c C-s' +`M-x texinfo-show-structure' + Show the `@chapter', `@section', and such lines of a Texinfo file. + +`C-c C-c' +`M-x occur-mode-goto-occurrence' + Go to the line in the Texinfo file corresponding to the line under + the cursor in the `*Occur*' buffer. + + If you call `texinfo-show-structure' with a prefix argument by typing +`C-u C-c C-s', it will list not only those lines with the @-commands +for `@chapter', `@section', and the like, but also the `@node' lines. +You can use `texinfo-show-structure' with a prefix argument to check +whether the `Next', `Previous', and `Up' pointers of an `@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 +`C-x n n' (`narrow-to-region') command and `texinfo-show-structure' +will work on only that region. To see the whole buffer again, use +`C-x n w' (`widen'). (*Note Narrowing: (emacs)Narrowing, for more +information about the narrowing commands.) + + In addition to providing the `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 `C-x ]' +(`forward-page') and `C-x [' (`backward-page') commands to move forward +and backward by chapter, and to use the `C-x p' (`narrow-to-page') +command to narrow to a chapter. *Note Pages: (emacs)Pages, for more +information about the page commands. + + +File: texinfo.info, Node: Updating Nodes and Menus, Next: Info Formatting, Prev: Showing the Structure, Up: Texinfo Mode + +2.5 Updating Nodes and 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 `@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. + +* 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. + + +File: texinfo.info, Node: Updating Commands, Next: Updating Requirements, Up: Updating Nodes and Menus + +2.5.1 The Updating Commands +--------------------------- + +You can use the updating commands to: + + * insert or update the `Next', `Previous', and `Up' pointers of a + node, + + * insert or update the menu for a section, and + + * create a master menu for a Texinfo source file. + + You can also use the commands to update all the nodes and menus in a +region or in a whole Texinfo file. + + The updating commands work only with conventional Texinfo files, which +are structured hierarchically like books. In such files, a structuring +command line must follow closely after each `@node' line, except for +the `Top' `@node' line. (A "structuring command line" is a line +beginning with `@chapter', `@section', or other similar command.) + + You can write the structuring command line on the line that follows +immediately after an `@node' line or else on the line that follows +after a single `@comment' line or a single `@ifinfo' line. You cannot +interpose more than one line between the `@node' line and the +structuring command line; and you may interpose only an `@comment' line +or an `@ifinfo' line. + + Commands which work on a whole buffer require that the `Top' node be +followed by a node with an `@chapter' or equivalent-level command. The +menu updating commands will not create a main or master menu for a +Texinfo file that has only `@chapter'-level nodes! The menu updating +commands only create menus _within_ nodes for lower level nodes. To +create a menu of chapters, you must provide a `Top' node. + + The menu updating commands remove menu entries that refer to other +Info files since they do not refer to nodes within the current buffer. +This is a deficiency. Rather than use menu entries, you can use cross +references to refer to other Info files. None of the updating commands +affect cross references. + + Texinfo mode has five updating commands that are used most often: two +are for updating the node pointers or menu of a single node (or a +region); two are for updating every node pointer and menu in a file; +and one, the `texinfo-master-menu' command, is for creating a master +menu for a complete file, and optionally, for updating every node and +menu in the whole Texinfo file. + + The `texinfo-master-menu' command is the primary command: + +`C-c C-u m' +`M-x texinfo-master-menu' + Create or update a master menu that includes all the other menus + (incorporating the descriptions from pre-existing menus, if any). + + With an argument (prefix argument, `C-u,' if interactive), first + create or update all the nodes and all the regular menus in the + buffer before constructing the master menu. (*Note The Top Node + and Master Menu: The Top Node, for more about a master menu.) + + For `texinfo-master-menu' to work, the Texinfo file must have a + `Top' node and at least one subsequent node. + + After extensively editing a Texinfo file, you can type the + following: + + C-u M-x texinfo-master-menu + or + C-u C-c C-u m + + This updates all the nodes and menus completely and all at once. + + 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. + + The commands are: + +`C-c C-u C-n' +`M-x texinfo-update-node' + Insert the `Next', `Previous', and `Up' pointers for the node that + point is within (i.e., for the `@node' line preceding point). If + the `@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, `C-u', if interactive), this + command updates all `@node' lines in the region (which is the text + between point and mark). + +`C-c C-u C-m' +`M-x texinfo-make-menu' + Create or update the menu in the node that point is within. With + an argument (`C-u' as prefix argument, if interactive), the + command makes or updates menus for the nodes which are either + within or a part of the region. + + Whenever `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. + +`C-c C-u C-e' +`M-x texinfo-every-node-update' + Insert or update the `Next', `Previous', and `Up' pointers for + every node in the buffer. + +`C-c C-u C-a' +`M-x texinfo-all-menus-update' + Create or update all the menus in the buffer. With an argument + (`C-u' as prefix argument, if interactive), first insert or update + all the node pointers before working on the menus. + + If a master menu exists, the `texinfo-all-menus-update' command + updates it; but the command does not create a new master menu if + none already exists. (Use the `texinfo-master-menu' command for + that.) + + When working on a document that does not merit a master menu, you + can type the following: + + C-u C-c C-u C-a + or + C-u M-x texinfo-all-menus-update + + This updates all the nodes and menus. + + The `texinfo-column-for-description' variable specifies the column to +which menu descriptions are indented. By default, the value is 32 +although it is often useful to reduce it to as low as 24. You can set +the variable via customization (*note Changing an Option: +(emacs)Changing an Option.) or with the `M-x set-variable' command +(*note Examining and Setting Variables: (emacs)Examining.). + + Also, the `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 `texinfo-insert-node-lines' command to insert +missing `@node' lines into a file. (*Note Other Updating Commands::, +for more information.) + + +File: texinfo.info, Node: Updating Requirements, Next: Other Updating Commands, Prev: Updating Commands, Up: Updating Nodes and Menus + +2.5.2 Updating Requirements +--------------------------- + +To use the updating commands, you must organize the Texinfo file +hierarchically with chapters, sections, subsections, and the like. +When you construct the hierarchy of the manual, do not `jump down' more +than one level at a time: you can follow the `Top' node with a chapter, +but not with a section; you can follow a chapter with a section, but +not with a subsection. However, you may `jump up' any number of levels +at one time--for example, from a subsection to a chapter. + + Each `@node' line, with the exception of the line for the `Top' node, +must be followed by a line with a structuring command such as +`@chapter', `@section', or `@unnumberedsubsec'. + + Each `@node' line/structuring-command line combination must look +either like this: + + @node Comments, Minimum, Conventions, Overview + @comment node-name, next, previous, up + @section Comments + + or like this (without the `@comment' line): + + @node Comments, Minimum, Conventions, Overview + @section Comments + + or like this (without the explicit node pointers): + + @node Comments + @section Comments + +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 +`@comment' line, you may also write an `@ifinfo' line.) + + If a file has a `Top' node, it must be called `top' or `Top' and be +the first node in the file. + + The menu updating commands create a menu of sections within a chapter, +a menu of subsections within a section, and so on. This means that you +must have a `Top' node if you want a menu of chapters. + + Incidentally, the `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 `makeinfo', you have no need for the update node +commands. (*Note Creating an Info File::, for more information about +`makeinfo'.) However, both `makeinfo' and the `texinfo-format-...' +commands require that you insert menus in the file. + + +File: texinfo.info, Node: Other Updating Commands, Prev: Updating Requirements, Up: Updating Nodes and Menus + +2.5.3 Other Updating Commands +----------------------------- + +In addition to the five major updating commands, Texinfo mode possesses +several less frequently used updating commands: + +`M-x texinfo-insert-node-lines' + Insert `@node' lines before the `@chapter', `@section', and other + sectioning commands wherever they are missing throughout a region + in a Texinfo file. + + With an argument (`C-u' as prefix argument, if interactive), the + `texinfo-insert-node-lines' command not only inserts `@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 `@node' lines that lack names. Since node + names should be more concise than section or chapter titles, you + must manually edit node names so inserted. + + For example, the following marks a whole buffer as a region and + inserts `@node' lines and titles throughout: + + C-x h C-u M-x texinfo-insert-node-lines + + This command inserts titles as node names in `@node' lines; the + `texinfo-start-menu-description' command (*note Inserting + Frequently Used Commands: Inserting.) inserts titles as + descriptions in menu entries, a different action. However, in + both cases, you need to edit the inserted text. + +`M-x texinfo-multiple-files-update' + Update nodes and menus in a document built from several separate + files. With `C-u' as a prefix argument, create and insert a + master menu in the outer file. With a numeric prefix argument, + such as `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 + `texinfo-multiple-files-update' command is described in the + appendix on `@include' files. *Note + texinfo-multiple-files-update::. + +`M-x 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 (`C-u' as prefix + argument, if interactive), the `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. + +`M-x 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 `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 + `texinfo-sequential-node-update' command sequentially updates all + the nodes in the region. + + +File: texinfo.info, Node: Info Formatting, Next: Printing, Prev: Updating Nodes and Menus, Up: Texinfo Mode + +2.6 Formatting for Info +======================= + +Texinfo mode provides several commands for formatting part or all of a +Texinfo file for Info. Often, when you are writing a document, you +want to format only part of a file--that is, a region. + + You can use either the `texinfo-format-region' or the +`makeinfo-region' command to format a region: + +`C-c C-e C-r' +`M-x texinfo-format-region' +`C-c C-m C-r' +`M-x makeinfo-region' + Format the current region for Info. + + You can use either the `texinfo-format-buffer' or the +`makeinfo-buffer' command to format a whole buffer: + +`C-c C-e C-b' +`M-x texinfo-format-buffer' +`C-c C-m C-b' +`M-x makeinfo-buffer' + Format the current buffer for Info. + + For example, after writing a Texinfo file, you can type the following: + + C-u C-c C-u m +or + C-u M-x texinfo-master-menu + +This updates all the nodes and menus. Then type the following to create +an Info file: + + C-c C-m C-b +or + M-x makeinfo-buffer + + For TeX or the Info formatting commands to work, the file _must_ +include a line that has `@setfilename' in its header. + + *Note Creating an Info File::, for details about Info formatting. + + +File: texinfo.info, Node: Printing, Next: Texinfo Mode Summary, Prev: Info Formatting, Up: Texinfo Mode + +2.7 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 `texindex' command after first running the `tex' +typesetting command; and then you must run the `tex' command again. Or +else run the `texi2dvi' command which automatically creates indices as +needed (*note 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 +`texinfo-tex-region' and related commands for this purpose. Use the +`texinfo-tex-buffer' command to format all of a buffer. + +`C-c C-t C-b' +`M-x texinfo-tex-buffer' + Run `texi2dvi' on the buffer. In addition to running TeX on the + buffer, this command automatically creates or updates indices as + needed. + +`C-c C-t C-r' +`M-x texinfo-tex-region' + Run TeX on the region. + +`C-c C-t C-i' +`M-x texinfo-texindex' + Run `texindex' to sort the indices of a Texinfo file formatted with + `texinfo-tex-region'. The `texinfo-tex-region' command does not + run `texindex' automatically; it only runs the `tex' typesetting + command. You must run the `texinfo-tex-region' command a second + time after sorting the raw index files with the `texindex' + command. (Usually, you do not format an index when you format a + region, only when you format a buffer. Now that the `texi2dvi' + command exists, there is little or no need for this command.) + +`C-c C-t C-p' +`M-x texinfo-tex-print' + Print the file (or the part of the file) previously formatted with + `texinfo-tex-buffer' or `texinfo-tex-region'. + + For `texinfo-tex-region' or `texinfo-tex-buffer' to work, the file +_must_ start with a `\input texinfo' line and must include an +`@settitle' line. The file must end with `@bye' on a line by itself. +(When you use `texinfo-tex-region', you must surround the `@settitle' +line with start-of-header and end-of-header lines.) + + *Note Hardcopy::, for a description of the other TeX related +commands, such as `tex-show-print-queue'. + + +File: texinfo.info, Node: Texinfo Mode Summary, Prev: Printing, Up: Texinfo Mode + +2.8 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 `C-c'. The keys are somewhat mnemonic. + +Insert Commands +--------------- + +The insert commands are invoked by typing `C-c' twice and then the +first letter of the @-command to be inserted. (It might make more +sense mnemonically to use `C-c C-i', for `custom insert', but `C-c C-c' +is quick to type.) + + C-c C-c c Insert `@code'. + C-c C-c d Insert `@dfn'. + C-c C-c e Insert `@end'. + C-c C-c i Insert `@item'. + C-c C-c n Insert `@node'. + C-c C-c s Insert `@samp'. + C-c C-c v Insert `@var'. + C-c C-c { Insert braces. + C-c C-c ] + C-c C-c } Move out of enclosing braces. + + C-c C-c C-d Insert a node's section title + in the space for the description + in a menu entry line. + +Show Structure +-------------- + +The `texinfo-show-structure' command is often used within a narrowed +region. + + C-c C-s List all the headings. + +The Master Update Command +------------------------- + +The `texinfo-master-menu' command creates a master menu; and can be +used to update every node and menu in a file as well. + + C-c C-u m + M-x texinfo-master-menu + Create or update a master menu. + + C-u C-c C-u m With `C-u' as a prefix argument, first + create or update all nodes and regular + menus, and then create a master menu. + +Update Pointers +--------------- + +The update pointer commands are invoked by typing `C-c C-u' and then +either `C-n' for `texinfo-update-node' or `C-e' for +`texinfo-every-node-update'. + + C-c C-u C-n Update a node. + C-c C-u C-e Update every node in the buffer. + +Update Menus +------------ + +Invoke the update menu commands by typing `C-c C-u' and then either +`C-m' for `texinfo-make-menu' or `C-a' for `texinfo-all-menus-update'. +To update both nodes and menus at the same time, precede `C-c C-u C-a' +with `C-u'. + + C-c C-u C-m Make or update a menu. + + C-c C-u C-a Make or update all + menus in a buffer. + + C-u C-c C-u C-a With `C-u' as a prefix argument, + first create or update all nodes and + then create or update all menus. + +Format for Info +--------------- + +The Info formatting commands that are written in Emacs Lisp are invoked +by typing `C-c C-e' and then either `C-r' for a region or `C-b' for the +whole buffer. + + The Info formatting commands that are written in C and based on the +`makeinfo' program are invoked by typing `C-c C-m' and then either +`C-r' for a region or `C-b' for the whole buffer. + +Use the `texinfo-format...' commands: + + C-c C-e C-r Format the region. + C-c C-e C-b Format the buffer. + +Use `makeinfo': + + C-c C-m C-r Format the region. + C-c C-m C-b Format the buffer. + C-c C-m C-l Recenter the `makeinfo' output buffer. + C-c C-m C-k Kill the `makeinfo' formatting job. + +Typeset and Print +----------------- + +The TeX typesetting and printing commands are invoked by typing `C-c +C-t' and then another control command: `C-r' for `texinfo-tex-region', +`C-b' for `texinfo-tex-buffer', and so on. + + C-c C-t C-r Run TeX on the region. + C-c C-t C-b Run `texi2dvi' on the buffer. + C-c C-t C-i Run `texindex'. + C-c C-t C-p Print the DVI file. + C-c C-t C-q Show the print queue. + C-c C-t C-d Delete a job from the print queue. + C-c C-t C-k Kill the current TeX formatting job. + C-c C-t C-x Quit a currently stopped TeX formatting job. + C-c C-t C-l Recenter the output buffer. + +Other Updating Commands +----------------------- + +The remaining updating commands do not have standard keybindings because +they are rarely used. + + M-x texinfo-insert-node-lines + Insert missing `@node' lines in region. + With `C-u' as a prefix argument, + use section titles as node names. + + M-x texinfo-multiple-files-update + Update a multi-file document. + With `C-u 2' as a prefix argument, + create or update all nodes and menus + in all included files first. + + M-x texinfo-indent-menu-description + Indent descriptions. + + M-x texinfo-sequential-node-update + Insert node pointers in strict sequence. + + +File: texinfo.info, Node: Beginning a File, Next: Ending a File, Prev: Texinfo Mode, Up: Top + +3 Beginning a Texinfo File +************************** + +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 (*note Six Parts::). It describes the numerous +commands for handling the traditional frontmatter items in Texinfo. + + 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. + + +File: texinfo.info, Node: Sample Beginning, Next: Texinfo File Header, Up: Beginning a File + +3.1 Sample Texinfo File Beginning +================================= + +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. + + *Note GNU Sample Texts::, for the full texts to be used in GNU +manuals. + + \input texinfo @c -*-texinfo-*- + @c %**start of header + @setfilename INFONAME.info + @settitle NAME-OF-MANUAL VERSION + @c %**end of header + + @copying + This manual is for PROGRAM, version VERSION. + + Copyright @copyright{} YEARS COPYRIGHT-OWNER. + + @quotation + Permission is granted to ... + @end quotation + @end copying + + @titlepage + @title NAME-OF-MANUAL-WHEN-PRINTED + @subtitle SUBTITLE-IF-ANY + @subtitle SECOND-SUBTITLE + @author AUTHOR + + @c The following two commands + @c start the copyright page. + @page + @vskip 0pt plus 1filll + @insertcopying + + Published by ... + @end titlepage + + @c So the toc is printed at the start. + @contents + + @ifnottex + @node Top + @top TITLE + + @insertcopying + @end ifnottex + + @menu + * First Chapter:: Getting started ... + * Second Chapter:: ... + ... + * Copying:: Your rights and freedoms. + @end menu + + @node First Chapter + @chapter First Chapter + + @cindex first chapter + @cindex chapter, first + ... + + +File: texinfo.info, Node: Texinfo File Header, Next: Document Permissions, Prev: Sample Beginning, Up: Beginning a File + +3.2 Texinfo File Header +======================= + +Texinfo files start with at least three lines that provide Info and TeX +with necessary information. These are the `\input texinfo' line, the +`@settitle' line, and the `@setfilename' line. + + Also, if you want to format just part of the Texinfo file, you must +write the `@settitle' and `@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. `@synindex' (*note synindex::), for instance, +is another command often included in the header. *Note GNU Sample +Texts::, for complete sample texts. + + Thus, the beginning of a Texinfo file generally looks like this: + + \input texinfo @c -*-texinfo-*- + @c %**start of header + @setfilename sample.info + @settitle Sample Manual 1.0 + @c %**end of header + +* 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. + + +File: texinfo.info, Node: First Line, Next: Start of Header, Up: Texinfo File Header + +3.2.1 The First Line 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: + + \input texinfo @c -*-texinfo-*- + +This line serves two functions: + + 1. When the file is processed by TeX, the `\input texinfo' command + tells TeX to load the macros needed for processing a Texinfo file. + These are in a file called `texinfo.tex', which should have been + installed on your system along with either the TeX or Texinfo + software. TeX uses the backslash, `\', to mark the beginning of a + command, exactly as Texinfo uses `@'. The `texinfo.tex' file + causes the switch from `\' to `@'; before the switch occurs, TeX + requires `\', which is why it appears at the beginning of the file. + + 2. When the file is edited in GNU Emacs, the `-*-texinfo-*-' mode + specification tells Emacs to use Texinfo mode. + + +File: texinfo.info, Node: Start of Header, Next: setfilename, Prev: First Line, Up: Texinfo File Header + +3.2.2 Start of Header +--------------------- + +A start-of-header line is a Texinfo comment that looks like this: + + @c %**start of header + + Write the start-of-header line on the second line of a Texinfo file. +Follow the start-of-header line with `@setfilename' and `@settitle' +lines and, optionally, with other commands that globally affect the +document formatting, such as `@synindex' or `@footnotestyle'; and then +by an end-of-header line (*note End of Header::). + + The start- and end-of-header lines allow you to format only part of a +Texinfo file for Info or printing. *Note texinfo-format commands::. + + The odd string of characters, `%**', 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 `tex-start-of-header' and/or +`tex-end-of-header' Emacs variables. *Note Texinfo Mode Printing::. + + +File: texinfo.info, Node: setfilename, Next: settitle, Prev: Start of Header, Up: Texinfo File Header + +3.2.3 `@setfilename': Set the output file name +---------------------------------------------- + +In order to serve as the primary input file for either `makeinfo' or +TeX, a Texinfo file must contain a line that looks like this: + + @setfilename INFO-FILE-NAME + + Write the `@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. + + The Info formatting commands ignore everything written before the +`@setfilename' line, which is why the very first line of the file (the +`\input' line) does not show up in the output. + + The `@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 `.texi') entirely from the input file +name, or, preferably, replace it with the `.info' extension. + + Although an explicit `.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 `-1', `-2', ..., `-10', `-11', and +so on, to the original file name. (*Note Tag and Split Files::.) The +subfile name `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 `texinfo' rather than `texinfo.info'. When +`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 `texin-10', `gcc.i12', etc. + + When producing HTML output, `makeinfo' will replace any extension +with `html', or add `.html' if the given name has no extension. + + The `@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 `texinfo.cnf' if that file is present on your system (*note +Preparing for TeX: Preparing for TeX.). + + +File: texinfo.info, Node: settitle, Next: End of Header, Prev: setfilename, Up: Texinfo File Header + +3.2.4 `@settitle': Set the document title +----------------------------------------- + +In order to be made into a printed manual, a Texinfo file must contain +a line that looks like this: + + @settitle TITLE + + Write the `@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 `@settitle' command should precede everything that generates +actual output. The best place for it is right after the `@setfilename' +command (see the previous section). + + In the HTML file produced by `makeinfo', TITLE serves as the document +`<title>'. It also becomes the default document description in the +`<head>' part (*note documentdescription::). + + The title in the `@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 `@settitle' title; on the title page, the +version number generally appears as a `@subtitle' so it would be +omitted from the `@title'. *Note 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 `@chapter' command.) By default, no page footer is printed. + + Even if you are printing in a single-sided style, TeX looks for an +`@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 +`@end titlepage' command in the Texinfo file, or that comes after an +`@headings' command that turns on headings. (*Note The `@headings' +Command: headings on off, for more information.) + + You may, if you wish, create your own, customized headings and +footings. *Note Headings::, for a detailed discussion of this. + + +File: texinfo.info, Node: End of Header, Prev: settitle, Up: Texinfo File Header + +3.2.5 End of Header +------------------- + +Follow the header lines with an end-of-header line, which is a Texinfo +comment that looks like this: + + @c %**end of header + + *Note Start of Header::. + + +File: texinfo.info, Node: Document Permissions, Next: Titlepage & Copyright Page, Prev: Texinfo File Header, Up: Beginning a File + +3.3 Document 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 (`@copying') to declare this text +once, and another command (`@insertcopying') to insert the text at +appropriate points. + +* Menu: + +* copying:: Declare the document's copying permissions. +* insertcopying:: Where to insert the permissions. + + +File: texinfo.info, Node: copying, Next: insertcopying, Up: Document Permissions + +3.3.1 `@copying': Declare Copying Permissions +--------------------------------------------- + +The `@copying' command should be given very early in the document; the +recommended location is right after the header material (*note 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: + + @copying + This manual is for PROGRAM (version VERSION, updated + DATE), which ... + + Copyright @copyright{} YEARS COPYRIGHT-OWNER. + + @quotation + Permission is granted to ... + @end quotation + @end copying + + The `@quotation' has no legal significance; it's there to improve +readability in some contexts. + + *Note GNU Sample Texts::, for the full text to be used in GNU manuals. +*Note 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 `@copying' is output as a comment at the beginning of +Info, HTML, and XML output files. It is _not_ output implicitly in +plain text or TeX; it's up to you to use `@insertcopying' to emit the +copying information. See the next section for details. + + The `@copyright{}' command generates a `c' inside a circle in output +formats that support this (print and HTML). In the other formats (Info +and plain text), it generates `(C)'. The copyright notice itself has +the following legally defined sequence: + + Copyright (C) YEARS COPYRIGHT-OWNER. + + 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. + + 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. + + 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. + + *Note Copyright Notices: (maintain)Copyright Notices, for additional +information. + + +File: texinfo.info, Node: insertcopying, Prev: copying, Up: Document Permissions + +3.3.2 `@insertcopying': Include Permissions Text +------------------------------------------------ + +The `@insertcopying' command is simply written on a line by itself, +like this: + + @insertcopying + + This inserts the text previously defined by `@copying'. To meet +legal requirements, it must be used on the copyright page in the printed +manual (*note Copyright::). + + We also strongly recommend using `@insertcopying' in the Top node of +your manual (*note The Top Node::), although it is not required +legally. Here's why: + + The `@copying' command itself causes the permissions text to appear +in an Info file _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 _not_ +see this text (except when using the advanced Info command `g *'). +Therefore, an explicit `@insertcopying' in the Top node makes it +apparent to readers that the manual is free. + + Similarly, the `@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). And +therefore again, the `@insertcopying' in the Top node is valuable +because it makes the copying permissions visible and thus promotes +freedom. + + The permissions text defined by `@copying' also appears automatically +at the beginning of the XML output file. + + +File: texinfo.info, Node: Titlepage & Copyright Page, Next: Contents, Prev: Document Permissions, Up: Beginning a File + +3.4 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. + + You may wish to include titlepage-like information for plain text +output. Simply place any such leading material between `@ifplaintext' +and `@end ifplaintext'; `makeinfo' includes this when writing plain +text (`--no-headers'), along with an `@insertcopying'. + +* Menu: + +* titlepage:: Create a title for the printed document. +* titlefont center sp:: The `@titlefont', `@center', + and `@sp' commands. +* title subtitle author:: The `@title', `@subtitle', + and `@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. + + +File: texinfo.info, Node: titlepage, Next: titlefont center sp, Up: Titlepage & Copyright Page + +3.4.1 `@titlepage' +------------------ + +Start the material for the title page and following copyright page with +`@titlepage' on a line by itself and end it with `@end titlepage' on a +line by itself. + + The `@end titlepage' command starts a new page and turns on page +numbering. (*Note Page Headings: 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 `@titlepage' and `@end +titlepage' commands. You can force the table of contents to appear +there with the `@setcontentsaftertitlepage' command (*note Contents::). + + By using the `@page' command you can force a page break within the +region delineated by the `@titlepage' and `@end titlepage' commands and +thereby create more than one unnumbered page. This is how the +copyright page is produced. (The `@titlepage' command might perhaps +have been better named the `@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(1) 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 +*Note The Top Node::.) + + Texinfo provides two main methods for creating a title page. One +method uses the `@titlefont', `@sp', and `@center' commands to generate +a title page in which the words on the page are centered. + + The second method uses the `@title', `@subtitle', and `@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. + + For extremely simple documents, and for the bastard title page in +traditional book frontmatter, Texinfo also provides a command +`@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. + + ---------- Footnotes ---------- + + (1) 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. + + +File: texinfo.info, Node: titlefont center sp, Next: title subtitle author, Prev: titlepage, Up: Titlepage & Copyright Page + +3.4.2 `@titlefont', `@center', and `@sp' +---------------------------------------- + +You can use the `@titlefont', `@sp', and `@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 `@titlefont' command to select a large font suitable for the +title itself. You can use `@titlefont' more than once if you have an +especially long title. + + For HTML output, each `@titlefont' command produces an `<h1>' +heading, but the HTML document `<title>' is not affected. For that, +you must put an `@settitle' command before the `@titlefont' command +(*note settitle::). + + For example: + + @titlefont{Texinfo} + + Use the `@center' command at the beginning of a line to center the +remaining text on that line. Thus, + + @center @titlefont{Texinfo} + +centers the title, which in this example is "Texinfo" printed in the +title font. + + Use the `@sp' command to insert vertical space. For example: + + @sp 2 + +This inserts two blank lines on the printed page. (*Note `@sp': sp, +for more information about the `@sp' command.) + + A template for this method looks like this: + + @titlepage + @sp 10 + @center @titlefont{NAME-OF-MANUAL-WHEN-PRINTED} + @sp 2 + @center SUBTITLE-IF-ANY + @sp 2 + @center AUTHOR + ... + @end titlepage + + 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. + + +File: texinfo.info, Node: title subtitle author, Next: Copyright, Prev: titlefont center sp, Up: Titlepage & Copyright Page + +3.4.3 `@title', `@subtitle', and `@author' +------------------------------------------ + +You can use the `@title', `@subtitle', and `@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 `@sp' command is needed to adjust +vertical spacing. + + Write the `@title', `@subtitle', or `@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 `@titlepage'. + + The `@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 `@*' 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 +`@title' and `@titlefont'; see the final example in this section. + + The `@subtitle' command sets subtitles in a normal-sized font flush +to the right-hand side of the page. + + The `@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 `@author' command line is followed +by an `@page' command line.) + + There are two ways to use the `@author' command: you can write the +name or names on the remaining part of the line that starts with an +`@author' command: + + @author by Jane Smith and John Doe + +or you can write the names one above each other by using two (or more) +`@author' commands: + + @author Jane Smith + @author John Doe + +(Only the bottom name is underlined with a black rule.) + + A template for this method looks like this: + + @titlepage + @title NAME-OF-MANUAL-WHEN-PRINTED + @subtitle SUBTITLE-IF-ANY + @subtitle SECOND-SUBTITLE + @author AUTHOR + @page + ... + @end titlepage + + You may also combine the `@titlefont' method described in the +previous section and `@title' method described in this one. This may +be useful if you have a very long title. Here is a real-life example: + + @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 + +(The use of `@value' here is explained in *Note value Example::. + + +File: texinfo.info, Node: Copyright, Next: end titlepage, Prev: title subtitle author, Up: Titlepage & Copyright Page + +3.4.4 Copyright Page +-------------------- + +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 `@titlepage' and `@end titlepage' commands. + + Use the `@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 incantantion after `@page': + + @vskip 0pt plus 1filll + +This is a TeX command that is not supported by the Info formatting +commands. The `@vskip' command inserts whitespace. The `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 `l's in the word `filll'; +this is correct. + + To insert the copyright text itself, write `@insertcopying' next +(*note Document Permissions::): + + @insertcopying + + Follow the copying text by the publisher, ISBN numbers, cover art +credits, and other such information. + + Here is an example putting all this together: + + @titlepage + ... + @page + @vskip 0pt plus 1filll + @insertcopying + + Published by ... + + Cover art by ... + @end titlepage + + +File: texinfo.info, Node: end titlepage, Next: headings on off, Prev: Copyright, Up: Titlepage & Copyright Page + +3.4.5 Heading Generation +------------------------ + +The `@end titlepage' command must be written on a line by itself. 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: + + * The conventional way is to write an `@setchapternewpage' command + before the title page commands, and then have the `@end titlepage' + command start generating page headings in the manner desired. + (*Note setchapternewpage::.) + + * Alternatively, you can use the `@headings' command to prevent page + headings from being generated or to start them for either single or + double-sided printing. (Write an `@headings' command immediately + after the `@end titlepage' command. *Note The `@headings' + Command: headings on off, for more information.) + + * Or, you may specify your own page heading and footing format. + *Note Page Headings: Headings, for detailed information about page + headings and footings. + + Most documents are formatted with the standard single-sided or +double-sided format, using `@setchapternewpage odd' for double-sided +printing and no `@setchapternewpage' command for single-sided printing. + + +File: texinfo.info, Node: headings on off, Prev: end titlepage, Up: Titlepage & Copyright Page + +3.4.6 The `@headings' Command +----------------------------- + +The `@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 `@setchapternewpage' command. You need the +`@headings' command only if the `@setchapternewpage' command does not +do what you want, or if you want to turn off pre-defined page headings +prior to defining your own. Write an `@headings' command immediately +after the `@end titlepage' command. + + You can use `@headings' as follows: + +`@headings off' + Turn off printing of page headings. + +`@headings single' + Turn on page headings appropriate for single-sided printing. + +`@headings double' +`@headings on' + Turn on page headings appropriate for double-sided printing. The + two commands, `@headings on' and `@headings double', are + synonymous. + +`@headings singleafter' +`@headings doubleafter' + Turn on `single' or `double' headings, respectively, after the + current page is output. + +`@headings on' + Turn on page headings: `single' if `@setchapternewpage on', + `double' otherwise. + + For example, suppose you write `@setchapternewpage off' before the +`@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 `@headings double' after the +`@end titlepage' command. + + You can stop TeX from generating any page headings at all by writing +`@headings off' on a line of its own immediately after the line +containing the `@end titlepage' command, like this: + + @end titlepage + @headings off + +The `@headings off' command overrides the `@end titlepage' command, +which would otherwise cause TeX to print page headings. + + You can also specify your own style of page heading and footing. +*Note Page Headings: Headings, for more information. + + +File: texinfo.info, Node: Contents, Next: The Top Node, Prev: Titlepage & Copyright Page, Up: Beginning a File + +3.5 Generating a Table of Contents +================================== + +The `@chapter', `@section', and other structuring commands (*note +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 `@contents' and/or `@summarycontents' command(s). + +`@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 `@majorheading', + `@chapheading', and the other `@...heading' commands do not appear + in the table of contents (*note Structuring Command Types::). + +`@shortcontents' +`@summarycontents' + (`@summarycontents' is a synonym for `@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. + + + Both contents commands should be written on a line by themselves, and +are best placed near the beginning of the file, after the `@end +titlepage' (*note 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 +`@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 `makeinfo --no-headers'), +unless `makeinfo' is writing its output to standard output. + + When `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 `@bye', but we no +longer recommend this. + + However, since many existing Texinfo documents still do have the +`@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 `@setcontentsaftertitlepage' +and/or `@setshortcontentsaftertitlepage'. The first prints only the +main contents after the `@end titlepage'; the second prints both the +short contents and the main contents. In either case, any subsequent +`@contents' or `@shortcontents' is ignored (unless, erroneously, no +`@end titlepage' is ever encountered). + + You need to include the `@set...contentsaftertitlepage' commands +early in the document (just after `@setfilename', for example). We +recommend using `texi2dvi' (*note Format with texi2dvi::) to specify +this without altering the source file at all. For example: + texi2dvi --texinfo=@setcontentsaftertitlepage foo.texi + + +File: texinfo.info, Node: The Top Node, Next: Global Document Commands, Prev: Contents, Up: Beginning a File + +3.6 The `Top' Node and Master Menu +================================== + +The `Top' node is the node in which a reader enters an Info manual. As +such, it should begin with the `@insertcopying' command (*note Document +Permissions::) to provide a brief description of the manual (including +the version number) and copying permissions, 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. + + It is also conventional to write an `@top' sectioning command line +containing the title of the document immediately after the `@node Top' +line (*note The `@top' Sectioning Command: makeinfo top command.). + + The contents of the `Top' node should appear only in the online +output; none of it should appear in printed output, so enclose it +between `@ifnottex' and `@end ifnottex' commands. (TeX does not print +either an `@node' line or a menu; they appear only in Info; strictly +speaking, you are not required to enclose these parts between +`@ifnottex' and `@end ifnottext', but it is simplest to do so. *Note +Conditionally Visible Text: Conditionals.) + +* Menu: + +* Top Node Example:: +* Master Menu Parts:: + + +File: texinfo.info, Node: Top Node Example, Next: Master Menu Parts, Up: The Top Node + +3.6.1 Top Node Example +---------------------- + +Here is an example of a Top node. + + @ifnottex + @node Top + @top Sample Title + + @insertcopying + + Additional general information. + + @menu + * First Chapter:: + * Second Chapter:: + ... + * Index:: + @end menu + + +File: texinfo.info, Node: Master Menu Parts, Prev: Top Node Example, Up: The Top Node + +3.6.2 Parts of a Master Menu +---------------------------- + +A "master menu" is a detailed main menu listing all the nodes in a file. + + A master menu is enclosed in `@menu' and `@end menu' commands and +does not appear in the printed document. + + Generally, a master menu is divided into parts. + + * The first part contains the major nodes in the Texinfo file: the + nodes for the chapters, chapter-like sections, and the appendices. + + * The second part contains nodes for the indices. + + * 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 `@detailmenu' before the + first one, and `@end detailmenu' after the last; otherwise, + `makeinfo' will get confused. + + Each section in the menu can be introduced by a descriptive line. So +long as the line does not begin with an asterisk, it will not be +treated as a menu entry. (*Note Writing a Menu::, for more +information.) + + For example, the master menu for this manual looks like the following +(but has many more entries): + + @menu + * Copying Conditions:: Your rights. + * Overview:: Texinfo in brief. + ... + * Command and Variable Index:: + * Concept Index:: + + @detailmenu + --- The Detailed Node Listing --- + + Overview of Texinfo + + * Reporting Bugs:: ... + ... + + Beginning a Texinfo File + + * Sample Beginning:: ... + ... + @end detailmenu + @end menu + + +File: texinfo.info, Node: Global Document Commands, Next: Software Copying Permissions, Prev: The Top Node, Up: Beginning a File + +3.7 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. + + +File: texinfo.info, Node: documentdescription, Next: setchapternewpage, Up: Global Document Commands + +3.7.1 `@documentdescription': Summary Text +------------------------------------------ + +When producing HTML output for a document, `makeinfo' writes a `<meta>' +element in the `<head>' to give some idea of the content of the +document. By default, this "description" is the title of the document, +taken from the `@settitle' command (*note settitle::). To change this, +use the `@documentdescription' environment, as in: + + @documentdescription + descriptive text. + @end documentdescription + +This will produce the following output in the `<head>' of the HTML: + + <meta name=description content="descriptive text."> + + `@documentdescription' must be specified before the first node of the +document. + + +File: texinfo.info, Node: setchapternewpage, Next: paragraphindent, Prev: documentdescription, Up: Global Document Commands + +3.7.2 `@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 `@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 `@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: + + @setchapternewpage odd + + You can specify one of three alternatives with the +`@setchapternewpage' command: + +`@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. + +`@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. + +`@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. + + Texinfo does not have an `@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 `@setchapternewpage' sets, +you can explicit control them with the `@headings' command. *Note The +`@headings' Command: headings on off. + + 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 `@setchapternewpage' +command has no effect on it. + + We recommend not including any `@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 +`--texinfo' option to `texi2dvi' to specify the output you want. + + +File: texinfo.info, Node: paragraphindent, Next: firstparagraphindent, Prev: setchapternewpage, Up: Global Document Commands + +3.7.3 `@paragraphindent': Paragraph Indenting +--------------------------------------------- + +The Texinfo processors may insert whitespace at the beginning of the +first line of each paragraph, thereby indenting that paragraph. You can +use the `@paragraphindent' command to specify this indentation. Write +an `@paragraphindent' command at the beginning of a line followed by +either `asis' or a number: + + @paragraphindent INDENT + + The indentation is according to the value of INDENT: + +`asis' + Do not change the existing indentation (not implemented in TeX). + +`none' +0 + Omit all indentation. + +N + Indent by N space characters in Info output, by N ems in TeX. + + + The default value of INDENT is 3. `@paragraphindent' is ignored for +HTML output. + + It is best to write the `@paragraphindent' command before the +end-of-header line at the beginning of a Texinfo file, so the region +formatting commands indent paragraphs as specified. *Note Start of +Header::. + + A peculiarity of the `texinfo-format-buffer' and +`texinfo-format-region' commands is that they do not indent (nor fill) +paragraphs that contain `@w' or `@*' commands. + + +File: texinfo.info, Node: firstparagraphindent, Next: exampleindent, Prev: paragraphindent, Up: Global Document Commands + +3.7.4 `@firstparagraphindent': Indenting After Headings +------------------------------------------------------- + +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 +`@firstparagraphindent' command: + + @firstparagraphindent WORD + + The first paragraph after a heading is indented according to the value +of WORD: + +`none' + Prevents the first paragraph from being indented (default). This + option is ignored by `makeinfo' if `@paragraphindent asis' is in + effect. + +`insert' + Include normal paragraph indentation. This respects the paragraph + indentation set by a `@paragraphindent' command (*note + paragraphindent::). + + For HTML and XML output, the `@firstparagraphindent' setting is +ignored. + + It is best to write the `@paragraphindent' command before the +end-of-header line at the beginning of a Texinfo file, so the region +formatting commands indent paragraphs as specified. *Note Start of +Header::. + + +File: texinfo.info, Node: exampleindent, Prev: firstparagraphindent, Up: Global Document Commands + +3.7.5 `@exampleindent': Environment Indenting +--------------------------------------------- + +The Texinfo processors indent each line of `@example' and similar +environments. You can use the `@exampleindent' command to specify this +indentation. Write an `@exampleindent' command at the beginning of a +line followed by either `asis' or a number: + + @exampleindent INDENT + + The indentation is according to the value of INDENT: + +`asis' + Do not change the existing indentation (not implemented in TeX). + +0 + Omit all indentation. + +N + Indent environments by N space characters in Info output, by N ems + in TeX. + + + The default value of INDENT is 5. `@exampleindent' is ignored for +HTML output. + + It is best to write the `@exampleindent' command before the +end-of-header line at the beginning of a Texinfo file, so the region +formatting commands indent paragraphs as specified. *Note Start of +Header::. + + +File: texinfo.info, Node: Software Copying Permissions, Prev: Global Document Commands, Up: Beginning a File + +3.8 Software Copying Permissions +================================ + +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. + + 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. + + +File: texinfo.info, Node: Ending a File, Next: Structuring, Prev: Beginning a File, Up: Top + +4 Ending a Texinfo File +*********************** + +The end of a Texinfo file should include commands to create indices, +and the `@bye' command to mark the last line to be processed. + + For example: + + @node Index + @unnumbered Index + + @printindex cp + + @bye + +* 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. + + +File: texinfo.info, Node: Printing Indices & Menus, Next: File End, Up: Ending a File + +4.1 Printing Indices and Menus +============================== + +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 `@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 `@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 +`texindex' (*note 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. *Note 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 `@printindex' command. + + `@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 `@printindex' command does not generate a chapter heading for the +index, since different manuals have different needs. Consequently, you +should precede the `@printindex' command with a suitable section or +chapter command (usually `@appendix' or `@unnumbered') to supply the +chapter heading and put the index into the table of contents. Precede +the chapter heading with an `@node' line as usual. + + For example: + + @node Variable Index + @unnumbered Variable Index + + @printindex vr + + @node Concept Index + @unnumbered Concept Index + + @printindex cp + + If you have more than one index, we recommend placing the concept +index last. + + * In printed output, `@printindex' produces a traditional two-column + index, with dot leaders between the index terms and page numbers. + + * In Info output, `@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: + + * First index entry: Top. (line 7) + + 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. + + * In plain text output, `@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. + + * In HTML and Docbook output, `@printindex' produces links to the + index entries. + + * In XML output, it simply records the index to be printed. + + It's not possible to generate an index when writing to standard +output; `makeinfo' generates a warning in this case. + + +File: texinfo.info, Node: File End, Prev: Printing Indices & Menus, Up: Ending a File + +4.2 `@bye' File Ending +====================== + +An `@bye' command terminates Texinfo processing. None of the +formatters read anything following `@bye'. The `@bye' command should +be on a line by itself. + + If you wish, you may follow the `@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 `@bye' were within `@ignore' ... `@end +ignore'. Also, you may follow the `@bye' line with a local variables +list for Emacs. *Note Using Local Variables and the Compile Command: +Compile-Command, for more information. + + +File: texinfo.info, Node: Structuring, Next: Nodes, Prev: Ending a File, Up: Top + +5 Chapter Structuring +********************* + +The "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 (*note Generating a Table of Contents: +Contents.). + + The chapter structuring commands do not create an Info node structure, +so normally you should put an `@node' command immediately before each +chapter structuring command (*note 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. + + 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. + +* Menu: + +* Tree Structuring:: A manual is like an upside down tree ... +* Structuring Command Types:: How to divide a manual into parts. +* makeinfo top:: The `@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. + + +File: texinfo.info, Node: Tree Structuring, Next: Structuring Command Types, Up: Structuring + +5.1 Tree Structure of Sections +============================== + +A Texinfo file is usually structured like a book with chapters, +sections, subsections, and the like. This structure can be visualized +as a tree (or rather as an upside-down tree) with the root at the top +and the levels corresponding to chapters, sections, subsection, and +subsubsections. + + Here is a diagram that shows a Texinfo file with three chapters, each +of which has two sections. + + 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 + + In a Texinfo file that has this structure, the beginning of Chapter 2 +looks like this: + + @node Chapter 2, Chapter 3, Chapter 1, top + @chapter Chapter 2 + + The chapter structuring commands are described in the sections that +follow; the `@node' and `@menu' commands are described in following +chapters. (*Note Nodes::, and see *Note Menus::.) + + +File: texinfo.info, Node: Structuring Command Types, Next: makeinfo top, Prev: Tree Structuring, Up: Structuring + +5.2 Structuring Command Types +============================= + +The chapter structuring commands fall into four groups or series, each +of which contains structuring commands corresponding to the +hierarchical levels of chapters, sections, subsections, and +subsubsections. + + The four groups are the `@chapter' series, the `@unnumbered' series, +the `@appendix' series, and the `@heading' series. + + 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. + + * The `@chapter' and `@appendix' series of commands produce numbered + or lettered entries both in the body of a printed work and in its + table of contents. + + * The `@unnumbered' series of commands produce unnumbered entries + both in the body of a printed work and in its table of contents. + The `@top' command, which has a special use, is a member of this + series (*note `@top': makeinfo top.). An `@unnumbered' section + should be associated with a node and be a normal part of the + document structure. + + * The `@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. + + * The `@majorheading' command is similar to `@chapheading', except + that it generates a larger vertical whitespace before the heading. + + * When an `@setchapternewpage' command says to do so, the + `@chapter', `@unnumbered', and `@appendix' commands start new + pages in the printed manual; the `@heading' commands do not. + + Here are the four groups of chapter structuring commands: + + No new page +Numbered Unnumbered Lettered/numbered Unnumbered +In contents In contents In contents Not in contents + `@top' `@majorheading' +`@chapter' `@unnumbered' `@appendix' `@chapheading' +`@section' `@unnumberedsec' `@appendixsec' `@heading' +`@subsection' `@unnumberedsubsec' `@appendixsubsec' `@subheading' +`@subsubsection'`@unnumberedsubsubsec' `@appendixsubsubsec' `@subsubheading' + + +File: texinfo.info, Node: makeinfo top, Next: chapter, Prev: Structuring Command Types, Up: Structuring + +5.3 `@top' +========== + +The `@top' command is a special sectioning command that you use only +after an `@node Top' line at the beginning of a Texinfo file. The +`@top' command tells the `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 +`@unnumbered' (*note `@unnumbered' and `@appendix': unnumbered & +appendix.). For detailed information, see *Note The `@top' Command: +makeinfo top command. + + The `@top' node and its menu (if any) is conventionally wrapped in an +`@ifnottex' conditional so that it will appear only in Info and HTML +output, not TeX. + + +File: texinfo.info, Node: chapter, Next: unnumbered & appendix, Prev: makeinfo top, Up: Structuring + +5.4 `@chapter' +============== + +`@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. + + For example, this chapter in this manual is entitled "Chapter +Structuring"; the `@chapter' line looks like this: + + @chapter Chapter Structuring + + In TeX, the `@chapter' command creates a chapter in the document, +specifying the chapter title. The chapter is numbered automatically. + + In Info, the `@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: + + Chapter Structuring + ******************* + + Texinfo also provides a command `@centerchap', which is analogous to +`@unnumbered', but centers its argument in the printed output. This +kind of stylistic choice is not usually offered by Texinfo. + + +File: texinfo.info, Node: unnumbered & appendix, Next: majorheading & chapheading, Prev: chapter, Up: Structuring + +5.5 `@unnumbered' and `@appendix' +================================= + +Use the `@unnumbered' command to create a chapter that appears in a +printed manual without chapter numbers of any kind. Use the +`@appendix' command to create an appendix in a printed manual that is +labelled by letter instead of by number. + + For Info file output, the `@unnumbered' and `@appendix' commands are +equivalent to `@chapter': the title is printed on a line by itself with +a line of asterisks underneath. (*Note `@chapter': chapter.) + + To create an appendix or an unnumbered chapter, write an `@appendix' +or `@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. + + +File: texinfo.info, Node: majorheading & chapheading, Next: section, Prev: unnumbered & appendix, Up: Structuring + +5.6 `@majorheading', `@chapheading' +=================================== + +The `@majorheading' and `@chapheading' commands put chapter-like +headings in the body of a document. + + 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. + + In TeX, an `@majorheading' command generates a larger vertical +whitespace before the heading than an `@chapheading' command but is +otherwise the same. + + In Info, the `@majorheading' and `@chapheading' commands are +equivalent to `@chapter': the title is printed on a line by itself with +a line of asterisks underneath. (*Note `@chapter': chapter.) + + +File: texinfo.info, Node: section, Next: unnumberedsec appendixsec heading, Prev: majorheading & chapheading, Up: Structuring + +5.7 `@section' +============== + +In a printed manual, an `@section' command identifies a numbered +section within a chapter. The section title appears in the table of +contents. In Info, an `@section' command provides a title for a +segment of text, underlined with `='. + + This section is headed with an `@section' command and looks like this +in the Texinfo file: + + @section @code{@@section} + + To create a section, write the `@section' command at the beginning of +a line and follow it on the same line by the section title. + + Thus, + + @section This is a section + +produces + + This is a section + ================= + +in Info. + + +File: texinfo.info, Node: unnumberedsec appendixsec heading, Next: subsection, Prev: section, Up: Structuring + +5.8 `@unnumberedsec', `@appendixsec', `@heading' +================================================ + +The `@unnumberedsec', `@appendixsec', and `@heading' commands are, +respectively, the unnumbered, appendix-like, and heading-like +equivalents of the `@section' command. (*Note `@section': section.) + +`@unnumberedsec' + The `@unnumberedsec' command may be used within an unnumbered + chapter or within a regular chapter or appendix to provide an + unnumbered section. + +`@appendixsec' +`@appendixsection' + `@appendixsection' is a longer spelling of the `@appendixsec' + command; the two are synonymous. + + Conventionally, the `@appendixsec' or `@appendixsection' command + is used only within appendices. + +`@heading' + You may use the `@heading' command anywhere you wish for a + section-style heading that will not appear in the table of + contents. + + +File: texinfo.info, Node: subsection, Next: unnumberedsubsec appendixsubsec subheading, Prev: unnumberedsec appendixsec heading, Up: Structuring + +5.9 The `@subsection' Command +============================= + +Subsections are to sections as sections are to chapters. (*Note +`@section': section.) In Info, subsection titles are underlined with +`-'. For example, + + @subsection This is a subsection + +produces + + This is a subsection + -------------------- + + In a printed manual, subsections are listed in the table of contents +and are numbered three levels deep. + + +File: texinfo.info, Node: unnumberedsubsec appendixsubsec subheading, Next: subsubsection, Prev: subsection, Up: Structuring + +5.10 The `@subsection'-like Commands +==================================== + +The `@unnumberedsubsec', `@appendixsubsec', and `@subheading' commands +are, respectively, the unnumbered, appendix-like, and heading-like +equivalents of the `@subsection' command. (*Note `@subsection': +subsection.) + + In Info, the `@subsection'-like commands generate a title underlined +with hyphens. In a printed manual, an `@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 +`@unnumberedsubsec' command produces an unnumbered heading like that of +a subsection and an `@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. + + +File: texinfo.info, Node: subsubsection, Next: Raise/lower sections, Prev: unnumberedsubsec appendixsubsec subheading, Up: Structuring + +5.11 The `subsub' Commands +========================== + +The fourth and lowest level sectioning commands in Texinfo are the +`subsub' commands. They are: + +`@subsubsection' + Subsubsections are to subsections as subsections are to sections. + (*Note `@subsection': subsection.) In a printed manual, + subsubsection titles appear in the table of contents and are + numbered four levels deep. + +`@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. + +`@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. + +`@subsubheading' + The `@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. + + In Info, `subsub' titles are underlined with periods. For example, + + @subsubsection This is a subsubsection + +produces + + This is a subsubsection + ....................... + + +File: texinfo.info, Node: Raise/lower sections, Prev: subsubsection, Up: Structuring + +5.12 `@raisesections' and `@lowersections' +========================================== + +The `@raisesections' and `@lowersections' commands implicitly raise and +lower the hierarchical level of following chapters, sections and the +other sectioning commands. + + That is, the `@raisesections' command changes sections to chapters, +subsections to sections, and so on. Conversely, the `@lowersections' +command changes chapters to sections, sections to subsections, and so +on. Thus, an `@lowersections' command cancels an `@raisesections' +command, and vice versa. + + You can use `@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: + + @lowersections + @include somefile.texi + @raisesections + +(Without the `@raisesections', all the subsequent sections in the +document would be lowered.) + + If the included file being lowered has a `@top' node, you'll need to +conditionalize its inclusion with a flag (*note set value::). + + Another difficulty can arise with documents that use the (recommended) +feature of `makeinfo' for implicitly determining node pointers. Since +`makeinfo' must assume a hierarchically organized document to determine +the pointers, you cannot just arbitrarily sprinkle `@raisesections' and +`@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 `makeinfo''s +feature of implicitly determining node pointers, since the menu +structure won't be correct. + + Write each `@raisesections' and `@lowersections' command on a line of +its own. + + +File: texinfo.info, Node: Nodes, Next: Menus, Prev: Structuring, Up: Top + +6 Nodes +******* + +"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 "node pointers" that name other nodes, and can +contain "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. + + +File: texinfo.info, Node: Two Paths, Next: Node Menu Illustration, Up: Nodes + +6.1 Two Paths +============= + +The node and menu commands and the chapter structuring commands are +technically independent of each other: + + * 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. + + * 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. + + 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. + + 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. + + +File: texinfo.info, Node: Node Menu Illustration, Next: node, Prev: Two Paths, Up: Nodes + +6.2 Node and Menu Illustration +============================== + +Here is a copy of the diagram shown earlier that illustrates a Texinfo +file with three chapters, each of which contains two sections. + + The "root" is at the top of the diagram and the "leaves" are at the +bottom. This is how such a diagram is drawn conventionally; it +illustrates an upside-down tree. For this reason, the root node is +called the `Top' node, and `Up' node pointers carry you closer to the +root. + + 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 + + The fully-written command to start Chapter 2 would be this: + + @node Chapter 2, Chapter 3, Chapter 1, Top + @comment node-name, next, previous, up + +This `@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 (*note makeinfo Pointer Creation::), but the pointer +relationships still obtain. + + Note: *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 _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.) + + To go to Sections 2.1 and 2.2 using Info, you need a menu inside +Chapter 2. (*Note Menus::.) You would write the menu just before the +beginning of Section 2.1, like this: + + @menu + * Sect. 2.1:: Description of this section. + * Sect. 2.2:: + @end menu + + Write the node for Sect. 2.1 like this: + + @node Sect. 2.1, Sect. 2.2, Chapter 2, Chapter 2 + @comment node-name, next, previous, up + + 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 +*Note Cross References::.) + + Usually, an `@node' command and a chapter structuring command are +used in sequence, along with indexing commands. (You may follow the +`@node' line with a comment line that reminds you which pointer is +which.) + + Here is the beginning of the chapter in this manual called "Ending a +Texinfo File". This shows an `@node' line followed by a comment line, +an `@chapter' line, and then by indexing lines. + + @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 + + +File: texinfo.info, Node: node, Next: makeinfo Pointer Creation, Prev: Node Menu Illustration, Up: Nodes + +6.3 The `@node' Command +======================= + +A "node" is a segment of text that begins at an `@node' command and +continues until the next `@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 +`@node' command in the file. A node usually contains only one chapter +structuring command, the one that follows the `@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 create a node, write an `@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. 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 (*note makeinfo +Pointer Creation::). + + You may insert spaces before each name if you wish; the spaces are +ignored. You must write the name of the node and (if present) the names +of the `Next', `Previous', and `Up' pointers all on the same line. +Otherwise, the formatters fail. (*note info: (info)Top, for more +information about nodes in Info.) + + Usually, you write one of the chapter-structuring command lines +immediately after an `@node' line--for example, an `@section' or +`@subsection' line. (*Note Structuring Command Types::.) + + Note: The GNU Emacs Texinfo mode updating commands work only with + Texinfo files in which `@node' lines are followed by chapter + structuring lines. *Note Updating Requirements::. + + TeX uses `@node' lines to identify the names to use for cross +references. For this reason, you must write `@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 `@xref' and related commands; see *Note +Cross References::.) + +* Menu: + +* Node Names:: How to choose node and pointer names. +* Writing a Node:: How to write an `@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 `@top' command. + + +File: texinfo.info, Node: Node Names, Next: Writing a Node, Up: node + +6.3.1 Choosing Node and Pointer Names +------------------------------------- + +The name of a node identifies the node. 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 that 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 `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. *Note 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 printed output. + + +File: texinfo.info, Node: Writing a Node, Next: Node Line Tips, Prev: Node Names, Up: node + +6.3.2 How to Write an `@node' Line +---------------------------------- + +The easiest way to write an `@node' line is to write `@node' at the +beginning of a line and then the name of the node, like this: + + @node NODE-NAME + + 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 `makeinfo' +insert node pointers into the Info file it creates. (*Note Texinfo +Mode::, and *Note 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 `C-c C-c n'. This command inserts +`@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: + + @node NODE-NAME, NEXT, PREVIOUS, UP + + If you wish, you can ignore `@node' lines altogether in your first +draft and then use the `texinfo-insert-node-lines' command to create +`@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 `@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. + + +File: texinfo.info, Node: Node Line Tips, Next: Node Line Requirements, Prev: Writing a Node, Up: node + +6.3.3 `@node' Line Tips +----------------------- + +Here are three suggestions: + + * Try to pick node names that are informative but short. + + In the Info file, the file name, node name, and pointer names are + all inserted on one line, which may run into the right edge of the + window. (This does not cause a problem with Info, but is ugly.) + + * 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. + + * 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. + + +File: texinfo.info, Node: Node Line Requirements, Next: First Node, Prev: Node Line Tips, Up: node + +6.3.4 `@node' Line Requirements +------------------------------- + +Here are several requirements for `@node' lines: + + * 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. + + * 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. + + * @-commands in node names are not allowed. This includes + punctuation characters that are escaped with a `@', such as `@' and + `{', and accent commands such as `@''. (For a few cases when this + is useful, Texinfo has limited support for using @-commands in + node names; see *Note Pointer Validation::.) Perhaps this + limitation will be removed some day. + + * 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. + + For example, the following is a section title in this manual: + + @code{@@unnumberedsec}, @code{@@appendixsec}, @code{@@heading} + + But the corresponding node name lacks the commas and the @'s: + + unnumberedsec appendixsec heading + + * Case is significant in node names. + + Spaces before and after names on the `@node' line are ignored, but + spaces "inside" a name are significant. For example: + + @node foo bar, + @node foo bar , + @node foo bar , + + all define the same node, `foo bar'. References to the node + should all use that name, without the leading or trailing spaces, + but with the internal spaces. + + +File: texinfo.info, Node: First Node, Next: makeinfo top command, Prev: Node Line Requirements, Up: node + +6.3.5 The First Node +-------------------- + +The first node of a Texinfo file is the "Top" node, except in an +included file (*note Include Files::). The Top node should contain a +short summary, copying permissions, and a master menu. *Note 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: + + * The Top node (which must be named `top' or `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 `(dir)' as the parent of the Top node; + this is short for `(dir)top', and specifies the Top node in the + `dir' file, which contains the main menu for the Info system as a + whole. + + * On the other hand, do not define the `Previous' node of the Top + node to be `(dir)', as it causes confusing behavior for users: if + you are in the Top node and hits <DEL> to go backwards, you wind + up in the middle of the some other entry in the `dir' file, which + has nothing to do with what you were reading. + + * The `Next' node of the Top node should be the first chapter in your + document. + + + *Note Installing an Info File::, for more information about installing +an Info file in the `info' directory. + + For concreteness, here is an example with explicit pointers (which you +can maintain automatically with the texinfo mode commands): + + Or you can leave the pointers off entirely and let the tools +implicitly define them. This is recommended. Thus: + + @node Top + + +File: texinfo.info, Node: makeinfo top command, Prev: First Node, Up: node + +6.3.6 The `@top' Sectioning Command +----------------------------------- + +A special sectioning command, `@top' should be used with the `@node +Top' line. The `@top' sectioning command tells `makeinfo' that it +marks the `Top' node in the file. It provides the information that +`makeinfo' needs to insert node pointers automatically. Write the +`@top' command at the beginning of the line immediately following the +`@node Top' line. Write the title on the remaining part of the same +line as the `@top' command. + + In Info, the `@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 `texinfo-format-buffer', the `@top' sectioning command is +merely a synonym for `@unnumbered'. Neither of these formatters +require an `@top' command, and do nothing special with it. You can use +`@chapter' or `@unnumbered' after the `@node Top' line when you use +these formatters. Also, you can use `@chapter' or `@unnumbered' when +you use the Texinfo updating commands to create or update pointers and +menus. + + Thus, in practice, a Top node starts like this: + + @node Top + @top Your Manual Title + + +File: texinfo.info, Node: makeinfo Pointer Creation, Next: anchor, Prev: node, Up: Nodes + +6.4 Creating Pointers with `makeinfo' +===================================== + +The `makeinfo' program has a feature for automatically determining node +pointers for a hierarchically organized document. + + 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 `@chapter' or +`@section', on the line immediately following each truncated `@node' +line (except that comment lines may intervene). + + In addition, you must follow the `Top' `@node' line with a line +beginning with `@top' to mark the `Top' node in the file. *Note +`@top': makeinfo 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. + + This implicit node pointer insertion feature in `makeinfo' relieves +you from the need to update menus and pointers manually or with Texinfo +mode commands. (*Note 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 (*note Menus::) also disables this feature, for that +group of nodes. In those cases, you will need to explicitly specify +the pointers. + + +File: texinfo.info, Node: anchor, Prev: makeinfo Pointer Creation, Up: Nodes + +6.5 `@anchor': Defining Arbitrary Cross-reference Targets +========================================================= + +An "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 `@anchor' command, and give the label as a normal +brace-delimited argument. For example: + + This marks the @anchor{x-spot}spot. + ... + @xref{x-spot,,the spot}. + +produces: + + This marks the spot. + ... + See [the spot], page 1. + + As you can see, the `@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 `@xref' or other cross-reference +command, as shown. *Note Cross References::, for details on the +cross-reference commands. + + It is best to put `@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 `@anchor' command +on a line by itself if that helps readability of the source. Spaces +are always ignored after `@anchor'. + + Anchor names and node names may not conflict. Anchors and nodes are +given similar treatment in some ways; for example, the `goto-node' +command in standalone Info takes either an anchor name or a node name as +an argument. (*Note goto-node: (info-stnd)goto-node.) + + +File: texinfo.info, Node: Menus, Next: Cross References, Prev: Nodes, Up: Top + +7 Menus +******* + +"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 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. + + +File: texinfo.info, Node: Menu Location, Next: Writing a Menu, Up: Menus + +7.1 Menu Location +================= + +A menu must be located at the end of a node, without any regular text +or additional commands between the `@end menu' and the beginning of the +next node. (As a consequence, there may be at most one menu in a node.) + + 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. + + 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 +`makeinfo' implicit pointer creation feature (*note 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 `@heading' command within an +`@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 aside from not working with +`makeinfo''s implicit pointer creation, it also makes the XML output +incorrect, since it does not reflect the true document structure. So, +unfortunately we can no longer recommend this. + + +File: texinfo.info, Node: Writing a Menu, Next: Menu Parts, Prev: Menu Location, Up: Menus + +7.2 Writing a Menu +================== + +A menu consists of an `@menu' command on a line by itself followed by +menu entry lines or menu comment lines and then by an `@end menu' +command on a line by itself. + + A menu looks like this: + + @menu + Larger Units of Text + + * Files:: All about handling files. + * Multiples: Buffers. Multiple buffers; editing + several files at once. + @end menu + + In a menu, every line that begins with an `* ' is a "menu entry". +(Note the space after the asterisk.) A line that does not start with +an `* ' 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 `Larger Units of Text' is a menu comment line; the two +lines starting with `* ' are menu entries. Space characters in a menu +are preserved as-is; this allows you to format the menu as you wish. + + +File: texinfo.info, Node: Menu Parts, Next: Less Cluttered Menu Entry, Prev: Writing a Menu, Up: Menus + +7.3 The Parts of a Menu +======================= + +A menu entry has three parts, only the second of which is required: + + 1. The menu entry name (optional). + + 2. The name of the node (required). + + 3. A description of the item (optional). + + The template for a menu entry looks like this: + + * MENU-ENTRY-NAME: NODE-NAME. DESCRIPTION + + Follow the menu entry name with a single colon and follow the node +name with tab, comma, period, or newline. + + In Info, a user selects a node with the `m' (`Info-menu') command. +The menu entry name is what the user types after the `m' command. + + The third part of a menu entry is a descriptive phrase or sentence. +Menu entry names and node names are often short; the description +explains to the reader what the node is about. A useful description +complements the node name rather than repeats it. The description, +which is optional, can spread over 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. + + +File: texinfo.info, Node: Less Cluttered Menu Entry, Next: Menu Example, Prev: Menu Parts, Up: Menus + +7.4 Less Cluttered 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. + + For example, write + + * Name:: DESCRIPTION + +instead of + + * Name: Name. DESCRIPTION + + You should use the node name for the menu entry name whenever +possible, since it reduces visual clutter in the menu. + + +File: texinfo.info, Node: Menu Example, Next: Other Info Files, Prev: Less Cluttered Menu Entry, Up: Menus + +7.5 A Menu Example +================== + +A menu looks like this in Texinfo: + + @menu + * menu entry name: Node name. A short description. + * Node name:: This form is preferred. + @end menu + +This produces: + + * menu: + + * menu entry name: Node name. A short description. + * Node name:: This form is preferred. + + Here is an example as you might see it in a Texinfo file: + + @menu + Larger Units of Text + + * Files:: All about handling files. + * Multiples: Buffers. Multiple buffers; editing + several files at once. + @end menu + +This produces: + + * menu: + Larger Units of Text + + * Files:: All about handling files. + * Multiples: Buffers. Multiple buffers; editing + several files at once. + + In this example, the menu has two entries. `Files' is both a menu +entry name and the name of the node referred to by that name. +`Multiples' is the menu entry name; it refers to the node named +`Buffers'. The line `Larger Units of Text' is a comment; it appears in +the menu, but is not an entry. + + Since no file name is specified with either `Files' or `Buffers', +they must be the names of nodes in the same Info file (*note Referring +to Other Info Files: Other Info Files.). + + +File: texinfo.info, Node: Other Info Files, Prev: Menu Example, Up: Menus + +7.6 Referring to Other Info Files +================================= + +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. + + The format looks like this: + + @menu + * FIRST-ENTRY-NAME:(FILENAME)NODENAME. DESCRIPTION + * SECOND-ENTRY-NAME:(FILENAME)SECOND-NODE. DESCRIPTION + @end menu + + For example, to refer directly to the `Outlining' and `Rebinding' +nodes in the `Emacs Manual', you would write a menu like this: + + @menu + * Outlining: (emacs)Outline Mode. The major mode for + editing outlines. + * Rebinding: (emacs)Rebinding. How to redefine the + meaning of a key. + @end menu + + If you do not list the node name, but only name the file, then Info +presumes that you are referring to the `Top' node. + + The `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. (*Note Installing an Info File::.) + + For example: + + * Info: (info). Documentation browsing system. + * Emacs: (emacs). The extensible, self-documenting + text editor. + +(The `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.) + + 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. + + +File: texinfo.info, Node: Cross References, Next: Marking Text, Prev: Menus, Up: Top + +8 Cross References +****************** + +"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' ... +* 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. + + +File: texinfo.info, Node: References, Next: Cross Reference Commands, Up: Cross References + +8.1 What References Are For +=========================== + +Often, but not always, a printed document should be designed so that it +can be read sequentially. People tire of flipping back and forth to +find information that should be presented to them as they need it. + + However, in any document, some information will be too detailed for +the current context, or incidental to it; use cross references to +provide access to such information. Also, an online help system or a +reference manual is not like a novel; few read such documents in +sequence from beginning to end. Instead, people look up what they +need. For this reason, such creations should contain many cross +references to help readers find other information that they may not +have read. + + In a printed manual, a cross reference results in a page reference, +unless it is to another manual altogether, in which case the cross +reference names that manual. + + In Info, a cross reference results in an entry that you can follow +using the Info `f' command. (*note Following cross-references: +(info)Help-Xref.) + + The various cross reference commands use nodes (or anchors, *note +`@anchor': 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 `@node' lines to name +the places to which you make cross references. + + +File: texinfo.info, Node: Cross Reference Commands, Next: Cross Reference Parts, Prev: References, Up: Cross References + +8.2 Different Cross Reference Commands +====================================== + +There are four different cross reference commands: + +`@xref' + Used to start a sentence in the printed manual saying `See ...' + or an Info cross-reference saying `*Note NAME: NODE.'. + +`@ref' + Used within or, more often, at the end of a sentence; same as + `@xref' for Info; produces just the reference in the printed + manual without a preceding `See'. + +`@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. (`p' is for `parenthesis'.) + +`@inforef' + Used to make a reference to an Info file for which there is no + printed manual. + +(The `@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. *Note `@cite': cite.) + + +File: texinfo.info, Node: Cross Reference Parts, Next: xref, Prev: Cross Reference Commands, Up: Cross References + +8.3 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. + + Here is a simple cross reference example: + + @xref{Node name}. + +which produces + + *Note Node name::. + +and + + See Section NNN [Node name], page PPP. + + Here is an example of a full five-part cross reference: + + @xref{Node name, Cross Reference Name, Particular Topic, + info-file-name, A Printed Manual}, for details. + +which produces + + *Note Cross Reference Name: (info-file-name)Node name, + for details. + +in Info and + + See section "Particular Topic" in A Printed Manual, for details. + +in a printed book. + + The five possible arguments for a cross reference are: + + 1. 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. + + 2. The cross reference name for the Info reference, if it is to be + different from the node name. If you include this argument, it + becomes the first part of the cross reference. It is usually + omitted. + + 3. 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. + + 4. 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 + `.info' suffix on the file name, since Info readers try appending + it automatically. + + 5. The name of a printed manual from a different Texinfo file. + + The template for a full five argument cross reference looks like this: + + @xref{NODE-NAME, CROSS-REFERENCE-NAME, TITLE-OR-TOPIC, + INFO-FILE-NAME, PRINTED-MANUAL-TITLE}. + + Cross references with one, two, three, four, and five arguments are +described separately following the description of `@xref'. + + Write a node name in a cross reference in exactly the same way as in +the `@node' line, including the same capitalization; otherwise, the +formatters may not find the reference. + + 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 `@xref' at the beginning of a sentence; write `@pxref' only +within parentheses, and so on. + + +File: texinfo.info, Node: xref, Next: Top Node Naming, Prev: Cross Reference Parts, Up: Cross References + +8.4 `@xref' +=========== + +The `@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 `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. + +* Menu: + +* Reference Syntax:: What a reference looks like and requires. +* One Argument:: `@xref' with one argument. +* Two Arguments:: `@xref' with two arguments. +* Three Arguments:: `@xref' with three arguments. +* Four and Five Arguments:: `@xref' with four and five arguments. + + +File: texinfo.info, Node: Reference Syntax, Next: One Argument, Up: xref + +8.4.1 What a Reference Looks Like and Requires +---------------------------------------------- + +Most often, an Info cross reference looks like this: + + *Note NODE-NAME::. + +or like this + + *Note CROSS-REFERENCE-NAME: NODE-NAME. + +In TeX, a cross reference looks like this: + + See Section SECTION-NUMBER [NODE-NAME], page PAGE. + +or like this + + See Section SECTION-NUMBER [TITLE-OR-TOPIC], page PAGE. + + The `@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 `@pxref' command works +differently. *Note `@pxref': pxref.) + + Caution: A period or comma *must* follow the closing brace of an + `@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. + + `@xref' must refer to an Info node by name. Use `@node' to define +the node (*note Writing a Node::). + + `@xref' is followed by several arguments inside braces, separated by +commas. Whitespace before and after these commas is ignored. + + 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. + + Note: Commas separate arguments in a cross reference; avoid + including them in the title or other part lest the formatters + mistake them for separators. + + +File: texinfo.info, Node: One Argument, Next: Two Arguments, Prev: Reference Syntax, Up: xref + +8.4.2 `@xref' with One Argument +------------------------------- + +The simplest form of `@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. + +For example, + + @xref{Tropical Storms}. + +produces + + *Note Tropical Storms::. + +and + + See Section 3.1 [Tropical Storms], page 24. + +(Note that in the preceding example the closing brace is followed by a +period.) + + You can write a clause after the cross reference, like this: + + @xref{Tropical Storms}, for more info. + +which produces + + *Note Tropical Storms::, for more info. + +and + + See Section 3.1 [Tropical Storms], page 24, for more info. + +(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.) + + +File: texinfo.info, Node: Two Arguments, Next: Three Arguments, Prev: One Argument, Up: xref + +8.4.3 `@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. + +The template is like this: + + @xref{NODE-NAME, CROSS-REFERENCE-NAME}. + +For example, + + @xref{Electrical Effects, Lightning}. + +produces: + + *Note Lightning: Electrical Effects. + +and + + See Section 5.2 [Electrical Effects], page 57. + +(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: + + @xref{Electrical Effects, Lightning}, for more info. + +which produces + *Note Lightning: Electrical Effects, for more info. + +and + + See Section 5.2 [Electrical Effects], page 57, for more info. + +(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.) + + +File: texinfo.info, Node: Three Arguments, Next: Four and Five Arguments, Prev: Two Arguments, Up: xref + +8.4.4 `@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. + + 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. + + Also, remember to write a comma or period after the closing brace of +an `@xref' to terminate the cross reference. In the following +examples, a clause follows a terminating comma. + +The template is like this: + + @xref{NODE-NAME, CROSS-REFERENCE-NAME, TITLE-OR-TOPIC}. + +For example, + + @xref{Electrical Effects, Lightning, Thunder and Lightning}, + for details. + +produces + + *Note Lightning: Electrical Effects, for details. + +and + + See Section 5.2 [Thunder and Lightning], page 57, for details. + + 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.) + + @xref{Electrical Effects, , Thunder and Lightning}, + for details. + +produces + + *Note Thunder and Lightning: Electrical Effects, for details. + +and + + See Section 5.2 [Thunder and Lightning], page 57, for details. + + 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. + + Here are several examples from `The GNU Awk User's Guide': + + @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}. + + +File: texinfo.info, Node: Four and Five Arguments, Prev: Three Arguments, Up: xref + +8.4.5 `@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. + + Remember that a comma or period must follow the closing brace of an +`@xref' command to terminate the cross reference. In the following +examples, a clause follows a terminating comma. + +The template is: + + @xref{NODE-NAME, CROSS-REFERENCE-NAME, TITLE-OR-TOPIC, + INFO-FILE-NAME, PRINTED-MANUAL-TITLE}. + +For example, + + @xref{Electrical Effects, Lightning, Thunder and Lightning, + weather, An Introduction to Meteorology}, for details. + +produces + + *Note Lightning: (weather)Electrical Effects, for details. + +The name of the Info file is enclosed in parentheses and precedes the +name of the node. + +In a printed manual, the reference looks like this: + + See section "Thunder and Lightning" in An Introduction to + Meteorology, for details. + +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. + + Often, you will leave out the second argument when you use the long +version of `@xref'. In this case, the third argument, the topic +description, will be used as the cross reference name in Info. + +The template looks like this: + + @xref{NODE-NAME, , TITLE-OR-TOPIC, INFO-FILE-NAME, + PRINTED-MANUAL-TITLE}, for details. + +which produces + + *Note TITLE-OR-TOPIC: (INFO-FILE-NAME)NODE-NAME, for details. + +and + + See section TITLE-OR-TOPIC in PRINTED-MANUAL-TITLE, for details. + +For example, + + @xref{Electrical Effects, , Thunder and Lightning, + weather, An Introduction to Meteorology}, for details. + +produces + + *Note Thunder and Lightning: (weather)Electrical Effects, + for details. + +and + + See section "Thunder and Lightning" in An Introduction to + Meteorology, for details. + + 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. + + +File: texinfo.info, Node: Top Node Naming, Next: ref, Prev: xref, Up: Cross References + +8.5 Naming a `Top' Node +======================= + +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 `@xref' command. (This is +different from the way you write a menu entry; see *Note Referring to +Other Info Files: 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 `@xref' command. + +Thus, to make a cross reference to `The GNU Make Manual', write: + + @xref{Top, , Overview, make, The GNU Make Manual}. + +which produces + + *Note Overview: (make)Top. + +and + + See section "Overview" in The GNU Make Manual. + +In this example, `Top' is the name of the first node, and `Overview' is +the name of the first section of the manual. + + +File: texinfo.info, Node: ref, Next: pxref, Prev: Top Node Naming, Up: Cross References + +8.6 `@ref' +========== + +`@ref' is nearly the same as `@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. + +For example, + + For more information, see @ref{Hurricanes}. + +produces (in Info): + + For more information, see *Note Hurricanes::. + +and (in printed output): + + For more information, see Section 8.2 [Hurricanes], page 123. + + The `@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: + + Sea surges are described in @ref{Hurricanes}. + +looks ok in the printed output: + + Sea surges are described in Section 6.7 [Hurricanes], page 72. + +but is awkward to read in Info: + + Sea surges are described in *Note Hurricanes::. + + Caution: You should write a period or comma immediately after an + `@ref' command with two or more arguments. Otherwise, Info will + generate a (grammatically incorrect) period, just so the + cross-reference doesn't fail completely. + + As a general rule, you should write a period or comma after every +`@ref' command. This works best in both the printed and the Info +output. + + +File: texinfo.info, Node: pxref, Next: inforef, Prev: ref, Up: Cross References + +8.7 `@pxref' +============ + +The parenthetical reference command, `@pxref', is nearly the same as +`@xref', but you use it _only_ inside parentheses and you do _not_ type +a comma or period after the command's closing brace. The command +differs from `@xref' in two ways: + + 1. TeX typesets the reference for the printed manual with a lower case + `see' rather than an upper case `See'. + + 2. The Info formatting commands automatically end the reference with a + closing colon or period. + + Because one type of formatting automatically inserts closing +punctuation and the other does not, you should use `@pxref' _only_ +inside parentheses as part of another sentence. Also, you yourself +should not insert punctuation after the reference, as you do with +`@xref'. + + `@pxref' is designed so that the output looks right and works right +between parentheses 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. `@pxref' spares you the need to use +complicated methods to put a terminator into one form of the output and +not the other. + +With one argument, a parenthetical cross reference looks like this: + + ... storms cause flooding (@pxref{Hurricanes}) ... + +which produces + + ... storms cause flooding (*Note Hurricanes::) ... + +and + + ... storms cause flooding (see Section 6.7 [Hurricanes], page 72) + ... + + With two arguments, a parenthetical cross reference has this template: + + ... (@pxref{NODE-NAME, CROSS-REFERENCE-NAME}) ... + +which produces + + ... (*Note CROSS-REFERENCE-NAME: NODE-NAME.) ... + +and + + ... (see Section NNN [NODE-NAME], page PPP) ... + + `@pxref' can be used with up to five arguments just like `@xref' +(*note `@xref': xref.). + + Caution: Use `@pxref' only as a parenthetical reference. Do not + try to use `@pxref' as a clause in a sentence. It will look bad + in either the Info file, the printed output, or both. + + Parenthetical cross references look best at the ends of sentences. +Although they technically work in the middle of a sentence, that +location breaks up the flow of reading. + + +File: texinfo.info, Node: inforef, Next: uref, Prev: pxref, Up: Cross References + +8.8 `@inforef' +============== + +`@inforef' is used for cross references to Info files for which there +are no printed manuals. Even in a printed manual, `@inforef' generates +a reference directing the user to look in an Info file. + + The command takes either two or three arguments, in the following +order: + + 1. The node name. + + 2. The cross reference name (optional). + + 3. The Info file name. + +Separate the arguments with commas, as with `@xref'. Also, you must +terminate the reference with a comma or period after the `}', as you do +with `@xref'. + +The template is: + + @inforef{NODE-NAME, CROSS-REFERENCE-NAME, INFO-FILE-NAME}, + +Thus, + + @inforef{Advanced, Advanced Info commands, info}, + for more information. + +produces + + *Note Advanced Info commands: (info)Advanced, + for more information. + +and + + See Info file `info', node `Advanced', for more information. + +Similarly, + + @inforef{Advanced, , info}, for more information. + +produces + + *Note (info)Advanced::, for more information. + +and + + See Info file `info', node `Advanced', for more information. + + The converse of `@inforef' is `@cite', which is used to refer to +printed works for which no Info form exists. *Note `@cite': cite. + + +File: texinfo.info, Node: uref, Prev: inforef, Up: Cross References + +8.9 `@url', `@uref{URL[, TEXT][, REPLACEMENT]}' +=============================================== + +`@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, `@uref' produces a +link you can follow. + + `@url' is a synonym for `@uref'. Originally, `@url' had the meaning +of `@indicateurl' (*note `@indicateurl': indicateurl.), but in actual +practice it was misused the vast majority of the time. So we've +changed the definitions. + + 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. + + The third argument, if specified, is the text to display, but in this +case the url is _not_ output in any format. This is useful when the +text is already sufficiently referential, as in a man page. If the +third argument is given, the second argument is ignored. + + If the url is long enough to cause problems with line breaking, you +may find it useful to insert `@/' at places where a line break would be +acceptable (after `/' characters, for instance). This tells TeX to +allow (but not force) a line break at those places. *Note 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: + + The official GNU ftp site is @uref{ftp://ftp.gnu.org/gnu}. + +produces: + The official GNU ftp site is `ftp://ftp.gnu.org/gnu'. + + An example of the two-argument form: + The official @uref{ftp://ftp.gnu.org/gnu, GNU ftp site} + holds programs and texts. + +produces: + The official GNU ftp site (ftp://ftp.gnu.org/gnu) + holds programs and texts. + +that is, the Info output is this: + The official GNU ftp site (ftp://ftp.gnu.org/gnu) + holds programs and texts. + +and the HTML output is this: + The official <a href="ftp://ftp.gnu.org/gnu">GNU ftp site</a> + holds programs and texts. + + An example of the three-argument form: + The @uref{/man.cgi/1/ls,,ls(1)} program ... + +produces: + The ls(1) program ... + +but with HTML: + The <a href="/man.cgi/1/ls">ls(1)</a> program ... + + To merely indicate a url without creating a link people can follow, +use `@indicateurl' (*note `@indicateurl': indicateurl.). + + Some people prefer to display url's in the unambiguous format: + + <URL:http://HOST/PATH> + +You can use this form in the input file if you wish. We feel it's not +necessary to include the `<URL:' and `>' in the output, since any +software that tries to detect url's in text already has to detect them +without the `<URL:' to be useful. + + +File: texinfo.info, Node: Marking Text, Next: Quotations and Examples, Prev: Cross References, Up: Top + +9 Marking Words and Phrases +*************************** + +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. + + +File: texinfo.info, Node: Indicating, Next: Emphasis, Up: Marking Text + +9.1 Indicating Definitions, Commands, etc. +========================================== + +Texinfo has commands for indicating just what kind of object a piece of +text refers to. For example, metasyntactic variables are marked by +`@var', and code by `@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 +_intentional_ formatting language rather than a _typesetting_ +formatting language.) + + For example, in a printed manual, code is usually illustrated in a +typewriter font; `@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. + +* Menu: + +* 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. +* acronym:: Indicating acronyms. +* indicateurl:: Indicating a World Wide Web reference. +* email:: Indicating an electronic mail address. + + +File: texinfo.info, Node: Useful Highlighting, Next: code, Up: Indicating + +9.1.1 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. + + The commands serve a variety of purposes: + +`@code{SAMPLE-CODE}' + Indicate text that is a literal example of a piece of a program. + +`@kbd{KEYBOARD-CHARACTERS}' + Indicate keyboard input. + +`@key{KEY-NAME}' + Indicate the conventional name for a key on a keyboard. + +`@samp{TEXT}' + Indicate text that is a literal example of a sequence of + characters. + +`@var{METASYNTACTIC-VARIABLE}' + Indicate a metasyntactic variable. + +`@env{ENVIRONMENT-VARIABLE}' + Indicate an environment variable. + +`@file{FILE-NAME}' + Indicate the name of a file. + +`@command{COMMAND-NAME}' + Indicate the name of a command. + +`@option{OPTION}' + Indicate a command-line option. + +`@dfn{TERM}' + Indicate the introductory or defining use of a term. + +`@cite{REFERENCE}' + Indicate the name of a book. + +`@acronym{ACRONYM}' + Indicate an acronym. + +`@indicateurl{UNIFORM-RESOURCE-LOCATOR}' + Indicate a uniform resource locator for the World Wide Web. + +`@email{EMAIL-ADDRESS[, DISPLAYED-TEXT]}' + Indicate an electronic mail address. + + + +File: texinfo.info, Node: code, Next: kbd, Prev: Useful Highlighting, Up: Indicating + +9.1.2 `@code'{SAMPLE-CODE} +-------------------------- + +Use the `@code' command to indicate text that is a piece of a program +and which consists of entire syntactic tokens. Enclose the text in +braces. + + Thus, you should use `@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' for command names in languages that resemble programming +languages, such as Texinfo. For example, `@code' and `@samp' are +produced by writing `@code{@@code}' and `@code{@@samp}' in the Texinfo +source, respectively. + + It is incorrect to alter the case of a word inside an `@code' command +when it appears at the beginning of a sentence. Most computer +languages are case sensitive. In C, for example, `Printf' is different +from the identifier `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' 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, + + The function returns @code{nil}. + +produces this in the printed manual: + + The function returns `nil'. + + Here are some cases for which it is preferable not to use `@code': + + * For shell command names such as `ls' (use `@command'). + + * For shell options such as `-c' when such options stand alone (use + `@option'). + + * Also, an entire shell command often looks better if written using + `@samp' rather than `@code'. In this case, the rule is to choose + the more pleasing format. + + * For environment variable such as `TEXINPUTS' (use `@env'). + + * For a string of characters shorter than a syntactic token. For + example, if you are writing about `goto-ch', which is just a part + of the name for the `goto-char' Emacs Lisp function, you should use + `@samp'. + + * In general, when writing about the characters used in a token; for + example, do not use `@code' when you are explaining what letters + or printable symbols can be used in the names of functions. (Use + `@samp'.) Also, you should not use `@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' for the keystroke commands of GNU Emacs (use + `@kbd' instead) although you may use `@code' for the names of the + Emacs Lisp functions that the keystroke commands invoke. + + + Since `@command', `@option', and `@env' were introduced relatively +recently, it is acceptable to use `@code' or `@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. + + +File: texinfo.info, Node: kbd, Next: key, Prev: code, Up: Indicating + +9.1.3 `@kbd'{KEYBOARD-CHARACTERS} +--------------------------------- + +Use the `@kbd' command for characters of input to be typed by users. +For example, to refer to the characters `M-a', write: + + @kbd{M-a} + +and to refer to the characters `M-x shell', write: + + @kbd{M-x shell} + + By default, the `@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, `@kbd' is usually the same as `@code', producing +`quotes' around its argument. However, in typewriter-like contexts +such as the `@example' environment (*note example::) and `@code' +command itself, the quotes are omitted, since Info format cannot use +distinguishing fonts. + + Since the usage of `@kbd' varies from manual to manual, you can +control the font switching with the `@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: + +`code' + Always use the same font for `@kbd' as `@code'. + +`example' + Use the distinguishing font for `@kbd' only in `@example' and + similar environments. + +`distinct' + (the default) Always use the distinguishing font for `@kbd'. + + You can embed another @-command inside the braces of an `@kbd' +command. Here, for example, is the way to describe a command that +would be described more verbosely as "press the `r' key and then press +the <RETURN> key": + + @kbd{r @key{RET}} + +This produces: `r <RET>'. (The present manual accepts the default for +`@kbdinputstyle'.) + + You also use the `@kbd' command if you are spelling out the letters +you type; for example: + + To give the @code{logout} command, + type the characters @kbd{l o g o u t @key{RET}}. + +This produces: + + To give the `logout' command, type the characters `l o g o u t + <RET>'. + + (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 `@key{SPC}' for it.) + + +File: texinfo.info, Node: key, Next: samp, Prev: kbd, Up: Indicating + +9.1.4 `@key'{KEY-NAME} +---------------------- + +Use the `@key' command for the conventional name for a key on a +keyboard, as in: + + @key{RET} + + You can use the `@key' command within the argument of an `@kbd' +command when the sequence of characters to be typed includes one or +more keys that are described by name. + + For example, to produce `C-x <ESC>' you would type: + + @kbd{C-x @key{ESC}} + + Here is a list of the recommended names for keys: + + SPC + Space + + RET + Return + + LFD + Linefeed (however, since most keyboards nowadays do not have + a Linefeed key, it might be better to call this character + `C-j'. + + TAB + Tab + + BS + Backspace + + ESC + Escape + + DEL + Delete + + SHIFT + Shift + + CTRL + Control + + META + Meta + + 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 `Meta-a', use the `@kbd' command alone; +do not use the `@key' command; but when you are referring to the +modifier key in isolation, use the `@key' command. For example, write +`@kbd{Meta-a}' to produce `Meta-a' and `@key{META}' to produce <META>. + + +File: texinfo.info, Node: samp, Next: verb, Prev: key, Up: Indicating + +9.1.5 `@samp'{TEXT} +------------------- + +Use the `@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. + + To match @samp{foo} at the end of the line, + use the regexp @samp{foo$}. + +produces + + To match `foo' at the end of the line, use the regexp `foo$'. + + Any time you are referring to single characters, you should use +`@samp' unless `@kbd' or `@key' is more appropriate. Also, you may use +`@samp' for entire statements in C and for entire shell commands--in +this case, `@samp' often looks better than `@code'. Basically, `@samp' +is a catchall for whatever is not covered by `@code', `@kbd', or `@key'. + + 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: + + In English, the vowels are @samp{a}, @samp{e}, + @samp{i}, @samp{o}, @samp{u}, and sometimes + @samp{y}. + +This produces: + + In English, the vowels are `a', `e', `i', `o', `u', and sometimes + `y'. + + +File: texinfo.info, Node: verb, Next: var, Prev: samp, Up: Indicating + +9.1.6 `@verb'{<char>TEXT<char>} +------------------------------- + +Use the `@verb' command to print a verbatim sequence of characters. + + Like LaTeX's `\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: + + How many @verb{|@|}-escapes does one need to print this + @verb{.@a @b @c.} string or @verb{+@'e?`!`{}\+} this? + +produces + + How many @-escapes does one need to print this + @a @b @c string or these @'e?`{}!`\ this? + + This is in contrast to `@samp' (see the previous section), `@code', +and similar commands; in those cases, the argument is normal Texinfo +text, where the three characters `@{}' are special. With `@verb', +nothing is special except the delimiter character you choose. + + It is not reliable to use `@verb' inside other Texinfo constructs. + + +File: texinfo.info, Node: var, Next: env, Prev: verb, Up: Indicating + +9.1.7 `@var'{METASYNTACTIC-VARIABLE} +------------------------------------ + +Use the `@var' command to indicate metasyntactic variables. A +"metasyntactic variable" is something that stands for another piece of +text. For example, you should use a metasyntactic variable in the +documentation of a function to describe the arguments that are passed +to that function. + + Do not use `@var' for the names of particular variables in +programming languages. These are specific names from a program, so +`@code' is correct for them (*note code::). For example, the Emacs +Lisp variable `texinfo-tex-command' is not a metasyntactic variable; it +is properly formatted using `@code'. + + Do not use `@var' for environment variables either; `@env' is correct +for them (see the next section). + + The effect of `@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. + + For example, + + To delete file @var{filename}, + type @samp{rm @var{filename}}. + +produces + + To delete file FILENAME, type `rm FILENAME'. + +(Note that `@var' may appear inside `@code', `@samp', `@file', etc.) + + 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: + + \input texinfo + @@setfilename @var{info-file-name} + @@settitle @var{name-of-manual} + +This produces: + + \input texinfo + @setfilename INFO-FILE-NAME + @settitle NAME-OF-MANUAL + + In some documentation styles, metasyntactic variables are shown with +angle brackets, for example: + + ..., type rm <filename> + +However, that is not the style that Texinfo uses. (You can, of course, +modify the sources to `texinfo.tex' and the Info formatting commands to +output the `<...>' format if you wish.) + + +File: texinfo.info, Node: env, Next: file, Prev: var, Up: Indicating + +9.1.8 `@env'{ENVIRONMENT-VARIABLE} +---------------------------------- + +Use the `@env' command to indicate environment variables, as used by +many operating systems, including GNU. Do not use it for metasyntactic +variables; use `@var' instead (see the previous section). + + `@env' is equivalent to `@code' in its effects. For example: + + The @env{PATH} environment variable ... + produces + + The `PATH' environment variable ... + + +File: texinfo.info, Node: file, Next: command, Prev: env, Up: Indicating + +9.1.9 `@file'{FILE-NAME} +------------------------ + +Use the `@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 `@file' for symbols +in a programming language; use `@code'. + + Currently, `@file' is equivalent to `@samp' in its effects. For +example, + + The @file{.el} files are in + the @file{/usr/local/emacs/lisp} directory. + +produces + + The `.el' files are in the `/usr/local/emacs/lisp' directory. + + +File: texinfo.info, Node: command, Next: option, Prev: file, Up: Indicating + +9.1.10 `@command'{COMMAND-NAME} +------------------------------- + +Use the `@command' command to indicate command names, such as `ls' or +`cc'. + + `@command' is equivalent to `@code' in its effects. For example: + + The command @command{ls} lists directory contents. + produces + + The command `ls' lists directory contents. + + You should write the name of a program in the ordinary text font, +rather than using `@command', if you regard it as a new English word, +such as `Emacs' or `Bison'. + + When writing an entire shell command invocation, as in `ls -l', you +should use either `@samp' or `@code' at your discretion. + + +File: texinfo.info, Node: option, Next: dfn, Prev: command, Up: Indicating + +9.1.11 `@option'{OPTION-NAME} +----------------------------- + +Use the `@option' command to indicate a command-line option; for +example, `-l' or `--version' or `--output=FILENAME'. + + `@option' is equivalent to `@samp' in its effects. For example: + + The option @option{-l} produces a long listing. + produces + + The option `-l' produces a long listing. + + In tables, putting options inside `@code' produces a more pleasing +effect. + + +File: texinfo.info, Node: dfn, Next: cite, Prev: option, Up: Indicating + +9.1.12 `@dfn'{TERM} +------------------- + +Use the `@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 `@dfn'. The command generates italics in the printed manual, +and double quotation marks in the Info file. For example: + + Getting rid of a file is called @dfn{deleting} it. + +produces + + Getting rid of a file is called "deleting" it. + + 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. + + +File: texinfo.info, Node: cite, Next: acronym, Prev: dfn, Up: Indicating + +9.1.13 `@cite'{REFERENCE} +------------------------- + +Use the `@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. +*Note `@xref': xref. + + +File: texinfo.info, Node: acronym, Next: indicateurl, Prev: cite, Up: Indicating + +9.1.14 `@acronym'{ACRONYM[, MEANING]} +------------------------------------- + +Use the `@acronym' command for abbreviations written in all capital +letters, such as `NASA'. The abbreviation is given as the single +argument in braces, as in `@acronym{NASA}'. As a matter of style, or +for particular abbreviations, you may prefer to use periods, as in +`@acronym{F.B.I.}'. + + If the acronym is at the end of a sentence, remember to use the +special `@.' and similar commands (*note Ending a Sentence::). + + In TeX, the acronym is printed in slightly smaller font. In the Info +output, the argument is printed as-is. In HTML, Docbook, and XML, the +`<acronym>' tag is used. + + `@acronym' accepts an optional second argument, intended to be used +for the meaning of the acronym. If present, it is printed in +parentheses after the acronym. For instance (since GNU is a recursive +acronym, we use `@acronym' recursively): + + @acronym{GNU, @acronym{GNU}'s Not Unix} + +produces: + + GNU (@acronym{GNU}'s Not Unix) + + In some circumstances, it is conventional to print family names in all +capitals. Don't use `@acronym' for this, since a name is not an +acronym. Use `@sc' instead (*note Smallcaps::). + + +File: texinfo.info, Node: indicateurl, Next: email, Prev: acronym, Up: Indicating + +9.1.15 `@indicateurl'{UNIFORM-RESOURCE-LOCATOR} +----------------------------------------------- + +Use the `@indicateurl' command to indicate a uniform resource locator +on the World Wide Web. This is analogous to `@file', `@var', etc., and +is purely for markup purposes. It does not produce a link you can +follow in HTML output (use the `@uref' command for that, *note `@uref': +uref.). It is useful for url's which do not actually exist. For +example: + + For example, the url might be @indicateurl{http://example.org/path}. + +which produces: + + For example, the url might be <http://example.org/path>. + + +File: texinfo.info, Node: email, Prev: indicateurl, Up: Indicating + +9.1.16 `@email'{EMAIL-ADDRESS[, DISPLAYED-TEXT]} +------------------------------------------------ + +Use the `@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). + + 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, `@email' produces a `mailto' link that usually brings up a mail +composition window. For example: + + Send bug reports to @email{bug-texinfo@@gnu.org}, + suggestions to the @email{bug-texinfo@@gnu.org, same place}. + produces + Send bug reports to <bug-texinfo@gnu.org>, + suggestions to the same place <bug-texinfo@gnu.org>. + + +File: texinfo.info, Node: Emphasis, Prev: Indicating, Up: Marking Text + +9.2 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' 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 `@r' command, has any +regular use. + +* Menu: + +* emph & strong:: How to emphasize text in Texinfo. +* Smallcaps:: How to use the small caps font. +* Fonts:: Various font commands for printed output. + + +File: texinfo.info, Node: emph & strong, Next: Smallcaps, Up: Emphasis + +9.2.1 `@emph'{TEXT} and `@strong'{TEXT} +--------------------------------------- + +The `@emph' and `@strong' commands are for emphasis; `@strong' is +stronger. In printed output, `@emph' produces _italics_ and `@strong' +produces *bold*. + + For example, + + @strong{Caution:} @samp{rm * .[^.]*} + removes @emph{all} files in the directory. + +produces the following in printed output and HTML: + + *Caution*: `rm * .[^.]*' removes _all_ files in the directory. + +and the following in Info: + + *Caution:* `rm * .[^.]*' removes _all_ + files in the directory. + + The `@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, `@emph' surrounds the text with underscores +(`_'), and `@strong' puts asterisks around the text. + + Caution: Do not use `@strong' with the word `Note'; Info will + mistake the combination for a cross reference. (It's usually + redundant, anyway.) Use a phrase such as *Please notice* or + *Caution* instead, or the optional argument to + `@quotation'--`Note' is allowable there. + + +File: texinfo.info, Node: Smallcaps, Next: Fonts, Prev: emph & strong, Up: Emphasis + +9.2.2 `@sc'{TEXT}: The Small Caps Font +-------------------------------------- + +Use the `@sc' command to set text in A SMALL CAPS FONT (where +possible). Write the text you want to be in small caps between braces +in lower case, like this: + + Richard @sc{Stallman} founded @acronym{GNU}. + +This produces: + + Richard STALLMAN founded GNU. + + As shown here, we recommend using `@acronym' for actual abbreviations +(*note acronym::), and reserving `@sc' for special cases where you want +small caps. The output is not the same (`@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. + + TeX typesets any uppercase letters between the braces of an `@sc' +command in full-size capitals; only lowercase letters are printed in +the small caps font. In the Info output, the argument to `@sc' is +printed in all upper case. In HTML, the argument is uppercased and the +output marked with the `<small>' tag to reduce the font size. + + Since it's redundant to mark all-uppercase text with `@sc', +`makeinfo' warns about such usage. + + We recommend using regular mixed case wherever possible. + + +File: texinfo.info, Node: Fonts, Prev: Smallcaps, Up: Emphasis + +9.2.3 Fonts for Printing, Not Info +---------------------------------- + +Texinfo provides four 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 four commands apply to an argument that +follows, surrounded by braces. + +`@i' + selects an italic font; + +`@b' + selects bold face; + +`@t' + selects the fixed-width, typewriter-style font used by `@code'; + +`@r' + selects a roman font, which is the usual font in which text is + printed. + + + Only the `@r' command has much use: in example-like environments, you +can use the `@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 `<lineannotation>' tag in Docbook output. + + For example, + + @lisp + (+ 2 2) ; @r{Add two plus two.} + @end lisp + +produces + + (+ 2 2) ; Add two plus two. + + In general, you should avoid using the other three font commands. If +you need to use one, it probably indicates a gap in the Texinfo +language. + + +File: texinfo.info, Node: Quotations and Examples, Next: Lists and Tables, Prev: Marking Text, Up: Top + +10 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 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 `@end' command that is also at the beginning of a line by itself. +For instance, you begin an example by writing `@example' by itself at +the beginning of a line and end the example by writing `@end example' +on a line by itself, at the beginning of that line. + +* 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. + + +File: texinfo.info, Node: Block Enclosing Commands, Next: quotation, Up: Quotations and Examples + +10.1 Block Enclosing Commands +============================= + +Here are commands for quotations and examples, explained further in the +following sections: + +`@quotation' + Indicate text that is quoted. The text is filled, indented (from + both margins), and printed in a roman font by default. + +`@example' + Illustrate code, commands, and the like. The text is printed in a + fixed-width font, and indented but not filled. + +`@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 + `@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. + +`@smallexample' + Same as `@example', except that in TeX this command typesets text + in a smaller font. + +`@lisp' + Like `@example', but specifically for illustrating Lisp code. The + text is printed in a fixed-width font, and indented but not filled. + +`@smalllisp' + Is to `@lisp' as `@smallexample' is to `@example'. + +`@display' + Display illustrative text. The text is indented but not filled, + and no font is selected (so, by default, the font is roman). + +`@smalldisplay' + Is to `@display' as `@smallexample' is to `@example'. + +`@format' + Like `@display' (the text is not filled and no font is selected), + but the text is not indented. + +`@smallformat' + Is to `@format' as `@smallexample' is to `@example'. + + The `@exdent' command is used within the above constructs to undo the +indentation of a line. + + The `@flushleft' and `@flushright' commands are used to line up the +left or right margins of unfilled text. + + The `@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 `@cartouche' environment around one of the above +constructs to highlight the example or quotation by drawing a box with +rounded corners around it. *Note Drawing Cartouches Around Examples: +cartouche. + + +File: texinfo.info, Node: quotation, Next: example, Prev: Block Enclosing Commands, Up: Quotations and Examples + +10.2 `@quotation': Block quotations +=================================== + +The text of a quotation is processed normally (regular font, text is +filled) except that: + + * the margins are closer to the center of the page, so the whole of + the quotation is indented; + + * the first lines of paragraphs are indented no more than other + lines; + + * in the printed output, interparagraph spacing is reduced. + + This is an example of text written between an `@quotation' command + and an `@end quotation' command. An `@quotation' command is most + often used to indicate text that is excerpted from another (real + or hypothetical) printed work. + + Write an `@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 `@end quotation'. The `@end +quotation' line will likewise disappear from the output. + + `@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 `:'. +For example: + + @quotation Note + This is + a foo. + @end quotation + +produces + + Note: This is a foo. + + If the `@quotation' argument is exactly one of these words: + + Caution Important Note Tip Warning + +then the Docbook output uses corresponding special tags (`<note>', +etc.) instead of the default `<blockquote>'. HTML output always uses +`<blockquote>'. + + +File: texinfo.info, Node: example, Next: verbatim, Prev: quotation, Up: Quotations and Examples + +10.3 `@example': Example Text +============================= + +The `@example' environment is used to indicate an example that is not +part of the running text, such as computer input or output. Write an +`@example' command at the beginning of a line by itself. Mark the end +of the example with an `@end example' command, also written at the +beginning of a line by itself. + + An `@example' environment has the following characteristics: + + * Each line in the input file is a line in the output; that is, the + source text is not filled as it normally is. + + * Extra spaces and blank lines are significant. + + * The output is indented. + + * The output uses a fixed-width font. + + * Texinfo commands _are_ expanded; if you want the output to be the + input verbatim, use the `@verbatim' environment instead (*note + `@verbatim': verbatim.). + + For example, + + @example + cp foo @var{dest1}; \ + cp foo @var{dest2} + @end example + +produces + + cp foo DEST1; \ + cp foo DEST2 + + The lines containing `@example' and `@end example' will disappear +from the output. To make the output look good, you should put a blank +line before the `@example' and another blank line after the `@end +example'. Blank lines inside the beginning `@example' and the ending +`@end example', on the other hand, do appear in the output. + + 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 `M-x untabify' to convert tabs in a region to + multiple spaces. + + 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 `@noindent' command prevents a +piece of text from being indented as if it were a new paragraph (*note +`@noindent': noindent. + + If you want to embed code fragments within sentences, instead of +displaying them, use the `@code' command or its relatives (*note +`@code': code.). + + If you wish to write a "comment" on a line of an example in the +normal roman font, you can use the `@r' command (*note Fonts::). + + +File: texinfo.info, Node: verbatim, Next: verbatiminclude, Prev: example, Up: Quotations and Examples + +10.4 `@verbatim': Literal Text +============================== + +Use the `@verbatim' environment for printing of text that may contain +special characters or commands that should not be interpreted, such as +computer input or output (`@example' interprets its text as regular +Texinfo commands). This is especially useful for including +automatically generated output in a Texinfo manual. Here is an example; +the output you see is just the same as the input, with a line +`@verbatim' before and a line `@end verbatim' after. + + +This is an example of text written in a @verbatim +block. No character substitutions are made. All commands +are ignored, until `<at>end verbatim'. + +In the printed manual, the text is typeset in a +fixed-width font, and not indented or filled. All +spaces and blank lines are significant, including tabs. + + Write a `@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 `@end verbatim' command, also written at the beginning of +a line by itself. The `@end verbatim' will also disappear from the +output. + + For example: + +@verbatim +{ +<TAB>@command with strange characters: @'e +expand<TAB>me +} +@end verbatim + + +produces + + +{ + @command with strange characters: @'e +expand me +} + + Since the lines containing `@verbatim' and `@end verbatim' produce no +output, typically you should put a blank line before the `@verbatim' +and another blank line after the `@end verbatim'. Blank lines between +the beginning `@verbatim' and the ending `@end verbatim' will appear in +the output. + + It is not reliable to use `@verbatim' inside other Texinfo constructs. + + +File: texinfo.info, Node: verbatiminclude, Next: lisp, Prev: verbatim, Up: Quotations and Examples + +10.5 `@verbatiminclude' FILE: Include a File Verbatim +===================================================== + +You can include the exact contents of a file in the document with the +`@verbatiminclude' command: + + @verbatiminclude FILENAME + + The contents of FILENAME is printed in a verbatim environment (*note +`@verbatim': 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 +`@verbatiminclude' within `@example' (*note `@example': example.). + + The name of the file is taken literally, with a single exception: +`@value{VAR}' references are expanded. This makes it possible to +reliably include files in other directories in a distribution, for +instance: + + @include @value{top_srcdir}/NEWS + +(You still have to get `top_srcdir' defined in the first place.) + + +File: texinfo.info, Node: lisp, Next: small, Prev: verbatiminclude, Up: Quotations and Examples + +10.6 `@lisp': Marking a Lisp Example +==================================== + +The `@lisp' command is used for Lisp code. It is synonymous with the +`@example' command. + + This is an example of text written between an + `@lisp' command and an `@end lisp' command. + + Use `@lisp' instead of `@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.(1) + + Mark the end of `@lisp' with `@end lisp' on a line by itself. + + ---------- Footnotes ---------- + + (1) It would be straightforward to extend Texinfo to work in a +similar fashion for C, Fortran, or other languages. + + +File: texinfo.info, Node: small, Next: display, Prev: lisp, Up: Quotations and Examples + +10.7 `@small...' Block Commands +=============================== + +In addition to the regular `@example' and `@lisp' commands, Texinfo has +"small" example-style commands. These are `@smalldisplay', +`@smallexample', `@smallformat', and `@smalllisp'. + + In Info, the `@small...' commands are equivalent to their non-small +companion commands. + + In TeX, however, the `@small...' 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 `@small...' block with a corresponding `@end +small...'. For example, pair `@smallexample' with `@end smallexample'. + + Here is an example of the font used by the `@small...' commands (in +Info, the output will be the same as usual): + + ... 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. + + The `@small...' 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) `@example' or `@smallexample' consistently +within a chapter. + + +File: texinfo.info, Node: display, Next: format, Prev: small, Up: Quotations and Examples + +10.8 `@display' and `@smalldisplay' +=================================== + +The `@display' command begins a kind of example. It is like the +`@example' command except that, in a printed manual, `@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 `@display' command. + + This is an example of text written between an `@display' command + and an `@end display' command. The `@display' command + indents the text, but does not fill it. + + Texinfo also provides a command `@smalldisplay', which is like +`@display' but uses a smaller font in `@smallbook' format. *Note +small::. + + +File: texinfo.info, Node: format, Next: exdent, Prev: display, Up: Quotations and Examples + +10.9 `@format' and `@smallformat' +================================= + +The `@format' command is similar to `@example' except that, in the +printed manual, `@format' does not select the fixed-width font and does +not narrow the margins. + +This is an example of text written between an `@format' command +and an `@end format' command. As you can see +from this example, +the `@format' command does not fill the text. + + Texinfo also provides a command `@smallformat', which is like +`@format' but uses a smaller font in `@smallbook' format. *Note +small::. + + +File: texinfo.info, Node: exdent, Next: flushleft & flushright, Prev: format, Up: Quotations and Examples + +10.10 `@exdent': Undoing a Line's Indentation +============================================= + +The `@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 `@exdent' +line is printed in the roman font. + + `@exdent' is usually used within examples. Thus, + + @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 group + +produces + + This line follows an @example command. +This line is exdented. + This line follows the exdented line. + The @end example comes on the next line. + + In practice, the `@exdent' command is rarely used. Usually, you +un-indent text by ending the example and returning the page to its +normal width. + + +File: texinfo.info, Node: flushleft & flushright, Next: noindent, Prev: exdent, Up: Quotations and Examples + +10.11 `@flushleft' and `@flushright' +==================================== + +The `@flushleft' and `@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 +`@flushleft' and `@flushright' commands are ended by `@end flushleft' +and `@end flushright' commands on lines of their own. + + For example, + + @flushleft + This text is + written flushleft. + @end flushleft + +produces + + This text is + written flushleft. + + `@flushright' produces the type of indentation often used in the +return address of letters. For example, + + @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 + +produces + + Here is an example of text written + flushright. The `@flushright' command + right justifies every line but leaves the + left end ragged. + + +File: texinfo.info, Node: noindent, Next: indent, Prev: flushleft & flushright, Up: Quotations and Examples + +10.12 `@noindent': Omitting Indentation +======================================= + +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 +`@noindent' at the beginning of a line, preceding the continuation +text. You can also disable indentation for all paragraphs globally with +`@paragraphindent' (*note Paragraph Indenting: paragraphindent.). + + It is best to write `@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. + + For example: + + @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}.) + +produces: + + + This is an example + + 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 + `@display' and `@end display'.) + + To adjust the number of blank lines properly in the Info file output, +remember that the line containing `@noindent' does not generate a blank +line, and neither does the `@end example' line. + + In the Texinfo source file for this manual, each line that says +`produces' is preceded by `@noindent'. + + Do not put braces after an `@noindent' command; they are not +necessary, since `@noindent' is a command used outside of paragraphs +(*note Command Syntax::). + + +File: texinfo.info, Node: indent, Next: cartouche, Prev: noindent, Up: Quotations and Examples + +10.13 `@indent': Forcing Indentation +==================================== + + To complement the `@noindent' command (see the previous section), +Texinfo provides the `@indent' command that forces a paragraph to be +indented. This paragraph, for instance, is indented using an `@indent' +command. The first paragraph of a section is the most likely place to +use `@indent', to override the normal behavior of no indentation there +(*note paragraphindent::). + + It is best to write `@indent' on a line by itself, since in most +environments, spaces following the command will not be ignored. The +`@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 `@indent' command; they are not necessary, +since `@indent' is a command used outside of paragraphs (*note Command +Syntax::). + + +File: texinfo.info, Node: cartouche, Prev: indent, Up: Quotations and Examples + +10.14 `@cartouche': Rounded Rectangles Around Examples +====================================================== + +In a printed manual, the `@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). `@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, + + @cartouche + @example + % pwd + /usr/local/share/emacs + @end example + @end cartouche + +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 `@cartouche' had no effect): + + % pwd + /usr/local/info + + For proper output in HTML, it's necessary to put the `@cartouche' +around the `@example', and not the other way around. This limitation +of `makeinfo' may be removed one day. + + `@cartouche' also implies `@group' (*note group::). + + +File: texinfo.info, Node: Lists and Tables, Next: Special Displays, Prev: Quotations and Examples, Up: Top + +11 Lists and Tables +******************* + +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. + + +File: texinfo.info, Node: Introducing Lists, Next: itemize, Up: Lists and Tables + +11.1 Introducing Lists +====================== + +Texinfo automatically indents the text in lists or tables, and numbers +an enumerated list. This last feature is useful if you modify the +list, since you do not need to renumber it yourself. + + Numbered lists and tables begin with the appropriate @-command at the +beginning of a line, and end with the corresponding `@end' command on a +line by itself. The table and itemized-list commands also require that +you write formatting information on the same line as the beginning +@-command. + + Begin an enumerated list, for example, with an `@enumerate' command +and end the list with an `@end enumerate' command. Begin an itemized +list with an `@itemize' command, followed on the same line by a +formatting command such as `@bullet', and end the list with an `@end +itemize' command. + + Precede each element of a list with an `@item' or `@itemx' command. + + +Here is an itemized list of the different kinds of table and lists: + + * Itemized lists with and without bullets. + + * Enumerated lists, using numbers or letters. + + * Two-column tables with highlighting. + + +Here is an enumerated list with the same items: + + 1. Itemized lists with and without bullets. + + 2. Enumerated lists, using numbers or letters. + + 3. Two-column tables with highlighting. + + +And here is a two-column table with the same items and their @-commands: + +`@itemize' + Itemized lists with and without bullets. + +`@enumerate' + Enumerated lists, using numbers or letters. + +`@table' +`@ftable' +`@vtable' + Two-column tables, optionally with indexing. + + +File: texinfo.info, Node: itemize, Next: enumerate, Prev: Introducing Lists, Up: Lists and Tables + +11.2 `@itemize': Making an Itemized List +======================================== + +The `@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. + + Begin an itemized list by writing `@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 +`@bullet' after `@itemize', but you can use `@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 `@w'. (When you write the mark command +such as `@bullet' after an `@itemize' command, you may omit the `{}'.) +If you don't specify a mark command, the default is `@bullet'. + + Write the text of the indented paragraphs themselves after the +`@itemize', up to another line that says `@end itemize'. + + At the beginning of each paragraph for which a mark in the margin is +desired, write a line that starts with `@item'. It is ok to have text +following the `@item'. + + Usually, you should put a blank line before an `@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. + + Here is an example of the use of `@itemize', followed by the output +it produces. `@bullet' produces an `*' in Info and a round dot in TeX. + + @itemize @bullet + @item + Some text for foo. + + @item + Some text + for bar. + @end itemize + +This produces: + + * Some text for foo. + + * Some text for bar. + + Itemized lists may be embedded within other itemized lists. Here is a +list marked with dashes embedded in a list marked with bullets: + + @itemize @bullet + @item + First item. + + @itemize @minus + @item + Inner item. + + @item + Second inner item. + @end itemize + + @item + Second outer item. + @end itemize + +This produces: + + * First item. + + - Inner item. + + - Second inner item. + + * Second outer item. + + +File: texinfo.info, Node: enumerate, Next: Two-column Tables, Prev: itemize, Up: Lists and Tables + +11.3 `@enumerate': Making a Numbered or Lettered List +===================================================== + +`@enumerate' is like `@itemize' (*note `@itemize': itemize.), except +that the labels on the items are successive integers or letters instead +of bullets. + + Write the `@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, `@enumerate' starts the list +with the number `1'. With a numeric argument, such as `3', the command +starts the list with that number. With an upper or lower case letter, +such as `a' or `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 `@item' at the beginning of each +paragraph that you want enumerated. It is ok to have text following +the `@item'. + + You should put a blank line between entries in the list. This +generally makes it easier to read the Info file. + + Here is an example of `@enumerate' without an argument: + + @enumerate + @item + Underlying causes. + + @item + Proximate causes. + @end enumerate + +This produces: + + 1. Underlying causes. + + 2. Proximate causes. + + + Here is an example with an argument of `3': + + @enumerate 3 + @item + Predisposing causes. + + @item + Precipitating causes. + + @item + Perpetuating causes. + @end enumerate + +This produces: + + 3. Predisposing causes. + + 4. Precipitating causes. + + 5. Perpetuating causes. + + + Here is a brief summary of the alternatives. The summary is +constructed using `@enumerate' with an argument of `a'. + + a. `@enumerate' + + Without an argument, produce a numbered list, starting with the + number 1. + + b. `@enumerate 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. + + c. `@enumerate 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. + + d. `@enumerate 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. + + You can also nest enumerated lists, as in an outline. + + +File: texinfo.info, Node: Two-column Tables, Next: Multi-column Tables, Prev: enumerate, Up: Lists and Tables + +11.4 Making a Two-column Table +============================== + +`@table' is similar to `@itemize' (*note `@itemize': itemize.), but +allows you to specify a name or heading line for each item. The +`@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. + + +File: texinfo.info, Node: table, Next: ftable vtable, Up: Two-column Tables + +11.4.1 Using the `@table' Command +--------------------------------- + +Use the `@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 `@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', `@samp', `@var', `@option', or +`@kbd' (*note 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, `@table @code' will cause the text in the first column to +be output as if it `@code' command. + + You may also use the `@asis' command as an argument to `@table'. +`@asis' is a command that does nothing; if you use this command after +`@table', the first column entries are output without added +highlighting ("as is"). + + The `@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 `@item''s will +supply the argument.) + + Begin each table entry with an `@item' command at the beginning of a +line. Write the first column text on the same line as the `@item' +command. Write the second column text on the line following the +`@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 `@item' will be placed in the +first column (including any footnotes). + + Normally, you should put a blank line before an `@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 `@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. + + The following table, for example, highlights the text in the first +column with an `@samp' command: + + @table @samp + @item foo + This is the text for + @samp{foo}. + + @item bar + Text for @samp{bar}. + @end table + +This produces: + +`foo' + This is the text for `foo'. + +`bar' + Text for `bar'. + + If you want to list two or more named items with a single block of +text, use the `@itemx' command. (*Note `@itemx': itemx.) + + +File: texinfo.info, Node: ftable vtable, Next: itemx, Prev: table, Up: Two-column Tables + +11.4.2 `@ftable' and `@vtable' +------------------------------ + +The `@ftable' and `@vtable' commands are the same as the `@table' +command except that `@ftable' automatically enters each of the items in +the first column of the table into the index of functions and `@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 `@item' commands are +indexed, and they are indexed in exactly the form that they appear on +that line. *Note Indices::, for more information about indices. + + Begin a two-column table using `@ftable' or `@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', exactly as you +would for an `@table' command; and end the table with an `@end ftable' +or `@end vtable' command on a line by itself. + + See the example for `@table' in the previous section. + + +File: texinfo.info, Node: itemx, Prev: ftable vtable, Up: Two-column Tables + +11.4.3 `@itemx' +--------------- + +Use the `@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 `@item' for the first entry, and `@itemx' for all subsequent +entries; `@itemx' must always follow an `@item' command, with no blank +line intervening. + + The `@itemx' command works exactly like `@item' except that it does +not generate extra vertical space above the first column text. If you +have multiple consecutive `@itemx' commands, do not insert any blank +lines between them. + + For example, + + @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 + +This produces: + +`upcase' +`downcase' + These two functions accept a character or a string as argument, + and return the corresponding upper case (lower case) character or + string. + +(Note also that this example illustrates multi-line supporting text in +a two-column table.) + + +File: texinfo.info, Node: Multi-column Tables, Prev: Two-column Tables, Up: Lists and Tables + +11.5 `@multitable': Multi-column Tables +======================================= + +`@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 `@multitable' line itself, and +write each row of the actual table following an `@item' command, with +columns separated by an `@tab' command. Finally, `@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. + + +File: texinfo.info, Node: Multitable Column Widths, Next: Multitable Rows, Up: Multi-column Tables + +11.5.1 Multitable Column Widths +------------------------------- + +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 `@multitable' command. + + 1. To specify column widths as fractions of the line length, write + `@columnfractions' and the decimal numbers (presumably less than + 1; a leading zero is allowed and ignored) after the `@multitable' + command, as in: + + @multitable @columnfractions .33 .33 .33 + + 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. + + 2. To specify a prototype row, write the longest entry for each column + enclosed in braces after the `@multitable' command. For example: + + @multitable {some text for column one} {for column two} + + 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' are particularly likely to be useful. + + + +File: texinfo.info, Node: Multitable Rows, Prev: Multitable Column Widths, Up: Multi-column Tables + +11.5.2 Multitable Rows +---------------------- + +After the `@multitable' command defining the column widths (see the +previous section), you begin each row in the body of a multitable with +`@item', and separate the column entries with `@tab'. Line breaks are +not special within the table body, and you may break input lines in +your source file as necessary. + + You can also use `@headitem' instead of `@item' to produce a "heading +row". The TeX output for such a row is in bold, and the HTML, XML, and +Docbook output uses the `<thead>' tag. + + Here is a complete example of a multi-column table (the text is from +`The GNU Emacs Manual', *note Splitting Windows: (emacs)Split Window.): + + @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 + +produces: + +Key Command Description +--------------------------------------------------------------------------- +C-x 2 `split-window-vertically' Split the selected window + into two windows, with one + above the other. +C-x 3 `split-window-horizontally' Split the selected window + into two windows positioned + side by side. +C-Mouse-2 In the mode line or scroll + bar of a window, split that + window. + + +File: texinfo.info, Node: Special Displays, Next: Indices, Prev: Lists and Tables, Up: Top + +12 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. + + +File: texinfo.info, Node: Floats, Next: Images, Up: Special Displays + +12.1 Floats +=========== + +A "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. + + 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 +`@group' (*note `@group': group.). + +* Menu: + +* float:: Producing floating material. +* caption shortcaption:: Specifying descriptions for floats. +* listoffloats:: A table of contents for floats. + + +File: texinfo.info, Node: float, Next: caption shortcaption, Up: Floats + +12.1.1 `@float' [TYPE][,LABEL]: Floating material +------------------------------------------------- + +To produce floating material, enclose the material you want to be +displayed separate between `@float' and `@end float' commands, on lines +by themselves. + + Floating material uses `@image' to display an already-existing +graphic (*note Images::), or `@multitable' to display a table (*note +Multi-column Tables::). However, the contents of the float can be +anything. Here's an example with simple text: + + @float Figure,fig:ex1 + This is an example float. + @end float + +And the output: + +This is an example float. + +Figure 12.1 + + As shown in the example, `@float' takes two arguments (separated by a +comma), TYPE and LABEL. Both are optional. + +TYPE + Specifies the sort of float this is; typically a word such as + "Figure", "Table", etc. If not given, and LABEL is, any + cross-referencing will simply use a bare number. + +LABEL + Specifies a cross-reference label for this float. If given, this + float is automatically given a number, and will appear in any + `@listofloats' output (*note listoffloats::). Cross-references to + LABEL are allowed. + + On the other hand, if LABEL is not given, then the float will not + be numbered and consequently will not appear in the + `@listoffloats' output or be cross-referenceable. + +Normally, you specify both TYPE and LABEL, to get a labeled and +numbered float. + + 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, ..., and is reset at each chapter. Each float +type is counted independently. + + Floats within an `@unnumbered' are numbered, or outside of any +chapter, are simply numbered consecutively from 1. + + These numbering conventions are not, at present, changeable. + + +File: texinfo.info, Node: caption shortcaption, Next: listoffloats, Prev: float, Up: Floats + +12.1.2 `@caption' & `@shortcaption' +----------------------------------- + +You may write an `@caption' anywhere within a `@float' environment, to +define a caption for the float. It is not allowed in any other +context. `@caption' takes a single argument, enclosed in braces. +Here's an example: + + @float + An example float, with caption. + @caption{Caption for example float.} + @end float + +The output is: + +An example float, with caption. + +Caption for example float. + + `@caption' can appear anywhere within the float; it is not processed +until the `@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 `@float' command (see the previous section). + + The `@shortcaption' command likewise may be used only within +`@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. + + +File: texinfo.info, Node: listoffloats, Prev: caption shortcaption, Up: Floats + +12.1.3 `@listoffloats': Tables of contents for floats +----------------------------------------------------- + +You can write a `@listoffloats' command to generate a list of floats +for a given float type (*note float::), analogous to the document's +overall table of contents. Typically, it is written in its own +`@unnumbered' node to provide a heading and structure, rather like +`@printindex' (*note Printing Indices & Menus::). + + `@listoffloats' takes one optional argument, the float type. Here's +an example: + + @node List of Figures + @unnumbered List of Figures + @listoffloats Figure + +And the output from `@listoffloats': + +* Menu: + +* Figure 12.1: fig:ex1. + + + Without any argument, `@listoffloats' generates a list of floats for +which no float type was specified, i.e., no first argument to the +`@float' command (*note float::). + + Each line in the list of floats contains the float type (if any), the +float number, and the caption, if any--the `@shortcaption' argument, if +it was specified, else the `@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. + + +File: texinfo.info, Node: Images, Next: Footnotes, Prev: Floats, Up: Special Displays + +12.2 Inserting Images +===================== + +You can insert an image given in an external file with the `@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:: + + +File: texinfo.info, Node: Image Syntax, Next: Image Scaling, Up: Images + +12.2.1 Image Syntax +------------------- + +Here is the basic synopsis of the `@image' command: + + @image{FILENAME[, WIDTH[, HEIGHT[, ALTTEXT[, EXTENSION]]]]} + + The FILENAME argument is mandatory, and must not have an extension, +because the different processors support different formats: + + * TeX reads the file `FILENAME.eps' (Encapsulated PostScript format). + + * PDFTeX reads `FILENAME.pdf' (Adobe's Portable Document Format). + + * `makeinfo' includes `FILENAME.txt' verbatim for Info output (more + or less as if it was an `@example'). + + * `makeinfo' uses the optional fifth argument EXTENSION to `@image' + for the filename extension, if it is specified. For example: + + @image{foo,,,,.xpm} + + will cause `makeinfo' to look for `foo.xpm' before any others. + + + The WIDTH and HEIGHT arguments are described in the next section. + + When producing html, `makeinfo' sets the "alt attribute" for inline +images to the optional ALTTEXT (fourth) argument to `@image', if +supplied. If not supplied, `makeinfo' uses the full file name of the +image being displayed. If you want an empty `alt' string, use `@-'. +The ALTTEXT is taken as Texinfo text, so special characters such as `"' +and `<' and `&' are escaped in the HTML and XML output. + + If you do not supply the optional EXTENSION (fifth) argument, +`makeinfo' first tries `FILENAME.png'; if that does not exist, it tries +`FILENAME.jpg'. If that does not exist either, it complains. (We +cannot support GIF format directly due to software patents.) + + In Info output, `makeinfo' writes a reference to the binary image +file (trying FILENAME suffixed with `EXTENSION', `.EXTENSION', `.png', +or `.jpg', in that order) if one exists. It also literally includes +the `.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. + + The implementation of this is to put the following construct into the +Info output: + + ^@^H[image src="BINARYFILE" text="TXTFILE" + alt="ALTTEXT ... ^@^H] + +where `^@' and `^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. + + +File: texinfo.info, Node: Image Scaling, Prev: Image Syntax, Up: Images + +12.2.2 Image Scaling +-------------------- + +The optional WIDTH and HEIGHT arguments to the `@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. + + The WIDTH and HEIGHT may be specified using any valid TeX dimension, +namely: + +pt + point (72.27pt = 1in) + +pc + pica (1pc = 12pt) + +bp + big point (72bp = 1in) + +in + inch + +cm + centimeter (2.54cm = 1in) + +mm + millimeter (10mm = 1cm) + +dd + dido^t point (1157dd = 1238pt) + +cc + cicero (1cc = 12dd) + +sp + scaled point (65536sp = 1pt) + + For example, the following will scale a file `ridt.eps' to one inch +vertically, with the width scaled proportionately: + + @image{ridt,,1in} + + For `@image' to work with TeX, the file `epsf.tex' must be installed +somewhere that TeX can find it. (The standard location is +`TEXMF/tex/generic/dvips/epsf.tex', where TEXMF is a root of your TeX +directory tree.) This file is included in the Texinfo distribution and +is also available from `ftp://tug.org/tex/epsf.tex', among other places. + + `@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. + + +File: texinfo.info, Node: Footnotes, Prev: Images, Up: Special Displays + +12.3 Footnotes +============== + +A "footnote" is for a reference that documents or elucidates the +primary text.(1) 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. + + ---------- Footnotes ---------- + + (1) 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 `The Chicago Manual +of Style', which is published by the University of Chicago Press. + + +File: texinfo.info, Node: Footnote Commands, Next: Footnote Styles, Up: Footnotes + +12.3.1 Footnote Commands +------------------------ + +In Texinfo, footnotes are created with the `@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: + + ordinary text@footnote{TEXT OF FOOTNOTE} + + As shown here, the `@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(1); in the +Texinfo source, it looks like this: + + ...a sample footnote@footnote{Here is the sample + footnote.}; in the Texinfo source... + + As you can see, the source includes two punctuation marks next to each +other; in this case, `.};' 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: `(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 `@item' command for a +`@table' must be on the same line as the `@item' (as usual). *Note +Two-column Tables::. + + ---------- Footnotes ---------- + + (1) Here is the sample footnote. + + +File: texinfo.info, Node: Footnote Styles, Prev: Footnote Commands, Up: Footnotes + +12.3.2 Footnote Styles +---------------------- + +Info has two footnote styles, which determine where the text of the +footnote is located: + + * 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 `Footnotes' + within it. Each footnote begins with an `(N)' reference mark. + + Here is an example of a single footnote in the end of node style: + + --------- Footnotes --------- + + (1) Here is a sample footnote. + + * 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 `(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 `-Footnotes' to the name of the node that contains the + footnotes. (Consequently, the footnotes' node for the `Footnotes' + node is `Footnotes-Footnotes'!) The footnotes' node has an `Up' + node pointer that leads back to its parent node. + + Here is how the first footnote in this manual looks after being + formatted for Info in the separate node style: + + File: texinfo.info Node: Overview-Footnotes, Up: Overview + + (1) The first syllable of "Texinfo" is pronounced like "speck", not + "hex". ... + + Unless your document has long and important footnotes (as in, say, +Gibbon's `Decline and Fall ...'), we recommend the `end' style, as it +is simpler for readers to follow. + + Use the `@footnotestyle' command to specify an Info file's footnote +style. Write this command at the beginning of a line followed by an +argument, either `end' for the end node style or `separate' for the +separate node style. + + For example, + + @footnotestyle end + or + @footnotestyle separate + + Write an `@footnotestyle' command before or shortly after the +end-of-header line at the beginning of a Texinfo file. (If you include +the `@footnotestyle' command between the start-of-header and +end-of-header lines, the region formatting commands will format +footnotes as specified.) + + If you do not specify a footnote style, the formatting commands use +their default style. Currently, `texinfo-format-buffer' and +`texinfo-format-region' use the `separate' style and `makeinfo' uses +the `end' style. + + +File: texinfo.info, Node: Indices, Next: Insertions, Prev: Special Displays, Up: Top + +13 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. + + *Note 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. + + +File: texinfo.info, Node: Index Entries, Next: Predefined Indices, Up: Indices + +13.1 Making Index Entries +========================= + +When you are making index entries, it is good practice to think of the +different ways people may look for something. Different people _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. + + 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. + + *Note Printing Indices & Menus::, for information about printing an +index at the end of a book or creating an index menu in an Info file. + + +File: texinfo.info, Node: Predefined Indices, Next: Indexing Commands, Prev: Index Entries, Up: Indices + +13.2 Predefined Indices +======================= + +Texinfo provides six predefined indices. Here are their nominal +meanings, abbreviations, and the corresponding index entry commands: + +`cp' + (`@cindex') concept index, for general concepts. + +`fn' + (`@findex') function index, for function and function-like names + (such as entry points of libraries). + +`ky' + (`@kindex') keystroke index, for keyboard commands. + +`pg' + (`@pindex') program index, for names of programs. + +`tp' + (`@tindex') data type index, for type names (such as structures + defined in header files). + +`vr' + (`@vindex') variable index, for variable names (such as global + variables of libraries). + +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 `@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 (*note 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 `@synindex' or `@syncodeindex' commands +(*note Combining Indices::). + + +File: texinfo.info, Node: Indexing Commands, Next: Combining Indices, Prev: Predefined Indices, Up: Indices + +13.3 Defining the Entries of an Index +===================================== + +The data to make an index come from many individual indexing commands +scattered throughout the Texinfo source file. Each command says to add +one entry to a particular index; after formatting, the index will give +the current page number or node name as the reference. + + An index entry consists of an indexing command at the beginning of a +line followed, on the rest of the line, by the entry. + + For example, this section begins with the following five entries for +the concept index: + + @cindex Defining indexing entries + @cindex Index entries, defining + @cindex Entries for an index + @cindex Specifying index entries + @cindex Creating index entries + + Each predefined index has its own indexing command--`@cindex' for the +concept index, `@findex' for the function index, and so on, as listed +in the previous section. + + 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. + + 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' +font. You may change the way part of an entry is printed with the +usual Texinfo commands, such as `@file' for file names (*note Marking +Text::), and `@r' for the normal roman font (*note Fonts::). + + 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. *Note Menu Parts::, for more + information about the structure of a menu entry. + + +File: texinfo.info, Node: Combining Indices, Next: New Indices, Prev: Indexing Commands, Up: Indices + +13.4 Combining Indices +====================== + +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 `@cindex' +commands for them instead of `@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'. + +* Menu: + +* syncodeindex:: How to merge two indices, using `@code' + font for the merged-from index. +* synindex:: How to merge two indices, using the + default font of the merged-to index. + + +File: texinfo.info, Node: syncodeindex, Next: synindex, Up: Combining Indices + +13.4.1 `@syncodeindex' +---------------------- + +When you want to combine functions and concepts into one index, you +should index the functions with `@findex' and index the concepts with +`@cindex', and use the `@syncodeindex' command to redirect the function +index entries into the concept index. + + The `@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: + + @syncodeindex FROM TO + + For this purpose, the indices are given two-letter names: + +`cp' + concept index + +`fn' + function index + +`vr' + variable index + +`ky' + key index + +`pg' + program index + +`tp' + data type index + + Write an `@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: + + @syncodeindex fn cp + +This will cause all entries designated for the function index to merge +in with the concept index instead. + + To merge both a variables index and a function index into a concept +index, write the following: + + @syncodeindex vr cp + @syncodeindex fn cp + + The `@syncodeindex' command puts all the entries from the `from' +index (the redirected index) into the `@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' +font as you would expect. + + +File: texinfo.info, Node: synindex, Prev: syncodeindex, Up: Combining Indices + +13.4.2 `@synindex' +------------------ + +The `@synindex' command is nearly the same as the `@syncodeindex' +command, except that it does not put the `from' index entries into the +`@code' font; rather it puts them in the roman font. Thus, you use +`@synindex' when you merge a concept index into a function index. + + *Note Printing Indices & Menus::, for information about printing an +index at the end of a book or creating an index menu in an Info file. + + +File: texinfo.info, Node: New Indices, Prev: Combining Indices, Up: Indices + +13.5 Defining New Indices +========================= + +In addition to the predefined indices, you may use the `@defindex' and +`@defcodeindex' commands to define new indices. These commands create +new indexing @-commands with which you mark index entries. The +`@defindex' command is used like this: + + @defindex NAME + + The name of an index should be a two letter word, such as `au'. For +example: + + @defindex au + + This defines a new index, called the `au' index. At the same time, +it creates a new indexing command, `@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 `au' index entries. + + @section Cognitive Semantics + @cindex kinesthetic image schemas + @auindex Johnson, Mark + @auindex Lakoff, George + +(Evidently, `au' serves here as an abbreviation for "author".) + + In general, Texinfo constructs the new indexing command by +concatenating the name of the index with `index'; thus, defining an +`xy' index leads to the automatic creation of an `@xyindex' command. + + Use the `@printindex' command to print the index, as you do with the +predefined indices. For example: + + @node Author Index + @unnumbered Author Index + + @printindex au + + The `@defcodeindex' is like the `@defindex' command, except that, in +the printed output, it prints entries in an `@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 `@synindex' or `@syncodeindex' +commands (*note Texinfo File Header::). + + +File: texinfo.info, Node: Insertions, Next: Breaks, Prev: Indices, Up: Top + +14 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. + +* Menu: + +* Atsign Braces Comma:: Inserting @ and {} and ,. +* Inserting Space:: How to insert the right amount of space + within a sentence. +* Inserting Accents:: How to insert accents and special characters. +* Dots Bullets:: How to insert dots and bullets. +* TeX and copyright:: How to insert the TeX logo + and the copyright symbol. +* pounds:: How to insert the pounds currency symbol. +* minus:: How to insert a minus sign. +* math:: How to format a mathematical expression. +* Glyphs:: How to indicate results of evaluation, + expansion of macros, errors, etc. + + +File: texinfo.info, Node: Atsign Braces Comma, Next: Inserting Space, Up: Insertions + +14.1 Inserting @ and {} and , +============================= + +`@' and curly braces are special characters in Texinfo. To insert +these characters so they appear in text, you must put an `@' 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:: + + +File: texinfo.info, Node: Inserting an Atsign, Next: Inserting Braces, Up: Atsign Braces Comma + +14.1.1 Inserting `@' with `@@' +------------------------------ + +`@@' stands for a single `@' in either printed or Info output. + + Do not put braces after an `@@' command. + + +File: texinfo.info, Node: Inserting Braces, Next: Inserting a Comma, Prev: Inserting an Atsign, Up: Atsign Braces Comma + +14.1.2 Inserting `{' and `}' with `@{' and `@}' +----------------------------------------------- + +`@{' stands for a single `{' in either printed or Info output. + + `@}' stands for a single `}' in either printed or Info output. + + Do not put braces after either an `@{' or an `@}' command.ppp + + +File: texinfo.info, Node: Inserting a Comma, Prev: Inserting Braces, Up: Atsign Braces Comma + +14.1.3 Inserting `,' with `@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 `@acronym' (*note acronym::) and +`@xref' (*note Cross References::), as well as user-defined macros +(*note Defining Macros::), can take more than one argument. In these +cases, the comma character is used to separate arguments. + + Since a comma chacter would confuse Texinfo's parsing for these +commands, you must use the command `,' instead if you want to have an +actual comma in the output. Here are some examples: + + @acronym{ABC, A Bizarre @comma{}} + @xref{Comma,, The @comma{} symbol} + @mymac{One argument@comma{} containing a comma} + + Although , can be used anywhere, there is no need for it anywhere +except in this unusual case. + + +File: texinfo.info, Node: Inserting Space, Next: Inserting Accents, Prev: Atsign Braces Comma, Up: Insertions + +14.2 Inserting Space +==================== + +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. +* dmn:: How to format a dimension. + + +File: texinfo.info, Node: Not Ending a Sentence, Next: Ending a Sentence, Up: Inserting Space + +14.2.1 Not Ending a Sentence +---------------------------- + +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. + + Use the `@:' command after a period, question mark, exclamation mark, +or colon that should not be followed by extra space. For example, use +`@:' after periods that end abbreviations which are not at the ends of +sentences. + + For example, + + The s.o.p.@: has three parts ... + The s.o.p. has three parts ... + +produces + + The s.o.p. has three parts ... + The s.o.p. has three parts ... + +(Incidentally, `s.o.p.' is an abbreviation for "Standard Operating +Procedure".) + + `@:' 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: `. ? ! :'. +This gives further processors a chance to notice and not add the usual +extra space. + + Do not put braces after `@:' (or any non-alphabetic command). + + +File: texinfo.info, Node: Ending a Sentence, Next: Multiple Spaces, Prev: Not Ending a Sentence, Up: Inserting Space + +14.2.2 Ending a Sentence +------------------------ + +Use `@.' instead of a period, `@!' instead of an exclamation point, and +`@?' 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: + + 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. + +produces + + 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. + + In the Info file output, `@.' is equivalent to a simple `.'; likewise +for `@!' and `@?'. + + The meanings of `@:' and `@.' in Texinfo are designed to work well +with the Emacs sentence motion commands (*note Sentences: +(emacs)Sentences.). + + Do not put braces after any of these commands. + + +File: texinfo.info, Node: Multiple Spaces, Next: dmn, Prev: Ending a Sentence, Up: Inserting Space + +14.2.3 Multiple Spaces +---------------------- + +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: `@SPACE', `@TAB', +and `@NL', all of which insert a single space into the output. (Here, +`@SPACE' represents an `@' character followed by a space, i.e., `@ ', +and `TAB' and `NL' represent the tab character and end-of-line, i.e., +when `@' is the last character on a line.) + + For example, + Spacey@ @ @ @ + example. + +produces + + Spacey example. + + Other possible uses of `@SPACE' have been subsumed by `@multitable' +(*note Multi-column Tables::). + + Do not follow any of these commands with braces. + + To produce a non-breakable space, see *Note `@tie': tie. + + +File: texinfo.info, Node: dmn, Prev: Multiple Spaces, Up: Inserting Space + +14.2.4 `@dmn'{DIMENSION}: Format a Dimension +-------------------------------------------- + +At times, you may want to write `12pt' or `8.5in' with little or no +space between the number and the abbreviation for the dimension. You +can use the `@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 `@dmn' command, write the number and then follow it +immediately, with no intervening space, by `@dmn', and then by the +dimension within braces. For example, + + A4 paper is 8.27@dmn{in} wide. + +produces + + A4 paper is 8.27in wide. + + Not everyone uses this style. Some people prefer `8.27 in.@:' or +`8.27 inches' to `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 `@w' (*note w::). Also, if you write a period +after an abbreviation within a sentence, you should write `@:' after +the period to prevent TeX from inserting extra whitespace, as shown +here. *Note Not Ending a Sentence::. + + +File: texinfo.info, Node: Inserting Accents, Next: Dots Bullets, Prev: Inserting Space, Up: Insertions + +14.3 Inserting Accents +====================== + +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: `@,' _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. + + To get the true accented characters output in Info, and not just the +ASCII transliterations, you can use the `--enable-encoding' option to +`makeinfo' (*note makeinfo options::). + +Command Output What +@"o o" umlaut accent +@'o o' acute accent +@,{c} c, cedilla accent +@=o o= macron/overbar accent +@^o o^ circumflex accent +@`o o` grave accent +@~o o~ tilde accent +@dotaccent{o} o. overdot accent +@H{o} o'' long Hungarian umlaut +@ringaccent{o} o* ring accent +@tieaccent{oo} oo[ tie-after accent +@u{o} o( breve accent +@ubaraccent{o} o_ underbar accent +@udotaccent{o} .o underdot accent +@v{o} o< hacek/check/caron accent + + This table lists the Texinfo commands for inserting other characters +commonly used in languages other than English. + +@exclamdown{} ! upside-down ! +@questiondown{} ? upside-down ? +@aa{} @AA{} aa AA a,A with circle +@ae{} @AE{} ae AE ae,AE ligatures +@dotless{i} i dotless i +@dotless{j} j dotless j +@l{} @L{} /l /L suppressed-L,l +@o{} @O{} /o /O O,o with slash +@oe{} @OE{} oe OE oe,OE ligatures +@ordf{} @ordm{} a o Spanish ordinals +@ss{} ss es-zet or sharp S + + +File: texinfo.info, Node: Dots Bullets, Next: TeX and copyright, Prev: Inserting Accents, Up: Insertions + +14.4 Inserting Ellipsis and Bullets +=================================== + +An "ellipsis" (a line of dots) is not typeset as a string of periods, +so a special command is used for ellipsis in Texinfo. The `@bullet' +command is special, too. Each of these commands is followed by a pair +of braces, `{}', 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. *Note @-Command Syntax: Command Syntax, for further +information.) + +* Menu: + +* dots:: How to insert dots ... +* bullet:: How to insert a bullet. + + +File: texinfo.info, Node: dots, Next: bullet, Up: Dots Bullets + +14.4.1 `@dots'{} (...) and `@enddots'{} (....) +---------------------------------------------- + +Use the `@dots{}' command to generate an ellipsis, which is three dots +in a row, appropriately spaced ... 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 `@enddots{}' command generates an end-of-sentence +ellipsis, which has different spacing afterwards, .... Look closely to +see the difference. + + +File: texinfo.info, Node: bullet, Prev: dots, Up: Dots Bullets + +14.4.2 `@bullet'{} (*) +---------------------- + +Use the `@bullet{}' command to generate a large round dot, or the +closest possible thing to one. In Info, an asterisk is used. + + Here is a bullet: * + + When you use `@bullet' in `@itemize', you do not need to type the +braces, because `@itemize' supplies them. (*Note `@itemize': itemize.) + + +File: texinfo.info, Node: TeX and copyright, Next: pounds, Prev: Dots Bullets, Up: Insertions + +14.5 Inserting TeX and Legal Symbols: (C), (R) +============================================== + +The logo `TeX' is typeset in a special fashion and it needs an +@-command. The copyright and registered symbols, `(C)' and `(R)', is +also special. Each of these commands is followed by a pair of braces, +`{}', 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). + + +File: texinfo.info, Node: tex, Next: copyright symbol, Up: TeX and copyright + +14.5.1 `@TeX'{} (TeX) and `@LaTeX'{} (LaTeX) +-------------------------------------------- + +Use the `@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 `TeX'. + + Similarly, use the `@LaTeX{}' command to generate `LaTeX', which is +even more special in printed manuals (and different from the incorrect +`La@TeX{}'. In Info, the result is just `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. + + +File: texinfo.info, Node: copyright symbol, Next: registered symbol, Prev: tex, Up: TeX and copyright + +14.5.2 `@copyright{}' ((C)) +--------------------------- + +Use the `@copyright{}' command to generate the copyright symbol, `(C)'. +Where possible, this is a `c' inside a circle; in Info, this is `(C)'. + + +File: texinfo.info, Node: registered symbol, Prev: copyright symbol, Up: TeX and copyright + +14.5.3 `@registeredsymbol{}' ((R)) +---------------------------------- + +Use the `@registeredsymbol{}' command to generate the registered +symbol, `(R)'. Where possible, this is an `R' inside a circle; in +Info, this is `(R)'. + + +File: texinfo.info, Node: pounds, Next: minus, Prev: TeX and copyright, Up: Insertions + +14.6 `@pounds'{} (#): Pounds Sterling +===================================== + +Use the `@pounds{}' command to generate `#'. In a printed manual, this +is the symbol for the currency pounds sterling. In Info, it is a `#'. +Other currency symbols are unfortunately not available. + + +File: texinfo.info, Node: minus, Next: math, Prev: pounds, Up: Insertions + +14.7 `@minus'{} (-): Inserting a Minus Sign +=========================================== + +Use the `@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: + + `-' is a minus sign generated with `@minus{}', + + `-' is a hyphen generated with the character `-', + + `--' is an em-dash for text. + +In the fixed-width font used by Info, `@minus{}' is the same as a +hyphen. + + You should not use `@minus{}' inside `@code' or `@example' because +the width distinction is not made in the fixed-width font they use. + + When you use `@minus' to specify the mark beginning each entry in an +itemized list, you do not need to type the braces (*note `@itemize': +itemize.). + + +File: texinfo.info, Node: math, Next: Glyphs, Prev: minus, Up: Insertions + +14.8 `@math': Inserting Mathematical Expressions +================================================ + +You can write a short mathematical expression with the `@math' command. +Write the mathematical expression between braces, like this: + + @math{(a + b)(a + b) = a^2 + 2ab + b^2} + +This produces the following in Info and HTML: + + (a + b)(a + b) = a^2 + 2ab + b^2 + + Thus, the `@math' command has no effect on the Info and HTML output; +`makeinfo' just reproduces the input, it does not try to interpret the +mathematics in any way. + + `@math' implies `@tex'. This not only makes it possible to write +superscripts and subscripts (as in the above example), but also allows +you to use any of the plain TeX math control sequences. It's +conventional to use `\' instead of `@' for these commands. As in: + @math{\sin 2\pi \equiv \cos 3\pi} + +which looks like the input in Info and HTML: + \sin 2\pi \equiv \cos 3\pi + + Since `\' is an escape character inside `@math', you can use `@\' to +get a literal backslash (`\\' will work in TeX, but you'll get the +literal `\\' in Info). `@\' is not defined outside of `@math', since a +`\' ordinarily produces a literal `\'. + + For displayed equations, you must at present use TeX directly (*note +Raw Formatter Commands::). + + +File: texinfo.info, Node: Glyphs, Prev: math, Up: Insertions + +14.9 Glyphs for Examples +======================== + +In Texinfo, code is often illustrated in examples that are delimited by +`@example' and `@end example', or by `@lisp' and `@end lisp'. In such +examples, you can indicate the results of evaluation or an expansion +using `=>' or `==>'. 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. + +* 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. + + +File: texinfo.info, Node: Glyphs Summary, Next: result, Up: Glyphs + +14.9.1 Glyphs Summary +--------------------- + +Here are the different glyph commands: + +=> + `@result{}' points to the result of an expression. + +==> + `@expansion{}' shows the results of a macro expansion. + +-| + `@print{}' indicates printed output. + +error--> + `@error{}' indicates that the following text is an error message. + +== + `@equiv{}' indicates the exact equivalence of two forms. + +-!- + `@point{}' shows the location of point. + +* Menu: + +* result:: +* expansion:: +* Print Glyph:: +* Error Glyph:: +* Equivalence:: +* Point Glyph:: + + +File: texinfo.info, Node: result, Next: expansion, Prev: Glyphs Summary, Up: Glyphs + +14.9.2 `@result{}' (=>): Indicating Evaluation +---------------------------------------------- + +Use the `@result{}' command to indicate the result of evaluating an +expression. + + The `@result{}' command is displayed as `=>' in Info and HTML and as +a true double stemmed arrow in the printed output. + + Thus, the following, + + (cdr '(1 2 3)) + => (2 3) + +may be read as "`(cdr '(1 2 3))' evaluates to `(2 3)'". + + +File: texinfo.info, Node: expansion, Next: Print Glyph, Prev: result, Up: Glyphs + +14.9.3 `@expansion{}' (==>): Indicating an Expansion +---------------------------------------------------- + +When an expression is a macro call, it expands into a new expression. +You can indicate the result of the expansion with the `@expansion{}' +command. + + The `@expansion{}' command is displayed as `==>' in Info and HTML, +and as a long arrow with a flat base in the printed output. + + For example, the following + + @lisp + (third '(a b c)) + @expansion{} (car (cdr (cdr '(a b c)))) + @result{} c + @end lisp + +produces + + (third '(a b c)) + ==> (car (cdr (cdr '(a b c)))) + => c + +which may be read as: + + `(third '(a b c))' expands to `(car (cdr (cdr '(a b c))))'; the + result of evaluating the expression is `c'. + +Often, as in this case, an example looks better if the `@expansion{}' +and `@result{}' commands are indented. + + +File: texinfo.info, Node: Print Glyph, Next: Error Glyph, Prev: expansion, Up: Glyphs + +14.9.4 `@print{}' (-|): Indicating Printed Output +------------------------------------------------- + +Sometimes an expression will print output during its execution. You +can indicate the printed output with the `@print{}' command. + + The `@print{}' command is displayed as `-|' in Info and HTML and +(similarly) as a horizontal dash butting against a vertical bar in the +printed output. + + In the following example, the printed text is indicated with `-|', +and the value of the expression follows on the last line. + + (progn (print 'foo) (print 'bar)) + -| foo + -| bar + => bar + +In a Texinfo source file, this example is written as follows: + + @lisp + (progn (print 'foo) (print 'bar)) + @print{} foo + @print{} bar + @result{} bar + @end lisp + + +File: texinfo.info, Node: Error Glyph, Next: Equivalence, Prev: Print Glyph, Up: Glyphs + +14.9.5 `@error{}' (error-->): Indicating an Error Message +--------------------------------------------------------- + +A piece of code may cause an error when you evaluate it. You can +designate the error message with the `@error{}' command. + + The `@error{}' command is displayed as `error-->' in Info and HTML +and as the word `error' in a box in the printed output. + + Thus, + + @lisp + (+ 23 'x) + @error{} Wrong type argument: integer-or-marker-p, x + @end lisp + +produces + + (+ 23 'x) + error--> Wrong type argument: integer-or-marker-p, x + +This indicates that the following error message is printed when you +evaluate the expression: + + Wrong type argument: integer-or-marker-p, x + + `error-->' itself is not part of the error message. + + +File: texinfo.info, Node: Equivalence, Next: Point Glyph, Prev: Error Glyph, Up: Glyphs + +14.9.6 `@equiv{}' (==): Indicating Equivalence +---------------------------------------------- + +Sometimes two expressions produce identical results. You can indicate +the exact equivalence of two forms with the `@equiv{}' command. + + The `@equiv{}' command is displayed as `==' in Info and HTML and as a +standard mathematical equivalence sign (three parallel horizontal +lines) in the printed output. + + Thus, + + @lisp + (make-sparse-keymap) @equiv{} (list 'keymap) + @end lisp + +produces + + (make-sparse-keymap) == (list 'keymap) + +This indicates that evaluating `(make-sparse-keymap)' produces +identical results to evaluating `(list 'keymap)'. + + +File: texinfo.info, Node: Point Glyph, Prev: Equivalence, Up: Glyphs + +14.9.7 `@point{}' (-!-): Indicating Point in a Buffer +----------------------------------------------------- + +Sometimes you need to show an example of text in an Emacs buffer. In +such examples, the convention is to include the entire contents of the +buffer in question between two lines of dashes containing the buffer +name. + + You can use the `@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 _between_ two +characters where point is located.) + + The `@point{}' command is displayed as `-!-' in Info and HTML and as +a small five pointed star in the printed output. + + The following example shows the contents of buffer `foo' before and +after evaluating a Lisp command to insert the word `changed'. + + ---------- Buffer: foo ---------- + This is the -!-contents of foo. + ---------- Buffer: foo ---------- + + (insert "changed ") + => nil + ---------- Buffer: foo ---------- + This is the changed -!-contents of foo. + ---------- Buffer: foo ---------- + + In a Texinfo source file, the example is written like this: + + @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 + + +File: texinfo.info, Node: Breaks, Next: Definition Commands, Prev: Insertions, Up: Top + +15 Forcing and Preventing 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. + + 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. +* 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. + + +File: texinfo.info, Node: Break Commands, Next: Line Breaks, Up: Breaks + +15.1 Break Commands +=================== + +The break commands create or allow line and paragraph breaks: + +`@*' + Force a line break. + +`@sp N' + Skip N blank lines. + +`@-' + Insert a discretionary hyphen. + +`@hyphenation{HY-PHEN-A-TED WORDS}' + Define hyphen points in HY-PHEN-A-TED WORDS. + + These commands hold text together on a single line: + +`@w{TEXT}' + Prevent TEXT from being split and hyphenated across two lines. + +`@tie{}' + Insert a normal interword space at which a line break may not + occur. + + The pagination commands apply only to printed output, since Info +files do not have pages. + +`@page' + Start a new page in the printed manual. + +`@group' + Hold text together that must appear on one printed page. + +`@need MILS' + Start a new printed page if not enough space on this one. + + +File: texinfo.info, Node: Line Breaks, Next: - and hyphenation, Prev: Break Commands, Up: Breaks + +15.2 `@*' and `@/': Generate and Allow Line Breaks +================================================== + +The `@*' command forces a line break in both the printed manual and in +Info. The `@/' command allows a line break (printed manual only). + + Here is an example with `@*': + + This line @* is broken @*in two places. + +produces + + This line + is broken + in two places. + + The `@/' command can be useful within a url (*note `@uref': uref.), +which tend to be long and are otherwise unbreakable. For example: + + The official Texinfo home page is on the GNU web site: + @uref{http://www.gnu.org/@/software/@/gnu/@/texinfo}. + +produces + + The official Texinfo home page is on the GNU web site: + `http://www.gnu.org/software/gnu/texinfo'. + +Without the `@/' commands, TeX would have nowhere to break the line. +`@/' has no effect in the online output. + + +File: texinfo.info, Node: - and hyphenation, Next: w, Prev: Line Breaks, Up: Breaks + +15.3 `@-' and `@hyphenation': Helping TeX Hyphenate +=================================================== + +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: + +`@-' + 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 (*note + Overfull hboxes::). TeX will not insert any hyphenation points + itself into a word containing `@-'. + +`@hyphenation{HY-PHEN-A-TED WORDS}' + Tell TeX how to hyphenate HY-PHEN-A-TED WORDS. As shown, you put + a `-' at each hyphenation point. For example: + @hyphenation{man-u-script man-u-scripts} + TeX only uses the specified hyphenation points when the words + match exactly, so give all necessary variants. + + Info output is not hyphenated, so these commands have no effect there. + + +File: texinfo.info, Node: w, Next: tie, Prev: - and hyphenation, Up: Breaks + +15.4 `@w'{TEXT}: Prevent Line Breaks +==================================== + +`@w{TEXT}' outputs TEXT and prohibits line breaks within TEXT, for both +TeX and `makeinfo'. + + Thus, you can use `@w' to produce a non-breakable space, fixed at the +width of a normal interword space: + + @w{ } @w{ } @w{ } indentation. + +produces: + + indentation. + + The space from `@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 indenting manual. However, usually you want a normal +interword space that does stretch and shrink (in the printed output); +see the `@tie' command in the next section. + + You can also use the `@w' command to prevent TeX from automatically +hyphenating a long name or phrase that happens to fall near the end of +a line. `makeinfo' does not ever hyphenate words. + + You can also use `@w' to avoid unwanted keyword expansion in source +control systems. For example, to literally write $Id$ in your +document, use `@w{$}Id$'. + + +File: texinfo.info, Node: tie, Next: sp, Prev: w, Up: Breaks + +15.5 `@tie{}': Inserting an Unbreakable Space +============================================= + +The `@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: + + @TeX{} was written by Donald E.@tie{}Knuth. + +produces: + + TeX was written by Donald E. Knuth. + + There are two important differences between `@tie{}' and `@w{ }': + + * The space produced by `@tie{}' will stretch and shrink slightly + along with the normal interword spaces in the paragraph; the space + produced by `@w{ }' will not vary. + + * `@tie{}' allows hyphenation of the surrounding words, while + `@w{ }' inhibits hyphenation of those words (for TeXnical reasons, + namely that it produces an `\hbox'). + + + +File: texinfo.info, Node: sp, Next: page, Prev: tie, Up: Breaks + +15.6 `@sp' N: Insert Blank Lines +================================ + +A line beginning with and containing only `@sp N' generates N blank +lines of space in both the printed manual and the Info file. `@sp' +also forces a paragraph break. For example, + + @sp 2 + +generates two blank lines. + + The `@sp' command is most often used in the title page. + + +File: texinfo.info, Node: page, Next: group, Prev: sp, Up: Breaks + +15.7 `@page': Start a New Page +============================== + +A line containing only `@page' starts a new page in a printed manual. +The command has no effect on Info files since they are not paginated. +An `@page' command is often used in the `@titlepage' section of a +Texinfo file to start the copyright page. + + +File: texinfo.info, Node: group, Next: need, Prev: page, Up: Breaks + +15.8 `@group': Prevent Page Breaks +================================== + +The `@group' command (on a line by itself) is used inside an `@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 `@end group'. These two lines +produce no output of their own, and in the Info file output they have +no effect at all. + + Although `@group' would make sense conceptually in a wide variety of +contexts, its current implementation works reliably only within +`@example' and variants, and within `@display', `@format', `@flushleft' +and `@flushright'. *Note Quotations and Examples::. (What all these +commands have in common is that each line of input produces a line of +output.) In other contexts, `@group' can cause anomalous vertical +spacing. + + This formatting requirement means that you should write: + + @example + @group + ... + @end group + @end example + +with the `@group' and `@end group' commands inside the `@example' and +`@end example' commands. + + The `@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 `@group' and `@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 `@end group' if you +get incomprehensible error messages in TeX. + + +File: texinfo.info, Node: need, Prev: group, Up: Breaks + +15.9 `@need MILS': Prevent Page Breaks +====================================== + +A line containing only `@need N' starts a new page in a printed manual +if fewer than N mils (thousandths of an inch) remain on the current +page. Do not use braces around the argument N. The `@need' command +has no effect on Info files since they are not paginated. + + This paragraph is preceded by an `@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: + + @need 800 + This paragraph is preceded by ... + + The `@need' command is useful for preventing orphans (single lines at +the bottoms of printed pages). + + +File: texinfo.info, Node: Definition Commands, Next: Conditionals, Prev: Breaks, Up: Top + +16 Definition Commands +********************** + +The `@deffn' command and the other "definition commands" enable you to +describe functions, variables, macros, commands, user options, special +forms and other such artifacts in a uniform format. + + In the Info file, a definition causes the entity +category--`Function', `Variable', or whatever--to appear at the +beginning of the first line of the definition, followed by the entity's +name and arguments. In the printed manual, the command causes TeX to +print the entity's name and its arguments on the left margin and print +the category next to the right margin. In both output formats, the +body of the definition is indented. Also, the name of the entity is +entered into the appropriate index: `@deffn' enters the name into the +index of functions, `@defvr' enters it into the index of variables, and +so on (*note 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 `@table' +rather than the definition commands. + +* Menu: + +* Def Cmd Template:: Writing descriptions using definition commands. +* Def Cmd Continuation Lines:: Continuing the heading over source lines. +* Optional Arguments:: Handling optional and repeated arguments. +* 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. + + +File: texinfo.info, Node: Def Cmd Template, Next: Def Cmd Continuation Lines, Up: Definition Commands + +16.1 The Template for a Definition +================================== + +The `@deffn' command is used for definitions of entities that resemble +functions. To write a definition using the `@deffn' command, write the +`@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 `@end deffn' command written on a line of its +own. + + The other definition commands follow the same format: a line with the +`@def...' command and whatever arguments are appropriate for that +command; the body of the definition; and a corresponding `@end' line. + + The template for a definition looks like this: + + @deffn CATEGORY NAME ARGUMENTS... + BODY-OF-DEFINITION + @end deffn + +For example, + + @deffn Command forward-word count + This command moves point forward @var{count} words + (or backward if @var{count} is negative). ... + @end deffn + +produces + + -- Command: forward-word count + This function moves point forward COUNT words (or backward if + COUNT is negative). ... + + 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: + + @deffn {Interactive Command} isearch-forward + ... + @end deffn + +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 +_except_ the last one are more than one word, you need to enclose them +in braces. + + Some of the definition commands are more general than others. The +`@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 (`@defun', `@defmac', and +`@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 `@defvr' command is +accompanied by several specialized variations for describing particular +kinds of variables. + + *Note Sample Function Definition::, for a detailed example of a +function definition, including the use of `@example' inside the +definition. + + Unfortunately, due to implementation difficulties, macros are not +expanded in `@deffn' and all the other definition commands. + + +File: texinfo.info, Node: Def Cmd Continuation Lines, Next: Optional Arguments, Prev: Def Cmd Template, Up: Definition Commands + +16.2 Definition Command Continuation Lines +========================================== + +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 `@' at the end of each line +to be continued. Here's an example: + + @defun fn-name @ + arg1 arg2 arg3 + This is the basic continued defun. + @end defun + +produces: + + -- Function: fn-name arg1 arg2 arg3 + This is the basic continued defun. + +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 `@' at +the end of each line to be continued. + + The `@' character does not have to be the last character on the +physical line: whitespace is allowed (and ignored) afterwards. + + In general, any number of spaces or tabs around the `@' continuation +character, both on the line with the `@' 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: + + @deffn {Category @ + Name} ... + +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 `@' outside braces. + + `@' does not (currently) function as a continuation character in +_any_ other context. Ordinarily, `@' followed by a whitespace +character (space, tab, newline) produces a normal interword space +(*note Multiple Spaces::). + + +File: texinfo.info, Node: Optional Arguments, Next: deffnx, Prev: Def Cmd Continuation Lines, Up: Definition Commands + +16.3 Optional and Repeated Arguments +==================================== + +Some entities take optional or repeated arguments, which may be +specified by a distinctive glyph that uses square brackets and +ellipses. For example, a special form often breaks its argument list +into separate arguments in more complicated ways than a straightforward +function. + + An argument enclosed within square brackets is optional. Thus, +[OPTIONAL-ARG] means that OPTIONAL-ARG is optional. An argument +followed by an ellipsis is optional and may be repeated more than once. +Thus, REPEATED-ARGS`...' 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 `@defspec' line of an example of an imaginary special +form: + + -- Special Form: foobar (VAR [FROM TO [INC]]) BODY... + +In this example, the arguments FROM and TO are optional, but must both +be present or both absent. If they are present, INC may optionally be +specified as well. These arguments are grouped with the argument VAR +into a list, to distinguish them from BODY, which includes all +remaining elements of the form. + + In a Texinfo source file, this `@defspec' line is written like this +(except it would not be split over two lines, as it is in this example). + + @defspec foobar (@var{var} [@var{from} @var{to} + [@var{inc}]]) @var{body}@dots{} + +The function is listed in the Command and Variable Index under `foobar'. + + +File: texinfo.info, Node: deffnx, Next: Def Cmds in Detail, Prev: Optional Arguments, Up: Definition Commands + +16.4 Two or More `First' Lines +============================== + +To create two or more `first' or header lines for a definition, follow +the first `@deffn' line by a line beginning with `@deffnx'. The +`@deffnx' command works exactly like `@deffn' except that it does not +generate extra vertical white space between it and the preceding line. + + For example, + + @deffn {Interactive Command} isearch-forward + @deffnx {Interactive Command} isearch-backward + These two search commands are similar except ... + @end deffn + +produces + + -- Interactive Command: isearch-forward + -- Interactive Command: isearch-backward + These two search commands are similar except ... + + Each definition command has an `x' form: `@defunx', `@defvrx', +`@deftypefunx', etc. + + The `x' forms work similarly to `@itemx' (*note itemx::). + + +File: texinfo.info, Node: Def Cmds in Detail, Next: Def Cmd Conventions, Prev: deffnx, Up: Definition Commands + +16.5 The Definition Commands +============================ + +Texinfo provides more than a dozen definition commands, all of which +are described in this section. + + The definition commands automatically enter the name of the entity in +the appropriate index: for example, `@deffn', `@defun', and `@defmac' +enter function names in the index of functions; `@defvr' and `@defvar' +enter variable names in the index of variables. + + Although the examples that follow mostly illustrate Lisp, the commands +can be used for other programming languages. + +* Menu: + +* Functions Commands:: Commands for functions and similar entities. +* Variables Commands:: Commands for variables and similar entities. +* Typed Functions:: Commands for functions in typed languages. +* Typed Variables:: Commands for variables in typed languages. +* Data Types:: The definition command for data types. +* Abstract Objects:: Commands for object-oriented programming. + + +File: texinfo.info, Node: Functions Commands, Next: Variables Commands, Up: Def Cmds in Detail + +16.5.1 Functions and Similar Entities +------------------------------------- + +This section describes the commands for describing functions and similar +entities: + +`@deffn CATEGORY NAME ARGUMENTS...' + The `@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 `@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 + `@end deffn' on a line of its own. + + For example, here is a definition: + + @deffn Command forward-char nchars + Move point forward @var{nchars} characters. + @end deffn + + This shows a rather terse definition for a "command" named + `forward-char' with one argument, NCHARS. + + `@deffn' and prints argument names such as 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 `@var' to refer to the value of the argument. In + the example above, we used `@var{nchars}' in this way. + + In the unusual case when an argument name contains `--', or + another character sequence which is treated specially (*note + Conventions::), use `@var' around the argument. This causes the + name to be printed in slanted typewriter, instead of the regular + slanted font, exactly as input. + + The template for `@deffn' is: + + @deffn CATEGORY NAME ARGUMENTS... + BODY-OF-DEFINITION + @end deffn + +`@defun NAME ARGUMENTS...' + The `@defun' command is the definition command for functions. + `@defun' is equivalent to `@deffn Function ...'. Terminate the + definition with `@end defun' on a line of its own. Thus, the + template is: + + @defun FUNCTION-NAME ARGUMENTS... + BODY-OF-DEFINITION + @end defun + +`@defmac NAME ARGUMENTS...' + The `@defmac' command is the definition command for macros. + `@defmac' is equivalent to `@deffn Macro ...' and works like + `@defun'. + +`@defspec NAME ARGUMENTS...' + The `@defspec' command is the definition command for special + forms. (In Lisp, a special form is an entity much like a function, + *note Special Forms: (elisp)Special Forms.) `@defspec' is + equivalent to `@deffn {Special Form} ...' and works like `@defun'. + + All these commands create entries in the index of functions. + + +File: texinfo.info, Node: Variables Commands, Next: Typed Functions, Prev: Functions Commands, Up: Def Cmds in Detail + +16.5.2 Variables and Similar Entities +------------------------------------- + +Here are the commands for defining variables and similar entities: + +`@defvr CATEGORY NAME' + The `@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 `@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, + + @defvr {User Option} fill-column + This buffer-local variable specifies + the maximum width of filled lines. + ... + @end defvr + + Terminate the definition with `@end defvr' on a line of its own. + + The template is: + + @defvr CATEGORY NAME + BODY-OF-DEFINITION + @end defvr + + `@defvr' creates an entry in the index of variables for NAME. + +`@defvar NAME' + The `@defvar' command is the definition command for variables. + `@defvar' is equivalent to `@defvr Variable ...'. + + For example: + + @defvar kill-ring + ... + @end defvar + + The template is: + + @defvar NAME + BODY-OF-DEFINITION + @end defvar + + `@defvar' creates an entry in the index of variables for NAME. + +`@defopt NAME' + The `@defopt' command is the definition command for "user + options", i.e., variables intended for users to change according to + taste; Emacs has many such (*note Variables: (emacs)Variables.). + `@defopt' is equivalent to `@defvr {User Option} ...' and works + like `@defvar'. It creates an entry in the index of variables. + + +File: texinfo.info, Node: Typed Functions, Next: Typed Variables, Prev: Variables Commands, Up: Def Cmds in Detail + +16.5.3 Functions in Typed Languages +----------------------------------- + +The `@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++. + +`@deftypefn CATEGORY DATA-TYPE NAME ARGUMENTS...' + The `@deftypefn' command is the general definition command for + functions and similar entities that may take arguments and that are + typed. The `@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. + + For example, + + @deftypefn {Library Function} int foobar + (int @var{foo}, float @var{bar}) + ... + @end deftypefn + + (where the text before the "...", shown above as two lines, would + actually be a single line in a real Texinfo file) produces the + following in Info: + + -- Library Function: int foobar (int FOO, float BAR) + ... + + This means that `foobar' is a "library function" that returns an + `int', and its arguments are FOO (an `int') and BAR (a `float'). + + Since in typed languages, the actual names of the arguments are + typically scattered among data type names and keywords, Texinfo + cannot find them without help. You can either (a) write everything + as straight text, and it will be printed in slanted type; (b) use + `@var' for the variable names, which will uppercase the variable + names in Info and use the slanted typewriter font in printed + output; (c) use `@var' for the variable names and `@code' for the + type names and keywords, which will be dutifully obeyed. + + The template for `@deftypefn' is: + + @deftypefn CATEGORY DATA-TYPE NAME ARGUMENTS ... + BODY-OF-DESCRIPTION + @end deftypefn + + Note that if the CATEGORY or DATA TYPE is more than one word then + it must be enclosed in braces to make it a single argument. + + If you are describing a procedure in a language that has packages, + such as Ada, you might consider using `@deftypefn' in a manner + somewhat contrary to the convention described in the preceding + paragraphs. For example: + + @deftypefn stacks private push @ + (@var{s}:in out stack; @ + @var{n}:in integer) + ... + @end deftypefn + + (The `@deftypefn' arguments are shown using continuations (*note + 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 `stacks' rather than classified as a `procedure' and its + data type is described as `private'. (The name of the procedure + is `push', and its arguments are S and N.) + + `@deftypefn' creates an entry in the index of functions for NAME. + +`@deftypefun DATA-TYPE NAME ARGUMENTS...' + The `@deftypefun' command is the specialized definition command + for functions in typed languages. The command is equivalent to + `@deftypefn Function ...'. The template is: + + @deftypefun TYPE NAME ARGUMENTS... + BODY-OF-DESCRIPTION + @end deftypefun + + `@deftypefun' creates an entry in the index of functions for NAME. + + + +File: texinfo.info, Node: Typed Variables, Next: Data Types, Prev: Typed Functions, Up: Def Cmds in Detail + +16.5.4 Variables in Typed Languages +----------------------------------- + +Variables in typed languages are handled in a manner similar to +functions in typed languages. *Note Typed Functions::. The general +definition command `@deftypevr' corresponds to `@deftypefn' and the +specialized definition command `@deftypevar' corresponds to +`@deftypefun'. + +`@deftypevr CATEGORY DATA-TYPE NAME' + The `@deftypevr' command is the general definition command for + something like a variable in a typed language--an entity that + records a value. You must choose a term to describe the category + of the entity being defined; for example, "Variable" could be used + if the entity is a variable. + + The `@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. + + For example: + + @deftypevr {Global Flag} int enable + ... + @end deftypevr + + produces the following in Info: + + -- Global Flag: int enable + ... + + The template is: + + @deftypevr CATEGORY DATA-TYPE NAME + BODY-OF-DESCRIPTION + @end deftypevr + +`@deftypevar DATA-TYPE NAME' + The `@deftypevar' command is the specialized definition command + for variables in typed languages. `@deftypevar' is equivalent to + `@deftypevr Variable ...'. The template is: + + @deftypevar DATA-TYPE NAME + BODY-OF-DESCRIPTION + @end deftypevar + + These commands create entries in the index of variables. + + +File: texinfo.info, Node: Data Types, Next: Abstract Objects, Prev: Typed Variables, Up: Def Cmds in Detail + +16.5.5 Data Types +----------------- + +Here is the command for data types: + +`@deftp CATEGORY NAME ATTRIBUTES...' + The `@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 `int' or `float'), and then by names of + attributes of objects of that type. Thus, you could use this + command for describing `int' or `float', in which case you could + use `data type' as the category. (A data type is a category of + certain objects for purposes of deciding which operations can be + performed on them.) + + In Lisp, for example, "pair" names a particular data type, and an + object of that type has two slots called the CAR and the CDR. + Here is how you would write the first line of a definition of + `pair'. + + @deftp {Data type} pair car cdr + ... + @end deftp + + The template is: + + @deftp CATEGORY NAME-OF-TYPE ATTRIBUTES... + BODY-OF-DEFINITION + @end deftp + + `@deftp' creates an entry in the index of data types. + + +File: texinfo.info, Node: Abstract Objects, Prev: Data Types, Up: Def Cmds in Detail + +16.5.6 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. + + +File: texinfo.info, Node: Object-Oriented Variables, Next: Object-Oriented Methods, Up: Abstract Objects + +16.5.6.1 Object-Oriented Variables +.................................. + +These commands allow you to define different sorts of variables in +object-oriented programming languages. + +`@defcv CATEGORY CLASS NAME' + The `@defcv' command is the general definition command for + variables associated with classes in object-oriented programming. + The `@defcv' command is followed by three arguments: the category + of thing being defined, the class to which it belongs, and its + name. For instance: + + @defcv {Class Option} Window border-pattern + ... + @end defcv + + produces: + + -- Class Option of Window: border-pattern + ... + + `@defcv' creates an entry in the index of variables. + +`@deftypecv CATEGORY CLASS DATA-TYPE NAME' + The `@deftypecv' command is the definition command for typed class + variables in object-oriented programming. It is analogous to + `@defcv' with the addition of the 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'. + For instance: + + @deftypecv {Class Option} Window @code{int} border-pattern + ... + @end deftypecv + + produces: + + -- Class Option of Window: `int' border-pattern + ... + + `@deftypecv' creates an entry in the index of variables. + +`@defivar CLASS NAME' + The `@defivar' command is the definition command for instance + variables in object-oriented programming. `@defivar' is + equivalent to `@defcv {Instance Variable} ...'. For instance: + + @defivar Window border-pattern + ... + @end defivar + + produces: + + -- Instance Variable of Window: border-pattern + ... + + `@defivar' creates an entry in the index of variables. + +`@deftypeivar CLASS DATA-TYPE NAME' + The `@deftypeivar' command is the definition command for typed + instance variables in object-oriented programming. It is + analogous to `@defivar' with the addition of the 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'. For instance: + + @deftypeivar Window @code{int} border-pattern + ... + @end deftypeivar + + produces: + + -- Instance Variable of Window: `int' border-pattern + ... + + `@deftypeivar' creates an entry in the index of variables. + + + +File: texinfo.info, Node: Object-Oriented Methods, Prev: Object-Oriented Variables, Up: Abstract Objects + +16.5.6.2 Object-Oriented Methods +................................ + +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. + +`@defop CATEGORY CLASS NAME ARGUMENTS...' + The `@defop' command is the general definition command for these + method-like entities. + + For example, some systems have constructs called "wrappers" that + are associated with classes as methods are, but that act more like + macros than like functions. You could use `@defop Wrapper' to + describe one of these. + + Sometimes it is useful to distinguish methods and "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 `expose'; we would say that this window system + defines an `expose' operation on windows in general. Typically, + the operation has a name and also specifies the pattern of + arguments; all methods that implement the operation must accept + the same arguments, since applications that use the operation do + so without knowing which method will implement it. + + Often it makes more sense to document operations than methods. For + example, window application developers need to know about the + `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: + + @defop Operation windows expose + + The `@defop' command is written at the beginning of a line and is + followed on the same line by the overall name of the category of + operation, the name of the class of the operation, the name of the + operation, and its arguments, if any. + + The template is: + @defop CATEGORY CLASS NAME ARGUMENTS... + BODY-OF-DEFINITION + @end defop + + `@defop' creates an entry, such as ``expose' on `windows'', in the + index of functions. + +`@deftypeop CATEGORY CLASS DATA-TYPE NAME ARGUMENTS...' + The `@deftypeop' command is the definition command for typed + operations in object-oriented programming. It is similar to + `@defop' with the addition of the DATA-TYPE parameter to specify + the return type of the method. `@deftypeop' creates an entry in + the index of functions. + +`@defmethod CLASS NAME ARGUMENTS...' + The `@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. + + `@defmethod' is equivalent to `@defop Method ...'. 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. + + For example: + @defmethod `bar-class' bar-method argument + ... + @end defmethod + + illustrates the definition for a method called `bar-method' of the + class `bar-class'. The method takes an argument. + + `@defmethod' creates an entry in the index of functions. + +`@deftypemethod CLASS DATA-TYPE NAME ARGUMENTS...' + The `@deftypemethod' command is the definition command for methods + in object-oriented typed languages, such as C++ and Java. It is + similar to the `@defmethod' command with the addition of the + DATA-TYPE parameter to specify the return type of the method. + `@deftypemethod' creates an entry in the index of functions. + + + +File: texinfo.info, Node: Def Cmd Conventions, Next: Sample Function Definition, Prev: Def Cmds in Detail, Up: Definition Commands + +16.6 Conventions for Writing Definitions +======================================== + +When you write a definition using `@deffn', `@defun', or one of the +other definition commands, please take care to use arguments that +indicate the meaning, as with the COUNT argument to the `forward-word' +function. Also, if the name of an argument contains the name of a +type, such as INTEGER, take care that the argument actually is of that +type. + + +File: texinfo.info, Node: Sample Function Definition, Prev: Def Cmd Conventions, Up: Definition Commands + +16.7 A Sample Function Definition +================================= + +A function definition uses the `@defun' and `@end defun' commands. The +name of the function follows immediately after the `@defun' command and +it is followed, on the same line, by the parameter list. + + Here is a definition from *Note Calling Functions: (elisp)Calling +Functions. + + -- Function: apply function &rest arguments + `apply' calls FUNCTION with ARGUMENTS, just like `funcall' + but with one difference: the last of ARGUMENTS is a list of + arguments to give to FUNCTION, rather than a single argument. + We also say that this list is "appended" to the other + arguments. + + `apply' returns the result of calling FUNCTION. As with + `funcall', FUNCTION must either be a Lisp function or a + primitive function; special forms and macros do not make + sense in `apply'. + + (setq f 'list) + => list + (apply f 'x 'y 'z) + error--> Wrong type argument: listp, z + (apply '+ 1 2 '(3 4)) + => 10 + (apply '+ '(1 2 3 4)) + => 10 + + (apply 'append '((a b c) nil (x y z) nil)) + => (a b c x y z) + + An interesting example of using `apply' is found in the + description of `mapcar'. + + In the Texinfo source file, this example looks like this: + + @defun apply function &rest arguments + @code{apply} calls @var{function} with + @var{arguments}, just like @code{funcall} but with one + difference: the last of @var{arguments} is a list of + arguments to give to @var{function}, rather than a single + argument. We also say that this list is @dfn{appended} + to the other arguments. + + @code{apply} returns the result of calling + @var{function}. As with @code{funcall}, + @var{function} must either be a Lisp function or a + primitive function; special forms and macros do not make + sense in @code{apply}. + + @example + (setq f 'list) + @result{} list + (apply f 'x 'y 'z) + @error{} Wrong type argument: listp, z + (apply '+ 1 2 '(3 4)) + @result{} 10 + (apply '+ '(1 2 3 4)) + @result{} 10 + + (apply 'append '((a b c) nil (x y z) nil)) + @result{} (a b c x y z) + @end example + + An interesting example of using @code{apply} is found + in the description of @code{mapcar}. + @end defun + +In this manual, this function is listed in the Command and Variable +Index under `apply'. + + Ordinary variables and user options are described using a format like +that for functions except that variables do not take arguments. + + +File: texinfo.info, Node: Conditionals, Next: Internationalization, Prev: Definition Commands, Up: Top + +17 Conditionally Visible Text +***************************** + +The "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. + + * Commands specific to an output format (Info, TeX, HTML, ...). + + * Commands specific to any output format _other_ than a given one + (not Info, not TeX, ...). + + * `Raw' formatter text for any output format, passed straight + through with no interpretation of @-commands. + + * Format-independent variable substitutions, and testing if a + variable is set or clear. + + +* 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. + + +File: texinfo.info, Node: Conditional Commands, Next: Conditional Not Commands, Up: Conditionals + +17.1 Conditional Commands +========================= + +Texinfo has an `@ifFORMAT' environment for each output format, to allow +conditional inclusion of text for a particular output format. + + `@ifinfo' begins segments of text that should be ignored by TeX when +it typesets the printed manual, and by `makeinfo' when not producing +Info output. The segment of text appears only in the Info file and, +for historical compatibility, the plain text output. + + The environments for the other formats are analogous: + +`@ifdocbook ... @end ifdocbook' + Text to appear only in the Docbook output. + +`@ifhtml ... @end ifhtml' + Text to appear only in the HTML output. + +`@ifplaintext ... @end ifplaintext' + Text to appear only in the plain text output. + +`@iftex ... @end iftex' + Text to appear only in the printed manual. + +`@ifxml ... @end ifxml' + Text to appear only in the XML output. + + The `@if...' and `@end if...' commands must appear on lines by +themselves in your source file. + + Here is an example showing all these conditionals: + + @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 + +The preceding example produces the following line: + + However, this text will appear only in Info and plain text. + +Notice that you only see one of the input lines, depending on which +version of the manual you are reading. + + +File: texinfo.info, Node: Conditional Not Commands, Next: Raw Formatter Commands, Prev: Conditional Commands, Up: Conditionals + +17.2 Conditional Not Commands +============================= + +You can specify text to be included in any output format _other_ than a +given one with the `@ifnot...' environments: + + @ifnotdocbook ... @end ifnotdocbook + @ifnothtml ... @end ifnothtml + @ifnotinfo ... @end ifnotinfo + @ifnotplaintext ... @end ifnotplaintext + @ifnottex ... @end ifnottex + @ifnotxml ... @end ifnotxml + +The `@ifnot...' command and the `@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 +_ignored_. Otherwise, it is included. + + There is one exception (for historical compatibility): `@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 +`@ifnotplaintext', like this: + + @ifinfo + @ifnotplaintext + This will be in Info, but not plain text. + @end ifnotplaintext + @end ifinfo + + The regions delimited by these commands are ordinary Texinfo source as +with `@iftex', not raw formatter source as with `@tex' (*note Raw +Formatter Commands::). + + +File: texinfo.info, Node: Raw Formatter Commands, Next: set clear value, Prev: Conditional Not Commands, Up: Conditionals + +17.3 Raw Formatter Commands +=========================== + +Inside a region delineated by `@iftex' and `@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 `\' used by TeX with an `@'. For example, in the +`@titlepage' section of a Texinfo file, you can use the TeX command +`@vskip' to format the copyright page. (The `@titlepage' command +causes Info to ignore the region automatically, as it does with the +`@iftex' command.) + + However, most features of plain TeX will not work within `@iftex', as +they are overridden by Texinfo features. The purpose of `@iftex' is to +provide conditional processing for the Texinfo source, not provide +access to underlying formatting features. + + You can enter plain TeX completely, and use `\' in the TeX commands, +by delineating a region with the `@tex' and `@end tex' commands. All +plain TeX commands and category codes are restored within an `@tex' +region. The sole exception is that the `@' character still introduces +a command, so that `@end tex' can be recognized properly. As with +`@iftex', Texinfo processors will ignore such a region unless TeX +output is being produced. + + In complex cases, you may wish to define new TeX macros within +`@tex'. You must use `\gdef' to do this, not `\def', because `@tex' +regions are processed in a TeX group. + + As an example, here is a mathematical expression written in plain TeX: + + @tex + $$ \chi^2 = \sum_{i=1}^N + \left (y_i - (a + b x_i) + \over \sigma_i\right)^2 $$ + @end tex + +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. + + Analogously, you can use `@ifhtml ... @end ifhtml' to delimit a +region to be included in HTML output only, and `@html ... @end html' +for a region of raw HTML. + + Likewise, you can use `@ifxml ... @end ifxml' to delimit a region to +be included in XML output only, and `@xml ... @end xml' for a region +of raw XML. + + Again likewise, you can use `@ifdocbook ... @end ifdocbook' to +delimit a region to be included in Docbook output only, and `@docbook +... @end docbook' for a region of raw Docbook. + + In all cases, the exception to the raw processing is that `@' is +still an escape character, so the `@end' command can be recognized. + + +File: texinfo.info, Node: set clear value, Next: Conditional Nesting, Prev: Raw Formatter Commands, Up: Conditionals + +17.4 `@set', `@clear', and `@value' +=================================== + +You can direct the Texinfo formatting commands to format or ignore parts +of a Texinfo file with the `@set', `@clear', `@ifset', and `@ifclear' +commands. + + Here are brief descriptions of these commands, see the following +sections for more details: + +`@set FLAG [VALUE]' + Set the variable FLAG, to the optional VALUE if specifed. + +`@clear FLAG' + Undefine the variable FLAG, whether or not it was previously + defined. + +`@ifset FLAG' + If FLAG is set, text through the next `@end ifset' command is + formatted. If FLAG is clear, text through the following `@end + ifset' command is ignored. + +`@ifclear FLAG' + If FLAG is set, text through the next `@end ifclear' command is + ignored. If FLAG is clear, text through the following `@end + ifclear' command is formatted. + +* 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. + + +File: texinfo.info, Node: set value, Next: ifset ifclear, Up: set clear value + +17.4.1 `@set' and `@value' +-------------------------- + +You use the `@set' command to specify a value for a flag, which is +later expanded by the `@value' command. + + A "flag" (aka "variable") is an identifier. It is best to use only +letters and numerals in a flag name, not `-' or `_'--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 `@set' command like this: + + @set foo This is a string. + +This sets the value of the flag `foo' to "This is a string.". + + The Texinfo formatters then replace an `@value{FLAG}' command with +the string to which FLAG is set. Thus, when `foo' is set as shown +above, the Texinfo formatters convert this: + + @value{foo} +to this: + This is a string. + + You can write an `@value' command within a paragraph; but you must +write an `@set' command on a line of its own. + + If you write the `@set' command like this: + + @set foo + +without specifying a string, the value of `foo' is the empty string. + + If you clear a previously set flag with `@clear FLAG', a subsequent +`@value{flag}' command will report an error. + + For example, if you set `foo' as follows: + + @set howmuch very, very, very + +then the formatters transform + + It is a @value{howmuch} wet day. +into + It is a very, very, very wet day. + + If you write + + @clear howmuch + +then the formatters transform + + It is a @value{howmuch} wet day. +into + It is a {No value for "howmuch"} wet day. + + +File: texinfo.info, Node: ifset ifclear, Next: value Example, Prev: set value, Up: set clear value + +17.4.2 `@ifset' and `@ifclear' +------------------------------ + +When a FLAG is set, the Texinfo formatting commands format text between +subsequent pairs of `@ifset FLAG' and `@end ifset' commands. When the +FLAG is cleared, the Texinfo formatting commands do _not_ format the +text. `@ifclear' operates analogously. + + Write the conditionally formatted text between `@ifset FLAG' and +`@end ifset' commands, like this: + + @ifset FLAG + CONDITIONAL-TEXT + @end ifset + + For example, you can create one document that has two variants, such +as a manual for a `large' and `small' model: + + 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 ... + +In the example, the formatting commands will format the text between +`@ifset large' and `@end ifset' because the `large' flag is set. + + When FLAG is cleared, the Texinfo formatting commands do _not_ format +the text between `@ifset FLAG' and `@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 `@clear large' command after the `@set large' command (but before +the conditional text), then the Texinfo formatting commands ignore the +text between the `@ifset large' and `@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 ...". + + If a flag is cleared with an `@clear FLAG' command, then the +formatting commands format text between subsequent pairs of `@ifclear' +and `@end ifclear' commands. But if the flag is set with `@set FLAG', +then the formatting commands do _not_ format text between an `@ifclear' +and an `@end ifclear' command; rather, they ignore that text. An +`@ifclear' command looks like this: + + @ifclear FLAG + + +File: texinfo.info, Node: value Example, Prev: ifset ifclear, Up: set clear value + +17.4.3 `@value' Example +----------------------- + +You can use the `@value' command to minimize the number of places you +need to change when you record an update to a manual. *Note GNU Sample +Texts::, for the full text of an example of using this to work with +Automake distributions. + + This example is adapted from *Note Overview: (make)Top. + + 1. Set the flags: + + @set EDITION 0.35 Beta + @set VERSION 3.63 Beta + @set UPDATED 14 August 1992 + @set UPDATE-MONTH August 1992 + + 2. Write text for the `@copying' section (*note copying::): + + @copying + This is Edition @value{EDITION}, + last updated @value{UPDATED}, + of @cite{The GNU Make Manual}, + for @code{make}, version @value{VERSION}. + + Copyright ... + + Permission is granted ... + @end copying + + 3. Write text for the title page, for people reading the printed + manual: + + @titlepage + @title GNU Make + @subtitle A Program for Directing Recompilation + @subtitle Edition @value{EDITION}, ... + @subtitle @value{UPDATE-MONTH} + @page + @insertcopying + ... + @end titlepage + + (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.) + + 4. Write text for the Top node, for people reading the Info file: + + @ifnottex + @node Top + @top Make + + @insertcopying + ... + @end ifnottex + + After you format the manual, the `@value' constructs have been + expanded, so the output contains text like this: + + This is Edition 0.35 Beta, last updated 14 August 1992, + of `The GNU Make Manual', for `make', Version 3.63 Beta. + + When you update the manual, you change only the values of the flags; +you do not need to edit the three sections. + + +File: texinfo.info, Node: Conditional Nesting, Prev: set clear value, Up: Conditionals + +17.5 Conditional Nesting +======================== + +Conditionals can be nested; however, the details are a little tricky. +The difficulty comes with failing conditionals, such as `@ifhtml' when +HTML is not being produced, where the included text is to be ignored. +However, it is not to be _completely_ ignored, since it is useful to +have one `@ifset' inside another, for example--that is a way to include +text only if two conditions are met. Here's an 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 + + 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 +_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: + + @ifset a + @ifset b + @ifclear ok - ok, ignored + @end junky - ok, ignored + @end ifset + @c WRONG - missing @end ifset. + + 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. + + +File: texinfo.info, Node: Internationalization, Next: Defining New Texinfo Commands, Prev: Conditionals, Up: Top + +18 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 *Note Inserting Accents::. + +* Menu: + +* documentlanguage:: Declaring the current language. +* documentencoding:: Declaring the input encoding. + + +File: texinfo.info, Node: documentlanguage, Next: documentencoding, Up: Internationalization + +18.1 `@documentlanguage CC': Set the Document Language +====================================================== + +The `@documentlanguage' command declares the current document language. +Write it on a line by itself, with a two-letter ISO-639 language code +following (list is included below). If you have a multilingual +document, the intent is to be able to use this command multiple times, +to declare each language change. If the command is not used at all, +the default is `en' for English. + + At present, this command is ignored in Info and HTML output. For +TeX, it causes the file `txi-CC.tex' to be read (if it exists). Such a +file appropriately redefines the various English words used in TeX +output, such as `Chapter', `See', and so on. + + It would be good if this command also changed TeX's ideas of the +current hyphenation patterns (via the TeX primitive `\language'), but +this is unfortunately not currently implemented. + + Hereare the valid language codes, from ISO-639. + +`aa' Afar `ab' Abkhazian `af' Afrikaans +`am' Amharic `ar' Arabic `as' Assamese +`ay' Aymara `az' Azerbaijani `ba' Bashkir +`be' Byelorussian `bg' Bulgarian `bh' Bihari +`bi' Bislama `bn' Bengali; Bangla `bo' Tibetan +`br' Breton `ca' Catalan `co' Corsican +`cs' Czech `cy' Welsh `da' Danish +`de' German `dz' Bhutani `el' Greek +`en' English `eo' Esperanto `es' Spanish +`et' Estonian `eu' Basque `fa' Persian +`fi' Finnish `fj' Fiji `fo' Faroese +`fr' French `fy' Frisian `ga' Irish +`gd' Scots Gaelic `gl' Galician `gn' Guarani +`gu' Gujarati `ha' Hausa `he' Hebrew +`hi' Hindi `hr' Croatian `hu' Hungarian +`hy' Armenian `ia' Interlingua `id' Indonesian +`ie' Interlingue `ik' Inupiak `is' Icelandic +`it' Italian `iu' Inuktitut `ja' Japanese +`jw' Javanese `ka' Georgian `kk' Kazakh +`kl' Greenlandic `km' Cambodian `kn' Kannada +`ks' Kashmiri `ko' Korean `ku' Kurdish +`ky' Kirghiz `la' Latin `ln' Lingala +`lt' Lithuanian `lo' Laothian `lv' Latvian, Lettish +`mg' Malagasy `mi' Maori `mk' Macedonian +`ml' Malayalam `mn' Mongolian `mo' Moldavian +`mr' Marathi `ms' Malay `mt' Maltese +`my' Burmese `na' Nauru `ne' Nepali +`nl' Dutch `no' Norwegian `oc' Occitan +`om' (Afan) Oromo `or' Oriya `pa' Punjabi +`pl' Polish `ps' Pashto, Pushto `pt' Portuguese +`qu' Quechua `rm' Rhaeto-Romance `rn' Kirundi +`ro' Romanian `ru' Russian `rw' Kinyarwanda +`sa' Sanskrit `sd' Sindhi `sg' Sangro +`sh' Serbo-Croatian `si' Sinhalese `sk' Slovak +`sl' Slovenian `sm' Samoan `sn' Shona +`so' Somali `sq' Albanian `sr' Serbian +`ss' Siswati `st' Sesotho `su' Sundanese +`sv' Swedish `sw' Swahili `ta' Tamil +`te' Telugu `tg' Tajik `th' Thai +`ti' Tigrinya `tk' Turkmen `tl' Tagalog +`tn' Setswana `to' Tonga `tr' Turkish +`ts' Tsonga `tt' Tatar `tw' Twi +`ug' Uighur `uk' Ukrainian `ur' Urdu +`uz' Uzbek `vi' Vietnamese `vo' Volapuk +`wo' Wolof `xh' Xhosa `yi' Yiddish +`yo' Yoruba `za' Zhuang `zh' Chinese +`zu' Zulu + + +File: texinfo.info, Node: documentencoding, Prev: documentlanguage, Up: Internationalization + +18.2 `@documentencoding ENC': Set Input Encoding +================================================ + +The `@documentencoding' command declares the input document encoding. +Write it on a line by itself, with a valid encoding specification +following. + + At present, Texinfo supports only three encodings: + +`US-ASCII' + This has no particular effect, but it's included for completeness. + +`ISO-8859-1' + +`ISO-8859-2' + These specify the standard encodings for Western European and + Eastern European languages, respectively. A full description of + the encodings is beyond our scope here; + `http://czyborra.com/charsets/iso8859.html' is one of many useful + references. + + Specifying an encoding ENC has the following effects: + + In Info output, if the option `--enable-encoding' is also given to +`makeinfo', a so-called `Local Variables' section (*note File +Variables: (emacs)File Variables.) is output including ENC. This +allows Info readers to set the encoding appropriately: + + Local Variables: + coding: ENC + End: + + In HTML output, a `<meta>' tag is output, in the `<head>' section of +the HTML, that specifies ENC. Web servers and browsers cooperate to +use this information so the correct encoding is used to display the +page. + + <meta http-equiv="Content-Type" content="text/html; + charset=ENC"> + + In all other cases, it is recognized but ignored. + + +File: texinfo.info, Node: Defining New Texinfo Commands, Next: Hardcopy, Prev: Internationalization, Up: Top + +19 Defining New Texinfo Commands +******************************** + +Texinfo provides several ways to define new commands: + + * A Texinfo "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 "parameters"--text you + supply each time you use the macro. + + Incidentally, these macros have nothing to do with the `@defmac' + command, which is for documenting macros in the subject of the + manual (*note Def Cmd Template::). + + * `@alias' is a convenient way to define a new name for an existing + command. + + * `@definfoenclose' allows you to define new commands with + customized output in the Info file. + + +* 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. + + +File: texinfo.info, Node: Defining Macros, Next: Invoking Macros, Up: Defining New Texinfo Commands + +19.1 Defining Macros +==================== + +You use the Texinfo `@macro' command to define a macro, like this: + + @macro MACRONAME{PARAM1, PARAM2, ...} + TEXT ... \PARAM1\ ... + @end macro + + The "parameters" PARAM1, PARAM2, ... correspond to arguments supplied +when the macro is subsequently used in the document (described in the +next section). + + For a macro to work consistently with TeX, MACRONAME must consist +entirely of letters: no digits, hyphens, underscores, or other special +characters. So, we recommend using only letters. However, `makeinfo' +will accept anything except `{}_^='; `_' and `^' are excluded so that +macros can be called in `@math' mode without a following space (*note +`@math': math.). + + If a macro needs no parameters, you can define it either with an empty +list (`@macro foo {}') or with no braces at all (`@macro foo'). + + The definition or "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 `@macro'. + + In the macro body, instances of a parameter name surrounded by +backslashes, as in `\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. + + To get a single `\' in the macro expansion, use `\\'. Any other use +of `\' in the body yields a warning. + + The newlines after the `@macro' line and before the `@end macro' line +are ignored, that is, not included in the macro body. All other +whitespace is treated according to the usual Texinfo rules. + + To allow a macro to be used recursively, that is, in an argument to a +call to itself, you must define it with `@rmacro', like this: + + @rmacro rmac {arg} + a\arg\b + @end rmacro + ... + @rmac{1@rmac{text}2} + + This produces the output `a1atextb2b'. With `@macro' instead of +`@rmacro', an error message is given. + + You can undefine a macro FOO with `@unmacro FOO'. It is not an error +to undefine a macro that is already undefined. For example: + + @unmacro foo + + +File: texinfo.info, Node: Invoking Macros, Next: Macro Details, Prev: Defining Macros, Up: Defining New Texinfo Commands + +19.2 Invoking Macros +==================== + +After a macro is defined (see the previous section), you can use +("invoke") it in your document like this: + + @MACRONAME {ARG1, ARG2, ...} + +and the result will be just as if you typed the body of MACRONAME at +that spot. For example: + + @macro foo {p, q} + Together: \p\ & \q\. + @end macro + @foo{a, b} + +produces: + + Together: a & b. + + 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: + + @macro argless {} + No arguments here. + @end macro + @argless{} + +produces: + + No arguments here. + + To insert a comma, brace, or backslash in an argument, prepend a +backslash, as in + + @MACNAME {\\\{\}\,} + +which will pass the (almost certainly error-producing) argument `\{},' +to 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: + + @macro bar {p} + Twice: \p\ & \p\. + @end macro + @bar aah + +produces: + + Twice: aah & aah. + + 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: + + @macro bar {p} + Twice: \p\ & \p\. + @end macro + @bar{a,b} + +produces: + + Twice: a,b & a,b. + + +File: texinfo.info, Node: Macro Details, Next: alias, Prev: Invoking Macros, Up: Defining New Texinfo Commands + +19.3 Macro Details +================== + +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 `makeinfo' +by invoking `texi2dvi' with the `-E' option (*note Format with +texi2dvi::). + + * As mentioned earlier, macro names must consist entirely of letters. + + * 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 completely + random. + + * All macros are expanded inside at least one TeX group. This means + that `@set' and other such commands have no effect inside a macro. + + * 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. + + * Commas in macro arguments, even if escaped by a backslash, don't + always work. + + * It is best to avoid comments inside macro definitions. + + * Macro arguments cannot cross lines. + + * Macros cannot define macros in the natural way. To do this, you + must use conditionals and raw TeX. For 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 + + + The `makeinfo' implementation also has limitations: + + * `@verbatim' and macros do not mix; for instance, you can't start a + verbatim block inside a macro and end it outside. (*Note + verbatim::.) Starting any environment inside a macro and ending + it outside may or may not work, for that matter. + + * Macros that completely define macros are ok, but it's not possible + to have incorrectly nested macro definitions. That is, `@macro' + and `@end macro' (likewise for `@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. + + * `@rmacro' is a kludge. + + + 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). + + +File: texinfo.info, Node: alias, Next: definfoenclose, Prev: Macro Details, Up: Defining New Texinfo Commands + +19.4 `@alias NEW=EXISTING' +========================== + +The `@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 `@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: + @alias NEW = EXISTING + + For example, if your document contains citations for both books and +some other media (movies, for example), you might like to define a +macro `@moviecite{}' that does the same thing as an ordinary `@cite{}' +but conveys the extra semantic information as well. You'd do this as +follows: + + @alias moviecite = cite + + 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. + + +File: texinfo.info, Node: definfoenclose, Prev: alias, Up: Defining New Texinfo Commands + +19.5 `definfoenclose': Customized Highlighting +============================================== + +A `@definfoenclose' command may be used to define a highlighting +command for Info, but not for TeX. A command defined using +`@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 `@definfoenclose' for Info, +you will create a corresponding command for TeX, either in +`texinfo.tex', `texinfo.cnf', or within an `@iftex' in your document. + + Write a `@definfoenclose' command on a line and follow it with three +arguments separated by commas. The first argument to `@definfoenclose' +is the @-command name (without the `@'); 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 `@definfoenclose' on the name of a pre-defined macro +(such as `@emph', `@strong', `@t', or `@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 (*note Marking Text::). + + For example, you can write: + + @definfoenclose phoo,//,\\ + +near the beginning of a Texinfo file to define `@phoo' as an Info +formatting command that inserts `//' before and `\\' after the argument +to `@phoo'. You can then write `@phoo{bar}' wherever you want +`//bar\\' highlighted in Info. + + Also, for TeX formatting, you could write + + @iftex + @global@let@phoo=@i + @end iftex + +to define `@phoo' as a command that causes TeX to typeset the argument +to `@phoo' in italics. + + Each definition applies to its own formatter: one for TeX, the other +for `texinfo-format-buffer' or `texinfo-format-region'. The +`@definfoenclose' command need not be within `@ifinfo', but the raw TeX +commands do need to be in `@iftex'. + + Here is another example: write + + @definfoenclose headword, , : + +near the beginning of the file, to define `@headword' as an Info +formatting command that inserts nothing before and a colon after the +argument to `@headword'. + + `@definfoenclose' definitions must not be recursive, directly or +indirectly. + + +File: texinfo.info, Node: Hardcopy, Next: Creating and Installing Info Files, Prev: Defining New Texinfo Commands, Up: Top + +20 Formatting and Printing Hardcopy +*********************************** + +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. + + +File: texinfo.info, Node: Use TeX, Next: Format with tex/texindex, Up: Hardcopy + +20.1 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. (*Note How to Obtain TeX: +Obtaining TeX, for information on how to obtain TeX.) + + The standalone `makeinfo' program and Emacs functions +`texinfo-format-region' and `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 (*note Creating an Info File::). + + +File: texinfo.info, Node: Format with tex/texindex, Next: Format with texi2dvi, Prev: Use TeX, Up: Hardcopy + +20.2 Format with `tex' and `texindex' +===================================== + +You can format the Texinfo file with the shell command `tex' followed +by the name of the Texinfo file. For example: + + tex foo.texi + +TeX will produce a "DVI file" as well as several auxiliary files +containing information for indices, cross references, etc. The DVI +file (for "DeVice Independent" file) can be printed on virtually any +device (see the following sections). + + The `tex' formatting command itself does not sort the indices; it +writes an output file of unsorted index data. (The `texi2dvi' command +automatically generates indices; *note Format with `texi2dvi': Format +with texi2dvi.) To generate a printed index after running the `tex' +command, you first need a sorted index to work from. The `texindex' +command sorts indices. (The source file `texindex.c' comes as part of +the standard Texinfo distribution, among other places.) + + The `tex' formatting command outputs unsorted index files under names +that obey a standard convention: the name of your main input file with +any `.tex' (or similar, *note tex invocation: (web2c)tex invocation.) +extension removed, followed by the two letter names of indices. For +example, the raw index output files for the input file `foo.texinfo' +would be `foo.cp', `foo.vr', `foo.fn', `foo.tp', `foo.pg' and `foo.ky'. +Those are exactly the arguments to give to `texindex'. + + Instead of specifying all the unsorted index file names explicitly, +you can use `??' as shell wildcards and give the command in this form: + + texindex foo.?? + +This command will run `texindex' on all the unsorted index files, +including any that you have defined yourself using `@defindex' or +`@defcodeindex'. (You may execute `texindex foo.??' even if there are +similarly named files with two letter extensions that are not index +files, such as `foo.el'. The `texindex' command reports but otherwise +ignores such files.) + + For each file specified, `texindex' generates a sorted index file +whose name is made by appending `s' to the input file name. The +`@printindex' command looks for a file with that name (*note Printing +Indices & Menus::). `texindex' does not alter the raw index output +file. + + After you have sorted the indices, you need to rerun `tex' on the +Texinfo file. This regenerates the DVI file, this time with up-to-date +index entries. + + Finally, you may need to run `tex' one more time, to get the page +numbers in the cross-references correct. + + To summarize, this is a five step process: + + 1. Run `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). + + 2. Run `texindex' on the raw index files. This creates the + corresponding sorted index files (with three letter extensions). + + 3. Run `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. + + 4. Sort the indices again, with `texindex'. + + 5. Run `tex' one last time. This time the correct page numbers are + written for the cross-references. + + Alternatively, it's a one-step process: run `texi2dvi' (*note Format +with texi2dvi::). + + You need not run `texindex' each time after you run `tex'. If you do +not, on the next run, the `tex' formatting command will use whatever +sorted index files happen to exist from the previous use of `texindex'. +This is usually ok while you are debugging. + + 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 `@novalidate' command, which you must give _before_ the +`@setfilename' command (*note `@setfilename': setfilename.). Thus, the +beginning of your file would look approximately like this: + + \input texinfo + @novalidate + @setfilename myfile.info + ... + +`@novalidate' also turns off validation in `makeinfo', just like its +`--no-validate' option (*note Pointer Validation::). + + +File: texinfo.info, Node: Format with texi2dvi, Next: Print with lpr, Prev: Format with tex/texindex, Up: Hardcopy + +20.3 Format with `texi2dvi' +=========================== + +The `texi2dvi' command automatically runs both TeX and `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 `tex'--`texindex'--`tex'--`tex' sequence described in the +previous section. + + To run `texi2dvi' on an input file `foo.texi', do this (where +`prompt$ ' is your shell prompt): + + prompt$ texi2dvi foo.texi + + As shown in this example, the input filenames to `texi2dvi' must +include any extension (`.texi', `.texinfo', etc.). Under MS-DOS and +perhaps in other circumstances, you may need to run `sh texi2dvi +foo.texi' instead of relying on the operating system to invoke the +shell on the `texi2dvi' script. + + Perhaps the most useful option to `texi2dvi' is `--command=CMD'. +This inserts CMD on a line by itself after the `@setfilename' in a +temporary copy of the input file before running TeX. With this, you +can specify different printing formats, such as `@smallbook' (*note +smallbook::), `@afourpaper' (*note A4 Paper::), or `@pagesizes' (*note +pagesizes::), without actually changing the document source. (You can +also do this on a site-wide basis with `texinfo.cnf'; *note Preparing +for TeX: Preparing for TeX.). + + `texi2dvi' can also be used to process LaTeX files; simply run +`texi2dvi filename.ext'. + + For a list of other options, run `texi2dvi --help'. + + +File: texinfo.info, Node: Print with lpr, Next: Within Emacs, Prev: Format with texi2dvi, Up: Hardcopy + +20.4 Shell Print Using `lpr -d' +=============================== + +The precise command to print a DVI file depends on your system +installation. Two common ones are `dvips foo.dvi -o' and `lpr -d +foo.dvi'. + + For example, the following commands will (perhaps) suffice to sort the +indices, format, and print the `Bison Manual': + + tex bison.texinfo + texindex bison.?? + tex bison.texinfo + lpr -d bison.dvi + +(Remember that the shell commands may be different at your site; but +these are commonly used versions.) + + Using the `texi2dvi' shell script (see the previous section): + + texi2dvi bison.texinfo + lpr -d bison.dvi + # or perhaps dvips bison.dvi -o + + `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 +`lpr', but these are usually limited to sending files to a print server +over the network, and generally don't support the `-d' option. If you +are unfortunate enough to work on one of these systems, you have +several alternative ways of printing DVI files: + + * Find and install a Unix-like `lpr' program, or its clone. If you + can do that, you will be able to print DVI files just like + described above. + + * 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 `lpr' which comes with + your network software will have a special option to send a file to + specific queues, like this: + + lpr -Qdvi -hprint.server.domain bison.dvi + + * Convert the DVI file to a Postscript or PCL file and send it to + your local printer. *Note Invoking Dvips: (dvips)Invoking Dvips, + and the man pages for `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 `PRN'. + + +File: texinfo.info, Node: Within Emacs, Next: Texinfo Mode Printing, Prev: Print with lpr, Up: Hardcopy + +20.5 From an Emacs Shell +======================== + +You can give formatting and printing commands from a shell within GNU +Emacs. To create a shell within Emacs, type `M-x shell'. In this +shell, you can format and print the document. *Note Format and Print +Hardcopy: Hardcopy, for details. + + You can switch to and from the shell buffer while `tex' is running +and do other editing. If you are formatting a long document on a slow +machine, this can be very convenient. + + You can also use `texi2dvi' from an Emacs shell. For example, here +is how to use `texi2dvi' to format and print `Using and Porting GNU CC' +from a shell within Emacs: + + texi2dvi gcc.texinfo + lpr -d gcc.dvi + + See the next section for more information about formatting and +printing in Texinfo mode. + + +File: texinfo.info, Node: Texinfo Mode Printing, Next: Compile-Command, Prev: Within Emacs, Up: Hardcopy + +20.6 Formatting and Printing 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. + +`C-c C-t C-b' +`M-x texinfo-tex-buffer' + Run `texi2dvi' on the current buffer. + +`C-c C-t C-r' +`M-x texinfo-tex-region' + Run TeX on the current region. + +`C-c C-t C-i' +`M-x texinfo-texindex' + Sort the indices of a Texinfo file formatted with + `texinfo-tex-region'. + +`C-c C-t C-p' +`M-x texinfo-tex-print' + Print a DVI file that was made with `texinfo-tex-region' or + `texinfo-tex-buffer'. + +`C-c C-t C-q' +`M-x tex-show-print-queue' + Show the print queue. + +`C-c C-t C-d' +`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 `C-c C-t C-q' command + (`texinfo-show-tex-print-queue'). + +`C-c C-t C-k' +`M-x tex-kill-job' + Kill the currently running TeX job started by either + `texinfo-tex-region' or `texinfo-tex-buffer', or any other process + running in the Texinfo shell buffer. + +`C-c C-t C-x' +`M-x texinfo-quit-job' + Quit a TeX formatting job that has stopped because of an error by + sending an <x> to it. When you do this, TeX preserves a record of + what it did in a `.log' file. + +`C-c C-t C-l' +`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. + + Thus, the usual sequence of commands for formatting a buffer is as +follows (with comments to the right): + + C-c C-t C-b Run `texi2dvi' on the buffer. + C-c C-t C-p Print the DVI file. + C-c C-t C-q Display the printer queue. + + The Texinfo mode TeX formatting commands start a subshell in Emacs +called the `*tex-shell*'. The `texinfo-tex-command', +`texinfo-texindex-command', and `tex-dvi-print-command' commands are +all run in this shell. + + You can watch the commands operate in the `*tex-shell*' buffer, and +you can switch to and from and use the `*tex-shell*' buffer as you +would any other shell buffer. + + The formatting and print commands depend on the values of several +variables. The default values are: + + Variable 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" + + You can change the values of these variables with the `M-x +set-variable' command (*note Examining and Setting Variables: +(emacs)Examining.), or with your `.emacs' initialization file (*note +Init File: (emacs)Init File.). + + Beginning with version 20, GNU Emacs offers a user-friendly interface, +called "Customize", for changing values of user-definable variables. +*Note Easy Customization Interface: (emacs)Easy Customization, for more +details about this. The Texinfo variables can be found in the +`Development/Docs/Texinfo' group, once you invoke the `M-x customize' +command. + + +File: texinfo.info, Node: Compile-Command, Next: Requirements Summary, Prev: Texinfo Mode Printing, Up: Hardcopy + +20.7 Using the Local Variables List +=================================== + +Yet another way to apply the TeX formatting command to a Texinfo file +is to put that command in a "local variables list" at the end of the +Texinfo file. You can then specify the `tex' or `texi2dvi' commands as +a `compile-command' and have Emacs run it by typing `M-x compile'. +This creates a special shell called the `*compilation*' buffer in which +Emacs runs the compile command. For example, at the end of the +`gdb.texinfo' file, after the `@bye', you could put the following: + + Local Variables: + compile-command: "texi2dvi gdb.texinfo" + End: + +This technique is most often used by programmers who also compile +programs this way; see *Note Compilation: (emacs)Compilation. + + +File: texinfo.info, Node: Requirements Summary, Next: Preparing for TeX, Prev: Compile-Command, Up: Hardcopy + +20.8 TeX Formatting Requirements Summary +======================================== + +Every Texinfo file that is to be input to TeX must begin with a +`\input' command and must contain an `@setfilename' command: + + \input texinfo + @setfilename ARG-NOT-USED-BY-TEX + +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: + + @bye + + Strictly speaking, these lines are all a Texinfo file needs to be +processed successfully by TeX. + + Usually, however, the beginning includes an `@settitle' command to +define the title of the printed manual, an `@setchapternewpage' +command, a title page, a copyright page, and permissions. Besides an +`@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: + + * *Note `@settitle': settitle. + + * *Note `@setchapternewpage': setchapternewpage. + + * *Note Page Headings: Headings. + + * *Note Titlepage & Copyright Page::. + + * *Note Printing Indices & Menus::. + + * *Note Contents::. + + +File: texinfo.info, Node: Preparing for TeX, Next: Overfull hboxes, Prev: Requirements Summary, Up: Hardcopy + +20.9 Preparing for TeX +====================== + +TeX needs to know where to find the `texinfo.tex' file that the `\input +texinfo' command on the first line reads. The `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: + `http://savannah.gnu.org/cgi-bin/viewcvs/texinfo/texinfo/doc/texinfo.tex?rev=HEAD' + + Usually, the installer has put the `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 `texinfo.tex' in the current directory when you run TeX, and TeX +will find it there. + + Also, you should install `epsf.tex', if it is not already installed +from another distribution. More details are at the end of the +description of the `@image' command (*note Images::). + + Likewise for `pdfcolor.tex', if it is not already installed and you +use pdftex. + + Optionally, you may create an additional `texinfo.cnf', and install +it as well. This file is read by TeX when the `@setfilename' command +is executed (*note `@setfilename': 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 `texinfo.cnf' contains the line `@afourpaper' (*note A4 Paper::), +then all Texinfo documents will be processed with that page size in +effect. If you have nothing to put in `texinfo.cnf', you do not need +to create it. + + If neither of the above locations for these system files suffice for +you, you can specify the directories explicitly. For `texinfo.tex', +you can do this by writing the complete path for the file after the +`\input' command. Another way, that works for both `texinfo.tex' and +`texinfo.cnf' (and any other file TeX might read), is to set the +`TEXINPUTS' environment variable in your `.cshrc' or `.profile' file. + + Which you use of `.cshrc' or `.profile' depends on whether you use a +Bourne shell-compatible (`sh', `bash', `ksh', ...) or C +shell-compatible (`csh', `tcsh') command interpreter. The latter read +the `.cshrc' file for initialization information, and the former read +`.profile'. + + In a `.cshrc' file, you could use the following `csh' command +sequence: + + setenv TEXINPUTS .:/home/me/mylib: + + In a `.profile' file, you could use the following `sh' command +sequence: + + TEXINPUTS=.:/home/me/mylib: + export TEXINPUTS + + On MS-DOS/MS-Windows, you would say it like this(1): + + set TEXINPUTS=.;d:/home/me/mylib;c: + +It is customary for DOS/Windows users to put such commands in the +`autoexec.bat' file, or in the Windows Registry. + +These settings would cause TeX to look for `\input' file first in the +current directory, indicated by the `.', then in a hypothetical user +`me''s `mylib' directory, and finally in the system directories. (A +leading, trailing, or doubled `:' indicates searching the system +directories at that point.) + + Finally, you may wish to dump a `.fmt' file (*note Memory dumps: +(web2c)Memory dumps.) so that TeX can load Texinfo faster. (The +disadvantage is that then updating `texinfo.tex' requires redumping.) +You can do this by running this command, assuming `epsf.tex' is +findable by TeX: + + initex texinfo @dump + + (`dump' is a TeX primitive.) Then, move `texinfo.fmt' to wherever +your `.fmt' files are found; typically, this will be in the +subdirectory `web2c' of your TeX installation. + + ---------- Footnotes ---------- + + (1) Note the use of the `;' character, instead of `:', as directory +separator on these systems. + + +File: texinfo.info, Node: Overfull hboxes, Next: smallbook, Prev: Preparing for TeX, Up: Hardcopy + +20.10 Overfull "hboxes" +======================= + +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: + + Overfull @hbox (20.76302pt too wide) + +(In TeX, lines are in "horizontal boxes", hence the term, "hbox". +`@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. *Note Catching Errors with TeX Formatting: +Debugging with TeX, for more information about typesetting errors. + + If the Texinfo file has an overfull hbox, you can rewrite the sentence +so the overfull hbox does not occur, or you can decide to leave it. A +small excursion into the right margin often does not matter and may not +even be noticeable. + + If you have many overfull boxes and/or an antipathy to rewriting, you +can coerce TeX into greatly increasing the allowable interword spacing, +thus (if you're lucky) avoiding many of the bad line breaks, like this: + + @tex + \global\emergencystretch = .9\hsize + @end tex + +(You should adjust the fraction as needed.) This huge value for +`\emergencystretch' cannot be the default, since then the typeset +output would generally be of noticeably lower quality; the default is +`.15\hsize'. `\hsize' is the TeX dimension containing the current line +width. + + 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. + + 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 `@titlepage' command: + + @finalout + + +File: texinfo.info, Node: smallbook, Next: A4 Paper, Prev: Overfull hboxes, Up: Hardcopy + +20.11 Printing "Small" Books +============================ + +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: + + @smallbook + +(Since many books are about 7 by 9.25 inches, this command might better +have been called the `@regularbooksize' command, but it came to be +called the `@smallbook' command by comparison to the 8.5 by 11 inch +format.) + + If you write the `@smallbook' command between the start-of-header and +end-of-header lines, the Texinfo mode TeX region formatting command, +`texinfo-tex-region', will format the region in "small" book size +(*note Start of Header::). + + *Note small::, for information about commands that make it easier to +produce examples for a smaller manual. + + *Note Format with texi2dvi::, and *Note Preparing for TeX: Preparing +for TeX, for other ways to format with `@smallbook' that do not require +changing the source file. + + +File: texinfo.info, Node: A4 Paper, Next: pagesizes, Prev: smallbook, Up: Hardcopy + +20.12 Printing on A4 Paper +========================== + +You can tell TeX to format a document for printing on European size A4 +paper (or A5) with the `@afourpaper' (or `@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: + + \input texinfo @c -*-texinfo-*- + @c %**start of header + @setfilename texinfo + @settitle Texinfo + @afourpaper + @c %**end of header + + *Note Format with texi2dvi::, and *Note Preparing for TeX: Preparing +for TeX, for other ways to format for different paper sizes that do not +require changing the source file. + + You may or may not prefer the formatting that results from the command +`@afourlatex'. There's also `@afourwide' for A4 paper in wide format. + + +File: texinfo.info, Node: pagesizes, Next: Cropmarks and Magnification, Prev: A4 Paper, Up: Hardcopy + +20.13 `@pagesizes' [WIDTH][, HEIGHT]: Custom Page Sizes +======================================================= + +You can explicitly specify the height and (optionally) width of the main +text area on the page with the `@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: + + @pagesizes 200mm,150mm + and + @pagesizes 11.5in + + This would be reasonable for printing on B5-size paper. To emphasize, +this command specifies the size of the _text area_, not the size of the +paper (which is 250mm by 177mm for B5, 14in by 8.5in for legal). + + To make more elaborate changes, such as changing any of the page +margins, you must define a new command in `texinfo.tex' (or +`texinfo.cnf', *note Preparing for TeX: Preparing for TeX.). + + *Note Format with texi2dvi::, and *Note Preparing for TeX: Preparing +for TeX, for other ways to specify `@pagesizes' that do not require +changing the source file. + + `@pagesizes' is ignored by `makeinfo'. + + +File: texinfo.info, Node: Cropmarks and Magnification, Next: PDF Output, Prev: pagesizes, Up: Hardcopy + +20.14 Cropmarks and Magnification +================================= + +You can (attempt to) direct TeX to print cropmarks at the corners of +pages with the `@cropmarks' command. Write the `@cropmarks' command on +a line by itself between `@iftex' and `@end iftex' lines near the +beginning of the Texinfo file, before the title page, like this: + + @iftex + @cropmarks + @end iftex + + 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 `@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 +`texinfo.tex'. + + You can attempt to direct TeX to typeset pages larger or smaller than +usual with the `\mag' TeX command. Everything that is typeset is +scaled proportionally larger or smaller. (`\mag' stands for +"magnification".) This is _not_ a Texinfo @-command, but is a plain +TeX command that is prefixed with a backslash. You have to write this +command between `@tex' and `@end tex' (*note Raw Formatter Commands::). + + Follow the `\mag' command with an `=' 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: + + @tex + \mag=1200 + @end tex + + 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-`\mag' may not print or may print only with certain +magnifications. Be prepared to experiment. + + +File: texinfo.info, Node: PDF Output, Next: Obtaining TeX, Prev: Cropmarks and Magnification, Up: Hardcopy + +20.15 PDF Output +================ + +You can generate a PDF output file from Texinfo source by using the +`pdftex' program to process your file instead of plain `tex'. That is, +run `pdftex foo.texi' instead of `tex foo.texi', or give the `--pdf' +option to `texi2dvi'. + + "PDF" stands for `Portable Document Format'. It was invented by Adobe +Systems some years ago for document interchange, based on their +PostScript language. A PDF reader (http://www.foolabs.com/xpdf/) for +the X window system is freely available, as is the definition of the +file format (http://partners.adobe.com/asn/developer/technotes/). At +present, there are no `@ifpdf' or `@pdf' commands as with the other +output formats. + + Despite the `portable' in the name, PDF files are nowhere near as +portable in practice as the plain ASCII formats (Info, HTML) that +Texinfo supports (DVI portability is arguable). They also tend to be +much larger. Nevertheless, a PDF file does preserve an actual printed +document on a screen as faithfully as possible, so it has its place. + + +File: texinfo.info, Node: Obtaining TeX, Prev: PDF Output, Up: Hardcopy + +20.16 How to Obtain TeX +======================= + +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 (`http://tug.org/web2c'). + + Instructions for retrieval by anonymous ftp and information on other +available distributions: `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: + + Free Software Foundation, Inc. + 59 Temple Place Suite 330 + Boston, MA 02111-1307 + USA + Telephone: +1-617-542-5942 + Fax: (including Japan) +1-617-542-2652 + Free Dial Fax (in Japan): + 0031-13-2473 (KDD) + 0066-3382-0158 (IDC) + Electronic mail: `gnu@gnu.org' + + Many other TeX distributions are available; see `http://tug.org/'. + + +File: texinfo.info, Node: Creating and Installing Info Files, Next: Generating HTML, Prev: Hardcopy, Up: Top + +21 Creating and Installing Info Files +************************************* + +This chapter describes how to create and install Info files. *Note +Info Files::, for general information about the file format itself. + +* Menu: + +* Creating an Info File:: +* Installing an Info File:: + + +File: texinfo.info, Node: Creating an Info File, Next: Installing an Info File, Up: Creating and Installing Info Files + +21.1 Creating an Info File +========================== + +`makeinfo' is a program that converts a Texinfo file into an Info file, +HTML file, or plain text. `texinfo-format-region' and +`texinfo-format-buffer' are GNU Emacs functions that convert Texinfo to +Info. + + For information on installing the Info file in the Info system, *note +Installing an Info File::. + +* Menu: + +* makeinfo advantages:: `makeinfo' provides better error checking. +* Invoking makeinfo:: How to run `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 `makeinfo' from Emacs. +* texinfo-format commands:: Two Info formatting commands written + in Emacs Lisp are an alternative + to `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. + + +File: texinfo.info, Node: makeinfo advantages, Next: Invoking makeinfo, Up: Creating an Info File + +21.1.1 `makeinfo' Preferred +--------------------------- + +The `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. `makeinfo' is a C program +that is independent of Emacs. You do not need to run Emacs to use +`makeinfo', which means you can use `makeinfo' on machines that are too +small to run Emacs. You can run `makeinfo' in any one of three ways: +from an operating system shell, from a shell inside Emacs, or by typing +the `C-c C-m C-r' or the `C-c C-m C-b' command in Texinfo mode in Emacs. + + The `texinfo-format-region' and the `texinfo-format-buffer' commands +are useful if you cannot run `makeinfo'. Also, in some circumstances, +they format short regions or buffers more quickly than `makeinfo'. + + +File: texinfo.info, Node: Invoking makeinfo, Next: makeinfo options, Prev: makeinfo advantages, Up: Creating an Info File + +21.1.2 Running `makeinfo' from a Shell +-------------------------------------- + +To create an Info file from a Texinfo file, invoke `makeinfo' followed +by the name of the Texinfo file. Thus, to create the Info file for +Bison, type the following to the shell: + + makeinfo bison.texinfo + + (You can run a shell inside Emacs by typing `M-x shell'.) + + `makeinfo' has many options to control its actions and output; see +the next section. + + +File: texinfo.info, Node: makeinfo options, Next: Pointer Validation, Prev: Invoking makeinfo, Up: Creating an Info File + +21.1.3 Options for `makeinfo' +----------------------------- + +The `makeinfo' program accepts many options. Perhaps the most commonly +needed are those that change the output format. By default, `makeinfo' +outputs Info files. + + Each command line option is a word preceded by `--' or a letter +preceded by `-'. 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 `bison.texinfo' in which each line is filled to only 68 +columns: + + makeinfo --fill-column=68 bison.texinfo + + You can write two or more options in sequence, like this: + + makeinfo --no-split --fill-column=70 ... + +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: + +`-D VAR' + Cause the variable VAR to be defined. This is equivalent to `@set + VAR' in the Texinfo file (*note set clear value::). + +`--commands-in-node-names' + Allow `@'-commands in node names. This is not recommended, as it + can probably never be implemented in TeX. It also makes + `makeinfo' much slower. Also, this option is ignored when + `--no-validate' is used. *Note Pointer Validation::, for more + details. + +`--css-include=FILE' + Include the contents of FILE, which should contain cascading style + sheets specifications, in the `<style>' block of the HTML output. + *Note HTML CSS::. If FILE is `-', read standard input. + +`--docbook' + Generate Docbook output rather than Info. + +`--enable-encoding' + Output accented and special characters in Info or plain text output + based on `@documentencoding'. *Note `documentencoding': + documentencoding, and *Note Inserting Accents::. + +`--error-limit=LIMIT' +`-e LIMIT' + Set the maximum number of errors that `makeinfo' will report + before exiting (on the assumption that continuing would be + useless); default 100. + +`--fill-column=WIDTH' +`-f 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 `--html'. + +`--footnote-style=STYLE' +`-s STYLE' + Set the footnote style to STYLE, either `end' for the end node + style (the default) or `separate' for the separate node style. + The value set by this option overrides the value set in a Texinfo + file by an `@footnotestyle' command (*note Footnotes::). When the + footnote style is `separate', `makeinfo' makes a new node + containing the footnotes found in the current node. When the + footnote style is `end', `makeinfo' places the footnote references + at the end of the current node. Ignored with `--html'. + +`--force' +`-F' + Ordinarily, if the input file has errors, the output files are not + created. With this option, they are preserved. + +`--help' +`-h' + Print a usage message listing all available options, then exit + successfully. + +`--html' + Generate HTML output rather than Info. *Note 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. + +`-I DIR' + Append DIR to the directory search list for finding files that are + included using the `@include' command. By default, `makeinfo' + searches only the current directory. If DIR is not given, the + current directory `.' is appended. Note that DIR can actually be + a list of several directories separated by the usual path + separator character (`:' on Unix, `;' on MS-DOS/MS-Windows). + +`--ifdocbook' +`--ifhtml' +`--ifinfo' +`--ifplaintext' +`--iftex' +`--ifxml' + For the specified format, process `@ifFORMAT' and `@FORMAT' + commands even if not generating the given output format. For + instance, if `--iftex' is specified, then `@iftex' and `@tex' + blocks will be read. This can be useful when postprocessing the + output. + +`--macro-expand=FILE' +`-E FILE' + Output the Texinfo source with all the macros expanded to the named + file. Normally, the results of macro expansion are used + internally by `makeinfo' and then discarded. This option is used + by `texi2dvi'. + +`--no-headers' + For Info output, do not include menus or node separator lines in + the output, and implicitly `--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 `INSTALL' file). + + For HTML output, likewise omit menus. And if `--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). *Note Generating HTML::. + + In both cases, ignore `@setfilename' and write to standard output + by default--can be overridden with `-o'. + +`--no-ifdocbook' +`--no-ifhtml' +`--no-ifinfo' +`--no-ifplaintext' +`--no-iftex' +`--no-ifxml' + Do not process `@ifFORMAT' and `@FORMAT' commands even if + generating the given format. For instance, if `--no-ifhtml' is + specified, then `@ifhtml' and `@html' blocks will not be read. + +`--no-split' + Suppress the splitting stage of `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 (*note + Generating HTML::). + +`--no-pointer-validate' +`--no-validate' + Suppress the pointer-validation phase of `makeinfo'. This can also + be done with the `@novalidate' command (*note 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. *Note Pointer Validation::. + +`--no-warn' + Suppress warning messages (but _not_ error messages). You might + want this if the file you are creating has examples of Texinfo + cross references within it, and the nodes that are referenced do + not actually exist. + +`--number-sections' + Output chapter, section, and appendix numbers as in printed + manuals. + +`--no-number-footnotes' + Suppress automatic footnote numbering. By default, `makeinfo' + numbers each footnote sequentially in a single node, resetting the + current footnote number to 1 at the start of each node. + +`--output=FILE' +`-o FILE' + Specify that the output should be directed to FILE and not to the + file name specified in the `@setfilename' command found in the + Texinfo source (*note setfilename::). If FILE is `-', output goes + to standard output and `--no-split' is implied. For split HTML + output, FILE is the name for the directory into which all HTML + nodes are written (*note Generating HTML::). + +`-P DIR' + Prepend DIR to the directory search list for `@include'. If DIR + is not given, the current directory `.' is prepended. See `-I' + for more details. + +`--paragraph-indent=INDENT' +`-p INDENT' + Set the paragraph indentation style to INDENT. The value set by + this option overrides the value set in a Texinfo file by an + `@paragraphindent' command (*note paragraphindent::). The value + of INDENT is interpreted as follows: + + `asis' + Preserve any existing indentation at the starts of paragraphs. + + `0' or `none' + Delete any existing indentation. + + NUM + Indent each paragraph by NUM spaces. + +`--reference-limit=LIMIT' +`-r LIMIT' + Set the value of the number of references to a node that + `makeinfo' will make without reporting a warning. If a node has + more than this number of references in it, `makeinfo' will make the + references but also report a warning. The default is 1000. + +`--split-size=NUM' + Keep Info files to at most NUM characters; default is 300,000. + +`-U VAR' + Cause VAR to be undefined. This is equivalent to `@clear VAR' in + the Texinfo file (*note set clear value::). + +`--verbose' + Cause `makeinfo' to display messages saying what it is doing. + Normally, `makeinfo' only outputs messages if there are errors or + warnings. + +`--version' +`-V' + Print the version number, then exit successfully. + +`--xml' + Generate XML output rather than Info. + + + `makeinfo' also reads the environment variable +`TEXINFO_OUTPUT_FORMAT' to determine the output format, if not +overridden by a command line option. The possible values are: + + docbook html info plaintext xml + + If not set, Info output is the default. + + +File: texinfo.info, Node: Pointer Validation, Next: makeinfo in Emacs, Prev: makeinfo options, Up: Creating an Info File + +21.1.4 Pointer Validation +------------------------- + +If you do not suppress pointer validation with the `--no-validate' +option or the `@novalidate' command in the source file (*note Use TeX: +Use TeX.), `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: + + 1. 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 `(dir)', then the referenced node must exist. + + 2. 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. + + 3. Every node except the `Top' node must have an `Up' pointer. + + 4. 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 `(FILE)'. + + 5. 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. + + 6. 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. + + Some Texinfo documents might fail during the validation phase because +they use commands like `@value' and `@definfoenclose' in node +definitions and cross-references inconsistently. Consider the +following example: + + @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. + +Here, the node "Node 1" was referenced both verbatim and through +`@value'. + + By default, `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 `@node' line should have also used `@value'. However, if, +for some reason, you _must_ reference node names inconsistently, and +`makeinfo' fails to validate the file, you can use the +`--commands-in-node-names' option to force `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. + + The support for `@'-commands in `@node' directives is not general +enough to be freely used. For example, if the example above redefined +`nodename' somewhere in the document, `makeinfo' will fail to convert +it, even if invoked with the `--commands-in-node-names' option. + + `--commands-in-node-names' has no effect if the `--no-validate' +option is given. + + +File: texinfo.info, Node: makeinfo in Emacs, Next: texinfo-format commands, Prev: Pointer Validation, Up: Creating an Info File + +21.1.5 Running `makeinfo' Within Emacs +-------------------------------------- + +You can run `makeinfo' in GNU Emacs Texinfo mode by using either the +`makeinfo-region' or the `makeinfo-buffer' commands. In Texinfo mode, +the commands are bound to `C-c C-m C-r' and `C-c C-m C-b' by default. + +`C-c C-m C-r' +`M-x makeinfo-region' + Format the current region for Info. + +`C-c C-m C-b' +`M-x makeinfo-buffer' + Format the current buffer for Info. + + When you invoke `makeinfo-region' the output goes to a temporary +buffer. When you invoke `makeinfo-buffer' output goes to the file set +with `@setfilename' (*note setfilename::). + + The Emacs `makeinfo-region' and `makeinfo-buffer' commands run the +`makeinfo' program in a temporary shell buffer. If `makeinfo' finds +any errors, Emacs displays the error messages in the temporary buffer. + + You can parse the error messages by typing `C-x `' (`next-error'). +This causes Emacs to go to and position the cursor on the line in the +Texinfo source that `makeinfo' thinks caused the error. *Note Running +`make' or Compilers Generally: (emacs)Compilation, for more information +about using the `next-error' command. + + In addition, you can kill the shell in which the `makeinfo' command +is running or make the shell buffer display its most recent output. + +`C-c C-m C-k' +`M-x makeinfo-kill-job' + Kill the current running `makeinfo' job (from `makeinfo-region' or + `makeinfo-buffer'). + +`C-c C-m C-l' +`M-x makeinfo-recenter-output-buffer' + Redisplay the `makeinfo' shell buffer to display its most recent + output. + +(Note that the parallel commands for killing and recentering a TeX job +are `C-c C-t C-k' and `C-c C-t C-l'. *Note Texinfo Mode Printing::.) + + You can specify options for `makeinfo' by setting the +`makeinfo-options' variable with either the `M-x customize' or the `M-x +set-variable' command, or by setting the variable in your `.emacs' +initialization file. + + For example, you could write the following in your `.emacs' file: + + (setq makeinfo-options + "--paragraph-indent=0 --no-split + --fill-column=70 --verbose") + +For more information, see +*Note Easy Customization Interface: (emacs)Easy Customization, +*Note Examining and Setting Variables: (emacs)Examining, +*Note Init File: (emacs)Init File, and +*Note Options for `makeinfo': makeinfo options. + + +File: texinfo.info, Node: texinfo-format commands, Next: Batch Formatting, Prev: makeinfo in Emacs, Up: Creating an Info File + +21.1.6 The `texinfo-format...' Commands +--------------------------------------- + +In GNU Emacs in Texinfo mode, you can format part or all of a Texinfo +file with the `texinfo-format-region' command. This formats the +current region and displays the formatted text in a temporary buffer +called `*Info Region*'. + + Similarly, you can format a buffer with the `texinfo-format-buffer' +command. This command creates a new buffer and generates the Info file +in it. Typing `C-x C-s' will save the Info file under the name +specified by the `@setfilename' line which must be near the beginning +of the Texinfo file. + +`C-c C-e C-r' +``texinfo-format-region'' + Format the current region for Info. + +`C-c C-e C-b' +``texinfo-format-buffer'' + Format the current buffer for Info. + + The `texinfo-format-region' and `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 *Note Catching Mistakes::. However, +the `makeinfo' program is often faster and provides better error +checking (*note makeinfo in Emacs::). + + +File: texinfo.info, Node: Batch Formatting, Next: Tag and Split Files, Prev: texinfo-format commands, Up: Creating an Info File + +21.1.7 Batch Formatting +----------------------- + +You can format Texinfo files for Info using `batch-texinfo-format' and +Emacs Batch mode. You can run Emacs in Batch mode from any shell, +including a shell inside of Emacs. (*Note Command Arguments: +(emacs)Command Arguments.) + + Here is a shell command to format all the files that end in +`.texinfo' in the current directory: + + emacs -batch -funcall batch-texinfo-format *.texinfo + +Emacs processes all the files listed on the command line, even if an +error occurs while attempting to format some of them. + + Run `batch-texinfo-format' only with Emacs in Batch mode as shown; it +is not interactive. It kills the Batch mode Emacs on completion. + + `batch-texinfo-format' is convenient if you lack `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 `texinfo-format-region' or +`texinfo-format-buffer', you cannot use that Emacs for anything else +until the command finishes.) + + +File: texinfo.info, Node: Tag and Split Files, Prev: Batch Formatting, Up: Creating an Info File + +21.1.8 Tag Files and Split Files +-------------------------------- + +If a Texinfo file has more than 30,000 bytes, `texinfo-format-buffer' +automatically creates a tag table for its Info file; `makeinfo' always +creates a tag table. With a "tag table", Info can jump to new nodes +more quickly than it can otherwise. + + In addition, if the Texinfo file contains more than about 300,000 +bytes, `texinfo-format-buffer' and `makeinfo' split the large Info file +into shorter "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 "include files" were designed as a way to create a single, +large printed manual out of the smaller Info files. *Note Include +Files::, for more information. Include files are still used for very +large documents, such as `The Emacs Lisp Reference Manual', in which +each chapter is a separate file.) + + When a file is split, Info itself makes use of a shortened version of +the original file that contains just the tag table and references to +the files that were split off. The split-off files are called +"indirect" files. + + The split-off files have names that are created by appending `-1', +`-2', `-3' and so on to the file name specified by the `@setfilename' +command. The shortened version of the original file continues to have +the name specified by `@setfilename'. + + At one stage in writing this document, for example, the Info file was +saved as the file `test-texinfo' and that file looked like this: + + 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 + test-texinfo-3: 101300 + ^_^L + Tag table: + (Indirect) + Node: overview^?104 + Node: info file^?1271 + Node: printed manual^?4853 + Node: conventions^?6855 + ... + +(But `test-texinfo' had far more nodes than are shown here.) Each of +the split-off, indirect files, `test-texinfo-1', `test-texinfo-2', and +`test-texinfo-3', is listed in this file after the line that says +`Indirect:'. The tag table is listed after the line that says `Tag +table:'. + + In the list of indirect files, the number following the file name +records the cumulative number of bytes in the preceding indirect files, +not counting the file list itself, the tag table, or 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 `texinfo-format-buffer' to create Info files, you +may want to run the `Info-validate' command. (The `makeinfo' command +does such a good job on its own, you do not need `Info-validate'.) +However, you cannot run the `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 *Note Using +Info-validate::. + + +File: texinfo.info, Node: Installing an Info File, Prev: Creating an Info File, Up: Creating and Installing Info Files + +21.2 Installing an Info File +============================ + +Info files are usually kept in the `info' directory. You can read Info +files using the standalone Info program or the Info reader built into +Emacs. (*note info: (info)Top, 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:: `install-info' options. + + +File: texinfo.info, Node: Directory File, Next: New Info File, Up: Installing an Info File + +21.2.1 The Directory File `dir' +------------------------------- + +For Info to work, the `info' directory must contain a file that serves +as a top level directory for the Info system. By convention, this file +is called `dir'. (You can find the location of this file within Emacs +by typing `C-h i' to enter Info and then typing `C-x C-f' to see the +pathname to the `info' directory.) + + The `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: + + * 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. + ... + + 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. *Note Nodes in Other Info Files: Other Info Files.) + + Thus, the `Info' entry points to the `Top' node of the `info' file +and the `Emacs' entry points to the `Top' node of the `emacs' file. + + In each of the Info files, the `Up' pointer of the `Top' node refers +back to the `dir' file. For example, the line for the `Top' node of +the Emacs manual looks like this in Info: + + File: emacs Node: Top, Up: (DIR), Next: Distrib + +In this case, the `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 `dir'. + + +File: texinfo.info, Node: New Info File, Next: Other Info Directories, Prev: Directory File, Up: Installing an Info File + +21.2.2 Listing a New Info File +------------------------------ + +To add a new Info file to your system, you must write a menu entry to +add to the menu in the `dir' file in the `info' directory. For +example, if you were adding documentation for GDB, you would write the +following new entry: + + * GDB: (gdb). The source-level C debugger. + +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 `.info' extension. Thus, the +Info file for GDB might be called either `gdb' or `gdb.info'. The Info +reader programs automatically try the file name both with and without +`.info'(1); so it is better to avoid clutter and not to write `.info' +explicitly in the menu entry. For example, the GDB menu entry should +use just `gdb' for the file name, not `gdb.info'. + + ---------- Footnotes ---------- + + (1) On MS-DOS/MS-Windows systems, Info will try the `.inf' extension +as well. + + +File: texinfo.info, Node: Other Info Directories, Next: Installing Dir Entries, Prev: New Info File, Up: Installing an Info File + +21.2.3 Info Files in Other Directories +-------------------------------------- + +If an Info file is not in the `info' directory, there are three ways to +specify its location: + + 1. Write the pathname in the `dir' file as the second part of the + menu. + + 2. If you are using Emacs, list the name of the file in a second `dir' + file, in its directory; and then add the name of that directory to + the `Info-directory-list' variable in your personal or site + initialization file. + + This variable tells Emacs where to look for `dir' files (the files + must be named `dir'). Emacs merges the files named `dir' from + each of the listed directories. (In Emacs version 18, you can set + the `Info-directory' variable to the name of only one directory.) + + 3. Specify the Info directory name in the `INFOPATH' environment + variable in your `.profile' or `.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.) + + For example, to reach a test file in the `/home/bob/info' directory, +you could add an entry like this to the menu in the standard `dir' file: + + * Test: (/home/bob/info/info-test). Bob's own test file. + +In this case, the absolute file name of the `info-test' file is written +as the second part of the menu entry. + + Alternatively, you could write the following in your `.emacs' file: + + (require 'info) + (setq Info-directory-list + (cons (expand-file-name "/home/bob/info") + Info-directory-list)) + + This tells Emacs to merge the system `dir' file with the `dir' file +in `/home/bob/info'. Thus, Info will list the +`/home/bob/info/info-test' file as a menu entry in the +`/home/bob/info/dir' file. Emacs does the merging only when `M-x info' +is first run, so if you want to set `Info-directory-list' in an Emacs +session where you've already run `info', you must `(setq +Info-dir-contents nil)' to force Emacs to recompose the `dir' file. + + Finally, you can tell Info where to look by setting the `INFOPATH' +environment variable in your shell startup file, such as `.cshrc', +`.profile' or `autoexec.bat'. If you use a Bourne-compatible shell +such as `sh' or `bash' for your shell command interpreter, you set the +`INFOPATH' environment variable in the `.profile' initialization file; +but if you use `csh' or `tcsh', you set the variable in the `.cshrc' +initialization file. On MS-DOS/MS-Windows systems, you must set +`INFOPATH' in your `autoexec.bat' file or in the Registry. Each type +of shell uses a different syntax. + + * In a `.cshrc' file, you could set the `INFOPATH' variable as + follows: + + setenv INFOPATH .:~/info:/usr/local/emacs/info + + * In a `.profile' file, you would achieve the same effect by writing: + + INFOPATH=.:$HOME/info:/usr/local/emacs/info + export INFOPATH + + * In a `autoexec.bat' file, you write this command(1): + + set INFOPATH=.;%HOME%/info;c:/usr/local/emacs/info + +The `.' indicates the current directory as usual. Emacs uses the +`INFOPATH' environment variable to initialize the value of Emacs's own +`Info-directory-list' variable. The stand-alone Info reader merges any +files named `dir' in any directory listed in the `INFOPATH' variable +into a single menu presented to you in the node called `(dir)Top'. + + However you set `INFOPATH', if its last character is a colon(2), 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 `sh' syntax): + + INFOPATH=/local/info: + export INFOPATH + +will search `/local/info' first, then the standard directories. +Leading or doubled colons are not treated specially. + + When you create your own `dir' file for use with +`Info-directory-list' or `INFOPATH', it's easiest to start by copying +an existing `dir' file and replace all the text after the `* Menu:' +with your desired entries. That way, the punctuation and special +CTRL-_ characters that Info needs will be present. + + ---------- Footnotes ---------- + + (1) Note the use of `;' as the directory separator, and a different +syntax for using values of other environment variables. + + (2) On MS-DOS/MS-Windows systems, use semi-colon instead. + + +File: texinfo.info, Node: Installing Dir Entries, Next: Invoking install-info, Prev: Other Info Directories, Up: Installing an Info File + +21.2.4 Installing Info Directory Files +-------------------------------------- + +When you install an Info file onto your system, you can use the program +`install-info' to update the Info directory file `dir'. Normally the +makefile for the package runs `install-info', just after copying the +Info file into its proper installed location. + + In order for the Info file to work with `install-info', you include +the commands `@dircategory' and `@direntry'...`@end direntry' in the +Texinfo source file. Use `@direntry' to specify the menu entries to +add to the Info directory file, and use `@dircategory' to specify which +part of the Info directory to put it in. Here is how these commands +are used in this manual: + + @dircategory Texinfo documentation system + @direntry + * Texinfo: (texinfo). The GNU documentation format. + * install-info: (texinfo)Invoking install-info. ... + ... + @end direntry + + Here's what this produces in the Info file: + + INFO-DIR-SECTION Texinfo documentation system + START-INFO-DIR-ENTRY + * Texinfo: (texinfo). The GNU documentation format. + * install-info: (texinfo)Invoking install-info. ... + ... + END-INFO-DIR-ENTRY + +The `install-info' program sees these lines in the Info file, and that +is how it knows what to do. + + Always use the `@direntry' and `@dircategory' commands near the +beginning of the Texinfo input, before the first `@node' command. If +you use them later on in the input, `install-info' will not notice them. + + If you use `@dircategory' more than once in the Texinfo source, each +usage specifies the `current' category; any subsequent `@direntry' +commands will add to that category. + + When choosing a category name for the `@dircategory' command, we +recommend consulting the Free Software Directory +(http://www.gnu.org/directory). If your program is not listed there, +or listed incorrectly or incompletely, please report the situation to +the directory maintainers (<bug-directory@gnu.org>) so that the +category names can be kept in sync. + + Here are a few examples (see the `util/dir-example' file in the +Texinfo distribution for large sample `dir' file): + + Emacs + Localization + Printing + Software development + Software libraries + Text creation and manipulation + + Each `Invoking' node for every program installed should have a +corresponding `@direntry'. This lets users easily find the +documentation for the different programs they can run, as with the +traditional `man' system. + + +File: texinfo.info, Node: Invoking install-info, Prev: Installing Dir Entries, Up: Installing an Info File + +21.2.5 Invoking `install-info' +------------------------------ + +`install-info' inserts menu entries from an Info file into the +top-level `dir' file in the Info system (see the previous sections for +an explanation of how the `dir' file works). It's most often run as +part of software installation, or when constructing a `dir' file for +all manuals on a system. Synopsis: + + install-info [OPTION]... [INFO-FILE [DIR-FILE]] + + If INFO-FILE or 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. `install-info' can read only one +Info file and write only one `dir' file per invocation. + + If DIR-FILE (however specified) does not exist, `install-info' +creates it if possible (with no entries). + + If any input file is compressed with `gzip' (*note Invoking gzip: +(gzip)Invoking gzip.), `install-info' automatically uncompresses it for +reading. And if DIR-FILE is compressed, `install-info' also +automatically leaves it compressed after writing any changes. If +DIR-FILE itself does not exist, `install-info' tries to open +`DIR-FILE.gz'. + + Options: + +`--delete' + Delete the entries in INFO-FILE from DIR-FILE. The file name in + the entry in DIR-FILE must be INFO-FILE (except for an optional + `.info' in either one). Don't insert any new entries. + +`--dir-file=NAME' +`-d NAME' + Specify file name of the Info directory file. This is equivalent + to using the DIR-FILE argument. + +`--entry=TEXT' +`-e TEXT' + Insert TEXT as an Info directory entry; 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. + +`--help' +`-h' + Display a usage message listing basic usage and all available + options, then exit successfully. + +`--info-file=FILE' +`-i FILE' + Specify Info file to install in the directory. Equivalent to + using the INFO-FILE argument. + +`--info-dir=DIR' +`-D DIR' + Specify the directory where the directory file `dir' resides. + Equivalent to `--dir-file=DIR/dir'. + +`--item=TEXT' + Same as `--entry=TEXT'. An Info directory entry is actually a + menu item. + +`--quiet' + Suppress warnings. + +`--remove' +`-r' + Same as `--delete'. + +`--section=SEC' +`-s SEC' + Put this file's entries in section 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. + +`--version' +`-V' + Display version information and exit successfully. + + + +File: texinfo.info, Node: Generating HTML, Next: Command List, Prev: Creating and Installing Info Files, Up: Top + +22 Generating HTML +****************** + +`makeinfo' generates Info output by default, but given the `--html' +option, it will generate HTML, for web browsers and other programs. +This chapter gives some details on such HTML output. + + `makeinfo' can also write in XML and Docbook format, but we do not as +yet describe these further. *Note 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. + + +File: texinfo.info, Node: HTML Translation, Next: HTML Splitting, Up: Generating HTML + +22.1 HTML Translation +===================== + +`makeinfo' will include segments of Texinfo source between `@ifhtml' +and `@end ifhtml' in the HTML output (but not any of the other +conditionals, by default). Source between `@html' and `@end html' is +passed without change to the output (i.e., suppressing the normal +escaping of input `<', `>' and `&' characters which have special +significance in HTML). *Note Conditional Commands::. + + The `--footnote-style' option is currently ignored for HTML output; +footnotes are always linked to the end of the output file. + + By default, a navigation bar is inserted at the start of each node, +analogous to Info output. The `--no-headers' option suppresses this if +used with `--no-split'. Header `<link>' elements in split output can +support info-like navigation with browsers like Lynx and Emacs W3 which +implement this HTML 1.0 feature. + + The HTML generated is mostly standard (i.e., HTML 2.0, RFC-1866). +One exception is that HTML 3.2 tables are generated from the +`@multitable' command, but tagged to degrade as well as possible in +browsers without table support. The HTML 4 `lang' attribute on the +`<html>' attribute is also used. (Please report output from an +error-free run of `makeinfo' which has browser portability problems as +a bug.) + + +File: texinfo.info, Node: HTML Splitting, Next: HTML CSS, Prev: HTML Translation, Up: Generating HTML + +22.2 HTML Splitting +=================== + +When splitting output (which is the default), `makeinfo' writes HTML +output into (generally) one output file per Texinfo source `@node'. + + The output file name is the node name with special characters replaced +by `-''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 `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: + 1. `makeinfo' first tries the subdirectory with the base name from + `@setfilename' (that is, any extension is removed). For example, + HTML output for `@setfilename gcc.info' would be written into a + subdirectory named `gcc'. + + 2. If that directory cannot be created for any reason, then + `makeinfo' tries appending `.html' to the directory name. For + example, output for `@setfilename texinfo' would be written to + `texinfo.html'. + + 3. If the `NAME.html' directory can't be created either, `makeinfo' + gives up. + + +In any case, the top-level output file within the directory is always +named `index.html'. + + Monolithic output (`--no-split') is named according to `@setfilename' +(with any `.info' extension is replaced with `.html') or `--output' +(the argument is used literally). + + +File: texinfo.info, Node: HTML CSS, Next: HTML Xref, Prev: HTML Splitting, Up: Generating HTML + +22.3 HTML CSS +============= + +Cascading Style Sheets (CSS for short) is an Internet standard for +influencing the display of HTML documents: see +`http://www.w3.org/Style/CSS/'. + + By default, `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: + + pre.display { font-family:inherit } + pre.smalldisplay { font-family:inherit; font-size:smaller } + + 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 `@smalldisplay' text, and to +use the `inherited' font (generally a regular roman typeface) for both +`@smalldisplay' and `@display'. By default, the HTML `<pre>' command +uses a monospaced font. + + You can influence the CSS in the HTML output with the +`--css-include=FILE' option to `makeinfo'. This includes the contents +FILE in the HTML output, as you might expect. However, the details are +somewhat tricky, as described in the following, to provide maximum +flexibility. + + The CSS file may begin with so-called `@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 `makeinfo' handles them. + + There can be more than one `@import', but they have to come first in +the file, with only whitespace and comments interspersed, no normal +definitions. (Technical exception: an `@charset' directive may precede +the `@import''s. This does not alter `makeinfo''s behavior, it just +copies the `@charset' if present.) Comments in CSS files are delimited +by `/* ... */', as in C. An `@import' directive must be in one of +these two forms: + + @import url(http://example.org/foo.css); + @import "http://example.net/bar.css"; + + As far as `makeinfo' is concerned, the crucial characters are the `@' +at the beginning and the semicolon terminating the directive. When +reading the CSS file, it simply copies any such `@'-directive into the +output, as follows: + + * If FILE contains only normal CSS declarations, it is included + after `makeinfo''s default CSS, thus overriding it. + + * If FILE begins with `@import' specifications (see below), then the + `import''s are included first (they have to come first, according + to the standard), and then `makeinfo''s default CSS is included. + If you need to override `makeinfo''s defaults from an `@import', + you can do so with the `! important' CSS construct, as in: + pre.smallexample { font-size: inherit ! important } + + * If FILE contains both `@import' and inline CSS specifications, the + `@import''s are included first, then `makeinfo''s defaults, and + lastly the inline CSS from FILE. + + * Any @-directive other than `@import' and `@charset' is treated as + a CSS declaration, meaning `makeinfo' includes its default CSS and + then the rest of the file. + + + If the CSS file is malformed or erroneous, `makeinfo''s output is +unspecified. `makeinfo' does not try to interpret the meaning of the +CSS file in any way; it just looks for the special `@' and `;' +characters and blindly copies the text into the output. Comments in +the CSS file may or may not be included in the output. + + +File: texinfo.info, Node: HTML Xref, Prev: HTML CSS, Up: Generating HTML + +22.4 HTML Cross-references +========================== + +Cross-references between Texinfo manuals in HTML format amount, in the +end, to a standard HTML `<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 `texi2html', by +writing mutually compatible HTML files. + + This algorithm may or may not be used for links _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 "monolithic" (mono) manual is entirely +contained in one file, and a "split" manual has a file for each node. +(*Note HTML Splitting::.) + + 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. + + +File: texinfo.info, Node: HTML Xref Link Basics, Next: HTML Xref Node Name Expansion, Up: HTML Xref + +22.4.1 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 `http' protocol. For example: + + http://HOST/DIR/FILE.html#TARGET + + The information to construct a link comes from the node name and +manual name in the cross-reference command in the Texinfo source (*note +Cross References::), and from "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 HOST is hardwired to be the local host. This could either be the +literal string `localhost', or, according to the rules for HTML links, +the `http://localhost/' could be omitted entirely. + + The DIR and 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 each manual is +either available as a monolithic file `manual.html', or a split +subdirectory `manual/*.html'. Here are the cases: + + * If the present manual is split, and the referent manual is also + split, the directory is `../REFERENT/' and the file is the + expanded node name (described later). + + * If the present manual is split, and the referent manual is mono, + the directory is `../' and the file is `REFERENT.html'. + + * If the present manual is mono, and the referent manual is split, + the directory is `REFERENT/' and the file is the expanded node + name. + + * If the present manual is mono, and the referent manual is also + mono, the directory is `./' (or just the empty string), and the + file is `REFERENT.html'. + + + Any directory part in the filename argument of the source +cross-reference command is ignored. Thus, `@xref{,,,../foo}' and +`@xref{,,,foo}' both use `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 TARGET part is always the expanded node name. + + Whether the present manual is split or mono is determined by user +option; `makeinfo' defaults to split, with the `--no-split' option +overriding this. + + Whether the referent manual is split or mono is another bit of the +external information. For now, `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. *Note HTML Xref Mismatch::. + + +File: texinfo.info, Node: HTML Xref Node Name Expansion, Next: HTML Xref Command Expansion, Prev: HTML Xref Link Basics, Up: HTML Xref + +22.4.2 HTML Cross-reference Node Name Expansion +----------------------------------------------- + +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 HTML identifiers and +filenames. The restrictions are similar for each: plain ASCII letters, +numbers, and the `-' and `_' characters are all that can be used. + + Cross-references in Texinfo can actually refer either to nodes or +anchors (*note 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 +`makeinfo' for HTML cross-references. See the next section.) + + A special exception: the Top node (*note The Top Node::) is always +mapped to the file `index.html', to match web server software. +However, the HTML _target_ is `Top'. Thus (in the split case): + @xref{Top, Introduction,, emacs, The GNU Emacs Manual}. + => <a href="emacs/index.html#Top"> + + 1. The standard ASCII letters (a-z and A-z), and numbers (0-9) are not + modified. All other characters are changed as specified below. + + 2. 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.) + + 3. Leading and trailing spaces are removed. + + 4. After the above has been applied, each remaining space character is + converted into a `-' character. + + 5. Other ASCII 7-bit characters are transformed into `_00XX', where + XX is the ASCII character code in (lowercase) hexadecimal. This + includes `_', which is mapped to `_005f'. + + + For example: + + @node A node --- with _'% + => A-node-_002d_002d_002d-with-_005f_0027_0025 + + Notice in particular: + + * `_' => `_005f' + + * `-' => `_002d' + + * `A node' => `A-node' + + 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 +`index.html'. Thus, on a case-folding system, Top and a node named +`Index' will both be written to `index.html'. + + Fortunately, the targets serve to distinguish these cases, since HTML +target names are always case-sensitive, independent of operating system. + + +File: texinfo.info, Node: HTML Xref Command Expansion, Next: HTML Xref 8-bit Character Expansion, Prev: HTML Xref Node Name Expansion, Up: HTML Xref + +22.4.3 HTML Cross-reference Command Expansion +--------------------------------------------- + +In standard Texinfo, node names may not contain @-commands. `makeinfo' +has an option `--commands-in-node-names' which partially supports it +(*note Invoking makeinfo::), but it is not robust and not recommended. + + Thus, `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 `@value' commands (*note set value::) and macro invocations +(*note 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: + @asis @b @cite @code @command @dfn @dmn @dotless + @emph @env @file @indicateurl @kbd @key + @samp @sc @strong @t @var @w + +For `@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 `@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+XXXX' means Unicode code point XXXX. There are further +transformations of many of these expansions for the final file or +target name, such as space characters to `-', etc., according to the +other rules. + +`@(newline)' (space) +`@(space)' (space) +`@(tab)' (space) +`@!' `!' +`@*' (space) +`@-' (nothing) +`@.' `.' +`@:' (nothing) +`@?' `?' +`@@' `@' +`@{' `{' +`@}' `}' +`@LaTeX' `LaTeX' +`@TeX' `TeX' +`@bullet' U+2022 +`@comma' `,' +`@copyright' U+00A9 +`@dots' U+2026 +`@enddots' `...' +`@equiv' U+2261 +`@error' `error-->' +`@exclamdown' U+00A1 +`@expansion' U+2192 +`@minus' U+2212 +`@ordf' U+00AA +`@ordm' U+00BA +`@point' U+2217 +`@pounds' U+00A3 +`@print' `-|' +`@questiondown' U+00BF +`@registeredsymbol' U+00AE +`@result' U+21D2 +`@tie' (space) + + An `@acronym' command is replaced by the first argument, followed by +the second argument in parentheses, if present. *Note acronym::. + + An `@email' command is replaced by the TEXT argument if present, else +the address. *Note email::. + + An `@image' command is replaced by the filename (first) argument. +*Note Images::. + + A `@verb' command is replaced by its transformed argument. *Note +verb::. + + Any other command is an error, and the result is unspecified. + + +File: texinfo.info, Node: HTML Xref 8-bit Character Expansion, Next: HTML Xref Mismatch, Prev: HTML Xref Command Expansion, Up: HTML Xref + +22.4.4 HTML Cross-reference 8-bit Character Expansion +----------------------------------------------------- + +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.) + + These will then be further transformed by the rules above into the +string `_XXXX', where XXXX is the code point in hex. + + For example, combining this rule and the previous section: + + @node @b{A} @TeX{} @u{B} @point{}@enddots{} + => A-TeX-B_0306-_2605_002e_002e_002e + + Notice: 1) `@enddots' expands to three periods which in turn expands +to three `_002e''s; 2) `@u{B}' is a `B' with a breve accent, which does +not exist as a pre-accented Unicode character, therefore expands to +`B_0306' (B with combining breve). + + For the definition of Unicode Normalization Form C, see Unicode report +UAX#15, `http://www.unicode.org/reports/tr15/'. Many related documents +and implementations are available elsewhere on the web. + + +File: texinfo.info, Node: HTML Xref Mismatch, Prev: HTML Xref 8-bit Character Expansion, Up: HTML Xref + +22.4.5 HTML Cross-reference Mismatch +------------------------------------ + +As mentioned earlier (*note 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 `manual/' +subdirectory full of HTML files which redirect back to the monolithic +`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 `manual.html' to the +different `manual/node.html' files. Here's an example: + + function redirect() { + switch (location.hash) { + case "#Node1": + location.replace("manual/Node1.html#Node1"); break; + case "#Node2" : + location.replace("manual/Node2.html#Node2"); break; + ... + default:; + } + } + + Then, in the `<body>' tag of `manual.html': + + <body onLoad="redirect();"> + + Once again, this is something the software which generated the +_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. + + +File: texinfo.info, Node: Command List, Next: Tips, Prev: Generating HTML, Up: Top + +Appendix A @-Command List +************************* + +Here is an alphabetical list of the @-commands in Texinfo. Square +brackets, [ ], indicate optional arguments; an ellipsis, `...', +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. + + +`@WHITESPACE' + An `@' followed by a space, tab, or newline produces a normal, + stretchable, interword space. *Note Multiple Spaces::. + +`@!' + Generate an exclamation point that really does end a sentence + (usually after an end-of-sentence capital letter). *Note Ending a + Sentence::. + +`@"' +`@'' + Generate an umlaut or acute accent, respectively, over the next + character, as in o" and o'. *Note Inserting Accents::. + +`@*' + Force a line break. *Note Line Breaks::. + +`@,{C}' + Generate a cedilla accent under C, as in c,. *Note Inserting + Accents::. + +`@-' + Insert a discretionary hyphenation point. *Note - and + hyphenation::. + +`@.' + Produce a period that really does end a sentence (usually after an + end-of-sentence capital letter). *Note Ending a Sentence::. + +`@/' + Produces no output, but allows a line break. *Note Line Breaks::. + +`@:' + Indicate to TeX that an immediately preceding period, question + mark, exclamation mark, or colon does not end a sentence. Prevent + TeX from inserting extra whitespace as it does at the end of a + sentence. The command has no effect on the Info file output. + *Note Not Ending a Sentence::. + +`@=' + Generate a macron (bar) accent over the next character, as in o=. + *Note Inserting Accents::. + +`@?' + Generate a question mark that really does end a sentence (usually + after an end-of-sentence capital letter). *Note Ending a + Sentence::. + +`@@' + Stands for an at sign, `@'. *Note Inserting @ and {} and ,: + Atsign Braces Comma. + +`@\' + Stands for a backslash (`\') inside `@math'. *Note `math': math. + +`@^' +`@`' + Generate a circumflex (hat) or grave accent, respectively, over + the next character, as in o^ and e`. *Note Inserting Accents::. + +`@{' + Stands for a left brace, `{'. *Note Inserting @ and {} and ,: + Atsign Braces Comma. + +`@}' + Stands for a right-hand brace, `}'. + *Note Inserting @ and {} and ,: Atsign Braces Comma. + +`@~' + Generate a tilde accent over the next character, as in N~. *Note + Inserting Accents::. + +`@AA{}' +`@aa{}' + Generate the uppercase and lowercase Scandinavian A-ring letters, + respectively: AA, aa. *Note Inserting Accents::. + +`@acronym{ABBREV}' + Tag ABBREV as an acronym, that is, an abbreviation written in all + capital letters, such as `NASA'. *Note `acronym': acronym. + +`@AE{}' +`@ae{}' + Generate the uppercase and lowercase AE ligatures, respectively: + AE, ae. *Note Inserting Accents::. + +`@afivepaper' + Change page dimensions for the A5 paper size. *Note A4 Paper::. + +`@afourlatex' +`@afourpaper' +`@afourwide' + Change page dimensions for the A4 paper size. *Note A4 Paper::. + +`@alias NEW=EXISTING' + Make the command `@NEW' an alias for the existing command + `@EXISTING'. *Note alias::. + +`@anchor{NAME}' + Define NAME as the current location for use as a cross-reference + target. *Note `@anchor': anchor. + +`@appendix TITLE' + Begin an appendix. The title appears in the table of contents of + a printed manual. In Info, the title is underlined with + asterisks. *Note The `@unnumbered' and `@appendix' Commands: + unnumbered & appendix. + +`@appendixsec TITLE' +`@appendixsection 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. `@appendixsection' is a + longer spelling of the `@appendixsec' command. *Note Section + Commands: unnumberedsec appendixsec heading. + +`@appendixsubsec 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. *Note Subsection Commands: + unnumberedsubsec appendixsubsec subheading. + +`@appendixsubsubsec 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. *Note The `subsub' + Commands: subsubsection. + +`@asis' + Used following `@table', `@ftable', and `@vtable' to print the + table's first column without highlighting ("as is"). *Note Making + a Two-column Table: Two-column Tables. + +`@author AUTHOR' + Typeset AUTHOR flushleft and underline it. *Note The `@title' and + `@author' Commands: title subtitle author. + +`@b{TEXT}' + Print TEXT in bold font. No effect in Info. *Note Fonts::. + +`@bullet{}' + Generate a large round dot, or the closest possible thing to one. + *Note `@bullet': bullet. + +`@bye' + Stop formatting a file. The formatters do not see the contents of + a file following an `@bye' command. *Note Ending a File::. + +`@c 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 + `@comment'. *Note Comments::. + +`@caption' + Define the full caption for a `@float'. *Note caption + shortcaption::. + +`@cartouche' + Highlight an example or quotation by drawing a box with rounded + corners around it. Pair with `@end cartouche'. No effect in + Info. *Note Drawing Cartouches Around Examples: cartouche.) + +`@center LINE-OF-TEXT' + Center the line of text following the command. *Note `@center': + titlefont center sp. + +`@centerchap LINE-OF-TEXT' + Like `@chapter', but centers the chapter title. *Note `@chapter': + chapter. + +`@chapheading 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. *Note `@majorheading' and `@chapheading': + majorheading & chapheading. + +`@chapter 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. *Note `@chapter': chapter. + +`@cindex ENTRY' + Add ENTRY to the index of concepts. *Note Defining the Entries of + an Index: Index Entries. + +`@cite{REFERENCE}' + Highlight the name of a book or other reference that lacks a + companion Info file. *Note `@cite': cite. + +`@clear FLAG' + Unset FLAG, preventing the Texinfo formatting commands from + formatting text between subsequent pairs of `@ifset FLAG' and + `@end ifset' commands, and preventing `@value{FLAG}' from + expanding to the value to which FLAG is set. *Note `@set' + `@clear' `@value': set clear value. + +`@code{SAMPLE-CODE}' + Highlight text that is an expression, a syntactically complete + token of a program, or a program name. *Note `@code': code. + +`@comma{}' + Insert a comma `,' character; only needed when a literal comma + would be taken as an argument separator. *Note Inserting a + Comma::. + +`@command{COMMAND-NAME}' + Indicate a command name, such as `ls'. *Note `@command': command. + +`@comment 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 `@c'. + *Note Comments::. + +`@contents' + Print a complete table of contents. Has no effect in Info, which + uses menus instead. *Note Generating a Table of Contents: + Contents. + +`@copyright{}' + Generate the copyright symbol (C). *Note `@copyright{}': + copyright symbol. + +`@defcodeindex INDEX-NAME' + Define a new index and its indexing command. Print entries in an + `@code' font. *Note Defining New Indices: New Indices. + +`@defcv CATEGORY CLASS NAME' +`@defcvx CATEGORY CLASS 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. *Note Definition Commands::, and *Note Def Cmds in Detail: + deffnx. + +`@deffn CATEGORY NAME ARGUMENTS...' +`@deffnx CATEGORY NAME ARGUMENTS...' + Format a description for a function, interactive command, or + similar entity that may take arguments. `@deffn' takes as + arguments the category of entity being described, the name of this + particular entity, and its arguments, if any. *Note Definition + Commands::. + +`@defindex INDEX-NAME' + Define a new index and its indexing command. Print entries in a + roman font. *Note Defining New Indices: New Indices. + +`@definfoenclose NEWCMD, BEFORE, AFTER,' + Create new @-command NEWCMD for Info that marks text by enclosing + it in strings that precede and follow the text. *Note + definfoenclose::. + +`@defivar CLASS INSTANCE-VARIABLE-NAME' +`@defivarx CLASS INSTANCE-VARIABLE-NAME' + This command formats a description for an instance variable in + object-oriented programming. The command is equivalent to `@defcv + {Instance Variable} ...'. *Note Definition Commands::, and *Note + Def Cmds in Detail: deffnx. + +`@defmac MACRONAME ARGUMENTS...' +`@defmacx MACRONAME ARGUMENTS...' + Format a description for a macro. The command is equivalent to + `@deffn Macro ...'. *Note Definition Commands::, and *Note Def + Cmds in Detail: deffnx. + +`@defmethod CLASS METHOD-NAME ARGUMENTS...' +`@defmethodx CLASS METHOD-NAME ARGUMENTS...' + Format a description for a method in object-oriented programming. + The command is equivalent to `@defop Method ...'. Takes as + arguments the name of the class of the method, the name of the + method, and its arguments, if any. *Note Definition Commands::, + and *Note Def Cmds in Detail: deffnx. + +`@defop CATEGORY CLASS NAME ARGUMENTS...' +`@defopx CATEGORY CLASS NAME ARGUMENTS...' + Format a description for an operation in object-oriented + programming. `@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. *Note + Definition Commands::, and *Note Abstract Objects::. + +`@defopt OPTION-NAME' +`@defoptx OPTION-NAME' + Format a description for a user option. The command is equivalent + to `@defvr {User Option} ...'. *Note Definition Commands::, and + *Note Def Cmds in Detail: deffnx. + +`@defspec SPECIAL-FORM-NAME ARGUMENTS...' +`@defspecx SPECIAL-FORM-NAME ARGUMENTS...' + Format a description for a special form. The command is + equivalent to `@deffn {Special Form} ...'. *Note Definition + Commands::, and *Note Def Cmds in Detail: deffnx. + +`@deftp CATEGORY NAME-OF-TYPE ATTRIBUTES...' +`@deftpx CATEGORY NAME-OF-TYPE ATTRIBUTES...' + Format a description for a data type. `@deftp' takes as arguments + the category, the name of the type (which is a word like `int' or + `float'), and then the names of attributes of objects of that type. + *Note Definition Commands::, and *Note Data Types::. + +`@deftypecv CATEGORY CLASS DATA-TYPE NAME' +`@deftypecvx CATEGORY CLASS DATA-TYPE NAME' + Format a description for a typed class variable in object-oriented + programming. *Note Definition Commands::, and *Note Abstract + Objects::. + +`@deftypefn CLASSIFICATION DATA-TYPE NAME ARGUMENTS...' +`@deftypefnx CLASSIFICATION DATA-TYPE NAME ARGUMENTS...' + Format a description for a function or similar entity that may take + arguments and that is typed. `@deftypefn' takes as arguments the + classification of entity being described, the type, the name of the + entity, and its arguments, if any. *Note Definition Commands::, + and *Note Def Cmds in Detail: deffnx. + +`@deftypefun DATA-TYPE FUNCTION-NAME ARGUMENTS...' +`@deftypefunx DATA-TYPE FUNCTION-NAME ARGUMENTS...' + Format a description for a function in a typed language. The + command is equivalent to `@deftypefn Function ...'. *Note + Definition Commands::, and *Note Def Cmds in Detail: deffnx. + +`@deftypeivar CLASS DATA-TYPE VARIABLE-NAME' +`@deftypeivarx CLASS DATA-TYPE VARIABLE-NAME' + Format a description for a typed instance variable in + object-oriented programming. *Note Definition Commands::, and + *Note Abstract Objects::. + +`@deftypemethod CLASS DATA-TYPE METHOD-NAME ARGUMENTS...' +`@deftypemethodx CLASS DATA-TYPE METHOD-NAME ARGUMENTS...' + Format a description for a typed method in object-oriented + programming. *Note Definition Commands::, and *Note Def Cmds in + Detail: deffnx. + +`@deftypeop CATEGORY CLASS DATA-TYPE NAME ARGUMENTS...' +`@deftypeopx CATEGORY CLASS DATA-TYPE NAME ARGUMENTS...' + Format a description for a typed operation in object-oriented + programming. *Note Definition Commands::, and *Note Abstract + Objects::. + +`@deftypevar DATA-TYPE VARIABLE-NAME' +`@deftypevarx DATA-TYPE VARIABLE-NAME' + Format a description for a variable in a typed language. The + command is equivalent to `@deftypevr Variable ...'. *Note + Definition Commands::, and *Note Def Cmds in Detail: deffnx. + +`@deftypevr CLASSIFICATION DATA-TYPE NAME' +`@deftypevrx CLASSIFICATION DATA-TYPE 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. *Note Definition Commands::, and *Note Def Cmds in + Detail: deffnx. + +`@defun FUNCTION-NAME ARGUMENTS...' +`@defunx FUNCTION-NAME ARGUMENTS...' + Format a description for functions. The command is equivalent to + `@deffn Function ...'. *Note Definition Commands::, and *Note Def + Cmds in Detail: deffnx. + +`@defvar VARIABLE-NAME' +`@defvarx VARIABLE-NAME' + Format a description for variables. The command is equivalent to + `@defvr Variable ...'. *Note Definition Commands::, and *Note Def + Cmds in Detail: deffnx. + +`@defvr CATEGORY NAME' +`@defvrx CATEGORY NAME' + Format a description for any kind of variable. `@defvr' takes as + arguments the category of the entity and the name of the entity. + *Note Definition Commands::, and *Note Def Cmds in Detail: deffnx. + +`@detailmenu' + Avoid `makeinfo' confusion stemming from the detailed node listing + in a master menu. *Note Master Menu Parts::. + +`@dfn{TERM}' + Highlight the introductory or defining use of a term. *Note + `@dfn': dfn. + +`@dircategory DIRPART' + Specify a part of the Info directory menu where this file's entry + should go. *Note Installing Dir Entries::. + +`@direntry' + Begin the Info directory menu entry for this file. Pair with + `@end direntry'. *Note Installing Dir Entries::. + +`@display' + Begin a kind of example. Like `@example' (indent text, do not + fill), but do not select a new font. Pair with `@end display'. + *Note `@display': display. + +`@dmn{DIMENSION}' + Format a unit of measure, as in 12pt. Causes TeX to insert a thin + space before DIMENSION. No effect in Info. *Note `@dmn': dmn. + +`@docbook' + Enter Docbook completely. Pair with `@end docbook'. *Note Raw + Formatter Commands::. + +`@documentdescription' + Set the document description text, included in the HTML output. + Pair with `@end documentdescription'. *Note + `@documentdescription': documentdescription. + +`@documentencoding ENC' + Declare the input encoding to be ENC. *Note `@documentencoding': + documentencoding. + +`@documentlanguage CC' + Declare the document language as the two-character ISO-639 + abbreviation CC. *Note `@documentlanguage': documentlanguage. + +`@dotaccent{C}' + Generate a dot accent over the character C, as in o.. *Note + Inserting Accents::. + +`@dots{}' + Insert an ellipsis: `...'. *Note `@dots': dots. + +`@email{ADDRESS[, DISPLAYED-TEXT]}' + Indicate an electronic mail address. *Note `@email': email. + +`@emph{TEXT}' + Highlight TEXT; text is displayed in _italics_ in printed output, + and surrounded by asterisks in Info. *Note Emphasizing Text: + Emphasis. + +`@end ENVIRONMENT' + Ends ENVIRONMENT, as in `@end example'. *Note @-commands: + Formatting Commands. + +`@env{ENVIRONMENT-VARIABLE}' + Indicate an environment variable name, such as `PATH'. *Note + `@env': env. + +`@enddots{}' + Generate an end-of-sentence of ellipsis, like this .... *Note + `@dots{}': dots. + +`@enumerate [NUMBER-OR-LETTER]' + Begin a numbered list, using `@item' for each entry. Optionally, + start list with NUMBER-OR-LETTER. Pair with `@end enumerate'. + *Note `@enumerate': enumerate. + +`@equiv{}' + Indicate to the reader the exact equivalence of two forms with a + glyph: `=='. *Note Equivalence::. + +`@error{}' + Indicate to the reader with a glyph that the following text is an + error message: `error-->'. *Note Error Glyph::. + +`@evenfooting [LEFT] @| [CENTER] @| [RIGHT]' +`@evenheading [LEFT] @| [CENTER] @| [RIGHT]' + Specify page footings resp. headings for even-numbered (left-hand) + pages. *Note How to Make Your Own Headings: Custom Headings. + +`@everyfooting [LEFT] @| [CENTER] @| [RIGHT]' +`@everyheading [LEFT] @| [CENTER] @| [RIGHT]' + Specify page footings resp. headings for every page. Not relevant + to Info. *Note How to Make Your Own Headings: Custom Headings. + +`@example' + Begin an example. Indent text, do not fill, and select + fixed-width font. Pair with `@end example'. *Note `@example': + example. + +`@exampleindent INDENT' + Indent example-like environments by INDENT number of spaces + (perhaps 0). *Note Paragraph Indenting: exampleindent. + +`@exclamdown{}' + Produce an upside-down exclamation point. *Note Inserting + Accents::. + +`@exdent LINE-OF-TEXT' + Remove any indentation a line might have. *Note Undoing the + Indentation of a Line: exdent. + +`@expansion{}' + Indicate the result of a macro expansion to the reader with a + special glyph: `==>'. *Note ==> Indicating an Expansion: + expansion. + +`@file{FILENAME}' + Highlight the name of a file, buffer, node, or directory. *Note + `@file': file. + +`@finalout' + Prevent TeX from printing large black warning rectangles beside + over-wide lines. *Note Overfull hboxes::. + +`@findex ENTRY' + Add ENTRY to the index of functions. *Note Defining the Entries + of an Index: Index Entries. + +`@float' + Environment to define floating material. Pair with `@end float'. + *Note Floats::. + +`@flushleft' +`@flushright' + Left justify every line but leave the right end ragged. Leave + font as is. Pair with `@end flushleft'. `@flushright' analogous. + *Note `@flushleft' and `@flushright': flushleft & flushright. + +`@footnote{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. *Note Footnotes::. + +`@footnotestyle STYLE' + Specify an Info file's footnote style, either `end' for the end + node style or `separate' for the separate node style. *Note + Footnotes::. + +`@format' + Begin a kind of example. Like `@display', but do not narrow the + margins. Pair with `@end format'. *Note `@example': example. + +`@ftable FORMATTING-COMMAND' + Begin a two-column table, using `@item' for each entry. + Automatically enter each of the items in the first column into the + index of functions. Pair with `@end ftable'. The same as + `@table', except for indexing. *Note `@ftable' and `@vtable': + ftable vtable. + +`@group' + Hold text together that must appear on one printed page. Pair with + `@end group'. Not relevant to Info. *Note `@group': group. + +`@H{C}' + Generate the long Hungarian umlaut accent over C, as in o''. + +`@heading 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. *Note Section Commands: + unnumberedsec appendixsec heading. + +`@headings ON-OFF-SINGLE-DOUBLE' + Turn page headings on or off, and/or specify single-sided or + double-sided page headings for printing. *Note The `@headings' + Command: headings on off. + +`@html' + Enter HTML completely. Pair with `@end html'. *Note Raw + Formatter Commands::. + +`@hyphenation{HY-PHEN-A-TED WORDS}' + Explicitly define hyphenation points. *Note `@-' and + `@hyphenation': - and hyphenation. + +`@i{TEXT}' + Print TEXT in italic font. No effect in Info. *Note Fonts::. + +`@ifclear FLAG' + If FLAG is cleared, the Texinfo formatting commands format text + between `@ifclear FLAG' and the following `@end ifclear' command. + *Note `@set' `@clear' `@value': set clear value. + +`@ifdocbook' +`@ifhtml' +`@ifinfo' + Begin text that will appear only in the given output format. + `@ifinfo' output appears in both Info and (for historical + compatibility) plain text output. Pair with `@end ifdocbook' + resp. `@end ifhtml' resp. `@end ifinfo'. *Note Conditionals::. + +`@ifnotdocbook' +`@ifnothtml' +`@ifnotinfo' +`@ifnotplaintext' +`@ifnottex' +`@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: + `@ifnothtml' text is omitted from html output, etc. The exception + is `@ifnotinfo' text, which is omitted from plain text output as + well as Info output. Pair with the corresponding `@end + ifnotFORMAT'. *Note Conditionals::. + +`@ifplaintext' + Begin text that will appear only in the plain text output. Pair + with `@end ifplaintext'. *Note Conditionals::. + +`@ifset FLAG' + If FLAG is set, the Texinfo formatting commands format text + between `@ifset FLAG' and the following `@end ifset' command. + *Note `@set' `@clear' `@value': set clear value. + +`@iftex' + Begin text that will not appear in the Info file or other output, + but will be processed only by TeX. Pair with `@end iftex'. *Note + Conditionally Visible Text: Conditionals. + +`@ifxml' + Begin text that will appear only in the XML output. Pair with + `@end ifxml'. *Note Conditionals::. + +`@ignore' + Begin text that will not appear in any output. Pair with `@end + ignore'. *Note Comments and Ignored Text: Comments. + +`@image{FILENAME, [WIDTH], [HEIGHT], [ALT], [EXT]}' + Include graphics image in external FILENAME scaled to the given + WIDTH and/or HEIGHT, using ALT text and looking for `FILENAME.EXT' + in HTML. *Note Images::. + +`@include FILENAME' + Incorporate the contents of the file FILENAME into the Info file + or printed document. *Note Include Files::. + +`@indicateurl{INDICATEURL}' + Indicate text that is a uniform resource locator for the World Wide + Web. *Note `@indicateurl': indicateurl. + +`@inforef{NODE-NAME, [ENTRY-NAME], INFO-FILE-NAME}' + Make a cross reference to an Info file for which there is no + printed manual. *Note Cross references using `@inforef': inforef. + +`\input 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 `texinfo' macro definitions file. The backslash in `\input' + is used instead of an `@' because TeX does not recognize `@' until + after it has read the definitions file. *Note Texinfo File + Header::. + +`@item' + Indicate the beginning of a marked paragraph for `@itemize' and + `@enumerate'; indicate the beginning of the text of a first column + entry for `@table', `@ftable', and `@vtable'. *Note Lists and + Tables::. + +`@itemize 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 `@end + itemize'. *Note `@itemize': itemize. + +`@itemx' + Like `@item' but do not generate extra vertical space above the + item text. *Note `@itemx': itemx. + +`@kbd{KEYBOARD-CHARACTERS}' + Indicate text that is characters of input to be typed by users. + *Note `@kbd': kbd. + +`@kbdinputstyle STYLE' + Specify when `@kbd' should use a font distinct from `@code'. + *Note `@kbd': kbd. + +`@key{KEY-NAME}' + Indicate a name for a key on a keyboard. *Note `@key': key. + +`@kindex ENTRY' + Add ENTRY to the index of keys. *Note Defining the Entries of an + Index: Index Entries. + +`@L{}' +`@l{}' + Generate the uppercase and lowercase Polish suppressed-L letters, + respectively: /L, /l. + +`@LaTeX{}' + Insert the logo LaTeX. *Note TeX and LaTeX: tex. + +`@lisp' + Begin an example of Lisp code. Indent text, do not fill, and + select fixed-width font. Pair with `@end lisp'. *Note `@lisp': + lisp. + +`@listoffloats' + Produce a table-of-contents-like listing of `@float's. *Note + listoffloats::. + +`@lowersections' + Change subsequent chapters to sections, sections to subsections, + and so on. *Note `@raisesections' and `@lowersections': + Raise/lower sections. + +`@macro MACRONAME {PARAMS}' + Define a new Texinfo command `@MACRONAME{PARAMS}'. Only supported + by `makeinfo' and `texi2dvi'. *Note Defining Macros::. + +`@majorheading 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 `@chapheading' command. *Note + `@majorheading' and `@chapheading': majorheading & chapheading. + +`@math{MATHEMATICAL-EXPRESSION}' + Format a mathematical expression. *Note `@math': Inserting + Mathematical Expressions: math. + +`@menu' + Mark the beginning of a menu of nodes in Info. No effect in a + printed manual. Pair with `@end menu'. *Note Menus::. + +`@minus{}' + Generate a minus sign, `-'. *Note `@minus': minus. + +`@multitable COLUMN-WIDTH-SPEC' + Begin a multi-column table. Pair with `@end multitable'. *Note + Multitable Column Widths::. + +`@need N' + Start a new page in a printed manual if fewer than N mils + (thousandths of an inch) remain on the current page. *Note + `@need': need. + +`@node NAME, NEXT, PREVIOUS, UP' + Define the beginning of a new node in Info, and serve as a locator + for references for TeX. *Note `@node': node. + +`@noindent' + Prevent text from being indented as if it were a new paragraph. + *Note `@noindent': noindent. + +`@novalidate' + Suppress validation of node references, omit creation of auxiliary + files with TeX. Use before `@setfilename'. *Note Pointer + Validation::. + +`@O{}' +`@o{}' + Generate the uppercase and lowercase O-with-slash letters, + respectively: /O, /o. + +`@oddfooting [LEFT] @| [CENTER] @| [RIGHT]' +`@oddheading [LEFT] @| [CENTER] @| [RIGHT]' + Specify page footings resp. headings for odd-numbered (right-hand) + pages. *Note How to Make Your Own Headings: Custom Headings. + +`@OE{}' +`@oe{}' + Generate the uppercase and lowercase OE ligatures, respectively: + OE, oe. *Note Inserting Accents::. + +`@option{OPTION-NAME}' + Indicate a command-line option, such as `-l' or `--help'. *Note + `@option': option. + +`@page' + Start a new page in a printed manual. No effect in Info. *Note + `@page': page. + +`@pagesizes [WIDTH][, HEIGHT]' + Change page dimensions. *Note pagesizes::. + +`@paragraphindent INDENT' + Indent paragraphs by INDENT number of spaces (perhaps 0); preserve + source file indentation if INDENT is `asis'. *Note Paragraph + Indenting: paragraphindent. + +`@pindex ENTRY' + Add ENTRY to the index of programs. *Note Defining the Entries of + an Index: Index Entries. + +`@point{}' + Indicate the position of point in a buffer to the reader with a + glyph: `-!-'. *Note Indicating Point in a Buffer: Point Glyph. + +`@pounds{}' + Generate the pounds sterling currency sign. *Note `@pounds{}': + pounds. + +`@print{}' + Indicate printed output to the reader with a glyph: `-|'. *Note + Print Glyph::. + +`@printindex INDEX-NAME' + Print an alphabetized two-column index in a printed manual or + generate an alphabetized menu of index entries for Info. *Note + Printing Indices & Menus::. + +`@pxref{NODE-NAME, [ENTRY], [TOPIC-OR-TITLE], [INFO-FILE], [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. *Note `@pxref': pxref. + +`@questiondown{}' + Generate an upside-down question mark. *Note Inserting Accents::. + +`@quotation' + Narrow the margins to indicate text that is quoted from another + real or imaginary work. Takes optional argument of prefix text. + Pair with `@end quotation'. *Note `@quotation': quotation. + +`@r{TEXT}' + Print TEXT in roman font. No effect in Info. *Note Fonts::. + +`@raisesections' + Change subsequent sections to chapters, subsections to sections, + and so on. *Note `@raisesections' and `@lowersections': + Raise/lower sections. + +`@ref{NODE-NAME, [ENTRY], [TOPIC-OR-TITLE], [INFO-FILE], [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. *Note `@ref': ref. + +`@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. + +`@registeredsymbol{}' + Generate the legal symbol (R). *Note `@registeredsymbol{}': + registered symbol. + +`@result{}' + Indicate the result of an expression to the reader with a special + glyph: `=>'. *Note `@result': result. + +`@ringaccent{C}' + Generate a ring accent over the next character, as in o*. *Note + Inserting Accents::. + +`@samp{TEXT}' + Highlight TEXT that is a literal example of a sequence of + characters. Used for single characters, for statements, and often + for entire shell commands. *Note `@samp': samp. + +`@sc{TEXT}' + Set TEXT in a printed output in THE SMALL CAPS FONT and set text + in the Info file in uppercase letters. *Note Smallcaps::. + +`@section 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. *Note `@section': + section. + +`@set FLAG [STRING]' + Make FLAG active, causing the Texinfo formatting commands to + format text between subsequent pairs of `@ifset FLAG' and `@end + ifset' commands. Optionally, set value of FLAG to STRING. *Note + `@set' `@clear' `@value': set clear value. + +`@setchapternewpage ON-OFF-ODD' + Specify whether chapters start on new pages, and if so, whether on + odd-numbered (right-hand) new pages. *Note `@setchapternewpage': + setchapternewpage. + +`@setcontentsaftertitlepage' + Put the table of contents after the `@end titlepage' even if the + `@contents' command is not there. *Note Contents::. + +`@setfilename 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. *Note `@setfilename': setfilename. + +`@setshortcontentsaftertitlepage' + Place the short table of contents after the `@end titlepage' + command even if the `@shortcontents' command is not there. *Note + Contents::. + +`@settitle TITLE' + Provide a title for page headers in a printed manual, and the + default document description for HTML `<head>'. *Note + `@settitle': settitle. + +`@shortcaption' + Define the short caption for a `@float'. *Note caption + shortcaption::. + +`@shortcontents' + Print a short table of contents. Not relevant to Info, which uses + menus rather than tables of contents. A synonym for + `@summarycontents'. *Note Generating a Table of Contents: + Contents. + +`@shorttitlepage TITLE' + Generate a minimal title page. *Note `@titlepage': titlepage. + +`@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. *Note Printing + Small Books: smallbook. Also, see *Note small::. + +`@smalldisplay' + Begin a kind of example. Like `@smallexample' (narrow margins, no + filling), but do not select the fixed-width font. Pair with `@end + smalldisplay'. *Note small::. + +`@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 `@example'. Pair with `@end + smallexample'. *Note small::. + +`@smallformat' + Begin a kind of example. Like `@smalldisplay', but do not narrow + the margins. Pair with `@end smallformat'. *Note small::. + +`@smalllisp' + Begin an example of Lisp code. Same as `@smallexample'. Pair + with `@end smalllisp'. *Note small::. + +`@sp N' + Skip N blank lines. *Note `@sp': sp. + +`@ss{}' + Generate the German sharp-S es-zet letter, ss. *Note Inserting + Accents::. + +`@strong {TEXT}' + Emphasize TEXT by typesetting it in a *bold* font for the printed + manual and by surrounding it with asterisks for Info. *Note + Emphasizing Text: emph & strong. + +`@subheading 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. *Note `@unnumberedsubsec' + `@appendixsubsec' `@subheading': unnumberedsubsec appendixsubsec + subheading. + +`@subsection 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. *Note + `@subsection': subsection. + +`@subsubheading 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. *Note The `subsub' Commands: + subsubsection. + +`@subsubsection 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. *Note + The `subsub' Commands: subsubsection. + +`@subtitle 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. *Note `@title' `@subtitle' and `@author' + Commands: title subtitle author. + +`@summarycontents' + Print a short table of contents. Not relevant to Info, which uses + menus rather than tables of contents. A synonym for + `@shortcontents'. *Note Generating a Table of Contents: Contents. + +`@syncodeindex FROM-INDEX 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' font. *Note Combining Indices::. + +`@synindex FROM-INDEX INTO-INDEX' + Merge the index named in the first argument into the index named in + the second argument. Do not change the font of FROM-INDEX + entries. *Note Combining Indices::. + +`@t{TEXT}' + Print TEXT in a fixed-width, typewriter-like font. No effect in + Info. *Note Fonts::. + +`@tab' + Separate columns in a multitable. *Note Multitable Rows::. + +`@table FORMATTING-COMMAND' + Begin a two-column table, using `@item' for each entry. Write + each first column entry on the same line as `@item'. First column + entries are printed in the font resulting from FORMATTING-COMMAND. + Pair with `@end table'. *Note Making a Two-column Table: + Two-column Tables. Also see *Note `@ftable' and `@vtable': ftable + vtable, and *Note `@itemx': itemx. + +`@TeX{}' + Insert the logo TeX. *Note TeX and LaTeX: tex. + +`@tex' + Enter TeX completely. Pair with `@end tex'. *Note Raw Formatter + Commands::. + +`@thischapter' +`@thischaptername' +`@thisfile' +`@thispage' +`@thistitle' + Only allowed in a heading or footing. Stands for the number and + name of the current chapter (in the format `Chapter 1: Title'), + the chapter name only, the filename, the current page number, and + the title of the document, respectively. *Note How to Make Your + Own Headings: Custom Headings. + +`@tie{}' + Generate a normal interword space at which a line break is not + allowed. *Note `@tie{}': tie. + +`@tieaccent{CC}' + Generate a tie-after accent over the next two characters CC, as in + `oo['. *Note Inserting Accents::. + +`@tindex ENTRY' + Add ENTRY to the index of data types. *Note Defining the Entries + of an Index: Index Entries. + +`@title 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. + *Note The `@title' `@subtitle' and `@author' Commands: title + subtitle author. + +`@titlefont{TEXT}' + In a printed manual, print TEXT in a larger than normal font. Not + relevant to Info, which does not have title pages. *Note The + `@titlefont' `@center' and `@sp' Commands: titlefont center sp. + +`@titlepage' + Indicate to Texinfo the beginning of the title page. Write + command on a line of its own. Pair with `@end titlepage'. + Nothing between `@titlepage' and `@end titlepage' appears in Info. + *Note `@titlepage': titlepage. + +`@today{}' + Insert the current date, in `1 Jan 1900' style. *Note How to Make + Your Own Headings: Custom Headings. + +`@top TITLE' + In a Texinfo file to be formatted with `makeinfo', identify the + topmost `@node' in the file, which must be written on the line + immediately preceding the `@top' command. Used for `makeinfo''s + node pointer insertion feature. The title is underlined with + asterisks. Both the `@node' line and the `@top' line normally + should be enclosed by `@ifnottex' and `@end ifnottex'. In TeX and + `texinfo-format-buffer', the `@top' command is merely a synonym + for `@unnumbered'. *Note Creating Pointers with `makeinfo': + makeinfo Pointer Creation. + +`@u{C}' +`@ubaraccent{C}' +`@udotaccent{C}' + Generate a breve, underbar, or underdot accent, respectively, over + or under the character C, as in o(, o_, .o. *Note Inserting + Accents::. + +`@unnumbered 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. *Note `@unnumbered' and `@appendix': unnumbered & + appendix. + +`@unnumberedsec 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. *Note Section Commands: unnumberedsec appendixsec heading. + +`@unnumberedsubsec 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. *Note + `@unnumberedsubsec' `@appendixsubsec' `@subheading': + unnumberedsubsec appendixsubsec subheading. + +`@unnumberedsubsubsec 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. *Note The + `subsub' Commands: subsubsection. + +`@uref{URL[, DISPLAYED-TEXT][, REPLACEMENT}' +`@url{URL[, DISPLAYED-TEXT][, REPLACEMENT}' + Define a cross reference to an external uniform resource locator + for the World Wide Web. *Note `@uref': uref. + +`@v{C}' + Generate check accent over the character C, as in o<. *Note + Inserting Accents::. + +`@value{FLAG}' + Replace FLAG with the value to which it is set by `@set FLAG'. + *Note `@set' `@clear' `@value': set clear value. + +`@var{METASYNTACTIC-VARIABLE}' + Highlight a metasyntactic variable, which is something that stands + for another piece of text. *Note Indicating Metasyntactic + Variables: var. + +`@verb{DELIM LITERAL DELIM}' + Output LITERAL, delimited by the single character DELIM, exactly + as is (in the fixed-width font), including any whitespace or + Texinfo special characters. *Note `verb': verb. + +`@verbatim' + Output the text of the environment exactly as is (in the + fixed-width font). Pair with `@end verbatim'. *Note `verbatim': + verbatim. + +`@verbatiminclude FILENAME' + Output the contents of FILENAME exactly as is (in the fixed-width + font). *Note `verbatiminclude': verbatiminclude. + +`@vindex ENTRY' + Add ENTRY to the index of variables. *Note Defining the Entries + of an Index: Index Entries. + +`@vskip 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 `0pt plus 1filll'. + (Note spelling of `filll'.) `@vskip' may be used only in + contexts ignored for Info. *Note Copyright::. + +`@vtable FORMATTING-COMMAND' + Begin a two-column table, using `@item' for each entry. + Automatically enter each of the items in the first column into the + index of variables. Pair with `@end vtable'. The same as + `@table', except for indexing. *Note `@ftable' and `@vtable': + ftable vtable. + +`@w{TEXT}' + Prevent TEXT from being split across two lines. *Note `@w': w. + +`@xml' + Enter XML completely. Pair with `@end xml'. *Note Raw Formatter + Commands::. + +`@xref{NODE-NAME, [ENTRY], [TOPIC-OR-TITLE], [INFO-FILE], [MANUAL]}' + Make a reference that starts with `See' in a printed manual. + Follow command with a punctuation mark. Only the first argument is + mandatory. *Note `@xref': xref. + + +File: texinfo.info, Node: Command Syntax, Up: Command List + +A.1 @-Command Syntax +==================== + +The character `@' is used to start special Texinfo commands. (It has +the same meaning that `\' has in plain TeX.) Texinfo has four types of +@-command: + +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, + and never take any argument. The two characters (@ and the other + one) are complete in themselves; none is followed by braces. The + non-alphabetic commands are: `@.', `@:', `@*', `@SPACE', `@TAB', + `@NL', `@@', `@{', and `@}'. + +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, + `@dots{}' => `...', `@equiv{}' => `==', `@TeX{}' => `TeX', and + `@bullet{}' => `*'. + +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 + `@dfn' indicates the introductory or defining use of a term; it is + used as follows: `In Texinfo, @@-commands are @dfn{mark-up} + commands.' + +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, + `@center' or `@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. + + 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. + + 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 `@refill', which is always used at +the end of a paragraph immediately following the final period or other +punctuation character. `@refill' takes no argument and does _not_ +require braces. `@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. + + +File: texinfo.info, Node: Tips, Next: Sample Texinfo Files, Prev: Command List, Up: Top + +Appendix B Tips and Hints +************************* + +Here are some tips for writing Texinfo documentation: + + * Write in the present tense, not in the past or the future. + + * Write actively! For example, write "We recommend that ..." rather + than "It is recommended that ...". + + * Use 70 or 72 as your fill column. Longer lines are hard to read. + + * Include a copyright notice and copying permissions. + +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: + + * Write each index entry differently, so each entry refers to a + different place in the document. + + * 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. + + * 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. + + * 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. + + * 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": + + @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. + + (Note that the example shows entries for the same concept that are + written in different ways--`Lazy dog', and `Dog, lazy'--so readers + can look up the concept in different ways.) + +Blank Lines +........... + + * 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. + + * Always insert a blank line before an `@table' command and after an + `@end table' command; but never insert a blank line after an + `@table' command or before an `@end table' command. + + For example, + + Types of fox: + + @table @samp + @item Quick + Jump over lazy dogs. + + @item Brown + Also jump over lazy dogs. + @end table + @noindent + On the other hand, ... + + Insert blank lines before and after `@itemize' ... `@end itemize' + and `@enumerate' ... `@end enumerate' in the same way. + +Complete Phrases +................ + +Complete phrases are easier to read than ... + + * Write entries in an itemized list as complete sentences; or at + least, as complete phrases. Incomplete expressions ... awkward + ... like this. + + * 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. + +Editions, Dates and Versions +............................ + +Include edition numbers, version numbers, and dates in the `@copying' +text (for people reading the Texinfo file, and for the legal copyright +in the output files). Then use `@insertcopying' in the `@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 `@set' and `@value'. *Note `@value' +Example: value Example, and *Note GNU Sample Texts::. + +Definition Commands +................... + +Definition commands are `@deffn', `@defun', `@defmac', and the like, +and enable you to write descriptions in a uniform format. + + * 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. + + * Use `@table' ... `@end table' in an appendix that contains a + summary of functions, not `@deffn' or other definition commands. + +Capitalization +.............. + + * Capitalize "Texinfo"; it is a name. Do not write the `x' or `i' + in upper case. + + * Capitalize "Info"; it is a name. + + * Write TeX using the `@TeX{}' command. Note the uppercase `T' and + `X'. This command causes the formatters to typeset the name + according to the wishes of Donald Knuth, who wrote TeX. + +Spaces +...... + +Do not use spaces to format a Texinfo file, except inside of `@example' +... `@end example' and other literal environments and commands. + + For example, TeX fills the following: + + @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. + +so it looks like this: + + `C-x v' `M-x vc-next-action' Perform the next logical operation on + the version-controlled file corresponding to the current buffer. + +In this case, the text should be formatted with `@table', `@item', and +`@itemx', to create a table. + +@code, @samp, @var, and `---' +............................. + + * Use `@code' around Lisp symbols, including command names. For + example, + + The main function is @code{vc-next-action}, ... + + * Avoid putting letters such as `s' immediately after an `@code'. + Such letters look bad. + + * Use `@var' around meta-variables. Do not write angle brackets + around them. + + * Use three hyphens in a row, `---', to indicate a long dash. TeX + typesets these as a long dash and the Info formatters reduce three + hyphens to two. + +Periods Outside of Quotes +......................... + +Place periods and other punctuation marks _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: + + Evidently, `au' is an abbreviation for ``author''. + +since `au' does _not_ serve as an abbreviation for `author.' (with a +period following the word). + +Introducing New Terms +..................... + + * 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. + + 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. + + * Use the `@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. + +@pxref +...... + +Absolutely never use `@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. + +Invoking from a Shell +..................... + +You can invoke programs such as Emacs, GCC, and `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. + +ANSI C Syntax +............. + +When you use `@example' to describe a C function's calling conventions, +use the ANSI C syntax, like this: + + void dld_init (char *@var{path}); + +And in the subsequent discussion, refer to the argument values by +writing the same argument names, again highlighted with `@var'. + + Avoid the obsolete style that looks like this: + + #include <dld.h> + + dld_init (path) + char *path; + + Also, it is best to avoid writing `#include' above the declaration +just to indicate that the function is declared in a header file. The +practice may give the misimpression that the `#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. + +Bad Examples +............ + +Here are several examples of bad writing to avoid: + + In this example, say, " ... you must `@dfn'{check in} the new +version." That flows better. + + When you are done editing the file, you must perform a + `@dfn'{check in}. + + In the following example, say, "... makes a unified interface such as +VC mode possible." + + 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). + + And in this example, you should specify what `it' refers to: + + If you are working with other people, it assists in coordinating + everyone's changes so they do not step on each other. + +And Finally ... +............... + + * Pronounce TeX as if the `X' were a Greek `chi', as the last sound + in the name `Bach'. But pronounce Texinfo as in `speck': + "teckinfo". + + * Write notes for yourself at the very end of a Texinfo file after + the `@bye'. None of the formatters process text after the `@bye'; + it is as if the text were within `@ignore' ... `@end ignore'. + + +File: texinfo.info, Node: Sample Texinfo Files, Next: Include Files, Prev: Tips, Up: Top + +Appendix C Sample Texinfo Files +******************************* + +The first example is from the first chapter (*note 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:: + + +File: texinfo.info, Node: Short Sample Texinfo File, Next: GNU Sample Texts, Up: Sample Texinfo Files + +C.1 Short Sample +================ + +Here is a complete, short sample Texinfo file, without any commentary. +You can see this file, with comments, in the first chapter. *Note +Short Sample::. + + In a nutshell: The `makeinfo' program transforms a Texinfo source +file such as this into an Info file or HTML; and TeX typesets it for a +printed manual. + + + \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 (C) 2004 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 + + +File: texinfo.info, Node: GNU Sample Texts, Next: Verbatim Copying License, Prev: Short Sample Texinfo File, Up: Sample Texinfo Files + +C.2 GNU Sample Texts +==================== + +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. + + *Note Short Sample::, for a minimal example of a Texinfo file. *Note +Beginning a File::, for a full explanation of that minimal example. + + Here are some notes on the example: + + * The `$Id:' comment is for the CVS (*note Overview: (cvs)Top.) or + RCS (see rcsintro(1)) version control systems, which expand it + into a string such as: + $Id: texinfo.txi,v 1.52 2004/04/09 21:30:07 karl Exp $ + (This is useful in all sources that use version control, not just + manuals.) You may wish to include the `$Id:' comment in the + `@copying' text, if you want a completely unambiguous reference to + the documentation version. + + If you want to literally write $Id$, use `@w': `@w{$}Id$'. + + * The `version.texi' in the `@include' command is maintained + automatically by Automake (*note Introduction: (automake)Top.). + It sets the `VERSION' and `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 (*note Time Stamps: + (emacs)Time Stamps.). + + * The `@syncodeindex' command reflects the recommendation to use + only one index where possible, to make it easier for readers to + look up index entries. + + * The `@dircategory' is for constructing the Info directory. *Note + Installing Dir Entries::, which includes a variety of recommended + category names. + + * The `Invoking' node is a GNU standard to help users find the basic + information about command-line usage of a given program. *Note + Manual Structure Details: (standards)Manual Structure Details. + + * 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 + `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. + *Note GNU Free Documentation License::. + + * If your manual has invariant sections (again, see the license + itself for details), then don't forget to change the text here + accordingly. + + * 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. *Note Verbatim + Copying License::. + + + Here is the sample document: + + +\input texinfo @c -*-texinfo-*- +@comment $Id: texinfo.txi,v 1.52 2004/04/09 21:30:07 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{} 2004 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.1 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 freedom to copy and modify +this GNU Manual, like GNU software. Copies published by the Free +Software Foundation raise funds for GNU development.'' +@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 + +@insertcopying +@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 Copying This Manual +@appendix Copying This Manual + +@menu +* GNU Free Documentation License:: License for copying this manual. +@end menu + +@include fdl.texi + + +@node Index +@unnumbered Index + +@printindex cp + +@bye + + +File: texinfo.info, Node: Verbatim Copying License, Next: All-permissive Copying License, Prev: GNU Sample Texts, Up: Sample Texinfo Files + +C.3 Verbatim Copying License +============================ + +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. + + +@copying +This document is a sample for allowing verbatim copying only. + +Copyright @copyright{} 2004 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 + + +File: texinfo.info, Node: All-permissive Copying License, Prev: Verbatim Copying License, Up: Sample Texinfo Files + +C.4 All-permissive Copying License +================================== + +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. + + Copyright (C) 2004 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. + + +File: texinfo.info, Node: Include Files, Next: Headings, Prev: Sample Texinfo Files, Up: Top + +Appendix D Include Files +************************ + +When TeX or an Info formatting command sees an `@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 `@include' command. +* texinfo-multiple-files-update:: How to create and update nodes and + menus when using included files. +* Include Files Requirements:: `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 `@include' command + has changed over time. + + +File: texinfo.info, Node: Using Include Files, Next: texinfo-multiple-files-update, Up: Include Files + +D.1 How to Use Include Files +============================ + +To include another file within a Texinfo file, write the `@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: + + @include buffers.texi + + The name of the file is taken literally, with a single exception: +`@value{VAR}' references are expanded. This makes it possible to +reliably include files in other directories in a distribution. *Note +`@verbatiminclude': 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 "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 +`\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 +`@bye' command; nothing after `@bye' is formatted. + + In the past, you were required to write an `@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 `@setfilename' line exists in an +included file, it is ignored. + + Conventionally, an included file begins with an `@node' line that is +followed by an `@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 `@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, `texinfo-multiple-files-update', that is designed for +`@include' files. + + 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 (*note GNU +Sample Texts::). + + +File: texinfo.info, Node: texinfo-multiple-files-update, Next: Include Files Requirements, Prev: Using Include Files, Up: Include Files + +D.2 `texinfo-multiple-files-update' +=================================== + +GNU Emacs Texinfo mode provides the `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 `@node' line of the included +files or all of them: + +`M-x texinfo-multiple-files-update' + Called without any arguments: + + - Create or update the `Next', `Previous', and `Up' pointers of + the first `@node' line in each file included in an outer or + overall Texinfo file. + + - Create or update the `Top' level node pointers of the outer or + overall file. + + - Create or update a main menu in the outer file. + +`C-u M-x texinfo-multiple-files-update' + Called with `C-u' as a prefix argument: + + - Create or update pointers in the first `@node' line in each + included file. + + - Create or update the `Top' level node pointers of the outer + file. + + - Create and insert a master menu in the outer file. The + master menu is made from all the menus in all the included + files. + +`C-u 8 M-x texinfo-multiple-files-update' + Called with a numeric prefix argument, such as `C-u 8': + + - Create or update *all* the `Next', `Previous', and `Up' + pointers of all the included files. + + - Create or update *all* the menus of all the included files. + + - Create or update the `Top' level node pointers of the outer or + overall file. + + - And then create a master menu in the outer file. This is + similar to invoking `texinfo-master-menu' with an argument + when you are working with just one file. + + Note the use of the prefix argument in interactive use: with a regular +prefix argument, just `C-u', the `texinfo-multiple-files-update' +command inserts a master menu; with a numeric prefix argument, such as +`C-u 8', the command updates *every* pointer and menu in *all* the +files and then inserts a master menu. + + +File: texinfo.info, Node: Include Files Requirements, Next: Sample Include File, Prev: texinfo-multiple-files-update, Up: Include Files + +D.3 Include Files Requirements +============================== + +If you plan to use the `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 `@include' commands listing the included files. It should not even +include indices, which should be listed in an included file of their +own. + + Moreover, each of the included files must contain exactly one highest +level node (conventionally, `@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 +`@chapter', an `@appendix', or an `@unnumbered' node. Thus, normally, +each included file contains one, and only one, chapter or +equivalent-level node. + + The outer file should contain only _one_ node, the `Top' node. It +should _not_ contain any nodes besides the single `Top' node. The +`texinfo-multiple-files-update' command will not process them. + + +File: texinfo.info, Node: Sample Include File, Next: Include Files Evolution, Prev: Include Files Requirements, Up: Include Files + +D.4 Sample File with `@include' +=============================== + +Here is an example of an outer Texinfo file with `@include' files +within it before running `texinfo-multiple-files-update', which would +insert a main or master menu: + + \input texinfo @c -*-texinfo-*- + @setfilename include-example.info + @settitle Include Example + + ... *Note Sample Texinfo Files::, for + examples of the rest of the frontmatter ... + + @ifnottex + @node Top + @top Include Example + @end ifnottex + + @include foo.texinfo + @include bar.texinfo + @include concept-index.texinfo + @bye + + An included file, such as `foo.texinfo', might look like this: + + @node First + @chapter First Chapter + + Contents of first chapter ... + + The full contents of `concept-index.texinfo' might be as simple as +this: + + @node Concept Index + @unnumbered Concept Index + + @printindex cp + + The outer Texinfo source file for `The GNU Emacs Lisp Reference +Manual' is named `elisp.texi'. This outer file contains a master menu +with 417 entries and a list of 41 `@include' files. + + +File: texinfo.info, Node: Include Files Evolution, Prev: Sample Include File, Up: Include Files + +D.5 Evolution of Include Files +============================== + +When Info was first created, it was customary to create many small Info +files on one subject. Each Info file was formatted from its own +Texinfo source file. This custom meant that Emacs did not need to make +a large buffer to hold the whole of a large Info file when someone +wanted information; instead, Emacs allocated just enough memory for the +small Info file that contained the particular information sought. This +way, Emacs could avoid wasting memory. + + References from one file to another were made by referring to the file +name as well as the node name. (*Note Referring to Other Info Files: +Other Info Files. Also, see *Note `@xref' with Four and Five +Arguments: Four and Five Arguments.) + + Include files were designed primarily as a way to create a single, +large printed manual out of several smaller Info files. In a printed +manual, all the references were within the same document, so TeX could +automatically determine the references' page numbers. The Info +formatting commands used include files only for creating joint indices; +each of the individual Texinfo files had to be formatted for Info +individually. (Each, therefore, required its own `@setfilename' line.) + + However, because large Info files are now split automatically, it is +no longer necessary to keep them small. + + Nowadays, multiple Texinfo files are used mostly for large documents, +such as `The GNU Emacs Lisp Reference Manual', and for projects in +which several different people write different sections of a document +simultaneously. + + In addition, the Info formatting commands have been extended to work +with the `@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. + + +File: texinfo.info, Node: Headings, Next: Catching Mistakes, Prev: Include Files, Up: Top + +Appendix E Page Headings +************************ + +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.) + +* 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. + + +File: texinfo.info, Node: Headings Introduced, Next: Heading Format, Up: Headings + +E.1 Headings Introduced +======================= + +Texinfo provides standard page heading formats for manuals that are +printed on one side of each sheet of paper and for manuals that are +printed on both sides of the paper. Typically, you will use these +formats, but you can specify your own format if you wish. + + In addition, you can specify whether chapters should begin on a new +page, or merely continue the same page as the previous chapter; and if +chapters begin on new pages, you can specify whether they must be +odd-numbered pages. + + By convention, a book is printed on both sides of each sheet of paper. +When you open a book, the right-hand page is odd-numbered, and chapters +begin on right-hand pages--a preceding left-hand page is left blank if +necessary. Reports, however, are often printed on just one side of +paper, and chapters begin on a fresh page immediately following the end +of the preceding chapter. In short or informal reports, chapters often +do not begin on a new page at all, but are separated from the preceding +text by a small amount of whitespace. + + The `@setchapternewpage' command controls whether chapters begin on +new pages, and whether one of the standard heading formats is used. In +addition, Texinfo has several heading and footing commands that you can +use to generate your own heading and footing formats. + + In Texinfo, headings and footings are single lines at the tops and +bottoms of pages; you cannot create multiline headings or footings. +Each header or footer line is divided into three parts: a left part, a +middle part, and a right part. Any part, or a whole line, may be left +blank. Text for the left part of a header or footer line is set +flushleft; text for the middle part is centered; and, text for the +right part is set flushright. + + +File: texinfo.info, Node: Heading Format, Next: Heading Choice, Prev: Headings Introduced, Up: Headings + +E.2 Standard Heading Formats +============================ + +Texinfo provides two standard heading formats, one for manuals printed +on one side of each sheet of paper, and the other for manuals printed +on both sides of the paper. + + By default, nothing is specified for the footing of a Texinfo file, +so the footing remains blank. + + The standard format for single-sided printing consists of a header +line in which the left-hand part contains the name of the chapter, the +central part is blank, and the right-hand part contains the page number. + + A single-sided page looks like this: + + _______________________ + | | + | chapter page number | + | | + | Start of text ... | + | ... | + | | + + The standard format for two-sided printing depends on whether the page +number is even or odd. By convention, even-numbered pages are on the +left- and odd-numbered pages are on the right. (TeX will adjust the +widths of the left- and right-hand margins. Usually, widths are +correct, but during double-sided printing, it is wise to check that +pages will bind properly--sometimes a printer will produce output in +which the even-numbered pages have a larger right-hand margin than the +odd-numbered pages.) + + In the standard double-sided format, the left part of the left-hand +(even-numbered) page contains the page number, the central part is +blank, and the right part contains the title (specified by the +`@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. + + Two pages, side by side as in an open book, look like this: + + _______________________ _______________________ + | | | | + | page number title | | chapter page number | + | | | | + | Start of text ... | | More text ... | + | ... | | ... | + | | | | + +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. + + +File: texinfo.info, Node: Heading Choice, Next: Custom Headings, Prev: Heading Format, Up: Headings + +E.3 Specifying the Type of Heading +================================== + +TeX does not begin to generate page headings for a standard Texinfo +file until it reaches the `@end titlepage' command. Thus, the title +and copyright pages are not numbered. The `@end titlepage' command +causes TeX to begin to generate page headings according to a standard +format specified by the `@setchapternewpage' command that precedes the +`@titlepage' section. + + There are four possibilities: + +No `@setchapternewpage' command + Cause TeX to specify the single-sided heading format, with chapters + on new pages. This is the same as `@setchapternewpage on'. + +`@setchapternewpage on' + Specify the single-sided heading format, with chapters on new + pages. + +`@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 `@headings double' command; + see *Note The `@headings' Command: headings on off.) + +`@setchapternewpage odd' + Specify the double-sided heading format, with chapters on new + pages. + +Texinfo lacks an `@setchapternewpage even' command. + + +File: texinfo.info, Node: Custom Headings, Prev: Heading Choice, Up: Headings + +E.4 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: + * `@everyheading' `@everyfooting' generate page headers and footers + that are the same for both even- and odd-numbered pages. + + * `@evenheading' and `@evenfooting' command generate headers and + footers for even-numbered (left-hand) pages. + + * `@oddheading' and `@oddfooting' generate headers and footers for + odd-numbered (right-hand) pages. + + Write custom heading specifications in the Texinfo file immediately +after the `@end titlepage' command. You must cancel the predefined +heading commands with the `@headings off' command before defining your +own specifications. + + 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: + + @headings off + @everyheading @thischapter @| @thispage @| @today{} + +You need to divide the left part from the central part and the central +part from the right part by inserting `@|' 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. + + Here are the six heading and footing commands: + +`@everyheading LEFT @| CENTER @| RIGHT' +`@everyfooting LEFT @| CENTER @| RIGHT' + 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. + +`@evenheading LEFT @| CENTER @| RIGHT' +`@oddheading LEFT @| CENTER @| RIGHT' +`@evenfooting LEFT @| CENTER @| RIGHT' +`@oddfooting LEFT @| CENTER @| RIGHT' + 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. + + Use the `@this...' series of @-commands to provide the names of +chapters and sections and the page number. You can use the `@this...' +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 `@iftex' +and `@end iftex' commands. + + Here are the `@this...' commands: + +`@thispage' + Expands to the current page number. + +`@thischaptername' + Expands to the name of the current chapter. + +`@thischapter' + Expands to the number and name of the current chapter, in the + format `Chapter 1: Title'. + +`@thistitle' + Expands to the name of the document, as specified by the + `@settitle' command. + +`@thisfile' + For `@include' files only: expands to the name of the current + `@include' file. If the current Texinfo source file is not an + `@include' file, this command has no effect. This command does + _not_ provide the name of the current Texinfo source file unless + it is an `@include' file. (*Note Include Files::, for more + information about `@include' files.) + +You can also use the `@today{}' command, which expands to the current +date, in `1 Jan 1900' format. + + 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: + + @headings off + @everyheading @emph{Draft!} @| @thispage @| @thischapter + @everyfooting @| @| Version: 0.27: @today{} + + Beware of overlong titles: they may overlap another part of the +header or footer and blot it out. + + +File: texinfo.info, Node: Catching Mistakes, Next: Copying This Manual, Prev: Headings, Up: Top + +Appendix F Formatting Mistakes +****************************** + +Besides mistakes in the content of your documentation, there are two +kinds of mistake you can make with Texinfo: you can make mistakes with +@-commands, and you can make mistakes with the structure of the nodes +and chapters. + + Emacs has two tools for catching the @-command mistakes and two for +catching structuring mistakes. + + For finding problems with @-commands, you can run TeX or a region +formatting command on the region that has a problem; indeed, you can +run these commands on each region as you write it. + + For finding problems with the structure of nodes and chapters, you +can use `C-c C-s' (`texinfo-show-structure') and the related `occur' +command and you can use the `M-x Info-validate' command. + +* Menu: + +* makeinfo Preferred:: `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 `texinfo-show-structure'. +* Using occur:: How to list all lines containing a pattern. +* Running Info-Validate:: How to find badly referenced nodes. + + +File: texinfo.info, Node: makeinfo Preferred, Next: Debugging with Info, Up: Catching Mistakes + +F.1 `makeinfo' Find Errors +========================== + +The `makeinfo' program does an excellent job of catching errors and +reporting them--far better than `texinfo-format-region' or +`texinfo-format-buffer'. In addition, the various functions for +automatically creating and updating node pointers and menus remove many +opportunities for human error. + + If you can, use the updating commands to create and insert pointers +and menus. These prevent many errors. Then use `makeinfo' (or its +Texinfo mode manifestations, `makeinfo-region' and `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 `makeinfo', or your +problem is very puzzling, then you may want to use the tools described +in this appendix. + + +File: texinfo.info, Node: Debugging with Info, Next: Debugging with TeX, Prev: makeinfo Preferred, Up: Catching Mistakes + +F.2 Catching Errors with Info Formatting +======================================== + +After you have written part of a Texinfo file, you can use the +`texinfo-format-region' or the `makeinfo-region' command to see whether +the region formats properly. + + Most likely, however, you are reading this section because for some +reason you cannot use the `makeinfo-region' command; therefore, the +rest of this section presumes that you are using +`texinfo-format-region'. + + If you have made a mistake with an @-command, `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 +`*Info Region*' buffer; the cursor will be in a position that is after +the location of the error. Also, the text will not be formatted after +the place where the error occurred (or more precisely, where it was +detected). + + For example, if you accidentally end a menu with the command `@end +menus' with an `s' on the end, instead of with `@end menu', you will +see an error message that says: + + @end menus is not handled by texinfo + +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: + + ---------- 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 + -!- + ---------- Buffer: *Info Region* ---------- + + The `texinfo-format-region' command sometimes provides slightly odd +error messages. For example, the following cross reference fails to +format: + + (@xref{Catching Mistakes, for more info.) + +In this case, `texinfo-format-region' detects the missing closing brace +but displays a message that says `Unbalanced parentheses' rather than +`Unbalanced braces'. This is because the formatting command looks for +mismatches between braces as if they were parentheses. + + Sometimes `texinfo-format-region' fails to detect mistakes. For +example, in the following, the closing brace is swapped with the +closing parenthesis: + + (@xref{Catching Mistakes), for more info.} + +Formatting produces: + (*Note for more info.: Catching Mistakes) + + The only way for you to detect this error is to realize that the +reference should have looked like this: + + (*Note Catching Mistakes::, for more info.) + + Incidentally, if you are reading this node in Info and type `f <RET>' +(`Info-follow-reference'), you will generate an error message that says: + + No such node: "Catching Mistakes) The only way ... + +This is because Info perceives the example of the error as the first +cross reference in this node and if you type a <RET> immediately after +typing the Info `f' command, Info will attempt to go to the referenced +node. If you type `f catch <TAB> <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 `l' (`Info-last').) + + +File: texinfo.info, Node: Debugging with TeX, Next: Using texinfo-show-structure, Prev: Debugging with Info, Up: Catching Mistakes + +F.3 Catching Errors with TeX Formatting +======================================= + +You can also catch mistakes when you format a file with TeX. + + Usually, you will want to do this after you have run +`texinfo-format-buffer' (or, better, `makeinfo-buffer') on the same +file, because `texinfo-format-buffer' sometimes displays error messages +that make more sense than TeX. (*Note Debugging with Info::, for more +information.) + + For example, TeX was run on a Texinfo file, part of which is shown +here: + + ---------- 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 ---------- + +(The cross reference lacks a closing brace.) TeX produced the +following output, after which it stopped: + + ---------- 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* ---------- + + In this case, TeX produced an accurate and understandable error +message: + + Paragraph ended before @xref was complete. + +`@par' is an internal TeX command of no relevance to Texinfo. `l.27' +means that TeX detected the problem on line 27 of the Texinfo file. +The `?' is the prompt TeX uses in this circumstance. + + Unfortunately, TeX is not always so helpful, and sometimes you must +truly be a Sherlock Holmes to discover what went wrong. + + In any case, if you run into a problem like this, you can do one of +three things. + + 1. You can tell TeX to continue running and ignore just this error by + typing <RET> at the `?' prompt. + + 2. You can tell TeX to continue running and to ignore all errors as + best it can by typing `r <RET>' at the `?' prompt. + + This is often the best thing to do. However, beware: the one error + may produce a cascade of additional error messages as its + consequences are felt through the rest of the file. To stop TeX + when it is producing such an avalanche of error messages, type + `C-c' (or `C-c C-c', if you are running a shell inside Emacs). + + 3. You can tell TeX to stop this run by typing `x <RET>' at the `?' + prompt. + + If you are running TeX inside Emacs, you need to switch to the shell +buffer and line at which TeX offers the `?' 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 `@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 + + (@end occurred inside a group at level 1) + +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 `@end' command somewhere in +the file; but that it could not determine where it was needed. + + Another source of notoriously hard-to-find errors is a missing `@end +group' command. If you ever are stumped by incomprehensible errors, +look for a missing `@end group' command first. + + If the Texinfo file lacks header lines, TeX may stop in the beginning +of its run and display output that looks like the following. The `*' +indicates that TeX is waiting for input. + + This is TeX, Version 3.14159 (Web2c 7.0) + (test.texinfo [1]) + * + +In this case, simply type `\end <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, `\'. TeX uses `\' instead of `@'; and +in this circumstance, you are working directly with TeX, not with +Texinfo.) + + +File: texinfo.info, Node: Using texinfo-show-structure, Next: Using occur, Prev: Debugging with TeX, Up: Catching Mistakes + +F.4 Using `texinfo-show-structure' +================================== + +It is not always easy to keep track of the nodes, chapters, sections, +and subsections of a Texinfo file. This is especially true if you are +revising or adding to a Texinfo file that someone else has written. + + In GNU Emacs, in Texinfo mode, the `texinfo-show-structure' command +lists all the lines that begin with the @-commands that specify the +structure: `@chapter', `@section', `@appendix', and so on. With an +argument (`C-u' as prefix argument, if interactive), the command also +shows the `@node' lines. The `texinfo-show-structure' command is bound +to `C-c C-s' in Texinfo mode, by default. + + The lines are displayed in a buffer called the `*Occur*' buffer, +indented by hierarchical level. For example, here is a part of what was +produced by running `texinfo-show-structure' on this manual: + + Lines matching "^@\\(chapter \\|sect\\|subs\\|subh\\| + unnum\\|major\\|chapheading \\|heading \\|appendix\\)" + in buffer texinfo.texi. + ... + 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 + ... + + This says that lines 4337, 4393, and 4417 of `texinfo.texi' begin +with the `@section', `@subheading', and `@subsection' commands +respectively. If you move your cursor into the `*Occur*' window, you +can position the cursor over one of the lines and use the `C-c C-c' +command (`occur-mode-goto-occurrence'), to jump to the corresponding +spot in the Texinfo file. *Note Using Occur: (emacs)Other Repeating +Search, for more information about `occur-mode-goto-occurrence'. + + The first line in the `*Occur*' window describes the "regular +expression" specified by TEXINFO-HEADING-PATTERN. This regular +expression is the pattern that `texinfo-show-structure' looks for. +*Note Using Regular Expressions: (emacs)Regexps, for more information. + + When you invoke the `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 `C-x n n' (`narrow-to-region') command to mark the region. +(*Note Narrowing: (emacs)Narrowing.) This is how the example used +above was generated. (To see the whole buffer again, use `C-x n w' +(`widen').) + + If you call `texinfo-show-structure' with a prefix argument by typing +`C-u C-c C-s', it will list lines beginning with `@node' as well as the +lines beginning with the @-sign commands for `@chapter', `@section', +and the like. + + You can remind yourself of the structure of a Texinfo file by looking +at the list in the `*Occur*' window; and if you have mis-named a node +or left out a section, you can correct the mistake. + + +File: texinfo.info, Node: Using occur, Next: Running Info-Validate, Prev: Using texinfo-show-structure, Up: Catching Mistakes + +F.5 Using `occur' +================= + +Sometimes the `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 `texinfo-show-structure'. In this case, you can use the +`occur' command directly. To do this, type + + M-x occur + +and then, when prompted, type a "regexp", a regular expression for the +pattern you want to match. (*Note Regular Expressions: +(emacs)Regexps.) The `occur' command works from the current location +of the cursor in the buffer to the end of the buffer. If you want to +run `occur' on the whole buffer, place the cursor at the beginning of +the buffer. + + For example, to see all the lines that contain the word `@chapter' in +them, just type `@chapter'. This will produce a list of the chapters. +It will also list all the sentences with `@chapter' in the middle of +the line. + + If you want to see only those lines that start with the word +`@chapter', type `^@chapter' when prompted by `occur'. If you want to +see all the lines that end with a word or phrase, end the last word +with a `$'; for example, `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. + + *Note Using Occur: (emacs)Other Repeating Search, for more +information. + + +File: texinfo.info, Node: Running Info-Validate, Prev: Using occur, Up: Catching Mistakes + +F.6 Finding Badly Referenced Nodes +================================== + +You can use the `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 `Info-validate' command works only on Info files, +not on Texinfo files. + + The `makeinfo' program validates pointers automatically, so you do +not need to use the `Info-validate' command if you are using +`makeinfo'. You only may need to use `Info-validate' if you are unable +to run `makeinfo' and instead must create an Info file using +`texinfo-format-region' or `texinfo-format-buffer', or if you write an +Info file from scratch. + +* Menu: + +* Using Info-validate:: How to run `Info-validate'. +* Unsplit:: How to create an unsplit file. +* Tagifying:: How to tagify a file. +* Splitting:: How to split a file manually. + + +File: texinfo.info, Node: Using Info-validate, Next: Unsplit, Up: Running Info-Validate + +F.6.1 Running `Info-validate' +----------------------------- + +To use `Info-validate', visit the Info file you wish to check and type: + + M-x Info-validate + +Note that the `Info-validate' command requires an upper case `I'. You +may also need to create a tag table before running `Info-validate'. +*Note 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 `*problems +in info file*'. + + For example, `Info-validate' was run on a test file that contained +only the first node of this manual. One of the messages said: + + In node "Overview", invalid Next: Texinfo Mode + +This meant that the node called `Overview' had a `Next' pointer that +did not point to anything (which was true in this case, since the test +file had only one node in it). + + Now suppose we add a node named `Texinfo Mode' to our test case but +we do not specify a `Previous' for this node. Then we will get the +following error message: + + In node "Texinfo Mode", should have Previous: Overview + +This is because every `Next' pointer should be matched by a `Previous' +(in the node where the `Next' points) which points back. + + `Info-validate' also checks that all menu entries and cross references +point to actual nodes. + + `Info-validate' requires a tag table and does not work with files +that have been split. (The `texinfo-format-buffer' command +automatically splits large files.) In order to use `Info-validate' on +a large file, you must run `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. + + +File: texinfo.info, Node: Unsplit, Next: Tagifying, Prev: Using Info-validate, Up: Running Info-Validate + +F.6.2 Creating an Unsplit File +------------------------------ + +You can run `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 +`texinfo-format-buffer' or `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 +`Info-validate' and look for badly referenced nodes. + + The first step is to create an unsplit Info file. To prevent +`texinfo-format-buffer' from splitting a Texinfo file into smaller Info +files, give a prefix to the `M-x texinfo-format-buffer' command: + + C-u M-x texinfo-format-buffer + +or else + + C-u C-c C-e C-b + +When you do this, Texinfo will not split the file and will not create a +tag table for it. + + +File: texinfo.info, Node: Tagifying, Next: Splitting, Prev: Unsplit, Up: Running Info-Validate + +F.6.3 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: + + M-x Info-tagify + +(Note the upper case `I' in `Info-tagify'.) This creates an Info file +with a tag table that you can validate. + + The third step is to validate the Info file: + + M-x Info-validate + +(Note the upper case `I' in `Info-validate'.) In brief, the steps are: + + C-u M-x texinfo-format-buffer + M-x Info-tagify + M-x Info-validate + + After you have validated the node structure, you can rerun +`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. + + +File: texinfo.info, Node: Splitting, Prev: Tagifying, Up: Running Info-Validate + +F.6.4 Splitting a File Manually +------------------------------- + +You should split a large file or else let the `texinfo-format-buffer' +or `makeinfo-buffer' command do it for you automatically. (Generally +you will let one of the formatting commands do this job for you. *Note +Creating an Info File::.) + + The split-off files are called the indirect subfiles. + + Info files are split to save memory. With smaller files, Emacs does +not have make such a large buffer to hold the information. + + If an Info file has more than 30 nodes, you should also make a tag +table for it. *Note 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 +`Info-validate'.) + + Visit the Info file you wish to tagify and split and type the two +commands: + + M-x Info-tagify + M-x Info-split + +(Note that the `I' in `Info' is upper case.) + + When you use the `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 `-' and a number to the original file name. + + The primary file still functions as an Info file, but it contains just +the tag table and a directory of subfiles. + + +File: texinfo.info, Node: Copying This Manual, Next: Command and Variable Index, Prev: Catching Mistakes, Up: Top + +Appendix G Copying This Manual +****************************** + +* Menu: + +* GNU Free Documentation License:: License for copying this manual. + + +File: texinfo.info, Node: GNU Free Documentation License, Up: Copying This Manual + +G.1 GNU Free Documentation License +================================== + + Version 1.2, November 2002 + + Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. + 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA + + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + 0. PREAMBLE + + The purpose of this License is to make a manual, textbook, or other + functional and useful document "free" in the sense of freedom: to + assure everyone the effective freedom to copy and redistribute it, + with or without modifying it, either commercially or + noncommercially. Secondarily, this License preserves for the + author and publisher a way to get credit for their work, while not + being considered responsible for modifications made by others. + + This License is a kind of "copyleft", which means that derivative + works of the document must themselves be free in the same sense. + It complements the GNU General Public License, which is a copyleft + license designed for free software. + + We have designed this License in order to use it for manuals for + free software, because free software needs free documentation: a + free program should come with manuals providing the same freedoms + that the software does. But this License is not limited to + software manuals; it can be used for any textual work, regardless + of subject matter or whether it is published as a printed book. + We recommend this License principally for works whose purpose is + instruction or reference. + + 1. APPLICABILITY AND DEFINITIONS + + This License applies to any manual or other work, in any medium, + that contains a notice placed by the copyright holder saying it + can be distributed under the terms of this License. Such a notice + grants a world-wide, royalty-free license, unlimited in duration, + to use that work under the conditions stated herein. The + "Document", below, refers to any such manual or work. Any member + of the public is a licensee, and is addressed as "you". You + accept the license if you copy, modify or distribute the work in a + way requiring permission under copyright law. + + A "Modified Version" of the Document means any work containing the + Document or a portion of it, either copied verbatim, or with + modifications and/or translated into another language. + + A "Secondary Section" is a named appendix or a front-matter section + of the Document that deals exclusively with the relationship of the + publishers or authors of the Document to the Document's overall + subject (or to related matters) and contains nothing that could + fall directly within that overall subject. (Thus, if the Document + is in part a textbook of mathematics, a Secondary Section may not + explain any mathematics.) The relationship could be a matter of + historical connection with the subject or with related matters, or + of legal, commercial, philosophical, ethical or political position + regarding them. + + The "Invariant Sections" are certain Secondary Sections whose + titles are designated, as being those of Invariant Sections, in + the notice that says that the Document is released under this + License. If a section does not fit the above definition of + Secondary then it is not allowed to be designated as Invariant. + The Document may contain zero Invariant Sections. If the Document + does not identify any Invariant Sections then there are none. + + The "Cover Texts" are certain short passages of text that are + listed, as Front-Cover Texts or Back-Cover Texts, in the notice + that says that the Document is released under this License. A + Front-Cover Text may be at most 5 words, and a Back-Cover Text may + be at most 25 words. + + A "Transparent" copy of the Document means a machine-readable copy, + represented in a format whose specification is available to the + general public, that is suitable for revising the document + straightforwardly with generic text editors or (for images + composed of pixels) generic paint programs or (for drawings) some + widely available drawing editor, and that is suitable for input to + text formatters or for automatic translation to a variety of + formats suitable for input to text formatters. A copy made in an + otherwise Transparent file format whose markup, or absence of + markup, has been arranged to thwart or discourage subsequent + modification by readers is not Transparent. An image format is + not Transparent if used for any substantial amount of text. A + copy that is not "Transparent" is called "Opaque". + + Examples of suitable formats for Transparent copies include plain + ASCII without markup, Texinfo input format, LaTeX input format, + SGML or XML using a publicly available DTD, and + standard-conforming simple HTML, PostScript or PDF designed for + human modification. Examples of transparent image formats include + PNG, XCF and JPG. Opaque formats include proprietary formats that + can be read and edited only by proprietary word processors, SGML or + XML for which the DTD and/or processing tools are not generally + available, and the machine-generated HTML, PostScript or PDF + produced by some word processors for output purposes only. + + The "Title Page" means, for a printed book, the title page itself, + plus such following pages as are needed to hold, legibly, the + material this License requires to appear in the title page. For + works in formats which do not have any title page as such, "Title + Page" means the text near the most prominent appearance of the + work's title, preceding the beginning of the body of the text. + + A section "Entitled XYZ" means a named subunit of the Document + whose title either is precisely XYZ or contains XYZ in parentheses + following text that translates XYZ in another language. (Here XYZ + stands for a specific section name mentioned below, such as + "Acknowledgements", "Dedications", "Endorsements", or "History".) + To "Preserve the Title" of such a section when you modify the + Document means that it remains a section "Entitled XYZ" according + to this definition. + + The Document may include Warranty Disclaimers next to the notice + which states that this License applies to the Document. These + Warranty Disclaimers are considered to be included by reference in + this License, but only as regards disclaiming warranties: any other + implication that these Warranty Disclaimers may have is void and + has no effect on the meaning of this License. + + 2. VERBATIM COPYING + + You may copy and distribute the Document in any medium, either + commercially or noncommercially, provided that this License, the + copyright notices, and the license notice saying this License + applies to the Document are reproduced in all copies, and that you + add no other conditions whatsoever to those of this License. You + may not use technical measures to obstruct or control the reading + or further copying of the copies you make or distribute. However, + you may accept compensation in exchange for copies. If you + distribute a large enough number of copies you must also follow + the conditions in section 3. + + You may also lend copies, under the same conditions stated above, + and you may publicly display copies. + + 3. COPYING IN QUANTITY + + If you publish printed copies (or copies in media that commonly + have printed covers) of the Document, numbering more than 100, and + the Document's license notice requires Cover Texts, you must + enclose the copies in covers that carry, clearly and legibly, all + these Cover Texts: Front-Cover Texts on the front cover, and + Back-Cover Texts on the back cover. Both covers must also clearly + and legibly identify you as the publisher of these copies. The + front cover must present the full title with all words of the + title equally prominent and visible. You may add other material + on the covers in addition. Copying with changes limited to the + covers, as long as they preserve the title of the Document and + satisfy these conditions, can be treated as verbatim copying in + other respects. + + If the required texts for either cover are too voluminous to fit + legibly, you should put the first ones listed (as many as fit + reasonably) on the actual cover, and continue the rest onto + adjacent pages. + + If you publish or distribute Opaque copies of the Document + numbering more than 100, you must either include a + machine-readable Transparent copy along with each Opaque copy, or + state in or with each Opaque copy a computer-network location from + which the general network-using public has access to download + using public-standard network protocols a complete Transparent + copy of the Document, free of added material. If you use the + latter option, you must take reasonably prudent steps, when you + begin distribution of Opaque copies in quantity, to ensure that + this Transparent copy will remain thus accessible at the stated + location until at least one year after the last time you + distribute an Opaque copy (directly or through your agents or + retailers) of that edition to the public. + + It is requested, but not required, that you contact the authors of + the Document well before redistributing any large number of + copies, to give them a chance to provide you with an updated + version of the Document. + + 4. MODIFICATIONS + + You may copy and distribute a Modified Version of the Document + under the conditions of sections 2 and 3 above, provided that you + release the Modified Version under precisely this License, with + the Modified Version filling the role of the Document, thus + licensing distribution and modification of the Modified Version to + whoever possesses a copy of it. In addition, you must do these + things in the Modified Version: + + A. Use in the Title Page (and on the covers, if any) a title + distinct from that of the Document, and from those of + previous versions (which should, if there were any, be listed + in the History section of the Document). You may use the + same title as a previous version if the original publisher of + that version gives permission. + + B. List on the Title Page, as authors, one or more persons or + entities responsible for authorship of the modifications in + the Modified Version, together with at least five of the + principal authors of the Document (all of its principal + authors, if it has fewer than five), unless they release you + from this requirement. + + C. State on the Title page the name of the publisher of the + Modified Version, as the publisher. + + D. Preserve all the copyright notices of the Document. + + E. Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices. + + F. Include, immediately after the copyright notices, a license + notice giving the public permission to use the Modified + Version under the terms of this License, in the form shown in + the Addendum below. + + G. Preserve in that license notice the full lists of Invariant + Sections and required Cover Texts given in the Document's + license notice. + + H. Include an unaltered copy of this License. + + I. Preserve the section Entitled "History", Preserve its Title, + and add to it an item stating at least the title, year, new + authors, and publisher of the Modified Version as given on + the Title Page. If there is no section Entitled "History" in + the Document, create one stating the title, year, authors, + and publisher of the Document as given on its Title Page, + then add an item describing the Modified Version as stated in + the previous sentence. + + J. Preserve the network location, if any, given in the Document + for public access to a Transparent copy of the Document, and + likewise the network locations given in the Document for + previous versions it was based on. These may be placed in + the "History" section. You may omit a network location for a + work that was published at least four years before the + Document itself, or if the original publisher of the version + it refers to gives permission. + + K. For any section Entitled "Acknowledgements" or "Dedications", + Preserve the Title of the section, and preserve in the + section all the substance and tone of each of the contributor + acknowledgements and/or dedications given therein. + + L. Preserve all the Invariant Sections of the Document, + unaltered in their text and in their titles. Section numbers + or the equivalent are not considered part of the section + titles. + + M. Delete any section Entitled "Endorsements". Such a section + may not be included in the Modified Version. + + N. Do not retitle any existing section to be Entitled + "Endorsements" or to conflict in title with any Invariant + Section. + + O. Preserve any Warranty Disclaimers. + + If the Modified Version includes new front-matter sections or + appendices that qualify as Secondary Sections and contain no + material copied from the Document, you may at your option + designate some or all of these sections as invariant. To do this, + add their titles to the list of Invariant Sections in the Modified + Version's license notice. These titles must be distinct from any + other section titles. + + You may add a section Entitled "Endorsements", provided it contains + nothing but endorsements of your Modified Version by various + parties--for example, statements of peer review or that the text + has been approved by an organization as the authoritative + definition of a standard. + + You may add a passage of up to five words as a Front-Cover Text, + and a passage of up to 25 words as a Back-Cover Text, to the end + of the list of Cover Texts in the Modified Version. Only one + passage of Front-Cover Text and one of Back-Cover Text may be + added by (or through arrangements made by) any one entity. If the + Document already includes a cover text for the same cover, + previously added by you or by arrangement made by the same entity + you are acting on behalf of, you may not add another; but you may + replace the old one, on explicit permission from the previous + publisher that added the old one. + + The author(s) and publisher(s) of the Document do not by this + License give permission to use their names for publicity for or to + assert or imply endorsement of any Modified Version. + + 5. COMBINING DOCUMENTS + + You may combine the Document with other documents released under + this License, under the terms defined in section 4 above for + modified versions, provided that you include in the combination + all of the Invariant Sections of all of the original documents, + unmodified, and list them all as Invariant Sections of your + combined work in its license notice, and that you preserve all + their Warranty Disclaimers. + + The combined work need only contain one copy of this License, and + multiple identical Invariant Sections may be replaced with a single + copy. If there are multiple Invariant Sections with the same name + but different contents, make the title of each such section unique + by adding at the end of it, in parentheses, the name of the + original author or publisher of that section if known, or else a + unique number. Make the same adjustment to the section titles in + the list of Invariant Sections in the license notice of the + combined work. + + In the combination, you must combine any sections Entitled + "History" in the various original documents, forming one section + Entitled "History"; likewise combine any sections Entitled + "Acknowledgements", and any sections Entitled "Dedications". You + must delete all sections Entitled "Endorsements." + + 6. COLLECTIONS OF DOCUMENTS + + You may make a collection consisting of the Document and other + documents released under this License, and replace the individual + copies of this License in the various documents with a single copy + that is included in the collection, provided that you follow the + rules of this License for verbatim copying of each of the + documents in all other respects. + + You may extract a single document from such a collection, and + distribute it individually under this License, provided you insert + a copy of this License into the extracted document, and follow + this License in all other respects regarding verbatim copying of + that document. + + 7. AGGREGATION WITH INDEPENDENT WORKS + + A compilation of the Document or its derivatives with other + separate and independent documents or works, in or on a volume of + a storage or distribution medium, is called an "aggregate" if the + copyright resulting from the compilation is not used to limit the + legal rights of the compilation's users beyond what the individual + works permit. When the Document is included in an aggregate, this + License does not apply to the other works in the aggregate which + are not themselves derivative works of the Document. + + If the Cover Text requirement of section 3 is applicable to these + copies of the Document, then if the Document is less than one half + of the entire aggregate, the Document's Cover Texts may be placed + on covers that bracket the Document within the aggregate, or the + electronic equivalent of covers if the Document is in electronic + form. Otherwise they must appear on printed covers that bracket + the whole aggregate. + + 8. TRANSLATION + + Translation is considered a kind of modification, so you may + distribute translations of the Document under the terms of section + 4. Replacing Invariant Sections with translations requires special + permission from their copyright holders, but you may include + translations of some or all Invariant Sections in addition to the + original versions of these Invariant Sections. You may include a + translation of this License, and all the license notices in the + Document, and any Warranty Disclaimers, provided that you also + include the original English version of this License and the + original versions of those notices and disclaimers. In case of a + disagreement between the translation and the original version of + this License or a notice or disclaimer, the original version will + prevail. + + If a section in the Document is Entitled "Acknowledgements", + "Dedications", or "History", the requirement (section 4) to + Preserve its Title (section 1) will typically require changing the + actual title. + + 9. TERMINATION + + You may not copy, modify, sublicense, or distribute the Document + except as expressly provided for under this License. Any other + attempt to copy, modify, sublicense or distribute the Document is + void, and will automatically terminate your rights under this + License. However, parties who have received copies, or rights, + from you under this License will not have their licenses + terminated so long as such parties remain in full compliance. + + 10. FUTURE REVISIONS OF THIS LICENSE + + The Free Software Foundation may publish new, revised versions of + the GNU Free Documentation License from time to time. Such new + versions will be similar in spirit to the present version, but may + differ in detail to address new problems or concerns. See + `http://www.gnu.org/copyleft/'. + + Each version of the License is given a distinguishing version + number. If the Document specifies that a particular numbered + version of this License "or any later version" applies to it, you + have the option of following the terms and conditions either of + that specified version or of any later version that has been + published (not as a draft) by the Free Software Foundation. If + the Document does not specify a version number of this License, + you may choose any version ever published (not as a draft) by the + Free Software Foundation. + +G.1.1 ADDENDUM: How to use this License for your documents +---------------------------------------------------------- + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and license +notices just after the title page: + + Copyright (C) YEAR YOUR NAME. + 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, no Front-Cover Texts, and no Back-Cover + Texts. A copy of the license is included in the section entitled ``GNU + Free Documentation License''. + + If you have Invariant Sections, Front-Cover Texts and Back-Cover +Texts, replace the "with...Texts." line with this: + + with the Invariant Sections being LIST THEIR TITLES, with + the Front-Cover Texts being LIST, and with the Back-Cover Texts + being LIST. + + If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + + If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, to +permit their use in free software. + + +File: texinfo.info, Node: Command and Variable Index, Next: Concept Index, Prev: Copying This Manual, Up: Top + +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 `@'. + + +* Menu: + +* ! (end of sentence): Ending a Sentence. (line 6) +* " (umlaut accent): Inserting Accents. (line 17) +* ' (umlaut accent): Inserting Accents. (line 17) +* * (force line break): Line Breaks. (line 6) +* , (cedilla accent): Inserting Accents. (line 17) +* - (discretionary hyphen): - and hyphenation. (line 6) +* . (end of sentence): Ending a Sentence. (line 6) +* / (allow line break): Line Breaks. (line 6) +* <colon> (suppress end-of-sentence space): Not Ending a Sentence. + (line 16) +* <newline>: Multiple Spaces. (line 6) +* <space>: Multiple Spaces. (line 6) +* <tab>: Multiple Spaces. (line 6) +* = (macron accent): Inserting Accents. (line 17) +* ? (end of sentence): Ending a Sentence. (line 6) +* @ (literal @): Inserting an Atsign. (line 6) +* \ (literal \ in @math): math. (line 28) +* \emergencystretch: Overfull hboxes. (line 31) +* \gdef within @tex: Raw Formatter Commands. + (line 29) +* \input (raw TeX startup): Minimum. (line 24) +* \mag (raw TeX magnification): Cropmarks and Magnification. + (line 24) +* ^ (circumflex accent): Inserting Accents. (line 17) +* ` (grave accent): Inserting Accents. (line 17) +* AA: Inserting Accents. (line 37) +* aa: Inserting Accents. (line 37) +* acronym: acronym. (line 6) +* AE: Inserting Accents. (line 37) +* ae: Inserting Accents. (line 37) +* afourlatex: A4 Paper. (line 23) +* afourpaper: A4 Paper. (line 6) +* afourwide: A4 Paper. (line 23) +* alias: alias. (line 6) +* anchor: anchor. (line 6) +* appendix: unnumbered & appendix. + (line 6) +* appendixsec: unnumberedsec appendixsec heading. + (line 6) +* appendixsection: unnumberedsec appendixsec heading. + (line 18) +* appendixsubsec: unnumberedsubsec appendixsubsec subheading. + (line 6) +* appendixsubsubsec: subsubsection. (line 6) +* apply: Sample Function Definition. + (line 14) +* asis: table. (line 20) +* author: title subtitle author. + (line 6) +* b (bold font): Fonts. (line 6) +* bullet: bullet. (line 6) +* bye <1>: File End. (line 6) +* bye: Ending a File. (line 6) +* c (comment): Comments. (line 6) +* caption: caption shortcaption. + (line 6) +* cartouche: cartouche. (line 6) +* center: titlefont center sp. (line 6) +* centerchap: chapter. (line 25) +* chapheading: majorheading & chapheading. + (line 6) +* chapter: chapter. (line 6) +* cite: cite. (line 6) +* code: code. (line 6) +* columnfractions: Multitable Column Widths. + (line 11) +* comma: Inserting a Comma. (line 6) +* command: command. (line 6) +* comment: Comments. (line 6) +* contents: Contents. (line 6) +* copying: copying. (line 6) +* copyright <1>: copying. (line 37) +* copyright: copyright symbol. (line 6) +* cropmarks: Cropmarks and Magnification. + (line 6) +* defcodeindex: New Indices. (line 6) +* defcv: Object-Oriented Variables. + (line 10) +* deffn: Functions Commands. (line 9) +* deffnx: deffnx. (line 6) +* defindex: New Indices. (line 6) +* definfoenclose: definfoenclose. (line 6) +* defivar: Object-Oriented Variables. + (line 47) +* defmac: Functions Commands. (line 58) +* defmethod: Object-Oriented Methods. + (line 80) +* defop: Object-Oriented Methods. + (line 11) +* defopt: Variables Commands. (line 56) +* defspec: Functions Commands. (line 63) +* deftp: Data Types. (line 8) +* deftypecv: Object-Oriented Variables. + (line 28) +* deftypefn: Typed Functions. (line 10) +* deftypefun: Typed Functions. (line 76) +* deftypeivar: Object-Oriented Variables. + (line 63) +* deftypeop: Object-Oriented Methods. + (line 51) +* deftypevar: Typed Variables. (line 40) +* deftypevr: Typed Variables. (line 12) +* defun: Functions Commands. (line 48) +* defvar: Variables Commands. (line 38) +* defvr: Variables Commands. (line 8) +* dfn: dfn. (line 6) +* dircategory: Installing Dir Entries. + (line 11) +* direntry: Installing Dir Entries. + (line 11) +* display: display. (line 6) +* dmn: dmn. (line 6) +* docbook: Raw Formatter Commands. + (line 53) +* documentdescription: documentdescription. (line 6) +* documentencoding: documentencoding. (line 6) +* documentlanguage: documentlanguage. (line 6) +* dotaccent: Inserting Accents. (line 17) +* dotless: Inserting Accents. (line 37) +* dots: dots. (line 6) +* email: email. (line 6) +* emph: emph & strong. (line 6) +* end <1>: Introducing Lists. (line 20) +* end: Quotations and Examples. + (line 15) +* end titlepage: end titlepage. (line 6) +* enddots: dots. (line 6) +* enumerate: enumerate. (line 6) +* env: env. (line 6) +* equiv: Equivalence. (line 6) +* error: Error Glyph. (line 6) +* evenfooting: Custom Headings. (line 51) +* evenheading: Custom Headings. (line 51) +* everyfooting: Custom Headings. (line 44) +* everyheading: Custom Headings. (line 44) +* example: example. (line 6) +* exampleindent: exampleindent. (line 6) +* exclamdown: Inserting Accents. (line 37) +* exdent: exdent. (line 6) +* expansion: expansion. (line 6) +* file: file. (line 6) +* filll TeX dimension: Copyright. (line 12) +* finalout: Overfull hboxes. (line 46) +* firstparagraphindent: firstparagraphindent. + (line 6) +* float: float. (line 6) +* flushleft: flushleft & flushright. + (line 6) +* flushright: flushleft & flushright. + (line 6) +* fn-name: Def Cmd Continuation Lines. + (line 19) +* foobar: Optional Arguments. (line 23) +* footnote: Footnotes. (line 6) +* footnotestyle: Footnote Styles. (line 44) +* format: format. (line 6) +* forward-word: Def Cmd Template. (line 35) +* ftable: ftable vtable. (line 6) +* group: group. (line 6) +* H (Hungarian umlaut accent): Inserting Accents. (line 17) +* hbox: Overfull hboxes. (line 14) +* heading: unnumberedsec appendixsec heading. + (line 6) +* headings: headings on off. (line 6) +* headitem: Multitable Rows. (line 12) +* headword: definfoenclose. (line 58) +* html: Raw Formatter Commands. + (line 45) +* hyphenation: - and hyphenation. (line 6) +* i (italic font): Fonts. (line 6) +* ifclear: ifset ifclear. (line 47) +* ifdocbook <1>: Raw Formatter Commands. + (line 53) +* ifdocbook: Conditional Commands. + (line 14) +* ifhtml <1>: Raw Formatter Commands. + (line 45) +* ifhtml: Conditional Commands. + (line 14) +* ifinfo: Conditional Commands. + (line 9) +* ifnotdocbook: Conditional Not Commands. + (line 6) +* ifnothtml: Conditional Not Commands. + (line 6) +* ifnotinfo: Conditional Not Commands. + (line 6) +* ifnotplaintext: Conditional Not Commands. + (line 6) +* ifnottex: Conditional Not Commands. + (line 6) +* ifnotxml: Conditional Not Commands. + (line 6) +* ifplaintext: Conditional Commands. + (line 14) +* ifset: ifset ifclear. (line 6) +* iftex: Conditional Commands. + (line 14) +* ifxml <1>: Raw Formatter Commands. + (line 49) +* ifxml: Conditional Commands. + (line 14) +* ignore: Comments. (line 19) +* image: Images. (line 6) +* include: Using Include Files. (line 6) +* indent: indent. (line 6) +* indicateurl: indicateurl. (line 6) +* Info-validate: Running Info-Validate. + (line 6) +* inforef: inforef. (line 6) +* insertcopying: insertcopying. (line 6) +* isearch-backward: deffnx. (line 22) +* isearch-forward: deffnx. (line 21) +* item <1>: Multitable Rows. (line 6) +* item <2>: table. (line 31) +* item: itemize. (line 22) +* itemize: itemize. (line 6) +* itemx: itemx. (line 6) +* kbd: kbd. (line 6) +* kbdinputstyle: kbd. (line 26) +* key: key. (line 6) +* l: Inserting Accents. (line 37) +* L: Inserting Accents. (line 37) +* LaTeX: tex. (line 6) +* lisp: lisp. (line 6) +* listoffloats: listoffloats. (line 6) +* lowersections: Raise/lower sections. + (line 6) +* macro: Defining Macros. (line 6) +* majorheading: majorheading & chapheading. + (line 6) +* makeinfo-buffer: makeinfo in Emacs. (line 16) +* makeinfo-kill-job: makeinfo in Emacs. (line 37) +* makeinfo-recenter-output-buffer: makeinfo in Emacs. (line 42) +* makeinfo-region: makeinfo in Emacs. (line 12) +* math: math. (line 6) +* menu: Menus. (line 6) +* minus: minus. (line 6) +* multitable: Multi-column Tables. (line 6) +* need: need. (line 6) +* next-error: makeinfo in Emacs. (line 26) +* node: node. (line 6) +* noindent: noindent. (line 6) +* novalidate: Format with tex/texindex. + (line 84) +* o: Inserting Accents. (line 37) +* O: Inserting Accents. (line 37) +* occur: Using occur. (line 6) +* occur-mode-goto-occurrence: Showing the Structure. + (line 22) +* oddfooting: Custom Headings. (line 51) +* oddheading: Custom Headings. (line 51) +* oe: Inserting Accents. (line 37) +* OE: Inserting Accents. (line 37) +* option: option. (line 6) +* ordf: Inserting Accents. (line 37) +* ordm: Inserting Accents. (line 37) +* page: page. (line 6) +* page, within @titlepage: titlepage. (line 17) +* pagesizes: pagesizes. (line 6) +* paragraphindent: paragraphindent. (line 6) +* phoo: definfoenclose. (line 35) +* point: Point Glyph. (line 6) +* pounds: pounds. (line 6) +* print: Print Glyph. (line 6) +* printindex: Printing Indices & Menus. + (line 23) +* pxref: pxref. (line 6) +* questiondown: Inserting Accents. (line 37) +* quotation: quotation. (line 6) +* r (roman font): Fonts. (line 6) +* raisesections: Raise/lower sections. + (line 6) +* ref: ref. (line 6) +* registeredsymbol: registered symbol. (line 6) +* result: result. (line 6) +* ringaccent: Inserting Accents. (line 17) +* rmacro: Defining Macros. (line 44) +* samp: samp. (line 6) +* sc (small caps font): Smallcaps. (line 6) +* section: section. (line 6) +* setchapternewpage: setchapternewpage. (line 6) +* setcontentsaftertitlepage: Contents. (line 51) +* setfilename: setfilename. (line 6) +* setshortcontentsaftertitlepage: Contents. (line 51) +* settitle: settitle. (line 6) +* shortcaption: caption shortcaption. + (line 6) +* shortcontents: Contents. (line 6) +* shorttitlepage: titlepage. (line 46) +* smallbook: smallbook. (line 6) +* smalldisplay <1>: small. (line 6) +* smalldisplay: display. (line 16) +* smallexample: small. (line 6) +* smallformat <1>: format. (line 15) +* smallformat: small. (line 6) +* smalllisp: small. (line 6) +* sp (line spacing): sp. (line 6) +* sp (titlepage line spacing): titlefont center sp. (line 6) +* ss: Inserting Accents. (line 37) +* strong: emph & strong. (line 6) +* subheading: unnumberedsubsec appendixsubsec subheading. + (line 6) +* subsection: subsection. (line 6) +* subsubheading: subsubsection. (line 6) +* subsubsection: subsubsection. (line 6) +* subtitle: title subtitle author. + (line 6) +* summarycontents: Contents. (line 6) +* syncodeindex: syncodeindex. (line 6) +* synindex: synindex. (line 6) +* t (typewriter font): Fonts. (line 6) +* tab: Multitable Rows. (line 6) +* table: Two-column Tables. (line 6) +* tex: Raw Formatter Commands. + (line 21) +* TeX: tex. (line 6) +* texinfo-all-menus-update: Updating Commands. (line 112) +* texinfo-every-node-update: Updating Commands. (line 107) +* texinfo-format-buffer <1>: texinfo-format commands. + (line 23) +* texinfo-format-buffer: Info Formatting. (line 22) +* texinfo-format-region <1>: texinfo-format commands. + (line 19) +* texinfo-format-region: Info Formatting. (line 13) +* texinfo-indent-menu-description: Other Updating Commands. + (line 45) +* texinfo-insert-@code: Inserting. (line 15) +* texinfo-insert-@dfn: Inserting. (line 19) +* texinfo-insert-@end: Inserting. (line 23) +* texinfo-insert-@example: Inserting. (line 62) +* texinfo-insert-@item: Inserting. (line 30) +* texinfo-insert-@kbd: Inserting. (line 35) +* texinfo-insert-@node: Inserting. (line 39) +* texinfo-insert-@noindent: Inserting. (line 44) +* texinfo-insert-@samp: Inserting. (line 49) +* texinfo-insert-@table: Inserting. (line 53) +* texinfo-insert-@var: Inserting. (line 58) +* texinfo-insert-braces: Inserting. (line 67) +* texinfo-insert-node-lines: Other Updating Commands. + (line 10) +* texinfo-make-menu: Updating Commands. (line 93) +* texinfo-master-menu: Updating Commands. (line 55) +* texinfo-multiple-files-update: texinfo-multiple-files-update. + (line 6) +* texinfo-multiple-files-update (in brief): Other Updating Commands. + (line 34) +* texinfo-sequential-node-update: Other Updating Commands. + (line 54) +* texinfo-show-structure <1>: Showing the Structure. + (line 18) +* texinfo-show-structure: Using texinfo-show-structure. + (line 6) +* texinfo-start-menu-description: Inserting. (line 94) +* texinfo-tex-buffer: Printing. (line 21) +* texinfo-tex-print: Printing. (line 42) +* texinfo-tex-region: Printing. (line 27) +* texinfo-update-node: Updating Commands. (line 83) +* thischapter: Custom Headings. (line 73) +* thischaptername: Custom Headings. (line 70) +* thisfile: Custom Headings. (line 81) +* thispage: Custom Headings. (line 67) +* thistitle: Custom Headings. (line 77) +* tie (unbreakable interword space): tie. (line 6) +* tieaccent: Inserting Accents. (line 17) +* title: title subtitle author. + (line 6) +* titlefont: titlefont center sp. (line 6) +* titlepage: titlepage. (line 6) +* today: Custom Headings. (line 90) +* top: The Top Node. (line 13) +* top (@-command): makeinfo top command. + (line 6) +* u (breve accent): Inserting Accents. (line 17) +* ubaraccent: Inserting Accents. (line 17) +* udotaccent: Inserting Accents. (line 17) +* unmacro: Defining Macros. (line 56) +* unnumbered: unnumbered & appendix. + (line 6) +* unnumberedsec: unnumberedsec appendixsec heading. + (line 6) +* unnumberedsubsec: unnumberedsubsec appendixsubsec subheading. + (line 6) +* unnumberedsubsubsec: subsubsection. (line 6) +* up-list: Inserting. (line 72) +* uref: uref. (line 6) +* v (check accent): Inserting Accents. (line 17) +* value: set value. (line 6) +* var: var. (line 6) +* verb: verb. (line 6) +* verbatim: verbatim. (line 6) +* verbatiminclude: verbatiminclude. (line 6) +* vskip TeX vertical skip: Copyright. (line 12) +* vtable: ftable vtable. (line 6) +* w (prevent line break): w. (line 6) +* xml: Raw Formatter Commands. + (line 49) +* xref: xref. (line 6) +* { (literal {): Inserting Braces. (line 6) +* } (literal }): Inserting Braces. (line 6) +* ~ (tilde accent): Inserting Accents. (line 17) + + +File: texinfo.info, Node: Concept Index, Prev: Command and Variable Index, Up: Top + +Concept Index +************* + + +* Menu: + +* !: Inserting Accents. (line 37) +* $Id: GNU Sample Texts. (line 21) +* $Id expansion, preventing: w. (line 28) +* (dir) as Up node of Top node: First Node. (line 13) +* --commands-in-node-names: makeinfo options. (line 34) +* --css-include: makeinfo options. (line 41) +* --delete: Invoking install-info. + (line 32) +* --dir-file=NAME: Invoking install-info. + (line 38) +* --docbook: makeinfo options. (line 46) +* --enable-encoding <1>: makeinfo options. (line 49) +* --enable-encoding: documentencoding. (line 26) +* --entry=TEXT: Invoking install-info. + (line 43) +* --error-limit=LIMIT: makeinfo options. (line 55) +* --fill-column=WIDTH: makeinfo options. (line 61) +* --footnote-style, ignored in HTML output: HTML Translation. (line 13) +* --footnote-style=STYLE: makeinfo options. (line 70) +* --force: makeinfo options. (line 81) +* --help <1>: makeinfo options. (line 86) +* --help: Invoking install-info. + (line 51) +* --html: makeinfo options. (line 90) +* --ifdocbook: makeinfo options. (line 104) +* --ifhtml: makeinfo options. (line 105) +* --ifinfo: makeinfo options. (line 106) +* --ifplaintext: makeinfo options. (line 107) +* --iftex: makeinfo options. (line 108) +* --ifxml: makeinfo options. (line 109) +* --info-dir=DIR: Invoking install-info. + (line 61) +* --info-file=FILE: Invoking install-info. + (line 56) +* --item=TEXT: Invoking install-info. + (line 65) +* --macro-expand=FILE: makeinfo options. (line 117) +* --no-headers: makeinfo options. (line 123) +* --no-ifdocbook: makeinfo options. (line 138) +* --no-ifhtml: makeinfo options. (line 139) +* --no-ifinfo: makeinfo options. (line 140) +* --no-ifplaintext: makeinfo options. (line 141) +* --no-iftex: makeinfo options. (line 142) +* --no-ifxml: makeinfo options. (line 143) +* --no-number-footnotes: makeinfo options. (line 173) +* --no-pointer-validate: makeinfo options. (line 156) +* --no-split: makeinfo options. (line 148) +* --no-validate: makeinfo options. (line 156) +* --no-warn: makeinfo options. (line 163) +* --number-sections: makeinfo options. (line 169) +* --output=FILE: makeinfo options. (line 179) +* --paragraph-indent=INDENT: makeinfo options. (line 193) +* --quiet: Invoking install-info. + (line 69) +* --reference-limit=LIMIT: makeinfo options. (line 209) +* --remove: Invoking install-info. + (line 73) +* --section=SEC: Invoking install-info. + (line 77) +* --split-size=NUM: makeinfo options. (line 215) +* --verbose: makeinfo options. (line 222) +* --version <1>: makeinfo options. (line 228) +* --version: Invoking install-info. + (line 84) +* --xml: makeinfo options. (line 231) +* -D DIR: Invoking install-info. + (line 61) +* -d NAME: Invoking install-info. + (line 38) +* -D VAR: makeinfo options. (line 30) +* -E FILE: makeinfo options. (line 117) +* -e LIMIT: makeinfo options. (line 55) +* -e TEXT: Invoking install-info. + (line 43) +* -F: makeinfo options. (line 81) +* -f WIDTH: makeinfo options. (line 61) +* -h <1>: makeinfo options. (line 86) +* -h: Invoking install-info. + (line 51) +* -I DIR: makeinfo options. (line 96) +* -i FILE: Invoking install-info. + (line 56) +* -o FILE: makeinfo options. (line 179) +* -P DIR: makeinfo options. (line 187) +* -p INDENT: makeinfo options. (line 193) +* -r: Invoking install-info. + (line 73) +* -r LIMIT: makeinfo options. (line 209) +* -s SEC: Invoking install-info. + (line 77) +* -s STYLE: makeinfo options. (line 70) +* -V <1>: Invoking install-info. + (line 84) +* -V: makeinfo options. (line 228) +* .cshrc initialization file: Preparing for TeX. (line 6) +* .profile initialization file: Preparing for TeX. (line 6) +* /l: Inserting Accents. (line 37) +* /L: Inserting Accents. (line 37) +* /O: Inserting Accents. (line 37) +* /o: Inserting Accents. (line 37) +* 8-bit characters, in HTML cross-references: HTML Xref 8-bit Character Expansion. + (line 6) +* <acronym> tag: acronym. (line 15) +* <blockquote> HTML tag: quotation. (line 45) +* <lineannotation> Docbook tag: Fonts. (line 25) +* <meta> HTML tag, and charset specification: documentencoding. + (line 35) +* <meta> HTML tag, and document description: documentdescription. + (line 6) +* <note> Docbook tag: quotation. (line 45) +* <small> tag: Smallcaps. (line 25) +* <thead> HTML tag: Multitable Rows. (line 12) +* <title> HTML tag: settitle. (line 21) +* <URL: convention, not used: uref. (line 71) +* ?: Inserting Accents. (line 37) +* @ as continuation in definition commands: Def Cmd Continuation Lines. + (line 6) +* @-command list: Command List. (line 6) +* @-command syntax: Command Syntax. (line 6) +* @-commands: Formatting Commands. (line 6) +* @-commands in @node, limited support: Pointer Validation. (line 36) +* @-commands in nodename: Node Line Requirements. + (line 23) +* @import specifications, in CSS files: HTML CSS. (line 30) +* @include file sample: Sample Include File. (line 6) +* @menu parts: Menu Parts. (line 6) +* @node line writing: Writing a Node. (line 6) +* @value in @node lines: Pointer Validation. (line 66) +* @w, for blank items: itemize. (line 10) +* \input source line ignored: setfilename. (line 16) +* a: Inserting Accents. (line 37) +* A4 paper, printing on: A4 Paper. (line 6) +* A5 paper, printing on: A4 Paper. (line 6) +* AA: Inserting Accents. (line 37) +* aa: Inserting Accents. (line 37) +* Abbreviations for keys: key. (line 19) +* Abbreviations, tagging: acronym. (line 6) +* Abstract of document: documentdescription. (line 6) +* Accents, inserting: Inserting Accents. (line 6) +* Acronyms, tagging: acronym. (line 6) +* Acute accent: Inserting Accents. (line 17) +* Adding a new Info file: New Info File. (line 6) +* ae: Inserting Accents. (line 37) +* AE: Inserting Accents. (line 37) +* Aliases, command: alias. (line 6) +* All-permissive copying license: All-permissive Copying License. + (line 6) +* Allow line break: Line Breaks. (line 6) +* Alphabetical @-command list: Command List. (line 6) +* Alt attribute for images: Image Syntax. (line 30) +* Anchors: anchor. (line 6) +* Another Info directory: Other Info Directories. + (line 6) +* Arguments, repeated and optional: Optional Arguments. (line 6) +* ASCII text output: makeinfo options. (line 123) +* Aspect ratio of images: Image Scaling. (line 6) +* autoexec.bat: Other Info Directories. + (line 70) +* automake, and version info: GNU Sample Texts. (line 32) +* Automatic pointer creation with makeinfo: makeinfo Pointer Creation. + (line 6) +* Automatically insert nodes, menus: Updating Nodes and Menus. + (line 6) +* Auxiliary files, avoiding: Format with tex/texindex. + (line 84) +* B5 paper, printing on: pagesizes. (line 16) +* Back-end output formats: Output Formats. (line 6) +* Backslash in macros: Defining Macros. (line 37) +* Backslash, and macros: Invoking Macros. (line 23) +* Badly referenced nodes: Running Info-Validate. + (line 6) +* Bastard title page: titlepage. (line 46) +* Batch formatting for Info: Batch Formatting. (line 6) +* Beebe, Nelson: Output Formats. (line 51) +* Beginning a Texinfo file: Beginning a File. (line 6) +* Beginning line of a Texinfo file: First Line. (line 6) +* Berry, Karl: History. (line 6) +* Big points: Image Scaling. (line 24) +* Black rectangle in hardcopy: Overfull hboxes. (line 41) +* Blank lines: sp. (line 6) +* Blank lines, as paragraph separator: Conventions. (line 16) +* Body of a macro: Defining Macros. (line 26) +* Bold font: Fonts. (line 15) +* Bolio: History. (line 30) +* Book characteristics, printed: Printed Books. (line 6) +* Book, printing small: smallbook. (line 6) +* border-pattern: Object-Oriented Variables. + (line 58) +* border-pattern of Window: Object-Oriented Variables. + (line 77) +* BoTeX: History. (line 30) +* Box with rounded corners: cartouche. (line 6) +* Box, ugly black in hardcopy: Overfull hboxes. (line 41) +* Braces and argument syntax: Command Syntax. (line 40) +* Braces, in macro arguments: Invoking Macros. (line 38) +* Braces, inserting: Inserting Braces. (line 6) +* Braces, when to use: Formatting Commands. (line 50) +* Breaks in a line: Line Breaks. (line 6) +* Breve accent: Inserting Accents. (line 17) +* Buffer formatting and printing: Printing. (line 6) +* Bugs, reporting: Reporting Bugs. (line 6) +* Bullets, inserting: Dots Bullets. (line 6) +* Captions, for floats: caption shortcaption. + (line 6) +* Caron accent: Inserting Accents. (line 17) +* Cascading Style Sheets, and HTML output: HTML CSS. (line 6) +* Case in node name: Node Line Requirements. + (line 42) +* Case, not altering in @code: code. (line 19) +* Catching errors with Info formatting: Debugging with Info. (line 6) +* Catching errors with TeX formatting: Debugging with TeX. (line 6) +* Catching mistakes: Catching Mistakes. (line 6) +* Categories, choosing: Installing Dir Entries. + (line 45) +* Cedilla accent: Inserting Accents. (line 17) +* Centimeters: Image Scaling. (line 30) +* Chapter structuring: Structuring. (line 6) +* Chapters, formatting one at a time: Format with tex/texindex. + (line 84) +* Character set, declaring: documentencoding. (line 6) +* Characteristics, printed books or manuals: Printed Books. (line 6) +* Characters, basic input: Conventions. (line 6) +* Characters, invalid in node name: Node Line Requirements. + (line 30) +* Chassell, Robert J.: History. (line 6) +* Check accent: Inserting Accents. (line 17) +* Checking for badly referenced nodes: Running Info-Validate. + (line 6) +* Checklist for bug reports: Reporting Bugs. (line 11) +* Ciceros: Image Scaling. (line 39) +* Circumflex accent: Inserting Accents. (line 17) +* code, value for @kbdinputstyle: kbd. (line 32) +* Collapsing whitespace around continuations: Def Cmd Continuation Lines. + (line 31) +* Colon in nodename: Node Line Requirements. + (line 30) +* Colon, last in INFOPATH: Other Info Directories. + (line 80) +* Column widths, defining for multitables: Multitable Column Widths. + (line 6) +* Combining indices: Combining Indices. (line 6) +* Comma in nodename: Node Line Requirements. + (line 30) +* Comma, in macro arguments: Invoking Macros. (line 38) +* Command aliases: alias. (line 6) +* Command definitions: Sample Function Definition. + (line 6) +* Command names, indicating: command. (line 6) +* Command syntax: Command Syntax. (line 6) +* Commands to insert special characters: Atsign Braces Comma. (line 6) +* Commands using raw TeX: Raw Formatter Commands. + (line 6) +* Commands, inserting them: Inserting. (line 6) +* Commas, inserting: Inserting a Comma. (line 6) +* Comments: Comments. (line 6) +* Comments, in CSS files: HTML CSS. (line 36) +* Compile command for formatting: Compile-Command. (line 6) +* Compressed files, reading: Invoking install-info. + (line 22) +* Conditionally visible text: Conditionals. (line 6) +* Conditionals, nested: Conditional Nesting. (line 6) +* Conditions for copying Texinfo: Copying Conditions. (line 6) +* Contents, after title page: Contents. (line 51) +* Contents, Table of: Contents. (line 6) +* Contents-like outline of file structure: Showing the Structure. + (line 6) +* Continuation lines in definition commands: Def Cmd Continuation Lines. + (line 6) +* Conventions for writing definitions: Def Cmd Conventions. (line 6) +* Conventions, syntactic: Conventions. (line 6) +* Copying conditions: Copying Conditions. (line 6) +* Copying Permissions: Document Permissions. + (line 6) +* Copying software: Software Copying Permissions. + (line 6) +* Copying text, including: insertcopying. (line 6) +* Copyright holder for FSF works: copying. (line 53) +* Copyright page: Copyright. (line 6) +* Copyright page, for plain text: Titlepage & Copyright Page. + (line 16) +* Copyright word, always in English: copying. (line 44) +* Correcting mistakes: Catching Mistakes. (line 6) +* cp (concept) index: Predefined Indices. (line 10) +* Create nodes, menus automatically: Updating Nodes and Menus. + (line 6) +* Creating an Info file: Creating an Info File. + (line 6) +* Creating an unsplit file: Unsplit. (line 6) +* Creating index entries: Indexing Commands. (line 6) +* Creating pointers with makeinfo: makeinfo Pointer Creation. + (line 6) +* Cropmarks for printing: Cropmarks and Magnification. + (line 6) +* Cross reference parts: Cross Reference Parts. + (line 6) +* Cross references: Cross References. (line 6) +* Cross references using @inforef: inforef. (line 6) +* Cross references using @pxref: pxref. (line 6) +* Cross references using @ref: ref. (line 6) +* Cross references using @xref: xref. (line 6) +* Cross-reference targets, arbitrary: anchor. (line 6) +* Cross-references, in HTML output: HTML Xref. (line 6) +* CSS, and HTML output: HTML CSS. (line 6) +* Custom page sizes: pagesizes. (line 6) +* Customize Emacs package (Development/Docs/Texinfo): Texinfo Mode Printing. + (line 92) +* Customized highlighting: definfoenclose. (line 6) +* Customizing of TeX for Texinfo: Preparing for TeX. (line 27) +* CVS $Id: GNU Sample Texts. (line 21) +* Dashes in source: Conventions. (line 41) +* Debugging the Texinfo structure: Catching Mistakes. (line 6) +* Debugging with Info formatting: Debugging with Info. (line 6) +* Debugging with TeX formatting: Debugging with TeX. (line 6) +* Defining indexing entries: Indexing Commands. (line 6) +* Defining macros: Defining Macros. (line 6) +* Defining new indices: New Indices. (line 6) +* Defining new Texinfo commands: Defining New Texinfo Commands. + (line 6) +* Definition command headings, continuing: Def Cmd Continuation Lines. + (line 6) +* Definition commands: Definition Commands. (line 6) +* Definition conventions: Def Cmd Conventions. (line 6) +* Definition lists, typesetting: table. (line 6) +* Definition template: Def Cmd Template. (line 6) +* Definitions grouped together: deffnx. (line 6) +* Delimiter character, for verbatim: verb. (line 6) +* Depth of text area: pagesizes. (line 6) +* Description for menu, start: Inserting. (line 94) +* Description of document: documentdescription. (line 6) +* Details of macro usage: Macro Details. (line 6) +* Dido^t points: Image Scaling. (line 36) +* Different cross reference commands: Cross Reference Commands. + (line 6) +* Dimension formatting: dmn. (line 6) +* Dimensions and image sizes: Image Scaling. (line 14) +* Dir categories, choosing: Installing Dir Entries. + (line 45) +* dir directory for Info installation: Installing an Info File. + (line 6) +* dir file listing: New Info File. (line 6) +* dir file, creating your own: Other Info Directories. + (line 91) +* dir files and Info directories: Other Info Directories. + (line 6) +* Dir files, compressed: Invoking install-info. + (line 22) +* dir, created by install-info: Invoking install-info. + (line 19) +* Display formatting: display. (line 6) +* Displayed equations: math. (line 33) +* distinct, value for @kbdinputstyle: kbd. (line 32) +* Distorting images: Image Scaling. (line 6) +* Distribution: Software Copying Permissions. + (line 6) +* Docbook output: Output Formats. (line 70) +* Docbook, including raw: Raw Formatter Commands. + (line 6) +* Document description: documentdescription. (line 6) +* Document input encoding: documentencoding. (line 6) +* Document language, declaring: documentlanguage. (line 6) +* Document Permissions: Document Permissions. + (line 6) +* Documentation identification: GNU Sample Texts. (line 21) +* Dot accent: Inserting Accents. (line 17) +* Dotless i, j: Inserting Accents. (line 37) +* Dots, inserting <1>: dots. (line 6) +* Dots, inserting: Dots Bullets. (line 6) +* Double-colon menu entries: Less Cluttered Menu Entry. + (line 6) +* DTD, for Texinfo XML: Output Formats. (line 60) +* Dumas, Patrice: HTML Xref. (line 21) +* Dumping a .fmt file: Preparing for TeX. (line 74) +* DVI file: Format with tex/texindex. + (line 6) +* DVI output: Output Formats. (line 36) +* dvips: Output Formats. (line 36) +* Ellipsis, inserting: Dots Bullets. (line 6) +* Em dash, compared to minus sign: minus. (line 6) +* Em dash, producing: Conventions. (line 41) +* Emacs: Texinfo Mode. (line 6) +* Emacs shell, format, print from: Within Emacs. (line 6) +* Emacs-W3: Output Formats. (line 26) +* Emphasizing text: Emphasis. (line 6) +* Emphasizing text, font for: emph & strong. (line 6) +* En dash, producing: Conventions. (line 41) +* Encoding, declaring: documentencoding. (line 6) +* End node footnote style: Footnote Styles. (line 9) +* End of header line: End of Header. (line 6) +* End titlepage starts headings: end titlepage. (line 6) +* Ending a Sentence: Ending a Sentence. (line 6) +* Ending a Texinfo file: Ending a File. (line 6) +* Entries for an index: Indexing Commands. (line 6) +* Entries, making index: Index Entries. (line 6) +* Enumeration: enumerate. (line 6) +* Environment indentation: exampleindent. (line 6) +* Environment variable INFOPATH: Other Info Directories. + (line 50) +* Environment variable TEXINFO_OUTPUT_FORMAT: makeinfo options. + (line 234) +* Environment variable TEXINPUTS: Preparing for TeX. (line 37) +* epsf.tex: Image Scaling. (line 49) +* epsf.tex, installing: Preparing for TeX. (line 20) +* Equations, displayed: math. (line 33) +* Equivalence, indicating: Equivalence. (line 6) +* Error message, indicating: Error Glyph. (line 6) +* Errors, parsing: makeinfo in Emacs. (line 26) +* Es-zet: Inserting Accents. (line 37) +* European A4 paper: A4 Paper. (line 6) +* Evaluation glyph: result. (line 6) +* Example beginning of Texinfo file: Sample Beginning. (line 6) +* Example indentation: exampleindent. (line 6) +* Example menu: Menu Example. (line 6) +* example, value for @kbdinputstyle: kbd. (line 32) +* Examples in smaller fonts: small. (line 6) +* Examples, formatting them: example. (line 6) +* Examples, glyphs for: Glyphs. (line 6) +* Expanding macros: Invoking Macros. (line 6) +* Expansion of 8-bit characters in HTML cross-references: HTML Xref 8-bit Character Expansion. + (line 6) +* Expansion, indicating: expansion. (line 6) +* expansion, of node names in HTML cross-references: HTML Xref Node Name Expansion. + (line 6) +* Expressions in a program, indicating: code. (line 10) +* F.B.I., as acronym: acronym. (line 6) +* FDL, GNU Free Documentation License: GNU Free Documentation License. + (line 6) +* Feminine ordinal: Inserting Accents. (line 37) +* File beginning: Beginning a File. (line 6) +* File ending: Ending a File. (line 6) +* File name collision: setfilename. (line 26) +* File section structure, showing it: Showing the Structure. + (line 6) +* Final output: Overfull hboxes. (line 6) +* Finding badly referenced nodes: Running Info-Validate. + (line 6) +* Fine-tuning, and hyphenation: - and hyphenation. (line 6) +* First line of a Texinfo file: First Line. (line 6) +* First node: First Node. (line 6) +* First paragraph, suppressing indentation of: firstparagraphindent. + (line 6) +* Fixed-width font: Fonts. (line 18) +* Float environment: float. (line 6) +* Floating accents, inserting: Inserting Accents. (line 6) +* Floating, not yet implemented: Floats. (line 10) +* Floats, in general: Floats. (line 6) +* Floats, list of: listoffloats. (line 6) +* Floats, making unnumbered: float. (line 39) +* Floats, numbering of: float. (line 46) +* Flooding: pxref. (line 34) +* fn (function) index: Predefined Indices. (line 13) +* Fonts for indices: syncodeindex. (line 52) +* Fonts for printing, not Info: Fonts. (line 6) +* Footings: Headings. (line 6) +* Footnotes: Footnotes. (line 6) +* Force line break: Line Breaks. (line 6) +* Forcing indentation: indent. (line 6) +* Forcing line and page breaks: Breaks. (line 6) +* Format a dimension: dmn. (line 6) +* Format and print hardcopy: Hardcopy. (line 6) +* Format and print in Texinfo mode: Texinfo Mode Printing. + (line 6) +* Format file, dumping: Preparing for TeX. (line 74) +* Format with the compile command: Compile-Command. (line 6) +* Format, print from Emacs shell: Within Emacs. (line 6) +* Formats for images: Image Syntax. (line 10) +* Formatting a file for Info: Creating an Info File. + (line 6) +* Formatting commands: Formatting Commands. (line 6) +* Formatting examples: example. (line 6) +* Formatting for Info: Info Formatting. (line 6) +* Formatting for printing: Printing. (line 6) +* Formatting headings and footings: Headings. (line 6) +* Formatting requirements: Requirements Summary. + (line 6) +* Formatting with tex and texindex: Format with tex/texindex. + (line 6) +* Formulas, mathematical: math. (line 6) +* Fox, Brian: History. (line 6) +* Free Documentation License, including entire: GNU Sample Texts. + (line 51) +* Free Software Directory: Installing Dir Entries. + (line 45) +* Frequently used commands, inserting: Inserting. (line 6) +* Frontmatter, text in: Beginning a File. (line 15) +* Full texts, GNU: GNU Sample Texts. (line 6) +* Function definitions: Sample Function Definition. + (line 6) +* General syntactic conventions: Conventions. (line 6) +* Generating menus with indices: Printing Indices & Menus. + (line 6) +* Generating plain text files: makeinfo options. (line 123) +* German S: Inserting Accents. (line 37) +* GIF images, unsupported due to patents: Image Syntax. (line 37) +* Global Document Commands: Global Document Commands. + (line 6) +* Globbing: Format with tex/texindex. + (line 32) +* Glyphs: Glyphs. (line 6) +* GNU Emacs: Texinfo Mode. (line 6) +* GNU Emacs shell, format, print from: Within Emacs. (line 6) +* GNU Free Documentation License, including entire: GNU Sample Texts. + (line 51) +* GNU sample texts: GNU Sample Texts. (line 6) +* Going to other Info files' nodes: Other Info Files. (line 6) +* Grave accent: Inserting Accents. (line 17) +* Grave accent, vs. left quote: Conventions. (line 35) +* Group (hold text together vertically): group. (line 6) +* Grouping two definitions together: deffnx. (line 6) +* Hacek accent: Inserting Accents. (line 17) +* Hardcopy, printing it: Hardcopy. (line 6) +* hboxes, overfull: Overfull hboxes. (line 6) +* Header for Texinfo files: Texinfo File Header. (line 6) +* Header of a Texinfo file: First Line. (line 6) +* Heading row, in table: Multitable Rows. (line 12) +* Headings: Headings. (line 6) +* Headings, indentation after: firstparagraphindent. + (line 6) +* Headings, page, begin to appear: end titlepage. (line 6) +* Height of images: Image Scaling. (line 6) +* Height of text area: pagesizes. (line 6) +* help2man: Output Formats. (line 88) +* Hierarchical documents, and menus: Menu Location. (line 16) +* Highlighting text: Indicating. (line 6) +* Highlighting, customized: definfoenclose. (line 6) +* Hints: Tips. (line 8) +* History of Texinfo: History. (line 24) +* Holder of copyright for FSF works: copying. (line 53) +* Holding text together vertically: group. (line 6) +* href, producing HTML: uref. (line 6) +* HTML cross-reference 8-bit character expansion: HTML Xref 8-bit Character Expansion. + (line 6) +* HTML cross-reference command expansion: HTML Xref Command Expansion. + (line 6) +* HTML cross-reference link basics: HTML Xref Link Basics. + (line 6) +* HTML cross-reference mismatch: HTML Xref Mismatch. (line 6) +* HTML cross-reference node name expansion: HTML Xref Node Name Expansion. + (line 6) +* HTML cross-references: HTML Xref. (line 6) +* HTML output <1>: Generating HTML. (line 6) +* HTML output: Output Formats. (line 26) +* HTML output, and encodings: documentencoding. (line 35) +* HTML output, browser compatibility of: HTML Translation. (line 22) +* HTML output, split: HTML Splitting. (line 6) +* HTML, and CSS: HTML CSS. (line 6) +* HTML, including raw: Raw Formatter Commands. + (line 6) +* http-equiv, and charset specification: documentencoding. (line 35) +* Hungarian umlaut accent: Inserting Accents. (line 17) +* Hurricanes: ref. (line 12) +* Hyphen, compared to minus: minus. (line 6) +* Hyphenation patterns, language-dependent: documentlanguage. (line 18) +* Hyphenation, helping TeX do: - and hyphenation. (line 6) +* Hyphenation, preventing: w. (line 24) +* Hyphens in source, two or three in a row: Conventions. (line 41) +* i (dotless i): Inserting Accents. (line 37) +* Identification of documentation: GNU Sample Texts. (line 21) +* If text conditionally visible: Conditionals. (line 6) +* Ignored before @setfilename: setfilename. (line 16) +* Ignored text: Comments. (line 19) +* Image formats: Image Syntax. (line 10) +* Images, alternate text for: Image Syntax. (line 30) +* Images, inserting: Images. (line 6) +* Images, scaling: Image Scaling. (line 6) +* Inches: Image Scaling. (line 27) +* Include file sample: Sample Include File. (line 6) +* Include files: Include Files. (line 6) +* Include files requirements: Include Files Requirements. + (line 6) +* Include files, and section levels: Raise/lower sections. + (line 16) +* Including a file verbatim: verbatiminclude. (line 6) +* Including permissions text: insertcopying. (line 6) +* Indentation undoing: exdent. (line 6) +* Indentation, forcing: indent. (line 6) +* Indentation, omitting: noindent. (line 6) +* Indenting environments: exampleindent. (line 6) +* Indenting paragraphs, control of: paragraphindent. (line 6) +* Indenting, suppressing of first paragraph: firstparagraphindent. + (line 6) +* Index entries: Indexing Commands. (line 6) +* Index entries, making: Index Entries. (line 6) +* Index entry writing: Indexing Commands. (line 27) +* Index file names: Format with tex/texindex. + (line 24) +* Index font types: Indexing Commands. (line 48) +* Indexing table entries automatically: ftable vtable. (line 6) +* Indicating commands, definitions, etc.: Indicating. (line 6) +* Indicating evaluation: result. (line 6) +* Indices: Indices. (line 6) +* Indices, combining them: Combining Indices. (line 6) +* Indices, defining new: New Indices. (line 6) +* Indices, printing and menus: Printing Indices & Menus. + (line 6) +* Indices, sorting: Hardcopy. (line 6) +* Indices, two letter names: syncodeindex. (line 17) +* Indirect subfiles: Tag and Split Files. (line 11) +* Info batch formatting: Batch Formatting. (line 6) +* Info file installation: Installing an Info File. + (line 6) +* Info file name, choosing: setfilename. (line 26) +* Info file, listing a new: New Info File. (line 6) +* Info file, splitting manually: Splitting. (line 6) +* Info files: Info Files. (line 6) +* Info format, and menus: Menu Location. (line 10) +* Info formatting: Info Formatting. (line 6) +* Info installed in another directory: Other Info Directories. + (line 6) +* Info output: Output Formats. (line 10) +* Info output, and encoding: documentencoding. (line 26) +* Info validating a large file: Using Info-validate. (line 6) +* Info, creating an online file: Creating an Info File. + (line 6) +* Info-directory-list: Other Info Directories. + (line 37) +* Info; other files' nodes: Other Info Files. (line 6) +* INFOPATH: Other Info Directories. + (line 50) +* Initialization file for TeX input: Preparing for TeX. (line 6) +* Input encoding, declaring: documentencoding. (line 6) +* Insert nodes, menus automatically: Updating Nodes and Menus. + (line 6) +* Inserting @ (literal @): Inserting an Atsign. (line 6) +* Inserting accents: Inserting Accents. (line 6) +* Inserting dots <1>: Dots Bullets. (line 6) +* Inserting dots: dots. (line 6) +* Inserting ellipsis: Dots Bullets. (line 6) +* Inserting frequently used commands: Inserting. (line 6) +* Inserting indentation: indent. (line 6) +* Inserting space: Inserting Space. (line 6) +* Inserting special characters and symbols: Insertions. (line 6) +* INSTALL file, generating: makeinfo options. (line 123) +* install-info: Invoking install-info. + (line 6) +* Installing an Info file: Installing an Info File. + (line 6) +* Installing Info in another directory: Other Info Directories. + (line 6) +* Internationalization: Internationalization. + (line 6) +* Introduction to Texinfo: Using Texinfo. (line 6) +* Introduction, as part of file: Software Copying Permissions. + (line 16) +* Invalid characters in node names: Node Line Requirements. + (line 30) +* Invoking macros: Invoking Macros. (line 6) +* Invoking nodes, including in dir file: Installing Dir Entries. + (line 62) +* ISO 639 codes: documentlanguage. (line 22) +* Italic font: Fonts. (line 12) +* Itemization: itemize. (line 6) +* j (dotless j): Inserting Accents. (line 37) +* JPG image format: Image Syntax. (line 37) +* Keyboard input: kbd. (line 6) +* Keys, recommended names: key. (line 19) +* Keyword expansion, preventing: w. (line 28) +* Keywords, indicating: code. (line 10) +* Knuth, Donald: Printed Books. (line 6) +* ky (keystroke) index: Predefined Indices. (line 17) +* Language codes: documentlanguage. (line 22) +* Language, declaring: documentlanguage. (line 6) +* Larger or smaller pages: Cropmarks and Magnification. + (line 24) +* LaTeX, processing with texi2dvi: Format with texi2dvi. + (line 32) +* Legal paper, printing on: pagesizes. (line 16) +* Length of file names: setfilename. (line 26) +* Less cluttered menu entry: Less Cluttered Menu Entry. + (line 6) +* License agreement: Software Copying Permissions. + (line 6) +* License for all-permissive copying: All-permissive Copying License. + (line 6) +* License for verbatim copying: Verbatim Copying License. + (line 6) +* Line breaks <1>: Breaks. (line 6) +* Line breaks: Line Breaks. (line 6) +* Line breaks, preventing: w. (line 6) +* Line length, column widths as fraction of: Multitable Column Widths. + (line 11) +* Line spacing: sp. (line 6) +* Lisp example: lisp. (line 6) +* Lisp examples in smaller fonts: small. (line 6) +* List of @-commands: Command List. (line 6) +* List of floats: listoffloats. (line 6) +* Listing a new Info file: New Info File. (line 6) +* Lists and tables, making: Lists and Tables. (line 6) +* Local variables: Compile-Command. (line 6) +* Local Variables: section, for encoding: documentencoding. (line 26) +* Location of menus: Menu Location. (line 6) +* Looking for badly referenced nodes: Running Info-Validate. + (line 6) +* Lowering and raising sections: Raise/lower sections. + (line 6) +* lpr (DVI print command): Print with lpr. (line 6) +* lpr-d, replacements on MS-DOS/MS-Windows: Print with lpr. (line 27) +* Lynx: Output Formats. (line 26) +* Macro definitions <1>: Defining Macros. (line 6) +* Macro definitions: Sample Function Definition. + (line 6) +* Macro details: Macro Details. (line 6) +* Macro expansion, indicating: expansion. (line 6) +* Macro invocation: Invoking Macros. (line 6) +* Macro names, valid characters in: Defining Macros. (line 16) +* Macron accent: Inserting Accents. (line 17) +* Macros: Defining New Texinfo Commands. + (line 6) +* Macros in definition commands: Def Cmd Template. (line 66) +* Macros, undefining: Defining Macros. (line 56) +* Magnified printing: Cropmarks and Magnification. + (line 24) +* Mailto link: email. (line 10) +* makeinfo: Invoking makeinfo. (line 6) +* makeinfo inside Emacs: makeinfo in Emacs. (line 6) +* makeinfo options: makeinfo options. (line 6) +* Making a printed manual: Hardcopy. (line 6) +* Making a tag table automatically: Tag and Split Files. (line 6) +* Making a tag table manually: Unsplit. (line 26) +* Making cross references: Cross References. (line 6) +* Making line and page breaks: Breaks. (line 6) +* Making lists and tables: Lists and Tables. (line 6) +* Man page output, not supported: Output Formats. (line 78) +* Man page, reference to: uref. (line 20) +* Manual characteristics, printed: Printed Books. (line 6) +* Margins on page, not controllable: pagesizes. (line 20) +* Marking text within a paragraph: Marking Text. (line 6) +* Marking words and phrases: Marking Text. (line 6) +* Masculine ordinal: Inserting Accents. (line 37) +* Master menu: Master Menu Parts. (line 6) +* Mathematical expressions <1>: Raw Formatter Commands. + (line 33) +* Mathematical expressions: math. (line 6) +* Menu description, start: Inserting. (line 94) +* Menu entries with two colons: Less Cluttered Menu Entry. + (line 6) +* Menu example: Menu Example. (line 6) +* Menu location: Menu Location. (line 6) +* Menu parts: Menu Parts. (line 6) +* Menu writing: Writing a Menu. (line 6) +* Menu, master: Master Menu Parts. (line 6) +* Menus: Menus. (line 6) +* Menus generated with indices: Printing Indices & Menus. + (line 6) +* Menus, omitting: makeinfo options. (line 123) +* META key: key. (line 53) +* Meta-syntactic chars for arguments: Optional Arguments. (line 6) +* Methods, object-oriented: Object-Oriented Methods. + (line 6) +* Millimeters: Image Scaling. (line 33) +* Minimal requirements for formatting: Requirements Summary. + (line 6) +* Minimal Texinfo file (requirements): Minimum. (line 6) +* Mismatched HTML cross-reference source and target: HTML Xref Mismatch. + (line 6) +* Mistakes, catching: Catching Mistakes. (line 6) +* Mode, using Texinfo: Texinfo Mode. (line 6) +* Monospace font: Fonts. (line 18) +* Mozilla: Output Formats. (line 26) +* Multiple dashes in source: Conventions. (line 41) +* Multiple spaces: Multiple Spaces. (line 6) +* Multitable column widths: Multitable Column Widths. + (line 6) +* Multitable rows: Multitable Rows. (line 6) +* Must have in Texinfo file: Minimum. (line 6) +* Mutually recursive macros: Defining Macros. (line 26) +* Names for indices: syncodeindex. (line 17) +* Names of index files: Format with tex/texindex. + (line 24) +* Names of macros, valid characters of: Defining Macros. (line 16) +* Names recommended for keys: key. (line 19) +* Naming a `Top' Node in references: Top Node Naming. (line 6) +* NASA, as acronym: acronym. (line 6) +* Navigation bar, in HTML output: HTML Translation. (line 16) +* Navigation links, omitting: makeinfo options. (line 129) +* Need space at page bottom: need. (line 6) +* Nesting conditionals: Conditional Nesting. (line 6) +* New index defining: New Indices. (line 6) +* New Info file, listing it in dir file: New Info File. (line 6) +* New Texinfo commands, defining: Defining New Texinfo Commands. + (line 6) +* Newlines, as blank lines: Conventions. (line 16) +* Next node of Top node: First Node. (line 30) +* Node line requirements: Node Line Requirements. + (line 6) +* Node line writing: Writing a Node. (line 6) +* node name expansion, in HTML cross-references: HTML Xref Node Name Expansion. + (line 6) +* Node name must be unique: Node Line Requirements. + (line 8) +* Node name, should not contain @-commands: Node Line Requirements. + (line 23) +* Node names, choosing: Node Names. (line 6) +* Node names, invalid characters in: Node Line Requirements. + (line 30) +* Node separators, omitting: makeinfo options. (line 123) +* Node, `Top': The Top Node. (line 6) +* Node, defined: node. (line 6) +* Nodes in other Info files: Other Info Files. (line 6) +* Nodes, catching mistakes: Catching Mistakes. (line 6) +* Nodes, checking for badly referenced: Running Info-Validate. + (line 6) +* Non-breakable space, fixed: w. (line 9) +* Non-breakable space, variable: tie. (line 6) +* Not ending a sentence: Not Ending a Sentence. + (line 6) +* Numbering of floats: float. (line 46) +* o: Inserting Accents. (line 37) +* O'Dea, Brendan: Output Formats. (line 88) +* Object-oriented programming: Abstract Objects. (line 6) +* Obtaining TeX: Obtaining TeX. (line 6) +* Occurrences, listing with @occur: Using occur. (line 6) +* OE: Inserting Accents. (line 37) +* oe: Inserting Accents. (line 37) +* Omitting indentation: noindent. (line 6) +* Optional and repeated arguments: Optional Arguments. (line 6) +* Options for makeinfo: makeinfo options. (line 6) +* Ordinals, Romance: Inserting Accents. (line 37) +* Ordinary TeX commands, using: Raw Formatter Commands. + (line 6) +* Other Info files' nodes: Other Info Files. (line 6) +* Outline of file structure, showing it: Showing the Structure. + (line 6) +* Output file splitting: makeinfo options. (line 148) +* Output formats: Output Formats. (line 6) +* Output formats, supporting more: Output Formats. (line 95) +* Overfull hboxes: Overfull hboxes. (line 6) +* Overview of Texinfo: Overview. (line 6) +* Owner of copyright for FSF works: copying. (line 53) +* Page breaks <1>: page. (line 6) +* Page breaks: Breaks. (line 11) +* Page delimiter in Texinfo mode: Showing the Structure. + (line 40) +* Page headings: Headings. (line 6) +* Page numbering: Headings. (line 6) +* Page sizes for books: smallbook. (line 6) +* Page sizes, customized: pagesizes. (line 6) +* page-delimiter: Showing the Structure. + (line 40) +* Pages, starting odd: setchapternewpage. (line 6) +* Paper size, A4: A4 Paper. (line 6) +* Paragraph indentation control: paragraphindent. (line 6) +* Paragraph separator: Conventions. (line 16) +* Paragraph, marking text within: Marking Text. (line 6) +* Parameters to macros: Defining Macros. (line 32) +* Parentheses in nodename: Node Line Requirements. + (line 30) +* Parsing errors: makeinfo in Emacs. (line 26) +* Part of file formatting and printing: Printing. (line 6) +* Parts of a cross reference: Cross Reference Parts. + (line 6) +* Parts of a master menu: Master Menu Parts. (line 6) +* Parts of a menu: Menu Parts. (line 6) +* Patches, contributing: Reporting Bugs. (line 30) +* PDF output <1>: PDF Output. (line 6) +* PDF output: Output Formats. (line 51) +* pdfcolor.tex, installing: Preparing for TeX. (line 24) +* pdftex <1>: Output Formats. (line 51) +* pdftex: PDF Output. (line 6) +* pdftex, and images: Image Syntax. (line 15) +* Period in nodename: Node Line Requirements. + (line 30) +* Periods, inserting: Not Ending a Sentence. + (line 6) +* Permissions text, including: insertcopying. (line 6) +* Permissions, printed: Copyright. (line 6) +* pg (program) index: Predefined Indices. (line 20) +* Picas: Image Scaling. (line 21) +* Pictures, inserting: Images. (line 6) +* Pinard, Franc,ois: History. (line 14) +* Plain TeX: Raw Formatter Commands. + (line 6) +* Plain text output <1>: Output Formats. (line 21) +* Plain text output: makeinfo options. (line 123) +* PNG image format: Image Syntax. (line 37) +* Point, indicating in a buffer: Point Glyph. (line 6) +* Pointer creation with makeinfo: makeinfo Pointer Creation. + (line 6) +* Pointer validation with makeinfo: Pointer Validation. (line 6) +* Pointer validation, suppressing <1>: makeinfo options. (line 156) +* Pointer validation, suppressing: Format with tex/texindex. + (line 84) +* Points (dimension): Image Scaling. (line 18) +* Predefined names for indices: syncodeindex. (line 17) +* Preparing for TeX: Preparing for TeX. (line 6) +* Preventing first paragraph indentation: firstparagraphindent. + (line 6) +* Preventing line and page breaks: Breaks. (line 6) +* Previous node of Top node: First Node. (line 24) +* Print and format in Texinfo mode: Texinfo Mode Printing. + (line 6) +* Print, format from Emacs shell: Within Emacs. (line 6) +* Printed book and manual characteristics: Printed Books. (line 6) +* Printed output, indicating: Print Glyph. (line 6) +* Printed permissions: Copyright. (line 6) +* Printing a region or buffer: Printing. (line 6) +* Printing an index: Printing Indices & Menus. + (line 6) +* Printing cropmarks: Cropmarks and Magnification. + (line 6) +* Printing DVI files, on MS-DOS/MS-Windows: Print with lpr. (line 27) +* Printing hardcopy: Hardcopy. (line 6) +* Problems, catching: Catching Mistakes. (line 6) +* Program names, indicating: command. (line 6) +* Prototype row, column widths defined by: Multitable Column Widths. + (line 22) +* Quotation characters (`'), in source: Conventions. (line 24) +* Quotations: quotation. (line 6) +* Ragged left: flushleft & flushright. + (line 6) +* Ragged right: flushleft & flushright. + (line 6) +* Raising and lowering sections: Raise/lower sections. + (line 6) +* Raw formatter commands: Raw Formatter Commands. + (line 6) +* RCS $Id: GNU Sample Texts. (line 21) +* Recommended names for keys: key. (line 19) +* Rectangle, black in hardcopy: Overfull hboxes. (line 41) +* Recursion, mutual: Defining Macros. (line 26) +* Recursive macro invocations: Defining Macros. (line 44) +* Reference to @-commands: Command List. (line 6) +* References: Cross References. (line 6) +* References using @inforef: inforef. (line 6) +* References using @pxref: pxref. (line 6) +* References using @ref: ref. (line 6) +* References using @xref: xref. (line 6) +* Referring to other Info files: Other Info Files. (line 6) +* Region formatting and printing: Printing. (line 6) +* Region printing in Texinfo mode: Texinfo Mode Printing. + (line 6) +* Reid, Brian: History. (line 24) +* Repeated and optional arguments: Optional Arguments. (line 6) +* Reporting bugs: Reporting Bugs. (line 6) +* Required in Texinfo file: Minimum. (line 6) +* Requirements for formatting: Requirements Summary. + (line 6) +* Requirements for include files: Include Files Requirements. + (line 6) +* Requirements for updating commands: Updating Requirements. + (line 6) +* Reserved words, indicating: code. (line 10) +* Restrictions on node names: Node Line Requirements. + (line 6) +* Result of an expression: result. (line 6) +* ridt.eps: Image Scaling. (line 44) +* Ring accent: Inserting Accents. (line 17) +* Roman font: Fonts. (line 21) +* Romance ordinals: Inserting Accents. (line 37) +* Rounded rectangles, around examples: cartouche. (line 6) +* Rows, of a multitable: Multitable Rows. (line 6) +* Running an Info formatter: Info Formatting. (line 6) +* Running Info-validate: Using Info-validate. (line 6) +* Running macros: Invoking Macros. (line 6) +* Running makeinfo in Emacs: makeinfo in Emacs. (line 6) +* Sample @include file: Sample Include File. (line 6) +* Sample function definition: Sample Function Definition. + (line 6) +* Sample Texinfo file, no comments: Short Sample Texinfo File. + (line 6) +* Sample Texinfo file, with comments: Short Sample. (line 6) +* Sample Texinfo files: Sample Texinfo Files. + (line 6) +* Sample texts, GNU: GNU Sample Texts. (line 6) +* Scaled points: Image Scaling. (line 42) +* Scaling images: Image Scaling. (line 6) +* Schwab, Andreas: History. (line 14) +* Scribe: History. (line 24) +* Sea surges: ref. (line 27) +* Section structure of a file, showing it: Showing the Structure. + (line 6) +* Sections, raising and lowering: Raise/lower sections. + (line 6) +* Sentence ending punctuation: Ending a Sentence. (line 6) +* Sentence non-ending punctuation: Not Ending a Sentence. + (line 6) +* Separate footnote style: Footnote Styles. (line 20) +* SGML-tools output format: Output Formats. (line 95) +* Sharp S: Inserting Accents. (line 37) +* Shell formatting with tex and texindex: Format with tex/texindex. + (line 6) +* Shell printing, on MS-DOS/MS-Windows: Print with lpr. (line 27) +* Shell, format, print from: Within Emacs. (line 6) +* Shell, running makeinfo in: makeinfo in Emacs. (line 6) +* Short captions, for lists of floats: caption shortcaption. + (line 6) +* Short table of contents: Contents. (line 6) +* Showing the section structure of a file: Showing the Structure. + (line 6) +* Showing the structure of a file: Using texinfo-show-structure. + (line 6) +* Shrubbery: ifset ifclear. (line 21) +* Site-wide Texinfo configuration file: Preparing for TeX. (line 27) +* Size of printed book: smallbook. (line 6) +* Slanted typewriter font, for @kbd: kbd. (line 15) +* Small book size: smallbook. (line 6) +* Small caps font: Smallcaps. (line 6) +* Small examples: small. (line 6) +* Software copying permissions: Software Copying Permissions. + (line 6) +* Sorting indices: Hardcopy. (line 6) +* Source file format: Using Texinfo. (line 19) +* Source files, characters used: Conventions. (line 9) +* Space, inserting horizontal: Multiple Spaces. (line 6) +* Space, inserting vertical: sp. (line 6) +* Spaces in macros: Defining Macros. (line 40) +* Spaces in node name: Node Line Requirements. + (line 44) +* Spaces, in menus: Writing a Menu. (line 25) +* Spacing, inserting: Inserting Space. (line 6) +* Special characters, inserting: Atsign Braces Comma. (line 6) +* Special displays: Special Displays. (line 6) +* Special insertions: Insertions. (line 6) +* Special typesetting commands: Dots Bullets. (line 6) +* Specifying index entries: Indexing Commands. (line 6) +* Split HTML output: HTML Splitting. (line 6) +* Splitting an Info file manually: Splitting. (line 6) +* Splitting of output files: makeinfo options. (line 148) +* ss: Inserting Accents. (line 37) +* Stallman, Richard M.: History. (line 6) +* Start of header line: Start of Header. (line 6) +* Starting chapters: setchapternewpage. (line 6) +* Structure of a file, showing it: Showing the Structure. + (line 6) +* Structure, catching mistakes in: Catching Mistakes. (line 6) +* Structuring of chapters: Structuring. (line 6) +* Subsection-like commands: unnumberedsubsec appendixsubsec subheading. + (line 6) +* Subsub commands: subsubsection. (line 6) +* Suggestions for Texinfo, making: Reporting Bugs. (line 6) +* Summary of document: documentdescription. (line 6) +* Suppressing first paragraph indentation: firstparagraphindent. + (line 6) +* Suppressing indentation: noindent. (line 6) +* Syntactic conventions: Conventions. (line 6) +* Syntactic tokens, indicating: code. (line 6) +* Syntax, of @-commands: Command Syntax. (line 6) +* Syntax, optional & repeated arguments: Optional Arguments. (line 6) +* Table of contents: Contents. (line 6) +* Table of contents, after title page: Contents. (line 51) +* Table of contents, for floats: listoffloats. (line 6) +* Tables and lists, making: Lists and Tables. (line 6) +* Tables with indexes: ftable vtable. (line 6) +* Tables, making multi-column: Multi-column Tables. (line 6) +* Tables, making two-column: Two-column Tables. (line 6) +* Tabs; don't use!: Conventions. (line 51) +* Tag table, making automatically: Tag and Split Files. (line 6) +* Tag table, making manually: Unsplit. (line 26) +* Targets for cross-references, arbitrary: anchor. (line 6) +* Template for a definition: Def Cmd Template. (line 6) +* TeX commands, using ordinary: Raw Formatter Commands. + (line 6) +* TeX index sorting: Hardcopy. (line 6) +* TeX input initialization: Preparing for TeX. (line 6) +* TeX, how to obtain: Obtaining TeX. (line 6) +* texi2dvi: Format with tex/texindex. + (line 76) +* texi2dvi (shell script): Format with texi2dvi. + (line 6) +* texi2roff, unsupported software: Printed Books. (line 59) +* texindex <1>: Hardcopy. (line 6) +* texindex: Format with tex/texindex. + (line 16) +* Texinfo commands, defining new: Defining New Texinfo Commands. + (line 6) +* Texinfo file beginning: Beginning a File. (line 6) +* Texinfo file ending: Ending a File. (line 6) +* Texinfo file header: Texinfo File Header. (line 6) +* Texinfo file minimum: Minimum. (line 6) +* Texinfo file section structure, showing it: Showing the Structure. + (line 6) +* Texinfo history: History. (line 24) +* Texinfo mode: Texinfo Mode. (line 6) +* Texinfo overview: Overview. (line 6) +* Texinfo printed book characteristics: Printed Books. (line 6) +* Texinfo requires @setfilename: setfilename. (line 6) +* Texinfo, introduction to: Using Texinfo. (line 6) +* texinfo.cnf: setfilename. (line 43) +* texinfo.cnf installation: Preparing for TeX. (line 27) +* texinfo.dtd: Output Formats. (line 60) +* texinfo.tex, installing: Preparing for TeX. (line 13) +* TEXINFO_OUTPUT_FORMAT: makeinfo options. (line 234) +* TEXINPUTS: Preparing for TeX. (line 37) +* Text width and height: pagesizes. (line 6) +* Text, conditionally visible: Conditionals. (line 6) +* Text, marking up: Marking Text. (line 6) +* Thin space between number, dimension: dmn. (line 6) +* Tie-after accent: Inserting Accents. (line 17) +* Tied space: tie. (line 6) +* Tilde accent: Inserting Accents. (line 17) +* time-stamp.el: GNU Sample Texts. (line 32) +* Tips: Tips. (line 8) +* Title page: titlepage. (line 6) +* Title page, bastard: titlepage. (line 46) +* Title page, for plain text: Titlepage & Copyright Page. + (line 16) +* Titlepage end starts headings: end titlepage. (line 6) +* Top node: The Top Node. (line 6) +* Top node example: Top Node Example. (line 6) +* Top node is first: First Node. (line 6) +* Top node naming for references: Top Node Naming. (line 6) +* tp (data type) index: Predefined Indices. (line 23) +* Tree structuring: Tree Structuring. (line 6) +* Two `First' Lines for @deffn: deffnx. (line 6) +* Two letter names for indices: syncodeindex. (line 17) +* Two named items for @table: itemx. (line 6) +* Two part menu entry: Less Cluttered Menu Entry. + (line 6) +* txi-CC.tex: documentlanguage. (line 13) +* Typesetting commands for dots, etc.: Dots Bullets. (line 6) +* Typewriter font: Fonts. (line 18) +* Ugly black rectangles in hardcopy: Overfull hboxes. (line 41) +* Umlaut accent: Inserting Accents. (line 17) +* Unbreakable space, fixed: w. (line 9) +* Unbreakable space, variable: tie. (line 6) +* Uncluttered menu entry: Less Cluttered Menu Entry. + (line 6) +* Undefining macros: Defining Macros. (line 56) +* Underbar accent: Inserting Accents. (line 17) +* Underdot accent: Inserting Accents. (line 17) +* Unicode quotation characters: Conventions. (line 35) +* Uniform resource locator, indicating: indicateurl. (line 6) +* Uniform resource locator, referring to: uref. (line 6) +* Unique nodename requirement: Node Line Requirements. + (line 8) +* Unnumbered float, creating: float. (line 39) +* Unprocessed text: Comments. (line 19) +* Unsplit file creation: Unsplit. (line 6) +* Up node of Top node: First Node. (line 13) +* UPDATED Automake variable: GNU Sample Texts. (line 32) +* Updating nodes and menus: Updating Nodes and Menus. + (line 6) +* Updating requirements: Updating Requirements. + (line 6) +* URI syntax for Info: Info Files. (line 78) +* URL, indicating: indicateurl. (line 6) +* URL, referring to: uref. (line 6) +* Usage tips: Tips. (line 8) +* User input: kbd. (line 15) +* User options, marking: Variables Commands. (line 57) +* User-defined Texinfo commands: Defining New Texinfo Commands. + (line 6) +* Using Texinfo in general: Using Texinfo. (line 6) +* Validating a large file: Using Info-validate. (line 6) +* Validation of pointers: Pointer Validation. (line 6) +* Value of an expression, indicating: result. (line 6) +* Variables, object-oriented: Object-Oriented Variables. + (line 6) +* Verbatim copying license: Verbatim Copying License. + (line 6) +* Verbatim environment: verbatim. (line 6) +* Verbatim in-line text: verb. (line 6) +* Verbatim, include file: verbatiminclude. (line 6) +* VERSION Automake variable: GNU Sample Texts. (line 32) +* Version control keywords, preventing expansion of: w. (line 28) +* Version number, for install-info: Invoking install-info. + (line 84) +* Vertically holding text together: group. (line 6) +* Visibility of conditional text: Conditionals. (line 6) +* vr (variable) index: Predefined Indices. (line 27) +* W3 consortium: Output Formats. (line 26) +* Weinberg, Zack: History. (line 14) +* Weisshaus, Melissa: History. (line 14) +* White space in node name: Node Line Requirements. + (line 44) +* White space, excessive: Breaks. (line 11) +* Whitespace in macros: Defining Macros. (line 40) +* Whitespace, collapsed around continuations: Def Cmd Continuation Lines. + (line 31) +* Whitespace, inserting: Multiple Spaces. (line 6) +* Width of images: Image Scaling. (line 6) +* Width of text area: pagesizes. (line 6) +* Widths, defining multitable column: Multitable Column Widths. + (line 6) +* Wildcards: Format with tex/texindex. + (line 32) +* Words and phrases, marking them: Marking Text. (line 6) +* Writing a menu: Writing a Menu. (line 6) +* Writing an @node line: Writing a Node. (line 6) +* Writing index entries: Indexing Commands. (line 27) +* xdvi: Output Formats. (line 36) +* XML output: Output Formats. (line 60) +* XML, including raw: Raw Formatter Commands. + (line 6) +* XPM image format: Image Syntax. (line 23) +* Years, in copyright line: copying. (line 48) +* Zaretskii, Eli: History. (line 14) +* Zuhn, David D.: History. (line 14) + + + +Tag Table: +Node: Top1485 +Node: Copying Conditions26788 +Node: Overview28855 +Ref: Overview-Footnote-130234 +Node: Reporting Bugs30691 +Node: Using Texinfo32215 +Node: Output Formats33804 +Node: Info Files38893 +Ref: Info Files-Footnote-143301 +Node: Printed Books43480 +Ref: Printed Books-Footnote-146309 +Node: Formatting Commands46643 +Ref: Formatting Commands-Footnote-149496 +Node: Conventions50104 +Node: Comments53438 +Node: Minimum55068 +Node: Six Parts57631 +Node: Short Sample59285 +Node: History63419 +Node: Texinfo Mode65471 +Node: Texinfo Mode Overview66848 +Node: Emacs Editing67618 +Node: Inserting69762 +Node: Showing the Structure74049 +Node: Updating Nodes and Menus76370 +Node: Updating Commands77449 +Node: Updating Requirements83453 +Node: Other Updating Commands85842 +Node: Info Formatting89108 +Node: Printing90374 +Node: Texinfo Mode Summary92682 +Node: Beginning a File97376 +Node: Sample Beginning98795 +Node: Texinfo File Header100392 +Node: First Line101856 +Node: Start of Header102887 +Node: setfilename103878 +Node: settitle106383 +Node: End of Header108644 +Node: Document Permissions108928 +Node: copying109559 +Node: insertcopying112113 +Node: Titlepage & Copyright Page113648 +Node: titlepage115327 +Ref: titlepage-Footnote-1117834 +Node: titlefont center sp118120 +Node: title subtitle author119802 +Node: Copyright122576 +Node: end titlepage124105 +Node: headings on off125759 +Node: Contents127829 +Node: The Top Node131059 +Node: Top Node Example132363 +Node: Master Menu Parts132748 +Node: Global Document Commands134558 +Node: documentdescription135314 +Node: setchapternewpage136130 +Node: paragraphindent139016 +Node: firstparagraphindent140290 +Node: exampleindent141558 +Node: Software Copying Permissions142582 +Node: Ending a File143640 +Node: Printing Indices & Menus144215 +Node: File End147315 +Node: Structuring148001 +Node: Tree Structuring149660 +Node: Structuring Command Types151079 +Node: makeinfo top153574 +Node: chapter154365 +Node: unnumbered & appendix155395 +Node: majorheading & chapheading156246 +Node: section157073 +Node: unnumberedsec appendixsec heading157843 +Node: subsection158840 +Node: unnumberedsubsec appendixsubsec subheading159418 +Node: subsubsection160379 +Node: Raise/lower sections161937 +Node: Nodes164113 +Node: Two Paths165323 +Node: Node Menu Illustration166659 +Node: node170467 +Node: Node Names173226 +Node: Writing a Node174610 +Node: Node Line Tips176656 +Node: Node Line Requirements177460 +Node: First Node179617 +Node: makeinfo top command181435 +Node: makeinfo Pointer Creation182716 +Node: anchor184345 +Node: Menus185821 +Node: Menu Location186887 +Node: Writing a Menu188518 +Node: Menu Parts189581 +Node: Less Cluttered Menu Entry190745 +Node: Menu Example191376 +Node: Other Info Files192886 +Node: Cross References194738 +Node: References195709 +Node: Cross Reference Commands197481 +Node: Cross Reference Parts198546 +Node: xref201402 +Node: Reference Syntax202207 +Node: One Argument203844 +Node: Two Arguments204871 +Node: Three Arguments205996 +Node: Four and Five Arguments208397 +Node: Top Node Naming210819 +Node: ref211835 +Node: pxref213256 +Node: inforef215624 +Node: uref216935 +Node: Marking Text219685 +Node: Indicating220338 +Node: Useful Highlighting222478 +Node: code224101 +Node: kbd227343 +Node: key229563 +Node: samp230907 +Node: verb232388 +Node: var233377 +Node: env235351 +Node: file235862 +Node: command236483 +Node: option237189 +Node: dfn237709 +Node: cite238633 +Node: acronym239101 +Node: indicateurl240384 +Node: email241082 +Node: Emphasis241938 +Node: emph & strong242775 +Node: Smallcaps243990 +Node: Fonts245336 +Node: Quotations and Examples246492 +Node: Block Enclosing Commands248177 +Node: quotation250364 +Node: example252002 +Node: verbatim254321 +Node: verbatiminclude256091 +Node: lisp257085 +Ref: lisp-Footnote-1257824 +Node: small257942 +Node: display259473 +Node: format260275 +Node: exdent260921 +Node: flushleft & flushright262011 +Node: noindent263286 +Node: indent265150 +Node: cartouche266194 +Node: Lists and Tables267390 +Node: Introducing Lists268079 +Node: itemize269741 +Node: enumerate272019 +Node: Two-column Tables274517 +Node: table275214 +Node: ftable vtable277892 +Node: itemx278989 +Node: Multi-column Tables280175 +Node: Multitable Column Widths280884 +Node: Multitable Rows282366 +Node: Special Displays284419 +Node: Floats285208 +Node: float286105 +Ref: fig:ex1286779 +Node: caption shortcaption288050 +Node: listoffloats289361 +Node: Images290764 +Node: Image Syntax291199 +Node: Image Scaling293804 +Node: Footnotes295528 +Ref: Footnotes-Footnote-1296094 +Node: Footnote Commands296374 +Ref: Footnote Commands-Footnote-1298251 +Node: Footnote Styles298287 +Node: Indices300902 +Node: Index Entries302116 +Node: Predefined Indices303241 +Node: Indexing Commands305350 +Node: Combining Indices308063 +Node: syncodeindex309416 +Node: synindex311064 +Node: New Indices311601 +Node: Insertions313370 +Node: Atsign Braces Comma314497 +Node: Inserting an Atsign315065 +Node: Inserting Braces315337 +Node: Inserting a Comma315756 +Node: Inserting Space316790 +Node: Not Ending a Sentence317307 +Node: Ending a Sentence318919 +Node: Multiple Spaces319943 +Node: dmn321234 +Node: Inserting Accents322459 +Node: Dots Bullets324462 +Node: dots325278 +Node: bullet325901 +Node: TeX and copyright326310 +Node: tex326986 +Node: copyright symbol327803 +Node: registered symbol328113 +Node: pounds328435 +Node: minus328806 +Node: math329725 +Node: Glyphs331073 +Node: Glyphs Summary332179 +Node: result332804 +Node: expansion333314 +Node: Print Glyph334276 +Node: Error Glyph335168 +Node: Equivalence336022 +Node: Point Glyph336772 +Node: Breaks338343 +Node: Break Commands339827 +Node: Line Breaks340723 +Node: - and hyphenation341697 +Node: w342963 +Node: tie344071 +Node: sp344975 +Node: page345394 +Node: group345779 +Node: need347531 +Node: Definition Commands348269 +Node: Def Cmd Template349920 +Node: Def Cmd Continuation Lines352645 +Node: Optional Arguments354456 +Node: deffnx356063 +Node: Def Cmds in Detail357006 +Node: Functions Commands358124 +Node: Variables Commands361026 +Node: Typed Functions363169 +Node: Typed Variables366674 +Node: Data Types368395 +Node: Abstract Objects369686 +Node: Object-Oriented Variables370293 +Node: Object-Oriented Methods372926 +Node: Def Cmd Conventions376737 +Node: Sample Function Definition377308 +Node: Conditionals380144 +Node: Conditional Commands381338 +Node: Conditional Not Commands383229 +Node: Raw Formatter Commands384513 +Node: set clear value387141 +Node: set value388355 +Node: ifset ifclear389957 +Node: value Example392088 +Node: Conditional Nesting394105 +Node: Internationalization395646 +Node: documentlanguage396182 +Node: documentencoding400369 +Node: Defining New Texinfo Commands401861 +Node: Defining Macros403039 +Node: Invoking Macros405417 +Node: Macro Details407218 +Node: alias409796 +Node: definfoenclose411220 +Node: Hardcopy413968 +Node: Use TeX416044 +Node: Format with tex/texindex416677 +Node: Format with texi2dvi421043 +Node: Print with lpr422614 +Node: Within Emacs424773 +Node: Texinfo Mode Printing425664 +Node: Compile-Command429333 +Node: Requirements Summary430215 +Node: Preparing for TeX431555 +Ref: Preparing for TeX-Footnote-1435308 +Node: Overfull hboxes435407 +Node: smallbook437566 +Node: A4 Paper438772 +Node: pagesizes439708 +Node: Cropmarks and Magnification440902 +Node: PDF Output442971 +Node: Obtaining TeX444127 +Node: Creating and Installing Info Files445104 +Node: Creating an Info File445498 +Node: makeinfo advantages446726 +Node: Invoking makeinfo447662 +Node: makeinfo options448228 +Node: Pointer Validation457295 +Node: makeinfo in Emacs460427 +Node: texinfo-format commands462910 +Node: Batch Formatting464197 +Node: Tag and Split Files465409 +Node: Installing an Info File468806 +Node: Directory File469645 +Node: New Info File471444 +Ref: New Info File-Footnote-1472558 +Node: Other Info Directories472639 +Ref: Other Info Directories-Footnote-1476914 +Ref: Other Info Directories-Footnote-2477041 +Node: Installing Dir Entries477102 +Node: Invoking install-info479764 +Node: Generating HTML482661 +Node: HTML Translation483442 +Node: HTML Splitting484824 +Node: HTML CSS486507 +Node: HTML Xref489996 +Node: HTML Xref Link Basics491203 +Node: HTML Xref Node Name Expansion494026 +Node: HTML Xref Command Expansion496579 +Node: HTML Xref 8-bit Character Expansion499584 +Node: HTML Xref Mismatch500818 +Node: Command List502636 +Node: Command Syntax545467 +Node: Tips548476 +Node: Sample Texinfo Files559473 +Node: Short Sample Texinfo File559939 +Node: GNU Sample Texts561534 +Node: Verbatim Copying License566809 +Node: All-permissive Copying License567911 +Node: Include Files568941 +Node: Using Include Files570052 +Node: texinfo-multiple-files-update572604 +Node: Include Files Requirements574972 +Node: Sample Include File576226 +Node: Include Files Evolution577463 +Node: Headings579443 +Node: Headings Introduced580100 +Node: Heading Format581977 +Node: Heading Choice584421 +Node: Custom Headings585799 +Node: Catching Mistakes589906 +Node: makeinfo Preferred591213 +Node: Debugging with Info592098 +Node: Debugging with TeX595442 +Node: Using texinfo-show-structure599705 +Node: Using occur602795 +Node: Running Info-Validate604336 +Node: Using Info-validate605403 +Node: Unsplit607213 +Node: Tagifying608272 +Node: Splitting609134 +Node: Copying This Manual610762 +Node: GNU Free Documentation License611025 +Node: Command and Variable Index633432 +Node: Concept Index662680 + +End Tag Table |