This is texinfo.info, produced by texi2any version 6.0 from texinfo.texi. This manual is for GNU Texinfo (version 6.0, 26 June 2015), a documentation system that can produce both online information and a printed manual from a single source using semantic markup. Copyright (C) 1988, 1990, 1991, 1992, 1993, 1995, 1996, 1997, 1998, 1999, 2001, 2001, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2015 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover Texts being "A GNU Manual", and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled "GNU Free Documentation License". (a) The FSF's Back-Cover Text is: "You have the freedom to copy and modify this GNU manual. Buying copies from the FSF supports it in developing GNU and promoting software freedom." INFO-DIR-SECTION Texinfo documentation system START-INFO-DIR-ENTRY * Texinfo: (texinfo). The GNU documentation format. * install-info: (texinfo)Invoking install-info. Update info/dir entries. * makeinfo: (texinfo)Invoking makeinfo. Translate Texinfo source. * pod2texi: (pod2texi)Invoking pod2texi. Translate Perl POD to Texinfo. * texi2dvi: (texinfo)Format with texi2dvi. Print Texinfo documents. * texi2pdf: (texinfo)PDF Output. PDF output for Texinfo. * pdftexi2dvi: (texinfo)PDF Output. PDF output for Texinfo. * texindex: (texinfo)Format with tex/texindex. Sort Texinfo index files. END-INFO-DIR-ENTRY  File: texinfo.info, Node: Batch Formatting, Next: Tag and Split Files, Prev: texinfo-format commands, Up: Creating an Info File 23.1.4 Batch Formatting ----------------------- You can format Texinfo files for Info using 'batch-texinfo-format' and Emacs batch mode. You can run Emacs in batch mode from any shell, including a shell inside of Emacs. (*Note (emacs)Initial Options::.) Here is a shell command to format all the files that end in '.texinfo' in the current directory: emacs -batch -funcall batch-texinfo-format *.texinfo Emacs processes all the files listed on the command line, even if an error occurs while attempting to format some of them. Run 'batch-texinfo-format' only with Emacs in batch mode as shown; it is not interactive. It kills the batch mode Emacs on completion. 'batch-texinfo-format' is convenient if you lack 'makeinfo' and want to format several Texinfo files at once. When you use Batch mode, you create a new Emacs process. This frees your current Emacs, so you can continue working in it. (When you run 'texinfo-format-region' or 'texinfo-format-buffer', you cannot use that Emacs for anything else until the command finishes.)  File: texinfo.info, Node: Tag and Split Files, Prev: Batch Formatting, Up: Creating an Info File 23.1.5 Tag Files and Split Files -------------------------------- If a Texinfo file has more than 30,000 bytes, 'texinfo-format-buffer' automatically creates a tag table for its Info file; 'makeinfo' always creates a tag table. With a "tag table", Info can jump to new nodes more quickly than it can otherwise. In addition, if the Texinfo file contains more than about 300,000 bytes, 'texinfo-format-buffer' and 'makeinfo' split the large Info file into shorter "indirect" subfiles of about 300,000 bytes each. Big files are split into smaller files so that Emacs does not need to make a large buffer to hold the whole of a large Info file; instead, Emacs allocates just enough memory for the small, split-off file that is needed at the time. This way, Emacs avoids wasting memory when you run Info. (Before splitting was implemented, Info files were always kept short and "include files" were designed as a way to create a single, large printed manual out of the smaller Info files. *Note Include Files::, for more information. Include files are still used for very large documents, such as 'The Emacs Lisp Reference Manual', in which each chapter is a separate file.) When a file is split, Info itself makes use of a shortened version of the original file that contains just the tag table and references to the files that were split off. The split-off files are called "indirect" files. The split-off files have names that are created by appending '-1', '-2', '-3' and so on to the file name specified by the '@setfilename' command. The shortened version of the original file continues to have the name specified by '@setfilename'. At one stage in writing this document, for example, the Info file was saved as the file 'test-texinfo' and that file looked like this: Info file: test-texinfo, -*-Text-*- produced by texinfo-format-buffer from file: new-texinfo-manual.texinfo ^_ Indirect: test-texinfo-1: 102 test-texinfo-2: 50422 test-texinfo-3: 101300 ^_^L Tag table: (Indirect) Node: overview^?104 Node: info file^?1271 Node: printed manual^?4853 Node: conventions^?6855 ... (But 'test-texinfo' had far more nodes than are shown here.) Each of the split-off, indirect files, 'test-texinfo-1', 'test-texinfo-2', and 'test-texinfo-3', is listed in this file after the line that says 'Indirect:'. The tag table is listed after the line that says 'Tag table:'. In the list of indirect files, the number following the file name records the cumulative number of bytes in the preceding indirect files, not counting the file list itself, the tag table, or any permissions text in the first file. In the tag table, the number following the node name records the location of the beginning of the node, in bytes from the beginning of the (unsplit) output. If you are using 'texinfo-format-buffer' to create Info files, you may want to run the 'Info-validate' command. (The 'makeinfo' command does such a good job on its own, you do not need 'Info-validate'.) However, you cannot run the 'M-x Info-validate' node-checking command on indirect files. For information on how to prevent files from being split and how to validate the structure of the nodes, see *note Using Info-validate::.  File: texinfo.info, Node: Installing an Info File, Prev: Creating an Info File, Up: Creating and Installing Info Files 23.2 Installing an Info File ============================ Info files are usually kept in the 'info' directory. You can read Info files using the standalone Info program or the Info reader built into Emacs. (*Note (info)Top::, for an introduction to Info.) * Menu: * Directory File:: The top level menu for all Info files. * New Info File:: Listing a new Info file. * Other Info Directories:: How to specify Info files that are located in other directories. * Installing Dir Entries:: How to specify what menu entry to add to the Info directory. * Invoking install-info:: 'install-info' options.  File: texinfo.info, Node: Directory File, Next: New Info File, Up: Installing an Info File 23.2.1 The Directory File 'dir' ------------------------------- For Info to work, the 'info' directory must contain a file that serves as a top level directory for the Info system. By convention, this file is called 'dir'. (You can find the location of this file within Emacs by typing 'C-h i' to enter Info and then typing 'C-x C-f' to see the pathname to the 'info' directory.) The 'dir' file is itself an Info file. It contains the top level menu for all the Info files in the system. The menu looks like this: * Menu: * Info: (info). Documentation browsing system. * Emacs: (emacs). The extensible, self-documenting text editor. * Texinfo: (texinfo). With one source file, make either a printed manual using @TeX{} or an Info file. ... Each of these menu entries points to the 'Top' node of the Info file that is named in parentheses. (The menu entry does not need to specify the 'Top' node, since Info goes to the 'Top' node if no node name is mentioned. *Note Nodes in Other Info Files: Other Info Files.) Thus, the 'Info' entry points to the 'Top' node of the 'info' file and the 'Emacs' entry points to the 'Top' node of the 'emacs' file. In each of the Info files, the 'Up' pointer of the 'Top' node refers back to the 'dir' file. For example, the line for the 'Top' node of the Emacs manual looks like this in Info: File: emacs Node: Top, Up: (DIR), Next: Distrib In this case, the 'dir' file name is written in uppercase letters--it can be written in either upper- or lowercase. This is not true in general, it is a special case for 'dir'.  File: texinfo.info, Node: New Info File, Next: Other Info Directories, Prev: Directory File, Up: Installing an Info File 23.2.2 Listing a New Info File ------------------------------ To add a new Info file to your system, you must write a menu entry to add to the menu in the 'dir' file in the 'info' directory. For example, if you were adding documentation for GDB, you would write the following new entry: * GDB: (gdb). The source-level C debugger. The first part of the menu entry is the menu entry name, followed by a colon. The second part is the name of the Info file, in parentheses, followed by a period. The third part is the description. The name of an Info file often has a '.info' extension. Thus, the Info file for GDB might be called either 'gdb' or 'gdb.info'. The Info reader programs automatically try the file name both with and without '.info'(1); so it is better to avoid clutter and not to write '.info' explicitly in the menu entry. For example, the GDB menu entry should use just 'gdb' for the file name, not 'gdb.info'. ---------- Footnotes ---------- (1) On MS-DOS/MS-Windows systems, Info will try the '.inf' extension as well.  File: texinfo.info, Node: Other Info Directories, Next: Installing Dir Entries, Prev: New Info File, Up: Installing an Info File 23.2.3 Info Files in Other Directories -------------------------------------- If an Info file is not in the 'info' directory, there are three ways to specify its location: 1. Write the pathname in the 'dir' file as the second part of the menu. 2. Specify the Info directory name in the 'INFOPATH' environment variable in your '.profile' or '.cshrc' initialization file. (Only you and others who set this environment variable will be able to find Info files whose location is specified this way.) 3. If you are using Emacs, list the name of the file in a second 'dir' file, in its directory; and then add the name of that directory to the 'Info-directory-list' variable in your personal or site initialization file. This variable tells Emacs where to look for 'dir' files (the files must be named 'dir'). Emacs merges the files named 'dir' from each of the listed directories. (In Emacs version 18, you can set the 'Info-directory' variable to the name of only one directory.) For example, to reach a test file in the '/home/bob/info' directory, you could add an entry like this to the menu in the standard 'dir' file: * Test: (/home/bob/info/info-test). Bob's own test file. In this case, the absolute file name of the 'info-test' file is written as the second part of the menu entry. If you don't want to edit the system 'dir' file, you can tell Info where to look by setting the 'INFOPATH' environment variable in your shell startup file. This works with both the Emacs and standalone Info readers. Specifically, if you use a Bourne-compatible shell such as 'sh' or 'bash' for your shell command interpreter, you set the 'INFOPATH' environment variable in the '.profile' initialization file; but if you use 'csh' or 'tcsh', you set the variable in the '.cshrc' initialization file. On MS-DOS/MS-Windows systems, you must set 'INFOPATH' in your 'autoexec.bat' file or in the registry. Each type of shell uses a different syntax. * In a '.cshrc' file, you could set the 'INFOPATH' variable as follows: setenv INFOPATH .:~/info:/usr/local/emacs/info * In a '.profile' file, you would achieve the same effect by writing: INFOPATH=.:$HOME/info:/usr/local/emacs/info export INFOPATH * In a 'autoexec.bat' file, you write this command (note the use of ';' as the directory separator, and a different syntax for using values of other environment variables): set INFOPATH=.;%HOME%/info;c:/usr/local/emacs/info The '.' indicates the current directory as usual. Emacs uses the 'INFOPATH' environment variable to initialize the value of Emacs's own 'Info-directory-list' variable. The standalone Info reader merges any files named 'dir' in any directory listed in the 'INFOPATH' variable into a single menu presented to you in the node called '(dir)Top'. However you set 'INFOPATH', if its last character is a colon (on MS-DOS/MS-Windows systems, use a semicolon instead), this is replaced by the default (compiled-in) path. This gives you a way to augment the default path with new directories without having to list all the standard places. For example (using 'sh' syntax): INFOPATH=/home/bob/info: export INFOPATH will search '/home/bob/info' first, then the standard directories. Leading or doubled colons are not treated specially. When you create your own 'dir' file for use with 'Info-directory-list' or 'INFOPATH', it's easiest to start by copying an existing 'dir' file and replace all the text after the '* Menu:' with your desired entries. That way, the punctuation and special 'CTRL-_' characters that Info needs will be present. As one final alternative, which works only with Emacs Info, you can change the 'Info-directory-list' variable. For example: (add-hook 'Info-mode-hook '(lambda () (add-to-list 'Info-directory-list (expand-file-name "~/info"))))  File: texinfo.info, Node: Installing Dir Entries, Next: Invoking install-info, Prev: Other Info Directories, Up: Installing an Info File 23.2.4 Installing Info Directory Files -------------------------------------- When you install an Info file onto your system, you can use the program 'install-info' to update the Info directory file 'dir'. Normally the makefile for the package runs 'install-info', just after copying the Info file into its proper installed location. In order for the Info file to work with 'install-info', you include the commands '@dircategory' and '@direntry'...'@end direntry' in the Texinfo source file. Use '@direntry' to specify the menu entries to add to the Info directory file, and use '@dircategory' to specify which part of the Info directory to put it in. Here is how these commands are used in this manual: @dircategory Texinfo documentation system @direntry * Texinfo: (texinfo). The GNU documentation format. * install-info: (texinfo)Invoking install-info. ... ... @end direntry Here's what this produces in the Info file: INFO-DIR-SECTION Texinfo documentation system START-INFO-DIR-ENTRY * Texinfo: (texinfo). The GNU documentation format. * install-info: (texinfo)Invoking install-info. ... ... END-INFO-DIR-ENTRY The 'install-info' program sees these lines in the Info file, and that is how it knows what to do. Always use the '@direntry' and '@dircategory' commands near the beginning of the Texinfo input, before the first '@node' command. If you use them later on in the input, 'install-info' will not notice them. 'install-info' will automatically reformat the description of the menu entries it is adding. As a matter of convention, the description of the main entry (above, 'The GNU documentation format') should start at column 32, starting at zero (as in 'what-cursor-position' in Emacs). This will make it align with most others. Description for individual utilities best start in column 48, where possible. For more information about formatting see the '--calign', '--align', and '--max-width' options in *note Invoking install-info::. If you use '@dircategory' more than once in the Texinfo source, each usage specifies the 'current' category; any subsequent '@direntry' commands will add to that category. When choosing a category name for the '@dircategory' command, we recommend consulting the Free Software Directory (http://www.gnu.org/directory). If your program is not listed there, or listed incorrectly or incompletely, please report the situation to the directory maintainers () so that the category names can be kept in sync. Here are a few examples (see the 'util/dir-example' file in the Texinfo distribution for large sample 'dir' file): Emacs Localization Printing Software development Software libraries Text creation and manipulation Each 'Invoking' node for every program installed should have a corresponding '@direntry'. This lets users easily find the documentation for the different programs they can run, as with the traditional 'man' system.  File: texinfo.info, Node: Invoking install-info, Prev: Installing Dir Entries, Up: Installing an Info File 23.2.5 Invoking 'install-info' ------------------------------ 'install-info' inserts menu entries from an Info file into the top-level 'dir' file in the Info system (see the previous sections for an explanation of how the 'dir' file works). 'install-info' also removes menu entries from the 'dir' file. It's most often run as part of software installation, or when constructing a 'dir' file for all manuals on a system. Synopsis: install-info [OPTION...] [INFO-FILE [DIR-FILE]] If INFO-FILE or DIR-FILE are not specified, the options (described below) that define them must be. There are no compile-time defaults, and standard input is never used. 'install-info' can read only one Info file and write only one 'dir' file per invocation. If DIR-FILE (however specified) does not exist, 'install-info' creates it if possible (with no entries). If any input file is compressed with 'gzip' (*note (gzip)Top::), 'install-info' automatically uncompresses it for reading. And if DIR-FILE is compressed, 'install-info' also automatically leaves it compressed after writing any changes. If DIR-FILE itself does not exist, 'install-info' tries to open 'DIR-FILE.gz', 'DIR-FILE.xz', 'DIR-FILE.bz2', 'DIR-FILE.lz', and 'DIR-FILE.lzma', in that order. Options: '--add-once' Specifies that the entry or entries will only be put into a single section. '--align=COLUMN' Specifies the column that the second and subsequent lines of menu entry's description will be formatted to begin at. The default for this option is '35'. It is used in conjunction with the '--max-width' option. COLUMN starts counting at 1. '--append-new-sections' Instead of alphabetizing new sections, place them at the end of the DIR file. '--calign=COLUMN' Specifies the column that the first line of menu entry's description will be formatted to begin at. The default for this option is '33'. It is used in conjunction with the '--max-width' option. When the name of the menu entry exceeds this column, entry's description will start on the following line. COLUMN starts counting at 1. '--debug' Report what is being done. '--delete' Delete the entries in INFO-FILE from DIR-FILE. The file name in the entry in DIR-FILE must be INFO-FILE (except for an optional '.info' in either one). Don't insert any new entries. Any empty sections that result from the removal are also removed. '--description=TEXT' Specify the explanatory portion of the menu entry. If you don't specify a description (either via '--entry', '--item' or this option), the description is taken from the Info file itself. '--dir-file=NAME' Specify file name of the Info directory file. This is equivalent to using the DIR-FILE argument. '--dry-run' Same as '--test'. '--entry=TEXT' Insert TEXT as an Info directory entry; TEXT should have the form of an Info menu item line plus zero or more extra lines starting with whitespace. If you specify more than one entry, they are all added. If you don't specify any entries, they are determined from information in the Info file itself. '--help' Display a usage message with basic usage and all available options, then exit successfully. '--info-file=FILE' Specify Info file to install in the directory. This is equivalent to using the INFO-FILE argument. '--info-dir=DIR' Specify the directory where the directory file 'dir' resides. Equivalent to '--dir-file=DIR/dir'. '--infodir=DIR' Same as '--info-dir'. '--item=TEXT' Same as '--entry=TEXT'. An Info directory entry is actually a menu item. '--keep-old' Do not replace pre-existing menu entries. When '--remove' is specified, this option means that empty sections are not removed. '--max-width=COLUMN' Specifies the column that the menu entry's description will be word-wrapped at. COLUMN starts counting at 1. '--maxwidth=COLUMN' Same as '--max-width'. '--menuentry=TEXT' Same as '--name'. '--name=TEXT' Specify the name portion of the menu entry. If the TEXT does not start with an asterisk '*', it is presumed to be the text after the '*' and before the parentheses that specify the Info file. Otherwise TEXT is taken verbatim, and is taken as defining the text up to and including the first period (a space is appended if necessary). If you don't specify the name (either via '--entry', '--item' or this option), it is taken from the Info file itself. If the Info does not contain the name, the basename of the Info file is used. '--no-indent' Suppress formatting of new entries into the 'dir' file. '--quiet' '--silent' Suppress warnings, etc., for silent operation. '--remove' Same as '--delete'. '--remove-exactly' Also like '--delete', but only entries if the Info file name matches exactly; '.info' and/or '.gz' suffixes are _not_ ignored. '--section=SEC' Put this file's entries in section SEC of the directory. If you specify more than one section, all the entries are added in each of the sections. If you don't specify any sections, they are determined from information in the Info file itself. If the Info file doesn't specify a section, the menu entries are put into the Miscellaneous section. '--section REGEX SEC' Same as '--regex=REGEX --section=SEC --add-once'. 'install-info' tries to detect when this alternate syntax is used, but does not always guess correctly. Here is the heuristic that 'install-info' uses: 1. If the second argument to '--section' starts with a hyphen, the original syntax is presumed. 2. If the second argument to '--section' is a file that can be opened, the original syntax is presumed. 3. Otherwise the alternate syntax is used. When the heuristic fails because your section title starts with a hyphen, or it happens to be a filename that can be opened, the syntax should be changed to '--regex=REGEX --section=SEC --add-once'. '--regex=REGEX' Put this file's entries into any section that matches REGEX. If more than one section matches, all of the entries are added in each of the sections. Specify REGEX using basic regular expression syntax, more or less as used with 'grep', for example. '--test' Suppress updating of the directory file. '--version' Display version information and exit successfully.  File: texinfo.info, Node: Generating HTML, Next: Command List, Prev: Creating and Installing Info Files, Up: Top 24 Generating HTML ****************** 'makeinfo' generates Info output by default, but given the '--html' option, it will generate HTML, for web browsers and other programs. This chapter gives some details on such HTML output. 'makeinfo' has many user-definable customization variables with which you can influence the HTML output. *Note Customization Variables::. 'makeinfo' can also produce output in XML and Docbook formats, but we do not as yet describe these in detail. *Note Output Formats::, for a brief overview of all the output formats. * Menu: * HTML Translation:: Details of the HTML output. * HTML Splitting:: How HTML output is split. * HTML CSS:: Influencing HTML output with Cascading Style Sheets. * HTML Xref:: Cross references in HTML output.  File: texinfo.info, Node: HTML Translation, Next: HTML Splitting, Up: Generating HTML 24.1 HTML Translation ===================== First, the HTML generated by 'makeinfo' is standard HTML 4. It also tries to be compatible with earlier standards (e.g., HTML 2.0, RFC-1866). Thus, please report output from an error-free run of 'makeinfo' which has practical browser portability problems as a bug (*note Reporting Bugs::). Some known exceptions to HTML 3.2 (using '--init-file=html32.pm' produces strict HTML 3.2 output; *note Invoking texi2any::): 1. HTML 3.2 tables are generated for the '@multitable' command (*note Multi-column Tables::), but they should degrade reasonably in browsers without table support. 2. The HTML 4 'lang' attribute on the '' attribute is used. 3. Entities that are not in the HTML 3.2 standard are also used. 4. CSS is used (*note HTML CSS::). 5. A few HTML 4 elements are used: 'thead', 'abbr', 'acronym'. To achieve maximum portability and accessibility among browsers (both graphical and text-based), systems, and users, the HTML output is intentionally quite plain and generic. It has always been our goal for users to be able to customize the output to their wishes via CSS (*note HTML CSS::) or other means (*note Customization Variables::. If you cannot accomplish a reasonable customization, feel free to report that. However, we do not wish to depart from our basic goal of widest readability for the core output. For example, using fancy CSS may make it possible for the HTML output to more closely resemble the TeX output in some details, but this result is not even close to being worth the ensuing difficulties. It is also intentionally not our goal, and not even possible, to pass through every conceivable validation test without any diagnostics. Different validation tests have different goals, often about pedantic enforcement of some standard or another. Our overriding goal is to help users, not blindly comply with standards. To repeat what was said at the top: please report output from an error-free run of 'makeinfo' which has _practical_ browser portability problems as a bug (*note Reporting Bugs::). A few other general points about the HTML output follow. *Navigation bar:* By default, a navigation bar is inserted at the start of each node, analogous to Info output. If the '--no-headers' option is used, the navigation bar is only inserted at the beginning of split files. Header '' elements in split output can support Info-like navigation with browsers like Lynx and Emacs W3 which implement this HTML 1.0 feature. *Footnotes:* for HTML, when the footnote style is 'end', or if the output is not split, footnotes are put at the end of the output. If the footnoet style is set to 'separate', and the output is split, they are placed in a separate file. *Note Footnote Styles::. *Raw HTML*: 'makeinfo' will include segments of Texinfo source between '@ifhtml' and '@end ifhtml' in the HTML output (but not any of the other conditionals, by default). Source between '@html' and '@end html' is passed without change to the output (i.e., suppressing the normal escaping of input '<', '>' and '&' characters which have special significance in HTML). *Note Conditional Commands::.  File: texinfo.info, Node: HTML Splitting, Next: HTML CSS, Prev: HTML Translation, Up: Generating HTML 24.2 HTML Splitting =================== When splitting output at nodes (which is the default), 'makeinfo' writes HTML output into (basically) one output file per Texinfo source '@node'. Each output file name is the node name with spaces replaced by '-''s and special characters changed to '_' followed by their code point in hex (*note HTML Xref::). This is to make it portable and easy to use 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 independently. If 'makeinfo' is run on a system which does not distinguish case in file names, nodes which are the same except for case (e.g., 'index' and 'Index') will also be folded into the same output file with anchors. You can also pretend to be on a case insensitive filesystem by setting the customization variable 'CASE_INSENSITIVE_FILENAMES'. It is also possible to split at chapters or sections with '--split' (*note Invoking texi2any::). In that case, the file names are constructed after the name of the node associated with the relevant sectioning command. Also, unless '--no-node-files' is specified, a redirection file is output for every node in order to more reliably support cross references to that manual (*note HTML Xref::). When splitting, the HTML output files are written into a subdirectory, with the name chosen as follows: 1. 'makeinfo' first tries the subdirectory with the base name from '@setfilename' (that is, any extension is removed). For example, HTML output for '@setfilename gcc.info' would be written into a subdirectory named 'gcc/'. 2. If that directory cannot be created for any reason, then 'makeinfo' tries appending '.html' to the directory name. For example, output for '@setfilename texinfo' would be written to 'texinfo.html/'. 3. If the 'NAME.html' directory can't be created either, 'makeinfo' gives up. In any case, the top-level output file within the directory is always named 'index.html'. Monolithic output ('--no-split') is named according to '@setfilename' (with any '.info' extension is replaced with '.html'), '--output' (the argument is used literally), or based on the input file name as a last resort (*note @setfilename::).  File: texinfo.info, Node: HTML CSS, Next: HTML Xref, Prev: HTML Splitting, Up: Generating HTML 24.3 HTML CSS ============= Cascading Style Sheets (CSS for short) is an Internet standard for influencing the display of HTML documents: see . By default, 'makeinfo' includes a few simple CSS commands to better implement the appearance of some Texinfo environments. Here are two of them, as an example: pre.display { font-family:inherit } pre.smalldisplay { font-family:inherit; font-size:smaller } A full explanation of CSS is (far) beyond this manual; please see the reference above. In brief, however, the above tells the web browser to use a 'smaller' font size for '@smalldisplay' text, and to use the same font as the main document for both '@smalldisplay' and '@display'. By default, the HTML '
' command uses a monospaced font.

  You can influence the CSS in the HTML output with two 'makeinfo'
options: '--css-include=FILE' and '--css-ref=URL'.

  The option '--css-ref=URL' adds to each output HTML file a ''
tag referencing a CSS at the given URL.  This allows using external
style sheets.  You may find the file
'texi2html/examples/texinfo-bright-colors.css' useful for visualizing
the CSS elements in Texinfo output.

  The option '--css-include=FILE' includes the contents FILE in the HTML
output, as you might expect.  However, the details are somewhat tricky,
as described in the following, to provide maximum flexibility.

  The CSS file may begin with so-called '@import' directives, which link
to external CSS specifications for browsers to use when interpreting the
document.  Again, a full description is beyond our scope here, but we'll
describe how they work syntactically, so we can explain how 'makeinfo'
handles them.

  There can be more than one '@import', but they have to come first in
the file, with only whitespace and comments interspersed, no normal
definitions.  (Technical exception: an '@charset' directive may precede
the '@import''s.  This does not alter 'makeinfo''s behavior, it just
copies the '@charset' if present.)  Comments in CSS files are delimited
by '/* ... */', as in C.  An '@import' directive must be in one of these
two forms:

     @import url(http://example.org/foo.css);
     @import "http://example.net/bar.css";

  As far as 'makeinfo' is concerned, the crucial characters are the '@'
at the beginning and the semicolon terminating the directive.  When
reading the CSS file, it simply copies any such '@'-directive into the
output, as follows:

   * If FILE contains only normal CSS declarations, it is included after
     'makeinfo''s default CSS, thus overriding it.

   * If FILE begins with '@import' specifications (see below), then the
     'import''s are included first (they have to come first, according
     to the standard), and then 'makeinfo''s default CSS is included.
     If you need to override 'makeinfo''s defaults from an '@import',
     you can do so with the '! important' CSS construct, as in:
          pre.smallexample { font-size: inherit ! important }

   * If FILE contains both '@import' and inline CSS specifications, the
     '@import''s are included first, then 'makeinfo''s defaults, and
     lastly the inline CSS from FILE.

   * Any @-directive other than '@import' and '@charset' is treated as a
     CSS declaration, meaning 'makeinfo' includes its default CSS and
     then the rest of the file.

  If the CSS file is malformed or erroneous, 'makeinfo''s output is
unspecified.  'makeinfo' does not try to interpret the meaning of the
CSS file in any way; it just looks for the special '@' and ';'
characters and blindly copies the text into the output.  Comments in the
CSS file may or may not be included in the output.

  In addition to the possibilities offered by CSS, 'makeinfo' has many
user-definable customization variables with which you can influence the
HTML output.  *Note Customization Variables::.


File: texinfo.info,  Node: HTML Xref,  Prev: HTML CSS,  Up: Generating HTML

24.4 HTML Cross References
==========================

Cross references between Texinfo manuals in HTML format become, in the
end, a standard HTML '' link, but the details are unfortunately
complex.  This section describes the algorithm used in detail, so that
Texinfo can cooperate with other programs, such as 'texi2html', by
writing mutually compatible HTML files.

  This algorithm may or may not be used for links _within_ HTML output
for a Texinfo file.  Since no issues of compatibility arise in such
cases, we do not need to specify this.

  We try to support references to such "external" manuals in both
monolithic and split forms.  A "monolithic" (mono) manual is entirely
contained in one file, and a "split" manual has a file for each node.
(*Note HTML Splitting::.)

  The 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.
* Configuration:     HTML Xref Configuration. htmlxref.cnf.
* Preserving links:  HTML Xref Link Preservation. MANUAL-noderename.cnf.


File: texinfo.info,  Node: HTML Xref Link Basics,  Next: HTML Xref Node Name Expansion,  Up: HTML Xref

24.4.1 HTML Cross Reference Link Basics
---------------------------------------

For our purposes, an HTML link consists of four components: a host name,
a directory part, a file part, and a target part.  We always assume the
'http' protocol.  For example:

     http://HOST/DIR/FILE.html#TARGET

  The information to construct a link comes from the node name and
manual name in the cross reference command in the Texinfo source (*note
Cross References::), and from "external information" (*note HTML Xref
Configuration::).

  We now consider each part in turn.

  The HOST is hardwired to be the local host.  This could either be the
literal string 'localhost', or, according to the rules for HTML links,
the 'http://localhost/' could be omitted entirely.

  The DIR and FILE parts are more complicated, and depend on the
relative split/mono nature of both the manual being processed and the
manual that the cross reference refers to.  The underlying idea is that
there is one directory for Texinfo manuals in HTML, and a given MANUAL
is either available as a monolithic file 'MANUAL.html', or a split
subdirectory 'MANUAL/*.html'.  Here are the cases:

   * If the present manual is split, and the referent manual is also
     split, the directory is '../REFERENT/' and the file is the expanded
     node name (described later).

   * If the present manual is split, and the referent manual is mono,
     the directory is '../' and the file is 'REFERENT.html'.

   * If the present manual is mono, and the referent manual is split,
     the directory is 'REFERENT/' and the file is the expanded node
     name.

   * If the present manual is mono, and the referent manual is also
     mono, the directory is './' (or just the empty string), and the
     file is 'REFERENT.html'.

  Another rule, that only holds for filenames, is that base filenames
are truncated to 245 characters, to allow for an extension to be
appended and still comply with the 255-character limit which is common
to many filesystems.  Although technically this can be changed with the
'BASEFILENAME_LENGTH' customization variable (*note Other Customization
Variables::), doing so would make cross-manual references to such nodes
invalid.

  Any directory part in the filename argument of the source cross
reference command is ignored.  Thus, '@xref{,,,../foo}' and
'@xref{,,,foo}' both use 'foo' as the manual name.  This is because any
such attempted hardwiring of the directory is very unlikely to be useful
for both Info and HTML output.

  Finally, the TARGET part is always the expanded node name.

  Whether the present manual is split or mono is determined by user
option; 'makeinfo' defaults to split, with the '--no-split' option
overriding this.

  Whether the referent manual is split or mono, however, is another bit
of the external information (*note HTML Xref Configuration::).  By
default, 'makeinfo' uses the same form of the referent manual as the
present manual.

  Thus, there can be a mismatch between the format of the referent
manual that the generating software assumes, and the format it's
actually present in.  *Note HTML Xref Mismatch::.


File: texinfo.info,  Node: HTML Xref Node Name Expansion,  Next: HTML Xref Command Expansion,  Prev: HTML Xref Link Basics,  Up: HTML Xref

24.4.2 HTML Cross Reference Node Name Expansion
-----------------------------------------------

As mentioned in the previous section, the key part of the HTML cross
reference algorithm is the conversion of node names in the Texinfo
source into strings suitable for XHTML identifiers and filenames.  The
restrictions are similar for each: plain ASCII letters, numbers, and the
'-' and '_' characters are all that can be used.  (Although HTML anchors
can contain most characters, XHTML is more restrictive.)

  Cross references in Texinfo can refer either to nodes or anchors
(*note @anchor::).  However, anchors are treated identically to nodes in
this context, so we'll continue to say "node" names for simplicity.

  A special exception: the Top node (*note The Top Node::) is always
mapped to the file 'index.html', to match web server software.  However,
the HTML _target_ is 'Top'.  Thus (in the split case):

     @xref{Top,,, emacs, The GNU Emacs Manual}.
     => 

  1. The standard ASCII letters (a-z and A-Z) are not modified.  All
     other characters may be changed as specified below.

  2. 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.

  3. 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.)

  4. Leading and trailing spaces are removed.

  5. After the above has been applied, each remaining space character is
     converted into a '-' character.

  6. Other ASCII 7-bit characters are transformed into '_00XX', where XX
     is the ASCII character code in (lowercase) hexadecimal.  This
     includes '_', which is mapped to '_005f'.

  7. If the node name does not begin with a letter, the literal string
     '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.

  For example:

     @node A  node --- with _'%
     => A-node-_002d_002d_002d-with-_005f_0027_0025

  Example translations of common characters:

   * '_' => '_005f'
   * '-' => '_002d'
   * 'A node' => 'A-node'

  On case-folding computer systems, nodes differing only by case will be
mapped to the same file.  In particular, as mentioned above, Top always
maps to the file 'index.html'.  Thus, on a case-folding system, Top and
a node named 'Index' will both be written to 'index.html'.  Fortunately,
the targets serve to distinguish these cases, since HTML target names
are always case-sensitive, independent of operating system.


File: texinfo.info,  Node: HTML Xref Command Expansion,  Next: HTML Xref 8-bit Character Expansion,  Prev: HTML Xref Node Name Expansion,  Up: HTML Xref

24.4.3 HTML Cross Reference Command Expansion
---------------------------------------------

Node names may contain @-commands (*note Node Line Requirements::).
This section describes how they are handled.

  First, comments are removed.

  Next, any '@value' commands (*note @set @value::) and macro
invocations (*note Invoking Macros::) are fully expanded.

  Then, for the following commands, the command name and braces are
removed, and the text of the argument is recursively transformed:

     @asis @b @cite @code @command @dfn @dmn @dotless
     @emph @env @file @i @indicateurl @kbd @key
     @samp @sansserif @sc @slanted @strong @sub @sup
     @t @U @var @verb @w

For '@sc', any letters are capitalized.

  In addition, the following commands are replaced by constant text, as
shown below.  If any of these commands have non-empty arguments, as in
'@TeX{bad}', it is an error, and the result is unspecified.  In this
table, '(space)' means a space character and '(nothing)' means the empty
string.  The notation 'U+HHHH' means Unicode code point HHHH (in hex, as
usual).

  There are further transformations of many of these expansions to yield
the final file or other target name, such as space characters to '-',
etc., according to the other rules.

'@(newline)'           (space)
'@(space)'             (space)
'@(tab)'               (space)
'@!'                   '!'
'@*'                   (space)
'@-'                   (nothing)
'@.'                   '.'
'@:'                   (nothing)
'@?'                   '?'
'@@'                   '@'
'@{'                   '{'
'@}'                   '}'
'@LaTeX'               'LaTeX'
'@TeX'                 'TeX'
'@arrow'               U+2192
'@bullet'              U+2022
'@comma'               ','
'@copyright'           U+00A9
'@dots'                U+2026
'@enddots'             '...'
'@equiv'               U+2261
'@error'               'error-->'
'@euro'                U+20AC
'@exclamdown'          U+00A1
'@expansion'           U+21A6
'@geq'                 U+2265
'@leq'                 U+2264
'@minus'               U+2212
'@ordf'                U+00AA
'@ordm'                U+00BA
'@point'               U+2605
'@pounds'              U+00A3
'@print'               U+22A3
'@questiondown'        U+00BF
'@registeredsymbol'    U+00AE
'@result'              U+21D2
'@textdegree'          U+00B0
'@tie'                 (space)

  Quotation mark @-commands ('@quotedblright{}' and the like), are
likewise replaced by their Unicode values.  Normal quotation
_characters_ (e.g., ASCII ' and ') are not altered.  *Note Inserting
Quotation Marks::.

  Any '@acronym', '@abbr', '@email', and '@image' commands are replaced
by their first argument.  (For these commands, all subsequent arguments
are optional, and ignored here.)  *Note @acronym::, and *note @email::,
and *note Images::.

  Accents are handled according to the next section.

  Any other command is an error, and the result is unspecified.


File: texinfo.info,  Node: HTML Xref 8-bit Character Expansion,  Next: HTML Xref Mismatch,  Prev: HTML Xref Command Expansion,  Up: HTML Xref

24.4.4 HTML Cross Reference 8-bit Character Expansion
-----------------------------------------------------

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 '_HHHH', where HHHH is the code point in hex.

  For example, combining this rule and the previous section:

     @node @b{A} @TeX{} @u{B} @point{}@enddots{}
     => A-TeX-B_0306-_2605_002e_002e_002e

  Notice: 1) '@enddots' expands to three periods which in turn expands
to three '_002e''s; 2) '@u{B}' is a 'B' with a breve accent, which does
not exist as a pre-accented Unicode character, therefore expands to
'B_0306' (B with combining breve).

  When the Unicode code point is above '0xffff', the transformation is
'__XXXXXX', that is, two leading underscores followed by six hex digits.
Since Unicode has declared that their highest code point is '0x10ffff',
this is sufficient.  (We felt it was better to define this extra escape
than to always use six hex digits, since the first two would nearly
always be zeros.)

  This method works fine if the node name consists mostly of ASCII
characters and contains only few 8-bit ones.  But if the document is
written in a language whose script is not based on the Latin alphabet
(for example, Ukrainian), it will create file names consisting almost
entirely of '_XXXX' notations, which is inconvenient and all but
unreadable.  To handle such cases, 'makeinfo' offers the
'--transliterate-file-names' command line option.  This option enables
"transliteration" of node names into ASCII characters for the purposes
of file name creation and referencing.  The transliteration is based on
phonetic principles, which makes the generated file names more easily
understanable.

  For the definition of Unicode Normalization Form C, see Unicode report
UAX#15, .  Many related documents
and implementations are available elsewhere on the web.


File: texinfo.info,  Node: HTML Xref Mismatch,  Next: HTML Xref Configuration,  Prev: HTML Xref 8-bit Character Expansion,  Up: HTML Xref

24.4.5 HTML Cross Reference Mismatch
------------------------------------

As mentioned earlier (*note HTML Xref Link Basics::), the generating
software may need to guess whether a given manual being cross referenced
is available in split or monolithic form--and, inevitably, it might
guess wrong.  However, when the _referent_ manual is generated, it is
possible to handle at least some mismatches.

  In the case where we assume the referent is split, but it is actually
available in mono, the only recourse would be to generate a 'manual/'
subdirectory full of HTML files which redirect back to the monolithic
'manual.html'.  Since this is essentially the same as a split manual in
the first place, it's not very appealing.

  On the other hand, in the case where we assume the referent is mono,
but it is actually available in split, it is possible to use JavaScript
to redirect from the putatively monolithic 'manual.html' to the
different 'manual/node.html' files.  Here's an example:

     function redirect() {
       switch (location.hash) {
         case "#Node1":
           location.replace("manual/Node1.html#Node1"); break;
         case "#Node2" :
           location.replace("manual/Node2.html#Node2"); break;
         ...
         default:;
       }
     }

  Then, in the '' tag of 'manual.html':

     

  Once again, this is something the software which generated the
_referent_ manual has to do in advance, it's not something the software
generating the cross reference in the present manual can control.


File: texinfo.info,  Node: HTML Xref Configuration,  Next: HTML Xref Link Preservation,  Prev: HTML Xref Mismatch,  Up: HTML Xref

24.4.6 HTML Cross Reference Configuration: 'htmlxref.cnf'
---------------------------------------------------------

'makeinfo' reads a file named 'htmlxref.cnf' to gather information for
cross references to other manuals in HTML output.  It is looked for in
the following directories:

'./'
     (the current directory)

'./.texinfo/'
     (under the current directory)

'~/.texinfo/'
     (where '~' is the current user's home directory)

'SYSCONFDIR/texinfo/'
     (where SYSCONFDIR is the system configuration directory specified
     at compile-time, e.g., '/usr/local/etc')

'DATADIR/texinfo/'
     (likewise specified at compile time, e.g., '/usr/local/share')

  All files found are used, with earlier entries overriding later ones.
The Texinfo distribution includes a default file which handles many GNU
manuals; it is installed in the last of the above directories, i.e.,
'DATADIR/texinfo/htmlxref.cnf'.

  The file is line-oriented.  Lines consisting only of whitespace are
ignored.  Comments are indicated with a '#' at the beginning of a line,
optionally preceded by whitespace.  Since '#' can occur in urls (like
almost any character), it does not otherwise start a comment.

  Each non-blank non-comment line must be either a "variable assignment"
or "manual information".

  A variable assignment line looks like this:

     VARNAME = VARVALUE

  Whitespace around the '=' is optional and ignored.  The VARNAME should
consist of letters; case is significant.  The VARVALUE is an arbitrary
string, continuing to the end of the line.  Variables are then
referenced with '${VARNAME}'; variable references can occur in the
VARVALUE.

  A manual information line looks like this:

     MANUAL KEYWORD URLPREFIX

with MANUAL the short identifier for a manual, KEYWORD being one of:
'mono', 'node', 'section', 'chapter', and URLPREFIX described below.
Variable references can occur only in the URLPREFIX.  For example (used
in the canonical 'htmlxref.cnf'):

     G = http://www.gnu.org
     GS = ${G}/software
     hello mono    ${GS}/hello/manual/hello.html
     hello chapter ${GS}/hello/manual/html_chapter/
     hello section ${GS}/hello/manual/html_section/
     hello node    ${GS}/hello/manual/html_node/

  If the keyword is 'mono', URLPREFIX gives the host, directory, and
file name for MANUAL as one monolithic file.

  If the keyword is 'node', 'section', or 'chapter', URLPREFIX gives the
host and directory for MANUAL split into nodes, sections, or chapters,
respectively.

  When available, 'makeinfo' will use the "corresponding" value for
cross references between manuals.  That is, when generating monolithic
output ('--no-split'), the 'mono' url will be used, when generating
output that is split by node, the 'node' url will be used, etc.
However, if a manual is not available in that form, anything that is
available can be used.  Here is the search order for each style:

     node    => node,    section, chapter, mono
     section => section, chapter, node,    mono
     chapter => chapter, section, node,    mono
     mono    => mono,    chapter, section, node

  These section- and chapter-level cross-manual references can succeed
only when the target manual was created using '--node-files'; this is
the default for split output.

  If you have additions or corrections to the 'htmlxref.cnf' distributed
with Texinfo, please email  as usual.  You can get
the latest version from .


File: texinfo.info,  Node: HTML Xref Link Preservation,  Prev: HTML Xref Configuration,  Up: HTML Xref

24.4.7 HTML Cross Reference Link Preservation: MANUAL'-noderename.cnf'
----------------------------------------------------------------------

Occasionally changes in a program require removing (or renaming) nodes
in the manual in order to have the best documentation.  Given the nature
of the web, however, links may exist anywhere to such a removed node
(renaming appears the same as removal for this purpose), and it's not
ideal for those links to simply break.

  Therefore, Texinfo provides a way for manual authors to specify old
node names and the new nodes to which the old names should be
redirected, via the file MANUAL'-noderename.cnf', where MANUAL is the
base name of the manual.  For example, the manual 'texinfo.texi' would
be supplemented by a file 'texinfo-noderename'.cnf.  (This name can be
overridden by setting the 'RENAMED_NODES_FILE' customization variable;
*note Customization Variables::).

  The file is read in pairs of lines, as follows:

     OLD-NODE-NAME
     @@{} NEW-NODE-NAME

  The usual conversion from Texinfo node names to HTML names is applied;
see this entire section for details (*note HTML Xref::).  The unusual
'@@{}' separator is used because it is not a valid Texinfo construct, so
can't appear in the node names.

  The effect is that 'makeinfo' generates a redirect from OLD-NODE-NAME
to NEW-NODE-NAME when producing HTML output.  Thus, external links to
the old node are preserved.

  Lines consisting only of whitespace are ignored.  Comments are
indicated with an '@c' at the beginning of a line, optionally preceded
by whitespace.

  Another approach to preserving links to deleted or renamed nodes is to
use anchors (*note @anchor::).  There is no effective difference between
the two approaches.


File: texinfo.info,  Node: Command List,  Next: Tips,  Prev: Generating HTML,  Up: Top

Appendix A @-Command List
*************************

Here is an alphabetical list of the @-commands in Texinfo.  Square
brackets, [ ], indicate optional arguments; an ellipsis, '...',
indicates repeated text.

  More specifics on the general syntax of different @-commands are given
in the section below.

* Menu:

* Command Syntax::             General syntax for varieties of @-commands.
* Command Contexts::           Guidelines for which commands can be used where.


'@WHITESPACE'
     An '@' followed by a space, tab, or newline produces a normal,
     stretchable, interword space.  *Note Multiple Spaces::.

'@!'
     Produce an exclamation point that ends a sentence (usually after an
     end-of-sentence capital letter).  *Note Ending a Sentence::.

'@"'
'@''
     Generate an umlaut or acute accent, respectively, over the next
     character, as in o" and o'.  *Note Inserting Accents::.

'@*'
     Force a line break.  *Note Line Breaks::.

'@,{C}'
     Generate a cedilla accent under C, as in c,.  *Note Inserting
     Accents::.

'@-'
     Insert a discretionary hyphenation point.  *Note @- @hyphenation::.

'@.'
     Produce a period that ends a sentence (usually after an
     end-of-sentence capital letter).  *Note Ending a Sentence::.

'@/'
     Produces no output, but allows a line break.  *Note Line Breaks::.

'@:'
     Tell TeX to refrain from inserting extra whitespace after an
     immediately preceding period, question mark, exclamation mark, or
     colon, as TeX normally would.  *Note Not Ending a Sentence::.

'@='
     Generate a macron (bar) accent over the next character, as in o=.
     *Note Inserting Accents::.

'@?'
     Produce a question mark that ends a sentence (usually after an
     end-of-sentence capital letter).  *Note Ending a Sentence::.

'@@'
'@atchar{}'
     Insert an at sign, '@'.  *Note Inserting an Atsign::.

'@\'
'@backslashchar{}'
     Insert a backslash, '\'; '@backslashchar{}' works anywhere, while
     '@\' works only inside '@math'.  *Note Inserting a Backslash::, and
     *note Inserting Math::.

'@^'
'@`'
     Generate a circumflex (hat) or grave accent, respectively, over the
     next character, as in o^ and e`.  *Note Inserting Accents::.

'@{'
'@lbracechar{}'
     Insert a left brace, '{'.  *Note Inserting Braces::.

'@}'
'@rbracechar{}'
     Insert a right brace, '}'.  *Note Inserting Braces::.

'@~'
     Generate a tilde accent over the next character, as in N~.  *Note
     Inserting Accents::.

'@AA{}'
'@aa{}'
     Generate the uppercase and lowercase Scandinavian A-ring letters,
     respectively: AA, aa.  *Note Inserting Accents::.

'@abbr{ABBREVIATION}'
     Indicate a general abbreviation, such as 'Comput.'.  *Note @abbr::.

'@acronym{ACRONYM}'
     Indicate an acronym in all capital letters, such as 'NASA'. *Note
     @acronym::.

'@AE{}'
'@ae{}'
     Generate the uppercase and lowercase AE ligatures, respectively:
     AE, ae.  *Note Inserting Accents::.

'@afivepaper'
     Change page dimensions for the A5 paper size.  *Note A4 Paper::.

'@afourlatex'
'@afourpaper'
'@afourwide'
     Change page dimensions for the A4 paper size.  *Note A4 Paper::.

'@alias NEW=EXISTING'
     Make the command '@NEW' a synonym for the existing command
     '@EXISTING'.  *Note @alias::.

'@allowcodebreaks TRUE-FALSE'
     Control breaking at '-' and '_' in TeX.  *Note @allowcodebreaks::.

'@anchor{NAME}'
     Define NAME as the current location for use as a cross reference
     target.  *Note @anchor::.

'@appendix TITLE'
     Begin an appendix.  The title appears in the table of contents.  In
     Info, the title is underlined with asterisks.  *Note @unnumbered
     @appendix::.

'@appendixsec TITLE'
'@appendixsection TITLE'
     Begin an appendix section within an appendix.  The section title
     appears in the table of contents.  In Info, the title is underlined
     with equal signs.  '@appendixsection' is a longer spelling of the
     '@appendixsec' command.  *Note @unnumberedsec @appendixsec
     @heading::.

'@appendixsubsec TITLE'
     Begin an appendix subsection.  The title appears in the table of
     contents.  In Info, the title is underlined with hyphens.  *Note
     @unnumberedsubsec @appendixsubsec @subheading::.

'@appendixsubsubsec TITLE'
     Begin an appendix subsubsection.  The title appears in the table of
     contents.  In Info, the title is underlined with periods.  *Note
     @subsubsection::.

'@arrow{}'
     Generate a right arrow glyph: '->'.  Used by default for '@click'.
     *Note Click Sequences::.

'@asis'
     Used following '@table', '@ftable', and '@vtable' to print the
     table's first column without highlighting ("as is").  *Note
     @asis::.

'@author AUTHOR'
     Typeset AUTHOR flushleft and underline it.  *Note @title @subtitle
     @author::.

'@b{TEXT}'
     Set TEXT in a bold font.  No effect in Info.  *Note Fonts::.

'@bullet{}'
     Generate a large round dot, * ('*' in Info).  Often used with
     '@table'.  *Note @bullet::.

'@bye'
     Stop formatting a file.  The formatters do not see anything in the
     input file following '@bye'.  *Note Ending a File::.

'@c COMMENT'
     Begin a comment in Texinfo.  The rest of the line does not appear
     in any output.  A synonym for '@comment'.  'DEL' also starts a
     comment.  *Note Comments::.

'@caption'
     Define the full caption for an '@float'.  *Note @caption
     @shortcaption::.

'@cartouche'
     Highlight an example or quotation by drawing a box with rounded
     corners around it.  Pair with '@end cartouche'.  No effect in Info.
     *Note @cartouche::.

'@center LINE-OF-TEXT'
     Center the line of text following the command.  *Note @titlefont
     @center @sp::.

'@centerchap LINE-OF-TEXT'
     Like '@chapter', but centers the chapter title.  *Note @chapter::.

'@chapheading TITLE'
     Print an unnumbered chapter-like heading, but omit from the table
     of contents.  In Info, the title is underlined with asterisks.
     *Note @majorheading @chapheading::.

'@chapter TITLE'
     Begin a numbered chapter.  The chapter title appears in the table
     of contents.  In Info, the title is underlined with asterisks.
     *Note @chapter::.

'@cindex ENTRY'
     Add ENTRY to the index of concepts.  *Note Defining the Entries of
     an Index: Index Entries.

'@cite{REFERENCE}'
     Highlight the name of a book or other reference that has no
     companion Info file.  *Note @cite::.

'@clear FLAG'
     Unset FLAG, preventing the Texinfo formatting commands from
     formatting text between subsequent pairs of '@ifset FLAG' and '@end
     ifset' commands, and preventing '@value{FLAG}' from expanding to
     the value to which FLAG is set.  *Note @set @clear @value::.

'@click{}'
     Represent a single "click" in a GUI.  Used within '@clicksequence'.
     *Note Click Sequences::.

'@clicksequence{ACTION @click{} ACTION}'
     Represent a sequence of clicks in a GUI.  *Note Click Sequences::.

'@clickstyle @CMD'
     Execute @CMD for each '@click'; the default is '@arrow'.  The usual
     following empty braces on @CMD are omitted.  *Note Click
     Sequences::.

'@code{SAMPLE-CODE}'
     Indicate an expression, a syntactically complete token of a
     program, or a program name.  Unquoted in Info output.  *Note
     @code::.

'@codequotebacktick ON-OFF'
'@codequoteundirected ON-OFF'
     Control output of '`' and ''' in code examples.  *Note Inserting
     Quote Characters::.

'@comma{}'
     Insert a comma ',' character; only needed when a literal comma
     would be taken as an argument separator.  *Note Inserting a
     Comma::.

'@command{COMMAND-NAME}'
     Indicate a command name, such as 'ls'.  *Note @command::.

'@comment COMMENT'
     Begin a comment in Texinfo.  The rest of the line does not appear
     in any output.  A synonym for '@c'.  *Note Comments::.

'@contents'
     Print a complete table of contents.  Has no effect in Info, which
     uses menus instead.  *Note Generating a Table of Contents:
     Contents.

'@copying'
     Specify copyright holders and copying conditions for the document
     Pair with '@end cartouche'.  *Note @copying::.

'@copyright{}'
     Generate the copyright symbol (C).  *Note @copyright::.

'@defcodeindex INDEX-NAME'
     Define a new index and its indexing command.  Print entries in an
     '@code' font.  *Note Defining New Indices: New Indices.

'@defcv CATEGORY CLASS NAME'
'@defcvx CATEGORY CLASS NAME'
     Format a description for a variable associated with a class in
     object-oriented programming.  Takes three arguments: the category
     of thing being defined, the class to which it belongs, and its
     name.  *Note Definition Commands::.

'@deffn CATEGORY NAME ARGUMENTS...'
'@deffnx CATEGORY NAME ARGUMENTS...'
     Format a description for a function, interactive command, or
     similar entity that may take arguments.  '@deffn' takes as
     arguments the category of entity being described, the name of this
     particular entity, and its arguments, if any.  *Note Definition
     Commands::.

'@defindex INDEX-NAME'
     Define a new index and its indexing command.  Print entries in a
     roman font.  *Note Defining New Indices: New Indices.

'@definfoenclose NEWCMD, BEFORE, AFTER'
     Must be used within '@ifinfo'; create a new command '@NEWCMD' for
     Info that marks text by enclosing it in strings that precede and
     follow the text.  *Note @definfoenclose::.

'@defivar CLASS INSTANCE-VARIABLE-NAME'
'@defivarx CLASS INSTANCE-VARIABLE-NAME'
     Format a description for an instance variable in object-oriented
     programming.  The command is equivalent to '@defcv {Instance
     Variable} ...'.  *Note Definition Commands::.

'@defmac MACRONAME ARGUMENTS...'
'@defmacx MACRONAME ARGUMENTS...'
     Format a description for a macro; equivalent to '@deffn Macro ...'.
     *Note Definition Commands::.

'@defmethod CLASS METHOD-NAME ARGUMENTS...'
'@defmethodx CLASS METHOD-NAME ARGUMENTS...'
     Format a description for a method in object-oriented programming;
     equivalent to '@defop Method ...'.  *Note Definition Commands::.

'@defop CATEGORY CLASS NAME ARGUMENTS...'
'@defopx CATEGORY CLASS NAME ARGUMENTS...'
     Format a description for an operation in object-oriented
     programming.  '@defop' takes as arguments the name of the category
     of operation, the name of the operation's class, the name of the
     operation, and its arguments, if any.  *Note Definition Commands::,
     and *note Abstract Objects::.

'@defopt OPTION-NAME'
'@defoptx OPTION-NAME'
     Format a description for a user option; equivalent to '@defvr {User
     Option} ...'.  *Note Definition Commands::.

'@defspec SPECIAL-FORM-NAME ARGUMENTS...'
'@defspecx SPECIAL-FORM-NAME ARGUMENTS...'
     Format a description for a special form; equivalent to '@deffn
     {Special Form} ...'.  *Note Definition Commands::.

'@deftp CATEGORY NAME-OF-TYPE ATTRIBUTES...'
'@deftpx CATEGORY NAME-OF-TYPE ATTRIBUTES...'
     Format a description for a data type; its arguments are the
     category, the name of the type (e.g., 'int') , and then the names
     of attributes of objects of that type.  *Note Definition
     Commands::, and *note Data Types::.

'@deftypecv CATEGORY CLASS DATA-TYPE NAME'
'@deftypecvx CATEGORY CLASS DATA-TYPE NAME'
     Format a description for a typed class variable in object-oriented
     programming.  *Note Definition Commands::, and *note Abstract
     Objects::.

'@deftypefn CATEGORY DATA-TYPE NAME ARGUMENTS...'
'@deftypefnx CATEGORY DATA-TYPE NAME ARGUMENTS...'
     Format a description for a function or similar entity that may take
     arguments and that is typed.  '@deftypefn' takes as arguments the
     category of entity being described, the type, the name of the
     entity, and its arguments, if any.  *Note Definition Commands::.

'@deftypefnnewline ON-OFF'
     Specifies whether return types for '@deftypefn' and similar are
     printed on lines by themselves; default is off.  *Note Functions in
     Typed Languages: Typed Functions.

'@deftypefun DATA-TYPE FUNCTION-NAME ARGUMENTS...'
'@deftypefunx DATA-TYPE FUNCTION-NAME ARGUMENTS...'
     Format a description for a function in a typed language.  The
     command is equivalent to '@deftypefn Function ...'.  *Note
     Definition Commands::.

'@deftypeivar CLASS DATA-TYPE VARIABLE-NAME'
'@deftypeivarx CLASS DATA-TYPE VARIABLE-NAME'
     Format a description for a typed instance variable in
     object-oriented programming.  *Note Definition Commands::, and
     *note Abstract Objects::.

'@deftypemethod CLASS DATA-TYPE METHOD-NAME ARGUMENTS...'
'@deftypemethodx CLASS DATA-TYPE METHOD-NAME ARGUMENTS...'
     Format a description for a typed method in object-oriented
     programming.  *Note Definition Commands::.

'@deftypeop CATEGORY CLASS DATA-TYPE NAME ARGUMENTS...'
'@deftypeopx CATEGORY CLASS DATA-TYPE NAME ARGUMENTS...'
     Format a description for a typed operation in object-oriented
     programming.  *Note Definition Commands::, and *note Abstract
     Objects::.

'@deftypevar DATA-TYPE VARIABLE-NAME'
'@deftypevarx DATA-TYPE VARIABLE-NAME'
     Format a description for a variable in a typed language.  The
     command is equivalent to '@deftypevr Variable ...'.  *Note
     Definition Commands::.

'@deftypevr CATEGORY DATA-TYPE NAME'
'@deftypevrx CATEGORY DATA-TYPE NAME'
     Format a description for something like a variable in a typed
     language--an entity that records a value.  Takes as arguments the
     category of entity being described, the type, and the name of the
     entity.  *Note Definition Commands::.

'@defun FUNCTION-NAME ARGUMENTS...'
'@defunx FUNCTION-NAME ARGUMENTS...'
     Format a description for a function; equivalent to '@deffn Function
     ...'.  *Note Definition Commands::.

'@defvar VARIABLE-NAME'
'@defvarx VARIABLE-NAME'
     Format a description for a variable; equivalent to '@defvr Variable
     ...'.  *Note Definition Commands::.

'@defvr CATEGORY NAME'
'@defvrx CATEGORY NAME'
     Format a description for any kind of variable.  '@defvr' takes as
     arguments the category of the entity and the name of the entity.
     *Note Definition Commands::.

'@detailmenu'
     Mark the (optional) detailed node listing in a master menu.  *Note
     Master Menu Parts::.

'@dfn{TERM}'
     Indicate the introductory or defining use of a term.  *Note @dfn::.

'@DH{}'
'@dh{}'
     Generate the uppercase and lowercase Icelandic letter eth,
     respectively: D, d.  *Note Inserting Accents::.

'@dircategory DIRPART'
     Specify a part of the Info directory menu where this file's entry
     should go.  *Note Installing Dir Entries::.

'@direntry'
     Begin the Info directory menu entry for this file.  Pair with '@end
     direntry'.  *Note Installing Dir Entries::.

'@display'
     Begin a kind of example.  Like '@example' (indent text, do not
     fill), but do not select a new font.  Pair with '@end display'.
     *Note @display::.

'@dmn{DIMENSION}'
     Format a unit of measure, as in 12pt.  Causes TeX to insert a thin
     space before DIMENSION.  No effect in Info.  *Note @dmn::.

'@docbook'
     Enter Docbook completely.  Pair with '@end docbook'.  *Note Raw
     Formatter Commands::.

'@documentdescription'
     Set the document description text, included in the HTML output.
     Pair with '@end documentdescription'.  *Note
     @documentdescription::.

'@documentencoding ENC'
     Declare the input encoding to be ENC.  *Note @documentencoding::.

'@documentlanguage CC'
     Declare the document language as the two-character ISO-639
     abbreviation CC.  *Note @documentlanguage::.

'@dotaccent{C}'
     Generate a dot accent over the character C, as in o..  *Note
     Inserting Accents::.

'@dotless{I-OR-J}'
     Generate dotless i ('i') and dotless j ('j').  *Note Inserting
     Accents::.

'@dots{}'
     Generate an ellipsis, '...'.  *Note @dots::.

'@email{ADDRESS[, DISPLAYED-TEXT]}'
     Indicate an electronic mail address.  *Note @email::.

'@emph{TEXT}'
     Emphasize TEXT, by using _italics_ where possible, and enclosing in
     asterisks in Info.  *Note Emphasizing Text: Emphasis.

'@end ENVIRONMENT'
     Ends ENVIRONMENT, as in '@end example'.  *Note @-commands:
     Formatting Commands.

'@enddots{}'
     Generate an end-of-sentence ellipsis, like this: ...  *Note
     @dots::.

'@enumerate [NUMBER-OR-LETTER]'
     Begin a numbered list, using '@item' for each entry.  Optionally,
     start list with NUMBER-OR-LETTER.  Pair with '@end enumerate'.
     *Note @enumerate::.

'@env{ENVIRONMENT-VARIABLE}'
     Indicate an environment variable name, such as 'PATH'.  *Note
     @env::.

'@equiv{}'
     Indicate to the reader the exact equivalence of two forms with a
     glyph: '=='.  *Note @equiv::.

'@error{}'
     Indicate to the reader with a glyph that the following text is an
     error message: 'error->'.  *Note @error::.

'@errormsg{MSG}'
     Report MSG as an error to standard error, and exit unsuccessfully.
     Texinfo commands within MSG are expanded to plain text.  *Note
     Conditionals::, and *note External Macro Processors::.

'@euro{}'
     Generate the Euro currency sign.  *Note @euro::.

'@evenfooting [LEFT] @| [CENTER] @| [RIGHT]'
'@evenheading [LEFT] @| [CENTER] @| [RIGHT]'
     Specify page footings resp. headings for even-numbered (left-hand)
     pages.  *Note How to Make Your Own Headings: Custom Headings.

'@everyfooting [LEFT] @| [CENTER] @| [RIGHT]'
'@everyheading [LEFT] @| [CENTER] @| [RIGHT]'
     Specify page footings resp. headings for every page.  Not relevant
     to Info.  *Note How to Make Your Own Headings: Custom Headings.

'@example'
     Begin an example.  Indent text, do not fill, and select fixed-width
     font.  Pair with '@end example'.  *Note @example::.

'@exampleindent INDENT'
     Indent example-like environments by INDENT number of spaces
     (perhaps 0).  *Note @exampleindent::.

'@exclamdown{}'
     Generate an upside-down exclamation point.  *Note Inserting
     Accents::.

'@exdent LINE-OF-TEXT'
     Remove any indentation a line might have.  *Note @exdent::.

'@expansion{}'
     Indicate the result of a macro expansion to the reader with a
     special glyph: '==>'.  *Note @expansion::.

'@file{FILENAME}'
     Highlight the name of a file, buffer, node, directory, etc.  *Note
     @file::.

'@finalout'
     Prevent TeX from printing large black warning rectangles beside
     over-wide lines.  *Note Overfull hboxes::.

'@findex ENTRY'
     Add ENTRY to the index of functions.  *Note Defining the Entries of
     an Index: Index Entries.

'@firstparagraphindent WORD'
     Control indentation of the first paragraph after section headers
     according to WORD, one of 'none' or 'insert'.  *Note
     @firstparagraphindent::.

'@float'
     Environment to define floating material.  Pair with '@end float'.
     *Note Floats::.

'@flushleft'
'@flushright'
     Do not fill text; left (right) justify every line while leaving the
     right (left) end ragged.  Leave font as is.  Pair with '@end
     flushleft' ('@end flushright').  *Note @flushleft @flushright::.

'@fonttextsize 10-11'
     Change the size of the main body font in the TeX output.  *Note
     Fonts::.

'@footnote{TEXT-OF-FOOTNOTE}'
     Enter a footnote.  Footnote text is printed at the bottom of the
     page by TeX; Info may format in either 'End' node or 'Separate'
     node style.  *Note Footnotes::.

'@footnotestyle STYLE'
     Specify an Info file's footnote style, either 'end' for the end
     node style or 'separate' for the separate node style.  *Note
     Footnotes::.

'@format'
     Begin a kind of example.  Like '@display', but do not indent.  Pair
     with '@end format'.  *Note @example::.

'@frenchspacing ON-OFF'
     Control spacing after punctuation.  *Note @frenchspacing::.

'@ftable FORMATTING-COMMAND'
     Begin a two-column table, using '@item' for each entry.
     Automatically enter each of the items in the first column into the
     index of functions.  Pair with '@end ftable'.  The same as
     '@table', except for indexing.  *Note @ftable @vtable::.

'@geq{}'
     Generate a greater-than-or-equal sign, '>='.  *Note @geq @leq::.

'@group'
     Disallow page breaks within following text.  Pair with '@end
     group'.  Ignored in Info.  *Note @group::.

'@guillemetleft{}'
'@guillemetright{}'
'@guillemotleft{}'
'@guillemotright{}'
'@guilsinglleft{}'
'@guilsinglright{}'
     Double and single angle quotation marks: << >> < >.
     '@guillemotleft' and '@guillemotright' are synonyms for
     '@guillemetleft' and '@guillemetright'.  *Note Inserting Quotation
     Marks::.

'@H{C}'
     Generate the long Hungarian umlaut accent over C, as in o''.

'@hashchar{}'
     Insert a hash '#' character; only needed when a literal hash would
     introduce '#line' directive.  *Note Inserting a Hashsign::, and
     *note External Macro Processors::.

'@heading TITLE'
     Print an unnumbered section-like heading, but omit from the table
     of contents.  In Info, the title is underlined with equal signs.
     *Note @unnumberedsec @appendixsec @heading::.

'@headings ON-OFF-SINGLE-DOUBLE'
     Turn page headings on or off, and/or specify single-sided or
     double-sided page headings for printing.  *Note @headings::.

'@headitem'
     Begin a heading row in a multitable.  *Note Multitable Rows::.

'@headitemfont{TEXT}'
     Set TEXT in the font used for multitable heading rows; mostly
     useful in multitable templates.  *Note Multitable Rows::.

'@html'
     Enter HTML completely.  Pair with '@end html'.  *Note Raw Formatter
     Commands::.

'@hyphenation{HY-PHEN-A-TED WORDS}'
     Explicitly define hyphenation points.  *Note @- @hyphenation::.

'@i{TEXT}'
     Set TEXT in an italic font.  No effect in Info.  *Note Fonts::.

'@ifclear TXIVAR'
     If the Texinfo variable TXIVAR is not set, format the following
     text.  Pair with '@end ifclear'.  *Note @set @clear @value::.

'@ifcommanddefined TXICMD'
'@ifcommandnotdefined TXICMD'
     If the Texinfo code '@TXICMD' is (not) defined, format the follow
     text.  Pair with the corresponding '@end ifcommand...'.  *Note
     Testing for Texinfo Commands::.

'@ifdocbook'
'@ifhtml'
'@ifinfo'
     Begin text that will appear only in the given output format.
     '@ifinfo' output appears in both Info and (for historical
     compatibility) plain text output.  Pair with '@end ifdocbook' resp.
     '@end ifhtml' resp. '@end ifinfo'.  *Note Conditionals::.

'@ifnotdocbook'
'@ifnothtml'
'@ifnotplaintext'
'@ifnottex'
'@ifnotxml'
     Begin text to be ignored in one output format but not the others.
     '@ifnothtml' text is omitted from HTML output, etc.  Pair with the
     corresponding '@end ifnotFORMAT'.  *Note Conditionals::.

'@ifnotinfo'
     Begin text to appear in output other than Info and (for historical
     compatibility) plain text.  Pair with '@end ifnotinfo'.  *Note
     Conditionals::.

'@ifplaintext'
     Begin text that will appear only in the plain text output.  Pair
     with '@end ifplaintext'.  *Note Conditionals::.

'@ifset TXIVAR'
     If the Texinfo variable TXIVAR is set, format the following text.
     Pair with '@end ifset'.  *Note @set @clear @value::.

'@iftex'
     Begin text to appear only in the TeX output.  Pair with '@end
     iftex'.  *Note Conditionally Visible Text: Conditionals.

'@ifxml'
     Begin text that will appear only in the XML output.  Pair with
     '@end ifxml'.  *Note Conditionals::.

'@ignore'
     Begin text that will not appear in any output.  Pair with '@end
     ignore'.  *Note Comments and Ignored Text: Comments.

'@image{FILENAME, [WIDTH], [HEIGHT], [ALT], [EXT]}'
     Include graphics image in external FILENAME scaled to the given
     WIDTH and/or HEIGHT, using ALT text and looking for 'FILENAME.EXT'
     in HTML.  *Note Images::.

'@include FILENAME'
     Read the contents of Texinfo source file FILENAME.  *Note Include
     Files::.

'@indent'
     Insert paragraph indentation.  *Note @indent::.

'@indentedblock'
     Indent a block of arbitary text on the left.  Pair with '@end
     indentedblock'.  *Note @indentedblock::.

'@indicateurl{INDICATEURL}'
     Indicate text that is a uniform resource locator for the World Wide
     Web.  *Note @indicateurl::.

'@inforef{NODE-NAME, [ENTRY-NAME], INFO-FILE-NAME}'
     Make a cross reference to an Info file for which there is no
     printed manual.  *Note @inforef::.

'@inlinefmt{FMT, TEXT}'
     Insert TEXT only if the output format is FMT.  *Note Inline
     Conditionals::.

'@inlinefmtifelse{FMT, TEXT, ELSE-TEXT}'
     Insert TEXT if the output format is FMT, else ELSE-TEXT.

'@inlineifclear{VAR, TEXT}'
'@inlineifset{VAR, TEXT}'
     Insert TEXT only if the Texinfo variable VAR is (not) set.

'@inlineraw{FMT, RAW-TEXT}'
     Insert TEXT as in a raw conditional, only if the output format is
     FMT.

'\input MACRO-DEFINITIONS-FILE'
     Use the specified macro definitions file.  This command is used
     only in the first line of a Texinfo file to cause TeX to make use
     of the 'texinfo' macro definitions file.  The '\' in '\input' is
     used instead of an '@' because TeX does not recognize '@' until
     after it has read the definitions file.  *Note Texinfo File
     Header::.

'@insertcopying'
     Insert the text previously defined with the '@copying' environment.
     *Note @insertcopying::.

'@item'
     Indicate the beginning of a marked paragraph for '@itemize' and
     '@enumerate'; indicate the beginning of the text of a first column
     entry for '@table', '@ftable', and '@vtable'.  *Note Lists and
     Tables::.

'@itemize MARK-GENERATING-CHARACTER-OR-COMMAND'
     Begin an unordered list: indented paragraphs with a mark, such as
     '@bullet', inside the left margin at the beginning of each item.
     Pair with '@end itemize'.  *Note @itemize::.

'@itemx'
     Like '@item' but do not generate extra vertical space above the
     item text.  Thus, when several items have the same description, use
     '@item' for the first and '@itemx' for the others.  *Note @itemx::.

'@kbd{KEYBOARD-CHARACTERS}'
     Indicate characters of input to be typed by users.  *Note @kbd::.

'@kbdinputstyle STYLE'
     Specify when '@kbd' should use a font distinct from '@code'
     according to STYLE: 'code', 'distinct', 'example'.  *Note @kbd::.

'@key{KEY-NAME}'
     Indicate the name of a key on a keyboard.  *Note @key::.

'@kindex ENTRY'
     Add ENTRY to the index of keys.  *Note Defining the Entries of an
     Index: Index Entries.

'@L{}'
'@l{}'
     Generate the uppercase and lowercase Polish suppressed-L letters,
     respectively: /L, /l.

'@LaTeX{}'
     Generate the LaTeX logo.  *Note @TeX @LaTeX::.

'@leq{}'
     Generate a less-than-or-equal sign, '<='.  *Note @geq @leq::.

'@lisp'
     Begin an example of Lisp code.  Indent text, do not fill, and
     select fixed-width font.  Pair with '@end lisp'.  *Note @lisp::.

'@listoffloats'
     Produce a table-of-contents-like listing of '@float's.  *Note
     @listoffloats::.

'@lowersections'
     Change subsequent chapters to sections, sections to subsections,
     and so on.  *Note '@raisesections' and '@lowersections':
     Raise/lower sections.

'@macro MACRONAME {PARAMS}'
     Define a new Texinfo command '@MACRONAME{PARAMS}'.  Pair with '@end
     macro'.  *Note Defining Macros::.

'@majorheading TITLE'
     Print an unnumbered chapter-like heading, but omit from the table
     of contents.  This generates more vertical whitespace before the
     heading than the '@chapheading' command.  *Note @majorheading
     @chapheading::.

'@math{MATHEMATICAL-EXPRESSION}'
     Format a mathematical expression.  *Note Inserting Math::.

'@menu'
     Mark the beginning of a menu of nodes.  No effect in a printed
     manual.  Pair with '@end menu'.  *Note Menus::.

'@minus{}'
     Generate a minus sign, '-'.  *Note @minus::.

'@multitable COLUMN-WIDTH-SPEC'
     Begin a multi-column table.  Begin each row with '@item' or
     '@headitem', and separate columns with '@tab'.  Pair with '@end
     multitable'.  *Note Multitable Column Widths::.

'@need N'
     Start a new page in a printed manual if fewer than N mils
     (thousandths of an inch) remain on the current page.  *Note
     @need::.

'@node NAME, NEXT, PREVIOUS, UP'
     Begin a new node.  *Note @node::.

'@noindent'
     Prevent text from being indented as if it were a new paragraph.
     *Note @noindent::.

'@novalidate'
     Suppress validation of node references and omit creation of
     auxiliary files with TeX.  Use before '@setfilename'.  *Note
     Pointer Validation::.

'@O{}'
'@o{}'
     Generate the uppercase and lowercase O-with-slash letters,
     respectively: /O, /o.

'@oddfooting [LEFT] @| [CENTER] @| [RIGHT]'
'@oddheading [LEFT] @| [CENTER] @| [RIGHT]'
     Specify page footings resp. headings for odd-numbered (right-hand)
     pages.  *Note How to Make Your Own Headings: Custom Headings.

'@OE{}'
'@oe{}'
     Generate the uppercase and lowercase OE ligatures, respectively:
     OE, oe.  *Note Inserting Accents::.

'@ogonek{C}'
     Generate an ogonek diacritic under the next character, as in a;.
     *Note Inserting Accents::.

'@option{OPTION-NAME}'
     Indicate a command-line option, such as '-l' or '--help'.  *Note
     @option::.

'@ordf{}'
'@ordm{}'
     Generate the feminine and masculine Spanish ordinals, respectively:
     a, o.  *Note Inserting Accents::.

'@page'
     Start a new page in a printed manual.  No effect in Info.  *Note
     @page::.

'@pagesizes [WIDTH][, HEIGHT]'
     Change page dimensions.  *Note pagesizes::.

'@paragraphindent INDENT'
     Indent paragraphs by INDENT number of spaces (perhaps 0); preserve
     source file indentation if INDENT is 'asis'.  *Note
     @paragraphindent::.

'@part TITLE'
     Begin a group of chapters or appendixes; included in the tables of
     contents and produces a page of its own in printed output.  *Note
     @part::.

'@pindex ENTRY'
     Add ENTRY to the index of programs.  *Note Defining the Entries of
     an Index: Index Entries.

'@point{}'
     Indicate the position of point in a buffer to the reader with a
     glyph: '-!-'.  *Note @point::.

'@pounds{}'
     Generate the pounds sterling currency sign.  *Note @pounds::.

'@print{}'
     Indicate printed output to the reader with a glyph: '-|'.  *Note
     @print::.

'@printindex INDEX-NAME'
     Generate the alphabetized index for INDEX-NAME (using two columns
     in a printed manual).  *Note Printing Indices & Menus::.

'@pxref{NODE, [ENTRY], [NODE-TITLE], [INFO-FILE], [MANUAL]}'
     Make a reference that starts with a lowercase 'see' in a printed
     manual.  Use within parentheses only.  Only the first argument is
     mandatory.  *Note @pxref::.

'@questiondown{}'
     Generate an upside-down question mark.  *Note Inserting Accents::.

'@quotation'
     Narrow the margins to indicate text that is quoted from another
     work.  Takes optional argument specifying prefix text, e.g., an
     author name.  Pair with '@end quotation'.  *Note @quotation::.

'@quotedblleft{}'
'@quotedblright{}'
'@quoteleft{}'
'@quoteright{}'
'@quotedblbase{}'
'@quotesinglbase{}'
     Produce various quotation marks: `` '' ` ' ,, ,.  *Note Inserting
     Quotation Marks::.

'@r{TEXT}'
     Set TEXT in the regular roman font.  No effect in Info.  *Note
     Fonts::.

'@raggedright'
     Fill text; left justify every line while leaving the right end
     ragged.  Leave font as is.  Pair with '@end raggedright'.  No
     effect in Info.  *Note @raggedright::.

'@raisesections'
     Change subsequent sections to chapters, subsections to sections,
     and so on.  *Note Raise/lower sections::.

'@ref{NODE, [ENTRY], [NODE-TITLE], [INFO-FILE], [MANUAL]}'
     Make a plain reference that does not start with any special text.
     Follow command with a punctuation mark.  Only the first argument is
     mandatory.  *Note @ref::.

'@refill'
     This command used to refill and indent the paragraph after all the
     other processing has been done.  It is no longer needed, since all
     formatters now automatically refill as needed, but you may still
     see it in the source to some manuals, as it does no harm.

'@registeredsymbol{}'
     Generate the legal symbol (R).  *Note @registeredsymbol::.

'@result{}'
     Indicate the result of an expression to the reader with a special
     glyph: '=>'.  *Note @result::.

'@ringaccent{C}'
     Generate a ring accent over the next character, as in o*.  *Note
     Inserting Accents::.

'@samp{TEXT}'
     Indicate a literal example of a sequence of characters, in general.
     Quoted in Info output.  *Note @samp::.

'@sansserif{TEXT}'
     Set TEXT in a sans serif font if possible.  No effect in Info.
     *Note Fonts::.

'@sc{TEXT}'
     Set TEXT in a small caps font in printed output, and uppercase in
     Info.  *Note Smallcaps::.

'@section TITLE'
     Begin a section within a chapter.  The section title appears in the
     table of contents.  In Info, the title is underlined with equal
     signs.  Within '@chapter' and '@appendix', the section title is
     numbered; within '@unnumbered', the section is unnumbered.  *Note
     @section::.

'@set TXIVAR [STRING]'
     Define the Texinfo variable TXIVAR, optionally to the value STRING.
     *Note @set @clear @value::.

'@setchapternewpage ON-OFF-ODD'
     Specify whether chapters start on new pages, and if so, whether on
     odd-numbered (right-hand) new pages.  *Note @setchapternewpage::.

'@setcontentsaftertitlepage'
     Put the table of contents after the '@end titlepage' even if the
     '@contents' command is at the end.  *Note Contents::.

'@setfilename INFO-FILE-NAME'
     Provide a name to be used for the output files.  This command is
     essential for TeX formatting as well, even though it produces no
     output of its own.  *Note @setfilename::.

'@setshortcontentsaftertitlepage'
     Place the short table of contents after the '@end titlepage'
     command even if the '@shortcontents' command is at the end.  *Note
     Contents::.

'@settitle TITLE'
     Specify the title for page headers in a printed manual, and the
     default document title for HTML ''.  *Note @settitle::.

'@shortcaption'
     Define the short caption for an '@float'.  *Note @caption
     @shortcaption::.

'@shortcontents'
     Print a short table of contents, with chapter-level entries only.
     Not relevant to Info, which uses menus rather than tables of
     contents.  *Note Generating a Table of Contents: Contents.

'@shorttitlepage TITLE'
     Generate a minimal title page.  *Note @titlepage::.

'@slanted{TEXT}'
     Set TEXT in a slanted font if possible.  No effect in Info.  *Note
     Fonts::.

'@smallbook'
     Cause TeX to produce a printed manual in a 7 by 9.25 inch format
     rather than the regular 8.5 by 11 inch format.  *Note @smallbook::.
     Also, see *note @small...::.

'@smalldisplay'
     Begin a kind of example.  Like '@display', but use a smaller font
     size where possible.  Pair with '@end smalldisplay'.  *Note
     @small...::.

'@smallexample'
     Begin an example.  Like '@example', but use a smaller font size
     where possible.  Pair with '@end smallexample'.  *Note @small...::.

'@smallformat'
     Begin a kind of example.  Like '@format', but use a smaller font
     size where possible.  Pair with '@end smallformat'.  *Note
     @small...::.

'@smallindentedblock'
     Like '@indentedblock', but use a smaller font size where possible.
     Pair with '@end smallindentedblock'.  *Note @small...::.

'@smalllisp'
     Begin an example of Lisp code.  Same as '@smallexample'.  Pair with
     '@end smalllisp'.  *Note @small...::.

'@smallquotation'
     Like '@quotation', but use a smaller font size where possible.
     Pair with '@end smallquotation'.  *Note @small...::.

'@sp N'
     Skip N blank lines.  *Note @sp::.

'@ss{}'
     Generate the German sharp-S es-zet letter, ss.  *Note Inserting
     Accents::.

'@strong {TEXT}'
     Emphasize TEXT more strongly than '@emph', by using *boldface*
     where possible; enclosed in asterisks in Info.  *Note Emphasizing
     Text: emph & strong.

'@sub {TEXT}'
     Set TEXT as a subscript.  *Note Inserting Subscripts and
     Superscripts::.

'@subheading TITLE'
     Print an unnumbered subsection-like heading, but omit from the
     table of contents of a printed manual.  In Info, the title is
     underlined with hyphens.  *Note @unnumberedsubsec @appendixsubsec
     @subheading::.

'@subsection TITLE'
     Begin a subsection within a section.  The subsection title appears
     in the table of contents.  In Info, the title is underlined with
     hyphens.  Same context-dependent numbering as '@section'.  *Note
     @subsection::.

'@subsubheading TITLE'
     Print an unnumbered subsubsection-like heading, but omit from the
     table of contents of a printed manual.  In Info, the title is
     underlined with periods.  *Note @subsubsection::.

'@subsubsection TITLE'
     Begin a subsubsection within a subsection.  The subsubsection title
     appears in the table of contents.  In Info, the title is underlined
     with periods.  Same context-dependent numbering as '@section'.
     *Note @subsubsection::.

'@subtitle TITLE'
     In a printed manual, set a subtitle in a normal sized font flush to
     the right-hand side of the page.  Not relevant to Info, which does
     not have title pages.  *Note @title @subtitle @author::.

'@summarycontents'
     Print a short table of contents.  Synonym for '@shortcontents'.
     *Note Generating a Table of Contents: Contents.

'@sup {TEXT}'
     Set TEXT as a superscript.  *Note Inserting Subscripts and
     Superscripts::.

'@syncodeindex FROM-INDEX TO-INDEX'
     Merge the index named in the first argument into the index named in
     the second argument, formatting the entries from the first index
     with '@code'.  *Note Combining Indices::.

'@synindex FROM-INDEX TO-INDEX'
     Merge the index named in the first argument into the index named in
     the second argument.  Do not change the font of FROM-INDEX entries.
     *Note Combining Indices::.

'@t{TEXT}'
     Set TEXT in a fixed-width, typewriter-like font.  No effect in
     Info.  *Note Fonts::.

'@tab'
     Separate columns in a row of a multitable.  *Note Multitable
     Rows::.

'@table FORMATTING-COMMAND'
     Begin a two-column table (description list), using '@item' for each
     entry.  Write each first column entry on the same line as '@item'.
     First column entries are printed in the font resulting from
     FORMATTING-COMMAND.  Pair with '@end table'.  *Note Making a
     Two-column Table: Two-column Tables.  Also see *note @ftable
     @vtable::, and *note @itemx::.

'@TeX{}'
     Generate the TeX logo.  *Note @TeX @LaTeX::.

'@tex'
     Enter TeX completely.  Pair with '@end tex'.  *Note Raw Formatter
     Commands::.

'@textdegree{}'
     Generate the degree symbol.  *Note @textdegree::.

'@thischapter'
'@thischaptername'
'@thischapternum'
'@thisfile'
'@thispage'
'@thistitle'
     Only allowed in a heading or footing.  Stands for, respectively,
     the number and name of the current chapter (in the format 'Chapter
     1: Title'), the current chapter name only, the current chapter
     number only, the filename, the current page number, and the title
     of the document, respectively.  *Note How to Make Your Own
     Headings: Custom Headings.

'@TH{}'
'@th{}'
     Generate the uppercase and lowercase Icelandic letter thorn,
     respectively: TH, th.  *Note Inserting Accents::.

'@tie{}'
     Generate a normal interword space at which a line break is not
     allowed.  *Note @tie::.

'@tieaccent{CC}'
     Generate a tie-after accent over the next two characters CC, as in
     'oo['.  *Note Inserting Accents::.

'@tindex ENTRY'
     Add ENTRY to the index of data types.  *Note Defining the Entries
     of an Index: Index Entries.

'@title TITLE'
     In a printed manual, set a title flush to the left-hand side of the
     page in a larger than normal font and underline it with a black
     rule.  Not relevant to Info, which does not have title pages.
     *Note @title @subtitle @author::.

'@titlefont{TEXT}'
     In a printed manual, print TEXT in a larger than normal font.
     *Note @titlefont @center @sp::.

'@titlepage'
     Begin the title page.  Write the command on a line of its own,
     paired with '@end titlepage'.  Nothing between '@titlepage' and
     '@end titlepage' appears in Info.  *Note @titlepage::.

'@today{}'
     Insert the current date, in '1 Jan 1900' style.  *Note How to Make
     Your Own Headings: Custom Headings.

'@top TITLE'
     Mark the topmost '@node' in the file, which must be defined on the
     line immediately preceding the '@top' command.  The title is
     formatted as a chapter-level heading.  The entire top node,
     including the '@node' and '@top' lines, are normally enclosed with
     '@ifnottex ... @end ifnottex'.  In TeX and 'texinfo-format-buffer',
     the '@top' command is merely a synonym for '@unnumbered'.  *Note
     makeinfo Pointer Creation::.

'@U{HEX}'
     Output a representation of Unicode character U+HEX.  *Note
     Inserting Unicode::.

'@u{C}'
'@ubaraccent{C}'
'@udotaccent{C}'
     Generate a breve, underbar, or underdot accent, respectively, over
     or under the character C, as in o(, o_, .o.  *Note Inserting
     Accents::.

'@unmacro MACRONAME'
     Undefine the macro '@MACRONAME' if it has been defined.  *Note
     Defining Macros::.

'@unnumbered TITLE'
     Begin a chapter that appears without chapter numbers of any kind.
     The title appears in the table of contents.  In Info, the title is
     underlined with asterisks.  *Note @unnumbered @appendix::.

'@unnumberedsec TITLE'
     Begin a section that appears without section numbers of any kind.
     The title appears in the table of contents of a printed manual.  In
     Info, the title is underlined with equal signs.  *Note
     @unnumberedsec @appendixsec @heading::.

'@unnumberedsubsec TITLE'
     Begin an unnumbered subsection.  The title appears in the table of
     contents.  In Info, the title is underlined with hyphens.  *Note
     @unnumberedsubsec @appendixsubsec @subheading::.

'@unnumberedsubsubsec TITLE'
     Begin an unnumbered subsubsection.  The title appears in the table
     of contents.  In Info, the title is underlined with periods.  *Note
     @subsubsection::.

'@uref{URL[, DISPLAYED-TEXT][, REPLACEMENT}'
'@url{URL[, DISPLAYED-TEXT][, REPLACEMENT}'
     Define a cross reference to an external uniform resource locator,
     e.g., for the World Wide Web.  *Note @url::.

'@urefbreakstyle STYLE'
     Specify how '@uref'/'@url' should break at special characters:
     'after', 'before', 'none'.  *Note @url::.

'@v{C}'
     Generate check accent over the character C, as in o<.  *Note
     Inserting Accents::.

'@value{TXIVAR}'
     Insert the value, if any, of the Texinfo variable TXIVAR,
     previously defined by '@set'.  *Note @set @clear @value::.

'@var{METASYNTACTIC-VARIABLE}'
     Highlight a metasyntactic variable, which is something that stands
     for another piece of text.  *Note @var::.

'@verb{DELIM LITERAL DELIM}'
     Output LITERAL, delimited by the single character DELIM, exactly as
     is (in the fixed-width font), including any whitespace or Texinfo
     special characters.  *Note @verb::.

'@verbatim'
     Output the text of the environment exactly as is (in the
     fixed-width font).  Pair with '@end verbatim'.  *Note @verbatim::.

'@verbatiminclude FILENAME'
     Output the contents of FILENAME exactly as is (in the fixed-width
     font).  *Note @verbatiminclude::.

'@vindex ENTRY'
     Add ENTRY to the index of variables.  *Note Defining the Entries of
     an Index: Index Entries.

'@vskip AMOUNT'
     In a printed manual, insert whitespace so as to push text on the
     remainder of the page towards the bottom of the page.  Used in
     formatting the copyright page with the argument '0pt plus 1filll'.
     (Note spelling of 'filll'.)  '@vskip' may be used only in contexts
     ignored for Info.  *Note Copyright::.

'@vtable FORMATTING-COMMAND'
     Begin a two-column table, using '@item' for each entry.
     Automatically enter each of the items in the first column into the
     index of variables.  Pair with '@end vtable'.  The same as
     '@table', except for indexing.  *Note @ftable @vtable::.

'@w{TEXT}'
     Disallow line breaks within TEXT.  *Note @w::.

'@xml'
     Enter XML completely.  Pair with '@end xml'.  *Note Raw Formatter
     Commands::.

'@xref{NODE, [ENTRY], [NODE-TITLE], [INFO-FILE], [MANUAL]}'
     Make a reference that starts with 'See' in a printed manual.
     Follow command with a punctuation mark.  Only the first argument is
     mandatory.  *Note @xref::.

'@xrefautomaticsectiontitle ON-OFF'
     By default, use the section title instead of the node name in cross
     references.  *Note Three Arguments::.


File: texinfo.info,  Node: Command Syntax,  Next: Command Contexts,  Up: Command List

A.1 @-Command Syntax
====================

The character '@' is used to start all Texinfo commands.  (It has the
same meaning that '\' has in plain TeX.)  Texinfo has four types of
@-command:

1. Non-alphabetic commands.
     These commands consist of an @ followed by a punctuation mark or
     other character that is not part of the Latin alphabet.
     Non-alphabetic commands are almost always part of the text within a
     paragraph.  The non-alphabetic commands include '@@', '@{', '@}',
     '@.', '@SPACE', most of the accent commands, and many more.

2. Alphabetic commands that do not require arguments.
     These commands start with @ followed by a word followed by a left
     and right- brace.  These commands insert special symbols in the
     document; they do not take arguments.  Some examples: '@dots{}' =>
     '...', '@equiv{}' => '==', '@TeX{}' => 'TeX', and '@bullet{}' =>
     '*'.

3. Alphabetic commands that require arguments within braces.
     These commands start with @ followed by a letter or a word,
     followed by an argument within braces.  For example, the command
     '@dfn' indicates the introductory or defining use of a term; it is
     used as follows: 'In Texinfo, @@-commands are @dfn{mark-up}
     commands.'

4. Alphabetic commands that occupy an entire line.
     These commands occupy an entire line.  The line starts with @,
     followed by the name of the command (a word); for example,
     '@center' or '@cindex'.  If no argument is needed, the word is
     followed by the end of the line.  If there is an argument, it is
     separated from the command name by a space.  Braces are not used.

  Whitespace following an @-command name are optional and (usually)
ignored if present.  The exceptions are contexts whee whitespace is
significant, e.g., an '@example' environment.

  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 among other text as
part of a paragraph, the command is in class 3 and must be followed by
an argument in braces; otherwise, it is in class 4 and uses the rest of
the line as its argument.

  The purpose of having a different syntax for commands of classes 3
and 4 is to make Texinfo files easier to read, and also to help the GNU
Emacs paragraph and filling commands work properly.  There is only one
exception to this rule: the command '@refill', which is always used at
the end of a paragraph immediately following the final period or other
punctuation character.  '@refill' takes no argument and does _not_
require braces.  '@refill' never confuses the Emacs paragraph commands
because it cannot appear at the beginning of a line.  It is also no
longer needed, since all formatters now refill paragraphs automatically.


File: texinfo.info,  Node: Command Contexts,  Prev: Command Syntax,  Up: Command List

A.2 @-Command Contexts
======================

Here we describe approximately which @-commands can be used in which
contexts.  It merely gives the general idea and is not exhaustive or
meant to be a complete reference.  Discrepancies between the information
here and the 'makeinfo' or TeX implementations are most likely to be
resolved in favor of the implementation.

  By "general text" below, we mean anything except sectioning and other
such outer-level document commands, such as '@section', '@node', and
'@setfilename'.

  '@c', '@comment' and '@if ... @end if' conditional commands may appear
anywhere (except the conditionals must still be on lines by themselves).
'@caption' may only appear in '@float' but may contain general text.
'@footnote' content likewise.

  @-commands with braces marking text (such as '@strong', '@sc',
'@asis') may contain raw formatter commands such as '@html' but no other
block commands (other commands terminated by '@end') and may not be
split across paragraphs, but may otherwise contain general text.

  In addition to the block command restriction, on '@center', '@exdent'
and '@item' in '@table' lines, @-commands that makes only sense in a
paragraph are not accepted, such as '@indent'.

  In addition to the above, sectioning commands cannot contain
'@anchor', '@footnote' or '@verb'.

  In addition to the above, remaining commands ('@node', '@anchor',
'@printindex', '@ref', '@math', '@cindex', '@url', '@image', and so on)
cannot contain cross reference commands ('@ref', '@xref', '@pxref' and
'@inforef').  In one last addition, '@shortcaption' may only appear
inside '@float'.

  For precise and complete information, we suggest looking into the
extensive test suite in the sources, which exhaustively try
combinations.


File: texinfo.info,  Node: Tips,  Next: Sample Texinfo Files,  Prev: Command List,  Up: Top

Appendix B Tips and Hints
*************************

Here are some tips for writing Texinfo documentation:

   * Write in the present tense, not in the past or the future.

   * Write actively!  For example, write "We recommend that ..." rather
     than "It is recommended that ...".

   * Use 70 or 72 as your fill column.  Longer lines are hard to read.

   * Include a copyright notice and copying permissions.

Index, Index, Index!
....................

Write many index entries, in different ways.  Readers like indices; they
are helpful and convenient.

  Although it is easiest to write index entries as you write the body of
the text, some people prefer to write entries afterwards.  In either
case, write an entry before the paragraph to which it applies.  This
way, an index entry points to the first page of a paragraph that is
split across pages.

  Here are more index-related hints we have found valuable:

   * Write each index entry differently, so each entry refers to a
     different place in the document.

   * Write index entries only where a topic is discussed significantly.
     For example, it is not useful to index "debugging information" in a
     chapter on reporting bugs.  Someone who wants to know about
     debugging information will certainly not find it in that chapter.

   * Consistently capitalize the first word of every concept index
     entry, or else consistently use lowercase.  Terse entries often
     call for lowercase; longer entries for capitalization.  Whichever
     case convention you use, please use one or the other consistently!
     Mixing the two styles looks bad.

   * Always capitalize or use uppercase for those words in an index for
     which this is proper, such as names of countries or acronyms.
     Always use the appropriate case for case-sensitive names, such as
     those in C or Lisp.

   * Write the indexing commands that refer to a whole section
     immediately after the section command, and write the indexing
     commands that refer to a paragraph before that paragraph.

     In the example that follows, a blank line comes after the index
     entry for "Leaping":

          @section The Dog and the Fox
          @cindex Jumping, in general
          @cindex Leaping

          @cindex Dog, lazy, jumped over
          @cindex Lazy dog jumped over
          @cindex Fox, jumps over dog
          @cindex Quick fox jumps over dog
          The quick brown fox jumps over the lazy dog.

     (Note that the example shows entries for the same concept that are
     written in different ways--'Lazy dog', and 'Dog, lazy'--so readers
     can look up the concept in different ways.)

Blank Lines
...........

   * Insert a blank line between a sectioning command and the first
     following sentence or paragraph, or between the indexing commands
     associated with the sectioning command and the first following
     sentence or paragraph, as shown in the tip on indexing.  It makes
     the source easier to read.

   * Always insert a blank line before an '@table' command and after an
     '@end table' command; but never insert a blank line after an
     '@table' command.

     For example,

          Types of fox:

          @table @samp
          @item Quick
          Jump over lazy dogs.

          @item Brown
          Also jump over lazy dogs.
          @end table

          @noindent
          On the other hand, ...

     Insert blank lines before and after '@itemize' ... '@end itemize'
     and '@enumerate' ... '@end enumerate' in the same way.

Complete Phrases
................

Complete phrases are easier to read than ...

   * Write entries in an itemized list as complete sentences; or at
     least, as complete phrases.  Incomplete expressions ... awkward ...
     like this.

   * Write the prefatory sentence or phrase for a multi-item list or
     table as a complete expression.  Do not write "You can set:";
     instead, write "You can set these variables:".  The former
     expression sounds cut off.

Editions, Dates and Versions
............................

Include edition numbers, version numbers, and dates in the '@copying'
text (for people reading the Texinfo file, and for the legal copyright
in the output files).  Then use '@insertcopying' in the '@titlepage'
section for people reading the printed output (*note Short Sample::).

  It is easiest to handle such version information using '@set' and
'@value'.  *Note @value Example::, and *note GNU Sample Texts::.

Definition Commands
...................

Definition commands are '@deffn', '@defun', '@defmac', and the like, and
enable you to write descriptions in a uniform format.

   * Write just one definition command for each entity you define with a
     definition command.  The automatic indexing feature creates an
     index entry that leads the reader to the definition.

   * Use '@table' ... '@end table' in an appendix that contains a
     summary of functions, not '@deffn' or other definition commands.

Capitalization
..............

   * Capitalize "Texinfo"; it is a name.  Do not write the 'x' or 'i' in
     uppercase.

   * Capitalize "Info"; it is a name.

   * Write TeX using the '@TeX{}' command.  Note the uppercase 'T' and
     'X'.  This command causes the formatters to typeset the name
     according to the wishes of Donald Knuth, who wrote TeX.  (Likewise
     '@LaTeX{}' for LaTeX.)

Spaces
......

Do not use spaces to format a Texinfo file, except inside of '@example'
... '@end example' and other literal environments and commands.

  For example, TeX fills the following:

        @kbd{C-x v}
        @kbd{M-x vc-next-action}
           Perform the next logical operation
           on the version-controlled file
           corresponding to the current buffer.

so it looks like this:

     'C-x v' 'M-x vc-next-action' Perform the next logical operation on
     the version-controlled file corresponding to the current buffer.

In this case, the text should be formatted with '@table', '@item', and
'@itemx', to create a table.

@code, @samp, @var, and '---'
.............................

   * Use '@code' around Lisp symbols, including command names.  For
     example,

          The main function is @code{vc-next-action}, ...

   * Avoid putting letters such as 's' immediately after an '@code'.
     Such letters look bad.

   * Use '@var' around meta-variables.  Do not write angle brackets
     around them.

   * Use three hyphens in a row, '---', to indicate a long dash.  TeX
     typesets these as a long dash and the Info formatters reduce three
     hyphens to two.

Periods Outside of Quotes
.........................

Place periods and other punctuation marks _outside_ of quotations,
unless the punctuation is part of the quotation.  This practice goes
against some publishing conventions in the United States, but enables
the reader to distinguish between the contents of the quotation and the
whole passage.

  For example, you should write the following sentence with the period
outside the end quotation marks:

     Evidently, 'au' is an abbreviation for ``author''.

since 'au' does _not_ serve as an abbreviation for 'author.' (with a
period following the word).

Introducing New Terms
.....................

   * Introduce new terms so that a reader who does not know them can
     understand them from context; or write a definition for the term.

     For example, in the following, the terms "check in", "register" and
     "delta" are all appearing for the first time; the example sentence
     should be rewritten so they are understandable.

          The major function assists you in checking in a file to your
          version control system and registering successive sets of
          changes to it as deltas.

   * Use the '@dfn' command around a word being introduced, to indicate
     that the reader should not expect to know the meaning already, and
     should expect to learn the meaning from this passage.

Program Invocation Nodes
........................

You can invoke programs such as Emacs, GCC, and 'gawk' from a shell.
The documentation for each program should contain a section that
describes this.  Unfortunately, if the node names and titles for these
sections are all different, they are difficult for users to find.

  So, there is a convention to name such sections with a phrase
beginning with the word 'Invoking', as in 'Invoking Emacs'; this way,
users can find the section easily.

ANSI C Syntax
.............

When you use '@example' to describe a C function's calling conventions,
use the ANSI C syntax, like this:

     void dld_init (char *@var{path});

And in the subsequent discussion, refer to the argument values by
writing the same argument names, again highlighted with '@var'.

  Avoid the obsolete style that looks like this:

     #include 

     dld_init (path)
       char *path;

  Also, it is best to avoid writing '#include' above the declaration
just to indicate that the function is declared in a header file.  The
practice may give the misimpression that the '#include' belongs near the
declaration of the function.  Either state explicitly which header file
holds the declaration or, better yet, name the header file used for a
group of functions at the beginning of the section that describes the
functions.

Node Length
...........

Keep nodes (sections) to a reasonable length, whatever reasonable might
be in the given context.  Don't hesitate break up long nodes into
subnodes and have an extensive tree structure; that's what it's there
for.  Many times, readers will probably try to find a single specific
point in the manual, using search, indexing, or just plain guessing,
rather than reading the whole thing from beginning to end.

  You can use the 'texi-elements-by-size' utility to see a list of all
nodes (or sections) in the document, sorted by size (either lines or
words), to find candidates for splitting.  It's in the 'util/'
subdirectory of the Texinfo sources.

Bad Examples
............

Here are several examples of bad writing to avoid:

  In this example, say, " ... you must '@dfn'{check in} the new
version."  That flows better.

     When you are done editing the file, you must perform a '@dfn'{check
     in}.

  In the following example, say, "... makes a unified interface such as
VC mode possible."

     SCCS, RCS and other version-control systems all perform similar
     functions in broadly similar ways (it is this resemblance which
     makes a unified control mode like this possible).

  And in this example, you should specify what 'it' refers to:

     If you are working with other people, it assists in coordinating
     everyone's changes so they do not step on each other.

And Finally ...
...............

   * Pronounce TeX as if the 'X' were a Greek 'chi', as the last sound
     in the name 'Bach'.  But pronounce Texinfo as in 'speck':
     "teckinfo".

   * Write notes for yourself at the very end of a Texinfo file after
     the '@bye'.  None of the formatters process text after the '@bye';
     it is as if the text were within '@ignore' ... '@end ignore'.


File: texinfo.info,  Node: Sample Texinfo Files,  Next: Headings,  Prev: Tips,  Up: Top

Appendix C Sample Texinfo Files
*******************************

The first example is from the first chapter (*note Short Sample::),
given here in its entirety, without commentary.  The second includes the
full texts to be used in GNU manuals.

* Menu:

* Short Sample Texinfo File::
* GNU Sample Texts::
* Verbatim Copying License::
* All-permissive Copying License::


File: texinfo.info,  Node: Short Sample Texinfo File,  Next: GNU Sample Texts,  Up: Sample Texinfo Files

C.1 Short Sample
================

Here is a complete, short sample Texinfo file, without any commentary.
You can see this file, with comments, in the first chapter.  *Note Short
Sample::.

  In a nutshell: The 'makeinfo' program transforms a Texinfo source file
such as this into an Info file or HTML; and TeX typesets it for a
printed manual.


     \input texinfo   @c -*-texinfo-*-
     @c %**start of header
     @setfilename sample.info
     @settitle Sample Manual 1.0
     @c %**end of header

     @copying
     This is a short example of a complete Texinfo file.

     Copyright @copyright{} 2015 Free Software Foundation, Inc.
     @end copying

     @titlepage
     @title Sample Title
     @page
     @vskip 0pt plus 1filll
     @insertcopying
     @end titlepage

     @c Output the table of the contents at the beginning.
     @contents

     @ifnottex
     @node Top
     @top GNU Sample

     This manual is for GNU Sample
     (version @value{VERSION}, @value{UPDATED}).
     @end ifnottex

     @menu
     * First Chapter::    The first chapter is the
                           only chapter in this sample.
     * Index::            Complete index.
     @end menu


     @node First Chapter
     @chapter First Chapter

     @cindex chapter, first

     This is the first chapter.
     @cindex index entry, another

     Here is a numbered list.

     @enumerate
     @item
     This is the first item.

     @item
     This is the second item.
     @end enumerate


     @node Index
     @unnumbered Index

     @printindex cp

     @bye


File: texinfo.info,  Node: GNU Sample Texts,  Next: Verbatim Copying License,  Prev: Short Sample Texinfo File,  Up: Sample Texinfo Files

C.2 GNU Sample Texts
====================

Following is a sample Texinfo document with the full texts that should
be used (adapted as necessary) in GNU manuals.

  As well as the legal texts, it also serves as a practical example of
how many elements in a GNU system can affect the manual.  If you're not
familiar with all these different elements, don't worry.  They're not
required and a perfectly good manual can be written without them.
They're included here nonetheless because many manuals do (or could)
benefit from them.

  *Note Short Sample::, for a minimal example of a Texinfo file.  *Note
Beginning a File::, for a full explanation of that minimal example.

  Here are some notes on the example:

   * The '$Id:' comment is for the CVS (),
     RCS (*note (rcs)Top::) and other version control systems, which
     expand it into a string such as:

          $Id: texinfo.texi 6362 2015-06-25 22:48:32Z gavin $

     (This is potentially useful in all sources that use version
     control, not just manuals.)  You may wish to include the '$Id:'
     comment in the '@copying' text, if you want a completely
     unambiguous reference to the documentation source version.

     If you want to literally write $Id$, use '@w': '@w{$}Id$'.
     Unfortunately, this technique does not work in plain text output,
     where it's not clear what should be done.

   * The 'version.texi' in the '@include' command is maintained
     automatically by Automake (*note (automake)Top::).  It sets the
     'VERSION' and 'UPDATED' values used elsewhere.  If your
     distribution doesn't use Automake, but you do use Emacs, you may
     find the time-stamp.el package helpful (*note (emacs)Time
     Stamps::).

   * The '@syncodeindex' command reflects the recommendation to use only
     one index where possible, to make it easier for readers to look up
     index entries.

   * The '@dircategory' is for constructing the Info directory.  *Note
     Installing Dir Entries::, which includes a variety of recommended
     category names.

   * The 'Invoking' node is a GNU standard to help users find the basic
     information about command-line usage of a given program.  *Note
     (standards)Manual Structure Details::.

   * It is best to include the entire GNU Free Documentation License in
     a GNU manual, unless the manual is only a few pages long.  Of
     course this sample is even shorter than that, but it includes the
     FDL anyway in order to show one conventional way to do so.  The
     'fdl.texi' file is available on the GNU machines and in the Texinfo
     and other GNU source distributions.

     The FDL provides for omitting itself under certain conditions, but
     in that case the sample texts given here have to be modified.
     *Note GNU Free Documentation License::.

   * If the FSF is not the copyright holder, then use the appropriate
     name.

   * If your manual is published on paper by the FSF or is longer than
     400 pages, you should include the standard FSF cover texts (*note
     (maintain)License Notices for Documentation::).

   * For documents that express your personal views, feelings or
     experiences, it is more appropriate to use a license permitting
     only verbatim copying, rather than the FDL.  *Note Verbatim Copying
     License::.

  Here is the sample document:

\input texinfo   @c -*-texinfo-*-
@comment $Id@w{$}
@comment %**start of header
@setfilename sample.info
@include version.texi
@settitle GNU Sample @value{VERSION}
@syncodeindex pg cp
@comment %**end of header
@copying
This manual is for GNU Sample (version @value{VERSION}, @value{UPDATED}),
which is an example in the Texinfo documentation.

Copyright @copyright{} 2015 Free Software Foundation, Inc.

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts.  A copy of the license is included in the section entitled
``GNU Free Documentation License''.
@end quotation
@end copying

@dircategory Texinfo documentation system
@direntry
* sample: (sample)Invoking sample.
@end direntry

@titlepage
@title GNU Sample
@subtitle for version @value{VERSION}, @value{UPDATED}
@author A.U. Thor (@email{bug-sample@@gnu.org})
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents

@ifnottex
@node Top
@top GNU Sample

This manual is for GNU Sample (version @value{VERSION}, @value{UPDATED}).
@end ifnottex

@menu
* Invoking sample::
* GNU Free Documentation License::
* Index::
@end menu


@node Invoking sample
@chapter Invoking sample

@pindex sample
@cindex invoking @command{sample}

This is a sample manual.  There is no sample program to
invoke, but if there were, you could see its basic usage
and command line options here.


@node GNU Free Documentation License
@appendix GNU Free Documentation License

@include fdl.texi


@node Index
@unnumbered Index

@printindex cp

@bye


File: texinfo.info,  Node: Verbatim Copying License,  Next: All-permissive Copying License,  Prev: GNU Sample Texts,  Up: Sample Texinfo Files

C.3 Verbatim Copying License
============================

For software manuals and other documentation, it is critical to use a
license permitting free redistribution and updating, so that when a free
program is changed, the documentation can be updated as well.

  On the other hand, for documents that express your personal views,
feelings or experiences, it is more appropriate to use a license
permitting only verbatim copying.

  Here is sample text for such a license permitting verbatim copying
only.  This is just the license text itself.  For a complete sample
document, see the previous sections.

@copying
This document is a sample for allowing verbatim copying only.

Copyright @copyright{} 2015 Free Software Foundation, Inc.

@quotation
Permission is granted to make and distribute verbatim copies
of this entire document without royalty provided the
copyright notice and this permission notice are preserved.
@end quotation
@end copying


File: texinfo.info,  Node: All-permissive Copying License,  Prev: Verbatim Copying License,  Up: Sample Texinfo Files

C.4 All-permissive Copying License
==================================

For software manuals and other documentation, it is important to use a
license permitting free redistribution and updating, so that when a free
program is changed, the documentation can be updated as well.

  On the other hand, for small supporting files, short manuals (under
300 lines long) and rough documentation (README files, INSTALL files,
etc.), the full FDL would be overkill.  They can use a simple
all-permissive license.

  Here is sample text for such an all-permissive license.  This is just
the license text itself.  For a complete sample document, see the
previous sections.

     Copyright @copyright{} 2015 Free Software Foundation, Inc.

     Copying and distribution of this file, with or without modification,
     are permitted in any medium without royalty provided the copyright
     notice and this notice are preserved.


File: texinfo.info,  Node: Headings,  Next: Catching Mistakes,  Prev: Sample Texinfo Files,  Up: Top

Appendix D Page Headings
************************

Most printed manuals contain headings along the top of every page except
the title and copyright pages.  Some manuals also contain footings.
Headings and footings have no meaning in Info or the other output
formats.

* Menu:

* Headings Introduced::         Conventions for using page headings.
* Heading Format::              Standard page heading formats.
* Heading Choice::              How to specify the type of page heading.
* Custom Headings::             How to create your own headings and footings.


File: texinfo.info,  Node: Headings Introduced,  Next: Heading Format,  Up: Headings

D.1 Headings Introduced
=======================

Texinfo provides standard page heading formats for manuals that are
printed on one side of each sheet of paper and for manuals that are
printed on both sides of the paper.  Typically, you will use these
formats, but you can specify your own format if you wish.

  In addition, you can specify whether chapters should begin on a new
page, or merely continue the same page as the previous chapter; and if
chapters begin on new pages, you can specify whether they must be
odd-numbered pages.

  By convention, a book is printed on both sides of each sheet of paper.
When you open a book, the right-hand page is odd-numbered, and chapters
begin on right-hand pages--a preceding left-hand page is left blank if
necessary.  Reports, however, are often printed on just one side of
paper, and chapters begin on a fresh page immediately following the end
of the preceding chapter.  In short or informal reports, chapters often
do not begin on a new page at all, but are separated from the preceding
text by a small amount of whitespace.

  The '@setchapternewpage' command controls whether chapters begin on
new pages, and whether one of the standard heading formats is used.  In
addition, Texinfo has several heading and footing commands that you can
use to generate your own heading and footing formats.

  In Texinfo, headings and footings are single lines at the tops and
bottoms of pages; you cannot create multiline headings or footings.
Each header or footer line is divided into three parts: a left part, a
middle part, and a right part.  Any part, or a whole line, may be left
blank.  Text for the left part of a header or footer line is set
flushleft; text for the middle part is centered; and, text for the right
part is set flushright.


File: texinfo.info,  Node: Heading Format,  Next: Heading Choice,  Prev: Headings Introduced,  Up: Headings

D.2 Standard Heading Formats
============================

Texinfo provides two standard heading formats, one for manuals printed
on one side of each sheet of paper, and the other for manuals printed on
both sides of the paper.

  By default, nothing is specified for the footing of a Texinfo file, so
the footing remains blank.

  The standard format for single-sided printing consists of a header
line in which the left-hand part contains the name of the chapter, the
central part is blank, and the right-hand part contains the page number.

  A single-sided page looks like this:

       _______________________
      |                       |
      | chapter   page number |
      |                       |
      | Start of text ...     |
      | ...                   |
      |                       |

  The standard format for two-sided printing depends on whether the page
number is even or odd.  By convention, even-numbered pages are on the
left- and odd-numbered pages are on the right.  (TeX will adjust the
widths of the left- and right-hand margins.  Usually, widths are
correct, but during double-sided printing, it is wise to check that
pages will bind properly--sometimes a printer will produce output in
which the even-numbered pages have a larger right-hand margin than the
odd-numbered pages.)

  In the standard double-sided format, the left part of the left-hand
(even-numbered) page contains the page number, the central part is
blank, and the right part contains the title (specified by the
'@settitle' command).  The left part of the right-hand (odd-numbered)
page contains the name of the chapter, the central part is blank, and
the right part contains the page number.

  Two pages, side by side as in an open book, look like this:

       _______________________     _______________________
      |                       |   |                       |
      | page number     title |   | chapter   page number |
      |                       |   |                       |
      | Start of text ...     |   | More  text ...        |
      | ...                   |   | ...                   |
      |                       |   |                       |

The chapter name is preceded by the word "Chapter", the chapter number
and a colon.  This makes it easier to keep track of where you are in the
manual.


File: texinfo.info,  Node: Heading Choice,  Next: Custom Headings,  Prev: Heading Format,  Up: Headings

D.3 Specifying the Type of Heading
==================================

TeX does not begin to generate page headings for a standard Texinfo file
until it reaches the '@end titlepage' command.  Thus, the title and
copyright pages are not numbered.  The '@end titlepage' command causes
TeX to begin to generate page headings according to a standard format
specified by the '@setchapternewpage' command that precedes the
'@titlepage' section.

  There are four possibilities:

No '@setchapternewpage' command
     Cause TeX to specify the single-sided heading format, with chapters
     on new pages.  This is the same as '@setchapternewpage on'.

'@setchapternewpage on'
     Specify the single-sided heading format, with chapters on new
     pages.

'@setchapternewpage off'
     Cause TeX to start a new chapter on the same page as the last page
     of the preceding chapter, after skipping some vertical whitespace.
     Also cause TeX to typeset for single-sided printing.  (You can
     override the headers format with the '@headings double' command;
     *note @headings::.)

'@setchapternewpage odd'
     Specify the double-sided heading format, with chapters on new
     pages.

Texinfo lacks an '@setchapternewpage even' command.


File: texinfo.info,  Node: Custom Headings,  Prev: Heading Choice,  Up: Headings

D.4 How to Make Your Own Headings
=================================

You can use the standard headings provided with Texinfo or specify your
own.  By default, Texinfo has no footers, so if you specify them, the
available page size for the main text will be slightly reduced.

  Texinfo provides six commands for specifying headings and footings:
   * '@everyheading' and '@everyfooting' generate page headers and
     footers that are the same for both even- and odd-numbered pages.
   * '@evenheading' and '@evenfooting' command generate headers and
     footers for even-numbered (left-hand) pages.
   * '@oddheading' and '@oddfooting' generate headers and footers for
     odd-numbered (right-hand) pages.

  Write custom heading specifications in the Texinfo file immediately
after the '@end titlepage' command.  You must cancel the predefined
heading commands with the '@headings off' command before defining your
own specifications.

  Here is how to tell TeX to place the chapter name at the left, the
page number in the center, and the date at the right of every header for
both even- and odd-numbered pages:

     @headings off
     @everyheading @thischapter @| @thispage @| @today{}

You need to divide the left part from the central part and the central
part from the right part by inserting '@|' between parts.  Otherwise,
the specification command will not be able to tell where the text for
one part ends and the next part begins.

  Each part can contain text or @-commands.  The text is printed as if
the part were within an ordinary paragraph in the body of the page.  The
@-commands replace themselves with the page number, date, chapter name,
or whatever.

  Here are the six heading and footing commands:

'@everyheading LEFT @| CENTER @| RIGHT'
'@everyfooting LEFT @| CENTER @| RIGHT'
     The 'every' commands specify the format for both even- and
     odd-numbered pages.  These commands are for documents that are
     printed on one side of each sheet of paper, or for documents in
     which you want symmetrical headers or footers.

'@evenheading LEFT @| CENTER @| RIGHT'
'@oddheading LEFT @| CENTER @| RIGHT'
'@evenfooting LEFT @| CENTER @| RIGHT'
'@oddfooting LEFT @| CENTER @| RIGHT'
     The 'even' and 'odd' commands specify the format for even-numbered
     pages and odd-numbered pages.  These commands are for books and
     manuals that are printed on both sides of each sheet of paper.

  Use the '@this...' series of @-commands to provide the names of
chapters and sections and the page number.  You can use the '@this...'
commands in the left, center, or right portions of headers and footers,
or anywhere else in a Texinfo file so long as they are between '@iftex'
and '@end iftex' commands.

  Here are the '@this...' commands:

'@thispage'
     Expands to the current page number.

'@thissectionname'
     Expands to the name of the current section.

'@thissectionnum'
     Expands to the number of the current section.

'@thissection'
     Expands to the number and name of the current section, in the
     format 'Section 1: Title'.

'@thischaptername'
     Expands to the name of the current chapter.

'@thischapternum'
     Expands to the number of the current chapter, or letter of the
     current appendix.

'@thischapter'
     Expands to the number and name of the current chapter, in the
     format 'Chapter 1: Title'.

'@thistitle'
     Expands to the name of the document, as specified by the
     '@settitle' command.

'@thisfile'
     For '@include' files only: expands to the name of the current
     '@include' file.  If the current Texinfo source file is not an
     '@include' file, this command has no effect.  This command does
     _not_ provide the name of the current Texinfo source file unless it
     is an '@include' file.  (*Note Include Files::, for more
     information about '@include' files.)

You can also use the '@today{}' command, which expands to the current
date, in '1 Jan 1900' format.

  Other @-commands and text are printed in a header or footer just as if
they were in the body of a page.  It is useful to incorporate text,
particularly when you are writing drafts:

     @headings off
     @everyheading @emph{Draft!} @| @thispage @| @thischapter
     @everyfooting @| @| Version: 0.27: @today{}

  Beware of overlong titles: they may overlap another part of the header
or footer and blot it out.

  If you have very short chapters and/or sections, several of them can
appear on a single page.  You can specify which chapters and sections
you want '@thischapter', '@thissection' and other such macros to refer
to on such pages as follows:

'@everyheadingmarks REF'
'@everyfootingmarks REF'
     The REF argument can be either 'top' (the '@this...' commands will
     refer to the chapter/section at the top of a page) or 'bottom' (the
     commands will reflect the situation at the bottom of a page).
     These '@every...' commands specify what to do on both even- and
     odd-numbered pages.

'@evenheadingmarks REF'
'@oddheadingmarks REF'
'@evenfootingmarks REF'
'@oddfootingmarks REF'
     These '@even...' and '@odd...' commands specify what to do on only
     even- or odd-numbered pages, respectively.  The REF argument is the
     same as with the '@every...' commands.

  Write these commands immediately after the '@...contents' commands, or
after the '@end titlepage' command if you don't have a table of contents
or if it is printed at the end of your manual.

  By default the '@this...' commands reflect the situation at the bottom
of a page both in headings and in footings.


File: texinfo.info,  Node: Catching Mistakes,  Next: Info Format Specification,  Prev: Headings,  Up: Top

Appendix E Catching Mistakes
****************************

Besides mistakes in the content of your documentation, there are two
kinds of mistake you can make with Texinfo: you can make mistakes with
@-commands, and you can make mistakes with the structure of the nodes
and chapters.

  Emacs has two tools for catching the @-command mistakes and two for
catching structuring mistakes.

  For finding problems with @-commands, you can run TeX or a region
formatting command on the region that has a problem; indeed, you can run
these commands on each region as you write it.

  For finding problems with the structure of nodes and chapters, you can
use 'C-c C-s' ('texinfo-show-structure') and the related 'occur' command
and you can use the 'M-x Info-validate' command.

* Menu:

* makeinfo Preferred::          'makeinfo' finds errors.
* Debugging with Info::         How to catch errors with Info formatting.
* Debugging with TeX::          How to catch errors with TeX formatting.
* Using texinfo-show-structure:: How to use 'texinfo-show-structure'.
* Using occur::                 How to list all lines containing a pattern.
* Running Info-validate::       How to find badly referenced nodes.


File: texinfo.info,  Node: makeinfo Preferred,  Next: Debugging with Info,  Up: Catching Mistakes

E.1 'makeinfo' Preferred
========================

The 'makeinfo' program does an excellent job of catching errors and
reporting them--far better than 'texinfo-format-region' or
'texinfo-format-buffer'.  In addition, the various functions for
automatically creating and updating node pointers and menus remove many
opportunities for human error.

  If you can, use the updating commands to create and insert pointers
and menus.  These prevent many errors.  Then use 'makeinfo' (or its
Texinfo mode manifestations, 'makeinfo-region' and 'makeinfo-buffer') to
format your file and check for other errors.  This is the best way to
work with Texinfo.  But if you cannot use 'makeinfo', or your problem is
very puzzling, then you may want to use the tools described in this
appendix.


File: texinfo.info,  Node: Debugging with Info,  Next: Debugging with TeX,  Prev: makeinfo Preferred,  Up: Catching Mistakes

E.2 Catching Errors with Info Formatting
========================================

After you have written part of a Texinfo file, you can use the
'texinfo-format-region' or the 'makeinfo-region' command to see whether
the region formats properly.

  Most likely, however, you are reading this section because for some
reason you cannot use the 'makeinfo-region' command; therefore, the rest
of this section presumes that you are using 'texinfo-format-region'.

  If you have made a mistake with an @-command, 'texinfo-format-region'
will stop processing at or after the error and display an error message.
To see where in the buffer the error occurred, switch to the '*Info
Region*' buffer; the cursor will be in a position that is after the
location of the error.  Also, the text will not be formatted after the
place where the error occurred (or more precisely, where it was
detected).

  For example, if you accidentally end a menu with the command '@end
menus' with an 's' on the end, instead of with '@end menu', you will see
an error message that says:

     @end menus is not handled by texinfo

The cursor will stop at the point in the buffer where the error occurs,
or not long after it.  The buffer will look like this:

     ---------- Buffer: *Info Region* ----------
     * Menu:

     * Using texinfo-show-structure::  How to use
                                      `texinfo-show-structure'
                                      to catch mistakes.
     * Running Info-validate::         How to check for
                                      unreferenced nodes.
     @end menus
     -!-
     ---------- Buffer: *Info Region* ----------

  The 'texinfo-format-region' command sometimes provides slightly odd
error messages.  For example, the following cross reference fails to
format:

     (@xref{Catching Mistakes, for more info.)

In this case, 'texinfo-format-region' detects the missing closing brace
but displays a message that says 'Unbalanced parentheses' rather than
'Unbalanced braces'.  This is because the formatting command looks for
mismatches between braces as if they were parentheses.

  Sometimes 'texinfo-format-region' fails to detect mistakes.  For
example, in the following, the closing brace is swapped with the closing
parenthesis:

     (@xref{Catching Mistakes), for more info.}

Formatting produces:
     (*Note for more info.: Catching Mistakes)

  The only way for you to detect this error is to realize that the
reference should have looked like this:

     (*Note Catching Mistakes::, for more info.)

  Incidentally, if you are reading this node in Info and type 'f '
('Info-follow-reference'), you will generate an error message that says:

     No such node: "Catching Mistakes) The only way ...

This is because Info perceives the example of the error as the first
cross reference in this node and if you type a  immediately after
typing the Info 'f' command, Info will attempt to go to the referenced
node.  If you type 'f catch  ', Info will complete the node
name of the correctly written example and take you to the 'Catching
Mistakes' node.  (If you try this, you can return from the 'Catching
Mistakes' node by typing 'l' ('Info-last').)


File: texinfo.info,  Node: Debugging with TeX,  Next: Using texinfo-show-structure,  Prev: Debugging with Info,  Up: Catching Mistakes

E.3 Debugging with TeX
======================

You can also catch mistakes when you format a file with TeX.

  Usually, you will want to do this after you have run
'texinfo-format-buffer' (or, better, 'makeinfo-buffer') on the same
file, because 'texinfo-format-buffer' sometimes displays error messages
that make more sense than TeX.  (*Note Debugging with Info::, for more
information.)

  For example, TeX was run on a Texinfo file, part of which is shown
here:

     ---------- Buffer: texinfo.texi ----------
     name of the Texinfo file as an extension.  The
     @samp{??} are `wildcards' that cause the shell to
     substitute all the raw index files.  (@xref{sorting
     indices, for more information about sorting
     indices.)@refill
     ---------- Buffer: texinfo.texi ----------

(The cross reference lacks a closing brace.)  TeX produced the following
output, after which it stopped:

     ---------- Buffer: *tex-shell* ----------
     Runaway argument?
     {sorting indices, for more information about sorting
     indices.) @refill @ETC.
     ! Paragraph ended before @xref was complete.
     
                       @par
     l.27

     ?
     ---------- Buffer: *tex-shell* ----------

  In this case, TeX produced an accurate and understandable error
message:

     Paragraph ended before @xref was complete.

'@par' is an internal TeX command of no relevance to Texinfo.  'l.27'
means that TeX detected the problem on line 27 of the Texinfo file.  The
'?' is the prompt TeX uses in this circumstance.

  Unfortunately, TeX is not always so helpful, and sometimes you must
truly be a Sherlock Holmes to discover what went wrong.

  In any case, if you run into a problem like this, you can do one of
three things.

  1. You can tell TeX to continue running and ignore just this error by
     typing  at the '?' prompt.

  2. You can tell TeX to continue running and to ignore all errors as
     best it can by typing 'r ' at the '?' prompt.

     This is often the best thing to do.  However, beware: the one error
     may produce a cascade of additional error messages as its
     consequences are felt through the rest of the file.  To stop TeX
     when it is producing such an avalanche of error messages, type
     'C-c' (or 'C-c C-c', if you are running a shell inside Emacs).

  3. You can tell TeX to stop this run by typing 'x ' at the '?'
     prompt.

  If you are running TeX inside Emacs, you need to switch to the shell
buffer and line at which TeX offers the '?' prompt.

  Sometimes TeX will format a file without producing error messages even
though there is a problem.  This usually occurs if a command is not
ended but TeX is able to continue processing anyhow.  For example, if
you fail to end an itemized list with the '@end itemize' command, TeX
will write a DVI file that you can print out.  The only error message
that TeX will give you is the somewhat mysterious comment:

     (@end occurred inside a group at level 1)

However, if you print the DVI file, you will find that the text of the
file that follows the itemized list is entirely indented as if it were
part of the last item in the itemized list.  The error message is the
way TeX says that it expected to find an '@end' command somewhere in the
file; but that it could not determine where it was needed.

  Another source of notoriously hard-to-find errors is a missing '@end
group' command.  If you ever are stumped by incomprehensible errors,
look for a missing '@end group' command first.

  If the Texinfo file lacks header lines, TeX may stop in the beginning
of its run and display output that looks like the following.  The '*'
indicates that TeX is waiting for input.

     This is TeX, Version 3.14159 (Web2c 7.0)
     (test.texinfo [1])
     *

In this case, simply type '\end ' after the asterisk.  Then write
the header lines in the Texinfo file and run the TeX command again.
(Note the use of the backslash, '\'.  TeX uses '\' instead of '@'; and
in this circumstance, you are working directly with TeX, not with
Texinfo.)


File: texinfo.info,  Node: Using texinfo-show-structure,  Next: Using occur,  Prev: Debugging with TeX,  Up: Catching Mistakes

E.4 Using 'texinfo-show-structure'
==================================

It is not always easy to keep track of the nodes, chapters, sections,
and subsections of a Texinfo file.  This is especially true if you are
revising or adding to a Texinfo file that someone else has written.

  In GNU Emacs, in Texinfo mode, the 'texinfo-show-structure' command
lists all the lines that begin with the @-commands that specify the
structure: '@chapter', '@section', '@appendix', and so on.  With an
argument ('C-u' as prefix argument, if interactive), the command also
shows the '@node' lines.  The 'texinfo-show-structure' command is bound
to 'C-c C-s' in Texinfo mode, by default.

  The lines are displayed in a buffer called the '*Occur*' buffer,
indented by hierarchical level.  For example, here is a part of what was
produced by running 'texinfo-show-structure' on this manual:

     Lines matching "^@\\(chapter \\|sect\\|subs\\|subh\\|
     unnum\\|major\\|chapheading \\|heading \\|appendix\\)"
     in buffer texinfo.texi.
     ...
     4177:@chapter Nodes
     4198:    @heading Two Paths
     4231:    @section Node and Menu Illustration
     4337:    @section The @code{@@node} Command
     4393:        @subheading Choosing Node and Pointer Names
     4417:        @subsection How to Write an @code{@@node} Line
     4469:        @subsection @code{@@node} Line Tips
     ...

  This says that lines 4337, 4393, and 4417 of 'texinfo.texi' begin with
the '@section', '@subheading', and '@subsection' commands respectively.
If you move your cursor into the '*Occur*' window, you can position the
cursor over one of the lines and use the 'C-c C-c' command
('occur-mode-goto-occurrence'), to jump to the corresponding spot in the
Texinfo file.  *Note Using Occur: (emacs)Other Repeating Search, for
more information about 'occur-mode-goto-occurrence'.

  The first line in the '*Occur*' window describes the "regular
expression" specified by TEXINFO-HEADING-PATTERN.  This regular
expression is the pattern that 'texinfo-show-structure' looks for.
*Note Using Regular Expressions: (emacs)Regexps, for more information.

  When you invoke the 'texinfo-show-structure' command, Emacs will
display the structure of the whole buffer.  If you want to see the
structure of just a part of the buffer, of one chapter, for example, use
the 'C-x n n' ('narrow-to-region') command to mark the region.  (*Note
(emacs)Narrowing::.)  This is how the example used above was generated.
(To see the whole buffer again, use 'C-x n w' ('widen').)

  If you call 'texinfo-show-structure' with a prefix argument by typing
'C-u C-c C-s', it will list lines beginning with '@node' as well as the
lines beginning with the @-sign commands for '@chapter', '@section', and
the like.

  You can remind yourself of the structure of a Texinfo file by looking
at the list in the '*Occur*' window; and if you have mis-named a node or
left out a section, you can correct the mistake.


File: texinfo.info,  Node: Using occur,  Next: Running Info-validate,  Prev: Using texinfo-show-structure,  Up: Catching Mistakes

E.5 Using 'occur'
=================

Sometimes the 'texinfo-show-structure' command produces too much
information.  Perhaps you want to remind yourself of the overall
structure of a Texinfo file, and are overwhelmed by the detailed list
produced by 'texinfo-show-structure'.  In this case, you can use the
'occur' command directly.  To do this, type:

     M-x occur

and then, when prompted, type a "regexp", a regular expression for the
pattern you want to match.  (*Note Regular Expressions: (emacs)Regexps.)
The 'occur' command works from the current location of the cursor in the
buffer to the end of the buffer.  If you want to run 'occur' on the
whole buffer, place the cursor at the beginning of the buffer.

  For example, to see all the lines that contain the word '@chapter' in
them, just type '@chapter'.  This will produce a list of the chapters.
It will also list all the sentences with '@chapter' in the middle of the
line.

  If you want to see only those lines that start with the word
'@chapter', type '^@chapter' when prompted by 'occur'.  If you want to
see all the lines that end with a word or phrase, end the last word with
a '$'; for example, 'catching mistakes$'.  This can be helpful when you
want to see all the nodes that are part of the same chapter or section
and therefore have the same 'Up' pointer.

  *Note Using Occur: (emacs)Other Repeating Search, for more
information.


File: texinfo.info,  Node: Running Info-validate,  Prev: Using occur,  Up: Catching Mistakes

E.6 Finding Badly Referenced Nodes
==================================

You can use the 'Info-validate' command to check whether any of the
'Next', 'Previous', 'Up' or other node pointers fail to point to a node.
This command checks that every node pointer points to an existing node.
The 'Info-validate' command works only on Info files, not on Texinfo
files.

  The 'makeinfo' program validates pointers automatically, so you do not
need to use the 'Info-validate' command if you are using 'makeinfo'.
You only may need to use 'Info-validate' if you are unable to run
'makeinfo' and instead must create an Info file using
'texinfo-format-region' or 'texinfo-format-buffer', or if you write an
Info file from scratch.

* Menu:

* Using Info-validate::         How to run 'Info-validate'.
* Unsplit::                     How to create an unsplit file.
* Tagifying::                   How to tagify a file.
* Splitting::                   How to split a file manually.


File: texinfo.info,  Node: Using Info-validate,  Next: Unsplit,  Up: Running Info-validate

E.6.1 Using 'Info-validate'
---------------------------

To use 'Info-validate', visit the Info file you wish to check and type:

     M-x Info-validate

Note that the 'Info-validate' command requires an uppercase 'I'.  You
may also need to create a tag table before running 'Info-validate'.
*Note Tagifying::.

  If your file is valid, you will receive a message that says "File
appears valid".  However, if you have a pointer that does not point to a
node, error messages will be displayed in a buffer called '*problems in
info file*'.

  For example, 'Info-validate' was run on a test file that contained
only the first node of this manual.  One of the messages said:

     In node "Overview", invalid Next: Texinfo Mode

This meant that the node called 'Overview' had a 'Next' pointer that did
not point to anything (which was true in this case, since the test file
had only one node in it).

  Now suppose we add a node named 'Texinfo Mode' to our test case but we
do not specify a 'Previous' for this node.  Then we will get the
following error message:

     In node "Texinfo Mode", should have Previous: Overview

This is because every 'Next' pointer should be matched by a 'Previous'
(in the node where the 'Next' points) which points back.

  'Info-validate' also checks that all menu entries and cross references
point to actual nodes.

  'Info-validate' requires a tag table and does not work with files that
have been split.  (The 'texinfo-format-buffer' command automatically
splits large files.)  In order to use 'Info-validate' on a large file,
you must run 'texinfo-format-buffer' with an argument so that it does
not split the Info file; and you must create a tag table for the unsplit
file.


File: texinfo.info,  Node: Unsplit,  Next: Tagifying,  Prev: Using Info-validate,  Up: Running Info-validate

E.6.2 Creating an Unsplit File
------------------------------

You can run 'Info-validate' only on a single Info file that has a tag
table.  The command will not work on the indirect subfiles that are
generated when a master file is split.  If you have a large file (longer
than 300,000 bytes or so), you need to run the 'texinfo-format-buffer'
or 'makeinfo-buffer' command in such a way that it does not create
indirect subfiles.  You will also need to create a tag table for the
Info file.  After you have done this, you can run 'Info-validate' and
look for badly referenced nodes.

  The first step is to create an unsplit Info file.  To prevent
'texinfo-format-buffer' from splitting a Texinfo file into smaller Info
files, give a prefix to the 'M-x texinfo-format-buffer' command:

     C-u M-x texinfo-format-buffer

or else

     C-u C-c C-e C-b

When you do this, Texinfo will not split the file and will not create a
tag table for it.


File: texinfo.info,  Node: Tagifying,  Next: Splitting,  Prev: Unsplit,  Up: Running Info-validate

E.6.3 Tagifying a File
----------------------

After creating an unsplit Info file, you must create a tag table for it.
Visit the Info file you wish to tagify and type:

     M-x Info-tagify

(Note the uppercase 'I' in 'Info-tagify'.)  This creates an Info file
with a tag table that you can validate.

  The third step is to validate the Info file:

     M-x Info-validate

(Note the uppercase 'I' in 'Info-validate'.)  In brief, the steps are:

     C-u M-x texinfo-format-buffer
     M-x Info-tagify
     M-x Info-validate

  After you have validated the node structure, you can rerun
'texinfo-format-buffer' in the normal way so it will construct a tag
table and split the file automatically, or you can make the tag table
and split the file manually.


File: texinfo.info,  Node: Splitting,  Prev: Tagifying,  Up: Running Info-validate

E.6.4 Splitting a File Manually
-------------------------------

You should split a large file or else let the 'texinfo-format-buffer' or
'makeinfo-buffer' command do it for you automatically.  (Generally you
will let one of the formatting commands do this job for you.  *Note
Creating an Info File::.)

  The split-off files are called the indirect subfiles.

  Info files are split to save memory.  With smaller files, Emacs does
not have make such a large buffer to hold the information.

  If an Info file has more than 30 nodes, you should also make a tag
table for it.  *Note Using Info-validate::, for information about
creating a tag table.  (Again, tag tables are usually created
automatically by the formatting command; you only need to create a tag
table yourself if you are doing the job manually.  Most likely, you will
do this for a large, unsplit file on which you have run
'Info-validate'.)

  Visit the Info file you wish to tagify and split and type the two
commands:

     M-x Info-tagify
     M-x Info-split

(Note that the 'I' in 'Info' is uppercase.)

  When you use the 'Info-split' command, the buffer is modified into a
(small) Info file which lists the indirect subfiles.  This file should
be saved in place of the original visited file.  The indirect subfiles
are written in the same directory the original file is in, with names
generated by appending '-' and a number to the original file name.

  The primary file still functions as an Info file, but it contains just
the tag table and a directory of subfiles.


File: texinfo.info,  Node: Info Format Specification,  Next: GNU Free Documentation License,  Prev: Catching Mistakes,  Up: Top

Appendix F Info Format Specification
************************************

Here we describe the technical details of the Info format.

  This format definition was written some 25 years after the Info format
was first devised.  So in the event of conflicts between this definition
and actual practice, practice wins.  It also assumes some general
knowledge of Texinfo; it is meant to be a guide for implementors rather
than a rigid technical standard.  We often refer back to other parts of
this manual for examples and definitions, rather than redundantly
spelling out every detail.

  In this formal description, the characters '<>*()|=#' are used for the
language of the description itself.  Other characters are literal.  The
formal constructs used are typical: '<...>' indicates a metavariable
name, '=' means definition, '*' repetition, '?' optional, '()' grouping,
'|' alternation, '#' comment.  Exception: '*' at the beginning of a line
is literal.

  The sections in an Info file (such as nodes or tag tables) are
separated with a sequence:

     (^L)?^_(^L)?^J

That is, a 'CTRL-_' character followed by a newline, with optional
formfeed characters.  We refer to such sequences as .

  We specify literal parentheses (those that are part of the Info
format) with  and , meaning the single characters '('
and ')' respectively.  The two-character sequence '^X' means the single
character 'CTRL-X', for any X.

* Menu:

* General: Info Format General Layout.
* Text:    Info Format Text Constructs.


File: texinfo.info,  Node: Info Format General Layout,  Next: Info Format Text Constructs,  Up: Info Format Specification

F.1 Info Format General Layout
==============================

This section describes the overall layout of Info manuals.

* Menu:

* Whole:           Info Format Whole Manual. Split vs. nonsplit manuals.
* Preamble:        Info Format Preamble.
* Indirect:        Info Format Indirect Table.
* Tag table:       Info Format Tag Table.
* Local variables: Info Format Local Variables.
* Regular nodes:   Info Format Regular Nodes.


File: texinfo.info,  Node: Info Format Whole Manual,  Next: Info Format Preamble,  Up: Info Format General Layout

Info Format: A Whole Manual
---------------------------

To begin, an Info manual is either "nonsplit" (contained wholly within a
single file) or "split" (across several files).

  The syntax for a nonsplit manual is:

          =
     
     *
     ?
     ?

  When split, there is a "main file", which contains only pointers to
the nodes given in other "subfiles".  The main file looks like this:

          =
     
     
     
     ?

  The subfiles in a split manual have the following syntax:

          =
     
     *

  Note that the tag table is not optional for split files, as it is used
with the indirect table to deduce which subfile a particular node is in.


File: texinfo.info,  Node: Info Format Preamble,  Next: Info Format Indirect Table,  Prev: Info Format Whole Manual,  Up: Info Format General Layout

Info Format: Preamble
---------------------

The  is text at the beginning of all output files.  It is not
intended to be visible by default in an Info viewer, but may be
displayed upon user request.

          =
            # "This is FILENAME, produced by ..."
              # Expansion of @copying text.
               # Derived from @dircategory and @direntry.

These pieces are:


     An arbitrary string beginning the output file, followed by a blank
     line.


     The expansion of an '@copying' environment, if the manual has one
     (*note @copying::).


     The result of any '@dircategory' and '@direntry' commands present
     in the manual (*note Installing Dir Entries::).


File: texinfo.info,  Node: Info Format Indirect Table,  Next: Info Format Tag Table,  Prev: Info Format Preamble,  Up: Info Format General Layout

Info Format: Indirect Table
---------------------------

          =
     
     Indirect:
     (: )*

  The indirect table is written to the main file in the case of split
output only.  It specifies, as a decimal integer, the starting byte
position (zero-based) that the first node of each subfile would have if
the subfiles were concatenated together in order, not including the
top-level file.  The first node of actual content is pointed to by the
first entry.

  As an example, suppose split output is generated for the GDB manual.
The top-level file 'gdb.info' will contain something like this:

     
     Indirect:
     gdb.info-1: 1878
     gdb.info-2: 295733
     ...

  This tells Info viewers that the first node of the manual occurs at
byte 1878 of the file 'gdb.info-1' (which would be after that file's
preamble.)  The first node in the 'gdb.info-2' subfile would start at
byte 295733 if 'gdb.info-2' were appended to 'gdb.info-1', including any
preamble sections in both files.

  Unfortunately, Info-creating programs such as 'makeinfo' have not
always implemented these rules perfectly, due to various bugs and
oversights.  Therefore, robust Info viewers should fall back to
searching "nearby" the given position for a node, instead of giving up
immediately if the position is not exactly at a node beginning.


File: texinfo.info,  Node: Info Format Tag Table,  Next: Info Format Local Variables,  Prev: Info Format Indirect Table,  Up: Info Format General Layout

Info Format: Tag Table
----------------------

          =
     
     Tag Table:
     (Indirect)?
     (Node|Ref): ^?
     
     End Tag Table

  The '(Indirect)' line appears in the case of split output only.

  The tag table specifies the starting byte position of each node and
anchor in the file.  In the case of split output, it is only written in
the main output file.

  Each line defines an identifier as either an anchor or a node, as
specified.  For example, 'Node: Top^?1647' says that the node named
'Top' starts at byte 1647 while 'Ref: Overview-Footnote-1^?30045' says
that the anchor named 'Overview-Footnote-1' starts at byte 30045.  It is
an error to define the same identifier both ways.

  In the case of nonsplit output, the byte positions simply refer to the
location in the output file.  In the case of split output, the byte
positions refer to an imaginary file created by concatenating all the
split files (but not the top-level file).  See the previous section.

  Here is an example:

     ^_
     Tag Table:
     Node: Top^?89
     Node: Ch1^?292
     ^_
     End Tag Table

This specifies a manual with two nodes, 'Top' and 'Ch1', at byte
positions 89 and 292 respectively.  Because the '(Indirect)' line is not
present, the manual is not split.

  Preamble sections or other non-node sections of files do not have a
tag table entry.


File: texinfo.info,  Node: Info Format Local Variables,  Next: Info Format Regular Nodes,  Prev: Info Format Tag Table,  Up: Info Format General Layout

Info Format: Local Variables
----------------------------

The local variables section is optional and is currently used to give
the encoding information.  It may be augmented in the future.

          =
     
     Local Variables:
     coding: 
     End:

  *Note @documentencoding::.


File: texinfo.info,  Node: Info Format Regular Nodes,  Prev: Info Format Local Variables,  Up: Info Format General Layout

Info Format: Regular Nodes
--------------------------

Regular nodes look like this:

          =
     
     File: , Node: , (Next: , )? (Prev: , )? Up: 

     

At least one space or tab must be present after each colon and comma,
but any number of spaces are ignored.  The  node identifiers have
following format:

          = ()?()?

  This  defines  in file , which is typically either
'manualname' or 'manualname.info'.  No parenthesized 
component may appear within .

  Each of the identifiers after 'Next', 'Prev' and 'Up' refer to nodes
or anchors within a file.  These pointers normally refer within the same
file, but '(dir)' is often used to point to the top-level dir file.  If
an  component is used then the node name may be omitted, in
which case the node identifier refers to the 'Top' node within the
referenced file.

  The 'Next' and 'Prev' pointers are optional.  The 'Up' pointer is
technically also optional, although most likely this indicates a mistake
in the node structuring.  Conventionally, the nodes are arranged to form
a tree, but this is not a requirement of the format.

  Node names containing periods, commas, colons or parentheses
(including @-commands which produce any of these) can confuse Info
readers.  *Note Node Line Requirements::.

  The use of non-ASCII characters in the names of nodes is permitted,
but can cause problems in cross-references between nodes in Info files
with different character encodings, and also when node names from many
different files are listed (for example, with the '--apropos' option to
the standalone Info browser), so we recommend avoiding them whenever
feasible.  For example, prefer the use of the ASCII apostrophe character
(') to Unicode directional quotes.

  The  of the node can include the special constructs
described next.


File: texinfo.info,  Node: Info Format Text Constructs,  Prev: Info Format General Layout,  Up: Info Format Specification

F.2 Info Format Text Constructs
===============================

These special Info constructs can appear within the text of a node.

* Menu:

* Menu:  Info Format Menu.
* Image: Info Format Image.
* Printindex: Info Format Printindex.
* Xref:  Info Format Cross Reference.


File: texinfo.info,  Node: Info Format Menu,  Next: Info Format Image,  Up: Info Format Text Constructs

F.2.1 Info Format: Menu
-----------------------

Conventionally menus appear at the end of nodes, but the Info format
places no restrictions on their location.

          =
     * Menu:
     ( | )*

  The parts of a  are also described in *note Menu Parts::.
They have the same syntax as cross-references (*note Info Format Cross
Reference::).  Indices extend the menu format to specify the destination
line; *note Info Format Printindex::.

  A  is any line not beginning with '*' that appears
either at the beginning of the menu or is separated from a menu entry by
one or more blank lines.  These comments are intended to be displayed as
part of the menu, as-is (*note Writing a Menu::).


File: texinfo.info,  Node: Info Format Image,  Next: Info Format Printindex,  Prev: Info Format Menu,  Up: Info Format Text Constructs

F.2.2 Info Format: Image
------------------------

The '@image' command results in the following special directive within
the Info file (*note Images::):

          =
     ^@^H[image src=""
                 (text="")?
                 (alt="")?
     ^@^H]

  The line breaks and indentation in this description are editorial; the
whitespace between the different parts of the directive in Info files is
arbitrary.

  In the strings ,  and , '"'
is quoted as '\"' and '\' is quoted as '\\'.  The txt and alt
specifications are optional.

  The alt value serves the same purpose as in HTML: A prose description
of the image.  In text-only displays or speech systems, for example, the
alt value may be used instead of displaying the (typically graphical)
.

  The , if present, should be taken as an ASCII
representation of the image, for possible use on a text-only display.

  The format does not prescribe the choice between displaying the , the  or the .


File: texinfo.info,  Node: Info Format Printindex,  Next: Info Format Cross Reference,  Prev: Info Format Image,  Up: Info Format Text Constructs

F.2.3 Info Format: Printindex
-----------------------------

Indices in Info format are generally written as a menu (*note
Indices::), but with an additional directive at the beginning marking
this as an index node:

          =
     ^@^H[index^@^H]
     * Menu:

     *

  The  items are similar to normal menu entries, but the
free-format description is replaced by the line number of where the
entries occurs in the text:

          =
     * : . line 

The  is the index term.  The  is an unsigned
integer, given relative to the start of the .  There may be
arbitrary whitespace after the colon and period, as usual in menus, and
may be broken across lines.  Here is an example:

     ^@^H[index^@^H]
     * Menu:

     * thunder:           Weather Phenomena.             (line 5)

  This means that an index entry for 'thunder' appears at line 5 of the
node 'Weather Phenomena'.


File: texinfo.info,  Node: Info Format Cross Reference,  Prev: Info Format Printindex,  Up: Info Format Text Constructs

F.2.4 Info Format: Cross Reference
----------------------------------

A general cross reference in Info format has one of the following two
forms:

          =
       * (N|n)ote ::
     | * (N|n)ote