diff options
Diffstat (limited to 'contrib/texinfo/doc/texinfo.txi')
| -rw-r--r-- | contrib/texinfo/doc/texinfo.txi | 2171 |
1 files changed, 1325 insertions, 846 deletions
diff --git a/contrib/texinfo/doc/texinfo.txi b/contrib/texinfo/doc/texinfo.txi index 7e0bbd0..fed4c4c 100644 --- a/contrib/texinfo/doc/texinfo.txi +++ b/contrib/texinfo/doc/texinfo.txi @@ -1,5 +1,5 @@ \input texinfo.tex @c -*-texinfo-*- -@c $Id: texinfo.txi,v 1.162 1999/09/28 19:38:01 karl Exp $ +@c $Id: texinfo.txi,v 1.192 2002/03/04 14:52:52 karl Exp $ @c %**start of header @c All text is ignored before the setfilename. @@ -18,7 +18,7 @@ @footnotestyle separate @paragraphindent 2 -@finalout +@c finalout @comment %**end of header @@ -28,7 +28,7 @@ * install-info: (texinfo)Invoking install-info. Update info/dir entries. * texi2dvi: (texinfo)Format with texi2dvi. Print Texinfo documents. * texindex: (texinfo)Format with tex/texindex. Sort Texinfo index files. -* makeinfo: (texinfo)makeinfo Preferred. Translate Texinfo source. +* 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 @@ -50,40 +50,24 @@ @ifinfo This file documents Texinfo, a documentation system that can produce -both online information and a printed manual from a single source file. +both online information and a printed manual from a single source. This +edition is for Texinfo version @value{VERSION}, @value{UPDATED}. -Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98, 99 +Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98, 99, 2000, 01, 02 Free Software Foundation, Inc. -This edition is for Texinfo version @value{VERSION}, @value{UPDATED}. - -Permission is granted to make and distribute verbatim copies of -this manual provided the copyright notice and this permission notice -are preserved on all copies. - -@ignore -Permission is granted to process this file through TeX and print the -results, provided the printed document carries copying permission -notice identical to this one except for the removal of this paragraph -(this paragraph not being relevant to the printed manual). - -@end ignore -Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided that the entire -resulting derived work is distributed under the terms of a permission -notice identical to this one. - -Permission is granted to copy and distribute translations of this manual -into another language, under the above conditions for modified versions, -except that this permission notice may be stated in a translation approved -by the Free Software Foundation. +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.1 or +any later version published by the Free Software Foundation; with the +Invariant Section being ``History'', with no Front-Cover Texts, and with +no Back-Cover Texts. A copy of the license is included in the section +entitled ``GNU Free Documentation License''. @end ifinfo @shorttitlepage Texinfo @titlepage -@c use the new format for titles @title Texinfo @subtitle The GNU Documentation Format @subtitle for Texinfo version @value{VERSION}, @value{UPDATED} @@ -96,7 +80,7 @@ by the Free Software Foundation. @page @vskip 0pt plus 1filll -Copyright @copyright{} 1988, 90, 91, 92, 93, 95, 96, 97, 98, 99 +Copyright @copyright{} 1988, 90, 91, 92, 93, 95, 96, 97, 98, 99, 2000, 01, 02 Free Software Foundation, Inc. This manual is for Texinfo version @value{VERSION}, @value{UPDATED}. @@ -110,21 +94,15 @@ ISBN 1-882114-67-1 @c for version 4.0, September 1999. @c ISBN 1-882114-63-9 is for edition 2.20 of 28 February 1995 @c ISBN 1-882114-64-7 is for edition 2.24 of November 1996. -Permission is granted to make and distribute verbatim copies of -this manual provided the copyright notice and this permission notice -are preserved on all copies. +Cover art by Etienne Suvasa. -Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided that the entire -resulting derived work is distributed under the terms of a permission -notice identical to this one. +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.1 or +any later version published by the Free Software Foundation; with the +Invariant Section being ``History'', with no Front-Cover Texts, and with +no Back-Cover Texts. A copy of the license is included in the section +entitled ``GNU Free Documentation License''. -Permission is granted to copy and distribute translations of this manual -into another language, under the above conditions for modified versions, -except that this permission notice may be stated in a translation approved -by the Free Software Foundation. -@sp 2 -Cover art by Etienne Suvasa. @end titlepage @summarycontents @@ -134,8 +112,8 @@ Cover art by Etienne Suvasa. @node Top @top Texinfo -Texinfo is a documentation system that uses a single source file to -produce both online information and printed output. +Texinfo is a documentation system that uses a single source to produce +both online information and printed output. The first part of this master menu lists the major nodes in this Info document, including the @@-command and concept indices. The rest of @@ -174,19 +152,17 @@ This is Edition @value{VERSION} of the Texinfo manual, updated @value{UPDATED}. * Command List:: All the Texinfo @@-commands. * Tips:: Hints on how to write a Texinfo document. * Sample Texinfo File:: A sample Texinfo file to look at. -* Sample Permissions:: Tell readers they have the right to copy - and distribute. * Include Files:: How to incorporate other Texinfo files. * Headings:: How to write page headings and footings. * Catching Mistakes:: How to find formatting mistakes. * Refilling Paragraphs:: All about paragraph refilling. * Command Syntax:: A description of @@-Command syntax. * Obtaining TeX:: How to Obtain @TeX{}. +* Documentation Copying:: The GNU Free Documentation License. * Command and Variable Index:: A menu containing commands and variables. * Concept Index:: A menu covering many topics. @detailmenu - --- The Detailed Node Listing --- Overview of Texinfo @@ -201,7 +177,7 @@ Overview of Texinfo * Minimum:: What a Texinfo file must have. * Six Parts:: Usually, a Texinfo file has six parts. * Short Sample:: A short sample Texinfo file. -* Acknowledgements and History:: Contributors and genesis. +* History:: Acknowledgements, contributors and genesis. Using Texinfo Mode @@ -241,6 +217,7 @@ The Texinfo File Header * 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. +* documentdescription:: Document summary for the HTML output. * setchapternewpage:: Start chapters on right-hand pages. * paragraphindent:: Specify paragraph indentation. * exampleindent:: Specify environment indentation. @@ -346,7 +323,8 @@ Indicating Definitions, Commands, etc. * code:: Indicating program code. * kbd:: Showing keyboard input. * key:: Specifying keys. -* samp:: Showing a literal sequence of characters. +* samp:: A literal sequence of characters. +* verb:: A verbatim sequence of characters. * var:: Indicating metasyntactic variables. * env:: Indicating environment variables. * file:: Indicating file names. @@ -366,19 +344,19 @@ Emphasizing Text Quotations and Examples -* Block Enclosing Commands:: Use different constructs for - different purposes. -* quotation:: How to write a quotation. -* example:: How to write an example in a fixed-width font. -* noindent:: How to prevent paragraph indentation. -* lisp:: How to illustrate Lisp code. +* 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:: Forms for @code{@@smallbook}. -* display:: How to write an example in the current font. -* format:: How to write an example that does not narrow - the margins. -* exdent:: How to undo the indentation of a line. -* flushleft & flushright:: How to push text flushleft or flushright. -* cartouche:: How to draw cartouches around examples. +* 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. +* cartouche:: Drawing rounded rectangles around examples. Lists and Tables @@ -444,7 +422,7 @@ Inserting Space * Multiple Spaces:: Inserting multiple spaces. * dmn:: How to format a dimension. -Inserting Ellipsis, Dots, and Bullets +Inserting Ellipsis and Bullets * dots:: How to insert dots @dots{} * bullet:: How to insert a bullet. @@ -482,7 +460,7 @@ Making and Preventing Breaks * Break Commands:: Cause and prevent splits. * Line Breaks:: How to force a single line to use two lines. -* - and hyphenation:: How to tell TeX about hyphenation points. +* - and hyphenation:: How to tell @TeX{} about hyphenation points. * w:: How to prevent unwanted line breaks. * sp:: How to insert blank lines. * page:: How to force the start of a new page. @@ -519,8 +497,8 @@ Conditionally Visible Text @code{@@set}, @code{@@clear}, and @code{@@value} -* ifset ifclear:: Format a region if a flag is set. * 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 @@ -549,7 +527,7 @@ Formatting and Printing Hardcopy * 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 European A4 paper. +* 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. @@ -558,7 +536,7 @@ Formatting and Printing Hardcopy Creating and Installing Info Files * Creating an Info File:: -* Install an Info File:: +* Installing an Info File:: Creating an Info File @@ -578,19 +556,13 @@ Creating an Info File Installing an Info File * Directory File:: The top level menu for all Info files. -* New Info File:: Listing a new info file. +* 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. -Sample Permissions - -* Inserting Permissions:: How to put permissions in your document. -* ifinfo Permissions:: Sample @samp{ifinfo} copying permissions. -* Titlepage Permissions:: Sample Titlepage copying permissions. - Include Files * Using Include Files:: How to use the @code{@@include} command. @@ -624,6 +596,7 @@ Finding Badly Referenced Nodes * Unsplit:: How to create an unsplit file. * Tagifying:: How to tagify a file. * Splitting:: How to split a file manually. + @end detailmenu @end menu @@ -642,38 +615,36 @@ when it is bad, it is better than nothing. @cindex Conditions for copying Texinfo The programs currently being distributed that relate to Texinfo include -portions of GNU Emacs, plus other separate programs (including -@code{makeinfo}, @code{info}, @code{texindex}, and @file{texinfo.tex}). +@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.@refill +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 +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.@refill +you can do these things. - To make sure that everyone has such rights, we have to forbid you to +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.@refill +can get the source code. And you must tell them their rights. - Also, for our own protection, we must make certain that everyone finds +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.@refill +reputation. -The precise conditions of the licenses for the programs currently -being distributed that relate to Texinfo are found in the General Public +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. @@ -707,7 +678,7 @@ that one document. * Minimum:: What a Texinfo file must have. * Six Parts:: Usually, a Texinfo file has six parts. * Short Sample:: A short sample Texinfo file. -* Acknowledgements and History:: Contributors and genesis. +* History:: Acknowledgements, contributors and genesis. @end menu @@ -717,8 +688,8 @@ that one document. @cindex Bugs, reporting @cindex Suggestions for Texinfo, making @cindex Reporting bugs -We welcome bug reports or suggestions for the Texinfo system, both -programs and documentation. Please email them to +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. @@ -743,11 +714,11 @@ Patches are most welcome; if possible, please make them with Merging Files}) and include @file{ChangeLog} entries (@pxref{Change Log,,, emacs, The GNU Emacs Manual}). -When sending email, please do not encode or split the messages in any -way if possible; it's much easier to deal with one plain text message, -however large, than many small ones. -@uref{ftp://ftp.gnu.org/gnu/sharutils/, GNU shar} is a convenient way of -packaging multiple and/or binary files for email. +When sending patches, if possible please do not encode or split them in +any way; it's much easier to deal with one plain text message, however +large, than many small ones. @uref{ftp://ftp.gnu.org/gnu/sharutils/, +GNU shar} is a convenient way of packaging multiple and/or binary files +for email. @node Using Texinfo @@ -762,8 +733,8 @@ features of a book, including chapters, sections, cross references, and indices. From the same Texinfo source file, you can create a menu-driven, online Info file with nodes, menus, cross references, and indices. You can also create from that same source file an HTML output -file suitable for use with a web browser. @cite{The GNU Emacs Manual} -is a good example of a Texinfo file, as is this manual. +file suitable for use with a web browser, or an XML file. @cite{The GNU +Emacs Manual} is a good example of a Texinfo file, as is this manual. To make a printed document, you process a Texinfo source file with the @TeX{} typesetting program (but the Texinfo language is very different @@ -773,15 +744,20 @@ that you can typeset and print as a book or report (@pxref{Hardcopy}). @pindex makeinfo To output an Info file, process your Texinfo source with the @code{makeinfo} utility or Emacs's @code{texinfo-format-buffer} command. -You can install the result in your Info tree (@pxref{Install an Info +You can install the result in your Info tree (@pxref{Installing an Info File}). -To output an HTML file, process your Texinfo source with @code{makeinfo} -using the @samp{--html} option. You can (for example) install the -result on your web site. +To output an HTML file, run @code{makeinfo --html} on your Texinfo +source. You can (for example) install the result on your web site. + +@cindex Docbook, converting to Texinfo +@cindex Conversion, from Docbook to Texinfo +To output an XML file, run @code{makeinfo --xml} on your Texinfo source. +To output DocBook, run @code{makeinfo --docbook}. If you want to +convert from Docbook @emph{to} Texinfo, please see +@uref{http://docbook2X.sourceforge.net/}. @cindex Output formats, supporting more -@cindex Docbook output format @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 @@ -831,7 +807,7 @@ output formats. You might as well just write the man page directly. If you wish to support man pages, the program @command{help2man} may 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 Texinfo programs themselves. It is free software written +pages for the Texinfo programs themselves. It is GNU software written by Brendan O'Dea, available from @uref{http://www.ozemail.com.au/~bod/help2man.tar.gz}. @@ -975,12 +951,12 @@ document.) @file{texinfo.tex} contains the specifications for printing a document. You can get the latest version of @file{texinfo.tex} from @uref{ftp://ftp.gnu.org/gnu/texinfo.tex}. -Most often, documents are 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 European A4 size paper -(@code{@@afourpaper}). (@xref{smallbook, , Printing ``Small'' Books}. -Also, see @ref{A4 Paper, ,Printing on A4 Paper}.)@refill +Most often, documents are 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 @@ -1007,7 +983,6 @@ To get a copy of @TeX{}, see @node Formatting Commands, Conventions, Printed Books, Overview -@comment node-name, next, previous, up @section @@-commands @cindex @@-commands @cindex Formatting commands @@ -1091,8 +1066,8 @@ make it easier to write and read Texinfo files than if all commands followed exactly the same syntax. (For details about @@-command syntax, see @ref{Command Syntax, , @@-Command Syntax}.)@refill + @node Conventions, Comments, Formatting Commands, Overview -@comment node-name, next, previous, up @section General Syntactic Conventions @cindex General syntactic conventions @cindex Syntactic conventions @@ -1157,24 +1132,25 @@ Similarly for @code{@@ifhtml @dots{} @@end ifhtml}, @cindex Tabs; don't use! @quotation -@strong{Caution:} Do not use tabs in a Texinfo file! @TeX{} uses -variable-width fonts, which means that it cannot predefine a tab to work -in all circumstances. Consequently, @TeX{} treats tabs like single -spaces, and that is not what they look like. Furthermore, -@code{makeinfo} does nothing special with tabs, and thus a tab character -in your input file may appear differently in the output. +@strong{Caution:} Do not use tabs 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. Furthermore, @code{makeinfo} does nothing special +with tabs, and thus a tab character in your input file may appear +differently in the output, for example, in an indented example. @noindent To avoid this problem, Texinfo mode causes GNU Emacs to insert multiple -spaces when you press the @key{TAB} key.@refill +spaces when you press the @key{TAB} key. @noindent Also, you can run @code{untabify} in Emacs to convert tabs in a region -to multiple spaces.@refill +to multiple spaces. @end quotation + @node Comments, Minimum, Conventions, Overview -@comment node-name, next, previous, up @section Comments You can write comments in a Texinfo file that will not appear in @@ -1199,10 +1175,8 @@ the Info file or the printed manual by using the @code{@@ignore} and 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. Often, @code{@@ignore} and @code{@@end ignore} is used -to enclose a part of the copying permissions that applies to the -Texinfo source file of a document, but not to the Info or printed -version of the document.@refill +comments. + @cindex Ignored text @cindex Unprocessed text @findex ignore @@ -1210,15 +1184,15 @@ version of the document.@refill @ignore 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 +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 will still get error messages if you have invalid Texinfo markup within ignored text. @end ignore + @node Minimum, Six Parts, Comments, Overview -@comment node-name, next, previous, up @section What a Texinfo File Must Have @cindex Minimal Texinfo file (requirements) @cindex Must have in Texinfo file @@ -1258,7 +1232,8 @@ The @samp{\input texinfo} line tells @TeX{} to use the backslash, @samp{\}; this is correct for @TeX{}.) The @samp{@@setfilename} line provides a name for the Info file and tells @TeX{} to open auxiliary files. The @samp{@@settitle} line specifies a -title for the page headers (or footers) of the printed manual.@refill +title for the page headers (or footers) of the printed manual, and the +default document description title for the @samp{<head>} in HTML format. 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.@refill @@ -1374,7 +1349,7 @@ appear in the printed document. @@ifinfo This is a short example of a complete Texinfo file. -Copyright @@copyright@{@} 1990 Free Software Foundation, Inc. +Copyright @@copyright@{@} 2002 Free Software Foundation, Inc. @@end ifinfo @end group @end example @@ -1386,17 +1361,17 @@ The titlepage segment does not appear in the Info file. @example @group +@@contents @@titlepage @@sp 10 -@@comment The title is printed in a large font. -@@center @@titlefont@{Sample Title@} +@@title Sample Title @end group @group @@c The following two commands start the copyright page. @@page @@vskip 0pt plus 1filll -Copyright @@copyright@{@} 1990 Free Software Foundation, Inc. +Copyright @@copyright@{@} 2002 Free Software Foundation, Inc. @@end titlepage @end group @end example @@ -1406,12 +1381,13 @@ Copyright @@copyright@{@} 1990 Free Software Foundation, Inc. @noindent The `Top' node contains the master menu for the Info file. Since a printed manual uses a table of contents rather than -a menu, the master menu appears only in the Info file. +a menu, the master menu appears only in online output. @example @group -@@node Top, First Chapter, , (dir) -@@comment node-name, next, previous, up +@@ifnottex +@@node Top +@@end ifnottex @end group @end example @@ -1434,10 +1410,9 @@ chapter containing an enumerated list.@refill @example @group -@@node First Chapter, Concept Index, Top, Top -@@comment node-name, next, previous, up +@@node First Chapter @@chapter First Chapter -@@cindex Sample index entry +@@cindex Chapter, first @end group @group @@ -1458,10 +1433,9 @@ This is the second item. @end group @group -The @@code@{makeinfo@} and @@code@{texinfo-format-buffer@} -commands transform a Texinfo file such as this into -an Info file; and @@TeX@{@} typesets it for a printed -manual. +The @@code@{makeinfo@} command transforms a Texinfo file +such as this into an Info file or other output; +@@TeX@ typesets it for a printed manual. @end group @end example @@ -1475,14 +1449,13 @@ document.@refill @example @group -@@node Concept Index, , First Chapter, Top +@@node Concept Index @@unnumbered Concept Index @end group @group @@printindex cp -@@contents @@bye @end group @end example @@ -1513,8 +1486,8 @@ manual. @end quotation -@node Acknowledgements and History -@section Acknowledgements and History +@node History +@section History @cindex Stallman, Richard M. @cindex Chassell, Robert J. @@ -1892,10 +1865,10 @@ about the page commands.@refill 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.@refill +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 @@ -2520,8 +2493,7 @@ M-x texinfo-sequential-node-update @end group @end example -@node Beginning a File, Ending a File, Texinfo Mode, Top -@comment node-name, next, previous, up +@node Beginning a File @chapter Beginning a Texinfo File @cindex Beginning a Texinfo file @cindex Texinfo file beginning @@ -2581,8 +2553,8 @@ document (in contrast to the copying permissions for a program) are in parts that appear only in the Info file or only in the printed manual, this information must be given twice.@refill -@node Sample Beginning, Header, Four Parts, Beginning a File -@comment node-name, next, previous, up + +@node Sample Beginning @section Sample Texinfo File Beginning The following sample shows what is needed.@refill @@ -2631,14 +2603,15 @@ Published by @dots{} Permission is granted to @dots{} @@end titlepage -@@node Top, Overview, , (dir) +@@ifnottex +@@node Top +@@top @var{title} -@@ifinfo This document describes @dots{} This document applies to version @dots{} of the program named @dots{} -@@end ifinfo +@@end ifnottex @group @@menu @@ -2651,26 +2624,24 @@ of the program named @dots{} @end group @group -@@node First Chapter, Second Chapter, top, top -@@comment node-name, next, previous, up +@@node First Chapter @@chapter First Chapter @@cindex Index entry for First Chapter @end group @end example -@node Header, Info Summary and Permissions, Sample Beginning, Beginning a File -@comment node-name, next, previous, up + +@node Header @section The 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. If you want to run @TeX{} on just a part -of the Texinfo File, you must write the @code{@@settitle} -and @code{@@setfilename} lines between start-of-header and end-of-header -lines.@refill +@TeX{} with necessary information. These are the @code{\input texinfo} +line, the @code{@@settitle} line, and the @code{@@setfilename} line. If +you want to run @TeX{} on just a part of the Texinfo file, you must +write the @code{@@settitle} and @code{@@setfilename} lines between +start-of-header and end-of-header lines. Thus, the beginning of a Texinfo file looks like this: @@ -2700,6 +2671,7 @@ or else like this: * 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. +* documentdescription:: Document summary for the HTML output. * setchapternewpage:: Start chapters on right-hand pages. * paragraphindent:: Specify paragraph indentation. * exampleindent:: Specify environment indentation. @@ -2739,8 +2711,8 @@ When the file is edited in GNU Emacs, the @samp{-*-texinfo-*-} mode specification tells Emacs to use Texinfo mode.@refill @end enumerate -@node Start of Header, setfilename, First Line, Header -@comment node-name, next, previous, up + +@node Start of Header @subsection Start of Header @cindex Start of header line @@ -2816,18 +2788,21 @@ also reads @file{texinfo.cnf} if that file is present on your system (@pxref{Preparing for TeX,, Preparing for @TeX{}}). -@node settitle, setchapternewpage, setfilename, Header -@comment node-name, next, previous, up -@subsection @code{@@settitle} +@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:@refill +a line that looks like this: @example @@settitle @var{title} @end example +In the HTML file produced by @command{makeinfo}, @var{title} serves as +the default document description in the @samp{<head>} part; see +@ref{documentdescription}, for how to change that. + 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; @@ -2866,8 +2841,40 @@ footings. @xref{Headings, , Page Headings}, for a detailed discussion of this process.@refill +@node documentdescription +@subsection @code{@@documentdescription}: Summary text +@cindex Document description +@cindex Description of document +@cindex Summary of document +@cindex <meta> HTML tag, and document description + +When producing HTML output for a document, @command{makeinfo} writes a +@samp{<meta>} element in the @samp{<head>} to give some idea of the +content of the document. By default, this @dfn{description} is the title +of the document, taken from the @code{@@settitle} command +(@pxref{settitle}). To change this, use the @code{@@documentdescription} +environment, as in: + +@example +@@documentdescription +descriptive text +@@end documendescription +@end example + +@noindent +This will produce the following output in the @samp{<head>} of the HTML: + +@example +<meta name=description content="descriptive text"> +@end example + +@code{@@documentdescription} must be specified before the first node of +the document. + + +@findex documentdescription @node setchapternewpage -@subsection @code{@@setchapternewpage} +@subsection @code{@@setchapternewpage}: @cindex Starting chapters @cindex Pages, starting odd @findex setchapternewpage @@ -2877,61 +2884,59 @@ the paper, chapters start on right-hand pages, and right-hand pages have odd numbers. But in short reports, text often is printed only on one side of the paper. Also in short reports, chapters sometimes do not start on new pages, but are printed on the same page as the end of the -preceding chapter, after a small amount of vertical whitespace.@refill +preceding chapter, after a small amount of vertical whitespace. You can use the @code{@@setchapternewpage} command with various arguments to specify how @TeX{} should start chapters and whether it should format headers for printing on one or both sides of the paper -(single-sided or double-sided printing).@refill +(single-sided or double-sided printing). Write the @code{@@setchapternewpage} command at the beginning of a -line followed by its argument.@refill +line followed by its argument. For example, you would write the following to cause each chapter to -start on a fresh odd-numbered page:@refill +start on a fresh odd-numbered page: @example @@setchapternewpage odd @end example You can specify one of three alternatives with the -@code{@@setchapternewpage} command:@refill +@code{@@setchapternewpage} command: @table @asis @item @code{@@setchapternewpage off} Cause @TeX{} to typeset a new chapter on the same page as the last chapter, after skipping some vertical whitespace. Also, cause @TeX{} to -format page headers for single-sided printing. (You can override the -headers format with the @code{@@headings double} command; see -@ref{headings on off, , The @code{@@headings} Command}.)@refill +format page headers for single-sided printing. @item @code{@@setchapternewpage on} Cause @TeX{} to start new chapters on new pages and to format page -headers for single-sided printing. This is the form most often -used for short reports or personal printing. - -This alternative is the default.@refill +headers for single-sided printing. This is the form most often used for +short reports or personal printing. This is the default. @item @code{@@setchapternewpage odd} Cause @TeX{} to start new chapters on new, odd-numbered pages (right-handed pages) and to typeset for double-sided printing. This is -the form most often used for books and manuals.@refill +the form most often used for books and manuals. @end table -Texinfo does not have an @code{@@setchapternewpage even} command.@refill +Texinfo does not have an @code{@@setchapternewpage even} command, +because there is no printing tradition of starting chapters or books on +an even-numbered page. -You can countermand or modify the effect on headers of an -@code{@@setchapternewpage} command with an @code{@@headings} command. -@xref{headings on off, , The @code{@@headings} Command}.@refill +If you don't like the default headers that @code{@@setchapternewpage} +sets, you can explicit control them with the @code{@@headings} command. +@xref{headings on off, , The @code{@@headings} Command}. At the beginning of a manual or book, pages are not numbered---for -example, the title and copyright pages of a book are not numbered. -By convention, table of contents pages are numbered with roman -numerals and not in sequence with the rest of the document.@refill +example, the title and copyright pages of a book are not numbered. By +convention, table of contents and frontmatter pages are numbered with +roman numerals and not in sequence with the rest of the document. Since an Info file does not have pages, the @code{@@setchapternewpage} -command has no effect on it.@refill +command has no effect on it. We recommend not including any @code{@@setchapternewpage} command in your manual sources at all, since the desired output is not intrinsic to @@ -3066,23 +3071,23 @@ section that appears only in the Info file. This section usually contains a brief description of the contents of the Info file, a copyright notice, and copying permissions.@refill -The copyright notice should read:@refill +The copyright notice should read: @example Copyright @var{year} @var{copyright-owner} @end example @noindent -and be put on a line by itself.@refill +and be put on a line by itself. -Standard text for the copyright permissions is contained in an appendix -to this manual; see @ref{ifinfo Permissions, , @samp{ifinfo} Copying -Permissions}, for the complete text.@refill +Standard text for the copyright permissions of free manuals is contained +in an appendix to this manual (@pxref{Documentation Copying, , GNU Free +Documentation License}). The permissions text appears in an Info file @emph{before} the first node. This mean that a reader does @emph{not} see this text when -reading the file using Info, except when using the advanced Info command -@kbd{g *}. +reading the file using Info (except when using the advanced Info command +@kbd{g *}). @node Titlepage & Copyright Page @@ -3105,8 +3110,8 @@ output. Simply place any such leading material between @code{@@ifinfo} and @code{@@end ifinfo}; @command{makeinfo} includes this in its plain text output. It will not show up in the Info readers. -@xref{Titlepage Permissions, , Titlepage Copying Permissions}, for the -standard text for the copyright permissions.@refill +@xref{Documentation Copying, , GNU Free Documentation License}, for the +standard text for the copyright permissions. @menu * titlepage:: Create a title for the printed document. @@ -3329,7 +3334,7 @@ may be useful if you have a very long title. Here is a real-life example: @@titlefont@{GNU Software@} @@sp 1 @@title for MS-Windows and MS-DOS -@@subtitle Edition @@value@{edition@} for Release @@value@{cd-edition@} +@@subtitle Edition @@value@{e@} for Release @@value@{cde@} @@author by Daniel Hagerty, Melissa Weisshaus @@author and Eli Zaretskii @end group @@ -3394,7 +3399,8 @@ Permissions must be given here as well as in the summary segment within header since this text appears only in the printed manual and the @samp{ifinfo} text appears only in the Info file. -@xref{Sample Permissions}, for the standard text.@refill +@xref{Documentation Copying,,GNU Free Documentation License}, for the +standard text. @node end titlepage @@ -3659,7 +3665,7 @@ Using Texinfo Mode @end group @end example -@node Software Copying Permissions, , The Top Node, Beginning a File +@node Software Copying Permissions @comment node-name, next, previous, up @section Software Copying Permissions @cindex Software copying permissions @@ -3674,9 +3680,8 @@ for the software that is documented, this section usually follows the GNU software. It ensures that you and others will continue to have a right to use and share the software.@refill -The copying and distribution information and the disclaimer are -followed by an introduction or else by the first chapter of the -manual.@refill +The copying and distribution information and the disclaimer are followed +by an introduction or else by the first chapter of the manual.@refill @cindex Introduction, as part of file Although an introduction is not a required part of a Texinfo file, it @@ -3848,7 +3853,15 @@ sectioning command such as @code{@@unnumbered} before them. Since an Info file uses menus instead of tables of contents, the Info formatting commands ignore the contents commands. But the contents are -included in plain text output (generated by @code{makeinfo --no-headers}). +included in plain text output (generated by @code{makeinfo +--no-headers}), unless @code{makeinfo} is writing its output to standard +output. + +When @code{makeinfo} writes a short table of contents while producing +html output, the links in the short table of contents point to +corresponding entries in the full table of contents rather than the text +of the document. The links in the full table of contents point to the +main text of the document. The contents commands can be placed either at the very end of the file, after any indices (see the previous section) and just before the @@ -3858,8 +3871,7 @@ the former is that then the contents output is always up to date, because it reflects the processing just done. The advantage to the latter is that the contents are printed in the proper place, thus you do not need to rearrange the DVI file with @command{dviselect} or shuffle -paper. However, contents commands at the beginning of the document are -ignored when outputting to standard output. +paper. @findex setcontentsaftertitlepage @findex setshortcontentsaftertitlepage @@ -4033,25 +4045,25 @@ start new pages in the printed manual; the @code{@@heading} commands do not.@refill @end itemize -Here are the four groups of chapter structuring commands:@refill +Here are the four groups of chapter structuring commands: -@multitable @columnfractions .19 .30 .29 .22 +@tex +{\globaldefs = 1 \smallfonts} +@end tex -@item @tab @tab @tab No new page -@item Numbered @tab Unnumbered @tab Lettered and numbered - @tab Unnumbered -@item In contents @tab In contents @tab In contents @tab Not in contents -@item @tab @code{@@top} @tab - @tab @code{@@majorheading} -@item @code{@@chapter} @tab @code{@@unnumbered} @tab @code{@@appendix} - @tab @code{@@chapheading} -@item @code{@@section} @tab @code{@@unnumberedsec} @tab @code{@@appendixsec} - @tab @code{@@heading} -@item @code{@@subsection} @tab @code{@@unnumberedsubsec} @tab @code{@@appendixsubsec} - @tab @code{@@subheading} -@item @code{@@subsubsection} @tab @code{@@unnumberedsubsubsec} @tab @code{@@appendixsubsubsec} - @tab @code{@@subsubheading} +@multitable @columnfractions .19 .30 .29 .22 +@item @tab @tab @tab No new page +@item @i{Numbered} @tab @i{Unnumbered} @tab @i{Lettered/numbered} @tab @i{Unnumbered} +@item In contents @tab In contents @tab In contents @tab Omitted from@*contents +@item @tab @code{@@top} @tab @tab @code{@@majorheading} +@item @code{@@chapter} @tab @code{@@unnumbered} @tab @code{@@appendix} @tab @code{@@chapheading} +@item @code{@@section} @tab @code{@@unnumberedsec} @tab @code{@@appendixsec} @tab @code{@@heading} +@item @code{@@subsection} @tab @code{@@unnumberedsubsec} @tab @code{@@appendixsubsec} @tab @code{@@subheading} +@item @code{@@subsubsection} @tab @code{@@unnumberedsubsubsec} @tab @code{@@appendixsubsubsec} @tab @code{@@subsubheading} @end multitable +@tex +{\globaldefs = 1 \textfonts} +@end tex @node makeinfo top @@ -4736,6 +4748,7 @@ capitalized; others are not.@refill @subsection @code{@@node} Line Requirements @cindex Node line requirements +@cindex Restrictions on node names Here are several requirements for @code{@@node} lines: @itemize @bullet @@ -4761,10 +4774,11 @@ node containing the pointer. @cindex @@-commands in nodename @cindex Node name, should not contain @@-commands @item -@w{@@-commands} used in node names generally confuse Info, so you should -avoid them. For a few rare cases when this is useful, Texinfo has -limited support for using @w{@@-commands} in node names; see -@ref{Pointer Validation}. +@w{@@-commands} used in node names generally confuse Info, so you +should avoid them. This includes punctuation characters that are +escaped with a @samp{@@}, such as @code{@@} and @code{@{}. For a few +rare cases when this is useful, Texinfo has limited support for using +@w{@@-commands} in node names; see @ref{Pointer Validation}. @need 750 Thus, the beginning of the section called @code{@@chapter} looks like @@ -4780,6 +4794,12 @@ this:@refill @end smallexample @item +@cindex Parentheses in nodename +You cannot use parentheses in node names, because a node name such as +@samp{(foo)bar} is interpreted by the Info readers as a node +@samp{bar} in an Info file @file{foo}. + +@item @cindex Apostrophe in nodename @cindex Colon in nodename @cindex Comma in nodename @@ -4787,7 +4807,7 @@ this:@refill @cindex Characters, invalid in node name @cindex Invalid characters in node names Unfortunately, you cannot use periods, commas, colons or apostrophes -within a node name; these confuse @TeX{} or the Info formatters.@refill +within a node name; these confuse @TeX{} or the Info formatters. @need 700 For example, the following is a section title: @@ -4846,7 +4866,7 @@ hits @key{DEL} to go backwards, you wind up in the middle of the some other entry in the @file{dir} file, which has nothing to do with what you were reading. -@xref{Install an Info File}, for more information about installing +@xref{Installing an Info File}, for more information about installing an Info file in the @file{info} directory. @@ -4906,6 +4926,7 @@ include an edition number for the manual. (The title page should also contain this information: see @ref{titlepage, , @code{@@titlepage}}.)@refill + @node makeinfo Pointer Creation @section Creating Pointers with @code{makeinfo} @cindex Creating pointers with @code{makeinfo} @@ -4933,6 +4954,12 @@ This node pointer insertion feature in @code{makeinfo} relieves you from the need to update menus and pointers manually or with Texinfo mode commands. (@xref{Updating Nodes and Menus}.) +In most cases, you will want to take advantage of this feature and not +redundantly specify node pointers. However, Texinfo documents are not +required to be organized hierarchically or in fact contain sectioning +commands at all. For example, if you never intend the document to be +printed. In those cases, you will need to explicitly specify the pointers. + @node anchor @section @code{@@anchor}: Defining Arbitrary Cross-reference Targets @@ -5278,7 +5305,7 @@ presumes that you are referring to the `Top' node.@refill The @file{dir} file that contains the main menu for Info has menu entries that list only file names. These take you directly to the `Top' -nodes of each Info document. (@xref{Install an Info File}.)@refill +nodes of each Info document. (@xref{Installing an Info File}.) @need 700 For example: @@ -6275,48 +6302,47 @@ The official GNU ftp site is @uref{ftp://ftp.gnu.org/gnu}. An example of the two-argument form: @example -The official @@uref@{ftp://ftp.gnu.org/gnu, GNU ftp site@} holds -programs and texts. +The official @@uref@{ftp://ftp.gnu.org/gnu, GNU ftp site@} +holds programs and texts. @end example @noindent produces: @display -The official @uref{ftp://ftp.gnu.org/gnu, GNU ftp site} holds -programs and texts. +The official @uref{ftp://ftp.gnu.org/gnu, GNU ftp site} +holds programs and texts. @end display @noindent that is, the Info output is this: @example -The official GNU ftp site (ftp://ftp.gnu.org/gnu) holds -programs and texts. +The official GNU ftp site (ftp://ftp.gnu.org/gnu) +holds programs and texts. @end example @noindent and the HTML output is this: @example -The official <a href="ftp://ftp.gnu.org/gnu">GNU ftp site</a> holds -programs and texts. +The official <a href="ftp://ftp.gnu.org/gnu">GNU ftp site</a> +holds programs and texts. @end example An example of the three-argument form: @example -The @@uref@{http://example.org/man.cgi/1/ls,,ls(1)@} program @dots{} +The @@uref@{/man.cgi/1/ls,,ls(1)@} program @dots{} @end example @noindent produces: @display -The @uref{http://example.org/man.cgi/1/ls,,ls(1)} program @dots{} +The @uref{/man.cgi/1/ls,,ls(1)} program @dots{} @end display @noindent but with HTML: @example -The <a href="http://example.org/man.cgi/1/ls">ls(1)</a> program @dots{} +The <a href="/man.cgi/1/ls">ls(1)</a> program @dots{} @end example To merely indicate a url without creating a link people can follow, use @code{@@url} (@pxref{url, @code{@@url}}). - Some people prefer to display url's in the unambiguous format: @display @@ -6324,7 +6350,7 @@ Some people prefer to display url's in the unambiguous format: @end display @noindent -@cindex <URL: convention, not used +@cindex <URL convention, not used You can use this form in the input file if you wish. We feel it's not necessary to clutter up the output with the extra @samp{<URL:} and @samp{>}, since any software that tries to detect url's in text already @@ -6351,8 +6377,8 @@ program. Also, you can emphasize text, in several different ways. * Emphasis:: How to emphasize text. @end menu + @node Indicating, Emphasis, Marking Text, Marking Text -@comment node-name, next, previous, up @section Indicating Definitions, Commands, etc. @cindex Highlighting text @cindex Indicating commands, definitions, etc. @@ -6380,7 +6406,8 @@ not something else that should not be changed.@refill * code:: Indicating program code. * kbd:: Showing keyboard input. * key:: Specifying keys. -* samp:: Showing a literal sequence of characters. +* samp:: A literal sequence of characters. +* verb:: A verbatim sequence of characters. * var:: Indicating metasyntactic variables. * env:: Indicating environment variables. * file:: Indicating file names. @@ -6712,8 +6739,7 @@ example, write @samp{@@kbd@{Meta-a@}} to produce @kbd{Meta-a} and @c the beginning of the sentence. The @code{@@key@{META@}} key is often in @c the lower left of the keyboard.''@refill -@node samp, var, key, Indicating -@comment node-name, next, previous, up +@node samp @subsection @code{@@samp}@{@var{text}@} @findex samp @@ -6767,6 +6793,38 @@ In English, the vowels are @samp{a}, @samp{e}, @end quotation +@node verb +@subsection @code{@@verb}@{<char>@var{text}<char>@} +@findex verb +@cindex Verbatim in-line text + +@cindex Delimiter character, for verbatim +Use the @code{@@verb} command to print a verbatim sequence of +characters. + +Like La@TeX{}'s @code{\verb} command, the verbatim text can be quoted using +any unique delimiter character. Enclose the verbatim text, including the +delimiters, in braces. Text is printed in a fixed-width font: + +@example +How many @@verb@{|@@|@}-escapes does one need to print this +@@verb@{.@@a @@b @@c.@} string or @@verb@{+@@'e@?`@!`@{@}\+@} this? +@end example + +@noindent +produces + +@example +How many @verb{|@|}-escapes does one need to print this +@verb{.@a @b @c.} string or these @verb{+@'e?`{}!`\+} this? +@end example + +This is in contrast to @code{@@samp} (see the previous +section), whose argument is normal Texinfo text, where the characters +@code{@@@{@}} are special; with @code{@@verb}, nothing is special except +the delimiter character you choose. + + @node var @subsection @code{@@var}@{@var{metasyntactic-variable}@} @findex var @@ -6859,11 +6917,11 @@ section). For example: @example -The @@env@{PATH@} environment variable sets the search path for commands. +The @@env@{PATH@} environment variable @dots{} @end example @noindent produces @quotation -The @env{PATH} environment variable sets the search path for commands. +The @env{PATH} environment variable @dots{} @end quotation @@ -7093,17 +7151,17 @@ the text to display if any. In HTML output, @code{@@email} produces a For example: @example -Send bug reports to @@email@{bug-texinfo@@@@gnu.org@}. -Send suggestions to the @@email@{bug-texinfo@@@@gnu.org, same place@}. +Send bug reports to @@email@{bug-texinfo@@@@gnu.org@}, +suggestions to the @@email@{bug-texinfo@@@@gnu.org, same place@}. @end example @noindent produces @display -Send bug reports to @email{bug-texinfo@@gnu.org}. -Send suggestions to the @email{bug-texinfo@@gnu.org, same place}. +Send bug reports to @email{bug-texinfo@@gnu.org}, +suggestions to the @email{bug-texinfo@@gnu.org, same place}. @end display -@node Emphasis, , Indicating, Marking Text +@node Emphasis @comment node-name, next, previous, up @section Emphasizing Text @cindex Emphasizing text @@ -7267,7 +7325,8 @@ produces If possible, you should avoid using the other three font commands. If you need to use one, it probably indicates a gap in the Texinfo -language.@refill +language. + @node Quotations and Examples @chapter Quotations and Examples @@ -7282,25 +7341,26 @@ an @code{@@end} command that is also at the beginning of a line by itself. For instance, you begin an example by writing @code{@@example} by itself at the beginning of a line and end the example by writing @code{@@end example} on a line by itself, at the beginning of that -line.@refill +line. @findex end @menu -* Block Enclosing Commands:: Use different constructs for - different purposes. -* quotation:: How to write a quotation. -* example:: How to write an example in a fixed-width font. -* noindent:: How to prevent paragraph indentation. -* lisp:: How to illustrate Lisp code. +* 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:: Forms for @code{@@smallbook}. -* display:: How to write an example in the current font. -* format:: How to write an example that does not narrow - the margins. -* exdent:: How to undo the indentation of a line. -* flushleft & flushright:: How to push text flushleft or flushright. -* cartouche:: How to draw cartouches around examples. +* 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. +* cartouche:: Drawing rounded rectangles around examples. @end menu + @node Block Enclosing Commands @section Block Enclosing Commands @@ -7310,16 +7370,22 @@ following sections: @table @code @item @@quotation Indicate text that is quoted. The text is filled, indented, and -printed in a roman font by default.@refill +printed in a roman font by default. @item @@example Illustrate code, commands, and the like. The text is printed -in a fixed-width font, and indented but not filled.@refill +in a fixed-width font, and indented but not filled. + +@item @@verbatim +Mark a piece of text that is to be printed verbatim; no character +substitutions are made and all commands are ignored, until the next +@code{@@end verbatim}. The text is printed in a fixed-width font, +and not indented or filled. Extra spaces and blank lines are +significant, and tabs are expanded. @item @@smallexample Same as @code{@@example}, except that in @TeX{} this command typesets -text in a smaller font for the @code{@@smallbook} format than for the -default 8.5 by 11 inch format. +text in a smaller font. @item @@lisp Like @code{@@example}, but specifically for illustrating Lisp code. The @@ -7351,7 +7417,7 @@ up the left or right margins of unfilled text.@refill The @code{@@noindent} command may be used after one of the above constructs to prevent the following text from being indented as a new -paragraph.@refill +paragraph. You can use the @code{@@cartouche} command within one of the above constructs to highlight the example or quotation by drawing a box with @@ -7408,13 +7474,13 @@ This is a foo. @node example -@section @code{@@example} +@section @code{@@example}: Example Text @cindex Examples, formatting them @cindex Formatting examples @findex example The @code{@@example} command is used to indicate an example that is -not part of the running text, such as computer input or output.@refill +not part of the running text, such as computer input or output. @example @group @@ -7463,11 +7529,11 @@ Note that blank lines inside the beginning the output.@refill @quotation -@strong{Caution:} Do not use tabs in the lines of an example (or anywhere -else in Texinfo, for that matter)! @TeX{} treats tabs as single -spaces, and that is not what they look like. This is a problem with -@TeX{}. (If necessary, in Emacs, you can use @kbd{M-x untabify} to -convert tabs in a region to multiple spaces.)@refill +@strong{Caution:} Do not use tabs in the lines of an example or anywhere +else in Texinfo (except in verbatim environments)! The @TeX{} +implementation of Texinfo treats tabs as single spaces, and that is not +what they look like. (If necessary, in Emacs, you can use @kbd{M-x +untabify} to convert tabs in a region to multiple spaces.)@refill @end quotation Examples are often, logically speaking, ``in the middle'' of a @@ -7483,66 +7549,84 @@ embedded within sentences, not set off from preceding and following text. @xref{code, , @code{@@code}}.) -@node noindent -@section @code{@@noindent} -@findex noindent +@node verbatim +@section @code{@@verbatim}: Literal Text +@findex verbatim +@cindex Verbatim environment -An example or other inclusion can break a paragraph into segments. -Ordinarily, the formatters indent text that follows an example as a new -paragraph. However, you can prevent this by writing @code{@@noindent} -at the beginning of a line by itself preceding the continuation -text.@refill +Use the @code{@@verbatim} environment for printing of text that may +contain special characters or commands that should not be interpreted, +such as computer input or output (@code{@@example} interprets its text +as regular Texinfo commands). This is especially useful for including +automatically generated output in a Texinfo manual. Here is an example; +the output you see is just the same as the input, with a line +@code{@@verbatim} before and a line @code{@@end verbatim} after. + +@verbatim +This is an example of text written in a @verbatim +block. No character substitutions are made all commands +are ignored, until the next 'end verbatim' command. + +In the printed manual, the text is typeset in a +fixed-width font, and not indented or filled. All +spaces and blank lines are significant, including tabs. +@end verbatim + +Write a @code{@@verbatim} command at the beginning of a line by itself. +This line will disappear from the output. Mark the end of the verbatim +block with a @code{@@end verbatim} command, also written at the +beginning of a line by itself. The @code{@@end verbatim} will also +disappear from the output. -@need 1500 For example: +@c urg: got to trick this a bit: can't use @end verbatim inside @verbatim @example -@group -@@example -This is an example -@@end example - -@@noindent -This line is not indented. As you can see, the -beginning of the line is fully flush left with the line -that follows after it. (This whole example is between -@@code@{@@@@display@} and @@code@{@@@@end display@}.) -@end group +@exdent @@verbatim +@exdent @{ +@exdent <tab>@@command with strange characters: @@'e +@exdent expand<tab>me +@exdent @} +@exdent @@end verbatim @end example @noindent produces -@display -@example -This is an example -@end example -@tex -% Remove extra vskip; this is a kludge to counter the effect of display -\vskip-3.5\baselineskip -@end tex +@verbatim +{ + @command with strange characters: @'e +expand me +} +@end verbatim -@noindent -This line is not indented. As you can see, the -beginning of the line is fully flush left with the line -that follows after it. (This whole example is between -@code{@@display} and @code{@@end display}.) -@end display +Since the lines containing @code{@@verbatim} and @code{@@end verbatim} +will disappear, tyically you should put a blank line before the +@code{@@verbatim} and another blank line after the @code{@@end +verbatim}. Blank lines between the beginning @code{@@verbatim} and the +ending @code{@@end verbatim} will appear in the output.) -To adjust the number of blank lines properly in the Info file output, -remember that the line containing @code{@@noindent} does not generate a -blank line, and neither does the @code{@@end example} line.@refill -In the Texinfo source file for this manual, each line that says -`produces' is preceded by a line containing @code{@@noindent}.@refill +@node verbatiminclude +@section @code{@@verbatiminclude} @var{file}: Include a File Verbatim +@cindex Verbatim, include file +@cindex Including a file verbatim +@findex verbatiminclude -Do not put braces after an @code{@@noindent} command; they are not -necessary, since @code{@@noindent} is a command used outside of -paragraphs (@pxref{Command Syntax}).@refill +You can include the exact contents of a file in the document with the +@code{@@verbatiminclude} command: + +@example +@@verbatiminclude @var{filename} +@end example + +The contents of @var{filename} is printed in a verbatim environment +(@pxref{verbatim,,@code{@@verbatim}}). Generally, the file is printed +exactly as it is, with all special characters and white space retained. @node lisp -@section @code{@@lisp} +@section @code{@@lisp}: Marking a Lisp Example @findex lisp @cindex Lisp example @@ -7567,9 +7651,9 @@ itself.@refill @node small @section @code{@@small@dots{}} Block Commands -@cindex Small book example -@cindex Example for a small book -@cindex Lisp example for a small book +@cindex Small examples +@cindex Examples in smaller fonts +@cindex Lisp examples in smaller fonts @findex smalldisplay @findex smallexample @findex smallformat @@ -7578,19 +7662,13 @@ itself.@refill In addition to the regular @code{@@example} and @code{@@lisp} commands, Texinfo has ``small'' example-style commands. These are @code{@@smalldisplay}, @code{@@smallexample}, @code{@@smallformat}, and -@code{@@smalllisp}. All of these commands are designed for use with the -@code{@@smallbook} command (which causes @TeX{} to format a printed book for -a 7 by 9.25 inch trim size rather than the default 8.5 by 11 inch size). +@code{@@smalllisp}. In @TeX{}, the @code{@@small@dots{}} commands typeset text in a smaller -font for the smaller @code{@@smallbook} format than for the 8.5 by 11 -inch format. Consequently, many examples containing long lines fit in a -narrower, @code{@@smallbook} page without needing to be shortened. Both -commands typeset in the normal font size when you format for the 8.5 by -11 inch size. Indeed, in this situation, the @code{@@small@dots{}} -commands are equivalent to their non-small versions. - -In Info, the @code{@@small@dots{}} commands are also equivalent to their +font than the non-small example commands. Consequently, many examples +containing long lines fit on a page without needing to be shortened. + +In Info, the @code{@@small@dots{}} commands are equivalent to their non-small companion commands. Mark the end of an @code{@@small@dots{}} block with a corresponding @@ -7621,24 +7699,22 @@ programs; and that you know you can do these things.} @iftex @smallexample This is an example of text written between @code{@@smallexample} and -@code{@@end smallexample}. In Info and in an 8.5 by 11 inch manual, -this text appears in its normal size; but in a 7 by 9.25 inch manual, -this text appears in a smaller font. +@code{@@end smallexample}. In Info this text appears in its normal size; +but in printed manuals, this text appears in a smaller font. @end smallexample @end iftex @end ifset @ifinfo @smallexample This is an example of text written between @code{@@smallexample} and -@code{@@end smallexample}. In Info and in an 8.5 by 11 inch manual, -this text appears in its normal size; but in a 7 by 9.25 inch manual, -this text appears in a smaller font. +@code{@@end smallexample}. In Info this text appears in its normal size; +but in a 7 by 9.25 inch manual, this text appears in a smaller font. @end smallexample @end ifinfo -The @code{@@small@dots{}} commands make it easier to prepare smaller -format manuals without forcing you to edit examples by hand to fit them -onto narrower pages.@refill +The @code{@@small@dots{}} commands make it easier to prepare manuals +without forcing you to edit examples by hand to fit them onto narrower +pages. As a general rule, a printed document looks better if you use only one of (for example) @code{@@example} or in @code{@@smallexample} @@ -7646,7 +7722,7 @@ consistently within a chapter. Only occasionally should you mix the two formats. @xref{smallbook, , Printing ``Small'' Books}, for more information -about the @code{@@smallbook} command.@refill +about the @code{@@smallbook} command. @node display @@ -7736,10 +7812,13 @@ In practice, the @code{@@exdent} command is rarely used. Usually, you un-indent text by ending the example and returning the page to its normal width.@refill -@node flushleft & flushright, cartouche, exdent, Quotations and Examples + +@node flushleft & flushright @section @code{@@flushleft} and @code{@@flushright} @findex flushleft @findex flushright +@cindex ragged right +@cindex ragged left The @code{@@flushleft} and @code{@@flushright} commands line up the ends of lines on the left and right margins of a page, @@ -7795,16 +7874,76 @@ right justifies every line but leaves the left end ragged. @end flushright -@node cartouche, , flushleft & flushright, Quotations and Examples -@section Drawing Cartouches Around Examples + +@node noindent +@section @code{@@noindent}: Omitting Indentation +@findex noindent + +An example or other inclusion can break a paragraph into segments. +Ordinarily, the formatters indent text that follows an example as a new +paragraph. However, you can prevent this by writing @code{@@noindent} +at the beginning of a line by itself preceding the continuation +text.@refill + +@need 1500 +For example: + +@example +@group +@@example +This is an example +@@end example + +@@noindent +This line is not indented. As you can see, the +beginning of the line is fully flush left with the line +that follows after it. (This whole example is between +@@code@{@@@@display@} and @@code@{@@@@end display@}.) +@end group +@end example + +@noindent +produces + +@display +@example +This is an example +@end example +@tex +% Remove extra vskip; this is a kludge to counter the effect of display +\vskip-3.5\baselineskip +@end tex + +@noindent +This line is not indented. As you can see, the +beginning of the line is fully flush left with the line +that follows after it. (This whole example is between +@code{@@display} and @code{@@end display}.) +@end display + +To adjust the number of blank lines properly in the Info file output, +remember that the line containing @code{@@noindent} does not generate a +blank line, and neither does the @code{@@end example} line.@refill + +In the Texinfo source file for this manual, each line that says +`produces' is preceded by a line containing @code{@@noindent}.@refill + +Do not put braces after an @code{@@noindent} command; they are not +necessary, since @code{@@noindent} is a command used outside of +paragraphs (@pxref{Command Syntax}).@refill + + +@node cartouche +@section @code{@@cartouche}: Rounded Rectangles Around Examples @findex cartouche @cindex Box with rounded corners +@cindex Rounded rectangles, around examples In a printed manual, the @code{@@cartouche} command draws a box with rounded corners around its contents. You can use this command to further highlight an example or quotation. For instance, you could write a manual in which one type of example is surrounded by a cartouche -for emphasis.@refill +for emphasis. @code{@@cartouche} affects only the printed manual; it has no effect in other output files. @@ -7841,7 +7980,7 @@ In a printed manual, the example looks like this:@refill @end iftex -@node Lists and Tables, Indices, Quotations and Examples, Top +@node Lists and Tables @chapter Lists and Tables @cindex Making lists and tables @cindex Lists and tables, making @@ -8944,7 +9083,7 @@ use the special commands; you just enter a period as you would if you were using a typewriter, which means you put two spaces after the period, question mark, or exclamation mark that ends a sentence. -@findex : @r{(suppress widening)} +@findex <colon> @r{(suppress widening)} Use the @code{@@:}@: command after a period, question mark, exclamation mark, or colon that should not be followed by extra space. For example, use @code{@@:}@: after periods that end abbreviations @@ -9070,6 +9209,8 @@ Other possible uses of @code{@@@kbd{SPACE}} have been subsumed by Do not follow any of these commands with braces. +To produce a non-breakable space, see @ref{w, non-breakable space}. + @node dmn @subsection @code{@@dmn}@{@var{dimension}@}: Format a Dimension @@ -9208,7 +9349,7 @@ commonly used in languages other than English. @cindex Es-zet @cindex Sharp S @cindex German S -@multitable {x@@questiondown@{@} } {oe,OE} {es-zet or sharp S} +@multitable {x@@questiondown@{@}} {oe,OE} {es-zet or sharp S} @item @t{@@exclamdown@{@}} @tab @exclamdown{} @tab upside-down ! @item @t{@@questiondown@{@}} @tab @questiondown{} @tab upside-down ? @item @t{@@aa@{@},@@AA@{@}} @tab @aa{},@AA{} @tab a,A with circle @@ -9335,6 +9476,8 @@ available. @section @code{@@minus}@{@} (@minus{}): Inserting a Minus Sign @findex minus +@cindex em-dash +@cindex hyphen Use the @code{@@minus@{@}} command to generate a minus sign. In a fixed-width font, this is a single hyphen, but in a proportional font, the symbol is the customary length for a minus sign---a little longer @@ -9361,10 +9504,11 @@ an itemized list, you do not need to type the braces (@pxref{itemize, , @code{@@itemize}}.) -@node math, Glyphs, minus, Insertions +@node math @section @code{@@math}: Inserting Mathematical Expressions @findex math @cindex Mathematical expressions +@cindex Formulas, mathematical You can write a short mathematical expression with the @code{@@math} command. Write the mathematical expression between braces, like this: @@ -9374,20 +9518,16 @@ command. Write the mathematical expression between braces, like this: @end example @iftex -@need 1000 -@noindent -This produces the following in @TeX{}: +@noindent This produces the following in @TeX{}: @display @math{(a + b)(a + b) = a^2 + 2ab + b^2} @end display -@noindent -and the following in Info: +@noindent and the following in Info: @end iftex @ifinfo -@noindent -This produces the following in Info: +@noindent This produces the following in Info: @end ifinfo @example @@ -9396,15 +9536,38 @@ This produces the following in Info: Thus, the @code{@@math} command has no effect on the Info output. -For complex mathematical expressions, you can also use @TeX{} directly -(@pxref{Raw Formatter Commands}). When you use @TeX{} directly, -remember to write the mathematical expression between one or two -@samp{$} (dollar-signs) as appropriate. +@code{@@math} implies @code{@@tex}. This not only makes it possible to +write superscripts and subscripts (as in the above example), but also +allows you to use any of the plain @TeX{} math control sequences. It's +simplest to use @samp{\} instead of @samp{@@} for these commands. As +in: +@example +@@math@{\sin 2\pi \equiv \cos 3\pi@} +@end example + +@iftex +@noindent which looks like this in @TeX{}: +@display +@math{\sin 2\pi \equiv \cos 3\pi} +@end display + +@noindent and +@end iftex +@noindent which looks like the input in Info and HTML: +@example +\sin 2\pi \equiv \cos 3\pi +@end example + +@cindex Displayed equations +@cindex Equations, displayed +For displayed equations, you must at present use @TeX{} directly +(@pxref{Raw Formatter Commands}). @node Glyphs @section Glyphs for Examples @cindex Glyphs +@cindex Examples, glyphs for In Texinfo, code is often illustrated in examples that are delimited by @code{@@example} and @code{@@end example}, or by @code{@@lisp} and @@ -9429,12 +9592,11 @@ left- and right-hand braces.@refill * Point Glyph:: How to indicate the location of point. @end menu -@node Glyphs Summary, result, Glyphs, Glyphs -@ifinfo -@subheading Glyphs Summary + +@node Glyphs Summary +@subsection Glyphs Summary Here are the different glyph commands:@refill -@end ifinfo @table @asis @item @result{} @@ -9457,7 +9619,6 @@ message.@refill @code{@@point@{@}} shows the location of point.@refill @end table - @menu * result:: * expansion:: @@ -9467,7 +9628,8 @@ message.@refill * Point Glyph:: @end menu -@node result, expansion, Glyphs Summary, Glyphs + +@node result @subsection @code{@@result@{@}} (@result{}): Indicating Evaluation @cindex Result of an expression @cindex Indicating evaluation @@ -9757,13 +9919,14 @@ primary text.@footnote{A footnote should complement or expand upon the primary text, but a reader should not need to read a footnote to understand the primary text. For a thorough discussion of footnotes, see @cite{The Chicago Manual of Style}, which is published by the -University of Chicago Press.}@refill +University of Chicago Press.} @menu * Footnote Commands:: How to write a footnote in Texinfo. * Footnote Styles:: Controlling how footnotes appear in Info. @end menu + @node Footnote Commands @subsection Footnote Commands @@ -9783,16 +9946,21 @@ marker might end up starting a line. For example, this clause is followed by a sample footnote@footnote{Here is the sample footnote.}; in the Texinfo source, it looks like -this:@refill +this: @example @dots{}a sample footnote@@footnote@{Here is the sample footnote.@}; in the Texinfo source@dots{} @end example +As you can see, the source includes two punctuation marks next to each +other; in this case, @samp{.@};} is the sequence. This is normal (the +first ends the footnote and the second belongs to the sentence being +footnoted), so don't worry that it looks odd. + In a printed manual or book, the reference mark for a footnote is a small, superscripted number; the text of the footnote appears at the -bottom of the page, below a horizontal line.@refill +bottom of the page, below a horizontal line. In Info, the reference mark for a footnote is a pair of parentheses with the footnote number between them, like this: @samp{(1)}. The @@ -9950,7 +10118,7 @@ You can insert an image given in an external file with the @code{@@image} command: @example -@@image@{@var{filename}, @r{[}@var{width}@r{]}, @r{[}@var{height}@r{]}@} +@@image@{@var{filename}, @r{[}@var{width}@r{]}, @r{[}@var{height}@r{]}, @r{[}@var{alttext}@r{]}, @r{[}@var{extension}@r{]}@} @end example @cindex Formats for images @@ -9968,13 +10136,26 @@ PDF@TeX{} reads @file{@var{filename}.pdf} (Adobe's Portable Document Format). @code{makeinfo} uses @file{@var{filename}.txt} verbatim for Info output (more or less as if it was an @code{@@example}). @item +@code{makeinfo} +uses the optional fifth argument to @code{@@image} for the extension if +you supply it. For example: + +@pindex XPM image format +@example +@@image@{foo,,,,xpm@} +@end example + +@noindent +will cause @samp{makeinfo --html} to try @file{foo.xpm}. + @cindex GIF, unsupported due to patents @cindex PNG image format -@cindex JPEG image format -@code{makeinfo} producing HTML output tries @file{@var{filename}.png}; -if that does not exist, it tries @file{@var{filename}.jpg}. If that -does not exist either, it complains. (We cannot support GIF format due -to patents.) +@cindex JPG image format +If you do not supply the optional fifth argument, @samp{makeinfo +---html} first tries @file{@var{filename}.png}; if that does not exist, +it tries @file{@var{filename}.jpg}. If that does not exist either, it +complains. (We cannot support GIF format directly due to software +patents.) @end itemize @cindex Width of images @@ -10035,38 +10216,48 @@ For @code{@@image} to work with @TeX{}, the file @file{epsf.tex} must be installed somewhere that @TeX{} can find it. (The standard location is @file{@var{texmf}/tex/generic/dvips/epsf.tex}, where @var{texmf} is a root of your @TeX{} directory tree.) This file is included in the -Texinfo distribution and is available from -@uref{ftp://tug.org/tex/epsf.tex}. +Texinfo distribution and is also available from +@uref{ftp://tug.org/tex/epsf.tex}, among other places. @code{@@image} can be used within a line as well as for displayed figures. Therefore, if you intend it to be displayed, be sure to leave a blank line before the command, or the output will run into the preceding text. +@cindex alt attribute for images +@cindex alternate text for images +When producing html, @code{makeinfo} sets the @dfn{alt attribute} for +inline images to the optional fourth argument to @code{@@image}, if +supplied. If not supplied, @code{makeinfo} uses the full file name of +the image being displayed. + @node Breaks @chapter Making and Preventing Breaks @cindex Making line and page breaks @cindex Preventing line and page breaks +@cindex Line breaks Usually, a Texinfo file is processed both by @TeX{} and by one of the Info formatting commands. Line, paragraph, or page breaks sometimes occur in the `wrong' place in one or other form of output. You must ensure that text looks right both in the printed manual and in the -Info file.@refill +Info file. +@cindex White space, excessive +@cindex Page breaks For example, in a printed manual, page breaks may occur awkwardly in the middle of an example; to prevent this, you can hold text together using a grouping command that keeps the text from being split across two pages. Conversely, you may want to force a page break where none would occur normally. Fortunately, problems like these do not often arise. When they do, use the break, break prevention, or pagination -commands.@refill +commands. @menu * Break Commands:: Cause and prevent splits. * Line Breaks:: How to force a single line to use two lines. -* - and hyphenation:: How to tell TeX about hyphenation points. +* - and hyphenation:: How to tell @TeX{} about hyphenation points. * w:: How to prevent unwanted line breaks. * sp:: How to insert blank lines. * page:: How to force the start of a new page. @@ -10074,6 +10265,7 @@ commands.@refill * need:: Another way to prevent unwanted page breaks. @end menu + @node Break Commands, Line Breaks, Breaks, Breaks @ifinfo @heading Break Commands @@ -10120,8 +10312,7 @@ Hold text together that must appear on one printed page.@refill Start a new printed page if not enough space on this one.@refill @end table -@node Line Breaks, - and hyphenation, Break Commands, Breaks -@comment node-name, next, previous, up +@node Line Breaks @section @code{@@*}: Generate Line Breaks @findex * @r{(force line break)} @cindex Line breaks @@ -10176,7 +10367,8 @@ refilled after the line break occurs, negating the effect of the line break.@refill @end quotation -@node - and hyphenation, w, Line Breaks, Breaks + +@node - and hyphenation @section @code{@@-} and @code{@@hyphenation}: Helping @TeX{} hyphenate @findex - @@ -10305,8 +10497,8 @@ and is followed by another line. The @code{@@br} command is seldom used. @end ignore -@node page, group, sp, Breaks -@comment node-name, next, previous, up + +@node page @section @code{@@page}: Start a New Page @cindex Page breaks @findex page @@ -10314,7 +10506,8 @@ The @code{@@br} command is seldom used. A line containing only @code{@@page} starts a new page in a printed manual. The command has no effect on Info files since they are not paginated. An @code{@@page} command is often used in the @code{@@titlepage} -section of a Texinfo file to start the copyright page.@refill +section of a Texinfo file to start the copyright page. + @node group, need, page, Breaks @comment node-name, next, previous, up @@ -10555,6 +10748,10 @@ definition.@refill The other specialized commands work like @code{@@defun}.@refill +@cindex Macros in definition commands +Note that, due to implementation difficulties, macros are not expanded +in @code{@@deffn} and all the other definition commands. + @node Optional Arguments, deffnx, Def Cmd Template, Definition Commands @section Optional and Repeated Arguments @cindex Optional and repeated arguments @@ -11621,7 +11818,7 @@ with @code{@@iftex}, not raw formatter source as with @code{@@tex} (@pxref{Raw Formatter Commands}). -@node Raw Formatter Commands, set clear value, Conditional Not Commands, Conditionals +@node Raw Formatter Commands @section Raw Formatter Commands @cindex @TeX{} commands, using ordinary @cindex HTML commands, using ordinary @@ -11697,147 +11894,45 @@ You can direct the Texinfo formatting commands to format or ignore parts of a Texinfo file with the @code{@@set}, @code{@@clear}, @code{@@ifset}, and @code{@@ifclear} commands.@refill -In addition, you can use the @code{@@set @var{flag}} command to set the -value of @var{flag} to a string of characters; and use -@code{@@value@{@var{flag}@}} to insert that string. You can use -@code{@@set}, for example, to set a date and use @code{@@value} to -insert the date in several places in the Texinfo file.@refill - -@menu -* ifset ifclear:: Format a region if a flag is set. -* set value:: Expand a flag variable to a string. -* value Example:: An easy way to update edition information. -@end menu - - -@node ifset ifclear -@subsection @code{@@ifset} and @code{@@ifclear} - -@findex ifset -When a @var{flag} is set, the Texinfo formatting commands format text -between subsequent pairs of @code{@@ifset @var{flag}} and @code{@@end -ifset} commands. When the @var{flag} is cleared, the Texinfo formatting -commands do @emph{not} format the text. - -Use the @code{@@set @var{flag}} command to turn on, or @dfn{set}, a -@var{flag}; a @dfn{flag} name can be any single word, containing -letters, numerals, hyphens, or underscores. - -The format for the command looks like this:@refill -@findex set - -@example -@@set @var{flag} -@end example - -Write the conditionally formatted text between @code{@@ifset @var{flag}} -and @code{@@end ifset} commands, like this:@refill - -@example -@group -@@ifset @var{flag} -@var{conditional-text} -@@end ifset -@end group -@end example - -For example, you can create one document that has two variants, such as -a manual for a `large' and `small' model:@refill - -@example -You can use this machine to dig up shrubs -without hurting them. - -@@set large - -@@ifset large -It can also dig up fully grown trees. -@@end ifset - -Remember to replant promptly @dots{} -@end example - -@noindent -In the example, the formatting commands will format the text between -@code{@@ifset large} and @code{@@end ifset} because the @code{large} -flag is set.@refill - -@findex clear -Use the @code{@@clear @var{flag}} command to turn off, or @dfn{clear}, -a flag. Clearing a flag is the opposite of setting a flag. The -command looks like this:@refill - -@example -@@clear @var{flag} -@end example - -@noindent -Write the command on a line of its own. - -When @var{flag} is cleared, the Texinfo formatting commands do -@emph{not} format the text between @code{@@ifset @var{flag}} and -@code{@@end ifset}; that text is ignored and does not appear in either -printed or Info output.@refill - -For example, if you clear the flag of the preceding example by writing -an @code{@@clear large} command after the @code{@@set large} command -(but before the conditional text), then the Texinfo formatting commands -ignore the text between the @code{@@ifset large} and @code{@@end ifset} -commands. In the formatted output, that text does not appear; in both -printed and Info output, you see only the lines that say, ``You can use -this machine to dig up shrubs without hurting them. Remember to replant -promptly @dots{}''. - -@findex ifclear -If a flag is cleared with an @code{@@clear @var{flag}} command, then -the formatting commands format text between subsequent pairs of -@code{@@ifclear} and @code{@@end ifclear} commands. But if the flag -is set with @code{@@set @var{flag}}, then the formatting commands do -@emph{not} format text between an @code{@@ifclear} and an @code{@@end -ifclear} command; rather, they ignore that text. An @code{@@ifclear} -command looks like this:@refill - -@example -@@ifclear @var{flag} -@end example - -@need 700 -In brief, the commands are:@refill +Brief descriptions: @table @code -@item @@set @var{flag} -Tell the Texinfo formatting commands that @var{flag} is set.@refill +@item @@set @var{flag} [@var{value}] +Set the variable @var{flag}, to the optional @var{value} if specifed. @item @@clear @var{flag} -Tell the Texinfo formatting commands that @var{flag} is cleared.@refill +Undefine the variable @var{flag}, whether or not it was previously defined. @item @@ifset @var{flag} -If @var{flag} is set, tell the Texinfo formatting commands to format -the text up to the following @code{@@end ifset} command.@refill - -If @var{flag} is cleared, tell the Texinfo formatting commands to -ignore text up to the following @code{@@end ifset} command.@refill +If @var{flag} is set, text through the next @code{@@end ifset} command +is formatted. If @var{flag} is clear, text through the following +@code{@@end ifset} command is ignored. @item @@ifclear @var{flag} -If @var{flag} is set, tell the Texinfo formatting commands to ignore -the text up to the following @code{@@end ifclear} command.@refill - -If @var{flag} is cleared, tell the Texinfo formatting commands to -format the text up to the following @code{@@end ifclear} -command.@refill +If @var{flag} is set, text through the next @code{@@end ifclear} command +is ignored. If @var{flag} is clear, text through the following +@code{@@end ifclear} command is formatted. @end table +@menu +* set value:: Expand a flag variable to a string. +* ifset ifclear:: Format a region if a flag is set. +* value Example:: An easy way to update edition information. +@end menu + @node set value @subsection @code{@@set} and @code{@@value} @findex value -You can use the @code{@@set} command to specify a value for a flag, -which is expanded by the @code{@@value} command. A flag is an -identifier; for best results, use only letters and numerals in a flag -name, not @samp{-} or @samp{_}---they will work in some contexts, but -not all, due to limitations in @TeX{}. The value is just a string of -characters, the remainder of the input line. +You use the @code{@@set} command to specify a value for a flag, which is +later expanded by the @code{@@value} command. + +A @dfn{flag} is an identifier. In general, it is best to use only +letters and numerals in a flag name, not @samp{-} or @samp{_}---they +will work in some contexts, but not all, due to limitations in @TeX{}. + +The value is the remainder of the input line, and can contain anything. Write the @code{@@set} command like this: @@ -11850,12 +11945,12 @@ This sets the value of the flag @code{foo} to ``This is a string.''. The Texinfo formatters then replace an @code{@@value@{@var{flag}@}} command with the string to which @var{flag} is set. Thus, when -@code{foo} is set as shown above, the Texinfo formatters convert +@code{foo} is set as shown above, the Texinfo formatters convert this: @example @group @@value@{foo@} -@exdent @r{to} +@exdent @r{to this:} This is a string. @end group @end example @@ -11870,12 +11965,10 @@ If you write the @code{@@set} command like this: @end example @noindent -without specifying a string, the value of @code{foo} is an empty string. +without specifying a string, the value of @code{foo} is the empty string. If you clear a previously set flag with @code{@@clear @var{flag}}, a -subsequent @code{@@value@{flag@}} command is invalid and the string is -replaced with an error message that says @samp{@{No value for -"@var{flag}"@}}. +subsequent @code{@@value@{flag@}} command will report an error. For example, if you set @code{foo} as follows:@refill @@ -11912,12 +12005,83 @@ It is a @{No value for "how-much"@} wet day. @end example +@node ifset ifclear +@subsection @code{@@ifset} and @code{@@ifclear} + +@findex ifset +When a @var{flag} is set, the Texinfo formatting commands format text +between subsequent pairs of @code{@@ifset @var{flag}} and @code{@@end +ifset} commands. When the @var{flag} is cleared, the Texinfo formatting +commands do @emph{not} format the text. @code{@@ifclear} operates +analogously. + +Write the conditionally formatted text between @code{@@ifset @var{flag}} +and @code{@@end ifset} commands, like this: + +@example +@group +@@ifset @var{flag} +@var{conditional-text} +@@end ifset +@end group +@end example + +For example, you can create one document that has two variants, such as +a manual for a `large' and `small' model: + +@cindex shrubbery +@example +You can use this machine to dig up shrubs +without hurting them. + +@@set large + +@@ifset large +It can also dig up fully grown trees. +@@end ifset + +Remember to replant promptly @dots{} +@end example + +@noindent +In the example, the formatting commands will format the text between +@code{@@ifset large} and @code{@@end ifset} because the @code{large} +flag is set. + +When @var{flag} is cleared, the Texinfo formatting commands do +@emph{not} format the text between @code{@@ifset @var{flag}} and +@code{@@end ifset}; that text is ignored and does not appear in either +printed or Info output. + +For example, if you clear the flag of the preceding example by writing +an @code{@@clear large} command after the @code{@@set large} command +(but before the conditional text), then the Texinfo formatting commands +ignore the text between the @code{@@ifset large} and @code{@@end ifset} +commands. In the formatted output, that text does not appear; in both +printed and Info output, you see only the lines that say, ``You can use +this machine to dig up shrubs without hurting them. Remember to replant +promptly @dots{}''. + +@findex ifclear +If a flag is cleared with an @code{@@clear @var{flag}} command, then +the formatting commands format text between subsequent pairs of +@code{@@ifclear} and @code{@@end ifclear} commands. But if the flag +is set with @code{@@set @var{flag}}, then the formatting commands do +@emph{not} format text between an @code{@@ifclear} and an @code{@@end +ifclear} command; rather, they ignore that text. An @code{@@ifclear} +command looks like this: + +@example +@@ifclear @var{flag} +@end example + + @node value Example @subsection @code{@@value} Example -You can use the @code{@@value} command to limit the number of places you -need to change when you record an update to a manual. Here is how it is -done in @cite{The GNU Make Manual}: +You can use the @code{@@value} command to minimize the number of places +you need to change when you record an update to a manual. Here is how +it is done in @cite{The GNU Make Manual}: @enumerate @item @@ -12033,14 +12197,9 @@ current hyphenation patterns (via the @TeX{} primitive @cindex ISO 639 codes @cindex Language codes -@cindex African languages -Here is the list of valid language codes. This list comes from -@uref{http://www.iro.umontreal.ca/contrib/po/iso-639, the free -translation project}. In the future we may wish to allow the 3-letter -POV codes described at @uref{http://www.sil.org/ethnologue/#contents}. -This will be necessary to support African languages. - -@multitable @columnfractions .06 .27 .06 .27 .06 .27 +Hereare the valid language codes, from ISO-639. + +@multitable @columnfractions .07 .26 .07 .26 .07 .26 @item @code{aa} @tab Afar @tab @code{ab} @tab Abkhazian @tab @@ -12245,11 +12404,12 @@ specification following, such as @samp{ISO-8859-1}. @cindex http-equiv, and charset @cindex meta HTML tag, and charset At present, this is used only in HTML output from @code{makeinfo}. If a -document encoding @var{enc} is specified, it is used in the -@samp{<meta>} tag is included in the @samp{<head>} of the output: +document encoding @var{enc} is specified, it is used in a +@samp{<meta>} tag included in the @samp{<head>} of the output: @example -<meta http-equiv="Content-Type" content="text/html; charset=@var{enc}"> +<meta http-equiv="Content-Type" content="text/html; + charset=@var{enc}"> @end example @@ -12297,7 +12457,6 @@ customized output in the Info file. @section Defining Macros @cindex Defining macros @cindex Macro definitions -@cindex Definitions, a.k.a.@: macros @findex macro You use the Texinfo @code{@@macro} command to define a macro, like this: @@ -12351,7 +12510,7 @@ To allow a macro to be used recursively, that is, in an argument to a call to itself, you must define it with @samp{@@rmacro}, like this: @example -@@rmacro rmac +@@rmacro rmac @{arg@} a\arg\b @@end rmacro @dots{} @@ -12423,6 +12582,8 @@ No arguments here. No arguments here. @end display +@cindex Comma, in macro arguments +@cindex Braces, in macro arguments To insert a comma, brace, or backslash in an argument, prepend a backslash, as in @@ -12432,7 +12593,8 @@ backslash, as in @noindent which will pass the (almost certainly error-producing) argument -@samp{\@{@},} to @var{macname}. +@samp{\@{@},} to @var{macname}. However, commas in parameters, even +if escaped by a backslash, might cause trouble in @TeX{}. If the macro is defined to take a single argument, and is invoked without any braces, the entire rest of the line after the macro name is @@ -12481,13 +12643,18 @@ implementations, Texinfo macros have the following limitations. @itemize @bullet @item All macros are expanded inside at least one @TeX{} group. This means -that @set and other such commands will have no effect inside a macro. +that @code{@@set} and other such commands will have no effect inside a +macro. @item Macros containing a command which must be on a line by itself, such as a conditional, cannot be invoked in the middle of a line. @item +Commas in macro arguments, even if escaped by a backslash, don't +always work. + +@item The @TeX{} implementation cannot construct macros that define macros in the natural way. To do this, you must use conditionals and raw @TeX{}. For example: @@ -12511,6 +12678,10 @@ It is best to avoid comments inside macro definitions. @end itemize +If some macro feature causes errors when producing the printed version +of a manual, try expanding the macros with @command{makeinfo} by +invoking @command{texi2dvi} with the @samp{-e} option; see @ref{Format +with texi2dvi}. @node alias @section @samp{@@alias @var{new}=@var{existing}} @@ -12553,7 +12724,7 @@ Aliases must not be recursive, directly or indirectly. @findex definfoenclose A @code{@@definfoenclose} command may be used to define a highlighting -command for Info, but not for TeX. A command defined using +command for Info, but not for @TeX{}. A command defined using @code{@@definfoenclose} marks text by enclosing it in strings that precede and follow the text. You can use this to get closer control of your Info output. @@ -12595,7 +12766,7 @@ formatting command that inserts `//' before and `\\' after the argument to @code{@@phoo}. You can then write @code{@@phoo@{bar@}} wherever you want `//bar\\' highlighted in Info. -Also, for TeX formatting, you could write +Also, for @TeX{} formatting, you could write @example @@iftex @@ -12604,14 +12775,13 @@ Also, for TeX formatting, you could write @end example @noindent -to define @code{@@phoo} as a command that causes TeX to typeset the +to define @code{@@phoo} as a command that causes @TeX{} to typeset the argument to @code{@@phoo} in italics. -Note that each definition applies to its own formatter: one for TeX, -the other for @code{texinfo-format-buffer} or -@code{texinfo-format-region}. The @code{@@definfoenclose} command need -not be within @samp{@@ifinfo}, but the raw @TeX{} commands do need to be -in @samp{@@iftex}. +Each definition applies to its own formatter: one for @TeX{}, the other +for @code{texinfo-format-buffer} or @code{texinfo-format-region}. The +@code{@@definfoenclose} command need not be within @samp{@@ifinfo}, but +the raw @TeX{} commands do need to be in @samp{@@iftex}. @findex headword Here is another example: write @@ -12665,7 +12835,7 @@ print queue, and delete a job from the print queue. * 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 European A4 paper. +* 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. @@ -12680,10 +12850,11 @@ file. @TeX{} is a very powerful typesetting program and, if used correctly, does an exceptionally good job. (@xref{Obtaining TeX, , How to Obtain @TeX{}}, for information on how to obtain @TeX{}.) -The @code{makeinfo}, @code{texinfo-format-region}, and -@code{texinfo-format-buffer} commands read the very same @@-commands -in the Texinfo file as does @TeX{}, but process them differently to -make an Info file (@pxref{Creating an Info File}). +The standalone @code{makeinfo} program and Emacs functions +@code{texinfo-format-region} and @code{texinfo-format-buffer} commands +read the very same @@-commands in the Texinfo file as does @TeX{}, but +process them differently to make an Info file (@pxref{Creating an Info +File}). @node Format with tex/texindex @@ -12844,7 +13015,7 @@ Perhaps the most useful option to @code{texi2dvi} is after the @code{@@setfilename} in a temporary copy of the input file before running @TeX{}. With this, you can specify different printing formats, such as @code{@@smallbook} (@pxref{smallbook}), -@code{@@afourpaper} (@pxref{A4 Paper}), or @code{@@pageparams} +@code{@@afourpaper} (@pxref{A4 Paper}), or @code{@@pagesizes} (@pxref{pagesizes}), without actually changing the document source. (You can also do this on a site-wide basis with @file{texinfo.cnf}; @pxref{Preparing for TeX,,Preparing for @TeX{}}). @@ -12852,16 +13023,15 @@ formats, such as @code{@@smallbook} (@pxref{smallbook}), For a list of other options, run @samp{texi2dvi --help}. -@node Print with lpr, Within Emacs, Format with texi2dvi, Hardcopy +@node Print with lpr @section Shell Print Using @code{lpr -d} @pindex lpr @r{(DVI print command)} The precise command to print a DVI file depends on your system -installation, but @samp{lpr -d} is common. The command may require the -DVI file name without any extension or with a @samp{.dvi} -extension. (If it is @samp{lpr}, you must include the @samp{.dvi}.) +installation. Two common ones are @samp{dvips foo.dvi -o} and @samp{lpr +-d foo.dvi}. -For example, the following commands, will (perhaps) suffice to sort the +For example, the following commands will (perhaps) suffice to sort the indices, format, and print the @cite{Bison Manual}: @example @@ -12875,15 +13045,15 @@ lpr -d bison.dvi @noindent (Remember that the shell commands may be different at your site; but -these are commonly used versions.)@refill +these are commonly used versions.) -@need 1000 -Using the @code{texi2dvi} shell script, you simply need type:@refill +Using the @code{texi2dvi} shell script (see the previous section): @example @group texi2dvi bison.texinfo lpr -d bison.dvi +# or perhaps dvips bison.dvi -o @end group @end example @@ -13155,26 +13325,28 @@ For more information, see: @cindex @b{.cshrc} initialization file @cindex Initialization file for @TeX{} input -@TeX{} needs to know where to find the @file{texinfo.tex} file that you -have told it to input with the @samp{\input texinfo} command at the -beginning of the first line. The @file{texinfo.tex} file tells @TeX{} -how to handle @@-commands; it is included in all standard GNU -distributions. +@TeX{} needs to know where to find the @file{texinfo.tex} file that the +@samp{\input texinfo} command on the first line reads. The +@file{texinfo.tex} file tells @TeX{} how to handle @@-commands; it is +included in all standard GNU distributions. @pindex texinfo.tex@r{, installing} -Usually, the @file{texinfo.tex} file is put under the default directory -that contains @TeX{} macros -(@file{/usr/local/share/texmf/tex/texinfo/texinfo.tex} by default) when -GNU Emacs or other GNU software is installed. In this case, @TeX{} will -find the file and you do not need to do anything special. -Alternatively, you can put @file{texinfo.tex} in the current directory -when you run @TeX{}, and @TeX{} will find it there. + +Usually, the installer has put the @file{texinfo.tex} file in the +default directory that contains @TeX{} macros when GNU Texinfo, Emacs or +other GNU software is installed. In this case, @TeX{} will find the +file and you do not need to do anything special. If this has not been +done, you can put @file{texinfo.tex} in the current directory when you +run @TeX{}, and @TeX{} will find it there. @pindex epsf.tex@r{, installing} -Also, you should install @file{epsf.tex} in the same place as -@file{texinfo.tex}, if it is not already installed from another -distribution. This file is needed to support the @code{@@image} command -(@pxref{Images}). +Also, you should install @file{epsf.tex}, if it is not already installed +from another distribution. More details are at the end of the description +of the @code{@@image} command (@pxref{Images}). + +@pindex pdfcolor.tex@r{, installing} +Likewise for @file{pdfcolor.tex}, if it is not already installed and you +use pdftex. @pindex texinfo.cnf @r{installation} @cindex Customizing of @TeX{} for Texinfo @@ -13254,10 +13426,9 @@ redumping.) You can do this by running this command, assuming initex texinfo @@dump @end example -(@code{@@dump} is a @TeX{} primitive.) You'll then need to move -@file{texinfo.fmt} to wherever your @code{.fmt} files are found; -typically this will be in the subdirectory @file{web2c} of your @TeX{} -installation, for example, @file{/usr/local/share/tex/web2c}. +(@code{dump} is a @TeX{} primitive.) Then, move @file{texinfo.fmt} to +wherever your @code{.fmt} files are found; typically, this will be in the +subdirectory @file{web2c} of your @TeX{} installation. @node Overfull hboxes @@ -13305,10 +13476,10 @@ like this: @end example @noindent -(You can adjust the fraction as needed.) This huge value for +(You should adjust the fraction as needed.) This huge value for @code{\emergencystretch} cannot be the default, since then the typeset -output would generally be of noticeably lower quality. The default -value is @samp{.15\hsize}. @code{\hsize} is the @TeX{} dimension +output would generally be of noticeably lower quality; the default +is @samp{.15\hsize}. @code{\hsize} is the @TeX{} dimension containing the current line width. @cindex Black rectangle in hardcopy @@ -13369,15 +13540,16 @@ require changing the source file. @node A4 Paper @section Printing on A4 Paper @cindex A4 paper, printing on -@cindex Paper size, European A4 +@cindex A5 paper, printing on +@cindex Paper size, A4 @cindex European A4 paper @findex afourpaper You can tell @TeX{} to format a document for printing on European size -A4 paper with the @code{@@afourpaper} command. Write the command on a -line by itself near the beginning of the Texinfo file, before the title -page. For example, this is how you would write the header for this -manual: +A4 paper (or A5) with the @code{@@afourpaper} (or @code{@@afivepaper}) +command. Write the command on a line by itself near the beginning of +the Texinfo file, before the title page. For example, this is how you +would write the header for this manual: @example @group @@ -13391,15 +13563,15 @@ manual: @end example @xref{Format with texi2dvi}, and @ref{Preparing for TeX,,Preparing for -@TeX{}}, for other ways to format with @code{@@afourpaper} that do not +@TeX{}}, for other ways to format for different paper sizes that do not require changing the source file. @findex afourlatex +@findex afourwide You may or may not prefer the formatting that results from the command @code{@@afourlatex}. There's also @code{@@afourwide} for A4 paper in wide format. - @node pagesizes @section @code{@@pagesizes} [@var{width}][, @var{height}]: Custom page sizes @findex pagesizes @@ -13515,21 +13687,21 @@ You can generate a PDF output file from Texinfo source by using the @command{tex}. Just run @samp{pdftex foo.texi} instead of @samp{tex foo.texi}, or give the @samp{--pdf} option to @command{texi2dvi}. -PDF stands for Portable Document Format, and was invented by Adobe -Systems. The -@uref{http://www.adobe.com/prodindex/acrobat/adobepdf.html, file format -definition} is freely available, as is a -@uref{http://www.foolabs.com/xpdf/, free viewer} for the X window -system. Since PDF is a binary format, there is no @samp{@@ifpdf} or -@samp{@@pdf} command by analogy with the other output formats. +@dfn{PDF} stands for `Portable Document Format'. It was invented by +Adobe Systems some years ago for document interchange, based on their +PostScript language. A @uref{http://www.foolabs.com/xpdf/, PDF reader} +for the X window system is freely available, as is the +@uref{http://partners.adobe.com/asn/developer/technotes/, definition of +the file format}. Since PDF is a binary format, there are no +@samp{@@ifpdf} or @samp{@@pdf} commands as with the other output +formats. Despite the `portable' in the name, PDF files are nowhere near as -portable in practice as the plain ASCII formats (Info, HTML) Texinfo -also supports (portability relative to DVI is arguable). They also tend -to be much larger and do not support the bitmap fonts used by @TeX{} (by +portable in practice as the plain ASCII formats (Info, HTML) that +Texinfo supports (DVI portability is arguable). They also tend to be +much larger and do not support the bitmap fonts used by @TeX{} (by default) very well. Nevertheless, a PDF file does preserve an actual -printed document on a screen as faithfully as possible, unlike HTML, -say, so have their place. +printed document on a screen as faithfully as possible, so it has its place. PDF support in Texinfo is fairly rudimentary. @@ -13537,15 +13709,15 @@ PDF support in Texinfo is fairly rudimentary. @node Creating and Installing Info Files @chapter Creating and Installing Info Files -This chapter describes how to create and install info files. @xref{Info +This chapter describes how to create and install Info files. @xref{Info Files}, for general information about the file format itself. - @menu * Creating an Info File:: -* Install an Info File:: +* Installing an Info File:: @end menu + @node Creating an Info File @section Creating an Info File @cindex Creating an Info file @@ -13558,7 +13730,7 @@ file, HTML file, or plain text. @code{texinfo-format-region} and Texinfo to Info. For information on installing the Info file in the Info system, -@pxref{Install an Info File}. +@pxref{Installing an Info File}. @menu * makeinfo advantages:: @code{makeinfo} provides better error checking. @@ -13668,6 +13840,10 @@ can probably never be implemented in @TeX{}. It also makes @samp{--no-validate} is used. @xref{Pointer Validation}, for more details. +@item --docbook +@opindex --docbook +Generate DocBook output rather than Info. + @item --error-limit=@var{limit} @itemx -e @var{limit} @opindex --error-limit=@var{limit} @@ -13714,7 +13890,11 @@ created. With this option, they are preserved. Print a usage message listing all available options, then exit successfully. @item --html -Generate HTML output rather than Info. @xref{makeinfo html}. +@opindex --html +Generate HTML output rather than Info. @xref{makeinfo html}. By +default, the HTML output is split into one output file per source node, +and the split output is written into a subdirectory with the name of the +top-level info file. @item -I @var{dir} @opindex -I @var{dir} @@ -13796,8 +13976,8 @@ Specify that the output should be directed to @var{file} and not to the file name specified in the @code{@@setfilename} command found in the Texinfo source (@pxref{setfilename}). If @var{file} is @samp{-}, output goes to standard output and @samp{--no-split} is implied. For split -HTML output, @var{file} is the name of the output file for the top node -(@pxref{makeinfo html}). +HTML output, @var{file} is the name for the directory into which all +HTML nodes are written (@pxref{makeinfo html}). @item -P @var{dir} @opindex -P @var{dir} @@ -13850,6 +14030,10 @@ warnings. @opindex -V Print the version number, then exit successfully. +@item --xml +@opindex --xml +Generate XML output rather than Info. + @end table @@ -14205,14 +14389,26 @@ Info-validate}.@refill @subsection Generating HTML @cindex HTML -As an alternative to the normal Info format output you can use the +Besides generating output in the Info format, you can use the @samp{--html} option to generate output in HTML format, for installation -on a web site (for example). In this release, HTML output from -@code{makeinfo} is monolithic, splitting the output by chapter or node -is not supported. We hope to implement this feature soon. - -The HTML output file is named according to @code{@@setfilename}, but -with any @samp{.info} extension replaced with @samp{.html}. +on a web site (for example). By default, the HTML output is split at +node level. + +When splitting, the HTML output files are written into a subdirectory. +The subdirectory is named according to the name from +@code{@@setfilename} with any extension removed; for example, HTML +output for @code{@@setfilename emacs.info} would be written into a +subdirectory named @samp{emacs}. If that directory cannot be created +for any reason, then @samp{.html} is appended to the directory name, as +in @samp{emacs.html} (this is necessary because sometimes the info file +is named without an extension, e.g., @samp{texinfo}). If the +@samp{@var{name}.html} directory can't be created either, +@code{makeinfo} gives up. In any case, the top-level output file within +the directory is always named @samp{index.html}. + +Monolithic output (@code{--no-split}) is named according to +@code{@@setfilename} or @code{--outfile}. Cross-document node +references are not supported in monolithic HTML. Texinfo input marked up with the @code{@@ifhtml} command will produce output only with the @samp{--html} option supplied. Input marked up @@ -14221,29 +14417,26 @@ the normal escaping of input @samp{<}, @samp{>} and @samp{&} characters which have special significance in HTML). The @samp{--footnote-style} option is currently ignored for HTML output; -footnotes are hyperlinked at the end of the output file. +footnotes are linked to the end of the output file. -The HTML generated is mostly standard (i.e., HTML 2.0, RFC1866). The +The HTML generated is mostly standard (i.e., HTML 2.0, RFC-1866). The exception is that HTML 3.2 tables are generated from the @code{@@multitable} command, but tagged to degrade as well as possible in browsers without table support. Please report output from an -error-free run of @code{makeinfo} which violates the HTML 3.2 DTD as a -bug. +error-free run of @code{makeinfo} which violates the @w{HTML 3.2} DTD as +a bug. Navigation bars are inserted at the start of nodes, similarly to Info output. The @samp{--no-headers} option will suppress this if used with @samp{--no-split}. Header @code{<link>} elements in split output can support info-like navigation with browsers like Lynx and @w{Emacs W3} -which implement this @w{HTML 1.0} feature. You still won't normally get -the multi-file regexp and index search facilities provided by Info -readers. Otherwise, hyperlinks are generated from Texinfo commands -where appropriate. @samp{@@xref} commands to other documents are -generated assuming the other document is available in HTML form too, and -@samp{.html} is appended to the @samp{@@xref} Info file name. This -presumably will often not work. +which implement this @w{HTML 1.0} feature. @samp{@@xref} commands to +other documents are generated assuming the other document is available +in split HTML form, and installed in the same HTML documentation tree, +at @file{../<info-document>/}. -@node Install an Info File +@node Installing an Info File @section Installing an Info File @cindex Installing an Info file @cindex Info file installation @@ -14285,7 +14478,7 @@ this:@refill text editor. * Texinfo: (texinfo). With one source file, make either a printed manual using - TeX or an Info file. + @@TeX@{@} or an Info file. @dots{} @end group @end example @@ -14316,9 +14509,9 @@ true in general, it is a special case for @file{dir}. @node New Info File @subsection Listing a New Info File -@cindex Adding a new info file -@cindex Listing a new info file -@cindex New info file, listing it in @file{dir} file +@cindex Adding a new Info file +@cindex Listing a new Info file +@cindex New Info file, listing it in @file{dir} file @cindex Info file, listing a new @cindex @file{dir} file listing @@ -14391,23 +14584,23 @@ standard @file{dir} file:@refill In this case, the absolute file name of the @file{info-test} file is written as the second part of the menu entry.@refill -Alternatively, you could write the following in your @file{.emacs} -file:@refill +Alternatively, you could write the following in your @file{.emacs} file: @vindex Info-directory-list @example @group (require 'info) (setq Info-directory-list - (cons (expand-file-name "/home/bob/info") Info-directory-list)) + (cons (expand-file-name "/home/bob/info") + Info-directory-list)) @end group @end example -This tells Emacs to merge the @file{dir} file from the -@file{/home/bob/info} directory with the system @file{dir} file. Info -will list the @file{/home/bob/info/info-test} file as a menu entry in -the @file{/home/bob/info/dir} file. Emacs does the merging only -when @kbd{M-x info} is first run, so if you want to set +This tells Emacs to merge the system @file{dir} file with the @file{dir} +file in @file{/home/bob/info}. Thus, Info will list the +@file{/home/bob/info/info-test} file as a menu entry in the +@file{/home/bob/info/dir} file. Emacs does the merging only when +@kbd{M-x info} is first run, so if you want to set @code{Info-directory-list} in an Emacs session where you've already run @code{info}, you must @code{(setq Info-dir-contents nil)} to force Emacs to recompose the @file{dir} file. @@ -14461,7 +14654,7 @@ merges any files named @file{dir} in any directory listed in the @env{INFOPATH} variable into a single menu presented to you in the node called @samp{(dir)Top}. -@cindex @samp{:} @r{last in @env{INFOPATH}} +@cindex colon, last in @env{INFOPATH} However you set @env{INFOPATH}, if its last character is a colon@footnote{On MS-DOS/MS-Windows systems, use semi-colon instead.}, this is replaced by the default (compiled-in) path. This gives you a way to @@ -14485,7 +14678,7 @@ copying an existing @file{dir} file and replace all the text after the special CTRL-_ characters that Info needs will be present. -@node Installing Dir Entries, Invoking install-info, Other Info Directories, Install an Info File +@node Installing Dir Entries @subsection Installing Info Directory Files When you install an Info file onto your system, you can use the program @@ -14536,12 +14729,22 @@ If you use @code{@@dircategory} more than once in the Texinfo source, each usage specifies the `current' category; any subsequent @code{@@direntry} commands will add to that category. -Here are some recommended @code{@@dircategory} categories: `GNU -packages', `GNU programming tools', `GNU programming documentation', -`GNU Emacs Lisp', `GNU libraries', `Linux', `TeX', `Individual -utilities'. The idea is to include the `invoking' node for every -program installed by a package under `Individual utilities', and an -entry for the manual as a whole in the appropriate other category. +Here are some recommended @code{@@dircategory} categories: + +@display +GNU packages +GNU programming tools +GNU programming documentation +GNU Emacs Lisp +GNU libraries +Linux +TeX +Individual utilities +@end display + +The idea is to include the `Invoking' node for every program installed +by a package under `Individual utilities', and an entry for the manual +as a whole in the appropriate other category. @node Invoking install-info @@ -14750,6 +14953,9 @@ capital letters, such as `NASA'. @xref{acronym,, @code{acronym}}. Generate the uppercase and lowercase AE ligatures, respectively: @AE{}, @ae{}. @xref{Inserting Accents}. +@itemx @@afivepaper +Change page dimensions for the A5 paper size. @xref{A4 Paper}. + @item @@afourlatex @itemx @@afourpaper @itemx @@afourwide @@ -15052,8 +15258,13 @@ Format a unit of measure, as in 12@dmn{pt}. Causes @TeX{} to insert a thin space before @var{dimension}. No effect in Info. @xref{dmn, , @code{@@dmn}}. +@item @@documentdescription +Set the document description text, included in the HTML output. Pair +with @code{@@end documentdescription}. @xref{documentdescription,, +@code{@@documentdescription}}. + @item @@documentencoding @var{enc} -Declare the input encoding as @var{enc}. +Declare the input encoding to be @var{enc}. @xref{documentencoding,, @code{@@documentencoding}}. @item @@documentlanguage @var{CC} @@ -15245,9 +15456,10 @@ Begin a stretch of text that will not appear in either the Info file or the printed output. Pair with @code{@@end ignore}. @xref{Comments, , Comments and Ignored Text}.@refill -@item @@image@{@var{filename}, [@var{width}], [@var{height}]@} +@item @@image@{@var{filename}, [@var{width}], [@var{height}], [@var{alt}], [@var{ext}]@} Include graphics image in external @var{filename} scaled to the given -@var{width} and/or @var{height}. @xref{Images}. +@var{width} and/or @var{height}, using @var{alt} text and looking for +@samp{@var{filename}.@var{ext}} in HTML. @xref{Images}. @item @@include @var{filename} Incorporate the contents of the file @var{filename} into the Info file @@ -15503,7 +15715,8 @@ command even if the @code{@@shortcontents} command is not there. @xref{Contents}. @item @@settitle @var{title} -Provide a title for page headers in a printed manual. +Provide a title for page headers in a printed manual, and the default +document description for HTML @samp{<head>}. @xref{settitle, , @code{@@settitle}}.@refill @item @@shortcontents @@ -15521,28 +15734,23 @@ rather than the regular 8.5 by 11 inch format. @xref{smallbook, , Printing Small Books}. Also, see @ref{small}. @item @@smalldisplay -Begin a kind of example. Like @code{@@smallexample} (indent text, no -filling), but do not select the fixed-width font. In @code{@@smallbook} -format, print text in a smaller font than with @code{@@display}. Pair -with @code{@@end smalldisplay}. @xref{small}. +Begin a kind of example. Like @code{@@smallexample} (narrow margins, no +filling), but do not select the fixed-width font. Pair with @code{@@end +smalldisplay}. @xref{small}. @item @@smallexample Indent text to indicate an example. Do not fill, select fixed-width -font. In @code{@@smallbook} format, print text in a smaller font than -with @code{@@example}. Pair with @code{@@end smallexample}. +font, narrow the margins. In printed manuals, print text in a smaller +font than with @code{@@example}. Pair with @code{@@end smallexample}. @xref{small}. @item @@smallformat Begin a kind of example. Like @code{@@smalldisplay}, but do not narrow -the margins and do not select the fixed-width font. -In @code{@@smallbook} format, print text in a smaller font than -with @code{@@format}. Pair with @code{@@end smallformat}. -@xref{small}. +the margins. Pair with @code{@@end smallformat}. @xref{small}. @item @@smalllisp -Begin an example of Lisp code. Indent text, do not fill, select -fixed-width font. In @code{@@smallbook} format, print text in a -smaller font. Pair with @code{@@end smalllisp}. @xref{small}. +Begin an example of Lisp code. Same as @code{@@smallexample}. Pair +with @code{@@end smalllisp}. @xref{small}. @item @@sp @var{n} Skip @var{n} blank lines. @xref{sp, , @code{@@sp}}.@refill @@ -15735,6 +15943,19 @@ Highlight a metasyntactic variable, which is something that stands for another piece of text. @xref{var, , Indicating Metasyntactic Variables}.@refill +@item @@verb@{@var{delim} @var{literal} @var{delim}@} +Output @var{literal}, delimited by the single character @var{delim}, +exactly as is (in the fixed-width font), including any whitespace or +Texinfo special characters. @xref{verb,,@code{verb}}. + +@item @@verbatim +Output the text of the environment exactly as is (in the fixed-width +font). Pair with @code{@@end verbatim}. @xref{verbatim,,@code{verbatim}}. + +@item @@verbatiminclude @var{filename} +Output the contents of @var{filename} exactly as is (in the fixed-width font). +@xref{verbatiminclude,,@code{verbatiminclude}}. + @item @@vindex @var{entry} Add @var{entry} to the index of variables. @xref{Index Entries, , Defining the Entries of an Index}.@refill @@ -16125,12 +16346,12 @@ file, but only when the command is used inside parentheses. You can invoke programs such as Emacs, GCC, and @code{gawk} from a shell. The documentation for each program should contain a section that describes this. Unfortunately, if the node names and titles for these -sections are all different, readers find it hard to search for the -section.@refill +sections are all different, they are difficult for users to find. + +So, there is a convention to name such sections with a phrase beginning +with the word `Invoking', as in `Invoking Emacs'; this way, users can +find the section easily. -Name such sections with a phrase beginning with the word -@w{`Invoking @dots{}'}, as in `Invoking Emacs'; this way -users can find the section easily. @subsubheading ANSI C Syntax @@ -16224,27 +16445,30 @@ You can see this file, with comments, in the first chapter. @@settitle Sample Document @@c %**end of header -@@setchapternewpage odd - @@ifinfo This is a short example of a complete Texinfo file. -Copyright 1990 Free Software Foundation, Inc. +Copyright (C) 2002 Free Software Foundation, Inc. @@end ifinfo @@titlepage -@@sp 10 @@comment The title is printed in a large font. -@@center @@titlefont@{Sample Title@} +@@title Sample Title @@c The following two commands start the copyright page. @@page @@vskip 0pt plus 1filll -Copyright @@copyright@{@} 1990 Free Software Foundation, Inc. +Copyright @@copyright@{@} 2002 Free Software Foundation, Inc. @@end titlepage -@@node Top, First Chapter, , (dir) -@@comment node-name, next, previous, up +@@c Output the table of the contents at the beginning. +@@contents + +@@ifnottex +@@node Top + +This is the top node of a sample document. +@@end ifnottex @@menu * First Chapter:: The first chapter is the @@ -16252,10 +16476,10 @@ Copyright @@copyright@{@} 1990 Free Software Foundation, Inc. * Concept Index:: This index has two entries. @@end menu -@@node First Chapter, Concept Index, Top, Top -@@comment node-name, next, previous, up + +@@node First Chapter @@chapter First Chapter -@@cindex Sample index entry +@@cindex Chapter, first This is the contents of the first chapter. @@cindex Another sample index entry @@ -16270,165 +16494,20 @@ This is the first item. This is the second item. @@end enumerate -The @@code@{makeinfo@} and @@code@{texinfo-format-buffer@} -commands transform a Texinfo file such as this into -an Info file; and @@TeX@{@} typesets it for a printed -manual. +The @@code@{makeinfo@} command transforms a Texinfo source file +such as this into an Info file or HTML; and @@TeX typesets it +for a printed manual. -@@node Concept Index, , First Chapter, Top -@@comment node-name, next, previous, up + +@@node Concept Index @@unnumbered Concept Index @@printindex cp -@@contents @@bye @end example -@node Sample Permissions -@appendix Sample Permissions -@cindex Permissions -@cindex Sample permissions -@cindex Copying permissions - -Texinfo files should contain sections that tell the readers that they -have the right to copy and distribute the Texinfo file, the Info file, -and the printed manual.@refill - -Also, if you are writing a manual about software, you should explain -that the software is free and either include the GNU General Public -License (GPL) or provide a reference to it. @xref{Distrib, , -Distribution, emacs, The GNU Emacs Manual}, for an example of the text -that could be used in the software ``Distribution'', ``General Public -License'', and ``NO WARRANTY'' sections of a document. @xref{Copying, -, Texinfo Copying Conditions}, for an example of a brief explanation -of how the copying conditions provide you with rights. @refill - -@menu -* Inserting Permissions:: How to put permissions in your document. -* ifinfo Permissions:: Sample @samp{ifinfo} copying permissions. -* Titlepage Permissions:: Sample Titlepage copying permissions. -@end menu - -@node Inserting Permissions, ifinfo Permissions, Sample Permissions, Sample Permissions -@ifinfo -@section Inserting Permissions -@end ifinfo - -In a Texinfo file, the first @code{@@ifinfo} section usually begins -with a line that says what the file documents. This is what a person -reading the unprocessed Texinfo file or using the advanced Info -command @kbd{g *} sees first. @inforef{Expert, Advanced Info -commands, info}, for more information. (A reader using the regular -Info commands usually starts reading at the first node and skips -this first section, which is not in a node.)@refill - -In the @code{@@ifinfo} section, the summary sentence is followed by a -copyright notice and then by the copying permission notice. One of -the copying permission paragraphs is enclosed in @code{@@ignore} and -@code{@@end ignore} commands. This paragraph states that the Texinfo -file can be processed through @TeX{} and printed, provided the printed -manual carries the proper copying permission notice. This paragraph -is not made part of the Info file since it is not relevant to the Info -file; but it is a mandatory part of the Texinfo file since it permits -people to process the Texinfo file in @TeX{} and print the -results.@refill - -In the printed manual, the Free Software Foundation copying permission -notice follows the copyright notice and publishing information and is -located within the region delineated by the @code{@@titlepage} and -@code{@@end titlepage} commands. The copying permission notice is exactly -the same as the notice in the @code{@@ifinfo} section except that the -paragraph enclosed in @code{@@ignore} and @code{@@end ignore} commands is -not part of the notice.@refill - -To make it simple to insert a permission notice into each section of -the Texinfo file, sample permission notices for each section are -reproduced in full below.@refill - -You may need to specify the correct name of a section mentioned in the -permission notice. For example, in @cite{The GDB Manual}, the name of -the section referring to the General Public License is called the ``GDB -General Public License'', but in the sample shown below, that section is -referred to generically as the ``GNU General Public License''. If the -Texinfo file does not carry a copy of the General Public License, leave -out the reference to it, but be sure to include the rest of the -sentence. - -@node ifinfo Permissions, Titlepage Permissions, Inserting Permissions, Sample Permissions -@comment node-name, next, previous, up -@section @samp{ifinfo} Copying Permissions -@cindex @samp{ifinfo} permissions - -In the @code{@@ifinfo} section of a Texinfo file, the standard Free -Software Foundation permission notice reads as follows:@refill - -@example -This file documents @dots{} - -Copyright 1999 Free Software Foundation, Inc. - -Permission is granted to make and distribute verbatim -copies of this manual provided the copyright notice and -this permission notice are preserved on all copies. - -@@ignore -Permission is granted to process this file through TeX -and print the results, provided the printed document -carries a copying permission notice identical to this -one except for the removal of this paragraph (this -paragraph not being relevant to the printed manual). - -@@end ignore -Permission is granted to copy and distribute modified -versions of this manual under the conditions for -verbatim copying, provided also that the sections -entitled ``Copying'' and ``GNU General Public License'' -are included exactly as in the original, and provided -that the entire resulting derived work is distributed -under the terms of a permission notice identical to this -one. - -Permission is granted to copy and distribute -translations of this manual into another language, -under the above conditions for modified versions, -except that this permission notice may be stated in a -translation approved by the Free Software Foundation. -@end example - -@node Titlepage Permissions, , ifinfo Permissions, Sample Permissions -@comment node-name, next, previous, up -@section Titlepage Copying Permissions -@cindex Titlepage permissions - -In the @code{@@titlepage} section of a Texinfo file, the standard Free -Software Foundation copying permission notice follows the copyright -notice and publishing information. The standard phrasing is as -follows:@refill - -@example -Permission is granted to make and distribute verbatim -copies of this manual provided the copyright notice and -this permission notice are preserved on all copies. - -Permission is granted to copy and distribute modified -versions of this manual under the conditions for -verbatim copying, provided also that the sections -entitled ``Copying'' and ``GNU General Public License'' -are included exactly as in the original, and provided -that the entire resulting derived work is distributed -under the terms of a permission notice identical to this -one. - -Permission is granted to copy and distribute -translations of this manual into another language, -under the above conditions for modified versions, -except that this permission notice may be stated in a -translation approved by the Free Software Foundation. -@end example - - @node Include Files @appendix Include Files @cindex Include files @@ -16440,7 +16519,7 @@ created. Index entries from the included file are incorporated into the indices of the output file.@refill Include files let you keep a single large document as a collection of -conveniently small parts.@refill +conveniently small parts. @menu * Using Include Files:: How to use the @code{@@include} command. @@ -16570,7 +16649,8 @@ with a numeric prefix argument, such as @kbd{C-u 8}, the command updates @strong{every} pointer and menu in @strong{all} the files and then inserts a master menu.@refill -@node Include File Requirements, Sample Include File, texinfo-multiple-files-update, Include Files + +@node Include File Requirements @section Include File Requirements @cindex Include file requirements @cindex Requirements for include files @@ -16627,7 +16707,7 @@ would insert a main or master menu:@refill @group @@page @@vskip 0pt plus 1filll -Copyright @@copyright@{@} 1999 Free Software Foundation, Inc. +Copyright @@copyright@{@} 2002 Free Software Foundation, Inc. @@end titlepage @end group @@ -16680,8 +16760,8 @@ Manual} is named @file{elisp.texi}. This outer file contains a master menu with 417 entries and a list of 41 @code{@@include} files.@refill -@node Include Files Evolution, , Sample Include File, Include Files -@comment node-name, next, previous, up + +@node Include Files Evolution @section Evolution of Include Files When Info was first created, it was customary to create many small @@ -18372,6 +18452,405 @@ Insert the current date. @end ignore +@node Documentation Copying +@appendix GNU Free Documentation License + +@cindex FDL, GNU Free Documentation License +@center Version 1.1, March 2000 + +@display +Copyright @copyright{} 2000 Free Software Foundation, Inc. +59 Temple Place, Suite 330, Boston, MA 02111-1307, USA + +Everyone is permitted to copy and distribute verbatim copies +of this license document, but changing it is not allowed. +@end display + +@enumerate 0 +@item +PREAMBLE + +The purpose of this License is to make a manual, textbook, or other +written document @dfn{free} in the sense of freedom: to assure everyone +the effective freedom to copy and redistribute it, with or without +modifying it, either commercially or noncommercially. Secondarily, +this License preserves for the author and publisher a way to get +credit for their work, while not being considered responsible for +modifications made by others. + +This License is a kind of ``copyleft'', which means that derivative +works of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft +license designed for free software. + +We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference. + +@item +APPLICABILITY AND DEFINITIONS + +This License applies to any manual or other work that contains a +notice placed by the copyright holder saying it can be distributed +under the terms of this License. The ``Document'', below, refers to any +such manual or work. Any member of the public is a licensee, and is +addressed as ``you''. + +A ``Modified Version'' of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. + +A ``Secondary Section'' is a named appendix or a front-matter section of +the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall subject +(or to related matters) and contains nothing that could fall directly +within that overall subject. (For example, if the Document is in part a +textbook of mathematics, a Secondary Section may not explain any +mathematics.) The relationship could be a matter of historical +connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding +them. + +The ``Invariant Sections'' are certain Secondary Sections whose titles +are designated, as being those of Invariant Sections, in the notice +that says that the Document is released under this License. + +The ``Cover Texts'' are certain short passages of text that are listed, +as Front-Cover Texts or Back-Cover Texts, in the notice that says that +the Document is released under this License. + +A ``Transparent'' copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, whose contents can be viewed and edited directly and +straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available +drawing editor, and that is suitable for input to text formatters or +for automatic translation to a variety of formats suitable for input +to text formatters. A copy made in an otherwise Transparent file +format whose markup has been designed to thwart or discourage +subsequent modification by readers is not Transparent. A copy that is +not ``Transparent'' is called ``Opaque''. + +Examples of suitable formats for Transparent copies include plain +@sc{ascii} without markup, Texinfo input format, La@TeX{} input format, +@acronym{SGML} or @acronym{XML} using a publicly available +@acronym{DTD}, and standard-conforming simple @acronym{HTML} designed +for human modification. Opaque formats include PostScript, +@acronym{PDF}, proprietary formats that can be read and edited only by +proprietary word processors, @acronym{SGML} or @acronym{XML} for which +the @acronym{DTD} and/or processing tools are not generally available, +and the machine-generated @acronym{HTML} produced by some word +processors for output purposes only. + +The ``Title Page'' means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, ``Title Page'' means +the text near the most prominent appearance of the work's title, +preceding the beginning of the body of the text. + +@item +VERBATIM COPYING + +You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies +to the Document are reproduced in all copies, and that you add no other +conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in section 3. + +You may also lend copies, under the same conditions stated above, and +you may publicly display copies. + +@item +COPYING IN QUANTITY + +If you publish printed copies of the Document numbering more than 100, +and the Document's license notice requires Cover Texts, you must enclose +the copies in covers that carry, clearly and legibly, all these Cover +Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on +the back cover. Both covers must also clearly and legibly identify +you as the publisher of these copies. The front cover must present +the full title with all words of the title equally prominent and +visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve +the title of the Document and satisfy these conditions, can be treated +as verbatim copying in other respects. + +If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. + +If you publish or distribute Opaque copies of the Document numbering +more than 100, you must either include a machine-readable Transparent +copy along with each Opaque copy, or state in or with each Opaque copy +a publicly-accessible computer-network location containing a complete +Transparent copy of the Document, free of added material, which the +general network-using public has access to download anonymously at no +charge using public-standard network protocols. If you use the latter +option, you must take reasonably prudent steps, when you begin +distribution of Opaque copies in quantity, to ensure that this +Transparent copy will remain thus accessible at the stated location +until at least one year after the last time you distribute an Opaque +copy (directly or through your agents or retailers) of that edition to +the public. + +It is requested, but not required, that you contact the authors of the +Document well before redistributing any large number of copies, to give +them a chance to provide you with an updated version of the Document. + +@item +MODIFICATIONS + +You may copy and distribute a Modified Version of the Document under +the conditions of sections 2 and 3 above, provided that you release +the Modified Version under precisely this License, with the Modified +Version filling the role of the Document, thus licensing distribution +and modification of the Modified Version to whoever possesses a copy +of it. In addition, you must do these things in the Modified Version: + +@enumerate A +@item +Use in the Title Page (and on the covers, if any) a title distinct +from that of the Document, and from those of previous versions +(which should, if there were any, be listed in the History section +of the Document). You may use the same title as a previous version +if the original publisher of that version gives permission. + +@item +List on the Title Page, as authors, one or more persons or entities +responsible for authorship of the modifications in the Modified +Version, together with at least five of the principal authors of the +Document (all of its principal authors, if it has less than five). + +@item +State on the Title page the name of the publisher of the +Modified Version, as the publisher. + +@item +Preserve all the copyright notices of the Document. + +@item +Add an appropriate copyright notice for your modifications +adjacent to the other copyright notices. + +@item +Include, immediately after the copyright notices, a license notice +giving the public permission to use the Modified Version under the +terms of this License, in the form shown in the Addendum below. + +@item +Preserve in that license notice the full lists of Invariant Sections +and required Cover Texts given in the Document's license notice. + +@item +Include an unaltered copy of this License. + +@item +Preserve the section entitled ``History'', and its title, and add to +it an item stating at least the title, year, new authors, and +publisher of the Modified Version as given on the Title Page. If +there is no section entitled ``History'' in the Document, create one +stating the title, year, authors, and publisher of the Document as +given on its Title Page, then add an item describing the Modified +Version as stated in the previous sentence. + +@item +Preserve the network location, if any, given in the Document for +public access to a Transparent copy of the Document, and likewise +the network locations given in the Document for previous versions +it was based on. These may be placed in the ``History'' section. +You may omit a network location for a work that was published at +least four years before the Document itself, or if the original +publisher of the version it refers to gives permission. + +@item +In any section entitled ``Acknowledgments'' or ``Dedications'', +preserve the section's title, and preserve in the section all the +substance and tone of each of the contributor acknowledgments +and/or dedications given therein. + +@item +Preserve all the Invariant Sections of the Document, +unaltered in their text and in their titles. Section numbers +or the equivalent are not considered part of the section titles. + +@item +Delete any section entitled ``Endorsements''. Such a section +may not be included in the Modified Version. + +@item +Do not retitle any existing section as ``Endorsements'' +or to conflict in title with any Invariant Section. +@end enumerate + +If the Modified Version includes new front-matter sections or +appendices that qualify as Secondary Sections and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the +list of Invariant Sections in the Modified Version's license notice. +These titles must be distinct from any other section titles. + +You may add a section entitled ``Endorsements'', provided it contains +nothing but endorsements of your Modified Version by various +parties---for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of a +standard. + +You may add a passage of up to five words as a Front-Cover Text, and a +passage of up to 25 words as a Back-Cover Text, to the end of the list +of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already +includes a cover text for the same cover, previously added by you or +by arrangement made by the same entity you are acting on behalf of, +you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. + +The author(s) and publisher(s) of the Document do not by this License +give permission to use their names for publicity for or to assert or +imply endorsement of any Modified Version. + +@item +COMBINING DOCUMENTS + +You may combine the Document with other documents released under this +License, under the terms defined in section 4 above for modified +versions, provided that you include in the combination all of the +Invariant Sections of all of the original documents, unmodified, and +list them all as Invariant Sections of your combined work in its +license notice. + +The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name but +different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original +author or publisher of that section if known, or else a unique number. +Make the same adjustment to the section titles in the list of +Invariant Sections in the license notice of the combined work. + +In the combination, you must combine any sections entitled ``History'' +in the various original documents, forming one section entitled +``History''; likewise combine any sections entitled ``Acknowledgments'', +and any sections entitled ``Dedications''. You must delete all sections +entitled ``Endorsements.'' + +@item +COLLECTIONS OF DOCUMENTS + +You may make a collection consisting of the Document and other documents +released under this License, and replace the individual copies of this +License in the various documents with a single copy that is included in +the collection, provided that you follow the rules of this License for +verbatim copying of each of the documents in all other respects. + +You may extract a single document from such a collection, and distribute +it individually under this License, provided you insert a copy of this +License into the extracted document, and follow this License in all +other respects regarding verbatim copying of that document. + +@item +AGGREGATION WITH INDEPENDENT WORKS + +A compilation of the Document or its derivatives with other separate +and independent documents or works, in or on a volume of a storage or +distribution medium, does not as a whole count as a Modified Version +of the Document, provided no compilation copyright is claimed for the +compilation. Such a compilation is called an ``aggregate'', and this +License does not apply to the other self-contained works thus compiled +with the Document, on account of their being thus compiled, if they +are not themselves derivative works of the Document. + +If the Cover Text requirement of section 3 is applicable to these +copies of the Document, then if the Document is less than one quarter +of the entire aggregate, the Document's Cover Texts may be placed on +covers that surround only the Document within the aggregate. +Otherwise they must appear on covers around the whole aggregate. + +@item +TRANSLATION + +Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of section 4. +Replacing Invariant Sections with translations requires special +permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include a +translation of this License provided that you also include the +original English version of this License. In case of a disagreement +between the translation and the original English version of this +License, the original English version will prevail. + +@item +TERMINATION + +You may not copy, modify, sublicense, or distribute the Document except +as expressly provided for under this License. Any other attempt to +copy, modify, sublicense or distribute the Document is void, and will +automatically terminate your rights under this License. However, +parties who have received copies, or rights, from you under this +License will not have their licenses terminated so long as such +parties remain in full compliance. + +@item +FUTURE REVISIONS OF THIS LICENSE + +The Free Software Foundation may publish new, revised versions +of the GNU Free Documentation License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. See +@uref{http://www.gnu.org/copyleft/}. + +Each version of the License is given a distinguishing version number. +If the Document specifies that a particular numbered version of this +License ``or any later version'' applies to it, you have the option of +following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation. +@end enumerate + +@page +@appendixsubsec ADDENDUM: How to use this License for your documents + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and +license notices just after the title page: + +@smallexample +@group + Copyright (C) @var{year} @var{your name}. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.1 + or any later version published by the Free Software Foundation; + with the Invariant Sections being @var{list their titles}, with the + Front-Cover Texts being @var{list}, and with the Back-Cover Texts being @var{list}. + A copy of the license is included in the section entitled ``GNU + Free Documentation License''. +@end group +@end smallexample + +If you have no Invariant Sections, write ``with no Invariant Sections'' +instead of saying which ones are invariant. If you have no +Front-Cover Texts, write ``no Front-Cover Texts'' instead of +``Front-Cover Texts being @var{list}''; likewise for Back-Cover Texts. + +If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, +to permit their use in free software. + + @node Command and Variable Index @unnumbered Command and Variable Index |
