\input texinfo.tex @c -*-texinfo-*- @c $Id: texinfo.txi,v 1.220 2008/04/09 17:07:31 karl Exp $ @c Ordinarily, Texinfo files have the extension .texi. But texinfo.texi @c clashes with texinfo.tex on 8.3 filesystems, so we use texinfo.txi. @c Everything between the start/end of header lines will be passed by @c Emacs's {texinfo,makeinfo}-format region commands. See the `start of @c header' node for more info. @c %**start of header @c makeinfo and texinfo.tex ignore all text before @setfilename. @c @c Ordinarily, the setfilename argument ends with .info. But @c texinfo.info-13 is too long for 14-character filesystems. @setfilename texinfo @c Automake automatically updates version.texi to @set VERSION and @c @set UPDATED to appropriate values. @include version.texi @settitle GNU Texinfo @value{VERSION} @c Define a new index for options. @defcodeindex op @c Put everything except function (command, in this case) names in one @c index (arbitrarily chosen to be the concept index). @syncodeindex op cp @syncodeindex vr cp @syncodeindex pg cp @paragraphindent 2 @c finalout @comment %**end of header @copying This manual is for GNU Texinfo (version @value{VERSION}, @value{UPDATED}), a documentation system that can produce both online information and a printed manual from a single source. Copyright @copyright{} 1988, 1990, 1991, 1992, 1993, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover Texts being ``A GNU Manual'', and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled ``GNU Free Documentation License.'' (a) The FSF's Back-Cover Text is: ``You are free to copy and modify this GNU Manual. Buying copies from GNU Press supports the FSF in developing GNU and promoting software freedom.'' @end quotation @end copying @dircategory Texinfo documentation system @direntry * Texinfo: (texinfo). The GNU documentation format. * install-info: (texinfo)Invoking install-info. Update info/dir entries. * texi2dvi: (texinfo)Format with texi2dvi. Print Texinfo documents. * texi2pdf: (texinfo)PDF Output. PDF output for Texinfo. * pdftexi2dvi: (texinfo)PDF Output. PDF output for Texinfo. * texindex: (texinfo)Format with tex/texindex. Sort Texinfo index files. * makeinfo: (texinfo)Invoking makeinfo. Translate Texinfo source. @end direntry @c Before release, run C-u C-c C-u C-a (texinfo-all-menus-update with a @c prefix arg). This updates the node pointers, which texinfmt.el needs. @c Set smallbook if printing in smallbook format so the example of the @c smallbook font is actually written using smallbook; in bigbook, a kludge @c is used for TeX output. Do this through the -t option to texi2dvi, @c so this same source can be used for other paper sizes as well. @c smallbook @c set smallbook @c @@clear smallbook @c If you like blank pages, add through texi2dvi -t. @c setchapternewpage odd @c Currently undocumented command, 5 December 1993: @c nwnode (Same as node, but no warnings; for `makeinfo'.) @shorttitlepage GNU Texinfo @titlepage @title Texinfo @subtitle The GNU Documentation Format @subtitle for Texinfo version @value{VERSION}, @value{UPDATED} @author Robert J. Chassell @author Richard M. Stallman @c Include the Distribution inside the titlepage so @c that headings are turned off. @page @vskip 0pt plus 1filll @insertcopying @sp 1 Published by the Free Software Foundation @* 51 Franklin St, Fifth Floor @* Boston, MA 02110-1301 @* USA @* ISBN 1-882114-67-1 @c for version 4.0, September 1999. @c ISBN 1-882114-65-5 is for version 3.12, March 1998. @c ISBN 1-882114-64-7 is for edition 2.24 of November 1996. @c ISBN 1-882114-63-9 is for edition 2.20 of 28 February 1995. @sp 1 Cover art by Etienne Suvasa. @end titlepage @summarycontents @contents @ifnottex @node Top @top Texinfo This manual is for GNU Texinfo (version @value{VERSION}, @value{UPDATED}), a documentation system that can produce both online information and a printed manual from a single source. The first part of this master menu lists the major nodes in this Info document, including the @@-command and concept indices. The rest of the menu lists all the lower level nodes in the document. @end ifnottex @menu * Copying Conditions:: Your rights. * Overview:: Texinfo in brief. * Texinfo Mode:: Using the GNU Emacs Texinfo mode. * Beginning a File:: What is at the beginning of a Texinfo file? * Ending a File:: What is at the end of a Texinfo file? * Structuring:: Creating chapters, sections, appendices, etc. * Nodes:: Writing nodes, the basic unit of Texinfo. * Menus:: Writing menus. * Cross References:: Writing cross references. * Marking Text:: Marking words and phrases as code, keyboard input, meta-syntactic variables, and the like. * Quotations and Examples:: Block quotations, examples, etc. * Lists and Tables:: Itemized or numbered lists, and tables. * Special Displays:: Floating figures and footnotes. * Indices:: Creating indices. * Insertions:: Inserting @@-signs, braces, etc. * Breaks:: Forcing or preventing line and page breaks. * Definition Commands:: Describing functions and the like uniformly. * Conditionals:: Specifying text for only some output cases. * Internationalization:: Supporting languages other than English. * Defining New Texinfo Commands:: User-defined macros and aliases. * Hardcopy:: Output for paper, with @TeX{}. * Creating and Installing Info Files:: Details on Info output. * Generating HTML:: Details on HTML output. * Command List:: All the Texinfo @@-commands. * Tips:: Hints on how to write a Texinfo document. * Sample Texinfo Files:: Complete examples, including full texts. * Include Files:: How to incorporate other Texinfo files. * Headings:: How to write page headings and footings. * Catching Mistakes:: How to find formatting mistakes. * GNU Free Documentation License::Copying this manual. * Command and Variable Index:: A menu containing commands and variables. * General Index:: A menu covering many topics. @detailmenu --- The Detailed Node Listing --- Overview of Texinfo * Reporting Bugs:: Submitting effective bug reports. * Using Texinfo:: Create printed or online output. * Output Formats:: Overview of the supported output formats. * Info Files:: What is an Info file? * Printed Books:: Characteristics of a printed book or manual. * Formatting Commands:: @@-commands are used for formatting. * Conventions:: General rules for writing a Texinfo file. * Comments:: Writing comments and ignored text in general. * Minimum:: What a Texinfo file must have. * Six Parts:: Usually, a Texinfo file has six parts. * Short Sample:: A short sample Texinfo file. * History:: Acknowledgements, contributors and genesis. Using Texinfo Mode * Texinfo Mode Overview:: How Texinfo mode can help you. * Emacs Editing:: Texinfo mode adds to GNU Emacs' general purpose editing features. * Inserting:: How to insert frequently used @@-commands. * Showing the Structure:: How to show the structure of a file. * Updating Nodes and Menus:: How to update or create new nodes and menus. * Info Formatting:: How to format for Info. * Printing:: How to format and print part or all of a file. * Texinfo Mode Summary:: Summary of all the Texinfo mode commands. Updating Nodes and Menus * Updating Commands:: Five major updating commands. * Updating Requirements:: How to structure a Texinfo file for using the updating command. * Other Updating Commands:: How to indent descriptions, insert missing nodes lines, and update nodes in sequence. Beginning a Texinfo File * Sample Beginning:: A sample beginning for a Texinfo file. * Texinfo File Header:: The first lines. * Document Permissions:: Ensuring your manual is free. * Titlepage & Copyright Page:: Creating the title and copyright pages. * Contents:: How to create a table of contents. * The Top Node:: Creating the `Top' node and master menu. * Global Document Commands:: Affecting formatting throughout. * Software Copying Permissions:: Ensure that you and others continue to have the right to use and share software. Texinfo File Header * First Line:: The first line of a Texinfo file. * Start of Header:: Formatting a region requires this. * setfilename:: Tell Info the name of the Info file. * settitle:: Create a title for the printed work. * End of Header:: Formatting a region requires this. Document Permissions * copying:: Declare the document's copying permissions. * insertcopying:: Where to insert the permissions. Title and Copyright Pages * titlepage:: Create a title for the printed document. * titlefont center sp:: The @code{@@titlefont}, @code{@@center}, and @code{@@sp} commands. * title subtitle author:: The @code{@@title}, @code{@@subtitle}, and @code{@@author} commands. * Copyright:: How to write the copyright notice and include copying permissions. * end titlepage:: Turn on page headings after the title and copyright pages. * headings on off:: An option for turning headings on and off and double or single sided printing. The `Top' Node and Master Menu * Top Node Example:: * Master Menu Parts:: Global Document Commands * documentdescription:: Document summary for the HTML output. * setchapternewpage:: Start chapters on right-hand pages. * paragraphindent:: Specify paragraph indentation. * firstparagraphindent:: Suppress indentation of the first paragraph. * exampleindent:: Specify environment indentation. Ending a Texinfo File * Printing Indices & Menus:: How to print an index in hardcopy and generate index menus in Info. * File End:: How to mark the end of a file. Chapter Structuring * Tree Structuring:: A manual is like an upside down tree @dots{} * Structuring Command Types:: How to divide a manual into parts. * makeinfo top:: The @code{@@top} command, part of the `Top' node. * chapter:: * unnumbered & appendix:: * majorheading & chapheading:: * section:: * unnumberedsec appendixsec heading:: * subsection:: * unnumberedsubsec appendixsubsec subheading:: * subsubsection:: Commands for the lowest level sections. * Raise/lower sections:: How to change commands' hierarchical level. Nodes * Two Paths:: Different commands to structure Info output and printed output. * Node Menu Illustration:: A diagram, and sample nodes and menus. * node:: Creating nodes, in detail. * makeinfo Pointer Creation:: Letting makeinfo determine node pointers. * anchor:: Defining arbitrary cross-reference targets. The @code{@@node} Command * Node Names:: How to choose node and pointer names. * Writing a Node:: How to write an @code{@@node} line. * Node Line Tips:: Keep names short. * Node Line Requirements:: Keep names unique, without @@-commands. * First Node:: How to write a `Top' node. * makeinfo top command:: How to use the @code{@@top} command. Menus * Menu Location:: Menus go at the ends of short nodes. * Writing a Menu:: What is a menu? * Menu Parts:: A menu entry has three parts. * Less Cluttered Menu Entry:: Two part menu entry. * Menu Example:: Two and three part menu entries. * Other Info Files:: How to refer to a different Info file. Cross References * References:: What cross references are for. * Cross Reference Commands:: A summary of the different commands. * Cross Reference Parts:: A cross reference has several parts. * xref:: Begin a reference with `See' @dots{} * Top Node Naming:: How to refer to the beginning of another file. * ref:: A reference for the last part of a sentence. * pxref:: How to write a parenthetical cross reference. * inforef:: How to refer to an Info-only file. * uref:: How to refer to a uniform resource locator. @code{@@xref} * Reference Syntax:: What a reference looks like and requires. * One Argument:: @code{@@xref} with one argument. * Two Arguments:: @code{@@xref} with two arguments. * Three Arguments:: @code{@@xref} with three arguments. * Four and Five Arguments:: @code{@@xref} with four and five arguments. Marking Words and Phrases * Indicating:: How to indicate definitions, files, etc. * Emphasis:: How to emphasize text. Indicating Definitions, Commands, etc. * Useful Highlighting:: Highlighting provides useful information. * code:: Indicating program code. * kbd:: Showing keyboard input. * key:: Specifying keys. * samp:: A literal sequence of characters. * verb:: A verbatim sequence of characters. * var:: Indicating metasyntactic variables. * env:: Indicating environment variables. * file:: Indicating file names. * command:: Indicating command names. * option:: Indicating option names. * dfn:: Specifying definitions. * cite:: Referring to books not in the Info system. * abbr:: Indicating abbreviations. * acronym:: Indicating acronyms. * indicateurl:: Indicating a World Wide Web reference. * email:: Indicating an electronic mail address. Emphasizing Text * emph & strong:: How to emphasize text in Texinfo. * Smallcaps:: How to use the small caps font. * Fonts:: Various font commands for printed output. Quotations and Examples * Block Enclosing Commands:: Different constructs for different purposes. * quotation:: Writing a quotation. * example:: Writing an example in a fixed-width font. * verbatim:: Writing a verbatim example. * verbatiminclude:: Including a file verbatim. * lisp:: Illustrating Lisp code. * small:: Examples in a smaller font. * display:: Writing an example in the current font. * format:: Writing an example without narrowed margins. * exdent:: Undo indentation on a line. * flushleft & flushright:: Pushing text flush left or flush right. * noindent:: Preventing paragraph indentation. * indent:: Forcing paragraph indentation. * cartouche:: Drawing rounded rectangles around examples. Lists and Tables * Introducing Lists:: Texinfo formats lists for you. * itemize:: How to construct a simple list. * enumerate:: How to construct a numbered list. * Two-column Tables:: How to construct a two-column table. * Multi-column Tables:: How to construct generalized tables. Making a Two-column Table * table:: How to construct a two-column table. * ftable vtable:: Automatic indexing for two-column tables. * itemx:: How to put more entries in the first column. @code{@@multitable}: Multi-column Tables * Multitable Column Widths:: Defining multitable column widths. * Multitable Rows:: Defining multitable rows, with examples. Special Displays * Floats:: Figures, tables, and the like. * Images:: Including graphics and images. * Footnotes:: Writing footnotes. Floats * float:: Producing floating material. * caption shortcaption:: Specifying descriptions for floats. * listoffloats:: A table of contents for floats. Inserting Images * Image Syntax:: * Image Scaling:: Footnotes * Footnote Commands:: How to write a footnote in Texinfo. * Footnote Styles:: Controlling how footnotes appear in Info. Indices * Index Entries:: Choose different words for index entries. * Predefined Indices:: Use different indices for different kinds of entries. * Indexing Commands:: How to make an index entry. * Combining Indices:: How to combine indices. * New Indices:: How to define your own indices. Combining Indices * syncodeindex:: How to merge two indices, using @code{@@code} font for the merged-from index. * synindex:: How to merge two indices, using the default font of the merged-to index. Special Insertions * Atsign Braces Comma:: Inserting @@ and @{@} and ,. * Inserting Quote Characters:: Inserting left and right quotes, in code. * Inserting Space:: How to insert the right amount of space within a sentence. * Inserting Accents:: How to insert accents and special characters. * Inserting Quotation Marks:: How to insert quotation marks. * Dots Bullets:: How to insert dots and bullets. * TeX and copyright:: How to insert the @TeX{} logo and the copyright symbol. * euro:: How to insert the Euro currency symbol. * pounds:: How to insert the pounds currency symbol. * textdegree:: How to insert the degrees symbol. * minus:: How to insert a minus sign. * geq leq:: How to insert greater/less-than-or-equal signs. * math:: How to format a mathematical expression. * Click Sequences:: Inserting GUI usage sequences. * Glyphs:: How to indicate results of evaluation, expansion of macros, errors, etc. Inserting @@ and @{@} and @comma{} * Inserting an Atsign:: * Inserting Braces:: * Inserting a Comma:: Inserting Space * Not Ending a Sentence:: Sometimes a . doesn't end a sentence. * Ending a Sentence:: Sometimes it does. * Multiple Spaces:: Inserting multiple spaces. * frenchspacing:: Specifying end-of-sentence spacing. * dmn:: How to format a dimension. Inserting Ellipsis and Bullets * dots:: How to insert dots @dots{} * bullet:: How to insert a bullet. Inserting @TeX{} and Legal Symbols: @copyright{}, @registeredsymbol{} * tex:: The @TeX{} logos. * copyright symbol:: The copyright symbol (c in a circle). * registered symbol:: The registered symbol (R in a circle). Glyphs for Examples * Glyphs Summary:: * result:: How to show the result of expression. * expansion:: How to indicate an expansion. * Print Glyph:: How to indicate printed output. * Error Glyph:: How to indicate an error message. * Equivalence:: How to indicate equivalence. * Point Glyph:: How to indicate the location of point. Glyphs Summary * result:: * expansion:: * Print Glyph:: * Error Glyph:: * Equivalence:: * Point Glyph:: Forcing and Preventing Breaks * Break Commands:: Summary of break-related commands. * Line Breaks:: Forcing line breaks. * - and hyphenation:: Helping @TeX{} with hyphenation points. * allowcodebreaks:: Controlling line breaks within @@code text. * w:: Preventing unwanted line breaks in text. * tie:: Inserting an unbreakable but varying space. * sp:: Inserting blank lines. * page:: Forcing the start of a new page. * group:: Preventing unwanted page breaks. * need:: Another way to prevent unwanted page breaks. Definition Commands * Def Cmd Template:: Writing descriptions using definition commands. * Def Cmd Continuation Lines:: Continuing the heading over source lines. * Optional Arguments:: Handling optional and repeated arguments. * deffnx:: Group two or more `first' lines. * Def Cmds in Detail:: Reference for all the definition commands. * Def Cmd Conventions:: Conventions for writing definitions. * Sample Function Definition:: An example. The Definition Commands * Functions Commands:: Commands for functions and similar entities. * Variables Commands:: Commands for variables and similar entities. * Typed Functions:: Commands for functions in typed languages. * Typed Variables:: Commands for variables in typed languages. * Data Types:: The definition command for data types. * Abstract Objects:: Commands for object-oriented programming. Object-Oriented Programming * Variables: Object-Oriented Variables. * Methods: Object-Oriented Methods. Conditionally Visible Text * Conditional Commands:: Text for a given format. * Conditional Not Commands:: Text for any format other than a given one. * Raw Formatter Commands:: Using raw formatter commands. * set clear value:: Variable tests and substitutions. * Conditional Nesting:: Using conditionals inside conditionals. @code{@@set}, @code{@@clear}, and @code{@@value} * set value:: Expand a flag variable to a string. * ifset ifclear:: Format a region if a flag is set. * value Example:: An easy way to update edition information. Internationalization * documentlanguage:: Declaring the current language. * documentencoding:: Declaring the input encoding. Defining New Texinfo Commands * Defining Macros:: Defining and undefining new commands. * Invoking Macros:: Using a macro, once you've defined it. * Macro Details:: Limitations of Texinfo macros. * alias:: Command aliases. * definfoenclose:: Customized highlighting. Formatting and Printing Hardcopy * Use TeX:: Use @TeX{} to format for hardcopy. * Format with tex/texindex:: How to format with explicit shell commands. * Format with texi2dvi:: A simpler way to format. * Print with lpr:: How to print. * Within Emacs:: How to format and print from an Emacs shell. * Texinfo Mode Printing:: How to format and print in Texinfo mode. * Compile-Command:: How to print using Emacs's compile command. * Requirements Summary:: @TeX{} formatting requirements summary. * Preparing for TeX:: What to do before you use @TeX{}. * Overfull hboxes:: What are and what to do with overfull hboxes. * smallbook:: How to print small format books and manuals. * A4 Paper:: How to print on A4 or A5 paper. * pagesizes:: How to print with customized page sizes. * Cropmarks and Magnification:: How to print marks to indicate the size of pages and how to print scaled up output. * PDF Output:: Portable Document Format output. * Obtaining TeX:: How to Obtain @TeX{}. Creating and Installing Info Files * Creating an Info File:: * Installing an Info File:: Creating an Info File * makeinfo advantages:: @code{makeinfo} provides better error checking. * Invoking makeinfo:: How to run @code{makeinfo} from a shell. * makeinfo options:: Specify fill-column and other options. * Pointer Validation:: How to check that pointers point somewhere. * makeinfo in Emacs:: How to run @code{makeinfo} from Emacs. * texinfo-format commands:: Two Info formatting commands written in Emacs Lisp are an alternative to @code{makeinfo}. * Batch Formatting:: How to format for Info in Emacs Batch mode. * Tag and Split Files:: How tagged and split files help Info to run better. Installing an Info File * Directory File:: The top level menu for all Info files. * New Info File:: Listing a new Info file. * Other Info Directories:: How to specify Info files that are located in other directories. * Installing Dir Entries:: How to specify what menu entry to add to the Info directory. * Invoking install-info:: @code{install-info} options. Generating HTML * HTML Translation:: Details of the HTML output. * HTML Splitting:: How HTML output is split. * HTML CSS:: Influencing HTML output with Cascading Style Sheets. * HTML Xref:: Cross-references in HTML output. HTML Cross-references * Link Basics: HTML Xref Link Basics. * Node Expansion: HTML Xref Node Name Expansion. * Command Expansion: HTML Xref Command Expansion. * 8-bit Expansion: HTML Xref 8-bit Character Expansion. * Mismatch: HTML Xref Mismatch. @@-Command List * Command Syntax:: General syntax for varieties of @@-commands. Sample Texinfo Files * Short Sample Texinfo File:: * GNU Sample Texts:: * Verbatim Copying License:: * All-permissive Copying License:: GNU Free Documentation License Include Files * Using Include Files:: How to use the @code{@@include} command. * texinfo-multiple-files-update:: How to create and update nodes and menus when using included files. * Include Files Requirements:: @code{texinfo-multiple-files-update} needs. * Sample Include File:: A sample outer file with included files within it; and a sample included file. * Include Files Evolution:: How use of the @code{@@include} command has changed over time. Page Headings * Headings Introduced:: Conventions for using page headings. * Heading Format:: Standard page heading formats. * Heading Choice:: How to specify the type of page heading. * Custom Headings:: How to create your own headings and footings. Formatting Mistakes * makeinfo Preferred:: @code{makeinfo} finds errors. * Debugging with Info:: How to catch errors with Info formatting. * Debugging with TeX:: How to catch errors with @TeX{} formatting. * Using texinfo-show-structure:: How to use @code{texinfo-show-structure}. * Using occur:: How to list all lines containing a pattern. * Running Info-Validate:: How to find badly referenced nodes. Finding Badly Referenced Nodes * Using Info-validate:: How to run @code{Info-validate}. * Unsplit:: How to create an unsplit file. * Tagifying:: How to tagify a file. * Splitting:: How to split a file manually. @end detailmenu @end menu @c Reward readers for getting to the end of the menu :). @c Contributed by Arnold Robbins. @quotation Documentation is like sex: when it is good, it is very, very good; and when it is bad, it is better than nothing. ---Dick Brandon @end quotation @node Copying Conditions @unnumbered Texinfo Copying Conditions @cindex Copying conditions @cindex Conditions for copying Texinfo The programs currently being distributed that relate to Texinfo include @code{makeinfo}, @code{info}, @code{texindex}, and @file{texinfo.tex}. These programs are @dfn{free}; this means that everyone is free to use them and free to redistribute them on a free basis. The Texinfo-related programs are not in the public domain; they are copyrighted and there are restrictions on their distribution, but these restrictions are designed to permit everything that a good cooperating citizen would want to do. What is not allowed is to try to prevent others from further sharing any version of these programs that they might get from you. Specifically, we want to make sure that you have the right to give away copies of the programs that relate to Texinfo, that you receive source code or else can get it if you want it, that you can change these programs or use pieces of them in new free programs, and that you know you can do these things. To make sure that everyone has such rights, we have to forbid you to deprive anyone else of these rights. For example, if you distribute copies of the Texinfo related programs, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must tell them their rights. Also, for our own protection, we must make certain that everyone finds out that there is no warranty for the programs that relate to Texinfo. If these programs are modified by someone else and passed on, we want their recipients to know that what they have is not what we distributed, so that any problems introduced by others will not reflect on our reputation. The precise conditions of the licenses for the programs currently being distributed that relate to Texinfo are found in the General Public Licenses that accompany them. This manual specifically is covered by the GNU Free Documentation License (@pxref{GNU Free Documentation License}). @node Overview @chapter Overview of Texinfo @cindex Overview of Texinfo @cindex Texinfo overview @dfn{Texinfo}@footnote{The first syllable of ``Texinfo'' is pronounced like ``speck'', not ``hex''. This odd pronunciation is derived from, but is not the same as, the pronunciation of @TeX{}. In the word @TeX{}, the @samp{X} is actually the Greek letter ``chi'' rather than the English letter ``ex''. Pronounce @TeX{} as if the @samp{X} were the last sound in the name `Bach'; but pronounce Texinfo as if the @samp{x} were a `k'. Spell ``Texinfo'' with a capital ``T'' and the other letters in lower case.} is a documentation system that uses a single source file to produce both online information and printed output. This means that instead of writing two different documents, one for the online information and the other for a printed work, you need write only one document. Therefore, when the work is revised, you need revise only that one document. @menu * Reporting Bugs:: Submitting effective bug reports. * Using Texinfo:: Create printed or online output. * Output Formats:: Overview of the supported output formats. * Info Files:: What is an Info file? * Printed Books:: Characteristics of a printed book or manual. * Formatting Commands:: @@-commands are used for formatting. * Conventions:: General rules for writing a Texinfo file. * Comments:: Writing comments and ignored text in general. * Minimum:: What a Texinfo file must have. * Six Parts:: Usually, a Texinfo file has six parts. * Short Sample:: A short sample Texinfo file. * History:: Acknowledgements, contributors and genesis. @end menu @node Reporting Bugs @section Reporting Bugs @cindex Bugs, reporting @cindex Suggestions for Texinfo, making @cindex Reporting bugs We welcome bug reports and suggestions for any aspect of the Texinfo system, programs, documentation, installation, anything. Please email them to @email{bug-texinfo@@gnu.org}. You can get the latest version of Texinfo from @uref{ftp://ftp.gnu.org/gnu/texinfo/} and its mirrors worldwide. @cindex Checklist for bug reports For bug reports, please include enough information for the maintainers to reproduce the problem. Generally speaking, that means: @itemize @bullet @item the version number of Texinfo and the program(s) or manual(s) involved. @item hardware and operating system names and versions. @item the contents of any input files necessary to reproduce the bug. @item a description of the problem and samples of any erroneous output. @item any unusual options you gave to @command{configure}. @item anything else that you think would be helpful. @end itemize When in doubt whether something is needed or not, include it. It's better to include too much than to leave out something important. @cindex Patches, contributing Patches are most welcome; if possible, please make them with @samp{@w{diff -c}} (@pxref{Top,, Overview, diff, Comparing and Merging Files}) and include @file{ChangeLog} entries (@pxref{Change Log,,, emacs, The GNU Emacs Manual}), and follow the existing coding style. @node Using Texinfo @section Using Texinfo @cindex Using Texinfo in general @cindex Texinfo, introduction to @cindex Introduction to Texinfo Using Texinfo, you can create a printed document (via the @TeX{} typesetting system) the normal features of a book, including chapters, sections, cross references, and indices. From the same Texinfo source file, you can create an Info file with special features to make documentation browsing easy. You can also create from that same source file an HTML output file suitable for use with a web browser, or an XML file. See the next section (@pxref{Output Formats}) for details and the exact commands to generate output from the source. @TeX{} works with virtually all printers; Info works with virtually all computer terminals; the HTML output works with virtually all web browsers. Thus Texinfo can be used by almost any computer user. @cindex Source file format A Texinfo source file is a plain ASCII file containing text interspersed with @dfn{@@-commands} (words preceded by an @samp{@@}) that tell the typesetting and formatting programs what to do. You can edit a Texinfo file with any text editor, but it is especially convenient to use GNU Emacs since that editor has a special mode, called Texinfo mode, that provides various Texinfo-related features. (@xref{Texinfo Mode}.) You can use Texinfo to create both online help and printed manuals; moreover, Texinfo is freely redistributable. For these reasons, Texinfo is the official documentation format of the GNU project. More information is available at the @uref{http://www.gnu.org/doc/, GNU documentation web page}. @node Output Formats @section Output Formats @cindex Output formats @cindex Back-end output formats Here is a brief overview of the output formats currently supported by Texinfo. @table @asis @item Info @cindex Info output (Generated via @command{makeinfo}.) This format is essentially a plain text transliteration of the Texinfo source. It adds a few control characters to separate nodes and provide navigational information for menus, cross-references, indices, and so on. See the next section (@pxref{Info Files}) for more details on this format. The Emacs Info subsystem (@pxref{Top,,Getting Started,info, Info}), and the standalone @command{info} program (@pxref{Top ,, Info Standalone, info-stnd, GNU Info}), among others, can read these files. @xref{Creating and Installing Info Files}. @item Plain text @cindex Plain text output (Generated via @command{makeinfo --no-headers}.) This is almost the same as Info output, except the navigational control characters are omitted. Also, standard output is used by default. @item HTML @cindex HTML output @cindex W3 consortium @cindex Mozilla @cindex Lynx @cindex Emacs-W3 (Generated via @command{makeinfo --html}.) This is the Hyper Text Markup Language that has become the most commonly used language for writing documents on the World Wide Web. Web browsers, such as Mozilla, Lynx, and Emacs-W3, can render this language online. There are many versions of HTML; @command{makeinfo} tries to use a subset of the language that can be interpreted by any common browser. For details of the HTML language and much related information, see @uref{http://www.w3.org/MarkUp/}. @xref{Generating HTML}. @item DVI @cindex DVI output @pindex dvips @pindex xdvi (Generated via @command{texi2dvi}.) This DeVice Independent binary format is output by the @TeX{} typesetting program (@uref{http://tug.org}). This is then read by a DVI `driver', which writes the actual device-specific commands that can be viewed or printed, notably Dvips for translation to PostScript (@pxref{Invoking Dvips,,, dvips, Dvips}) and Xdvi for viewing on an X display (@uref{http://sourceforge.net/projects/xdvi/}). @xref{Hardcopy}. Be aware that the Texinfo language is very different from and much stricter than @TeX{}'s usual languages, plain @TeX{} and @LaTeX{}. For more information on @TeX{} in general, please see the book @cite{@TeX{} for the Impatient}, available from @uref{http://savannah.gnu.org/projects/teximpatient}. @item PDF @cindex PDF output @cindex Beebe, Nelson @pindex pdftex (Generated via @command{texi2dvi --pdf} or @command{texi2pdf}.) This format was developed by Adobe Systems for portable document interchange, based on their previous PostScript language. It can represent the exact appearance of a document, including fonts and graphics, and supporting arbitrary scaling. It is intended to be platform-independent and easily viewable, among other design goals; @uref{http://tug.org/TUGboat/Articles/tb22-3/tb72beebe-pdf.pdf} has some background. Texinfo uses the @command{pdftex} program, a variant of @TeX{}, to output PDF; see @uref{http://tug.org/applications/pdftex}. @xref{PDF Output}. @item XML @cindex XML output @cindex DTD, for Texinfo XML @pindex texinfo.dtd (Generated via @command{makeinfo --xml}.) XML is a generic syntax specification usable for any sort of content (see, for example, @uref{http://www.w3.org/XML/}). The @command{makeinfo} XML output, unlike all the formats above, interprets very little of the Texinfo source. Rather, it merely translates the Texinfo markup commands into XML syntax, for processing by further XML tools. The particular syntax output is defined in the file @file{texinfo.dtd} included in the Texinfo source distribution. @item Docbook @cindex Docbook output (Generated via @command{makeinfo --docbook}.) This is an XML-based format developed some years ago, primarily for technical documentation. It therefore bears some resemblance, in broad outlines, to Texinfo. See @uref{http://www.docbook.org}. If you want to convert from Docbook @emph{to} Texinfo, please see @uref{http://docbook2X.sourceforge.net}. @end table @cindex Man page output, not supported From time to time, proposals are made to generate traditional Unix man pages from Texinfo source. However, because man pages have a very strict conventional format, generating a good man page requires a completely different source than the typical Texinfo applications of writing a good user tutorial and/or a good reference manual. This makes generating man pages incompatible with the Texinfo design goal of not having to document the same information in different ways for different output formats. You might as well just write the man page directly. @pindex help2man @cindex O'Dea, Brendan Man pages still have their place, and if you wish to support them, you may find the program @command{help2man} to be useful; it generates a traditional man page from the @samp{--help} output of a program. In fact, this is currently used to generate man pages for the programs in the Texinfo distribution. It is GNU software written by Brendan O'Dea, available from @uref{ftp://ftp.gnu.org/gnu/help2man/}. @cindex Output formats, supporting more @cindex SGML-tools output format If you are a programmer and would like to contribute to the GNU project by implementing additional output formats for Texinfo, that would be excellent. But please do not write a separate translator texi2foo for your favorite format foo! That is the hard way to do the job, and makes extra work in subsequent maintenance, since the Texinfo language is continually being enhanced and updated. Instead, the best approach is modify @code{makeinfo} to generate the new format. @node Info Files @section Info Files @cindex Info files An Info file is a Texinfo file formatted so that the Info documentation reading program can operate on it. (@code{makeinfo} and @code{texinfo-format-buffer} are two commands that convert a Texinfo file into an Info file.) Info files are divided into pieces called @dfn{nodes}, each of which contains the discussion of one topic. Each node has a name, and contains both text for the user to read and pointers to other nodes, which are identified by their names. The Info program displays one node at a time, and provides commands with which the user can move to other related nodes. @xref{Top,,, info, GNU Info}, for more information about using Info. Each node of an Info file may have any number of child nodes that describe subtopics of the node's topic. The names of child nodes are listed in a @dfn{menu} within the parent node; this allows you to use certain Info commands to move to one of the child nodes. Generally, an Info file is organized like a book. If a node is at the logical level of a chapter, its child nodes are at the level of sections; likewise, the child nodes of sections are at the level of subsections. All the children of any one parent are linked together in a bidirectional chain of `Next' and `Previous' pointers. The `Next' pointer provides a link to the next section, and the `Previous' pointer provides a link to the previous section. This means that all the nodes that are at the level of sections within a chapter are linked together. Normally the order in this chain is the same as the order of the children in the parent's menu. Each child node records the parent node name as its `Up' pointer. The last child has no `Next' pointer, and the first child has the parent both as its `Previous' and as its `Up' pointer.@footnote{In some documents, the first child has no `Previous' pointer. Occasionally, the last child has the node name of the next following higher level node as its `Next' pointer.} The book-like structuring of an Info file into nodes that correspond to chapters, sections, and the like is a matter of convention, not a requirement. The `Up', `Previous', and `Next' pointers of a node can point to any other nodes, and a menu can contain any other nodes. Thus, the node structure can be any directed graph. But it is usually more comprehensible to follow a structure that corresponds to the structure of chapters and sections in a printed book or report.@refill In addition to menus and to `Next', `Previous', and `Up' pointers, Info provides pointers of another kind, called references, that can be sprinkled throughout the text. This is usually the best way to represent links that do not fit a hierarchical structure.@refill Usually, you will design a document so that its nodes match the structure of chapters and sections in the printed output. But occasionally there are times when this is not right for the material being discussed. Therefore, Texinfo uses separate commands to specify the node structure for the Info file and the section structure for the printed output.@refill Generally, you enter an Info file through a node that by convention is named `Top'. This node normally contains just a brief summary of the file's purpose, and a large menu through which the rest of the file is reached. From this node, you can either traverse the file systematically by going from node to node, or you can go to a specific node listed in the main menu, or you can search the index menus and then go directly to the node that has the information you want. Alternatively, with the standalone Info program, you can specify specific menu items on the command line (@pxref{Top,,, info, Info}). If you want to read through an Info file in sequence, as if it were a printed manual, you can hit @key{SPC} repeatedly, or you get the whole file with the advanced Info command @kbd{g *}. (@inforef{Advanced, Advanced Info commands, info}.)@refill @c !!! dir file may be located in one of many places: @c /usr/local/emacs/info mentioned in info.c DEFAULT_INFOPATH @c /usr/local/lib/emacs/info mentioned in info.c DEFAULT_INFOPATH @c /usr/gnu/info mentioned in info.c DEFAULT_INFOPATH @c /usr/local/info @c /usr/local/lib/info The @file{dir} file in the @file{info} directory serves as the departure point for the whole Info system. From it, you can reach the `Top' nodes of each of the documents in a complete Info system.@refill @cindex URI syntax for Info If you wish to refer to an Info file in a URI, you can use the (unofficial) syntax exemplified in the following. This works with Emacs/W3, for example: @example info:///usr/info/emacs#Dissociated%20Press info:emacs#Dissociated%20Press info://localhost/usr/info/emacs#Dissociated%20Press @end example The @command{info} program itself does not follow URIs of any kind. @node Printed Books @section Printed Books @cindex Printed book and manual characteristics @cindex Manual characteristics, printed @cindex Book characteristics, printed @cindex Texinfo printed book characteristics @cindex Characteristics, printed books or manuals @cindex Knuth, Donald A Texinfo file can be formatted and typeset as a printed book or manual. To do this, you need @TeX{}, a powerful, sophisticated typesetting program written by Donald Knuth.@footnote{You can also use the @pindex texi2roff@r{, unsupported software} @uref{ftp://tug.org/texi2roff.tar.gz, @code{texi2roff}} program if you do not have @TeX{}; since Texinfo is designed for use with @TeX{}, @code{texi2roff} is not described here. @code{texi2roff} is not part of the standard GNU distribution and is not maintained or up-to-date with all the Texinfo features described in this manual.} A Texinfo-based book is similar to any other typeset, printed work: it can have a title page, copyright page, table of contents, and preface, as well as chapters, numbered or unnumbered sections and subsections, page headers, cross references, footnotes, and indices.@refill You can use Texinfo to write a book without ever having the intention of converting it into online information. You can use Texinfo for writing a printed novel, and even to write a printed memo, although this latter application is not recommended since electronic mail is so much easier.@refill @TeX{} is a general purpose typesetting program. Texinfo provides a file @file{texinfo.tex} that contains information (definitions or @dfn{macros}) that @TeX{} uses when it typesets a Texinfo file. (@file{texinfo.tex} tells @TeX{} how to convert the Texinfo @@-commands to @TeX{} commands, which @TeX{} can then process to create the typeset document.) @file{texinfo.tex} contains the specifications for printing a document. You can get the latest version of @file{texinfo.tex} from the Texinfo home page, @uref{http://www.gnu.org/software/texinfo/}. In the United States, documents are most often printed on 8.5 inch by 11 inch pages (216@dmn{mm} by 280@dmn{mm}); this is the default size. But you can also print for 7 inch by 9.25 inch pages (178@dmn{mm} by 235@dmn{mm}, the @code{@@smallbook} size; or on A4 or A5 size paper (@code{@@afourpaper}, @code{@@afivepaper}). (@xref{smallbook, , Printing ``Small'' Books}. Also, see @ref{A4 Paper, ,Printing on A4 Paper}.) By changing the parameters in @file{texinfo.tex}, you can change the size of the printed document. In addition, you can change the style in which the printed document is formatted; for example, you can change the sizes and fonts used, the amount of indentation for each paragraph, the degree to which words are hyphenated, and the like. By changing the specifications, you can make a book look dignified, old and serious, or light-hearted, young and cheery. @TeX{} is freely distributable. It is written in a superset of Pascal called WEB and can be compiled either in Pascal or (by using a conversion program that comes with the @TeX{} distribution) in C. (@xref{TeX Mode, ,@TeX{} Mode, emacs, The GNU Emacs Manual}, for information about @TeX{}.)@refill @TeX{} is very powerful and has a great many features. Because a Texinfo file must be able to present information both on a character-only terminal in Info form and in a typeset book, the formatting commands that Texinfo supports are necessarily limited. To get a copy of @TeX{}, see @ref{Obtaining TeX, , How to Obtain @TeX{}}. @node Formatting Commands @section @@-commands @cindex @@-commands @cindex Formatting commands In a Texinfo file, the commands that tell @TeX{} how to typeset the printed manual and tell @code{makeinfo} and @code{texinfo-format-buffer} how to create an Info file are preceded by @samp{@@}; they are called @dfn{@@-commands}. For example, @code{@@node} is the command to indicate a node and @code{@@chapter} is the command to indicate the start of a chapter.@refill @quotation Note Almost all @@ command names are entirely lower case. @end quotation The Texinfo @@-commands are a strictly limited set of constructs. The strict limits make it possible for Texinfo files to be understood both by @TeX{} and by the code that converts them into Info files. You can display Info files on any terminal that displays alphabetic and numeric characters. Similarly, you can print the output generated by @TeX{} on a wide variety of printers.@refill Depending on what they do or what arguments@footnote{The word @dfn{argument} comes from the way it is used in mathematics and does not refer to a dispute between two people; it refers to the information presented to the command. According to the @cite{Oxford English Dictionary}, the word derives from the Latin for @dfn{to make clear, prove}; thus it came to mean `the evidence offered as proof', which is to say, `the information offered', which led to its mathematical meaning. In its other thread of derivation, the word came to mean `to assert in a manner against which others may make counter assertions', which led to the meaning of `argument' as a dispute.} they take, you need to write @@-commands on lines of their own or as part of sentences: @itemize @bullet @item Write a command such as @code{@@quotation} at the beginning of a line as the only text on the line. (@code{@@quotation} begins an indented environment.) @item Write a command such as @code{@@chapter} at the beginning of a line followed by the command's arguments, in this case the chapter title, on the rest of the line. (@code{@@chapter} creates chapter titles.)@refill @item Write a command such as @code{@@dots@{@}} wherever you wish but usually within a sentence. (@code{@@dots@{@}} creates an ellipsis @dots{})@refill @item Write a command such as @code{@@code@{@var{sample-code}@}} wherever you wish (but usually within a sentence) with its argument, @var{sample-code} in this example, between the braces. (@code{@@code} marks text as being code.)@refill @item Write a command such as @code{@@example} on a line of its own; write the body-text on following lines; and write the matching @code{@@end} command, @code{@@end example} in this case, on a line of its own after the body-text. (@code{@@example} @dots{} @code{@@end example} indents and typesets body-text as an example.) It's usually ok to indent environment commands like this, but in complicated and hard-to-define circumstances the extra spaces cause extra space to appear in the output, so beware. @end itemize @noindent @cindex Braces, when to use As a general rule, a command requires braces if it mingles among other text; but it does not need braces if it starts a line of its own. The non-alphabetic commands, such as @code{@@:}, are exceptions to the rule; they do not need braces.@refill As you gain experience with Texinfo, you will rapidly learn how to write the different commands: the different ways to write commands actually make it easier to write and read Texinfo files than if all commands followed exactly the same syntax. @xref{Command Syntax, , @@-Command Syntax}, for all the details. @node Conventions @section General Syntactic Conventions @cindex General syntactic conventions @cindex Syntactic conventions @cindex Conventions, syntactic @cindex Characters, basic input This section describes the general conventions used in all Texinfo documents. @itemize @bullet @item @cindex Source files, characters used All printable ASCII characters except @samp{@@}, @samp{@{} and @samp{@}} can appear in a Texinfo file and stand for themselves. @samp{@@} is the escape character which introduces commands, while @samp{@{} and @samp{@}} are used to surround arguments to certain commands. To put one of these special characters into the document, put an @samp{@@} character in front of it, like this: @samp{@@@@}, @samp{@@@{}, and @samp{@@@}}. @item @cindex Paragraph separator @cindex Blank lines, as paragraph separator @cindex Newlines, as blank lines Separate paragraphs with one or more blank lines. Currently Texinfo only recognizes newline characters as end of line, not the CRLF sequence used on some systems; so a @dfn{blank line} means exactly two consecutive newlines. Sometimes blank lines are useful or convenient in other cases as well; you can use the @code{@@noindent} to inhibit paragraph indentation if required (@pxref{noindent,,@code{@@noindent}}). @item Texinfo supports the usual quotation marks used in English, and quotation marks used in other languages, please see @ref{Inserting Quotation Marks}. @item @cindex Multiple dashes in source @cindex Dashes in source @cindex Hyphens in source, two or three in a row @cindex Em dash, producing @cindex En dash, producing Use three hyphens in a row, @samp{---}, to produce a long dash---like this (called an @dfn{em dash}), used for punctuation in sentences. Use two hyphens, @samp{--}, to produce a medium dash (called an @dfn{en dash}), used primarily for numeric ranges, as in ``June 25--26''. Use a single hyphen, @samp{-}, to produce a standard hyphen used in compound words. For display on the screen, Info reduces three hyphens to two and two hyphens to one (not transitively!). Of course, any number of hyphens in the source remain as they are in literal contexts, such as @code{@@code} and @code{@@example}. @item @cindex Tabs; don't use! @strong{Caution:} Last, do not use tab characters in a Texinfo file (except in verbatim modes)! @TeX{} uses variable-width fonts, which means that it is impractical at best to define a tab to work in all circumstances. Consequently, @TeX{} treats tabs like single spaces, and that is not what they look like in the source. Furthermore, @code{makeinfo} does nothing special with tabs, and thus a tab character in your input file will usually appear differently in the output. @noindent To avoid this problem, Texinfo mode in GNU Emacs inserts multiple spaces when you press the @key{TAB} key. Also, you can run @code{untabify} in Emacs to convert tabs in a region to multiple spaces, or use the @code{unexpand} command from the shell. @end itemize @node Comments @section Comments @cindex Comments @findex comment @findex c @r{(comment)} You can write comments in a Texinfo file that will not appear in either the Info file or the printed manual by using the @code{@@comment} command (which may be abbreviated to @code{@@c}). Such comments are for the person who revises the Texinfo file. All the text on a line that follows either @code{@@comment} or @code{@@c} is a comment; the rest of the line does not appear in either the Info file or the printed manual. Often, you can write the @code{@@comment} or @code{@@c} in the middle of a line, and only the text that follows after the @code{@@comment} or @code{@@c} command does not appear; but some commands, such as @code{@@settitle} and @code{@@setfilename}, work on a whole line. You cannot use @code{@@comment} or @code{@@c} in a line beginning with such a command. @cindex Ignored text @cindex Unprocessed text @findex ignore You can write long stretches of text that will not appear in either the Info file or the printed manual by using the @code{@@ignore} and @code{@@end ignore} commands. Write each of these commands on a line of its own, starting each command at the beginning of the line. Text between these two commands does not appear in the processed output. You can use @code{@@ignore} and @code{@@end ignore} for writing comments. Text enclosed by @code{@@ignore} or by failing @code{@@ifset} or @code{@@ifclear} conditions is ignored in the sense that it will not contribute to the formatted output. However, @TeX{} and makeinfo must still parse the ignored text, in order to understand when to @emph{stop} ignoring text from the source file; that means that you may still get error messages if you have invalid Texinfo commands within ignored text. @node Minimum @section What a Texinfo File Must Have @cindex Minimal Texinfo file (requirements) @cindex Must have in Texinfo file @cindex Required in Texinfo file @cindex Texinfo file minimum By convention, the name of a Texinfo file ends with (in order of preference) one of the extensions @file{.texinfo}, @file{.texi}, @file{.txi}, or @file{.tex}. The longer extensions are preferred since they describe more clearly to a human reader the nature of the file. The shorter extensions are for operating systems that cannot handle long file names. In order to be made into a printed manual and an Info file, a Texinfo file @strong{must} begin with lines like this: @example @group \input texinfo @@setfilename @var{info-file-name} @@settitle @var{name-of-manual} @end group @end example @noindent The contents of the file follow this beginning, and then you @strong{must} end a Texinfo file with a line like this: @example @@bye @end example @findex \input @r{(raw @TeX{} startup)} @noindent Here's an explanation: @itemize @bullet @item The @samp{\input texinfo} line tells @TeX{} to use the @file{texinfo.tex} file, which tells @TeX{} how to translate the Texinfo @@-commands into @TeX{} typesetting commands. (Note the use of the backslash, @samp{\}; this is correct for @TeX{}.) @item The @code{@@setfilename} line provides a name for the Info file and tells @TeX{} to open auxiliary files. @strong{All text before @code{@@setfilename} is ignored!} @item The @code{@@settitle} line specifies a title for the page headers (or footers) of the printed manual, and the default document description for the @samp{} in HTML format. Strictly speaking, @code{@@settitle} is optional---if you don't mind your document being titled `Untitled'. @item The @code{@@bye} line at the end of the file on a line of its own tells the formatters that the file is ended and to stop formatting. @end itemize Typically, you will not use quite such a spare format, but will include mode setting and start-of-header and end-of-header lines at the beginning of a Texinfo file, like this: @example @group \input texinfo @@c -*-texinfo-*- @@c %**start of header @@setfilename @var{info-file-name} @@settitle @var{name-of-manual} @@c %**end of header @end group @end example @noindent In the first line, @samp{-*-texinfo-*-} causes Emacs to switch into Texinfo mode when you edit the file. The @code{@@c} lines which surround the @code{@@setfilename} and @code{@@settitle} lines are optional, but you need them in order to run @TeX{} or Info on just part of the file. (@xref{Start of Header}.) Furthermore, you will usually provide a Texinfo file with a title page, indices, and the like, all of which are explained in this manual. But the minimum, which can be useful for short documents, is just the three lines at the beginning and the one line at the end. @node Six Parts @section Six Parts of a Texinfo File Generally, a Texinfo file contains more than the minimal beginning and end described in the previous section---it usually contains the six parts listed below. These are described fully in the following sections. @table @r @item 1. Header The @dfn{Header} names the file, tells @TeX{} which definitions file to use, and other such housekeeping tasks. @item 2. Summary and Copyright The @dfn{Summary and Copyright} segment describes the document and contains the copyright notice and copying permissions. This is done with the @code{@@copying} command. @item 3. Title and Copyright The @dfn{Title and Copyright} segment contains the title and copyright pages for the printed manual. The segment must be enclosed between @code{@@titlepage} and @code{@@end titlepage} commands. The title and copyright page appear only in the printed manual. @item 4. `Top' Node and Master Menu The `Top' node starts off the online output; it does not appear in the printed manual. We recommend including the copying permissions here as well as the segments above. And it contains at least a top-level menu listing the chapters, and possibly a @dfn{Master Menu} listing all the nodes in the entire document. @item 5. Body The @dfn{Body} of the document is typically structured like a traditional book or encyclopedia, but it may be free form. @item 6. End The @dfn{End} segment may contain commands for printing indices, and closes with the @code{@@bye} command on a line of its own. @end table @node Short Sample @section A Short Sample Texinfo File @cindex Sample Texinfo file, with comments Here is a very short but complete Texinfo file, in the six conventional parts enumerated in the previous section, so you can see how Texinfo source appears in practice. The first three parts of the file, from @samp{\input texinfo} through to @samp{@@end titlepage}, look more intimidating than they are: most of the material is standard boilerplate; when writing a manual, you simply change the names as appropriate. @xref{Beginning a File}, for full documentation on the commands listed here. @xref{GNU Sample Texts}, for the full texts to be used in GNU manuals. In the following, the sample text is @emph{indented}; comments on it are not. The complete file, without interspersed comments, is shown in @ref{Short Sample Texinfo File}. @subheading Part 1: Header @noindent The header does not appear in either the Info file or the printed output. It sets various parameters, including the name of the Info file and the title used in the header. @example @group \input texinfo @@c -*-texinfo-*- @@c %**start of header @@setfilename sample.info @@settitle Sample Manual 1.0 @@c %**end of header @end group @end example @subheading Part 2: Summary Description and Copyright @noindent A real manual includes more text here, according to the license under which it is distributed. @xref{GNU Sample Texts}. @example @group @@copying This is a short example of a complete Texinfo file, version 1.0. Copyright @@copyright@{@} 2005 Free Software Foundation, Inc. @@end copying @end group @end example @subheading Part 3: Titlepage, Contents, Copyright @noindent The titlepage segment does not appear in the online output, only in the printed manual. We use the @code{@@insertcopying} command to include the permission text from the previous section, instead of writing it out again; it is output on the back of the title page. The @code{@@contents} command generates a table of contents. @example @group @@titlepage @@title Sample Title @end group @group @@c The following two commands start the copyright page. @@page @@vskip 0pt plus 1filll @@insertcopying @@end titlepage @end group @@c Output the table of contents at the beginning. @@contents @end example @subheading Part 4: `Top' Node and Master Menu @noindent The `Top' node contains the master menu for the Info file. Since the printed manual uses a table of contents rather than a menu, it excludes the `Top' node. We repeat the short description from the beginning of the @samp{@@copying} text, but there's no need to repeat the copyright information, so we don't use @samp{@@insertcopying} here. The @samp{@@top} command itself helps @command{makeinfo} determine the relationships between nodes. @example @@ifnottex @@node Top @@top Short Sample This is a short sample Texinfo file. @@end ifnottex @group @@menu * First Chapter:: The first chapter is the only chapter in this sample. * Index:: Complete index. @@end menu @end group @end example @subheading Part 5: The Body of the Document @noindent The body segment contains all the text of the document, but not the indices or table of contents. This example illustrates a node and a chapter containing an enumerated list. @example @group @@node First Chapter @@chapter First Chapter @@cindex chapter, first @end group @group This is the first chapter. @@cindex index entry, another @end group @group Here is a numbered list. @@enumerate @@item This is the first item. @@item This is the second item. @@end enumerate @end group @end example @subheading Part 6: The End of the Document @noindent The end segment contains commands for generating an index in a node and unnumbered chapter of its own, and the @code{@@bye} command that marks the end of the document. @example @group @@node Index @@unnumbered Index @end group @group @@printindex cp @@bye @end group @end example @subheading Some Results Here is what the contents of the first chapter of the sample look like: @sp 1 @need 700 @quotation This is the first chapter. Here is a numbered list. @enumerate @item This is the first item. @item This is the second item. @end enumerate @end quotation @node History @section History @cindex Stallman, Richard M. @cindex Chassell, Robert J. @cindex Fox, Brian @cindex Berry, Karl Richard M. Stallman invented the Texinfo format, wrote the initial processors, and created Edition 1.0 of this manual. Robert@tie{}J. Chassell greatly revised and extended the manual, starting with Edition 1.1. Brian Fox was responsible for the standalone Texinfo distribution until version 3.8, and wrote the standalone @command{makeinfo} and @command{info} programs. Karl Berry has continued maintenance since Texinfo 3.8 (manual edition 2.22). @cindex Pinard, Fran@,{c}ois @cindex Zuhn, David D. @cindex Weisshaus, Melissa @cindex Zaretskii, Eli @cindex Schwab, Andreas @cindex Weinberg, Zack Our thanks go out to all who helped improve this work, particularly the indefatigable Eli Zaretskii and Andreas Schwab, who have provided patches beyond counting. Fran@,{c}ois Pinard and David@tie{}D. Zuhn, tirelessly recorded and reported mistakes and obscurities. Zack Weinberg did the impossible by implementing the macro syntax in @file{texinfo.tex}. Special thanks go to Melissa Weisshaus for her frequent reviews of nearly similar editions. Dozens of others have contributed patches and suggestions, they are gratefully acknowledged in the @file{ChangeLog} file. Our mistakes are our own. @cindex Scribe @cindex Reid, Brian @cindex History of Texinfo @cindex Texinfo history A bit of history: in the 1970's at CMU, Brian Reid developed a program and format named Scribe to mark up documents for printing. It used the @code{@@} character to introduce commands, as Texinfo does. Much more consequentially, it strove to describe document contents rather than formatting, an idea wholeheartedly adopted by Texinfo. @cindex Bolio @cindex Bo@TeX{} Meanwhile, people at MIT developed another, not too dissimilar format called Bolio. This then was converted to using @TeX{} as its typesetting language: Bo@TeX{}. The earliest Bo@TeX{} version seems to have been 0.02 on October 31, 1984. Bo@TeX{} could only be used as a markup language for documents to be printed, not for online documents. Richard Stallman (RMS) worked on both Bolio and Bo@TeX{}. He also developed a nifty on-line help format called Info, and then combined Bo@TeX{} and Info to create Texinfo, a mark up language for text that is intended to be read both online and as printed hard copy. @node Texinfo Mode @chapter Using Texinfo Mode @cindex Texinfo mode @cindex Mode, using Texinfo @cindex GNU Emacs @cindex Emacs You may edit a Texinfo file with any text editor you choose. A Texinfo file is no different from any other ASCII file. However, GNU Emacs comes with a special mode, called Texinfo mode, that provides Emacs commands and tools to help ease your work. This chapter describes features of GNU Emacs' Texinfo mode but not any features of the Texinfo formatting language. So if you are reading this manual straight through from the beginning, you may want to skim through this chapter briefly and come back to it after reading succeeding chapters which describe the Texinfo formatting language in detail. @menu * Texinfo Mode Overview:: How Texinfo mode can help you. * Emacs Editing:: Texinfo mode adds to GNU Emacs' general purpose editing features. * Inserting:: How to insert frequently used @@-commands. * Showing the Structure:: How to show the structure of a file. * Updating Nodes and Menus:: How to update or create new nodes and menus. * Info Formatting:: How to format for Info. * Printing:: How to format and print part or all of a file. * Texinfo Mode Summary:: Summary of all the Texinfo mode commands. @end menu @node Texinfo Mode Overview @section Texinfo Mode Overview Texinfo mode provides special features for working with Texinfo files. You can: @itemize @bullet @item Insert frequently used @@-commands. @refill @item Automatically create @code{@@node} lines. @item Show the structure of a Texinfo source file.@refill @item Automatically create or update the `Next', `Previous', and `Up' pointers of a node. @item Automatically create or update menus.@refill @item Automatically create a master menu.@refill @item Format a part or all of a file for Info.@refill @item Typeset and print part or all of a file.@refill @end itemize Perhaps the two most helpful features are those for inserting frequently used @@-commands and for creating node pointers and menus.@refill @node Emacs Editing @section The Usual GNU Emacs Editing Commands In most cases, the usual Text mode commands work the same in Texinfo mode as they do in Text mode. Texinfo mode adds new editing commands and tools to GNU Emacs' general purpose editing features. The major difference concerns filling. In Texinfo mode, the paragraph separation variable and syntax table are redefined so that Texinfo commands that should be on lines of their own are not inadvertently included in paragraphs. Thus, the @kbd{M-q} (@code{fill-paragraph}) command will refill a paragraph but not mix an indexing command on a line adjacent to it into the paragraph.@refill In addition, Texinfo mode sets the @code{page-delimiter} variable to the value of @code{texinfo-chapter-level-regexp}; by default, this is a regular expression matching the commands for chapters and their equivalents, such as appendices. With this value for the page delimiter, you can jump from chapter title to chapter title with the @kbd{C-x ]} (@code{forward-page}) and @kbd{C-x [} (@code{backward-page}) commands and narrow to a chapter with the @kbd{C-x n p} (@code{narrow-to-page}) command. (@xref{Pages, , ,emacs, The GNU Emacs Manual}, for details about the page commands.)@refill You may name a Texinfo file however you wish, but the convention is to end a Texinfo file name with one of the extensions @file{.texinfo}, @file{.texi}, @file{.txi}, or @file{.tex}. A longer extension is preferred, since it is explicit, but a shorter extension may be necessary for operating systems that limit the length of file names. GNU Emacs automatically enters Texinfo mode when you visit a file with a @file{.texinfo}, @file{.texi} or @file{.txi} extension. Also, Emacs switches to Texinfo mode when you visit a file that has @samp{-*-texinfo-*-} in its first line. If ever you are in another mode and wish to switch to Texinfo mode, type @code{M-x texinfo-mode}.@refill Like all other Emacs features, you can customize or enhance Texinfo mode as you wish. In particular, the keybindings are very easy to change. The keybindings described here are the default or standard ones.@refill @node Inserting @comment node-name, next, previous, up @section Inserting Frequently Used Commands @cindex Inserting frequently used commands @cindex Frequently used commands, inserting @cindex Commands, inserting them Texinfo mode provides commands to insert various frequently used @@-commands into the buffer. You can use these commands to save keystrokes.@refill The insert commands are invoked by typing @kbd{C-c} twice and then the first letter of the @@-command:@refill @table @kbd @item C-c C-c c @itemx M-x texinfo-insert-@@code @findex texinfo-insert-@@code Insert @code{@@code@{@}} and put the cursor between the braces.@refill @item C-c C-c d @itemx M-x texinfo-insert-@@dfn @findex texinfo-insert-@@dfn Insert @code{@@dfn@{@}} and put the cursor between the braces.@refill @item C-c C-c e @itemx M-x texinfo-insert-@@end @findex texinfo-insert-@@end Insert @code{@@end} and attempt to insert the correct following word, such as @samp{example} or @samp{table}. (This command does not handle nested lists correctly, but inserts the word appropriate to the immediately preceding list.)@refill @item C-c C-c i @itemx M-x texinfo-insert-@@item @findex texinfo-insert-@@item Insert @code{@@item} and put the cursor at the beginning of the next line.@refill @item C-c C-c k @itemx M-x texinfo-insert-@@kbd @findex texinfo-insert-@@kbd Insert @code{@@kbd@{@}} and put the cursor between the braces.@refill @item C-c C-c n @itemx M-x texinfo-insert-@@node @findex texinfo-insert-@@node Insert @code{@@node} and a comment line listing the sequence for the `Next', `Previous', and `Up' nodes. Leave point after the @code{@@node}.@refill @item C-c C-c o @itemx M-x texinfo-insert-@@noindent @findex texinfo-insert-@@noindent Insert @code{@@noindent} and put the cursor at the beginning of the next line.@refill @item C-c C-c s @itemx M-x texinfo-insert-@@samp @findex texinfo-insert-@@samp Insert @code{@@samp@{@}} and put the cursor between the braces.@refill @item C-c C-c t @itemx M-x texinfo-insert-@@table @findex texinfo-insert-@@table Insert @code{@@table} followed by a @key{SPC} and leave the cursor after the @key{SPC}.@refill @item C-c C-c v @itemx M-x texinfo-insert-@@var @findex texinfo-insert-@@var Insert @code{@@var@{@}} and put the cursor between the braces.@refill @item C-c C-c x @itemx M-x texinfo-insert-@@example @findex texinfo-insert-@@example Insert @code{@@example} and put the cursor at the beginning of the next line.@refill @c M-@{ was the binding for texinfo-insert-braces; @c in Emacs 19, backward-paragraph will take this binding. @item C-c C-c @{ @itemx M-x texinfo-insert-braces @findex texinfo-insert-braces Insert @code{@{@}} and put the cursor between the braces.@refill @item C-c @} @itemx C-c ] @itemx M-x up-list @findex up-list Move from between a pair of braces forward past the closing brace. Typing @kbd{C-c ]} is easier than typing @kbd{C-c @}}, which is, however, more mnemonic; hence the two keybindings. (Also, you can move out from between braces by typing @kbd{C-f}.)@refill @end table To put a command such as @w{@code{@@code@{@dots{}@}}} around an @emph{existing} word, position the cursor in front of the word and type @kbd{C-u 1 C-c C-c c}. This makes it easy to edit existing plain text. The value of the prefix argument tells Emacs how many words following point to include between braces---@samp{1} for one word, @samp{2} for two words, and so on. Use a negative argument to enclose the previous word or words. If you do not specify a prefix argument, Emacs inserts the @@-command string and positions the cursor between the braces. This feature works only for those @@-commands that operate on a word or words within one line, such as @code{@@kbd} and @code{@@var}.@refill This set of insert commands was created after analyzing the frequency with which different @@-commands are used in the @cite{GNU Emacs Manual} and the @cite{GDB Manual}. If you wish to add your own insert commands, you can bind a keyboard macro to a key, use abbreviations, or extend the code in @file{texinfo.el}.@refill @findex texinfo-start-menu-description @cindex Menu description, start @cindex Description for menu, start @kbd{C-c C-c C-d} (@code{texinfo-start-menu-description}) is an insert command that works differently from the other insert commands. It inserts a node's section or chapter title in the space for the description in a menu entry line. (A menu entry has three parts, the entry name, the node name, and the description. Only the node name is required, but a description helps explain what the node is about. @xref{Menu Parts, , The Parts of a Menu}.)@refill To use @code{texinfo-start-menu-description}, position point in a menu entry line and type @kbd{C-c C-c C-d}. The command looks for and copies the title that goes with the node name, and inserts the title as a description; it positions point at beginning of the inserted text so you can edit it. The function does not insert the title if the menu entry line already contains a description.@refill This command is only an aid to writing descriptions; it does not do the whole job. You must edit the inserted text since a title tends to use the same words as a node name but a useful description uses different words.@refill @node Showing the Structure @comment node-name, next, previous, up @section Showing the Section Structure of a File @cindex Showing the section structure of a file @cindex Section structure of a file, showing it @cindex Structure of a file, showing it @cindex Outline of file structure, showing it @cindex Contents-like outline of file structure @cindex File section structure, showing it @cindex Texinfo file section structure, showing it You can show the section structure of a Texinfo file by using the @kbd{C-c C-s} command (@code{texinfo-show-structure}). This command shows the section structure of a Texinfo file by listing the lines that begin with the @@-commands for @code{@@chapter}, @code{@@section}, and the like. It constructs what amounts to a table of contents. These lines are displayed in another buffer called the @samp{*Occur*} buffer. In that buffer, you can position the cursor over one of the lines and use the @kbd{C-c C-c} command (@code{occur-mode-goto-occurrence}), to jump to the corresponding spot in the Texinfo file.@refill @table @kbd @item C-c C-s @itemx M-x texinfo-show-structure @findex texinfo-show-structure Show the @code{@@chapter}, @code{@@section}, and such lines of a Texinfo file.@refill @item C-c C-c @itemx M-x occur-mode-goto-occurrence @findex occur-mode-goto-occurrence Go to the line in the Texinfo file corresponding to the line under the cursor in the @file{*Occur*} buffer.@refill @end table If you call @code{texinfo-show-structure} with a prefix argument by typing @w{@kbd{C-u C-c C-s}}, it will list not only those lines with the @@-commands for @code{@@chapter}, @code{@@section}, and the like, but also the @code{@@node} lines. You can use @code{texinfo-show-structure} with a prefix argument to check whether the `Next', `Previous', and `Up' pointers of an @code{@@node} line are correct. Often, when you are working on a manual, you will be interested only in the structure of the current chapter. In this case, you can mark off the region of the buffer that you are interested in by using the @kbd{C-x n n} (@code{narrow-to-region}) command and @code{texinfo-show-structure} will work on only that region. To see the whole buffer again, use @w{@kbd{C-x n w}} (@code{widen}). (@xref{Narrowing, , , emacs, The GNU Emacs Manual}, for more information about the narrowing commands.)@refill @vindex page-delimiter @cindex Page delimiter in Texinfo mode In addition to providing the @code{texinfo-show-structure} command, Texinfo mode sets the value of the page delimiter variable to match the chapter-level @@-commands. This enables you to use the @kbd{C-x ]} (@code{forward-page}) and @kbd{C-x [} (@code{backward-page}) commands to move forward and backward by chapter, and to use the @kbd{C-x n p} (@code{narrow-to-page}) command to narrow to a chapter. @xref{Pages, , , emacs, The GNU Emacs Manual}, for more information about the page commands.@refill @node Updating Nodes and Menus @comment node-name, next, previous, up @section Updating Nodes and Menus @cindex Updating nodes and menus @cindex Create nodes, menus automatically @cindex Insert nodes, menus automatically @cindex Automatically insert nodes, menus Texinfo mode provides commands for automatically creating or updating menus and node pointers. The commands are called ``update'' commands because their most frequent use is for updating a Texinfo file after you have worked on it; but you can use them to insert the `Next', `Previous', and `Up' pointers into an @code{@@node} line that has none and to create menus in a file that has none. If you do not use the updating commands, you need to write menus and node pointers by hand, which is a tedious task.@refill @menu * Updating Commands:: Five major updating commands. * Updating Requirements:: How to structure a Texinfo file for using the updating command. * Other Updating Commands:: How to indent descriptions, insert missing nodes lines, and update nodes in sequence. @end menu @node Updating Commands @subsection The Updating Commands You can use the updating commands to:@refill @itemize @bullet @item insert or update the `Next', `Previous', and `Up' pointers of a node,@refill @item insert or update the menu for a section, and@refill @item create a master menu for a Texinfo source file.@refill @end itemize You can also use the commands to update all the nodes and menus in a region or in a whole Texinfo file.@refill The updating commands work only with conventional Texinfo files, which are structured hierarchically like books. In such files, a structuring command line must follow closely after each @code{@@node} line, except for the `Top' @code{@@node} line. (A @dfn{structuring command line} is a line beginning with @code{@@chapter}, @code{@@section}, or other similar command.) You can write the structuring command line on the line that follows immediately after an @code{@@node} line or else on the line that follows after a single @code{@@comment} line or a single @code{@@ifinfo} line. You cannot interpose more than one line between the @code{@@node} line and the structuring command line; and you may interpose only an @code{@@comment} line or an @code{@@ifinfo} line. Commands which work on a whole buffer require that the `Top' node be followed by a node with an @code{@@chapter} or equivalent-level command. The menu updating commands will not create a main or master menu for a Texinfo file that has only @code{@@chapter}-level nodes! The menu updating commands only create menus @emph{within} nodes for lower level nodes. To create a menu of chapters, you must provide a `Top' node. The menu updating commands remove menu entries that refer to other Info files since they do not refer to nodes within the current buffer. This is a deficiency. Rather than use menu entries, you can use cross references to refer to other Info files. None of the updating commands affect cross references.@refill Texinfo mode has five updating commands that are used most often: two are for updating the node pointers or menu of a single node (or a region); two are for updating every node pointer and menu in a file; and one, the @code{texinfo-master-menu} command, is for creating a master menu for a complete file, and optionally, for updating every node and menu in the whole Texinfo file.@refill The @code{texinfo-master-menu} command is the primary command:@refill @table @kbd @item C-c C-u m @itemx M-x texinfo-master-menu @findex texinfo-master-menu Create or update a master menu that includes all the other menus (incorporating the descriptions from pre-existing menus, if any).@refill With an argument (prefix argument, @kbd{C-u,} if interactive), first create or update all the nodes and all the regular menus in the buffer before constructing the master menu. (@xref{The Top Node, , The Top Node and Master Menu}, for more about a master menu.)@refill For @code{texinfo-master-menu} to work, the Texinfo file must have a `Top' node and at least one subsequent node.@refill After extensively editing a Texinfo file, you can type the following: @example C-u M-x texinfo-master-menu @exdent or C-u C-c C-u m @end example @noindent This updates all the nodes and menus completely and all at once.@refill @end table The other major updating commands do smaller jobs and are designed for the person who updates nodes and menus as he or she writes a Texinfo file.@refill @need 1000 The commands are:@refill @table @kbd @item C-c C-u C-n @itemx M-x texinfo-update-node @findex texinfo-update-node Insert the `Next', `Previous', and `Up' pointers for the node that point is within (i.e., for the @code{@@node} line preceding point). If the @code{@@node} line has pre-existing `Next', `Previous', or `Up' pointers in it, the old pointers are removed and new ones inserted. With an argument (prefix argument, @kbd{C-u}, if interactive), this command updates all @code{@@node} lines in the region (which is the text between point and mark).@refill @item C-c C-u C-m @itemx M-x texinfo-make-menu @findex texinfo-make-menu Create or update the menu in the node that point is within. With an argument (@kbd{C-u} as prefix argument, if interactive), the command makes or updates menus for the nodes which are either within or a part of the region.@refill Whenever @code{texinfo-make-menu} updates an existing menu, the descriptions from that menu are incorporated into the new menu. This is done by copying descriptions from the existing menu to the entries in the new menu that have the same node names. If the node names are different, the descriptions are not copied to the new menu.@refill @item C-c C-u C-e @itemx M-x texinfo-every-node-update @findex texinfo-every-node-update Insert or update the `Next', `Previous', and `Up' pointers for every node in the buffer.@refill @item C-c C-u C-a @itemx M-x texinfo-all-menus-update @findex texinfo-all-menus-update Create or update all the menus in the buffer. With an argument (@kbd{C-u} as prefix argument, if interactive), first insert or update all the node pointers before working on the menus.@refill If a master menu exists, the @code{texinfo-all-menus-update} command updates it; but the command does not create a new master menu if none already exists. (Use the @code{texinfo-master-menu} command for that.)@refill When working on a document that does not merit a master menu, you can type the following: @example C-u C-c C-u C-a @exdent or C-u M-x texinfo-all-menus-update @end example @noindent This updates all the nodes and menus.@refill @end table The @code{texinfo-column-for-description} variable specifies the column to which menu descriptions are indented. By default, the value is 32 although it can be useful to reduce it to as low as 24. You can set the variable via customization (@pxref{Changing an Option,,, emacs, The GNU Emacs Manual}) or with the @kbd{M-x set-variable} command (@pxref{Examining, , Examining and Setting Variables, emacs, The GNU Emacs Manual}). Also, the @code{texinfo-indent-menu-description} command may be used to indent existing menu descriptions to a specified column. Finally, if you wish, you can use the @code{texinfo-insert-node-lines} command to insert missing @code{@@node} lines into a file. (@xref{Other Updating Commands}, for more information.)@refill @node Updating Requirements @subsection Updating Requirements @cindex Updating requirements @cindex Requirements for updating commands To use the updating commands, you must organize the Texinfo file hierarchically with chapters, sections, subsections, and the like. When you construct the hierarchy of the manual, do not `jump down' more than one level at a time: you can follow the `Top' node with a chapter, but not with a section; you can follow a chapter with a section, but not with a subsection. However, you may `jump up' any number of levels at one time---for example, from a subsection to a chapter.@refill Each @code{@@node} line, with the exception of the line for the `Top' node, must be followed by a line with a structuring command such as @code{@@chapter}, @code{@@section}, or @code{@@unnumberedsubsec}.@refill Each @code{@@node} line/structuring-command line combination must look either like this: @example @group @@node Comments, Minimum, Conventions, Overview @@comment node-name, next, previous, up @@section Comments @end group @end example or like this (without the @code{@@comment} line): @example @group @@node Comments, Minimum, Conventions, Overview @@section Comments @end group @end example or like this (without the explicit node pointers): @example @group @@node Comments @@section Comments @end group @end example @noindent In this example, `Comments' is the name of both the node and the section. The next node is called `Minimum' and the previous node is called `Conventions'. The `Comments' section is within the `Overview' node, which is specified by the `Up' pointer. (Instead of an @code{@@comment} line, you may also write an @code{@@ifinfo} line.) If a file has a `Top' node, it must be called @samp{top} or @samp{Top} and be the first node in the file. The menu updating commands create a menu of sections within a chapter, a menu of subsections within a section, and so on. This means that you must have a `Top' node if you want a menu of chapters.@refill Incidentally, the @code{makeinfo} command will create an Info file for a hierarchically organized Texinfo file that lacks `Next', `Previous' and `Up' pointers. Thus, if you can be sure that your Texinfo file will be formatted with @code{makeinfo}, you have no need for the update node commands. (@xref{Creating an Info File}, for more information about @code{makeinfo}.) However, both @code{makeinfo} and the @code{texinfo-format-@dots{}} commands require that you insert menus in the file. @node Other Updating Commands @subsection Other Updating Commands In addition to the five major updating commands, Texinfo mode possesses several less frequently used updating commands:@refill @table @kbd @item M-x texinfo-insert-node-lines @findex texinfo-insert-node-lines Insert @code{@@node} lines before the @code{@@chapter}, @code{@@section}, and other sectioning commands wherever they are missing throughout a region in a Texinfo file.@refill With an argument (@kbd{C-u} as prefix argument, if interactive), the @code{texinfo-insert-node-lines} command not only inserts @code{@@node} lines but also inserts the chapter or section titles as the names of the corresponding nodes. In addition, it inserts the titles as node names in pre-existing @code{@@node} lines that lack names. Since node names should be more concise than section or chapter titles, you must manually edit node names so inserted.@refill For example, the following marks a whole buffer as a region and inserts @code{@@node} lines and titles throughout:@refill @example C-x h C-u M-x texinfo-insert-node-lines @end example This command inserts titles as node names in @code{@@node} lines; the @code{texinfo-start-menu-description} command (@pxref{Inserting, Inserting Frequently Used Commands}) inserts titles as descriptions in menu entries, a different action. However, in both cases, you need to edit the inserted text. @item M-x texinfo-multiple-files-update @findex texinfo-multiple-files-update @r{(in brief)} Update nodes and menus in a document built from several separate files. With @kbd{C-u} as a prefix argument, create and insert a master menu in the outer file. With a numeric prefix argument, such as @kbd{C-u 2}, first update all the menus and all the `Next', `Previous', and `Up' pointers of all the included files before creating and inserting a master menu in the outer file. The @code{texinfo-multiple-files-update} command is described in the appendix on @code{@@include} files. @xref{texinfo-multiple-files-update}. @item M-x texinfo-indent-menu-description @findex texinfo-indent-menu-description Indent every description in the menu following point to the specified column. You can use this command to give yourself more space for descriptions. With an argument (@kbd{C-u} as prefix argument, if interactive), the @code{texinfo-indent-menu-description} command indents every description in every menu in the region. However, this command does not indent the second and subsequent lines of a multi-line description.@refill @item M-x texinfo-sequential-node-update @findex texinfo-sequential-node-update Insert the names of the nodes immediately following and preceding the current node as the `Next' or `Previous' pointers regardless of those nodes' hierarchical level. This means that the `Next' node of a subsection may well be the next chapter. Sequentially ordered nodes are useful for novels and other documents that you read through sequentially. (However, in Info, the @kbd{g *} command lets you look through the file sequentially, so sequentially ordered nodes are not strictly necessary.) With an argument (prefix argument, if interactive), the @code{texinfo-sequential-node-update} command sequentially updates all the nodes in the region.@refill @end table @node Info Formatting @comment node-name, next, previous, up @section Formatting for Info @cindex Formatting for Info @cindex Running an Info formatter @cindex Info formatting Texinfo mode provides several commands for formatting part or all of a Texinfo file for Info. Often, when you are writing a document, you want to format only part of a file---that is, a region.@refill You can use either the @code{texinfo-format-region} or the @code{makeinfo-region} command to format a region:@refill @table @kbd @findex texinfo-format-region @item C-c C-e C-r @itemx M-x texinfo-format-region @itemx C-c C-m C-r @itemx M-x makeinfo-region Format the current region for Info.@refill @end table You can use either the @code{texinfo-format-buffer} or the @code{makeinfo-buffer} command to format a whole buffer:@refill @table @kbd @findex texinfo-format-buffer @item C-c C-e C-b @itemx M-x texinfo-format-buffer @itemx C-c C-m C-b @itemx M-x makeinfo-buffer Format the current buffer for Info.@refill @end table @need 1000 For example, after writing a Texinfo file, you can type the following: @example C-u C-c C-u m @exdent or C-u M-x texinfo-master-menu @end example @noindent This updates all the nodes and menus. Then type the following to create an Info file: @example C-c C-m C-b @exdent or M-x makeinfo-buffer @end example For @TeX{} or the Info formatting commands to work, the file @emph{must} include a line that has @code{@@setfilename} in its header. @xref{Creating an Info File}, for details about Info formatting.@refill @node Printing @comment node-name, next, previous, up @section Printing @cindex Formatting for printing @cindex Printing a region or buffer @cindex Region formatting and printing @cindex Buffer formatting and printing @cindex Part of file formatting and printing Typesetting and printing a Texinfo file is a multi-step process in which you first create a file for printing (called a DVI file), and then print the file. Optionally, you may also create indices. To do this, you must run the @code{texindex} command after first running the @code{tex} typesetting command; and then you must run the @code{tex} command again. Or else run the @code{texi2dvi} command which automatically creates indices as needed (@pxref{Format with texi2dvi}). Often, when you are writing a document, you want to typeset and print only part of a file to see what it will look like. You can use the @code{texinfo-tex-region} and related commands for this purpose. Use the @code{texinfo-tex-buffer} command to format all of a buffer.@refill @table @kbd @item C-c C-t C-b @itemx M-x texinfo-tex-buffer @findex texinfo-tex-buffer Run @code{texi2dvi} on the buffer. In addition to running @TeX{} on the buffer, this command automatically creates or updates indices as needed.@refill @item C-c C-t C-r @itemx M-x texinfo-tex-region @findex texinfo-tex-region Run @TeX{} on the region.@refill @item C-c C-t C-i @itemx M-x texinfo-texindex Run @code{texindex} to sort the indices of a Texinfo file formatted with @code{texinfo-tex-region}. The @code{texinfo-tex-region} command does not run @code{texindex} automatically; it only runs the @code{tex} typesetting command. You must run the @code{texinfo-tex-region} command a second time after sorting the raw index files with the @code{texindex} command. (Usually, you do not format an index when you format a region, only when you format a buffer. Now that the @code{texi2dvi} command exists, there is little or no need for this command.)@refill @item C-c C-t C-p @itemx M-x texinfo-tex-print @findex texinfo-tex-print Print the file (or the part of the file) previously formatted with @code{texinfo-tex-buffer} or @code{texinfo-tex-region}.@refill @end table For @code{texinfo-tex-region} or @code{texinfo-tex-buffer} to work, the file @emph{must} start with a @samp{\input texinfo} line and must include an @code{@@settitle} line. The file must end with @code{@@bye} on a line by itself. (When you use @code{texinfo-tex-region}, you must surround the @code{@@settitle} line with start-of-header and end-of-header lines.)@refill @xref{Hardcopy}, for a description of the other @TeX{} related commands, such as @code{tex-show-print-queue}.@refill @node Texinfo Mode Summary @comment node-name, next, previous, up @section Texinfo Mode Summary In Texinfo mode, each set of commands has default keybindings that begin with the same keys. All the commands that are custom-created for Texinfo mode begin with @kbd{C-c}. The keys are somewhat mnemonic.@refill @subheading Insert Commands The insert commands are invoked by typing @kbd{C-c} twice and then the first letter of the @@-command to be inserted. (It might make more sense mnemonically to use @kbd{C-c C-i}, for `custom insert', but @kbd{C-c C-c} is quick to type.)@refill @example C-c C-c c @r{Insert} @samp{@@code}. C-c C-c d @r{Insert} @samp{@@dfn}. C-c C-c e @r{Insert} @samp{@@end}. C-c C-c i @r{Insert} @samp{@@item}. C-c C-c n @r{Insert} @samp{@@node}. C-c C-c s @r{Insert} @samp{@@samp}. C-c C-c v @r{Insert} @samp{@@var}. C-c @{ @r{Insert braces.} C-c ] C-c @} @r{Move out of enclosing braces.} @group C-c C-c C-d @r{Insert a node's section title} @r{in the space for the description} @r{in a menu entry line.} @end group @end example @subheading Show Structure The @code{texinfo-show-structure} command is often used within a narrowed region.@refill @example C-c C-s @r{List all the headings.} @end example @subheading The Master Update Command The @code{texinfo-master-menu} command creates a master menu; and can be used to update every node and menu in a file as well.@refill @c Probably should use @tables in this section. @example @group C-c C-u m M-x texinfo-master-menu @r{Create or update a master menu.} @end group @group C-u C-c C-u m @r{With @kbd{C-u} as a prefix argument, first} @r{create or update all nodes and regular} @r{menus, and then create a master menu.} @end group @end example @subheading Update Pointers The update pointer commands are invoked by typing @kbd{C-c C-u} and then either @kbd{C-n} for @code{texinfo-update-node} or @kbd{C-e} for @code{texinfo-every-node-update}.@refill @example C-c C-u C-n @r{Update a node.} C-c C-u C-e @r{Update every node in the buffer.} @end example @subheading Update Menus Invoke the update menu commands by typing @kbd{C-c C-u} and then either @kbd{C-m} for @code{texinfo-make-menu} or @kbd{C-a} for @code{texinfo-all-menus-update}. To update both nodes and menus at the same time, precede @kbd{C-c C-u C-a} with @kbd{C-u}.@refill @example C-c C-u C-m @r{Make or update a menu.} @group C-c C-u C-a @r{Make or update all} @r{menus in a buffer.} @end group @group C-u C-c C-u C-a @r{With @kbd{C-u} as a prefix argument,} @r{first create or update all nodes and} @r{then create or update all menus.} @end group @end example @subheading Format for Info The Info formatting commands that are written in Emacs Lisp are invoked by typing @kbd{C-c C-e} and then either @kbd{C-r} for a region or @kbd{C-b} for the whole buffer.@refill The Info formatting commands that are written in C and based on the @code{makeinfo} program are invoked by typing @kbd{C-c C-m} and then either @kbd{C-r} for a region or @kbd{C-b} for the whole buffer.@refill @need 800 @noindent Use the @code{texinfo-format@dots{}} commands: @example @group C-c C-e C-r @r{Format the region.} C-c C-e C-b @r{Format the buffer.} @end group @end example @need 750 @noindent Use @code{makeinfo}: @example C-c C-m C-r @r{Format the region.} C-c C-m C-b @r{Format the buffer.} C-c C-m C-l @r{Recenter the @code{makeinfo} output buffer.} C-c C-m C-k @r{Kill the @code{makeinfo} formatting job.} @end example @subheading Typeset and Print The @TeX{} typesetting and printing commands are invoked by typing @kbd{C-c C-t} and then another control command: @kbd{C-r} for @code{texinfo-tex-region}, @kbd{C-b} for @code{texinfo-tex-buffer}, and so on.@refill @example C-c C-t C-r @r{Run @TeX{} on the region.} C-c C-t C-b @r{Run} @code{texi2dvi} @r{on the buffer.} C-c C-t C-i @r{Run} @code{texindex}. C-c C-t C-p @r{Print the DVI file.} C-c C-t C-q @r{Show the print queue.} C-c C-t C-d @r{Delete a job from the print queue.} C-c C-t C-k @r{Kill the current @TeX{} formatting job.} C-c C-t C-x @r{Quit a currently stopped @TeX{} formatting job.} C-c C-t C-l @r{Recenter the output buffer.} @end example @subheading Other Updating Commands The remaining updating commands do not have standard keybindings because they are rarely used. @example @group M-x texinfo-insert-node-lines @r{Insert missing @code{@@node} lines in region.} @r{With @kbd{C-u} as a prefix argument,} @r{use section titles as node names.} @end group @group M-x texinfo-multiple-files-update @r{Update a multi-file document.} @r{With @kbd{C-u 2} as a prefix argument,} @r{create or update all nodes and menus} @r{in all included files first.} @end group @group M-x texinfo-indent-menu-description @r{Indent descriptions.} @end group @group M-x texinfo-sequential-node-update @r{Insert node pointers in strict sequence.} @end group @end example @node Beginning a File @chapter Beginning a Texinfo File @cindex Beginning a Texinfo file @cindex Texinfo file beginning @cindex File beginning Certain pieces of information must be provided at the beginning of a Texinfo file, such as the name for the output file(s), the title of the document, and the Top node. A table of contents is also generally produced here. This chapter expands on the minimal complete Texinfo source file previously given (@pxref{Six Parts}). It describes the numerous commands for handling the traditional frontmatter items in Texinfo. @cindex Frontmatter, text in Straight text outside of any command before the Top node should be avoided. Such text is treated differently in the different output formats: visible in @TeX{} and HTML, by default not shown in Info readers, and so on. @menu * Sample Beginning:: A sample beginning for a Texinfo file. * Texinfo File Header:: The first lines. * Document Permissions:: Ensuring your manual is free. * Titlepage & Copyright Page:: Creating the title and copyright pages. * Contents:: How to create a table of contents. * The Top Node:: Creating the `Top' node and master menu. * Global Document Commands:: Affecting formatting throughout. * Software Copying Permissions:: Ensure that you and others continue to have the right to use and share software. @end menu @node Sample Beginning @section Sample Texinfo File Beginning @cindex Example beginning of Texinfo file The following sample shows what is needed. The elements given here are explained in more detail in the following sections. Other commands are often included at the beginning of Texinfo files, but the ones here are the most critical. @xref{GNU Sample Texts}, for the full texts to be used in GNU manuals. @example \input texinfo @@c -*-texinfo-*- @@c %**start of header @@setfilename @var{infoname}.info @@settitle @var{name-of-manual} @var{version} @@c %**end of header @@copying This manual is for @var{program}, version @var{version}. Copyright @@copyright@{@} @var{years} @var{copyright-owner}. @group @@quotation Permission is granted to @dots{} @@end quotation @@end copying @end group @group @@titlepage @@title @var{name-of-manual-when-printed} @@subtitle @var{subtitle-if-any} @@subtitle @var{second-subtitle} @@author @var{author} @end group @group @@c The following two commands @@c start the copyright page. @@page @@vskip 0pt plus 1filll @@insertcopying @end group Published by @dots{} @@end titlepage @@c So the toc is printed at the start. @@contents @@ifnottex @@node Top @@top @var{title} This manual is for @var{program}, version @var{version}. @@end ifnottex @group @@menu * First Chapter:: Getting started @dots{} * Second Chapter:: @dots{} @dots{} * Copying:: Your rights and freedoms. @@end menu @end group @group @@node First Chapter @@chapter First Chapter @@cindex first chapter @@cindex chapter, first @dots{} @end group @end example @node Texinfo File Header @section Texinfo File Header @cindex Header for Texinfo files @cindex Texinfo file header Texinfo files start with at least three lines that provide Info and @TeX{} with necessary information. These are the @code{\input texinfo} line, the @code{@@settitle} line, and the @code{@@setfilename} line. Also, if you want to format just part of the Texinfo file, you must write the @code{@@settitle} and @code{@@setfilename} lines between start-of-header and end-of-header lines. The start- and end-of-header lines are optional, but they do no harm, so you might as well always include them. Any command that affects document formatting as a whole makes sense to include in the header. @code{@@synindex} (@pxref{synindex}), for instance, is another command often included in the header. @xref{GNU Sample Texts}, for complete sample texts. Thus, the beginning of a Texinfo file generally looks like this: @example @group \input texinfo @@c -*-texinfo-*- @@c %**start of header @@setfilename sample.info @@settitle Sample Manual 1.0 @@c %**end of header @end group @end example @menu * First Line:: The first line of a Texinfo file. * Start of Header:: Formatting a region requires this. * setfilename:: Tell Info the name of the Info file. * settitle:: Create a title for the printed work. * End of Header:: Formatting a region requires this. @end menu @node First Line @subsection The First Line of a Texinfo File @cindex First line of a Texinfo file @cindex Beginning line of a Texinfo file @cindex Header of a Texinfo file Every Texinfo file that is to be the top-level input to @TeX{} must begin with a line that looks like this: @example \input texinfo @@c -*-texinfo-*- @end example @noindent This line serves two functions: @enumerate @item When the file is processed by @TeX{}, the @samp{\input texinfo} command tells @TeX{} to load the macros needed for processing a Texinfo file. These are in a file called @file{texinfo.tex}, which should have been installed on your system along with either the @TeX{} or Texinfo software. @TeX{} uses the backslash, @samp{\}, to mark the beginning of a command, exactly as Texinfo uses @samp{@@}. The @file{texinfo.tex} file causes the switch from @samp{\} to @samp{@@}; before the switch occurs, @TeX{} requires @samp{\}, which is why it appears at the beginning of the file. @item When the file is edited in GNU Emacs, the @samp{-*-texinfo-*-} mode specification tells Emacs to use Texinfo mode. @end enumerate @node Start of Header @subsection Start of Header @cindex Start of header line A start-of-header line is a Texinfo comment that looks like this: @example @@c %**start of header @end example Write the start-of-header line on the second line of a Texinfo file. Follow the start-of-header line with @code{@@setfilename} and @code{@@settitle} lines and, optionally, with other commands that globally affect the document formatting, such as @code{@@synindex} or @code{@@footnotestyle}; and then by an end-of-header line (@pxref{End of Header}). The start- and end-of-header lines allow you to format only part of a Texinfo file for Info or printing. @xref{texinfo-format commands}. The odd string of characters, @samp{%**}, is to ensure that no other comment is accidentally taken for a start-of-header line. You can change it if you wish by setting the @code{tex-start-of-header} and/or @code{tex-end-of-header} Emacs variables. @xref{Texinfo Mode Printing}. @node setfilename @subsection @code{@@setfilename}: Set the output file name @findex setfilename @cindex Texinfo requires @code{@@setfilename} In order to serve as the primary input file for either @code{makeinfo} or @TeX{}, a Texinfo file must contain a line that looks like this: @example @@setfilename @var{info-file-name} @end example Write the @code{@@setfilename} command at the beginning of a line and follow it on the same line by the Info file name. Do not write anything else on the line; anything on the line after the command is considered part of the file name, including what would otherwise be a comment. @cindex Ignored before @code{@@setfilename} @cindex @samp{\input} source line ignored The Info formatting commands ignore everything written before the @code{@@setfilename} line, which is why the very first line of the file (the @code{\input} line) does not show up in the output. The @code{@@setfilename} line specifies the name of the output file to be generated. This name must be different from the name of the Texinfo file. There are two conventions for choosing the name: you can either remove the extension (such as @samp{.texi}) entirely from the input file name, or, preferably, replace it with the @samp{.info} extension. @cindex Length of file names @cindex File name collision @cindex Info file name, choosing Although an explicit @samp{.info} extension is preferable, some operating systems cannot handle long file names. You can run into a problem even when the file name you specify is itself short enough. This occurs because the Info formatters split a long Info file into short indirect subfiles, and name them by appending @samp{-1}, @samp{-2}, @dots{}, @samp{-10}, @samp{-11}, and so on, to the original file name. (@xref{Tag and Split Files}.) The subfile name @file{texinfo.info-10}, for example, is too long for old systems with a 14-character limit on filenames; so the Info file name for this document is @file{texinfo} rather than @file{texinfo.info}. When @code{makeinfo} is running on operating systems such as MS-DOS which impose severe limits on file names, it may remove some characters from the original file name to leave enough space for the subfile suffix, thus producing files named @file{texin-10}, @file{gcc.i12}, etc. When producing HTML output, @code{makeinfo} will replace any extension with @samp{html}, or add @samp{.html} if the given name has no extension. @pindex texinfo.cnf The @code{@@setfilename} line produces no output when you typeset a manual with @TeX{}, but it is nevertheless essential: it opens the index, cross-reference, and other auxiliary files used by Texinfo, and also reads @file{texinfo.cnf} if that file is present on your system (@pxref{Preparing for TeX,, Preparing for @TeX{}}). @node settitle @subsection @code{@@settitle}: Set the document title @findex settitle In order to be made into a printed manual, a Texinfo file must contain a line that looks like this: @example @@settitle @var{title} @end example Write the @code{@@settitle} command at the beginning of a line and follow it on the same line by the title. This tells @TeX{} the title to use in a header or footer. Do not write anything else on the line; anything on the line after the command is considered part of the title, including what would otherwise be a comment. The @code{@@settitle} command should precede everything that generates actual output. The best place for it is right after the @code{@@setfilename} command (see the previous section). @cindex HTML tag In the HTML file produced by @command{makeinfo}, @var{title} serves as the document @samp{<title>}. It also becomes the default document description in the @samp{<head>} part (@pxref{documentdescription}). The title in the @code{@@settitle} command does not affect the title as it appears on the title page. Thus, the two do not need not match exactly. A practice we recommend is to include the version or edition number of the manual in the @code{@@settitle} title; on the title page, the version number generally appears as a @code{@@subtitle} so it would be omitted from the @code{@@title}. @xref{titlepage}. Conventionally, when @TeX{} formats a Texinfo file for double-sided output, the title is printed in the left-hand (even-numbered) page headings and the current chapter title is printed in the right-hand (odd-numbered) page headings. (@TeX{} learns the title of each chapter from each @code{@@chapter} command.) By default, no page footer is printed. Even if you are printing in a single-sided style, @TeX{} looks for an @code{@@settitle} command line, in case you include the manual title in the heading. @TeX{} prints page headings only for that text that comes after the @code{@@end titlepage} command in the Texinfo file, or that comes after an @code{@@headings} command that turns on headings. (@xref{headings on off, , The @code{@@headings} Command}, for more information.) You may, if you wish, create your own, customized headings and footings. @xref{Headings}, for a detailed discussion of this. @node End of Header @subsection End of Header @cindex End of header line Follow the header lines with an @w{end-of-header} line, which is a Texinfo comment that looks like this: @example @@c %**end of header @end example @xref{Start of Header}. @node Document Permissions @section Document Permissions @cindex Document Permissions @cindex Copying Permissions The copyright notice and copying permissions for a document need to appear in several places in the various Texinfo output formats. Therefore, Texinfo provides a command (@code{@@copying}) to declare this text once, and another command (@code{@@insertcopying}) to insert the text at appropriate points. @menu * copying:: Declare the document's copying permissions. * insertcopying:: Where to insert the permissions. @end menu @node copying @subsection @code{@@copying}: Declare Copying Permissions @findex copying The @code{@@copying} command should be given very early in the document; the recommended location is right after the header material (@pxref{Texinfo File Header}). It conventionally consists of a sentence or two about what the program is, identification of the documentation itself, the legal copyright line, and the copying permissions. Here is a skeletal example: @example @@copying This manual is for @var{program} (version @var{version}, updated @var{date}), which @dots{} Copyright @@copyright@{@} @var{years} @var{copyright-owner}. @@quotation Permission is granted to @dots{} @@end quotation @@end copying @end example The @code{@@quotation} has no legal significance; it's there to improve readability in some contexts. @xref{GNU Sample Texts}, for the full text to be used in GNU manuals. @xref{GNU Free Documentation License}, for the license itself under which GNU and other free manuals are distributed. You need to include the license as an appendix to your document. The text of @code{@@copying} is output as a comment at the beginning of Info, HTML, and XML output files. It is @emph{not} output implicitly in plain text or @TeX{}; it's up to you to use @code{@@insertcopying} to emit the copying information. See the next section for details. @findex copyright The @code{@@copyright@{@}} command generates a @samp{c} inside a circle in output formats that support this (print and HTML). In the other formats (Info and plain text), it generates @samp{(C)}. The copyright notice itself has the following legally defined sequence: @example Copyright @copyright{} @var{years} @var{copyright-owner}. @end example @cindex Copyright word, always in English The word `Copyright' must always be written in English, even if the document is otherwise written in another language. This is due to international law. @cindex Years, in copyright line The list of years should include all years in which a version was completed (even if it was released in a subsequent year). Ranges are not allowed; each year must be written out individually and in full, separated by commas. @cindex Copyright holder for FSF works @cindex Holder of copyright for FSF works @cindex Owner of copyright for FSF works The copyright owner (or owners) is whoever holds legal copyright on the work. In the case of works assigned to the FSF, the owner is `Free Software Foundation, Inc.'. The copyright `line' may actually be split across multiple lines, both in the source document and in the output. This often happens for documents with a long history, having many different years of publication. If you do use several lines, do not indent any of them (or anything else in the @code{@@copying} block) in the source file. @xref{Copyright Notices,,,maintain,GNU Maintenance Instructions}, for additional information. @node insertcopying @subsection @code{@@insertcopying}: Include Permissions Text @findex insertcopying @cindex Copying text, including @cindex Permissions text, including @cindex Including permissions text The @code{@@insertcopying} command is simply written on a line by itself, like this: @example @@insertcopying @end example This inserts the text previously defined by @code{@@copying}. To meet legal requirements, it must be used on the copyright page in the printed manual (@pxref{Copyright}). The @code{@@copying} command itself causes the permissions text to appear in an Info file @emph{before} the first node. The text is also copied into the beginning of each split Info output file, as is legally necessary. This location implies a human reading the manual using Info does @emph{not} see this text (except when using the advanced Info command @kbd{g *}), but this does not matter for legal purposes, because the text is present. Similarly, the @code{@@copying} text is automatically included at the beginning of each HTML output file, as an HTML comment. Again, this text is not visible (unless the reader views the HTML source). The permissions text defined by @code{@@copying} also appears automatically at the beginning of the XML output file. @node Titlepage & Copyright Page @section Title and Copyright Pages In hard copy output, the manual's name and author are usually printed on a title page. Copyright information is usually printed on the back of the title page. The title and copyright pages appear in the printed manual, but not in the Info file. Because of this, it is possible to use several slightly obscure @TeX{} typesetting commands that cannot be used in an Info file. In addition, this part of the beginning of a Texinfo file contains the text of the copying permissions that appears in the printed manual. @cindex Title page, for plain text @cindex Copyright page, for plain text You may wish to include titlepage-like information for plain text output. Simply place any such leading material between @code{@@ifplaintext} and @code{@@end ifplaintext}; @command{makeinfo} includes this when writing plain text (@samp{--no-headers}), along with an @code{@@insertcopying}. @menu * titlepage:: Create a title for the printed document. * titlefont center sp:: The @code{@@titlefont}, @code{@@center}, and @code{@@sp} commands. * title subtitle author:: The @code{@@title}, @code{@@subtitle}, and @code{@@author} commands. * Copyright:: How to write the copyright notice and include copying permissions. * end titlepage:: Turn on page headings after the title and copyright pages. * headings on off:: An option for turning headings on and off and double or single sided printing. @end menu @node titlepage @subsection @code{@@titlepage} @cindex Title page @findex titlepage Start the material for the title page and following copyright page with @code{@@titlepage} on a line by itself and end it with @code{@@end titlepage} on a line by itself. The @code{@@end titlepage} command starts a new page and turns on page numbering. (@xref{Headings, , Page Headings}, for details about how to generate page headings.) All the material that you want to appear on unnumbered pages should be put between the @code{@@titlepage} and @code{@@end titlepage} commands. You can force the table of contents to appear there with the @code{@@setcontentsaftertitlepage} command (@pxref{Contents}). @findex page@r{, within @code{@@titlepage}} By using the @code{@@page} command you can force a page break within the region delineated by the @code{@@titlepage} and @code{@@end titlepage} commands and thereby create more than one unnumbered page. This is how the copyright page is produced. (The @code{@@titlepage} command might perhaps have been better named the @code{@@titleandadditionalpages} command, but that would have been rather long!) When you write a manual about a computer program, you should write the version of the program to which the manual applies on the title page. If the manual changes more frequently than the program or is independent of it, you should also include an edition number@footnote{We have found that it is helpful to refer to versions of independent manuals as `editions' and versions of programs as `versions'; otherwise, we find we are liable to confuse each other in conversation by referring to both the documentation and the software with the same words.} for the manual. This helps readers keep track of which manual is for which version of the program. (The `Top' node should also contain this information; see @ref{The Top Node}.) Texinfo provides two main methods for creating a title page. One method uses the @code{@@titlefont}, @code{@@sp}, and @code{@@center} commands to generate a title page in which the words on the page are centered. The second method uses the @code{@@title}, @code{@@subtitle}, and @code{@@author} commands to create a title page with black rules under the title and author lines and the subtitle text set flush to the right hand side of the page. With this method, you do not specify any of the actual formatting of the title page. You specify the text you want, and Texinfo does the formatting. You may use either method, or you may combine them; see the examples in the sections below. @findex shorttitlepage @cindex Bastard title page @cindex Title page, bastard For extremely simple documents, and for the bastard title page in traditional book frontmatter, Texinfo also provides a command @code{@@shorttitlepage} which takes the rest of the line as the title. The argument is typeset on a page by itself and followed by a blank page. @node titlefont center sp @subsection @code{@@titlefont}, @code{@@center}, and @code{@@sp} @findex titlefont @findex center @findex sp @r{(titlepage line spacing)} You can use the @code{@@titlefont}, @code{@@sp}, and @code{@@center} commands to create a title page for a printed document. (This is the first of the two methods for creating a title page in Texinfo.) Use the @code{@@titlefont} command to select a large font suitable for the title itself. You can use @code{@@titlefont} more than once if you have an especially long title. For HTML output, each @code{@@titlefont} command produces an @code{<h1>} heading, but the HTML document @code{<title>} is not affected. For that, you must put an @code{@@settitle} command before the @code{@@titlefont} command (@pxref{settitle}). @need 700 For example: @example @@titlefont@{Texinfo@} @end example Use the @code{@@center} command at the beginning of a line to center the remaining text on that line. Thus, @example @@center @@titlefont@{Texinfo@} @end example @noindent centers the title, which in this example is ``Texinfo'' printed in the title font. Use the @code{@@sp} command to insert vertical space. For example: @example @@sp 2 @end example @noindent This inserts two blank lines on the printed page. (@xref{sp, , @code{@@sp}}, for more information about the @code{@@sp} command.) A template for this method looks like this: @example @group @@titlepage @@sp 10 @@center @@titlefont@{@var{name-of-manual-when-printed}@} @@sp 2 @@center @var{subtitle-if-any} @@sp 2 @@center @var{author} @dots{} @@end titlepage @end group @end example The spacing of the example fits an 8.5 by 11 inch manual. You can in fact use these commands anywhere, not just on a title page, but since they are not logical markup commands, we don't recommend them. @node title subtitle author @subsection @code{@@title}, @code{@@subtitle}, and @code{@@author} @findex title @findex subtitle @findex author You can use the @code{@@title}, @code{@@subtitle}, and @code{@@author} commands to create a title page in which the vertical and horizontal spacing is done for you automatically. This contrasts with the method described in the previous section, in which the @code{@@sp} command is needed to adjust vertical spacing. Write the @code{@@title}, @code{@@subtitle}, or @code{@@author} commands at the beginning of a line followed by the title, subtitle, or author. These commands are only effective in @TeX{} output; it's an error to use them anywhere except within @code{@@titlepage}. The @code{@@title} command produces a line in which the title is set flush to the left-hand side of the page in a larger than normal font. The title is underlined with a black rule. Only a single line is allowed; the @code{@@*} command may not be used to break the title into two lines. To handle very long titles, you may find it profitable to use both @code{@@title} and @code{@@titlefont}; see the final example in this section. The @code{@@subtitle} command sets subtitles in a normal-sized font flush to the right-hand side of the page. The @code{@@author} command sets the names of the author or authors in a middle-sized font flush to the left-hand side of the page on a line near the bottom of the title page. The names are underlined with a black rule that is thinner than the rule that underlines the title. (The black rule only occurs if the @code{@@author} command line is followed by an @code{@@page} command line.) There are two ways to use the @code{@@author} command: you can write the name or names on the remaining part of the line that starts with an @code{@@author} command: @example @@author by Jane Smith and John Doe @end example @noindent or you can write the names one above each other by using two (or more) @code{@@author} commands: @example @group @@author Jane Smith @@author John Doe @end group @end example @noindent (Only the bottom name is underlined with a black rule.) @need 950 A template for this meth