diff options
Diffstat (limited to 'contrib/texinfo/doc/texinfo.txi')
| -rw-r--r-- | contrib/texinfo/doc/texinfo.txi | 5783 |
1 files changed, 3475 insertions, 2308 deletions
diff --git a/contrib/texinfo/doc/texinfo.txi b/contrib/texinfo/doc/texinfo.txi index ab7e112..15ef1dd 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.48 2003/06/02 12:32:28 karl Exp $ +@c $Id: texinfo.txi,v 1.128 2004/12/29 15:06:41 karl Exp $ @c Ordinarily, Texinfo files have the extension .texi. But texinfo.texi @c clashes with texinfo.tex on 8.3 filesystems, so we use texinfo.txi. @@ -27,7 +27,6 @@ @syncodeindex vr cp @syncodeindex pg cp -@footnotestyle separate @paragraphindent 2 @c finalout @@ -39,7 +38,7 @@ a documentation system that can produce both online information and a printed manual from a single source. Copyright (C) 1988, 1990, 1991, 1992, 1993, 1995, 1996, 1997, 1998, -1999, 2000, 2001, 2002, 2003 Free Software Foundation, Inc. +1999, 2000, 2001, 2002, 2003, 2004 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -60,6 +59,7 @@ Software Foundation raise funds for GNU development.'' * Texinfo: (texinfo). The GNU documentation format. * install-info: (texinfo)Invoking install-info. Update info/dir entries. * texi2dvi: (texinfo)Format with texi2dvi. Print Texinfo documents. +* texi2pdf: (texinfo)PDF Output. PDF output for Texinfo. * texindex: (texinfo)Format with tex/texindex. Sort Texinfo index files. * makeinfo: (texinfo)Invoking makeinfo. Translate Texinfo source. @end direntry @@ -82,7 +82,7 @@ Software Foundation raise funds for GNU development.'' @c nwnode (Same as node, but no warnings; for `makeinfo'.) -@shorttitlepage Texinfo +@shorttitlepage GNU Texinfo @titlepage @title Texinfo @@ -131,44 +131,41 @@ the menu lists all the lower level nodes in the document. @end ifnottex @menu -* Copying Conditions:: Your rights. -* Overview:: Texinfo in brief. -* Texinfo Mode:: How to use Texinfo mode. -* Beginning a File:: What is at the beginning of a Texinfo file? -* Ending a File:: What is at the end of a Texinfo file? -* Structuring:: How to create chapters, sections, subsections, - appendices, and other parts. -* Nodes:: How to write nodes. -* Menus:: How to write menus. -* Cross References:: How to write cross references. -* Marking Text:: How to mark words and phrases as code, - keyboard input, meta-syntactic - variables, and the like. -* Quotations and Examples:: How to write quotations, examples, etc. -* Lists and Tables:: How to write lists and tables. -* Indices:: How to create indices. -* Insertions:: How to insert @@-signs, braces, etc. -* Breaks:: How to force and prevent line and page breaks. -* Definition Commands:: How to describe functions and the like - in a uniform manner. -* Conditionals:: How to specify text for either @TeX{} or Info. -* Internationalization:: -* Defining New Texinfo Commands:: -* Hardcopy:: How to convert a Texinfo file to a file - for printing and how to print that file. -* Creating and Installing Info Files:: -* Command List:: All the Texinfo @@-commands. -* Tips:: Hints on how to write a Texinfo document. -* Sample Texinfo Files:: Complete examples, including full texts. -* Include Files:: How to incorporate other Texinfo files. -* Headings:: How to write page headings and footings. -* Catching Mistakes:: How to find formatting mistakes. -* Refilling Paragraphs:: All about paragraph refilling. -* Command Syntax:: A description of @@-Command syntax. -* Obtaining TeX:: How to Obtain @TeX{}. -* Copying This Manual:: The GNU Free Documentation License. -* Command and Variable Index:: A menu containing commands and variables. -* Concept Index:: A menu covering many topics. +* Copying Conditions:: Your rights. +* Overview:: Texinfo in brief. +* Texinfo Mode:: Using the GNU Emacs Texinfo mode. +* Beginning a File:: What is at the beginning of a Texinfo file? +* Ending a File:: What is at the end of a Texinfo file? +* Structuring:: Creating chapters, sections, appendices, etc. +* Nodes:: Writing nodes, the basic unit of Texinfo. +* Menus:: Writing menus. +* Cross References:: Writing cross references. +* Marking Text:: Marking words and phrases as code, + keyboard input, meta-syntactic + variables, and the like. +* Quotations and Examples:: Block quotations, examples, etc. +* Lists and Tables:: Itemized or numbered lists, and tables. +* Special Displays:: Floating figures and footnotes. +* Indices:: Creating indices. +* Insertions:: Inserting @@-signs, braces, etc. +* Breaks:: Forcing or preventing line and page breaks. +* Definition Commands:: Describing functions and the like uniformly. +* Conditionals:: Specifying text for only some output cases. +* Internationalization:: Supporting languages other than English. +* Defining New Texinfo Commands:: User-defined macros and aliases. +* Hardcopy:: Output for paper, with @TeX{}. +* Creating and Installing Info Files:: Details on Info output. +* Generating HTML:: Details on HTML output. + +* Command List:: All the Texinfo @@-commands. +* Tips:: Hints on how to write a Texinfo document. +* Sample Texinfo Files:: Complete examples, including full texts. +* Include Files:: How to incorporate other Texinfo files. +* Headings:: How to write page headings and footings. +* Catching Mistakes:: How to find formatting mistakes. +* Copying This Manual:: The GNU Free Documentation License. +* Command and Variable Index:: A menu containing commands and variables. +* Concept Index:: A menu covering many topics. @detailmenu --- The Detailed Node Listing --- @@ -231,8 +228,8 @@ Texinfo File Header Document Permissions -* copying:: Declare the document's copying permissions. -* insertcopying:: Where to insert the permissions. +* copying:: Declare the document's copying permissions. +* insertcopying:: Where to insert the permissions. Title and Copyright Pages @@ -302,7 +299,7 @@ The @code{@@node} Command Menus -* Menu Location:: Put a menu in a short node. +* Menu Location:: Menus go at the ends of short nodes. * Writing a Menu:: What is a menu? * Menu Parts:: A menu entry has three parts. * Less Cluttered Menu Entry:: Two part menu entry. @@ -349,8 +346,9 @@ Indicating Definitions, Commands, etc. * option:: Indicating option names. * dfn:: Specifying definitions. * cite:: Referring to books not in the Info system. +* abbr:: Indicating abbreviations. * acronym:: Indicating acronyms. -* url:: Indicating a World Wide Web reference. +* indicateurl:: Indicating a World Wide Web reference. * email:: Indicating an electronic mail address. Emphasizing Text @@ -390,16 +388,38 @@ Making a Two-column Table * ftable vtable:: Automatic indexing for two-column tables. * itemx:: How to put more entries in the first column. -Multi-column Tables +@code{@@multitable}: Multi-column Tables * Multitable Column Widths:: Defining multitable column widths. * Multitable Rows:: Defining multitable rows, with examples. +Special Displays + +* Floats:: Figures, tables, and the like. +* Images:: Including graphics and images. +* Footnotes:: Writing footnotes. + +Floats + +* float:: Producing floating material. +* caption shortcaption:: Specifying descriptions for floats. +* listoffloats:: A table of contents for floats. + +Inserting Images + +* Image Syntax:: +* Image Scaling:: + +Footnotes + +* Footnote Commands:: How to write a footnote in Texinfo. +* Footnote Styles:: Controlling how footnotes appear in Info. + Indices * Index Entries:: Choose different words for index entries. * Predefined Indices:: Use different indices for different kinds - of entry. + of entries. * Indexing Commands:: How to make an index entry. * Combining Indices:: How to combine indices. * New Indices:: How to define your own indices. @@ -413,25 +433,25 @@ Combining Indices Special Insertions -* Braces Atsigns:: How to insert braces, @samp{@@}. +* Atsign Braces Comma:: Inserting @@ and @{@} and ,. * Inserting Space:: How to insert the right amount of space within a sentence. * Inserting Accents:: How to insert accents and special characters. * Dots Bullets:: How to insert dots and bullets. * TeX and copyright:: How to insert the @TeX{} logo and the copyright symbol. +* euro:: How to insert the Euro currency symbol. * pounds:: How to insert the pounds currency symbol. * minus:: How to insert a minus sign. * math:: How to format a mathematical expression. * Glyphs:: How to indicate results of evaluation, expansion of macros, errors, etc. -* Footnotes:: How to include footnotes. -* Images:: How to include graphics. -Inserting @@ and Braces +Inserting @@ and @{@} and @comma{} -* Inserting An Atsign:: How to insert @samp{@@}. -* Inserting Braces:: How to insert @samp{@{} and @samp{@}}. +* Inserting an Atsign:: +* Inserting Braces:: +* Inserting a Comma:: Inserting Space @@ -445,10 +465,11 @@ Inserting Ellipsis and Bullets * dots:: How to insert dots @dots{} * bullet:: How to insert a bullet. -Inserting @TeX{} and the Copyright Symbol +Inserting @TeX{} and Legal Symbols: @copyright{}, @registeredsymbol{} -* tex:: How to insert the @TeX{} logo. -* copyright symbol:: How to use @code{@@copyright@{@}}. +* tex:: The @TeX{} logos. +* copyright symbol:: The copyright symbol (c in a circle). +* registered symbol:: The registered symbol (R in a circle). Glyphs for Examples @@ -469,17 +490,7 @@ Glyphs Summary * Equivalence:: * Point Glyph:: -Footnotes - -* Footnote Commands:: How to write a footnote in Texinfo. -* Footnote Styles:: Controlling how footnotes appear in Info. - -Inserting Images - -* Image Syntax:: -* Image Scaling:: - -Making and Preventing Breaks +Forcing and Preventing Breaks * Break Commands:: Summary of break-related commands. * Line Breaks:: Forcing line breaks. @@ -493,13 +504,13 @@ Making and Preventing Breaks Definition Commands -* Def Cmd Template:: How to structure a description using a - definition command. -* Optional Arguments:: How to handle optional and repeated arguments. -* deffnx:: How to group two or more `first' lines. -* Def Cmds in Detail:: All the definition commands. +* Def Cmd Template:: Writing descriptions using definition commands. +* Def Cmd Continuation Lines:: Continuing the heading over source lines. +* Optional Arguments:: Handling optional and repeated arguments. +* deffnx:: Group two or more `first' lines. +* Def Cmds in Detail:: Reference for all the definition commands. * Def Cmd Conventions:: Conventions for writing definitions. -* Sample Function Definition:: +* Sample Function Definition:: An example. The Definition Commands @@ -507,17 +518,21 @@ The Definition Commands * Variables Commands:: Commands for variables and similar entities. * Typed Functions:: Commands for functions in typed languages. * Typed Variables:: Commands for variables in typed languages. -* Abstract Objects:: Commands for object-oriented programming. * Data Types:: The definition command for data types. +* Abstract Objects:: Commands for object-oriented programming. + +Object-Oriented Programming + +* Variables: Object-Oriented Variables. +* Methods: Object-Oriented Methods. Conditionally Visible Text -* Conditional Commands:: Specifying text for HTML, Info, or @TeX{}. -* Conditional Not Commands:: Specifying text for not HTML, Info, or @TeX{}. -* Raw Formatter Commands:: Using raw @TeX{} or HTML commands. -* set clear value:: Designating which text to format (for - all output formats); and how to set a - flag to a string that you can insert. +* Conditional Commands:: Text for a given format. +* Conditional Not Commands:: Text for any format other than a given one. +* Raw Formatter Commands:: Using raw formatter commands. +* set clear value:: Variable tests and substitutions. +* Conditional Nesting:: Using conditionals inside conditionals. @code{@@set}, @code{@@clear}, and @code{@@value} @@ -534,7 +549,7 @@ Defining New Texinfo Commands * Defining Macros:: Defining and undefining new commands. * Invoking Macros:: Using a macro, once you've defined it. -* Macro Details:: Beyond basic macro usage. +* Macro Details:: Limitations of Texinfo macros. * alias:: Command aliases. * definfoenclose:: Customized highlighting. @@ -556,6 +571,7 @@ Formatting and Printing Hardcopy * Cropmarks and Magnification:: How to print marks to indicate the size of pages and how to print scaled up output. * PDF Output:: Portable Document Format output. +* Obtaining TeX:: How to Obtain @TeX{}. Creating and Installing Info Files @@ -575,13 +591,6 @@ Creating an Info File * Batch Formatting:: How to format for Info in Emacs Batch mode. * Tag and Split Files:: How tagged and split files help Info to run better. -* Generating HTML:: Generating HTML output with makeinfo. - -Generating HTML - -* HTML Translation:: Details of the HTML output. -* HTML Splitting:: How HTML output is split. -* HTML CSS:: HTML output and Cascading Style Sheets. Installing an Info File @@ -593,6 +602,25 @@ Installing an Info File to the Info directory. * Invoking install-info:: @code{install-info} options. +Generating HTML + +* HTML Translation:: Details of the HTML output. +* HTML Splitting:: How HTML output is split. +* HTML CSS:: Influencing HTML output with Cascading Style Sheets. +* HTML Xref:: Cross-references in HTML output. + +HTML Cross-references + +* Link Basics: HTML Xref Link Basics. +* Node Expansion: HTML Xref Node Name Expansion. +* Command Expansion: HTML Xref Command Expansion. +* 8-bit Expansion: HTML Xref 8-bit Character Expansion. +* Mismatch: HTML Xref Mismatch. + +@@-Command List + +* Command Syntax:: General syntax for varieties of @@-commands. + Sample Texinfo Files * Short Sample Texinfo File:: @@ -608,12 +636,12 @@ Include Files * Using Include Files:: How to use the @code{@@include} command. * texinfo-multiple-files-update:: How to create and update nodes and - menus when using included files. -* Include Files Requirements:: What @code{texinfo-multiple-files-update} expects. + menus when using included files. +* Include Files Requirements:: @code{texinfo-multiple-files-update} needs. * Sample Include File:: A sample outer file with included files - within it; and a sample included file. + within it; and a sample included file. * Include Files Evolution:: How use of the @code{@@include} command - has changed over time. + has changed over time. Page Headings @@ -759,9 +787,9 @@ better to include too much than to leave out something important. @cindex Patches, contributing Patches are most welcome; if possible, please make them with -@samp{@w{diff -c}} (@pxref{Top,, Overview, diffutils, Comparing and -Merging Files}) and include @file{ChangeLog} entries (@pxref{Change -Log,,, emacs, The GNU Emacs Manual}). +@samp{@w{diff -c}} (@pxref{Top,, Overview, diff, Comparing and Merging +Files}) and include @file{ChangeLog} entries (@pxref{Change Log,,, +emacs, The GNU Emacs Manual}). 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 @@ -777,34 +805,14 @@ for email. @cindex Texinfo, introduction to @cindex Introduction to Texinfo -Using Texinfo, you can create a printed document with the normal -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, 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 -from and much stricter than @TeX{}'s usual languages, plain @TeX{} and -La@TeX{}). This creates a DVI file 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. You can install the result in your Info tree -(@pxref{Installing an Info File}). - -To output an HTML file, run @code{makeinfo --html} on your Texinfo -source. You can (for example) install the result on a 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 (a particular form of XML), run @code{makeinfo ---docbook}. If you want to convert from Docbook @emph{to} Texinfo, -please see @uref{http://docbook2X.sourceforge.net/}. +Using Texinfo, you can create a printed document (via the @TeX{} +typesetting system) the normal features of a book, including chapters, +sections, cross references, and indices. From the same Texinfo source +file, you can create an Info file with special features to make +documentation browsing easy. You can also create from that same +source file an HTML output file suitable for use with a web browser, +or an XML file. See the next section (@pxref{Output Formats}) for +details and the exact commands to generate output from the source. @TeX{} works with virtually all printers; Info works with virtually all computer terminals; the HTML output works with virtually all web @@ -813,16 +821,12 @@ browsers. Thus Texinfo can be used by almost any computer user. @cindex Source file format A Texinfo source file is a plain @sc{ascii} file containing text interspersed with @dfn{@@-commands} (words preceded by an @samp{@@}) -that tell the typesetting and formatting programs what to do. You may -edit a Texinfo file with any text editor; but it is especially +that tell the typesetting and formatting programs what to do. You can +edit a Texinfo file with any text editor, but it is especially convenient to use GNU Emacs since that editor has a special mode, called Texinfo mode, that provides various Texinfo-related features. (@xref{Texinfo Mode}.) -Before writing a Texinfo source file, you should learn about nodes, -menus, cross references, and the rest, for example by reading this -manual. - You can use Texinfo to create both online help and printed manuals; moreover, Texinfo is freely redistributable. For these reasons, Texinfo is the official documentation format of the GNU project. More @@ -841,20 +845,21 @@ Texinfo. @table @asis @item Info @cindex Info output -(Generated via @command{makeinfo}.) This format is a plain text -transliteration of the Texinfo source. It uses control characters to -separate nodes and provide other navigational information. See the +(Generated via @command{makeinfo}.) This format is essentially a +plain text transliteration of the Texinfo source. It adds a few +control characters to separate nodes and provide navigational +information for menus, cross-references, indices, and so on. See the next section (@pxref{Info Files}) for more details on this format. The Emacs Info subsystem (@pxref{Top,,Getting Started,info, Info}), -and the standalone @command{info} program (@pxref{info -standalone,,,info-stnd, GNU Info}), among others, can read these +and the standalone @command{info} program (@pxref{Top +,, Info Standalone, info-stnd, GNU Info}), among others, can read these files. @xref{Creating and Installing Info Files}. @item Plain text @cindex Plain text output (Generated via @command{makeinfo --no-headers}.) This is almost the same as Info output, except the navigational control characters are -omitted. +omitted. Also, standard output is used by default. @item HTML @cindex HTML output @@ -873,45 +878,57 @@ details of the HTML language and much related information, see @item DVI @cindex DVI output -@pindex Dvips -@pindex Xdvi +@pindex dvips +@pindex xdvi (Generated via @command{texi2dvi}.) This DeVice Independent binary format is output by the @TeX{} typesetting program -(@uref{http://tug.org}). It is then read by a DVI `driver', which +(@uref{http://tug.org}). This is then read by a DVI `driver', which writes the actual device-specific commands that can be viewed or -printed, notably Dvips for translation to PostScript (@pxref{dvips -invocation,,, dvips, Dvips}) and Xdvi for viewing on an X display +printed, notably Dvips for translation to PostScript (@pxref{Invoking +Dvips,,, dvips, Dvips}) and Xdvi for viewing on an X display (@uref{http://sourceforge.net/projects/xdvi/}). @xref{Hardcopy}. +Be aware that the Texinfo language is very different from and much +stricter than @TeX{}'s usual languages, plain @TeX{} and @LaTeX{}. +For more information on @TeX{} in general, please see the book +@cite{@TeX{} for the Impatient}, available from +@uref{http://savannah.gnu.org/projects/teximpatient}. + @item PDF @cindex PDF output @cindex Beebe, Nelson @pindex pdftex -(Generated via @command{texi2dvi --pdf}.) This format, based on -PostScript, was developed by Adobe Systems for document interchange. -It is intended to be platform-independent and easily viewable, among -other design goals; for a discussion, see -@uref{http://tug.org/tugboat/Articles/tb22-3/tb72beebeI.pdf}. Texinfo -uses the @command{pdftex} program, a variant of @TeX{}, to output pdf; +(Generated via @command{texi2dvi --pdf} or @command{texi2pdf}.) This +was developed by Adobe Systems for portable document interchange, +based on their previous PostScript language. It can represent the exact +appearance of a document, including fonts, and supporting arbitrary +scaling. It is intended to be platform-independent and easily +viewable, among other design goals; for a discussion, see +@uref{http://tug.org/TUGboat/Articles/tb22-3/tb72beebeI.pdf}. Texinfo +uses the @command{pdftex} program, a variant of @TeX{}, to output PDF; see @uref{http://tug.org/applications/pdftex}. @xref{PDF Output}. @item XML @cindex XML output @cindex DTD, for Texinfo XML +@pindex texinfo.dtd (Generated via @command{makeinfo --xml}.) XML is a generic syntax specification usable for any sort of content (see, for example, @uref{http://www.w3.org/XML/}). The @command{makeinfo} xml output, -unlike all the formats above, interprets very little of the Texinfo +unlike all the formats above, interprets very little of the Texinfo source. Rather, it merely translates the Texinfo markup commands into XML syntax, for processing by further XML tools. The particular syntax output is defined in the file @file{texinfo.dtd} included in the Texinfo source distribution. -@item DocBook -@cindex DocBook output -(Generated via @command{makeinfo --docbook}.) This is an XML format -of long standing used primarily for technical documentation. See -@uref{http://www.docbook.org/}. +@item Docbook +@cindex Docbook output +(Generated via @command{makeinfo --docbook}.) This is an XML-based +format developed some years ago, primarily for technical +documentation. It therefore bears some resemblance, in broad +outlines, to Texinfo. See @uref{http://www.docbook.org}. If you want +to convert from Docbook @emph{to} Texinfo, please see +@uref{http://docbook2X.sourceforge.net}. @end table @@ -962,9 +979,7 @@ which are identified by their names. The Info program displays one node at a time, and provides commands with which the user can move to other related nodes. -@ifinfo -@inforef{Top, info, info}, for more information about using Info. -@end ifinfo +@xref{Top,,, info, GNU Info}, for more information about using Info. Each node of an Info file may have any number of child nodes that describe subtopics of the node's topic. The names of child @@ -1020,7 +1035,7 @@ the command line (@pxref{Top,,, info, Info}). If you want to read through an Info file in sequence, as if it were a printed manual, you can hit @key{SPC} repeatedly, or you get the whole -file with the advanced Info command @kbd{g *}. (@inforef{Expert, +file with the advanced Info command @kbd{g *}. (@inforef{Advanced, Advanced Info commands, info}.)@refill @c !!! dir file may be located in one of many places: @@ -1128,9 +1143,8 @@ by @samp{@@}; they are called @dfn{@@-commands}. For example, @code{@@node} is the command to indicate a node and @code{@@chapter} is the command to indicate the start of a chapter.@refill -@quotation -@strong{Please note:} All the @@-commands, with the exception of the -@code{@@TeX@{@}} command, must be written entirely in lower case. +@quotation Note +Almost all @@ command names are entirely lower case. @end quotation The Texinfo @@-commands are a strictly limited set of constructs. The @@ -1194,9 +1208,9 @@ they do not need braces.@refill As you gain experience with Texinfo, you will rapidly learn how to write the different commands: the different ways to write commands -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 +actually make it easier to write and read Texinfo files than if all +commands followed exactly the same syntax. @xref{Command Syntax, , +@@-Command Syntax}, for all the details. @node Conventions @@ -1204,6 +1218,7 @@ syntax, see @ref{Command Syntax, , @@-Command Syntax}.)@refill @cindex General syntactic conventions @cindex Syntactic conventions @cindex Conventions, syntactic +@cindex Characters, basic input This section describes the general conventions used in all Texinfo documents. @@ -1215,7 +1230,7 @@ All printable @sc{ascii} characters except @samp{@@}, @samp{@{} and @samp{@@} is the escape character which introduces commands, while @samp{@{} and @samp{@}} are used to surround arguments to certain commands. To put one of these special characters into the document, put -xan @samp{@@} character in front of it, like this: @samp{@@@@}, +an @samp{@@} character in front of it, like this: @samp{@@@@}, @samp{@@@{}, and @samp{@@@}}. @item @@ -1232,9 +1247,8 @@ paragraph indentation if required (@pxref{noindent,,@code{@@noindent}}). @item @cindex Quotation characters (`'), in source Use doubled single-quote characters to begin and end quotations: -@w{@t{`@w{}`@dots{}'@w{}'}}. (Texinfo takes this convention from -@TeX{}.) @TeX{} converts two single quotes to left- and right-hand -doubled quotation marks, +@w{@t{`@w{}`@dots{}'@w{}'}}. @TeX{} converts two single quotes to +left- and right-hand doubled quotation marks, @c this comes out as "like this" in Info, which is just confusing. @iftex ``like this'', @@ -1242,38 +1256,46 @@ doubled quotation marks, and Info converts doubled single-quote characters to @sc{ascii} double-quotes: @w{@t{`@w{}`@dots{}'@w{}'}} becomes @w{@t{"@dots{}"}}. -@item -@cindex Dashes, in source -Use three hyphens in a row, @samp{---}, for a dash---like this. In -@TeX{}, a single or double hyphen produces a printed dash that is -shorter than the usual typeset dash. Info reduces three hyphens to two -for display on the screen. +You may occasionally need to produce two consecutive single quotes; +for example, in documenting a computer language such as Maxima where +@t{'@w{}'} is a valid command. You can do this with the input +@t{'@@w@{@}'}; the empty @code{@@w} command stops the combination into +the double-quote characters. -@item -If you mark off a region of the Texinfo file with the @code{@@iftex} -and @w{@code{@@end iftex}} commands, that region will appear only in -the printed copy; in that region, you can use certain commands -borrowed from plain @TeX{} that you cannot use in Info. Conversely, -text surrounded by @code{@@ifnottex} and @code{@@end ifnottex} will -appear in all output formats @emph{except} @TeX{}. +@cindex Unicode quotation characters +@cindex Grave accent, vs.@: left quote +The left quote character (@t{`}, ASCII code 96) used in Texinfo is a +grave accent in ANSI and ISO character set standards. We use it as a +quote character because that is how @TeX{} is set up, by default. We +hope to eventually support the various quotation characters in +Unicode. -Each of the other output formats (@code{html}, @code{info}, -@code{plaintext}, @code{xml}) have an analogous pair of commands. -@xref{Conditionals}. +@item +@cindex Multiple dashes in source +@cindex Dashes in source +@cindex Hyphens in source, two or three in a row +@cindex Em dash, producing +@cindex En dash, producing +Use three hyphens in a row, @samp{---}, to produce a long dash---like +this (called an @dfn{em dash}), used for punctuation in sentences. +Use two hyphens, @samp{--}, to produce a medium dash (called an +@dfn{en dash}), used primarily for numeric ranges, as in ``June +25--26''. Use a single hyphen, @samp{-}, to produce a standard hyphen +used in compound words. For display on the screen, Info reduces three +hyphens to two and two hyphens to one (not transitively!). Of course, +any number of hyphens in the source remain as they are in literal +contexts, such as @code{@@code} and @code{@@example}. @item -@iftex -@vskip-@baselineskip -@end iftex @cindex Tabs; don't use! -@quotation -@strong{Caution:} Do not use tab characters in a Texinfo file (except in -verbatim modes)! @TeX{} uses variable-width fonts, which means that it -is impractical at best to define a tab to work in all circumstances. -Consequently, @TeX{} treats tabs like single spaces, and that is not -what they look like. 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 indented text. +@strong{Caution:} Last and most important, do not use tab characters +in a Texinfo file (except in verbatim modes)! @TeX{} uses +variable-width fonts, which means that it is impractical at best to +define a tab to work in all circumstances. Consequently, @TeX{} +treats tabs like single spaces, and that is not what they look like in +the source. Furthermore, @code{makeinfo} does nothing special with +tabs, and thus a tab character in your input file will usually appear +differently in the output. @noindent To avoid this problem, Texinfo mode causes GNU Emacs to insert multiple @@ -1281,10 +1303,9 @@ 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. -@end quotation -@end itemize +to multiple spaces, or use the @code{unexpand} command from the shell. +@end itemize @node Comments @section Comments @@ -1505,7 +1526,7 @@ which it is distributed. @xref{GNU Sample Texts}. @@copying This is a short example of a complete Texinfo file, version 1.0. -Copyright @@copyright@{@} 2003 Free Software Foundation, Inc. +Copyright @@copyright@{@} 2004 Free Software Foundation, Inc. @@end copying @end group @end example @@ -1728,14 +1749,11 @@ chapters which describe the Texinfo formatting language in detail. * Texinfo Mode Summary:: Summary of all the Texinfo mode commands. @end menu -@node Texinfo Mode Overview, Emacs Editing, Texinfo Mode, Texinfo Mode -@ifinfo -@heading Texinfo Mode Overview -@end ifinfo +@node Texinfo Mode Overview +@section Texinfo Mode Overview -Texinfo mode provides special features for working with Texinfo -files. -You can:@refill +Texinfo mode provides special features for working with Texinfo files. +You can: @itemize @bullet @item @@ -1767,7 +1785,7 @@ Typeset and print part or all of a file.@refill Perhaps the two most helpful features are those for inserting frequently used @@-commands and for creating node pointers and menus.@refill -@node Emacs Editing, Inserting, Texinfo Mode Overview, Texinfo Mode +@node Emacs Editing @section The Usual GNU Emacs Editing Commands In most cases, the usual Text mode commands work the same in Texinfo @@ -1808,7 +1826,7 @@ mode as you wish. In particular, the keybindings are very easy to change. The keybindings described here are the default or standard ones.@refill -@node Inserting, Showing the Structure, Emacs Editing, Texinfo Mode +@node Inserting @comment node-name, next, previous, up @section Inserting Frequently Used Commands @cindex Inserting frequently used commands @@ -1950,7 +1968,7 @@ whole job. You must edit the inserted text since a title tends to use the same words as a node name but a useful description uses different words.@refill -@node Showing the Structure, Updating Nodes and Menus, Inserting, Texinfo Mode +@node Showing the Structure @comment node-name, next, previous, up @section Showing the Section Structure of a File @cindex Showing the section structure of a file @@ -2013,7 +2031,7 @@ commands to move forward and backward by chapter, and to use the @xref{Pages, , , emacs, The GNU Emacs Manual}, for more information about the page commands.@refill -@node Updating Nodes and Menus, Info Formatting, Showing the Structure, Texinfo Mode +@node Updating Nodes and Menus @comment node-name, next, previous, up @section Updating Nodes and Menus @cindex Updating nodes and menus @@ -2040,10 +2058,8 @@ node pointers by hand, which is a tedious task.@refill nodes in sequence. @end menu -@node Updating Commands, Updating Requirements, Updating Nodes and Menus, Updating Nodes and Menus -@ifinfo -@subheading The Updating Commands -@end ifinfo +@node Updating Commands +@subsection The Updating Commands You can use the updating commands to:@refill @@ -2196,11 +2212,10 @@ This updates all the nodes and menus.@refill The @code{texinfo-column-for-description} variable specifies the column to which menu descriptions are indented. By default, the value is 32 although it is often useful to reduce it to as low as 24. You -can set the variable with the @kbd{M-x edit-options} command -(@pxref{Edit Options, , Editing Variable Values, emacs, The GNU Emacs -Manual}) or with the @kbd{M-x set-variable} command (@pxref{Examining, -, Examining and Setting Variables, emacs, The GNU Emacs -Manual}).@refill +can set the variable via customization (@pxref{Changing an Option,,, +emacs, The GNU Emacs Manual}) or with the @kbd{M-x set-variable} +command (@pxref{Examining, , Examining and Setting Variables, emacs, +The GNU Emacs Manual}). Also, the @code{texinfo-indent-menu-description} command may be used to indent existing menu descriptions to a specified column. Finally, if @@ -2323,13 +2338,7 @@ update all the menus and all the `Next', `Previous', and `Up' pointers of all the included files before creating and inserting a master menu in the outer file. The @code{texinfo-multiple-files-update} command is described in the appendix on @code{@@include} files. -@ifinfo -@xref{texinfo-multiple-files-update}.@refill -@end ifinfo -@iftex -@xref{texinfo-multiple-files-update, , -@code{texinfo-multiple-files-update}}.@refill -@end iftex +@xref{texinfo-multiple-files-update}. @item M-x texinfo-indent-menu-description @findex texinfo-indent-menu-description @@ -2355,7 +2364,7 @@ interactive), the @code{texinfo-sequential-node-update} command sequentially updates all the nodes in the region.@refill @end table -@node Info Formatting, Printing, Updating Nodes and Menus, Texinfo Mode +@node Info Formatting @comment node-name, next, previous, up @section Formatting for Info @cindex Formatting for Info @@ -2414,9 +2423,9 @@ include a line that has @code{@@setfilename} in its header. @xref{Creating an Info File}, for details about Info formatting.@refill -@node Printing, Texinfo Mode Summary, Info Formatting, Texinfo Mode +@node Printing @comment node-name, next, previous, up -@section Formatting and Printing +@section Printing @cindex Formatting for printing @cindex Printing a region or buffer @cindex Region formatting and printing @@ -2478,7 +2487,7 @@ end-of-header lines.)@refill @xref{Hardcopy}, for a description of the other @TeX{} related commands, such as @code{tex-show-print-queue}.@refill -@node Texinfo Mode Summary, , Printing, Texinfo Mode +@node Texinfo Mode Summary @comment node-name, next, previous, up @section Texinfo Mode Summary @@ -2672,7 +2681,14 @@ document, and the Top node. A table of contents is also generally produced here. This chapter expands on the minimal complete Texinfo source file -previously given (@pxref{Six Parts}). +previously given (@pxref{Six Parts}). It describes the numerous +commands for handling the traditional frontmatter items in Texinfo. + +@cindex Frontmatter, text in +Straight text outside of any command before the Top node should be +avoided. Such text is treated differently in the different output +formats: visible in @TeX{} and HTML, by default not shown in Info +readers, and so on. @menu * Sample Beginning:: A sample beginning for a Texinfo file. @@ -2946,20 +2962,20 @@ anything on the line after the command is considered part of the title, including what would otherwise be a comment. The @code{@@settitle} command should precede everything that generates -actual output in @TeX{}. +actual output. The best place for it is right after the +@code{@@setfilename} command (see the previous section). @cindex <title> HTML tag -In the HTML file produced by @command{makeinfo}, @var{title} also serves -as the document @samp{<title>} and the default document description in -the @samp{<head>} part; see @ref{documentdescription}, for how to change -that. +In the HTML file produced by @command{makeinfo}, @var{title} serves as +the document @samp{<title>}. It also becomes the default document +description in the @samp{<head>} part (@pxref{documentdescription}). The title in the @code{@@settitle} command does not affect the title as it appears on the title page. Thus, the two do not need not match exactly. A practice we recommend is to include the version or edition number of the manual in the @code{@@settitle} title; on the title page, the version number generally appears as a @code{@@subtitle} so it would -be omitted from the @code{@@title}. (@xref{titlepage}.) +be omitted from the @code{@@title}. @xref{titlepage}. Conventionally, when @TeX{} formats a Texinfo file for double-sided output, the title is printed in the left-hand (even-numbered) page @@ -3008,8 +3024,8 @@ this text once, and another command (@code{@@insertcopying}) to insert the text at appropriate points. @menu -* copying:: Declare the document's copying permissions. -* insertcopying:: Where to insert the permissions. +* copying:: Declare the document's copying permissions. +* insertcopying:: Where to insert the permissions. @end menu @@ -3219,8 +3235,8 @@ the sections below. @findex shorttitlepage @cindex Bastard title page @cindex Title page, bastard -For extremely simple applications, and for the bastard title page in -traditional book front matter, Texinfo also provides a command +For extremely simple documents, and for the bastard title page in +traditional book frontmatter, Texinfo also provides a command @code{@@shorttitlepage} which takes the rest of the line as the title. The argument is typeset on a page by itself and followed by a blank page. @@ -3240,6 +3256,11 @@ Use the @code{@@titlefont} command to select a large font suitable for the title itself. You can use @code{@@titlefont} more than once if you have an especially long title. +For HTML output, each @code{@@titlefont} command produces an +@code{<h1>} heading, but the HTML document @code{<title>} is not +affected. For that, you must put an @code{@@settitle} command before +the @code{@@titlefont} command (@pxref{settitle}). + @need 700 For example: @@ -3287,6 +3308,9 @@ A template for this method looks like this: The spacing of the example fits an 8.5 by 11 inch manual. +You can in fact use these commands anywhere, not just on a title page, +but since they are not logical markup commands, we don't recommend +them. @node title subtitle author @subsection @code{@@title}, @code{@@subtitle}, and @code{@@author} @@ -3302,7 +3326,8 @@ needed to adjust vertical spacing. Write the @code{@@title}, @code{@@subtitle}, or @code{@@author} commands at the beginning of a line followed by the title, subtitle, -or author. +or author. These commands are only effective in @TeX{} output; it's +an error to use them anywhere except within @code{@@titlepage}. The @code{@@title} command produces a line in which the title is set flush to the left-hand side of the page in a larger than normal font. @@ -3444,9 +3469,11 @@ Cover art by @dots{} @cindex Titlepage end starts headings @cindex End titlepage starts headings -The @code{@@end titlepage} command must be written on a line by itself. -It not only marks the end of the title and copyright pages, but also -causes @TeX{} to start generating page headings and page numbers. +Like all @code{@@end} commands (@pxref{Quotations and Examples}), the @code{@@end titlepage} command +must be written at the beginning of a line by itself, with only one +space between the @code{@@end} and the @code{titlepage}. It not only +marks the end of the title and copyright pages, but also causes @TeX{} +to start generating page headings and page numbers. To repeat what is said elsewhere, Texinfo has two standard page heading formats, one for documents which are printed on one side of each sheet of paper @@ -3562,9 +3589,10 @@ the manual. To do this, you must use the @code{@@contents} and/or @item @@contents Generates a table of contents in a printed manual, including all chapters, sections, subsections, etc., as well as appendices and -unnumbered chapters. Headings generated by the @code{@@majorheading}, -@code{@@chapheading}, and @code{@@heading} commands do not appear in -the table of contents. +unnumbered chapters. Headings generated by @code{@@majorheading}, +@code{@@chapheading}, and the other @code{@@@dots{}heading} commands +do not appear in the table of contents (@pxref{Structuring Command +Types}). @item @@shortcontents @itemx @@summarycontents @@ -3926,11 +3954,10 @@ Header}. A peculiarity of the @code{texinfo-format-buffer} and @code{texinfo-format-region} commands is that they do not indent (nor fill) paragraphs that contain @code{@@w} or @code{@@*} commands. -@xref{Refilling Paragraphs}, for further information. @node firstparagraphindent -@subsection @code{@@firstparagraphindent}: Indentation After Headings +@subsection @code{@@firstparagraphindent}: Indenting After Headings @cindex First paragraph, suppressing indentation of @cindex Suppressing first paragraph indentation @cindex Preventing first paragraph indentation @@ -3988,7 +4015,8 @@ beginning of a line followed by either @samp{asis} or a number: @@exampleindent @var{indent} @end example -The indentation is according to the value of @var{indent}: +@code{@@exampleindent} is ignored for HTML output. Otherwise, the +indentation is according to the value of @var{indent}: @table @asis @item @code{asis} @@ -4003,8 +4031,9 @@ Indent environments by @var{n} space characters in Info output, by @end table -The default value of @var{indent} is 5. @code{@@exampleindent} is -ignored for HTML output. +The default value of @var{indent} is 5 spaces in Info, and 0.4@dmn{in} +in @TeX{}, which is somewhat less. (The reduction is to help @TeX{} +fit more characters onto physical lines.) It is best to write the @code{@@exampleindent} command before the end-of-header line at the beginning of a Texinfo file, so the region @@ -4067,7 +4096,6 @@ For example: @node Printing Indices & Menus @section Printing Indices and Menus -@findex printindex @cindex Printing an index @cindex Indices, printing and menus @cindex Generating menus with indices @@ -4084,39 +4112,25 @@ process of creating a printed manual, you must run a program called sorted index file. The sorted index file is what is actually used to print the index. -Texinfo offers six separate types of predefined index, each with a -two-letter abbreviation, as illustrated in the following table. -However, you may merge indices (@pxref{Combining Indices}) or define -your own indices (@pxref{New Indices}). - -Here are the predefined indices, their abbreviations, and the -corresponding index entry commands: - -@table @samp -@item cp -concept index (@code{@@cindex}) -@item fn -function index (@code{@@findex}) -@item vr -variable index (@code{@@index}) -@item ky -key index (@code{@@kindex}) -@item pg -program index (@code{@@pindex}) -@item tp -data type index (@code{@@tindex}) -@end table - -The @code{@@printindex} command takes a two-letter index abbreviation, -reads the corresponding sorted index file and formats it appropriately -into an index. +Texinfo offers six separate types of predefined index, which suffice +in most cases. @xref{Indices}, for information on this, as well +defining your own new indices, combining indices, and, most +importantly advice on writing the actual index entries. This section +focuses on printing indices, which is done with the +@code{@@printindex} command. -The @code{@@printindex} command does not generate a chapter heading for -the index. Consequently, you should precede the @code{@@printindex} -command with a suitable section or chapter command (usually -@code{@@appendix} or @code{@@unnumbered}) to supply the chapter heading -and put the index into the table of contents. Precede the -@code{@@unnumbered} command with an @code{@@node} line. +@findex printindex +@code{@@printindex} takes one argument, a two-letter index +abbreviation. It reads the corresponding sorted index file (for +printed output), and formats it appropriately into an index. + +The @code{@@printindex} command does not generate a chapter heading +for the index, since different manuals have different needs. +Consequently, you should precede the @code{@@printindex} command with +a suitable section or chapter command (usually @code{@@appendix} or +@code{@@unnumbered}) to supply the chapter heading and put the index +into the table of contents. Precede the chapter heading with an +@code{@@node} line as usual. For example: @@ -4136,11 +4150,44 @@ For example: @end group @end smallexample -@noindent +If you have more than one index, we recommend placing the concept index last. + +@itemize +@item +In printed output, @code{@@printindex} produces a traditional +two-column index, with dot leaders between the index terms and page +numbers. -We recommend placing the concept index last, since that makes it easiest -to find. We also recommend having a single index whenever possible, -since then readers have only one place to look (@pxref{Combining Indices}). +@item +In Info output, @code{@@printindex} produces a special menu containing +the line number of the entry, relative to the start of the node. Info +readers can use this to go to the exact line of an entry, not just the +containing node. (Older Info readers will just go to the node.) +Here's an example: + +@smallexample +* First index entry: Top. (line 7) +@end smallexample + +@noindent The actual number of spaces is variable, to right-justify +the line number; it's been reduced here to make the line fit in the +printed manual. + +@item +In plain text output, @code{@@printindex} produces the same menu, but +the line numbers are relative to the start of the file, since that's +more convenient for that format. + +@item +In HTML and Docbook output, @code{@@printindex} produces links +to the index entries. + +@item +In XML output, it simply records the index to be printed. +@end itemize + +It's not possible to generate an index when writing to standard +output; @command{makeinfo} generates a warning in this case. @node File End @@ -4271,17 +4318,20 @@ its table of contents.@refill The @code{@@unnumbered} series of commands produce unnumbered entries both in the body of a printed work and in its table of contents. The @code{@@top} command, which has a special use, is a member of this -series (@pxref{makeinfo top, , @code{@@top}}).@refill +series (@pxref{makeinfo top, , @code{@@top}}). An @code{@@unnumbered} +section should be associated with a node and be a normal part of the +document structure. @item -The @code{@@heading} series of commands produce unnumbered headings -that do not appear in a table of contents. The heading commands never -start a new page.@refill +The @code{@@heading} series of commands produce simple unnumbered +headings that do not appear in a table of contents, are not associated +with nodes, and cannot be cross-referenced. The heading commands +never start a new page. @item -The @code{@@majorheading} command produces results similar to using -the @code{@@chapheading} command but generates a larger vertical -whitespace before the heading.@refill +The @code{@@majorheading} command is similar to @code{@@chapheading}, +except that it generates a larger vertical whitespace before the +heading. @item When an @code{@@setchapternewpage} command says to do so, the @@ -4299,7 +4349,7 @@ Here are the four groups of chapter structuring commands: @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 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} @@ -4318,7 +4368,7 @@ The @code{@@top} command is a special sectioning command that you use only after an @samp{@@node Top} line at the beginning of a Texinfo file. The @code{@@top} command tells the @code{makeinfo} formatter which node is the `Top' node, so it can use it as the root of the node tree if your -manual uses implicit pointers. It has the same typesetting effect as +manual uses implicit node pointers. It has the same typesetting effect as @code{@@unnumbered} (@pxref{unnumbered & appendix, , @code{@@unnumbered} and @code{@@appendix}}). For detailed information, see @ref{makeinfo top command, , The @code{@@top} Command}. @@ -4328,7 +4378,7 @@ an @code{@@ifnottex} conditional so that it will appear only in Info and HTML output, not @TeX{}. -@node chapter, unnumbered & appendix, makeinfo top, Structuring +@node chapter @comment node-name, next, previous, up @section @code{@@chapter} @findex chapter @@ -4385,7 +4435,7 @@ line and follow it on the same line by the title, as you would if you were creating a chapter.@refill -@node majorheading & chapheading, section, unnumbered & appendix, Structuring +@node majorheading & chapheading @section @code{@@majorheading}, @code{@@chapheading} @findex majorheading @findex chapheading @@ -4399,7 +4449,7 @@ or an entry in the table of contents; and neither command causes In @TeX{}, an @code{@@majorheading} command generates a larger vertical whitespace before the heading than an @code{@@chapheading} command but -is otherwise the same.@refill +is otherwise the same. In Info, the @code{@@majorheading} and @@ -4407,7 +4457,8 @@ the @code{@@majorheading} and @code{@@chapter}: the title is printed on a line by itself with a line of asterisks underneath. (@xref{chapter, , @code{@@chapter}}.)@refill -@node section, unnumberedsec appendixsec heading, majorheading & chapheading, Structuring + +@node section @comment node-name, next, previous, up @section @code{@@section} @findex section @@ -4447,7 +4498,8 @@ This is a section @noindent in Info. -@node unnumberedsec appendixsec heading, subsection, section, Structuring + +@node unnumberedsec appendixsec heading @comment node-name, next, previous, up @section @code{@@unnumberedsec}, @code{@@appendixsec}, @code{@@heading} @findex unnumberedsec @@ -4479,7 +4531,8 @@ You may use the @code{@@heading} command anywhere you wish for a section-style heading that will not appear in the table of contents.@refill @end table -@node subsection, unnumberedsubsec appendixsubsec subheading, unnumberedsec appendixsec heading, Structuring + +@node subsection @comment node-name, next, previous, up @section The @code{@@subsection} Command @findex subsection @@ -4505,7 +4558,7 @@ This is a subsection In a printed manual, subsections are listed in the table of contents and are numbered three levels deep.@refill -@node unnumberedsubsec appendixsubsec subheading, subsubsection, subsection, Structuring +@node unnumberedsubsec appendixsubsec subheading @comment node-name, next, previous, up @section The @code{@@subsection}-like Commands @cindex Subsection-like commands @@ -4528,8 +4581,7 @@ subsection-like heading labelled with a letter and numbers; both of these commands produce headings that appear in the table of contents.@refill -@node subsubsection, Raise/lower sections, unnumberedsubsec appendixsubsec subheading, Structuring -@comment node-name, next, previous, up +@node subsubsection @section The `subsub' Commands @cindex Subsub commands @findex subsubsection @@ -4583,66 +4635,29 @@ This is a subsubsection @end group @end example -@node Raise/lower sections, , subsubsection, Structuring -@comment node-name, next, previous, up + +@node Raise/lower sections @section @code{@@raisesections} and @code{@@lowersections} @findex raisesections @findex lowersections @cindex Raising and lowering sections +@cindex Lowering and raising sections @cindex Sections, raising and lowering -The @code{@@raisesections} and @code{@@lowersections} commands raise and -lower the hierarchical level of chapters, sections, subsections and the -like. The @code{@@raisesections} command changes sections to chapters, -subsections to sections, and so on. The @code{@@lowersections} command -changes chapters to sections, sections to subsections, and so on. - -@cindex Include files, and section levels -An @code{@@lowersections} command is useful if you wish to include text -that is written as an outer or standalone Texinfo file in another -Texinfo file as an inner, included file. If you write the command at -the beginning of the file, all your @code{@@chapter} commands are -formatted as if they were @code{@@section} commands, all your -@code{@@section} command are formatted as if they were -@code{@@subsection} commands, and so on. - -@need 1000 -@code{@@raisesections} raises a command one level in the chapter -structuring hierarchy:@refill - -@example -@group - @r{Change} @r{To} - -@@subsection @@section, -@@section @@chapter, -@@heading @@chapheading, - @r{etc.} -@end group -@end example - -@need 1000 -@code{@@lowersections} lowers a command one level in the chapter -structuring hierarchy:@refill +The @code{@@raisesections} and @code{@@lowersections} commands +implicitly raise and lower the hierarchical level of following +chapters, sections and the other sectioning commands. -@example -@group - @r{Change} @r{To} +That is, the @code{@@raisesections} command changes sections to +chapters, subsections to sections, and so on. Conversely, the +@code{@@lowersections} command changes chapters to sections, sections +to subsections, and so on. Thus, an @code{@@lowersections} command +cancels an @code{@@raisesections} command, and vice versa. -@@chapter @@section, -@@subsection @@subsubsection, -@@heading @@subheading, - @r{etc.} -@end group -@end example - -An @code{@@raisesections} or @code{@@lowersections} command changes only -those structuring commands that follow the command in the Texinfo file. -Write an @code{@@raisesections} or @code{@@lowersections} command on a -line of its own. - -An @code{@@lowersections} command cancels an @code{@@raisesections} -command, and vice versa. Typically, the commands are used like this: +@cindex Include files, and section levels +You can use @code{@@lowersections} to include text written as an outer +or standalone Texinfo file in another Texinfo file as an inner, +included file. Typical usage looks like this: @example @@lowersections @@ -4650,27 +4665,51 @@ command, and vice versa. Typically, the commands are used like this: @@raisesections @end example -Without the @code{@@raisesections}, all the subsequent sections in your -document will be lowered. +@noindent (Without the @code{@@raisesections}, all the subsequent +sections in the document would be lowered.) -Repeated use of the commands continue to raise or lower the hierarchical -level a step at a time. +If the included file being lowered has a @code{@@top} node, you'll +need to conditionalize its inclusion with a flag (@pxref{set value}). + +Another difficulty can arise with documents that use the (recommended) +feature of @command{makeinfo} for implicitly determining node +pointers. Since @command{makeinfo} must assume a hierarchically +organized document to determine the pointers, you cannot just +arbitrarily sprinkle @code{@@raisesections} and @code{@@lowersections} +commands in the document. The final result has to have menus that +take the raising and lowering into account. Therefore, as a practical +matter, you generally only want to raise or lower large chunks, +usually in external files as shown above. + +Repeated use of the commands continue to raise or lower the +hierarchical level a step at a time. An attempt to raise above +`chapter' reproduces chapter commands; an attempt to lower below +`subsubsection' reproduces subsubsection commands. Also, lowered +subsubsections and raised chapters will not work with +@command{makeinfo}'s feature of implicitly determining node pointers, +since the menu structure won't be correct. + +Write each @code{@@raisesections} and @code{@@lowersections} command +on a line of its own. -An attempt to raise above `chapters' reproduces chapter commands; an -attempt to lower below `subsubsections' reproduces subsubsection -commands. @node Nodes @chapter Nodes @dfn{Nodes} are the primary segments of a Texinfo file. They do not -themselves impose a hierarchical or any other kind of structure on a file. -Nodes contain @dfn{node pointers} that name other nodes, and can contain -@dfn{menus} which are lists of nodes. In Info, the movement commands -can carry you to a pointed-to node or to a node listed in a menu. Node -pointers and menus provide structure for Info files just as chapters, -sections, subsections, and the like, provide structure for printed -books.@refill +in and of themselves impose a hierarchical or any other kind of +structure on a file. Nodes contain @dfn{node pointers} that name +other nodes, and can contain @dfn{menus} which are lists of nodes. In +Info, the movement commands can carry you to a pointed-to node or to a +node listed in a menu. + +Node pointers and menus provide structure for Info files just as +chapters, sections, subsections, and the like, provide structure for +printed books. + +Because node names are used in cross-references, it is not desirable +to casually change them. Such name changes invalidate references from +other manuals, from mail archives, and so on. @menu * Two Paths:: Different commands to structure @@ -4758,7 +4797,7 @@ This @code{@@node} line says that the name of this node is ``Chapter hierarchically organized (@pxref{makeinfo Pointer Creation}), but the pointer relationships still obtain. -@quotation +@quotation Note @strong{Please Note:} `Next' refers to the next node at the same hierarchical level in the manual, not necessarily to the next node within the Texinfo file. In the Texinfo file, the subsequent node may @@ -4859,8 +4898,8 @@ immediately after an @code{@@node} line---for example, an @code{@@section} or @code{@@subsection} line. (@xref{Structuring Command Types}.) -@quotation -@strong{Please note:} The GNU Emacs Texinfo mode updating commands work +@quotation Note +The GNU Emacs Texinfo mode updating commands work only with Texinfo files in which @code{@@node} lines are followed by chapter structuring lines. @xref{Updating Requirements}. @end quotation @@ -5020,9 +5059,10 @@ node containing the pointer. @item @@-commands in node names are not allowed. 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}.) +@code{@{}, and accent commands such as @samp{@@'}. (For a few cases +when this is useful, Texinfo has limited support for using +@w{@@-commands} in node names; see @ref{Pointer Validation}.) Perhaps +this limitation will be removed some day. @item @cindex Colon in nodename @@ -5033,7 +5073,8 @@ limited support for using @w{@@-commands} in node names; see @cindex Invalid characters in node names @cindex Node names, invalid characters in Unfortunately, you cannot use periods, commas, colons or parentheses -within a node name; these confuse the Texinfo processors. +within a node name; these confuse the Texinfo processors. Perhaps +this limitation will be removed some day, too. @need 700 For example, the following is a section title in this manual: @@ -5051,7 +5092,22 @@ unnumberedsec appendixsec heading @cindex Case in node name @item -Case is significant. +Case is significant in node names. + +@cindex White space in node name +@cindex Spaces in node name +Spaces before and after names on the @samp{@@node} line are ignored, +but spaces ``inside'' a name are significant. For example: + +@example +@@node foo bar, +@@node foo bar , +@@node foo bar , +@end example + +@noindent all define the same node, @samp{foo bar}. References to the +node should all use that name, without the leading or trailing spaces, +but with the internal spaces. @end itemize @@ -5149,8 +5205,8 @@ Thus, in practice, a Top node starts like this: @cindex Pointer creation with @code{makeinfo} @cindex Automatic pointer creation with @code{makeinfo} -The @code{makeinfo} program has a feature for automatically defining -node pointers for a hierarchically organized file. +The @code{makeinfo} program has a feature for automatically determining +node pointers for a hierarchically organized document. When you take advantage of this feature, you do not need to write the `Next', `Previous', and `Up' pointers after the name of a node. @@ -5166,15 +5222,18 @@ Finally, you must write the name of each node (except for the `Top' node) in a menu that is one or more hierarchical levels above the node's hierarchical level. -This 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}.) +This implicit 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. +required to be organized hierarchically or in fact to contain +sectioning commands at all (for example, if you never intend the +document to be printed). The special procedure for handling the short +text before a menu (@pxref{Menus}) also disables this +feature, for that group of nodes. In those cases, you will need to +explicitly specify the pointers. @node anchor @@ -5227,25 +5286,19 @@ an argument. (@xref{goto-node,,,info-stnd,GNU Info}.) @cindex Menus @findex menu -@dfn{Menus} contain pointers to subordinate nodes.@footnote{Menus can -carry you to any node, regardless of the hierarchical structure; even to -nodes in a different Info file. However, the GNU Emacs Texinfo mode -updating commands work only to create menus of subordinate nodes. -Conventionally, cross references are used to refer to other nodes.} In -Info, you use menus to go to such nodes. Menus have no effect in -printed manuals and do not appear in them. - -By convention, a menu is put at the end of a node since a reader who -uses the menu may not see text that follows it. Furthermore, a node -that has a menu should not contain much text. If you have a lot of text -and a menu, move most of the text into a new subnode---all but a few -lines. Otherwise, a reader with a terminal that displays only a few -lines may miss the menu and its associated text. As a practical matter, -you should locate a menu within 20 lines of the beginning of the -node. +@dfn{Menus} contain pointers to subordinate nodes. In online output, +you use menus to go to such nodes. Menus have no effect in printed +manuals and do not appear in them. + +A node with a menu should not contain much text. If you find yourself +writing a lot of before a menu, we generally recommend moving most of +the text into a new subnode---all but a paragraph or two. Otherwise, +a reader with a terminal that displays only a few lines may miss the +menu and its associated text. As a practical matter, it is best to +locate a menu within 20 or so lines of the beginning of the node. @menu -* Menu Location:: Put a menu in a short node. +* Menu Location:: Menus go at the ends of short nodes. * Writing a Menu:: What is a menu? * Menu Parts:: A menu entry has three parts. * Less Cluttered Menu Entry:: Two part menu entry. @@ -5254,59 +5307,53 @@ node. @end menu -@node Menu Location, Writing a Menu, Menus, Menus -@ifinfo -@heading Menus Need Short Nodes -@end ifinfo +@node Menu Location +@section Menu Location @cindex Menu location @cindex Location of menus -@cindex Nodes for menus are short -@cindex Short nodes for menus - -The short text before a menu may look awkward in a printed manual. To -avoid this, you can write a menu near the beginning of its node and -follow the menu by an @code{@@node} line, and then an @code{@@heading} -line located within @code{@@ifinfo} and @code{@@end ifinfo}. This way, -the menu, @code{@@node} line, and title appear only in the Info file, -not the printed document. - -For example, the preceding two paragraphs follow an Info-only menu, -@code{@@node} line, and heading, and look like this: - -@example -@group -@@menu -* Menu Location:: Put a menu in a short node. -* Writing a Menu:: What is a menu? -* Menu Parts:: A menu entry has three parts. -* Less Cluttered Menu Entry:: Two part menu entry. -* Menu Example:: Two and three part entries. -* Other Info Files:: How to refer to a different - Info file. -@@end menu -@@node Menu Location, Writing a Menu, , Menus -@@ifinfo -@@heading Menus Need Short Nodes -@@end ifinfo -@end group -@end example - -The Texinfo file for this document contains a number of -examples of this procedure; one is at the beginning of this chapter. - - -@node Writing a Menu, Menu Parts, Menu Location, Menus +A menu must be located at the end of a node, without any regular text +or additional commands between the @code{@@end menu} and the beginning +of the next node. (As a consequence, there may be at most one menu in +a node.) + +@cindex Info format, and menus +This is actually a useful restriction, since a reader who uses the +menu could easily miss any such text. Technically, it is necessary +because in Info format, there is no marker for the end of a menu, so +Info-reading programs would have no way to know when the menu ends and +normal text resumes. + +@cindex Hierarchical documents, and menus +Technically, menus can carry you to any node, regardless of the +structure of the document; even to nodes in a different Info file. +However, we do not recommend ever making use of this, because the +@command{makeinfo} implicit pointer creation feature (@pxref{makeinfo +Pointer Creation}) and GNU Emacs Texinfo mode updating commands work +only to create menus of subordinate nodes in a hierarchically +structured document. Instead, use cross references to refer to +arbitrary nodes. + +In the past, we recommended using a @samp{@@heading} command within an +@code{@@ifinfo} conditional instead of the normal sectioning commands +after a very short node with a menu. This had the advantage of making +the printed output look better, because there was no very short text +between two headings on the page. But aside from not working with +@command{makeinfo}'s implicit pointer creation, it also makes the XML +output incorrect, since it does not reflect the true document +structure. So, unfortunately we can no longer recommend this. + + +@node Writing a Menu @section Writing a Menu @cindex Writing a menu @cindex Menu writing -A menu consists of an @code{@@menu} command on a line by -itself followed by menu entry lines or menu comment lines -and then by an @code{@@end menu} command on a line by -itself.@refill +A menu consists of an @code{@@menu} command on a line by itself +followed by menu entry lines or menu comment lines and then by an +@code{@@end menu} command on a line by itself. -A menu looks like this:@refill +A menu looks like this: @example @group @@ -5331,7 +5378,7 @@ entries. Space characters in a menu are preserved as-is; this allows you to format the menu as you wish. -@node Menu Parts, Less Cluttered Menu Entry, Writing a Menu, Menus +@node Menu Parts @section The Parts of a Menu @cindex Parts of a menu @cindex Menu parts @@ -5372,7 +5419,7 @@ authors prefer to indent the second line while others prefer to align it with the first (and all others). It's up to you. -@node Less Cluttered Menu Entry, Menu Example, Menu Parts, Menus +@node Less Cluttered Menu Entry @comment node-name, next, previous, up @section Less Cluttered Menu Entry @cindex Two part menu entry @@ -5403,7 +5450,7 @@ instead of You should use the node name for the menu entry name whenever possible, since it reduces visual clutter in the menu.@refill -@node Menu Example, Other Info Files, Less Cluttered Menu Entry, Menus +@node Menu Example @comment node-name, next, previous, up @section A Menu Example @cindex Menu example @@ -5473,7 +5520,7 @@ Since no file name is specified with either @samp{Files} or @samp{Buffers}, they must be the names of nodes in the same Info file (@pxref{Other Info Files, , Referring to Other Info Files}).@refill -@node Other Info Files, , Menu Example, Menus +@node Other Info Files @comment node-name, next, previous, up @section Referring to Other Info Files @cindex Referring to other Info files @@ -5565,10 +5612,8 @@ places to which cross references can refer. * uref:: How to refer to a uniform resource locator. @end menu -@node References, Cross Reference Commands, Cross References, Cross References -@ifinfo -@heading What References Are For -@end ifinfo +@node References +@section What References Are For Often, but not always, a printed document should be designed so that it can be read sequentially. People tire of flipping back and forth @@ -5588,9 +5633,9 @@ In a printed manual, a cross reference results in a page reference, unless it is to another manual altogether, in which case the cross reference names that manual.@refill -In Info, a cross reference results in an entry that you can follow using -the Info @samp{f} command. (@inforef{Help-Adv, Some advanced Info -commands, info}.)@refill +In Info, a cross reference results in an entry that you can follow +using the Info @samp{f} command. (@inforef{Help-Xref, Following +cross-references, info}.) The various cross reference commands use nodes (or anchors, @pxref{anchor,,@code{@@anchor}}) to define cross reference locations. @@ -5604,7 +5649,7 @@ printed, and will not be used online, you must nonetheless write references.@refill @need 800 -@node Cross Reference Commands, Cross Reference Parts, References, Cross References +@node Cross Reference Commands @comment node-name, next, previous, up @section Different Cross Reference Commands @cindex Different cross reference commands @@ -5636,7 +5681,7 @@ manual.@refill manuals for which there is no corresponding Info file and, therefore, no node to which to point. @xref{cite, , @code{@@cite}}.)@refill -@node Cross Reference Parts, xref, Cross Reference Commands, Cross References +@node Cross Reference Parts @comment node-name, next, previous, up @section Parts of a Cross Reference @cindex Cross reference parts @@ -5749,7 +5794,7 @@ how Info and @TeX{} format the output of each of the various commands: write @code{@@xref} at the beginning of a sentence; write @code{@@pxref} only within parentheses, and so on.@refill -@node xref, Top Node Naming, Cross Reference Parts, Cross References +@node xref @comment node-name, next, previous, up @section @code{@@xref} @findex xref @@ -5771,10 +5816,8 @@ manual.@refill * Four and Five Arguments:: @code{@@xref} with four and five arguments. @end menu -@node Reference Syntax, One Argument, xref, xref -@ifinfo -@subheading What a Reference Looks Like and Requires -@end ifinfo +@node Reference Syntax +@subsection What a Reference Looks Like and Requires Most often, an Info cross reference looks like this:@refill @@ -5809,8 +5852,8 @@ You must write that period or comma yourself; otherwise, Info will not recognize the end of the reference. (The @code{@@pxref} command works differently. @xref{pxref, , @code{@@pxref}}.)@refill -@quotation -@strong{Please note:} A period or comma @strong{must} follow the closing +@quotation Caution +A period or comma @strong{must} follow the closing brace of an @code{@@xref}. It is required to terminate the cross reference. This period or comma will appear in the output, both in the Info file and in the printed manual.@refill @@ -5826,13 +5869,13 @@ A cross reference requires only the name of a node; but it may contain up to four additional arguments. Each of these variations produces a cross reference that looks somewhat different.@refill -@quotation -@strong{Please note:} Commas separate arguments in a cross reference; +@quotation Note +Commas separate arguments in a cross reference; avoid including them in the title or other part lest the formatters mistake them for separators.@refill @end quotation -@node One Argument, Two Arguments, Reference Syntax, xref +@node One Argument @subsection @code{@@xref} with One Argument The simplest form of @code{@@xref} takes one argument, the name of @@ -5890,7 +5933,7 @@ See Section 3.1 [Tropical Storms], page 24, for more info. (Note that in the preceding example the closing brace is followed by a comma, and then by the clause, which is followed by a period.)@refill -@node Two Arguments, Three Arguments, One Argument, xref +@node Two Arguments @subsection @code{@@xref} with Two Arguments With two arguments, the second is used as the name of the Info cross @@ -5954,7 +5997,7 @@ See Section 5.2 [Electrical Effects], page 57, for more info. (Note that in the preceding example the closing brace is followed by a comma, and then by the clause, which is followed by a period.)@refill -@node Three Arguments, Four and Five Arguments, Two Arguments, xref +@node Three Arguments @subsection @code{@@xref} with Three Arguments A third argument replaces the node name in the @TeX{} output. The third @@ -6052,7 +6095,7 @@ Here are several examples from @cite{The GNU Awk User's Guide}:@refill @@xref@{Regexp, , Regular Expressions as Patterns@}. @end smallexample -@node Four and Five Arguments, , Three Arguments, xref +@node Four and Five Arguments @subsection @code{@@xref} with Four and Five Arguments In a cross reference, a fourth argument specifies the name of another @@ -6166,7 +6209,7 @@ incorporated into the same @TeX{} run but make separate Info files. In this case, you need to specify only the fourth argument, and not the fifth.@refill -@node Top Node Naming, ref, xref, Cross References +@node Top Node Naming @section Naming a `Top' Node @cindex Naming a `Top' Node in references @cindex @samp{@r{Top}} node naming for references @@ -6205,9 +6248,10 @@ See section ``Overview'' in @i{The GNU Make Manual}. @noindent In this example, @samp{Top} is the name of the first node, and -@samp{Overview} is the name of the first section of the manual.@refill -@node ref, pxref, Top Node Naming, Cross References -@comment node-name, next, previous, up +@samp{Overview} is the name of the first section of the manual. + + +@node ref @section @code{@@ref} @cindex Cross references using @code{@@ref} @cindex References using @code{@@ref} @@ -6215,75 +6259,59 @@ In this example, @samp{Top} is the name of the first node, and @code{@@ref} is nearly the same as @code{@@xref} except that it does not generate a `See' in the printed output, just the reference itself. -This makes it useful as the last part of a sentence.@refill +This makes it useful as the last part of a sentence. -@need 700 -@noindent -For example, +@noindent For example, @cindex Hurricanes @example For more information, see @@ref@{Hurricanes@}. @end example -@noindent -produces +@noindent produces (in Info): @example For more information, see *Note Hurricanes::. @end example -@noindent -and +@noindent and (in printed output): @quotation For more information, see Section 8.2 [Hurricanes], page 123. @end quotation -The @code{@@ref} command sometimes leads writers to express themselves -in a manner that is suitable for a printed manual but looks awkward -in the Info format. Bear in mind that your audience will be using -both the printed and the Info format.@refill - -@need 800 -@noindent -For example, +The @code{@@ref} command sometimes tempts writers to express +themselves in a manner that is suitable for a printed manual but looks +awkward in the Info format. Bear in mind that your audience will be +using both the printed and the Info format. For example: @cindex Sea surges @example -@group Sea surges are described in @@ref@{Hurricanes@}. -@end group @end example -@need 800 -@noindent -produces +@noindent looks ok in the printed output: @quotation Sea surges are described in Section 6.7 [Hurricanes], page 72. @end quotation -@need 800 -@noindent -in a printed document, and the following in Info: +@noindent but is awkward to read in Info: @example Sea surges are described in *Note Hurricanes::. @end example -@quotation -@strong{Caution:} You @emph{must} write a period, comma, or right -parenthesis immediately after an @code{@@ref} command with two or more -arguments. Otherwise, Info will not find the end of the cross reference -entry and its attempt to follow the cross reference will fail. As a -general rule, you should write a period or comma after every -@code{@@ref} command. This looks best in both the printed and the Info -output.@refill -@end quotation +As a general rule, you should write a period or comma immediately +after an @code{@@ref} command with two or more arguments. -@node pxref, inforef, ref, Cross References -@comment node-name, next, previous, up +If there is no such following punctuation, @command{makeinfo} will +generate a (grammatically incorrect) period in the Info output; +otherwise, the cross-reference would fail completely, due to the +current syntax of Info format. + + +@node pxref @section @code{@@pxref} @cindex Cross references using @code{@@pxref} @cindex References using @code{@@pxref} @@ -6291,9 +6319,9 @@ output.@refill The parenthetical reference command, @code{@@pxref}, is nearly the same as @code{@@xref}, but you use it @emph{only} inside parentheses -and you do @emph{not} type a comma or period after the command's -closing brace. The command differs from @code{@@xref} in two -ways:@refill +and you do @emph{not} type a comma or period (or anything else) after +the command's closing brace. The command differs from @code{@@xref} +in two ways: @enumerate @item @@ -6308,8 +6336,9 @@ closing colon or period.@refill Because one type of formatting automatically inserts closing punctuation and the other does not, you should use @code{@@pxref} @emph{only} inside parentheses as part of another sentence. Also, you -yourself should not insert punctuation after the reference, as you do -with @code{@@xref}.@refill +yourself should not insert punctuation after the reference (or any +other text), as you do with @code{@@xref}. In the Info +output, such text would follow a period, which is grammatically wrong. @code{@@pxref} is designed so that the output looks right and works right between parentheses both in printed output and in an Info file. @@ -6371,27 +6400,30 @@ and @code{@@pxref} can be used with up to five arguments just like @code{@@xref} (@pxref{xref, , @code{@@xref}}).@refill -@quotation -@strong{Please note:} Use @code{@@pxref} only as a parenthetical +@quotation Caution +Use @code{@@pxref} only as a parenthetical reference. Do not try to use @code{@@pxref} as a clause in a sentence. It will look bad in either the Info file, the printed output, or both.@refill - -Also, parenthetical cross references look best at the ends of sentences. -Although you may write them in the middle of a sentence, that location -breaks up the flow of text.@refill @end quotation -@node inforef, uref, pxref, Cross References +Parenthetical cross references look best at the ends of sentences. +Although they technically work in the middle of a sentence, that +location breaks up the flow of reading. + + +@node inforef @section @code{@@inforef} @cindex Cross references using @code{@@inforef} @cindex References using @code{@@inforef} @findex inforef -@code{@@inforef} is used for cross references to Info files for which -there are no printed manuals. Even in a printed manual, -@code{@@inforef} generates a reference directing the user to look in -an Info file.@refill +@code{@@inforef} is used for making cross references to Info +documents---even from a printed manual. This might be because you +want to refer to conditional @code{@@ifinfo} text +(@pxref{Conditionals}), or because printed output is not available +(perhaps because there is no Texinfo source), among other +possibilities. The command takes either two or three arguments, in the following order:@refill @@ -6421,67 +6453,44 @@ The template is: @need 800 @noindent -Thus, +For example, @example @group -@@inforef@{Expert, Advanced Info commands, info@}, +@@inforef@{Advanced, Advanced Info commands, info@}, for more information. @end group @end example @need 800 @noindent -produces +produces (in Info): @example @group -*Note Advanced Info commands: (info)Expert, +*Note Advanced Info commands: (info)Advanced, for more information. @end group @end example @need 800 @noindent -and +and (in the printed output): @quotation -See Info file @file{info}, node @samp{Expert}, for more information. +See Info file @file{info}, node @samp{Advanced}, for more information. @end quotation -@need 800 -@noindent -Similarly, - -@example -@group -@@inforef@{Expert, , info@}, for more information. -@end group -@end example - -@need 800 -@noindent -produces - -@example -*Note (info)Expert::, for more information. -@end example - -@need 800 -@noindent -and - -@quotation -See Info file @file{info}, node @samp{Expert}, for more information. -@end quotation +(This particular example is not realistic, since the Info manual is +written in Texinfo, so all formats are available.) The converse of @code{@@inforef} is @code{@@cite}, which is used to refer to printed works for which no Info form exists. @xref{cite, , -@code{@@cite}}.@refill +@code{@@cite}}. @node uref -@section @code{@@uref@{@var{url}[, @var{text}][, @var{replacement}]@}} +@section @code{@@url}, @code{@@uref@{@var{url}[, @var{text}][, @var{replacement}]@}} @findex uref @cindex Uniform resource locator, referring to @cindex URL, referring to @@ -6492,6 +6501,12 @@ It takes one mandatory argument, the url, and two optional arguments which control the text that is displayed. In HTML output, @code{@@uref} produces a link you can follow. +@code{@@url} is a synonym for @code{@@uref}. Originally, @code{@@url} +had the meaning of @code{@@indicateurl} +(@pxref{indicateurl,,@code{@@indicateurl}}), but in actual practice it +was misused the vast majority of the time. So we've changed the +definitions. + The second argument, if specified, is the text to display (the default is the url itself); in Info and DVI output, but not in HTML output, the url is also output. @@ -6562,7 +6577,7 @@ 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}}). +@code{@@indicateurl} (@pxref{indicateurl, @code{@@indicateurl}}). Some people prefer to display url's in the unambiguous format: @@ -6599,7 +6614,7 @@ program. Also, you can emphasize text, in several different ways. @end menu -@node Indicating, Emphasis, Marking Text, Marking Text +@node Indicating @section Indicating Definitions, Commands, etc. @cindex Highlighting text @cindex Indicating commands, definitions, etc. @@ -6627,25 +6642,24 @@ not something else that should not be changed.@refill * code:: Indicating program code. * kbd:: Showing keyboard input. * key:: Specifying keys. -* samp:: A literal sequence of characters. -* verb:: A verbatim sequence of characters. +* samp:: Indicating a literal sequence of characters. +* verb:: Indicating a verbatim sequence of characters. * var:: Indicating metasyntactic variables. * env:: Indicating environment variables. * file:: Indicating file names. * command:: Indicating command names. * option:: Indicating option names. * dfn:: Specifying definitions. -* cite:: Referring to books not in the Info system. +* cite:: Referring to books not in the Info system. +* abbr:: Indicating abbreviations. * acronym:: Indicating acronyms. -* url:: Indicating a World Wide Web reference. +* indicateurl:: Indicating an example URL. * email:: Indicating an electronic mail address. @end menu -@node Useful Highlighting, code, Indicating, Indicating -@ifinfo -@subheading Highlighting Commands are Useful -@end ifinfo +@node Useful Highlighting +@subsection Highlighting Commands are Useful The highlighting commands can be used to extract useful information from the file, such as lists of functions or file names. It is @@ -6659,46 +6673,68 @@ The commands serve a variety of purposes:@refill @table @code @item @@code@{@var{sample-code}@} -Indicate text that is a literal example of a piece of a program.@refill +Indicate text that is a literal example of a piece of a program. +@xref{code,,@code{@@code}}. @item @@kbd@{@var{keyboard-characters}@} -Indicate keyboard input.@refill +Indicate keyboard input. +@xref{kbd,,@code{@@kbd}}. @item @@key@{@var{key-name}@} -Indicate the conventional name for a key on a keyboard.@refill +Indicate the conventional name for a key on a keyboard. +@xref{key,,@code{@@key}}. @item @@samp@{@var{text}@} -Indicate text that is a literal example of a sequence of characters.@refill +Indicate text that is a literal example of a sequence of characters. +@xref{samp,,@code{@@samp}}. + +@item @@verb@{@var{text}@} +Write a verbatim sequence of characters. +@xref{verb,,@code{@@verb}}. @item @@var@{@var{metasyntactic-variable}@} -Indicate a metasyntactic variable.@refill +Indicate a metasyntactic variable. +@xref{var,,@code{@@var}}. @item @@env@{@var{environment-variable}@} -Indicate an environment variable.@refill +Indicate an environment variable. +@xref{env,,@code{@@kenv}}. @item @@file@{@var{file-name}@} -Indicate the name of a file.@refill +Indicate the name of a file. +@xref{file,,@code{@@file}}. @item @@command@{@var{command-name}@} -Indicate the name of a command.@refill +Indicate the name of a command. +@xref{command,,@code{@@command}}. @item @@option@{@var{option}@} -Indicate a command-line option.@refill +Indicate a command-line option. +@xref{option,,@code{@@option}}. @item @@dfn@{@var{term}@} -Indicate the introductory or defining use of a term.@refill +Indicate the introductory or defining use of a term. +@xref{dfn,,@code{@@dfn}}. @item @@cite@{@var{reference}@} -Indicate the name of a book.@refill +Indicate the name of a book. +@xref{cite,,@code{@@cite}}. + +@item @@abbr@{@var{abbreviation}@} +Indicate an abbreviation. @item @@acronym@{@var{acronym}@} -Indicate an acronym.@refill +Indicate an acronym. +@xref{acronym,,@code{@@acronym}}. -@item @@url@{@var{uniform-resource-locator}@} -Indicate a uniform resource locator for the World Wide Web. +@item @@indicateurl@{@var{uniform-resource-locator}@} +Indicate an example (that is, nonfunctional) uniform resource locator. +@xref{indicateurl,,@code{@@indicateurl}}. (Use @code{@@url} +(@pxref{uref,,@code{@@url}}) for live url's.) @item @@email@{@var{email-address}[, @var{displayed-text}]@} Indicate an electronic mail address. +@xref{email,,@code{@@email}}. @ignore @item @@ctrl@{@var{ctrl-char}@} @@ -6816,26 +6852,31 @@ long-standing manuals do so. @cindex Keyboard input Use the @code{@@kbd} command for characters of input to be typed by -users. For example, to refer to the characters @kbd{M-a}, -write@refill +users. For example, to refer to the characters @kbd{M-a}, write: @example @@kbd@{M-a@} @end example @noindent -and to refer to the characters @kbd{M-x shell}, write@refill +and to refer to the characters @kbd{M-x shell}, write: @example @@kbd@{M-x shell@} @end example -@cindex user input -@cindex slanted typewriter font, for @code{@@kbd} -The @code{@@kbd} command has the same effect as @code{@@code} in Info, -but by default produces a different font (slanted typewriter instead of -normal typewriter) in the printed manual, so users can distinguish the -characters they are supposed to type from those the computer outputs. +@cindex User input +@cindex Slanted typewriter font, for @code{@@kbd} +By default, the @code{@@kbd} command produces a different font +(slanted typewriter instead of normal typewriter) in the printed +manual, so users can distinguish the characters that they are supposed +to type from those that the computer outputs. + +In Info output, @code{@@kbd} is usually the same as @code{@@code}, +producing `quotes' around its argument. However, in typewriter-like +contexts such as the @code{@@example} environment (@pxref{example}) +and @code{@@code} command itself, the quotes are omitted, since Info +format cannot use distinguishing fonts. @findex kbdinputstyle Since the usage of @code{@@kbd} varies from manual to manual, you can @@ -6843,9 +6884,10 @@ control the font switching with the @code{@@kbdinputstyle} command. This command has no effect on Info output. Write this command at the beginning of a line with a single word as an argument, one of the following: -@vindex distinct@r{, arg to @@kbdinputstyle} -@vindex example@r{, arg to @@kbdinputstyle} -@vindex code@r{, arg to @@kbdinputstyle} + +@vindex distinct@r{, value for @code{@@kbdinputstyle}} +@vindex example@r{, value for @code{@@kbdinputstyle}} +@vindex code@r{, value for @code{@@kbdinputstyle}} @table @samp @item code Always use the same font for @code{@@kbd} as @code{@@code}. @@ -6858,18 +6900,19 @@ and similar environments. You can embed another @@-command inside the braces of an @code{@@kbd} command. Here, for example, is the way to describe a command that -would be described more verbosely as ``press an @samp{r} and then -press the @key{RET} key'':@refill +would be described more verbosely as ``press the @samp{r} key and then +press the @key{RETURN} key'': @example @@kbd@{r @@key@{RET@}@} @end example @noindent -This produces: @kbd{r @key{RET}} +This produces: @kbd{r @key{RET}}. (The present manual accepts the +default for @code{@@kbdinputstyle}.) You also use the @code{@@kbd} command if you are spelling out the letters -you type; for example:@refill +you type; for example: @example To give the @@code@{logout@} command, @@ -6885,11 +6928,11 @@ type the characters @kbd{l o g o u t @key{RET}}. @end quotation (Also, this example shows that you can add spaces for clarity. If you -really want to mention a space character as one of the characters of +explicitly want to mention a space character as one of the characters of input, write @kbd{@@key@{SPC@}} for it.)@refill -@node key, samp, kbd, Indicating +@node key @comment node-name, next, previous, up @subsection @code{@@key}@{@var{key-name}@} @findex key @@ -7023,7 +7066,7 @@ In English, the vowels are @samp{a}, @samp{e}, 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 +Like @LaTeX{}'s @code{\verb} command, the verbatim text can be quoted using any unique delimiter character. Enclose the verbatim text, including the delimiters, in braces. Text is printed in a fixed-width font: @@ -7040,10 +7083,16 @@ 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. +This is in contrast to @code{@@samp} (see the previous section), +@code{@@code}, and similar commands; in those cases, the argument is +normal Texinfo text, where the three characters @code{@@@{@}} are +special. With @code{@@verb}, nothing is special except the delimiter +character you choose. + +It is not reliable to use @code{@@verb} inside other Texinfo +constructs. In particular, it does not work to use @code{@@verb} in +anything related to cross-referencing, such as section titles or +figure captions. @node var @@ -7314,46 +7363,145 @@ identify that control character: an uparrow followed by the character @end ignore +@node abbr +@subsection @code{@@abbr}@{@var{abbreviation}[, @var{meaning}]@} +@findex abbr + +@cindex Abbreviations, tagging +You can use the @code{@@abbr} command for general abbreviations. The +abbreviation is given as the single argument in braces, as in +@samp{@@abbr@{Comput.@}}. As a matter of style, or for particular +abbreviations, you may prefer to omit periods, as in +@samp{@@abbr@{Mr@} Stallman}. + +@code{@@abbr} accepts an optional second argument, intended to be used +for the meaning of the abbreviation. + +If the abbreviation ends with a lowercase letter and a period, and is +not at the end of a sentence, and has no second argument, remember to +use the @code{@@.} command (@pxref{Not Ending a +Sentence}) to get the correct spacing. However, you do not have to +use @code{@@.} within the abbreviation itself; Texinfo automatically +assumes periods within the abbreivation do not end a sentence. + +@cindex <abbr> tag +In @TeX{} and in the Info output, the first argument is printed as-is; +if the second argument is present, it is printed in parentheses after +the abbreviation. In HTML and XML, the @code{<abbr>} tag is +used; in Docbook, the @code{<abbrev>} tag is used. For instance: + +@example +@@abbr@{Comput. J., Computer Journal@} +@end example + +@noindent produces: + +@display +@abbr{Comput. J., Computer Journal} +@end display + +For abbreviations consisting of all capital letters, you may prefer to +use the @code{@@acronym} command instead. See the next section for +more on the usage of these two commands. + + @node acronym -@subsection @code{@@acronym}@{@var{acronym}@} +@subsection @code{@@acronym}@{@var{acronym}[, @var{meaning}]@} @findex acronym @cindex NASA, as acronym -@cindex F.B.I., as acronym -@cindex Abbreviations, tagging @cindex Acronyms, tagging Use the @code{@@acronym} command for abbreviations written in all capital letters, such as `@acronym{NASA}'. The abbreviation is given as the single argument in braces, as in @samp{@@acronym@{NASA@}}. As -a matter of style, or for particular abbreviations, you may prefer to -use periods, as in @samp{@@acronym@{F.B.I.@}}. +a matter of style, or for particular acronyms, you may prefer to +use periods, as in @samp{@@acronym@{N.A.S.A.@}}. + +@code{@@acronym} accepts an optional second argument, intended to be +used for the meaning of the acronym. + +If the acronym is at the end of a sentence, and if there is no second +argument, remember to use the @code{@@.} or similar command +(@pxref{Ending a Sentence}) to get the correct spacing. + +@cindex <acronym> tag +In @TeX{}, the acronym is printed in slightly smaller font. In the +Info output, the argument is printed as-is. In either format, if the +second argument is present, it is printed in parentheses after the +acronym. In HTML, Docbook, and XML, the @code{<acronym>} tag is +used. + +For instance (since GNU is a recursive acronym, we use +@code{@@acronym} recursively): + +@example +@@acronym@{GNU, @@acronym@{GNU@}'s Not Unix@} +@end example + +@noindent produces: + +@display +@acronym{GNU, @acronym{GNU}'s Not Unix} +@end display + +In some circumstances, it is conventional to print family names in all +capitals. Don't use @code{@@acronym} for this, since a name is not an +acronym. Use @code{@@sc} instead (@pxref{Smallcaps}). + +@code{@@abbr} and @code{@@acronym} are closely related commands: they +both signal to the reader that a shortened form is being used, and +possibly give a meaning. When choosing whether to use these two +commands, please bear the following in mind. + +@itemize @minus +@item +In standard English usage, acronyms are a subset of abbreviations: +they include pronounceable words like `@acronym{NATO}', `radar', and +`snafu', and some sources also include syllable acronyms like +`Usenet', hybrids like `@acronym{SIGGRAPH}', and unpronounceable +initialisms like `@acronym{FBI}'. + +@item +In Texinfo, an acronym (but not an abbreviation) should consist only +of capital letters and periods, no lowercase. + +@item +In @TeX{}, an acronym (but not an abbreviation) is printed in a +slightly smaller font. + +@item +Some browsers place a dotted bottom border under abbreviations but not +acronyms. -In @TeX{} and HTML, the argument is printed in a slightly smaller font -size. In Info or plain text output, this command changes nothing. +@item +It's not essential to use these commands for all abbreviations. Text +is perfectly readable without them, and for common abbreviations like +`etc.@:', we consider them to be overkill. +@end itemize -@node url -@subsection @code{@@url}@{@var{uniform-resource-locator}@} -@findex url + +@node indicateurl +@subsection @code{@@indicateurl}@{@var{uniform-resource-locator}@} +@findex indicateurl @cindex Uniform resource locator, indicating @cindex URL, indicating -Use the @code{@@url} command to indicate a uniform resource locator on -the World Wide Web. This is analogous to @code{@@file}, @code{@@var}, -etc., and is purely for markup purposes. It does not produce a link you -can follow in HTML output (use the @code{@@uref} command for that, -@pxref{uref,, @code{@@uref}}). It is useful for url's which do -not actually exist. For example: +Use the @code{@@indicateurl} command to indicate a uniform resource +locator on the World Wide Web. This is analogous to @code{@@file}, +@code{@@var}, etc., and is purely for markup purposes. It does not +produce a link you can follow in HTML output (use the @code{@@uref} +command for that, @pxref{uref,, @code{@@uref}}). It is useful for +url's which do not actually exist. For example: -@c Two lines because one is too long for smallbook format. @example -For example, the url might be @@url@{http://example.org/path@}. +For example, the url might be @@indicateurl@{http://example.org/path@}. @end example @noindent which produces: @display -For example, the url might be @url{http://example.org/path}. +For example, the url might be @indicateurl{http://example.org/path}. @end display @@ -7365,11 +7513,11 @@ Use the @code{@@email} command to indicate an electronic mail address. It takes one mandatory argument, the address, and one optional argument, the text to display (the default is the address itself). -@cindex mailto link -In Info and @TeX{}, the address is shown in angle brackets, preceded by -the text to display if any. In HTML output, @code{@@email} produces a -@samp{mailto} link that usually brings up a mail composition window. -For example: +@cindex Mailto link +In Info, the address is shown in angle brackets, preceded by the text +to display if any. In @TeX{}, the angle brackets are omitted. In +HTML output, @code{@@email} produces a @samp{mailto} link that usually +brings up a mail composition window. For example: @example Send bug reports to @@email@{bug-texinfo@@@@gnu.org@}, @@ -7412,38 +7560,29 @@ The @code{@@emph} and @code{@@strong} commands are for emphasis; @code{@@strong} is stronger. In printed output, @code{@@emph} produces @emph{italics} and @code{@@strong} produces @strong{bold}. -@need 800 For example, @example @group -@@quotation -@@strong@{Caution:@} @@samp@{rm * .[^.]*@} removes @@emph@{all@} -files in the directory. -@@end quotation +@@strong@{Caution:@} @@samp@{rm * .[^.]*@} +removes @@emph@{all@} files in the directory. @end group @end example -@iftex @noindent -produces the following in printed output: +produces the following in printed output and HTML: @quotation -@strong{Caution}: @samp{rm * .[^.]*} removes @emph{all} -files in the directory. +@strong{Caution}: @samp{rm * .[^.]*} +removes @emph{all} files in the directory. @end quotation @noindent and the following in Info: -@end iftex -@ifinfo -@noindent -produces: -@end ifinfo @example - *Caution*: `rm * .[^.]*' removes _all_ - files in the directory. +*Caution:* `rm * .[^.]*' removes _all_ +files in the directory. @end example The @code{@@strong} command is seldom used except to mark what is, in @@ -7453,10 +7592,12 @@ preceding example. In the Info output, @code{@@emph} surrounds the text with underscores (@samp{_}), and @code{@@strong} puts asterisks around the text. -@quotation -@strong{Caution:} Do not use @code{@@strong} with the word @samp{Note}; -Info will mistake the combination for a cross reference. Use a phrase -such as @strong{Please note} or @strong{Caution} instead. +@quotation Caution +Do not use @code{@@strong} with the word @samp{Note}; Info will +mistake the combination for a cross reference. (It's usually +redundant, anyway.) Use a phrase such as @strong{Please notice} or +@strong{Caution} instead, or the optional argument to +@code{@@quotation}---@samp{Note} is allowable there. @end quotation @@ -7465,68 +7606,103 @@ such as @strong{Please note} or @strong{Caution} instead. @cindex Small caps font @findex sc @r{(small caps font)} -Use the @samp{@@sc} command to set text in the printed and the HTML -output in @sc{a small caps font} and set text in the Info file in upper -case letters. Write the text you want to be in small caps (where -possible) between braces in lower case, like this: +Use the @samp{@@sc} command to set text in @sc{a small caps font} +(where possible). Write the text you want to be in small caps between +braces in lower case, like this: @example -The @@sc@{acm@} and @@sc@{ieee@} are technical societies. +Richard @@sc@{Stallman@} founded @@acronym@{GNU@}. @end example @noindent This produces: @display -The @sc{acm} and @sc{ieee} are technical societies. +Richard @sc{Stallman} founded @acronym{GNU}. @end display -@TeX{} typesets the small caps font in a manner that prevents the -letters from `jumping out at you on the page'. This makes small caps -text easier to read than text in all upper case---but it's usually -better to use regular mixed case anyway. The Info formatting commands -set all small caps text in upper case. In HTML, the text is upper-cased -and a smaller font is used to render it. +As shown here, we recommend using @code{@@acronym} for actual +acronyms (@pxref{acronym}), and reserving @code{@@sc} for special +cases where you want small caps. The output is not the same +(@code{@@acronym} prints in a smaller text font, not the small caps +font), but more importantly it describes the actual text more +accurately. -If the text between the braces of an @code{@@sc} command is uppercase, -@TeX{} typesets in FULL-SIZE CAPITALS. Use full-size capitals -sparingly, if ever, and since it's redundant to mark all-uppercase text -with @code{@@sc}, @command{makeinfo} warns about such usage. +Family names are one case where small capitals are sometimes desirable, +also as shown here. -You may also use the small caps font for a jargon word such as -@sc{ato} (a @sc{nasa} word meaning `abort to orbit'). +@cindex <small> tag +@TeX{} typesets any uppercase letters between the braces of an +@code{@@sc} command in full-size capitals; only lowercase letters are +printed in the small caps font. In the Info output, the argument to +@code{@@sc} is printed in all upper case. In HTML, the argument is +uppercased and the output marked with the @code{<small>} tag to reduce +the font size. -There are subtleties to using the small caps font with a jargon word -such as @sc{cdr}, a word used in Lisp programming. In this case, you -should use the small caps font when the word refers to the second and -subsequent elements of a list (the @sc{cdr} of the list), but you -should use @samp{@@code} when the word refers to the Lisp function of -the same spelling. +Since it's redundant to mark all-uppercase text with @code{@@sc}, +@command{makeinfo} warns about such usage. + +We recommend using regular mixed case wherever possible. @node Fonts @subsection Fonts for Printing, Not Info -@cindex Fonts for printing, not for Info -@findex i @r{(italic font)} +@cindex Fonts for printing, not Info + +Texinfo provides a number of font commands that specify font changes +in the printed manual and (where possible) in the HTML output, but +have no effect in the Info file. All the commands apply to an +argument that follows, surrounded by braces. + +@table @code +@item @@b @findex b @r{(bold font)} +@cindex Bold font +selects @b{bold} face; + +@item @@i +@findex i @r{(italic font)} +@cindex Italic font +selects an @i{italic} font; + +@item @@r +@findex r @r{(roman font)} +@cindex Roman font +@cindex Default font +selects a @r{roman} font, which is the usual font in which text is +printed. It may or may not be seriffed. + +@item @@sansserif +@findex sansserif @r{(sans serif font)} +@cindex Sans serif font +selects a @sansserif{sans serif} font; + +@item @@slanted +@findex slanted @r{(slanted font)} +@cindex Slanted font +@cindex Oblique font +rselects a @slanted{slanted} font; + +@item @@t @findex t @r{(typewriter font)} -@findex r @r{(Roman font)} - -Texinfo provides four font commands that specify font changes in the -printed manual but have no effect in the Info file. @code{@@i} -requests @i{italic} font (in some versions of @TeX{}, a slanted font -is used), @code{@@b} requests @b{bold} face, @code{@@t} requests the -@t{fixed-width}, typewriter-style font used by @code{@@code}, and @code{@@r} requests a -@r{roman} font, which is the usual font in which text is printed. All -four commands apply to an argument that follows, surrounded by -braces.@refill - -Only the @code{@@r} command has much use: in example programs, you -can use the @code{@@r} command to convert code comments from the -fixed-width font to a roman font. This looks better in printed -output.@refill +@cindex Monospace font +@cindex Fixed-width font +@cindex Typewriter font +selects the @t{fixed-width}, typewriter-style font used by @code{@@code}; + +@end table + +(The commands with longer names were invented much later than the +others, when it did not seem desirable to use very short names for +such an infrequently needed feature.) + +@cindex <lineannotation> Docbook tag +Only the @code{@@r} command has much use: in example-like +environments, you can use the @code{@@r} command to write comments in +the standard roman font instead of the fixed-width font. This looks +better in printed output, and produces a @code{<lineannotation>} tag +in Docbook output. -@need 700 For example, @example @@ -7544,9 +7720,9 @@ produces (+ 2 2) ; @r{Add two plus two.} @end lisp -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. +In general, you should avoid using the other font commands. Some of +them are only useful when documenting functionality with specific font +effects, such as in \TeX\ and related packages. @node Quotations and Examples @@ -7554,16 +7730,17 @@ language. Quotations and examples are blocks of text consisting of one or more whole paragraphs that are set off from the bulk of the text and -treated differently. They are usually indented.@refill +treated differently. They are usually indented in the output. +@findex end In Texinfo, you always begin a quotation or example by writing an @@-command at the beginning of a line by itself, and end it by writing an @code{@@end} command that is also at the beginning of a line by itself. For instance, you begin an example by writing @code{@@example} by itself at the beginning of a line and end the example by writing @code{@@end example} on a line by itself, at the beginning of that -line. -@findex end +line, and with only one space between the @code{@@end} and the +@code{example}. @menu * Block Enclosing Commands:: Different constructs for different purposes. @@ -7591,8 +7768,8 @@ following sections: @table @code @item @@quotation -Indicate text that is quoted. The text is filled, indented, and -printed in a roman font by default. +Indicate text that is quoted. The text is filled, indented (from both +margins), and printed in a roman font by default. @item @@example Illustrate code, commands, and the like. The text is printed @@ -7641,47 +7818,50 @@ The @code{@@noindent} command may be used after one of the above constructs to prevent the following text from being indented as a new paragraph. -You can use the @code{@@cartouche} command within one of the above +You can use the @code{@@cartouche} environment around one of the above constructs to highlight the example or quotation by drawing a box with rounded corners around it. @xref{cartouche, , Drawing Cartouches Around Examples}. @node quotation -@section @code{@@quotation} +@section @code{@@quotation}: Block quotations @cindex Quotations @findex quotation -The text of a quotation is processed normally except that: +The text of a quotation is processed normally (regular font, text is +filled) except that: @itemize @bullet @item the margins are closer to the center of the page, so the whole of the -quotation is indented;@refill +quotation is indented; @item -the first lines of paragraphs are indented no more than other -lines;@refill +and the first lines of paragraphs are indented no more than other lines. -@item -in the printed output, interparagraph spacing is reduced.@refill @end itemize @quotation This is an example of text written between an @code{@@quotation} command and an @code{@@end quotation} command. An @code{@@quotation} command is most often used to indicate text that is excerpted from -another (real or hypothetical) printed work.@refill +another (real or hypothetical) printed work. @end quotation Write an @code{@@quotation} command as text on a line by itself. This line will disappear from the output. Mark the end of the quotation with a line beginning with and containing only @code{@@end quotation}. The @code{@@end quotation} line will likewise disappear from the -output. Thus, the following,@refill +output. + +@code{@@quotation} takes one optional argument, given on the remainder +of the line. This text, if present, is included at the beginning of +the quotation in bold or otherwise emphasized, and followed with a +@samp{:}. For example: @example -@@quotation +@@quotation Note This is a foo. @@end quotation @@ -7690,10 +7870,23 @@ a foo. @noindent produces -@quotation -This is a foo. +@quotation Note +This is +a foo. @end quotation +If the @code{@@quotation} argument is exactly one of these words: + +@example +Caution Important Note Tip Warning +@end example + +@cindex <note> Docbook tag +@cindex <blockquote> HTML tag +@noindent then the Docbook output uses corresponding special tags +(@code{<note>}, etc.) instead of the default @code{<blockquote>}. +HTML output always uses @code{<blockquote>}. + @node example @section @code{@@example}: Example Text @@ -7714,10 +7907,9 @@ An @code{@@example} environment has the following characteristics: the source text is not filled as it normally is. @item Extra spaces and blank lines are significant. @item The output is indented. -@item The output uses a fixed-width font (for formats where this is -possible and meaningful). -@item Texinfo commands @emph{are} expanded; if you want the input to -be the output verbatim, use the @code{@@verbatim} environment instead +@item The output uses a fixed-width font. +@item Texinfo commands @emph{are} expanded; if you want the output to +be the input verbatim, use the @code{@@verbatim} environment instead (@pxref{verbatim,,@code{@@verbatim}}). @end itemize @@ -7745,12 +7937,11 @@ after the @code{@@end example}. Blank lines inside the beginning @code{@@example} and the ending @code{@@end example}, on the other hand, do appear in the output. -@quotation -@strong{Caution:} Do not use tabs in the lines of an example! (Or -anywhere else in Texinfo, except in verbatim environments.) @TeX{} -treats tabs as single spaces, and that is not what they look like. In -Emacs, you can use @kbd{M-x untabify} to convert tabs in a region to -multiple spaces. +@quotation Caution +Do not use tabs in the lines of an example! (Or anywhere else in +Texinfo, except in verbatim environments.) @TeX{} treats tabs as +single spaces, and that is not what they look like. In Emacs, you can +use @kbd{M-x untabify} to convert tabs in a region to multiple spaces. @end quotation Examples are often, logically speaking, ``in the middle'' of a @@ -7763,6 +7954,9 @@ If you want to embed code fragments within sentences, instead of displaying them, use the @code{@@code} command or its relatives (@pxref{code,,@code{@@code}}). +If you wish to write a ``comment'' on a line of an example in the +normal roman font, you can use the @code{@@r} command (@pxref{Fonts}). + @node verbatim @section @code{@@verbatim}: Literal Text @@ -7797,12 +7991,12 @@ For example: @c oops, got to trick this a bit: can't use @end verbatim inside @verbatim @example -@exdent @@verbatim -@exdent @{ -@exdent <tab>@@command with strange characters: @@'e -@exdent expand<tab>me -@exdent @} -@exdent @@end verbatim +@exdent @t{@@verbatim} +@exdent @t{@{} +@exdent @key{TAB}@t{@@command with strange characters: @@'e} +@exdent @t{expand@key{TAB}me} +@exdent @t{@}} +@exdent @t{@@end verbatim} @end example @noindent @@ -7810,16 +8004,18 @@ produces @verbatim { - @command with strange characters: @'e + @command with strange characters: @'e expand me } @end verbatim Since the lines containing @code{@@verbatim} and @code{@@end verbatim} -produce no output, tyically you should put a blank line before the +produce no output, typically you should put a blank line before the @code{@@verbatim} and another blank line after the @code{@@end -verbatim}. Blank lines between the beginning @code{@@verbatim} and the -ending @code{@@end verbatim} will appear in the output. +verbatim}. Blank lines between the beginning @code{@@verbatim} and +the ending @code{@@end verbatim} will appear in the output. + +It is not reliable to use @code{@@verbatim} inside other Texinfo constructs. @node verbatiminclude @@ -7837,7 +8033,10 @@ You can include the exact contents of a file in the document with the 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. +exactly as it is, with all special characters and white space +retained. No indentation is added; if you want indentation, enclose +the @code{@@verbatiminclude} within @code{@@example} +(@pxref{example,,@code{@@example}}). The name of the file is taken literally, with a single exception: @code{@@value@{@var{var}@}} references are expanded. This makes it @@ -7929,13 +8128,13 @@ consistently within a chapter. @cindex Display formatting @findex display -The @code{@@display} command begins a kind of example. It is like the -@code{@@example} command -except that, in -a printed manual, @code{@@display} does not select the fixed-width -font. In fact, it does not specify the font at all, so that the text -appears in the same font it would have appeared in without the -@code{@@display} command.@refill +The @code{@@display} command begins a kind of example, where each line +of input produces a line of output, and the output is indented. It is +thus like the @code{@@example} command except that, in a printed +manual, @code{@@display} does not select the fixed-width font. In +fact, it does not specify the font at all, so that the text appears in +the same font it would have appeared in without the @code{@@display} +command. @display This is an example of text written between an @code{@@display} command @@ -7948,6 +8147,11 @@ Texinfo also provides a command @code{@@smalldisplay}, which is like @code{@@display} but uses a smaller font in @code{@@smallbook} format. @xref{small}. +The @code{@@table} command (@pxref{table}) does not work inside +@code{@@display}. Since @code{@@display} is line-oriented, it doesn't +make sense to use them together. If you want to indent a table, try +@code{@@quotation} (@pxref{quotation}). + @node format @section @code{@@format} and @code{@@smallformat} @@ -8016,8 +8220,8 @@ returning the page to its normal width.@refill @section @code{@@flushleft} and @code{@@flushright} @findex flushleft @findex flushright -@cindex ragged right -@cindex ragged left +@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, @@ -8173,45 +8377,44 @@ paragraphs (@pxref{Command Syntax}). @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. +rounded corners around its contents. In HTML, a normal rectangle is +drawn (that's the best HTML can do). @code{@@cartouche} has no effect +in Info output. -@code{@@cartouche} affects only the printed manual; it has no effect in -other output files. +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. -@need 1500 For example, @example -@group -@@example @@cartouche +@@example % pwd /usr/local/share/emacs -@@end cartouche @@end example -@end group +@@end cartouche @end example @noindent surrounds the two-line example with a box with rounded corners, in the printed manual. -@iftex -In a printed manual, the example looks like this:@refill +The output from the example looks like this (if you're reading this in +Info, you'll see the @code{@@cartouche} had no effect): -@example -@group @cartouche +@example % pwd -/usr/local/lib/emacs/info -@end cartouche -@end group +/usr/local/info @end example -@end iftex +@end cartouche + +For proper output in HTML, it's necessary to put the +@code{@@cartouche} around the @code{@@example}, and not the other way +around. This limitation of @command{makeinfo} may be removed one day. +@code{@@cartouche} also implies @code{@@group} (@pxref{group}). @node Lists and Tables @chapter Lists and Tables @@ -8231,10 +8434,8 @@ the first column; multi-column tables are also supported. * Multi-column Tables:: How to construct generalized tables. @end menu -@node Introducing Lists, itemize, Lists and Tables, Lists and Tables -@ifinfo -@heading Introducing Lists -@end ifinfo +@node Introducing Lists +@section Introducing Lists Texinfo automatically indents the text in lists or tables, and numbers an enumerated list. This last feature is useful if you modify the @@ -8662,10 +8863,16 @@ See the example for @code{@@table} in the previous section. Use the @code{@@itemx} command inside a table when you have two or more first column entries for the same item, each of which should appear on a -line of its own. Use @code{@@itemx} for all but the first entry; -@code{@@itemx} should always follow an @code{@@item} command. The -@code{@@itemx} command works exactly like @code{@@item} except that it -does not generate extra vertical space above the first column text. +line of its own. + +Use @code{@@item} for the first entry, and @code{@@itemx} for all +subsequent entries; @code{@@itemx} must always follow an @code{@@item} +command, with no blank line intervening. + +The @code{@@itemx} command works exactly like @code{@@item} except +that it does not generate extra vertical space above the first column +text. If you have multiple consecutive @code{@@itemx} commands, do +not insert any blank lines between them. For example, @@ -8697,8 +8904,8 @@ case) character or string.@refill a two-column table.)@refill -@node Multi-column Tables, , Two-column Tables, Lists and Tables -@section Multi-column Tables +@node Multi-column Tables +@section @code{@@multitable}: Multi-column Tables @cindex Tables, making multi-column @findex multitable @@ -8732,15 +8939,15 @@ entirely on the same line as the @code{@@multitable} command. @cindex Line length, column widths as fraction of To specify column widths as fractions of the line length, write @code{@@columnfractions} and the decimal numbers (presumably less than -1) after the @code{@@multitable} command, as in: +1; a leading zero is allowed and ignored) after the +@code{@@multitable} command, as in: @example @@multitable @@columnfractions .33 .33 .33 @end example -@noindent The fractions need not add up exactly to 1.0, as these do -not. This allows you to produce tables that do not need the full line -length. You can use a leading zero if you wish. +The fractions need not add up exactly to 1.0, as these do not. This +allows you to produce tables that do not need the full line length. @item @cindex Prototype row, column widths defined by @@ -8764,7 +8971,7 @@ particularly likely to be useful. @end enumerate -@node Multitable Rows, , Multitable Column Widths, Multi-column Tables +@node Multitable Rows @subsection Multitable Rows @cindex Multitable rows @cindex Rows, of a multitable @@ -8777,13 +8984,20 @@ with @code{@@item}, and separate the column entries with @code{@@tab}. Line breaks are not special within the table body, and you may break input lines in your source file as necessary. +@findex headitem +@cindex Heading row, in table +@cindex <thead> HTML tag +You can also use @code{@@headitem} instead of @code{@@item} to produce +a @dfn{heading row}. The @TeX{} output for such a row is in bold, and +the HTML, XML, and Docbook output uses the @code{<thead>} tag. + Here is a complete example of a multi-column table (the text is from @cite{The GNU Emacs Manual}, @pxref{Split Window,, Splitting Windows, emacs, The GNU Emacs Manual}): @example @@multitable @@columnfractions .15 .45 .4 -@@item Key @@tab Command @@tab Description +@@headitem Key @@tab Command @@tab Description @@item C-x 2 @@tab @@code@{split-window-vertically@} @@tab Split the selected window into two windows, @@ -8802,7 +9016,7 @@ split that window. @noindent produces: @multitable @columnfractions .15 .45 .4 -@item Key @tab Command @tab Description +@headitem Key @tab Command @tab Description @item C-x 2 @tab @code{split-window-vertically} @tab Split the selected window into two windows, @@ -8818,8 +9032,561 @@ split that window. @end multitable -@node Indices, Insertions, Lists and Tables, Top -@comment node-name, next, previous, up +@node Special Displays +@chapter Special Displays +@cindex Special displays + +The commands in this chapter allow you to write text that is specially +displayed (output format permitting), outside of the normal document +flow. + +One set of such commands is for creating ``floats'', that is, figures, +tables, and the like, set off from the main text, possibly numbered, +captioned, and/or referred to from elsewhere in the document. Images +are often included in these displays. + +Another group of commands is for creating footnotes in Texinfo. + +@menu +* Floats:: Figures, tables, and the like. +* Images:: Including graphics and images. +* Footnotes:: Writing footnotes. +@end menu + + +@node Floats +@section Floats +@cindex Floats, in general + +A @dfn{float} is a display which is set off from the main text. It is +typically labelled as being a ``Figure'', ``Table'', ``Example'', or +some similar type. + +@cindex Floating, not yet implemented +A float is so-named because, in principle, it can be moved to the +bottom or top of the current page, or to a following page, in the +printed output. (Floating does not make sense in other output +formats.) In the present version of Texinfo, however, this floating +is unfortunately not yet implemented. Instead, the floating material +is simply output at the current location, more or less as if it were +an @code{@@group} (@pxref{group,,@code{@@group}}). + +@menu +* float:: Producing floating material. +* caption shortcaption:: Specifying descriptions for floats. +* listoffloats:: A table of contents for floats. +@end menu + + +@node float +@subsection @code{@@float} [@var{type}][,@var{label}]: Floating material +@findex float +@cindex Float environment + +To produce floating material, enclose the material you want to be +displayed separate between @code{@@float} and @code{@@end float} +commands, on lines by themselves. + +Floating material uses @code{@@image} to display an already-existing +graphic (@pxref{Images}), or @code{@@multitable} to display a table +(@pxref{Multi-column Tables}). However, the contents of the float can +be anything. Here's an example with simple text: + +@example +@@float Figure,fig:ex1 +This is an example float. +@@end float +@end example + +@noindent And the output: + +@float Figure,fig:ex1 +This is an example float. +@end float + +As shown in the example, @code{@@float} takes two arguments (separated +by a comma), @var{type} and @var{label}. Both are optional. + +@table @var +@item type +Specifies the sort of float this is; typically a word such as +``Figure'', ``Table'', etc. If not given, and @var{label} is, any +cross-referencing will simply use a bare number. + +@item label +Specifies a cross-reference label for this float. If given, this +float is automatically given a number, and will appear in any +@code{@@listofloats} output (@pxref{listoffloats}). Cross-references +to @var{label} are allowed. + +@cindex Floats, making unnumbered +@cindex Unnumbered float, creating +On the other hand, if @var{label} is not given, then the float will +not be numbered and consequently will not appear in the +@code{@@listoffloats} output or be cross-referenceable. +@end table + +@noindent Normally, you specify both @var{type} and @var{label}, to get a +labeled and numbered float. + +@cindex Floats, numbering of +@cindex Numbering of floats +In Texinfo, all floats are numbered the same way: with the chapter +number (or appendix letter), a period, and the float number, which +simply counts 1, 2, 3, @dots{}, and is reset at each chapter. Each +float type is counted independently. + +Floats within an @code{@@unnumbered} are numbered, or outside of any +chapter, are simply numbered consecutively from 1. + +These numbering conventions are not, at present, changeable. + + +@node caption shortcaption +@subsection @code{@@caption} & @code{@@shortcaption} +@findex caption +@findex shortcaption +@cindex Captions, for floats +@cindex Short captions, for lists of floats + +You may write an @code{@@caption} anywhere within a @code{@@float} +environment, to define a caption for the float. It is not allowed in +any other context. @code{@@caption} takes a single argument, enclosed +in braces. Here's an example: + +@example +@@float +An example float, with caption. +@@caption@{Caption for example float.@} +@@end float +@end example + +@noindent The output is: + +@float +An example float, with caption. +@caption{Caption for example float.} +@end float + +@code{@@caption} can appear anywhere within the float; it is not +processed until the @code{@@end float}. The caption text is usually a +sentence or two, but may consist of several paragraphs if necessary. + +In the output, the caption always appears below the float; this is not +currently changeable. It is preceded by the float type and/or number, +as specified to the @code{@@float} command (see the previous section). + +The @code{@@shortcaption} command likewise may be used only within +@code{@@float}, and takes a single argument in braces. The short +caption text is used instead of the caption text in a list of floats +(see the next section). Thus, you can write a long caption for the +main document, and a short title to appear in the list of floats. For +example: + +@example +@@float +... as above ... +@@shortcaption@{Text for list of floats.@} +@@end float +@end example + +The text for @code{@@caption} and @code{@@shortcaption} may not +contain comments (@code{@@c}), verbatim text (@code{@@verb}), +environments such as @code{@@example}, or other complex constructs. + + +@node listoffloats +@subsection @code{@@listoffloats}: Tables of contents for floats +@findex listoffloats +@cindex List of floats +@cindex Floats, list of +@cindex Table of contents, for floats + +You can write a @code{@@listoffloats} command to generate a list of +floats for a given float type (@pxref{float}), analogous to the +document's overall table of contents. Typically, it is written in its +own @code{@@unnumbered} node to provide a heading and structure, +rather like @code{@@printindex} (@pxref{Printing Indices & Menus}). + +@code{@@listoffloats} takes one optional argument, the float type. +Here's an example: + +@example +@@node List of Figures +@@unnumbered List of Figures +@@listoffloats Figure +@end example + +@noindent And the output from @code{@@listoffloats}: + +@display +@listoffloats Figure +@end display + +Without any argument, @code{@@listoffloats} generates a list of +floats for which no float type was specified, i.e., no first argument +to the @code{@@float} command (@pxref{float}). + +Each line in the list of floats contains the float type (if any), +the float number, and the caption, if any---the @code{@@shortcaption} +argument, if it was specified, else the @code{@@caption} argument. +In Info, the result is a menu where each float can be selected. In +HTML, each line is a link to the float. In printed output, the page +number is included. + +Unnumbered floats (those without cross-reference labels) are omitted +from the list of floats. + + +@node Images +@section Inserting Images + +@cindex Images, inserting +@cindex Pictures, inserting +@findex image + +You can insert an image given in an external file with the +@code{@@image} command. Although images can be used anywhere, +including the middle of a paragraph, we describe them in this chapter +since they are most often part of a displayed figure or example. + +@menu +* Image Syntax:: +* Image Scaling:: +@end menu + + +@node Image Syntax +@subsection Image Syntax + +Here is the basic synopsis of the @code{@@image} command: + +@example +@@image@{@var{filename}@r{[,} @var{width}@r{[,} @var{height}@r{[,} @var{alttext}@r{[, }@var{extension}@r{]]]]}@} +@end example + +@cindex Formats for images +@cindex Image formats +The @var{filename} argument is mandatory, and must not have an +extension, because the different processors support different formats: + +@itemize @bullet +@item +@TeX{} reads the file @file{@var{filename}.eps} (Encapsulated PostScript +format). +@item +@pindex pdftex@r{, and images} +PDF@TeX{} reads @file{@var{filename}.pdf} (Adobe's Portable Document Format). +@item +@code{makeinfo} includes @file{@var{filename}.txt} verbatim for +Info output (more or less as if it was an @code{@@example}). +@item +@code{makeinfo} uses the optional fifth argument @var{extension} to +@code{@@image} for the filename extension, if it is specified. For example: + +@pindex XPM image format +@example +@@image@{foo,,,,.xpm@} +@end example + +@noindent +will cause @code{makeinfo} to look for @file{foo.xpm} before any others. + +@end itemize + +The @var{width} and @var{height} arguments are described in the next +section. + +For @TeX{} output, if an image is the first thing in a paragraph, for +example if you want two images side-by-side, you must precede it with +@code{@@noindent} (@pxref{noindent,,@code{@@noindent}}). Otherwise it +will be displayed on a line by itself. If you want it centered, +use @code{@@center} (@pxref{titlefont center sp,,@code{@@titlefont +@@center @@sp}}). + +@cindex Alt attribute for images +@cindex Images, alternate text for +When producing html, @code{makeinfo} sets the @dfn{alt attribute} for +inline images to the optional @var{alttext} (fourth) argument to +@code{@@image}, if supplied. If not supplied, @code{makeinfo} uses +the full file name of the image being displayed. If you want an empty +@code{alt} string, use @code{@@-}. The @var{alttext} is taken as +Texinfo text, so special characters such as @samp{"} and @samp{<} and +@samp{&} are escaped in the HTML and XML output. + +@cindex GIF images, unsupported due to patents +@cindex PNG image format +@cindex JPG image format +If you do not supply the optional @var{extension} (fifth) argument, +@code{makeinfo} first tries @file{@var{filename}.png}; if that does +not exist, it tries @file{@var{filename}.jpg}. If that does not exist +either, it complains. (We cannot support GIF format directly due to +software patents.) + +In Info output, @code{makeinfo} writes a reference to the binary image +file (trying @var{filename} suffixed with @file{@var{extension}}, +@file{@var{.extension}}, @file{.png}, or @file{.jpg}, in that order) +if one exists. It also literally includes the @file{.txt} file if one +exists. This way, Info readers which can display images (such as the +Emacs Info browser, running under X) can do so, whereas Info readers +which can only use text (such as the standalone Info reader) can +display the textual version. + +The implementation of this is to put the following construct into the +Info output: + +@example +^@@^H[image src="@var{binaryfile}" text="@var{txtfile}" + alt="@var{alttext} ... ^@@^H] +@end example + +@noindent where @samp{^@@} and @samp{^H} stand for the actual null and +backspace control characters. If one of the files is not present, the +corresponding argument is omitted. + +The reason for mentioning this here is that older Info browsers (this +feature was introduced in Texinfo version 4.6) will display the above +literally, which, although not pretty, should not be harmful. + + +@node Image Scaling +@subsection Image Scaling + +@cindex Images, scaling +@cindex Scaling images +@cindex Width of images +@cindex Height of images +@cindex Aspect ratio of images +@cindex Distorting images +The optional @var{width} and @var{height} arguments to the +@code{@@image} command (see the previous section) specify the size to +scale the image to. They are ignored for Info output. If neither is +specified, the image is presented in its natural size (given in the +file); if only one is specified, the other is scaled proportionately; +and if both are specified, both are respected, thus possibly distorting +the original image by changing its aspect ratio. + +@cindex Dimensions and image sizes +The @var{width} and @var{height} may be specified using any valid @TeX{} +dimension, namely: + +@table @asis +@item pt +@cindex Points (dimension) +point (72.27pt = 1in) +@item pc +@cindex Picas +pica (1pc = 12pt) +@item bp +@cindex Big points +big point (72bp = 1in) +@item in +@cindex Inches +inch +@item cm +@cindex Centimeters +centimeter (2.54cm = 1in) +@item mm +@cindex Millimeters +millimeter (10mm = 1cm) +@item dd +@cindex Did@^ot points +did@^ot point (1157dd = 1238pt) +@item cc +@cindex Ciceros +cicero (1cc = 12dd) +@item sp +@cindex Scaled points +scaled point (65536sp = 1pt) +@end table + +@pindex ridt.eps +For example, the following will scale a file @file{ridt.eps} to one +inch vertically, with the width scaled proportionately: + +@example +@@image@{ridt,,1in@} +@end example + +@pindex epsf.tex +For @code{@@image} to work with @TeX{}, the file @file{epsf.tex} must be +installed somewhere that @TeX{} can find it. (The standard location is +@file{@var{texmf}/tex/generic/dvips/epsf.tex}, where @var{texmf} is a +root of your @TeX{} directory tree.) This file is included in the +Texinfo distribution and is also available from +@uref{ftp://tug.org/tex/epsf.tex}, among other places. + +@code{@@image} can be used within a line as well as for displayed +figures. Therefore, if you intend it to be displayed, be sure to leave +a blank line before the command, or the output will run into the +preceding text. + +Image scaling is presently implemented only in @TeX{}, not in HTML or +any other sort of output. + + +@node Footnotes +@section Footnotes +@cindex Footnotes +@findex footnote + +A @dfn{footnote} is for a reference that documents or elucidates the +primary text.@footnote{A footnote should complement or expand upon +the primary text, but a reader should not need to read a footnote to +understand the primary text. For a thorough discussion of footnotes, +see @cite{The Chicago Manual of Style}, which is published by the +University of Chicago Press.} Footnotes are distracting; use them +sparingly, if at all. Standard bibliographical references are better +placed in a bibliography at the end of a document than in footnotes +throughout. + +@menu +* Footnote Commands:: How to write a footnote in Texinfo. +* Footnote Styles:: Controlling how footnotes appear in Info. +@end menu + + +@node Footnote Commands +@subsection Footnote Commands + +In Texinfo, footnotes are created with the @code{@@footnote} command. +This command is followed immediately by a left brace, then by the text +of the footnote, and then by a terminating right brace. Footnotes may +be of any length (they will be broken across pages if necessary), but +are usually short. The template is: + +@example +ordinary text@@footnote@{@var{text of footnote}@} +@end example + +As shown here, the @code{@@footnote} command should come right after the +text being footnoted, with no intervening space; otherwise, the footnote +marker might end up starting a line. + +For example, this clause is followed by a sample footnote@footnote{Here +is the sample footnote.}; in the Texinfo source, it looks like +this: + +@example +@dots{}a sample footnote@@footnote@{Here is the sample +footnote.@}; in the Texinfo source@dots{} +@end example + +As you can see, the source includes two punctuation marks next to each +other; in this case, @samp{.@};} is the sequence. This is normal (the +first ends the footnote and the second belongs to the sentence being +footnoted), so don't worry that it looks odd. + +In a printed manual or book, the reference mark for a footnote is a +small, superscripted number; the text of the footnote appears at the +bottom of the page, below a horizontal line. + +In Info, the reference mark for a footnote is a pair of parentheses +with the footnote number between them, like this: @samp{(1)}. The +reference mark is followed by a cross-reference link to the footnote's +text. + +In the HTML output, footnote references are marked with a small, +superscripted number which is rendered as a hypertext link to the +footnote text. + +By the way, footnotes in the argument of an @code{@@item} command for a +@code{@@table} must be on the same line as the @code{@@item} +(as usual). @xref{Two-column Tables}. + + +@node Footnote Styles +@subsection Footnote Styles + +Info has two footnote styles, which determine where the text of the +footnote is located: + +@itemize @bullet +@cindex @samp{@r{End}} node footnote style +@item +In the `End' node style, all the footnotes for a single node +are placed at the end of that node. The footnotes are separated from +the rest of the node by a line of dashes with the word +@samp{Footnotes} within it. Each footnote begins with an +@samp{(@var{n})} reference mark. + +@need 700 +@noindent +Here is an example of a single footnote in the end of node style:@refill + +@example +@group +--------- Footnotes --------- + +(1) Here is a sample footnote. +@end group +@end example + +@cindex @samp{@r{Separate}} footnote style +@item +In the `Separate' node style, all the footnotes for a single +node are placed in an automatically constructed node of +their own. In this style, a ``footnote reference'' follows +each @samp{(@var{n})} reference mark in the body of the +node. The footnote reference is actually a cross reference +which you use to reach the footnote node. + +The name of the node with the footnotes is constructed +by appending @w{@samp{-Footnotes}} to the name of the node +that contains the footnotes. (Consequently, the footnotes' +node for the @file{Footnotes} node is +@w{@file{Footnotes-Footnotes}}!) The footnotes' node has an +`Up' node pointer that leads back to its parent node. + +@noindent +Here is how the first footnote in this manual looks after being +formatted for Info in the separate node style: + +@smallexample +@group +File: texinfo.info Node: Overview-Footnotes, Up: Overview + +(1) The first syllable of "Texinfo" is pronounced like "speck", not +"hex". @dots{} +@end group +@end smallexample +@end itemize + +Unless your document has long and important footnotes (as in, say, +Gibbon's @cite{Decline and Fall @dots{}}), we recommend the @samp{end} +style, as it is simpler for readers to follow. + +@findex footnotestyle +Use the @code{@@footnotestyle} command to specify an Info file's +footnote style. Write this command at the beginning of a line followed +by an argument, either @samp{end} for the end node style or +@samp{separate} for the separate node style. + +@need 700 +For example, + +@example +@@footnotestyle end +@end example +@noindent +or +@example +@@footnotestyle separate +@end example + +Write an @code{@@footnotestyle} command before or shortly after the +end-of-header line at the beginning of a Texinfo file. (If you +include the @code{@@footnotestyle} command between the start-of-header +and end-of-header lines, the region formatting commands will format +footnotes as specified.)@refill + +If you do not specify a footnote style, the formatting commands use +their default style. Currently, @code{texinfo-format-buffer} and +@code{texinfo-format-region} use the `separate' style and +@code{makeinfo} uses the `end' style. + + +@node Indices @chapter Indices @cindex Indices @@ -8828,24 +9595,27 @@ collate entries manually. In an index, the entries are listed in alphabetical order, together with information on how to find the discussion of each entry. In a printed manual, this information consists of page numbers. In an Info file, this information is a menu -entry leading to the first node referenced.@refill +entry leading to the first node referenced. Texinfo provides several predefined kinds of index: an index for functions, an index for variables, an index for concepts, and so on. You can combine indices or use them for other than their -canonical purpose. If you wish, you can define your own indices.@refill +canonical purpose. Lastly, you can define your own new indices. + +@xref{Printing Indices & Menus}, for information on how to print +indices. @menu * Index Entries:: Choose different words for index entries. * Predefined Indices:: Use different indices for different kinds - of entry. + of entries. * Indexing Commands:: How to make an index entry. * Combining Indices:: How to combine indices. * New Indices:: How to define your own indices. @end menu -@node Index Entries, Predefined Indices, Indices, Indices -@comment node-name, next, previous, up + +@node Index Entries @section Making Index Entries @cindex Index entries, making @cindex Entries, making index @@ -8869,45 +9639,65 @@ need to do it yourself.@refill @xref{Printing Indices & Menus}, for information about printing an index at the end of a book or creating an index menu in an Info file.@refill -@node Predefined Indices, Indexing Commands, Index Entries, Indices -@comment node-name, next, previous, up -@section Predefined Indices -Texinfo provides six predefined indices:@refill +@node Predefined Indices +@section Predefined Indices -@itemize @bullet -@item -A @dfn{concept index} listing concepts that are discussed.@refill +Texinfo provides six predefined indices. Here are their nominal +meanings, abbreviations, and the corresponding index entry commands: -@item -A @dfn{function index} listing functions (such as entry points of -libraries).@refill +@table @samp +@item cp +@cindex @code{cp} (concept) index +(@code{@@cindex}) concept index, for general concepts. +@item fn +@cindex @code{fn} (function) index +(@code{@@findex}) function index, for function and function-like +names (such as entry points of libraries). +@item ky +@cindex @code{ky} (keystroke) index +(@code{@@kindex}) keystroke index, for keyboard commands. +@item pg +@cindex @code{pg} (program) index +(@code{@@pindex}) program index, for names of programs. +@item tp +@cindex @code{tp} (data type) index +(@code{@@tindex}) data type index, for type names (such as structures +defined in header files). +@item vr +@cindex @code{vr} (variable) index +(@code{@@vindex}) variable index, for variable names (such as global +variables of libraries). +@end table -@item -A @dfn{variables index} listing variables (such as global variables -of libraries).@refill +@noindent +Not every manual needs all of these, and most manuals use only two or +three at most. The present manual, for example, has two indices: a +concept index and an @@-command index (that is actually the function +index but is called a command index in the chapter heading). -@item -A @dfn{keystroke index} listing keyboard commands.@refill +You are not required to use the predefined indices strictly for their +canonical purposes. For example, suppose you wish to index some C +preprocessor macros. You could put them in the function index along +with actual functions, just by writing @code{@@findex} commands for +them; then, when you print the ``Function Index'' as an unnumbered +chapter, you could give it the title `Function and Macro Index' and +all will be consistent for the reader. -@item -A @dfn{program index} listing names of programs.@refill +On the other hand, it is best not to stray too far from the meaning of +the predefined indices. Otherwise, in the event that your text is +combined with other text from other manuals, the index entries will +not match up. Instead, define your own new index (@pxref{New +Indices}). -@item -A @dfn{data type index} listing data types (such as structures defined in -header files).@refill -@end itemize +We recommend having a single index in the final document whenever +possible, however many source indices you use, since then readers have +only one place to look. Two or more source indices can be combined +into one output index using the @code{@@synindex} or +@code{@@syncodeindex} commands (@pxref{Combining Indices}). -@noindent -Not every manual needs all of these, and most manuals use two or three -of them. This manual has two indices: a -concept index and an @@-command index (that is actually the function -index but is called a command index in the chapter heading). Two or -more indices can be combined into one using the @code{@@synindex} or -@code{@@syncodeindex} commands. @xref{Combining Indices}.@refill -@node Indexing Commands, Combining Indices, Predefined Indices, Indices -@comment node-name, next, previous, up +@node Indexing Commands @section Defining the Entries of an Index @cindex Defining indexing entries @cindex Index entries @@ -8928,7 +9718,7 @@ the concept index:@refill @example @@cindex Defining indexing entries -@@cindex Index entries +@@cindex Index entries, defining @@cindex Entries for an index @@cindex Specifying index entries @@cindex Creating index entries @@ -8936,7 +9726,7 @@ the concept index:@refill Each predefined index has its own indexing command---@code{@@cindex} for the concept index, @code{@@findex} for the function index, and so -on.@refill +on, as listed in the previous section. @cindex Writing index entries @cindex Index entry writing @@ -8961,84 +9751,43 @@ Entries in indices other than the concept index are symbol names in programming languages, or program names; these names are usually case-sensitive, so use upper and lower case as required for them. +@cindex Index font types By default, entries for a concept index are printed in a small roman font and entries for the other indices are printed in a small @code{@@code} font. You may change the way part of an entry is printed with the usual Texinfo commands, such as @code{@@file} for -file names and @code{@@emph} for emphasis (@pxref{Marking -Text}).@refill -@cindex Index font types - -@cindex Predefined indexing commands -@cindex Indexing commands, predefined -The six indexing commands for predefined indices are: - -@table @code -@item @@cindex @var{concept} -@findex cindex -Make an entry in the concept index for @var{concept}.@refill - -@item @@findex @var{function} -@findex findex -Make an entry in the function index for @var{function}.@refill - -@item @@vindex @var{variable} -@findex vindex -Make an entry in the variable index for @var{variable}.@refill - -@item @@kindex @var{keystroke} -@findex kindex -Make an entry in the key index for @var{keystroke}.@refill - -@item @@pindex @var{program} -@findex pindex -Make an entry in the program index for @var{program}.@refill - -@item @@tindex @var{data type} -@findex tindex -Make an entry in the data type index for @var{data type}.@refill -@end table - -@quotation -@strong{Caution:} Do not use a colon in an index entry. In Info, a -colon separates the menu entry name from the node name, so a colon in -the entry itself confuses Info. @xref{Menu Parts, , The Parts of a -Menu}, for more information about the structure of a menu entry. +file names (@pxref{Marking Text}), and @code{@@r} for the normal roman +font (@pxref{Fonts}). + +@quotation Caution +Do not use a colon in an index entry. In Info, a colon separates the +menu entry name from the node name, so a colon in the entry itself +confuses Info. @xref{Menu Parts}, for more information about the +structure of a menu entry. @end quotation -You are not actually required to use the predefined indices for their -canonical purposes. For example, suppose you wish to index some C -preprocessor macros. You could put them in the function index along -with actual functions, just by writing @code{@@findex} commands for -them; then, when you print the ``Function Index'' as an unnumbered -chapter, you could give it the title `Function and Macro Index' and -all will be consistent for the reader. Or you could put the macros in -with the data types by writing @code{@@tindex} commands for them, and -give that index a suitable title so the reader will understand. -(@xref{Printing Indices & Menus}.)@refill -@node Combining Indices, New Indices, Indexing Commands, Indices -@comment node-name, next, previous, up +@node Combining Indices @section Combining Indices @cindex Combining indices @cindex Indices, combining them -Sometimes you will want to combine two disparate indices such as functions -and concepts, perhaps because you have few enough of one of them that -a separate index for them would look silly.@refill +Sometimes you will want to combine two disparate indices such as +functions and concepts, perhaps because you have few enough entries +that a separate index would look silly. You could put functions into the concept index by writing @code{@@cindex} commands for them instead of @code{@@findex} commands, and produce a consistent manual by printing the concept index with the title `Function and Concept Index' and not printing the `Function Index' at all; but this is not a robust procedure. It works only if -your document is never included as part of another -document that is designed to have a separate function index; if your -document were to be included with such a document, the functions from -your document and those from the other would not end up together. -Also, to make your function names appear in the right font in the -concept index, you would need to enclose every one of them between -the braces of @code{@@code}.@refill +your document is never included as part of another document that is +designed to have a separate function index; if your document were to +be included with such a document, the functions from your document and +those from the other would not end up together. Also, to make your +function names appear in the right font in the concept index, you +would need to enclose every one of them between the braces of +@code{@@code}. @menu * syncodeindex:: How to merge two indices, using @code{@@code} @@ -9055,7 +9804,6 @@ When you want to combine functions and concepts into one index, you should index the functions with @code{@@findex} and index the concepts with @code{@@cindex}, and use the @code{@@syncodeindex} command to redirect the function index entries into the concept index.@refill -@findex syncodeindex The @code{@@syncodeindex} command takes two arguments; they are the name of the index to redirect, and the name of the index to redirect it to. @@ -9117,7 +9865,7 @@ now directed. This way, if you direct function names from a function index into a concept index, all the function names are printed in the @code{@@code} font as you would expect.@refill -@node synindex, , syncodeindex, Combining Indices +@node synindex @subsection @code{@@synindex} @findex synindex @@ -9130,7 +9878,8 @@ merge a concept index into a function index.@refill @xref{Printing Indices & Menus}, for information about printing an index at the end of a book or creating an index menu in an Info file.@refill -@node New Indices, , Combining Indices, Indices + +@node New Indices @section Defining New Indices @cindex Defining new indices @cindex Indices, defining new @@ -9141,15 +9890,15 @@ at the end of a book or creating an index menu in an Info file.@refill In addition to the predefined indices, you may use the @code{@@defindex} and @code{@@defcodeindex} commands to define new indices. These commands create new indexing @@-commands with which -you mark index entries. The @code{@@defindex }command is used like -this:@refill +you mark index entries. The @code{@@defindex} command is used like +this: @example @@defindex @var{name} @end example The name of an index should be a two letter word, such as @samp{au}. -For example:@refill +For example: @example @@defindex au @@ -9157,11 +9906,11 @@ For example:@refill This defines a new index, called the @samp{au} index. At the same time, it creates a new indexing command, @code{@@auindex}, that you -can use to make index entries. Use the new indexing command just as -you would use a predefined indexing command.@refill +can use to make index entries. Use this new indexing command just as +you would use a predefined indexing command. For example, here is a section heading followed by a concept index -entry and two @samp{au} index entries.@refill +entry and two @samp{au} index entries. @example @@section Cognitive Semantics @@ -9172,29 +9921,30 @@ entry and two @samp{au} index entries.@refill @noindent (Evidently, @samp{au} serves here as an abbreviation for ``author''.) -Texinfo constructs the new indexing command by concatenating the name -of the index with @samp{index}; thus, defining an @samp{au} index -leads to the automatic creation of an @code{@@auindex} command.@refill + +In general, Texinfo constructs the new indexing command by +concatenating the name of the index with @samp{index}; thus, defining +an @samp{xy} index leads to the automatic creation of an +@code{@@xyindex} command. Use the @code{@@printindex} command to print the index, as you do with -the predefined indices. For example:@refill +the predefined indices. For example: @example @group -@@node Author Index, Subject Index, , Top +@@node Author Index @@unnumbered Author Index @@printindex au @end group @end example -The @code{@@defcodeindex} is like the @code{@@defindex} command, except -that, in the printed output, it prints entries in an @code{@@code} font -instead of a roman font. Thus, it parallels the @code{@@findex} command -rather than the @code{@@cindex} command.@refill +The @code{@@defcodeindex} is like the @code{@@defindex} command, +except that, in the printed output, it prints entries in an +@code{@@code} font by default instead of a roman font. -You should define new indices within or right after the end-of-header -line of a Texinfo file, before any @code{@@synindex} or +You should define new indices before the end-of-header line of a +Texinfo file, and (of course) before any @code{@@synindex} or @code{@@syncodeindex} commands (@pxref{Texinfo File Header}). @@ -9211,7 +9961,7 @@ elements that do not correspond to simple characters you can type. These are: @itemize @bullet -@item Braces and @samp{@@}. +@item @samp{@@} and braces and commas. @item Whitespace within and around a sentence. @item Accents. @item Dots and bullets. @@ -9226,28 +9976,25 @@ These are: @end iftex @menu -* Braces Atsigns:: How to insert braces, @samp{@@}. +* Atsign Braces Comma:: Inserting @@ and @{@} and ,. * Inserting Space:: How to insert the right amount of space within a sentence. * Inserting Accents:: How to insert accents and special characters. * Dots Bullets:: How to insert dots and bullets. * TeX and copyright:: How to insert the @TeX{} logo and the copyright symbol. +* euro:: How to insert the Euro currency symbol. * pounds:: How to insert the pounds currency symbol. * minus:: How to insert a minus sign. * math:: How to format a mathematical expression. * Glyphs:: How to indicate results of evaluation, expansion of macros, errors, etc. -* Footnotes:: How to include footnotes. -* Images:: How to include graphics. @end menu -@node Braces Atsigns, Inserting Space, Insertions, Insertions -@section Inserting @@ and Braces -@cindex Inserting @@, braces -@cindex Braces, inserting -@cindex Special characters, commands to insert +@node Atsign Braces Comma +@section Inserting @@ and @{@} and @comma{} +@cindex Special characters, inserting @cindex Commands to insert special characters @samp{@@} and curly braces are special characters in Texinfo. To insert @@ -9255,17 +10002,20 @@ these characters so they appear in text, you must put an @samp{@@} in front of these characters to prevent Texinfo from misinterpreting them. -Do not put braces after any of these commands; they are not -necessary. +The comma `,' is a special character only in one uncommon context: +it separates arguments to commands that take multiple arguments. @menu -* Inserting An Atsign:: How to insert @samp{@@}. -* Inserting Braces:: How to insert @samp{@{} and @samp{@}}. +* Inserting an Atsign:: +* Inserting Braces:: +* Inserting a Comma:: @end menu -@node Inserting An Atsign, Inserting Braces, Braces Atsigns, Braces Atsigns -@subsection Inserting @samp{@@} with @@@@ + +@node Inserting an Atsign +@subsection Inserting `@@' with @code{@@@@} @findex @@ @r{(literal @samp{@@})} +@cindex Inserting @@ @r{(literal @samp{@@})} @code{@@@@} stands for a single @samp{@@} in either printed or Info output. @@ -9274,7 +10024,8 @@ Do not put braces after an @code{@@@@} command. @node Inserting Braces -@subsection Inserting @samp{@{} and @samp{@}}with @@@{ and @@@} +@subsection Inserting `@{' and `@}' with @code{@@@{} and @code{@@@}} +@cindex Braces, inserting @findex @{ @r{(literal @samp{@{})} @findex @} @r{(literal @samp{@}})} @@ -9285,7 +10036,35 @@ output. output. Do not put braces after either an @code{@@@{} or an @code{@@@}} -command. +command.ppp + + +@node Inserting a Comma +@subsection Inserting `,' with @code{@@comma@{@}} +@cindex Commas, inserting +@findex comma + +Ordinarily, a comma `,' is a normal character that can be simply typed +in your input where you need it. + +However, Texinfo uses the comma as a special character in one uncommon +context: some commands, such as @code{@@acronym} (@pxref{acronym}) and +@code{@@xref} (@pxref{Cross References}), as well as user-defined +macros (@pxref{Defining Macros}), can take more than one argument. In +these cases, the comma character is used to separate arguments. + +Since a comma chacter would confuse Texinfo's parsing for these +commands, you must use the command @samp{@comma{}} instead if you want +to have an actual comma in the output. Here are some examples: + +@example +@@acronym@{ABC, A Bizarre @@comma@{@}@} +@@xref@{Comma,, The @@comma@{@} symbol@} +@@mymac@{One argument@@comma@{@} containing a comma@} +@end example + +Although @comma{} can be used anywhere, there is no need for it +anywhere except in this unusual case. @node Inserting Space @@ -9320,7 +10099,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 <colon> @r{(suppress widening)} +@findex <colon> @r{(suppress end-of-sentence space)} Use the @code{@@:}@: command after a period, question mark, exclamation mark, or colon that should not be followed by extra space. For example, use @code{@@:}@: after periods that end abbreviations @@ -9334,13 +10113,13 @@ The s.o.p. has three parts @dots{} @end example @noindent -@ifinfo +@ifnottex produces -@end ifinfo +@end ifnottex @iftex produces the following. If you look carefully at this printed output, -you will see a little more whitespace after @samp{s.o.p.} in the second -line.@refill +you will see a little extraneous space after @samp{s.o.p.} in the second +line. @end iftex @quotation @@ -9352,11 +10131,16 @@ The s.o.p. has three parts @dots{} (Incidentally, @samp{s.o.p.} is an abbreviation for ``Standard Operating Procedure''.) -@code{@@:} has no effect on the Info output. Do not put braces after -@code{@@:}. +@code{@@:} has no effect on the Info and HTML output. In Docbook and +XML, the previous punctuation character (.?!:) is output as an entity +instead of as the normal character: @samp{. ? ! +:}. This gives further processors a chance to notice and not +add the usual extra space. + +Do not put braces after @code{@@:} (or any non-alphabetic command). -@node Ending a Sentence, Multiple Spaces, Not Ending a Sentence, Inserting Space +@node Ending a Sentence @subsection Ending a Sentence @cindex Ending a Sentence @@ -9367,7 +10151,7 @@ Procedure''.) @findex ? @r{(end of sentence)} Use @code{@@.}@: instead of a period, @code{@@!}@: instead of an exclamation point, and @code{@@?}@: instead of a question mark at the end -of a sentence that ends with a single capital letter. Otherwise, @TeX{} +of a sentence that ends with a capital letter. Otherwise, @TeX{} will think the letter is an abbreviation and will not insert the correct end-of-sentence spacing. Here is an example: @@ -9377,9 +10161,9 @@ Give it to M.I.B. and to M.E.W. Also, give it to R.J.C. @end example @noindent -@ifinfo +@ifnottex produces -@end ifinfo +@end ifnottex @iftex produces the following. If you look carefully at this printed output, you will see a little more whitespace after the @samp{W} in the first @@ -9407,9 +10191,9 @@ Do not put braces after any of these commands. @cindex Multiple spaces @cindex Whitespace, inserting @cindex Space, inserting horizontal -@findex (space) -@findex (tab) -@findex (newline) +@findex <space> +@findex <tab> +@findex <newline> Ordinarily, @TeX{} collapses multiple whitespace characters (space, tab, and newline) into a single space. Info output, on the other hand, @@ -9534,8 +10318,10 @@ option to @command{makeinfo} (@pxref{makeinfo options}). @findex udotaccent @cindex Underdot accent @findex v @r{(check accent)} +@cindex Hacek accent @cindex Check accent -@multitable {@@questiondown@{@}} {Output} {macron/overbar accent} +@cindex Caron accent +@multitable {@@questiondown@{@}} {Output} {hacek/check/caron accent} @item Command @tab Output @tab What @item @t{@@"o} @tab @"o @tab umlaut accent @item @t{@@'o} @tab @'o @tab acute accent @@ -9551,7 +10337,7 @@ option to @command{makeinfo} (@pxref{makeinfo options}). @item @t{@@u@{o@}} @tab @u{o} @tab breve accent @item @t{@@ubaraccent@{o@}} @tab @ubaraccent{o} @tab underbar accent @item @t{@@udotaccent@{o@}} @tab @udotaccent{o} @tab underdot accent -@item @t{@@v@{o@}} @tab @v{o} @tab hacek or check accent +@item @t{@@v@{o@}} @tab @v{o} @tab hacek/check/caron accent @end multitable This table lists the Texinfo commands for inserting other characters @@ -9570,8 +10356,8 @@ commonly used in languages other than English. @findex AE @cindex @AE{} @findex dotless -@cindex @dotless{i} -@cindex @dotless{j} +@cindex @dotless{i} (dotless i) +@cindex @dotless{j} (dotless j) @cindex Dotless i, j @findex l @cindex @l{} @@ -9585,21 +10371,30 @@ commonly used in languages other than English. @cindex @oe{} @findex OE @cindex @OE{} +@cindex Romance ordinals +@cindex Ordinals, Romance +@cindex Feminine ordinal +@findex ordf +@cindex @ordf{} +@cindex Masculine ordinal +@findex ordm +@cindex @ordm{} @findex ss @cindex @ss{} @cindex Es-zet @cindex Sharp S @cindex German S -@multitable {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 -@item @t{@@ae@{@},@@AE@{@}} @tab @ae{},@AE{} @tab ae,AE ligatures +@item @t{@@aa@{@} @@AA@{@}} @tab @aa{} @AA{} @tab a,A with circle +@item @t{@@ae@{@} @@AE@{@}} @tab @ae{} @AE{} @tab ae,AE ligatures @item @t{@@dotless@{i@}} @tab @dotless{i} @tab dotless i @item @t{@@dotless@{j@}} @tab @dotless{j} @tab dotless j -@item @t{@@l@{@},@@L@{@}} @tab @l{},@L{} @tab suppressed-L,l -@item @t{@@o@{@},@@O@{@}} @tab @o{},@O{} @tab O,o with slash -@item @t{@@oe@{@},@@OE@{@}} @tab @oe{},@OE{} @tab oe,OE ligatures +@item @t{@@l@{@} @@L@{@}} @tab @l{} @L{} @tab suppressed-L,l +@item @t{@@o@{@} @@O@{@}} @tab @o{} @O{} @tab O,o with slash +@item @t{@@oe@{@} @@OE@{@}} @tab @oe{} @OE{} @tab oe,OE ligatures +@item @t{@@ordf@{@} @@ordm@{@}} @tab @ordf{} @ordm{} @tab Spanish ordinals @item @t{@@ss@{@}} @tab @ss{} @tab es-zet or sharp S @end multitable @@ -9637,13 +10432,14 @@ the braces, the formatters would be confused. @xref{Command Syntax, , @cindex Dots, inserting Use the @code{@@dots@{@}} command to generate an ellipsis, which is -three dots in a row, appropriately spaced, like this: `@dots{}'. Do +three dots in a row, appropriately spaced @dots{} like so. Do not simply write three periods in the input file; that would work for the Info file output, but would produce the wrong amount of space between the periods in the printed manual. Similarly, the @code{@@enddots@{@}} command generates an -end-of-sentence ellipsis (four dots) @enddots{} +end-of-sentence ellipsis, which has different spacing afterwards, +@enddots{} Look closely to see the difference. @iftex Here is an ellipsis: @dots{} @@ -9668,57 +10464,100 @@ type the braces, because @code{@@itemize} supplies them. (@xref{itemize, , @code{@@itemize}}.)@refill -@node TeX and copyright, pounds, Dots Bullets, Insertions -@section Inserting @TeX{} and the Copyright Symbol +@node TeX and copyright +@section Inserting @TeX{} and Legal Symbols: @copyright{}, @registeredsymbol{} The logo `@TeX{}' is typeset in a special fashion and it needs an -@@-command. The copyright symbol, `@copyright{}', is also special. -Each of these commands is followed by a pair of braces, @samp{@{@}}, -without any whitespace between the name of the command and the -braces.@refill +@@-command. The copyright and registered symbols, `@copyright{}' and +`@registeredsymbol{}', is also special. Each of these commands is +followed by a pair of braces, @samp{@{@}}, without any whitespace +between the name of the command and the braces. @menu -* tex:: How to insert the @TeX{} logo. -* copyright symbol:: How to use @code{@@copyright@{@}}. +* tex:: The @TeX{} logos. +* copyright symbol:: The copyright symbol (c in a circle). +* registered symbol:: The registered symbol (R in a circle). @end menu @node tex -@subsection @code{@@TeX}@{@} (@TeX{}) -@findex tex (command) +@subsection @code{@@TeX}@{@} (@TeX{}) and @code{@@LaTeX}@{@} (@LaTeX{}) +@findex TeX +@findex LaTeX Use the @code{@@TeX@{@}} command to generate `@TeX{}'. In a printed manual, this is a special logo that is different from three ordinary -letters. In Info, it just looks like @samp{TeX}. The -@code{@@TeX@{@}} command is unique among Texinfo commands in that the -@samp{T} and the @samp{X} are in upper case.@refill +letters. In Info, it just looks like @samp{TeX}. + +Similarly, use the @code{@@LaTeX@{@}} command to generate `@LaTeX{}', +which is even more special in printed manuals (and different from the +incorrect @code{La@@TeX@{@}}. In Info, the result is just +@samp{LaTeX}. (@LaTeX{} is another macro package built on top of +@TeX{}, very loosely analogous to Texinfo in that it emphasizes +logical structure, but much (much) larger.) + +The spelling of these commands are unusual among Texinfo commands in +that they use both uppercase and lowercase letters. @node copyright symbol @subsection @code{@@copyright@{@}} (@copyright{}) @findex copyright -Use the @code{@@copyright@{@}} command to generate `@copyright{}'. In -a printed manual, this is a @samp{c} inside a circle, and in Info, -this is @samp{(C)}. +Use the @code{@@copyright@{@}} command to generate the copyright +symbol, `@copyright{}'. Where possible, this is a @samp{c} +inside a circle; in Info, this is @samp{(C)}. + +@node registered symbol +@subsection @code{@@registeredsymbol@{@}} (@registeredsymbol{}) +@findex registeredsymbol -@node pounds, minus, TeX and copyright, Insertions +Use the @code{@@registeredsymbol@{@}} command to generate the +registered symbol, `@registeredsymbol{}'. Where possible, this is an +@samp{R} inside a circle; in Info, this is @samp{(R)}. + + +@node euro +@section @code{@@euro}@{@} (@euro{}): Euro currency symbol +@findex euro + +Use the @code{@@euro@{@}} command to generate `@euro{}'. Where +possible, this is the symbol for the Euro currency, invented as part +of the European economic unification relatively recently. In plain +Info, it is the word @samp{Euro }. (The space is included in the text +transliteration since typically there would be no space after the +symbol, so it would be inappropriate to have a space in the source document.) + +Texinfo cannot magically synthesize support for the Euro symbol where +the underlying system (fonts, software, whatever) does not support +it. Therefore, in many cases it is preferable to use the word +``Euro''. (In banking circles, the abbreviation for the Euro is EUR.) + +@cindex ISO 8859-15 +@cindex Latin 9 +In order to get the Euro symbol in encoded Info output, for example, +it is necessary to specify @code{@@documentencoding ISO-8859-15}. +(@xref{documentencoding,,@code{@@documentencoding}}.) The Euro symbol +is in ISO 8859-15 (aka Latin@tie{}9), and is @emph{not} in the more +widely-used and supported ISO 8859-1 (Latin@tie{}1). + + +@node pounds @section @code{@@pounds}@{@} (@pounds{}): Pounds Sterling @findex pounds -Use the @code{@@pounds@{@}} command to generate `@pounds{}'. In a -printed manual, this is the symbol for the currency pounds sterling. -In Info, it is a @samp{#}. Other currency symbols are unfortunately not -available. +Use the @code{@@pounds@{@}} command to generate `@pounds{}'. Where +possible, this is the symbol for the currency pounds sterling. In +Info, it is a @samp{#}. -@node minus, math, pounds, Insertions +@node minus @section @code{@@minus}@{@} (@minus{}): Inserting a Minus Sign @findex minus -@cindex em-dash -@cindex hyphen +@cindex Em dash, compared to minus sign +@cindex Hyphen, compared to minus Use the @code{@@minus@{@}} command to generate a minus sign. In a fixed-width font, this is a single hyphen, but in a proportional font, the symbol is the customary length for a minus sign---a little longer @@ -9742,7 +10581,7 @@ fixed-width font they use. When you use @code{@@minus} to specify the mark beginning each entry in an itemized list, you do not need to type the braces -(@pxref{itemize, , @code{@@itemize}}.) +(@pxref{itemize, , @code{@@itemize}}). @node math @@ -9765,19 +10604,19 @@ command. Write the mathematical expression between braces, like this: @math{(a + b)(a + b) = a^2 + 2ab + b^2} @end display -@noindent and the following in Info: +@noindent and the following in other formats: @end iftex -@ifinfo -@noindent This produces the following in Info: -@end ifinfo +@ifnottex +@noindent This produces the following in Info and HTML: +@end ifnottex @example (a + b)(a + b) = a^2 + 2ab + b^2 @end example -Thus, the @code{@@math} command has no effect on the Info output; -@command{makeinfo} just reproduces the input, it does not try to -interpret the mathematics in any way. +Thus, the @code{@@math} command has no effect on the Info and HTML +output; @command{makeinfo} just reproduces the input, it does not try +to interpret the mathematics in any way. @code{@@math} implies @code{@@tex}. This not only makes it possible to write superscripts and subscripts (as in the above example), but also @@ -9892,13 +10731,13 @@ Use the @code{@@result@{@}} command to indicate the result of evaluating an expression.@refill @iftex -The @code{@@result@{@}} command is displayed as @samp{=>} in Info and -as @samp{@result{}} in the printed output. +The @code{@@result@{@}} command is displayed as @samp{@result{}} in +the printed output and as @samp{=>} in other formats. @end iftex -@ifinfo -The @code{@@result@{@}} command is displayed as @samp{@result{}} in Info -and as a double stemmed arrow in the printed output.@refill -@end ifinfo +@ifnottex +The @code{@@result@{@}} command is displayed as @samp{@result{}} in +Info and HTML and as a true double stemmed arrow in the printed output. +@end ifnottex Thus, the following, @@ -9911,9 +10750,10 @@ Thus, the following, may be read as ``@code{(cdr '(1 2 3))} evaluates to @code{(2 3)}''. -@node expansion, Print Glyph, result, Glyphs +@node expansion @subsection @code{@@expansion@{@}} (@expansion{}): Indicating an Expansion -@cindex Expansion, indicating it +@cindex Expansion, indicating +@cindex Macro expansion, indicating @findex expansion When an expression is a macro call, it expands into a new expression. @@ -9921,13 +10761,14 @@ You can indicate the result of the expansion with the @code{@@expansion@{@}} command.@refill @iftex -The @code{@@expansion@{@}} command is displayed as @samp{==>} in Info and -as @samp{@expansion{}} in the printed output. +The @code{@@expansion@{@}} command is displayed as @samp{@expansion{}} +in the printed output. and as @samp{==>} in other formats. @end iftex -@ifinfo +@ifnottex The @code{@@expansion@{@}} command is displayed as @samp{@expansion{}} -in Info and as a long arrow with a flat base in the printed output.@refill -@end ifinfo +in Info and HTML, and as a long arrow with a flat base in the printed +output. +@end ifnottex @need 700 For example, the following @@ -9963,13 +10804,12 @@ the result of evaluating the expression is @code{c}. @noindent Often, as in this case, an example looks better if the -@code{@@expansion@{@}} and @code{@@result@{@}} commands are indented -five spaces.@refill +@code{@@expansion@{@}} and @code{@@result@{@}} commands are indented. -@node Print Glyph, Error Glyph, expansion, Glyphs +@node Print Glyph @subsection @code{@@print@{@}} (@print{}): Indicating Printed Output -@cindex Printed output, indicating it +@cindex Printed output, indicating @findex print Sometimes an expression will print output during its execution. You @@ -9977,17 +10817,17 @@ can indicate the printed output with the @code{@@print@{@}} command.@refill @iftex The @code{@@print@{@}} command is displayed as @samp{-|} in Info and -as @samp{@print{}} in the printed output. +HTML and as @samp{@print{}} in the printed output. @end iftex -@ifinfo +@ifnottex The @code{@@print@{@}} command is displayed as @samp{@print{}} in Info -and similarly, as a horizontal dash butting against a vertical bar, in -the printed output.@refill -@end ifinfo +and HTML and (similarly) as a horizontal dash butting against a +vertical bar in the printed output. +@end ifnottex In the following example, the printed text is indicated with @samp{@print{}}, and the value of the expression follows on the -last line.@refill +last line. @lisp @group @@ -10013,9 +10853,9 @@ In a Texinfo source file, this example is written as follows: @end lisp -@node Error Glyph, Equivalence, Print Glyph, Glyphs +@node Error Glyph @subsection @code{@@error@{@}} (@error{}): Indicating an Error Message -@cindex Error message, indicating it +@cindex Error message, indicating @findex error A piece of code may cause an error when you evaluate it. You can @@ -10023,12 +10863,12 @@ designate the error message with the @code{@@error@{@}} command.@refill @iftex The @code{@@error@{@}} command is displayed as @samp{error-->} in Info -and as @samp{@error{}} in the printed output. +and HTML and as @samp{@error{}} in the printed output. @end iftex -@ifinfo +@ifnottex The @code{@@error@{@}} command is displayed as @samp{@error{}} in Info -and as the word `error' in a box in the printed output.@refill -@end ifinfo +and HTML and as the word `error' in a box in the printed output. +@end ifnottex @need 700 Thus, @@ -10059,9 +10899,9 @@ Wrong type argument: integer-or-marker-p, x @samp{@error{}} itself is not part of the error message. -@node Equivalence, Point Glyph, Error Glyph, Glyphs +@node Equivalence @subsection @code{@@equiv@{@}} (@equiv{}): Indicating Equivalence -@cindex Equivalence, indicating it +@cindex Equivalence, indicating @findex equiv Sometimes two expressions produce identical results. You can indicate the @@ -10069,12 +10909,13 @@ exact equivalence of two forms with the @code{@@equiv@{@}} command.@refill @iftex The @code{@@equiv@{@}} command is displayed as @samp{==} in Info and -as @samp{@equiv{}} in the printed output. +HTML and as @samp{@equiv{}} in the printed output. @end iftex -@ifinfo +@ifnottex The @code{@@equiv@{@}} command is displayed as @samp{@equiv{}} in Info -and as a three parallel horizontal lines in the printed output.@refill -@end ifinfo +and HTML and as a standard mathematical equivalence sign (three +parallel horizontal lines) in the printed output. +@end ifnottex Thus, @@ -10113,12 +10954,13 @@ two characters where point is located.)@refill @iftex The @code{@@point@{@}} command is displayed as @samp{-!-} in Info and -as @samp{@point{}} in the printed output. +HTML and as @samp{@point{}} in the printed output. @end iftex -@ifinfo +@ifnottex The @code{@@point@{@}} command is displayed as @samp{@point{}} in Info -and as a small five pointed star in the printed output.@refill -@end ifinfo +and HTML and as a small five pointed star in the printed +output. +@end ifnottex The following example shows the contents of buffer @file{foo} before and after evaluating a Lisp command to insert the word @code{changed}.@refill @@ -10160,376 +11002,9 @@ This is the changed @@point@{@}contents of foo. @end example -@node Footnotes -@section Footnotes -@cindex Footnotes -@findex footnote - -A @dfn{footnote} is for a reference that documents or elucidates the -primary text.@footnote{A footnote should complement or expand upon -the primary text, but a reader should not need to read a footnote to -understand the primary text. For a thorough discussion of footnotes, -see @cite{The Chicago Manual of Style}, which is published by the -University of Chicago Press.} - -@menu -* Footnote Commands:: How to write a footnote in Texinfo. -* Footnote Styles:: Controlling how footnotes appear in Info. -@end menu - - -@node Footnote Commands -@subsection Footnote Commands - -In Texinfo, footnotes are created with the @code{@@footnote} command. -This command is followed immediately by a left brace, then by the text -of the footnote, and then by a terminating right brace. Footnotes may -be of any length (they will be broken across pages if necessary), but -are usually short. The template is: - -@example -ordinary text@@footnote@{@var{text of footnote}@} -@end example - -As shown here, the @code{@@footnote} command should come right after the -text being footnoted, with no intervening space; otherwise, the footnote -marker might end up starting a line. - -For example, this clause is followed by a sample footnote@footnote{Here -is the sample footnote.}; in the Texinfo source, it looks like -this: - -@example -@dots{}a sample footnote@@footnote@{Here is the sample -footnote.@}; in the Texinfo source@dots{} -@end example - -As you can see, the source includes two punctuation marks next to each -other; in this case, @samp{.@};} is the sequence. This is normal (the -first ends the footnote and the second belongs to the sentence being -footnoted), so don't worry that it looks odd. - -In a printed manual or book, the reference mark for a footnote is a -small, superscripted number; the text of the footnote appears at the -bottom of the page, below a horizontal line. - -In Info, the reference mark for a footnote is a pair of parentheses -with the footnote number between them, like this: @samp{(1)}. The -reference mark is followed by a cross-reference link to the footnote's -text. - -In the HTML output, footnote references are marked with a small, -superscripted number which is rendered as a hypertext link to the -footnote text. - -By the way, footnotes in the argument of an @code{@@item} command for a -@code{@@table} must be on the same line as the @code{@@item} -(as usual). @xref{Two-column Tables}. - - -@node Footnote Styles -@subsection Footnote Styles - -Info has two footnote styles, which determine where the text of the -footnote is located:@refill - -@itemize @bullet -@cindex @samp{@r{End}} node footnote style -@item -In the `End' node style, all the footnotes for a single node -are placed at the end of that node. The footnotes are separated from -the rest of the node by a line of dashes with the word -@samp{Footnotes} within it. Each footnote begins with an -@samp{(@var{n})} reference mark.@refill - -@need 700 -@noindent -Here is an example of a single footnote in the end of node style:@refill - -@example -@group ---------- Footnotes --------- - -(1) Here is a sample footnote. -@end group -@end example - -@cindex @samp{@r{Separate}} footnote style -@item -In the `Separate' node style, all the footnotes for a single -node are placed in an automatically constructed node of -their own. In this style, a ``footnote reference'' follows -each @samp{(@var{n})} reference mark in the body of the -node. The footnote reference is actually a cross reference -which you use to reach the footnote node.@refill - -The name of the node with the footnotes is constructed -by appending @w{@samp{-Footnotes}} to the name of the node -that contains the footnotes. (Consequently, the footnotes' -node for the @file{Footnotes} node is -@w{@file{Footnotes-Footnotes}}!) The footnotes' node has an -`Up' node pointer that leads back to its parent node.@refill - -@noindent -Here is how the first footnote in this manual looks after being -formatted for Info in the separate node style:@refill - -@smallexample -@group -File: texinfo.info Node: Overview-Footnotes, Up: Overview - -(1) The first syllable of "Texinfo" is pronounced like "speck", not -"hex". @dots{} -@end group -@end smallexample -@end itemize - -A Texinfo file may be formatted into an Info file with either footnote -style.@refill - -@findex footnotestyle -Use the @code{@@footnotestyle} command to specify an Info file's -footnote style. Write this command at the beginning of a line followed -by an argument, either @samp{end} for the end node style or -@samp{separate} for the separate node style. - -@need 700 -For example, - -@example -@@footnotestyle end -@end example -@noindent -or -@example -@@footnotestyle separate -@end example - -Write an @code{@@footnotestyle} command before or shortly after the -end-of-header line at the beginning of a Texinfo file. (If you -include the @code{@@footnotestyle} command between the start-of-header -and end-of-header lines, the region formatting commands will format -footnotes as specified.)@refill - -If you do not specify a footnote style, the formatting commands use -their default style. Currently, @code{texinfo-format-buffer} and -@code{texinfo-format-region} use the `separate' style and -@code{makeinfo} uses the `end' style.@refill - -@c !!! note: makeinfo's --footnote-style option overrides footnotestyle -@ignore -If you use @code{makeinfo} to create the Info file, the -@samp{--footnote-style} option determines which style is used, -@samp{end} for the end of node style or @samp{separate} for the -separate node style. Thus, to format the Texinfo manual in the -separate node style, you would use the following shell command:@refill - -@example -makeinfo --footnote-style=separate texinfo.texi -@end example - -@noindent -To format the Texinfo manual in the end of node style, you would -type:@refill - -@example -makeinfo --footnote-style=end texinfo.texi -@end example -@end ignore -@ignore -If you use @code{texinfo-format-buffer} or -@code{texinfo-format-region} to create the Info file, the value of the -@code{texinfo-footnote-style} variable controls the footnote style. -It can be either @samp{"separate"} for the separate node style or -@samp{"end"} for the end of node style. (You can change the value of -this variable with the @kbd{M-x edit-options} command (@pxref{Edit -Options, , Editing Variable Values, emacs, The GNU Emacs Manual}), or -with the @kbd{M-x set-variable} command (@pxref{Examining, , Examining -and Setting Variables, emacs, The GNU Emacs Manual}).@refill - -The @code{texinfo-footnote-style} variable also controls the style if -you use the @kbd{M-x makeinfo-region} or @kbd{M-x makeinfo-buffer} -command in Emacs.@refill -@end ignore -@ifinfo -This chapter contains two footnotes.@refill -@end ifinfo - - -@c This should be described along with figures when we have them; -@c perhaps in the quotation/example chapter. -@node Images -@section Inserting Images - -@cindex Images, inserting -@cindex Pictures, inserting -@findex image - -You can insert an image given in an external file with the -@code{@@image} command. - -@menu -* Image Syntax:: -* Image Scaling:: -@end menu - - -@node Image Syntax -@subsection Image Syntax - -Here is the basic synopsis of the @code{@@image} command: - -@example -@@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 -@cindex Image formats -The @var{filename} argument is mandatory, and must not have an -extension, because the different processors support different formats: - -@itemize @bullet -@item -@TeX{} reads the file @file{@var{filename}.eps} (Encapsulated PostScript -format). -@item -@pindex pdftex@r{, and images} -PDF@TeX{} reads @file{@var{filename}.pdf} (Adobe's Portable Document Format). -@item -@code{makeinfo} includes @file{@var{filename}.txt} verbatim for -Info output (more or less as if it was an @code{@@example}). -@item -@code{makeinfo} uses the optional fifth argument @var{extension} to -@code{@@image} for the filename extension, if it is specified. For example: - -@pindex XPM image format -@example -@@image@{foo,,,,xpm@} -@end example - -@noindent -will cause @code{makeinfo} to look for @file{foo.xpm} before any others. - -@end itemize - -The @var{width} and @var{height} arguments are described in the next -section. - -@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. - -@cindex GIF, unsupported due to patents -@cindex PNG image format -@cindex JPG image format -If you do not supply the optional fifth argument, @code{makeinfo} -first tries @file{@var{filename}.png}; if that does not exist, it -tries @file{@var{filename}.jpg}. If that does not exist either, it -complains. (We cannot support GIF format directly due to software -patents.) - -In Info output, @code{makeinfo} writes a reference to the binary image -file (with the @file{.@var{extension}}, @file{.png}, or @file{.jpg} -suffix) if it exists. It also physically includes the @file{.txt} -file if that exists. This way, Info readers which can display images -(such as the Emacs Info browser) can do so, whereas Info readers which -can only use text (such as the standalone Info reader) can display the -textual version. - -The implementation of this is to put the following construct into the -Info output: - -@example -^@^H[image src="@var{binaryfile}" text="@var{txtfile}" - alt="@var{alttext} ... ^@^H] -@end example - -@noindent (If one of the files is not present, the corresponding argument -is omitted.) - -The reason for mentioning this here is that older Info browsers (this -feature was introduced in Texinfo version 4.6) will display the above -literally, which, although not ideal, should not be harmful. - - -@node Image Scaling -@subsection Image Scaling - -@cindex Images, scaling -@cindex Scaling images -@cindex Width of images -@cindex Height of images -@cindex Aspect ratio of images -@cindex Distorting images -The optional @var{width} and @var{height} arguments to the -@code{@@image} command (see the previous section) specify the size to -scale the image to. They are ignored for Info output. If neither is -specified, the image is presented in its natural size (given in the -file); if only one is specified, the other is scaled proportionately; -and if both are specified, both are respected, thus possibly distorting -the original image by changing its aspect ratio. - -@cindex Dimensions and image sizes -The @var{width} and @var{height} may be specified using any valid @TeX{} -dimension, namely: - -@table @asis -@item pt -@cindex Points (dimension) -point (72.27pt = 1in) -@item pc -@cindex Picas -pica (1pc = 12pt) -@item bp -@cindex Big points -big point (72bp = 1in) -@item in -@cindex Inches -inch -@item cm -@cindex Centimeters -centimeter (2.54cm = 1in) -@item mm -@cindex Millimeters -millimeter (10mm = 1cm) -@item dd -@cindex Did@^ot points -did@^ot point (1157dd = 1238pt) -@item cc -@cindex Ciceros -cicero (1cc = 12dd) -@item sp -@cindex Scaled points -scaled point (65536sp = 1pt) -@end table - -@pindex ridt.eps -For example, the following will scale a file @file{ridt.eps} to one -inch vertically, with the width scaled proportionately: - -@example -@@image@{ridt,,1in@} -@end example - -@pindex epsf.tex -For @code{@@image} to work with @TeX{}, the file @file{epsf.tex} must be -installed somewhere that @TeX{} can find it. (The standard location is -@file{@var{texmf}/tex/generic/dvips/epsf.tex}, where @var{texmf} is a -root of your @TeX{} directory tree.) This file is included in the -Texinfo distribution and is also available from -@uref{ftp://tug.org/tex/epsf.tex}, among other places. - -@code{@@image} can be used within a line as well as for displayed -figures. Therefore, if you intend it to be displayed, be sure to leave -a blank line before the command, or the output will run into the -preceding text. - - @node Breaks -@chapter Making and Preventing Breaks +@chapter Forcing and Preventing Breaks +@cindex Forcing line and page breaks @cindex Making line and page breaks @cindex Preventing line and page breaks @@ -10637,11 +11112,6 @@ in two places. @end group @end example -Do not write an @code{@@refill} command at the end of a paragraph -containing an @code{@@*} command; it will cause the paragraph to be -refilled after the line break occurs, negating the effect of the line -break. @xref{Refilling Paragraphs}. - The @code{@@/} command can be useful within a url (@pxref{uref,,@code{@@uref}}), which tend to be long and are otherwise unbreakable. For example: @@ -10696,33 +11166,18 @@ words match exactly, so give all necessary variants. Info output is not hyphenated, so these commands have no effect there. + @node w @section @code{@@w}@{@var{text}@}: Prevent Line Breaks @findex w @r{(prevent line break)} @cindex Line breaks, preventing -@cindex Hyphenation, preventing @code{@@w@{@var{text}@}} outputs @var{text} and prohibits line breaks -within @var{text}. - -You can use the @code{@@w} command to prevent @TeX{} from automatically -hyphenating a long name or phrase that happens to fall near the end of a -line. For example: - -@example -You can copy GNU software from @@w@{@@samp@{ftp.gnu.org@}@}. -@end example - -@noindent -produces - -@quotation -You can copy GNU software from @w{@samp{ftp.gnu.org}}. -@end quotation +within @var{text}, for both @TeX{} and @command{makeinfo}. @cindex Non-breakable space, fixed @cindex Unbreakable space, fixed -You can also use @code{@@w} to produce a non-breakable space, fixed at +Thus, you can use @code{@@w} to produce a non-breakable space, fixed at the width of a normal interword space: @example @@ -10735,11 +11190,24 @@ the width of a normal interword space: @w{ } @w{ } @w{ } indentation. @end display -The space from @code{@@w@{@w{ }@}}, as well as being non-breakable, also -will not stretch or shrink. Sometimes that is what you want, for -instance if you're doing some manual indenting. However, usually you -want a normal interword space that does stretch and shrink (in the -printed output); see the @code{@@tie} command in the next section. +The space from @code{@@w@{@w{ }@}}, as well as being non-breakable, +also will not stretch or shrink. Sometimes that is what you want, for +instance if you're doing indenting manual. However, usually you want +a normal interword space that does stretch and shrink (in the printed +output); see the @code{@@tie} command in the next section. + +@cindex Hyphenation, preventing +You can also use the @code{@@w} command to prevent @TeX{} from +automatically hyphenating a long name or phrase that happens to fall +near the end of a line. @command{makeinfo} does not ever hyphenate +words. + +@cindex Keyword expansion, preventing +@cindex Version control keywords, preventing expansion of +@cindex $Id expansion, preventing +You can also use @code{@@w} to avoid unwanted keyword expansion in +source control systems. For example, to literally write @t{@w{$}Id$} +in your document, use @code{@@w@{$@}Id$}. @node tie @@ -10854,7 +11322,7 @@ paginated. An @code{@@page} command is often used in the @code{@@titlepage} section of a Texinfo file to start the copyright page. -@node group, need, page, Breaks +@node group @comment node-name, next, previous, up @section @code{@@group}: Prevent Page Breaks @cindex Group (hold text together vertically) @@ -10911,7 +11379,7 @@ considerable text. It is a good rule of thumb to look for a missing @code{@@end group} if you get incomprehensible error messages in @TeX{}.@refill -@node need, , group, Breaks +@node need @comment node-name, next, previous, up @section @code{@@need @var{mils}}: Prevent Page Breaks @cindex Need space at page bottom @@ -10958,23 +11426,24 @@ output formats, the body of the definition is indented. Also, the name of the entity is entered into the appropriate index: @code{@@deffn} enters the name into the index of functions, @code{@@defvr} enters it into the index of variables, and so -on.@refill +on (@pxref{Predefined Indices}). A manual need not and should not contain more than one definition for a given name. An appendix containing a summary should use @code{@@table} rather than the definition commands.@refill @menu -* Def Cmd Template:: How to structure a description using a - definition command. -* Optional Arguments:: How to handle optional and repeated arguments. -* deffnx:: How to group two or more `first' lines. -* Def Cmds in Detail:: All the definition commands. +* Def Cmd Template:: Writing descriptions using definition commands. +* Def Cmd Continuation Lines:: Continuing the heading over source lines. +* Optional Arguments:: Handling optional and repeated arguments. +* deffnx:: Group two or more `first' lines. +* Def Cmds in Detail:: Reference for all the definition commands. * Def Cmd Conventions:: Conventions for writing definitions. -* Sample Function Definition:: +* Sample Function Definition:: An example. @end menu -@node Def Cmd Template, Optional Arguments, Definition Commands, Definition Commands + +@node Def Cmd Template @section The Template for a Definition @cindex Definition template @cindex Template for a definition @@ -10986,8 +11455,12 @@ and follow it on the same line by the category of the entity, the name of the entity itself, and its arguments (if any). Then write the body of the definition on succeeding lines. (You may embed examples in the body.) Finally, end the definition with an @code{@@end deffn} command -written on a line of its own. (The other definition commands follow -the same format.)@refill +written on a line of its own. + +The other definition commands follow the same format: a line with the +@code{@@def@dots{}} command and whatever arguments are appropriate for +that command; the body of the definition; and a corresponding +@code{@@end} line. The template for a definition looks like this: @@ -11024,7 +11497,7 @@ This function moves point forward @var{count} words Capitalize the category name like a title. If the name of the category contains spaces, as in the phrase `Interactive Command', -write braces around it. For example:@refill +enclose it in braces. For example: @example @group @@ -11036,68 +11509,91 @@ write braces around it. For example:@refill @noindent Otherwise, the second word will be mistaken for the name of the -entity.@refill +entity. As a general rule, when any of the arguments in the heading +line @emph{except} the last one are more than one word, you need to +enclose them in braces. Some of the definition commands are more general than others. The @code{@@deffn} command, for example, is the general definition command -for functions and the like---for entities that may take arguments. When -you use this command, you specify the category to which the entity -belongs. The @code{@@deffn} command possesses three predefined, -specialized variations, @code{@@defun}, @code{@@defmac}, and -@code{@@defspec}, that specify the category for you: ``Function'', -``Macro'', and ``Special Form'' respectively. (In Lisp, a special form -is an entity much like a function.) The @code{@@defvr} command also is -accompanied by several predefined, specialized variations for describing -particular kinds of variables.@refill +for functions and the like---for entities that may take arguments. +When you use this command, you specify the category to which the +entity belongs. Three predefined, specialized variations +(@code{@@defun}, @code{@@defmac}, and @code{@@defspec}) specify the +category for you: ``Function'', ``Macro'', and ``Special Form'' +respectively. (In Lisp, a special form is an entity much like a +function.) Similarly, the general @code{@@defvr} command is +accompanied by several specialized variations for describing +particular kinds of variables. + +@xref{Sample Function Definition}, for a detailed example of a +function definition, including the use of @code{@@example} inside the +definition. -The template for a specialized definition, such as @code{@@defun}, is -similar to the template for a generalized definition, except that you -do not need to specify the category:@refill +@cindex Macros in definition commands +Unfortunately, due to implementation difficulties, macros are not expanded +in @code{@@deffn} and all the other definition commands. -@example -@group -@@defun @var{name} @var{arguments}@dots{} -@var{body-of-definition} -@@end defun -@end group -@end example -@noindent -Thus, +@node Def Cmd Continuation Lines +@section Definition Command Continuation Lines +@cindex Continuation lines in definition commands +@cindex Definition command headings, continuing +@cindex @samp{@@} as continuation in definition commands + +The heading line of a definition command can get very long. +Therefore, Texinfo has a special syntax allowing them to be continued +over multiple lines of the source file: a lone @samp{@@} at the end of +each line to be continued. Here's an example: @example -@group -@@defun buffer-end flag -This function returns @@code@{(point-min)@} if @@var@{flag@} -is less than 1, @@code@{(point-max)@} otherwise. -@dots{} +@@defun fn-name @@ + arg1 arg2 arg3 +This is the basic continued defun. @@end defun -@end group @end example -@noindent -produces +@noindent produces: -@quotation -@defun buffer-end flag -This function returns @code{(point-min)} if @var{flag} is less than 1, -@code{(point-max)} otherwise. @dots{} +@defun fn-name @ + arg1 arg2 arg3 +This is the basic continued defun. @end defun -@end quotation @noindent -@xref{Sample Function Definition, Sample Function Definition, A Sample -Function Definition}, for a more detailed example of a function -definition, including the use of @code{@@example} inside the -definition.@refill +As you can see, the continued lines are combined, as if they had been +typed on one source line. -The other specialized commands work like @code{@@defun}.@refill +Although this example only shows a one-line continuation, +continuations may extend over any number of lines; simply put an +@code{@@} at the end of each line to be continued. -@cindex Macros in definition commands -Note that, due to implementation difficulties, macros are not expanded -in @code{@@deffn} and all the other definition commands. +The @code{@@} character does not have to be the last character on the +physical line: whitespace is allowed (and ignored) afterwards. + +@cindex Whitespace, collapsed around continuations +@cindex Collapsing whitespace around continuations +In general, any number of spaces or tabs around the @code{@@} +continuation character, both on the line with the @code{@@} and on the +continued line, are collapsed into a single space. There is one +exception: the Texinfo processors will not fully collapse whitespace +around a continuation inside braces. For example: + +@example +@@deffn @{Category @@ + Name@} @dots{} +@end example -@node Optional Arguments, deffnx, Def Cmd Template, Definition Commands +@noindent The output (not shown) has excess space between `Category' +and `Name'. In this case, simply elide any unwanted whitespace in +your input, or put the continuation @code{@@} outside braces. + +@code{@@} does not (currently) function as a continuation character in +@emph{any} other context. Ordinarily, @samp{@@} followed by a +whitespace character (space, tab, newline) produces a normal interword +space (@pxref{Multiple Spaces}). + + +@node Optional Arguments @section Optional and Repeated Arguments @cindex Optional and repeated arguments @cindex Repeated and optional arguments @@ -11109,34 +11605,20 @@ Some entities take optional or repeated arguments, which may be specified by a distinctive glyph that uses square brackets and ellipses. For @w{example}, a special form often breaks its argument list into separate arguments in more complicated ways than a -straightforward function.@refill +straightforward function. -@iftex -An argument enclosed within square brackets is optional. -Thus, the phrase -@samp{@code{@r{[}@var{optional-arg}@r{]}}} means that -@var{optional-arg} is optional. -An argument followed by an ellipsis is optional -and may be repeated more than once. @c This is consistent with Emacs Lisp Reference manual -Thus, @samp{@var{repeated-args}@dots{}} stands for zero or more arguments. -Parentheses are used when several arguments are grouped -into additional levels of list structure in Lisp. -@end iftex -@c The following looks better in Info (no `r', `samp' and `code'): -@ifinfo An argument enclosed within square brackets is optional. Thus, [@var{optional-arg}] means that @var{optional-arg} is optional. An argument followed by an ellipsis is optional and may be repeated more than once. @c This is consistent with Emacs Lisp Reference manual -Thus, @var{repeated-args}@dots{} stands for zero or more arguments. -Parentheses are used when several arguments are grouped +Thus, @var{repeated-args}@samp{@dots{}} stands for zero or more +arguments. Parentheses are used when several arguments are grouped into additional levels of list structure in Lisp. -@end ifinfo Here is the @code{@@defspec} line of an example of an imaginary -special form:@refill +special form: @quotation @defspec foobar (@var{var} [@var{from} @var{to} [@var{inc}]]) @var{body}@dots{} @@ -11169,7 +11651,8 @@ example).@refill The function is listed in the Command and Variable Index under @samp{foobar}.@refill -@node deffnx, Def Cmds in Detail, Optional Arguments, Definition Commands + +@node deffnx @section Two or More `First' Lines @cindex Two `First' Lines for @code{@@deffn} @cindex Grouping two definitions together @@ -11205,9 +11688,10 @@ These two search commands are similar except @dots{} Each definition command has an `x' form: @code{@@defunx}, @code{@@defvrx}, @code{@@deftypefunx}, etc. -The `x' forms work just like @code{@@itemx}; see @ref{itemx, , @code{@@itemx}}. +The `x' forms work similarly to @code{@@itemx} (@pxref{itemx}). + -@node Def Cmds in Detail, Def Cmd Conventions, deffnx, Definition Commands +@node Def Cmds in Detail @section The Definition Commands Texinfo provides more than a dozen definition commands, all of which @@ -11227,11 +11711,11 @@ can be used for other programming languages.@refill * Variables Commands:: Commands for variables and similar entities. * Typed Functions:: Commands for functions in typed languages. * Typed Variables:: Commands for variables in typed languages. -* Abstract Objects:: Commands for object-oriented programming. * Data Types:: The definition command for data types. +* Abstract Objects:: Commands for object-oriented programming. @end menu -@node Functions Commands, Variables Commands, Def Cmds in Detail, Def Cmds in Detail +@node Functions Commands @subsection Functions and Similar Entities This section describes the commands for describing functions and similar @@ -11265,12 +11749,19 @@ Move point forward @@var@{nchars@} characters. This shows a rather terse definition for a ``command'' named @code{forward-char} with one argument, @var{nchars}. -@code{@@deffn} prints argument names such as @var{nchars} in italics or -upper case, as if @code{@@var} had been used, because we think of these -names as metasyntactic variables---they stand for the actual argument -values. Within the text of the description, write an argument name -explicitly with @code{@@var} to refer to the value of the argument. In -the example above, we used @samp{@@var@{nchars@}} in this way. +@code{@@deffn} and prints argument names such as @var{nchars} in slanted +type in the printed output, because we think of these names as +metasyntactic variables---they stand for the actual argument values. +Within the text of the description, however, write an argument name +explicitly with @code{@@var} to refer to the value of the argument. +In the example above, we used @samp{@@var@{nchars@}} in this way. + +In the unusual case when an argument name contains @samp{--}, or +another character sequence which is treated specially +(@pxref{Conventions}), use @code{@@var} around the argument. This +causes the name to be printed in slanted typewriter, instead of the +regular slanted font, exactly as input. +@c except for ?` and !`, but we won't explain that. The template for @code{@@deffn} is: @@ -11285,30 +11776,9 @@ The template for @code{@@deffn} is: @findex defun @item @@defun @var{name} @var{arguments}@dots{} The @code{@@defun} command is the definition command for functions. -@code{@@defun} is equivalent to @samp{@@deffn Function -@dots{}}.@refill - -@need 800 -@noindent -For example, - -@example -@group -@@defun set symbol new-value -Change the value of the symbol @@var@{symbol@} -to @@var@{new-value@}. -@@end defun -@end group -@end example - -@noindent -shows a rather terse definition for a function @code{set} whose -arguments are @var{symbol} and @var{new-value}. The argument names on -the @code{@@defun} line automatically appear in italics or upper case as -if they were enclosed in @code{@@var}. Terminate the definition with -@code{@@end defun} on a line of its own.@refill - -The template is: +@code{@@defun} is equivalent to @samp{@@deffn Function @dots{}}. +Terminate the definition with @code{@@end defun} on a line of its own. +Thus, the template is: @example @group @@ -11318,13 +11788,11 @@ The template is: @end group @end example -@code{@@defun} creates an entry in the index of functions. - @findex defmac @item @@defmac @var{name} @var{arguments}@dots{} The @code{@@defmac} command is the definition command for macros. @code{@@defmac} is equivalent to @samp{@@deffn Macro @dots{}} and -works like @code{@@defun}.@refill +works like @code{@@defun}. @findex defspec @item @@defspec @var{name} @var{arguments}@dots{} @@ -11332,10 +11800,13 @@ The @code{@@defspec} command is the definition command for special forms. (In Lisp, a special form is an entity much like a function, @pxref{Special Forms,,, elisp, GNU Emacs Lisp Reference Manual}.) @code{@@defspec} is equivalent to @samp{@@deffn @{Special Form@} -@dots{}} and works like @code{@@defun}.@refill +@dots{}} and works like @code{@@defun}. @end table -@node Variables Commands, Typed Functions, Functions Commands, Def Cmds in Detail +All these commands create entries in the index of functions. + + +@node Variables Commands @subsection Variables and Similar Entities Here are the commands for defining variables and similar @@ -11419,11 +11890,12 @@ The @code{@@defopt} command is the definition command for @dfn{user options}, i.e., variables intended for users to change according to taste; Emacs has many such (@pxref{Variables,,, emacs, The GNU Emacs Manual}). @code{@@defopt} is equivalent to @samp{@@defvr @{User -Option@} @dots{}} and works like @code{@@defvar}.@refill +Option@} @dots{}} and works like @code{@@defvar}. It creates an entry +in the index of variables. @end table -@node Typed Functions, Typed Variables, Variables Commands, Def Cmds in Detail +@node Typed Functions @subsection Functions in Typed Languages The @code{@@deftypefn} command and its variations are for describing @@ -11480,12 +11952,15 @@ This means that @code{foobar} is a ``library function'' that returns an @code{int}, and its arguments are @var{foo} (an @code{int}) and @var{bar} (a @code{float}).@refill -The argument names that you write in @code{@@deftypefn} are not subject -to an implicit @code{@@var}---since the actual names of the arguments in -@code{@@deftypefn} are typically scattered among data type names and -keywords, Texinfo cannot find them without help. Instead, you must write -@code{@@var} explicitly around the argument names. In the example -above, the argument names are @samp{foo} and @samp{bar}.@refill +Since in typed languages, the actual names of the arguments are +typically scattered among data type names and keywords, Texinfo cannot +find them without help. You can either (a)@tie{}write everything +as straight text, and it will be printed in slanted type; (b)@tie{}use +@code{@@var} for the variable names, which will uppercase the +variable names in Info and use the slanted typewriter font in printed +output; (c)@tie{}use @code{@@var} for the variable names and +@code{@@code} for the type names and keywords, which will be dutifully +obeyed. The template for @code{@@deftypefn} is:@refill @@ -11504,16 +11979,12 @@ word then it must be enclosed in braces to make it a single argument.@refill If you are describing a procedure in a language that has packages, such as Ada, you might consider using @code{@@deftypefn} in a manner somewhat contrary to the convention described in the preceding -paragraphs.@refill - -@need 800 -@noindent -For example: +paragraphs. For example: @example @group -@@deftypefn stacks private push - (@@var@{s@}:in out stack; +@@deftypefn stacks private push @@ + (@@var@{s@}:in out stack; @@ @@var@{n@}:in integer) @dots{} @@end deftypefn @@ -11521,8 +11992,9 @@ For example: @end example @noindent -(The @code{@@deftypefn} arguments are shown split into three lines, but -would be a single line in a real Texinfo file.) +(The @code{@@deftypefn} arguments are shown using continuations +(@pxref{Def Cmd Continuation Lines}), but could be on a single line in +a real Texinfo file.) In this instance, the procedure is classified as belonging to the package @code{stacks} rather than classified as a `procedure' and its @@ -11530,50 +12002,13 @@ data type is described as @code{private}. (The name of the procedure is @code{push}, and its arguments are @var{s} and @var{n}.)@refill @code{@@deftypefn} creates an entry in the index of functions for -@var{name}.@refill +@var{name}. @item @@deftypefun @var{data-type} @var{name} @var{arguments}@dots{} @findex deftypefun The @code{@@deftypefun} command is the specialized definition command for functions in typed languages. The command is equivalent to -@samp{@@deftypefn Function @dots{}}.@refill - -@need 800 -@noindent -Thus, - -@smallexample -@group -@@deftypefun int foobar (int @@var@{foo@}, float @@var@{bar@}) -@dots{} -@@end deftypefun -@end group -@end smallexample - -@noindent -produces the following in Info: - -@example -@group --- Function: int foobar (int FOO, float BAR) -@dots{} -@end group -@end example -@iftex - -@need 800 -@noindent -and the following in a printed manual: - -@quotation -@deftypefun int foobar (int @var{foo}, float @var{bar}) -@dots{} -@end deftypefun -@end quotation -@end iftex - -@need 800 -The template is: +@samp{@@deftypefn Function @dots{}}. The template is: @example @group @@ -11584,12 +12019,12 @@ The template is: @end example @code{@@deftypefun} creates an entry in the index of functions for -@var{name}.@refill +@var{name}. @end table -@node Typed Variables, Abstract Objects, Typed Functions, Def Cmds in Detail +@node Typed Variables @subsection Variables in Typed Languages Variables in typed languages are handled in a manner similar to @@ -11654,87 +12089,103 @@ The template is: @@end deftypevr @end example -@code{@@deftypevr} creates an entry in the index of variables for -@var{name}.@refill - @findex deftypevar @item @@deftypevar @var{data-type} @var{name} The @code{@@deftypevar} command is the specialized definition command for variables in typed languages. @code{@@deftypevar} is equivalent -to @samp{@@deftypevr Variable @dots{}}.@refill - -@need 800 -@noindent -For example: +to @samp{@@deftypevr Variable @dots{}}. The template is: @example @group -@@deftypevar int fubar -@dots{} +@@deftypevar @var{data-type} @var{name} +@var{body-of-description} @@end deftypevar @end group @end example +@end table -@noindent -produces the following in Info: +These commands create entries in the index of variables. + +@node Data Types +@subsection Data Types + +Here is the command for data types:@refill + +@table @code +@findex deftp +@item @@deftp @var{category} @var{name} @var{attributes}@dots{} +The @code{@@deftp} command is the generic definition command for data +types. The command is written at the beginning of a line and is +followed on the same line by the category, by the name of the type +(which is a word like @code{int} or @code{float}), and then by names of +attributes of objects of that type. Thus, you could use this command +for describing @code{int} or @code{float}, in which case you could use +@code{data type} as the category. (A data type is a category of +certain objects for purposes of deciding which operations can be +performed on them.)@refill + +In Lisp, for example, @dfn{pair} names a particular data +type, and an object of that type has two slots called the +@sc{car} and the @sc{cdr}. Here is how you would write the first line +of a definition of @code{pair}.@refill @example @group --- Variable: int fubar +@@deftp @{Data type@} pair car cdr @dots{} +@@end deftp @end group @end example -@iftex -@need 800 -@noindent -and the following in a printed manual: - -@quotation -@deftypevar int fubar -@dots{} -@end deftypevar -@end quotation -@end iftex - -@need 800 -@noindent +@need 950 The template is: @example @group -@@deftypevar @var{data-type} @var{name} -@var{body-of-description} -@@end deftypevar +@@deftp @var{category} @var{name-of-type} @var{attributes}@dots{} +@var{body-of-definition} +@@end deftp @end group @end example -@code{@@deftypevar} creates an entry in the index of variables for -@var{name}.@refill +@code{@@deftp} creates an entry in the index of data types. @end table + @node Abstract Objects @subsection Object-Oriented Programming +@cindex Object-oriented programming + Here are the commands for formatting descriptions about abstract objects, such as are used in object-oriented programming. A class is a defined type of abstract object. An instance of a class is a particular object that has the type of the class. An instance variable is a variable that belongs to the class but for which each -instance has its own value.@refill +instance has its own value. -In a definition, if the name of a class is truly a name defined in the -programming system for a class, then you should write an @code{@@code} -around it. Otherwise, it is printed in the usual text font.@refill +@menu +* Variables: Object-Oriented Variables. +* Methods: Object-Oriented Methods. +@end menu + + +@node Object-Oriented Variables +@subsubsection Object-Oriented Variables + +@cindex Variables, object-oriented + +These commands allow you to define different sorts of variables in +object-oriented programming languages. @table @code -@findex defcv @item @@defcv @var{category} @var{class} @var{name} +@findex defcv The @code{@@defcv} command is the general definition command for variables associated with classes in object-oriented programming. The @code{@@defcv} command is followed by three arguments: the category of thing being defined, the class to which it belongs, and its -name. Thus,@refill +name. For instance: @example @group @@ -11744,52 +12195,104 @@ name. Thus,@refill @end group @end example -@noindent -illustrates how you would write the first line of a definition of the -@code{border-pattern} class option of the class @code{Window}.@refill +@noindent produces: +@defcv {Class Option} Window border-pattern +@dots{} +@end defcv + +@code{@@defcv} creates an entry in the index of variables. + +@item @@deftypecv @var{category} @var{class} @var{data-type} @var{name} +@findex deftypecv +The @code{@@deftypecv} command is the definition command for typed +class variables in object-oriented programming. It is analogous to +@code{@@defcv} with the addition of the @var{data-type} parameter to +specify the type of the instance variable. Ordinarily, the data type +is a programming language construct that should be marked with +@code{@@code}. For instance: -The template is: @example @group -@@defcv @var{category} @var{class} @var{name} +@@deftypecv @{Class Option@} Window @@code@{int@} border-pattern @dots{} -@@end defcv +@@end deftypecv @end group @end example -@code{@@defcv} creates an entry in the index of variables. +@noindent produces: + +@deftypecv {Class Option} Window @code{int} border-pattern +@dots{} +@end deftypecv + +@code{@@deftypecv} creates an entry in the index of variables. -@findex defivar @item @@defivar @var{class} @var{name} +@findex defivar The @code{@@defivar} command is the definition command for instance variables in object-oriented programming. @code{@@defivar} is -equivalent to @samp{@@defcv @{Instance Variable@} @dots{}}@refill +equivalent to @samp{@@defcv @{Instance Variable@} @dots{}}. For +instance: -The template is: @example @group -@@defivar @var{class} @var{instance-variable-name} -@var{body-of-definition} +@@defivar Window border-pattern +@dots{} @@end defivar @end group @end example +@noindent produces: + +@defivar Window border-pattern +@dots{} +@end defivar + @code{@@defivar} creates an entry in the index of variables. -@findex deftypeivar @item @@deftypeivar @var{class} @var{data-type} @var{name} +@findex deftypeivar The @code{@@deftypeivar} command is the definition command for typed -instance variables in object-oriented programming. It is similar to +instance variables in object-oriented programming. It is analogous to @code{@@defivar} with the addition of the @var{data-type} parameter to -specify the type of the instance variable. @code{@@deftypeivar} creates an -entry in the index of variables. +specify the type of the instance variable. Ordinarily, the data type +is a programming language construct that should be marked with +@code{@@code}. For instance: + +@example +@group +@@deftypeivar Window @@code@{int@} border-pattern +@dots{} +@@end deftypeivar +@end group +@end example + +@noindent produces: + +@deftypeivar Window @code{int} border-pattern +@dots{} +@end deftypeivar + +@code{@@deftypeivar} creates an entry in the index of variables. + +@end table + +@node Object-Oriented Methods +@subsubsection Object-Oriented Methods + +@cindex Methods, object-oriented + +These commands allow you to define different sorts of function-like +entities resembling methods in object-oriented programming languages. +These entities take arguments, as functions do, but are associated with +particular classes of objects. + +@table @code @findex defop @item @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{} -The @code{@@defop} command is the general definition command for -entities that may resemble methods in object-oriented programming. -These entities take arguments, as functions do, but are associated with -particular classes of objects.@refill +The @code{@@defop} command is the general definition command for these +method-like entities. For example, some systems have constructs called @dfn{wrappers} that are associated with classes as methods are, but that act more like @@ -11871,21 +12374,9 @@ For example: @noindent illustrates the definition for a method called @code{bar-method} of -the class @code{bar-class}. The method takes an argument.@refill - -The template is: - -@example -@group -@@defmethod @var{class} @var{method-name} @var{arguments}@dots{} -@var{body-of-definition} -@@end defmethod -@end group -@end example - -@code{@@defmethod} creates an entry, such as `@code{bar-method} on -@code{bar-class}', in the index of functions.@refill +the class @code{bar-class}. The method takes an argument. +@code{@@defmethod} creates an entry in the index of functions. @item @@deftypemethod @var{class} @var{data-type} @var{name} @var{arguments}@dots{} @findex defmethod @@ -11893,56 +12384,12 @@ The @code{@@deftypemethod} command is the definition command for methods in object-oriented typed languages, such as C++ and Java. It is similar to the @code{@@defmethod} command with the addition of the @var{data-type} parameter to specify the return type of the method. +@code{@@deftypemethod} creates an entry in the index of functions. @end table -@node Data Types -@subsection Data Types - -Here is the command for data types:@refill - -@table @code -@findex deftp -@item @@deftp @var{category} @var{name} @var{attributes}@dots{} -The @code{@@deftp} command is the generic definition command for data -types. The command is written at the beginning of a line and is -followed on the same line by the category, by the name of the type -(which is a word like @code{int} or @code{float}), and then by names of -attributes of objects of that type. Thus, you could use this command -for describing @code{int} or @code{float}, in which case you could use -@code{data type} as the category. (A data type is a category of -certain objects for purposes of deciding which operations can be -performed on them.)@refill - -In Lisp, for example, @dfn{pair} names a particular data -type, and an object of that type has two slots called the -@sc{car} and the @sc{cdr}. Here is how you would write the first line -of a definition of @code{pair}.@refill - -@example -@group -@@deftp @{Data type@} pair car cdr -@dots{} -@@end deftp -@end group -@end example - -@need 950 -The template is: - -@example -@group -@@deftp @var{category} @var{name-of-type} @var{attributes}@dots{} -@var{body-of-definition} -@@end deftp -@end group -@end example - -@code{@@deftp} creates an entry in the index of data types. -@end table - -@node Def Cmd Conventions, Sample Function Definition, Def Cmds in Detail, Definition Commands +@node Def Cmd Conventions @section Conventions for Writing Definitions @cindex Definition conventions @cindex Conventions for writing definitions @@ -11954,7 +12401,8 @@ to the @code{forward-word} function. Also, if the name of an argument contains the name of a type, such as @var{integer}, take care that the argument actually is of that type.@refill -@node Sample Function Definition, , Def Cmd Conventions, Definition Commands + +@node Sample Function Definition @section A Sample Function Definition @cindex Function definitions @cindex Command definitions @@ -12061,67 +12509,89 @@ that for functions except that variables do not take arguments. @cindex Visibility of conditional text @cindex If text conditionally visible -Sometimes it is good to use different text for different output formats. -For example, you can use the @dfn{conditional commands} to specify -different text for the printed manual and the Info output. - -Conditional commands may not be nested. +The @dfn{conditional commands} allow you to use different text for +different output formats, or for general conditions that you define. +For example, you can use them to specify different text for the +printed manual and the Info output. The conditional commands comprise the following categories. @itemize @bullet -@item Commands for HTML, Info, or @TeX{}. -@item Commands for not HTML, Info, or @TeX{}. -@item Raw @TeX{} or HTML commands. @item -Substituting text for all formats, and testing if a flag is set or clear. +Commands specific to an output format (Info, @TeX{}, HTML, @dots{}). + +@item +Commands specific to any output format @emph{other} than a given +one (not Info, not @TeX{}, @dots{}). + +@item +`Raw' formatter text for any output format, passed straight +through with no interpretation of @@-commands. + +@item +Format-independent variable substitutions, and testing if a variable +is set or clear. + @end itemize @menu -* Conditional Commands:: Specifying text for HTML, Info, or @TeX{}. -* Conditional Not Commands:: Specifying text for not HTML, Info, or @TeX{}. -* Raw Formatter Commands:: Using raw @TeX{} or HTML commands. -* set clear value:: Designating which text to format (for - all output formats); and how to set a - flag to a string that you can insert. +* Conditional Commands:: Text for a given format. +* Conditional Not Commands:: Text for any format other than a given one. +* Raw Formatter Commands:: Using raw formatter commands. +* set clear value:: Variable tests and substitutions. +* Conditional Nesting:: Using conditionals inside conditionals. @end menu @node Conditional Commands @section Conditional Commands -Texinfo has an @code{@@if@dots{}} environment for each output format, to -allow conditional inclusion of text for a particular output format. +Texinfo has an @code{@@if@var{format}} environment for each output +format, to allow conditional inclusion of text for a particular output +format. @findex ifinfo -@code{@@ifinfo} begins segments of text that should be ignored by @TeX{} -when it typesets the printed manual. The segment of text appears only -in the Info file and (for historical compatibility) the plain text -output. The @code{@@ifinfo} command should appear on a line by itself; -end the Info-only text with a line containing @code{@@end ifinfo} by -itself. +@code{@@ifinfo} begins segments of text that should be ignored by +@TeX{} when it typesets the printed manual, and by @command{makeinfo} +when not producing Info output. The segment of text appears only in +the Info file and, for historical compatibility, the plain text +output. +@findex ifdocbook @findex ifhtml @findex ifplaintext @findex iftex @findex ifxml -The @code{@@iftex} and @code{@@end iftex} commands are analogous to the -@code{@@ifinfo} and @code{@@end ifinfo} commands; they specify text that -will appear in the printed manual but not in the Info file. Likewise -for @code{@@ifhtml} and @code{@@end ifhtml}, which specify text to -appear only in HTML output. And for @code{@@ifplaintext} and -@code{@@end ifplaintext}, which specify text to appear only in plain -text output. And for @code{@@ifxml} and -@code{@@end ifxml}, for the XML output. +The environments for the other formats are analogous: -For example, +@table @code +@item @@ifdocbook @dots{} @@end ifdocbook +Text to appear only in the Docbook output. + +@item @@ifhtml @dots{} @@end ifhtml +Text to appear only in the HTML output. + +@item @@ifplaintext @dots{} @@end ifplaintext +Text to appear only in the plain text output. + +@item @@iftex @dots{} @@end iftex +Text to appear only in the printed manual. + +@item @@ifxml @dots{} @@end ifxml +Text to appear only in the XML output. +@end table + +The @code{@@if@dots{}} and @code{@@end if@dots{}} commands must appear +on lines by themselves in your source file. + +Here is an example showing all these conditionals: @example @@iftex This text will appear only in the printed manual. @@end iftex @@ifinfo -However, this text will appear only in Info (or plain text). +However, this text will appear only in Info and plain text. @@end ifinfo @@ifhtml And this text will only appear in HTML. @@ -12130,17 +12600,21 @@ And this text will only appear in HTML. Whereas this text will only appear in plain text. @@end ifplaintext @@ifxml -And this will only appear in XML output. +Notwithstanding that this will only appear in XML. @@end ifxml +@@ifdocbook +Nevertheless, this will only appear in Docbook. +@@end ifdocbook @end example @noindent The preceding example produces the following line: + @iftex This text will appear only in the printed manual. @end iftex @ifinfo -However, this text will appear only in Info (or plain text). +However, this text will appear only in Info and plain text. @end ifinfo @ifhtml And this text will only appear in HTML. @@ -12149,8 +12623,11 @@ And this text will only appear in HTML. Whereas this text will only appear in plain text. @end ifplaintext @ifxml -And this will only appear in XML output. +Notwithstanding that this will only appear in XML. @end ifxml +@ifdocbook +Nevertheless, this will only appear in Docbook. +@end ifdocbook @noindent Notice that you only see one of the input lines, depending on which @@ -12159,6 +12636,7 @@ version of the manual you are reading. @node Conditional Not Commands @section Conditional Not Commands +@findex ifnotdocbook @findex ifnothtml @findex ifnotinfo @findex ifnotplaintext @@ -12166,14 +12644,17 @@ version of the manual you are reading. @findex ifnotxml You can specify text to be included in any output format @emph{other} -than some given one with the @code{@@ifnot@dots{}} commands: +than a given one with the @code{@@ifnot@dots{}} environments: + @example +@@ifnotdocbook @dots{} @@end ifnotdocbook @@ifnothtml @dots{} @@end ifnothtml @@ifnotinfo @dots{} @@end ifnotinfo @@ifnotplaintext @dots{} @@end ifnotplaintext @@ifnottex @dots{} @@end ifnottex @@ifnotxml @dots{} @@end ifnotxml @end example + @noindent The @code{@@ifnot@dots{}} command and the @code{@@end} command must appear on lines by themselves in your actual source file. @@ -12181,10 +12662,11 @@ appear on lines by themselves in your actual source file. If the output file is being made in the given format, the region is @emph{ignored}. Otherwise, it is included. -With one exception (for historical compatibility): @code{@@ifnotinfo} -text is omitted for both Info and plain text output, not just Info. To -specify text which appears only in Info and not in plain text, use -@code{@@ifnotplaintext}, like this: +There is one exception (for historical compatibility): +@code{@@ifnotinfo} text is omitted for both Info and plain text +output, not just Info. To specify text which appears only in Info and +not in plain text, use @code{@@ifnotplaintext}, like this: + @example @@ifinfo @@ifnotplaintext @@ -12204,9 +12686,10 @@ with @code{@@iftex}, not raw formatter source as with @code{@@tex} @cindex @TeX{} commands, using ordinary @cindex Ordinary @TeX{} commands, using @cindex Commands using raw @TeX{} +@cindex Docbook, including raw @cindex HTML, including raw @cindex XML, including raw -@cindex plain @TeX{} +@cindex Plain @TeX{} Inside a region delineated by @code{@@iftex} and @code{@@end iftex}, you can embed some raw @TeX{} commands. The Texinfo processors will @@ -12268,17 +12751,23 @@ $$ \chi^2 = \sum_{i=1}^N @findex html Analogously, you can use @code{@@ifhtml @dots{} @@end ifhtml} to delimit a region to be included in HTML output only, and @code{@@html @dots{} -@@end html} for a region of raw HTML (again, except that @code{@@} is -still the escape character, so the @code{@@end} command can be -recognized.) +@@end html} for a region of raw HTML. @findex ifxml @findex xml -Analogously, you can use @code{@@ifxml @dots{} @@end ifxml} to delimit +Likewise, you can use @code{@@ifxml @dots{} @@end ifxml} to delimit a region to be included in XML output only, and @code{@@xml @dots{} -@@end xml} for a region of raw XML (again, except that @code{@@} is -still the escape character, so the @code{@@end} command can be -recognized.) +@@end xml} for a region of raw XML. + +@findex ifdocbook +@findex docbook +Again likewise, you can use @code{@@ifdocbook @dots{} @@end ifdocbook} +to delimit a region to be included in Docbook output only, and +@code{@@docbook @dots{} @@end docbook} for a region of raw Docbook. + +In all cases, the exception to the raw processing is that @code{@@} is +still an escape character, so the @code{@@end} command can be +recognized. @node set clear value @@ -12286,9 +12775,10 @@ recognized.) 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 +and @code{@@ifclear} commands. -Brief descriptions: +Here are brief descriptions of these commands, see the following +sections for more details: @table @code @item @@set @var{flag} [@var{value}] @@ -12319,12 +12809,13 @@ is ignored. If @var{flag} is clear, text through the following @subsection @code{@@set} and @code{@@value} @findex value -You use the @code{@@set} command to specify a value for a flag, which is -later expanded by the @code{@@value} command. +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{}. +A @dfn{flag} (aka @dfn{variable}) is an identifier. It is best to use +only letters and numerals in a flag name, not @samp{-} or +@samp{_}---they will work in some contexts, but not all, due to +limitations in @TeX{}. The value is the remainder of the input line, and can contain anything. @@ -12364,10 +12855,10 @@ without specifying a string, the value of @code{foo} is the empty string. If you clear a previously set flag with @code{@@clear @var{flag}}, a subsequent @code{@@value@{flag@}} command will report an error. -For example, if you set @code{foo} as follows:@refill +For example, if you set @code{foo} as follows: @example -@@set how-much very, very, very +@@set howmuch very, very, very @end example @noindent @@ -12375,7 +12866,7 @@ then the formatters transform @example @group -It is a @@value@{how-much@} wet day. +It is a @@value@{howmuch@} wet day. @exdent @r{into} It is a very, very, very wet day. @end group @@ -12384,7 +12875,7 @@ It is a very, very, very wet day. If you write @example -@@clear how-much +@@clear howmuch @end example @noindent @@ -12392,9 +12883,9 @@ then the formatters transform @example @group -It is a @@value@{how-much@} wet day. +It is a @@value@{howmuch@} wet day. @exdent @r{into} -It is a @{No value for "how-much"@} wet day. +It is a @{No value for "howmuch"@} wet day. @end group @end example @@ -12423,7 +12914,7 @@ and @code{@@end ifset} commands, like this: For example, you can create one document that has two variants, such as a manual for a `large' and `small' model: -@cindex shrubbery +@cindex Shrubbery @example You can use this machine to dig up shrubs without hurting them. @@ -12473,13 +12964,13 @@ command looks like this: @node value Example @subsection @code{@@value} Example -You can use the @code{@@value} command to minimize the number of places -you need to change when you record an update to a manual. @xref{GNU -Sample Texts}, for an example of this same principle can work with -Automake distributions, and full texts. +You can use the @code{@@value} command to minimize the number of +places you need to change when you record an update to a manual. +@xref{GNU Sample Texts}, for the full text of an example of using this +to work with Automake distributions. -Here is an example adapted from @ref{Top,, Overview, make, The GNU Make -Manual}): +This example is adapted from @ref{Top,, Overview, make, The GNU Make +Manual}. @enumerate @item @@ -12563,6 +13054,53 @@ When you update the manual, you change only the values of the flags; you do not need to edit the three sections. +@node Conditional Nesting +@section Conditional Nesting +@cindex Conditionals, nested +@cindex Nesting conditionals + +Conditionals can be nested; however, the details are a little tricky. +The difficulty comes with failing conditionals, such as +@code{@@ifhtml} when HTML is not being produced, where the included +text is to be ignored. However, it is not to be @emph{completely} +ignored, since it is useful to have one @code{@@ifset} inside another, +for example---that is a way to include text only if two conditions are +met. Here's an example: + +@example +@@ifset somevar +@@ifset anothervar +Both somevar and anothervar are set. +@@end ifset +@@ifclear anothervar +Somevar is set, anothervar is not. +@@end ifclear +@@end ifset +@end example + +Technically, Texinfo requires that for a failing conditional, the +ignored text must be properly nested with respect to that failing +conditional. Unfortunately, it's not always feasible to check that +@emph{all} conditionals are properly nested, because then the +processors could have to fully interpret the ignored text, which +defeats the purpose of the command. Here's an example illustrating +these rules: + +@example +@@ifset a +@@ifset b +@@ifclear ok - ok, ignored +@@end junky - ok, ignored +@@end ifset +@@c WRONG - missing @@end ifset. +@end example + +Finally, as mentioned above, all conditional commands must be on lines +by themselves, with no text (even spaces) before or after. Otherwise, +the processors cannot reliably determine which commands to consider +for nesting purposes. + + @node Internationalization @chapter Internationalization @@ -12811,18 +13349,23 @@ The @code{@@documentencoding} command declares the input document encoding. Write it on a line by itself, with a valid encoding specification following. -At present, Texinfo supports only three encodings: +At present, Texinfo supports only these encodings: @table @code @item US-ASCII This has no particular effect, but it's included for completeness. + @itemx ISO-8859-1 +@itemx ISO-8859-15 @item ISO-8859-2 -These specify the standard encodings for Western European and -Eastern European languages, respectively. A full description of the -encodings is beyond our scope here; -@uref{http://czyborra.com/charsets/iso8859.html} is one of many useful -references. +These specify the standard encodings for Western European (the first +two) and Eastern European languages (the third), respectively. ISO +8859-15 replaces some little-used characters from 8859-1 (e.g., +precomposed fractions) with more commonly needed ones, such as the +Euro symbol. + +A full description of the encodings is beyond our scope here; +one useful reference is @uref{http://czyborra.com/charsets/iso8859.html}. @end table Specifying an encoding @var{enc} has the following effects: @@ -12830,11 +13373,11 @@ Specifying an encoding @var{enc} has the following effects: @opindex --enable-encoding @cindex Local Variables: section, for encoding @cindex Info output, and encoding -In Info output, if the option @option{--enable-encoding} is also given +In Info output, if the option @option{--enable-encoding} is given to @command{makeinfo}, a so-called `Local Variables' section (@pxref{File Variables,,,emacs,The GNU Emacs Manual}) is output including @var{enc}. This allows Info readers to set the encoding -appropriately: +appropriately. @example Local Variables: @@ -12843,12 +13386,12 @@ End: @end example @cindex HTML output, and encodings -@cindex http-equiv, and charset specification -@cindex meta HTML tag, and charset specification +@cindex @code{http-equiv}, and charset specification +@cindex @code{<meta>} HTML tag, and charset specification In HTML output, a @samp{<meta>} tag is output, in the @samp{<head>} section of the HTML, that specifies @var{enc}. Web servers and browsers cooperate to use this information so the correct encoding is -used to display the page. +used to display the page, if supported by the system. @example <meta http-equiv="Content-Type" content="text/html; @@ -12892,7 +13435,7 @@ customized output in the Info file. @menu * Defining Macros:: Defining and undefining new commands. * Invoking Macros:: Using a macro, once you've defined it. -* Macro Details:: Beyond basic macro usage. +* Macro Details:: Limitations of Texinfo macros. * alias:: Command aliases. * definfoenclose:: Customized highlighting. @end menu @@ -13085,35 +13628,87 @@ Twice: a,b & a,b. @node Macro Details -@section Macro Details +@section Macro Details and Caveats @cindex Macro details @cindex Details of macro usage +@cindex Caveats for macro usage Due to unavoidable limitations, certain macro-related constructs cause problems with @TeX{}. If you get macro-related errors when producing the printed version of a manual, try expanding the macros with @command{makeinfo} by invoking @command{texi2dvi} with the @samp{-E} -option (@ref{Format with texi2dvi}). +option (@pxref{Format with texi2dvi}). @itemize @bullet @item +As mentioned earlier, macro names must consist entirely of letters. + +@item +It is not advisable to redefine any @TeX{} primitive, plain, or +Texinfo command name as a macro. Unfortunately this is a very large +set of names, and the possible resulting errors are unpredictable. + +@item All macros are expanded inside at least one @TeX{} group. This means that @code{@@set} and other such commands have no effect inside a macro. @item -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 -It is best to avoid comments inside macro definitions. +Macro arguments cannot cross lines. @item -Macro arguments cannot cross lines. +It is (usually) best to avoid comments inside macro definitions, but +see the next item. + +@item +Macros containing a command which must be on a line by itself, such as +a conditional, cannot be invoked in the middle of a line. In general, +the interaction of newlines in the macro definitions and invocations +depends on the precise commands and context. You may be able to work +around some problems with judicious use of @code{@@c}. Suppose you +define a macro that is always intended to be used on a line by itself: + +@example +@@macro linemac +@@cindex whatever +@@c +@@end macro +... +foo +@@linemac +bar +@end example + +Without the @code{@@c}, there will be an unwanted blank line between +the @samp{@@cindex whatever} and the @samp{bar} (one newline comes +from the macro definition, one from after the invocation), causing a +paragraph break. + +On the other hand, you wouldn't want the @code{@@c} if the macro was +sometimes invoked in the middle of a line (the text after the +invocation would be treated as a comment). + +@item +In general, you can't arbitrarily substitute a macro call for Texinfo +command arguments, even when the text is the same. It might work with +some commands, it fails with others. Best not to do it at all. For +instance, this fails: + +@example +@@macro offmacro +off +@@end macro +@@headings @@offmacro +@end example + +@noindent +You would expect this to be equivalent to @code{@@headings off}, but +for @TeX{}nical reasons, it fails with a mysterious error message +(@code{Paragraph ended before @@headings was complete}). @item Macros cannot define macros in the natural way. To do this, you must @@ -13135,6 +13730,33 @@ something involving \arg\ somehow @end itemize +The @command{makeinfo} implementation also has limitations: + +@itemize +@item +@code{@@verbatim} and macros do not mix; for instance, you can't start +a verbatim block inside a macro and end it outside. +(@xref{verbatim}.) Starting any environment inside a macro and ending +it outside may or may not work, for that matter. + +@item +Macros that completely define macros are ok, but it's not possible to +have incorrectly nested macro definitions. That is, @code{@@macro} +and @code{@@end macro} (likewise for @code{@@rmacro}) must be +correctly paired. For example, you cannot start a macro definition +within a macro, and then end the nested definition outside the macro. + +@item +@code{@@rmacro} is a kludge. + +@end itemize + +One more limitation is common to both implementations: white space is +ignored at the beginnings of lines. + +Future major revisions of Texinfo may ease some of these limitations +(by introducing a new macro syntax). + @node alias @section @samp{@@alias @var{new}=@var{existing}} @@ -13164,12 +13786,18 @@ You'd do this as follows: @@alias moviecite = cite @end example -Macros do not always have the same effect due to vagaries of argument -parsing. Also, aliases are much simpler to define than macros. So the -command is not redundant. (It was also heavily used in the Jargon File!) +Macros do not always have the same effect as aliases, due to vagaries +of argument parsing. Also, aliases are much simpler to define than +macros. So the command is not redundant. (It was also heavily used +in the Jargon File!) Aliases must not be recursive, directly or indirectly. +It is not advisable to redefine any @TeX{} primitive, plain, or +Texinfo command name as an alias. Unfortunately this is a very large +set of names, and the possible resulting errors are completely random. + + @node definfoenclose @section @samp{definfoenclose}: Customized Highlighting @cindex Highlighting, customized @@ -13293,6 +13921,7 @@ print queue, and delete a job from the print queue. * Cropmarks and Magnification:: How to print marks to indicate the size of pages and how to print scaled up output. * PDF Output:: Portable Document Format output. +* Obtaining TeX:: How to Obtain @TeX{}. @end menu @node Use TeX @@ -13316,8 +13945,8 @@ File}). @cindex Formatting with @code{tex} and @code{texindex} @cindex DVI file -Format the Texinfo file with the shell command @code{tex} followed by -the name of the Texinfo file. For example: +You can format the Texinfo file with the shell command @code{tex} +followed by the name of the Texinfo file. For example: @example tex foo.texi @@ -13330,13 +13959,12 @@ any device (see the following sections). @pindex texindex The @code{tex} formatting command itself does not sort the indices; it -writes an output file of unsorted index data. (The @code{texi2dvi} -command automatically generates indices; @pxref{Format with texi2dvi,, -Format with @code{texi2dvi}}.) To generate a printed index after -running the @code{tex} command, you first need a sorted index to work -from. The @code{texindex} command sorts indices. (The source file -@file{texindex.c} comes as part of the standard Texinfo distribution, -among other places.)@refill +writes an output file of unsorted index data. To generate a printed +index after running the @command{tex} command, you first need a sorted +index to work from. The @command{texindex} command sorts indices. +(The source file @file{texindex.c} comes as part of the standard +Texinfo distribution, among other places.) (@command{texi2dvi} runs +@command{tex} and @command{texindex} as necessary.) @cindex Names of index files @cindex Index file names @@ -13374,9 +14002,9 @@ whose name is made by appending @samp{s} to the input file name. The (@pxref{Printing Indices & Menus}). @code{texindex} does not alter the raw index output file. -After you have sorted the indices, you need to rerun the @code{tex} -formatting command on the Texinfo file. This regenerates the DVI file, -this time with up-to-date index entries. +After you have sorted the indices, you need to rerun @code{tex} on the +Texinfo file. This regenerates the DVI file, this time with +up-to-date index entries. Finally, you may need to run @code{tex} one more time, to get the page numbers in the cross-references correct. @@ -13444,10 +14072,10 @@ your file would look approximately like this: @section Format with @code{texi2dvi} @pindex texi2dvi @r{(shell script)} -The @code{texi2dvi} command automatically runs both @code{tex} and -@code{texindex} as many times as necessary to produce a DVI file with -sorted indices and all cross-references resolved. It is therefore -simpler than manually executing the +The @code{texi2dvi} command automatically runs both @TeX{} and +@command{texindex} as many times as necessary to produce a DVI file +with sorted indices and all cross-references resolved. It is +therefore simpler than manually executing the @code{tex}---@code{texindex}---@code{tex}---@code{tex} sequence described in the previous section. @@ -13474,9 +14102,20 @@ formats, such as @code{@@smallbook} (@pxref{smallbook}), (You can also do this on a site-wide basis with @file{texinfo.cnf}; @pxref{Preparing for TeX,,Preparing for @TeX{}}). -@cindex La@TeX{}, processing with @command{texi2dvi} -@command{texi2dvi} can also be used to process La@TeX{} files; simply -run @samp{texi2dvi doc.tex}. +With the @option{--pdf} option, @command{texi2dvi} produces PDF output +instead of DVI (@pxref{PDF Output}), by running @command{pdftex} +instead of @command{tex}. Alternatively, the command +@command{texi2pdf} is an abbreviation for running @samp{texi2dvi --pdf}. + +@cindex @LaTeX{}, processing with @command{texi2dvi} +@command{texi2dvi} can also be used to process @LaTeX{} files; simply +run @samp{texi2dvi filename.ext}. + +@command{texi2dvi} will use @command{etex} (or @command{pdfetex}) if +they are available; these extended versions of @TeX{} are not +required, and the DVI (or PDF) output is identical, but they simplify +the @TeX{} programming in some cases, and provide additional tracing +information when debugging @file{texinfo.tex}. For a list of other options, run @samp{texi2dvi --help}. @@ -13542,7 +14181,7 @@ lpr -Qdvi -hprint.server.domain bison.dvi @end example @item Convert the DVI file to a Postscript or PCL file and send it to your -local printer. @xref{dvips invocation,,, dvips, Dvips}, and the man +local printer. @xref{Invoking Dvips,,, dvips, Dvips}, and the man pages for @code{dvilj}, for detailed description of these tools. Once the DVI file is converted to the format your local printer understands directly, just send it to the appropriate port, usually @samp{PRN}. @@ -13576,14 +14215,12 @@ texi2dvi gcc.texinfo lpr -d gcc.dvi @end group @end example -@ifinfo -@xref{Texinfo Mode Printing}, for more information about formatting -and printing in Texinfo mode.@refill -@end ifinfo +See the next section for more information about formatting +and printing in Texinfo mode. -@node Texinfo Mode Printing, Compile-Command, Within Emacs, Hardcopy +@node Texinfo Mode Printing @section Formatting and Printing in Texinfo Mode @cindex Region printing in Texinfo mode @cindex Format and print in Texinfo mode @@ -13684,11 +14321,10 @@ tex-show-queue-command "lpq" @end example You can change the values of these variables with the @kbd{M-x -edit-options} command (@pxref{Edit Options, , Editing Variable Values, -emacs, The GNU Emacs Manual}), with the @kbd{M-x set-variable} command -(@pxref{Examining, , Examining and Setting Variables, emacs, The GNU -Emacs Manual}), or with your @file{.emacs} initialization file -(@pxref{Init File, , , emacs, The GNU Emacs Manual}).@refill +set-variable} command (@pxref{Examining, , Examining and Setting +Variables, emacs, The GNU Emacs Manual}), or with your @file{.emacs} +initialization file (@pxref{Init File, , , emacs, The GNU Emacs +Manual}). @cindex Customize Emacs package (@t{Development/Docs/Texinfo}) Beginning with version 20, GNU Emacs offers a user-friendly interface, @@ -13762,13 +14398,14 @@ command, a title page, a copyright page, and permissions. Besides an contents. (And of course most manuals contain a body of text as well.) For more information, see: + @itemize @bullet -@item @ref{settitle, , @code{@@settitle}} -@item @ref{setchapternewpage, , @code{@@setchapternewpage}} -@item @ref{Headings, ,Page Headings} -@item @ref{Titlepage & Copyright Page} -@item @ref{Printing Indices & Menus} -@item @ref{Contents} +@item @ref{settitle, , @code{@@settitle}}. +@item @ref{setchapternewpage, , @code{@@setchapternewpage}}. +@item @ref{Headings, ,Page Headings}. +@item @ref{Titlepage & Copyright Page}. +@item @ref{Printing Indices & Menus}. +@item @ref{Contents}. @end itemize @@ -13776,8 +14413,6 @@ For more information, see: @section Preparing for @TeX{} @cindex Preparing for @TeX{} @cindex @TeX{} input initialization -@cindex @code{TEXINPUTS} environment variable -@vindex TEXINPUTS @cindex @b{.profile} initialization file @cindex @b{.cshrc} initialization file @cindex Initialization file for @TeX{} input @@ -13786,7 +14421,10 @@ For more information, see: @samp{\input texinfo} command on the first line reads. The @file{texinfo.tex} file tells @TeX{} how to handle @@-commands; it is included in all standard GNU distributions. The latest version is -always available at @uref{ftp://ftp.gnu.org/gnu/texinfo/texinfo.tex}. +always available from the Texinfo source repository: +@smalldisplay +@uref{http://savannah.gnu.org/cgi-bin/viewcvs/texinfo/texinfo/doc/texinfo.tex?rev=HEAD} +@end smalldisplay @pindex texinfo.tex@r{, installing} @@ -13819,6 +14457,7 @@ example, if @file{texinfo.cnf} contains the line @samp{@@afourpaper} that page size in effect. If you have nothing to put in @file{texinfo.cnf}, you do not need to create it. +@cindex Environment variable @code{TEXINPUTS} @vindex TEXINPUTS If neither of the above locations for these system files suffice for you, you can specify the directories explicitly. For @@ -14142,27 +14781,83 @@ magnifications. Be prepared to experiment. @cindex PDF output @pindex pdftex -You can generate a PDF output file from Texinfo source by using the -@command{pdftex} program to process your file instead of plain -@command{tex}. That is, run @samp{pdftex foo.texi} instead of @samp{tex -foo.texi}, or give the @samp{--pdf} option to @command{texi2dvi}. +The simplest way to generate PDF output from Texinfo source is to run +the convenience script @command{texi2pdf}; this simply executes the +@command{texi2dvi} script with the @option{--pdf} option +(@pxref{Format with texi2dvi}). If for some reason you want to +process by hand, simply run the @command{pdftex} program instead of +plain @command{tex}. That is, run @samp{pdftex foo.texi} instead of +@samp{tex foo.texi}. @dfn{PDF} stands for `Portable Document Format'. It was invented by Adobe Systems some years ago for document interchange, based on their -PostScript language. 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}. At present, there are no @samp{@@ifpdf} or -@samp{@@pdf} commands as with the other output formats. +PostScript language. Related links: + +@itemize +@item +GNU GV, a @uref{http://www.foolabs.com/xpdf/, Ghostscript-based PDF +reader}. (It can also preview PostScript documents.) -Despite the `portable' in the name, PDF files are nowhere near as -portable in practice as the plain ASCII formats (Info, HTML) that -Texinfo supports (DVI portability is arguable). They also tend to be -much larger 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, so it has its place. +@item +A freely available standalone @uref{http://www.foolabs.com/xpdf/, +PDF reader} for the X window system. -PDF support in Texinfo is fairly rudimentary. +@item +@uref{http://partners.adobe.com/asn/acrobat/sdk/public/docs/, PDF definition}. + +@end itemize + +At present, Texinfo does not provide +@samp{@@ifpdf} or @samp{@@pdf} commands as for the other output +formats, since PDF documents contain many internal links that would be +hard or impossible to get right at the Texinfo source level. + +PDF files require special software to be displayed, unlike the plain +ASCII formats (Info, HTML) that Texinfo supports. They also tend to +be much larger than the DVI files output by @TeX{} by default. +Nevertheless, a PDF file does define an actual typeset document in a +self-contained file, so it has its place. + + +@node Obtaining TeX +@section How to Obtain @TeX{} +@cindex Obtaining @TeX{} +@cindex @TeX{}, how to obtain + +@c !!! Here is information about obtaining TeX. Update it whenever. +@c !!! Also consider updating TeX.README on ftp.gnu.org. +@c Updated by RJC on 1 March 1995, conversation with MacKay. +@c Updated by kb@cs.umb.edu on 29 July 1996. +@c Updated by kb@cs.umb.edu on 25 April 1997. +@c Updated by kb@cs.umb.edu on 27 February 1998. +@TeX{} is freely redistributable. You can obtain @TeX{} for Unix +systems via anonymous ftp or on physical media. The core material +consists of the Web2c @TeX{} distribution (@uref{http://tug.org/web2c}). + +Instructions for retrieval by anonymous ftp and information on other +available distributions: +@uref{http://tug.org/unixtex.ftp}. + +The Free Software Foundation provides a core distribution on its Source +Code CD-ROM suitable for printing Texinfo manuals. To order it, contact: + +@display +@group +Free Software Foundation, Inc. +59 Temple Place Suite 330 +Boston, MA @ @ 02111-1307 +USA +Telephone: @w{+1-617-542-5942} +Fax: (including Japan) @w{+1-617-542-2652} +Free Dial Fax (in Japan): +@w{ } @w{ } @w{ } 0031-13-2473 (KDD) +@w{ } @w{ } @w{ } 0066-3382-0158 (IDC) +Electronic mail: @code{gnu@@gnu.org} +@end group +@end display + +Many other @TeX{} distributions are available; see +@uref{http://tug.org/}. @node Creating and Installing Info Files @@ -14203,7 +14898,6 @@ For information on installing the Info file in the Info system, * Batch Formatting:: How to format for Info in Emacs Batch mode. * Tag and Split Files:: How tagged and split files help Info to run better. -* Generating HTML:: Generating HTML output with makeinfo. @end menu @@ -14219,17 +14913,18 @@ that are too small to run Emacs. You can run @code{makeinfo} in any one of three ways: from an operating system shell, from a shell inside Emacs, or by typing the @kbd{C-c C-m C-r} or the @kbd{C-c C-m C-b} command in Texinfo mode in Emacs. -@refill The @code{texinfo-format-region} and the @code{texinfo-format-buffer} commands are useful if you cannot run @code{makeinfo}. Also, in some circumstances, they format short regions or buffers more quickly than -@code{makeinfo}.@refill +@code{makeinfo}. + @node Invoking makeinfo @subsection Running @code{makeinfo} from a Shell +@pindex makeinfo -To create an Info file from a Texinfo file, type @code{makeinfo} +To create an Info file from a Texinfo file, invoke @command{makeinfo} followed by the name of the Texinfo file. Thus, to create the Info file for Bison, type the following to the shell: @@ -14237,19 +14932,10 @@ file for Bison, type the following to the shell: makeinfo bison.texinfo @end example -(You can run a shell inside Emacs by typing @kbd{M-x shell}.)@refill - -@ifinfo -Sometimes you will want to specify options. For example, if you wish -to discover which version of @code{makeinfo} you are using, -type:@refill - -@example -makeinfo --version -@end example +(You can run a shell inside Emacs by typing @kbd{M-x shell}.) -@xref{makeinfo options}, for more information. -@end ifinfo +@command{makeinfo} has many options to control its actions and output; +see the next section. @node makeinfo options @@ -14257,15 +14943,17 @@ makeinfo --version @cindex @code{makeinfo} options @cindex Options for @code{makeinfo} -The @code{makeinfo} command takes a number of options. Most often, -options are used to set the value of the fill column and specify the -footnote style. Each command line option is a word preceded by -@samp{--} or a letter preceded by @samp{-}. You can use abbreviations -for the long option names as long as they are unique.@refill +The @command{makeinfo} program accepts many options. Perhaps the most +commonly needed are those that change the output format. By default, +@command{makeinfo} outputs Info files. + +Each command line option is a word preceded by @samp{--} or a letter +preceded by @samp{-}. You can use abbreviations for the long option +names as long as they are unique. For example, you could use the following shell command to create an Info file for @file{bison.texinfo} in which each line is filled to only 68 -columns:@refill +columns: @example makeinfo --fill-column=68 bison.texinfo @@ -14279,7 +14967,7 @@ makeinfo --no-split --fill-column=70 @dots{} @noindent This would keep the Info file together as one possibly very long -file and would also set the fill column to 70.@refill +file and would also set the fill column to 70. The options are: @@ -14307,7 +14995,7 @@ input. @item --docbook @opindex --docbook -Generate DocBook output rather than Info. +Generate Docbook output rather than Info. @item --enable-encoding @opindex --enable-encoding @@ -14377,21 +15065,22 @@ not given, the current directory @file{.} is appended. Note that usual path separator character (@samp{:} on Unix, @samp{;} on MS-DOS/MS-Windows). -@item --ifhtml -@itemx --ifinfo -@itemx --ifplaintext -@itemx --iftex -@itemx --ifxml +@item --ifdocbook +@opindex --ifdocbook +@itemx --ifhtml @opindex --ifhtml +@itemx --ifinfo @opindex --ifinfo +@itemx --ifplaintext @opindex --ifplaintext +@itemx --iftex @opindex --iftex +@itemx --ifxml @opindex --ifxml For the specified format, process @samp{@@if@var{format}} and @samp{@@@var{format}} commands even if not generating the given output format. For instance, if @option{--iftex} is specified, then -@samp{@@iftex} and @samp{@@tex} blocks will be read. This can be useful -when postprocessing the output. +@samp{@@iftex} and @samp{@@tex} blocks will be read. @item --macro-expand=@var{file} @itemx -E @var{file} @@ -14400,21 +15089,23 @@ when postprocessing the output. Output the Texinfo source with all the macros expanded to the named file. Normally, the results of macro expansion are used internally by @code{makeinfo} and then discarded. This option is used by -@command{texi2dvi} if you are using an old version of @file{texinfo.tex} -that does not support @code{@@macro}. +@command{texi2dvi}. @item --no-headers +@item --plaintext @opindex --no-headers +@opindex --plaintext @cindex Plain text output @cindex ASCII text output @cindex Generating plain text files @cindex @file{INSTALL} file, generating @cindex Node separators, omitting @cindex Menus, omitting -For Info output, do not include menus or node separator lines in the -output. This results in a simple plain text file that you can (for -example) send in email without complications, or include in a -distribution (as in an @file{INSTALL} file). +Do not include menus or node separator lines in the output, and +implicitly @option{--enable-encoding} (see above). This results in a +simple plain text file that you can (for example) send in email +without complications, or include in a distribution (as in an +@file{INSTALL} file). @cindex Navigation links, omitting For HTML output, likewise omit menus. And if @samp{--no-split} is also @@ -14422,23 +15113,37 @@ specified, do not include a navigation links at the top of each node (these are never included in the default case of split output). @xref{Generating HTML}. -In both cases, write to standard output by default (can still be -overridden by @option{-o}). +In both cases, ignore @code{@@setfilename} and write to standard +output by default---can be overridden with @option{-o}. -@item --no-ifhtml -@itemx --no-ifinfo -@itemx --no-ifplaintext -@itemx --no-iftex -@itemx --no-ifxml +@item --no-ifdocbook +@opindex --no-ifdocbook +@itemx --no-ifhtml @opindex --no-ifhtml +@itemx --no-ifinfo @opindex --no-ifinfo +@itemx --no-ifplaintext @opindex --no-ifplaintext +@itemx --no-iftex @opindex --no-iftex +@itemx --no-ifxml @opindex --no-ifxml Do not process @samp{@@if@var{format}} and @samp{@@@var{format}} -commands even if generating the given format. For instance, if -@option{--no-ifhtml} is specified, then @samp{@@ifhtml} and -@samp{@@html} blocks will not be read. +commands, and do process @samp{@@ifnot@var{format}}, even if +generating the given format. For instance, if @option{--no-ifhtml} is +specified, then @samp{@@ifhtml} and @samp{@@html} blocks will not be +read, and @samp{@@ifnothtml} blocks will be. + +@item --no-number-footnotes +@opindex --no-number-footnotes +Suppress automatic footnote numbering. By default, @code{makeinfo} +numbers each footnote sequentially in a single node, resetting the +current footnote number to 1 at the start of each node. + +@item --no-number-sections +@opindex --no-number-sections +Do not output chapter, section, and appendix numbers. +You need to specify this if your manual is not hierarchically-structured. @item --no-split @opindex --no-split @@ -14454,28 +15159,21 @@ For HTML output, each file contains one node (@pxref{Generating HTML}). @opindex --no-pointer-validate @opindex --no-validate @cindex Pointer validation, suppressing -Suppress the pointer-validation phase of @code{makeinfo}. This can also -be done with the @code{@@novalidate} command (@pxref{Use TeX,,Use -@TeX{}}). Normally, after a Texinfo file is processed, some consistency -checks are made to ensure that cross references can be resolved, etc. -@xref{Pointer Validation}. +Suppress the pointer-validation phase of @code{makeinfo}---a dangerous +thing to do. This can also be done with the @code{@@novalidate} +command (@pxref{Use TeX,,Use @TeX{}}). Normally, after a Texinfo file +is processed, some consistency checks are made to ensure that cross +references can be resolved, etc. @xref{Pointer Validation}. @item --no-warn @opindex --no-warn -Suppress warning messages (but @emph{not} error messages). You might -want this if the file you are creating has examples of Texinfo cross -references within it, and the nodes that are referenced do not actually -exist. +Suppress warning messages (but @emph{not} error messages). @item --number-sections @opindex --number-sections Output chapter, section, and appendix numbers as in printed manuals. - -@item --no-number-footnotes -@opindex --no-number-footnotes -Suppress automatic footnote numbering. By default, @code{makeinfo} -numbers each footnote sequentially in a single node, resetting the -current footnote number to 1 at the start of each node. +This is the default. It works only with hierarchically-structured +manuals. @item --output=@var{file} @itemx -o @var{file} @@ -14549,6 +15247,18 @@ Generate XML output rather than Info. @end table +@vindex TEXINFO_OUTPUT_FORMAT +@cindex Environment variable @code{TEXINFO_OUTPUT_FORMAT} +@command{makeinfo} also reads the environment variable +@env{TEXINFO_OUTPUT_FORMAT} to determine the output format, if not +overridden by a command line option. The possible values are: + +@example +docbook html info plaintext xml +@end example + +If not set, Info output is the default. + @node Pointer Validation @subsection Pointer Validation @@ -14596,7 +15306,8 @@ cross-reference.@refill @cindex @@-commands in @@node, limited support Some Texinfo documents might fail during the validation phase because they use commands like @code{@@value} and @code{@@definfoenclose} in -node definitions and cross-references inconsistently. Consider the +node definitions and cross-references inconsistently. (Your best bet +is to avoid using @@-commands in node names.) Consider the following example: @example @@ -14707,8 +15418,8 @@ Printing}.)@refill You can specify options for @code{makeinfo} by setting the @code{makeinfo-options} variable with either the @kbd{M-x -edit-options} or the @kbd{M-x set-variable} command, or by setting the -variable in your @file{.emacs} initialization file.@refill +customize} or the @kbd{M-x set-variable} command, or by setting the +variable in your @file{.emacs} initialization file. For example, you could write the following in your @file{.emacs} file:@refill @@ -14720,28 +15431,25 @@ For example, you could write the following in your @file{.emacs} file:@refill @end group @end example +@noindent @c If you write these three cross references using xref, you see @c three references to the same named manual, which looks strange. @iftex For more information, see @ref{makeinfo options, , Options for -@code{makeinfo}}, as well as ``Editing Variable Values,'' ``Examining +@code{makeinfo}}, as well as ``Easy Customization Interface,'' ``Examining and Setting Variables,'' and ``Init File'' in @cite{The GNU Emacs Manual}. @end iftex -@noindent -@ifinfo +@ifnottex For more information, see@* -@ref{Edit Options, , Editing Variable Values, emacs, The GNU Emacs Manual},@* +@ref{Easy Customization, , Easy Customization Interface, emacs, The GNU Emacs Manual},@* @ref{Examining, , Examining and Setting Variables, emacs, The GNU Emacs Manual},@* @ref{Init File, , , emacs, The GNU Emacs Manual}, and@* @ref{makeinfo options, , Options for @code{makeinfo}}. -@end ifinfo +@end ifnottex @node texinfo-format commands -@comment node-name, next, previous, up @subsection The @code{texinfo-format@dots{}} Commands -@findex texinfo-format-region -@findex texinfo-format-buffer In GNU Emacs in Texinfo mode, you can format part or all of a Texinfo file with the @code{texinfo-format-region} command. This formats the @@ -14758,13 +15466,13 @@ Texinfo file.@refill @table @kbd @item C-c C-e C-r @itemx @code{texinfo-format-region} -Format the current region for Info. @findex texinfo-format-region +Format the current region for Info. @item C-c C-e C-b @itemx @code{texinfo-format-buffer} -Format the current buffer for Info. @findex texinfo-format-buffer +Format the current buffer for Info. @end table The @code{texinfo-format-region} and @code{texinfo-format-buffer} @@ -14782,8 +15490,8 @@ provides better error checking (@pxref{makeinfo in Emacs}).@refill You can format Texinfo files for Info using @code{batch-texinfo-format} and Emacs Batch mode. You can run Emacs in Batch mode from any shell, -including a shell inside of Emacs. (@xref{Command Switches, , Command -Line Switches and Arguments, emacs, The GNU Emacs Manual}.)@refill +including a shell inside of Emacs. (@xref{Command Arguments,,, +emacs, The GNU Emacs Manual}.) Here is a shell command to format all the files that end in @file{.texinfo} in the current directory: @@ -14892,172 +15600,7 @@ you may want to run the @code{Info-validate} command. (The need @code{Info-validate}.) However, you cannot run the @kbd{M-x Info-validate} node-checking command on indirect files. For information on how to prevent files from being split and how to -validate the structure of the nodes, see @ref{Using -Info-validate}.@refill - - -@node Generating HTML -@subsection Generating HTML -@cindex HTML, generating - -Besides generating output in the Info format, you can use the -@samp{--html} option to @command{makeinfo} to generate output in HTML -format, for use by web browsers (for example). - -@menu -* HTML Translation:: Details of the HTML output. -* HTML Splitting:: How HTML output is split. -* HTML CSS:: HTML output and Cascading Style Sheets. -@end menu - -@node HTML Translation -@subsubsection HTML Translation - -@command{makeinfo} will include segments of Texinfo source between -@code{@@ifhtml} and @code{@@end ifhtml} in the HTML output (but not -any of the other conditionals, by default). Source between -@code{@@html} and @code{@@end html} is passed without change to the -output (i.e., suppressing the normal escaping of input @samp{<}, -@samp{>} and @samp{&} characters which have special significance in -HTML). @xref{Conditional Commands}. - -@opindex --footnote-style@r{, ignored in HTML output} -The @option{--footnote-style} option is currently ignored for HTML output; -footnotes are always linked to the end of the output file. - -@cindex Navigation bar, in HTML output -By default, a navigation bar is inserted at the start of each node, -analogous to Info output. The @samp{--no-headers} option suppresses -this if used with @samp{--no-split}. Header @code{<link>} elements in -split output can support info-like navigation with browsers like Lynx -and @w{Emacs W3} which implement this HTML@tie{}1.0 feature. - -@cindex HTML output, browser compatibility of -The HTML generated is mostly standard (i.e., HTML@tie{}2.0, RFC-1866). -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. The HTML@tie{}4 @samp{lang} -attribute on the @samp{<html>} attribute is also used. (Please report -output from an error-free run of @code{makeinfo} which has browser -portability problems as a bug.) - - -@node HTML Splitting -@subsubsection HTML Splitting - -@cindex Split HTML output -@cindex HTML output, split - -By default, @command{makeinfo} splits HTML output into one output file -per Texinfo source node. - -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}. - -@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>/}. -Cross-document node references are not supported in monolithic HTML. - - -@node HTML CSS -@subsubsection HTML CSS -@cindex HTML, and CSS -@cindex CSS, and HTML output -@cindex Cascading Style Sheets, and HTML output - -Cascading Style Sheets (CSS for short) is a network standard for -influencing the display of HTML documents: -@uref{http://www.w3.org/Style/CSS/}. - -By default, @command{makeinfo} includes a few simple CSS commands to -better implement the appearance of some of the environments. Here is -a couple of them: - -@example -pre.display @{ font-family:inherit @} -pre.smalldisplay @{ font-family:inherit; font-size:smaller @} -@end example - -A full explanation of CSS is (far) beyond this manual; please see the -references above. In brief, however, this specification tells the web -browser to use a `smaller' font size for @code{@@smalldisplay} text, -and to use the `inherited' font (generally a regular roman typeface) -for both @code{@@smalldisplay} and @code{@@display}. By default, the -HTML @samp{<pre>} command uses a monospaced font. - -You can influence the CSS in the HTML output with the -@option{--css-include=@var{file}} option to @command{makeinfo}. This -includes the contents @var{file} in the HTML output, as you might -expect. However, the details are somewhat tricky, to provide maximum -flexibility. - -@cindex @@import specifications, in CSS files -The CSS file may begin with so-called @samp{@@import} directives, -which link to external CSS specifications for browsers to use when -interpreting the document. Again, a full description is beyond our -scope here, but we'll describe how they work syntactically, so we can -explain how @command{makeinfo} handles them. - -@cindex Comments, in CSS files -There can be more than one @samp{@@import}, but they have to come -first in the file, with only whitespace and comments interspersed, no -normal definitions. (Technical exception: an @samp{@@charset} -directive may precede the @samp{@@import}'s. This does not alter -@command{makeinfo}'s behavior.) Comments in CSS files are delimited -by @samp{/* ... */}, as in C. An @samp{@@import} directive must be in -one of these two forms: - -@example -@@import url(http://example.org/foo.css); -@@import "http://example.net/bar.css"; -@end example - -As far as @command{makeinfo} is concerned, the crucial characters are -the @samp{@@} at the beginning and the semicolon terminating the -directive. CSS provides for a number of different -@samp{@@}-directives, and @command{makeinfo} treats them all the same -way. When reading the CSS file, it simply copies any such -@samp{@@}-directive into the output, as follows: - -@itemize -@item If @var{file} contains only normal CSS declarations, it is -included after @command{makeinfo}'s default CSS, thus overriding it. - -@item If @var{file} begins with @samp{@@import} specifications (see -below), then the @samp{import}'s are included first (they have to come -first, according to the standard), and then @command{makeinfo}'s -default CSS is included. If you need to override @command{makeinfo}'s -defaults from an @samp{@@import}, you can do so with the @samp{! -important} CSS construct, as in: -@example -pre.smallexample @{ font-size: inherit ! important @} -@end example - -@item If @var{file} contains both @samp{@@import} and inline CSS -specifications, the @samp{@@import}'s are included first, then -@command{makeinfo}'s defaults, and lastly the inline CSS from -@var{file}. -@end itemize - -If the CSS file is malformed or erroneous, @command{makeinfo}'s output -is unspecified. @command{makeinfo} does not try to interpret the -meaning of the CSS file in any way; it just looks for the special -@samp{@@} and @samp{;} characters and blindly copies the text into the -output. Comments in the CSS file may or may not be included in the -output. +validate the structure of the nodes, see @ref{Using Info-validate}. @node Installing an Info File @@ -15230,6 +15773,7 @@ file in @file{/home/bob/info}. Thus, Info will list the to recompose the @file{dir} file. @vindex INFOPATH +@cindex Environment variable @code{INFOPATH} Finally, you can tell Info where to look by setting the @code{INFOPATH} environment variable in your shell startup file, such as @file{.cshrc}, @file{.profile} or @file{autoexec.bat}. If you use a Bourne-compatible @@ -15278,7 +15822,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 colon, 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 @@ -15356,11 +15900,11 @@ each usage specifies the `current' category; any subsequent @cindex Free Software Directory @cindex Dir categories, choosing @cindex Categories, choosing -When choosing the categories for @code{@@dircategory}, we recommend -consulting the @uref{Free Sofware Directory, -http://www.gnu.org/directory}. If your program is not listed there, or -listed incorrectly or incompletely, please report the situation to the -directory maintainers (@email{bug-directory@@gnu.org}) so that the +When choosing a category name for the @code{@@dircategory} command, we +recommend consulting the @uref{http://www.gnu.org/directory, +Free Software Directory}. If your program is not listed there, +or listed incorrectly or incompletely, please report the situation to +the directory maintainers (@email{bug-directory@@gnu.org}) so that the category names can be kept in sync. Here are a few examples (see the @file{util/dir-example} file in the @@ -15458,7 +16002,7 @@ Equivalent to using the @var{info-file} argument. @itemx -D @var{dir} @opindex --info-dir=@var{dir} @opindex -D @var{dir} -Specify the directory where @file{dir} resides. +Specify the directory where the directory file @file{dir} resides. Equivalent to @samp{--dir-file=@var{dir}/dir}. @item --item=@var{text} @@ -15489,12 +16033,619 @@ information in the Info file itself. @itemx -V @opindex --version @opindex -V -@cindex version number, for install-info +@cindex Version number, for install-info Display version information and exit successfully. @end table +@node Generating HTML +@chapter Generating HTML +@cindex HTML output + +@command{makeinfo} generates Info output by default, but given the +@option{--html} option, it will generate HTML, for web browsers and +other programs. This chapter gives some details on such HTML output. + + +@command{makeinfo} can also write in XML and Docbook format, but we do +not as yet describe these further. @xref{Output Formats}, for a brief +overview of all the output formats. + +@menu +* HTML Translation:: Details of the HTML output. +* HTML Splitting:: How HTML output is split. +* HTML CSS:: Influencing HTML output with Cascading Style Sheets. +* HTML Xref:: Cross-references in HTML output. +@end menu + + +@node HTML Translation +@section HTML Translation + +@command{makeinfo} will include segments of Texinfo source between +@code{@@ifhtml} and @code{@@end ifhtml} in the HTML output (but not +any of the other conditionals, by default). Source between +@code{@@html} and @code{@@end html} is passed without change to the +output (i.e., suppressing the normal escaping of input @samp{<}, +@samp{>} and @samp{&} characters which have special significance in +HTML). @xref{Conditional Commands}. + +@opindex --footnote-style@r{, ignored in HTML output} +The @option{--footnote-style} option is currently ignored for HTML output; +footnotes are always linked to the end of the output file. + +@cindex Navigation bar, in HTML output +By default, a navigation bar is inserted at the start of each node, +analogous to Info output. The @samp{--no-headers} option suppresses +this if used with @samp{--no-split}. Header @code{<link>} elements in +split output can support info-like navigation with browsers like Lynx +and @w{Emacs W3} which implement this HTML@tie{}1.0 feature. + +@cindex HTML output, browser compatibility of +The HTML generated is mostly standard (i.e., HTML@tie{}2.0, RFC-1866). +One exception is that HTML@tie{}3.2 tables are generated from the +@code{@@multitable} command, but tagged to degrade as well as possible +in browsers without table support. The HTML@tie{}4 @samp{lang} +attribute on the @samp{<html>} attribute is also used. (Please report +output from an error-free run of @code{makeinfo} which has browser +portability problems as a bug.) + + +@node HTML Splitting +@section HTML Splitting +@cindex Split HTML output +@cindex HTML output, split + +When splitting output (which is the default), @command{makeinfo} +writes HTML output into (generally) one output file per Texinfo source +@code{@@node}. + +The output file name is the node name with special characters replaced +by @samp{-}'s, so it can work as a filename. In the unusual case of +two different nodes having the same name after this treatment, they +are written consecutively to the same file, with HTML anchors so each +can be referred to separately. If @command{makeinfo} is run on a +system which does not distinguish case in filenames, nodes which are +the same except for case will also be folded into the same output +file. + +When splitting, the HTML output files are written into a subdirectory, +with the name chosen as follows: +@enumerate +@item +@command{makeinfo} first tries the subdirectory with the base name +from @code{@@setfilename} (that is, any extension is removed). For +example, HTML output for @code{@@setfilename gcc.info} would be +written into a subdirectory named @samp{gcc}. + +@item +If that directory cannot be created for any reason, then +@command{makeinfo} tries appending @samp{.html} to the directory name. +For example, output for @code{@@setfilename texinfo} would be written +to @samp{texinfo.html}. + +@item +If the @samp{@var{name}.html} directory can't be +created either, @code{makeinfo} gives up. + +@end enumerate + +@noindent In any case, the top-level output file within the directory +is always named @samp{index.html}. + +Monolithic output (@code{--no-split}) is named according to +@code{@@setfilename} (with any @samp{.info} extension is replaced with +@samp{.html}) or @code{--output} (the argument is used literally). + + +@node HTML CSS +@section HTML CSS +@cindex HTML, and CSS +@cindex CSS, and HTML output +@cindex Cascading Style Sheets, and HTML output + +Cascading Style Sheets (CSS for short) is an Internet standard for +influencing the display of HTML documents: see +@uref{http://www.w3.org/Style/CSS/}. + +By default, @command{makeinfo} includes a few simple CSS commands to +better implement the appearance of some of the environments. Here +are two of them, as an example: + +@example +pre.display @{ font-family:inherit @} +pre.smalldisplay @{ font-family:inherit; font-size:smaller @} +@end example + +A full explanation of CSS is (far) beyond this manual; please see the +reference above. In brief, however, this specification tells the web +browser to use a `smaller' font size for @code{@@smalldisplay} text, +and to use the `inherited' font (generally a regular roman typeface) +for both @code{@@smalldisplay} and @code{@@display}. By default, the +HTML @samp{<pre>} command uses a monospaced font. + +You can influence the CSS in the HTML output with the +@option{--css-include=@var{file}} option to @command{makeinfo}. This +includes the contents @var{file} in the HTML output, as you might +expect. However, the details are somewhat tricky, as described in the +following, to provide maximum flexibility. + +@cindex @@import specifications, in CSS files +The CSS file may begin with so-called @samp{@@import} directives, +which link to external CSS specifications for browsers to use when +interpreting the document. Again, a full description is beyond our +scope here, but we'll describe how they work syntactically, so we can +explain how @command{makeinfo} handles them. + +@cindex Comments, in CSS files +There can be more than one @samp{@@import}, but they have to come +first in the file, with only whitespace and comments interspersed, no +normal definitions. (Technical exception: an @samp{@@charset} +directive may precede the @samp{@@import}'s. This does not alter +@command{makeinfo}'s behavior, it just copies the @samp{@@charset} if +present.) Comments in CSS files are delimited by @samp{/* ... */}, as +in C. An @samp{@@import} directive must be in one of these two forms: + +@example +@@import url(http://example.org/foo.css); +@@import "http://example.net/bar.css"; +@end example + +As far as @command{makeinfo} is concerned, the crucial characters are +the @samp{@@} at the beginning and the semicolon terminating the +directive. When reading the CSS file, it simply copies any such +@samp{@@}-directive into the output, as follows: + +@itemize +@item If @var{file} contains only normal CSS declarations, it is +included after @command{makeinfo}'s default CSS, thus overriding it. + +@item If @var{file} begins with @samp{@@import} specifications (see +below), then the @samp{import}'s are included first (they have to come +first, according to the standard), and then @command{makeinfo}'s +default CSS is included. If you need to override @command{makeinfo}'s +defaults from an @samp{@@import}, you can do so with the @samp{!@: +important} CSS construct, as in: +@example +pre.smallexample @{ font-size: inherit ! important @} +@end example + +@item If @var{file} contains both @samp{@@import} and inline CSS +specifications, the @samp{@@import}'s are included first, then +@command{makeinfo}'s defaults, and lastly the inline CSS from +@var{file}. + +@item Any @@-directive other than @samp{@@import} and @samp{@@charset} +is treated as a CSS declaration, meaning @command{makeinfo} includes +its default CSS and then the rest of the file. + +@end itemize + +If the CSS file is malformed or erroneous, @command{makeinfo}'s output +is unspecified. @command{makeinfo} does not try to interpret the +meaning of the CSS file in any way; it just looks for the special +@samp{@@} and @samp{;} characters and blindly copies the text into the +output. Comments in the CSS file may or may not be included in the +output. + + +@node HTML Xref +@section HTML Cross-references +@cindex HTML cross-references +@cindex Cross-references, in HTML output + +Cross-references between Texinfo manuals in HTML format amount, in the +end, to a standard HTML @code{<a>} link, but the details are +unfortunately complex. This section describes the algorithm used in +detail, so that Texinfo can cooperate with other programs, such as +@command{texi2html}, by writing mutually compatible HTML files. + +This algorithm may or may not be used for links @emph{within} HTML +output for a Texinfo file. Since no issues of compatibility arise in +such cases, we do not need to specify this. + +We try to support references to such ``external'' manuals in both +monolithic and split forms. A @dfn{monolithic} (mono) manual is +entirely contained in one file, and a @dfn{split} manual has a file +for each node. (@xref{HTML Splitting}.) + +@cindex Dumas, Patrice +Acknowledgement: this algorithm was primarily devised by Patrice Dumas +in 2003--04. + +@menu +* Link Basics: HTML Xref Link Basics. +* Node Expansion: HTML Xref Node Name Expansion. +* Command Expansion: HTML Xref Command Expansion. +* 8-bit Expansion: HTML Xref 8-bit Character Expansion. +* Mismatch: HTML Xref Mismatch. +@end menu + + +@node HTML Xref Link Basics +@subsection HTML Cross-reference Link Basics +@cindex HTML cross-reference link basics + +For our purposes, an HTML link consists of four components: a host +name, a directory part, a file part, and a target part. We +always assume the @code{http} protocol. For example: + +@example +http://@var{host}/@var{dir}/@var{file}.html#@var{target} +@end example + +The information to construct a link comes from the node name and +manual name in the cross-reference command in the Texinfo source +(@pxref{Cross References}), and from @dfn{external information}, which +is currently simply hardwired. In the future, it may come from an +external data file. + +We now consider each part in turn. + +The @var{host} is hardwired to be the local host. This could either +be the literal string @samp{localhost}, or, according to the rules for +HTML links, the @samp{http://localhost/} could be omitted entirely. + +The @var{dir} and @var{file} parts are more complicated, and depend on +the relative split/mono nature of both the manual being processed and +the manual that the cross-reference refers to. The underlying idea is +that there is one directory for Texinfo manuals in HTML, and each +manual is either available as a monolithic file @file{manual.html}, or a +split subdirectory @file{manual/*.html}. Here are the cases: + +@itemize @bullet +@item +If the present manual is split, and the referent manual is also split, +the directory is @samp{../@var{referent/}} and the file is the +expanded node name (described later). + +@item +If the present manual is split, and the referent manual is mono, the +directory is @samp{../} and the file is @file{@var{referent}.html}. + +@item +If the present manual is mono, and the referent manual is split, the +directory is @file{@var{referent}/} and the file is the expanded node +name. + +@item +If the present manual is mono, and the referent manual is also mono, +the directory is @file{./} (or just the empty string), and the file is +@file{@var{referent}.html}. + +@end itemize + +One exception: the algorithm for node name expansion prefixes the +string @samp{g_t} when the node name begins with a non-letter. This +kludge (due to XHTML rules) is not necessary for filenames, and is +therefore omitted. + +Any directory part in the filename argument of the source +cross-reference command is ignored. Thus, @code{@@xref@{,,,../foo@}} +and @code{@@xref@{,,,foo@}} both use @samp{foo} as the manual name. +This is because any such attempted hardwiring of the directory is very +unlikely to be useful for both Info and HTML output. + +Finally, the @var{target} part is always the expanded node name. + +Whether the present manual is split or mono is determined by user +option; @command{makeinfo} defaults to split, with the +@option{--no-split} option overriding this. + +Whether the referent manual is split or mono is another bit of the +external information. For now, @command{makeinfo} simply assumes the +referent manual is the same as the present manual. + +There can be a mismatch between the format of the referent manual that +the generating software assumes, and the format it's actually present +in. @xref{HTML Xref Mismatch}. + + +@node HTML Xref Node Name Expansion +@subsection HTML Cross-reference Node Name Expansion +@cindex HTML cross-reference node name expansion +@cindex node name expansion, in HTML cross-references +@cindex expansion, of node names in HTML cross-references + +As mentioned in the previous section, the key part of the HTML +cross-reference algorithm is the conversion of node names in the +Texinfo source into strings suitable for XHTML identifiers and +filenames. The restrictions are similar for each: plain ASCII +letters, numbers, and the @samp{-} and @samp{_} characters are all +that can be used. (Although HTML anchors can contain most characters, +XHTML is more restrictive.) + +Cross-references in Texinfo can actually refer either to nodes or +anchors (@pxref{anchor}), but anchors are treated identically to nodes +in this context, so we'll continue to say ``node'' names for +simplicity. + +(@@-commands and 8-bit characters are not presently handled by +@command{makeinfo} for HTML cross-references. See the next section.) + +A special exception: the Top node (@pxref{The Top Node}) is always +mapped to the file @file{index.html}, to match web server software. +However, the HTML @emph{target} is @samp{Top}. Thus (in the split case): + +@example +@@xref@{Top, Introduction,, emacs, The GNU Emacs Manual@}. +@result{} <a href="emacs/index.html#Top"> +@end example + +@enumerate +@item +The standard ASCII letters (a-z and A-Z) are not modified. All other +characters are changed as specified below. + +@item +The standard ASCII numbers (0-9) are not modified except when a number +is the first character of the node name. In that case, see below. + +@item +Multiple consecutive space, tab and newline characters are transformed +into just one space. (It's not possible to have newlines in node +names with the current implementation, but we specify it anyway, just +in case.) + +@item +Leading and trailing spaces are removed. + +@item +After the above has been applied, each remaining space character is +converted into a @samp{-} character. + +@item +Other ASCII 7-bit characters are transformed into @samp{_00@var{xx}}, +where @var{xx} is the ASCII character code in (lowercase) hexadecimal. +This includes @samp{_}, which is mapped to @samp{_005f}. + +@item +If the node name does not begin with a letter, the literal string +@samp{g_t} is prefixed to the result. (Due to the rules above, that +string can never occur otherwise; it is an arbitrary choice, standing +for ``GNU Texinfo''.) This is necessary because XHTML requires that +identifiers begin with a letter. + +@end enumerate + +For example: + +@example +@@node A node --- with _'% +@result{} A-node-_002d_002d_002d-with-_005f_0027_0025 +@end example + +Notice in particular: + +@itemize @bullet +@item @samp{_} @result{} @samp{_005f} +@item @samp{-} @result{} @samp{_002d} +@item @samp{A node} @result{} @samp{A-node} +@end itemize + +On case-folding computer systems, nodes differing only by case will be +mapped to the same file. + +In particular, as mentioned above, Top always maps to the file +@file{index.html}. Thus, on a case-folding system, Top and a node +named `Index' will both be written to @file{index.html}. + +Fortunately, the targets serve to distinguish these cases, since HTML +target names are always case-sensitive, independent of operating +system. + + +@node HTML Xref Command Expansion +@subsection HTML Cross-reference Command Expansion +@cindex HTML cross-reference command expansion + +In standard Texinfo, node names may not contain @@-commands. +@command{makeinfo} has an option @option{--commands-in-node-names} +which partially supports it (@pxref{Invoking makeinfo}), but it is not +robust and not recommended. + +Thus, @command{makeinfo} also does not fully implement this part of +the HTML cross-reference algorithm, but it is documented here for the +sake of completeness. + +First, comments are removed. + +Next, any @code{@@value} commands (@pxref{set value}) and macro invocations +(@pxref{Invoking Macros}) are fully expanded. + +Then, for the following commands, the command name and braces are removed, +the text of the argument is recursively transformed: +@example +@@asis @@b @@cite @@code @@command @@dfn @@dmn @@dotless +@@emph @@env @@file @@indicateurl @@kbd @@key +@@samp @@sc @@slanted @@strong @@t @@var @@w +@end example + +@noindent For @code{@@sc}, any letters are capitalized. + +The following commands are replaced by constant text, as shown. If +any of these commands have non-empty arguments, as in +@code{@@TeX@{bad@}}, it is an error, and the result is unspecified. +`(space)' means a space character, `(nothing)' means the empty string, +etc. The notation `U+@var{xxxx}' means Unicode code point @var{xxxx}. +There are further transformations of many of these expansions for the +final file or target name, such as space characters to @samp{-}, etc., +according to the other rules. + +@multitable @columnfractions .3 .5 +@item @code{@@(newline)} @tab (space) +@item @code{@@(space)} @tab (space) +@item @code{@@(tab)} @tab (space) +@item @code{@@!} @tab @samp{!} +@item @code{@@*} @tab (space) +@item @code{@@-} @tab (nothing) +@item @code{@@.} @tab @samp{.} +@item @code{@@:} @tab (nothing) +@item @code{@@?} @tab @samp{?} +@item @code{@@@@} @tab @samp{@@} +@item @code{@@@{} @tab @samp{@{} +@item @code{@@@}} @tab @samp{@}} +@item @code{@@LaTeX} @tab @samp{LaTeX} +@item @code{@@TeX} @tab @samp{TeX} +@item @code{@@bullet} @tab U+2022 +@item @code{@@comma} @tab @samp{,} +@item @code{@@copyright} @tab U+00A9 +@item @code{@@dots} @tab U+2026 +@item @code{@@enddots} @tab @samp{...} +@item @code{@@equiv} @tab U+2261 +@item @code{@@error} @tab @samp{error-->} +@item @code{@@euro} @tab U+20AC +@item @code{@@exclamdown} @tab U+00A1 +@item @code{@@expansion} @tab U+2192 +@item @code{@@minus} @tab U+2212 +@item @code{@@ordf} @tab U+00AA +@item @code{@@ordm} @tab U+00BA +@item @code{@@point} @tab U+2217 +@item @code{@@pounds} @tab U+00A3 +@item @code{@@print} @tab @samp{-|} +@item @code{@@questiondown} @tab U+00BF +@item @code{@@registeredsymbol} @tab U+00AE +@item @code{@@result} @tab U+21D2 +@item @code{@@tie} @tab (space) +@end multitable + +An @code{@@acronym} or @code{@@abbr} command is replaced by the first +argument, followed by the second argument in parentheses, if present. +@xref{acronym}. + +An @code{@@email} command is replaced by the @var{text} argument if +present, else the address. @xref{email}. + +An @code{@@image} command is replaced by the filename (first) +argument. @xref{Images}. + +A @code{@@verb} command is replaced by its transformed argument. +@xref{verb}. + +Any other command is an error, and the result is unspecified. + + +@node HTML Xref 8-bit Character Expansion +@subsection HTML Cross-reference 8-bit Character Expansion +@cindex HTML cross-reference 8-bit character expansion +@cindex 8-bit characters, in HTML cross-references +@cindex Expansion of 8-bit characters in HTML cross-references + +Usually, characters other than plain 7-bit ASCII are transformed into +the corresponding Unicode code point(s) in Normalization Form C, which +uses precomposed characters where available. (This is the +normalization form recommended by the W3C and other bodies.) This +holds when that code point is 0xffff or less, as it almost always is. + +These will then be further transformed by the rules above into the +string @samp{_@var{xxxx}}, where @var{xxxx} is the code point in hex. + +For example, combining this rule and the previous section: + +@example +@@node @@b@{A@} @@TeX@{@} @@u@{B@} @@point@{@}@@enddots@{@} +@result{} A-TeX-B_0306-_2605_002e_002e_002e +@end example + +Notice: 1)@tie{}@code{@@enddots} expands to three periods which in +turn expands to three @samp{_002e}'s; 2)@tie{}@code{@@u@{B@}} is a `B' +with a breve accent, which does not exist as a pre-accented Unicode +character, therefore expands to @samp{B_0306} (B with combining +breve). + +When the Unicode code point is above 0xffff, the transformation is +@samp{__@var{xxxxxx}}, that is, two leading underscores followed by +six hex digits. Since Unicode has declared that their highest code +point is 0x10ffff, this is sufficient. (We felt it was better to +define this extra escape than to always use six hex digits, since the +first two would nearly always be zeros.) + +For the definition of Unicode Normalization Form C, see Unicode report +UAX#15, @uref{http://www.unicode.org/reports/tr15/}. Many related +documents and implementations are available elsewhere on the web. + + +@node HTML Xref Mismatch +@subsection HTML Cross-reference Mismatch +@cindex HTML cross-reference mismatch +@cindex Mismatched HTML cross-reference source and target + +As mentioned earlier (@pxref{HTML Xref Link Basics}), the generating +software has to guess whether a given manual being cross-referenced is +available in split or monolithic form---and, inevitably, it might +guess wrong. However, it is possible when the referent manual itself +is generated, it is possible to handle at least some mismatches. + +In the case where we assume the referent is split, but it is actually +available in mono, the only recourse would be to generate a +@file{manual/} subdirectory full of HTML files which redirect back to +the monolithic @file{manual.html}. Since this is essentially the same +as a split manual in the first place, it's not very appealing. + +On the other hand, in the case where we assume the referent is mono, +but it is actually available in split, it is possible to use +JavaScript to redirect from the putatively monolithic +@file{manual.html} to the different @file{manual/node.html} files. +Here's an example: + +@example +function redirect() @{ + switch (location.hash) @{ + case "#Node1": + location.replace("manual/Node1.html#Node1"); break; + case "#Node2" : + location.replace("manual/Node2.html#Node2"); break; + @dots{} + default:; + @} +@} +@end example + +Then, in the @code{<body>} tag of @file{manual.html}: + +@example +<body onLoad="redirect();"> +@end example + +Once again, this is something the software which generated the +@emph{referent} manual has to do in advance, it's not something the +software generating the actual cross-reference in the present manual +can control. + +Ultimately, we hope to allow for an external configuration file to +control which manuals are available from where, and how. + + +@ignore +-- not yet -- + +external information +-------------------- + +The information for the reference is searched in the file +`htmlxref.cnf' present in the following directories: +<srcdir>/.texinfo/, ~/.texinfo/, SYSCONFDIR/texinfo/, +DATADIR/texinfo/ +The first match should be used. + +The file is line-oriented, with the following format: + <manualname> <whitespace> <keyword> <whitespace> <urlprefix> +with <keyword> being "mono" or "split". Thus +texinfo split http://www.gnu.org/software/texinfo/manual/texinfo/html_node/ +texinfo mono http://www.gnu.org/software/texinfo/manual/texinfo/texinfo.html + +If the keyword is 'split', that is the target is split, the urlprefix gives +the directory and host name. +If the keyword is 'mono', that is the target is mono, the urlprefix gives +directory, host and file name. + +'#' followed by a space begins comments. '#' followed by another character +cannot begin comments as there are # in urls. + +@end ignore + + @node Command List @appendix @@-Command List @cindex Alphabetical @@-command list @@ -15506,6 +16657,13 @@ Here is an alphabetical list of the @@-commands in Texinfo. Square brackets, @t{[}@w{ }@t{]}, indicate optional arguments; an ellipsis, @samp{@dots{}}, indicates repeated text. +More specifics on the general syntax of different @@-commands are +given in the section below. + +@menu +* Command Syntax:: General syntax for varieties of @@-commands. +@end menu + @sp 1 @table @code @item @@@var{whitespace} @@ -15522,8 +16680,7 @@ Generate an umlaut or acute accent, respectively, over the next character, as in @"o and @'o. @xref{Inserting Accents}. @item @@* -Force a line break. Do not end a paragraph that uses @code{@@*} with -an @code{@@refill} command. @xref{Line Breaks}. +Force a line break. @xref{Line Breaks}. @item @@,@{@var{c}@} Generate a cedilla accent under @var{c}, as in @,{c}. @xref{Inserting @@ -15536,7 +16693,7 @@ Insert a discretionary hyphenation point. @xref{- and hyphenation}. Produce a period that really does end a sentence (usually after an end-of-sentence capital letter). @xref{Ending a Sentence}. -@item @/ +@item @@/ Produces no output, but allows a line break. @xref{Line Breaks}. @item @@: @@ -15556,7 +16713,7 @@ an end-of-sentence capital letter). @xref{Ending a Sentence}. @item @@@@ Stands for an at sign, @samp{@@}. -@xref{Braces Atsigns, , Inserting @@ and braces}. +@xref{Atsign Braces Comma, , Inserting @@ and @{@} and @comma{}}. @item @@\ Stands for a backslash (@samp{\}) inside @code{@@math}. @@ -15570,11 +16727,11 @@ character, as in @^o and @`e. @item @@@{ Stands for a left brace, @samp{@{}. -@xref{Braces Atsigns, , Inserting @@ and braces}. +@xref{Atsign Braces Comma, , Inserting @@ and @{@} and @comma{}}. @item @@@} Stands for a right-hand brace, @samp{@}}.@* -@xref{Braces Atsigns, , Inserting @@ and braces}. +@xref{Atsign Braces Comma, , Inserting @@ and @{@} and @comma{}}. @item @@~ Generate a tilde accent over the next character, as in @~N. @@ -15585,9 +16742,13 @@ Generate a tilde accent over the next character, as in @~N. Generate the uppercase and lowercase Scandinavian A-ring letters, respectively: @AA{}, @aa{}. @xref{Inserting Accents}. -@item @@acronym@{@var{abbrev}@} -Tag @var{abbrev} as an acronym, that is, an abbreviation written in all -capital letters, such as `NASA'. @xref{acronym,, @code{acronym}}. +@item @@abbr@{@var{abbreviation}@} +Tag @var{abbreviation} as an abbreviation, such as `Comput.'. +@xref{abbr,, @code{abbr}}. + +@item @@acronym@{@var{acronym}@} +Tag @var{acronym} as an acronym, such as `NASA'. +@xref{acronym,, @code{acronym}}. @item @@AE@{@} @itemx @@ae@{@} @@ -15666,7 +16827,10 @@ file following an @code{@@bye} command. @xref{Ending a File}.@refill @item @@c @var{comment} Begin a comment in Texinfo. The rest of the line does not appear in either the Info file or the printed manual. A synonym for -@code{@@comment}. @xref{Comments, , Comments}.@refill +@code{@@comment}. @xref{Comments}. + +@item @@caption +Define the full caption for a @code{@@float}. @xref{caption shortcaption}. @item @@cartouche Highlight an example or quotation by drawing a box with rounded @@ -15712,6 +16876,10 @@ and @code{@@end ifset} commands, and preventing Highlight text that is an expression, a syntactically complete token of a program, or a program name. @xref{code, , @code{@@code}}.@refill +@item @@comma@{@} +Insert a comma `,' character; only needed when a literal comma would +be taken as an argument separator. @xref{Inserting a Comma}. + @item @@command@{@var{command-name}@} Indicate a command name, such as @command{ls}. @xref{command,, @code{@@command}}. @@ -15727,7 +16895,8 @@ menus instead. @xref{Contents, , Generating a Table of Contents}.@refill @item @@copyright@{@} -Generate a copyright symbol. @xref{copyright symbol,, @code{@@copyright@{@}}}. +Generate the copyright symbol @copyright{}. @xref{copyright symbol,, +@code{@@copyright@{@}}}. @ignore @item @@ctrl@{@var{ctrl-char}@} @@ -15810,6 +16979,11 @@ the category, the name of the type (which is a word like @samp{int} or @samp{float}), and then the names of attributes of objects of that type. @xref{Definition Commands}, and @ref{Data Types}. +@item @@deftypecv @var{category} @var{class} @var{data-type} @var{name} +@itemx @@deftypecvx @var{category} @var{class} @var{data-type} @var{name} +Format a description for a typed class variable in object-oriented programming. +@xref{Definition Commands}, and @ref{Abstract Objects}. + @item @@deftypefn @var{classification} @var{data-type} @var{name} @var{arguments}@dots{} @itemx @@deftypefnx @var{classification} @var{data-type} @var{name} @var{arguments}@dots{} Format a description for a function or similar entity that may take @@ -15898,6 +17072,10 @@ Format a unit of measure, as in 12@dmn{pt}. Causes @TeX{} to insert a thin space before @var{dimension}. No effect in Info. @xref{dmn, , @code{@@dmn}}. +@item @@docbook +Enter Docbook completely. Pair with @code{@@end docbook}. @xref{Raw +Formatter Commands}. + @item @@documentdescription Set the document description text, included in the HTML output. Pair with @code{@@end documentdescription}. @xref{documentdescription,, @@ -15950,6 +17128,10 @@ Optionally, start list with @var{number-or-letter}. Pair with Indicate to the reader the exact equivalence of two forms with a glyph: @samp{@equiv{}}. @xref{Equivalence}.@refill +@item @@euro@{@} +Generate the Euro currency sign. +@xref{euro,,@code{@@euro@{@}}}. + @item @@error@{@} Indicate to the reader with a glyph that the following text is an error message: @samp{@error{}}. @xref{Error Glyph}.@refill @@ -15998,6 +17180,10 @@ over-wide lines. @xref{Overfull hboxes}.@refill Add @var{entry} to the index of functions. @xref{Index Entries, , Defining the Entries of an Index}.@refill +@item @@float +Environment to define floating material. Pair with @code{@@end float}. +@xref{Floats}. + @item @@flushleft @itemx @@flushright Left justify every line but leave the right end ragged. @@ -16064,15 +17250,17 @@ between @code{@@ifclear @var{flag}} and the following @code{@@end ifclear} command. @xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill -@item @@ifhtml +@item @@ifdocbook +@itemx @@ifhtml @itemx @@ifinfo -Begin a stretch of text that will be ignored by @TeX{} when it typesets -the printed manual. @code{@@ifhtml} text appears only in the HTML -output. @code{@@ifinfo} output appears in both Info and (for historical -compatibility) plain text output . Pair with @code{@@end ifhtml} -resp.@: @code{@@end ifinfo}. @xref{Conditionals}. +Begin text that will appear only in the given output format. +@code{@@ifinfo} output appears in both Info and (for historical +compatibility) plain text output. Pair with @code{@@end ifdocbook} +resp.@: @code{@@end ifhtml} resp.@: @code{@@end ifinfo}. +@xref{Conditionals}. -@item @@ifnothtml +@item @@ifnotdocbook +@itemx @@ifnothtml @itemx @@ifnotinfo @itemx @@ifnotplaintext @itemx @@ifnottex @@ -16085,7 +17273,7 @@ well as Info output. Pair with the corresponding @code{@@end ifnot@var{format}}. @xref{Conditionals}. @item @@ifplaintext -Begin a stretch of text that appears only in the plain text output. +Begin text that will appear only in the plain text output. Pair with @code{@@end ifplaintext}. @xref{Conditionals}. @item @@ifset @var{flag} @@ -16095,18 +17283,17 @@ command. @xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill @item @@iftex -Begin a stretch of text that will not appear in the Info file, but +Begin text that will not appear in the Info file or other output, but will be processed only by @TeX{}. Pair with @code{@@end iftex}. @xref{Conditionals, , Conditionally Visible Text}.@refill @item @@ifxml -Begin a stretch of text that appears only in the XML output. -Pair with @code{@@end ifxml}. @xref{Conditionals}. +Begin text that will appear only in the XML output. Pair with +@code{@@end ifxml}. @xref{Conditionals}. @item @@ignore -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 +Begin text that will not appear in any output. Pair with @code{@@end +ignore}. @xref{Comments, , Comments and Ignored Text}. @item @@image@{@var{filename}, [@var{width}], [@var{height}], [@var{alt}], [@var{ext}]@} Include graphics image in external @var{filename} scaled to the given @@ -16117,6 +17304,10 @@ Include graphics image in external @var{filename} scaled to the given Incorporate the contents of the file @var{filename} into the Info file or printed document. @xref{Include Files}.@refill +@item @@indicateurl@{@var{indicateurl}@} +Indicate text that is a uniform resource locator for the World Wide +Web. @xref{indicateurl, , @code{@@indicateurl}}. + @item @@inforef@{@var{node-name}, [@var{entry-name}], @var{info-file-name}@} Make a cross reference to an Info file for which there is no printed manual. @xref{inforef, , Cross references using @@ -16166,17 +17357,17 @@ Add @var{entry} to the index of keys. Generate the uppercase and lowercase Polish suppressed-L letters, respectively: @L{}, @l{}. -@c Possibly this can be tossed now that we have macros. --karl, 16sep96. -@c Yes, let's toss it, it's pretty weird. --karl, 15jun97. -@c @item @@global@@let@var{new-command}=@var{existing-command} -@c Equate a new highlighting command with an existing one. Only for -@c @TeX{}. Write definition inside of @code{@@iftex} @dots{} @code{@@end -@c iftex}. @xref{Customized Highlighting}.@refill +@item @@LaTeX@{@} +Insert the logo @LaTeX{}. @xref{tex, , @TeX{} and @LaTeX{}}. @item @@lisp Begin an example of Lisp code. Indent text, do not fill, and select fixed-width font. Pair with @code{@@end lisp}. @xref{lisp, , @code{@@lisp}}. +@item @@listoffloats +Produce a table-of-contents-like listing of @code{@@float}s. +@xref{listoffloats}. + @item @@lowersections Change subsequent chapters to sections, sections to subsections, and so on. @xref{Raise/lower sections, , @code{@@raisesections} and @@ -16190,8 +17381,7 @@ Macros}. @item @@majorheading @var{title} Print a chapter-like heading in the text, but not in the table of contents of a printed manual. Generate more vertical whitespace before -the heading than the @code{@@chapheading} command. In Info, the chapter -heading line is underlined with asterisks. @xref{majorheading & +the heading than the @code{@@chapheading} command. @xref{majorheading & chapheading, , @code{@@majorheading} and @code{@@chapheading}}.@refill @item @@math@{@var{mathematical-expression}@} @@ -16292,7 +17482,7 @@ Generate an upside-down question mark. @xref{Inserting Accents}. @item @@quotation Narrow the margins to indicate text that is quoted from another real -or imaginary work. Write command on a line of its own. Pair with +or imaginary work. Takes optional argument of prefix text. Pair with @code{@@end quotation}. @xref{quotation, , @code{@@quotation}}.@refill @@ -16311,10 +17501,14 @@ with a `See'. Follow command with a punctuation mark. Only the first argument is mandatory. @xref{ref, , @code{@@ref}}.@refill @item @@refill -In Info, refill and indent the paragraph after all the other processing -has been done. No effect on @TeX{}, which always refills. This command -is no longer needed, since all formatters now automatically refill. -@xref{Refilling Paragraphs}.@refill +This command used to refill and indent the paragraph after all the +other processing has been done. It is no longer needed, since all +formatters now automatically refill as needed, but you may still see +it in the source to some manuals, as it does no harm. + +@item @@registeredsymbol@{@} +Generate the legal symbol @registeredsymbol{}. @xref{registered +symbol,, @code{@@registeredsymbol@{@}}}. @item @@result@{@} Indicate the result of an expression to the reader with a special @@ -16329,6 +17523,10 @@ Highlight @var{text} that is a literal example of a sequence of characters. Used for single characters, for statements, and often for entire shell commands. @xref{samp, , @code{@@samp}}.@refill +@item @@sansserif@{@var{text}@} +Print @var{text} in a @sansserif{sans serif} font if possible. No +effect in Info. @xref{Fonts}. + @item @@sc@{@var{text}@} Set @var{text} in a printed output in @sc{the small caps font} and set text in the Info file in uppercase letters. @@ -16371,6 +17569,9 @@ Provide a title for page headers in a printed manual, and the default document description for HTML @samp{<head>}. @xref{settitle, , @code{@@settitle}}.@refill +@item @@shortcaption +Define the short caption for a @code{@@float}. @xref{caption shortcaption}. + @item @@shortcontents Print a short table of contents. Not relevant to Info, which uses menus rather than tables of contents. A synonym for @@ -16380,6 +17581,10 @@ Contents}.@refill @item @@shorttitlepage @var{title} Generate a minimal title page. @xref{titlepage,,@code{@@titlepage}}. +@item @@slanted@{@var{text}@} +Print @var{text} in a @slanted{slanted} font if possible. No effect +in Info. @xref{Fonts}. + @item @@smallbook Cause @TeX{} to produce a printed manual in a 7 by 9.25 inch format rather than the regular 8.5 by 11 inch format. @xref{smallbook, , @@ -16479,8 +17684,7 @@ Also see @ref{ftable vtable, , @code{@@ftable} and @code{@@vtable}}, and @ref{itemx, , @code{@@itemx}}.@refill @item @@TeX@{@} -Insert the logo @TeX{}. @xref{TeX and copyright, , Inserting @TeX{} -and @copyright{}}.@refill +Insert the logo @TeX{}. @xref{tex, , @TeX{} and @LaTeX{}}. @item @@tex Enter @TeX{} completely. Pair with @code{@@end tex}. @xref{Raw @@ -16578,12 +17782,9 @@ manual. In Info, the title is underlined with periods. @xref{subsubsection, , The `subsub' Commands}.@refill @item @@uref@{@var{url}[, @var{displayed-text}][, @var{replacement}@} +@itemx @@url@{@var{url}[, @var{displayed-text}][, @var{replacement}@} Define a cross reference to an external uniform resource locator for the -World Wide Web. @xref{uref, , @code{@@uref}}.@refill - -@item @@url@{@var{url}@} -Indicate text that is a uniform resource locator for the World Wide -Web. @xref{url, , @code{@@url}}.@refill +World Wide Web. @xref{uref, , @code{@@uref}}. @item @@v@{@var{c}@} Generate check accent over the character @var{c}, as in @v{o}. @@ -16631,10 +17832,13 @@ index of variables. Pair with @code{@@end vtable}. The same as @code{@@ftable} and @code{@@vtable}}.@refill @item @@w@{@var{text}@} -Prevent @var{text} from being split across two lines. Do not end a -paragraph that uses @code{@@w} with an @code{@@refill} command. +Prevent @var{text} from being split across two lines. @xref{w, , @code{@@w}}.@refill +@item @@xml +Enter XML completely. Pair with @code{@@end xml}. @xref{Raw +Formatter Commands}. + @item @@xref@{@var{node-name}, [@var{entry}], [@var{topic-or-title}], [@var{info-file}], [@var{manual}]@} Make a reference that starts with `See' in a printed manual. Follow command with a punctuation mark. Only the first argument is @@ -16642,6 +17846,72 @@ mandatory. @xref{xref, , @code{@@xref}}.@refill @end table +@node Command Syntax +@section @@-Command Syntax +@cindex @@-command syntax +@cindex Syntax, of @@-commands +@cindex Command syntax + +The character @samp{@@} is used to start special Texinfo commands. +(It has the same meaning that @samp{\} has in plain @TeX{}.) Texinfo +has four types of @@-command:@refill + +@table @asis +@item 1. Non-alphabetic commands. +These commands consist of an @@ followed by a punctuation mark or other +character that is not part of the alphabet. Non-alphabetic commands are +almost always part of the text within a paragraph, and never take any +argument. The two characters (@@ and the other one) are complete in +themselves; none is followed by braces. The non-alphabetic commands +are: @code{@@.}, @code{@@:}, @code{@@*}, @code{@@@kbd{SPACE}}, +@code{@@@kbd{TAB}}, @code{@@@kbd{NL}}, @code{@@@@}, @code{@@@{}, and +@code{@@@}}.@refill + +@item 2. Alphabetic commands that do not require arguments. +These commands start with @@ followed by a word followed by left- and +right-hand braces. These commands insert special symbols in the +document; they do not require arguments. For example, +@code{@@dots@{@}} @result{} @samp{@dots{}}, @code{@@equiv@{@}} +@result{} @samp{@equiv{}}, @code{@@TeX@{@}} @result{} `@TeX{}', +and @code{@@bullet@{@}} @result{} @samp{@bullet{}}.@refill + +@item 3. Alphabetic commands that require arguments within braces. +These commands start with @@ followed by a letter or a word, followed by an +argument within braces. For example, the command @code{@@dfn} indicates +the introductory or defining use of a term; it is used as follows: @samp{In +Texinfo, @@@@-commands are @@dfn@{mark-up@} commands.}@refill + +@item 4. Alphabetic commands that occupy an entire line. +These commands occupy an entire line. The line starts with @@, +followed by the name of the command (a word); for example, @code{@@center} +or @code{@@cindex}. If no argument is needed, the word is followed by +the end of the line. If there is an argument, it is separated from +the command name by a space. Braces are not used.@refill +@end table + +@cindex Braces and argument syntax +Thus, the alphabetic commands fall into classes that have +different argument syntaxes. You cannot tell to which class a command +belongs by the appearance of its name, but you can tell by the +command's meaning: if the command stands for a glyph, it is in +class 2 and does not require an argument; if it makes sense to use the +command together with other text as part of a paragraph, the command +is in class 3 and must be followed by an argument in braces; +otherwise, it is in class 4 and uses the rest of the line as its +argument.@refill + +The purpose of having a different syntax for commands of classes 3 and +4 is to make Texinfo files easier to read, and also to help the GNU +Emacs paragraph and filling commands work properly. There is only one +exception to this rule: the command @code{@@refill}, which is always +used at the end of a paragraph immediately following the final period +or other punctuation character. @code{@@refill} takes no argument and +does @emph{not} require braces. @code{@@refill} never confuses the +Emacs paragraph commands because it cannot appear at the beginning of +a line. It is also no longer needed, since all formatters now refill +paragraphs automatically. + + @node Tips @appendix Tips and Hints @@ -16840,7 +18110,8 @@ typeset the name according to the wishes of Donald Knuth, who wrote @subsubheading Spaces Do not use spaces to format a Texinfo file, except inside of -@code{@@example} @dots{} @code{@@end example} and similar commands. +@code{@@example} @dots{} @code{@@end example} and other literal +environments and commands. @need 700 For example, @TeX{} fills the following: @@ -16867,17 +18138,18 @@ so it looks like this: corresponding to the current buffer. @end quotation @end iftex -@ifinfo +@ifnottex @quotation `C-x v' `M-x vc-next-action' Perform the next logical operation on the version-controlled file corresponding to the current buffer. @end quotation -@end ifinfo +@end ifnottex @noindent In this case, the text should be formatted with @code{@@table}, @code{@@item}, and @code{@@itemx}, to create a table. + @subsubheading @@code, @@samp, @@var, and @samp{---} @itemize @bullet @@ -17090,7 +18362,7 @@ it for a printed manual. @@copying This is a short example of a complete Texinfo file. -Copyright (C) 2003 Free Software Foundation, Inc. +Copyright (C) 2004 Free Software Foundation, Inc. @@end copying @@titlepage @@ -17170,22 +18442,25 @@ Here are some notes on the example: @itemize @bullet @item -@cindex $Id: -@cindex CVS $Id: -@cindex RCS $Id: +@cindex $Id +@cindex CVS $Id +@cindex RCS $Id @cindex Documentation identification @cindex Identification of documentation The @samp{$Id:} comment is for the CVS (@pxref{Top,, Overview, cvs, Concurrent Versions System}) or RCS (see rcsintro(1)) version control systems, which expand it into a string such as: @example -$Id: texinfo.txi,v 1.48 2003/06/02 12:32:28 karl Exp $ +$Id: texinfo.txi,v 1.128 2004/12/29 15:06:41 karl Exp $ @end example (This is useful in all sources that use version control, not just manuals.) You may wish to include the @samp{$Id:} comment in the @code{@@copying} text, if you want a completely unambiguous reference to the documentation version. +If you want to literally write @t{@w{$}Id$}, use @code{@@w}: +@code{@@w@{$@}Id$}. + @item @pindex automake@r{, and version info} @vindex UPDATED @r{Automake variable} @@ -17242,7 +18517,7 @@ Here is the sample document: @verbatim \input texinfo @c -*-texinfo-*- -@comment $Id: texinfo.txi,v 1.48 2003/06/02 12:32:28 karl Exp $ +@comment $Id: texinfo.txi,v 1.128 2004/12/29 15:06:41 karl Exp $ @comment %**start of header @setfilename sample.info @include version.texi @@ -17254,7 +18529,7 @@ This manual is for GNU Sample (version @value{VERSION}, @value{UPDATED}), which is an example in the Texinfo documentation. -Copyright @copyright{} 2003 Free Software Foundation, Inc. +Copyright @copyright{} 2004 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -17353,7 +18628,7 @@ see the previous sections. @copying This document is a sample for allowing verbatim copying only. -Copyright @copyright{} 2003 Free Software Foundation, Inc. +Copyright @copyright{} 2004 Free Software Foundation, Inc. @quotation Permission is granted to make and distribute verbatim copies @@ -17384,7 +18659,7 @@ the license text itself. For a complete sample document, see the previous sections. @example -Copyright @copyright{} 2003 Free Software Foundation, Inc. +Copyright @copyright{} 2004 Free Software Foundation, Inc. Copying and distribution of this file, with or without modification, are permitted in any medium without royalty provided the copyright @@ -17408,12 +18683,12 @@ conveniently small parts. @menu * Using Include Files:: How to use the @code{@@include} command. * texinfo-multiple-files-update:: How to create and update nodes and - menus when using included files. -* Include Files Requirements:: What @code{texinfo-multiple-files-update} expects. + menus when using included files. +* Include Files Requirements:: @code{texinfo-multiple-files-update} needs. * Sample Include File:: A sample outer file with included files - within it; and a sample included file. + within it; and a sample included file. * Include Files Evolution:: How use of the @code{@@include} command - has changed over time. + has changed over time. @end menu @node Using Include Files @@ -17462,6 +18737,13 @@ whole file. Either you must insert the menus and the `Next', Texinfo mode command, @code{texinfo-multiple-files-update}, that is designed for @code{@@include} files.@refill +When an included file does not have any node lines in it, the +multiple files update command does not try to create a menu entry +for it. Consequently, you can include any file, such as a +version or an update file without node lines, not just files that +are chapters. Small includable files like this are created by +Automake (@pxref{GNU Sample Texts}). + @node texinfo-multiple-files-update @section @code{texinfo-multiple-files-update} @@ -17692,10 +18974,8 @@ not paginated.)@refill * Custom Headings:: How to create your own headings and footings. @end menu -@node Headings Introduced, Heading Format, Headings, Headings -@ifinfo -@heading Headings Introduced -@end ifinfo +@node Headings Introduced +@section Headings Introduced Texinfo provides standard page heading formats for manuals that are printed on one side of each sheet of paper and for manuals that are @@ -17729,7 +19009,7 @@ blank. Text for the left part of a header or footer line is set flushleft; text for the middle part is centered; and, text for the right part is set flushright.@refill -@node Heading Format, Heading Choice, Headings Introduced, Headings +@node Heading Format @comment node-name, next, previous, up @section Standard Heading Formats @@ -17757,7 +19037,6 @@ A single-sided page looks like this: | Start of text ... | | ... | | | - @end group @end example @@ -17789,7 +19068,6 @@ Two pages, side by side as in an open book, look like this:@refill | Start of text ... | | More text ... | | ... | | ... | | | | | - @end group @end example @@ -17798,7 +19076,7 @@ The chapter name is preceded by the word ``Chapter'', the chapter number and a colon. This makes it easier to keep track of where you are in the manual.@refill -@node Heading Choice, Custom Headings, Heading Format, Headings +@node Heading Choice @comment node-name, next, previous, up @section Specifying the Type of Heading @@ -17835,7 +19113,7 @@ Specify the double-sided heading format, with chapters on new pages.@refill @noindent Texinfo lacks an @code{@@setchapternewpage even} command.@refill -@node Custom Headings, , Heading Choice, Headings +@node Custom Headings @comment node-name, next, previous, up @section How to Make Your Own Headings @@ -17907,7 +19185,6 @@ headers or footers.@refill @findex oddfooting @item @@evenheading @var{left} @@| @var{center} @@| @var{right} @itemx @@oddheading @var{left} @@| @var{center} @@| @var{right} - @itemx @@evenfooting @var{left} @@| @var{center} @@| @var{right} @itemx @@oddfooting @var{left} @@| @var{center} @@| @var{right} @@ -18016,10 +19293,9 @@ command and you can use the @kbd{M-x Info-validate} command.@refill * Running Info-Validate:: How to find badly referenced nodes. @end menu -@node makeinfo Preferred, Debugging with Info, Catching Mistakes, Catching Mistakes -@ifinfo -@heading @code{makeinfo} Find Errors -@end ifinfo + +@node makeinfo Preferred +@section @code{makeinfo} Find Errors The @code{makeinfo} program does an excellent job of catching errors and reporting them---far better than @code{texinfo-format-region} or @@ -18035,7 +19311,7 @@ errors. This is the best way to work with Texinfo. But if you cannot use @code{makeinfo}, or your problem is very puzzling, then you may want to use the tools described in this appendix.@refill -@node Debugging with Info, Debugging with TeX, makeinfo Preferred, Catching Mistakes +@node Debugging with Info @comment node-name, next, previous, up @section Catching Errors with Info Formatting @cindex Catching errors with Info formatting @@ -18222,7 +19498,7 @@ not find the missing right-hand brace.@refill Manual}, for more information.@refill @end ignore -@node Debugging with TeX, Using texinfo-show-structure, Debugging with Info, Catching Mistakes +@node Debugging with TeX @comment node-name, next, previous, up @section Catching Errors with @TeX{} Formatting @cindex Catching errors with @TeX{} formatting @@ -18351,7 +19627,7 @@ again. (Note the use of the backslash, @samp{\}. @TeX{} uses @samp{\} instead of @samp{@@}; and in this circumstance, you are working directly with @TeX{}, not with Texinfo.)@refill -@node Using texinfo-show-structure, Using occur, Debugging with TeX, Catching Mistakes +@node Using texinfo-show-structure @comment node-name, next, previous, up @section Using @code{texinfo-show-structure} @cindex Showing the structure of a file @@ -18423,7 +19699,7 @@ You can remind yourself of the structure of a Texinfo file by looking at the list in the @samp{*Occur*} window; and if you have mis-named a node or left out a section, you can correct the mistake.@refill -@node Using occur, Running Info-Validate, Using texinfo-show-structure, Catching Mistakes +@node Using occur @comment node-name, next, previous, up @section Using @code{occur} @cindex Occurrences, listing with @code{@@occur} @@ -18463,7 +19739,7 @@ therefore have the same `Up' pointer.@refill @xref{Other Repeating Search, , Using Occur, emacs , The GNU Emacs Manual}, for more information.@refill -@node Running Info-Validate, , Using occur, Catching Mistakes +@node Running Info-Validate @comment node-name, next, previous, up @section Finding Badly Referenced Nodes @findex Info-validate @@ -18493,7 +19769,7 @@ if you write an Info file from scratch.@refill * Splitting:: How to split a file manually. @end menu -@node Using Info-validate, Unsplit, Running Info-Validate, Running Info-Validate +@node Using Info-validate @subsection Running @code{Info-validate} @cindex Running @code{Info-validate} @cindex Info validating a large file @@ -18550,7 +19826,7 @@ on a large file, you must run @code{texinfo-format-buffer} with an argument so that it does not split the Info file; and you must create a tag table for the unsplit file. -@node Unsplit, Tagifying, Using Info-validate, Running Info-Validate +@node Unsplit @comment node-name, next, previous, up @subsection Creating an Unsplit File @cindex Creating an unsplit file @@ -18588,7 +19864,7 @@ a tag table for it. @refill @cindex Making a tag table manually @cindex Tag table, making manually -@node Tagifying, Splitting, Unsplit, Running Info-Validate +@node Tagifying @subsection Tagifying a File After creating an unsplit Info file, you must create a tag table for @@ -18625,7 +19901,7 @@ After you have validated the node structure, you can rerun tag table and split the file automatically, or you can make the tag table and split the file manually.@refill -@node Splitting, , Tagifying, Running Info-Validate +@node Splitting @comment node-name, next, previous, up @subsection Splitting a File Manually @cindex Splitting an Info file manually @@ -18677,6 +19953,10 @@ The primary file still functions as an Info file, but it contains just the tag table and a directory of subfiles.@refill +@ignore +The simple description in the command summary seems sufficient to me +these days, so ignore this appendix. --karl, 13mar04. + @node Refilling Paragraphs @appendix Refilling Paragraphs @cindex Refilling paragraphs @@ -18716,114 +19996,7 @@ paragraph that should be filled. They do not append @code{@@refill} to the ends of paragraphs that contain @code{@@*} or @w{@code{@@w@{ @dots{}@}}} and therefore do not refill or indent them.@refill - -@node Command Syntax -@appendix @@-Command Syntax -@cindex @@-command syntax -@cindex Syntax, of @@-commands -@cindex Command syntax - -The character @samp{@@} is used to start special Texinfo commands. -(It has the same meaning that @samp{\} has in plain @TeX{}.) Texinfo -has four types of @@-command:@refill - -@table @asis -@item 1. Non-alphabetic commands. -These commands consist of an @@ followed by a punctuation mark or other -character that is not part of the alphabet. Non-alphabetic commands are -almost always part of the text within a paragraph, and never take any -argument. The two characters (@@ and the other one) are complete in -themselves; none is followed by braces. The non-alphabetic commands -are: @code{@@.}, @code{@@:}, @code{@@*}, @code{@@@kbd{SPACE}}, -@code{@@@kbd{TAB}}, @code{@@@kbd{NL}}, @code{@@@@}, @code{@@@{}, and -@code{@@@}}.@refill - -@item 2. Alphabetic commands that do not require arguments. -These commands start with @@ followed by a word followed by left- and -right-hand braces. These commands insert special symbols in the -document; they do not require arguments. For example, -@code{@@dots@{@}} @result{} @samp{@dots{}}, @code{@@equiv@{@}} -@result{} @samp{@equiv{}}, @code{@@TeX@{@}} @result{} `@TeX{}', -and @code{@@bullet@{@}} @result{} @samp{@bullet{}}.@refill - -@item 3. Alphabetic commands that require arguments within braces. -These commands start with @@ followed by a letter or a word, followed by an -argument within braces. For example, the command @code{@@dfn} indicates -the introductory or defining use of a term; it is used as follows: @samp{In -Texinfo, @@@@-commands are @@dfn@{mark-up@} commands.}@refill - -@item 4. Alphabetic commands that occupy an entire line. -These commands occupy an entire line. The line starts with @@, -followed by the name of the command (a word); for example, @code{@@center} -or @code{@@cindex}. If no argument is needed, the word is followed by -the end of the line. If there is an argument, it is separated from -the command name by a space. Braces are not used.@refill -@end table - -@cindex Braces and argument syntax -Thus, the alphabetic commands fall into classes that have -different argument syntaxes. You cannot tell to which class a command -belongs by the appearance of its name, but you can tell by the -command's meaning: if the command stands for a glyph, it is in -class 2 and does not require an argument; if it makes sense to use the -command together with other text as part of a paragraph, the command -is in class 3 and must be followed by an argument in braces; -otherwise, it is in class 4 and uses the rest of the line as its -argument.@refill - -The purpose of having a different syntax for commands of classes 3 and -4 is to make Texinfo files easier to read, and also to help the GNU -Emacs paragraph and filling commands work properly. There is only one -exception to this rule: the command @code{@@refill}, which is always -used at the end of a paragraph immediately following the final period -or other punctuation character. @code{@@refill} takes no argument and -does @emph{not} require braces. @code{@@refill} never confuses the -Emacs paragraph commands because it cannot appear at the beginning of -a line.@refill - - -@node Obtaining TeX -@appendix How to Obtain @TeX{} -@cindex Obtaining @TeX{} -@cindex @TeX{}, how to obtain - -@c !!! Here is information about obtaining TeX. Update it whenever. -@c !!! Also consider updating TeX.README on ftp.gnu.org. -@c Updated by RJC on 1 March 1995, conversation with MacKay. -@c Updated by kb@cs.umb.edu on 29 July 1996. -@c Updated by kb@cs.umb.edu on 25 April 1997. -@c Updated by kb@cs.umb.edu on 27 February 1998. -@TeX{} is freely redistributable. You can obtain @TeX{} for Unix -systems via anonymous ftp or on physical media. The core material -consists of the Web2c @TeX{} distribution (@uref{http://tug.org/web2c}). - -Instructions for retrieval by anonymous ftp and information on other -available distributions: -@example -@uref{ftp://tug.org/tex/unixtex.ftp} -@uref{http://tug.org/unixtex.ftp} -@end example - -The Free Software Foundation provides a core distribution on its Source -Code CD-ROM suitable for printing Texinfo manuals. To order it, contact: - -@display -@group -Free Software Foundation, Inc. -59 Temple Place Suite 330 -Boston, MA @ @ 02111-1307 -USA -Telephone: @w{+1-617-542-5942} -Fax: (including Japan) @w{+1-617-542-2652} -Free Dial Fax (in Japan): -@w{ } @w{ } @w{ } 0031-13-2473 (KDD) -@w{ } @w{ } @w{ } 0066-3382-0158 (IDC) -Electronic mail: @code{gnu@@gnu.org} -@end group -@end display - -Many other @TeX{} distributions are available; see -@uref{http://tug.org/}. +@end ignore @c These are no longer ``new'', and the explanations @@ -18970,16 +20143,10 @@ Kill the @code{makeinfo} formatting job. @c subheading Typeset and Print @noindent -Typeset and print Texinfo documents from within Emacs.@refill +Typeset and print Texinfo documents from within Emacs. -@ifinfo @noindent @xref{Printing}. -@end ifinfo -@iftex -@noindent -@xref{Printing, , Formatting and Printing}. -@end iftex @table @kbd @item C-c C-t C-b @@ -19157,7 +20324,7 @@ Format blocks of text. @table @kbd @item @@cartouche -Draw rounded box surrounding text (not in Info). +Draw rounded box surrounding text (no effect in Info). @item @@enumerate @var{optional-arg} Enumerate a list with letters or numbers. |
