diff options
| author | Karl Berry <karl@freefriends.org> | 2006-01-03 00:03:41 +0000 |
|---|---|---|
| committer | Karl Berry <karl@freefriends.org> | 2006-01-03 00:03:41 +0000 |
| commit | ed761d546905fa3c52013c1075865991b5f485ff (patch) | |
| tree | ce0129220c44a6e522cf73525cf50aa7d89be0c8 /Master/texmf/doc | |
| parent | 190e50abeda2127720c100ad282c55a4bd332cf3 (diff) | |
trunk/Master/texmf/doc/texinfo/
git-svn-id: svn://tug.org/texlive/trunk@60 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf/doc')
| -rw-r--r-- | Master/texmf/doc/texinfo/info-stnd.html | 2463 | ||||
| -rw-r--r-- | Master/texmf/doc/texinfo/info-stnd.pdf | bin | 0 -> 366035 bytes | |||
| -rw-r--r-- | Master/texmf/doc/texinfo/info.html | 1534 | ||||
| -rw-r--r-- | Master/texmf/doc/texinfo/info.pdf | bin | 0 -> 229224 bytes | |||
| -rw-r--r-- | Master/texmf/doc/texinfo/texinfo.html | 19883 | ||||
| -rw-r--r-- | Master/texmf/doc/texinfo/texinfo.pdf | bin | 0 -> 1603231 bytes |
6 files changed, 23880 insertions, 0 deletions
diff --git a/Master/texmf/doc/texinfo/info-stnd.html b/Master/texmf/doc/texinfo/info-stnd.html new file mode 100644 index 00000000000..3e227d9a42f --- /dev/null +++ b/Master/texmf/doc/texinfo/info-stnd.html @@ -0,0 +1,2463 @@ +<html lang="en"> +<head> +<title>GNU Info 4.7</title> +<meta http-equiv="Content-Type" content="text/html"> +<meta name="description" content="GNU Info 4.7"> +<meta name="generator" content="makeinfo 4.7"> +<link title="Top" rel="top" href="#Top"> +<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> +<!-- +This manual is for GNU Info (version 4.7, 23 March 2004), +a program for viewing documents in Info format (usually created from +Texinfo source files). + +Copyright (C) 1992, 1993, 1996, 1997, 1998, 1999, 2001, 2002, +2003, 2004 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation License, + Version 1.1 or any later version published by the Free Software + Foundation; with no Invariant Sections, with the Front-Cover texts + being "A GNU Manual," and with the Back-Cover Texts as in (a) + below. A copy of the license is included in the section entitled + "GNU Free Documentation License." + + (a) The FSF's Back-Cover Text is: "You have freedom to copy and + modify this GNU Manual, like GNU software. Copies published by + the Free Software Foundation raise funds for GNU development." + --> +<meta http-equiv="Content-Style-Type" content="text/css"> +<style type="text/css"><!-- + pre.display { font-family:inherit } + pre.format { font-family:inherit } + pre.smalldisplay { font-family:inherit; font-size:smaller } + pre.smallformat { font-family:inherit; font-size:smaller } + pre.smallexample { font-size:smaller } + pre.smalllisp { font-size:smaller } + span.sc { font-variant:small-caps } + span.roman { font-family: serif; font-weight: normal; } +--></style> +</head> +<body> +<h1 class="settitle">GNU Info 4.7</h1> + <div class="contents"> +<h2>Table of Contents</h2> +<ul> +<li><a name="toc_Top" href="#Top">GNU Info</a> +<li><a name="toc_What-is-Info" href="#What-is-Info">1 What is Info?</a> +<li><a name="toc_Invoking-Info" href="#Invoking-Info">2 Invoking Info</a> +<li><a name="toc_Cursor-Commands" href="#Cursor-Commands">3 Moving the Cursor</a> +<li><a name="toc_Scrolling-Commands" href="#Scrolling-Commands">4 Moving Text Within a Window</a> +<li><a name="toc_Node-Commands" href="#Node-Commands">5 Selecting a Node</a> +<li><a name="toc_Searching-Commands" href="#Searching-Commands">6 Searching an Info File</a> +<li><a name="toc_Xref-Commands" href="#Xref-Commands">7 Selecting Cross References</a> +<ul> +<li><a href="#Parts-of-an-Xref">7.1 Parts of an Xref</a> +<li><a href="#Selecting-Xrefs">7.2 Selecting Xrefs</a> +</li></ul> +<li><a name="toc_Window-Commands" href="#Window-Commands">8 Manipulating Multiple Windows</a> +<ul> +<li><a href="#The-Mode-Line">8.1 The Mode Line</a> +<li><a href="#Basic-Windows">8.2 Window Commands</a> +<li><a href="#The-Echo-Area">8.3 The Echo Area</a> +</li></ul> +<li><a name="toc_Printing-Nodes" href="#Printing-Nodes">9 Printing Nodes</a> +<li><a name="toc_Miscellaneous-Commands" href="#Miscellaneous-Commands">10 Miscellaneous Commands</a> +<li><a name="toc_Variables" href="#Variables">11 Manipulating Variables</a> +<li><a name="toc_Custom-Key-Bindings" href="#Custom-Key-Bindings">12 Customizing Key Bindings and Variables</a> +<ul> +<li><a href="#Invoking-infokey">12.1 Invoking <span class="command">infokey</span></a> +<li><a href="#infokey-source-format">12.2 <span class="command">infokey</span> source format</a> +</li></ul> +<li><a name="toc_Copying-This-Manual" href="#Copying-This-Manual">Appendix A Copying This Manual</a> +<ul> +<li><a href="#GNU-Free-Documentation-License">A.1 GNU Free Documentation License</a> +<ul> +<li><a href="#GNU-Free-Documentation-License">A.1.1 ADDENDUM: How to use this License for your documents</a> +</li></ul> +</li></ul> +<li><a name="toc_Index" href="#Index">Appendix B Index</a> +</li></ul> +</div> + + + +<div class="node"> +<p><hr> +<a name="Top"></a>Next: <a rel="next" accesskey="n" href="#What-is-Info">What is Info</a>, +Up: <a rel="up" accesskey="u" href="#dir">(dir)</a> +<br> +</div> + +<h2 class="unnumbered">GNU Info</h2> + +<p>This manual is for GNU Info (version 4.7, 23 March 2004), +a program for viewing documents in Info format (usually created from +Texinfo source files). + + <p>Copyright © 1992, 1993, 1996, 1997, 1998, 1999, 2001, 2002, +2003, 2004 Free Software Foundation, Inc. + + <blockquote> +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.1 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover texts being “A GNU Manual,” +and with the Back-Cover Texts as in (a) below. A copy of the +license is included in the section entitled “GNU Free Documentation +License.” + + <p>(a) The FSF's Back-Cover Text is: “You have freedom to copy and modify +this GNU Manual, like GNU software. Copies published by the Free +Software Foundation raise funds for GNU development.” +</blockquote> + + <p>This documentation is different from the documentation for the Info +reader that is part of GNU Emacs. If you do not know how to use Info, +but have a working Info reader, you should read the Emacs documentation +first, as it includes more background information and a thorough tutorial. + +<ul class="menu"> +<li><a accesskey="1" href="#What-is-Info">What is Info</a>: What is Info? +<li><a accesskey="2" href="#Invoking-Info">Invoking Info</a>: Options you can pass on the command line. +<li><a accesskey="3" href="#Cursor-Commands">Cursor Commands</a>: Commands which move the cursor within a node. +<li><a accesskey="4" href="#Scrolling-Commands">Scrolling Commands</a>: Commands for reading the text within a node. +<li><a accesskey="5" href="#Node-Commands">Node Commands</a>: Commands for selecting a new node. +<li><a accesskey="6" href="#Searching-Commands">Searching Commands</a>: Commands for searching an Info file. +<li><a accesskey="7" href="#Xref-Commands">Xref Commands</a>: Commands for selecting cross references. +<li><a accesskey="8" href="#Window-Commands">Window Commands</a>: Commands which manipulate multiple windows. +<li><a accesskey="9" href="#Printing-Nodes">Printing Nodes</a>: How to print out the contents of a node. +<li><a href="#Miscellaneous-Commands">Miscellaneous Commands</a>: A few commands that defy categories. +<li><a href="#Variables">Variables</a>: How to change the default behavior of Info. +<li><a href="#Custom-Key-Bindings">Custom Key Bindings</a>: How to define your own key-to-command bindings. +<li><a href="#Copying-This-Manual">Copying This Manual</a>: The GNU Free Documentation License. +<li><a href="#Index">Index</a>: Global index containing keystrokes, + command names, variable names, + and general concepts. +</ul> + +<div class="node"> +<p><hr> +<a name="What-is-Info"></a>Next: <a rel="next" accesskey="n" href="#Invoking-Info">Invoking Info</a>, +Previous: <a rel="previous" accesskey="p" href="#Top">Top</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> +<br> +</div> + +<h2 class="chapter">1 What is Info?</h2> + +<p><dfn>Info</dfn> is a program which is used to view Info files on an ASCII +terminal. <dfn>Info files</dfn> are the result of processing Texinfo files +with the program <code>makeinfo</code> or with one of the Emacs commands, such +as <code>M-x texinfo-format-buffer</code>. Texinfo itself is a documentation +system that uses a single source file to produce both on-line +information and printed output. You can typeset and print the files +that you read in Info. + +<div class="node"> +<p><hr> +<a name="Invoking-Info"></a>Next: <a rel="next" accesskey="n" href="#Cursor-Commands">Cursor Commands</a>, +Previous: <a rel="previous" accesskey="p" href="#What-is-Info">What is Info</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> +<br> +</div> + +<h2 class="chapter">2 Invoking Info</h2> + +<p><a name="index-Info_002c-invoking-1"></a><a name="index-invoking-Info-2"></a><a name="index-command-line-options-3"></a><a name="index-options_002c-command-line-4"></a><a name="index-arguments_002c-command-line-5"></a> +GNU Info accepts several options to control the initial node being +viewed, and to specify which directories to search for Info files. Here +is a template showing an invocation of GNU Info from the shell: + +<pre class="example"> info [<var>option</var>]... [<var>menu-item</var>...] +</pre> + <p>The program accepts the following options: + + <dl> +<a name="_002d_002dapropos"></a> +<dt><code>--apropos=</code><var>string</var><dd><a name="index-Searching-all-indices-6"></a><a name="index-Info-files_0040r_007b_002c-searching-all-indices_007d-7"></a><a name="index-Apropos_0040r_007b_002c-in-Info-files_007d-8"></a>Specify a string to search in every index of every Info file installed +on your system. Info looks up the named <var>string</var> in all the indices +it can find, prints the results to standard output, and then exits. If +you are not sure which Info file explains certain issues, this option is +your friend. Note that if your system has a lot of Info files +installed, searching all of them might take some time. + + <p>You can invoke the apropos command from inside Info; see +<a href="#Searching-Commands">Searching Commands</a>. + + <p><a name="index-directory-path-9"></a><br><dt><code>--directory </code><var>directory-path</var><dt><code>-d </code><var>directory-path</var><dd>Prepend <var>directory-path</var> to the list of directory paths searched +when Info needs to find a file. You may issue <code>--directory</code> +multiple times; once for each directory which contains Info files. The +list of directories searched by Info is constructed from the value of +the environment variable <code>INFOPATH</code>; <code>--directory</code> causes the +named <var>directory-path</var> to be prepended to that list. The value of +<code>INFOPATH</code> is a list of directories usually separated by a colon; +on MS-DOS/MS-Windows systems, the semicolon is used. If you do not +define <code>INFOPATH</code>, Info uses a default path defined when Info was +built as the initial list of directories. If the value of +<code>INFOPATH</code> ends with a colon (or semicolon on MS-DOS/MS-Windows), +the initial list of directories is constructed by appending the +build-time default to the value of <code>INFOPATH</code>. + + <p><a name="index-keystrokes_002c-recording-10"></a><a name="index-remembering-user-keystrokes-11"></a><br><dt><code>--dribble=</code><var>dribble-file</var><dd>Specify a file where all user keystrokes will be recorded. This file +can be used later to replay the same sequence of commands, see the +<span class="samp">--restore</span> option below. + + <br><dt><code>--file </code><var>filename</var><dt><code>-f </code><var>filename</var><dd><a name="index-Info-file_002c-selecting-12"></a>Specify a particular Info file to visit. By default, Info visits +the file <code>dir</code>; if you use this option, Info will start with +<code>(</code><var>filename</var><code>)Top</code> as the first file and node. + + <p><a name="index-relative-Info-file-names-13"></a><a name="index-file-names_002c-relative-14"></a><a name="index-Info-files_002c-relative-15"></a>If <var>filename</var> is an absolute file name, or begins with <span class="file">./</span> or +<span class="file">../</span>, Info looks for <var>filename</var> only in the directory of the +specified <var>filename</var>, and adds the directory of <var>filename</var> to +the value of <code>INFOPATH</code>. In contrast, if <var>filename</var> is in the +form of a relative file name, but without the <span class="file">./</span> or <span class="file">../</span> +prefix, Info will only look for it in the directories specified in +<code>INFOPATH</code>. In other words, Info does <em>not</em> treat file names +which lack <span class="file">./</span> and <span class="file">../</span> prefix as relative to the current +directory. + + <p><a name="index-compressed-Info-files-16"></a><a name="index-files_002c-compressed-17"></a><a name="index-Info-files_002c-compressed-18"></a>In every directory Info tries, if <var>filename</var> is not found, Info +looks for it with a number of known extensions of Info files<a rel="footnote" href="#fn-1" name="fnd-1"><sup>1</sup></a>. For every +known extension, Info looks for a compressed file, if a regular file +isn't found. Info supports files compressed with <code>gzip</code>, +<code>bzip2</code>, <code>compress</code> and <code>yabba</code> programs; it calls +<code>gunzip</code>, <code>bunzip2</code>, <code>uncompress</code> and <code>unyabba</code>, +accordingly, to decompress such files. Compressed Info files are +assumed to have <span class="file">.z</span>, <span class="file">.gz</span>, <span class="file">.bz2</span>, <span class="file">.Z</span>, or +<span class="file">.Y</span> extensions, possibly in addition to one of the known Info +files extensions<a rel="footnote" href="#fn-2" name="fnd-2"><sup>2</sup></a>. + + <br><dt><code>--help</code><dt><code>-h</code><dd>Produces a relatively brief description of the available Info options. + + <br><dt><code>--index-search </code><var>string</var><dd><a name="index-index-search_002c-selecting-from-the-command-line-19"></a><a name="index-online-help_002c-using-Info-as-20"></a>After processing all command-line arguments, go to the index in the Info +file and search for index entries which match <var>string</var>. If such an +entry is found, the Info session begins with displaying the node pointed +to by the first matching index entry; press <kbd>,</kbd> to step through the +rest of the matching entries. If no such entry exists, print <span class="samp">no +entries found</span> and exit with nonzero status. This can be used from +another program as a way to provide online help, or as a quick way of +starting to read an Info file at a certain node when you don't know the +exact name of that node. + + <p>This command can also be invoked from inside Info; see <a href="#Searching-Commands">Searching Commands</a>. + + <br><dt><code>--node </code><var>nodename</var><dt><code>-n </code><var>nodename</var><dd><a name="index-node_002c-selecting-from-the-command-line-21"></a>Specify a particular node to visit in the initial file that Info +loads. This is especially useful in conjunction with +<code>--file</code><a rel="footnote" href="#fn-3" name="fnd-3"><sup>3</sup></a>. You may specify <code>--node</code> multiple times; for +an interactive Info, each <var>nodename</var> is visited in its own window, +for a non-interactive Info (such as when <code>--output</code> is given) each +<var>nodename</var> is processed sequentially. + + <br><dt><code>--output </code><var>filename</var><dt><code>-o </code><var>filename</var><dd><a name="index-file_002c-outputting-to-22"></a><a name="index-outputting-to-a-file-23"></a>Specify <var>filename</var> as the name of a file to which to direct output. +Each node that Info visits will be output to <var>filename</var> instead of +interactively viewed. A value of <code>-</code> for <var>filename</var> specifies +the standard output. + + <p><a name="index-colors-in-documents-24"></a><a name="index-ANSI-escape-sequences-in-documents-25"></a><br><dt><code>--raw-escapes</code><dt><code>--no-raw-escapes</code><dt><code>-R</code><dd>Do not remove ANSI escape sequences from documents. Some versions of +Groff, the GNU document formatter, produce man pages with ANSI escape +sequences for bold, italics, and underlined characters, and for +colorized text. By default, Info lets those escape sequences pass +through directly to the terminal. If your terminal does not support +these escapes, use <code>--no-raw-escapes</code> to make Info remove them. + + <p><a name="index-replaying-recorded-keystrokes-26"></a><br><dt><code>--restore=</code><var>dribble-file</var><dd>Read keystrokes from <var>dribble-file</var>, presumably recorded during +previous Info session (see the description of the <span class="samp">--dribble</span> +option above). When the keystrokes in the files are all read, Info +reverts its input to the usual interactive operation. + + <p><a name="_002d_002dshow_002doptions"></a> +<a name="index-command_002dline-options_002c-how-to-find-27"></a><a name="index-invocation-description_002c-how-to-find-28"></a><br><dt><code>--show-options</code><dt><code>--usage</code><dt><code>-O</code><dd>This option causes Info to look for the node that describes how to +invoke the program and its command-line options, and begin the session +by displaying that node. It is provided to make it easier to find the +most important usage information in a manual without the need to wade +through complex menu hierarchies. The effect is similar to the +<code>M-x goto-invocation</code> command (see <a href="#goto_002dinvocation">goto-invocation</a>) from inside +Info. + + <p><a name="index-speech-synthesizers-29"></a><br><dt><code>--speech-friendly</code><dt><code>-b</code><dd>On MS-DOS/MS-Windows only, this option causes Info to use standard file +I/O functions for screen writes. (By default, Info uses direct writes +to the video memory on these systems, for faster operation and colored +display support.) This allows the speech synthesizers used by blind +persons to catch the output and convert it to audible speech. + + <br><dt><code>--subnodes</code><dd><a name="index-_0040code_007b_002d_002dsubnodes_007d_002c-command-line-option-30"></a>This option only has meaning when given in conjunction with +<code>--output</code>. It means to recursively output the nodes appearing in +the menus of each node being output. Menu items which resolve to +external Info files are not output, and neither are menu items which are +members of an index. Each node is only output once. + + <br><dt><code>--version</code><dd><a name="index-version-information-31"></a>Prints the version information of Info and exits. + + <p><a name="_002d_002dvi_002dkeys"></a> +<a name="index-vi_002dlike-key-bindings-32"></a><a name="index-Less_002dlike-key-bindings-33"></a><br><dt><code>--vi-keys</code><dd>This option binds functions to keys differently, to emulate the key +bindings of <code>vi</code> and Less. The default key bindings are generally +modeled after Emacs. +(See <a href="#Custom-Key-Bindings">Custom Key Bindings</a>, +for a more general way of altering GNU Info's key bindings.) + + <p><a name="index-Info-manual-location-34"></a><a name="index-Where-is-an-Info-manual_003f-35"></a><br><dt><code>--where</code><dt><code>--location</code><dt><code>-w</code><dd>Show the filename that would be read and exit, instead of actually +reading it and starting Info. + + <br><dt><var>menu-item</var><dd><a name="index-menu_002c-following-36"></a><a name="command_002dline-menu-items"></a> +Info treats its remaining arguments as the names of menu items. The +first argument is a menu item in the initial node visited (generally +<code>dir</code>), the second argument is a menu item in the first argument's +node, etc. You can easily move to the node of your choice by specifying +the menu names which describe the path to that node. For example, + + <pre class="example"> info emacs buffers + </pre> + <p class="noindent">first selects the menu item <span class="samp">Emacs</span> in the node <span class="samp">(dir)Top</span>, +and then selects the menu item <span class="samp">Buffers</span> in the node +<span class="samp">(emacs)Top</span>. +</dl> + + <p>To avoid searching the <span class="file">dir</span> files and just show some arbitrary +file, use <span class="samp">-f</span> and the filename, as in <span class="samp">info -f ./foo.info</span>. + + <p>The index search and the search for the node which describes program +invocation and command-line options begins <em>after</em> processing all +the command-line menu items. Therefore, the Info file searched for the +index or the invocation node is the file where Info finds itself after +following all the menu items given on the command line. This is so +<span class="samp">info emacs --show-options</span> does what you'd expect. + +<!-- FIXME: the feature with lowercasing the file name isn't documented --> +<div class="node"> +<p><hr> +<a name="Cursor-Commands"></a>Next: <a rel="next" accesskey="n" href="#Scrolling-Commands">Scrolling Commands</a>, +Previous: <a rel="previous" accesskey="p" href="#Invoking-Info">Invoking Info</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> +<br> +</div> + +<h2 class="chapter">3 Moving the Cursor</h2> + +<p><a name="index-cursor_002c-moving-37"></a><a name="index-moving-the-cursor-38"></a> +Many people find that reading screens of text page by page is made +easier when one is able to indicate particular pieces of text with +some kind of pointing device. Since this is the case, GNU Info (both +the Emacs and standalone versions) have several commands which allow +you to move the cursor about the screen. The notation used in this +manual to describe keystrokes is identical to the notation used within +the Emacs manual, and the GNU Readline manual. See <a href="emacs.html#User-Input">User Input (the GNU Emacs Manual)</a>, if you are unfamiliar with the +notation.<a rel="footnote" href="#fn-4" name="fnd-4"><sup>4</sup></a> + + <p>The following table lists the basic cursor movement commands in Info. +Each entry consists of the key sequence you should type to execute the +cursor movement, the <code>M-x</code><a rel="footnote" href="#fn-5" name="fnd-5"><sup>5</sup></a> command name (displayed in parentheses), and a short +description of what the command does. All of the cursor motion commands +can take a <dfn>numeric</dfn> argument (see <a href="#Miscellaneous-Commands"><code>universal-argument</code></a>. With a +numeric argument, the motion commands are simply executed that +many times; for example, a numeric argument of 4 given to +<code>next-line</code> causes the cursor to move down 4 lines. With a +negative numeric argument, the motion is reversed; an argument of -4 +given to the <code>next-line</code> command would cause the cursor to move +<em>up</em> 4 lines. + + <dl> +<dt><C-n> (<code>next-line</code>)<dt><DOWN> (an arrow key)<dd><a name="index-C_002dn-39"></a><a name="index-DOWN-_0028an-arrow-key_0029-40"></a><a name="index-next_002dline-41"></a>Move the cursor down to the next line. + + <br><dt><C-p> (<code>prev-line</code>)<dt><UP> (an arrow key)<dd><a name="index-C_002dp-42"></a><a name="index-UP-_0028an-arrow-key_0029-43"></a><a name="index-prev_002dline-44"></a>Move the cursor up to the previous line. + + <br><dt><C-a> (<code>beginning-of-line</code>)<dt><Home> (on DOS/Windows only)<dd><a name="index-C_002da_002c-in-Info-windows-45"></a><a name="index-Home-46"></a><a name="index-beginning_002dof_002dline-47"></a>Move the cursor to the start of the current line. + + <br><dt><C-e> (<code>end-of-line</code>)<dt><End> (on DOS/Windows only)<dd><a name="index-C_002de_002c-in-Info-windows-48"></a><a name="index-End-49"></a><a name="index-end_002dof_002dline-50"></a>Move the cursor to the end of the current line. + + <br><dt><C-f> (<code>forward-char</code>)<dt><RIGHT> (an arrow key)<dd><a name="index-C_002df_002c-in-Info-windows-51"></a><a name="index-RIGHT-_0028an-arrow-key_0029-52"></a><a name="index-forward_002dchar-53"></a>Move the cursor forward a character. + + <br><dt><C-b> (<code>backward-char</code>)<dt><LEFT> (an arrow key)<dd><a name="index-C_002db_002c-in-Info-windows-54"></a><a name="index-LEFT-_0028an-arrow-key_0029-55"></a><a name="index-backward_002dchar-56"></a>Move the cursor backward a character. + + <br><dt><M-f> (<code>forward-word</code>)<dt><kbd>C-<RIGHT></kbd> (on DOS/Windows only)<dd><a name="index-M_002df_002c-in-Info-windows-57"></a><a name="index-C_002dRIGHT-58"></a><a name="index-forward_002dword-59"></a>Move the cursor forward a word. + + <br><dt><M-b> (<code>backward-word</code>)<dt><kbd>C-<LEFT></kbd> (on DOS/Windows only)<dd><a name="index-M_002db_002c-in-Info-windows-60"></a><a name="index-C_002dLEFT-61"></a><a name="index-backward_002dword-62"></a>Move the cursor backward a word. + + <br><dt><M-<> (<code>beginning-of-node</code>)<dt><C-<Home>> (on DOS/Windows only)<dt><b><dt><M-b>, vi-like operation<dd><a name="index-b_002c-in-Info-windows-63"></a><a name="index-M_002d_003c-64"></a><a name="index-C_002dHome-65"></a><a name="index-M_002db_002c-vi_002dlike-operation-66"></a><a name="index-beginning_002dof_002dnode-67"></a>Move the cursor to the start of the current node. + + <br><dt><M->> (<code>end-of-node</code>)<dt><C-<End>> (on DOS/Windows only)<dt><e><dd><a name="index-M_002d_003e-68"></a><a name="index-e_002c-in-Info-windows-69"></a><a name="index-C_002dEnd-70"></a><a name="index-end_002dof_002dnode-71"></a>Move the cursor to the end of the current node. + + <br><dt><M-r> (<code>move-to-window-line</code>)<dd><a name="index-M_002dr-72"></a><a name="index-move_002dto_002dwindow_002dline-73"></a>Move the cursor to a specific line of the window. Without a numeric +argument, <code>M-r</code> moves the cursor to the start of the line in the +center of the window. With a numeric argument of <var>n</var>, <code>M-r</code> +moves the cursor to the start of the <var>n</var>th line in the window. +</dl> + +<div class="node"> +<p><hr> +<a name="Scrolling-Commands"></a>Next: <a rel="next" accesskey="n" href="#Node-Commands">Node Commands</a>, +Previous: <a rel="previous" accesskey="p" href="#Cursor-Commands">Cursor Commands</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> +<br> +</div> + +<h2 class="chapter">4 Moving Text Within a Window</h2> + +<p><a name="index-scrolling-74"></a> +Sometimes you are looking at a screenful of text, and only part of the +current paragraph you are reading is visible on the screen. The +commands detailed in this section are used to shift which part of the +current node is visible on the screen. + + <p>Scrolling commands are bound differently when <span class="samp">--vi-keys</span> operation +is in effect (see <a href="#_002d_002dvi_002dkeys">–vi-keys</a>). These key bindings are designated +with “vi-like operation”. + + <dl> +<dt><SPC> (<code>scroll-forward</code>)<dd><a name="index-SPC_002c-in-Info-windows-75"></a><a name="index-scroll_002dforward-76"></a>Shift the text in this window up. That is, show more of the node which +is currently below the bottom of the window. With a numeric argument, +show that many more lines at the bottom of the window; a numeric +argument of 4 would shift all of the text in the window up 4 lines +(discarding the top 4 lines), and show you four new lines at the bottom +of the window. Without a numeric argument, <SPC> takes the bottom +two lines of the window and places them at the top of the window, +redisplaying almost a completely new screenful of lines. If you are at +the end of a node, <SPC> takes you to the “next” node, so that you can +read an entire manual from start to finish by repeating <SPC>. + + <p>The default scroll size is one screen-full, but it can be changed by +invoking the (<code>scroll-forward-page-only-set-window</code>) command, +<span class="samp">z</span> under <span class="samp">--vi-keys</span>, with a numeric argument. + + <br><dt><NEXT> (an arrow key) (<code>scroll-forward-page-only</code>)<dt><C-v><dt><C-f>, vi-like operation<dt><f>, vi-like operation<dt><M-SPC>, vi-like operation<dd><a name="index-NEXT-77"></a><a name="index-C_002dv-78"></a><a name="index-C_002df_002c-vi_002dlike-operation-79"></a><a name="index-f_002c-vi_002dlike-operation-80"></a><a name="index-M_002dSPC_002c-vi_002dlike-operation-81"></a><a name="index-scroll_002dforward_002dpage_002donly-82"></a>Shift the text in this window up. This is identical to the <SPC> +operation above, except that it never scrolls beyond the end of the +current node. + + <p><a name="index-PageDown-83"></a>The <NEXT> key is known as the <PageDown> key on some +keyboards. + + <br><dt><z> (<code>scroll-forward-page-only-set-window</code>, vi-like operation)<dd><a name="index-z_002c-vi_002dlike-operation-84"></a><a name="index-scroll_002dforward_002dpage_002donly_002dset_002dwindow-85"></a>Scroll forward, like with <NEXT>, but if a numeric argument is +specified, it becomes the default scroll size for subsequent +<code>scroll-forward</code> and <code>scroll-backward</code> commands and their +ilk. + + <br><dt><DEL> (<code>scroll-backward</code>)<dd><a name="index-DEL_002c-in-Info-windows-86"></a><a name="index-scroll_002dbackward-87"></a>Shift the text in this window down. The inverse of +<code>scroll-forward</code>. +If you are at the start of a node, <DEL> takes you to the +“previous” node, so that you can read an entire manual from finish to +start by repeating <DEL>. The default scroll size can be changed by +invoking the (<code>scroll-backward-page-only-set-window</code>) command, +<span class="samp">w</span> under <span class="samp">--vi-keys</span>, with a numeric argument. + + <dt><PREVIOUS> (arrow key) (<code>scroll-backward-page-only</code>)<dt><PRIOR> (arrow key)<dt><M-v><dt><b>, vi-like operation<dt><C-b>, vi-like operation<dd><a name="index-PREVIOUS-88"></a><a name="index-M_002dv-89"></a><a name="index-b_002c-vi_002dlike-operation-90"></a><a name="index-C_002db_002c-vi_002dlike-operation-91"></a><a name="index-scroll_002dbackward_002dpage_002donly-92"></a>Shift the text in this window down. The inverse of +<code>scroll-forward-page-only</code>. Does not scroll beyond the start of +the current node. The default scroll size can be changed by invoking +the(<code>scroll-backward-page-only-set-window</code>) command, <span class="samp">w</span> under +<span class="samp">--vi-keys</span>, with a numeric argument. + + <br><dt><w> (<code>scroll-backward-page-only-set-window</code>, vi-like operation)<dd><a name="index-w_002c-vi_002dlike-operation-93"></a><a name="index-scroll_002dbackward_002dpage_002donly_002dset_002dwindow-94"></a>Scroll backward, like with <PREVIOUS>, but if a numeric argument is +specified, it becomes the default scroll size for subsequent +<code>scroll-forward</code> and <code>scroll-backward</code> commands. + + <br><dt><C-n> (<code>down-line</code>, vi-like operation)<dt><C-e>, vi-like operation<dt><RET>, vi-like operation<dt><LFD>, vi-like operation<dt><DOWN>, vi-like operation<dd><a name="index-C_002dn_002c-vi_002dlike-operation-95"></a><a name="index-C_002de_002c-vi_002dlike-operation-96"></a><a name="index-RET_002c-vi_002dlike-operation-97"></a><a name="index-LFD_002c-vi_002dlike-operation-98"></a><a name="index-DOWN_002c-vi_002dlike-operation-99"></a><a name="index-down_002dline-100"></a>Scroll forward by one line. With a numeric argument, scroll forward +that many lines. + + <br><dt><C-p> (<code>up-line</code>, vi-like operation)<dt><UP>, vi-like operation<dt><y>, vi-like operation<dt><k>, vi-like operation<dt><C-k>, vi-like operation<dt><C-y>, vi-like operation<dd><a name="index-C_002dp_002c-vi_002dlike-operation-101"></a><a name="index-UP_002c-vi_002dlike-operation-102"></a><a name="index-y_002c-vi_002dlike-operation-103"></a><a name="index-k_002c-vi_002dlike-operation-104"></a><a name="index-C_002dk_002c-vi_002dlike-operation-105"></a><a name="index-C_002dy_002c-vi_002dlike-operation-106"></a><a name="index-up_002dline-107"></a>Scroll backward one line. With a numeric argument, scroll backward that +many lines. + + <br><dt><d> (<code>scroll-half-screen-down</code>, vi-like operation)<dt><C-d>, vi-like operation<dd><a name="index-d_002c-vi_002dlike-operation-108"></a><a name="index-C_002dd_002c-vi_002dlike-operation-109"></a><a name="index-scroll_002dhalf_002dscreen_002ddown-110"></a>Scroll forward by half of the screen size. With a numeric argument, +scroll that many lines. If an argument is specified, it becomes the new +default number of lines to scroll for subsequent <span class="samp">d</span> and <span class="samp">u</span> +commands. + + <br><dt><u> (<code>scroll-half-screen-up</code>, vi-like operation)<dt><C-u>, vi-like operation<dd><a name="index-u_002c-vi_002dlike-operation-111"></a><a name="index-C_002du_002c-vi_002dlike-operation-112"></a><a name="index-scroll_002dhalf_002dscreen_002dup-113"></a>Scroll back by half of the screen size. With a numeric argument, +scroll that many lines. If an argument is specified, it becomes the new +default number of lines to scroll for subsequent <span class="samp">u</span> and <span class="samp">d</span> +commands. +</dl> + + <p><a name="index-scrolling-through-node-structure-114"></a>The <code>scroll-forward</code> and <code>scroll-backward</code> commands can also +move forward and backward through the node structure of the file. If +you press <SPC> while viewing the end of a node, or <DEL> while +viewing the beginning of a node, what happens is controlled by the +variable <code>scroll-behavior</code>. See <a href="#Variables"><code>scroll-behavior</code></a>, for more information. + + <p>The <code>scroll-forward-page-only</code> and <code>scroll-backward-page-only</code> +commands never scroll beyond the current node. + + <p><a name="index-PageUp-115"></a>The <PREVIOUS> key is the <PageUp> key on many keyboards. Emacs +refers to it by the name <PRIOR>. When you use <PRIOR> or +<PageUp> to scroll, Info never scrolls beyond the beginning of the +current node. + + <p><a name="index-BS-_0028backspace_0029-116"></a>If your keyboard lacks the <DEL> key, look for a key called +<BS>, or <span class="samp">BackSpace</span>, sometimes designated with an arrow which +points to the left, which should perform the same function. + + <dl> +<dt><C-l> (<code>redraw-display</code>)<dd><a name="index-C_002dl-117"></a><a name="index-redraw_002ddisplay-118"></a>Redraw the display from scratch, or shift the line containing the cursor +to a specified location. With no numeric argument, <span class="samp">C-l</span> clears +the screen, and then redraws its entire contents. Given a numeric +argument of <var>n</var>, the line containing the cursor is shifted so that +it is on the <var>n</var>th line of the window. + + <br><dt><kbd>C-x <w></kbd> (<code>toggle-wrap</code>)<dd><a name="index-C_002dw-119"></a><a name="index-toggle_002dwrap-120"></a>Toggles the state of line wrapping in the current window. Normally, +lines which are longer than the screen width <dfn>wrap</dfn>, i.e., they are +continued on the next line. Lines which wrap have a <span class="samp">\</span> appearing +in the rightmost column of the screen. You can cause such lines to be +terminated at the rightmost column by changing the state of line +wrapping in the window with <code>C-x w</code>. When a line which needs more +space than one screen width to display is displayed, a <span class="samp">$</span> appears +in the rightmost column of the screen, and the remainder of the line is +invisible. When long lines are truncated, the modeline displays the +<span class="samp">$</span> character near its left edge. +</dl> + +<div class="node"> +<p><hr> +<a name="Node-Commands"></a>Next: <a rel="next" accesskey="n" href="#Searching-Commands">Searching Commands</a>, +Previous: <a rel="previous" accesskey="p" href="#Scrolling-Commands">Scrolling Commands</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> +<br> +</div> + +<h2 class="chapter">5 Selecting a Node</h2> + +<p><a name="index-nodes_002c-selection-of-121"></a> +This section details the numerous Info commands which select a new node +to view in the current window. + + <p>The most basic node commands are <span class="samp">n</span>, <span class="samp">p</span>, <span class="samp">u</span>, and +<span class="samp">l</span>. Note that the commands to select nodes are mapped differently +when <span class="samp">--vi-keys</span> is in effect; these keybindings are designated +below as “vi-like operation”. + + <p>When you are viewing a node, the top line of the node contains some Info +<dfn>pointers</dfn> which describe where the next, previous, and up nodes +are. Info uses this line to move about the node structure of the file +when you use the following commands: + + <dl> +<dt><n> (<code>next-node</code>)<dt><kbd>C-<NEXT></kbd> (on DOS/Windows only)<dt><kbd>C-x <n></kbd>, vi-like operation<dd><a name="index-n-122"></a><a name="index-C_002dNEXT-123"></a><a name="index-C_002dx-n_002c-vi_002dlike-operation-124"></a><a name="index-next_002dnode-125"></a>Select the `Next' node. + + <p><a name="index-C_002dPgDn-126"></a>The <NEXT> key is known as the <PgDn> key on some +keyboards. + + <br><dt><p> (<code>prev-node</code>)<dt><kbd>C-<PREVIOUS></kbd> (on DOS/Windows only)<dd><a name="index-p-127"></a><a name="index-C_002dPREVIOUS-128"></a><a name="index-prev_002dnode-129"></a>Select the `Prev' node. + + <p><a name="index-C_002dPgUp-130"></a>The <PREVIOUS> key is known as the <PgUp> key on some +keyboards. + + <br><dt><u> (<code>up-node</code>)<dt><kbd>C-<UP></kbd> (an arrow key on DOS/Windows only)<dt><kbd>C-x <u></kbd>, vi-like operation<dd><a name="index-u-131"></a><a name="index-C_002dUP-132"></a><a name="index-C_002dx-u_002c-vi_002dlike-operation-133"></a><a name="index-up_002dnode-134"></a>Select the `Up' node. +</dl> + + <p>You can easily select a node that you have already viewed in this window +by using the <span class="samp">l</span> command – this name stands for "last", and +actually moves backwards through the history of visited nodes for this +window. This is handy when you followed a reference to another node, +possibly to read about a related issue, and would like then to resume +reading at the same place where you started the excursion. + + <p>Each node where you press <span class="samp">l</span> is discarded from the history. Thus, +by the time you get to the first node you visited in a window, the +entire history of that window is discarded. + + <dl> +<dt><l> (<code>history-node</code>)<dt><C-<CENTER>> (on DOS/Windows only)<dt><'>, vi-like operation<dd><a name="index-l-135"></a><a name="index-C_002dCENTER-136"></a><a name="index-_0027_002c-vi_002dlike-operation-137"></a><a name="index-history_002dnode-138"></a>Pop the most recently selected node in this window from the node +history. +</dl> + + <p>Two additional commands make it easy to select the most commonly +selected nodes; they are <span class="samp">t</span> and <span class="samp">d</span>. + + <dl> +<dt><t> (<code>top-node</code>)<dt><M-t>, vi-like operation<dd><a name="index-t-139"></a><a name="index-M_002dt_002c-vi_002dlike-operation-140"></a><a name="index-top_002dnode-141"></a>Select the node <span class="samp">Top</span> in the current Info file. + + <br><dt><d> (<code>dir-node</code>)<dt><M-d>, vi-like operation<dd><a name="index-d-142"></a><a name="index-M_002dd_002c-vi_002dlike-operation-143"></a><a name="index-dir_002dnode-144"></a>Select the directory node (i.e., the node <span class="samp">(dir)</span>). +</dl> + + <p>Here are some other commands which immediately result in the selection +of a different node in the current window: + + <dl> +<dt><<> (<code>first-node</code>)<dt><g>, vi-like operation<dd><a name="index-_003c-145"></a><a name="index-g_002c-vi_002dlike-operation-146"></a><a name="index-first_002dnode-147"></a>Selects the first node which appears in this file. This node is most +often <span class="samp">Top</span>, but it does not have to be. With a numeric argument +<var>N</var>, select the <var>N</var>th node (the first node is node 1). An +argument of zero is the same as the argument of 1. + + <br><dt><>> (<code>last-node</code>)<dt><G>, vi-like operation<dd><a name="index-_003e-148"></a><a name="index-G_002c-vi_002dlike-operation-149"></a><a name="index-last_002dnode-150"></a>Select the last node which appears in this file. With a numeric argument +<var>N</var>, select the <var>N</var>th node (the first node is node 1). An +argument of zero is the same as no argument, i.e., it selects the last +node. + + <br><dt><]> (<code>global-next-node</code>)<dd><a name="index-_005d-151"></a><a name="index-global_002dnext_002dnode-152"></a>Move forward or down through node structure. If the node that you are +currently viewing has a <span class="samp">Next</span> pointer, that node is selected. +Otherwise, if this node has a menu, the first menu item is selected. If +there is no <span class="samp">Next</span> and no menu, the same process is tried with the +<span class="samp">Up</span> node of this node. + + <br><dt><[> (<code>global-prev-node</code>)<dd><a name="index-_005b-153"></a><a name="index-global_002dprev_002dnode-154"></a>Move backward or up through node structure. If the node that you are +currently viewing has a <span class="samp">Prev</span> pointer, that node is selected. +Otherwise, if the node has an <span class="samp">Up</span> pointer, that node is selected, +and if it has a menu, the last item in the menu is selected. +</dl> + + <p>You can get the same behavior as <code>global-next-node</code> and +<code>global-prev-node</code> while simply scrolling through the file with +<SPC> and <DEL>; See <a href="#Variables"><code>scroll-behavior</code></a>, for +more information. + + <dl> +<a name="goto_002dnode"></a> +<dt><g> (<code>goto-node</code>)<dt><kbd>C-x <g></kbd>, vi-like operation<dd><a name="index-g-155"></a><a name="index-C_002dx-g_002c-vi_002dlike-operation-156"></a><a name="index-goto_002dnode-157"></a>Read the name of a node and select it. While reading the node name, +completion (see <a href="#The-Echo-Area">completion</a>) is only done for the +nodes which reside in one of the Info files that were loaded in the +current Info session; if the desired node resides in some other file, +you must type the node exactly as it appears in that Info file, and you +must include the Info file of the other file. For example, + + <pre class="example"> <code>g(emacs)Buffers</code> + </pre> + <p>finds the node <span class="samp">Buffers</span> in the Info file <span class="file">emacs</span>. + + <p><a name="goto_002dinvocation"></a> +<br><dt><O> (<code>goto-invocation</code><dt><I><dd><a name="index-O-158"></a><a name="index-I-159"></a><a name="index-goto_002dinvocation-160"></a><a name="index-finding-the-Invocation-node-161"></a>Read the name of a program and look for a node in the current Info file +which describes the invocation and the command-line options for that +program. The default program name is derived from the name of the +current Info file. This command does the same as the +<span class="samp">--show-options</span> command-line option (see <a href="#_002d_002dshow_002doptions">–show-options</a>), but +it also allows to specify the program name; this is important for those +manuals which describe several programs. + + <p>If you need to find the Invocation node of a program that is documented +in another Info file, you need to visit that file before invoking +<span class="samp">I</span>. For example, if you are reading the Emacs manual and want to +see the command-line options of the <code>makeinfo</code> program, type <kbd>g +(texinfo) <RET></kbd> and then <kbd>I makeinfo <RET></kbd>. If you don't +know what Info file documents the command, or if invoking <span class="samp">I</span> +doesn't display the right node, go to the <span class="samp">(dir)</span> node (using the +<span class="samp">d</span> command) and invoke <span class="samp">I</span> from there. + + <br><dt><G> (<code>menu-sequence</code>)<dd><a name="index-G-162"></a><a name="index-menu_002dsequence-163"></a><a name="index-menu_002c-following_002c-from-inside-Info-164"></a>Read a sequence of menu entries and follow it. Info prompts for a +sequence of menu items separated by commas. (Since commas are not +allowed in a node name, they are a natural choice for a delimiter in a +list of menu items.) Info then looks up the first item in the menu of +the node <span class="samp">(dir)</span> (if the <span class="samp">(dir)</span> node cannot be found, Info +uses <span class="samp">Top</span>). If such an entry is found, Info goes to the node it +points to and looks up the second item in the menu of that node, etc. +In other words, you can specify a complete path which descends through +the menu hierarchy of a particular Info file starting at the +<span class="samp">(dir)</span> node. This has the same effect as if you typed the menu +item sequence on Info's command line, see <a href="#command_002dline-menu-items">Info command-line arguments processing</a>. For example, + + <pre class="example"> <kbd>G Texinfo,Overview,Reporting Bugs <RET></kbd> + </pre> + <p class="noindent">displays the node <span class="samp">Reporting Bugs</span> in the Texinfo manual. (You +don't actually need to type the menu items in their full length, or in +their exact letter-case. However, if you do type the menu items +exactly, Info will find it faster.) + + <p>If any of the menu items you type are not found, Info stops at the last +entry it did find and reports an error. + + <br><dt><kbd>C-x <k></kbd> (<code>kill-node</code>)<dd><a name="index-C_002dx-k-165"></a><a name="index-kill_002dnode-166"></a>Kill a node. The node name is prompted for in the echo area, with a +default of the current node. <dfn>Killing</dfn> a node means that Info tries +hard to forget about it, removing it from the list of history nodes kept +for the window where that node is found. Another node is selected in +the window which contained the killed node. + + <br><dt><kbd>C-x C-f</kbd> (<code>view-file</code>)<dd><a name="index-C_002dx-C_002df-167"></a><a name="index-view_002dfile-168"></a>Read the name of a file and selects the entire file. The command + <pre class="example"> <code>C-x C-f </code><var>filename</var> + </pre> + <p>is equivalent to typing + <pre class="example"> <code>g(</code><var>filename</var><code>)*</code> + </pre> + <br><dt><kbd>C-x C-b</kbd> (<code>list-visited-nodes</code>)<dd><a name="index-C_002dx-C_002db-169"></a><a name="index-list_002dvisited_002dnodes-170"></a>Make a window containing a menu of all of the currently visited nodes. +This window becomes the selected window, and you may use the standard +Info commands within it. + + <br><dt><kbd>C-x <b></kbd> (<code>select-visited-node</code>)<dd><a name="index-C_002dx-b-171"></a><a name="index-select_002dvisited_002dnode-172"></a>Select a node which has been previously visited in a visible window. +This is similar to <span class="samp">C-x C-b</span> followed by <span class="samp">m</span>, but no window is +created. +</dl> + +<div class="node"> +<p><hr> +<a name="Searching-Commands"></a>Next: <a rel="next" accesskey="n" href="#Xref-Commands">Xref Commands</a>, +Previous: <a rel="previous" accesskey="p" href="#Node-Commands">Node Commands</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> +<br> +</div> + +<h2 class="chapter">6 Searching an Info File</h2> + +<p><a name="index-searching-173"></a> +GNU Info allows you to search for a sequence of characters throughout an +entire Info file, search through the indices of an Info file, or find +areas within an Info file which discuss a particular topic. + + <dl> +<dt><s> (<code>search</code>)<dt></><dd><a name="index-s-174"></a><a name="index-_002f-175"></a><a name="index-search-176"></a>Read a string in the echo area and search for it. If the string +includes upper-case characters, the Info file is searched +case-sensitively; otherwise Info ignores the letter case. With a +numeric argument of <var>N</var>, search for <var>N</var>th occurrence of the +string. Negative arguments search backwards. + + <br><dt><?> (<code>search-backward</code>, vi-like operation)<dd><a name="index-_003f_002c-vi_002dlike-operation-177"></a><a name="index-search_002dbackward-178"></a>Read a string in the echo area and search backward through the Info file +for that string. If the string includes upper-case characters, the Info +file is searched case-sensitively; otherwise Info ignores the letter +case. With a numeric argument of <var>N</var>, search for <var>N</var>th +occurrence of the string. Negative arguments search forward. + + <br><dt><S> (<code>search-case-sensitively</code><dd><a name="index-S-179"></a><a name="index-search_002dcase_002dsensitively-180"></a><a name="index-search_002c-case_002dsensitive-181"></a><a name="index-case_002dsensitive-search-182"></a>Read a string in the echo area and search for it case-sensitively, even +if the string includes only lower-case letters. With a numeric argument +of <var>N</var>, search for <var>N</var>th occurrence of the string. Negative +arguments search backwards. + + <br><dt><kbd>C-x <n></kbd> (<code>search-next</code>)<dt><n>, vi-like operation<dd><a name="index-C_002dx-n-183"></a><a name="index-n_002c-vi_002dlike-operation-184"></a><a name="index-search_002dnext-185"></a><a name="index-repeated-search-186"></a>Search for the same string used in the last search command, in the same +direction, and with the same case-sensitivity option. With a numeric +argument of <var>N</var>, search for <var>N</var>th next occurrence. + + <br><dt><kbd>C-x <N></kbd> (<code>search-previous</code>)<dt><N>, vi-like operation<dd><a name="index-C_002dx-N-187"></a><a name="index-n_002c-vi_002dlike-operation-188"></a><a name="index-search_002dprevious-189"></a>Search for the same string used in the last search command, and with the +same case-sensitivity option, but in the reverse direction. With a +numeric argument of <var>N</var>, search for <var>N</var>th previous occurrence. + + <br><dt><C-s> (<code>isearch-forward</code>)<dd><a name="index-C_002ds-190"></a><a name="index-isearch_002dforward-191"></a><a name="index-incremental-search-192"></a>Interactively search forward through the Info file for a string as you +type it. If the string includes upper-case characters, the search is +case-sensitive; otherwise Info ignores the letter case. + + <br><dt><C-r> (<code>isearch-backward</code>)<dd><a name="index-C_002dr-193"></a><a name="index-isearch_002dbackward-194"></a>Interactively search backward through the Info file for a string as +you type it. If the string includes upper-case characters, the search +is case-sensitive; otherwise Info ignores the letter case. + + <br><dt><i> (<code>index-search</code>)<dd><a name="index-i-195"></a><a name="index-index_002dsearch-196"></a><a name="index-index_002c-searching-197"></a><a name="index-searching_002c-in-the-indices-198"></a>Look up a string in the indices for this Info file, and select a node +to which the found index entry points. + + <br><dt><,> (<code>next-index-match</code>)<dd><a name="index-_002c-199"></a><a name="index-next_002dindex_002dmatch-200"></a>Move to the node containing the next matching index item from the last +<span class="samp">i</span> command. + + <br><dt><kbd>M-x index-apropos</kbd><dd><a name="index-index_002dapropos-201"></a>Grovel the indices of all the known Info files on your system for a +string, and build a menu of the possible matches. +</dl> + + <p>The most basic searching command is <span class="samp">s</span> or <span class="samp">/</span> +(<code>search</code>). The <span class="samp">s</span> command prompts you for a string in the +echo area, and then searches the remainder of the Info file for an +occurrence of that string. If the string is found, the node containing +it is selected, and the cursor is left positioned at the start of the +found string. Subsequent <span class="samp">s</span> commands show you the default search +string within <span class="samp">[</span> and <span class="samp">]</span>; pressing <RET> instead of +typing a new string will use the default search string. Under +<span class="samp">--vi-keys</span> (see <a href="#_002d_002dvi_002dkeys">–vi-keys</a>), using the <span class="samp">n</span> or <span class="samp">N</span> +commands is a faster way of searching for the same string. + + <p><dfn>Incremental searching</dfn> is similar to basic searching, but the +string is looked up while you are typing it, instead of waiting until +the entire search string has been specified. + + <p><a name="index-search_002c-and-case_002dsensitivity-202"></a><a name="index-case_002dsensitivity_002c-and-search-203"></a>Both incremental and non-incremental search by default ignore the case +of letters when comparing the Info file text with the search string. +However, an uppercase letter in the search string makes the search +case-sensitive. You can force a case-sensitive non-incremental search, +even for a string that includes only lower-case letters, by using the +<span class="samp">S</span> command (<code>search-case-sensitively</code>). The <span class="samp">n</span> and +<span class="samp">N</span> commands operate case-sensitively if the last search command +was <span class="samp">S</span>. + + <p>The most efficient means of finding something quickly in a manual is +the <span class="samp">i</span> command (<code>index-search</code>). This command prompts for +a string, and then looks for that string in all the indices of the +current Info manual. If it finds a matching index entry, it displays +the node to which that entry refers and prints the full text of the +entry in the echo area. You can press <span class="samp">,</span> +(<code>next-index-match</code>) to find more matches. A good Info manual +has all of its important concepts indexed, so the <span class="samp">i</span> command +lets you use a manual as a reference. + + <p>If you don't know what manual documents something, try the <kbd>M-x +index-apropos</kbd> command. It prompts for a string and then looks up +that string in all the indices of all the Info documents installed on +your system. It can also be invoked from the command line; see +<a href="#_002d_002dapropos">–apropos</a>. + +<div class="node"> +<p><hr> +<a name="Xref-Commands"></a>Next: <a rel="next" accesskey="n" href="#Window-Commands">Window Commands</a>, +Previous: <a rel="previous" accesskey="p" href="#Searching-Commands">Searching Commands</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> +<br> +</div> + +<h2 class="chapter">7 Selecting Cross References</h2> + +<p>We have already discussed the <span class="samp">Next</span>, <span class="samp">Prev</span>, and <span class="samp">Up</span> +pointers which appear at the top of a node. In addition to these +pointers, a node may contain other pointers which refer you to a +different node, perhaps in another Info file. Such pointers are called +<dfn>cross references</dfn>, or <dfn>xrefs</dfn> for short. + +<ul class="menu"> +<li><a accesskey="1" href="#Parts-of-an-Xref">Parts of an Xref</a>: What a cross reference is made of. +<li><a accesskey="2" href="#Selecting-Xrefs">Selecting Xrefs</a>: Commands for selecting menu or note items. +</ul> + +<div class="node"> +<p><hr> +<a name="Parts-of-an-Xref"></a>Next: <a rel="next" accesskey="n" href="#Selecting-Xrefs">Selecting Xrefs</a>, +Up: <a rel="up" accesskey="u" href="#Xref-Commands">Xref Commands</a> +<br> +</div> + +<h3 class="section">7.1 Parts of an Xref</h3> + +<p>Cross references have two major parts: the first part is called the +<dfn>label</dfn>; it is the name that you can use to refer to the cross +reference, and the second is the <dfn>target</dfn>; it is the full name of +the node that the cross reference points to. + + <p>The target is separated from the label by a colon <span class="samp">:</span>; first the +label appears, and then the target. For example, in the sample menu +cross reference below, the single colon separates the label from the +target. + +<pre class="example"> * Foo Label: Foo Target. More information about Foo. +</pre> + <p>Note the <span class="samp">.</span> which ends the name of the target. The <span class="samp">.</span> is +not part of the target; it serves only to let Info know where the target +name ends. + + <p>A shorthand way of specifying references allows two adjacent colons to +stand for a target name which is the same as the label name: + +<pre class="example"> * Foo Commands:: Commands pertaining to Foo. +</pre> + <p>In the above example, the name of the target is the same as the name of +the label, in this case <code>Foo Commands</code>. + + <p>You will normally see two types of cross reference while viewing nodes: +<dfn>menu</dfn> references, and <dfn>note</dfn> references. Menu references +appear within a node's menu; they begin with a <span class="samp">*</span> at the beginning +of a line, and continue with a label, a target, and a comment which +describes what the contents of the node pointed to contains. + + <p>Note references appear within the body of the node text; they begin with +<code>*Note</code>, and continue with a label and a target. + + <p>Like <span class="samp">Next</span>, <span class="samp">Prev</span>, and <span class="samp">Up</span> pointers, cross references +can point to any valid node. They are used to refer you to a place +where more detailed information can be found on a particular subject. +Here is a cross reference which points to a node within the Texinfo +documentation: See <a href="texinfo.html#xref">Writing an Xref (the Texinfo Manual)</a>, for more information on creating your own texinfo cross +references. + +<div class="node"> +<p><hr> +<a name="Selecting-Xrefs"></a>Previous: <a rel="previous" accesskey="p" href="#Parts-of-an-Xref">Parts of an Xref</a>, +Up: <a rel="up" accesskey="u" href="#Xref-Commands">Xref Commands</a> +<br> +</div> + +<h3 class="section">7.2 Selecting Xrefs</h3> + +<p>The following table lists the Info commands which operate on menu items. + + <dl> +<dt><1> (<code>menu-digit</code>)<dt><2> <small class="dots">...</small> <9><dt><M-1>, vi-like operation<dt><M-2> <small class="dots">...</small> <M-9>, vi-like operation<dd><a name="index-1-_0040dots_007b_007d-9_002c-in-Info-windows-204"></a><a name="index-M_002d1-_0040dots_007b_007d-M_002d9_002c-vi_002dlike-operation-205"></a><a name="index-1-_0040dots_007b_007d-9_002c-in-Info-windows-206"></a><a name="index-M_002d1-_0040dots_007b_007d-M_002d9_002c-vi_002dlike-operation-207"></a><a name="index-menu_002ddigit-208"></a>Within an Info window, pressing a single digit, (such as <span class="samp">1</span>), +selects that menu item, and places its node in the current window. +For convenience, there is one exception; pressing <span class="samp">0</span> selects the +<em>last</em> item in the node's menu. When <span class="samp">--vi-keys</span> is in +effect, digits set the numeric argument, so these commands are remapped +to their <span class="samp">M-</span> varieties. For example, to select the last menu +item, press <M-0>. + + <br><dt><0> (<code>last-menu-item</code>)<dt><M-0>, vi-like operation<dd><a name="index-0_002c-in-Info-windows-209"></a><a name="index-M_002d0_002c-vi_002dlike-operation-210"></a><a name="index-last_002dmenu_002ditem-211"></a>Select the last item in the current node's menu. + + <br><dt><m> (<code>menu-item</code>)<dd><a name="index-m-212"></a><a name="index-menu_002ditem-213"></a>Reads the name of a menu item in the echo area and selects its node. +Completion is available while reading the menu label. See <a href="#The-Echo-Area">completion</a>. + + <br><dt><kbd>M-x find-menu</kbd><dd><a name="index-find_002dmenu-214"></a>Move the cursor to the start of this node's menu. +</dl> + + <p>This table lists the Info commands which operate on cross references. + + <dl> +<dt><f> (<code>xref-item</code>)<dt><r><br><dt><M-f>, vi-like operation<dt><kbd>C-x <r></kbd>, vi-like operation<dd><a name="index-f-215"></a><a name="index-r-216"></a><a name="index-M_002df_002c-vi_002dlike-operation-217"></a><a name="index-C_002dx-r_002c-vi_002dlike-operation-218"></a><a name="index-xref_002ditem-219"></a>Reads the name of a note cross reference in the echo area and selects +its node. Completion is available while reading the cross reference +label. See <a href="#The-Echo-Area">completion</a>. +</dl> + + <p>Finally, the next few commands operate on menu or note references alike: + + <dl> +<dt><TAB> (<code>move-to-next-xref</code>)<dd><a name="index-TAB_002c-in-Info-windows-220"></a><a name="index-move_002dto_002dnext_002dxref-221"></a>Move the cursor to the start of the next nearest menu item or note +reference in this node. You can then use <RET> +(<code>select-reference-this-line</code>) to select the menu or note reference. + + <br><dt><M-TAB> (<code>move-to-prev-xref</code>)<dt><Shift-<TAB>> (on DOS/Windows only)<dd><a name="index-M_002dTAB_002c-in-Info-windows-222"></a><a name="index-move_002dto_002dprev_002dxref-223"></a>Move the cursor the start of the nearest previous menu item or note +reference in this node. + + <p><a name="index-Shift_002dTAB_002c-in-Info-windows-224"></a><a name="index-BackTab_002c-in-Info-windows-225"></a>On DOS/Windows only, the <kbd>Shift-<TAB></kbd> key is an alias for +<kbd>M-<TAB></kbd>. This key is sometimes called <span class="samp">BackTab</span>. + + <br><dt><RET> (<code>select-reference-this-line</code>)<dt><M-g>, vi-like operation<dd><a name="index-RET_002c-in-Info-windows-226"></a><a name="index-M_002dg_002c-vi_002dlike-operation-227"></a><a name="index-select_002dreference_002dthis_002dline-228"></a>Select the menu item or note reference appearing on this line. +</dl> + +<div class="node"> +<p><hr> +<a name="Window-Commands"></a>Next: <a rel="next" accesskey="n" href="#Printing-Nodes">Printing Nodes</a>, +Previous: <a rel="previous" accesskey="p" href="#Xref-Commands">Xref Commands</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> +<br> +</div> + +<h2 class="chapter">8 Manipulating Multiple Windows</h2> + +<p><a name="index-windows_002c-manipulating-229"></a> +A <dfn>window</dfn> is a place to show the text of a node. Windows have a +view area where the text of the node is displayed, and an associated +<dfn>mode line</dfn>, which briefly describes the node being viewed. + + <p>GNU Info supports multiple windows appearing in a single screen; each +window is separated from the next by its modeline. At any time, there +is only one <dfn>active</dfn> window, that is, the window in which the cursor +appears. There are commands available for creating windows, changing +the size of windows, selecting which window is active, and for deleting +windows. + +<ul class="menu"> +<li><a accesskey="1" href="#The-Mode-Line">The Mode Line</a>: What appears in the mode line? +<li><a accesskey="2" href="#Basic-Windows">Basic Windows</a>: Manipulating windows in Info. +<li><a accesskey="3" href="#The-Echo-Area">The Echo Area</a>: Used for displaying errors and reading input. +</ul> + +<div class="node"> +<p><hr> +<a name="The-Mode-Line"></a>Next: <a rel="next" accesskey="n" href="#Basic-Windows">Basic Windows</a>, +Up: <a rel="up" accesskey="u" href="#Window-Commands">Window Commands</a> +<br> +</div> + +<h3 class="section">8.1 The Mode Line</h3> + +<p>A <dfn>mode line</dfn> is a line of inverse video which appears at the bottom +of an Info window. It describes the contents of the window just above +it; this information includes the name of the file and node appearing in +that window, the number of screen lines it takes to display the node, +and the percentage of text that is above the top of the window. It can +also tell you if the indirect tags table for this Info file needs to be +updated, and whether or not the Info file was compressed when stored on +disk. + + <p>Here is a sample mode line for a window containing an uncompressed file +named <span class="file">dir</span>, showing the node <span class="samp">Top</span>. + +<pre class="example"> -----Info: (dir)Top, 40 lines --Top------------------------------------- + ^^ ^ ^^^ ^^ + (file)Node #lines where +</pre> + <p>When a node comes from a file which is compressed on disk, this is +indicated in the mode line with two small <span class="samp">z</span>'s. In addition, if +the Info file containing the node has been split into subfiles, the name +of the subfile containing the node appears in the modeline as well: + +<pre class="example"> --zz-Info: (emacs)Top, 291 lines --Top-- Subfile: emacs-1.Z------------- +</pre> + <p>Truncation of long lines (as opposed to wrapping them to the next +display line, see <a href="#Scrolling-Commands">toggle-wrap</a>) is indicated by a +<span class="samp">$</span> at the left edge of the mode line: + +<pre class="example"> --$--Info: (texinfo)Top, 480 lines --Top-- Subfile: texinfo-1----------- +</pre> + <p>When Info makes a node internally, such that there is no corresponding +info file on disk, the name of the node is surrounded by asterisks +(<span class="samp">*</span>). The name itself tells you what the contents of the window +are; the sample mode line below shows an internally constructed node +showing possible completions: + +<pre class="example"> -----Info: *Completions*, 7 lines --All--------------------------------- +</pre> + <div class="node"> +<p><hr> +<a name="Basic-Windows"></a>Next: <a rel="next" accesskey="n" href="#The-Echo-Area">The Echo Area</a>, +Previous: <a rel="previous" accesskey="p" href="#The-Mode-Line">The Mode Line</a>, +Up: <a rel="up" accesskey="u" href="#Window-Commands">Window Commands</a> +<br> +</div> + +<h3 class="section">8.2 Window Commands</h3> + +<p>It can be convenient to view more than one node at a time. To allow +this, Info can display more than one <dfn>window</dfn>. Each window has its +own mode line (see <a href="#The-Mode-Line">The Mode Line</a>) and history of nodes viewed in that +window (see <a href="#Node-Commands"><code>history-node</code></a>). + + <dl> +<dt><kbd>C-x <o></kbd> (<code>next-window</code>)<dd><a name="index-windows_002c-selecting-230"></a><a name="index-C_002dx-o-231"></a><a name="index-next_002dwindow-232"></a>Select the next window on the screen. Note that the echo area can only be +selected if it is already in use, and you have left it temporarily. +Normally, <span class="samp">C-x o</span> simply moves the cursor into the next window on +the screen, or if you are already within the last window, into the first +window on the screen. Given a numeric argument, <span class="samp">C-x o</span> moves over +that many windows. A negative argument causes <span class="samp">C-x o</span> to select +the previous window on the screen. + + <br><dt><kbd>M-x prev-window</kbd><dd><a name="index-prev_002dwindow-233"></a>Select the previous window on the screen. This is identical to +<span class="samp">C-x o</span> with a negative argument. + + <br><dt><kbd>C-x <2></kbd> (<code>split-window</code>)<dd><a name="index-windows_002c-creating-234"></a><a name="index-C_002dx-2-235"></a><a name="index-split_002dwindow-236"></a>Split the current window into two windows, both showing the same node. +Each window is one half the size of the original window, and the cursor +remains in the original window. The variable <code>automatic-tiling</code> +can cause all of the windows on the screen to be resized for you +automatically, please see <a href="#Variables">automatic-tiling</a> for more +information. + + <br><dt><kbd>C-x <0></kbd> (<code>delete-window</code>)<dd><a name="index-windows_002c-deleting-237"></a><a name="index-C_002dx-0-238"></a><a name="index-delete_002dwindow-239"></a>Delete the current window from the screen. If you have made too many +windows and your screen appears cluttered, this is the way to get rid of +some of them. + + <br><dt><kbd>C-x <1></kbd> (<code>keep-one-window</code>)<dd><a name="index-C_002dx-1-240"></a><a name="index-keep_002done_002dwindow-241"></a>Delete all of the windows excepting the current one. + + <br><dt><kbd>ESC <C-v></kbd> (<code>scroll-other-window</code>)<dd><a name="index-ESC-C_002dv_002c-in-Info-windows-242"></a><a name="index-scroll_002dother_002dwindow-243"></a>Scroll the other window, in the same fashion that <span class="samp">C-v</span> might +scroll the current window. Given a negative argument, scroll the +"other" window backward. + + <br><dt><kbd>C-x <^></kbd> (<code>grow-window</code>)<dd><a name="index-C_002dx-_005e-244"></a><a name="index-grow_002dwindow-245"></a>Grow (or shrink) the current window. Given a numeric argument, grow +the current window that many lines; with a negative numeric argument, +shrink the window instead. + + <br><dt><kbd>C-x <t></kbd> (<code>tile-windows</code>)<dd><a name="index-tiling-246"></a><a name="index-C_002dx-t-247"></a><a name="index-tile_002dwindows-248"></a>Divide the available screen space among all of the visible windows. +Each window is given an equal portion of the screen in which to display +its contents. The variable <code>automatic-tiling</code> can cause +<code>tile-windows</code> to be called when a window is created or deleted. +See <a href="#Variables"><code>automatic-tiling</code></a>. +</dl> + +<div class="node"> +<p><hr> +<a name="The-Echo-Area"></a>Previous: <a rel="previous" accesskey="p" href="#Basic-Windows">Basic Windows</a>, +Up: <a rel="up" accesskey="u" href="#Window-Commands">Window Commands</a> +<br> +</div> + +<h3 class="section">8.3 The Echo Area</h3> + +<p><a name="index-echo-area-249"></a> +The <dfn>echo area</dfn> is a one line window which appears at the bottom of +the screen. It is used to display informative or error messages, and to +read lines of input from you when that is necessary. Almost all of the +commands available in the echo area are identical to their Emacs +counterparts, so please refer to that documentation for greater depth of +discussion on the concepts of editing a line of text. The following +table briefly lists the commands that are available while input is being +read in the echo area: + + <dl> +<dt><C-f> (<code>echo-area-forward</code>)<dt><RIGHT> (an arrow key)<dt><M-h>, vi-like operation<dd><a name="index-C_002df_002c-in-the-echo-area-250"></a><a name="index-RIGHT_002c-in-the-echo-area-251"></a><a name="index-M_002dh_002c-in-the-echo-area_002c-vi_002dlike-operation-252"></a><a name="index-echo_002darea_002dforward-253"></a>Move forward a character. + + <br><dt><C-b> (<code>echo-area-backward</code>)<dt><LEFT> (an arrow key)<dt><M-l>, vi-like operation<dd><a name="index-LEFT_002c-in-the-echo-area-254"></a><a name="index-C_002db_002c-in-the-echo-area-255"></a><a name="index-M_002dl_002c-in-the-echo-area_002c-vi_002dlike-operation-256"></a><a name="index-echo_002darea_002dbackward-257"></a>Move backward a character. + + <br><dt><C-a> (<code>echo-area-beg-of-line</code>)<dt><M-0>, vi-like operation<dd><a name="index-C_002da_002c-in-the-echo-area-258"></a><a name="index-M_002d0_002c-in-the-echo-area_002c-vi_002dlike-operation-259"></a><a name="index-echo_002darea_002dbeg_002dof_002dline-260"></a>Move to the start of the input line. + + <br><dt><C-e> (<code>echo-area-end-of-line</code>)<dt><M-$>, vi-like operation<dd><a name="index-C_002de_002c-in-the-echo-area-261"></a><a name="index-M_002d_0024_002c-vi_002dlike-operation-262"></a><a name="index-echo_002darea_002dend_002dof_002dline-263"></a>Move to the end of the input line. + + <br><dt><M-f> (<code>echo-area-forward-word</code>)<dt><C-<RIGHT>> (DOS/Windows only)<dt><M-w>, vi-like operation<dd><a name="index-M_002df_002c-in-the-echo-area-264"></a><a name="index-M_002dw_002c-in-the-echo-area_002c-vi_002dlike-operation-265"></a><a name="index-echo_002darea_002dforward_002dword-266"></a>Move forward a word. + + <p><a name="index-C_002dRIGHT_002c-in-the-echo-area-267"></a>On DOS/Windows, <kbd>C-<RIGHT></kbd> moves forward by words. + + <br><dt><M-b> (<code>echo-area-backward-word</code>)<dt><C-<LEFT>> (DOS/Windows only)<dd><a name="index-M_002db_002c-in-the-echo-area-268"></a><a name="index-echo_002darea_002dbackward_002dword-269"></a>Move backward a word. + + <p><a name="index-C_002dLEFT_002c-in-the-echo-area-270"></a>On DOS/Windows, <kbd>C-<LEFT></kbd> moves backward by words. + + <br><dt><C-d> (<code>echo-area-delete</code>)<dt><M-x>, vi-like operation<dd><a name="index-C_002dd_002c-in-the-echo-area-271"></a><a name="index-M_002dx_002c-in-the-echo-area_002c-vi_002dlike-operation-272"></a><a name="index-echo_002darea_002ddelete-273"></a>Delete the character under the cursor. + + <br><dt><DEL> (<code>echo-area-rubout</code>)<dd><a name="index-DEL_002c-in-the-echo-area-274"></a><a name="index-echo_002darea_002drubout-275"></a>Delete the character behind the cursor. + + <p>On some keyboards, this key is designated <BS>, for +<span class="samp">BackSpace</span>. Those keyboards will usually bind <DEL> in the +echo area to <code>echo-area-delete</code>. + + <br><dt><C-g> (<code>echo-area-abort</code>)<dt><C-u>, vi-like operation<dd><a name="index-C_002dg_002c-in-the-echo-area-276"></a><a name="index-C_002du_002c-in-the-echo-area_002c-vi_002dlike-operation-277"></a><a name="index-echo_002darea_002dabort-278"></a>Cancel or quit the current operation. If completion is being read, this +command discards the text of the input line which does not match any +completion. If the input line is empty, it aborts the calling function. + + <br><dt><RET> (<code>echo-area-newline</code>)<dd><a name="index-RET_002c-in-the-echo-area-279"></a><a name="index-echo_002darea_002dnewline-280"></a>Accept (or forces completion of) the current input line. + + <br><dt><C-q> (<code>echo-area-quoted-insert</code>)<dt><C-v>, vi-like operation<dd><a name="index-C_002dq_002c-in-the-echo-area-281"></a><a name="index-C_002dv_002c-in-the-echo-area_002c-vi_002dlike-operation-282"></a><a name="index-echo_002darea_002dquoted_002dinsert-283"></a>Insert the next character verbatim. This is how you can insert control +characters into a search string, for example, or the <span class="samp">?</span> character +when Info prompts with completion. + + <br><dt><var>printing character</var> (<code>echo-area-insert</code>)<dd><a name="index-printing-characters_002c-in-the-echo-area-284"></a><a name="index-echo_002darea_002dinsert-285"></a>Insert the character. Characters that have their 8th bit set, and not +bound to <span class="samp">M-</span> commands, are also inserted verbatim; this is useful +for terminals which support Latin scripts. + + <br><dt><M-TAB> (<code>echo-area-tab-insert</code>)<dt><Shift-<TAB>> (on DOS/Windows only)<dd><a name="index-M_002dTAB_002c-in-the-echo-area-286"></a><a name="index-Shift_002dTAB_002c-in-the-echo-area-287"></a><a name="index-echo_002darea_002dtab_002dinsert-288"></a>Insert a TAB character. + + <p><a name="index-Shift_002dTAB_002c-in-the-echo-area-289"></a><a name="index-BackTab_002c-in-the-echo-area-290"></a>On DOS/Windows only, the <kbd>Shift-<TAB></kbd> key is an alias for +<kbd>M-<TAB></kbd>. This key is sometimes called <span class="samp">BackTab</span>. + + <br><dt><C-t> (<code>echo-area-transpose-chars</code>)<dd><a name="index-C_002dt_002c-in-the-echo-area-291"></a><a name="index-echo_002darea_002dtranspose_002dchars-292"></a>Transpose the characters at the cursor. +</dl> + + <p>The next group of commands deal with <dfn>killing</dfn>, and <dfn>yanking</dfn> +text<a rel="footnote" href="#fn-6" name="fnd-6"><sup>6</sup></a>. For an in-depth discussion of killing and +yanking, see <a href="emacs.html#Killing">Killing and Deleting (the GNU Emacs Manual)</a>. + + <dl> +<dt><M-d> (<code>echo-area-kill-word</code>)<dt><M-X>, vi-like operation<dd><a name="index-M_002dd_002c-in-the-echo-area-293"></a><a name="index-M_002dX_002c-in-the-echo-area_002c-vi_002dlike-operation-294"></a><a name="index-echo_002darea_002dkill_002dword-295"></a>Kill the word following the cursor. + + <br><dt><M-DEL> (<code>echo-area-backward-kill-word</code>)<dt><M-<BS>><dd><a name="index-M_002dDEL_002c-in-the-echo-area-296"></a><a name="index-echo_002darea_002dbackward_002dkill_002dword-297"></a>Kill the word preceding the cursor. + + <p><a name="index-M_002dBS_002c-in-the-echo-area-298"></a>On some keyboards, the <code>Backspace</code> key is used instead of +<code>DEL</code>, so <code>M-<Backspace></code> has the same effect as +<code>M-<DEL></code>. + + <br><dt><C-k> (<code>echo-area-kill-line</code>)<dd><a name="index-C_002dk_002c-in-the-echo-area-299"></a><a name="index-echo_002darea_002dkill_002dline-300"></a>Kill the text from the cursor to the end of the line. + + <br><dt><kbd>C-x <DEL></kbd> (<code>echo-area-backward-kill-line</code>)<dd><a name="index-C_002dx-DEL_002c-in-the-echo-area-301"></a><a name="index-echo_002darea_002dbackward_002dkill_002dline-302"></a>Kill the text from the cursor to the beginning of the line. + + <br><dt><C-y> (<code>echo-area-yank</code>)<dd><a name="index-C_002dy_002c-in-the-echo-area-303"></a><a name="index-echo_002darea_002dyank-304"></a>Yank back the contents of the last kill. + + <br><dt><M-y> (<code>echo-area-yank-pop</code>)<dd><a name="index-M_002dy_002c-in-the-echo-area-305"></a><a name="index-echo_002darea_002dyank_002dpop-306"></a>Yank back a previous kill, removing the last yanked text first. +</dl> + + <p><a name="index-completion-307"></a>Sometimes when reading input in the echo area, the command that needed +input will only accept one of a list of several choices. The choices +represent the <dfn>possible completions</dfn>, and you must respond with one +of them. Since there are a limited number of responses you can make, +Info allows you to abbreviate what you type, only typing as much of the +response as is necessary to uniquely identify it. In addition, you can +request Info to fill in as much of the response as is possible; this +is called <dfn>completion</dfn>. + + <p>The following commands are available when completing in the echo area: + + <dl> +<dt><TAB> (<code>echo-area-complete</code>)<dt><SPC><dd><a name="index-TAB_002c-in-the-echo-area-308"></a><a name="index-SPC_002c-in-the-echo-area-309"></a><a name="index-echo_002darea_002dcomplete-310"></a>Insert as much of a completion as is possible. + + <br><dt><?> (<code>echo-area-possible-completions</code>)<dd><a name="index-_003f_002c-in-the-echo-area-311"></a><a name="index-echo_002darea_002dpossible_002dcompletions-312"></a>Display a window containing a list of the possible completions of what +you have typed so far. For example, if the available choices are: + + <pre class="example"> bar + foliate + food + forget + </pre> + <p class="noindent">and you have typed an <span class="samp">f</span>, followed by <span class="samp">?</span>, Info will pop up a +window showing a node called <span class="samp">*Completions*</span> which lists the +possible completions like this: + + <pre class="example"> 3 completions: + foliate food + forget + </pre> + <p class="noindent">i.e., all of the choices which begin with <span class="samp">f</span>. Pressing <SPC> +or <TAB> would result in <span class="samp">fo</span> appearing in the echo area, since +all of the choices which begin with <span class="samp">f</span> continue with <span class="samp">o</span>. +Now, typing <span class="samp">l</span> followed by <span class="samp">TAB</span> results in <span class="samp">foliate</span> +appearing in the echo area, since that is the only choice which begins +with <span class="samp">fol</span>. + + <br><dt><ESC C-v> (<code>echo-area-scroll-completions-window</code>)<dd><a name="index-ESC-C_002dv_002c-in-the-echo-area-313"></a><a name="index-echo_002darea_002dscroll_002dcompletions_002dwindow-314"></a>Scroll the completions window, if that is visible, or the "other" +window if not. +</dl> + +<div class="node"> +<p><hr> +<a name="Printing-Nodes"></a>Next: <a rel="next" accesskey="n" href="#Miscellaneous-Commands">Miscellaneous Commands</a>, +Previous: <a rel="previous" accesskey="p" href="#Window-Commands">Window Commands</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> +<br> +</div> + +<h2 class="chapter">9 Printing Nodes</h2> + +<p><a name="index-printing-315"></a> +In general, we recommend that you use TeX to format the document and +print sections of it, by running <code>tex</code> on the Texinfo source file. +However, you may wish to print out the contents of a node as a quick +reference document for later use, or if you don't have TeX installed. +Info provides you with a command for doing this. + + <dl> +<dt><kbd>M-x print-node</kbd><dd><a name="index-print_002dnode-316"></a><a name="index-INFO_005fPRINT_005fCOMMAND_002c-environment-variable-317"></a>Pipe the contents of the current node through the command in the +environment variable <code>INFO_PRINT_COMMAND</code>. If the variable does not +exist, the node is simply piped to <code>lpr</code> (on DOS/Windows, the +default is to print the node to the local printer device, <span class="file">PRN</span>). + + <p><a name="index-printing-nodes-to-the-local-printer-318"></a><a name="index-local-printer-device-319"></a>The value of <code>INFO_PRINT_COMMAND</code> may begin with the <span class="samp">></span> +character, as in <span class="samp">>/dev/printer</span>, in which case Info treats the +rest as the name of a file or a device. Instead of piping to a command, +Info opens the file, writes the node contents, and closes the file, +under the assumption that text written to that file will be printed by +the underlying OS. +</dl> + +<div class="node"> +<p><hr> +<a name="Miscellaneous-Commands"></a>Next: <a rel="next" accesskey="n" href="#Variables">Variables</a>, +Previous: <a rel="previous" accesskey="p" href="#Printing-Nodes">Printing Nodes</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> +<br> +</div> + +<h2 class="chapter">10 Miscellaneous Commands</h2> + +<p>GNU Info contains several commands which self-document GNU Info: + + <dl> +<dt><kbd>M-x describe-command</kbd><dd><a name="index-functions_002c-describing-320"></a><a name="index-commands_002c-describing-321"></a><a name="index-describe_002dcommand-322"></a>Read the name of an Info command in the echo area and then display a +brief description of what that command does. + + <br><dt><kbd>M-x describe-key</kbd><dd><a name="index-keys_002c-describing-323"></a><a name="index-describe_002dkey-324"></a>Read a key sequence in the echo area, and then display the name and +documentation of the Info command that the key sequence invokes. + + <br><dt><kbd>M-x describe-variable</kbd><dd>Read the name of a variable in the echo area and then display a brief +description of what the variable affects. + + <br><dt><kbd>M-x where-is</kbd><dd><a name="index-where_002dis-325"></a>Read the name of an Info command in the echo area, and then display +a key sequence which can be typed in order to invoke that command. + + <br><dt><C-h> (<code>get-help-window</code>)<dt><?><dt><F1> (on DOS/Windows only)<dt>h, vi-like operation<dd><a name="index-C_002dh-326"></a><a name="index-_003f_002c-in-Info-windows-327"></a><a name="index-F1-328"></a><a name="index-h_002c-vi_002dlike-operation-329"></a><a name="index-get_002dhelp_002dwindow-330"></a>Create (or Move into) the window displaying <code>*Help*</code>, and place +a node containing a quick reference card into it. This window displays +the most concise information about GNU Info available. + + <br><dt><h> (<code>get-info-help-node</code>)<dt><M-h>, vi-like operation<dd><a name="index-h-331"></a><a name="index-M_002dh_002c-vi_002dlike-operation-332"></a><a name="index-get_002dinfo_002dhelp_002dnode-333"></a>Try hard to visit the node <code>(info)Help</code>. The Info file +<span class="file">info.texi</span> distributed with GNU Info contains this node. Of +course, the file must first be processed with <code>makeinfo</code>, and then +placed into the location of your Info directory. +</dl> + + <p>Here are the commands for creating a numeric argument: + + <dl> +<dt><C-u> (<code>universal-argument</code>)<dd><a name="index-numeric-arguments-334"></a><a name="index-C_002du-335"></a><a name="index-universal_002dargument-336"></a>Start (or multiply by 4) the current numeric argument. <span class="samp">C-u</span> is +a good way to give a small numeric argument to cursor movement or +scrolling commands; <span class="samp">C-u C-v</span> scrolls the screen 4 lines, while +<span class="samp">C-u C-u C-n</span> moves the cursor down 16 lines. <span class="samp">C-u</span> followed +by digit keys sets the numeric argument to the number thus typed: +<kbd>C-u 1 2 0</kbd> sets the argument to 120. + + <br><dt><M-1> (<code>add-digit-to-numeric-arg</code>)<dt><1>, vi-like operation<dt><M-2> <small class="dots">...</small> <M-9><dt><2> <small class="dots">...</small> <9>, vi-like operation<dt><M-0><dt><0>, vi-like operation<dd><a name="index-M_002d0-_0040dots_007b_007d-M_002d9-337"></a><a name="index-0-_0040dots_007b_007d-9_002c-vi_002dlike-operation-338"></a><a name="index-add_002ddigit_002dto_002dnumeric_002darg-339"></a>Add the digit value of the invoking key to the current numeric +argument. Once Info is reading a numeric argument, you may just type +the digits of the argument, without the Meta prefix. For example, you +might give <span class="samp">C-l</span> a numeric argument of 32 by typing: + + <pre class="example"> <kbd>C-u 3 2 C-l</kbd> + </pre> + <p class="noindent">or + + <pre class="example"> <kbd>M-3 2 C-l</kbd> + </pre> + <br><dt><M–> (<code>add-digit-to-numeric-arg</code><dt><-><dd><a name="index-M_002d_002d-340"></a><a name="index-_002d-341"></a><a name="index-negative-arguments-342"></a><a name="index-arguments_002c-negative-343"></a><a name="index-numeric-arguments_002c-negative-344"></a>To make a negative argument, type <kbd>-</kbd>. Typing <kbd>-</kbd> alone makes a +negative argument with a value of -1. If you continue to type digit or +Meta-digit keys after <kbd>-</kbd>, the result is a negative number produced +by those digits. + + <p><kbd>-</kbd> doesn't work when you type in the echo area, because you need to +be able to insert the <span class="samp">-</span> character itself; use <kbd>M--</kbd> instead, +if you need to specify negative arguments in the echo area. +</dl> + + <p><span class="samp">C-g</span> is used to abort the reading of a multi-character key +sequence, to cancel lengthy operations (such as multi-file searches) and +to cancel reading input in the echo area. + + <dl> +<dt><C-g> (<code>abort-key</code>)<dt><C-u>, vi-like operation<dd><a name="index-cancelling-typeahead-345"></a><a name="index-cancelling-the-current-operation-346"></a><a name="index-C_002dg_002c-in-Info-windows-347"></a><a name="index-C_002du-cancels-typeahead_002c-vi_002dlike-operation-348"></a><a name="index-abort_002dkey-349"></a>Cancel current operation. +</dl> + + <p>The <span class="samp">q</span> command of Info simply quits running Info. Under +<span class="samp">--vi-keys</span> (see <a href="#_002d_002dvi_002dkeys">–vi-keys</a>), you can also exit with <span class="samp">:q</span> +or <span class="samp">ZZ</span>. + + <dl> +<dt><q> (<code>quit</code>)<dt><kbd>C-x C-c</kbd><dt><kbd>:q</kbd>, vi-like operation<dt><kbd>ZZ</kbd>, vi-like operation<dd><a name="index-quitting-350"></a><a name="index-q-351"></a><a name="index-C_002dx-C_002dc-352"></a><a name="index-ZZ_002c-vi_002dlike-operation-353"></a><a name="index-quit-354"></a>Exit GNU Info. +</dl> + + <p>If the operating system tells GNU Info that the screen is 60 lines tall, +and it is actually only 40 lines tall, here is a way to tell Info that +the operating system is correct. + + <dl> +<dt><kbd>M-x set-screen-height</kbd><dd><a name="index-set_002dscreen_002dheight-355"></a><a name="index-screen_002c-changing-the-height-of-356"></a>Read a height value in the echo area and set the height of the +displayed screen to that value. +</dl> + + <p>On MS-DOS/MS-Windows, this command actually tries to change the +dimensions of the visible screen to the value you type in the echo +area. + + <p>Finally, Info provides a convenient way to display footnotes which might +be associated with the current node that you are viewing: + + <dl> +<dt><ESC C-f> (<code>show-footnotes</code>)<dd><a name="index-ESC-C_002df-357"></a><a name="index-show_002dfootnotes-358"></a><a name="index-footnotes_002c-displaying-359"></a>Show the footnotes (if any) associated with the current node in another +window. You can have Info automatically display the footnotes +associated with a node when the node is selected by setting the variable +<code>automatic-footnotes</code>. See <a href="#Variables"><code>automatic-footnotes</code></a>. +</dl> + +<div class="node"> +<p><hr> +<a name="Variables"></a>Next: <a rel="next" accesskey="n" href="#Custom-Key-Bindings">Custom Key Bindings</a>, +Previous: <a rel="previous" accesskey="p" href="#Miscellaneous-Commands">Miscellaneous Commands</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> +<br> +</div> + +<h2 class="chapter">11 Manipulating Variables</h2> + +<p>GNU Info contains several <dfn>variables</dfn> whose values are looked at by +various Info commands. You can change the values of these variables, +and thus change the behavior of Info to more closely match your +environment and Info file reading manner. + + <p>There are two ways to set the value of a variable: interactively, using +the <code>set-variable</code> command described below, or in the <code>#var</code> +section of the <code>.infokey</code> file. See <a href="#Custom-Key-Bindings">Custom Key Bindings</a>. + + <dl> +<dt><kbd>M-x set-variable</kbd><dd><a name="index-variables_002c-setting-360"></a><a name="index-set_002dvariable-361"></a>Read the name of a variable, and the value for it, in the echo area and +then set the variable to that value. Completion is available when +reading the variable name (see <a href="#The-Echo-Area">completion</a>); often, +completion is available when reading the value to give to the variable, +but that depends on the variable itself. If a variable does <em>not</em> +supply multiple choices to complete over, it expects a numeric value. + + <br><dt><kbd>M-x describe-variable</kbd><dd><a name="index-variables_002c-describing-362"></a><a name="index-describe_002dvariable-363"></a>Read the name of a variable in the echo area and then display a brief +description of what the variable affects. +</dl> + + <p>Here is a list of the variables that you can set in Info. + + <dl> +<dt><code>automatic-footnotes</code><dd><a name="index-automatic_002dfootnotes-364"></a>When set to <code>On</code>, footnotes appear and disappear automatically; +else, they appear at the bottom of the node text. This variable is +<code>Off</code> by default. When a node is selected, a window containing +the footnotes which appear in that node is created, and the footnotes +are displayed within the new window. The window that Info creates to +contain the footnotes is called <span class="samp">*Footnotes*</span>. If a node is +selected which contains no footnotes, and a <span class="samp">*Footnotes*</span> window +is on the screen, the <span class="samp">*Footnotes*</span> window is deleted. Footnote +windows created in this fashion are not automatically tiled so that +they can use as little of the display as is possible. + + <br><dt><code>automatic-tiling</code><dd><a name="index-automatic_002dtiling-365"></a>When set to <code>On</code>, creating or deleting a window resizes other +windows. This variable is <code>Off</code> by default. Normally, typing +<span class="samp">C-x 2</span> divides the current window into two equal parts. When +<code>automatic-tiling</code> is set to <code>On</code>, all of the windows are +resized automatically, keeping an equal number of lines visible in each +window. There are exceptions to the automatic tiling; specifically, the +windows <span class="samp">*Completions*</span> and <span class="samp">*Footnotes*</span> are <em>not</em> +resized through automatic tiling; they remain their original size. + + <br><dt><code>errors-ring-bell</code><dd><a name="index-errors_002dring_002dbell-366"></a>When set to <code>On</code>, errors cause the bell to ring. The default +setting of this variable is <code>On</code>. + + <br><dt><code>gc-compressed-files</code><dd><a name="index-gc_002dcompressed_002dfiles-367"></a>When set to <code>On</code>, Info garbage collects files which had to be +uncompressed. The default value of this variable is <code>Off</code>. +Whenever a node is visited in Info, the Info file containing that node +is read into core, and Info reads information about the tags and nodes +contained in that file. Once the tags information is read by Info, it +is never forgotten. However, the actual text of the nodes does not need +to remain in core unless a particular Info window needs it. For +non-compressed files, the text of the nodes does not remain in core when +it is no longer in use. But de-compressing a file can be a time +consuming operation, and so Info tries hard not to do it twice. +<code>gc-compressed-files</code> tells Info it is okay to garbage collect the +text of the nodes of a file which was compressed on disk. + + <br><dt><code>ISO-Latin</code><dd><a name="index-ISO-Latin-characters-368"></a><a name="index-ISO_002dLatin-369"></a>When set to <code>On</code>, Info accepts and displays ISO Latin characters. +By default, Info assumes an ASCII character set. <code>ISO-Latin</code> tells +Info that it is running in an environment where the European standard +character set is in use, and allows you to input such characters to +Info, as well as display them. + + <br><dt><code>scroll-behavior</code><dd><a name="index-scroll_002dbehavior-370"></a>Control what happens when forward scrolling is requested at the end of +a node, or when backward scrolling is requested at the beginning of a +node. The default value for this variable is <code>Continuous</code>. There +are three possible values for this variable: + + <dl> +<dt><code>Continuous</code><dd>Try to get the first item in this node's menu, or failing that, the +<span class="samp">Next</span> node, or failing that, the <span class="samp">Next</span> of the <span class="samp">Up</span>. +This behavior is identical to using the <span class="samp">]</span> +(<code>global-next-node</code>) and <span class="samp">[</span> (<code>global-prev-node</code>) +commands. + + <br><dt><code>Next Only</code><dd>Only try to get the <span class="samp">Next</span> node. + + <br><dt><code>Page Only</code><dd>Simply give up, changing nothing. If <code>scroll-behavior</code> is +<code>Page Only</code>, no scrolling command can change the node that is being +viewed. +</dl> + + <br><dt><code>scroll-step</code><dd><a name="index-scroll_002dstep-371"></a>The number of lines to scroll when the cursor moves out of the window. +Scrolling happens automatically if the cursor has moved out of the +visible portion of the node text when it is time to display. Usually +the scrolling is done so as to put the cursor on the center line of the +current window. However, if the variable <code>scroll-step</code> has a +nonzero value, Info attempts to scroll the node text by that many lines; +if that is enough to bring the cursor back into the window, that is what +is done. The default value of this variable is 0, thus placing the +cursor (and the text it is attached to) in the center of the window. +Setting this variable to 1 causes a kind of "smooth scrolling" which +some people prefer. + + <br><dt><code>show-index-match</code><dd><a name="index-show_002dindex_002dmatch-372"></a>When set to <code>On</code>, the portion of the matched search string is +highlighted in the message which explains where the matched search +string was found. The default value of this variable is <code>On</code>. +When Info displays the location where an index match was found, +(see <a href="#Searching-Commands"><code>next-index-match</code></a>), the portion of the +string that you had typed is highlighted by displaying it in the inverse +case from its surrounding characters. + + <br><dt><code>visible-bell</code><dd><a name="index-visible_002dbell-373"></a>When set to <code>On</code>, GNU Info attempts to flash the screen instead of +ringing the bell. This variable is <code>Off</code> by default. Of course, +Info can only flash the screen if the terminal allows it; in the case +that the terminal does not allow it, the setting of this variable has no +effect. However, you can make Info perform quietly by setting the +<code>errors-ring-bell</code> variable to <code>Off</code>. + + </dl> + +<div class="node"> +<p><hr> +<a name="Custom-Key-Bindings"></a>Next: <a rel="next" accesskey="n" href="#Copying-This-Manual">Copying This Manual</a>, +Previous: <a rel="previous" accesskey="p" href="#Variables">Variables</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> +<br> +</div> + +<h2 class="chapter">12 Customizing Key Bindings and Variables</h2> + +<p><a name="index-default-key-bindings_002c-overriding-374"></a><a name="index-overriding-default-key-bindings-375"></a><a name="index-customizing-key-bindings-376"></a><a name="index-key-bindings_002c-customizing-377"></a><a name="index-infokey-378"></a><a name="index-_002einfo-379"></a><a name="index-_002einfokey-380"></a><a name="index-_005finfo-file-_0028MS_002dDOS_0029-381"></a> +For those whose editor/pager of choice is not Emacs and who are not +entirely satisfied with the –vi-keys option (see <a href="#_002d_002dvi_002dkeys">–vi-keys</a>), GNU +Info provides a way to define different key-to-command bindings and +variable settings from the defaults described in this document. + + <p>On startup, GNU Info looks for a configuration file in the invoker's +HOME directory called <span class="file">.info</span><a rel="footnote" href="#fn-7" name="fnd-7"><sup>7</sup></a>. If it is present, and +appears to contain Info configuration data, and was created with the +current version of the <code>infokey</code> command, then Info adopts the +key bindings and variable settings contained therein. + + <p>The <span class="file">.info</span> file contains compact, non-textual data for reasons of +efficiency and because its design was lifted wholesale from the GNU Less +program, which also does it that way. It must be created by compiling a +textual source file using the <code>infokey</code> command. + +<ul class="menu"> +<li><a accesskey="1" href="#Invoking-infokey">Invoking infokey</a> +<li><a accesskey="2" href="#infokey-source-format">infokey source format</a> +</ul> + +<div class="node"> +<p><hr> +<a name="Invoking-infokey"></a>Next: <a rel="next" accesskey="n" href="#infokey-source-format">infokey source format</a>, +Up: <a rel="up" accesskey="u" href="#Custom-Key-Bindings">Custom Key Bindings</a> +<br> +</div> + +<h3 class="section">12.1 Invoking <span class="command">infokey</span></h3> + +<p><a name="index-invoking-infokey-382"></a><a name="index-infokey_002c-invoking-383"></a><a name="index-_005finfokey-file-_0028MS_002dDOS_0029-384"></a> +<span class="command">infokey</span> compiles a source file +(<span class="file">$HOME/.infokey</span><a rel="footnote" href="#fn-8" name="fnd-8"><sup>8</sup></a> by default) containing Info customizations +into a binary format (<span class="file">$HOME/.info</span> by default). GNU Info reads +the binary file at startup to override the default key bindings and +variable definitions. Synopsis: + +<pre class="example"> infokey [<var>option</var>...] [<var>input-file</var>] +</pre> + <p>Besides the standard <span class="option">--help</span> and <span class="option">--version</span>, the only +option is <span class="option">--output </span><var>file</var>. This tells <span class="command">infokey</span> to +write the binary data to <var>file</var> instead of <span class="file">$HOME/.info</span>. + +<div class="node"> +<p><hr> +<a name="infokey-source-format"></a>Previous: <a rel="previous" accesskey="p" href="#Invoking-infokey">Invoking infokey</a>, +Up: <a rel="up" accesskey="u" href="#Custom-Key-Bindings">Custom Key Bindings</a> +<br> +</div> + +<h3 class="section">12.2 <span class="command">infokey</span> source format</h3> + +<p><a name="index-infokey-source-format-385"></a><a name="index-_002einfokey-source-format-386"></a><a name="index-format-of-_002einfokey-source-387"></a> +The format of the source file read by <span class="command">infokey</span> is most easily +illustrated by example. For instance, here is a sample <span class="file">.infokey</span> +source file suitable for aficionados of <span class="command">vi</span> or <span class="command">less</span>: + +<pre class="example"> #info + j next-line + k prev-line + l forward-char + h backward-char + \kd next-line + \ku prev-line + \kr forward-char + \kl backward-char + \ scroll-forward + \kD scroll-forward-page-only + b scroll-backward + \kU scroll-backward-page-only + g beginning-of-node + \kh beginning-of-node + G end-of-node + \ke end-of-node + \t select-reference-this-line + - history-node + n next-node + p prev-node + u up-node + t top-node + d dir-node + #var + scroll-step=1 +</pre> + <p>The source file consists of one or more <dfn>sections</dfn>. +Each section starts with a line that identifies the type of section. +Possible sections are: + + <dl> +<dt><code>#info</code><dd>Key bindings for Info windows. +The start of this section is indicated by a line containing just +<code>#info</code> by itself. If this is the first section in the source +file, the <code>#info</code> line can be omitted. The rest of this section +consists of lines of the form: + + <pre class="example"> <var>string</var> whitespace <var>action</var> [ whitespace [ # comment ] ] newline + </pre> + <p>Whitespace is any sequence of one or more spaces and/or tabs. Comment +is any sequence of any characters, excluding newline. <var>string</var> is +the key sequence which invokes the action. <var>action</var> is the name of +an Info command. The characters in <var>string</var> are interpreted +literally or prefixed by a caret (<code>^</code>) to indicate a control +character. A backslash followed by certain characters specifies input +keystrokes as follows: + + <dl> +<dt><code>\b</code><dd>Backspace +<br><dt><code>\e</code><dd>Escape (ESC) +<br><dt><code>\n</code><dd>Newline +<br><dt><code>\r</code><dd>Return +<br><dt><code>\t</code><dd>Tab +<br><dt><code>\ku</code><dd>Up arrow +<br><dt><code>\kd</code><dd>Down arrow +<br><dt><code>\kl</code><dd>Left arrow +<br><dt><code>\kr</code><dd>Right arrow +<br><dt><code>\kU</code><dd>Page Up +<br><dt><code>\kD</code><dd>Page Down +<br><dt><code>\kh</code><dd>HOME +<br><dt><code>\ke</code><dd>END +<br><dt><code>\kx</code><dd>Delete (DEL) +<br><dt><code>\m</code><var>x</var><dd>Meta-<var>x</var> where <var>x</var> is any character as described above. +</dl> + + <p>Backslash followed by any other character indicates that character is to +be taken literally. Characters which must be preceded by a backslash +include caret, space, tab, and backslash itself. + + <br><dt><code>#echo-area</code><dd>Key bindings for the echo area. +The start of this section is indicated by a line containing just +<code>#echo-area</code> by itself. The rest of this section has a syntax +identical to that for the key definitions for the Info area, described +above. + + <br><dt><code>#var</code><dd>Variable initializations. +The start of this section is indicated by a line containing just +<code>#var</code> by itself. Following this line is a list of variable +assignments, one per line. Each line consists of a variable name +(See <a href="#Variables">Variables</a>,) followed by <code>=</code> followed by a value. +There may be no white space between the variable name and the <code>=</code>, +and all characters following the <code>=</code>, including white space, +are included in the value. +</dl> + + <p>Blank lines and lines starting with <code>#</code> are ignored, except for +the special section header lines. + + <p>Key bindings defined in the <span class="file">.info</span> file take precedence over GNU +Info's default key bindings, whether or not <span class="samp">--vi-keys</span> is used. A +default key binding may be disabled by overriding it in the <span class="file">.info</span> +file with the action <code>invalid</code>. In addition, <em>all</em> default +key bindings can be disabled by adding this line <em>anywhere</em> in the +relevant section: + +<pre class="example"> #stop +</pre> + <p>This will cause GNU Info to ignore all the default key commands for that +section. + + <p>Beware: <code>#stop</code> can be dangerous. Since it disables all default +key bindings, you must supply enough new key bindings to enable all +necessary actions. Failure to bind any key to the <code>quit</code> command, +for example, can lead to frustration. + + <p>The order in which key bindings are defined in the <span class="file">.info</span> file is +not important, except that the command summary produced by the +<code>get-help-window</code> command only displays the <em>first</em> key that +is bound to each command. + +<!-- the following is incomplete --> +<div class="node"> +<p><hr> +<a name="Copying-This-Manual"></a>Next: <a rel="next" accesskey="n" href="#Index">Index</a>, +Previous: <a rel="previous" accesskey="p" href="#Custom-Key-Bindings">Custom Key Bindings</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> +<br> +</div> + +<h2 class="appendix">Appendix A Copying This Manual</h2> + +<ul class="menu"> +<li><a accesskey="1" href="#GNU-Free-Documentation-License">GNU Free Documentation License</a>: License for copying this manual. +</ul> + +<div class="node"> +<p><hr> +<a name="GNU-Free-Documentation-License"></a>Up: <a rel="up" accesskey="u" href="#Copying-This-Manual">Copying This Manual</a> +<br> +</div> + +<h3 class="appendixsec">A.1 GNU Free Documentation License</h3> + +<p><a name="index-FDL_002c-GNU-Free-Documentation-License-388"></a><div align="center">Version 1.2, November 2002</div> + +<pre class="display"> Copyright © 2000,2001,2002 Free Software Foundation, Inc. + 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA + + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. +</pre> + <ol type=1 start=0> +<li>PREAMBLE + + <p>The purpose of this License is to make a manual, textbook, or other +functional and useful document <dfn>free</dfn> in the sense of freedom: to +assure everyone the effective freedom to copy and redistribute it, +with or without modifying it, either commercially or noncommercially. +Secondarily, this License preserves for the author and publisher a way +to get credit for their work, while not being considered responsible +for modifications made by others. + + <p>This License is a kind of “copyleft”, which means that derivative +works of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft +license designed for free software. + + <p>We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference. + + <li>APPLICABILITY AND DEFINITIONS + + <p>This License applies to any manual or other work, in any medium, that +contains a notice placed by the copyright holder saying it can be +distributed under the terms of this License. Such a notice grants a +world-wide, royalty-free license, unlimited in duration, to use that +work under the conditions stated herein. The “Document”, below, +refers to any such manual or work. Any member of the public is a +licensee, and is addressed as “you”. You accept the license if you +copy, modify or distribute the work in a way requiring permission +under copyright law. + + <p>A “Modified Version” of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. + + <p>A “Secondary Section” is a named appendix or a front-matter section +of the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall +subject (or to related matters) and contains nothing that could fall +directly within that overall subject. (Thus, if the Document is in +part a textbook of mathematics, a Secondary Section may not explain +any mathematics.) The relationship could be a matter of historical +connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding +them. + + <p>The “Invariant Sections” are certain Secondary Sections whose titles +are designated, as being those of Invariant Sections, in the notice +that says that the Document is released under this License. If a +section does not fit the above definition of Secondary then it is not +allowed to be designated as Invariant. The Document may contain zero +Invariant Sections. If the Document does not identify any Invariant +Sections then there are none. + + <p>The “Cover Texts” are certain short passages of text that are listed, +as Front-Cover Texts or Back-Cover Texts, in the notice that says that +the Document is released under this License. A Front-Cover Text may +be at most 5 words, and a Back-Cover Text may be at most 25 words. + + <p>A “Transparent” copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, that is suitable for revising the document +straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available +drawing editor, and that is suitable for input to text formatters or +for automatic translation to a variety of formats suitable for input +to text formatters. A copy made in an otherwise Transparent file +format whose markup, or absence of markup, has been arranged to thwart +or discourage subsequent modification by readers is not Transparent. +An image format is not Transparent if used for any substantial amount +of text. A copy that is not “Transparent” is called “Opaque”. + + <p>Examples of suitable formats for Transparent copies include plain +<span class="sc">ascii</span> without markup, Texinfo input format, LaTeX input +format, <acronym>SGML</acronym> or <acronym>XML</acronym> using a publicly available +<acronym>DTD</acronym>, and standard-conforming simple <acronym>HTML</acronym>, +PostScript or <acronym>PDF</acronym> designed for human modification. Examples +of transparent image formats include <acronym>PNG</acronym>, <acronym>XCF</acronym> and +<acronym>JPG</acronym>. Opaque formats include proprietary formats that can be +read and edited only by proprietary word processors, <acronym>SGML</acronym> or +<acronym>XML</acronym> for which the <acronym>DTD</acronym> and/or processing tools are +not generally available, and the machine-generated <acronym>HTML</acronym>, +PostScript or <acronym>PDF</acronym> produced by some word processors for +output purposes only. + + <p>The “Title Page” means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, “Title Page” means +the text near the most prominent appearance of the work's title, +preceding the beginning of the body of the text. + + <p>A section “Entitled XYZ” means a named subunit of the Document whose +title either is precisely XYZ or contains XYZ in parentheses following +text that translates XYZ in another language. (Here XYZ stands for a +specific section name mentioned below, such as “Acknowledgements”, +“Dedications”, “Endorsements”, or “History”.) To “Preserve the Title” +of such a section when you modify the Document means that it remains a +section “Entitled XYZ” according to this definition. + + <p>The Document may include Warranty Disclaimers next to the notice which +states that this License applies to the Document. These Warranty +Disclaimers are considered to be included by reference in this +License, but only as regards disclaiming warranties: any other +implication that these Warranty Disclaimers may have is void and has +no effect on the meaning of this License. + + <li>VERBATIM COPYING + + <p>You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies +to the Document are reproduced in all copies, and that you add no other +conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in section 3. + + <p>You may also lend copies, under the same conditions stated above, and +you may publicly display copies. + + <li>COPYING IN QUANTITY + + <p>If you publish printed copies (or copies in media that commonly have +printed covers) of the Document, numbering more than 100, and the +Document's license notice requires Cover Texts, you must enclose the +copies in covers that carry, clearly and legibly, all these Cover +Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on +the back cover. Both covers must also clearly and legibly identify +you as the publisher of these copies. The front cover must present +the full title with all words of the title equally prominent and +visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve +the title of the Document and satisfy these conditions, can be treated +as verbatim copying in other respects. + + <p>If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. + + <p>If you publish or distribute Opaque copies of the Document numbering +more than 100, you must either include a machine-readable Transparent +copy along with each Opaque copy, or state in or with each Opaque copy +a computer-network location from which the general network-using +public has access to download using public-standard network protocols +a complete Transparent copy of the Document, free of added material. +If you use the latter option, you must take reasonably prudent steps, +when you begin distribution of Opaque copies in quantity, to ensure +that this Transparent copy will remain thus accessible at the stated +location until at least one year after the last time you distribute an +Opaque copy (directly or through your agents or retailers) of that +edition to the public. + + <p>It is requested, but not required, that you contact the authors of the +Document well before redistributing any large number of copies, to give +them a chance to provide you with an updated version of the Document. + + <li>MODIFICATIONS + + <p>You may copy and distribute a Modified Version of the Document under +the conditions of sections 2 and 3 above, provided that you release +the Modified Version under precisely this License, with the Modified +Version filling the role of the Document, thus licensing distribution +and modification of the Modified Version to whoever possesses a copy +of it. In addition, you must do these things in the Modified Version: + + <ol type=A start=1> +<li>Use in the Title Page (and on the covers, if any) a title distinct +from that of the Document, and from those of previous versions +(which should, if there were any, be listed in the History section +of the Document). You may use the same title as a previous version +if the original publisher of that version gives permission. + + <li>List on the Title Page, as authors, one or more persons or entities +responsible for authorship of the modifications in the Modified +Version, together with at least five of the principal authors of the +Document (all of its principal authors, if it has fewer than five), +unless they release you from this requirement. + + <li>State on the Title page the name of the publisher of the +Modified Version, as the publisher. + + <li>Preserve all the copyright notices of the Document. + + <li>Add an appropriate copyright notice for your modifications +adjacent to the other copyright notices. + + <li>Include, immediately after the copyright notices, a license notice +giving the public permission to use the Modified Version under the +terms of this License, in the form shown in the Addendum below. + + <li>Preserve in that license notice the full lists of Invariant Sections +and required Cover Texts given in the Document's license notice. + + <li>Include an unaltered copy of this License. + + <li>Preserve the section Entitled “History”, Preserve its Title, and add +to it an item stating at least the title, year, new authors, and +publisher of the Modified Version as given on the Title Page. If +there is no section Entitled “History” in the Document, create one +stating the title, year, authors, and publisher of the Document as +given on its Title Page, then add an item describing the Modified +Version as stated in the previous sentence. + + <li>Preserve the network location, if any, given in the Document for +public access to a Transparent copy of the Document, and likewise +the network locations given in the Document for previous versions +it was based on. These may be placed in the “History” section. +You may omit a network location for a work that was published at +least four years before the Document itself, or if the original +publisher of the version it refers to gives permission. + + <li>For any section Entitled “Acknowledgements” or “Dedications”, Preserve +the Title of the section, and preserve in the section all the +substance and tone of each of the contributor acknowledgements and/or +dedications given therein. + + <li>Preserve all the Invariant Sections of the Document, +unaltered in their text and in their titles. Section numbers +or the equivalent are not considered part of the section titles. + + <li>Delete any section Entitled “Endorsements”. Such a section +may not be included in the Modified Version. + + <li>Do not retitle any existing section to be Entitled “Endorsements” or +to conflict in title with any Invariant Section. + + <li>Preserve any Warranty Disclaimers. + </ol> + + <p>If the Modified Version includes new front-matter sections or +appendices that qualify as Secondary Sections and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the +list of Invariant Sections in the Modified Version's license notice. +These titles must be distinct from any other section titles. + + <p>You may add a section Entitled “Endorsements”, provided it contains +nothing but endorsements of your Modified Version by various +parties—for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of a +standard. + + <p>You may add a passage of up to five words as a Front-Cover Text, and a +passage of up to 25 words as a Back-Cover Text, to the end of the list +of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already +includes a cover text for the same cover, previously added by you or +by arrangement made by the same entity you are acting on behalf of, +you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. + + <p>The author(s) and publisher(s) of the Document do not by this License +give permission to use their names for publicity for or to assert or +imply endorsement of any Modified Version. + + <li>COMBINING DOCUMENTS + + <p>You may combine the Document with other documents released under this +License, under the terms defined in section 4 above for modified +versions, provided that you include in the combination all of the +Invariant Sections of all of the original documents, unmodified, and +list them all as Invariant Sections of your combined work in its +license notice, and that you preserve all their Warranty Disclaimers. + + <p>The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name but +different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original +author or publisher of that section if known, or else a unique number. +Make the same adjustment to the section titles in the list of +Invariant Sections in the license notice of the combined work. + + <p>In the combination, you must combine any sections Entitled “History” +in the various original documents, forming one section Entitled +“History”; likewise combine any sections Entitled “Acknowledgements”, +and any sections Entitled “Dedications”. You must delete all +sections Entitled “Endorsements.” + + <li>COLLECTIONS OF DOCUMENTS + + <p>You may make a collection consisting of the Document and other documents +released under this License, and replace the individual copies of this +License in the various documents with a single copy that is included in +the collection, provided that you follow the rules of this License for +verbatim copying of each of the documents in all other respects. + + <p>You may extract a single document from such a collection, and distribute +it individually under this License, provided you insert a copy of this +License into the extracted document, and follow this License in all +other respects regarding verbatim copying of that document. + + <li>AGGREGATION WITH INDEPENDENT WORKS + + <p>A compilation of the Document or its derivatives with other separate +and independent documents or works, in or on a volume of a storage or +distribution medium, is called an “aggregate” if the copyright +resulting from the compilation is not used to limit the legal rights +of the compilation's users beyond what the individual works permit. +When the Document is included in an aggregate, this License does not +apply to the other works in the aggregate which are not themselves +derivative works of the Document. + + <p>If the Cover Text requirement of section 3 is applicable to these +copies of the Document, then if the Document is less than one half of +the entire aggregate, the Document's Cover Texts may be placed on +covers that bracket the Document within the aggregate, or the +electronic equivalent of covers if the Document is in electronic form. +Otherwise they must appear on printed covers that bracket the whole +aggregate. + + <li>TRANSLATION + + <p>Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of section 4. +Replacing Invariant Sections with translations requires special +permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include a +translation of this License, and all the license notices in the +Document, and any Warranty Disclaimers, provided that you also include +the original English version of this License and the original versions +of those notices and disclaimers. In case of a disagreement between +the translation and the original version of this License or a notice +or disclaimer, the original version will prevail. + + <p>If a section in the Document is Entitled “Acknowledgements”, +“Dedications”, or “History”, the requirement (section 4) to Preserve +its Title (section 1) will typically require changing the actual +title. + + <li>TERMINATION + + <p>You may not copy, modify, sublicense, or distribute the Document except +as expressly provided for under this License. Any other attempt to +copy, modify, sublicense or distribute the Document is void, and will +automatically terminate your rights under this License. However, +parties who have received copies, or rights, from you under this +License will not have their licenses terminated so long as such +parties remain in full compliance. + + <li>FUTURE REVISIONS OF THIS LICENSE + + <p>The Free Software Foundation may publish new, revised versions +of the GNU Free Documentation License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. See +<a href="http://www.gnu.org/copyleft/">http://www.gnu.org/copyleft/</a>. + + <p>Each version of the License is given a distinguishing version number. +If the Document specifies that a particular numbered version of this +License “or any later version” applies to it, you have the option of +following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation. + </ol> + +<h4 class="appendixsubsec">A.1.1 ADDENDUM: How to use this License for your documents</h4> + +<p>To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and +license notices just after the title page: + +<pre class="smallexample"> Copyright (C) <var>year</var> <var>your name</var>. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.2 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover + Texts. A copy of the license is included in the section entitled ``GNU + Free Documentation License''. +</pre> + <p>If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, +replace the “with...Texts.” line with this: + +<pre class="smallexample"> with the Invariant Sections being <var>list their titles</var>, with + the Front-Cover Texts being <var>list</var>, and with the Back-Cover Texts + being <var>list</var>. +</pre> + <p>If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + + <p>If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, +to permit their use in free software. + +<!-- Local Variables: --> +<!-- ispell-local-pdict: "ispell-dict" --> +<!-- End: --> +<div class="node"> +<p><hr> +<a name="Index"></a>Previous: <a rel="previous" accesskey="p" href="#Copying-This-Manual">Copying This Manual</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> +<br> +</div> + +<h2 class="appendix">Appendix B Index</h2> + +<ul class="index-cp" compact> +<li><a href="#index-_0027_002c-vi_002dlike-operation-137"><code>', vi-like operation</code></a>: <a href="#Node-Commands">Node Commands</a></li> +<li><a href="#index-_002c-199"><code>,</code></a>: <a href="#Searching-Commands">Searching Commands</a></li> +<li><a href="#index-_002d-341"><code>-</code></a>: <a href="#Miscellaneous-Commands">Miscellaneous Commands</a></li> +<li><a href="#index-_0040code_007b_002d_002dsubnodes_007d_002c-command-line-option-30"><code>--subnodes</code>, command line option</a>: <a href="#Invoking-Info">Invoking Info</a></li> +<li><a href="#index-_002einfo-379">.info</a>: <a href="#Custom-Key-Bindings">Custom Key Bindings</a></li> +<li><a href="#index-_002einfokey-380">.infokey</a>: <a href="#Custom-Key-Bindings">Custom Key Bindings</a></li> +<li><a href="#index-_002einfokey-source-format-386">.infokey source format</a>: <a href="#infokey-source-format">infokey source format</a></li> +<li><a href="#index-_002f-175"><code>/</code></a>: <a href="#Searching-Commands">Searching Commands</a></li> +<li><a href="#index-0-_0040dots_007b_007d-9_002c-vi_002dlike-operation-338"><code>0 ... 9, vi-like operation</code></a>: <a href="#Miscellaneous-Commands">Miscellaneous Commands</a></li> +<li><a href="#index-0_002c-in-Info-windows-209"><code>0, in Info windows</code></a>: <a href="#Selecting-Xrefs">Selecting Xrefs</a></li> +<li><a href="#index-1-_0040dots_007b_007d-9_002c-in-Info-windows-204">1 <small class="dots">...</small> 9, in Info windows</a>: <a href="#Selecting-Xrefs">Selecting Xrefs</a></li> +<li><a href="#index-_003c-145"><code><</code></a>: <a href="#Node-Commands">Node Commands</a></li> +<li><a href="#index-_003e-148"><code>></code></a>: <a href="#Node-Commands">Node Commands</a></li> +<li><a href="#index-_003f_002c-in-Info-windows-327"><code>?, in Info windows</code></a>: <a href="#Miscellaneous-Commands">Miscellaneous Commands</a></li> +<li><a href="#index-_003f_002c-in-the-echo-area-311"><code>?, in the echo area</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> +<li><a href="#index-_003f_002c-vi_002dlike-operation-177"><code>?, vi-like operation</code></a>: <a href="#Searching-Commands">Searching Commands</a></li> +<li><a href="#index-_005b-153"><code>[</code></a>: <a href="#Node-Commands">Node Commands</a></li> +<li><a href="#index-_005d-151"><code>]</code></a>: <a href="#Node-Commands">Node Commands</a></li> +<li><a href="#index-_005finfo-file-_0028MS_002dDOS_0029-381">_info file (MS-DOS)</a>: <a href="#Custom-Key-Bindings">Custom Key Bindings</a></li> +<li><a href="#index-_005finfokey-file-_0028MS_002dDOS_0029-384">_infokey file (MS-DOS)</a>: <a href="#Invoking-infokey">Invoking infokey</a></li> +<li><a href="#index-abort_002dkey-349"><code>abort-key</code></a>: <a href="#Miscellaneous-Commands">Miscellaneous Commands</a></li> +<li><a href="#index-add_002ddigit_002dto_002dnumeric_002darg-339"><code>add-digit-to-numeric-arg</code></a>: <a href="#Miscellaneous-Commands">Miscellaneous Commands</a></li> +<li><a href="#index-ANSI-escape-sequences-in-documents-25">ANSI escape sequences in documents</a>: <a href="#Invoking-Info">Invoking Info</a></li> +<li><a href="#index-Apropos_0040r_007b_002c-in-Info-files_007d-8">Apropos<span class="roman">, in Info files</span></a>: <a href="#Invoking-Info">Invoking Info</a></li> +<li><a href="#index-arguments_002c-command-line-5">arguments, command line</a>: <a href="#Invoking-Info">Invoking Info</a></li> +<li><a href="#index-arguments_002c-negative-343">arguments, negative</a>: <a href="#Miscellaneous-Commands">Miscellaneous Commands</a></li> +<li><a href="#index-automatic_002dfootnotes-364"><code>automatic-footnotes</code></a>: <a href="#Variables">Variables</a></li> +<li><a href="#index-automatic_002dtiling-365"><code>automatic-tiling</code></a>: <a href="#Variables">Variables</a></li> +<li><a href="#index-b_002c-in-Info-windows-63"><code>b, in Info windows</code></a>: <a href="#Cursor-Commands">Cursor Commands</a></li> +<li><a href="#index-b_002c-vi_002dlike-operation-90"><code>b, vi-like operation</code></a>: <a href="#Scrolling-Commands">Scrolling Commands</a></li> +<li><a href="#index-BackTab_002c-in-Info-windows-225"><code>BackTab, in Info windows</code></a>: <a href="#Selecting-Xrefs">Selecting Xrefs</a></li> +<li><a href="#index-BackTab_002c-in-the-echo-area-290"><code>BackTab, in the echo area</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> +<li><a href="#index-backward_002dchar-56"><code>backward-char</code></a>: <a href="#Cursor-Commands">Cursor Commands</a></li> +<li><a href="#index-backward_002dword-62"><code>backward-word</code></a>: <a href="#Cursor-Commands">Cursor Commands</a></li> +<li><a href="#index-beginning_002dof_002dline-47"><code>beginning-of-line</code></a>: <a href="#Cursor-Commands">Cursor Commands</a></li> +<li><a href="#index-beginning_002dof_002dnode-67"><code>beginning-of-node</code></a>: <a href="#Cursor-Commands">Cursor Commands</a></li> +<li><a href="#index-BS-_0028backspace_0029-116"><code>BS (backspace)</code></a>: <a href="#Scrolling-Commands">Scrolling Commands</a></li> +<li><a href="#index-C_002da_002c-in-Info-windows-45"><code>C-a, in Info windows</code></a>: <a href="#Cursor-Commands">Cursor Commands</a></li> +<li><a href="#index-C_002da_002c-in-the-echo-area-258"><code>C-a, in the echo area</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> +<li><a href="#index-C_002db_002c-in-Info-windows-54"><code>C-b, in Info windows</code></a>: <a href="#Cursor-Commands">Cursor Commands</a></li> +<li><a href="#index-C_002db_002c-in-the-echo-area-255"><code>C-b, in the echo area</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> +<li><a href="#index-C_002db_002c-vi_002dlike-operation-91"><code>C-b, vi-like operation</code></a>: <a href="#Scrolling-Commands">Scrolling Commands</a></li> +<li><a href="#index-C_002dCENTER-136"><code>C-CENTER</code></a>: <a href="#Node-Commands">Node Commands</a></li> +<li><a href="#index-C_002dd_002c-in-the-echo-area-271"><code>C-d, in the echo area</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> +<li><a href="#index-C_002dd_002c-vi_002dlike-operation-109"><code>C-d, vi-like operation</code></a>: <a href="#Scrolling-Commands">Scrolling Commands</a></li> +<li><a href="#index-C_002de_002c-in-Info-windows-48"><code>C-e, in Info windows</code></a>: <a href="#Cursor-Commands">Cursor Commands</a></li> +<li><a href="#index-C_002de_002c-in-the-echo-area-261"><code>C-e, in the echo area</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> +<li><a href="#index-C_002de_002c-vi_002dlike-operation-96"><code>C-e, vi-like operation</code></a>: <a href="#Scrolling-Commands">Scrolling Commands</a></li> +<li><a href="#index-C_002dEnd-70"><code>C-End</code></a>: <a href="#Cursor-Commands">Cursor Commands</a></li> +<li><a href="#index-C_002df_002c-in-Info-windows-51"><code>C-f, in Info windows</code></a>: <a href="#Cursor-Commands">Cursor Commands</a></li> +<li><a href="#index-C_002df_002c-in-the-echo-area-250"><code>C-f, in the echo area</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> +<li><a href="#index-C_002df_002c-vi_002dlike-operation-79"><code>C-f, vi-like operation</code></a>: <a href="#Scrolling-Commands">Scrolling Commands</a></li> +<li><a href="#index-C_002dg_002c-in-Info-windows-347"><code>C-g, in Info windows</code></a>: <a href="#Miscellaneous-Commands">Miscellaneous Commands</a></li> +<li><a href="#index-C_002dg_002c-in-the-echo-area-276"><code>C-g, in the echo area</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> +<li><a href="#index-C_002dh-326"><code>C-h</code></a>: <a href="#Miscellaneous-Commands">Miscellaneous Commands</a></li> +<li><a href="#index-C_002dHome-65"><code>C-Home</code></a>: <a href="#Cursor-Commands">Cursor Commands</a></li> +<li><a href="#index-C_002dk_002c-in-the-echo-area-299"><code>C-k, in the echo area</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> +<li><a href="#index-C_002dk_002c-vi_002dlike-operation-105"><code>C-k, vi-like operation</code></a>: <a href="#Scrolling-Commands">Scrolling Commands</a></li> +<li><a href="#index-C_002dl-117"><code>C-l</code></a>: <a href="#Scrolling-Commands">Scrolling Commands</a></li> +<li><a href="#index-C_002dLEFT-61"><code>C-LEFT</code></a>: <a href="#Cursor-Commands">Cursor Commands</a></li> +<li><a href="#index-C_002dLEFT_002c-in-the-echo-area-270"><code>C-LEFT, in the echo area</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> +<li><a href="#index-C_002dn-39"><code>C-n</code></a>: <a href="#Cursor-Commands">Cursor Commands</a></li> +<li><a href="#index-C_002dn_002c-vi_002dlike-operation-95"><code>C-n, vi-like operation</code></a>: <a href="#Scrolling-Commands">Scrolling Commands</a></li> +<li><a href="#index-C_002dNEXT-123"><code>C-NEXT</code></a>: <a href="#Node-Commands">Node Commands</a></li> +<li><a href="#index-C_002dp-42"><code>C-p</code></a>: <a href="#Cursor-Commands">Cursor Commands</a></li> +<li><a href="#index-C_002dp_002c-vi_002dlike-operation-101"><code>C-p, vi-like operation</code></a>: <a href="#Scrolling-Commands">Scrolling Commands</a></li> +<li><a href="#index-C_002dPgDn-126"><code>C-PgDn</code></a>: <a href="#Node-Commands">Node Commands</a></li> +<li><a href="#index-C_002dPgUp-130"><code>C-PgUp</code></a>: <a href="#Node-Commands">Node Commands</a></li> +<li><a href="#index-C_002dPREVIOUS-128"><code>C-PREVIOUS</code></a>: <a href="#Node-Commands">Node Commands</a></li> +<li><a href="#index-C_002dq_002c-in-the-echo-area-281"><code>C-q, in the echo area</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> +<li><a href="#index-C_002dr-193"><code>C-r</code></a>: <a href="#Searching-Commands">Searching Commands</a></li> +<li><a href="#index-C_002dRIGHT-58"><code>C-RIGHT</code></a>: <a href="#Cursor-Commands">Cursor Commands</a></li> +<li><a href="#index-C_002dRIGHT_002c-in-the-echo-area-267"><code>C-RIGHT, in the echo area</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> +<li><a href="#index-C_002ds-190"><code>C-s</code></a>: <a href="#Searching-Commands">Searching Commands</a></li> +<li><a href="#index-C_002dt_002c-in-the-echo-area-291"><code>C-t, in the echo area</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> +<li><a href="#index-C_002du-335"><code>C-u</code></a>: <a href="#Miscellaneous-Commands">Miscellaneous Commands</a></li> +<li><a href="#index-C_002du-cancels-typeahead_002c-vi_002dlike-operation-348"><code>C-u cancels typeahead, vi-like operation</code></a>: <a href="#Miscellaneous-Commands">Miscellaneous Commands</a></li> +<li><a href="#index-C_002du_002c-in-the-echo-area_002c-vi_002dlike-operation-277"><code>C-u, in the echo area, vi-like operation</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> +<li><a href="#index-C_002du_002c-vi_002dlike-operation-112"><code>C-u, vi-like operation</code></a>: <a href="#Scrolling-Commands">Scrolling Commands</a></li> +<li><a href="#index-C_002dUP-132"><code>C-UP</code></a>: <a href="#Node-Commands">Node Commands</a></li> +<li><a href="#index-C_002dv-78"><code>C-v</code></a>: <a href="#Scrolling-Commands">Scrolling Commands</a></li> +<li><a href="#index-C_002dv_002c-in-the-echo-area_002c-vi_002dlike-operation-282"><code>C-v, in the echo area, vi-like operation</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> +<li><a href="#index-C_002dw-119"><code>C-w</code></a>: <a href="#Scrolling-Commands">Scrolling Commands</a></li> +<li><a href="#index-C_002dx-0-238"><code>C-x 0</code></a>: <a href="#Basic-Windows">Basic Windows</a></li> +<li><a href="#index-C_002dx-1-240"><code>C-x 1</code></a>: <a href="#Basic-Windows">Basic Windows</a></li> +<li><a href="#index-C_002dx-2-235"><code>C-x 2</code></a>: <a href="#Basic-Windows">Basic Windows</a></li> +<li><a href="#index-C_002dx-_005e-244"><code>C-x ^</code></a>: <a href="#Basic-Windows">Basic Windows</a></li> +<li><a href="#index-C_002dx-b-171"><code>C-x b</code></a>: <a href="#Node-Commands">Node Commands</a></li> +<li><a href="#index-C_002dx-C_002db-169"><code>C-x C-b</code></a>: <a href="#Node-Commands">Node Commands</a></li> +<li><a href="#index-C_002dx-C_002dc-352"><code>C-x C-c</code></a>: <a href="#Miscellaneous-Commands">Miscellaneous Commands</a></li> +<li><a href="#index-C_002dx-C_002df-167"><code>C-x C-f</code></a>: <a href="#Node-Commands">Node Commands</a></li> +<li><a href="#index-C_002dx-DEL_002c-in-the-echo-area-301"><code>C-x DEL, in the echo area</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> +<li><a href="#index-C_002dx-g_002c-vi_002dlike-operation-156"><code>C-x g, vi-like operation</code></a>: <a href="#Node-Commands">Node Commands</a></li> +<li><a href="#index-C_002dx-k-165"><code>C-x k</code></a>: <a href="#Node-Commands">Node Commands</a></li> +<li><a href="#index-C_002dx-N-187"><code>C-x N</code></a>: <a href="#Searching-Commands">Searching Commands</a></li> +<li><a href="#index-C_002dx-n-183"><code>C-x n</code></a>: <a href="#Searching-Commands">Searching Commands</a></li> +<li><a href="#index-C_002dx-n_002c-vi_002dlike-operation-124"><code>C-x n, vi-like operation</code></a>: <a href="#Node-Commands">Node Commands</a></li> +<li><a href="#index-C_002dx-o-231"><code>C-x o</code></a>: <a href="#Basic-Windows">Basic Windows</a></li> +<li><a href="#index-C_002dx-r_002c-vi_002dlike-operation-218"><code>C-x r, vi-like operation</code></a>: <a href="#Selecting-Xrefs">Selecting Xrefs</a></li> +<li><a href="#index-C_002dx-t-247"><code>C-x t</code></a>: <a href="#Basic-Windows">Basic Windows</a></li> +<li><a href="#index-C_002dx-u_002c-vi_002dlike-operation-133"><code>C-x u, vi-like operation</code></a>: <a href="#Node-Commands">Node Commands</a></li> +<li><a href="#index-C_002dy_002c-in-the-echo-area-303"><code>C-y, in the echo area</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> +<li><a href="#index-C_002dy_002c-vi_002dlike-operation-106"><code>C-y, vi-like operation</code></a>: <a href="#Scrolling-Commands">Scrolling Commands</a></li> +<li><a href="#index-cancelling-the-current-operation-346">cancelling the current operation</a>: <a href="#Miscellaneous-Commands">Miscellaneous Commands</a></li> +<li><a href="#index-cancelling-typeahead-345">cancelling typeahead</a>: <a href="#Miscellaneous-Commands">Miscellaneous Commands</a></li> +<li><a href="#index-case_002dsensitive-search-182">case-sensitive search</a>: <a href="#Searching-Commands">Searching Commands</a></li> +<li><a href="#index-case_002dsensitivity_002c-and-search-203">case-sensitivity, and search</a>: <a href="#Searching-Commands">Searching Commands</a></li> +<li><a href="#index-colors-in-documents-24">colors in documents</a>: <a href="#Invoking-Info">Invoking Info</a></li> +<li><a href="#index-command-line-options-3">command line options</a>: <a href="#Invoking-Info">Invoking Info</a></li> +<li><a href="#index-command_002dline-options_002c-how-to-find-27">command-line options, how to find</a>: <a href="#Invoking-Info">Invoking Info</a></li> +<li><a href="#index-commands_002c-describing-321">commands, describing</a>: <a href="#Miscellaneous-Commands">Miscellaneous Commands</a></li> +<li><a href="#index-completion-307">completion</a>: <a href="#The-Echo-Area">The Echo Area</a></li> +<li><a href="#index-compressed-Info-files-16">compressed Info files</a>: <a href="#Invoking-Info">Invoking Info</a></li> +<li><a href="#index-cursor_002c-moving-37">cursor, moving</a>: <a href="#Cursor-Commands">Cursor Commands</a></li> +<li><a href="#index-customizing-key-bindings-376">customizing key bindings</a>: <a href="#Custom-Key-Bindings">Custom Key Bindings</a></li> +<li><a href="#index-d-142"><code>d</code></a>: <a href="#Node-Commands">Node Commands</a></li> +<li><a href="#index-d_002c-vi_002dlike-operation-108"><code>d, vi-like operation</code></a>: <a href="#Scrolling-Commands">Scrolling Commands</a></li> +<li><a href="#index-default-key-bindings_002c-overriding-374">default key bindings, overriding</a>: <a href="#Custom-Key-Bindings">Custom Key Bindings</a></li> +<li><a href="#index-DEL_002c-in-Info-windows-86"><code>DEL, in Info windows</code></a>: <a href="#Scrolling-Commands">Scrolling Commands</a></li> +<li><a href="#index-DEL_002c-in-the-echo-area-274"><code>DEL, in the echo area</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> +<li><a href="#index-delete_002dwindow-239"><code>delete-window</code></a>: <a href="#Basic-Windows">Basic Windows</a></li> +<li><a href="#index-describe_002dcommand-322"><code>describe-command</code></a>: <a href="#Miscellaneous-Commands">Miscellaneous Commands</a></li> +<li><a href="#index-describe_002dkey-324"><code>describe-key</code></a>: <a href="#Miscellaneous-Commands">Miscellaneous Commands</a></li> +<li><a href="#index-describe_002dvariable-363"><code>describe-variable</code></a>: <a href="#Variables">Variables</a></li> +<li><a href="#index-dir_002dnode-144"><code>dir-node</code></a>: <a href="#Node-Commands">Node Commands</a></li> +<li><a href="#index-directory-path-9">directory path</a>: <a href="#Invoking-Info">Invoking Info</a></li> +<li><a href="#index-DOWN-_0028an-arrow-key_0029-40"><code>DOWN (an arrow key)</code></a>: <a href="#Cursor-Commands">Cursor Commands</a></li> +<li><a href="#index-DOWN_002c-vi_002dlike-operation-99"><code>DOWN, vi-like operation</code></a>: <a href="#Scrolling-Commands">Scrolling Commands</a></li> +<li><a href="#index-down_002dline-100"><code>down-line</code></a>: <a href="#Scrolling-Commands">Scrolling Commands</a></li> +<li><a href="#index-e_002c-in-Info-windows-69"><code>e, in Info windows</code></a>: <a href="#Cursor-Commands">Cursor Commands</a></li> +<li><a href="#index-echo-area-249">echo area</a>: <a href="#The-Echo-Area">The Echo Area</a></li> +<li><a href="#index-echo_002darea_002dabort-278"><code>echo-area-abort</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> +<li><a href="#index-echo_002darea_002dbackward-257"><code>echo-area-backward</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> +<li><a href="#index-echo_002darea_002dbackward_002dkill_002dline-302"><code>echo-area-backward-kill-line</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> +<li><a href="#index-echo_002darea_002dbackward_002dkill_002dword-297"><code>echo-area-backward-kill-word</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> +<li><a href="#index-echo_002darea_002dbackward_002dword-269"><code>echo-area-backward-word</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> +<li><a href="#index-echo_002darea_002dbeg_002dof_002dline-260"><code>echo-area-beg-of-line</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> +<li><a href="#index-echo_002darea_002dcomplete-310"><code>echo-area-complete</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> +<li><a href="#index-echo_002darea_002ddelete-273"><code>echo-area-delete</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> +<li><a href="#index-echo_002darea_002dend_002dof_002dline-263"><code>echo-area-end-of-line</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> +<li><a href="#index-echo_002darea_002dforward-253"><code>echo-area-forward</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> +<li><a href="#index-echo_002darea_002dforward_002dword-266"><code>echo-area-forward-word</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> +<li><a href="#index-echo_002darea_002dinsert-285"><code>echo-area-insert</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> +<li><a href="#index-echo_002darea_002dkill_002dline-300"><code>echo-area-kill-line</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> +<li><a href="#index-echo_002darea_002dkill_002dword-295"><code>echo-area-kill-word</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> +<li><a href="#index-echo_002darea_002dnewline-280"><code>echo-area-newline</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> +<li><a href="#index-echo_002darea_002dpossible_002dcompletions-312"><code>echo-area-possible-completions</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> +<li><a href="#index-echo_002darea_002dquoted_002dinsert-283"><code>echo-area-quoted-insert</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> +<li><a href="#index-echo_002darea_002drubout-275"><code>echo-area-rubout</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> +<li><a href="#index-echo_002darea_002dscroll_002dcompletions_002dwindow-314"><code>echo-area-scroll-completions-window</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> +<li><a href="#index-echo_002darea_002dtab_002dinsert-288"><code>echo-area-tab-insert</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> +<li><a href="#index-echo_002darea_002dtranspose_002dchars-292"><code>echo-area-transpose-chars</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> +<li><a href="#index-echo_002darea_002dyank-304"><code>echo-area-yank</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> +<li><a href="#index-echo_002darea_002dyank_002dpop-306"><code>echo-area-yank-pop</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> +<li><a href="#index-End-49"><code>End</code></a>: <a href="#Cursor-Commands">Cursor Commands</a></li> +<li><a href="#index-end_002dof_002dline-50"><code>end-of-line</code></a>: <a href="#Cursor-Commands">Cursor Commands</a></li> +<li><a href="#index-end_002dof_002dnode-71"><code>end-of-node</code></a>: <a href="#Cursor-Commands">Cursor Commands</a></li> +<li><a href="#index-errors_002dring_002dbell-366"><code>errors-ring-bell</code></a>: <a href="#Variables">Variables</a></li> +<li><a href="#index-ESC-C_002df-357"><code>ESC C-f</code></a>: <a href="#Miscellaneous-Commands">Miscellaneous Commands</a></li> +<li><a href="#index-ESC-C_002dv_002c-in-Info-windows-242"><code>ESC C-v, in Info windows</code></a>: <a href="#Basic-Windows">Basic Windows</a></li> +<li><a href="#index-ESC-C_002dv_002c-in-the-echo-area-313"><code>ESC C-v, in the echo area</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> +<li><a href="#index-f-215"><code>f</code></a>: <a href="#Selecting-Xrefs">Selecting Xrefs</a></li> +<li><a href="#index-f_002c-vi_002dlike-operation-80"><code>f, vi-like operation</code></a>: <a href="#Scrolling-Commands">Scrolling Commands</a></li> +<li><a href="#index-F1-328"><code>F1</code></a>: <a href="#Miscellaneous-Commands">Miscellaneous Commands</a></li> +<li><a href="#index-FDL_002c-GNU-Free-Documentation-License-388">FDL, GNU Free Documentation License</a>: <a href="#GNU-Free-Documentation-License">GNU Free Documentation License</a></li> +<li><a href="#index-file-names_002c-relative-14">file names, relative</a>: <a href="#Invoking-Info">Invoking Info</a></li> +<li><a href="#index-file_002c-outputting-to-22">file, outputting to</a>: <a href="#Invoking-Info">Invoking Info</a></li> +<li><a href="#index-files_002c-compressed-17">files, compressed</a>: <a href="#Invoking-Info">Invoking Info</a></li> +<li><a href="#index-find_002dmenu-214"><code>find-menu</code></a>: <a href="#Selecting-Xrefs">Selecting Xrefs</a></li> +<li><a href="#index-finding-the-Invocation-node-161">finding the Invocation node</a>: <a href="#Node-Commands">Node Commands</a></li> +<li><a href="#index-first_002dnode-147"><code>first-node</code></a>: <a href="#Node-Commands">Node Commands</a></li> +<li><a href="#index-footnotes_002c-displaying-359">footnotes, displaying</a>: <a href="#Miscellaneous-Commands">Miscellaneous Commands</a></li> +<li><a href="#index-format-of-_002einfokey-source-387">format of .infokey source</a>: <a href="#infokey-source-format">infokey source format</a></li> +<li><a href="#index-forward_002dchar-53"><code>forward-char</code></a>: <a href="#Cursor-Commands">Cursor Commands</a></li> +<li><a href="#index-forward_002dword-59"><code>forward-word</code></a>: <a href="#Cursor-Commands">Cursor Commands</a></li> +<li><a href="#index-functions_002c-describing-320">functions, describing</a>: <a href="#Miscellaneous-Commands">Miscellaneous Commands</a></li> +<li><a href="#index-g-155"><code>g</code></a>: <a href="#Node-Commands">Node Commands</a></li> +<li><a href="#index-G-162"><code>G</code></a>: <a href="#Node-Commands">Node Commands</a></li> +<li><a href="#index-G_002c-vi_002dlike-operation-149"><code>G, vi-like operation</code></a>: <a href="#Node-Commands">Node Commands</a></li> +<li><a href="#index-g_002c-vi_002dlike-operation-146"><code>g, vi-like operation</code></a>: <a href="#Node-Commands">Node Commands</a></li> +<li><a href="#index-gc_002dcompressed_002dfiles-367"><code>gc-compressed-files</code></a>: <a href="#Variables">Variables</a></li> +<li><a href="#index-get_002dhelp_002dwindow-330"><code>get-help-window</code></a>: <a href="#Miscellaneous-Commands">Miscellaneous Commands</a></li> +<li><a href="#index-get_002dinfo_002dhelp_002dnode-333"><code>get-info-help-node</code></a>: <a href="#Miscellaneous-Commands">Miscellaneous Commands</a></li> +<li><a href="#index-global_002dnext_002dnode-152"><code>global-next-node</code></a>: <a href="#Node-Commands">Node Commands</a></li> +<li><a href="#index-global_002dprev_002dnode-154"><code>global-prev-node</code></a>: <a href="#Node-Commands">Node Commands</a></li> +<li><a href="#index-goto_002dinvocation-160"><code>goto-invocation</code></a>: <a href="#Node-Commands">Node Commands</a></li> +<li><a href="#index-goto_002dnode-157"><code>goto-node</code></a>: <a href="#Node-Commands">Node Commands</a></li> +<li><a href="#index-grow_002dwindow-245"><code>grow-window</code></a>: <a href="#Basic-Windows">Basic Windows</a></li> +<li><a href="#index-h-331"><code>h</code></a>: <a href="#Miscellaneous-Commands">Miscellaneous Commands</a></li> +<li><a href="#index-h_002c-vi_002dlike-operation-329"><code>h, vi-like operation</code></a>: <a href="#Miscellaneous-Commands">Miscellaneous Commands</a></li> +<li><a href="#index-history_002dnode-138"><code>history-node</code></a>: <a href="#Node-Commands">Node Commands</a></li> +<li><a href="#index-Home-46"><code>Home</code></a>: <a href="#Cursor-Commands">Cursor Commands</a></li> +<li><a href="#index-i-195"><code>i</code></a>: <a href="#Searching-Commands">Searching Commands</a></li> +<li><a href="#index-I-159"><code>I</code></a>: <a href="#Node-Commands">Node Commands</a></li> +<li><a href="#index-incremental-search-192">incremental search</a>: <a href="#Searching-Commands">Searching Commands</a></li> +<li><a href="#index-index-search_002c-selecting-from-the-command-line-19">index search, selecting from the command line</a>: <a href="#Invoking-Info">Invoking Info</a></li> +<li><a href="#index-index_002c-searching-197">index, searching</a>: <a href="#Searching-Commands">Searching Commands</a></li> +<li><a href="#index-index_002dapropos-201"><code>index-apropos</code></a>: <a href="#Searching-Commands">Searching Commands</a></li> +<li><a href="#index-index_002dsearch-196"><code>index-search</code></a>: <a href="#Searching-Commands">Searching Commands</a></li> +<li><a href="#index-Info-file_002c-selecting-12">Info file, selecting</a>: <a href="#Invoking-Info">Invoking Info</a></li> +<li><a href="#index-Info-files_002c-compressed-18">Info files, compressed</a>: <a href="#Invoking-Info">Invoking Info</a></li> +<li><a href="#index-Info-files_002c-relative-15">Info files, relative</a>: <a href="#Invoking-Info">Invoking Info</a></li> +<li><a href="#index-Info-files_0040r_007b_002c-searching-all-indices_007d-7">Info files<span class="roman">, searching all indices</span></a>: <a href="#Invoking-Info">Invoking Info</a></li> +<li><a href="#index-Info-manual-location-34">Info manual location</a>: <a href="#Invoking-Info">Invoking Info</a></li> +<li><a href="#index-Info_002c-invoking-1">Info, invoking</a>: <a href="#Invoking-Info">Invoking Info</a></li> +<li><a href="#index-INFO_005fPRINT_005fCOMMAND_002c-environment-variable-317">INFO_PRINT_COMMAND, environment variable</a>: <a href="#Printing-Nodes">Printing Nodes</a></li> +<li><a href="#index-infokey-378">infokey</a>: <a href="#Custom-Key-Bindings">Custom Key Bindings</a></li> +<li><a href="#index-infokey-source-format-385">infokey source format</a>: <a href="#infokey-source-format">infokey source format</a></li> +<li><a href="#index-infokey_002c-invoking-383">infokey, invoking</a>: <a href="#Invoking-infokey">Invoking infokey</a></li> +<li><a href="#index-invocation-description_002c-how-to-find-28">invocation description, how to find</a>: <a href="#Invoking-Info">Invoking Info</a></li> +<li><a href="#index-invoking-Info-2">invoking Info</a>: <a href="#Invoking-Info">Invoking Info</a></li> +<li><a href="#index-invoking-infokey-382">invoking infokey</a>: <a href="#Invoking-infokey">Invoking infokey</a></li> +<li><a href="#index-isearch_002dbackward-194"><code>isearch-backward</code></a>: <a href="#Searching-Commands">Searching Commands</a></li> +<li><a href="#index-isearch_002dforward-191"><code>isearch-forward</code></a>: <a href="#Searching-Commands">Searching Commands</a></li> +<li><a href="#index-ISO-Latin-characters-368">ISO Latin characters</a>: <a href="#Variables">Variables</a></li> +<li><a href="#index-ISO_002dLatin-369"><code>ISO-Latin</code></a>: <a href="#Variables">Variables</a></li> +<li><a href="#index-k_002c-vi_002dlike-operation-104"><code>k, vi-like operation</code></a>: <a href="#Scrolling-Commands">Scrolling Commands</a></li> +<li><a href="#index-keep_002done_002dwindow-241"><code>keep-one-window</code></a>: <a href="#Basic-Windows">Basic Windows</a></li> +<li><a href="#index-key-bindings_002c-customizing-377">key bindings, customizing</a>: <a href="#Custom-Key-Bindings">Custom Key Bindings</a></li> +<li><a href="#index-keys_002c-describing-323">keys, describing</a>: <a href="#Miscellaneous-Commands">Miscellaneous Commands</a></li> +<li><a href="#index-keystrokes_002c-recording-10">keystrokes, recording</a>: <a href="#Invoking-Info">Invoking Info</a></li> +<li><a href="#index-kill_002dnode-166"><code>kill-node</code></a>: <a href="#Node-Commands">Node Commands</a></li> +<li><a href="#index-l-135"><code>l</code></a>: <a href="#Node-Commands">Node Commands</a></li> +<li><a href="#index-last_002dmenu_002ditem-211"><code>last-menu-item</code></a>: <a href="#Selecting-Xrefs">Selecting Xrefs</a></li> +<li><a href="#index-last_002dnode-150"><code>last-node</code></a>: <a href="#Node-Commands">Node Commands</a></li> +<li><a href="#index-LEFT-_0028an-arrow-key_0029-55"><code>LEFT (an arrow key)</code></a>: <a href="#Cursor-Commands">Cursor Commands</a></li> +<li><a href="#index-LEFT_002c-in-the-echo-area-254"><code>LEFT, in the echo area</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> +<li><a href="#index-Less_002dlike-key-bindings-33">Less-like key bindings</a>: <a href="#Invoking-Info">Invoking Info</a></li> +<li><a href="#index-LFD_002c-vi_002dlike-operation-98"><code>LFD, vi-like operation</code></a>: <a href="#Scrolling-Commands">Scrolling Commands</a></li> +<li><a href="#index-list_002dvisited_002dnodes-170"><code>list-visited-nodes</code></a>: <a href="#Node-Commands">Node Commands</a></li> +<li><a href="#index-local-printer-device-319">local printer device</a>: <a href="#Printing-Nodes">Printing Nodes</a></li> +<li><a href="#index-m-212"><code>m</code></a>: <a href="#Selecting-Xrefs">Selecting Xrefs</a></li> +<li><a href="#index-M_002d_0024_002c-vi_002dlike-operation-262"><code>M-$, vi-like operation</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> +<li><a href="#index-M_002d_002d-340"><code>M--</code></a>: <a href="#Miscellaneous-Commands">Miscellaneous Commands</a></li> +<li><a href="#index-M_002d0-_0040dots_007b_007d-M_002d9-337"><code>M-0 ... M-9</code></a>: <a href="#Miscellaneous-Commands">Miscellaneous Commands</a></li> +<li><a href="#index-M_002d0_002c-in-the-echo-area_002c-vi_002dlike-operation-259"><code>M-0, in the echo area, vi-like operation</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> +<li><a href="#index-M_002d0_002c-vi_002dlike-operation-210"><code>M-0, vi-like operation</code></a>: <a href="#Selecting-Xrefs">Selecting Xrefs</a></li> +<li><a href="#index-M_002d1-_0040dots_007b_007d-M_002d9_002c-vi_002dlike-operation-205">M-1 <small class="dots">...</small> M-9, vi-like operation</a>: <a href="#Selecting-Xrefs">Selecting Xrefs</a></li> +<li><a href="#index-M_002d_003c-64"><code>M-<</code></a>: <a href="#Cursor-Commands">Cursor Commands</a></li> +<li><a href="#index-M_002d_003e-68"><code>M-></code></a>: <a href="#Cursor-Commands">Cursor Commands</a></li> +<li><a href="#index-M_002db_002c-in-Info-windows-60"><code>M-b, in Info windows</code></a>: <a href="#Cursor-Commands">Cursor Commands</a></li> +<li><a href="#index-M_002db_002c-in-the-echo-area-268"><code>M-b, in the echo area</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> +<li><a href="#index-M_002db_002c-vi_002dlike-operation-66"><code>M-b, vi-like operation</code></a>: <a href="#Cursor-Commands">Cursor Commands</a></li> +<li><a href="#index-M_002dBS_002c-in-the-echo-area-298"><code>M-BS, in the echo area</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> +<li><a href="#index-M_002dd_002c-in-the-echo-area-293"><code>M-d, in the echo area</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> +<li><a href="#index-M_002dd_002c-vi_002dlike-operation-143"><code>M-d, vi-like operation</code></a>: <a href="#Node-Commands">Node Commands</a></li> +<li><a href="#index-M_002dDEL_002c-in-the-echo-area-296"><code>M-DEL, in the echo area</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> +<li><a href="#index-M_002df_002c-in-Info-windows-57"><code>M-f, in Info windows</code></a>: <a href="#Cursor-Commands">Cursor Commands</a></li> +<li><a href="#index-M_002df_002c-in-the-echo-area-264"><code>M-f, in the echo area</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> +<li><a href="#index-M_002df_002c-vi_002dlike-operation-217"><code>M-f, vi-like operation</code></a>: <a href="#Selecting-Xrefs">Selecting Xrefs</a></li> +<li><a href="#index-M_002dg_002c-vi_002dlike-operation-227"><code>M-g, vi-like operation</code></a>: <a href="#Selecting-Xrefs">Selecting Xrefs</a></li> +<li><a href="#index-M_002dh_002c-in-the-echo-area_002c-vi_002dlike-operation-252"><code>M-h, in the echo area, vi-like operation</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> +<li><a href="#index-M_002dh_002c-vi_002dlike-operation-332"><code>M-h, vi-like operation</code></a>: <a href="#Miscellaneous-Commands">Miscellaneous Commands</a></li> +<li><a href="#index-M_002dl_002c-in-the-echo-area_002c-vi_002dlike-operation-256"><code>M-l, in the echo area, vi-like operation</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> +<li><a href="#index-M_002dr-72"><code>M-r</code></a>: <a href="#Cursor-Commands">Cursor Commands</a></li> +<li><a href="#index-M_002dSPC_002c-vi_002dlike-operation-81"><code>M-SPC, vi-like operation</code></a>: <a href="#Scrolling-Commands">Scrolling Commands</a></li> +<li><a href="#index-M_002dt_002c-vi_002dlike-operation-140"><code>M-t, vi-like operation</code></a>: <a href="#Node-Commands">Node Commands</a></li> +<li><a href="#index-M_002dTAB_002c-in-Info-windows-222"><code>M-TAB, in Info windows</code></a>: <a href="#Selecting-Xrefs">Selecting Xrefs</a></li> +<li><a href="#index-M_002dTAB_002c-in-the-echo-area-286"><code>M-TAB, in the echo area</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> +<li><a href="#index-M_002dv-89"><code>M-v</code></a>: <a href="#Scrolling-Commands">Scrolling Commands</a></li> +<li><a href="#index-M_002dw_002c-in-the-echo-area_002c-vi_002dlike-operation-265"><code>M-w, in the echo area, vi-like operation</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> +<li><a href="#index-M_002dx_002c-in-the-echo-area_002c-vi_002dlike-operation-272"><code>M-x, in the echo area, vi-like operation</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> +<li><a href="#index-M_002dX_002c-in-the-echo-area_002c-vi_002dlike-operation-294"><code>M-X, in the echo area, vi-like operation</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> +<li><a href="#index-M_002dy_002c-in-the-echo-area-305"><code>M-y, in the echo area</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> +<li><a href="#index-menu_002c-following-36">menu, following</a>: <a href="#Invoking-Info">Invoking Info</a></li> +<li><a href="#index-menu_002c-following_002c-from-inside-Info-164">menu, following, from inside Info</a>: <a href="#Node-Commands">Node Commands</a></li> +<li><a href="#index-menu_002ddigit-208"><code>menu-digit</code></a>: <a href="#Selecting-Xrefs">Selecting Xrefs</a></li> +<li><a href="#index-menu_002ditem-213"><code>menu-item</code></a>: <a href="#Selecting-Xrefs">Selecting Xrefs</a></li> +<li><a href="#index-menu_002dsequence-163"><code>menu-sequence</code></a>: <a href="#Node-Commands">Node Commands</a></li> +<li><a href="#index-move_002dto_002dnext_002dxref-221"><code>move-to-next-xref</code></a>: <a href="#Selecting-Xrefs">Selecting Xrefs</a></li> +<li><a href="#index-move_002dto_002dprev_002dxref-223"><code>move-to-prev-xref</code></a>: <a href="#Selecting-Xrefs">Selecting Xrefs</a></li> +<li><a href="#index-move_002dto_002dwindow_002dline-73"><code>move-to-window-line</code></a>: <a href="#Cursor-Commands">Cursor Commands</a></li> +<li><a href="#index-moving-the-cursor-38">moving the cursor</a>: <a href="#Cursor-Commands">Cursor Commands</a></li> +<li><a href="#index-n-122"><code>n</code></a>: <a href="#Node-Commands">Node Commands</a></li> +<li><a href="#index-n_002c-vi_002dlike-operation-184"><code>n, vi-like operation</code></a>: <a href="#Searching-Commands">Searching Commands</a></li> +<li><a href="#index-negative-arguments-342">negative arguments</a>: <a href="#Miscellaneous-Commands">Miscellaneous Commands</a></li> +<li><a href="#index-NEXT-77"><code>NEXT</code></a>: <a href="#Scrolling-Commands">Scrolling Commands</a></li> +<li><a href="#index-next_002dindex_002dmatch-200"><code>next-index-match</code></a>: <a href="#Searching-Commands">Searching Commands</a></li> +<li><a href="#index-next_002dline-41"><code>next-line</code></a>: <a href="#Cursor-Commands">Cursor Commands</a></li> +<li><a href="#index-next_002dnode-125"><code>next-node</code></a>: <a href="#Node-Commands">Node Commands</a></li> +<li><a href="#index-next_002dwindow-232"><code>next-window</code></a>: <a href="#Basic-Windows">Basic Windows</a></li> +<li><a href="#index-node_002c-selecting-from-the-command-line-21">node, selecting from the command line</a>: <a href="#Invoking-Info">Invoking Info</a></li> +<li><a href="#index-nodes_002c-selection-of-121">nodes, selection of</a>: <a href="#Node-Commands">Node Commands</a></li> +<li><a href="#index-numeric-arguments-334">numeric arguments</a>: <a href="#Miscellaneous-Commands">Miscellaneous Commands</a></li> +<li><a href="#index-numeric-arguments_002c-negative-344">numeric arguments, negative</a>: <a href="#Miscellaneous-Commands">Miscellaneous Commands</a></li> +<li><a href="#index-O-158"><code>O</code></a>: <a href="#Node-Commands">Node Commands</a></li> +<li><a href="#index-online-help_002c-using-Info-as-20">online help, using Info as</a>: <a href="#Invoking-Info">Invoking Info</a></li> +<li><a href="#index-options_002c-command-line-4">options, command line</a>: <a href="#Invoking-Info">Invoking Info</a></li> +<li><a href="#index-outputting-to-a-file-23">outputting to a file</a>: <a href="#Invoking-Info">Invoking Info</a></li> +<li><a href="#index-overriding-default-key-bindings-375">overriding default key bindings</a>: <a href="#Custom-Key-Bindings">Custom Key Bindings</a></li> +<li><a href="#index-p-127"><code>p</code></a>: <a href="#Node-Commands">Node Commands</a></li> +<li><a href="#index-PageDown-83"><code>PageDown</code></a>: <a href="#Scrolling-Commands">Scrolling Commands</a></li> +<li><a href="#index-PageUp-115"><code>PageUp</code></a>: <a href="#Scrolling-Commands">Scrolling Commands</a></li> +<li><a href="#index-prev_002dline-44"><code>prev-line</code></a>: <a href="#Cursor-Commands">Cursor Commands</a></li> +<li><a href="#index-prev_002dnode-129"><code>prev-node</code></a>: <a href="#Node-Commands">Node Commands</a></li> +<li><a href="#index-prev_002dwindow-233"><code>prev-window</code></a>: <a href="#Basic-Windows">Basic Windows</a></li> +<li><a href="#index-PREVIOUS-88"><code>PREVIOUS</code></a>: <a href="#Scrolling-Commands">Scrolling Commands</a></li> +<li><a href="#index-print_002dnode-316"><code>print-node</code></a>: <a href="#Printing-Nodes">Printing Nodes</a></li> +<li><a href="#index-printing-315">printing</a>: <a href="#Printing-Nodes">Printing Nodes</a></li> +<li><a href="#index-printing-characters_002c-in-the-echo-area-284"><code>printing characters, in the echo area</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> +<li><a href="#index-printing-nodes-to-the-local-printer-318">printing nodes to the local printer</a>: <a href="#Printing-Nodes">Printing Nodes</a></li> +<li><a href="#index-q-351"><code>q</code></a>: <a href="#Miscellaneous-Commands">Miscellaneous Commands</a></li> +<li><a href="#index-quit-354"><code>quit</code></a>: <a href="#Miscellaneous-Commands">Miscellaneous Commands</a></li> +<li><a href="#index-quitting-350">quitting</a>: <a href="#Miscellaneous-Commands">Miscellaneous Commands</a></li> +<li><a href="#index-r-216"><code>r</code></a>: <a href="#Selecting-Xrefs">Selecting Xrefs</a></li> +<li><a href="#index-redraw_002ddisplay-118"><code>redraw-display</code></a>: <a href="#Scrolling-Commands">Scrolling Commands</a></li> +<li><a href="#index-relative-Info-file-names-13">relative Info file names</a>: <a href="#Invoking-Info">Invoking Info</a></li> +<li><a href="#index-remembering-user-keystrokes-11">remembering user keystrokes</a>: <a href="#Invoking-Info">Invoking Info</a></li> +<li><a href="#index-repeated-search-186">repeated search</a>: <a href="#Searching-Commands">Searching Commands</a></li> +<li><a href="#index-replaying-recorded-keystrokes-26">replaying recorded keystrokes</a>: <a href="#Invoking-Info">Invoking Info</a></li> +<li><a href="#index-RET_002c-in-Info-windows-226"><code>RET, in Info windows</code></a>: <a href="#Selecting-Xrefs">Selecting Xrefs</a></li> +<li><a href="#index-RET_002c-in-the-echo-area-279"><code>RET, in the echo area</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> +<li><a href="#index-RET_002c-vi_002dlike-operation-97"><code>RET, vi-like operation</code></a>: <a href="#Scrolling-Commands">Scrolling Commands</a></li> +<li><a href="#index-RIGHT-_0028an-arrow-key_0029-52"><code>RIGHT (an arrow key)</code></a>: <a href="#Cursor-Commands">Cursor Commands</a></li> +<li><a href="#index-RIGHT_002c-in-the-echo-area-251"><code>RIGHT, in the echo area</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> +<li><a href="#index-S-179"><code>S</code></a>: <a href="#Searching-Commands">Searching Commands</a></li> +<li><a href="#index-s-174"><code>s</code></a>: <a href="#Searching-Commands">Searching Commands</a></li> +<li><a href="#index-screen_002c-changing-the-height-of-356">screen, changing the height of</a>: <a href="#Miscellaneous-Commands">Miscellaneous Commands</a></li> +<li><a href="#index-scroll_002dbackward-87"><code>scroll-backward</code></a>: <a href="#Scrolling-Commands">Scrolling Commands</a></li> +<li><a href="#index-scroll_002dbackward_002dpage_002donly-92"><code>scroll-backward-page-only</code></a>: <a href="#Scrolling-Commands">Scrolling Commands</a></li> +<li><a href="#index-scroll_002dbackward_002dpage_002donly_002dset_002dwindow-94"><code>scroll-backward-page-only-set-window</code></a>: <a href="#Scrolling-Commands">Scrolling Commands</a></li> +<li><a href="#index-scroll_002dbehavior-370"><code>scroll-behavior</code></a>: <a href="#Variables">Variables</a></li> +<li><a href="#index-scroll_002dforward-76"><code>scroll-forward</code></a>: <a href="#Scrolling-Commands">Scrolling Commands</a></li> +<li><a href="#index-scroll_002dforward_002dpage_002donly-82"><code>scroll-forward-page-only</code></a>: <a href="#Scrolling-Commands">Scrolling Commands</a></li> +<li><a href="#index-scroll_002dforward_002dpage_002donly_002dset_002dwindow-85"><code>scroll-forward-page-only-set-window</code></a>: <a href="#Scrolling-Commands">Scrolling Commands</a></li> +<li><a href="#index-scroll_002dhalf_002dscreen_002ddown-110"><code>scroll-half-screen-down</code></a>: <a href="#Scrolling-Commands">Scrolling Commands</a></li> +<li><a href="#index-scroll_002dhalf_002dscreen_002dup-113"><code>scroll-half-screen-up</code></a>: <a href="#Scrolling-Commands">Scrolling Commands</a></li> +<li><a href="#index-scroll_002dother_002dwindow-243"><code>scroll-other-window</code></a>: <a href="#Basic-Windows">Basic Windows</a></li> +<li><a href="#index-scroll_002dstep-371"><code>scroll-step</code></a>: <a href="#Variables">Variables</a></li> +<li><a href="#index-scrolling-74">scrolling</a>: <a href="#Scrolling-Commands">Scrolling Commands</a></li> +<li><a href="#index-scrolling-through-node-structure-114">scrolling through node structure</a>: <a href="#Scrolling-Commands">Scrolling Commands</a></li> +<li><a href="#index-search-176"><code>search</code></a>: <a href="#Searching-Commands">Searching Commands</a></li> +<li><a href="#index-search_002c-and-case_002dsensitivity-202">search, and case-sensitivity</a>: <a href="#Searching-Commands">Searching Commands</a></li> +<li><a href="#index-search_002c-case_002dsensitive-181">search, case-sensitive</a>: <a href="#Searching-Commands">Searching Commands</a></li> +<li><a href="#index-search_002dbackward-178"><code>search-backward</code></a>: <a href="#Searching-Commands">Searching Commands</a></li> +<li><a href="#index-search_002dcase_002dsensitively-180"><code>search-case-sensitively</code></a>: <a href="#Searching-Commands">Searching Commands</a></li> +<li><a href="#index-search_002dnext-185"><code>search-next</code></a>: <a href="#Searching-Commands">Searching Commands</a></li> +<li><a href="#index-search_002dprevious-189"><code>search-previous</code></a>: <a href="#Searching-Commands">Searching Commands</a></li> +<li><a href="#index-searching-173">searching</a>: <a href="#Searching-Commands">Searching Commands</a></li> +<li><a href="#index-Searching-all-indices-6">Searching all indices</a>: <a href="#Invoking-Info">Invoking Info</a></li> +<li><a href="#index-searching_002c-in-the-indices-198">searching, in the indices</a>: <a href="#Searching-Commands">Searching Commands</a></li> +<li><a href="#index-select_002dreference_002dthis_002dline-228"><code>select-reference-this-line</code></a>: <a href="#Selecting-Xrefs">Selecting Xrefs</a></li> +<li><a href="#index-select_002dvisited_002dnode-172"><code>select-visited-node</code></a>: <a href="#Node-Commands">Node Commands</a></li> +<li><a href="#index-set_002dscreen_002dheight-355"><code>set-screen-height</code></a>: <a href="#Miscellaneous-Commands">Miscellaneous Commands</a></li> +<li><a href="#index-set_002dvariable-361"><code>set-variable</code></a>: <a href="#Variables">Variables</a></li> +<li><a href="#index-Shift_002dTAB_002c-in-Info-windows-224"><code>Shift-TAB, in Info windows</code></a>: <a href="#Selecting-Xrefs">Selecting Xrefs</a></li> +<li><a href="#index-Shift_002dTAB_002c-in-the-echo-area-287"><code>Shift-TAB, in the echo area</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> +<li><a href="#index-show_002dfootnotes-358"><code>show-footnotes</code></a>: <a href="#Miscellaneous-Commands">Miscellaneous Commands</a></li> +<li><a href="#index-show_002dindex_002dmatch-372"><code>show-index-match</code></a>: <a href="#Variables">Variables</a></li> +<li><a href="#index-SPC_002c-in-Info-windows-75"><code>SPC, in Info windows</code></a>: <a href="#Scrolling-Commands">Scrolling Commands</a></li> +<li><a href="#index-SPC_002c-in-the-echo-area-309"><code>SPC, in the echo area</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> +<li><a href="#index-speech-synthesizers-29">speech synthesizers</a>: <a href="#Invoking-Info">Invoking Info</a></li> +<li><a href="#index-split_002dwindow-236"><code>split-window</code></a>: <a href="#Basic-Windows">Basic Windows</a></li> +<li><a href="#index-t-139"><code>t</code></a>: <a href="#Node-Commands">Node Commands</a></li> +<li><a href="#index-TAB_002c-in-Info-windows-220"><code>TAB, in Info windows</code></a>: <a href="#Selecting-Xrefs">Selecting Xrefs</a></li> +<li><a href="#index-TAB_002c-in-the-echo-area-308"><code>TAB, in the echo area</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> +<li><a href="#index-tile_002dwindows-248"><code>tile-windows</code></a>: <a href="#Basic-Windows">Basic Windows</a></li> +<li><a href="#index-tiling-246">tiling</a>: <a href="#Basic-Windows">Basic Windows</a></li> +<li><a href="#index-toggle_002dwrap-120"><code>toggle-wrap</code></a>: <a href="#Scrolling-Commands">Scrolling Commands</a></li> +<li><a href="#index-top_002dnode-141"><code>top-node</code></a>: <a href="#Node-Commands">Node Commands</a></li> +<li><a href="#index-u-131"><code>u</code></a>: <a href="#Node-Commands">Node Commands</a></li> +<li><a href="#index-u_002c-vi_002dlike-operation-111"><code>u, vi-like operation</code></a>: <a href="#Scrolling-Commands">Scrolling Commands</a></li> +<li><a href="#index-universal_002dargument-336"><code>universal-argument</code></a>: <a href="#Miscellaneous-Commands">Miscellaneous Commands</a></li> +<li><a href="#index-UP-_0028an-arrow-key_0029-43"><code>UP (an arrow key)</code></a>: <a href="#Cursor-Commands">Cursor Commands</a></li> +<li><a href="#index-UP_002c-vi_002dlike-operation-102"><code>UP, vi-like operation</code></a>: <a href="#Scrolling-Commands">Scrolling Commands</a></li> +<li><a href="#index-up_002dline-107"><code>up-line</code></a>: <a href="#Scrolling-Commands">Scrolling Commands</a></li> +<li><a href="#index-up_002dnode-134"><code>up-node</code></a>: <a href="#Node-Commands">Node Commands</a></li> +<li><a href="#index-variables_002c-describing-362">variables, describing</a>: <a href="#Variables">Variables</a></li> +<li><a href="#index-variables_002c-setting-360">variables, setting</a>: <a href="#Variables">Variables</a></li> +<li><a href="#index-version-information-31">version information</a>: <a href="#Invoking-Info">Invoking Info</a></li> +<li><a href="#index-vi_002dlike-key-bindings-32">vi-like key bindings</a>: <a href="#Invoking-Info">Invoking Info</a></li> +<li><a href="#index-view_002dfile-168"><code>view-file</code></a>: <a href="#Node-Commands">Node Commands</a></li> +<li><a href="#index-visible_002dbell-373"><code>visible-bell</code></a>: <a href="#Variables">Variables</a></li> +<li><a href="#index-w_002c-vi_002dlike-operation-93"><code>w, vi-like operation</code></a>: <a href="#Scrolling-Commands">Scrolling Commands</a></li> +<li><a href="#index-Where-is-an-Info-manual_003f-35">Where is an Info manual?</a>: <a href="#Invoking-Info">Invoking Info</a></li> +<li><a href="#index-where_002dis-325"><code>where-is</code></a>: <a href="#Miscellaneous-Commands">Miscellaneous Commands</a></li> +<li><a href="#index-windows_002c-creating-234">windows, creating</a>: <a href="#Basic-Windows">Basic Windows</a></li> +<li><a href="#index-windows_002c-deleting-237">windows, deleting</a>: <a href="#Basic-Windows">Basic Windows</a></li> +<li><a href="#index-windows_002c-manipulating-229">windows, manipulating</a>: <a href="#Window-Commands">Window Commands</a></li> +<li><a href="#index-windows_002c-selecting-230">windows, selecting</a>: <a href="#Basic-Windows">Basic Windows</a></li> +<li><a href="#index-xref_002ditem-219"><code>xref-item</code></a>: <a href="#Selecting-Xrefs">Selecting Xrefs</a></li> +<li><a href="#index-y_002c-vi_002dlike-operation-103"><code>y, vi-like operation</code></a>: <a href="#Scrolling-Commands">Scrolling Commands</a></li> +<li><a href="#index-z_002c-vi_002dlike-operation-84"><code>z, vi-like operation</code></a>: <a href="#Scrolling-Commands">Scrolling Commands</a></li> +<li><a href="#index-ZZ_002c-vi_002dlike-operation-353"><code>ZZ, vi-like operation</code></a>: <a href="#Miscellaneous-Commands">Miscellaneous Commands</a></li> + </ul><div class="footnote"> +<hr> +<a name="texinfo-footnotes-in-document"></a><h4>Footnotes</h4><p class="footnote"><small>[<a name="fn-1" href="#fnd-1">1</a>]</small> +<span class="file">.info</span>, <span class="file">-info</span>, <span class="file">/index</span>, and <span class="file">.inf</span>.</p> + + <p class="footnote"><small>[<a name="fn-2" href="#fnd-2">2</a>]</small> The MS-DOS version allows for the Info +extension, such as <code>.inf</code>, and the short compressed file +extensions, such as <span class="file">.z</span> and <span class="file">.gz</span>, to be merged into a single +extension, since DOS doesn't allow more than a single dot in the +basename of a file. Thus, on MS-DOS, if Info looks for <span class="file">bison</span>, +file names like <span class="file">bison.igz</span> and <span class="file">bison.inz</span> will be found and +decompressed by <code>gunzip</code>.</p> + + <p class="footnote"><small>[<a name="fn-3" href="#fnd-3">3</a>]</small> Of course, you can specify both the file and node +in a <code>--node</code> command; but don't forget to escape the open and +close parentheses and whitespace from the shell as in: <code>info --node +"(emacs)Buffers"</code>.</p> + + <p class="footnote"><small>[<a name="fn-4" href="#fnd-4">4</a>]</small> Here's a short summary. <kbd>C-</kbd><var>x</var> means +press the <kbd>CTRL</kbd> key and the key <var>x</var>. <kbd>M-</kbd><var>x</var> means +press the <kbd>META</kbd> key and the key <var>x</var>. On many terminals th +<kbd>META</kbd> key is known as the <kbd>ALT</kbd> key. <kbd>SPC</kbd> is the space +bar. The other keys are usually called by the names imprinted on +them.</p> + + <p class="footnote"><small>[<a name="fn-5" href="#fnd-5">5</a>]</small> <code>M-x</code> is also a command; it +invokes <code>execute-extended-command</code>. See <a href="emacs.html#M_002dx">Executing an extended command (the GNU Emacs Manual)</a>, for more detailed +information.</p> + + <p class="footnote"><small>[<a name="fn-6" href="#fnd-6">6</a>]</small> +Some people are used to calling these operations <dfn>cut</dfn> and +<dfn>paste</dfn>, respectively.</p> + + <p class="footnote"><small>[<a name="fn-7" href="#fnd-7">7</a>]</small> Due to the limitations of +DOS filesystems, the MS-DOS version of Info looks for a file +<span class="file">_info</span> instead. If the <span class="env">HOME</span> variable is not defined, Info +additionally looks in the current directory.</p> + + <p class="footnote"><small>[<a name="fn-8" href="#fnd-8">8</a>]</small> This file is named <span class="file">_infokey</span> in +the MS-DOS version, and is looked for in the current directory if +<span class="env">HOME</span> is undefined.</p> + + <p><hr></div> + +</body></html> + diff --git a/Master/texmf/doc/texinfo/info-stnd.pdf b/Master/texmf/doc/texinfo/info-stnd.pdf Binary files differnew file mode 100644 index 00000000000..b12ac9057e7 --- /dev/null +++ b/Master/texmf/doc/texinfo/info-stnd.pdf diff --git a/Master/texmf/doc/texinfo/info.html b/Master/texmf/doc/texinfo/info.html new file mode 100644 index 00000000000..c9c89eb97d9 --- /dev/null +++ b/Master/texmf/doc/texinfo/info.html @@ -0,0 +1,1534 @@ +<html lang="en"> +<head> +<title>Info</title> +<meta http-equiv="Content-Type" content="text/html"> +<meta name="description" content="Info"> +<meta name="generator" content="makeinfo 4.7"> +<link title="Top" rel="top" href="#Top"> +<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> +<!-- +This file describes how to use Info, the on-line, menu-driven GNU +documentation system. + +Copyright (C) 1989, 1992, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004 +Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation License, + Version 1.1 or any later version published by the Free Software + Foundation; with no Invariant Sections, with the Front-Cover texts + being "A GNU Manual", and with the Back-Cover Texts as in (a) + below. A copy of the license is included in the section entitled + "GNU Free Documentation License" in the Emacs manual. + + (a) The FSF's Back-Cover Text is: "You have freedom to copy and + modify this GNU Manual, like GNU software. Copies published by + the Free Software Foundation raise funds for GNU development." + + This document is part of a collection distributed under the GNU + Free Documentation License. If you want to distribute this + document separately from the collection, you can do so by adding a + copy of the license to the document, as described in section 6 of + the license. + --> +<meta http-equiv="Content-Style-Type" content="text/css"> +<style type="text/css"><!-- + pre.display { font-family:inherit } + pre.format { font-family:inherit } + pre.smalldisplay { font-family:inherit; font-size:smaller } + pre.smallformat { font-family:inherit; font-size:smaller } + pre.smallexample { font-size:smaller } + pre.smalllisp { font-size:smaller } + span.sc { font-variant:small-caps } + span.roman { font-family: serif; font-weight: normal; } +--></style> +</head> +<body> +<h1 class="settitle">Info</h1> + <div class="contents"> +<h2>Table of Contents</h2> +<ul> +<li><a name="toc_Top" href="#Top">Info: An Introduction</a> +<li><a name="toc_Getting-Started" href="#Getting-Started">1 Getting Started</a> +<ul> +<li><a href="#Help_002dSmall_002dScreen">1.1 Starting Info on a Small Screen</a> +<li><a href="#Help">1.2 How to use Info</a> +<li><a href="#Help_002dP">1.3 Returning to the Previous node</a> +<li><a href="#Help_002d_005eL">1.4 The Space, DEL, B and ^L commands</a> +<li><a href="#Help_002dInv">1.5 Invisible text in Emacs Info</a> +<ul> +<li><a href="#Help_002d_005d">1.5.1 The <kbd>]</kbd> and <kbd>[</kbd> commands</a> +</li></ul> +<li><a href="#Help_002dM">1.6 Menus and the <kbd>m</kbd> command</a> +<ul> +<li><a href="#Help_002dFOO">1.6.1 The <kbd>u</kbd> command</a> +</li></ul> +<li><a href="#Help_002dXref">1.7 Following Cross-References</a> +<li><a href="#Help_002dInt">1.8 Some intermediate Info commands</a> +</li></ul> +<li><a name="toc_Expert-Info" href="#Expert-Info">2 Info for Experts</a> +<ul> +<li><a href="#Advanced">2.1 Advanced Info Commands</a> +<li><a href="#Info-Search">2.2 How to search Info documents for specific subjects</a> +<li><a href="#Add">2.3 Adding a new node to Info</a> +<li><a href="#Menus">2.4 How to Create Menus</a> +<li><a href="#Cross_002drefs">2.5 Creating Cross References</a> +<ul> +<li><a href="#Help_002dCross">2.5.1 The node reached by the cross reference in Info</a> +</li></ul> +<li><a href="#Help_002dQ">2.6 Quitting Info</a> +<li><a href="#Tags">2.7 Tags Tables for Info Files</a> +<li><a href="#Checking">2.8 Checking an Info File</a> +<li><a href="#Emacs-Info-Variables">2.9 Emacs Info-mode Variables</a> +</li></ul> +<li><a name="toc_Creating-an-Info-File" href="#Creating-an-Info-File">3 Creating an Info File from a Texinfo File</a> +<li><a name="toc_Index" href="#Index">Index</a> +</li></ul> +</div> + + + +<div class="node"> +<p><hr> +<a name="Top"></a>Next: <a rel="next" accesskey="n" href="#Getting-Started">Getting Started</a>, +Up: <a rel="up" accesskey="u" href="#dir">(dir)</a> +<br> +</div> + +<h2 class="unnumbered">Info: An Introduction</h2> + +<p>The GNU Project distributes most of its on-line manuals in the +<dfn>Info format</dfn>, which you read using an <dfn>Info reader</dfn>. You are +probably using an Info reader to read this now. + +<ul class="menu"> +<li><a accesskey="1" href="#Getting-Started">Getting Started</a>: Getting started using an Info reader. +<li><a accesskey="2" href="#Expert-Info">Expert Info</a>: Info commands for experts. +<li><a accesskey="3" href="#Creating-an-Info-File">Creating an Info File</a>: How to make your own Info file. +<li><a accesskey="4" href="#Index">Index</a>: An index of topics, commands, and variables. +</ul> + +<div class="node"> +<p><hr> +<a name="Getting-Started"></a>Next: <a rel="next" accesskey="n" href="#Expert-Info">Expert Info</a>, +Previous: <a rel="previous" accesskey="p" href="#Top">Top</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> +<br> +</div> + +<!-- node-name, next, previous, up --> +<h2 class="chapter">1 Getting Started</h2> + +<p>This first part of the Info manual describes how to get around inside +of Info. The second part of the manual describes various advanced +Info commands, and how to write an Info as distinct from a Texinfo +file. The third part briefly explains how to generate Info files from +Texinfo files. + + <p>This manual is primarily designed for browsing with an Info reader +program on a computer, so that you can try Info commands while reading +about them. Reading it on paper or with an HTML browser is less +effective, since you must take it on faith that the commands described +really do what the manual says. By all means go through this manual +now that you have it; but please try going through the on-line version +as well. + + <p><a name="index-Info-reader_002c-how-to-invoke-1"></a><a name="index-entering-Info-2"></a>There are two ways of looking at the online version of this manual: + + <ol type=1 start=1> +<li>Type <code>info</code> at your shell's command line. This approach uses a +stand-alone program designed just to read Info files. + + <li>Type <code>emacs</code> at the command line; then type <kbd>C-h i</kbd> +(<kbd>Control-h</kbd>, followed by <kbd>i</kbd>). This approach uses the Info +mode of the Emacs program, an editor with many other capabilities. + </ol> + + <p>In either case, then type <kbd>mInfo</kbd> (just the letters), followed by +<RET>—the “Return” or “Enter” key. At this point, you should +be ready to follow the instructions in this manual as you read them on +the screen. +<!-- FIXME! (pesch@cygnus.com, 14 dec 1992) --> +<!-- Is it worth worrying about what-if the beginner goes to somebody --> +<!-- else's Emacs session, which already has an Info running in the middle --> +<!-- of something-in which case these simple instructions won't work? --> + +<ul class="menu"> +<li><a accesskey="1" href="#Help_002dSmall_002dScreen">Help-Small-Screen</a>: Starting Info on a Small Screen +<li><a accesskey="2" href="#Help">Help</a>: How to use Info +<li><a accesskey="3" href="#Help_002dP">Help-P</a>: Returning to the Previous node +<li><a accesskey="4" href="#Help_002d_005eL">Help-^L</a>: The Space, DEL, B and ^L commands. +<li><a accesskey="5" href="#Help_002dInv">Help-Inv</a>: Invisible text in Emacs Info. +<li><a accesskey="6" href="#Help_002dM">Help-M</a>: Menus +<li><a accesskey="7" href="#Help_002dXref">Help-Xref</a>: Following cross-references +<li><a accesskey="8" href="#Help_002dInt">Help-Int</a>: Some intermediate Info commands +<li><a accesskey="9" href="#Help_002dQ">Help-Q</a>: Quitting Info +</ul> + +<div class="node"> +<p><hr> +<a name="Help_002dSmall_002dScreen"></a>Next: <a rel="next" accesskey="n" href="#Help">Help</a>, +Up: <a rel="up" accesskey="u" href="#Getting-Started">Getting Started</a> +<br> +</div> + +<h3 class="section">1.1 Starting Info on a Small Screen</h3> + +<p>(In Info, you only see this section if your terminal has a small +number of lines; most readers pass by it without seeing it.) + +<p><a name="index-small-screen_002c-moving-around-3"></a>Since your terminal has a relatively small number of lines on its +screen, it is necessary to give you special advice at the beginning. + + <p>If you see the text <span class="samp">--All----</span> near the bottom right corner +of the screen, it means the entire text you are looking at fits on the +screen. If you see <span class="samp">--Top----</span> instead, it means that there is +more text below that does not fit. To move forward through the text +and see another screen full, press <SPC>, the Space bar. To move +back up, press the key labeled <span class="samp">Backspace</span> or <span class="samp">DEL</span> (on some +keyboards, this key might be labeled <span class="samp">Delete</span>). + +<div class="node"> +<p><hr> +<a name="Help"></a>Next: <a rel="next" accesskey="n" href="#Help_002dP">Help-P</a>, +Previous: <a rel="previous" accesskey="p" href="#Help_002dSmall_002dScreen">Help-Small-Screen</a>, +Up: <a rel="up" accesskey="u" href="#Getting-Started">Getting Started</a> +<br> +</div> + +<!-- node-name, next, previous, up --> +<h3 class="section">1.2 How to use Info</h3> + +<p>You are talking to the program Info, for reading documentation. + + <p>There are two ways to use Info: from within Emacs or as a +stand-alone reader that you can invoke from a shell using the command +<span class="command">info</span>. + + <p><a name="index-node_002c-in-Info-documents-4"></a> Right now you are looking at one <dfn>Node</dfn> of Information. +A node contains text describing a specific topic at a specific +level of detail. This node's topic is “how to use Info”. The mode +line says that this is node <span class="samp">Help</span> in the file <span class="file">info</span>. + + <p><a name="index-header-of-Info-node-5"></a> The top line of a node is its <dfn>header</dfn>. This node's header +(look at it now) says that the <span class="samp">Next</span> node after this one is the +node called <span class="samp">Help-P</span>. An advanced Info command lets you go to +any node whose name you know. In the stand-alone Info reader program, +the header line shows the names of this node and the info file as +well. In Emacs, the header line is duplicated in a special typeface, +and the duplicate remains at the top of the window all the time even +if you scroll through the node. + + <p>Besides a <span class="samp">Next</span>, a node can have a <span class="samp">Previous</span> or an +<span class="samp">Up</span> links, or both. As you can see, this node has all of these +links. + + <p><a name="index-n-_0040r_007b_0028Info-mode_0029_007d-6"></a> Now it is time to move on to the <span class="samp">Next</span> node, named <span class="samp">Help-P</span>. + +<pre class="format">>> Type <kbd>n</kbd> to move there. Type just one character; + do not type the quotes and do not type a <RET> afterward. +</pre> + <p class="noindent"><span class="samp">>></span> in the margin means it is really time to try a command. + +<pre class="format">>> If you are in Emacs and have a mouse, and if you already practiced + typing <kbd>n</kbd> to get to the next node, click now with the middle + mouse button on the <span class="samp">Next</span> link to do the same “the mouse way”. +</pre> + <div class="node"> +<p><hr> +<a name="Help_002dP"></a>Next: <a rel="next" accesskey="n" href="#Help_002d_005eL">Help-^L</a>, +Previous: <a rel="previous" accesskey="p" href="#Help">Help</a>, +Up: <a rel="up" accesskey="u" href="#Getting-Started">Getting Started</a> +<br> +</div> + +<!-- node-name, next, previous, up --> +<h3 class="section">1.3 Returning to the Previous node</h3> + +<p><a name="index-p-_0040r_007b_0028Info-mode_0029_007d-7"></a>This node is called <span class="samp">Help-P</span>. The <span class="samp">Previous</span> node, as you see, +is <span class="samp">Help</span>, which is the one you just came from using the <kbd>n</kbd> +command. Another <kbd>n</kbd> command now would take you to the next +node, <span class="samp">Help-^L</span>. + +<pre class="format">>> But do not type <kbd>n</kbd> yet. First, try the <kbd>p</kbd> command, + or click the middle mouse button on the <span class="samp">Prev</span> link. That + takes you to the <span class="samp">Previous</span> node. Then use <kbd>n</kbd> to return here. +</pre> + <p>If you read this in Emacs, you will see an <span class="samp">Info</span> item in the +menu bar, close to its right edge. Clicking the mouse on the +<span class="samp">Info</span> menu-bar item opens a menu of commands which include +<span class="samp">Next</span> and <span class="samp">Prev</span> (and also some others which you didn't yet +learn about). + + <p>This all probably seems insultingly simple so far, but <em>please +don't</em> start skimming. Things will get complicated soon enough! +Also, please do not try a new command until you are told it is time +to. You could make Info skip past an important warning that was +coming up. + +<pre class="format">>> Now do an <kbd>n</kbd>, or click the middle mouse button on the <span class="samp">Next</span> + link, to get to the node <span class="samp">Help-^L</span> and learn more. +</pre> + <div class="node"> +<p><hr> +<a name="Help_002d_005eL"></a>Next: <a rel="next" accesskey="n" href="#Help_002dInv">Help-Inv</a>, +Previous: <a rel="previous" accesskey="p" href="#Help_002dP">Help-P</a>, +Up: <a rel="up" accesskey="u" href="#Getting-Started">Getting Started</a> +<br> +</div> + +<!-- node-name, next, previous, up --> +<h3 class="section">1.4 The Space, DEL, B and ^L commands</h3> + +<p>This node's mode line tells you that you are now at node +<span class="samp">Help-^L</span>, and the header line tells you that <kbd>p</kbd> would get +you back to <span class="samp">Help-P</span>. The node's title is highlighted and may be +underlined as well; it says what the node is about. + + <p>This is a big node and it does not all fit on your display screen. +You can tell that there is more that is not visible because you +can see the string <span class="samp">--Top-----</span> rather than <span class="samp">--All----</span> near +the bottom right corner of the screen. + + <p><a name="index-SPC-_0040r_007b_0028Info-mode_0029_007d-8"></a><a name="index-DEL-_0040r_007b_0028Info-mode_0029_007d-9"></a><a name="index-BACKSPACE-_0040r_007b_0028Info-mode_0029_007d-10"></a><a name="index-Info_002dscroll_002dup-11"></a><a name="index-Info_002dscroll_002ddown-12"></a> The <SPC>, <BACKSPACE> (or <DEL>)<a rel="footnote" href="#fn-1" name="fnd-1"><sup>1</sup></a> and <kbd>b</kbd> commands exist to +allow you to “move around” in a node that does not all fit on the +screen at once. <SPC> moves forward, to show what was below the +bottom of the screen. <DEL> or <BACKSPACE> moves backward, to +show what was above the top of the screen (there is not anything above +the top until you have typed some spaces). + +<pre class="format">>> Now try typing a <SPC> (afterward, type a <BACKSPACE> to + return here). +</pre> + <p>When you type the <SPC>, the two lines that were at the bottom of +the screen appear at the top, followed by more lines. <DEL> or +<BACKSPACE> takes the two lines from the top and moves them to the +bottom, <em>usually</em>, but if there are not a full screen's worth of +lines above them they may not make it all the way to the bottom. + + <p>If you are reading this in Emacs, note that the header line is +always visible, never scrolling off the display. That way, you can +always see the <span class="samp">Next</span>, <span class="samp">Prev</span>, and <span class="samp">Up</span> links, and you +can conveniently go to one of these links at any time by +clicking the middle mouse button on the link. + + <p><a name="index-reading-Info-documents-top-to-bottom-13"></a><a name="index-Info-documents-as-tutorials-14"></a> <SPC> and <DEL> not only move forward and backward through +the current node. They also move between nodes. <SPC> at the end +of a node moves to the next node; <DEL> (or <BACKSPACE>) at +the beginning of a node moves to the previous node. In effect, these +commands scroll through all the nodes in an Info file as a single +logical sequence. You can read an entire manual top to bottom by just +typing <SPC>, and move backward through the entire manual from +bottom to top by typing <DEL> (or <BACKSPACE>). + + <p>In this sequence, a node's subnodes appear following their parent. +If a node has a menu, <SPC> takes you into the subnodes listed in +the menu, one by one. Once you reach the end of a node, and have seen +all of its subnodes, <SPC> takes you to the next node or to the +parent's next node. + + <p><a name="index-PAGEUP-_0040r_007b_0028Info-mode_0029_007d-15"></a><a name="index-PAGEDOWN-_0040r_007b_0028Info-mode_0029_007d-16"></a> Many keyboards nowadays have two scroll keys labeled <span class="samp">PageUp</span> +and <span class="samp">PageDown</span> (or maybe <span class="samp">Prior</span> and <span class="samp">Next</span>). If your +keyboard has these keys, you can use them to move forward and backward +through the text of one node, like <SPC> and <BACKSPACE> (or +<DEL>). However, <PAGEUP> and <PAGEDOWN> keys never +scroll beyond the beginning or the end of the current node. + + <p><a name="index-C_002dl-_0040r_007b_0028Info-mode_0029_007d-17"></a> If your screen is ever garbaged, you can tell Info to display it +again by typing <kbd>C-l</kbd> (<kbd>Control-L</kbd>, that is—hold down +<CTRL> and type <kbd>L</kbd> or <kbd>l</kbd>). + +<pre class="format">>> Type <kbd>C-l</kbd> now. +</pre> + <p><a name="index-b-_0040r_007b_0028Info-mode_0029_007d-18"></a> To move back to the beginning of the node you are on, you can type +the <BACKSPACE> key (or <DEL>) many times. You can also type +<kbd>b</kbd> just once. <kbd>b</kbd> stands for “beginning.” + +<pre class="format">>> Try that now. (We have put in enough verbiage to push this past + the first screenful, but screens are so big nowadays that perhaps it + isn't enough. You may need to shrink your Emacs or Info window.) + Then come back, by typing <SPC> one or more times. +</pre> + <p>If your screen is very tall, all of this node might fit at once. In +that case, <kbd>b</kbd> won't do anything. But you could observe the +effect of the <kbd>b</kbd> key if you use a smaller window. + + <p><a name="index-_003f-_0040r_007b_0028Info-mode_0029_007d-19"></a><a name="index-Info_002dsummary-20"></a> You have just learned a considerable number of commands. If you +want to use one but have trouble remembering which, you should type +a <kbd>?</kbd> (in Emacs it runs the <code>Info-summary</code> command) which +displays a brief list of commands. When you are finished looking at +the list, make it go away by typing a <SPC> repeatedly. + +<pre class="format">>> Type a <?> now. Press <SPC> to see consecutive screenfuls of + the list until finished. Then type <SPC> several times. If + you are using Emacs, the help will then go away automatically. +</pre> + <p>(If you are using the stand-alone Info reader, type <kbd>C-x 0</kbd> to +return here, that is—press and hold <CTRL>, type an <kbd>x</kbd>, +then release <CTRL> and <kbd>x</kbd>, and press <kbd>0</kbd>—a zero, not +the letter “o”.) + + <p>From now on, you will encounter large nodes without warning, and +will be expected to know how to use <SPC> and <BACKSPACE> to +move around in them without being told. Since not all terminals have +the same size screen, it would be impossible to warn you anyway. + +<pre class="format">>> Now type <kbd>n</kbd>, or click the middle mouse button on the <span class="samp">Next</span> link, + to visit the next node. +</pre> + <div class="node"> +<p><hr> +<a name="Help_002dInv"></a>Next: <a rel="next" accesskey="n" href="#Help_002dM">Help-M</a>, +Previous: <a rel="previous" accesskey="p" href="#Help_002d_005eL">Help-^L</a>, +Up: <a rel="up" accesskey="u" href="#Getting-Started">Getting Started</a> +<br> +</div> + +<!-- node-name, next, previous, up --> +<h3 class="section">1.5 Invisible text in Emacs Info</h3> + +<p>Before discussing menus, we need to make some remarks that are only +relevant to users reading Info using Emacs. Users of the stand-alone +version can skip this node by typing <kbd>]</kbd> now. + + <p><a name="index-invisible-text-in-Emacs-21"></a> In Emacs, certain text that appears in the stand-alone version is +normally hidden, technically because it has the <span class="samp">invisibility</span> +property. Invisible text is really a part of the text. It becomes +visible (by default) after killing and yanking, it appears in printed +output, it gets saved to file just like any other text, and so on. +Thus it is useful to know it is there. + + <p><a name="index-visible_002dmode-22"></a>You can make invisible text visible by using the command <kbd>M-x +visible-mode</kbd>. Visible mode is a minor mode, so using the command a +second time will make the text invisible again. Watch the effects of +the command on the “menu” below and the top line of this node. + + <p>If you prefer to <em>always</em> see the invisible text, you can set +<code>Info-hide-note-references</code> to <code>nil</code>. Enabling Visible mode +permanently is not a real alternative, because Emacs Info also uses +(although less extensively) another text property that can change the +text being displayed, the <span class="samp">display</span> property. Only the +invisibility property is affected by Visible mode. When, in this +tutorial, we refer to the <span class="samp">Emacs</span> behavior, we mean the +<em>default</em> Emacs behavior. + + <p>Now type <kbd>]</kbd>, to learn about the <kbd>]</kbd> and <kbd>[</kbd> commands. + +<ul class="menu"> +<li><a accesskey="1" href="#Help_002d_005d">]</a>: Node telling about ]. +<li><a accesskey="2" href="#Help_002d_005d">stuff</a>: Same node. +<li><a accesskey="3" href="#Help_002d_005d">Help-]</a>: Yet again, same node. +</ul> + +<div class="node"> +<p><hr> +<a name="Help_002d_005d"></a>Up: <a rel="up" accesskey="u" href="#Help_002dInv">Help-Inv</a> +<br> +</div> + +<h4 class="subsection">1.5.1 The <kbd>]</kbd> and <kbd>[</kbd> commands</h4> + +<p>If you type <kbd>n</kbd> now, you get an error message saying that this +node has no next node. Similarly, if you type <kbd>p</kbd>, the error +message tells you that there is no previous node. (The exact message +depends on the Info reader you use.) This is because <kbd>n</kbd> and +<kbd>p</kbd> carry you to the next and previous node <em>at the same +level</em>. The present node is contained in a menu (see next) of the +node you came from, and hence is considered to be at a lower level. +It is the only node in the previous node's menu (even though it was +listed three times). Hence it has no next or previous node that +<kbd>n</kbd> or <kbd>p</kbd> could move to. + + <p>If you systematically move through a manual by typing <kbd>n</kbd>, you run +the risk of skipping many nodes. You do not run this risk if you +systematically use <kbd><SPC></kbd>, because, when you scroll to the +bottom of a node and type another <kbd><SPC></kbd>, then this carries +you to the following node in the manual <em>regardless of level</em>. +If you immediately want to go to that node, without having to scroll +to the bottom of the screen first, you can type <kbd>]</kbd>. + + <p>Similarly, <kbd><BACKSPACE></kbd> carries you to the preceding node +regardless of level, after you scrolled to the beginning of the +present node. If you want to go to the preceding node immediately, +you can type <kbd>[</kbd>. + + <p>For instance, typing this sequence will come back here in three steps: +<kbd>[ n [</kbd>. To do the same backward, type <kbd>] p ]</kbd>. + + <p>Now type <kbd>]</kbd> to go to the next node and learn about menus. + +<div class="node"> +<p><hr> +<a name="Help_002dM"></a>Next: <a rel="next" accesskey="n" href="#Help_002dXref">Help-Xref</a>, +Previous: <a rel="previous" accesskey="p" href="#Help_002dInv">Help-Inv</a>, +Up: <a rel="up" accesskey="u" href="#Getting-Started">Getting Started</a> +<br> +</div> + +<!-- node-name, next, previous, up --> +<h3 class="section">1.6 Menus and the <kbd>m</kbd> command</h3> + +<p><a name="index-menus-in-an-Info-document-23"></a><a name="index-Info-menus-24"></a> With only the <kbd>n</kbd> (next), <kbd>p</kbd> (previous), <kbd><SPC></kbd>, +<kbd><BACKSPACE></kbd>, <kbd>]</kbd> and <kbd>[</kbd> commands for moving between +nodes, nodes are restricted to a linear sequence. Menus allow a +branching structure. A menu is a list of other nodes you can move to. +It is actually just part of the text of the node formatted specially +so that Info can interpret it. The beginning of a menu is always +identified by a line which starts with <span class="samp">* Menu:</span><!-- /@w -->. A node +contains a menu if and only if it has a line in it which starts that +way. The only menu you can use at any moment is the one in the node +you are in. To use a menu in any other node, you must move to that +node first. + + <p>After the start of the menu, each line that starts with a <span class="samp">*</span> +identifies one subtopic. The line usually contains a brief name for +the subtopic (followed by a <span class="samp">:</span>, normally hidden in Emacs), the +name of the node that talks about that subtopic (again, normally +hidden in Emacs), and optionally some further description of the +subtopic. Lines in the menu that do not start with a <span class="samp">*</span> have no +special meaning—they are only for the human reader's benefit and do +not define additional subtopics. Here is an example: + +<pre class="example"> * Foo: Node about FOO. This tells about FOO. +</pre> + <p>The subtopic name is Foo, and the node describing it is <span class="samp">Node +about FOO</span>. The rest of the line is just for the reader's +Information. [[ But this line is not a real menu item, simply because +there is no line above it which starts with <span class="samp">* Menu:</span><!-- /@w -->. Also, +in a real menu item, the <span class="samp">*</span> would appear at the very start of +the line. This is why the “normally hidden” text in Emacs, namely +<span class="samp">: Node about FOO.</span>, is actually visible in this example, even +when Visible mode is off.]] + + <p>When you use a menu to go to another node (in a way that will be +described soon), what you specify is the subtopic name, the first +thing in the menu line. Info uses it to find the menu line, extracts +the node name from it, and goes to that node. The reason that there +is both a subtopic name and a node name is that the node name must be +meaningful to the computer and may therefore have to be ugly looking. +The subtopic name can be chosen just to be convenient for the user to +specify. Often the node name is convenient for the user to specify +and so both it and the subtopic name are the same. There is an +abbreviation for this: + +<pre class="example"> * Foo:: This tells about FOO. +</pre> + <p class="noindent">This means that the subtopic name and node name are the same; they are +both <span class="samp">Foo</span>. (The <span class="samp">::</span> is normally hidden in Emacs.) + +<pre class="format">>> Now use <SPC> to find the menu in this node, then come back to + the front with a <kbd>b</kbd> and some <SPC>s. As you see, a menu is + actually visible in its node. If you cannot find a menu in a node + by looking at it, then the node does not have a menu and the + <kbd>m</kbd> command is not available. +</pre> + <p>If you keep typing <SPC> once the menu appears on the screen, it +will move to another node (the first one in the menu). If that +happens, type <BACKSPACE> to come back. + + <p><a name="index-m-_0040r_007b_0028Info-mode_0029_007d-25"></a> The command to go to one of the subnodes is <kbd>m</kbd>. This is very +different from the commands you have used: it is a command that +prompts you for more input. + + <p>The Info commands you know do not need additional input; when you +type one of them, Info processes it instantly and then is ready for +another command. The <kbd>m</kbd> command is different: it needs to know +the <dfn>name of the subtopic</dfn>. Once you have typed <kbd>m</kbd>, Info +tries to read the subtopic name. + + <p>Now, in the stand-alone Info, look for the line containing many +dashes near the bottom of the screen. (This is the stand-alone +equivalent for the mode line in Emacs.) There is one more line +beneath that one, but usually it is blank. (In Emacs, this is the +echo area.) When it is blank, Info is ready for a command, such as +<kbd>n</kbd> or <kbd>b</kbd> or <SPC> or <kbd>m</kbd>. If that line contains +text ending in a colon, it means Info is reading more input for the +last command. You can't type an Info command then, because Info is +trying to read input, not commands. You must either give the input +and finish the command you started, or type <kbd>Control-g</kbd> to cancel +the command. When you have done one of those things, the input entry +line becomes blank again. Then you can type Info commands again. + + <p><a name="index-Info_002dmenu-26"></a> The command to go to a subnode via a menu is <kbd>m</kbd>. After you type +the <kbd>m</kbd>, the line at the bottom of the screen says <span class="samp">Menu item: </span>. +You must then type the name of the subtopic you want, and end it with +a <RET>. In Emacs, <kbd>m</kbd> runs the command <code>Info-menu</code>. + + <p><a name="index-abbreviating-Info-subnodes-27"></a> You can abbreviate the subtopic name. If the abbreviation is not +unique, the first matching subtopic is chosen. Some menus put +the shortest possible abbreviation for each subtopic name in capital +letters, so you can see how much you need to type. It does not +matter whether you use upper case or lower case when you type the +subtopic. You should not put any spaces at the end, or inside of the +item name, except for one space where a space appears in the item in +the menu. + + <p><a name="index-completion-of-Info-node-names-28"></a> You can also use the <dfn>completion</dfn> feature to help enter the +subtopic name. If you type the <TAB> key after entering part of a +name, it will fill in more of the name—as much as Info can deduce +from the part you have entered. + + <p>If you move the cursor to one of the menu subtopic lines, then you do +not need to type the argument: you just type a <RET>, and it +stands for the subtopic of the line you are on. You can also click +the middle mouse button directly on the subtopic line to go there. + + <p>Here is a menu to give you a chance to practice. This menu gives you +three ways of going to one place, Help-FOO: + +<ul class="menu"> +<li><a accesskey="1" href="#Help_002dFOO">Foo</a>: A node you can visit for fun. +<li><a accesskey="2" href="#Help_002dFOO">Bar</a>: We have made two ways to get to the same place. +<li><a accesskey="3" href="#Help_002dFOO">Help-FOO</a>: And yet another! +</ul> + + <p>(Turn Visible mode on if you are using Emacs.) + +<pre class="format">>> Now type just an <kbd>m</kbd> and see what happens: +</pre> + <p>Now you are “inside” an <kbd>m</kbd> command. Commands cannot be used +now; the next thing you will type must be the name of a subtopic. + + <p>You can change your mind about doing the <kbd>m</kbd> by typing +<kbd>Control-g</kbd>. + +<pre class="format">>> Try that now; notice the bottom line clear. +</pre> + <pre class="format">>> Then type another <kbd>m</kbd>. +</pre> + <pre class="format">>> Now type <kbd>BAR</kbd>, the item name. Do not type <RET> yet. +</pre> + <p>While you are typing the item name, you can use the <DEL> (or +<BACKSPACE>) key to cancel one character at a time if you make a +mistake. + +<pre class="format">>> Press <DEL> to cancel the <span class="samp">R</span>. You could type another <kbd>R</kbd> + to replace it. But you do not have to, since <span class="samp">BA</span> is a valid + abbreviation. +</pre> + <pre class="format">>> Now you are ready to go. Type a <RET>. +</pre> + <p>After visiting <span class="samp">Help-FOO</span>, you should return here. + + <p>Another way to move to the menu subtopic lines and between them is +to type <TAB>. Each time you type a <TAB>, you move to the +next subtopic line. To move to a previous subtopic line, type +<kbd>M-<TAB></kbd>—that is, press and hold the <META> key and then +press <TAB>. (On some keyboards, the <META> key might be labeled +<span class="samp">Alt</span>.) + + <p>Once you move cursor to a subtopic line, press <RET> to go to +that subtopic's node. + + <p><a name="index-mouse-support-in-Info-mode-29"></a><a name="index-Mouse_002d2-_0040r_007b_0028Info-mode_0029_007d-30"></a> If your terminal supports a mouse, you have yet another way of going +to a subtopic. Move your mouse pointer to the subtopic line, +somewhere between the beginning <span class="samp">*</span> and the colon <span class="samp">:</span> which +ends the subtopic's brief name. You will see the subtopic's name +change its appearance (usually, its background color will change), and +the shape of the mouse pointer will change if your platform supports +that. After a while, if you leave the mouse on that spot, a small +window will pop up, saying “Mouse-2: go to that node”, or the same +message may appear at the bottom of the screen. + + <p><kbd>Mouse-2</kbd> is the second button of your mouse counting from the +left—the middle button on a 3-button mouse. (On a 2-button mouse, +you may have to press both buttons together to “press the middle +button”.) The message tells you pressing <kbd>Mouse-2</kbd> with the +current position of the mouse pointer (on subtopic in the menu) will +go to that subtopic. + + <p><a name="index-Info_002dmouse_002dfollow_002dnearest_002dnode-31"></a> More generally, <kbd>Mouse-2</kbd> in an Info buffer finds the nearest +link to another node and goes there. For example, near a cross +reference it acts like <kbd>f</kbd>, in a menu it acts like <kbd>m</kbd>, on the +node's header line it acts like <kbd>n</kbd>, <kbd>p</kbd>, or <kbd>u</kbd>, etc. At +end of the node's text <kbd>Mouse-2</kbd> moves to the next node, or up if +there's no next node. + +<pre class="format">>> Type <kbd>n</kbd> to see more commands. +</pre> + <div class="node"> +<p><hr> +<a name="Help_002dFOO"></a>Up: <a rel="up" accesskey="u" href="#Help_002dM">Help-M</a> +<br> +</div> + +<h4 class="subsection">1.6.1 The <kbd>u</kbd> command</h4> + +<p>Congratulations! This is the node <span class="samp">Help-FOO</span>. It has an <span class="samp">Up</span> +pointer <span class="samp">Help-M</span>, the node you just came from via the <kbd>m</kbd> +command. This is the usual convention—the nodes you reach from a menu +have <span class="samp">Up</span> nodes that lead back to the menu. Menus move Down in the +tree, and <span class="samp">Up</span> moves Up. <span class="samp">Previous</span>, on the other hand, is +usually used to “stay on the same level but go backwards”. + + <p><a name="index-u-_0040r_007b_0028Info-mode_0029_007d-32"></a><a name="index-Info_002dup-33"></a> You can go back to the node <span class="samp">Help-M</span> by typing the command +<kbd>u</kbd> for “Up” (the Emacs command run by <kbd>u</kbd> is +<code>Info-up</code>). That puts you at the <em>front</em> of the node—to +get back to where you were reading you have to type some <SPC>s. +(Some Info readers, such as the one built into Emacs, put you at the +same place where you were reading in <span class="samp">Help-M</span>.) + + <p>Another way to go Up is to click <kbd>Mouse-2</kbd> on the <span class="samp">Up</span> +pointer shown in the header line (provided that you have a mouse). + +<pre class="format">>> Now type <kbd>u</kbd> to move back up to <span class="samp">Help-M</span>. +</pre> + <div class="node"> +<p><hr> +<a name="Help_002dXref"></a>Next: <a rel="next" accesskey="n" href="#Help_002dInt">Help-Int</a>, +Previous: <a rel="previous" accesskey="p" href="#Help_002dM">Help-M</a>, +Up: <a rel="up" accesskey="u" href="#Getting-Started">Getting Started</a> +<br> +</div> + +<!-- node-name, next, previous, up --> +<h3 class="section">1.7 Following Cross-References</h3> + +<p><a name="index-cross-references-in-Info-documents-34"></a> In Info documentation, you will see many <dfn>cross references</dfn>. +Cross references look like this: See <a href="#Help_002dCross">Cross</a>. That text +is a real, live cross reference, whose name is <span class="samp">Cross</span> and which +points to the node named <span class="samp">Help-Cross</span>. (The node name is hidden +in Emacs. Do <kbd>M-x visible-mode</kbd> to show or hide it.) + + <p><a name="index-f-_0040r_007b_0028Info-mode_0029_007d-35"></a><a name="index-Info_002dfollow_002dreference-36"></a> There are two ways to follow a cross reference. You can move the +cursor to it and press <RET>, just as in a menu. <RET> +follows the cross reference that the cursor is on. Or you can type +<kbd>f</kbd> and then specify the name of the cross reference (in this +case, <span class="samp">Cross</span>) as an argument. In Emacs Info, <kbd>f</kbd> runs +<code>Info-follow-reference</code>, + + <p>In the <kbd>f</kbd> command, you select the cross reference with its +name, so it does not matter where the cursor was. If the cursor is on +or near a cross reference, <kbd>f</kbd> suggests that reference name in +parentheses as the default; typing <RET> will follow that +reference. However, if you type a different reference name, <kbd>f</kbd> +will follow the other reference which has that name. + +<pre class="format">>> Type <kbd>f</kbd>, followed by <kbd>Cross</kbd>, and then <RET>. +</pre> + <p>As you enter the reference name, you can use the <DEL> (or +<BACKSPACE>) key to edit your input. If you change your mind +about following any reference, you can use <kbd>Control-g</kbd> to cancel +the command. Completion is available in the <kbd>f</kbd> command; you can +complete among all the cross reference names in the current node by +typing a <TAB>. + + <p>To get a list of all the cross references in the current node, you +can type <kbd>?</kbd> after an <kbd>f</kbd>. The <kbd>f</kbd> continues to await a +cross reference name even after displaying the list, so if you don't +actually want to follow a reference, you should type a <kbd>Control-g</kbd> +to cancel the <kbd>f</kbd>. + +<pre class="format">>> Type <kbd>f?</kbd> to get a list of the cross references in this node. Then + type a <kbd>Control-g</kbd> and see how the <span class="samp">f</span> gives up. +</pre> + <p>The <TAB> and <kbd>M-<TAB></kbd> key, which move between menu +items in a menu, also move between cross references outside of menus. + + <p>Sometimes a cross reference (or a node) can lead to another file (in +other words another “manual”), or, on occasion, even a file on a +remote machine (although Info files distributed with Emacs or the +stand-alone Info avoid using remote links). Such a cross reference +looks like this: See <a href="texinfo.html#Top">Overview of Texinfo (Texinfo: The GNU Documentation Format)</a>. (After following this link, type +<kbd>l</kbd> to get back to this node.) Here the name <span class="samp">texinfo</span> +between parentheses (shown in the stand-alone version) refers to the +file name. This file name appears in cross references and node names +if it differs from the current file. In Emacs, the file name is +hidden (along with other text). (Use <kbd>M-x visible-mode</kbd> to show +or hide it.) + + <p>The remainder of this node applies only to the Emacs version. If +you use the stand-alone version, you can type <kbd>n</kbd> immediately. + + <p>To some users, switching manuals is a much bigger switch than +switching sections. These users like to know that they are going to +be switching to another manual (and which one) before actually doing +so, especially given that, if one does not notice, Info commands like +<kbd>t</kbd> (see the next node) can have confusing results. + + <p>If you put your mouse over the cross reference and if the cross +reference leads to a different manual, then the information appearing +in a separate box (tool tip) or in the echo area, will mention the +file the cross reference will carry you to (between parentheses). +This is also true for menu subtopic names. If you have a mouse, just +leave it over the <span class="samp">Overview</span> cross reference above and watch what +happens. + + <p>If you always like to have that information available without having +to move your mouse over the cross reference, set +<code>Info-hide-note-references</code> to a value other than t (see <a href="#Emacs-Info-Variables">Emacs Info Variables</a>). You might also want to do that if you have a lot of +cross references to files on remote machines and have non-permanent or +slow access, since otherwise you might not be able to distinguish +between local and remote links. + +<pre class="format">>> Now type <kbd>n</kbd> to learn more commands. +</pre> + <div class="node"> +<p><hr> +<a name="Help_002dInt"></a>Next: <a rel="next" accesskey="n" href="#Help_002dQ">Help-Q</a>, +Previous: <a rel="previous" accesskey="p" href="#Help_002dXref">Help-Xref</a>, +Up: <a rel="up" accesskey="u" href="#Getting-Started">Getting Started</a> +<br> +</div> + +<!-- node-name, next, previous, up --> +<h3 class="section">1.8 Some intermediate Info commands</h3> + +<p>The introductory course is almost over; please continue +a little longer to learn some intermediate-level commands. + + <p>Most Info files have an index, which is actually a large node +containing little but a menu. The menu has one menu item for each +topic listed in the index. (As a special feature, menus for indices +may also include the line number within the node of the index entry. +This allows Info readers to go to the exact line of an entry, not just +the start of the containing node.) + + <p>You can get to the index from the main menu of the file with the +<kbd>m</kbd> command; then you can use the <kbd>m</kbd> command again in the +index node to go to the node that describes the topic you want. + + <p>There is also a short-cut Info command, <kbd>i</kbd>, which does all of +that for you. It searches the index for a given topic (a string) and +goes to the node which is listed in the index for that topic. +See <a href="#Info-Search">Info Search</a>, for a full explanation. + + <p><a name="index-l-_0040r_007b_0028Info-mode_0029_007d-37"></a><a name="index-Info_002dlast-38"></a><a name="index-going-back-in-Info-mode-39"></a> If you have been moving around to different nodes and wish to +retrace your steps, the <kbd>l</kbd> command (<kbd>l</kbd> for <dfn>last</dfn>) will +do that, one node-step at a time. As you move from node to node, Info +records the nodes where you have been in a special history list. The +<kbd>l</kbd> command revisits nodes in the history list; each successive +<kbd>l</kbd> command moves one step back through the history. + + <p>In Emacs, <kbd>l</kbd> runs the command <code>Info-last</code>. + +<pre class="format">>> Try typing <kbd>p p n</kbd> and then three <kbd>l</kbd>'s, pausing in between +to see what each <kbd>l</kbd> does. You should wind up right back here. +</pre> + <p>Note the difference between <kbd>l</kbd> and <kbd>p</kbd>: <kbd>l</kbd> moves to +where <em>you</em> last were, whereas <kbd>p</kbd> always moves to the node +which the header says is the <span class="samp">Previous</span> node (from this node, the +<span class="samp">Prev</span> link leads to <span class="samp">Help-Xref</span>). + + <p><a name="index-d-_0040r_007b_0028Info-mode_0029_007d-40"></a><a name="index-Info_002ddirectory-41"></a><a name="index-go-to-Directory-node-42"></a> The <kbd>d</kbd> command (<code>Info-directory</code> in Emacs) gets you +instantly to the Directory node. This node, which is the first one +you saw when you entered Info, has a menu which leads (directly or +indirectly, through other menus), to all the nodes that exist. The +Directory node lists all the manuals and other Info documents that +are, or could be, installed on your system. + +<pre class="format">>> Try doing a <kbd>d</kbd>, then do an <kbd>l</kbd> to return here (yes, + <em>do</em> return). +</pre> + <p><a name="index-t-_0040r_007b_0028Info-mode_0029_007d-43"></a><a name="index-Info_002dtop_002dnode-44"></a><a name="index-go-to-Top-node-45"></a> The <kbd>t</kbd> command moves to the <span class="samp">Top</span> node of the manual. +This is useful if you want to browse the manual's main menu, or select +some specific top-level menu item. The Emacs command run by <kbd>t</kbd> +is <code>Info-top-node</code>. + + <p>Clicking <kbd>Mouse-2</kbd> on or near a cross reference also follows the +reference. You can see that the cross reference is mouse-sensitive by +moving the mouse pointer to the reference and watching how the +underlying text and the mouse pointer change in response. + +<pre class="format">>> Now type <kbd>n</kbd> to see the last node of the course. +</pre> + <p>See <a href="#Expert-Info">Expert Info</a>, for more advanced Info features. + +<!-- If a menu appears at the end of this node, remove it. --> +<!-- It is an accident of the menu updating command. --> +<div class="node"> +<p><hr> +<a name="Expert-Info"></a>Next: <a rel="next" accesskey="n" href="#Creating-an-Info-File">Creating an Info File</a>, +Previous: <a rel="previous" accesskey="p" href="#Getting-Started">Getting Started</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> +<br> +</div> + +<h2 class="chapter">2 Info for Experts</h2> + +<p>This chapter describes various Info commands for experts. (If you +are using a stand-alone Info reader, there are additional commands +specific to it, which are documented in several chapters of <a href="info-stnd.html#Top">GNU Info (GNU Info)</a>.) + + <p>This chapter also explains how to write an Info as distinct from a +Texinfo file. (However, in most cases, writing a Texinfo file is +better, since you can use it to make a printed manual or produce other +formats, such as HTML and DocBook, as well as for generating Info +files.) See <a href="texinfo.html#Top">Overview of Texinfo (Texinfo: The GNU Documentation Format)</a>. + +<ul class="menu"> +<li><a accesskey="1" href="#Advanced">Advanced</a>: Advanced Info commands: g, e, and 1 - 9. +<li><a accesskey="2" href="#Info-Search">Info Search</a>: How to search Info documents for specific subjects. +<li><a accesskey="3" href="#Add">Add</a>: Describes how to add new nodes to the hierarchy. + Also tells what nodes look like. +<li><a accesskey="4" href="#Menus">Menus</a>: How to add to or create menus in Info nodes. +<li><a accesskey="5" href="#Cross_002drefs">Cross-refs</a>: How to add cross-references to Info nodes. +<li><a accesskey="6" href="#Tags">Tags</a>: How to make tags tables for Info files. +<li><a accesskey="7" href="#Checking">Checking</a>: Checking an Info File +<li><a accesskey="8" href="#Emacs-Info-Variables">Emacs Info Variables</a>: Variables modifying the behavior of Emacs Info. +</ul> + +<div class="node"> +<p><hr> +<a name="Advanced"></a>Next: <a rel="next" accesskey="n" href="#Info-Search">Info Search</a>, +Up: <a rel="up" accesskey="u" href="#Expert-Info">Expert Info</a> +<br> +</div> + +<!-- node-name, next, previous, up --> +<h3 class="section">2.1 Advanced Info Commands</h3> + +<p>Here are some more Info commands that make it easier to move around. + +<h4 class="subheading"><kbd>g</kbd> goes to a node by name</h4> + +<p><a name="index-g-_0040r_007b_0028Info-mode_0029_007d-46"></a><a name="index-Info_002dgoto_002dnode-47"></a><a name="index-go-to-a-node-by-name-48"></a> If you know a node's name, you can go there by typing <kbd>g</kbd>, the +name, and <RET>. Thus, <kbd>gTop<RET></kbd> would go to the node +called <span class="samp">Top</span> in this file. (This is equivalent to <kbd>t</kbd>, see +<a href="#Help_002dInt">Help-Int</a>.) <kbd>gAdvanced<RET></kbd> would come back here. +<kbd>g</kbd> in Emacs runs the command <code>Info-goto-node</code>. + + <p>Unlike <kbd>m</kbd>, <kbd>g</kbd> does not allow the use of abbreviations. +But it does allow completion, so you can type <TAB> to complete a +partial node name. + + <p><a name="index-go-to-another-Info-file-49"></a> To go to a node in another file, you can include the file name in the +node name by putting it at the front, in parentheses. Thus, +<kbd>g(dir)Top<RET></kbd> would go to the Info Directory node, which is +the node <span class="samp">Top</span> in the Info file <span class="file">dir</span>. Likewise, +<kbd>g(emacs)Top<RET></kbd> goes to the top node of the Emacs manual. + + <p>The node name <span class="samp">*</span> specifies the whole file. So you can look at +all of the current file by typing <kbd>g*<RET></kbd> or all of any +other file with <kbd>g(</kbd><var>filename</var><kbd>)<RET></kbd>. + +<h4 class="subheading"><kbd>1</kbd> – <kbd>9</kbd> choose a menu subtopic by its number</h4> + +<p><a name="index-1-_0040r_007bthrough_007d-9-_0040r_007b_0028Info-mode_0029_007d-50"></a><a name="index-Info_002dnth_002dmenu_002ditem-51"></a><a name="index-select-_0040var_007bn_007d_0027th-menu-item-52"></a> If you begrudge each character of type-in which your system requires, +you might like to use the commands <kbd>1</kbd>, <kbd>2</kbd>, <kbd>3</kbd>, <kbd>4</kbd>, +<small class="dots">...</small>, <kbd>9</kbd>. They are short for the <kbd>m</kbd> command together +with a name of a menu subtopic. <kbd>1</kbd> goes through the first item +in the current node's menu; <kbd>2</kbd> goes through the second item, etc. +In the stand-alone reader, <kbd>0</kbd> goes through the last menu item; +this is so you need not count how many entries are there. In Emacs, +the digit keys run the command <code>Info-nth-menu-item</code>. + + <p>If your display supports multiple fonts, colors or underlining, and +you are using Emacs' Info mode to read Info files, the third, sixth +and ninth menu items have a <span class="samp">*</span> that stands out, either in color +or in some other attribute, such as underline; this makes it easy to +see at a glance which number to use for an item. + + <p>Some terminals don't support either multiple fonts, colors or +underlining. If you need to actually count items, it is better to use +<kbd>m</kbd> instead, and specify the name, or use <TAB> to quickly +move between menu items. + +<h4 class="subheading"><kbd>e</kbd> makes Info document editable</h4> + +<p><a name="index-e-_0040r_007b_0028Info-mode_0029_007d-53"></a><a name="index-Info_002dedit-54"></a><a name="index-edit-Info-document-55"></a> The Info command <kbd>e</kbd> changes from Info mode to an ordinary +Emacs editing mode, so that you can edit the text of the current node. +Type <kbd>C-c C-c</kbd> to switch back to Info. The <kbd>e</kbd> command is allowed +only if the variable <code>Info-enable-edit</code> is non-<code>nil</code>. + + <p>The <kbd>e</kbd> command only works in Emacs, where it runs the command +<code>Info-edit</code>. The stand-alone Info reader doesn't allow you to +edit the Info file, so typing <kbd>e</kbd> there goes to the end of the +current node. + +<h4 class="subheading"><kbd>M-n</kbd> creates a new independent Info buffer in Emacs</h4> + +<p><a name="index-M_002dn-_0040r_007b_0028Info-mode_0029_007d-56"></a><a name="index-clone_002dbuffer-57"></a><a name="index-multiple-Info-buffers-58"></a> If you are reading Info in Emacs, you can select a new independent +Info buffer in another window by typing <kbd>M-n</kbd>. The new buffer +starts out as an exact copy of the old one, but you will be able to +move independently between nodes in the two buffers. (In Info mode, +<kbd>M-n</kbd> runs the Emacs command <code>clone-buffer</code>.) + + <p>In Emacs Info, you can also produce new Info buffers by giving a +numeric prefix argument to the <kbd>m</kbd> and <kbd>g</kbd> commands. <kbd>C-u +m</kbd> and <kbd>C-u g</kbd> go to a new node in exactly the same way that +<kbd>m</kbd> and <kbd>g</kbd> do, but they do so in a new Info buffer which they +select in another window. + +<div class="node"> +<p><hr> +<a name="Info-Search"></a>Next: <a rel="next" accesskey="n" href="#Add">Add</a>, +Previous: <a rel="previous" accesskey="p" href="#Advanced">Advanced</a>, +Up: <a rel="up" accesskey="u" href="#Expert-Info">Expert Info</a> +<br> +</div> + +<!-- node-name, next, previous, up --> +<h3 class="section">2.2 How to search Info documents for specific subjects</h3> + +<p><a name="index-searching-Info-documents-59"></a><a name="index-Info-document-as-a-reference-60"></a> The commands which move between and inside nodes allow you to read +the entire manual or its large portions. But what if you need to find +some information in the manual as fast as you can, and you don't know +or don't remember in what node to look for it? This need arises when +you use a manual as a <dfn>reference</dfn>, or when it is impractical to +read the entire manual before you start using the programs it +describes. + + <p>Info has powerful searching facilities that let you find things +quickly. You can search either the manual indices or its text. + + <p><a name="index-i-_0040r_007b_0028Info-mode_0029_007d-61"></a><a name="index-Info_002dindex-62"></a> Since most subjects related to what the manual describes should be +indexed, you should try the index search first. The <kbd>i</kbd> command +prompts you for a subject and then looks up that subject in the +indices. If it finds an index entry with the subject you typed, it +goes to the node to which that index entry points. You should browse +through that node to see whether the issue you are looking for is +described there. If it isn't, type <kbd>,</kbd> one or more times to go +through additional index entries which match your subject. + + <p>The <kbd>i</kbd> command finds all index entries which include the string +you typed <em>as a substring</em>. For each match, Info shows in the +echo area the full index entry it found. Often, the text of the full +index entry already gives you enough information to decide whether it +is relevant to what you are looking for, so we recommend that you read +what Emacs shows in the echo area before looking at the node it +displays. + + <p>Since <kbd>i</kbd> looks for a substring, you can search for subjects even +if you are not sure how they are spelled in the index. For example, +suppose you want to find something that is pertinent to commands which +complete partial input (e.g., when you type <TAB>). If you want +to catch index entries that refer to “complete”, “completion”, and +“completing”, you could type <kbd>icomplet<RET></kbd>. + + <p>Info documents which describe programs should index the commands, +options, and key sequences that the program provides. If you are +looking for a description of a command, an option, or a key, just type +their names when <kbd>i</kbd> prompts you for a topic. For example, if you +want to read the description of what the <kbd>C-f</kbd> key does, type +<kbd>i C - f <RET></kbd>. Here <kbd>C-f</kbd> are 3 literal characters +<span class="samp">C</span>, <span class="samp">-</span>, and <span class="samp">f</span>, not the “Control-f” command key +you type inside Emacs to run the command bound to <kbd>C-f</kbd>. + + <p>In Emacs, <kbd>i</kbd> runs the command <code>Info-index</code>. + + <p><a name="index-info_002dapropos-63"></a>If you don't know what manual documents something, try the <kbd>M-x +info-apropos</kbd> command. It prompts for a string and then looks up that +string in all the indices of all the Info documents installed on your +system. + + <p><a name="index-s-_0040r_007b_0028Info-mode_0029_007d-64"></a><a name="index-Info_002dsearch-65"></a> The <kbd>s</kbd> command allows you to search a whole file for a string. +It switches to the next node if and when that is necessary. You +type <kbd>s</kbd> followed by the string to search for, terminated by +<RET>. To search for the same string again, just <kbd>s</kbd> followed +by <RET> will do. The file's nodes are scanned in the order +they are in in the file, which has no necessary relationship to the +order that they may be in the tree structure of menus and <span class="samp">next</span> +pointers. But normally the two orders are not very different. In any +case, you can always do a <kbd>b</kbd> to find out what node you have +reached, if the header is not visible (this can happen, because <kbd>s</kbd> +puts your cursor at the occurrence of the string, not at the beginning +of the node). + + <p><a name="index-M_002ds-_0040r_007b_0028Info-mode_0029_007d-66"></a> In Emacs, <kbd>Meta-s</kbd> is equivalent to <kbd>s</kbd>. That is for +compatibility with other GNU packages that use <kbd>M-s</kbd> for a similar +kind of search command. Both <kbd>s</kbd> and <kbd>M-s</kbd> run in Emacs the +command <code>Info-search</code>. + +<div class="node"> +<p><hr> +<a name="Add"></a>Next: <a rel="next" accesskey="n" href="#Menus">Menus</a>, +Previous: <a rel="previous" accesskey="p" href="#Info-Search">Info Search</a>, +Up: <a rel="up" accesskey="u" href="#Expert-Info">Expert Info</a> +<br> +</div> + +<!-- node-name, next, previous, up --> +<h3 class="section">2.3 Adding a new node to Info</h3> + +<p>To add a new topic to the list in the Info directory, you must: + + <ol type=1 start=1> +<li>Create some nodes, in some file, to document that topic. +<li>Put that topic in the menu in the directory. See <a href="#Menus">Menu</a>. + </ol> + + <p>Usually, the way to create the nodes is with Texinfo (see <a href="texinfo.html#Top">Overview of Texinfo (Texinfo: The GNU Documentation Format)</a>); +this has the advantage that you can also make a printed manual or HTML +from them. You would use the <span class="samp">@dircategory</span> and +<span class="samp">@direntry</span> commands to put the manual into the Info directory. +However, if you want to edit an Info file manually and install it +manually, here is how. + + <p><a name="index-node-delimiters-67"></a> The new node can live in an existing documentation file, or in a new +one. It must have a <span class="samp">^_</span> character before it (invisible to the +user; this node has one but you cannot see it), and it ends with either +a <span class="samp">^_</span>, a <span class="samp">^L</span> (“formfeed”), or the end of file.<a rel="footnote" href="#fn-2" name="fnd-2"><sup>2</sup></a> + + <p>The <span class="samp">^_</span> starting a node must be followed by a newline or a +<span class="samp">^L</span> newline, after which comes the node's header line. The +header line must give the node's name (by which Info finds it), and +state the names of the <span class="samp">Next</span>, <span class="samp">Previous</span>, and <span class="samp">Up</span> +nodes (if there are any). As you can see, this node's <span class="samp">Up</span> node +is the node <span class="samp">Expert Info</span>. The <span class="samp">Next</span> node is <span class="samp">Menus</span>. + + <p><a name="index-node-header-line-format-68"></a><a name="index-format-of-node-headers-69"></a> The keywords <dfn>Node</dfn>, <dfn>Next</dfn>, <dfn>Previous</dfn>, and <dfn>Up</dfn> +may appear in any order, anywhere in the header line, but the +recommended order is the one in this sentence. Each keyword must be +followed by a colon, spaces and tabs, and then the appropriate name. +The name may be terminated with a tab, a comma, or a newline. A space +does not end it; node names may contain spaces. The case of letters +in the names is insignificant. + + <p><a name="index-node-name-format-70"></a><a name="index-Directory-node-71"></a> A node name has two forms. A node in the current file is named by +what appears after the <span class="samp">Node: </span> in that node's first line. For +example, this node's name is <span class="samp">Add</span>. A node in another file is +named by <span class="samp">(</span><var>filename</var><span class="samp">)</span><var>node-within-file</var>, as in +<span class="samp">(info)Add</span> for this node. If the file name starts with “./”, +then it is relative to the current directory; otherwise, it is +relative starting from the standard directory for Info files of your +site. The name <span class="samp">(</span><var>filename</var><span class="samp">)Top</span> can be abbreviated to just +<span class="samp">(</span><var>filename</var><span class="samp">)</span>. By convention, the name <span class="samp">Top</span> is used +for the “highest” node in any single file—the node whose <span class="samp">Up</span> +points out of the file. The <span class="samp">Directory</span> node is <span class="file">(dir)</span>, it +points to a file <span class="file">dir</span> which holds a large menu listing all the +Info documents installed on your site. The <span class="samp">Top</span> node of a +document file listed in the <span class="samp">Directory</span> should have an <span class="samp">Up: +(dir)</span> in it. + + <p><a name="index-unstructured-documents-72"></a> The node name <kbd>*</kbd> is special: it refers to the entire file. +Thus, <kbd>g*</kbd> shows you the whole current file. The use of the +node <kbd>*</kbd> is to make it possible to make old-fashioned, +unstructured files into nodes of the tree. + + <p>The <span class="samp">Node:</span> name, in which a node states its own name, must not +contain a file name, since when Info searches for a node, it does not +expect a file name to be there. The <span class="samp">Next</span>, <span class="samp">Previous</span> and +<span class="samp">Up</span> names may contain them. In this node, since the <span class="samp">Up</span> +node is in the same file, it was not necessary to use one. + + <p>Note that the nodes in this file have a file name in the header +line. The file names are ignored by Info, but they serve as comments +to help identify the node for the user. + +<div class="node"> +<p><hr> +<a name="Menus"></a>Next: <a rel="next" accesskey="n" href="#Cross_002drefs">Cross-refs</a>, +Previous: <a rel="previous" accesskey="p" href="#Add">Add</a>, +Up: <a rel="up" accesskey="u" href="#Expert-Info">Expert Info</a> +<br> +</div> + +<!-- node-name, next, previous, up --> +<h3 class="section">2.4 How to Create Menus</h3> + +<p>Any node in the Info hierarchy may have a <dfn>menu</dfn>—a list of subnodes. +The <kbd>m</kbd> command searches the current node's menu for the topic which it +reads from the terminal. + + <p><a name="index-menu-and-menu-entry-format-73"></a> A menu begins with a line starting with <span class="samp">* Menu:</span><!-- /@w -->. The +rest of the line is a comment. After the starting line, every line +that begins with a <span class="samp">* </span> lists a single topic. The name of the +topic–what the user must type at the <kbd>m</kbd>'s command prompt to +select this topic—comes right after the star and space, and is +followed by a colon, spaces and tabs, and the name of the node which +discusses that topic. The node name, like node names following +<span class="samp">Next</span>, <span class="samp">Previous</span> and <span class="samp">Up</span>, may be terminated with a +tab, comma, or newline; it may also be terminated with a period. + + <p>If the node name and topic name are the same, then rather than +giving the name twice, the abbreviation <span class="samp">* </span><var>name</var><span class="samp">::</span> may be +used (and should be used, whenever possible, as it reduces the visual +clutter in the menu). + + <p>It is considerate to choose the topic names so that they differ +from each other very near the beginning—this allows the user to type +short abbreviations. In a long menu, it is a good idea to capitalize +the beginning of each item name which is the minimum acceptable +abbreviation for it (a long menu is more than 5 or so entries). + + <p>The nodes listed in a node's menu are called its “subnodes”, and it +is their “superior”. They should each have an <span class="samp">Up:</span> pointing at +the superior. It is often useful to arrange all or most of the subnodes +in a sequence of <span class="samp">Next</span> and <span class="samp">Previous</span> pointers so that +someone who wants to see them all need not keep revisiting the Menu. + + <p>The Info Directory is simply the menu of the node <span class="samp">(dir)Top</span>—that +is, node <span class="samp">Top</span> in file <span class="file">.../info/dir</span>. You can put new entries +in that menu just like any other menu. The Info Directory is <em>not</em> the +same as the file directory called <span class="file">info</span>. It happens that many of +Info's files live in that file directory, but they do not have to; and +files in that directory are not automatically listed in the Info +Directory node. + + <p>Also, although the Info node graph is claimed to be a “hierarchy”, +in fact it can be <em>any</em> directed graph. Shared structures and +pointer cycles are perfectly possible, and can be used if they are +appropriate to the meaning to be expressed. There is no need for all +the nodes in a file to form a connected structure. In fact, this file +has two connected components. You are in one of them, which is under +the node <span class="samp">Top</span>; the other contains the node <span class="samp">Help</span> which the +<kbd>h</kbd> command goes to. In fact, since there is no garbage +collector, nothing terrible happens if a substructure is not pointed +to, but such a substructure is rather useless since nobody can +ever find out that it exists. + +<div class="node"> +<p><hr> +<a name="Cross_002drefs"></a>Next: <a rel="next" accesskey="n" href="#Tags">Tags</a>, +Previous: <a rel="previous" accesskey="p" href="#Menus">Menus</a>, +Up: <a rel="up" accesskey="u" href="#Expert-Info">Expert Info</a> +<br> +</div> + +<!-- node-name, next, previous, up --> +<h3 class="section">2.5 Creating Cross References</h3> + +<p><a name="index-cross-reference-format-74"></a> A cross reference can be placed anywhere in the text, unlike a menu +item which must go at the front of a line. A cross reference looks +like a menu item except that it has <span class="samp">*note</span> instead of <span class="samp">*</span>. +It <em>cannot</em> be terminated by a <span class="samp">)</span>, because <span class="samp">)</span>'s are +so often part of node names. If you wish to enclose a cross reference +in parentheses, terminate it with a period first. Here are two +examples of cross references pointers: + +<pre class="example"> *Note details: commands. (See *note 3: Full Proof.) +</pre> + <p class="noindent"><em>These are just examples.</em> The places they “lead to” do not +really exist! + +<ul class="menu"> +<li><a accesskey="1" href="#Help_002dCross">Help-Cross</a>: Target of a cross-reference. +</ul> + +<div class="node"> +<p><hr> +<a name="Help_002dCross"></a>Up: <a rel="up" accesskey="u" href="#Cross_002drefs">Cross-refs</a> +<br> +</div> + +<h4 class="subsection">2.5.1 The node reached by the cross reference in Info</h4> + +<p>This is the node reached by the cross reference named <span class="samp">Cross</span>. + + <p>While this node is specifically intended to be reached by a cross +reference, most cross references lead to nodes that “belong” +someplace else far away in the structure of an Info document. So you +cannot expect this node to have a <span class="samp">Next</span>, <span class="samp">Previous</span> or +<span class="samp">Up</span> links pointing back to where you came from. In general, the +<kbd>l</kbd> (el) command is the only way to get back there. + +<pre class="format">>> Type <kbd>l</kbd> to return to the node where the cross reference was. +</pre> + <div class="node"> +<p><hr> +<a name="Help_002dQ"></a>Previous: <a rel="previous" accesskey="p" href="#Help_002dInt">Help-Int</a>, +Up: <a rel="up" accesskey="u" href="#Getting-Started">Getting Started</a> +<br> +</div> + +<!-- node-name, next, previous, up --> +<h3 class="section">2.6 Quitting Info</h3> + +<p><a name="index-q-_0040r_007b_0028Info-mode_0029_007d-75"></a><a name="index-Info_002dexit-76"></a><a name="index-quitting-Info-mode-77"></a> To get out of Info, back to what you were doing before, type <kbd>q</kbd> +for <dfn>Quit</dfn>. This runs <code>Info-exit</code> in Emacs. + + <p>This is the end of the basic course on using Info. You have learned +how to move in an Info document, and how to follow menus and cross +references. This makes you ready for reading manuals top to bottom, +as new users should do when they learn a new package. + + <p>Another set of Info commands is useful when you need to find +something quickly in a manual—that is, when you need to use a manual +as a reference rather than as a tutorial. We urge you to learn +these search commands as well. If you want to do that now, follow this +cross reference to <a href="#Info-Search">Info Search</a>. + + <p>Yet another set of commands are meant for experienced users; you can +find them by looking in the Directory node for documentation on Info. +Finding them will be a good exercise in using Info in the usual +manner. + +<pre class="format">>> Type <kbd>d</kbd> to go to the Info directory node; then type + <kbd>mInfo</kbd> and Return, to get to the node about Info and + see what other help is available. +</pre> + <div class="node"> +<p><hr> +<a name="Tags"></a>Next: <a rel="next" accesskey="n" href="#Checking">Checking</a>, +Previous: <a rel="previous" accesskey="p" href="#Cross_002drefs">Cross-refs</a>, +Up: <a rel="up" accesskey="u" href="#Expert-Info">Expert Info</a> +<br> +</div> + +<!-- node-name, next, previous, up --> +<h3 class="section">2.7 Tags Tables for Info Files</h3> + +<p><a name="index-tags-tables-in-info-files-78"></a> You can speed up the access to nodes of a large Info file by giving +it a tags table. Unlike the tags table for a program, the tags table for +an Info file lives inside the file itself and is used +automatically whenever Info reads in the file. + + <p><a name="index-Info_002dtagify-79"></a> To make a tags table, go to a node in the file using Emacs Info mode and type +<kbd>M-x Info-tagify</kbd>. Then you must use <kbd>C-x C-s</kbd> to save the +file. Info files produced by the <code>makeinfo</code> command that is part +of the Texinfo package always have tags tables to begin with. + + <p><a name="index-stale-tags-tables-80"></a><a name="index-update-Info-tags-table-81"></a> Once the Info file has a tags table, you must make certain it is up +to date. If you edit an Info file directly (as opposed to editing its +Texinfo source), and, as a result of deletion of text, any node moves back +more than a thousand characters in the file from the position +recorded in the tags table, Info will no longer be able to find that +node. To update the tags table, use the <code>Info-tagify</code> command +again. + + <p>An Info file tags table appears at the end of the file and looks like +this: + +<pre class="example"> ^_^L + Tag Table: + File: info, Node: Cross-refs^?21419 + File: info, Node: Tags^?22145 + ^_ + End Tag Table +</pre> + <p class="noindent">Note that it contains one line per node, and this line contains +the beginning of the node's header (ending just after the node name), +a <span class="samp">DEL</span> character, and the character position in the file of the +beginning of the node. + +<div class="node"> +<p><hr> +<a name="Checking"></a>Next: <a rel="next" accesskey="n" href="#Emacs-Info-Variables">Emacs Info Variables</a>, +Previous: <a rel="previous" accesskey="p" href="#Tags">Tags</a>, +Up: <a rel="up" accesskey="u" href="#Expert-Info">Expert Info</a> +<br> +</div> + +<h3 class="section">2.8 Checking an Info File</h3> + +<p>When creating an Info file, it is easy to forget the name of a node when +you are making a pointer to it from another node. If you put in the +wrong name for a node, this is not detected until someone tries to go +through the pointer using Info. Verification of the Info file is an +automatic process which checks all pointers to nodes and reports any +pointers which are invalid. Every <span class="samp">Next</span>, <span class="samp">Previous</span>, and +<span class="samp">Up</span> is checked, as is every menu item and every cross reference. In +addition, any <span class="samp">Next</span> which does not have a <span class="samp">Previous</span> pointing +back is reported. Only pointers within the file are checked, because +checking pointers to other files would be terribly slow. But those are +usually few. + + <p><a name="index-Info_002dvalidate-82"></a>To check an Info file, do <kbd>M-x Info-validate</kbd> while looking at any +node of the file with Emacs Info mode. + +<div class="node"> +<p><hr> +<a name="Emacs-Info-Variables"></a>Previous: <a rel="previous" accesskey="p" href="#Checking">Checking</a>, +Up: <a rel="up" accesskey="u" href="#Expert-Info">Expert Info</a> +<br> +</div> + +<h3 class="section">2.9 Emacs Info-mode Variables</h3> + +<p>The following variables may modify the behavior of Info-mode in Emacs; +you may wish to set one or several of these variables interactively, or +in your <span class="file">~/.emacs</span> init file. See <a href="emacs.html#Examining">Examining and Setting Variables (The GNU Emacs Manual)</a>. The stand-alone Info reader program has its own set of +variables, described in <a href="info-stnd.html#Variables">Manipulating Variables (GNU Info)</a>. + + <dl> +<dt><code>Info-directory-list</code><a name="index-Info_002ddirectory_002dlist-83"></a><dd>The list of directories to search for Info files. Each element is a +string (directory name) or <code>nil</code> (try default directory). If not +initialized Info uses the environment variable <span class="env">INFOPATH</span> to +initialize it, or <code>Info-default-directory-list</code> if there is no +<span class="env">INFOPATH</span> variable in the environment. + + <p>If you wish to customize the Info directory search list for both Emacs +info and stand-alone Info, it is best to set the <span class="env">INFOPATH</span> +environment variable, since that applies to both programs. + + <br><dt><code>Info-additional-directory-list</code><a name="index-Info_002dadditional_002ddirectory_002dlist-84"></a><dd>A list of additional directories to search for Info documentation files. +These directories are not searched for merging the <span class="file">dir</span> file. + + <br><dt><code>Info-fontify</code><a name="index-Info_002dfontify-85"></a><dd>When set to a non-<code>nil</code> value, enables highlighting of Info +files. The default is <code>t</code>. You can change how the highlighting +looks by customizing the faces <code>info-node</code>, <code>info-xref</code>, +<code>info-header-xref</code>, <code>info-header-node</code>, <code>info-menu-5</code>, +<code>info-menu-header</code>, and <code>info-title-</code><var>n</var><code>-face</code> (where +<var>n</var> is the level of the section, a number between 1 and 4). To +customize a face, type <kbd>M-x customize-face <RET> </kbd><var>face</var><kbd> +<RET></kbd>, where <var>face</var> is one of the face names listed here. + + <br><dt><code>Info-use-header-line</code><a name="index-Info_002duse_002dheader_002dline-86"></a><dd>If non-<code>nil</code>, Emacs puts in the Info buffer a header line showing +the <span class="samp">Next</span>, <span class="samp">Prev</span>, and <span class="samp">Up</span> links. A header line does +not scroll with the rest of the buffer, making these links always +visible. + + <br><dt><code>Info-hide-note-references</code><a name="index-Info_002dhide_002dnote_002dreferences-87"></a><dd>As explained in earlier nodes, the Emacs version of Info normally +hides some text in menus and cross-references. You can completely +disable this feature, by setting this option to <code>nil</code>. Setting +it to a value that is neither <code>nil</code> nor <code>t</code> produces an +intermediate behavior, hiding a limited amount of text, but showing +all text that could potentially be useful. + + <br><dt><code>Info-scroll-prefer-subnodes</code><a name="index-Info_002dscroll_002dprefer_002dsubnodes-88"></a><dd>If set to a non-<code>nil</code> value, <SPC> and <BACKSPACE> (or +<DEL>) keys in a menu visit subnodes of the current node before +scrolling to its end or beginning, respectively. For example, if the +node's menu appears on the screen, the next <SPC> moves to a +subnode indicated by the following menu item. Setting this option to +<code>nil</code> results in behavior similar to the stand-alone Info reader +program, which visits the first subnode from the menu only when you +hit the end of the current node. The default is <code>nil</code>. + + <br><dt><code>Info-enable-active-nodes</code><a name="index-Info_002denable_002dactive_002dnodes-89"></a><dd>When set to a non-<code>nil</code> value, allows Info to execute Lisp code +associated with nodes. The Lisp code is executed when the node is +selected. The Lisp code to be executed should follow the node +delimiter (the <span class="samp">DEL</span> character) and an <span class="samp">execute: </span> tag, like +this: + + <pre class="example"> ^_execute: (message "This is an active node!") + </pre> + <br><dt><code>Info-enable-edit</code><a name="index-Info_002denable_002dedit-90"></a><dd>Set to <code>nil</code>, disables the <span class="samp">e</span> (<code>Info-edit</code>) command. A +non-<code>nil</code> value enables it. See <a href="#Add">Edit</a>. +</dl> + +<div class="node"> +<p><hr> +<a name="Creating-an-Info-File"></a>Next: <a rel="next" accesskey="n" href="#Index">Index</a>, +Previous: <a rel="previous" accesskey="p" href="#Expert-Info">Expert Info</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> +<br> +</div> + +<h2 class="chapter">3 Creating an Info File from a Texinfo File</h2> + +<p><code>makeinfo</code> is a utility that converts a Texinfo file into an Info +file; <code>texinfo-format-region</code> and <code>texinfo-format-buffer</code> are +GNU Emacs functions that do the same. + + <p>See <a href="texinfo.html#Top">Overview of Texinfo (Texinfo: The GNU Documentation Format)</a>, to learn how to write a Texinfo file. + + <p>See <a href="texinfo.html#Creating-an-Info-File">Creating an Info File (Texinfo: The GNU Documentation Format)</a>, to learn how to create an Info file from a Texinfo file. + + <p>See <a href="texinfo.html#Installing-an-Info-File">Installing an Info File (Texinfo: The GNU Documentation Format)</a>, to learn how to install an Info file after you +have created one. + +<div class="node"> +<p><hr> +<a name="Index"></a>Previous: <a rel="previous" accesskey="p" href="#Creating-an-Info-File">Creating an Info File</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> +<br> +</div> + +<h2 class="unnumbered">Index</h2> + +<p>This is an alphabetical listing of all the commands, variables, and +topics discussed in this document. + +<ul class="index-cp" compact> +<li><a href="#index-1-_0040r_007bthrough_007d-9-_0040r_007b_0028Info-mode_0029_007d-50"><code>1 </code><span class="roman">through</span><code> 9 </code><span class="roman">(Info mode)</span></a>: <a href="#Advanced">Advanced</a></li> +<li><a href="#index-_003f-_0040r_007b_0028Info-mode_0029_007d-19"><code>? </code><span class="roman">(Info mode)</span></a>: <a href="#Help_002d_005eL">Help-^L</a></li> +<li><a href="#index-abbreviating-Info-subnodes-27">abbreviating Info subnodes</a>: <a href="#Help_002dM">Help-M</a></li> +<li><a href="#index-b-_0040r_007b_0028Info-mode_0029_007d-18"><code>b </code><span class="roman">(Info mode)</span></a>: <a href="#Help_002d_005eL">Help-^L</a></li> +<li><a href="#index-BACKSPACE-_0040r_007b_0028Info-mode_0029_007d-10"><code>BACKSPACE </code><span class="roman">(Info mode)</span></a>: <a href="#Help_002d_005eL">Help-^L</a></li> +<li><a href="#index-C_002dl-_0040r_007b_0028Info-mode_0029_007d-17"><code>C-l </code><span class="roman">(Info mode)</span></a>: <a href="#Help_002d_005eL">Help-^L</a></li> +<li><a href="#index-clone_002dbuffer-57"><code>clone-buffer</code></a>: <a href="#Advanced">Advanced</a></li> +<li><a href="#index-completion-of-Info-node-names-28">completion of Info node names</a>: <a href="#Help_002dM">Help-M</a></li> +<li><a href="#index-cross-reference-format-74">cross reference format</a>: <a href="#Cross_002drefs">Cross-refs</a></li> +<li><a href="#index-cross-references-in-Info-documents-34">cross references in Info documents</a>: <a href="#Help_002dXref">Help-Xref</a></li> +<li><a href="#index-d-_0040r_007b_0028Info-mode_0029_007d-40"><code>d </code><span class="roman">(Info mode)</span></a>: <a href="#Help_002dInt">Help-Int</a></li> +<li><a href="#index-DEL-_0040r_007b_0028Info-mode_0029_007d-9"><code>DEL </code><span class="roman">(Info mode)</span></a>: <a href="#Help_002d_005eL">Help-^L</a></li> +<li><a href="#index-Directory-node-71">Directory node</a>: <a href="#Add">Add</a></li> +<li><a href="#index-e-_0040r_007b_0028Info-mode_0029_007d-53"><code>e </code><span class="roman">(Info mode)</span></a>: <a href="#Advanced">Advanced</a></li> +<li><a href="#index-edit-Info-document-55">edit Info document</a>: <a href="#Advanced">Advanced</a></li> +<li><a href="#index-entering-Info-2">entering Info</a>: <a href="#Getting-Started">Getting Started</a></li> +<li><a href="#index-f-_0040r_007b_0028Info-mode_0029_007d-35"><code>f </code><span class="roman">(Info mode)</span></a>: <a href="#Help_002dXref">Help-Xref</a></li> +<li><a href="#index-format-of-node-headers-69">format of node headers</a>: <a href="#Add">Add</a></li> +<li><a href="#index-g-_0040r_007b_0028Info-mode_0029_007d-46"><code>g </code><span class="roman">(Info mode)</span></a>: <a href="#Advanced">Advanced</a></li> +<li><a href="#index-go-to-a-node-by-name-48">go to a node by name</a>: <a href="#Advanced">Advanced</a></li> +<li><a href="#index-go-to-another-Info-file-49">go to another Info file</a>: <a href="#Advanced">Advanced</a></li> +<li><a href="#index-go-to-Directory-node-42">go to Directory node</a>: <a href="#Help_002dInt">Help-Int</a></li> +<li><a href="#index-go-to-Top-node-45">go to Top node</a>: <a href="#Help_002dInt">Help-Int</a></li> +<li><a href="#index-going-back-in-Info-mode-39">going back in Info mode</a>: <a href="#Help_002dInt">Help-Int</a></li> +<li><a href="#index-header-of-Info-node-5">header of Info node</a>: <a href="#Help">Help</a></li> +<li><a href="#index-i-_0040r_007b_0028Info-mode_0029_007d-61"><code>i </code><span class="roman">(Info mode)</span></a>: <a href="#Info-Search">Info Search</a></li> +<li><a href="#index-Info-document-as-a-reference-60">Info document as a reference</a>: <a href="#Info-Search">Info Search</a></li> +<li><a href="#index-Info-documents-as-tutorials-14">Info documents as tutorials</a>: <a href="#Help_002d_005eL">Help-^L</a></li> +<li><a href="#index-Info-menus-24">Info menus</a>: <a href="#Help_002dM">Help-M</a></li> +<li><a href="#index-Info-reader_002c-how-to-invoke-1">Info reader, how to invoke</a>: <a href="#Getting-Started">Getting Started</a></li> +<li><a href="#index-Info_002dadditional_002ddirectory_002dlist-84"><code>Info-additional-directory-list</code></a>: <a href="#Emacs-Info-Variables">Emacs Info Variables</a></li> +<li><a href="#index-info_002dapropos-63"><code>info-apropos</code></a>: <a href="#Info-Search">Info Search</a></li> +<li><a href="#index-Info_002ddirectory-41"><code>Info-directory</code></a>: <a href="#Help_002dInt">Help-Int</a></li> +<li><a href="#index-Info_002ddirectory_002dlist-83"><code>Info-directory-list</code></a>: <a href="#Emacs-Info-Variables">Emacs Info Variables</a></li> +<li><a href="#index-Info_002dedit-54"><code>Info-edit</code></a>: <a href="#Advanced">Advanced</a></li> +<li><a href="#index-Info_002denable_002dactive_002dnodes-89"><code>Info-enable-active-nodes</code></a>: <a href="#Emacs-Info-Variables">Emacs Info Variables</a></li> +<li><a href="#index-Info_002denable_002dedit-90"><code>Info-enable-edit</code></a>: <a href="#Emacs-Info-Variables">Emacs Info Variables</a></li> +<li><a href="#index-Info_002dexit-76"><code>Info-exit</code></a>: <a href="#Help_002dQ">Help-Q</a></li> +<li><a href="#index-Info_002dfollow_002dreference-36"><code>Info-follow-reference</code></a>: <a href="#Help_002dXref">Help-Xref</a></li> +<li><a href="#index-Info_002dfontify-85"><code>Info-fontify</code></a>: <a href="#Emacs-Info-Variables">Emacs Info Variables</a></li> +<li><a href="#index-Info_002dgoto_002dnode-47"><code>Info-goto-node</code></a>: <a href="#Advanced">Advanced</a></li> +<li><a href="#index-Info_002dhide_002dnote_002dreferences-87"><code>Info-hide-note-references</code></a>: <a href="#Emacs-Info-Variables">Emacs Info Variables</a></li> +<li><a href="#index-Info_002dindex-62"><code>Info-index</code></a>: <a href="#Info-Search">Info Search</a></li> +<li><a href="#index-Info_002dlast-38"><code>Info-last</code></a>: <a href="#Help_002dInt">Help-Int</a></li> +<li><a href="#index-Info_002dmenu-26"><code>Info-menu</code></a>: <a href="#Help_002dM">Help-M</a></li> +<li><a href="#index-Info_002dmouse_002dfollow_002dnearest_002dnode-31"><code>Info-mouse-follow-nearest-node</code></a>: <a href="#Help_002dM">Help-M</a></li> +<li><a href="#index-Info_002dnth_002dmenu_002ditem-51"><code>Info-nth-menu-item</code></a>: <a href="#Advanced">Advanced</a></li> +<li><a href="#index-Info_002dscroll_002ddown-12"><code>Info-scroll-down</code></a>: <a href="#Help_002d_005eL">Help-^L</a></li> +<li><a href="#index-Info_002dscroll_002dprefer_002dsubnodes-88"><code>Info-scroll-prefer-subnodes</code></a>: <a href="#Emacs-Info-Variables">Emacs Info Variables</a></li> +<li><a href="#index-Info_002dscroll_002dup-11"><code>Info-scroll-up</code></a>: <a href="#Help_002d_005eL">Help-^L</a></li> +<li><a href="#index-Info_002dsearch-65"><code>Info-search</code></a>: <a href="#Info-Search">Info Search</a></li> +<li><a href="#index-Info_002dsummary-20"><code>Info-summary</code></a>: <a href="#Help_002d_005eL">Help-^L</a></li> +<li><a href="#index-Info_002dtagify-79"><code>Info-tagify</code></a>: <a href="#Tags">Tags</a></li> +<li><a href="#index-Info_002dtop_002dnode-44"><code>Info-top-node</code></a>: <a href="#Help_002dInt">Help-Int</a></li> +<li><a href="#index-Info_002dup-33"><code>Info-up</code></a>: <a href="#Help_002dFOO">Help-FOO</a></li> +<li><a href="#index-Info_002duse_002dheader_002dline-86"><code>Info-use-header-line</code></a>: <a href="#Emacs-Info-Variables">Emacs Info Variables</a></li> +<li><a href="#index-Info_002dvalidate-82"><code>Info-validate</code></a>: <a href="#Checking">Checking</a></li> +<li><a href="#index-invisible-text-in-Emacs-21">invisible text in Emacs</a>: <a href="#Help_002dInv">Help-Inv</a></li> +<li><a href="#index-l-_0040r_007b_0028Info-mode_0029_007d-37"><code>l </code><span class="roman">(Info mode)</span></a>: <a href="#Help_002dInt">Help-Int</a></li> +<li><a href="#index-m-_0040r_007b_0028Info-mode_0029_007d-25"><code>m </code><span class="roman">(Info mode)</span></a>: <a href="#Help_002dM">Help-M</a></li> +<li><a href="#index-M_002dn-_0040r_007b_0028Info-mode_0029_007d-56"><code>M-n </code><span class="roman">(Info mode)</span></a>: <a href="#Advanced">Advanced</a></li> +<li><a href="#index-M_002ds-_0040r_007b_0028Info-mode_0029_007d-66"><code>M-s </code><span class="roman">(Info mode)</span></a>: <a href="#Info-Search">Info Search</a></li> +<li><a href="#index-menu-and-menu-entry-format-73">menu and menu entry format</a>: <a href="#Menus">Menus</a></li> +<li><a href="#index-menus-in-an-Info-document-23">menus in an Info document</a>: <a href="#Help_002dM">Help-M</a></li> +<li><a href="#index-mouse-support-in-Info-mode-29">mouse support in Info mode</a>: <a href="#Help_002dM">Help-M</a></li> +<li><a href="#index-Mouse_002d2-_0040r_007b_0028Info-mode_0029_007d-30"><code>Mouse-2 </code><span class="roman">(Info mode)</span></a>: <a href="#Help_002dM">Help-M</a></li> +<li><a href="#index-multiple-Info-buffers-58">multiple Info buffers</a>: <a href="#Advanced">Advanced</a></li> +<li><a href="#index-n-_0040r_007b_0028Info-mode_0029_007d-6"><code>n </code><span class="roman">(Info mode)</span></a>: <a href="#Help">Help</a></li> +<li><a href="#index-node-delimiters-67">node delimiters</a>: <a href="#Add">Add</a></li> +<li><a href="#index-node-header-line-format-68">node header line format</a>: <a href="#Add">Add</a></li> +<li><a href="#index-node-name-format-70">node name format</a>: <a href="#Add">Add</a></li> +<li><a href="#index-node_002c-in-Info-documents-4">node, in Info documents</a>: <a href="#Help">Help</a></li> +<li><a href="#index-p-_0040r_007b_0028Info-mode_0029_007d-7"><code>p </code><span class="roman">(Info mode)</span></a>: <a href="#Help_002dP">Help-P</a></li> +<li><a href="#index-PAGEDOWN-_0040r_007b_0028Info-mode_0029_007d-16"><code>PAGEDOWN </code><span class="roman">(Info mode)</span></a>: <a href="#Help_002d_005eL">Help-^L</a></li> +<li><a href="#index-PAGEUP-_0040r_007b_0028Info-mode_0029_007d-15"><code>PAGEUP </code><span class="roman">(Info mode)</span></a>: <a href="#Help_002d_005eL">Help-^L</a></li> +<li><a href="#index-q-_0040r_007b_0028Info-mode_0029_007d-75"><code>q </code><span class="roman">(Info mode)</span></a>: <a href="#Help_002dQ">Help-Q</a></li> +<li><a href="#index-quitting-Info-mode-77">quitting Info mode</a>: <a href="#Help_002dQ">Help-Q</a></li> +<li><a href="#index-reading-Info-documents-top-to-bottom-13">reading Info documents top to bottom</a>: <a href="#Help_002d_005eL">Help-^L</a></li> +<li><a href="#index-s-_0040r_007b_0028Info-mode_0029_007d-64"><code>s </code><span class="roman">(Info mode)</span></a>: <a href="#Info-Search">Info Search</a></li> +<li><a href="#index-searching-Info-documents-59">searching Info documents</a>: <a href="#Info-Search">Info Search</a></li> +<li><a href="#index-select-_0040var_007bn_007d_0027th-menu-item-52">select <var>n</var>'th menu item</a>: <a href="#Advanced">Advanced</a></li> +<li><a href="#index-small-screen_002c-moving-around-3">small screen, moving around</a>: <a href="#Help_002dSmall_002dScreen">Help-Small-Screen</a></li> +<li><a href="#index-SPC-_0040r_007b_0028Info-mode_0029_007d-8"><code>SPC </code><span class="roman">(Info mode)</span></a>: <a href="#Help_002d_005eL">Help-^L</a></li> +<li><a href="#index-stale-tags-tables-80">stale tags tables</a>: <a href="#Tags">Tags</a></li> +<li><a href="#index-t-_0040r_007b_0028Info-mode_0029_007d-43"><code>t </code><span class="roman">(Info mode)</span></a>: <a href="#Help_002dInt">Help-Int</a></li> +<li><a href="#index-tags-tables-in-info-files-78">tags tables in info files</a>: <a href="#Tags">Tags</a></li> +<li><a href="#index-u-_0040r_007b_0028Info-mode_0029_007d-32"><code>u </code><span class="roman">(Info mode)</span></a>: <a href="#Help_002dFOO">Help-FOO</a></li> +<li><a href="#index-unstructured-documents-72">unstructured documents</a>: <a href="#Add">Add</a></li> +<li><a href="#index-update-Info-tags-table-81">update Info tags table</a>: <a href="#Tags">Tags</a></li> +<li><a href="#index-visible_002dmode-22"><code>visible-mode</code></a>: <a href="#Help_002dInv">Help-Inv</a></li> + </ul> <div class="footnote"> +<hr> +<a name="texinfo-footnotes-in-document"></a><h4>Footnotes</h4><p class="footnote"><small>[<a name="fn-1" href="#fnd-1">1</a>]</small> The key which +we call “Backspace or DEL” in this manual is labeled differently on +different keyboards. Look for a key which is a little ways above the +<ENTER> or <RET> key and which you normally use outside Emacs +to erase the character before the cursor, i.e. the character you +typed last. It might be labeled <span class="samp">Backspace</span> or <span class="samp"><-</span> or +<span class="samp">DEL</span>, or sometimes <span class="samp">Delete</span>.</p> + + <p class="footnote"><small>[<a name="fn-2" href="#fnd-2">2</a>]</small> If +you put in a <span class="samp">^L</span> to end a new node, be sure that there is a +<span class="samp">^_</span> after it to start the next one, since <span class="samp">^L</span> cannot +<em>start</em> a node. Also, a nicer way to make a node boundary be a +page boundary as well is to put a <span class="samp">^L</span> <em>right after</em> the +<span class="samp">^_</span>.</p> + + <p><hr></div> + +</body></html> + diff --git a/Master/texmf/doc/texinfo/info.pdf b/Master/texmf/doc/texinfo/info.pdf Binary files differnew file mode 100644 index 00000000000..0676759673c --- /dev/null +++ b/Master/texmf/doc/texinfo/info.pdf diff --git a/Master/texmf/doc/texinfo/texinfo.html b/Master/texmf/doc/texinfo/texinfo.html new file mode 100644 index 00000000000..bd02990f831 --- /dev/null +++ b/Master/texmf/doc/texinfo/texinfo.html @@ -0,0 +1,19883 @@ +<html lang="en"> +<head> +<title>GNU Texinfo 4.7</title> +<meta http-equiv="Content-Type" content="text/html"> +<meta name="description" content="GNU Texinfo 4.7"> +<meta name="generator" content="makeinfo 4.7"> +<link title="Top" rel="top" href="#Top"> +<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> +<!-- +This manual is for GNU Texinfo (version 4.7, 9 April 2004), +a documentation system that can produce both online information and a +printed manual from a single source. + +Copyright (C) 1988, 1990, 1991, 1992, 1993, 1995, 1996, 1997, 1998, +1999, 2000, 2001, 2002, 2003, 2004 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation License, + Version 1.1 or any later version published by the Free Software + Foundation; with no Invariant Sections, with the Front-Cover texts + being "A GNU Manual," and with the Back-Cover Texts as in (a) + below. A copy of the license is included in the section entitled + "GNU Free Documentation License." + + (a) The FSF's Back-Cover Text is: "You have freedom to copy and + modify this GNU Manual, like GNU software. Copies published by + the Free Software Foundation raise funds for GNU development." + --> +<meta http-equiv="Content-Style-Type" content="text/css"> +<style type="text/css"><!-- + pre.display { font-family:inherit } + pre.format { font-family:inherit } + pre.smalldisplay { font-family:inherit; font-size:smaller } + pre.smallformat { font-family:inherit; font-size:smaller } + pre.smallexample { font-size:smaller } + pre.smalllisp { font-size:smaller } + span.sc { font-variant:small-caps } + span.roman { font-family: serif; font-weight: normal; } +--></style> +</head> +<body> +<h1 class="settitle">GNU Texinfo 4.7</h1> + <div class="shortcontents"> +<h2>Short Contents</h2> +<ul> +<li><a href="#toc_Top">Texinfo</a></li> +<li><a href="#toc_Copying-Conditions">Texinfo Copying Conditions</a></li> +<li><a href="#toc_Overview">1 Overview of Texinfo</a></li> +<li><a href="#toc_Texinfo-Mode">2 Using Texinfo Mode</a></li> +<li><a href="#toc_Beginning-a-File">3 Beginning a Texinfo File</a></li> +<li><a href="#toc_Ending-a-File">4 Ending a Texinfo File</a></li> +<li><a href="#toc_Structuring">5 Chapter Structuring</a></li> +<li><a href="#toc_Nodes">6 Nodes</a></li> +<li><a href="#toc_Menus">7 Menus</a></li> +<li><a href="#toc_Cross-References">8 Cross References</a></li> +<li><a href="#toc_Marking-Text">9 Marking Words and Phrases</a></li> +<li><a href="#toc_Quotations-and-Examples">10 Quotations and Examples</a></li> +<li><a href="#toc_Lists-and-Tables">11 Lists and Tables</a></li> +<li><a href="#toc_Special-Displays">12 Special Displays</a></li> +<li><a href="#toc_Indices">13 Indices</a></li> +<li><a href="#toc_Insertions">14 Special Insertions</a></li> +<li><a href="#toc_Breaks">15 Forcing and Preventing Breaks</a></li> +<li><a href="#toc_Definition-Commands">16 Definition Commands</a></li> +<li><a href="#toc_Conditionals">17 Conditionally Visible Text</a></li> +<li><a href="#toc_Internationalization">18 Internationalization</a></li> +<li><a href="#toc_Defining-New-Texinfo-Commands">19 Defining New Texinfo Commands</a></li> +<li><a href="#toc_Hardcopy">20 Formatting and Printing Hardcopy</a></li> +<li><a href="#toc_Creating-and-Installing-Info-Files">21 Creating and Installing Info Files</a></li> +<li><a href="#toc_Generating-HTML">22 Generating HTML</a></li> +<li><a href="#toc_Command-List">Appendix A @-Command List</a></li> +<li><a href="#toc_Tips">Appendix B Tips and Hints</a></li> +<li><a href="#toc_Sample-Texinfo-Files">Appendix C Sample Texinfo Files</a></li> +<li><a href="#toc_Include-Files">Appendix D Include Files</a></li> +<li><a href="#toc_Headings">Appendix E Page Headings</a></li> +<li><a href="#toc_Catching-Mistakes">Appendix F Formatting Mistakes</a></li> +<li><a href="#toc_Copying-This-Manual">Appendix G Copying This Manual</a></li> +<li><a href="#toc_Command-and-Variable-Index">Command and Variable Index</a></li> +<li><a href="#toc_Concept-Index">Concept Index</a></li> +</ul> +</div> + + + + <div class="contents"> +<h2>Table of Contents</h2> +<ul> +<li><a name="toc_Top" href="#Top">Texinfo</a> +<li><a name="toc_Copying-Conditions" href="#Copying-Conditions">Texinfo Copying Conditions</a> +<li><a name="toc_Overview" href="#Overview">1 Overview of Texinfo</a> +<ul> +<li><a href="#Reporting-Bugs">1.1 Reporting Bugs</a> +<li><a href="#Using-Texinfo">1.2 Using Texinfo</a> +<li><a href="#Output-Formats">1.3 Output Formats</a> +<li><a href="#Info-Files">1.4 Info Files</a> +<li><a href="#Printed-Books">1.5 Printed Books</a> +<li><a href="#Formatting-Commands">1.6 @-commands</a> +<li><a href="#Conventions">1.7 General Syntactic Conventions</a> +<li><a href="#Comments">1.8 Comments</a> +<li><a href="#Minimum">1.9 What a Texinfo File Must Have</a> +<li><a href="#Six-Parts">1.10 Six Parts of a Texinfo File</a> +<li><a href="#Short-Sample">1.11 A Short Sample Texinfo File</a> +<li><a href="#History">1.12 History</a> +</li></ul> +<li><a name="toc_Texinfo-Mode" href="#Texinfo-Mode">2 Using Texinfo Mode</a> +<ul> +<li><a href="#Texinfo-Mode-Overview">2.1 Texinfo Mode Overview</a> +<li><a href="#Emacs-Editing">2.2 The Usual GNU Emacs Editing Commands</a> +<li><a href="#Inserting">2.3 Inserting Frequently Used Commands</a> +<li><a href="#Showing-the-Structure">2.4 Showing the Section Structure of a File</a> +<li><a href="#Updating-Nodes-and-Menus">2.5 Updating Nodes and Menus</a> +<ul> +<li><a href="#Updating-Commands">2.5.1 The Updating Commands</a> +<li><a href="#Updating-Requirements">2.5.2 Updating Requirements</a> +<li><a href="#Other-Updating-Commands">2.5.3 Other Updating Commands</a> +</li></ul> +<li><a href="#Info-Formatting">2.6 Formatting for Info</a> +<li><a href="#Printing">2.7 Printing</a> +<li><a href="#Texinfo-Mode-Summary">2.8 Texinfo Mode Summary</a> +</li></ul> +<li><a name="toc_Beginning-a-File" href="#Beginning-a-File">3 Beginning a Texinfo File</a> +<ul> +<li><a href="#Sample-Beginning">3.1 Sample Texinfo File Beginning</a> +<li><a href="#Texinfo-File-Header">3.2 Texinfo File Header</a> +<ul> +<li><a href="#First-Line">3.2.1 The First Line of a Texinfo File</a> +<li><a href="#Start-of-Header">3.2.2 Start of Header</a> +<li><a href="#setfilename">3.2.3 <code>@setfilename</code>: Set the output file name</a> +<li><a href="#settitle">3.2.4 <code>@settitle</code>: Set the document title</a> +<li><a href="#End-of-Header">3.2.5 End of Header</a> +</li></ul> +<li><a href="#Document-Permissions">3.3 Document Permissions</a> +<ul> +<li><a href="#copying">3.3.1 <code>@copying</code>: Declare Copying Permissions</a> +<li><a href="#insertcopying">3.3.2 <code>@insertcopying</code>: Include Permissions Text</a> +</li></ul> +<li><a href="#Titlepage-_0026-Copyright-Page">3.4 Title and Copyright Pages</a> +<ul> +<li><a href="#titlepage">3.4.1 <code>@titlepage</code></a> +<li><a href="#titlefont-center-sp">3.4.2 <code>@titlefont</code>, <code>@center</code>, and <code>@sp</code></a> +<li><a href="#title-subtitle-author">3.4.3 <code>@title</code>, <code>@subtitle</code>, and <code>@author</code></a> +<li><a href="#Copyright">3.4.4 Copyright Page</a> +<li><a href="#end-titlepage">3.4.5 Heading Generation</a> +<li><a href="#headings-on-off">3.4.6 The <code>@headings</code> Command</a> +</li></ul> +<li><a href="#Contents">3.5 Generating a Table of Contents</a> +<li><a href="#The-Top-Node">3.6 The `Top' Node and Master Menu</a> +<ul> +<li><a href="#Top-Node-Example">3.6.1 Top Node Example</a> +<li><a href="#Master-Menu-Parts">3.6.2 Parts of a Master Menu</a> +</li></ul> +<li><a href="#Global-Document-Commands">3.7 Global Document Commands</a> +<ul> +<li><a href="#documentdescription">3.7.1 <code>@documentdescription</code>: Summary Text</a> +<li><a href="#setchapternewpage">3.7.2 <code>@setchapternewpage</code>:</a> +<li><a href="#paragraphindent">3.7.3 <code>@paragraphindent</code>: Paragraph Indenting</a> +<li><a href="#firstparagraphindent">3.7.4 <code>@firstparagraphindent</code>: Indenting After Headings</a> +<li><a href="#exampleindent">3.7.5 <code>@exampleindent</code>: Environment Indenting</a> +</li></ul> +<li><a href="#Software-Copying-Permissions">3.8 Software Copying Permissions</a> +</li></ul> +<li><a name="toc_Ending-a-File" href="#Ending-a-File">4 Ending a Texinfo File</a> +<ul> +<li><a href="#Printing-Indices-_0026-Menus">4.1 Printing Indices and Menus</a> +<li><a href="#File-End">4.2 <code>@bye</code> File Ending</a> +</li></ul> +<li><a name="toc_Structuring" href="#Structuring">5 Chapter Structuring</a> +<ul> +<li><a href="#Tree-Structuring">5.1 Tree Structure of Sections</a> +<li><a href="#Structuring-Command-Types">5.2 Structuring Command Types</a> +<li><a href="#makeinfo-top">5.3 <code>@top</code></a> +<li><a href="#chapter">5.4 <code>@chapter</code></a> +<li><a href="#unnumbered-_0026-appendix">5.5 <code>@unnumbered</code> and <code>@appendix</code></a> +<li><a href="#majorheading-_0026-chapheading">5.6 <code>@majorheading</code>, <code>@chapheading</code></a> +<li><a href="#section">5.7 <code>@section</code></a> +<li><a href="#unnumberedsec-appendixsec-heading">5.8 <code>@unnumberedsec</code>, <code>@appendixsec</code>, <code>@heading</code></a> +<li><a href="#subsection">5.9 The <code>@subsection</code> Command</a> +<li><a href="#unnumberedsubsec-appendixsubsec-subheading">5.10 The <code>@subsection</code>-like Commands</a> +<li><a href="#subsubsection">5.11 The `subsub' Commands</a> +<li><a href="#Raise_002flower-sections">5.12 <code>@raisesections</code> and <code>@lowersections</code></a> +</li></ul> +<li><a name="toc_Nodes" href="#Nodes">6 Nodes</a> +<ul> +<li><a href="#Two-Paths">6.1 Two Paths</a> +<li><a href="#Node-Menu-Illustration">6.2 Node and Menu Illustration</a> +<li><a href="#node">6.3 The <code>@node</code> Command</a> +<ul> +<li><a href="#Node-Names">6.3.1 Choosing Node and Pointer Names</a> +<li><a href="#Writing-a-Node">6.3.2 How to Write an <code>@node</code> Line</a> +<li><a href="#Node-Line-Tips">6.3.3 <code>@node</code> Line Tips</a> +<li><a href="#Node-Line-Requirements">6.3.4 <code>@node</code> Line Requirements</a> +<li><a href="#First-Node">6.3.5 The First Node</a> +<li><a href="#makeinfo-top-command">6.3.6 The <code>@top</code> Sectioning Command</a> +</li></ul> +<li><a href="#makeinfo-Pointer-Creation">6.4 Creating Pointers with <code>makeinfo</code></a> +<li><a href="#anchor">6.5 <code>@anchor</code>: Defining Arbitrary Cross-reference Targets</a> +</li></ul> +<li><a name="toc_Menus" href="#Menus">7 Menus</a> +<ul> +<li><a href="#Menu-Location">7.1 Menu Location</a> +<li><a href="#Writing-a-Menu">7.2 Writing a Menu</a> +<li><a href="#Menu-Parts">7.3 The Parts of a Menu</a> +<li><a href="#Less-Cluttered-Menu-Entry">7.4 Less Cluttered Menu Entry</a> +<li><a href="#Menu-Example">7.5 A Menu Example</a> +<li><a href="#Other-Info-Files">7.6 Referring to Other Info Files</a> +</li></ul> +<li><a name="toc_Cross-References" href="#Cross-References">8 Cross References</a> +<ul> +<li><a href="#References">8.1 What References Are For</a> +<li><a href="#Cross-Reference-Commands">8.2 Different Cross Reference Commands</a> +<li><a href="#Cross-Reference-Parts">8.3 Parts of a Cross Reference</a> +<li><a href="#xref">8.4 <code>@xref</code></a> +<ul> +<li><a href="#Reference-Syntax">8.4.1 What a Reference Looks Like and Requires</a> +<li><a href="#One-Argument">8.4.2 <code>@xref</code> with One Argument</a> +<li><a href="#Two-Arguments">8.4.3 <code>@xref</code> with Two Arguments</a> +<li><a href="#Three-Arguments">8.4.4 <code>@xref</code> with Three Arguments</a> +<li><a href="#Four-and-Five-Arguments">8.4.5 <code>@xref</code> with Four and Five Arguments</a> +</li></ul> +<li><a href="#Top-Node-Naming">8.5 Naming a `Top' Node</a> +<li><a href="#ref">8.6 <code>@ref</code></a> +<li><a href="#pxref">8.7 <code>@pxref</code></a> +<li><a href="#inforef">8.8 <code>@inforef</code></a> +<li><a href="#uref">8.9 <code>@url</code>, <code>@uref{</code><var>url</var><code>[, </code><var>text</var><code>][, </code><var>replacement</var><code>]}</code></a> +</li></ul> +<li><a name="toc_Marking-Text" href="#Marking-Text">9 Marking Words and Phrases</a> +<ul> +<li><a href="#Indicating">9.1 Indicating Definitions, Commands, etc.</a> +<ul> +<li><a href="#Useful-Highlighting">9.1.1 Highlighting Commands are Useful</a> +<li><a href="#code">9.1.2 <code>@code</code>{<var>sample-code</var>}</a> +<li><a href="#kbd">9.1.3 <code>@kbd</code>{<var>keyboard-characters</var>}</a> +<li><a href="#key">9.1.4 <code>@key</code>{<var>key-name</var>}</a> +<li><a href="#samp">9.1.5 <code>@samp</code>{<var>text</var>}</a> +<li><a href="#verb">9.1.6 <code>@verb</code>{<char><var>text</var><char>}</a> +<li><a href="#var">9.1.7 <code>@var</code>{<var>metasyntactic-variable</var>}</a> +<li><a href="#env">9.1.8 <code>@env</code>{<var>environment-variable</var>}</a> +<li><a href="#file">9.1.9 <code>@file</code>{<var>file-name</var>}</a> +<li><a href="#command">9.1.10 <code>@command</code>{<var>command-name</var>}</a> +<li><a href="#option">9.1.11 <code>@option</code>{<var>option-name</var>}</a> +<li><a href="#dfn">9.1.12 <code>@dfn</code>{<var>term</var>}</a> +<li><a href="#cite">9.1.13 <code>@cite</code>{<var>reference</var>}</a> +<li><a href="#acronym">9.1.14 <code>@acronym</code>{<var>acronym</var>[, <var>meaning</var>]}</a> +<li><a href="#indicateurl">9.1.15 <code>@indicateurl</code>{<var>uniform-resource-locator</var>}</a> +<li><a href="#email">9.1.16 <code>@email</code>{<var>email-address</var>[, <var>displayed-text</var>]}</a> +</li></ul> +<li><a href="#Emphasis">9.2 Emphasizing Text</a> +<ul> +<li><a href="#emph-_0026-strong">9.2.1 <code>@emph</code>{<var>text</var>} and <code>@strong</code>{<var>text</var>}</a> +<li><a href="#Smallcaps">9.2.2 <code>@sc</code>{<var>text</var>}: The Small Caps Font</a> +<li><a href="#Fonts">9.2.3 Fonts for Printing, Not Info</a> +</li></ul> +</li></ul> +<li><a name="toc_Quotations-and-Examples" href="#Quotations-and-Examples">10 Quotations and Examples</a> +<ul> +<li><a href="#Block-Enclosing-Commands">10.1 Block Enclosing Commands</a> +<li><a href="#quotation">10.2 <code>@quotation</code>: Block quotations</a> +<li><a href="#example">10.3 <code>@example</code>: Example Text</a> +<li><a href="#verbatim">10.4 <code>@verbatim</code>: Literal Text</a> +<li><a href="#verbatiminclude">10.5 <code>@verbatiminclude</code> <var>file</var>: Include a File Verbatim</a> +<li><a href="#lisp">10.6 <code>@lisp</code>: Marking a Lisp Example</a> +<li><a href="#small">10.7 <code>@small...</code> Block Commands</a> +<li><a href="#display">10.8 <code>@display</code> and <code>@smalldisplay</code></a> +<li><a href="#format">10.9 <code>@format</code> and <code>@smallformat</code></a> +<li><a href="#exdent">10.10 <code>@exdent</code>: Undoing a Line's Indentation</a> +<li><a href="#flushleft-_0026-flushright">10.11 <code>@flushleft</code> and <code>@flushright</code></a> +<li><a href="#noindent">10.12 <code>@noindent</code>: Omitting Indentation</a> +<li><a href="#indent">10.13 <code>@indent</code>: Forcing Indentation</a> +<li><a href="#cartouche">10.14 <code>@cartouche</code>: Rounded Rectangles Around Examples</a> +</li></ul> +<li><a name="toc_Lists-and-Tables" href="#Lists-and-Tables">11 Lists and Tables</a> +<ul> +<li><a href="#Introducing-Lists">11.1 Introducing Lists</a> +<li><a href="#itemize">11.2 <code>@itemize</code>: Making an Itemized List</a> +<li><a href="#enumerate">11.3 <code>@enumerate</code>: Making a Numbered or Lettered List</a> +<li><a href="#Two_002dcolumn-Tables">11.4 Making a Two-column Table</a> +<ul> +<li><a href="#table">11.4.1 Using the <code>@table</code> Command</a> +<li><a href="#ftable-vtable">11.4.2 <code>@ftable</code> and <code>@vtable</code></a> +<li><a href="#itemx">11.4.3 <code>@itemx</code></a> +</li></ul> +<li><a href="#Multi_002dcolumn-Tables">11.5 <code>@multitable</code>: Multi-column Tables</a> +<ul> +<li><a href="#Multitable-Column-Widths">11.5.1 Multitable Column Widths</a> +<li><a href="#Multitable-Rows">11.5.2 Multitable Rows</a> +</li></ul> +</li></ul> +<li><a name="toc_Special-Displays" href="#Special-Displays">12 Special Displays</a> +<ul> +<li><a href="#Floats">12.1 Floats</a> +<ul> +<li><a href="#float">12.1.1 <code>@float</code> [<var>type</var>][,<var>label</var>]: Floating material</a> +<li><a href="#caption-shortcaption">12.1.2 <code>@caption</code> & <code>@shortcaption</code></a> +<li><a href="#listoffloats">12.1.3 <code>@listoffloats</code>: Tables of contents for floats</a> +</li></ul> +<li><a href="#Images">12.2 Inserting Images</a> +<ul> +<li><a href="#Image-Syntax">12.2.1 Image Syntax</a> +<li><a href="#Image-Scaling">12.2.2 Image Scaling</a> +</li></ul> +<li><a href="#Footnotes">12.3 Footnotes</a> +<ul> +<li><a href="#Footnote-Commands">12.3.1 Footnote Commands</a> +<li><a href="#Footnote-Styles">12.3.2 Footnote Styles</a> +</li></ul> +</li></ul> +<li><a name="toc_Indices" href="#Indices">13 Indices</a> +<ul> +<li><a href="#Index-Entries">13.1 Making Index Entries</a> +<li><a href="#Predefined-Indices">13.2 Predefined Indices</a> +<li><a href="#Indexing-Commands">13.3 Defining the Entries of an Index</a> +<li><a href="#Combining-Indices">13.4 Combining Indices</a> +<ul> +<li><a href="#syncodeindex">13.4.1 <code>@syncodeindex</code></a> +<li><a href="#synindex">13.4.2 <code>@synindex</code></a> +</li></ul> +<li><a href="#New-Indices">13.5 Defining New Indices</a> +</li></ul> +<li><a name="toc_Insertions" href="#Insertions">14 Special Insertions</a> +<ul> +<li><a href="#Atsign-Braces-Comma">14.1 Inserting @ and {} and ,</a> +<ul> +<li><a href="#Inserting-an-Atsign">14.1.1 Inserting `@' with <code>@@</code></a> +<li><a href="#Inserting-Braces">14.1.2 Inserting `{' and `}' with <code>@{</code> and <code>@}</code></a> +<li><a href="#Inserting-a-Comma">14.1.3 Inserting `,' with <code>@comma{}</code></a> +</li></ul> +<li><a href="#Inserting-Space">14.2 Inserting Space</a> +<ul> +<li><a href="#Not-Ending-a-Sentence">14.2.1 Not Ending a Sentence</a> +<li><a href="#Ending-a-Sentence">14.2.2 Ending a Sentence</a> +<li><a href="#Multiple-Spaces">14.2.3 Multiple Spaces</a> +<li><a href="#dmn">14.2.4 <code>@dmn</code>{<var>dimension</var>}: Format a Dimension</a> +</li></ul> +<li><a href="#Inserting-Accents">14.3 Inserting Accents</a> +<li><a href="#Dots-Bullets">14.4 Inserting Ellipsis and Bullets</a> +<ul> +<li><a href="#dots">14.4.1 <code>@dots</code>{} (<small class="dots">...</small>) and <code>@enddots</code>{} (<small class="enddots">....</small>)</a> +<li><a href="#bullet">14.4.2 <code>@bullet</code>{} (•)</a> +</li></ul> +<li><a href="#TeX-and-copyright">14.5 Inserting TeX and Legal Symbols: ©, ®</a> +<ul> +<li><a href="#tex">14.5.1 <code>@TeX</code>{} (TeX) and <code>@LaTeX</code>{} (LaTeX)</a> +<li><a href="#copyright-symbol">14.5.2 <code>@copyright{}</code> (©)</a> +<li><a href="#registered-symbol">14.5.3 <code>@registeredsymbol{}</code> (®)</a> +</li></ul> +<li><a href="#pounds">14.6 <code>@pounds</code>{} (£): Pounds Sterling</a> +<li><a href="#minus">14.7 <code>@minus</code>{} (−): Inserting a Minus Sign</a> +<li><a href="#math">14.8 <code>@math</code>: Inserting Mathematical Expressions</a> +<li><a href="#Glyphs">14.9 Glyphs for Examples</a> +<ul> +<li><a href="#Glyphs-Summary">14.9.1 Glyphs Summary</a> +<li><a href="#result">14.9.2 <code>@result{}</code> (=>): Indicating Evaluation</a> +<li><a href="#expansion">14.9.3 <code>@expansion{}</code> (==>): Indicating an Expansion</a> +<li><a href="#Print-Glyph">14.9.4 <code>@print{}</code> (-|): Indicating Printed Output</a> +<li><a href="#Error-Glyph">14.9.5 <code>@error{}</code> (error-->): Indicating an Error Message</a> +<li><a href="#Equivalence">14.9.6 <code>@equiv{}</code> (==): Indicating Equivalence</a> +<li><a href="#Point-Glyph">14.9.7 <code>@point{}</code> (-!-): Indicating Point in a Buffer</a> +</li></ul> +</li></ul> +<li><a name="toc_Breaks" href="#Breaks">15 Forcing and Preventing Breaks</a> +<ul> +<li><a href="#Break-Commands">15.1 Break Commands</a> +<li><a href="#Line-Breaks">15.2 <code>@*</code> and <code>@/</code>: Generate and Allow Line Breaks</a> +<li><a href="#_002d-and-hyphenation">15.3 <code>@-</code> and <code>@hyphenation</code>: Helping TeX Hyphenate</a> +<li><a href="#w">15.4 <code>@w</code>{<var>text</var>}: Prevent Line Breaks</a> +<li><a href="#tie">15.5 <code>@tie{}</code>: Inserting an Unbreakable Space</a> +<li><a href="#sp">15.6 <code>@sp</code> <var>n</var>: Insert Blank Lines</a> +<li><a href="#page">15.7 <code>@page</code>: Start a New Page</a> +<li><a href="#group">15.8 <code>@group</code>: Prevent Page Breaks</a> +<li><a href="#need">15.9 <code>@need </code><var>mils</var>: Prevent Page Breaks</a> +</li></ul> +<li><a name="toc_Definition-Commands" href="#Definition-Commands">16 Definition Commands</a> +<ul> +<li><a href="#Def-Cmd-Template">16.1 The Template for a Definition</a> +<li><a href="#Def-Cmd-Continuation-Lines">16.2 Definition Command Continuation Lines</a> +<li><a href="#Optional-Arguments">16.3 Optional and Repeated Arguments</a> +<li><a href="#deffnx">16.4 Two or More `First' Lines</a> +<li><a href="#Def-Cmds-in-Detail">16.5 The Definition Commands</a> +<ul> +<li><a href="#Functions-Commands">16.5.1 Functions and Similar Entities</a> +<li><a href="#Variables-Commands">16.5.2 Variables and Similar Entities</a> +<li><a href="#Typed-Functions">16.5.3 Functions in Typed Languages</a> +<li><a href="#Typed-Variables">16.5.4 Variables in Typed Languages</a> +<li><a href="#Data-Types">16.5.5 Data Types</a> +<li><a href="#Abstract-Objects">16.5.6 Object-Oriented Programming</a> +<ul> +<li><a href="#Object_002dOriented-Variables">16.5.6.1 Object-Oriented Variables</a> +<li><a href="#Object_002dOriented-Methods">16.5.6.2 Object-Oriented Methods</a> +</li></ul> +</li></ul> +<li><a href="#Def-Cmd-Conventions">16.6 Conventions for Writing Definitions</a> +<li><a href="#Sample-Function-Definition">16.7 A Sample Function Definition</a> +</li></ul> +<li><a name="toc_Conditionals" href="#Conditionals">17 Conditionally Visible Text</a> +<ul> +<li><a href="#Conditional-Commands">17.1 Conditional Commands</a> +<li><a href="#Conditional-Not-Commands">17.2 Conditional Not Commands</a> +<li><a href="#Raw-Formatter-Commands">17.3 Raw Formatter Commands</a> +<li><a href="#set-clear-value">17.4 <code>@set</code>, <code>@clear</code>, and <code>@value</code></a> +<ul> +<li><a href="#set-value">17.4.1 <code>@set</code> and <code>@value</code></a> +<li><a href="#ifset-ifclear">17.4.2 <code>@ifset</code> and <code>@ifclear</code></a> +<li><a href="#value-Example">17.4.3 <code>@value</code> Example</a> +</li></ul> +<li><a href="#Conditional-Nesting">17.5 Conditional Nesting</a> +</li></ul> +<li><a name="toc_Internationalization" href="#Internationalization">18 Internationalization</a> +<ul> +<li><a href="#documentlanguage">18.1 <code>@documentlanguage </code><var>cc</var>: Set the Document Language</a> +<li><a href="#documentencoding">18.2 <code>@documentencoding </code><var>enc</var>: Set Input Encoding</a> +</li></ul> +<li><a name="toc_Defining-New-Texinfo-Commands" href="#Defining-New-Texinfo-Commands">19 Defining New Texinfo Commands</a> +<ul> +<li><a href="#Defining-Macros">19.1 Defining Macros</a> +<li><a href="#Invoking-Macros">19.2 Invoking Macros</a> +<li><a href="#Macro-Details">19.3 Macro Details</a> +<li><a href="#alias">19.4 <span class="samp">@alias </span><var>new</var><span class="samp">=</span><var>existing</var></a> +<li><a href="#definfoenclose">19.5 <span class="samp">definfoenclose</span>: Customized Highlighting</a> +</li></ul> +<li><a name="toc_Hardcopy" href="#Hardcopy">20 Formatting and Printing Hardcopy</a> +<ul> +<li><a href="#Use-TeX">20.1 Use TeX</a> +<li><a href="#Format-with-tex_002ftexindex">20.2 Format with <code>tex</code> and <code>texindex</code></a> +<li><a href="#Format-with-texi2dvi">20.3 Format with <code>texi2dvi</code></a> +<li><a href="#Print-with-lpr">20.4 Shell Print Using <code>lpr -d</code></a> +<li><a href="#Within-Emacs">20.5 From an Emacs Shell</a> +<li><a href="#Texinfo-Mode-Printing">20.6 Formatting and Printing in Texinfo Mode</a> +<li><a href="#Compile_002dCommand">20.7 Using the Local Variables List</a> +<li><a href="#Requirements-Summary">20.8 TeX Formatting Requirements Summary</a> +<li><a href="#Preparing-for-TeX">20.9 Preparing for TeX</a> +<li><a href="#Overfull-hboxes">20.10 Overfull “hboxes”</a> +<li><a href="#smallbook">20.11 Printing “Small” Books</a> +<li><a href="#A4-Paper">20.12 Printing on A4 Paper</a> +<li><a href="#pagesizes">20.13 <code>@pagesizes</code> [<var>width</var>][, <var>height</var>]: Custom Page Sizes</a> +<li><a href="#Cropmarks-and-Magnification">20.14 Cropmarks and Magnification</a> +<li><a href="#PDF-Output">20.15 PDF Output</a> +<li><a href="#Obtaining-TeX">20.16 How to Obtain TeX</a> +</li></ul> +<li><a name="toc_Creating-and-Installing-Info-Files" href="#Creating-and-Installing-Info-Files">21 Creating and Installing Info Files</a> +<ul> +<li><a href="#Creating-an-Info-File">21.1 Creating an Info File</a> +<ul> +<li><a href="#makeinfo-advantages">21.1.1 <code>makeinfo</code> Preferred</a> +<li><a href="#Invoking-makeinfo">21.1.2 Running <code>makeinfo</code> from a Shell</a> +<li><a href="#makeinfo-options">21.1.3 Options for <code>makeinfo</code></a> +<li><a href="#Pointer-Validation">21.1.4 Pointer Validation</a> +<li><a href="#makeinfo-in-Emacs">21.1.5 Running <code>makeinfo</code> Within Emacs</a> +<li><a href="#texinfo_002dformat-commands">21.1.6 The <code>texinfo-format...</code> Commands</a> +<li><a href="#Batch-Formatting">21.1.7 Batch Formatting</a> +<li><a href="#Tag-and-Split-Files">21.1.8 Tag Files and Split Files</a> +</li></ul> +<li><a href="#Installing-an-Info-File">21.2 Installing an Info File</a> +<ul> +<li><a href="#Directory-File">21.2.1 The Directory File <span class="file">dir</span></a> +<li><a href="#New-Info-File">21.2.2 Listing a New Info File</a> +<li><a href="#Other-Info-Directories">21.2.3 Info Files in Other Directories</a> +<li><a href="#Installing-Dir-Entries">21.2.4 Installing Info Directory Files</a> +<li><a href="#Invoking-install_002dinfo">21.2.5 Invoking <span class="command">install-info</span></a> +</li></ul> +</li></ul> +<li><a name="toc_Generating-HTML" href="#Generating-HTML">22 Generating HTML</a> +<ul> +<li><a href="#HTML-Translation">22.1 HTML Translation</a> +<li><a href="#HTML-Splitting">22.2 HTML Splitting</a> +<li><a href="#HTML-CSS">22.3 HTML CSS</a> +<li><a href="#HTML-Xref">22.4 HTML Cross-references</a> +<ul> +<li><a href="#HTML-Xref-Link-Basics">22.4.1 HTML Cross-reference Link Basics</a> +<li><a href="#HTML-Xref-Node-Name-Expansion">22.4.2 HTML Cross-reference Node Name Expansion</a> +<li><a href="#HTML-Xref-Command-Expansion">22.4.3 HTML Cross-reference Command Expansion</a> +<li><a href="#HTML-Xref-8_002dbit-Character-Expansion">22.4.4 HTML Cross-reference 8-bit Character Expansion</a> +<li><a href="#HTML-Xref-Mismatch">22.4.5 HTML Cross-reference Mismatch</a> +</li></ul> +</li></ul> +<li><a name="toc_Command-List" href="#Command-List">Appendix A @-Command List</a> +<ul> +<li><a href="#Command-Syntax">A.1 @-Command Syntax</a> +</li></ul> +<li><a name="toc_Tips" href="#Tips">Appendix B Tips and Hints</a> +<li><a name="toc_Sample-Texinfo-Files" href="#Sample-Texinfo-Files">Appendix C Sample Texinfo Files</a> +<ul> +<li><a href="#Short-Sample-Texinfo-File">C.1 Short Sample</a> +<li><a href="#GNU-Sample-Texts">C.2 GNU Sample Texts</a> +<li><a href="#Verbatim-Copying-License">C.3 Verbatim Copying License</a> +<li><a href="#All_002dpermissive-Copying-License">C.4 All-permissive Copying License</a> +</li></ul> +<li><a name="toc_Include-Files" href="#Include-Files">Appendix D Include Files</a> +<ul> +<li><a href="#Using-Include-Files">D.1 How to Use Include Files</a> +<li><a href="#texinfo_002dmultiple_002dfiles_002dupdate">D.2 <code>texinfo-multiple-files-update</code></a> +<li><a href="#Include-Files-Requirements">D.3 Include Files Requirements</a> +<li><a href="#Sample-Include-File">D.4 Sample File with <code>@include</code></a> +<li><a href="#Include-Files-Evolution">D.5 Evolution of Include Files</a> +</li></ul> +<li><a name="toc_Headings" href="#Headings">Appendix E Page Headings</a> +<ul> +<li><a href="#Headings-Introduced">E.1 Headings Introduced</a> +<li><a href="#Heading-Format">E.2 Standard Heading Formats</a> +<li><a href="#Heading-Choice">E.3 Specifying the Type of Heading</a> +<li><a href="#Custom-Headings">E.4 How to Make Your Own Headings</a> +</li></ul> +<li><a name="toc_Catching-Mistakes" href="#Catching-Mistakes">Appendix F Formatting Mistakes</a> +<ul> +<li><a href="#makeinfo-Preferred">F.1 <code>makeinfo</code> Find Errors</a> +<li><a href="#Debugging-with-Info">F.2 Catching Errors with Info Formatting</a> +<li><a href="#Debugging-with-TeX">F.3 Catching Errors with TeX Formatting</a> +<li><a href="#Using-texinfo_002dshow_002dstructure">F.4 Using <code>texinfo-show-structure</code></a> +<li><a href="#Using-occur">F.5 Using <code>occur</code></a> +<li><a href="#Running-Info_002dValidate">F.6 Finding Badly Referenced Nodes</a> +<ul> +<li><a href="#Using-Info_002dvalidate">F.6.1 Running <code>Info-validate</code></a> +<li><a href="#Unsplit">F.6.2 Creating an Unsplit File</a> +<li><a href="#Tagifying">F.6.3 Tagifying a File</a> +<li><a href="#Splitting">F.6.4 Splitting a File Manually</a> +</li></ul> +</li></ul> +<li><a name="toc_Copying-This-Manual" href="#Copying-This-Manual">Appendix G Copying This Manual</a> +<ul> +<li><a href="#GNU-Free-Documentation-License">G.1 GNU Free Documentation License</a> +<ul> +<li><a href="#GNU-Free-Documentation-License">G.1.1 ADDENDUM: How to use this License for your documents</a> +</li></ul> +</li></ul> +<li><a name="toc_Command-and-Variable-Index" href="#Command-and-Variable-Index">Command and Variable Index</a> +<li><a name="toc_Concept-Index" href="#Concept-Index">Concept Index</a> +</li></ul> +</div> + +<div class="node"> +<p><hr> +<a name="Top"></a>Next: <a rel="next" accesskey="n" href="#Copying-Conditions">Copying Conditions</a>, +Up: <a rel="up" accesskey="u" href="#dir">(dir)</a> +<br> +</div> + +<h2 class="unnumbered">Texinfo</h2> + +<p>This manual is for GNU Texinfo (version 4.7, 9 April 2004), +a documentation system that can produce both online information and a +printed manual from a single source. + + <p>Copyright (C) 1988, 1990, 1991, 1992, 1993, 1995, 1996, 1997, 1998, +1999, 2000, 2001, 2002, 2003, 2004 Free Software Foundation, Inc. + + <blockquote> +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.1 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover texts being “A GNU Manual,” +and with the Back-Cover Texts as in (a) below. A copy of the license is +included in the section entitled “GNU Free Documentation License.” + + <p>(a) The FSF's Back-Cover Text is: “You have freedom to copy and modify +this GNU Manual, like GNU software. Copies published by the Free +Software Foundation raise funds for GNU development.” +</blockquote> + + <p>The first part of this master menu lists the major nodes in this Info +document, including the @-command and concept indices. The rest of +the menu lists all the lower level nodes in the document. + +<ul class="menu"> +<li><a accesskey="1" href="#Copying-Conditions">Copying Conditions</a>: Your rights. +<li><a accesskey="2" href="#Overview">Overview</a>: Texinfo in brief. +<li><a accesskey="3" href="#Texinfo-Mode">Texinfo Mode</a>: Using the GNU Emacs Texinfo mode. +<li><a accesskey="4" href="#Beginning-a-File">Beginning a File</a>: What is at the beginning of a Texinfo file? +<li><a accesskey="5" href="#Ending-a-File">Ending a File</a>: What is at the end of a Texinfo file? +<li><a accesskey="6" href="#Structuring">Structuring</a>: Creating chapters, sections, appendices, etc. +<li><a accesskey="7" href="#Nodes">Nodes</a>: Writing nodes, the basic unit of Texinfo. +<li><a accesskey="8" href="#Menus">Menus</a>: Writing menus. +<li><a accesskey="9" href="#Cross-References">Cross References</a>: Writing cross references. +<li><a href="#Marking-Text">Marking Text</a>: Marking words and phrases as code, + keyboard input, meta-syntactic + variables, and the like. +<li><a href="#Quotations-and-Examples">Quotations and Examples</a>: Block quotations, examples, etc. +<li><a href="#Lists-and-Tables">Lists and Tables</a>: Itemized or numbered lists, and tables. +<li><a href="#Special-Displays">Special Displays</a>: Floating figures and footnotes. +<li><a href="#Indices">Indices</a>: Creating indices. +<li><a href="#Insertions">Insertions</a>: Inserting @-signs, braces, etc. +<li><a href="#Breaks">Breaks</a>: Forcing or preventing line and page breaks. +<li><a href="#Definition-Commands">Definition Commands</a>: Describing functions and the like uniformly. +<li><a href="#Conditionals">Conditionals</a>: Specifying text for only some output cases. +<li><a href="#Internationalization">Internationalization</a>: Supporting languages other than English. +<li><a href="#Defining-New-Texinfo-Commands">Defining New Texinfo Commands</a>: User-defined macros and aliases. +<li><a href="#Hardcopy">Hardcopy</a>: Output for paper, with TeX. +<li><a href="#Creating-and-Installing-Info-Files">Creating and Installing Info Files</a>: Details on Info output. +<li><a href="#Generating-HTML">Generating HTML</a>: Details on HTML output. + +<li><a href="#Command-List">Command List</a>: All the Texinfo @-commands. +<li><a href="#Tips">Tips</a>: Hints on how to write a Texinfo document. +<li><a href="#Sample-Texinfo-Files">Sample Texinfo Files</a>: Complete examples, including full texts. +<li><a href="#Include-Files">Include Files</a>: How to incorporate other Texinfo files. +<li><a href="#Headings">Headings</a>: How to write page headings and footings. +<li><a href="#Catching-Mistakes">Catching Mistakes</a>: How to find formatting mistakes. +<li><a href="#Copying-This-Manual">Copying This Manual</a>: The GNU Free Documentation License. +<li><a href="#Command-and-Variable-Index">Command and Variable Index</a>: A menu containing commands and variables. +<li><a href="#Concept-Index">Concept Index</a>: A menu covering many topics. + +</li></ul> +<p>--- The Detailed Node Listing --- + +<p>Overview of Texinfo + +</p> +<ul class="menu"> +<li><a href="#Reporting-Bugs">Reporting Bugs</a>: Submitting effective bug reports. +<li><a href="#Using-Texinfo">Using Texinfo</a>: Create printed or online output. +<li><a href="#Output-Formats">Output Formats</a>: Overview of the supported output formats. +<li><a href="#Info-Files">Info Files</a>: What is an Info file? +<li><a href="#Printed-Books">Printed Books</a>: Characteristics of a printed book or manual. +<li><a href="#Formatting-Commands">Formatting Commands</a>: @-commands are used for formatting. +<li><a href="#Conventions">Conventions</a>: General rules for writing a Texinfo file. +<li><a href="#Comments">Comments</a>: Writing comments and ignored text in general. +<li><a href="#Minimum">Minimum</a>: What a Texinfo file must have. +<li><a href="#Six-Parts">Six Parts</a>: Usually, a Texinfo file has six parts. +<li><a href="#Short-Sample">Short Sample</a>: A short sample Texinfo file. +<li><a href="#History">History</a>: Acknowledgements, contributors and genesis. + +</li></ul> +<p>Using Texinfo Mode + +</p> +<ul class="menu"> +<li><a href="#Texinfo-Mode-Overview">Texinfo Mode Overview</a>: How Texinfo mode can help you. +<li><a href="#Emacs-Editing">Emacs Editing</a>: Texinfo mode adds to GNU Emacs' general + purpose editing features. +<li><a href="#Inserting">Inserting</a>: How to insert frequently used @-commands. +<li><a href="#Showing-the-Structure">Showing the Structure</a>: How to show the structure of a file. +<li><a href="#Updating-Nodes-and-Menus">Updating Nodes and Menus</a>: How to update or create new nodes and menus. +<li><a href="#Info-Formatting">Info Formatting</a>: How to format for Info. +<li><a href="#Printing">Printing</a>: How to format and print part or all of a file. +<li><a href="#Texinfo-Mode-Summary">Texinfo Mode Summary</a>: Summary of all the Texinfo mode commands. + +</li></ul> +<p>Updating Nodes and Menus + +</p> +<ul class="menu"> +<li><a href="#Updating-Commands">Updating Commands</a>: Five major updating commands. +<li><a href="#Updating-Requirements">Updating Requirements</a>: How to structure a Texinfo file for + using the updating command. +<li><a href="#Other-Updating-Commands">Other Updating Commands</a>: How to indent descriptions, insert + missing nodes lines, and update + nodes in sequence. + +</li></ul> +<p>Beginning a Texinfo File + +</p> +<ul class="menu"> +<li><a href="#Sample-Beginning">Sample Beginning</a>: A sample beginning for a Texinfo file. +<li><a href="#Texinfo-File-Header">Texinfo File Header</a>: The first lines. +<li><a href="#Document-Permissions">Document Permissions</a>: Ensuring your manual is free. +<li><a href="#Titlepage-_0026-Copyright-Page">Titlepage & Copyright Page</a>: Creating the title and copyright pages. +<li><a href="#Contents">Contents</a>: How to create a table of contents. +<li><a href="#The-Top-Node">The Top Node</a>: Creating the `Top' node and master menu. +<li><a href="#Global-Document-Commands">Global Document Commands</a>: Affecting formatting throughout. +<li><a href="#Software-Copying-Permissions">Software Copying Permissions</a>: Ensure that you and others continue to + have the right to use and share software. + +</li></ul> +<p>Texinfo File Header + +</p> +<ul class="menu"> +<li><a href="#First-Line">First Line</a>: The first line of a Texinfo file. +<li><a href="#Start-of-Header">Start of Header</a>: Formatting a region requires this. +<li><a href="#setfilename">setfilename</a>: Tell Info the name of the Info file. +<li><a href="#settitle">settitle</a>: Create a title for the printed work. +<li><a href="#End-of-Header">End of Header</a>: Formatting a region requires this. + +</li></ul> +<p>Document Permissions + +</p> +<ul class="menu"> +<li><a href="#copying">copying</a>: Declare the document's copying permissions. +<li><a href="#insertcopying">insertcopying</a>: Where to insert the permissions. + +</li></ul> +<p>Title and Copyright Pages + +</p> +<ul class="menu"> +<li><a href="#titlepage">titlepage</a>: Create a title for the printed document. +<li><a href="#titlefont-center-sp">titlefont center sp</a>: The <code>@titlefont</code>, <code>@center</code>, + and <code>@sp</code> commands. +<li><a href="#title-subtitle-author">title subtitle author</a>: The <code>@title</code>, <code>@subtitle</code>, + and <code>@author</code> commands. +<li><a href="#Copyright">Copyright</a>: How to write the copyright notice and + include copying permissions. +<li><a href="#end-titlepage">end titlepage</a>: Turn on page headings after the title and + copyright pages. +<li><a href="#headings-on-off">headings on off</a>: An option for turning headings on and off + and double or single sided printing. + +</li></ul> +<p>The `Top' Node and Master Menu + +</p> +<ul class="menu"> +<li><a href="#Top-Node-Example">Top Node Example</a> +<li><a href="#Master-Menu-Parts">Master Menu Parts</a> + +</li></ul> +<p>Global Document Commands + +</p> +<ul class="menu"> +<li><a href="#documentdescription">documentdescription</a>: Document summary for the HTML output. +<li><a href="#setchapternewpage">setchapternewpage</a>: Start chapters on right-hand pages. +<li><a href="#paragraphindent">paragraphindent</a>: Specify paragraph indentation. +<li><a href="#firstparagraphindent">firstparagraphindent</a>: Suppress indentation of the first paragraph. +<li><a href="#exampleindent">exampleindent</a>: Specify environment indentation. + +</li></ul> +<p>Ending a Texinfo File + +</p> +<ul class="menu"> +<li><a href="#Printing-Indices-_0026-Menus">Printing Indices & Menus</a>: How to print an index in hardcopy and + generate index menus in Info. +<li><a href="#File-End">File End</a>: How to mark the end of a file. + +</li></ul> +<p>Chapter Structuring + +</p> +<ul class="menu"> +<li><a href="#Tree-Structuring">Tree Structuring</a>: A manual is like an upside down tree ... +<li><a href="#Structuring-Command-Types">Structuring Command Types</a>: How to divide a manual into parts. +<li><a href="#makeinfo-top">makeinfo top</a>: The <code>@top</code> command, part of the `Top' node. +<li><a href="#chapter">chapter</a> +<li><a href="#unnumbered-_0026-appendix">unnumbered & appendix</a> +<li><a href="#majorheading-_0026-chapheading">majorheading & chapheading</a> +<li><a href="#section">section</a> +<li><a href="#unnumberedsec-appendixsec-heading">unnumberedsec appendixsec heading</a> +<li><a href="#subsection">subsection</a> +<li><a href="#unnumberedsubsec-appendixsubsec-subheading">unnumberedsubsec appendixsubsec subheading</a> +<li><a href="#subsubsection">subsubsection</a>: Commands for the lowest level sections. +<li><a href="#Raise_002flower-sections">Raise/lower sections</a>: How to change commands' hierarchical level. + +</li></ul> +<p>Nodes + +</p> +<ul class="menu"> +<li><a href="#Two-Paths">Two Paths</a>: Different commands to structure + Info output and printed output. +<li><a href="#Node-Menu-Illustration">Node Menu Illustration</a>: A diagram, and sample nodes and menus. +<li><a href="#node">node</a>: Creating nodes, in detail. +<li><a href="#makeinfo-Pointer-Creation">makeinfo Pointer Creation</a>: Letting makeinfo determine node pointers. +<li><a href="#anchor">anchor</a>: Defining arbitrary cross-reference targets. + +</li></ul> +<p>The <code>@node</code> Command + +</p> +<ul class="menu"> +<li><a href="#Node-Names">Node Names</a>: How to choose node and pointer names. +<li><a href="#Writing-a-Node">Writing a Node</a>: How to write an <code>@node</code> line. +<li><a href="#Node-Line-Tips">Node Line Tips</a>: Keep names short. +<li><a href="#Node-Line-Requirements">Node Line Requirements</a>: Keep names unique, without @-commands. +<li><a href="#First-Node">First Node</a>: How to write a `Top' node. +<li><a href="#makeinfo-top-command">makeinfo top command</a>: How to use the <code>@top</code> command. + +</li></ul> +<p>Menus + +</p> +<ul class="menu"> +<li><a href="#Menu-Location">Menu Location</a>: Menus go at the ends of short nodes. +<li><a href="#Writing-a-Menu">Writing a Menu</a>: What is a menu? +<li><a href="#Menu-Parts">Menu Parts</a>: A menu entry has three parts. +<li><a href="#Less-Cluttered-Menu-Entry">Less Cluttered Menu Entry</a>: Two part menu entry. +<li><a href="#Menu-Example">Menu Example</a>: Two and three part menu entries. +<li><a href="#Other-Info-Files">Other Info Files</a>: How to refer to a different Info file. + +</li></ul> +<p>Cross References + +</p> +<ul class="menu"> +<li><a href="#References">References</a>: What cross references are for. +<li><a href="#Cross-Reference-Commands">Cross Reference Commands</a>: A summary of the different commands. +<li><a href="#Cross-Reference-Parts">Cross Reference Parts</a>: A cross reference has several parts. +<li><a href="#xref">xref</a>: Begin a reference with `See' ... +<li><a href="#Top-Node-Naming">Top Node Naming</a>: How to refer to the beginning of another file. +<li><a href="#ref">ref</a>: A reference for the last part of a sentence. +<li><a href="#pxref">pxref</a>: How to write a parenthetical cross reference. +<li><a href="#inforef">inforef</a>: How to refer to an Info-only file. +<li><a href="#uref">uref</a>: How to refer to a uniform resource locator. + +</li></ul> +<p><code>@xref</code> + +</p> +<ul class="menu"> +<li><a href="#Reference-Syntax">Reference Syntax</a>: What a reference looks like and requires. +<li><a href="#One-Argument">One Argument</a>: <code>@xref</code> with one argument. +<li><a href="#Two-Arguments">Two Arguments</a>: <code>@xref</code> with two arguments. +<li><a href="#Three-Arguments">Three Arguments</a>: <code>@xref</code> with three arguments. +<li><a href="#Four-and-Five-Arguments">Four and Five Arguments</a>: <code>@xref</code> with four and five arguments. + +</li></ul> +<p>Marking Words and Phrases + +</p> +<ul class="menu"> +<li><a href="#Indicating">Indicating</a>: How to indicate definitions, files, etc. +<li><a href="#Emphasis">Emphasis</a>: How to emphasize text. + +</li></ul> +<p>Indicating Definitions, Commands, etc. + +</p> +<ul class="menu"> +<li><a href="#Useful-Highlighting">Useful Highlighting</a>: Highlighting provides useful information. +<li><a href="#code">code</a>: Indicating program code. +<li><a href="#kbd">kbd</a>: Showing keyboard input. +<li><a href="#key">key</a>: Specifying keys. +<li><a href="#samp">samp</a>: A literal sequence of characters. +<li><a href="#verb">verb</a>: A verbatim sequence of characters. +<li><a href="#var">var</a>: Indicating metasyntactic variables. +<li><a href="#env">env</a>: Indicating environment variables. +<li><a href="#file">file</a>: Indicating file names. +<li><a href="#command">command</a>: Indicating command names. +<li><a href="#option">option</a>: Indicating option names. +<li><a href="#dfn">dfn</a>: Specifying definitions. +<li><a href="#cite">cite</a>: Referring to books not in the Info system. +<li><a href="#acronym">acronym</a>: Indicating acronyms. +<li><a href="#indicateurl">indicateurl</a>: Indicating a World Wide Web reference. +<li><a href="#email">email</a>: Indicating an electronic mail address. + +</li></ul> +<p>Emphasizing Text + +</p> +<ul class="menu"> +<li><a href="#emph-_0026-strong">emph & strong</a>: How to emphasize text in Texinfo. +<li><a href="#Smallcaps">Smallcaps</a>: How to use the small caps font. +<li><a href="#Fonts">Fonts</a>: Various font commands for printed output. + +</li></ul> +<p>Quotations and Examples + +</p> +<ul class="menu"> +<li><a href="#Block-Enclosing-Commands">Block Enclosing Commands</a>: Different constructs for different purposes. +<li><a href="#quotation">quotation</a>: Writing a quotation. +<li><a href="#example">example</a>: Writing an example in a fixed-width font. +<li><a href="#verbatim">verbatim</a>: Writing a verbatim example. +<li><a href="#verbatiminclude">verbatiminclude</a>: Including a file verbatim. +<li><a href="#lisp">lisp</a>: Illustrating Lisp code. +<li><a href="#small">small</a>: Examples in a smaller font. +<li><a href="#display">display</a>: Writing an example in the current font. +<li><a href="#format">format</a>: Writing an example without narrowed margins. +<li><a href="#exdent">exdent</a>: Undo indentation on a line. +<li><a href="#flushleft-_0026-flushright">flushleft & flushright</a>: Pushing text flush left or flush right. +<li><a href="#noindent">noindent</a>: Preventing paragraph indentation. +<li><a href="#indent">indent</a>: Forcing paragraph indentation. +<li><a href="#cartouche">cartouche</a>: Drawing rounded rectangles around examples. + +</li></ul> +<p>Lists and Tables + +</p> +<ul class="menu"> +<li><a href="#Introducing-Lists">Introducing Lists</a>: Texinfo formats lists for you. +<li><a href="#itemize">itemize</a>: How to construct a simple list. +<li><a href="#enumerate">enumerate</a>: How to construct a numbered list. +<li><a href="#Two_002dcolumn-Tables">Two-column Tables</a>: How to construct a two-column table. +<li><a href="#Multi_002dcolumn-Tables">Multi-column Tables</a>: How to construct generalized tables. + +</li></ul> +<p>Making a Two-column Table + +</p> +<ul class="menu"> +<li><a href="#table">table</a>: How to construct a two-column table. +<li><a href="#ftable-vtable">ftable vtable</a>: Automatic indexing for two-column tables. +<li><a href="#itemx">itemx</a>: How to put more entries in the first column. + +</li></ul> +<p><code>@multitable</code>: Multi-column Tables + +</p> +<ul class="menu"> +<li><a href="#Multitable-Column-Widths">Multitable Column Widths</a>: Defining multitable column widths. +<li><a href="#Multitable-Rows">Multitable Rows</a>: Defining multitable rows, with examples. + +</li></ul> +<p>Special Displays + +</p> +<ul class="menu"> +<li><a href="#Floats">Floats</a>: Figures, tables, and the like. +<li><a href="#Images">Images</a>: Including graphics and images. +<li><a href="#Footnotes">Footnotes</a>: Writing footnotes. + +</li></ul> +<p>Floats + +</p> +<ul class="menu"> +<li><a href="#float">float</a>: Producing floating material. +<li><a href="#caption-shortcaption">caption shortcaption</a>: Specifying descriptions for floats. +<li><a href="#listoffloats">listoffloats</a>: A table of contents for floats. + +</li></ul> +<p>Inserting Images + +</p> +<ul class="menu"> +<li><a href="#Image-Syntax">Image Syntax</a> +<li><a href="#Image-Scaling">Image Scaling</a> + +</li></ul> +<p>Footnotes + +</p> +<ul class="menu"> +<li><a href="#Footnote-Commands">Footnote Commands</a>: How to write a footnote in Texinfo. +<li><a href="#Footnote-Styles">Footnote Styles</a>: Controlling how footnotes appear in Info. + +</li></ul> +<p>Indices + +</p> +<ul class="menu"> +<li><a href="#Index-Entries">Index Entries</a>: Choose different words for index entries. +<li><a href="#Predefined-Indices">Predefined Indices</a>: Use different indices for different kinds + of entries. +<li><a href="#Indexing-Commands">Indexing Commands</a>: How to make an index entry. +<li><a href="#Combining-Indices">Combining Indices</a>: How to combine indices. +<li><a href="#New-Indices">New Indices</a>: How to define your own indices. + +</li></ul> +<p>Combining Indices + +</p> +<ul class="menu"> +<li><a href="#syncodeindex">syncodeindex</a>: How to merge two indices, using <code>@code</code> + font for the merged-from index. +<li><a href="#synindex">synindex</a>: How to merge two indices, using the + default font of the merged-to index. + +</li></ul> +<p>Special Insertions + +</p> +<ul class="menu"> +<li><a href="#Atsign-Braces-Comma">Atsign Braces Comma</a>: Inserting @ and {} and ,. +<li><a href="#Inserting-Space">Inserting Space</a>: How to insert the right amount of space + within a sentence. +<li><a href="#Inserting-Accents">Inserting Accents</a>: How to insert accents and special characters. +<li><a href="#Dots-Bullets">Dots Bullets</a>: How to insert dots and bullets. +<li><a href="#TeX-and-copyright">TeX and copyright</a>: How to insert the TeX logo + and the copyright symbol. +<li><a href="#pounds">pounds</a>: How to insert the pounds currency symbol. +<li><a href="#minus">minus</a>: How to insert a minus sign. +<li><a href="#math">math</a>: How to format a mathematical expression. +<li><a href="#Glyphs">Glyphs</a>: How to indicate results of evaluation, + expansion of macros, errors, etc. + +</li></ul> +<p>Inserting @ and {} and , + +</p> +<ul class="menu"> +<li><a href="#Inserting-an-Atsign">Inserting an Atsign</a> +<li><a href="#Inserting-Braces">Inserting Braces</a> +<li><a href="#Inserting-a-Comma">Inserting a Comma</a> + +</li></ul> +<p>Inserting Space + +</p> +<ul class="menu"> +<li><a href="#Not-Ending-a-Sentence">Not Ending a Sentence</a>: Sometimes a . doesn't end a sentence. +<li><a href="#Ending-a-Sentence">Ending a Sentence</a>: Sometimes it does. +<li><a href="#Multiple-Spaces">Multiple Spaces</a>: Inserting multiple spaces. +<li><a href="#dmn">dmn</a>: How to format a dimension. + +</li></ul> +<p>Inserting Ellipsis and Bullets + +</p> +<ul class="menu"> +<li><a href="#dots">dots</a>: How to insert dots ... +<li><a href="#bullet">bullet</a>: How to insert a bullet. + +</li></ul> +<p>Inserting TeX and Legal Symbols: ©, ® + +</p> +<ul class="menu"> +<li><a href="#tex">tex</a>: The TeX logos. +<li><a href="#copyright-symbol">copyright symbol</a>: The copyright symbol (c in a circle). +<li><a href="#registered-symbol">registered symbol</a>: The registered symbol (R in a circle). + +</li></ul> +<p>Glyphs for Examples + +</p> +<ul class="menu"> +<li><a href="#Glyphs-Summary">Glyphs Summary</a> +<li><a href="#result">result</a>: How to show the result of expression. +<li><a href="#expansion">expansion</a>: How to indicate an expansion. +<li><a href="#Print-Glyph">Print Glyph</a>: How to indicate printed output. +<li><a href="#Error-Glyph">Error Glyph</a>: How to indicate an error message. +<li><a href="#Equivalence">Equivalence</a>: How to indicate equivalence. +<li><a href="#Point-Glyph">Point Glyph</a>: How to indicate the location of point. + +</li></ul> +<p>Glyphs Summary + +</p> +<ul class="menu"> +<li><a href="#result">result</a> +<li><a href="#expansion">expansion</a> +<li><a href="#Print-Glyph">Print Glyph</a> +<li><a href="#Error-Glyph">Error Glyph</a> +<li><a href="#Equivalence">Equivalence</a> +<li><a href="#Point-Glyph">Point Glyph</a> + +</li></ul> +<p>Forcing and Preventing Breaks + +</p> +<ul class="menu"> +<li><a href="#Break-Commands">Break Commands</a>: Summary of break-related commands. +<li><a href="#Line-Breaks">Line Breaks</a>: Forcing line breaks. +<li><a href="#_002d-and-hyphenation">- and hyphenation</a>: Helping TeX with hyphenation points. +<li><a href="#w">w</a>: Preventing unwanted line breaks in text. +<li><a href="#tie">tie</a>: Inserting an unbreakable but varying space. +<li><a href="#sp">sp</a>: Inserting blank lines. +<li><a href="#page">page</a>: Forcing the start of a new page. +<li><a href="#group">group</a>: Preventing unwanted page breaks. +<li><a href="#need">need</a>: Another way to prevent unwanted page breaks. + +</li></ul> +<p>Definition Commands + +</p> +<ul class="menu"> +<li><a href="#Def-Cmd-Template">Def Cmd Template</a>: Writing descriptions using definition commands. +<li><a href="#Def-Cmd-Continuation-Lines">Def Cmd Continuation Lines</a>: Continuing the heading over source lines. +<li><a href="#Optional-Arguments">Optional Arguments</a>: Handling optional and repeated arguments. +<li><a href="#deffnx">deffnx</a>: Group two or more `first' lines. +<li><a href="#Def-Cmds-in-Detail">Def Cmds in Detail</a>: Reference for all the definition commands. +<li><a href="#Def-Cmd-Conventions">Def Cmd Conventions</a>: Conventions for writing definitions. +<li><a href="#Sample-Function-Definition">Sample Function Definition</a>: An example. + +</li></ul> +<p>The Definition Commands + +</p> +<ul class="menu"> +<li><a href="#Functions-Commands">Functions Commands</a>: Commands for functions and similar entities. +<li><a href="#Variables-Commands">Variables Commands</a>: Commands for variables and similar entities. +<li><a href="#Typed-Functions">Typed Functions</a>: Commands for functions in typed languages. +<li><a href="#Typed-Variables">Typed Variables</a>: Commands for variables in typed languages. +<li><a href="#Data-Types">Data Types</a>: The definition command for data types. +<li><a href="#Abstract-Objects">Abstract Objects</a>: Commands for object-oriented programming. + +</li></ul> +<p>Object-Oriented Programming + +</p> +<ul class="menu"> +<li><a href="#Object_002dOriented-Variables">Variables</a> +<li><a href="#Object_002dOriented-Methods">Methods</a> + +</li></ul> +<p>Conditionally Visible Text + +</p> +<ul class="menu"> +<li><a href="#Conditional-Commands">Conditional Commands</a>: Text for a given format. +<li><a href="#Conditional-Not-Commands">Conditional Not Commands</a>: Text for any format other than a given one. +<li><a href="#Raw-Formatter-Commands">Raw Formatter Commands</a>: Using raw formatter commands. +<li><a href="#set-clear-value">set clear value</a>: Variable tests and substitutions. +<li><a href="#Conditional-Nesting">Conditional Nesting</a>: Using conditionals inside conditionals. + +</li></ul> +<p><code>@set</code>, <code>@clear</code>, and <code>@value</code> + +</p> +<ul class="menu"> +<li><a href="#set-value">set value</a>: Expand a flag variable to a string. +<li><a href="#ifset-ifclear">ifset ifclear</a>: Format a region if a flag is set. +<li><a href="#value-Example">value Example</a>: An easy way to update edition information. + +</li></ul> +<p>Internationalization + +</p> +<ul class="menu"> +<li><a href="#documentlanguage">documentlanguage</a>: Declaring the current language. +<li><a href="#documentencoding">documentencoding</a>: Declaring the input encoding. + +</li></ul> +<p>Defining New Texinfo Commands + +</p> +<ul class="menu"> +<li><a href="#Defining-Macros">Defining Macros</a>: Defining and undefining new commands. +<li><a href="#Invoking-Macros">Invoking Macros</a>: Using a macro, once you've defined it. +<li><a href="#Macro-Details">Macro Details</a>: Limitations of Texinfo macros. +<li><a href="#alias">alias</a>: Command aliases. +<li><a href="#definfoenclose">definfoenclose</a>: Customized highlighting. + +</li></ul> +<p>Formatting and Printing Hardcopy + +</p> +<ul class="menu"> +<li><a href="#Use-TeX">Use TeX</a>: Use TeX to format for hardcopy. +<li><a href="#Format-with-tex_002ftexindex">Format with tex/texindex</a>: How to format with explicit shell commands. +<li><a href="#Format-with-texi2dvi">Format with texi2dvi</a>: A simpler way to format. +<li><a href="#Print-with-lpr">Print with lpr</a>: How to print. +<li><a href="#Within-Emacs">Within Emacs</a>: How to format and print from an Emacs shell. +<li><a href="#Texinfo-Mode-Printing">Texinfo Mode Printing</a>: How to format and print in Texinfo mode. +<li><a href="#Compile_002dCommand">Compile-Command</a>: How to print using Emacs's compile command. +<li><a href="#Requirements-Summary">Requirements Summary</a>: TeX formatting requirements summary. +<li><a href="#Preparing-for-TeX">Preparing for TeX</a>: What to do before you use TeX. +<li><a href="#Overfull-hboxes">Overfull hboxes</a>: What are and what to do with overfull hboxes. +<li><a href="#smallbook">smallbook</a>: How to print small format books and manuals. +<li><a href="#A4-Paper">A4 Paper</a>: How to print on A4 or A5 paper. +<li><a href="#pagesizes">pagesizes</a>: How to print with customized page sizes. +<li><a href="#Cropmarks-and-Magnification">Cropmarks and Magnification</a>: How to print marks to indicate the size + of pages and how to print scaled up output. +<li><a href="#PDF-Output">PDF Output</a>: Portable Document Format output. +<li><a href="#Obtaining-TeX">Obtaining TeX</a>: How to Obtain TeX. + +</li></ul> +<p>Creating and Installing Info Files + +</p> +<ul class="menu"> +<li><a href="#Creating-an-Info-File">Creating an Info File</a> +<li><a href="#Installing-an-Info-File">Installing an Info File</a> + +</li></ul> +<p>Creating an Info File + +</p> +<ul class="menu"> +<li><a href="#makeinfo-advantages">makeinfo advantages</a>: <code>makeinfo</code> provides better error checking. +<li><a href="#Invoking-makeinfo">Invoking makeinfo</a>: How to run <code>makeinfo</code> from a shell. +<li><a href="#makeinfo-options">makeinfo options</a>: Specify fill-column and other options. +<li><a href="#Pointer-Validation">Pointer Validation</a>: How to check that pointers point somewhere. +<li><a href="#makeinfo-in-Emacs">makeinfo in Emacs</a>: How to run <code>makeinfo</code> from Emacs. +<li><a href="#texinfo_002dformat-commands">texinfo-format commands</a>: Two Info formatting commands written + in Emacs Lisp are an alternative + to <code>makeinfo</code>. +<li><a href="#Batch-Formatting">Batch Formatting</a>: How to format for Info in Emacs Batch mode. +<li><a href="#Tag-and-Split-Files">Tag and Split Files</a>: How tagged and split files help Info + to run better. + +</li></ul> +<p>Installing an Info File + +</p> +<ul class="menu"> +<li><a href="#Directory-File">Directory File</a>: The top level menu for all Info files. +<li><a href="#New-Info-File">New Info File</a>: Listing a new Info file. +<li><a href="#Other-Info-Directories">Other Info Directories</a>: How to specify Info files that are + located in other directories. +<li><a href="#Installing-Dir-Entries">Installing Dir Entries</a>: How to specify what menu entry to add + to the Info directory. +<li><a href="#Invoking-install_002dinfo">Invoking install-info</a>: <code>install-info</code> options. + +</li></ul> +<p>Generating HTML + +</p> +<ul class="menu"> +<li><a href="#HTML-Translation">HTML Translation</a>: Details of the HTML output. +<li><a href="#HTML-Splitting">HTML Splitting</a>: How HTML output is split. +<li><a href="#HTML-CSS">HTML CSS</a>: Influencing HTML output with Cascading Style Sheets. +<li><a href="#HTML-Xref">HTML Xref</a>: Cross-references in HTML output. + +</li></ul> +<p>HTML Cross-references + +</p> +<ul class="menu"> +<li><a href="#HTML-Xref-Link-Basics">Link Basics</a> +<li><a href="#HTML-Xref-Node-Name-Expansion">Node Expansion</a> +<li><a href="#HTML-Xref-Command-Expansion">Command Expansion</a> +<li><a href="#HTML-Xref-8_002dbit-Character-Expansion">8-bit Expansion</a> +<li><a href="#HTML-Xref-Mismatch">Mismatch</a> + +</li></ul> +<p>@-Command List + +</p> +<ul class="menu"> +<li><a href="#Command-Syntax">Command Syntax</a>: General syntax for varieties of @-commands. + +</li></ul> +<p>Sample Texinfo Files + +</p> +<ul class="menu"> +<li><a href="#Short-Sample-Texinfo-File">Short Sample Texinfo File</a> +<li><a href="#GNU-Sample-Texts">GNU Sample Texts</a> +<li><a href="#Verbatim-Copying-License">Verbatim Copying License</a> +<li><a href="#All_002dpermissive-Copying-License">All-permissive Copying License</a> + +</li></ul> +<p>Copying This Manual + +</p> +<ul class="menu"> +<li><a href="#GNU-Free-Documentation-License">GNU Free Documentation License</a>: License for copying this manual. + +</li></ul> +<p>Include Files + +</p> +<ul class="menu"> +<li><a href="#Using-Include-Files">Using Include Files</a>: How to use the <code>@include</code> command. +<li><a href="#texinfo_002dmultiple_002dfiles_002dupdate">texinfo-multiple-files-update</a>: How to create and update nodes and + menus when using included files. +<li><a href="#Include-Files-Requirements">Include Files Requirements</a>: <code>texinfo-multiple-files-update</code> needs. +<li><a href="#Sample-Include-File">Sample Include File</a>: A sample outer file with included files + within it; and a sample included file. +<li><a href="#Include-Files-Evolution">Include Files Evolution</a>: How use of the <code>@include</code> command + has changed over time. + +</li></ul> +<p>Page Headings + +</p> +<ul class="menu"> +<li><a href="#Headings-Introduced">Headings Introduced</a>: Conventions for using page headings. +<li><a href="#Heading-Format">Heading Format</a>: Standard page heading formats. +<li><a href="#Heading-Choice">Heading Choice</a>: How to specify the type of page heading. +<li><a href="#Custom-Headings">Custom Headings</a>: How to create your own headings and footings. + +</li></ul> +<p>Formatting Mistakes + +</p> +<ul class="menu"> +<li><a href="#makeinfo-Preferred">makeinfo Preferred</a>: <code>makeinfo</code> finds errors. +<li><a href="#Debugging-with-Info">Debugging with Info</a>: How to catch errors with Info formatting. +<li><a href="#Debugging-with-TeX">Debugging with TeX</a>: How to catch errors with TeX formatting. +<li><a href="#Using-texinfo_002dshow_002dstructure">Using texinfo-show-structure</a>: How to use <code>texinfo-show-structure</code>. +<li><a href="#Using-occur">Using occur</a>: How to list all lines containing a pattern. +<li><a href="#Running-Info_002dValidate">Running Info-Validate</a>: How to find badly referenced nodes. + +</li></ul> +<p>Finding Badly Referenced Nodes + +</p> +<ul class="menu"> +<li><a href="#Using-Info_002dvalidate">Using Info-validate</a>: How to run <code>Info-validate</code>. +<li><a href="#Unsplit">Unsplit</a>: How to create an unsplit file. +<li><a href="#Tagifying">Tagifying</a>: How to tagify a file. +<li><a href="#Splitting">Splitting</a>: How to split a file manually. + +</li></ul> +<p>Copying This Manual + +</p> +<ul class="menu"> +<li><a href="#GNU-Free-Documentation-License">GNU Free Documentation License</a>: License for copying this manual. + + </ul> + +<!-- Reward readers for getting to the end of the menu :). --> +<!-- Contributed by Arnold Robbins. --> +<blockquote> +Documentation is like sex: when it is good, it is very, very good; and +when it is bad, it is better than nothing. +—Dick Brandon +</blockquote> + +<div class="node"> +<p><hr> +<a name="Copying-Conditions"></a>Next: <a rel="next" accesskey="n" href="#Overview">Overview</a>, +Previous: <a rel="previous" accesskey="p" href="#Top">Top</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> +<br> +</div> + +<h2 class="unnumbered">Texinfo Copying Conditions</h2> + +<p><a name="index-Copying-conditions-1"></a><a name="index-Conditions-for-copying-Texinfo-2"></a> +The programs currently being distributed that relate to Texinfo include +<code>makeinfo</code>, <code>info</code>, <code>texindex</code>, and <span class="file">texinfo.tex</span>. +These programs are <dfn>free</dfn>; this means that everyone is free to use +them and free to redistribute them on a free basis. The Texinfo-related +programs are not in the public domain; they are copyrighted and there +are restrictions on their distribution, but these restrictions are +designed to permit everything that a good cooperating citizen would want +to do. What is not allowed is to try to prevent others from further +sharing any version of these programs that they might get from you. + + <p>Specifically, we want to make sure that you have the right to give away +copies of the programs that relate to Texinfo, that you receive source +code or else can get it if you want it, that you can change these +programs or use pieces of them in new free programs, and that you know +you can do these things. + + <p>To make sure that everyone has such rights, we have to forbid you to +deprive anyone else of these rights. For example, if you distribute +copies of the Texinfo related programs, you must give the recipients all +the rights that you have. You must make sure that they, too, receive or +can get the source code. And you must tell them their rights. + + <p>Also, for our own protection, we must make certain that everyone finds +out that there is no warranty for the programs that relate to Texinfo. +If these programs are modified by someone else and passed on, we want +their recipients to know that what they have is not what we distributed, +so that any problems introduced by others will not reflect on our +reputation. + + <p>The precise conditions of the licenses for the programs currently being +distributed that relate to Texinfo are found in the General Public +Licenses that accompany them. This manual specifically is covered by +the GNU Free Documentation License (see <a href="#GNU-Free-Documentation-License">GNU Free Documentation License</a>). + +<div class="node"> +<p><hr> +<a name="Overview"></a>Next: <a rel="next" accesskey="n" href="#Texinfo-Mode">Texinfo Mode</a>, +Previous: <a rel="previous" accesskey="p" href="#Copying-Conditions">Copying Conditions</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> +<br> +</div> + +<h2 class="chapter">1 Overview of Texinfo</h2> + +<p><a name="index-Overview-of-Texinfo-3"></a><a name="index-Texinfo-overview-4"></a> +<dfn>Texinfo</dfn><a rel="footnote" href="#fn-1" name="fnd-1"><sup>1</sup></a> is a documentation system that uses a single +source file to produce both online information and printed output. This +means that instead of writing two different documents, one for the +online information and the other for a printed work, you need write only +one document. Therefore, when the work is revised, you need revise only +that one document. + +<ul class="menu"> +<li><a accesskey="1" href="#Reporting-Bugs">Reporting Bugs</a>: Submitting effective bug reports. +<li><a accesskey="2" href="#Using-Texinfo">Using Texinfo</a>: Create printed or online output. +<li><a accesskey="3" href="#Output-Formats">Output Formats</a>: Overview of the supported output formats. +<li><a accesskey="4" href="#Info-Files">Info Files</a>: What is an Info file? +<li><a accesskey="5" href="#Printed-Books">Printed Books</a>: Characteristics of a printed book or manual. +<li><a accesskey="6" href="#Formatting-Commands">Formatting Commands</a>: @-commands are used for formatting. +<li><a accesskey="7" href="#Conventions">Conventions</a>: General rules for writing a Texinfo file. +<li><a accesskey="8" href="#Comments">Comments</a>: Writing comments and ignored text in general. +<li><a accesskey="9" href="#Minimum">Minimum</a>: What a Texinfo file must have. +<li><a href="#Six-Parts">Six Parts</a>: Usually, a Texinfo file has six parts. +<li><a href="#Short-Sample">Short Sample</a>: A short sample Texinfo file. +<li><a href="#History">History</a>: Acknowledgements, contributors and genesis. +</ul> + +<div class="node"> +<p><hr> +<a name="Reporting-Bugs"></a>Next: <a rel="next" accesskey="n" href="#Using-Texinfo">Using Texinfo</a>, +Up: <a rel="up" accesskey="u" href="#Overview">Overview</a> +<br> +</div> + +<h3 class="section">1.1 Reporting Bugs</h3> + +<p><a name="index-Bugs_002c-reporting-5"></a><a name="index-Suggestions-for-Texinfo_002c-making-6"></a><a name="index-Reporting-bugs-7"></a>We welcome bug reports and suggestions for any aspect of the Texinfo system, +programs, documentation, installation, anything. Please email them to +<a href="mailto:bug-texinfo@gnu.org">bug-texinfo@gnu.org</a>. You can get the latest version of Texinfo +from <a href="ftp://ftp.gnu.org/gnu/texinfo/">ftp://ftp.gnu.org/gnu/texinfo/</a> and its mirrors worldwide. + + <p><a name="index-Checklist-for-bug-reports-8"></a>For bug reports, please include enough information for the maintainers +to reproduce the problem. Generally speaking, that means: + + <ul> +<li>the version number of Texinfo and the program(s) or manual(s) involved. +<li>hardware and operating system names and versions. +<li>the contents of any input files necessary to reproduce the bug. +<li>a description of the problem and samples of any erroneous output. +<li>any unusual options you gave to <span class="command">configure</span>. +<li>anything else that you think would be helpful. +</ul> + + <p>When in doubt whether something is needed or not, include it. It's +better to include too much than to leave out something important. + + <p><a name="index-Patches_002c-contributing-9"></a>Patches are most welcome; if possible, please make them with +<span class="samp">diff -c<!-- /@w --></span> (see <a href="diff.html#Top">Overview (Comparing and Merging Files)</a>) and include <span class="file">ChangeLog</span> entries (see <a href="emacs.html#Change-Log">Change Log (The GNU Emacs Manual)</a>). + + <p>When sending patches, if possible please do not encode or split them in +any way; it's much easier to deal with one plain text message, however +large, than many small ones. <a href="ftp://ftp.gnu.org/gnu/sharutils/">GNU shar</a> is a convenient way of packaging multiple and/or binary files +for email. + +<div class="node"> +<p><hr> +<a name="Using-Texinfo"></a>Next: <a rel="next" accesskey="n" href="#Output-Formats">Output Formats</a>, +Previous: <a rel="previous" accesskey="p" href="#Reporting-Bugs">Reporting Bugs</a>, +Up: <a rel="up" accesskey="u" href="#Overview">Overview</a> +<br> +</div> + +<h3 class="section">1.2 Using Texinfo</h3> + +<p><a name="index-Using-Texinfo-in-general-10"></a><a name="index-Texinfo_002c-introduction-to-11"></a><a name="index-Introduction-to-Texinfo-12"></a> +Using Texinfo, you can create a printed document (via the TeX +typesetting system) the normal features of a book, including chapters, +sections, cross references, and indices. From the same Texinfo source +file, you can create an Info file with special features to make +documentation browsing easy. You can also create from that same +source file an HTML output file suitable for use with a web browser, +or an XML file. See the next section (see <a href="#Output-Formats">Output Formats</a>) for +details and the exact commands to generate output from the source. + + <p>TeX works with virtually all printers; Info works with virtually all +computer terminals; the HTML output works with virtually all web +browsers. Thus Texinfo can be used by almost any computer user. + + <p><a name="index-Source-file-format-13"></a>A Texinfo source file is a plain <span class="sc">ascii</span> file containing text +interspersed with <dfn>@-commands</dfn> (words preceded by an <span class="samp">@</span>) +that tell the typesetting and formatting programs what to do. You can +edit a Texinfo file with any text editor, but it is especially +convenient to use GNU Emacs since that editor has a special mode, +called Texinfo mode, that provides various Texinfo-related features. +(See <a href="#Texinfo-Mode">Texinfo Mode</a>.) + + <p>You can use Texinfo to create both online help and printed manuals; +moreover, Texinfo is freely redistributable. For these reasons, Texinfo +is the official documentation format of the GNU project. More +information is available at the <a href="http://www.gnu.org/doc/">GNU documentation web page</a>. + +<div class="node"> +<p><hr> +<a name="Output-Formats"></a>Next: <a rel="next" accesskey="n" href="#Info-Files">Info Files</a>, +Previous: <a rel="previous" accesskey="p" href="#Using-Texinfo">Using Texinfo</a>, +Up: <a rel="up" accesskey="u" href="#Overview">Overview</a> +<br> +</div> + +<h3 class="section">1.3 Output Formats</h3> + +<p><a name="index-Output-formats-14"></a><a name="index-Back_002dend-output-formats-15"></a> +Here is a brief overview of the output formats currently supported by +Texinfo. + + <dl> +<dt>Info<dd><a name="index-Info-output-16"></a>(Generated via <span class="command">makeinfo</span>.) This format is essentially a +plain text transliteration of the Texinfo source. It adds a few +control characters to separate nodes and provide navigational +information for menus, cross-references, indices, and so on. See the +next section (see <a href="#Info-Files">Info Files</a>) for more details on this format. +The Emacs Info subsystem (see <a href="info.html#Top">Getting Started (Info)</a>), +and the standalone <span class="command">info</span> program (see <a href="info-stnd.html#Top">Info Standalone (GNU Info)</a>), among others, can read these +files. See <a href="#Creating-and-Installing-Info-Files">Creating and Installing Info Files</a>. + + <br><dt>Plain text<dd><a name="index-Plain-text-output-17"></a>(Generated via <span class="command">makeinfo --no-headers</span>.) This is almost the +same as Info output, except the navigational control characters are +omitted. + + <br><dt>HTML<dd><a name="index-HTML-output-18"></a><a name="index-W3-consortium-19"></a><a name="index-Mozilla-20"></a><a name="index-Lynx-21"></a><a name="index-Emacs_002dW3-22"></a>(Generated via <span class="command">makeinfo --html</span>.) This is the Hyper Text +Markup Language that has become the most commonly used language for +writing documents on the World Wide Web. Web browsers, such as +Mozilla, Lynx, and Emacs-W3, can render this language online. There +are many versions of HTML; <span class="command">makeinfo</span> tries to use a subset +of the language that can be interpreted by any common browser. For +details of the HTML language and much related information, see +<a href="http://www.w3.org/MarkUp/">http://www.w3.org/MarkUp/</a>. See <a href="#Generating-HTML">Generating HTML</a>. + + <br><dt>DVI<dd><a name="index-DVI-output-23"></a><a name="index-dvips-24"></a><a name="index-xdvi-25"></a>(Generated via <span class="command">texi2dvi</span>.) This DeVice Independent binary +format is output by the TeX typesetting program +(<a href="http://tug.org">http://tug.org</a>). This is then read by a DVI `driver', which +writes the actual device-specific commands that can be viewed or +printed, notably Dvips for translation to PostScript (see <a href="dvips.html#Invoking-Dvips">Invoking Dvips (Dvips)</a>) and Xdvi for viewing on an X display +(<a href="http://sourceforge.net/projects/xdvi/">http://sourceforge.net/projects/xdvi/</a>). See <a href="#Hardcopy">Hardcopy</a>. + + <p>Be aware that the Texinfo language is very different from and much +stricter than TeX's usual languages, plain TeX and LaTeX. +For more information on TeX in general, please see the book +<cite>TeX for the Impatient</cite>, available from +<a href="http://savannah.gnu.org/projects/teximpatient">http://savannah.gnu.org/projects/teximpatient</a>. + + <br><dt>PDF<dd><a name="index-PDF-output-26"></a><a name="index-Beebe_002c-Nelson-27"></a><a name="index-pdftex-28"></a>(Generated via <span class="command">texi2dvi --pdf</span>.) This format, based on +PostScript, was developed by Adobe Systems for document interchange. +It is intended to be platform-independent and easily viewable, among +other design goals; for a discussion, see +<a href="http://tug.org/tugboat/Articles/tb22-3/tb72beebeI.pdf">http://tug.org/tugboat/Articles/tb22-3/tb72beebeI.pdf</a>. Texinfo +uses the <span class="command">pdftex</span> program, a variant of TeX, to output pdf; +see <a href="http://tug.org/applications/pdftex">http://tug.org/applications/pdftex</a>. See <a href="#PDF-Output">PDF Output</a>. + + <br><dt>XML<dd><a name="index-XML-output-29"></a><a name="index-DTD_002c-for-Texinfo-XML-30"></a><a name="index-texinfo_002edtd-31"></a>(Generated via <span class="command">makeinfo --xml</span>.) XML is a generic syntax +specification usable for any sort of content (see, for example, +<a href="http://www.w3.org/XML/">http://www.w3.org/XML/</a>). The <span class="command">makeinfo</span> xml output, +unlike all the formats above, interprets very little of the Texinfo +source. Rather, it merely translates the Texinfo markup commands into +XML syntax, for processing by further XML tools. The particular +syntax output is defined in the file <span class="file">texinfo.dtd</span> included in +the Texinfo source distribution. + + <br><dt>Docbook<dd><a name="index-Docbook-output-32"></a>(Generated via <span class="command">makeinfo --docbook</span>.) This is an XML-based +format developed some years ago, primarily for technical +documentation. It therefore bears some resemblance, in broad +outlines, to Texinfo. See <a href="http://www.docbook.org">http://www.docbook.org</a>. If you want +to convert from Docbook <em>to</em> Texinfo, please see +<a href="http://docbook2X.sourceforge.net">http://docbook2X.sourceforge.net</a>. + + </dl> + + <p><a name="index-Man-page-output_002c-not-supported-33"></a>From time to time, proposals are made to generate traditional Unix man +pages from Texinfo source. However, because man pages have a very +strict conventional format, generating a good man page requires a +completely different source than the typical Texinfo applications of +writing a good user tutorial and/or a good reference manual. This +makes generating man pages incompatible with the Texinfo design goal +of not having to document the same information in different ways for +different output formats. You might as well just write the man page +directly. + + <p><a name="index-help2man-34"></a><a name="index-O_0027Dea_002c-Brendan-35"></a>Man pages still have their place, and if you wish to support them, you +may find the program <span class="command">help2man</span> to be useful; it generates a +traditional man page from the <span class="samp">--help</span> output of a program. In +fact, this is currently used to generate man pages for the programs in +the Texinfo distribution. It is GNU software written by Brendan +O'Dea, available from <a href="ftp://ftp.gnu.org/gnu/help2man/">ftp://ftp.gnu.org/gnu/help2man/</a>. + + <p><a name="index-Output-formats_002c-supporting-more-36"></a><a name="index-SGML_002dtools-output-format-37"></a>If you are a programmer and would like to contribute to the GNU project +by implementing additional output formats for Texinfo, that would be +excellent. But please do not write a separate translator texi2foo for +your favorite format foo! That is the hard way to do the job, and makes +extra work in subsequent maintenance, since the Texinfo language is +continually being enhanced and updated. Instead, the best approach is +modify <code>makeinfo</code> to generate the new format. + +<div class="node"> +<p><hr> +<a name="Info-Files"></a>Next: <a rel="next" accesskey="n" href="#Printed-Books">Printed Books</a>, +Previous: <a rel="previous" accesskey="p" href="#Output-Formats">Output Formats</a>, +Up: <a rel="up" accesskey="u" href="#Overview">Overview</a> +<br> +</div> + +<h3 class="section">1.4 Info Files</h3> + +<p><a name="index-Info-files-38"></a> +An Info file is a Texinfo file formatted so that the Info documentation +reading program can operate on it. (<code>makeinfo</code> +and <code>texinfo-format-buffer</code> are two commands that convert a Texinfo file +into an Info file.) + + <p>Info files are divided into pieces called <dfn>nodes</dfn>, each of which +contains the discussion of one topic. Each node has a name, and +contains both text for the user to read and pointers to other nodes, +which are identified by their names. The Info program displays one node +at a time, and provides commands with which the user can move to other +related nodes. + + <p>See <a href="info.html#Top">Top (GNU Info)</a>, for more information about using Info. + + <p>Each node of an Info file may have any number of child nodes that +describe subtopics of the node's topic. The names of child +nodes are listed in a <dfn>menu</dfn> within the parent node; this +allows you to use certain Info commands to move to one of the child +nodes. Generally, an Info file is organized like a book. If a node +is at the logical level of a chapter, its child nodes are at the level +of sections; likewise, the child nodes of sections are at the level +of subsections. + + <p>All the children of any one parent are linked together in a +bidirectional chain of `Next' and `Previous' pointers. The `Next' +pointer provides a link to the next section, and the `Previous' pointer +provides a link to the previous section. This means that all the nodes +that are at the level of sections within a chapter are linked together. +Normally the order in this chain is the same as the order of the +children in the parent's menu. Each child node records the parent node +name as its `Up' pointer. The last child has no `Next' pointer, and the +first child has the parent both as its `Previous' and as its `Up' +pointer.<a rel="footnote" href="#fn-2" name="fnd-2"><sup>2</sup></a> + + <p>The book-like structuring of an Info file into nodes that correspond +to chapters, sections, and the like is a matter of convention, not a +requirement. The `Up', `Previous', and `Next' pointers of a node can +point to any other nodes, and a menu can contain any other nodes. +Thus, the node structure can be any directed graph. But it is usually +more comprehensible to follow a structure that corresponds to the +structure of chapters and sections in a printed book or report. + + <p>In addition to menus and to `Next', `Previous', and `Up' pointers, Info +provides pointers of another kind, called references, that can be +sprinkled throughout the text. This is usually the best way to +represent links that do not fit a hierarchical structure. + + <p>Usually, you will design a document so that its nodes match the +structure of chapters and sections in the printed output. But +occasionally there are times when this is not right for the material +being discussed. Therefore, Texinfo uses separate commands to specify +the node structure for the Info file and the section structure for the +printed output. + + <p>Generally, you enter an Info file through a node that by convention is +named `Top'. This node normally contains just a brief summary of the +file's purpose, and a large menu through which the rest of the file is +reached. From this node, you can either traverse the file +systematically by going from node to node, or you can go to a specific +node listed in the main menu, or you can search the index menus and then +go directly to the node that has the information you want. Alternatively, +with the standalone Info program, you can specify specific menu items on +the command line (see <a href="info.html#Top">Top (Info)</a>). + + <p>If you want to read through an Info file in sequence, as if it were a +printed manual, you can hit <SPC> repeatedly, or you get the whole +file with the advanced Info command <kbd>g *</kbd>. (see <a href="info.html#Advanced">Advanced Info commands</a>.) + +<!-- !!! dir file may be located in one of many places: --> +<!-- /usr/local/emacs/info mentioned in info.c DEFAULT_INFOPATH --> +<!-- /usr/local/lib/emacs/info mentioned in info.c DEFAULT_INFOPATH --> +<!-- /usr/gnu/info mentioned in info.c DEFAULT_INFOPATH --> +<!-- /usr/local/info --> +<!-- /usr/local/lib/info --> +<p>The <span class="file">dir</span> file in the <span class="file">info</span> directory serves as the +departure point for the whole Info system. From it, you can reach the +`Top' nodes of each of the documents in a complete Info system. + + <p><a name="index-URI-syntax-for-Info-39"></a>If you wish to refer to an Info file in a URI, you can use the +(unofficial) syntax exemplified in the following. This works with +Emacs/W3, for example: +<pre class="example"> info:///usr/info/emacs#Dissociated%20Press + info:emacs#Dissociated%20Press + info://localhost/usr/info/emacs#Dissociated%20Press +</pre> + <p>The <span class="command">info</span> program itself does not follow URI's of any kind. + +<div class="node"> +<p><hr> +<a name="Printed-Books"></a>Next: <a rel="next" accesskey="n" href="#Formatting-Commands">Formatting Commands</a>, +Previous: <a rel="previous" accesskey="p" href="#Info-Files">Info Files</a>, +Up: <a rel="up" accesskey="u" href="#Overview">Overview</a> +<br> +</div> + +<h3 class="section">1.5 Printed Books</h3> + +<p><a name="index-Printed-book-and-manual-characteristics-40"></a><a name="index-Manual-characteristics_002c-printed-41"></a><a name="index-Book-characteristics_002c-printed-42"></a><a name="index-Texinfo-printed-book-characteristics-43"></a><a name="index-Characteristics_002c-printed-books-or-manuals-44"></a> +<a name="index-Knuth_002c-Donald-45"></a>A Texinfo file can be formatted and typeset as a printed book or manual. +To do this, you need TeX, a powerful, sophisticated typesetting +program written by Donald Knuth.<a rel="footnote" href="#fn-3" name="fnd-3"><sup>3</sup></a> + + <p>A Texinfo-based book is similar to any other typeset, printed work: it +can have a title page, copyright page, table of contents, and preface, +as well as chapters, numbered or unnumbered sections and subsections, +page headers, cross references, footnotes, and indices. + + <p>You can use Texinfo to write a book without ever having the intention +of converting it into online information. You can use Texinfo for +writing a printed novel, and even to write a printed memo, although +this latter application is not recommended since electronic mail is so +much easier. + + <p>TeX is a general purpose typesetting program. Texinfo provides a +file <span class="file">texinfo.tex</span> that contains information (definitions or +<dfn>macros</dfn>) that TeX uses when it typesets a Texinfo file. +(<span class="file">texinfo.tex</span> tells TeX how to convert the Texinfo @-commands +to TeX commands, which TeX can then process to create the typeset +document.) <span class="file">texinfo.tex</span> contains the specifications for printing +a document. You can get the latest version of <span class="file">texinfo.tex</span> from +<a href="ftp://ftp.gnu.org/gnu/texinfo/texinfo.tex">ftp://ftp.gnu.org/gnu/texinfo/texinfo.tex</a>. + + <p>In the United States, documents are most often printed on 8.5 inch by 11 +inch pages (216<span class="dmn">mm</span> by 280<span class="dmn">mm</span>); this is the default size. But +you can also print for 7 inch by 9.25 inch pages (178<span class="dmn">mm</span> by +235<span class="dmn">mm</span>, the <code>@smallbook</code> size; or on A4 or A5 size paper +(<code>@afourpaper</code>, <code>@afivepaper</code>). (See <a href="#smallbook">Printing “Small” Books</a>. Also, see <a href="#A4-Paper">Printing on A4 Paper</a>.) + + <p>By changing the parameters in <span class="file">texinfo.tex</span>, you can change the +size of the printed document. In addition, you can change the style in +which the printed document is formatted; for example, you can change the +sizes and fonts used, the amount of indentation for each paragraph, the +degree to which words are hyphenated, and the like. By changing the +specifications, you can make a book look dignified, old and serious, or +light-hearted, young and cheery. + + <p>TeX is freely distributable. It is written in a superset of Pascal +called WEB and can be compiled either in Pascal or (by using a +conversion program that comes with the TeX distribution) in C. +(See <a href="emacs.html#TeX-Mode">TeX Mode (The GNU Emacs Manual)</a>, for information +about TeX.) + + <p>TeX is very powerful and has a great many features. Because a +Texinfo file must be able to present information both on a +character-only terminal in Info form and in a typeset book, the +formatting commands that Texinfo supports are necessarily limited. + + <p>To get a copy of TeX, see +<a href="#Obtaining-TeX">How to Obtain TeX</a>. + +<div class="node"> +<p><hr> +<a name="Formatting-Commands"></a>Next: <a rel="next" accesskey="n" href="#Conventions">Conventions</a>, +Previous: <a rel="previous" accesskey="p" href="#Printed-Books">Printed Books</a>, +Up: <a rel="up" accesskey="u" href="#Overview">Overview</a> +<br> +</div> + +<h3 class="section">1.6 @-commands</h3> + +<p><a name="index-_0040_0040_002dcommands-46"></a><a name="index-Formatting-commands-47"></a> +In a Texinfo file, the commands that tell TeX how to typeset the +printed manual and tell <code>makeinfo</code> and +<code>texinfo-format-buffer</code> how to create an Info file are preceded +by <span class="samp">@</span>; they are called <dfn>@-commands</dfn>. For example, +<code>@node</code> is the command to indicate a node and <code>@chapter</code> +is the command to indicate the start of a chapter. + + <blockquote> +<b>Note:</b> Almost all @ command names are entirely lower case. +</blockquote> + + <p>The Texinfo @-commands are a strictly limited set of constructs. The +strict limits make it possible for Texinfo files to be understood both +by TeX and by the code that converts them into Info files. You can +display Info files on any terminal that displays alphabetic and +numeric characters. Similarly, you can print the output generated by +TeX on a wide variety of printers. + + <p>Depending on what they do or what arguments<a rel="footnote" href="#fn-4" name="fnd-4"><sup>4</sup></a> they take, you +need to write @-commands on lines of their own or as part of +sentences: + + <ul> +<li>Write a command such as <code>@quotation</code> at the beginning of a line as +the only text on the line. (<code>@quotation</code> begins an indented +environment.) + + <li>Write a command such as <code>@chapter</code> at the beginning of a line +followed by the command's arguments, in this case the chapter title, on +the rest of the line. (<code>@chapter</code> creates chapter titles.) + + <li>Write a command such as <code>@dots{}</code> wherever you wish but usually +within a sentence. (<code>@dots{}</code> creates dots <small class="dots">...</small>) + + <li>Write a command such as <code>@code{</code><var>sample-code</var><code>}</code> wherever you +wish (but usually within a sentence) with its argument, +<var>sample-code</var> in this example, between the braces. (<code>@code</code> +marks text as being code.) + + <li>Write a command such as <code>@example</code> on a line of its own; write the +body-text on following lines; and write the matching <code>@end</code> +command, <code>@end example</code> in this case, on a line of its own +after the body-text. (<code>@example</code> <small class="dots">...</small> <code>@end example</code> +indents and typesets body-text as an example.) It's usually ok to +indent environment commands like this, but in complicated and +hard-to-define circumstances the extra spaces cause extra space to +appear in the output, so beware. +</ul> + +<p class="noindent"><a name="index-Braces_002c-when-to-use-48"></a>As a general rule, a command requires braces if it mingles among other +text; but it does not need braces if it starts a line of its own. The +non-alphabetic commands, such as <code>@:</code>, are exceptions to the rule; +they do not need braces. + + <p>As you gain experience with Texinfo, you will rapidly learn how to +write the different commands: the different ways to write commands +actually make it easier to write and read Texinfo files than if all +commands followed exactly the same syntax. See <a href="#Command-Syntax">@-Command Syntax</a>, for all the details. + +<div class="node"> +<p><hr> +<a name="Conventions"></a>Next: <a rel="next" accesskey="n" href="#Comments">Comments</a>, +Previous: <a rel="previous" accesskey="p" href="#Formatting-Commands">Formatting Commands</a>, +Up: <a rel="up" accesskey="u" href="#Overview">Overview</a> +<br> +</div> + +<h3 class="section">1.7 General Syntactic Conventions</h3> + +<p><a name="index-General-syntactic-conventions-49"></a><a name="index-Syntactic-conventions-50"></a><a name="index-Conventions_002c-syntactic-51"></a><a name="index-Characters_002c-basic-input-52"></a> +This section describes the general conventions used in all Texinfo documents. + + <ul> +<li><a name="index-Source-files_002c-characters-used-53"></a>All printable <span class="sc">ascii</span> characters except <span class="samp">@</span>, <span class="samp">{</span> and +<span class="samp">}</span> can appear in a Texinfo file and stand for themselves. +<span class="samp">@</span> is the escape character which introduces commands, while +<span class="samp">{</span> and <span class="samp">}</span> are used to surround arguments to certain +commands. To put one of these special characters into the document, put +an <span class="samp">@</span> character in front of it, like this: <span class="samp">@@</span>, +<span class="samp">@{</span>, and <span class="samp">@}</span>. + + <li><a name="index-Paragraph-separator-54"></a><a name="index-Blank-lines_002c-as-paragraph-separator-55"></a><a name="index-Newlines_002c-as-blank-lines-56"></a>Separate paragraphs with one or more blank lines. Currently Texinfo +only recognizes newline characters as end of line, not the CRLF +sequence used on some systems; so a <dfn>blank line</dfn> means exactly two +consecutive newlines. Sometimes blank lines are useful or convenient +in other cases as well; you can use the <code>@noindent</code> to inhibit +paragraph indentation if required (see <a href="#noindent"><code>@noindent</code></a>). + + <li><a name="index-Quotation-characters-_0028_0060_0027_0029_002c-in-source-57"></a>Use doubled single-quote characters to begin and end quotations: +<tt>`<!-- /@w -->`<small class="dots">...</small>'<!-- /@w -->'</tt><!-- /@w -->. TeX converts two single quotes to +left- and right-hand doubled quotation marks, +<!-- this comes out as "like this" in Info, which is just confusing. --> +and Info converts doubled single-quote characters to <span class="sc">ascii</span> +double-quotes: <tt>`<!-- /@w -->`<small class="dots">...</small>'<!-- /@w -->'</tt><!-- /@w --> becomes <tt>"<small class="dots">...</small>"</tt><!-- /@w -->. + + <p>You may occasionally need to produce two consecutive single quotes; +for example, in documenting a computer language such as Maxima where +<tt>'<!-- /@w -->'</tt> is a valid command. You can do this with the input +<tt>'@w{}'</tt>; the empty <code>@w</code> command stops the combination into +the double-quote characters. + + <p><a name="index-Unicode-quotation-characters-58"></a><a name="index-Grave-accent_002c-vs_002e_0040_003a-left-quote-59"></a>The left quote character (<tt>`</tt>, ASCII code 96) used in Texinfo is a +grave accent in ANSI and ISO character set standards. We use it as a +quote character because that is how TeX is set up, by default. We +hope to eventually support the various quotation characters in +Unicode. + + <li><a name="index-Multiple-dashes-in-source-60"></a><a name="index-Dashes-in-source-61"></a><a name="index-Hyphens-in-source_002c-two-or-three-in-a-row-62"></a><a name="index-Em-dash_002c-producing-63"></a><a name="index-En-dash_002c-producing-64"></a>Use three hyphens in a row, <span class="samp">---</span>, to produce a long dash—like +this (called an <dfn>em dash</dfn>), used for punctuation in sentences. +Use two hyphens, <span class="samp">--</span>, to produce a medium dash–like this +(called an <dfn>en dash</dfn>), used to separate numeric ranges. Use a +single hyphen, <span class="samp">-</span>, to produce a standard hyphen used in compound +words. For display on the screen, Info reduces three hyphens to two +and two hyphens to one (not transitively!). Of course, any number of +hyphens in the source remain as they are in literal contexts, such as +<code>@code</code> and <code>@example</code>. + + <li><a name="index-Tabs_003b-don_0027t-use_0021-65"></a><strong>Caution:</strong> Last and most important, do not use tab characters +in a Texinfo file (except in verbatim modes)! TeX uses +variable-width fonts, which means that it is impractical at best to +define a tab to work in all circumstances. Consequently, TeX +treats tabs like single spaces, and that is not what they look like in +the source. Furthermore, <code>makeinfo</code> does nothing special with +tabs, and thus a tab character in your input file will usually appear +differently in the output. + + <p class="noindent">To avoid this problem, Texinfo mode causes GNU Emacs to insert multiple +spaces when you press the <TAB> key. + + <p class="noindent">Also, you can run <code>untabify</code> in Emacs to convert tabs in a region +to multiple spaces, or use the <code>unexpand</code> command from the shell. + + </ul> + +<div class="node"> +<p><hr> +<a name="Comments"></a>Next: <a rel="next" accesskey="n" href="#Minimum">Minimum</a>, +Previous: <a rel="previous" accesskey="p" href="#Conventions">Conventions</a>, +Up: <a rel="up" accesskey="u" href="#Overview">Overview</a> +<br> +</div> + +<h3 class="section">1.8 Comments</h3> + +<p><a name="index-Comments-66"></a><a name="index-comment-67"></a><a name="index-c-_0040r_007b_0028comment_0029_007d-68"></a> +You can write comments in a Texinfo file that will not appear in +either the Info file or the printed manual by using the +<code>@comment</code> command (which may be abbreviated to <code>@c</code>). +Such comments are for the person who revises the Texinfo file. All the +text on a line that follows either <code>@comment</code> or <code>@c</code> is a +comment; the rest of the line does not appear in either the Info file +or the printed manual. + + <p>Often, you can write the <code>@comment</code> or <code>@c</code> in the middle of +a line, and only the text that follows after the <code>@comment</code> or +<code>@c</code> command does not appear; but some commands, such as +<code>@settitle</code> and <code>@setfilename</code>, work on a whole line. You +cannot use <code>@comment</code> or <code>@c</code> in a line beginning with such +a command. + + <p><a name="index-Ignored-text-69"></a><a name="index-Unprocessed-text-70"></a><a name="index-ignore-71"></a>You can write long stretches of text that will not appear in either +the Info file or the printed manual by using the <code>@ignore</code> and +<code>@end ignore</code> commands. Write each of these commands on a line +of its own, starting each command at the beginning of the line. Text +between these two commands does not appear in the processed output. +You can use <code>@ignore</code> and <code>@end ignore</code> for writing +comments. + + <p>Text enclosed by <code>@ignore</code> or by failing <code>@ifset</code> or +<code>@ifclear</code> conditions is ignored in the sense that it will not +contribute to the formatted output. However, TeX and makeinfo must +still parse the ignored text, in order to understand when to <em>stop</em> +ignoring text from the source file; that means that you may still get +error messages if you have invalid Texinfo commands within ignored text. + +<div class="node"> +<p><hr> +<a name="Minimum"></a>Next: <a rel="next" accesskey="n" href="#Six-Parts">Six Parts</a>, +Previous: <a rel="previous" accesskey="p" href="#Comments">Comments</a>, +Up: <a rel="up" accesskey="u" href="#Overview">Overview</a> +<br> +</div> + +<h3 class="section">1.9 What a Texinfo File Must Have</h3> + +<p><a name="index-Minimal-Texinfo-file-_0028requirements_0029-72"></a><a name="index-Must-have-in-Texinfo-file-73"></a><a name="index-Required-in-Texinfo-file-74"></a><a name="index-Texinfo-file-minimum-75"></a> +By convention, the namea of a Texinfo file ends with (in order of +preference) one of the extensions <span class="file">.texinfo</span>, <span class="file">.texi</span>, +<span class="file">.txi</span>, or <span class="file">.tex</span>. The longer extensions are preferred since +they describe more clearly to a human reader the nature of the file. +The shorter extensions are for operating systems that cannot handle long +file names. + + <p>In order to be made into a printed manual and an Info file, a Texinfo +file <strong>must</strong> begin with lines like this: + +<pre class="example"> \input texinfo + @setfilename <var>info-file-name</var> + @settitle <var>name-of-manual</var> +</pre> + <p class="noindent">The contents of the file follow this beginning, and then you +<strong>must</strong> end a Texinfo file with a line like this: + +<pre class="example"> @bye +</pre> + <p><a name="index-_005cinput-_0040r_007b_0028raw-_0040TeX_007b_007d-startup_0029_007d-76"></a>Here's an explanation: + + <ul> +<li>The <span class="samp">\input texinfo</span> line tells TeX to use the +<span class="file">texinfo.tex</span> file, which tells TeX how to translate the Texinfo +@-commands into TeX typesetting commands. (Note the use of the +backslash, <span class="samp">\</span>; this is correct for TeX.) + + <li>The <code>@setfilename</code> line provides a name for the Info file and +tells TeX to open auxiliary files. <strong>All text before +</strong><code>@setfilename</code><strong> is ignored!</strong> + + <li>The <code>@settitle</code> line specifies a title for the page headers (or +footers) of the printed manual, and the default document description for +the <span class="samp"><head></span> in HTML format. Strictly speaking, <code>@settitle</code> +is optional—if you don't mind your document being titled `Untitled'. + + <li>The <code>@bye</code> line at the end of the file on a line of its own tells +the formatters that the file is ended and to stop formatting. + + </ul> + + <p>Typically, you will not use quite such a spare format, but will include +mode setting and start-of-header and end-of-header lines at the +beginning of a Texinfo file, like this: + +<pre class="example"> \input texinfo @c -*-texinfo-*- + @c %**start of header + @setfilename <var>info-file-name</var> + @settitle <var>name-of-manual</var> + @c %**end of header +</pre> + <p class="noindent">In the first line, <span class="samp">-*-texinfo-*-</span> causes Emacs to switch into +Texinfo mode when you edit the file. + + <p>The <code>@c</code> lines which surround the <code>@setfilename</code> and +<code>@settitle</code> lines are optional, but you need them in order to +run TeX or Info on just part of the file. (See <a href="#Start-of-Header">Start of Header</a>.) + + <p>Furthermore, you will usually provide a Texinfo file with a title page, +indices, and the like, all of which are explained in this manual. But +the minimum, which can be useful for short documents, is just the three +lines at the beginning and the one line at the end. + +<div class="node"> +<p><hr> +<a name="Six-Parts"></a>Next: <a rel="next" accesskey="n" href="#Short-Sample">Short Sample</a>, +Previous: <a rel="previous" accesskey="p" href="#Minimum">Minimum</a>, +Up: <a rel="up" accesskey="u" href="#Overview">Overview</a> +<br> +</div> + +<h3 class="section">1.10 Six Parts of a Texinfo File</h3> + +<p>Generally, a Texinfo file contains more than the minimal beginning and +end described in the previous section—it usually contains the six +parts listed below. These are described fully in the following sections. + + <dl> +<dt><span class="roman">1. Header</span><dd>The <dfn>Header</dfn> names the file, tells TeX which definitions file to +use, and other such housekeeping tasks. + + <br><dt><span class="roman">2. Summary and Copyright</span><dd>The <dfn>Summary and Copyright</dfn> segment describes the document and +contains the copyright notice and copying permissions. This is done +with the <code>@copying</code> command. + + <br><dt><span class="roman">3. Title and Copyright</span><dd>The <dfn>Title and Copyright</dfn> segment contains the title and copyright +pages for the printed manual. The segment must be enclosed between +<code>@titlepage</code> and <code>@end titlepage</code> commands. The title and +copyright page appear only in the printed manual. + + <br><dt><span class="roman">4. `Top' Node and Master Menu</span><dd>The `Top' node starts off the online output; it does not appear in the +printed manual. We recommend including the copying permissions here as +well as the segments above. And it contains at least a top-level menu +listing the chapters, and possibly a <dfn>Master Menu</dfn> listing all the +nodes in the entire document. + + <br><dt><span class="roman">5. Body</span><dd>The <dfn>Body</dfn> of the document is typically structured like a +traditional book or encyclopedia, but it may be free form. + + <br><dt><span class="roman">6. End</span><dd>The <dfn>End</dfn> segment contains commands for printing indices and +generating the table of contents, and the <code>@bye</code> command on a line +of its own. +</dl> + +<div class="node"> +<p><hr> +<a name="Short-Sample"></a>Next: <a rel="next" accesskey="n" href="#History">History</a>, +Previous: <a rel="previous" accesskey="p" href="#Six-Parts">Six Parts</a>, +Up: <a rel="up" accesskey="u" href="#Overview">Overview</a> +<br> +</div> + +<h3 class="section">1.11 A Short Sample Texinfo File</h3> + +<p><a name="index-Sample-Texinfo-file_002c-with-comments-77"></a> +Here is a very short but complete Texinfo file, in the six conventional +parts enumerated in the previous section, so you can see how Texinfo +source appears in practice. The first three parts of the file, from +<span class="samp">\input texinfo</span> through to <span class="samp">@end titlepage</span>, look more +intimidating than they are: most of the material is standard +boilerplate; when writing a manual, you simply change the names as +appropriate. + + <p>See <a href="#Beginning-a-File">Beginning a File</a>, for full documentation on the commands listed +here. See <a href="#GNU-Sample-Texts">GNU Sample Texts</a>, for the full texts to be used in GNU +manuals. + + <p>In the following, the sample text is <em>indented</em>; comments on it are +not. The complete file, without interspersed comments, is shown in +<a href="#Short-Sample-Texinfo-File">Short Sample Texinfo File</a>. + +<h4 class="subheading">Part 1: Header</h4> + +<p class="noindent">The header does not appear in either the Info file or the +printed output. It sets various parameters, including the +name of the Info file and the title used in the header. + +<pre class="example"> \input texinfo @c -*-texinfo-*- + @c %**start of header + @setfilename sample.info + @settitle Sample Manual 1.0 + @c %**end of header +</pre> + <h4 class="subheading">Part 2: Summary Description and Copyright</h4> + +<p class="noindent">A real manual includes more text here, according to the license under +which it is distributed. See <a href="#GNU-Sample-Texts">GNU Sample Texts</a>. + +<pre class="example"> @copying + This is a short example of a complete Texinfo file, version 1.0. + + Copyright @copyright{} 2004 Free Software Foundation, Inc. + @end copying +</pre> + <h4 class="subheading">Part 3: Titlepage, Contents, Copyright</h4> + +<p class="noindent">The titlepage segment does not appear in the online output, only in the +printed manual. We use the <code>@insertcopying</code> command to +include the permission text from the previous section, instead of +writing it out again; it is output on the back of the title page. The +<code>@contents</code> command generates a table of contents. + +<pre class="example"> @titlepage + @title Sample Title + + @c The following two commands start the copyright page. + @page + @vskip 0pt plus 1filll + @insertcopying + @end titlepage + + @c Output the table of contents at the beginning. + @contents +</pre> + <h4 class="subheading">Part 4: `Top' Node and Master Menu</h4> + +<p class="noindent">The `Top' node contains the master menu for the Info file. Since the +printed manual uses a table of contents rather than a menu, it +excludes the `Top' node. We also include the copying text again for +the benefit of online readers. Since the copying text begins with +a brief description of the manual, no other text is needed in this +case. The <span class="samp">@top</span> command itself helps <span class="command">makeinfo</span> +determine the relationships between nodes. + +<pre class="example"> @ifnottex + @node Top + @top Short Sample + + @insertcopying + @end ifnottex + + @menu + * First Chapter:: The first chapter is the + only chapter in this sample. + * Index:: Complete index. + @end menu +</pre> + <h4 class="subheading">Part 5: The Body of the Document</h4> + +<p class="noindent">The body segment contains all the text of the document, but not the +indices or table of contents. This example illustrates a node and a +chapter containing an enumerated list. + +<pre class="example"> @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 +</pre> + <h4 class="subheading">Part 6: The End of the Document</h4> + +<p class="noindent">The end segment contains commands for generating an index in a node and +unnumbered chapter of its own, and the <code>@bye</code> command that marks +the end of the document. + +<pre class="example"> @node Index + @unnumbered Index + + @printindex cp + + @bye +</pre> + <h4 class="subheading">Some Results</h4> + +<p>Here is what the contents of the first chapter of the sample look like: + + <pre class="sp"> + +</pre> +<blockquote> +This is the first chapter. + + <p>Here is a numbered list. + + <ol type=1 start=1> +<li>This is the first item. + + <li>This is the second item. + </ol> +</blockquote> + +<div class="node"> +<p><hr> +<a name="History"></a>Previous: <a rel="previous" accesskey="p" href="#Short-Sample">Short Sample</a>, +Up: <a rel="up" accesskey="u" href="#Overview">Overview</a> +<br> +</div> + +<h3 class="section">1.12 History</h3> + +<p><a name="index-Stallman_002c-Richard-M_002e-78"></a><a name="index-Chassell_002c-Robert-J_002e-79"></a><a name="index-Fox_002c-Brian-80"></a><a name="index-Berry_002c-Karl-81"></a>Richard M. Stallman invented the Texinfo format, wrote the initial +processors, and created Edition 1.0 of this manual. Robert J.<!-- /@w --> +Chassell greatly revised and extended the manual, starting with Edition +1.1. Brian Fox was responsible for the standalone Texinfo distribution +until version 3.8, and wrote the standalone <span class="command">makeinfo</span> and +<span class="command">info</span> programs. Karl Berry has continued maintenance since +Texinfo 3.8 (manual edition 2.22). + + <p><a name="index-Pinard_002c-Fran_0040_002c_007bc_007dois-82"></a><a name="index-Zuhn_002c-David-D_002e-83"></a><a name="index-Weisshaus_002c-Melissa-84"></a><a name="index-Zaretskii_002c-Eli-85"></a><a name="index-Schwab_002c-Andreas-86"></a><a name="index-Weinberg_002c-Zack-87"></a>Our thanks go out to all who helped improve this work, particularly the +indefatigable Eli Zaretskii and Andreas Schwab, who have provided +patches beyond counting. François Pinard and David D. Zuhn<!-- /@w -->, +tirelessly recorded and reported mistakes and obscurities. Zack +Weinberg did the impossible by implementing the macro syntax in +<span class="file">texinfo.tex</span>. Special thanks go to Melissa Weisshaus for her +frequent reviews of nearly similar editions. Dozens of others have +contributed patches and suggestions, they are gratefully acknowledged in +the <span class="file">ChangeLog</span> file. Our mistakes are our own. + + <p><a name="index-Scribe-88"></a><a name="index-Reid_002c-Brian-89"></a><a name="index-History-of-Texinfo-90"></a><a name="index-Texinfo-history-91"></a>A bit of history: in the 1970's at CMU, Brian Reid developed a program +and format named Scribe to mark up documents for printing. It used the +<code>@</code> character to introduce commands, as Texinfo does. Much more +consequentially, it strived to describe document contents rather than +formatting, an idea wholeheartedly adopted by Texinfo. + + <p><a name="index-Bolio-92"></a><a name="index-Bo_0040TeX_007b_007d-93"></a>Meanwhile, people at MIT developed another, not too dissimilar format +called Bolio. This then was converted to using TeX as its typesetting +language: BoTeX. The earliest BoTeX version seems to have been +0.02 on October 31, 1984. + + <p>BoTeX could only be used as a markup language for documents to be +printed, not for online documents. Richard Stallman (RMS) worked on +both Bolio and BoTeX. He also developed a nifty on-line help format +called Info, and then combined BoTeX and Info to create Texinfo, a +mark up language for text that is intended to be read both online and +as printed hard copy. + +<div class="node"> +<p><hr> +<a name="Texinfo-Mode"></a>Next: <a rel="next" accesskey="n" href="#Beginning-a-File">Beginning a File</a>, +Previous: <a rel="previous" accesskey="p" href="#Overview">Overview</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> +<br> +</div> + +<h2 class="chapter">2 Using Texinfo Mode</h2> + +<p><a name="index-Texinfo-mode-94"></a><a name="index-Mode_002c-using-Texinfo-95"></a><a name="index-GNU-Emacs-96"></a><a name="index-Emacs-97"></a> +You may edit a Texinfo file with any text editor you choose. A Texinfo +file is no different from any other <span class="sc">ascii</span> file. However, GNU Emacs +comes with a special mode, called Texinfo mode, that provides Emacs +commands and tools to help ease your work. + + <p>This chapter describes features of GNU Emacs' Texinfo mode but not any +features of the Texinfo formatting language. So if you are reading this +manual straight through from the beginning, you may want to skim through +this chapter briefly and come back to it after reading succeeding +chapters which describe the Texinfo formatting language in detail. + +<ul class="menu"> +<li><a accesskey="1" href="#Texinfo-Mode-Overview">Texinfo Mode Overview</a>: How Texinfo mode can help you. +<li><a accesskey="2" href="#Emacs-Editing">Emacs Editing</a>: Texinfo mode adds to GNU Emacs' general + purpose editing features. +<li><a accesskey="3" href="#Inserting">Inserting</a>: How to insert frequently used @-commands. +<li><a accesskey="4" href="#Showing-the-Structure">Showing the Structure</a>: How to show the structure of a file. +<li><a accesskey="5" href="#Updating-Nodes-and-Menus">Updating Nodes and Menus</a>: How to update or create new nodes and menus. +<li><a accesskey="6" href="#Info-Formatting">Info Formatting</a>: How to format for Info. +<li><a accesskey="7" href="#Printing">Printing</a>: How to format and print part or all of a file. +<li><a accesskey="8" href="#Texinfo-Mode-Summary">Texinfo Mode Summary</a>: Summary of all the Texinfo mode commands. +</ul> + +<div class="node"> +<p><hr> +<a name="Texinfo-Mode-Overview"></a>Next: <a rel="next" accesskey="n" href="#Emacs-Editing">Emacs Editing</a>, +Up: <a rel="up" accesskey="u" href="#Texinfo-Mode">Texinfo Mode</a> +<br> +</div> + +<h3 class="section">2.1 Texinfo Mode Overview</h3> + +<p>Texinfo mode provides special features for working with Texinfo files. +You can: + + <ul> +<li>Insert frequently used @-commands. + + <li>Automatically create <code>@node</code> lines. + + <li>Show the structure of a Texinfo source file. + + <li>Automatically create or update the `Next', +`Previous', and `Up' pointers of a node. + + <li>Automatically create or update menus. + + <li>Automatically create a master menu. + + <li>Format a part or all of a file for Info. + + <li>Typeset and print part or all of a file. +</ul> + + <p>Perhaps the two most helpful features are those for inserting frequently +used @-commands and for creating node pointers and menus. + +<div class="node"> +<p><hr> +<a name="Emacs-Editing"></a>Next: <a rel="next" accesskey="n" href="#Inserting">Inserting</a>, +Previous: <a rel="previous" accesskey="p" href="#Texinfo-Mode-Overview">Texinfo Mode Overview</a>, +Up: <a rel="up" accesskey="u" href="#Texinfo-Mode">Texinfo Mode</a> +<br> +</div> + +<h3 class="section">2.2 The Usual GNU Emacs Editing Commands</h3> + +<p>In most cases, the usual Text mode commands work the same in Texinfo +mode as they do in Text mode. Texinfo mode adds new editing commands +and tools to GNU Emacs' general purpose editing features. The major +difference concerns filling. In Texinfo mode, the paragraph +separation variable and syntax table are redefined so that Texinfo +commands that should be on lines of their own are not inadvertently +included in paragraphs. Thus, the <kbd>M-q</kbd> (<code>fill-paragraph</code>) +command will refill a paragraph but not mix an indexing command on a +line adjacent to it into the paragraph. + + <p>In addition, Texinfo mode sets the <code>page-delimiter</code> variable to +the value of <code>texinfo-chapter-level-regexp</code>; by default, this is +a regular expression matching the commands for chapters and their +equivalents, such as appendices. With this value for the page +delimiter, you can jump from chapter title to chapter title with the +<kbd>C-x ]</kbd> (<code>forward-page</code>) and <kbd>C-x [</kbd> +(<code>backward-page</code>) commands and narrow to a chapter with the +<kbd>C-x p</kbd> (<code>narrow-to-page</code>) command. (See <a href="emacs.html#Pages">Pages (The GNU Emacs Manual)</a>, for details about the page commands.) + + <p>You may name a Texinfo file however you wish, but the convention is to +end a Texinfo file name with one of the extensions +<span class="file">.texinfo</span>, <span class="file">.texi</span>, <span class="file">.txi</span>, or <span class="file">.tex</span>. A longer +extension is preferred, since it is explicit, but a shorter extension +may be necessary for operating systems that limit the length of file +names. GNU Emacs automatically enters Texinfo mode when you visit a +file with a <span class="file">.texinfo</span>, <span class="file">.texi</span> or <span class="file">.txi</span> +extension. Also, Emacs switches to Texinfo mode +when you visit a +file that has <span class="samp">-*-texinfo-*-</span> in its first line. If ever you are +in another mode and wish to switch to Texinfo mode, type <code>M-x +texinfo-mode</code>. + + <p>Like all other Emacs features, you can customize or enhance Texinfo +mode as you wish. In particular, the keybindings are very easy to +change. The keybindings described here are the default or standard +ones. + +<div class="node"> +<p><hr> +<a name="Inserting"></a>Next: <a rel="next" accesskey="n" href="#Showing-the-Structure">Showing the Structure</a>, +Previous: <a rel="previous" accesskey="p" href="#Emacs-Editing">Emacs Editing</a>, +Up: <a rel="up" accesskey="u" href="#Texinfo-Mode">Texinfo Mode</a> +<br> +</div> + +<!-- node-name, next, previous, up --> +<h3 class="section">2.3 Inserting Frequently Used Commands</h3> + +<p><a name="index-Inserting-frequently-used-commands-98"></a><a name="index-Frequently-used-commands_002c-inserting-99"></a><a name="index-Commands_002c-inserting-them-100"></a> +Texinfo mode provides commands to insert various frequently used +@-commands into the buffer. You can use these commands to save +keystrokes. + + <p>The insert commands are invoked by typing <kbd>C-c</kbd> twice and then the +first letter of the @-command: + + <dl> +<dt><kbd>C-c C-c c</kbd><dt><kbd>M-x texinfo-insert-@code</kbd><dd><a name="index-texinfo_002dinsert_002d_0040_0040code-101"></a>Insert <code>@code{}</code> and put the +cursor between the braces. + + <br><dt><kbd>C-c C-c d</kbd><dt><kbd>M-x texinfo-insert-@dfn</kbd><dd><a name="index-texinfo_002dinsert_002d_0040_0040dfn-102"></a>Insert <code>@dfn{}</code> and put the +cursor between the braces. + + <br><dt><kbd>C-c C-c e</kbd><dt><kbd>M-x texinfo-insert-@end</kbd><dd><a name="index-texinfo_002dinsert_002d_0040_0040end-103"></a>Insert <code>@end</code> and attempt to insert the correct following word, +such as <span class="samp">example</span> or <span class="samp">table</span>. (This command does not handle +nested lists correctly, but inserts the word appropriate to the +immediately preceding list.) + + <br><dt><kbd>C-c C-c i</kbd><dt><kbd>M-x texinfo-insert-@item</kbd><dd><a name="index-texinfo_002dinsert_002d_0040_0040item-104"></a>Insert <code>@item</code> and put the +cursor at the beginning of the next line. + + <br><dt><kbd>C-c C-c k</kbd><dt><kbd>M-x texinfo-insert-@kbd</kbd><dd><a name="index-texinfo_002dinsert_002d_0040_0040kbd-105"></a>Insert <code>@kbd{}</code> and put the +cursor between the braces. + + <br><dt><kbd>C-c C-c n</kbd><dt><kbd>M-x texinfo-insert-@node</kbd><dd><a name="index-texinfo_002dinsert_002d_0040_0040node-106"></a>Insert <code>@node</code> and a comment line +listing the sequence for the `Next', +`Previous', and `Up' nodes. +Leave point after the <code>@node</code>. + + <br><dt><kbd>C-c C-c o</kbd><dt><kbd>M-x texinfo-insert-@noindent</kbd><dd><a name="index-texinfo_002dinsert_002d_0040_0040noindent-107"></a>Insert <code>@noindent</code> and put the +cursor at the beginning of the next line. + + <br><dt><kbd>C-c C-c s</kbd><dt><kbd>M-x texinfo-insert-@samp</kbd><dd><a name="index-texinfo_002dinsert_002d_0040_0040samp-108"></a>Insert <code>@samp{}</code> and put the +cursor between the braces. + + <br><dt><kbd>C-c C-c t</kbd><dt><kbd>M-x texinfo-insert-@table</kbd><dd><a name="index-texinfo_002dinsert_002d_0040_0040table-109"></a>Insert <code>@table</code> followed by a <SPC> +and leave the cursor after the <SPC>. + + <br><dt><kbd>C-c C-c v</kbd><dt><kbd>M-x texinfo-insert-@var</kbd><dd><a name="index-texinfo_002dinsert_002d_0040_0040var-110"></a>Insert <code>@var{}</code> and put the +cursor between the braces. + + <br><dt><kbd>C-c C-c x</kbd><dt><kbd>M-x texinfo-insert-@example</kbd><dd><a name="index-texinfo_002dinsert_002d_0040_0040example-111"></a>Insert <code>@example</code> and put the +cursor at the beginning of the next line. + + <!-- M-@{ was the binding for texinfo-insert-braces; --> +<!-- in Emacs 19, backward-paragraph will take this binding. --> +<br><dt><kbd>C-c C-c {</kbd><dt><kbd>M-x texinfo-insert-braces</kbd><dd><a name="index-texinfo_002dinsert_002dbraces-112"></a>Insert <code>{}</code> and put the cursor between the braces. + + <br><dt><kbd>C-c C-c }</kbd><dt><kbd>C-c C-c ]</kbd><dt><kbd>M-x up-list</kbd><dd><a name="index-up_002dlist-113"></a>Move from between a pair of braces forward past the closing brace. +Typing <kbd>C-c C-c ]</kbd> is easier than typing <kbd>C-c C-c }</kbd>, which +is, however, more mnemonic; hence the two keybindings. (Also, you can +move out from between braces by typing <kbd>C-f</kbd>.) +</dl> + + <p>To put a command such as <code>@code{...}</code><!-- /@w --> around an +<em>existing</em> word, position the cursor in front of the word and type +<kbd>C-u 1 C-c C-c c</kbd>. This makes it easy to edit existing plain text. +The value of the prefix argument tells Emacs how many words following +point to include between braces—<span class="samp">1</span> for one word, <span class="samp">2</span> for +two words, and so on. Use a negative argument to enclose the previous +word or words. If you do not specify a prefix argument, Emacs inserts +the @-command string and positions the cursor between the braces. This +feature works only for those @-commands that operate on a word or words +within one line, such as <code>@kbd</code> and <code>@var</code>. + + <p>This set of insert commands was created after analyzing the frequency +with which different @-commands are used in the <cite>GNU Emacs +Manual</cite> and the <cite>GDB Manual</cite>. If you wish to add your own insert +commands, you can bind a keyboard macro to a key, use abbreviations, +or extend the code in <span class="file">texinfo.el</span>. + + <p><a name="index-texinfo_002dstart_002dmenu_002ddescription-114"></a><a name="index-Menu-description_002c-start-115"></a><a name="index-Description-for-menu_002c-start-116"></a><kbd>C-c C-c C-d</kbd> (<code>texinfo-start-menu-description</code>) is an insert +command that works differently from the other insert commands. It +inserts a node's section or chapter title in the space for the +description in a menu entry line. (A menu entry has three parts, the +entry name, the node name, and the description. Only the node name is +required, but a description helps explain what the node is about. +See <a href="#Menu-Parts">The Parts of a Menu</a>.) + + <p>To use <code>texinfo-start-menu-description</code>, position point in a menu +entry line and type <kbd>C-c C-c C-d</kbd>. The command looks for and copies +the title that goes with the node name, and inserts the title as a +description; it positions point at beginning of the inserted text so you +can edit it. The function does not insert the title if the menu entry +line already contains a description. + + <p>This command is only an aid to writing descriptions; it does not do the +whole job. You must edit the inserted text since a title tends to use +the same words as a node name but a useful description uses different +words. + +<div class="node"> +<p><hr> +<a name="Showing-the-Structure"></a>Next: <a rel="next" accesskey="n" href="#Updating-Nodes-and-Menus">Updating Nodes and Menus</a>, +Previous: <a rel="previous" accesskey="p" href="#Inserting">Inserting</a>, +Up: <a rel="up" accesskey="u" href="#Texinfo-Mode">Texinfo Mode</a> +<br> +</div> + +<!-- node-name, next, previous, up --> +<h3 class="section">2.4 Showing the Section Structure of a File</h3> + +<p><a name="index-Showing-the-section-structure-of-a-file-117"></a><a name="index-Section-structure-of-a-file_002c-showing-it-118"></a><a name="index-Structure-of-a-file_002c-showing-it-119"></a><a name="index-Outline-of-file-structure_002c-showing-it-120"></a><a name="index-Contents_002dlike-outline-of-file-structure-121"></a><a name="index-File-section-structure_002c-showing-it-122"></a><a name="index-Texinfo-file-section-structure_002c-showing-it-123"></a> +You can show the section structure of a Texinfo file by using the +<kbd>C-c C-s</kbd> command (<code>texinfo-show-structure</code>). This command +shows the section structure of a Texinfo file by listing the lines +that begin with the @-commands for <code>@chapter</code>, +<code>@section</code>, and the like. It constructs what amounts +to a table of contents. These lines are displayed in another buffer +called the <span class="samp">*Occur*</span> buffer. In that buffer, you can position +the cursor over one of the lines and use the <kbd>C-c C-c</kbd> command +(<code>occur-mode-goto-occurrence</code>), to jump to the corresponding spot +in the Texinfo file. + + <dl> +<dt><kbd>C-c C-s</kbd><dt><kbd>M-x texinfo-show-structure</kbd><dd><a name="index-texinfo_002dshow_002dstructure-124"></a>Show the <code>@chapter</code>, <code>@section</code>, and such lines of a +Texinfo file. + + <br><dt><kbd>C-c C-c</kbd><dt><kbd>M-x occur-mode-goto-occurrence</kbd><dd><a name="index-occur_002dmode_002dgoto_002doccurrence-125"></a>Go to the line in the Texinfo file corresponding to the line under the +cursor in the <span class="file">*Occur*</span> buffer. +</dl> + + <p>If you call <code>texinfo-show-structure</code> with a prefix argument by +typing <kbd>C-u C-c C-s</kbd><!-- /@w -->, it will list not only those lines with the +@-commands for <code>@chapter</code>, <code>@section</code>, and the like, but +also the <code>@node</code> lines. You can use <code>texinfo-show-structure</code> +with a prefix argument to check whether the `Next', `Previous', and `Up' +pointers of an <code>@node</code> line are correct. + + <p>Often, when you are working on a manual, you will be interested only +in the structure of the current chapter. In this case, you can mark +off the region of the buffer that you are interested in by using the +<kbd>C-x n n</kbd> (<code>narrow-to-region</code>) command and +<code>texinfo-show-structure</code> will work on only that region. To see +the whole buffer again, use <kbd>C-x n w</kbd><!-- /@w --> (<code>widen</code>). +(See <a href="emacs.html#Narrowing">Narrowing (The GNU Emacs Manual)</a>, for more +information about the narrowing commands.) + + <p><a name="index-page_002ddelimiter-126"></a><a name="index-Page-delimiter-in-Texinfo-mode-127"></a>In addition to providing the <code>texinfo-show-structure</code> command, +Texinfo mode sets the value of the page delimiter variable to match +the chapter-level @-commands. This enables you to use the <kbd>C-x +]</kbd> (<code>forward-page</code>) and <kbd>C-x [</kbd> (<code>backward-page</code>) +commands to move forward and backward by chapter, and to use the +<kbd>C-x p</kbd> (<code>narrow-to-page</code>) command to narrow to a chapter. +See <a href="emacs.html#Pages">Pages (The GNU Emacs Manual)</a>, for more information +about the page commands. + +<div class="node"> +<p><hr> +<a name="Updating-Nodes-and-Menus"></a>Next: <a rel="next" accesskey="n" href="#Info-Formatting">Info Formatting</a>, +Previous: <a rel="previous" accesskey="p" href="#Showing-the-Structure">Showing the Structure</a>, +Up: <a rel="up" accesskey="u" href="#Texinfo-Mode">Texinfo Mode</a> +<br> +</div> + +<!-- node-name, next, previous, up --> +<h3 class="section">2.5 Updating Nodes and Menus</h3> + +<p><a name="index-Updating-nodes-and-menus-128"></a><a name="index-Create-nodes_002c-menus-automatically-129"></a><a name="index-Insert-nodes_002c-menus-automatically-130"></a><a name="index-Automatically-insert-nodes_002c-menus-131"></a> +Texinfo mode provides commands for automatically creating or updating +menus and node pointers. The commands are called “update” commands +because their most frequent use is for updating a Texinfo file after you +have worked on it; but you can use them to insert the `Next', +`Previous', and `Up' pointers into an <code>@node</code> line that has none +and to create menus in a file that has none. + + <p>If you do not use the updating commands, you need to write menus and +node pointers by hand, which is a tedious task. + +<ul class="menu"> +<li><a accesskey="1" href="#Updating-Commands">Updating Commands</a>: Five major updating commands. +<li><a accesskey="2" href="#Updating-Requirements">Updating Requirements</a>: How to structure a Texinfo file for + using the updating command. +<li><a accesskey="3" href="#Other-Updating-Commands">Other Updating Commands</a>: How to indent descriptions, insert + missing nodes lines, and update + nodes in sequence. +</ul> + +<div class="node"> +<p><hr> +<a name="Updating-Commands"></a>Next: <a rel="next" accesskey="n" href="#Updating-Requirements">Updating Requirements</a>, +Up: <a rel="up" accesskey="u" href="#Updating-Nodes-and-Menus">Updating Nodes and Menus</a> +<br> +</div> + +<h4 class="subsection">2.5.1 The Updating Commands</h4> + +<p>You can use the updating commands to: + + <ul> +<li>insert or update the `Next', `Previous', and `Up' pointers of a +node, + + <li>insert or update the menu for a section, and + + <li>create a master menu for a Texinfo source file. +</ul> + + <p>You can also use the commands to update all the nodes and menus in a +region or in a whole Texinfo file. + + <p>The updating commands work only with conventional Texinfo files, which +are structured hierarchically like books. In such files, a structuring +command line must follow closely after each <code>@node</code> line, except +for the `Top' <code>@node</code> line. (A <dfn>structuring command line</dfn> is +a line beginning with <code>@chapter</code>, <code>@section</code>, or other +similar command.) + + <p>You can write the structuring command line on the line that follows +immediately after an <code>@node</code> line or else on the line that +follows after a single <code>@comment</code> line or a single +<code>@ifinfo</code> line. You cannot interpose more than one line between +the <code>@node</code> line and the structuring command line; and you may +interpose only an <code>@comment</code> line or an <code>@ifinfo</code> line. + + <p>Commands which work on a whole buffer require that the `Top' node be +followed by a node with an <code>@chapter</code> or equivalent-level command. +The menu updating commands will not create a main or master menu for a +Texinfo file that has only <code>@chapter</code>-level nodes! The menu +updating commands only create menus <em>within</em> nodes for lower level +nodes. To create a menu of chapters, you must provide a `Top' +node. + + <p>The menu updating commands remove menu entries that refer to other Info +files since they do not refer to nodes within the current buffer. This +is a deficiency. Rather than use menu entries, you can use cross +references to refer to other Info files. None of the updating commands +affect cross references. + + <p>Texinfo mode has five updating commands that are used most often: two +are for updating the node pointers or menu of a single node (or a +region); two are for updating every node pointer and menu in a file; +and one, the <code>texinfo-master-menu</code> command, is for creating a +master menu for a complete file, and optionally, for updating every +node and menu in the whole Texinfo file. + + <p>The <code>texinfo-master-menu</code> command is the primary command: + + <dl> +<dt><kbd>C-c C-u m</kbd><dt><kbd>M-x texinfo-master-menu</kbd><dd><a name="index-texinfo_002dmaster_002dmenu-132"></a>Create or update a master menu that includes all the other menus +(incorporating the descriptions from pre-existing menus, if +any). + + <p>With an argument (prefix argument, <kbd>C-u,</kbd> if interactive), first create or +update all the nodes and all the regular menus in the buffer before +constructing the master menu. (See <a href="#The-Top-Node">The Top Node and Master Menu</a>, for more about a master menu.) + + <p>For <code>texinfo-master-menu</code> to work, the Texinfo file must have a +`Top' node and at least one subsequent node. + + <p>After extensively editing a Texinfo file, you can type the following: + + <pre class="example"> C-u M-x texinfo-master-menu + <br>or<br> + C-u C-c C-u m + </pre> + <p class="noindent">This updates all the nodes and menus completely and all at once. +</dl> + + <p>The other major updating commands do smaller jobs and are designed for +the person who updates nodes and menus as he or she writes a Texinfo +file. + + <p>The commands are: + + <dl> +<dt><kbd>C-c C-u C-n</kbd><dt><kbd>M-x texinfo-update-node</kbd><dd><a name="index-texinfo_002dupdate_002dnode-133"></a>Insert the `Next', `Previous', and `Up' pointers for the node that point is +within (i.e., for the <code>@node</code> line preceding point). If the +<code>@node</code> line has pre-existing `Next', `Previous', or `Up' +pointers in it, the old pointers are removed and new ones inserted. +With an argument (prefix argument, <kbd>C-u</kbd>, if interactive), this command +updates all <code>@node</code> lines in the region (which is the text +between point and mark). + + <br><dt><kbd>C-c C-u C-m</kbd><dt><kbd>M-x texinfo-make-menu</kbd><dd><a name="index-texinfo_002dmake_002dmenu-134"></a>Create or update the menu in the node that point is within. +With an argument (<kbd>C-u</kbd> as prefix argument, if +interactive), the command makes or updates menus for the +nodes which are either within or a part of the +region. + + <p>Whenever <code>texinfo-make-menu</code> updates an existing menu, the +descriptions from that menu are incorporated into the new menu. This +is done by copying descriptions from the existing menu to the entries +in the new menu that have the same node names. If the node names are +different, the descriptions are not copied to the new menu. + + <br><dt><kbd>C-c C-u C-e</kbd><dt><kbd>M-x texinfo-every-node-update</kbd><dd><a name="index-texinfo_002devery_002dnode_002dupdate-135"></a>Insert or update the `Next', `Previous', and `Up' pointers for every +node in the buffer. + + <br><dt><kbd>C-c C-u C-a</kbd><dt><kbd>M-x texinfo-all-menus-update</kbd><dd><a name="index-texinfo_002dall_002dmenus_002dupdate-136"></a>Create or update all the menus in the buffer. With an argument +(<kbd>C-u</kbd> as prefix argument, if interactive), first insert +or update all the node +pointers before working on the menus. + + <p>If a master menu exists, the <code>texinfo-all-menus-update</code> command +updates it; but the command does not create a new master menu if none +already exists. (Use the <code>texinfo-master-menu</code> command for +that.) + + <p>When working on a document that does not merit a master menu, you can +type the following: + + <pre class="example"> C-u C-c C-u C-a + <br>or<br> + C-u M-x texinfo-all-menus-update + </pre> + <p class="noindent">This updates all the nodes and menus. +</dl> + + <p>The <code>texinfo-column-for-description</code> variable specifies the +column to which menu descriptions are indented. By default, the value +is 32 although it is often useful to reduce it to as low as 24. You +can set the variable via customization (see <a href="emacs.html#Changing-an-Option">Changing an Option (The GNU Emacs Manual)</a>) or with the <kbd>M-x set-variable</kbd> +command (see <a href="emacs.html#Examining">Examining and Setting Variables (The GNU Emacs Manual)</a>). + + <p>Also, the <code>texinfo-indent-menu-description</code> command may be used to +indent existing menu descriptions to a specified column. Finally, if +you wish, you can use the <code>texinfo-insert-node-lines</code> command to +insert missing <code>@node</code> lines into a file. (See <a href="#Other-Updating-Commands">Other Updating Commands</a>, for more information.) + +<div class="node"> +<p><hr> +<a name="Updating-Requirements"></a>Next: <a rel="next" accesskey="n" href="#Other-Updating-Commands">Other Updating Commands</a>, +Previous: <a rel="previous" accesskey="p" href="#Updating-Commands">Updating Commands</a>, +Up: <a rel="up" accesskey="u" href="#Updating-Nodes-and-Menus">Updating Nodes and Menus</a> +<br> +</div> + +<h4 class="subsection">2.5.2 Updating Requirements</h4> + +<p><a name="index-Updating-requirements-137"></a><a name="index-Requirements-for-updating-commands-138"></a> +To use the updating commands, you must organize the Texinfo file +hierarchically with chapters, sections, subsections, and the like. +When you construct the hierarchy of the manual, do not `jump down' +more than one level at a time: you can follow the `Top' node with a +chapter, but not with a section; you can follow a chapter with a +section, but not with a subsection. However, you may `jump up' any +number of levels at one time—for example, from a subsection to a +chapter. + + <p>Each <code>@node</code> line, with the exception of the line for the `Top' +node, must be followed by a line with a structuring command such as +<code>@chapter</code>, <code>@section</code>, or +<code>@unnumberedsubsec</code>. + + <p>Each <code>@node</code> line/structuring-command line combination +must look either like this: + +<pre class="example"> @node Comments, Minimum, Conventions, Overview + @comment node-name, next, previous, up + @section Comments +</pre> + <p>or like this (without the <code>@comment</code> line): + +<pre class="example"> @node Comments, Minimum, Conventions, Overview + @section Comments +</pre> + <p>or like this (without the explicit node pointers): + +<pre class="example"> @node Comments + @section Comments +</pre> + <p class="noindent">In this example, `Comments' is the name of both the node and the +section. The next node is called `Minimum' and the previous node is +called `Conventions'. The `Comments' section is within the `Overview' +node, which is specified by the `Up' pointer. (Instead of an +<code>@comment</code> line, you may also write an <code>@ifinfo</code> line.) + + <p>If a file has a `Top' node, it must be called <span class="samp">top</span> or <span class="samp">Top</span> +and be the first node in the file. + + <p>The menu updating commands create a menu of sections within a chapter, +a menu of subsections within a section, and so on. This means that +you must have a `Top' node if you want a menu of chapters. + + <p>Incidentally, the <code>makeinfo</code> command will create an Info file for a +hierarchically organized Texinfo file that lacks `Next', `Previous' and +`Up' pointers. Thus, if you can be sure that your Texinfo file will be +formatted with <code>makeinfo</code>, you have no need for the update node +commands. (See <a href="#Creating-an-Info-File">Creating an Info File</a>, for more information about +<code>makeinfo</code>.) However, both <code>makeinfo</code> and the +<code>texinfo-format-...</code> commands require that you insert menus in +the file. + +<div class="node"> +<p><hr> +<a name="Other-Updating-Commands"></a>Previous: <a rel="previous" accesskey="p" href="#Updating-Requirements">Updating Requirements</a>, +Up: <a rel="up" accesskey="u" href="#Updating-Nodes-and-Menus">Updating Nodes and Menus</a> +<br> +</div> + +<h4 class="subsection">2.5.3 Other Updating Commands</h4> + +<p>In addition to the five major updating commands, Texinfo mode +possesses several less frequently used updating commands: + + <dl> +<dt><kbd>M-x texinfo-insert-node-lines</kbd><dd><a name="index-texinfo_002dinsert_002dnode_002dlines-139"></a>Insert <code>@node</code> lines before the <code>@chapter</code>, +<code>@section</code>, and other sectioning commands wherever they are +missing throughout a region in a Texinfo file. + + <p>With an argument (<kbd>C-u</kbd> as prefix argument, if interactive), the +<code>texinfo-insert-node-lines</code> command not only inserts +<code>@node</code> lines but also inserts the chapter or section titles as +the names of the corresponding nodes. In addition, it inserts the +titles as node names in pre-existing <code>@node</code> lines that lack +names. Since node names should be more concise than section or +chapter titles, you must manually edit node names so inserted. + + <p>For example, the following marks a whole buffer as a region and inserts +<code>@node</code> lines and titles throughout: + + <pre class="example"> C-x h C-u M-x texinfo-insert-node-lines + </pre> + <p>This command inserts titles as node names in <code>@node</code> lines; the +<code>texinfo-start-menu-description</code> command (see <a href="#Inserting">Inserting Frequently Used Commands</a>) inserts titles as descriptions in +menu entries, a different action. However, in both cases, you need to +edit the inserted text. + + <br><dt><kbd>M-x texinfo-multiple-files-update</kbd><dd><a name="index-texinfo_002dmultiple_002dfiles_002dupdate-_0040r_007b_0028in-brief_0029_007d-140"></a>Update nodes and menus in a document built from several separate files. +With <kbd>C-u</kbd> as a prefix argument, create and insert a master menu in +the outer file. With a numeric prefix argument, such as <kbd>C-u 2</kbd>, first +update all the menus and all the `Next', `Previous', and `Up' pointers +of all the included files before creating and inserting a master menu in +the outer file. The <code>texinfo-multiple-files-update</code> command is +described in the appendix on <code>@include</code> files. +See <a href="#texinfo_002dmultiple_002dfiles_002dupdate">texinfo-multiple-files-update</a>. + + <br><dt><kbd>M-x texinfo-indent-menu-description</kbd><dd><a name="index-texinfo_002dindent_002dmenu_002ddescription-141"></a>Indent every description in the menu following point to the specified +column. You can use this command to give yourself more space for +descriptions. With an argument (<kbd>C-u</kbd> as prefix argument, if +interactive), the <code>texinfo-indent-menu-description</code> command indents +every description in every menu in the region. However, this command +does not indent the second and subsequent lines of a multi-line +description. + + <br><dt><kbd>M-x texinfo-sequential-node-update</kbd><dd><a name="index-texinfo_002dsequential_002dnode_002dupdate-142"></a>Insert the names of the nodes immediately following and preceding the +current node as the `Next' or `Previous' pointers regardless of those +nodes' hierarchical level. This means that the `Next' node of a +subsection may well be the next chapter. Sequentially ordered nodes are +useful for novels and other documents that you read through +sequentially. (However, in Info, the <kbd>g *</kbd> command lets +you look through the file sequentially, so sequentially ordered nodes +are not strictly necessary.) With an argument (prefix argument, if +interactive), the <code>texinfo-sequential-node-update</code> command +sequentially updates all the nodes in the region. +</dl> + +<div class="node"> +<p><hr> +<a name="Info-Formatting"></a>Next: <a rel="next" accesskey="n" href="#Printing">Printing</a>, +Previous: <a rel="previous" accesskey="p" href="#Updating-Nodes-and-Menus">Updating Nodes and Menus</a>, +Up: <a rel="up" accesskey="u" href="#Texinfo-Mode">Texinfo Mode</a> +<br> +</div> + +<!-- node-name, next, previous, up --> +<h3 class="section">2.6 Formatting for Info</h3> + +<p><a name="index-Formatting-for-Info-143"></a><a name="index-Running-an-Info-formatter-144"></a><a name="index-Info-formatting-145"></a> +Texinfo mode provides several commands for formatting part or all of a +Texinfo file for Info. Often, when you are writing a document, you +want to format only part of a file—that is, a region. + + <p>You can use either the <code>texinfo-format-region</code> or the +<code>makeinfo-region</code> command to format a region: + + +<a name="index-texinfo_002dformat_002dregion-146"></a> +<dl><dt><kbd>C-c C-e C-r</kbd><dt><kbd>M-x texinfo-format-region</kbd><dt><kbd>C-c C-m C-r</kbd><dt><kbd>M-x makeinfo-region</kbd><dd>Format the current region for Info. +</dl> + + <p>You can use either the <code>texinfo-format-buffer</code> or the +<code>makeinfo-buffer</code> command to format a whole buffer: + + +<a name="index-texinfo_002dformat_002dbuffer-147"></a> +<dl><dt><kbd>C-c C-e C-b</kbd><dt><kbd>M-x texinfo-format-buffer</kbd><dt><kbd>C-c C-m C-b</kbd><dt><kbd>M-x makeinfo-buffer</kbd><dd>Format the current buffer for Info. +</dl> + + <p>For example, after writing a Texinfo file, you can type the following: + +<pre class="example"> C-u C-c C-u m +<br>or<br> + C-u M-x texinfo-master-menu +</pre> + <p class="noindent">This updates all the nodes and menus. Then type the following to create +an Info file: + +<pre class="example"> C-c C-m C-b +<br>or<br> + M-x makeinfo-buffer +</pre> + <p>For TeX or the Info formatting commands to work, the file <em>must</em> +include a line that has <code>@setfilename</code> in its header. + + <p>See <a href="#Creating-an-Info-File">Creating an Info File</a>, for details about Info formatting. + +<div class="node"> +<p><hr> +<a name="Printing"></a>Next: <a rel="next" accesskey="n" href="#Texinfo-Mode-Summary">Texinfo Mode Summary</a>, +Previous: <a rel="previous" accesskey="p" href="#Info-Formatting">Info Formatting</a>, +Up: <a rel="up" accesskey="u" href="#Texinfo-Mode">Texinfo Mode</a> +<br> +</div> + +<!-- node-name, next, previous, up --> +<h3 class="section">2.7 Printing</h3> + +<p><a name="index-Formatting-for-printing-148"></a><a name="index-Printing-a-region-or-buffer-149"></a><a name="index-Region-formatting-and-printing-150"></a><a name="index-Buffer-formatting-and-printing-151"></a><a name="index-Part-of-file-formatting-and-printing-152"></a> +Typesetting and printing a Texinfo file is a multi-step process in which +you first create a file for printing (called a DVI file), and then +print the file. Optionally, you may also create indices. To do this, +you must run the <code>texindex</code> command after first running the +<code>tex</code> typesetting command; and then you must run the <code>tex</code> +command again. Or else run the <code>texi2dvi</code> command which +automatically creates indices as needed (see <a href="#Format-with-texi2dvi">Format with texi2dvi</a>). + + <p>Often, when you are writing a document, you want to typeset and print +only part of a file to see what it will look like. You can use the +<code>texinfo-tex-region</code> and related commands for this purpose. Use +the <code>texinfo-tex-buffer</code> command to format all of a +buffer. + + <dl> +<dt><kbd>C-c C-t C-b</kbd><dt><kbd>M-x texinfo-tex-buffer</kbd><dd><a name="index-texinfo_002dtex_002dbuffer-153"></a>Run <code>texi2dvi</code> on the buffer. In addition to running TeX on the +buffer, this command automatically creates or updates indices as +needed. + + <br><dt><kbd>C-c C-t C-r</kbd><dt><kbd>M-x texinfo-tex-region</kbd><dd><a name="index-texinfo_002dtex_002dregion-154"></a>Run TeX on the region. + + <br><dt><kbd>C-c C-t C-i</kbd><dt><kbd>M-x texinfo-texindex</kbd><dd>Run <code>texindex</code> to sort the indices of a Texinfo file formatted with +<code>texinfo-tex-region</code>. The <code>texinfo-tex-region</code> command does +not run <code>texindex</code> automatically; it only runs the <code>tex</code> +typesetting command. You must run the <code>texinfo-tex-region</code> command +a second time after sorting the raw index files with the <code>texindex</code> +command. (Usually, you do not format an index when you format a region, +only when you format a buffer. Now that the <code>texi2dvi</code> command +exists, there is little or no need for this command.) + + <br><dt><kbd>C-c C-t C-p</kbd><dt><kbd>M-x texinfo-tex-print</kbd><dd><a name="index-texinfo_002dtex_002dprint-155"></a>Print the file (or the part of the file) previously formatted with +<code>texinfo-tex-buffer</code> or <code>texinfo-tex-region</code>. +</dl> + + <p>For <code>texinfo-tex-region</code> or <code>texinfo-tex-buffer</code> to work, the +file <em>must</em> start with a <span class="samp">\input texinfo</span> line and must +include an <code>@settitle</code> line. The file must end with <code>@bye</code> +on a line by itself. (When you use <code>texinfo-tex-region</code>, you must +surround the <code>@settitle</code> line with start-of-header and +end-of-header lines.) + + <p>See <a href="#Hardcopy">Hardcopy</a>, for a description of the other TeX related +commands, such as <code>tex-show-print-queue</code>. + +<div class="node"> +<p><hr> +<a name="Texinfo-Mode-Summary"></a>Previous: <a rel="previous" accesskey="p" href="#Printing">Printing</a>, +Up: <a rel="up" accesskey="u" href="#Texinfo-Mode">Texinfo Mode</a> +<br> +</div> + +<!-- node-name, next, previous, up --> +<h3 class="section">2.8 Texinfo Mode Summary</h3> + +<p>In Texinfo mode, each set of commands has default keybindings that +begin with the same keys. All the commands that are custom-created +for Texinfo mode begin with <kbd>C-c</kbd>. The keys are somewhat +mnemonic. + +<h4 class="subheading">Insert Commands</h4> + +<p>The insert commands are invoked by typing <kbd>C-c</kbd> twice and then the +first letter of the @-command to be inserted. (It might make more +sense mnemonically to use <kbd>C-c C-i</kbd>, for `custom insert', but +<kbd>C-c C-c</kbd> is quick to type.) + +<pre class="example"> C-c C-c c <span class="roman">Insert</span> <span class="samp">@code</span>. + C-c C-c d <span class="roman">Insert</span> <span class="samp">@dfn</span>. + C-c C-c e <span class="roman">Insert</span> <span class="samp">@end</span>. + C-c C-c i <span class="roman">Insert</span> <span class="samp">@item</span>. + C-c C-c n <span class="roman">Insert</span> <span class="samp">@node</span>. + C-c C-c s <span class="roman">Insert</span> <span class="samp">@samp</span>. + C-c C-c v <span class="roman">Insert</span> <span class="samp">@var</span>. + C-c C-c { <span class="roman">Insert braces.</span> + C-c C-c ] + C-c C-c } <span class="roman">Move out of enclosing braces.</span> + + C-c C-c C-d <span class="roman">Insert a node's section title</span> + <span class="roman">in the space for the description</span> + <span class="roman">in a menu entry line.</span> +</pre> + <h4 class="subheading">Show Structure</h4> + +<p>The <code>texinfo-show-structure</code> command is often used within a +narrowed region. + +<pre class="example"> C-c C-s <span class="roman">List all the headings.</span> +</pre> + <h4 class="subheading">The Master Update Command</h4> + +<p>The <code>texinfo-master-menu</code> command creates a master menu; and can +be used to update every node and menu in a file as well. + +<!-- Probably should use @tables in this section. --> +<pre class="example"> C-c C-u m + M-x texinfo-master-menu + <span class="roman">Create or update a master menu.</span> + + C-u C-c C-u m <span class="roman">With </span><kbd>C-u</kbd><span class="roman"> as a prefix argument, first</span> + <span class="roman">create or update all nodes and regular</span> + <span class="roman">menus, and then create a master menu.</span> +</pre> + <h4 class="subheading">Update Pointers</h4> + +<p>The update pointer commands are invoked by typing <kbd>C-c C-u</kbd> and +then either <kbd>C-n</kbd> for <code>texinfo-update-node</code> or <kbd>C-e</kbd> for +<code>texinfo-every-node-update</code>. + +<pre class="example"> C-c C-u C-n <span class="roman">Update a node.</span> + C-c C-u C-e <span class="roman">Update every node in the buffer.</span> +</pre> + <h4 class="subheading">Update Menus</h4> + +<p>Invoke the update menu commands by typing <kbd>C-c C-u</kbd> +and then either <kbd>C-m</kbd> for <code>texinfo-make-menu</code> or +<kbd>C-a</kbd> for <code>texinfo-all-menus-update</code>. To update +both nodes and menus at the same time, precede <kbd>C-c C-u +C-a</kbd> with <kbd>C-u</kbd>. + +<pre class="example"> C-c C-u C-m <span class="roman">Make or update a menu.</span> + + C-c C-u C-a <span class="roman">Make or update all</span> + <span class="roman">menus in a buffer.</span> + + C-u C-c C-u C-a <span class="roman">With </span><kbd>C-u</kbd><span class="roman"> as a prefix argument,</span> + <span class="roman">first create or update all nodes and</span> + <span class="roman">then create or update all menus.</span> +</pre> + <h4 class="subheading">Format for Info</h4> + +<p>The Info formatting commands that are written in Emacs Lisp are +invoked by typing <kbd>C-c C-e</kbd> and then either <kbd>C-r</kbd> for a region +or <kbd>C-b</kbd> for the whole buffer. + + <p>The Info formatting commands that are written in C and based on the +<code>makeinfo</code> program are invoked by typing <kbd>C-c C-m</kbd> and then +either <kbd>C-r</kbd> for a region or <kbd>C-b</kbd> for the whole buffer. + +<p class="noindent">Use the <code>texinfo-format...</code> commands: + +<pre class="example"> C-c C-e C-r <span class="roman">Format the region.</span> + C-c C-e C-b <span class="roman">Format the buffer.</span> +</pre> + <p class="noindent">Use <code>makeinfo</code>: + +<pre class="example"> C-c C-m C-r <span class="roman">Format the region.</span> + C-c C-m C-b <span class="roman">Format the buffer.</span> + C-c C-m C-l <span class="roman">Recenter the </span><code>makeinfo</code><span class="roman"> output buffer.</span> + C-c C-m C-k <span class="roman">Kill the </span><code>makeinfo</code><span class="roman"> formatting job.</span> +</pre> + <h4 class="subheading">Typeset and Print</h4> + +<p>The TeX typesetting and printing commands are invoked by typing +<kbd>C-c C-t</kbd> and then another control command: <kbd>C-r</kbd> for +<code>texinfo-tex-region</code>, <kbd>C-b</kbd> for <code>texinfo-tex-buffer</code>, +and so on. + +<pre class="example"> C-c C-t C-r <span class="roman">Run TeX on the region.</span> + C-c C-t C-b <span class="roman">Run</span> <code>texi2dvi</code> <span class="roman">on the buffer.</span> + C-c C-t C-i <span class="roman">Run</span> <code>texindex</code>. + C-c C-t C-p <span class="roman">Print the DVI file.</span> + C-c C-t C-q <span class="roman">Show the print queue.</span> + C-c C-t C-d <span class="roman">Delete a job from the print queue.</span> + C-c C-t C-k <span class="roman">Kill the current TeX formatting job.</span> + C-c C-t C-x <span class="roman">Quit a currently stopped TeX formatting job.</span> + C-c C-t C-l <span class="roman">Recenter the output buffer.</span> +</pre> + <h4 class="subheading">Other Updating Commands</h4> + +<p>The remaining updating commands do not have standard keybindings because +they are rarely used. + +<pre class="example"> M-x texinfo-insert-node-lines + <span class="roman">Insert missing </span><code>@node</code><span class="roman"> lines in region.</span> + <span class="roman">With </span><kbd>C-u</kbd><span class="roman"> as a prefix argument,</span> + <span class="roman">use section titles as node names.</span> + + M-x texinfo-multiple-files-update + <span class="roman">Update a multi-file document.</span> + <span class="roman">With </span><kbd>C-u 2</kbd><span class="roman"> as a prefix argument,</span> + <span class="roman">create or update all nodes and menus</span> + <span class="roman">in all included files first.</span> + + M-x texinfo-indent-menu-description + <span class="roman">Indent descriptions.</span> + + M-x texinfo-sequential-node-update + <span class="roman">Insert node pointers in strict sequence.</span> +</pre> + <div class="node"> +<p><hr> +<a name="Beginning-a-File"></a>Next: <a rel="next" accesskey="n" href="#Ending-a-File">Ending a File</a>, +Previous: <a rel="previous" accesskey="p" href="#Texinfo-Mode">Texinfo Mode</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> +<br> +</div> + +<h2 class="chapter">3 Beginning a Texinfo File</h2> + +<p><a name="index-Beginning-a-Texinfo-file-156"></a><a name="index-Texinfo-file-beginning-157"></a><a name="index-File-beginning-158"></a> +Certain pieces of information must be provided at the beginning of a +Texinfo file, such as the name for the output file(s), the title of the +document, and the Top node. A table of contents is also generally +produced here. + + <p>This chapter expands on the minimal complete Texinfo source file +previously given (see <a href="#Six-Parts">Six Parts</a>). It describes the numerous +commands for handling the traditional frontmatter items in Texinfo. + + <p><a name="index-Frontmatter_002c-text-in-159"></a>Straight text outside of any command before the Top node should be +avoided. Such text is treated differently in the different output +formats: visible in TeX and HTML, by default not shown in Info +readers, and so on. + +<ul class="menu"> +<li><a accesskey="1" href="#Sample-Beginning">Sample Beginning</a>: A sample beginning for a Texinfo file. +<li><a accesskey="2" href="#Texinfo-File-Header">Texinfo File Header</a>: The first lines. +<li><a accesskey="3" href="#Document-Permissions">Document Permissions</a>: Ensuring your manual is free. +<li><a accesskey="4" href="#Titlepage-_0026-Copyright-Page">Titlepage & Copyright Page</a>: Creating the title and copyright pages. +<li><a accesskey="5" href="#Contents">Contents</a>: How to create a table of contents. +<li><a accesskey="6" href="#The-Top-Node">The Top Node</a>: Creating the `Top' node and master menu. +<li><a accesskey="7" href="#Global-Document-Commands">Global Document Commands</a>: Affecting formatting throughout. +<li><a accesskey="8" href="#Software-Copying-Permissions">Software Copying Permissions</a>: Ensure that you and others continue to + have the right to use and share software. +</ul> + +<div class="node"> +<p><hr> +<a name="Sample-Beginning"></a>Next: <a rel="next" accesskey="n" href="#Texinfo-File-Header">Texinfo File Header</a>, +Up: <a rel="up" accesskey="u" href="#Beginning-a-File">Beginning a File</a> +<br> +</div> + +<h3 class="section">3.1 Sample Texinfo File Beginning</h3> + +<p><a name="index-Example-beginning-of-Texinfo-file-160"></a> +The following sample shows what is needed. The elements given here are +explained in more detail in the following sections. Other commands are +often included at the beginning of Texinfo files, but the ones here are +the most critical. + + <p>See <a href="#GNU-Sample-Texts">GNU Sample Texts</a>, for the full texts to be used in GNU manuals. + +<pre class="example"> \input texinfo @c -*-texinfo-*- + @c %**start of header + @setfilename <var>infoname</var>.info + @settitle <var>name-of-manual</var> <var>version</var> + @c %**end of header + + @copying + This manual is for <var>program</var>, version <var>version</var>. + + Copyright @copyright{} <var>years</var> <var>copyright-owner</var>. + + @quotation + Permission is granted to ... + @end quotation + @end copying + + @titlepage + @title <var>name-of-manual-when-printed</var> + @subtitle <var>subtitle-if-any</var> + @subtitle <var>second-subtitle</var> + @author <var>author</var> + + @c The following two commands + @c start the copyright page. + @page + @vskip 0pt plus 1filll + @insertcopying + + Published by ... + @end titlepage + + @c So the toc is printed at the start. + @contents + + @ifnottex + @node Top + @top <var>title</var> + + @insertcopying + @end ifnottex + + @menu + * First Chapter:: Getting started ... + * Second Chapter:: ... + ... + * Copying:: Your rights and freedoms. + @end menu + + @node First Chapter + @chapter First Chapter + + @cindex first chapter + @cindex chapter, first + ... +</pre> + <div class="node"> +<p><hr> +<a name="Texinfo-File-Header"></a>Next: <a rel="next" accesskey="n" href="#Document-Permissions">Document Permissions</a>, +Previous: <a rel="previous" accesskey="p" href="#Sample-Beginning">Sample Beginning</a>, +Up: <a rel="up" accesskey="u" href="#Beginning-a-File">Beginning a File</a> +<br> +</div> + +<h3 class="section">3.2 Texinfo File Header</h3> + +<p><a name="index-Header-for-Texinfo-files-161"></a><a name="index-Texinfo-file-header-162"></a> +Texinfo files start with at least three lines that provide Info and +TeX with necessary information. These are the <code>\input texinfo</code> +line, the <code>@settitle</code> line, and the <code>@setfilename</code> line. + + <p>Also, if you want to format just part of the Texinfo file, you must +write the <code>@settitle</code> and <code>@setfilename</code> lines between +start-of-header and end-of-header lines. The start- and end-of-header +lines are optional, but they do no harm, so you might as well always +include them. + + <p>Any command that affects document formatting as a whole makes sense to +include in the header. <code>@synindex</code> (see <a href="#synindex">synindex</a>), for +instance, is another command often included in the header. See <a href="#GNU-Sample-Texts">GNU Sample Texts</a>, for complete sample texts. + + <p>Thus, the beginning of a Texinfo file generally looks like this: + +<pre class="example"> \input texinfo @c -*-texinfo-*- + @c %**start of header + @setfilename sample.info + @settitle Sample Manual 1.0 + @c %**end of header +</pre> + <ul class="menu"> +<li><a accesskey="1" href="#First-Line">First Line</a>: The first line of a Texinfo file. +<li><a accesskey="2" href="#Start-of-Header">Start of Header</a>: Formatting a region requires this. +<li><a accesskey="3" href="#setfilename">setfilename</a>: Tell Info the name of the Info file. +<li><a accesskey="4" href="#settitle">settitle</a>: Create a title for the printed work. +<li><a accesskey="5" href="#End-of-Header">End of Header</a>: Formatting a region requires this. +</ul> + +<div class="node"> +<p><hr> +<a name="First-Line"></a>Next: <a rel="next" accesskey="n" href="#Start-of-Header">Start of Header</a>, +Up: <a rel="up" accesskey="u" href="#Texinfo-File-Header">Texinfo File Header</a> +<br> +</div> + +<h4 class="subsection">3.2.1 The First Line of a Texinfo File</h4> + +<p><a name="index-First-line-of-a-Texinfo-file-163"></a><a name="index-Beginning-line-of-a-Texinfo-file-164"></a><a name="index-Header-of-a-Texinfo-file-165"></a> +Every Texinfo file that is to be the top-level input to TeX must begin +with a line that looks like this: + +<pre class="example"> \input texinfo @c -*-texinfo-*- +</pre> + <p class="noindent">This line serves two functions: + + <ol type=1 start=1> +<li>When the file is processed by TeX, the <span class="samp">\input texinfo</span> command +tells TeX to load the macros needed for processing a Texinfo file. +These are in a file called <span class="file">texinfo.tex</span>, which should have been +installed on your system along with either the TeX or Texinfo +software. TeX uses the backslash, <span class="samp">\</span>, to mark the beginning of +a command, exactly as Texinfo uses <span class="samp">@</span>. The <span class="file">texinfo.tex</span> +file causes the switch from <span class="samp">\</span> to <span class="samp">@</span>; before the switch +occurs, TeX requires <span class="samp">\</span>, which is why it appears at the +beginning of the file. + + <li>When the file is edited in GNU Emacs, the <span class="samp">-*-texinfo-*-</span> mode +specification tells Emacs to use Texinfo mode. + </ol> + +<div class="node"> +<p><hr> +<a name="Start-of-Header"></a>Next: <a rel="next" accesskey="n" href="#setfilename">setfilename</a>, +Previous: <a rel="previous" accesskey="p" href="#First-Line">First Line</a>, +Up: <a rel="up" accesskey="u" href="#Texinfo-File-Header">Texinfo File Header</a> +<br> +</div> + +<h4 class="subsection">3.2.2 Start of Header</h4> + +<p><a name="index-Start-of-header-line-166"></a> +A start-of-header line is a Texinfo comment that looks like this: + +<pre class="example"> @c %**start of header +</pre> + <p>Write the start-of-header line on the second line of a Texinfo file. +Follow the start-of-header line with <code>@setfilename</code> and +<code>@settitle</code> lines and, optionally, with other commands that +globally affect the document formatting, such as <code>@synindex</code> or +<code>@footnotestyle</code>; and then by an end-of-header line (see <a href="#End-of-Header">End of Header</a>). + + <p>The start- and end-of-header lines allow you to format only part of a +Texinfo file for Info or printing. See <a href="#texinfo_002dformat-commands">texinfo-format commands</a>. + + <p>The odd string of characters, <span class="samp">%**</span>, is to ensure that no other +comment is accidentally taken for a start-of-header line. You can +change it if you wish by setting the <code>tex-start-of-header</code> and/or +<code>tex-end-of-header</code> Emacs variables. See <a href="#Texinfo-Mode-Printing">Texinfo Mode Printing</a>. + +<div class="node"> +<p><hr> +<a name="setfilename"></a>Next: <a rel="next" accesskey="n" href="#settitle">settitle</a>, +Previous: <a rel="previous" accesskey="p" href="#Start-of-Header">Start of Header</a>, +Up: <a rel="up" accesskey="u" href="#Texinfo-File-Header">Texinfo File Header</a> +<br> +</div> + +<h4 class="subsection">3.2.3 <code>@setfilename</code>: Set the output file name</h4> + +<p><a name="index-setfilename-167"></a><a name="index-Texinfo-requires-_0040code_007b_0040_0040setfilename_007d-168"></a> +In order to serve as the primary input file for either <code>makeinfo</code> +or TeX, a Texinfo file must contain a line that looks like this: + +<pre class="example"> @setfilename <var>info-file-name</var> +</pre> + <p>Write the <code>@setfilename</code> command at the beginning of a line and +follow it on the same line by the Info file name. Do not write anything +else on the line; anything on the line after the command is considered +part of the file name, including what would otherwise be a +comment. + + <p><a name="index-Ignored-before-_0040code_007b_0040_0040setfilename_007d-169"></a><a name="index-_0040samp_007b_005cinput_007d-source-line-ignored-170"></a>The Info formatting commands ignore everything written before the +<code>@setfilename</code> line, which is why the very first line of +the file (the <code>\input</code> line) does not show up in the output. + + <p>The <code>@setfilename</code> line specifies the name of the output file to +be generated. This name must be different from the name of the Texinfo +file. There are two conventions for choosing the name: you can either +remove the extension (such as <span class="samp">.texi</span>) entirely from the input file +name, or, preferably, replace it with the <span class="samp">.info</span> extension. + + <p><a name="index-Length-of-file-names-171"></a><a name="index-File-name-collision-172"></a><a name="index-Info-file-name_002c-choosing-173"></a>Although an explicit <span class="samp">.info</span> extension is preferable, some +operating systems cannot handle long file names. You can run into a +problem even when the file name you specify is itself short enough. +This occurs because the Info formatters split a long Info file into +short indirect subfiles, and name them by appending <span class="samp">-1</span>, +<span class="samp">-2</span>, <small class="dots">...</small>, <span class="samp">-10</span>, <span class="samp">-11</span>, and so on, to the original +file name. (See <a href="#Tag-and-Split-Files">Tag and Split Files</a>.) The subfile name +<span class="file">texinfo.info-10</span>, for example, is too long for old systems with a +14-character limit on filenames; so the Info file name for this document +is <span class="file">texinfo</span> rather than <span class="file">texinfo.info</span>. When <code>makeinfo</code> +is running on operating systems such as MS-DOS which impose severe +limits on file names, it may remove some characters from the original +file name to leave enough space for the subfile suffix, thus producing +files named <span class="file">texin-10</span>, <span class="file">gcc.i12</span>, etc. + + <p>When producing HTML output, <code>makeinfo</code> will replace any extension +with <span class="samp">html</span>, or add <span class="samp">.html</span> if the given name has no +extension. + + <p><a name="index-texinfo_002ecnf-174"></a>The <code>@setfilename</code> line produces no output when you typeset a +manual with TeX, but it is nevertheless essential: it opens the +index, cross-reference, and other auxiliary files used by Texinfo, and +also reads <span class="file">texinfo.cnf</span> if that file is present on your system +(see <a href="#Preparing-for-TeX">Preparing for TeX</a>). + +<div class="node"> +<p><hr> +<a name="settitle"></a>Next: <a rel="next" accesskey="n" href="#End-of-Header">End of Header</a>, +Previous: <a rel="previous" accesskey="p" href="#setfilename">setfilename</a>, +Up: <a rel="up" accesskey="u" href="#Texinfo-File-Header">Texinfo File Header</a> +<br> +</div> + +<h4 class="subsection">3.2.4 <code>@settitle</code>: Set the document title</h4> + +<p><a name="index-settitle-175"></a> +In order to be made into a printed manual, a Texinfo file must contain +a line that looks like this: + +<pre class="example"> @settitle <var>title</var> +</pre> + <p>Write the <code>@settitle</code> command at the beginning of a line and +follow it on the same line by the title. This tells TeX the title to +use in a header or footer. Do not write anything else on the line; +anything on the line after the command is considered part of the title, +including what would otherwise be a comment. + + <p>The <code>@settitle</code> command should precede everything that generates +actual output. The best place for it is right after the +<code>@setfilename</code> command (see the previous section). + + <p><a name="index-_003ctitle_003e-HTML-tag-176"></a>In the HTML file produced by <span class="command">makeinfo</span>, <var>title</var> serves as +the document <span class="samp"><title></span>. It also becomes the default document +description in the <span class="samp"><head></span> part (see <a href="#documentdescription">documentdescription</a>). + + <p>The title in the <code>@settitle</code> command does not affect the title as +it appears on the title page. Thus, the two do not need not match +exactly. A practice we recommend is to include the version or edition +number of the manual in the <code>@settitle</code> title; on the title page, +the version number generally appears as a <code>@subtitle</code> so it would +be omitted from the <code>@title</code>. See <a href="#titlepage">titlepage</a>. + + <p>Conventionally, when TeX formats a Texinfo file for double-sided +output, the title is printed in the left-hand (even-numbered) page +headings and the current chapter title is printed in the right-hand +(odd-numbered) page headings. (TeX learns the title of each chapter +from each <code>@chapter</code> command.) By default, no page footer is +printed. + + <p>Even if you are printing in a single-sided style, TeX looks for an +<code>@settitle</code> command line, in case you include the manual title +in the heading. + + <p>TeX prints page headings only for that text that comes after the +<code>@end titlepage</code> command in the Texinfo file, or that comes +after an <code>@headings</code> command that turns on headings. +(See <a href="#headings-on-off">The <code>@headings</code> Command</a>, for more +information.) + + <p>You may, if you wish, create your own, customized headings and footings. +See <a href="#Headings">Headings</a>, for a detailed discussion of this. + +<div class="node"> +<p><hr> +<a name="End-of-Header"></a>Previous: <a rel="previous" accesskey="p" href="#settitle">settitle</a>, +Up: <a rel="up" accesskey="u" href="#Texinfo-File-Header">Texinfo File Header</a> +<br> +</div> + +<h4 class="subsection">3.2.5 End of Header</h4> + +<p><a name="index-End-of-header-line-177"></a> +Follow the header lines with an end-of-header<!-- /@w --> line, which is a +Texinfo comment that looks like this: + +<pre class="example"> @c %**end of header +</pre> + <p>See <a href="#Start-of-Header">Start of Header</a>. + +<div class="node"> +<p><hr> +<a name="Document-Permissions"></a>Next: <a rel="next" accesskey="n" href="#Titlepage-_0026-Copyright-Page">Titlepage & Copyright Page</a>, +Previous: <a rel="previous" accesskey="p" href="#Texinfo-File-Header">Texinfo File Header</a>, +Up: <a rel="up" accesskey="u" href="#Beginning-a-File">Beginning a File</a> +<br> +</div> + +<h3 class="section">3.3 Document Permissions</h3> + +<p><a name="index-Document-Permissions-178"></a><a name="index-Copying-Permissions-179"></a> +The copyright notice and copying permissions for a document need to +appear in several places in the various Texinfo output formats. +Therefore, Texinfo provides a command (<code>@copying</code>) to declare +this text once, and another command (<code>@insertcopying</code>) to +insert the text at appropriate points. + +<ul class="menu"> +<li><a accesskey="1" href="#copying">copying</a>: Declare the document's copying permissions. +<li><a accesskey="2" href="#insertcopying">insertcopying</a>: Where to insert the permissions. +</ul> + +<div class="node"> +<p><hr> +<a name="copying"></a>Next: <a rel="next" accesskey="n" href="#insertcopying">insertcopying</a>, +Up: <a rel="up" accesskey="u" href="#Document-Permissions">Document Permissions</a> +<br> +</div> + +<h4 class="subsection">3.3.1 <code>@copying</code>: Declare Copying Permissions</h4> + +<p><a name="index-copying-180"></a> +The <code>@copying</code> command should be given very early in the document; +the recommended location is right after the header material +(see <a href="#Texinfo-File-Header">Texinfo File Header</a>). It conventionally consists of a sentence +or two about what the program is, identification of the documentation +itself, the legal copyright line, and the copying permissions. Here is +a skeletal example: + +<pre class="example"> @copying + This manual is for <var>program</var> (version <var>version</var>, updated + <var>date</var>), which ... + + Copyright @copyright{} <var>years</var> <var>copyright-owner</var>. + + @quotation + Permission is granted to ... + @end quotation + @end copying +</pre> + <p>The <code>@quotation</code> has no legal significance; it's there to improve +readability in some contexts. + + <p>See <a href="#GNU-Sample-Texts">GNU Sample Texts</a>, for the full text to be used in GNU manuals. +See <a href="#GNU-Free-Documentation-License">GNU Free Documentation License</a>, for the license itself under +which GNU and other free manuals are distributed. You need to include +the license as an appendix to your document. + + <p>The text of <code>@copying</code> is output as a comment at the beginning of +Info, HTML, and XML output files. It is <em>not</em> output implicitly in +plain text or TeX; it's up to you to use <code>@insertcopying</code> to +emit the copying information. See the next section for details. + + <p><a name="index-copyright-181"></a>The <code>@copyright{}</code> command generates a <span class="samp">c</span> inside a circle +in output formats that support this (print and HTML). In the other +formats (Info and plain text), it generates <span class="samp">(C)</span>. The copyright +notice itself has the following legally defined sequence: + +<pre class="example"> Copyright © <var>years</var> <var>copyright-owner</var>. +</pre> + <p><a name="index-Copyright-word_002c-always-in-English-182"></a>The word `Copyright' must always be written in English, even if the +document is otherwise written in another language. This is due to +international law. + + <p><a name="index-Years_002c-in-copyright-line-183"></a>The list of years should include all years in which a version was +completed (even if it was released in a subsequent year). Ranges are +not allowed; each year must be written out individually and in full, +separated by commas. + + <p><a name="index-Copyright-holder-for-FSF-works-184"></a><a name="index-Holder-of-copyright-for-FSF-works-185"></a><a name="index-Owner-of-copyright-for-FSF-works-186"></a>The copyright owner (or owners) is whoever holds legal copyright on the +work. In the case of works assigned to the FSF, the owner is `Free +Software Foundation, Inc.'. + + <p>The copyright `line' may actually be split across multiple +lines, both in the source document and in the output. This often +happens for documents with a long history, having many different years +of publication. + + <p>See <a href="maintain.html#Copyright-Notices">Copyright Notices (GNU Maintenance Instructions)</a>, for +additional information. + +<div class="node"> +<p><hr> +<a name="insertcopying"></a>Previous: <a rel="previous" accesskey="p" href="#copying">copying</a>, +Up: <a rel="up" accesskey="u" href="#Document-Permissions">Document Permissions</a> +<br> +</div> + +<h4 class="subsection">3.3.2 <code>@insertcopying</code>: Include Permissions Text</h4> + +<p><a name="index-insertcopying-187"></a><a name="index-Copying-text_002c-including-188"></a><a name="index-Permissions-text_002c-including-189"></a><a name="index-Including-permissions-text-190"></a> +The <code>@insertcopying</code> command is simply written on a line by +itself, like this: + +<pre class="example"> @insertcopying +</pre> + <p>This inserts the text previously defined by <code>@copying</code>. To meet +legal requirements, it must be used on the copyright page in the printed +manual (see <a href="#Copyright">Copyright</a>). + + <p>We also strongly recommend using <code>@insertcopying</code> in the Top node +of your manual (see <a href="#The-Top-Node">The Top Node</a>), although it is not required +legally. Here's why: + + <p>The <code>@copying</code> command itself causes the permissions text to +appear in an Info file <em>before</em> the first node. The text is also +copied into the beginning of each split Info output file, as is legally +necessary. This location implies a human reading the manual using Info +does <em>not</em> see this text (except when using the advanced Info +command <kbd>g *</kbd>). Therefore, an explicit <code>@insertcopying</code> +in the Top node makes it apparent to readers that the manual is free. + + <p>Similarly, the <code>@copying</code> text is automatically included at the +beginning of each HTML output file, as an HTML comment. Again, this +text is not visible (unless the reader views the HTML source). And +therefore again, the <code>@insertcopying</code> in the Top node is valuable +because it makes the copying permissions visible and thus promotes +freedom. + + <p>The permissions text defined by <code>@copying</code> also appears +automatically at the beginning of the XML output file. + +<div class="node"> +<p><hr> +<a name="Titlepage-_0026-Copyright-Page"></a>Next: <a rel="next" accesskey="n" href="#Contents">Contents</a>, +Previous: <a rel="previous" accesskey="p" href="#Document-Permissions">Document Permissions</a>, +Up: <a rel="up" accesskey="u" href="#Beginning-a-File">Beginning a File</a> +<br> +</div> + +<h3 class="section">3.4 Title and Copyright Pages</h3> + +<p>In hard copy output, the manual's name and author are usually printed on +a title page. Copyright information is usually printed on the back of +the title page. + + <p>The title and copyright pages appear in the printed manual, but not in +the Info file. Because of this, it is possible to use several slightly +obscure TeX typesetting commands that cannot be used in an Info file. +In addition, this part of the beginning of a Texinfo file contains the +text of the copying permissions that appears in the printed manual. + + <p><a name="index-Title-page_002c-for-plain-text-191"></a><a name="index-Copyright-page_002c-for-plain-text-192"></a>You may wish to include titlepage-like information for plain text +output. Simply place any such leading material between +<code>@ifplaintext</code> and <code>@end ifplaintext</code>; <span class="command">makeinfo</span> +includes this when writing plain text (<span class="samp">--no-headers</span>), along with +an <code>@insertcopying</code>. + +<ul class="menu"> +<li><a accesskey="1" href="#titlepage">titlepage</a>: Create a title for the printed document. +<li><a accesskey="2" href="#titlefont-center-sp">titlefont center sp</a>: The <code>@titlefont</code>, <code>@center</code>, + and <code>@sp</code> commands. +<li><a accesskey="3" href="#title-subtitle-author">title subtitle author</a>: The <code>@title</code>, <code>@subtitle</code>, + and <code>@author</code> commands. +<li><a accesskey="4" href="#Copyright">Copyright</a>: How to write the copyright notice and + include copying permissions. +<li><a accesskey="5" href="#end-titlepage">end titlepage</a>: Turn on page headings after the title and + copyright pages. +<li><a accesskey="6" href="#headings-on-off">headings on off</a>: An option for turning headings on and off + and double or single sided printing. +</ul> + +<div class="node"> +<p><hr> +<a name="titlepage"></a>Next: <a rel="next" accesskey="n" href="#titlefont-center-sp">titlefont center sp</a>, +Up: <a rel="up" accesskey="u" href="#Titlepage-_0026-Copyright-Page">Titlepage & Copyright Page</a> +<br> +</div> + +<h4 class="subsection">3.4.1 <code>@titlepage</code></h4> + +<p><a name="index-Title-page-193"></a><a name="index-titlepage-194"></a> +Start the material for the title page and following copyright page +with <code>@titlepage</code> on a line by itself and end it with +<code>@end titlepage</code> on a line by itself. + + <p>The <code>@end titlepage</code> command starts a new page and turns on page +numbering. (See <a href="#Headings">Page Headings</a>, for details about how to +generate page headings.) All the material that you want to appear on +unnumbered pages should be put between the <code>@titlepage</code> and +<code>@end titlepage</code> commands. You can force the table of contents to +appear there with the <code>@setcontentsaftertitlepage</code> command +(see <a href="#Contents">Contents</a>). + + <p><a name="index-page_0040r_007b_002c-within-_0040code_007b_0040_0040titlepage_007d_007d-195"></a>By using the <code>@page</code> command you can force a page break within the +region delineated by the <code>@titlepage</code> and <code>@end titlepage</code> +commands and thereby create more than one unnumbered page. This is how +the copyright page is produced. (The <code>@titlepage</code> command might +perhaps have been better named the <code>@titleandadditionalpages</code> +command, but that would have been rather long!) + + <p>When you write a manual about a computer program, you should write the +version of the program to which the manual applies on the title page. +If the manual changes more frequently than the program or is independent +of it, you should also include an edition number<a rel="footnote" href="#fn-5" name="fnd-5"><sup>5</sup></a> for the manual. +This helps readers keep track of which manual is for which version of +the program. (The `Top' node should also contain this information; see +<a href="#The-Top-Node">The Top Node</a>.) + + <p>Texinfo provides two main methods for creating a title page. One method +uses the <code>@titlefont</code>, <code>@sp</code>, and <code>@center</code> commands +to generate a title page in which the words on the page are +centered. + + <p>The second method uses the <code>@title</code>, <code>@subtitle</code>, and +<code>@author</code> commands to create a title page with black rules under +the title and author lines and the subtitle text set flush to the +right hand side of the page. With this method, you do not specify any +of the actual formatting of the title page. You specify the text +you want, and Texinfo does the formatting. + + <p>You may use either method, or you may combine them; see the examples in +the sections below. + + <p><a name="index-shorttitlepage-196"></a><a name="index-Bastard-title-page-197"></a><a name="index-Title-page_002c-bastard-198"></a>For extremely simple documents, and for the bastard title page in +traditional book frontmatter, Texinfo also provides a command +<code>@shorttitlepage</code> which takes the rest of the line as the title. +The argument is typeset on a page by itself and followed by a blank +page. + +<div class="node"> +<p><hr> +<a name="titlefont-center-sp"></a>Next: <a rel="next" accesskey="n" href="#title-subtitle-author">title subtitle author</a>, +Previous: <a rel="previous" accesskey="p" href="#titlepage">titlepage</a>, +Up: <a rel="up" accesskey="u" href="#Titlepage-_0026-Copyright-Page">Titlepage & Copyright Page</a> +<br> +</div> + +<h4 class="subsection">3.4.2 <code>@titlefont</code>, <code>@center</code>, and <code>@sp</code></h4> + +<p><a name="index-titlefont-199"></a><a name="index-center-200"></a><a name="index-sp-_0040r_007b_0028titlepage-line-spacing_0029_007d-201"></a> +You can use the <code>@titlefont</code>, <code>@sp</code>, and <code>@center</code> +commands to create a title page for a printed document. (This is the +first of the two methods for creating a title page in Texinfo.) + + <p>Use the <code>@titlefont</code> command to select a large font suitable for +the title itself. You can use <code>@titlefont</code> more than once if you +have an especially long title. + + <p>For HTML output, each <code>@titlefont</code> command produces an +<code><h1></code> heading, but the HTML document <code><title></code> is not +affected. For that, you must put an <code>@settitle</code> command before +the <code>@titlefont</code> command (see <a href="#settitle">settitle</a>). + + <p>For example: + +<pre class="example"> @titlefont{Texinfo} +</pre> + <p>Use the <code>@center</code> command at the beginning of a line to center +the remaining text on that line. Thus, + +<pre class="example"> @center @titlefont{Texinfo} +</pre> + <p class="noindent">centers the title, which in this example is “Texinfo” printed +in the title font. + + <p>Use the <code>@sp</code> command to insert vertical space. For example: + +<pre class="example"> @sp 2 +</pre> + <p class="noindent">This inserts two blank lines on the printed page. (See <a href="#sp"><code>@sp</code></a>, for more information about the <code>@sp</code> +command.) + + <p>A template for this method looks like this: + +<pre class="example"> @titlepage + @sp 10 + @center @titlefont{<var>name-of-manual-when-printed</var>} + @sp 2 + @center <var>subtitle-if-any</var> + @sp 2 + @center <var>author</var> + ... + @end titlepage +</pre> + <p>The spacing of the example fits an 8.5 by 11 inch manual. + + <p>You can in fact use these commands anywhere, not just on a title page, +but since they are not logical markup commands, we don't recommend +them. + +<div class="node"> +<p><hr> +<a name="title-subtitle-author"></a>Next: <a rel="next" accesskey="n" href="#Copyright">Copyright</a>, +Previous: <a rel="previous" accesskey="p" href="#titlefont-center-sp">titlefont center sp</a>, +Up: <a rel="up" accesskey="u" href="#Titlepage-_0026-Copyright-Page">Titlepage & Copyright Page</a> +<br> +</div> + +<h4 class="subsection">3.4.3 <code>@title</code>, <code>@subtitle</code>, and <code>@author</code></h4> + +<p><a name="index-title-202"></a><a name="index-subtitle-203"></a><a name="index-author-204"></a> +You can use the <code>@title</code>, <code>@subtitle</code>, and <code>@author</code> +commands to create a title page in which the vertical and horizontal +spacing is done for you automatically. This contrasts with the method +described in the previous section, in which the <code>@sp</code> command is +needed to adjust vertical spacing. + + <p>Write the <code>@title</code>, <code>@subtitle</code>, or <code>@author</code> +commands at the beginning of a line followed by the title, subtitle, +or author. These commands are only effective in TeX output; it's +an error to use them anywhere except within <code>@titlepage</code>. + + <p>The <code>@title</code> command produces a line in which the title is set +flush to the left-hand side of the page in a larger than normal font. +The title is underlined with a black rule. Only a single line is +allowed; the <code>@*</code> command may not be used to break the title into +two lines. To handle very long titles, you may find it profitable to +use both <code>@title</code> and <code>@titlefont</code>; see the final example in +this section. + + <p>The <code>@subtitle</code> command sets subtitles in a normal-sized font +flush to the right-hand side of the page. + + <p>The <code>@author</code> command sets the names of the author or authors in +a middle-sized font flush to the left-hand side of the page on a line +near the bottom of the title page. The names are underlined with a +black rule that is thinner than the rule that underlines the title. +(The black rule only occurs if the <code>@author</code> command line is +followed by an <code>@page</code> command line.) + + <p>There are two ways to use the <code>@author</code> command: you can write +the name or names on the remaining part of the line that starts with +an <code>@author</code> command: + +<pre class="example"> @author by Jane Smith and John Doe +</pre> + <p class="noindent">or you can write the names one above each other by using two (or more) +<code>@author</code> commands: + +<pre class="example"> @author Jane Smith + @author John Doe +</pre> + <p class="noindent">(Only the bottom name is underlined with a black rule.) + + <p>A template for this method looks like this: + +<pre class="example"> @titlepage + @title <var>name-of-manual-when-printed</var> + @subtitle <var>subtitle-if-any</var> + @subtitle <var>second-subtitle</var> + @author <var>author</var> + @page + ... + @end titlepage +</pre> + <p>You may also combine the <code>@titlefont</code> method described in the +previous section and <code>@title</code> method described in this one. This +may be useful if you have a very long title. Here is a real-life example: + +<pre class="example"> @titlepage + @titlefont{GNU Software} + @sp 1 + @title for MS-Windows and MS-DOS + @subtitle Edition @value{e} for Release @value{cde} + @author by Daniel Hagerty, Melissa Weisshaus + @author and Eli Zaretskii +</pre> + <p class="noindent">(The use of <code>@value</code> here is explained in <a href="#value-Example">value Example</a>. + +<div class="node"> +<p><hr> +<a name="Copyright"></a>Next: <a rel="next" accesskey="n" href="#end-titlepage">end titlepage</a>, +Previous: <a rel="previous" accesskey="p" href="#title-subtitle-author">title subtitle author</a>, +Up: <a rel="up" accesskey="u" href="#Titlepage-_0026-Copyright-Page">Titlepage & Copyright Page</a> +<br> +</div> + +<h4 class="subsection">3.4.4 Copyright Page</h4> + +<p><a name="index-Copyright-page-205"></a><a name="index-Printed-permissions-206"></a><a name="index-Permissions_002c-printed-207"></a> +By international treaty, the copyright notice for a book must be either +on the title page or on the back of the title page. When the copyright +notice is on the back of the title page, that page is customarily not +numbered. Therefore, in Texinfo, the information on the copyright page +should be within <code>@titlepage</code> and <code>@end titlepage</code> +commands. + + <p><a name="index-vskip-_0040r_007b_0040TeX_007b_007d-vertical-skip_007d-208"></a><a name="index-filll-_0040r_007b_0040TeX_007b_007d-dimension_007d-209"></a>Use the <code>@page</code> command to cause a page break. To push the +copyright notice and the other text on the copyright page towards the +bottom of the page, use the following incantantion after <code>@page</code>: + +<pre class="example"> @vskip 0pt plus 1filll +</pre> + <p class="noindent">This is a TeX command that is not supported by the Info formatting +commands. The <code>@vskip</code> command inserts whitespace. The <span class="samp">0pt +plus 1filll</span> means to put in zero points of mandatory whitespace, and as +much optional whitespace as needed to push the following text to the +bottom of the page. Note the use of three <span class="samp">l</span>s in the word +<span class="samp">filll</span>; this is correct. + + <p>To insert the copyright text itself, write <code>@insertcopying</code> +next (see <a href="#Document-Permissions">Document Permissions</a>): + +<pre class="example"> @insertcopying +</pre> + <p>Follow the copying text by the publisher, ISBN numbers, cover art +credits, and other such information. + + <p>Here is an example putting all this together: + +<pre class="example"> @titlepage + ... + @page + @vskip 0pt plus 1filll + @insertcopying + + Published by ... + + Cover art by ... + @end titlepage +</pre> + <div class="node"> +<p><hr> +<a name="end-titlepage"></a>Next: <a rel="next" accesskey="n" href="#headings-on-off">headings on off</a>, +Previous: <a rel="previous" accesskey="p" href="#Copyright">Copyright</a>, +Up: <a rel="up" accesskey="u" href="#Titlepage-_0026-Copyright-Page">Titlepage & Copyright Page</a> +<br> +</div> + +<h4 class="subsection">3.4.5 Heading Generation</h4> + +<p><a name="index-end-titlepage-210"></a><a name="index-Headings_002c-page_002c-begin-to-appear-211"></a><a name="index-Titlepage-end-starts-headings-212"></a><a name="index-End-titlepage-starts-headings-213"></a> +The <code>@end titlepage</code> command must be written on a line by itself. +It not only marks the end of the title and copyright pages, but also +causes TeX to start generating page headings and page numbers. + + <p>To repeat what is said elsewhere, Texinfo has two standard page heading +formats, one for documents which are printed on one side of each sheet of paper +(single-sided printing), and the other for documents which are printed on both +sides of each sheet (double-sided printing). +You can specify these formats in different ways: + + <ul> +<li>The conventional way is to write an <code>@setchapternewpage</code> command +before the title page commands, and then have the <code>@end +titlepage</code> command start generating page headings in the manner desired. +(See <a href="#setchapternewpage">setchapternewpage</a>.) + + <li>Alternatively, you can use the <code>@headings</code> command to prevent page +headings from being generated or to start them for either single or +double-sided printing. (Write an <code>@headings</code> command immediately +after the <code>@end titlepage</code> command. See <a href="#headings-on-off">The <code>@headings</code> Command</a>, for more information.) + + <li>Or, you may specify your own page heading and footing format. +See <a href="#Headings">Page Headings</a>, for detailed +information about page headings and footings. +</ul> + + <p>Most documents are formatted with the standard single-sided or +double-sided format, using <code>@setchapternewpage odd</code> for +double-sided printing and no <code>@setchapternewpage</code> command for +single-sided printing. + +<div class="node"> +<p><hr> +<a name="headings-on-off"></a>Previous: <a rel="previous" accesskey="p" href="#end-titlepage">end titlepage</a>, +Up: <a rel="up" accesskey="u" href="#Titlepage-_0026-Copyright-Page">Titlepage & Copyright Page</a> +<br> +</div> + +<h4 class="subsection">3.4.6 The <code>@headings</code> Command</h4> + +<p><a name="index-headings-214"></a> +The <code>@headings</code> command is rarely used. It specifies what kind of +page headings and footings to print on each page. Usually, this is +controlled by the <code>@setchapternewpage</code> command. You need the +<code>@headings</code> command only if the <code>@setchapternewpage</code> command +does not do what you want, or if you want to turn off pre-defined page +headings prior to defining your own. Write an <code>@headings</code> command +immediately after the <code>@end titlepage</code> command. + + <p>You can use <code>@headings</code> as follows: + + <dl> +<dt><code>@headings off</code><dd>Turn off printing of page headings. + + <br><dt><code>@headings single</code><dd>Turn on page headings appropriate for single-sided printing. + + <br><dt><code>@headings double</code><dt><code>@headings on</code><dd>Turn on page headings appropriate for double-sided printing. The two +commands, <code>@headings on</code> and <code>@headings double</code>, are +synonymous. + + <br><dt><code>@headings singleafter</code><dt><code>@headings doubleafter</code><dd>Turn on <code>single</code> or <code>double</code> headings, respectively, after the +current page is output. + + <br><dt><code>@headings on</code><dd>Turn on page headings: <code>single</code> if <span class="samp">@setchapternewpage +on</span>, <code>double</code> otherwise. +</dl> + + <p>For example, suppose you write <code>@setchapternewpage off</code> before the +<code>@titlepage</code> command to tell TeX to start a new chapter on the +same page as the end of the last chapter. This command also causes +TeX to typeset page headers for single-sided printing. To cause +TeX to typeset for double sided printing, write <code>@headings +double</code> after the <code>@end titlepage</code> command. + + <p>You can stop TeX from generating any page headings at all by +writing <code>@headings off</code> on a line of its own immediately after the +line containing the <code>@end titlepage</code> command, like this: + +<pre class="example"> @end titlepage + @headings off +</pre> + <p class="noindent">The <code>@headings off</code> command overrides the <code>@end titlepage</code> +command, which would otherwise cause TeX to print page +headings. + + <p>You can also specify your own style of page heading and footing. +See <a href="#Headings">Page Headings</a>, for more information. + +<div class="node"> +<p><hr> +<a name="Contents"></a>Next: <a rel="next" accesskey="n" href="#The-Top-Node">The Top Node</a>, +Previous: <a rel="previous" accesskey="p" href="#Titlepage-_0026-Copyright-Page">Titlepage & Copyright Page</a>, +Up: <a rel="up" accesskey="u" href="#Beginning-a-File">Beginning a File</a> +<br> +</div> + +<h3 class="section">3.5 Generating a Table of Contents</h3> + +<p><a name="index-Table-of-contents-215"></a><a name="index-Contents_002c-Table-of-216"></a><a name="index-Short-table-of-contents-217"></a><a name="index-contents-218"></a><a name="index-summarycontents-219"></a><a name="index-shortcontents-220"></a> +The <code>@chapter</code>, <code>@section</code>, and other structuring commands +(see <a href="#Structuring">Structuring</a>) supply the information to make up a +table of contents, but they do not cause an actual table to appear in +the manual. To do this, you must use the <code>@contents</code> and/or +<code>@summarycontents</code> command(s). + + <dl> +<dt><code>@contents</code><dd>Generates a table of contents in a printed manual, including all +chapters, sections, subsections, etc., as well as appendices and +unnumbered chapters. Headings generated by <code>@majorheading</code>, +<code>@chapheading</code>, and the other <code>@...heading</code> commands +do not appear in the table of contents (see <a href="#Structuring-Command-Types">Structuring Command Types</a>). + + <br><dt><code>@shortcontents</code><dt><code>@summarycontents</code><dd>(<code>@summarycontents</code> is a synonym for <code>@shortcontents</code>.) + + <p>Generates a short or summary table of contents that lists only the +chapters, appendices, and unnumbered chapters. Sections, subsections +and subsubsections are omitted. Only a long manual needs a short +table of contents in addition to the full table of contents. + + </dl> + + <p>Both contents commands should be written on a line by themselves, and +are best placed near the beginning of the file, after the <code>@end +titlepage</code> (see <a href="#titlepage">titlepage</a>). The contents commands automatically +generate a chapter-like heading at the top of the first table of +contents page, so don't include any sectioning command such as +<code>@unnumbered</code> before them. + + <p>Since an Info file uses menus instead of tables of contents, the Info +formatting commands ignore the contents commands. But the contents are +included in plain text output (generated by <code>makeinfo +--no-headers</code>), unless <code>makeinfo</code> is writing its output to standard +output. + + <p>When <code>makeinfo</code> writes a short table of contents while producing +html output, the links in the short table of contents point to +corresponding entries in the full table of contents rather than the text +of the document. The links in the full table of contents point to the +main text of the document. + + <p>In the past, the contents commands were sometimes placed at the end of +the file, after any indices and just before the <code>@bye</code>, but we +no longer recommend this. + + <p><a name="index-setcontentsaftertitlepage-221"></a><a name="index-setshortcontentsaftertitlepage-222"></a><a name="index-Contents_002c-after-title-page-223"></a><a name="index-Table-of-contents_002c-after-title-page-224"></a>However, since many existing Texinfo documents still do have the +<code>@contents</code> at the end of the manual, if you are a user printing +a manual, you may wish to force the contents to be printed after the +title page. You can do this by specifying +<code>@setcontentsaftertitlepage</code> and/or +<code>@setshortcontentsaftertitlepage</code>. The first prints only the +main contents after the <code>@end titlepage</code>; the second prints both +the short contents and the main contents. In either case, any +subsequent <code>@contents</code> or <code>@shortcontents</code> is ignored +(unless, erroneously, no <code>@end titlepage</code> is ever encountered). + + <p>You need to include the <code>@set...contentsaftertitlepage</code> +commands early in the document (just after <code>@setfilename</code>, for +example). We recommend using <span class="command">texi2dvi</span> (see <a href="#Format-with-texi2dvi">Format with texi2dvi</a>) to specify this without altering the source file at all. For +example: +<pre class="example"> texi2dvi --texinfo=@setcontentsaftertitlepage foo.texi +</pre> + <div class="node"> +<p><hr> +<a name="The-Top-Node"></a>Next: <a rel="next" accesskey="n" href="#Global-Document-Commands">Global Document Commands</a>, +Previous: <a rel="previous" accesskey="p" href="#Contents">Contents</a>, +Up: <a rel="up" accesskey="u" href="#Beginning-a-File">Beginning a File</a> +<br> +</div> + +<h3 class="section">3.6 The `Top' Node and Master Menu</h3> + +<p><a name="index-Top-node-225"></a><a name="index-Node_002c-_0060Top_0027-226"></a> +The `Top' node is the node in which a reader enters an Info manual. As +such, it should begin with the <code>@insertcopying</code> command +(see <a href="#Document-Permissions">Document Permissions</a>) to provide a brief description of the +manual (including the version number) and copying permissions, and end +with a master menu for the whole manual. Of course you should include +any other general information you feel a reader would find helpful. + + <p><a name="index-top-227"></a>It is also conventional to write an <code>@top</code> sectioning command line +containing the title of the document immediately after the <code>@node +Top</code> line (see <a href="#makeinfo-top-command">The <code>@top</code> Sectioning Command</a>). + + <p>The contents of the `Top' node should appear only in the online output; +none of it should appear in printed output, so enclose it between +<code>@ifnottex</code> and <code>@end ifnottex</code> commands. (TeX does not +print either an <code>@node</code> line or a menu; they appear only in Info; +strictly speaking, you are not required to enclose these parts between +<code>@ifnottex</code> and <code>@end ifnottext</code>, but it is simplest to do +so. See <a href="#Conditionals">Conditionally Visible Text</a>.) + +<ul class="menu"> +<li><a accesskey="1" href="#Top-Node-Example">Top Node Example</a> +<li><a accesskey="2" href="#Master-Menu-Parts">Master Menu Parts</a> +</ul> + +<div class="node"> +<p><hr> +<a name="Top-Node-Example"></a>Next: <a rel="next" accesskey="n" href="#Master-Menu-Parts">Master Menu Parts</a>, +Up: <a rel="up" accesskey="u" href="#The-Top-Node">The Top Node</a> +<br> +</div> + +<h4 class="subsection">3.6.1 Top Node Example</h4> + +<p><a name="index-Top-node-example-228"></a> +Here is an example of a Top node. + +<pre class="example"> @ifnottex + @node Top + @top Sample Title + + @insertcopying + + Additional general information. + + @menu + * First Chapter:: + * Second Chapter:: + ... + * Index:: + @end menu +</pre> + <div class="node"> +<p><hr> +<a name="Master-Menu-Parts"></a>Previous: <a rel="previous" accesskey="p" href="#Top-Node-Example">Top Node Example</a>, +Up: <a rel="up" accesskey="u" href="#The-Top-Node">The Top Node</a> +<br> +</div> + +<h4 class="subsection">3.6.2 Parts of a Master Menu</h4> + +<p><a name="index-Master-menu-229"></a><a name="index-Menu_002c-master-230"></a><a name="index-Parts-of-a-master-menu-231"></a> +A <dfn>master menu</dfn> is a detailed main menu listing all the nodes in a +file. + + <p>A master menu is enclosed in <code>@menu</code> and <code>@end menu</code> +commands and does not appear in the printed document. + + <p>Generally, a master menu is divided into parts. + + <ul> +<li>The first part contains the major nodes in the Texinfo file: the nodes +for the chapters, chapter-like sections, and the appendices. + + <li>The second part contains nodes for the indices. + + <li>The third and subsequent parts contain a listing of the other, lower +level nodes, often ordered by chapter. This way, rather than go +through an intermediary menu, an inquirer can go directly to a +particular node when searching for specific information. These menu +items are not required; add them if you think they are a +convenience. If you do use them, put <code>@detailmenu</code> before the +first one, and <code>@end detailmenu</code> after the last; otherwise, +<code>makeinfo</code> will get confused. +</ul> + + <p>Each section in the menu can be introduced by a descriptive line. So +long as the line does not begin with an asterisk, it will not be +treated as a menu entry. (See <a href="#Writing-a-Menu">Writing a Menu</a>, for more +information.) + + <p>For example, the master menu for this manual looks like the following +(but has many more entries): + +<pre class="example"> @menu + * Copying Conditions:: Your rights. + * Overview:: Texinfo in brief. + ... + * Command and Variable Index:: + * Concept Index:: + + @detailmenu + --- The Detailed Node Listing --- + + Overview of Texinfo + + * Reporting Bugs:: ... + ... + + Beginning a Texinfo File + + * Sample Beginning:: ... + ... + @end detailmenu + @end menu +</pre> + <div class="node"> +<p><hr> +<a name="Global-Document-Commands"></a>Next: <a rel="next" accesskey="n" href="#Software-Copying-Permissions">Software Copying Permissions</a>, +Previous: <a rel="previous" accesskey="p" href="#The-Top-Node">The Top Node</a>, +Up: <a rel="up" accesskey="u" href="#Beginning-a-File">Beginning a File</a> +<br> +</div> + +<h3 class="section">3.7 Global Document Commands</h3> + +<p><a name="index-Global-Document-Commands-232"></a> +Besides the basic commands mentioned in the previous sections, here are +additional commands which affect the document as a whole. They are +generally all given before the Top node, if they are given at all. + +<ul class="menu"> +<li><a accesskey="1" href="#documentdescription">documentdescription</a>: Document summary for the HTML output. +<li><a accesskey="2" href="#setchapternewpage">setchapternewpage</a>: Start chapters on right-hand pages. +<li><a accesskey="3" href="#paragraphindent">paragraphindent</a>: Specify paragraph indentation. +<li><a accesskey="4" href="#firstparagraphindent">firstparagraphindent</a>: Suppress indentation of the first paragraph. +<li><a accesskey="5" href="#exampleindent">exampleindent</a>: Specify environment indentation. +</ul> + +<div class="node"> +<p><hr> +<a name="documentdescription"></a>Next: <a rel="next" accesskey="n" href="#setchapternewpage">setchapternewpage</a>, +Up: <a rel="up" accesskey="u" href="#Global-Document-Commands">Global Document Commands</a> +<br> +</div> + +<h4 class="subsection">3.7.1 <code>@documentdescription</code>: Summary Text</h4> + +<p><a name="index-Document-description-233"></a><a name="index-Description-of-document-234"></a><a name="index-Summary-of-document-235"></a><a name="index-Abstract-of-document-236"></a><a name="index-_003cmeta_003e-HTML-tag_002c-and-document-description-237"></a><a name="index-documentdescription-238"></a> +When producing HTML output for a document, <span class="command">makeinfo</span> writes a +<span class="samp"><meta></span> element in the <span class="samp"><head></span> to give some idea of the +content of the document. By default, this <dfn>description</dfn> is the title +of the document, taken from the <code>@settitle</code> command +(see <a href="#settitle">settitle</a>). To change this, use the <code>@documentdescription</code> +environment, as in: + +<pre class="example"> @documentdescription + descriptive text. + @end documentdescription +</pre> + <p class="noindent">This will produce the following output in the <span class="samp"><head></span> of the HTML: + +<pre class="example"> <meta name=description content="descriptive text."> +</pre> + <p><code>@documentdescription</code> must be specified before the first node of +the document. + +<div class="node"> +<p><hr> +<a name="setchapternewpage"></a>Next: <a rel="next" accesskey="n" href="#paragraphindent">paragraphindent</a>, +Previous: <a rel="previous" accesskey="p" href="#documentdescription">documentdescription</a>, +Up: <a rel="up" accesskey="u" href="#Global-Document-Commands">Global Document Commands</a> +<br> +</div> + +<h4 class="subsection">3.7.2 <code>@setchapternewpage</code>:</h4> + +<p><a name="index-Starting-chapters-239"></a><a name="index-Pages_002c-starting-odd-240"></a><a name="index-setchapternewpage-241"></a> +In an officially bound book, text is usually printed on both sides of +the paper, chapters start on right-hand pages, and right-hand pages have +odd numbers. But in short reports, text often is printed only on one +side of the paper. Also in short reports, chapters sometimes do not +start on new pages, but are printed on the same page as the end of the +preceding chapter, after a small amount of vertical whitespace. + + <p>You can use the <code>@setchapternewpage</code> command with various +arguments to specify how TeX should start chapters and whether it +should format headers for printing on one or both sides of the paper +(single-sided or double-sided printing). + + <p>Write the <code>@setchapternewpage</code> command at the beginning of a +line followed by its argument. + + <p>For example, you would write the following to cause each chapter to +start on a fresh odd-numbered page: + +<pre class="example"> @setchapternewpage odd +</pre> + <p>You can specify one of three alternatives with the +<code>@setchapternewpage</code> command: + + <dl> +<dt><code>@setchapternewpage off</code><dd>Cause TeX to typeset a new chapter on the same page as the last +chapter, after skipping some vertical whitespace. Also, cause TeX to +format page headers for single-sided printing. + + <br><dt><code>@setchapternewpage on</code><dd>Cause TeX to start new chapters on new pages and to format page +headers for single-sided printing. This is the form most often used for +short reports or personal printing. This is the default. + + <br><dt><code>@setchapternewpage odd</code><dd>Cause TeX to start new chapters on new, odd-numbered pages +(right-handed pages) and to typeset for double-sided printing. This is +the form most often used for books and manuals. +</dl> + + <p>Texinfo does not have an <code>@setchapternewpage even</code> command, +because there is no printing tradition of starting chapters or books on +an even-numbered page. + + <p>If you don't like the default headers that <code>@setchapternewpage</code> +sets, you can explicit control them with the <code>@headings</code> command. +See <a href="#headings-on-off">The <code>@headings</code> Command</a>. + + <p>At the beginning of a manual or book, pages are not numbered—for +example, the title and copyright pages of a book are not numbered. By +convention, table of contents and frontmatter pages are numbered with +roman numerals and not in sequence with the rest of the document. + + <p>Since an Info file does not have pages, the <code>@setchapternewpage</code> +command has no effect on it. + + <p>We recommend not including any <code>@setchapternewpage</code> command in +your manual sources at all, since the desired output is not intrinsic to +the document. For a particular hard copy run, if you don't want the +default option (no blank pages, same headers on all pages) use the +<span class="option">--texinfo</span> option to <span class="command">texi2dvi</span> to specify the output +you want. + +<div class="node"> +<p><hr> +<a name="paragraphindent"></a>Next: <a rel="next" accesskey="n" href="#firstparagraphindent">firstparagraphindent</a>, +Previous: <a rel="previous" accesskey="p" href="#setchapternewpage">setchapternewpage</a>, +Up: <a rel="up" accesskey="u" href="#Global-Document-Commands">Global Document Commands</a> +<br> +</div> + +<h4 class="subsection">3.7.3 <code>@paragraphindent</code>: Paragraph Indenting</h4> + +<p><a name="index-Indenting-paragraphs_002c-control-of-242"></a><a name="index-Paragraph-indentation-control-243"></a><a name="index-paragraphindent-244"></a> +The Texinfo processors may insert whitespace at the beginning of the +first line of each paragraph, thereby indenting that paragraph. You can +use the <code>@paragraphindent</code> command to specify this indentation. +Write an <code>@paragraphindent</code> command at the beginning of a line +followed by either <span class="samp">asis</span> or a number: + +<pre class="example"> @paragraphindent <var>indent</var> +</pre> + <p>The indentation is according to the value of <var>indent</var>: + + <dl> +<dt><code>asis</code><dd>Do not change the existing indentation (not implemented in TeX). + + <br><dt><code>none</code><dt>0<dd>Omit all indentation. + + <br><dt><var>n</var><dd>Indent by <var>n</var> space characters in Info output, by <var>n</var> ems in +TeX. + + </dl> + + <p>The default value of <var>indent</var> is 3. <code>@paragraphindent</code> is +ignored for HTML output. + + <p>It is best to write the <code>@paragraphindent</code> command before the +end-of-header line at the beginning of a Texinfo file, so the region +formatting commands indent paragraphs as specified. See <a href="#Start-of-Header">Start of Header</a>. + + <p>A peculiarity of the <code>texinfo-format-buffer</code> and +<code>texinfo-format-region</code> commands is that they do not indent (nor +fill) paragraphs that contain <code>@w</code> or <code>@*</code> commands. + +<div class="node"> +<p><hr> +<a name="firstparagraphindent"></a>Next: <a rel="next" accesskey="n" href="#exampleindent">exampleindent</a>, +Previous: <a rel="previous" accesskey="p" href="#paragraphindent">paragraphindent</a>, +Up: <a rel="up" accesskey="u" href="#Global-Document-Commands">Global Document Commands</a> +<br> +</div> + +<h4 class="subsection">3.7.4 <code>@firstparagraphindent</code>: Indenting After Headings</h4> + +<p><a name="index-First-paragraph_002c-suppressing-indentation-of-245"></a><a name="index-Suppressing-first-paragraph-indentation-246"></a><a name="index-Preventing-first-paragraph-indentation-247"></a><a name="index-Indenting_002c-suppressing-of-first-paragraph-248"></a><a name="index-Headings_002c-indentation-after-249"></a><a name="index-firstparagraphindent-250"></a> +As you can see in the present manual, the first paragraph in any +section is not indented by default. Typographically, indentation is a +paragraph separator, which means that it is unnecessary when a new +section begins. This indentation is controlled with the +<code>@firstparagraphindent</code> command: + +<pre class="example"> @firstparagraphindent <var>word</var> +</pre> + <p>The first paragraph after a heading is indented according to the value +of <var>word</var>: + + <dl> +<dt><code>none</code><dd>Prevents the first paragraph from being indented (default). +This option is ignored by <span class="command">makeinfo</span> if +<code>@paragraphindent asis</code> is in effect. + + <br><dt><code>insert</code><dd>Include normal paragraph indentation. This respects the paragraph +indentation set by a <code>@paragraphindent</code> command +(see <a href="#paragraphindent">paragraphindent</a>). +</dl> + + <p>For HTML and XML output, the <code>@firstparagraphindent</code> setting is +ignored. + + <p>It is best to write the <code>@paragraphindent</code> command before the +end-of-header line at the beginning of a Texinfo file, so the region +formatting commands indent paragraphs as specified. See <a href="#Start-of-Header">Start of Header</a>. + +<div class="node"> +<p><hr> +<a name="exampleindent"></a>Previous: <a rel="previous" accesskey="p" href="#firstparagraphindent">firstparagraphindent</a>, +Up: <a rel="up" accesskey="u" href="#Global-Document-Commands">Global Document Commands</a> +<br> +</div> + +<h4 class="subsection">3.7.5 <code>@exampleindent</code>: Environment Indenting</h4> + +<p><a name="index-Indenting-environments-251"></a><a name="index-Environment-indentation-252"></a><a name="index-Example-indentation-253"></a><a name="index-exampleindent-254"></a> +The Texinfo processors indent each line of <code>@example</code> and similar +environments. You can use the <code>@exampleindent</code> command to specify +this indentation. Write an <code>@exampleindent</code> command at the +beginning of a line followed by either <span class="samp">asis</span> or a number: + +<pre class="example"> @exampleindent <var>indent</var> +</pre> + <p>The indentation is according to the value of <var>indent</var>: + + <dl> +<dt><code>asis</code><dd>Do not change the existing indentation (not implemented in TeX). + + <br><dt>0<dd>Omit all indentation. + + <br><dt><var>n</var><dd>Indent environments by <var>n</var> space characters in Info output, by +<var>n</var> ems in TeX. + + </dl> + + <p>The default value of <var>indent</var> is 5. <code>@exampleindent</code> is +ignored for HTML output. + + <p>It is best to write the <code>@exampleindent</code> command before the +end-of-header line at the beginning of a Texinfo file, so the region +formatting commands indent paragraphs as specified. See <a href="#Start-of-Header">Start of Header</a>. + +<div class="node"> +<p><hr> +<a name="Software-Copying-Permissions"></a>Previous: <a rel="previous" accesskey="p" href="#Global-Document-Commands">Global Document Commands</a>, +Up: <a rel="up" accesskey="u" href="#Beginning-a-File">Beginning a File</a> +<br> +</div> + +<h3 class="section">3.8 Software Copying Permissions</h3> + +<p><a name="index-Software-copying-permissions-255"></a><a name="index-Copying-software-256"></a><a name="index-Distribution-257"></a><a name="index-License-agreement-258"></a> +If the Texinfo file has a section containing the “General Public +License” and the distribution information and a warranty disclaimer for +the software that is documented, we recommend placing this right after +the `Top' node. The General Public License is very important to Project +GNU software. It ensures that you and others will continue to have a +right to use and share the software. + + <p>The copying and distribution information and the disclaimer are followed +by an introduction or else by the first chapter of the manual. + + <p><a name="index-Introduction_002c-as-part-of-file-259"></a>Although an introduction is not a required part of a Texinfo file, it +is very helpful. Ideally, it should state clearly and concisely what +the file is about and who would be interested in reading it. In +general, an introduction would follow the licensing and distribution +information, although sometimes people put it earlier in the document. + +<div class="node"> +<p><hr> +<a name="Ending-a-File"></a>Next: <a rel="next" accesskey="n" href="#Structuring">Structuring</a>, +Previous: <a rel="previous" accesskey="p" href="#Beginning-a-File">Beginning a File</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> +<br> +</div> + +<h2 class="chapter">4 Ending a Texinfo File</h2> + +<p><a name="index-Ending-a-Texinfo-file-260"></a><a name="index-Texinfo-file-ending-261"></a><a name="index-File-ending-262"></a><a name="index-bye-263"></a> +The end of a Texinfo file should include commands to create indices, +and the <code>@bye</code> command to mark the last line to be processed. + + <p>For example: + +<pre class="example"> @node Index + @unnumbered Index + + @printindex cp + + @bye +</pre> + <ul class="menu"> +<li><a accesskey="1" href="#Printing-Indices-_0026-Menus">Printing Indices & Menus</a>: How to print an index in hardcopy and + generate index menus in Info. +<li><a accesskey="2" href="#File-End">File End</a>: How to mark the end of a file. +</ul> + +<div class="node"> +<p><hr> +<a name="Printing-Indices-_0026-Menus"></a>Next: <a rel="next" accesskey="n" href="#File-End">File End</a>, +Up: <a rel="up" accesskey="u" href="#Ending-a-File">Ending a File</a> +<br> +</div> + +<h3 class="section">4.1 Printing Indices and Menus</h3> + +<p><a name="index-Printing-an-index-264"></a><a name="index-Indices_002c-printing-and-menus-265"></a><a name="index-Generating-menus-with-indices-266"></a><a name="index-Menus-generated-with-indices-267"></a> +To print an index means to include it as part of a manual or Info file. +This does not happen automatically just because you use <code>@cindex</code> +or other index-entry generating commands in the Texinfo file; those just +cause the raw data for the index to be accumulated. To generate an +index, you must include the <code>@printindex</code> command at the place in +the document where you want the index to appear. Also, as part of the +process of creating a printed manual, you must run a program called +<code>texindex</code> (see <a href="#Hardcopy">Hardcopy</a>) to sort the raw data to produce a +sorted index file. The sorted index file is what is actually used to +print the index. + + <p>Texinfo offers six separate types of predefined index, which suffice +in most cases. See <a href="#Indices">Indices</a>, for information on this, as well +defining your own new indices, combining indices, and, most +importantly advice on writing the actual index entries. This section +focuses on printing indices, which is done with the +<code>@printindex</code> command. + + <p><a name="index-printindex-268"></a><code>@printindex</code> takes one argument, a two-letter index +abbreviation. It reads the corresponding sorted index file (for +printed output), and formats it appropriately into an index. + + <p>The <code>@printindex</code> command does not generate a chapter heading +for the index, since different manuals have different needs. +Consequently, you should precede the <code>@printindex</code> command with +a suitable section or chapter command (usually <code>@appendix</code> or +<code>@unnumbered</code>) to supply the chapter heading and put the index +into the table of contents. Precede the chapter heading with an +<code>@node</code> line as usual. + + <p>For example: + +<pre class="smallexample"> @node Variable Index + @unnumbered Variable Index + + @printindex vr + + @node Concept Index + @unnumbered Concept Index + + @printindex cp +</pre> + <p>If you have more than one index, we recommend placing the concept index last. + + <ul> +<li>In printed output, <code>@printindex</code> produces a traditional +two-column index, with dot leaders between the index terms and page +numbers. + + <li>In Info output, <code>@printindex</code> produces a special menu containing +the line number of the entry, relative to the start of the node. Info +readers can use this to go to the exact line of an entry, not just the +containing node. (Older Info readers will just go to the node.) +Here's an example: + + <pre class="smallexample"> * First index entry: Top. (line 7) + </pre> + <p class="noindent">The actual number of spaces is variable, to right-justify +the line number; it's been reduced here to make the line fit in the +printed manual. + + <li>In plain text output, <code>@printindex</code> produces the same menu, but +the line numbers are relative to the start of the file, since that's +more convenient for that format. + + <li>In HTML and Docbook output, <code>@printindex</code> produces links +to the index entries. + + <li>In XML output, it simply records the index to be printed. +</ul> + + <p>It's not possible to generate an index when writing to standard +output; <span class="command">makeinfo</span> generates a warning in this case. + +<div class="node"> +<p><hr> +<a name="File-End"></a>Previous: <a rel="previous" accesskey="p" href="#Printing-Indices-_0026-Menus">Printing Indices & Menus</a>, +Up: <a rel="up" accesskey="u" href="#Ending-a-File">Ending a File</a> +<br> +</div> + +<h3 class="section">4.2 <code>@bye</code> File Ending</h3> + +<p><a name="index-bye-269"></a> +An <code>@bye</code> command terminates Texinfo processing. None of the +formatters read anything following <code>@bye</code>. The <code>@bye</code> +command should be on a line by itself. + + <p>If you wish, you may follow the <code>@bye</code> line with notes. These +notes will not be formatted and will not appear in either Info or a +printed manual; it is as if text after <code>@bye</code> were within +<code>@ignore</code> <small class="dots">...</small> <code>@end ignore</code>. Also, you may follow the +<code>@bye</code> line with a local variables list for Emacs. +See <a href="#Compile_002dCommand">Using Local Variables and the Compile Command</a>, +for more information. + +<div class="node"> +<p><hr> +<a name="Structuring"></a>Next: <a rel="next" accesskey="n" href="#Nodes">Nodes</a>, +Previous: <a rel="previous" accesskey="p" href="#Ending-a-File">Ending a File</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> +<br> +</div> + +<h2 class="chapter">5 Chapter Structuring</h2> + +<p><a name="index-Chapter-structuring-270"></a><a name="index-Structuring-of-chapters-271"></a> +The <dfn>chapter structuring</dfn> commands divide a document into a hierarchy of +chapters, sections, subsections, and subsubsections. These commands +generate large headings; they also provide information for the table +of contents of a printed manual (see <a href="#Contents">Generating a Table of Contents</a>). + + <p>The chapter structuring commands do not create an Info node structure, +so normally you should put an <code>@node</code> command immediately before +each chapter structuring command (see <a href="#Nodes">Nodes</a>). The only time you +are likely to use the chapter structuring commands without using the +node structuring commands is if you are writing a document that +contains no cross references and will never be transformed into Info +format. + + <p>It is unlikely that you will ever write a Texinfo file that is +intended only as an Info file and not as a printable document. If you +do, you might still use chapter structuring commands to create a +heading at the top of each node—but you don't need to. + +<ul class="menu"> +<li><a accesskey="1" href="#Tree-Structuring">Tree Structuring</a>: A manual is like an upside down tree ... +<li><a accesskey="2" href="#Structuring-Command-Types">Structuring Command Types</a>: How to divide a manual into parts. +<li><a accesskey="3" href="#makeinfo-top">makeinfo top</a>: The <code>@top</code> command, part of the `Top' node. +<li><a accesskey="4" href="#chapter">chapter</a> +<li><a accesskey="5" href="#unnumbered-_0026-appendix">unnumbered & appendix</a> +<li><a accesskey="6" href="#majorheading-_0026-chapheading">majorheading & chapheading</a> +<li><a accesskey="7" href="#section">section</a> +<li><a accesskey="8" href="#unnumberedsec-appendixsec-heading">unnumberedsec appendixsec heading</a> +<li><a accesskey="9" href="#subsection">subsection</a> +<li><a href="#unnumberedsubsec-appendixsubsec-subheading">unnumberedsubsec appendixsubsec subheading</a> +<li><a href="#subsubsection">subsubsection</a>: Commands for the lowest level sections. +<li><a href="#Raise_002flower-sections">Raise/lower sections</a>: How to change commands' hierarchical level. +</ul> + +<div class="node"> +<p><hr> +<a name="Tree-Structuring"></a>Next: <a rel="next" accesskey="n" href="#Structuring-Command-Types">Structuring Command Types</a>, +Up: <a rel="up" accesskey="u" href="#Structuring">Structuring</a> +<br> +</div> + +<h3 class="section">5.1 Tree Structure of Sections</h3> + +<p><a name="index-Tree-structuring-272"></a> +A Texinfo file is usually structured like a book with chapters, +sections, subsections, and the like. This structure can be visualized +as a tree (or rather as an upside-down tree) with the root at the top +and the levels corresponding to chapters, sections, subsection, and +subsubsections. + + <p>Here is a diagram that shows a Texinfo file with three chapters, +each of which has two sections. + +<pre class="example"> Top + | + ------------------------------------- + | | | + Chapter 1 Chapter 2 Chapter 3 + | | | + -------- -------- -------- + | | | | | | + Section Section Section Section Section Section + 1.1 1.2 2.1 2.2 3.1 3.2 +</pre> + <p>In a Texinfo file that has this structure, the beginning of Chapter 2 +looks like this: + +<pre class="example"> @node Chapter 2, Chapter 3, Chapter 1, top + @chapter Chapter 2 +</pre> + <p>The chapter structuring commands are described in the sections that +follow; the <code>@node</code> and <code>@menu</code> commands are described in +following chapters. (See <a href="#Nodes">Nodes</a>, and see <a href="#Menus">Menus</a>.) + +<div class="node"> +<p><hr> +<a name="Structuring-Command-Types"></a>Next: <a rel="next" accesskey="n" href="#makeinfo-top">makeinfo top</a>, +Previous: <a rel="previous" accesskey="p" href="#Tree-Structuring">Tree Structuring</a>, +Up: <a rel="up" accesskey="u" href="#Structuring">Structuring</a> +<br> +</div> + +<h3 class="section">5.2 Structuring Command Types</h3> + +<p>The chapter structuring commands fall into four groups or series, each +of which contains structuring commands corresponding to the +hierarchical levels of chapters, sections, subsections, and +subsubsections. + + <p>The four groups are the <code>@chapter</code> series, the +<code>@unnumbered</code> series, the <code>@appendix</code> series, and the +<code>@heading</code> series. + + <p>Each command produces titles that have a different appearance on the +printed page or Info file; only some of the commands produce +titles that are listed in the table of contents of a printed book or +manual. + + <ul> +<li>The <code>@chapter</code> and <code>@appendix</code> series of commands produce +numbered or lettered entries both in the body of a printed work and in +its table of contents. + + <li>The <code>@unnumbered</code> series of commands produce unnumbered entries +both in the body of a printed work and in its table of contents. The +<code>@top</code> command, which has a special use, is a member of this +series (see <a href="#makeinfo-top"><code>@top</code></a>). An <code>@unnumbered</code> +section should be associated with a node and be a normal part of the +document structure. + + <li>The <code>@heading</code> series of commands produce simple unnumbered +headings that do not appear in a table of contents, are not associated +with nodes, and cannot be cross-referenced. The heading commands +never start a new page. + + <li>The <code>@majorheading</code> command is similar to <code>@chapheading</code>, +except that it generates a larger vertical whitespace before the +heading. + + <li>When an <code>@setchapternewpage</code> command says to do so, the +<code>@chapter</code>, <code>@unnumbered</code>, and <code>@appendix</code> commands +start new pages in the printed manual; the <code>@heading</code> commands +do not. +</ul> + + <p>Here are the four groups of chapter structuring commands: + + <p><table summary=""><tr align="left"><td valign="top" width="19%"></td><td valign="top" width="30%"></td><td valign="top" width="29%"></td><td valign="top" width="22%">No new page +<br></td></tr><tr align="left"><td valign="top" width="19%"><i>Numbered</i> </td><td valign="top" width="30%"><i>Unnumbered</i> </td><td valign="top" width="29%"><i>Lettered/numbered</i> </td><td valign="top" width="22%"><i>Unnumbered</i> +<br></td></tr><tr align="left"><td valign="top" width="19%">In contents </td><td valign="top" width="30%">In contents </td><td valign="top" width="29%">In contents </td><td valign="top" width="22%">Not in contents +<br></td></tr><tr align="left"><td valign="top" width="19%"></td><td valign="top" width="30%"><code>@top</code> </td><td valign="top" width="29%"></td><td valign="top" width="22%"><code>@majorheading</code> +<br></td></tr><tr align="left"><td valign="top" width="19%"><code>@chapter</code> </td><td valign="top" width="30%"><code>@unnumbered</code> </td><td valign="top" width="29%"><code>@appendix</code> </td><td valign="top" width="22%"><code>@chapheading</code> +<br></td></tr><tr align="left"><td valign="top" width="19%"><code>@section</code> </td><td valign="top" width="30%"><code>@unnumberedsec</code> </td><td valign="top" width="29%"><code>@appendixsec</code> </td><td valign="top" width="22%"><code>@heading</code> +<br></td></tr><tr align="left"><td valign="top" width="19%"><code>@subsection</code> </td><td valign="top" width="30%"><code>@unnumberedsubsec</code> </td><td valign="top" width="29%"><code>@appendixsubsec</code> </td><td valign="top" width="22%"><code>@subheading</code> +<br></td></tr><tr align="left"><td valign="top" width="19%"><code>@subsubsection</code> </td><td valign="top" width="30%"><code>@unnumberedsubsubsec</code> </td><td valign="top" width="29%"><code>@appendixsubsubsec</code> </td><td valign="top" width="22%"><code>@subsubheading</code> + <br></td></tr></table> + +<div class="node"> +<p><hr> +<a name="makeinfo-top"></a>Next: <a rel="next" accesskey="n" href="#chapter">chapter</a>, +Previous: <a rel="previous" accesskey="p" href="#Structuring-Command-Types">Structuring Command Types</a>, +Up: <a rel="up" accesskey="u" href="#Structuring">Structuring</a> +<br> +</div> + +<h3 class="section">5.3 <code>@top</code></h3> + +<p>The <code>@top</code> command is a special sectioning command that you use +only after an <span class="samp">@node Top</span> line at the beginning of a Texinfo file. +The <code>@top</code> command tells the <code>makeinfo</code> formatter which node +is the `Top' node, so it can use it as the root of the node tree if your +manual uses implicit node pointers. It has the same typesetting effect as +<code>@unnumbered</code> (see <a href="#unnumbered-_0026-appendix"><code>@unnumbered</code> and <code>@appendix</code></a>). For detailed information, see <a href="#makeinfo-top-command">The <code>@top</code> Command</a>. + + <p>The <code>@top</code> node and its menu (if any) is conventionally wrapped in +an <code>@ifnottex</code> conditional so that it will appear only in Info and +HTML output, not TeX. + +<div class="node"> +<p><hr> +<a name="chapter"></a>Next: <a rel="next" accesskey="n" href="#unnumbered-_0026-appendix">unnumbered & appendix</a>, +Previous: <a rel="previous" accesskey="p" href="#makeinfo-top">makeinfo top</a>, +Up: <a rel="up" accesskey="u" href="#Structuring">Structuring</a> +<br> +</div> + +<!-- node-name, next, previous, up --> +<h3 class="section">5.4 <code>@chapter</code></h3> + +<p><a name="index-chapter-273"></a> +<code>@chapter</code> identifies a chapter in the document. Write the +command at the beginning of a line and follow it on the same line by +the title of the chapter. + + <p>For example, this chapter in this manual is entitled “Chapter +Structuring”; the <code>@chapter</code> line looks like this: + +<pre class="example"> @chapter Chapter Structuring +</pre> + <p>In TeX, the <code>@chapter</code> command creates a chapter in the +document, specifying the chapter title. The chapter is numbered +automatically. + + <p>In Info, the <code>@chapter</code> command causes the title to appear on a +line by itself, with a line of asterisks inserted underneath. Thus, +in Info, the above example produces the following output: + +<pre class="example"> Chapter Structuring + ******************* +</pre> + <p><a name="index-centerchap-274"></a>Texinfo also provides a command <code>@centerchap</code>, which is analogous +to <code>@unnumbered</code>, but centers its argument in the printed output. +This kind of stylistic choice is not usually offered by Texinfo. +<!-- but the Hacker's Dictionary wanted it ... --> + +<div class="node"> +<p><hr> +<a name="unnumbered-_0026-appendix"></a>Next: <a rel="next" accesskey="n" href="#majorheading-_0026-chapheading">majorheading & chapheading</a>, +Previous: <a rel="previous" accesskey="p" href="#chapter">chapter</a>, +Up: <a rel="up" accesskey="u" href="#Structuring">Structuring</a> +<br> +</div> + +<h3 class="section">5.5 <code>@unnumbered</code> and <code>@appendix</code></h3> + +<p><a name="index-unnumbered-275"></a><a name="index-appendix-276"></a> +Use the <code>@unnumbered</code> command to create a chapter that appears +in a printed manual without chapter numbers of any kind. Use the +<code>@appendix</code> command to create an appendix in a printed manual +that is labelled by letter instead of by number. + + <p>For Info file output, the <code>@unnumbered</code> and <code>@appendix</code> +commands are equivalent to <code>@chapter</code>: the title is printed on a +line by itself with a line of asterisks underneath. (See <a href="#chapter"><code>@chapter</code></a>.) + + <p>To create an appendix or an unnumbered chapter, write an +<code>@appendix</code> or <code>@unnumbered</code> command at the beginning of a +line and follow it on the same line by the title, as you would if you +were creating a chapter. + +<div class="node"> +<p><hr> +<a name="majorheading-_0026-chapheading"></a>Next: <a rel="next" accesskey="n" href="#section">section</a>, +Previous: <a rel="previous" accesskey="p" href="#unnumbered-_0026-appendix">unnumbered & appendix</a>, +Up: <a rel="up" accesskey="u" href="#Structuring">Structuring</a> +<br> +</div> + +<h3 class="section">5.6 <code>@majorheading</code>, <code>@chapheading</code></h3> + +<p><a name="index-majorheading-277"></a><a name="index-chapheading-278"></a> +The <code>@majorheading</code> and <code>@chapheading</code> commands put +chapter-like headings in the body of a document. + + <p>However, neither command causes TeX to produce a numbered heading +or an entry in the table of contents; and neither command causes +TeX to start a new page in a printed manual. + + <p>In TeX, an <code>@majorheading</code> command generates a larger vertical +whitespace before the heading than an <code>@chapheading</code> command but +is otherwise the same. + + <p>In Info, +the <code>@majorheading</code> and +<code>@chapheading</code> commands are equivalent to +<code>@chapter</code>: the title is printed on a line by itself with a line +of asterisks underneath. (See <a href="#chapter"><code>@chapter</code></a>.) + +<div class="node"> +<p><hr> +<a name="section"></a>Next: <a rel="next" accesskey="n" href="#unnumberedsec-appendixsec-heading">unnumberedsec appendixsec heading</a>, +Previous: <a rel="previous" accesskey="p" href="#majorheading-_0026-chapheading">majorheading & chapheading</a>, +Up: <a rel="up" accesskey="u" href="#Structuring">Structuring</a> +<br> +</div> + +<!-- node-name, next, previous, up --> +<h3 class="section">5.7 <code>@section</code></h3> + +<p><a name="index-section-279"></a> +In a printed manual, an <code>@section</code> command identifies a +numbered section within a chapter. The section title appears in the +table of contents. In Info, an <code>@section</code> command provides a +title for a segment of text, underlined with <span class="samp">=</span>. + + <p>This section is headed with an <code>@section</code> command and looks like +this in the Texinfo file: + +<pre class="example"> @section @code{@@section} +</pre> + <p>To create a section, write the <code>@section</code> command at the +beginning of a line and follow it on the same line by the section +title. + + <p>Thus, + +<pre class="example"> @section This is a section +</pre> + <p class="noindent">produces + +<pre class="example"> This is a section + ================= +</pre> + <p class="noindent">in Info. + +<div class="node"> +<p><hr> +<a name="unnumberedsec-appendixsec-heading"></a>Next: <a rel="next" accesskey="n" href="#subsection">subsection</a>, +Previous: <a rel="previous" accesskey="p" href="#section">section</a>, +Up: <a rel="up" accesskey="u" href="#Structuring">Structuring</a> +<br> +</div> + +<!-- node-name, next, previous, up --> +<h3 class="section">5.8 <code>@unnumberedsec</code>, <code>@appendixsec</code>, <code>@heading</code></h3> + +<p><a name="index-unnumberedsec-280"></a><a name="index-appendixsec-281"></a><a name="index-heading-282"></a> +The <code>@unnumberedsec</code>, <code>@appendixsec</code>, and <code>@heading</code> +commands are, respectively, the unnumbered, appendix-like, and +heading-like equivalents of the <code>@section</code> command. +(See <a href="#section"><code>@section</code></a>.) + + <dl> +<dt><code>@unnumberedsec</code><dd>The <code>@unnumberedsec</code> command may be used within an +unnumbered chapter or within a regular chapter or appendix to +provide an unnumbered section. + + <br><dt><code>@appendixsec</code><dt><code>@appendixsection</code><dd><code>@appendixsection</code> is a longer spelling of the +<code>@appendixsec</code> command; the two are synonymous. +<a name="index-appendixsection-283"></a> +Conventionally, the <code>@appendixsec</code> or <code>@appendixsection</code> +command is used only within appendices. + + <br><dt><code>@heading</code><dd>You may use the <code>@heading</code> command anywhere you wish for a +section-style heading that will not appear in the table of contents. +</dl> + +<div class="node"> +<p><hr> +<a name="subsection"></a>Next: <a rel="next" accesskey="n" href="#unnumberedsubsec-appendixsubsec-subheading">unnumberedsubsec appendixsubsec subheading</a>, +Previous: <a rel="previous" accesskey="p" href="#unnumberedsec-appendixsec-heading">unnumberedsec appendixsec heading</a>, +Up: <a rel="up" accesskey="u" href="#Structuring">Structuring</a> +<br> +</div> + +<!-- node-name, next, previous, up --> +<h3 class="section">5.9 The <code>@subsection</code> Command</h3> + +<p><a name="index-subsection-284"></a> +Subsections are to sections as sections are to chapters. +(See <a href="#section"><code>@section</code></a>.) In Info, subsection titles are +underlined with <span class="samp">-</span>. For example, + +<pre class="example"> @subsection This is a subsection +</pre> + <p class="noindent">produces + +<pre class="example"> This is a subsection + -------------------- +</pre> + <p>In a printed manual, subsections are listed in the table of contents +and are numbered three levels deep. + +<div class="node"> +<p><hr> +<a name="unnumberedsubsec-appendixsubsec-subheading"></a>Next: <a rel="next" accesskey="n" href="#subsubsection">subsubsection</a>, +Previous: <a rel="previous" accesskey="p" href="#subsection">subsection</a>, +Up: <a rel="up" accesskey="u" href="#Structuring">Structuring</a> +<br> +</div> + +<!-- node-name, next, previous, up --> +<h3 class="section">5.10 The <code>@subsection</code>-like Commands</h3> + +<p><a name="index-Subsection_002dlike-commands-285"></a><a name="index-unnumberedsubsec-286"></a><a name="index-appendixsubsec-287"></a><a name="index-subheading-288"></a> +The <code>@unnumberedsubsec</code>, <code>@appendixsubsec</code>, and +<code>@subheading</code> commands are, respectively, the unnumbered, +appendix-like, and heading-like equivalents of the <code>@subsection</code> +command. (See <a href="#subsection"><code>@subsection</code></a>.) + + <p>In Info, the <code>@subsection</code>-like commands generate a title +underlined with hyphens. In a printed manual, an <code>@subheading</code> +command produces a heading like that of a subsection except that it is +not numbered and does not appear in the table of contents. Similarly, +an <code>@unnumberedsubsec</code> command produces an unnumbered heading like +that of a subsection and an <code>@appendixsubsec</code> command produces a +subsection-like heading labelled with a letter and numbers; both of +these commands produce headings that appear in the table of +contents. + +<div class="node"> +<p><hr> +<a name="subsubsection"></a>Next: <a rel="next" accesskey="n" href="#Raise_002flower-sections">Raise/lower sections</a>, +Previous: <a rel="previous" accesskey="p" href="#unnumberedsubsec-appendixsubsec-subheading">unnumberedsubsec appendixsubsec subheading</a>, +Up: <a rel="up" accesskey="u" href="#Structuring">Structuring</a> +<br> +</div> + +<h3 class="section">5.11 The `subsub' Commands</h3> + +<p><a name="index-Subsub-commands-289"></a><a name="index-subsubsection-290"></a><a name="index-unnumberedsubsubsec-291"></a><a name="index-appendixsubsubsec-292"></a><a name="index-subsubheading-293"></a> +The fourth and lowest level sectioning commands in Texinfo are the +`subsub' commands. They are: + + <dl> +<dt><code>@subsubsection</code><dd>Subsubsections are to subsections as subsections are to sections. +(See <a href="#subsection"><code>@subsection</code></a>.) In a printed manual, +subsubsection titles appear in the table of contents and are numbered +four levels deep. + + <br><dt><code>@unnumberedsubsubsec</code><dd>Unnumbered subsubsection titles appear in the table of contents of a +printed manual, but lack numbers. Otherwise, unnumbered +subsubsections are the same as subsubsections. In Info, unnumbered +subsubsections look exactly like ordinary subsubsections. + + <br><dt><code>@appendixsubsubsec</code><dd>Conventionally, appendix commands are used only for appendices and are +lettered and numbered appropriately in a printed manual. They also +appear in the table of contents. In Info, appendix subsubsections look +exactly like ordinary subsubsections. + + <br><dt><code>@subsubheading</code><dd>The <code>@subsubheading</code> command may be used anywhere that you need +a small heading that will not appear in the table of contents. In +Info, subsubheadings look exactly like ordinary subsubsection +headings. +</dl> + + <p>In Info, `subsub' titles are underlined with periods. +For example, + +<pre class="example"> @subsubsection This is a subsubsection +</pre> + <p class="noindent">produces + +<pre class="example"> This is a subsubsection + ....................... +</pre> + <div class="node"> +<p><hr> +<a name="Raise_002flower-sections"></a>Previous: <a rel="previous" accesskey="p" href="#subsubsection">subsubsection</a>, +Up: <a rel="up" accesskey="u" href="#Structuring">Structuring</a> +<br> +</div> + +<h3 class="section">5.12 <code>@raisesections</code> and <code>@lowersections</code></h3> + +<p><a name="index-raisesections-294"></a><a name="index-lowersections-295"></a><a name="index-Raising-and-lowering-sections-296"></a><a name="index-Lowering-and-raising-sections-297"></a><a name="index-Sections_002c-raising-and-lowering-298"></a> +The <code>@raisesections</code> and <code>@lowersections</code> commands +implicitly raise and lower the hierarchical level of following +chapters, sections and the other sectioning commands. + + <p>That is, the <code>@raisesections</code> command changes sections to +chapters, subsections to sections, and so on. Conversely, the +<code>@lowersections</code> command changes chapters to sections, sections +to subsections, and so on. Thus, an <code>@lowersections</code> command +cancels an <code>@raisesections</code> command, and vice versa. + + <p><a name="index-Include-files_002c-and-section-levels-299"></a>You can use <code>@lowersections</code> to include text written as an outer +or standalone Texinfo file in another Texinfo file as an inner, +included file. Typical usage looks like this: + +<pre class="example"> @lowersections + @include somefile.texi + @raisesections +</pre> + <p class="noindent">(Without the <code>@raisesections</code>, all the subsequent +sections in the document would be lowered.) + + <p>If the included file being lowered has a <code>@top</code> node, you'll +need to conditionalize its inclusion with a flag (see <a href="#set-value">set value</a>). + + <p>Another difficulty can arise with documents that use the (recommended) +feature of <span class="command">makeinfo</span> for implicitly determining node +pointers. Since <span class="command">makeinfo</span> must assume a hierarchically +organized document to determine the pointers, you cannot just +arbitrarily sprinkle <code>@raisesections</code> and <code>@lowersections</code> +commands in the document. The final result has to have menus that +take the raising and lowering into account. Therefore, as a practical +matter, you generally only want to raise or lower large chunks, +usually in external files as shown above. + + <p>Repeated use of the commands continue to raise or lower the +hierarchical level a step at a time. An attempt to raise above +`chapter' reproduces chapter commands; an attempt to lower below +`subsubsection' reproduces subsubsection commands. Also, lowered +subsubsections and raised chapters will not work with +<span class="command">makeinfo</span>'s feature of implicitly determining node pointers, +since the menu structure won't be correct. + + <p>Write each <code>@raisesections</code> and <code>@lowersections</code> command +on a line of its own. + +<div class="node"> +<p><hr> +<a name="Nodes"></a>Next: <a rel="next" accesskey="n" href="#Menus">Menus</a>, +Previous: <a rel="previous" accesskey="p" href="#Structuring">Structuring</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> +<br> +</div> + +<h2 class="chapter">6 Nodes</h2> + +<p><dfn>Nodes</dfn> are the primary segments of a Texinfo file. They do not +in and of themselves impose a hierarchical or any other kind of +structure on a file. Nodes contain <dfn>node pointers</dfn> that name +other nodes, and can contain <dfn>menus</dfn> which are lists of nodes. In +Info, the movement commands can carry you to a pointed-to node or to a +node listed in a menu. + + <p>Node pointers and menus provide structure for Info files just as +chapters, sections, subsections, and the like, provide structure for +printed books. + + <p>Because node names are used in cross-references, it is not desirable +to casually change them. Such name changes invalidate references from +other manuals, from mail archives, and so on. + +<ul class="menu"> +<li><a accesskey="1" href="#Two-Paths">Two Paths</a>: Different commands to structure + Info output and printed output. +<li><a accesskey="2" href="#Node-Menu-Illustration">Node Menu Illustration</a>: A diagram, and sample nodes and menus. +<li><a accesskey="3" href="#node">node</a>: Creating nodes, in detail. +<li><a accesskey="4" href="#makeinfo-Pointer-Creation">makeinfo Pointer Creation</a>: Letting makeinfo determine node pointers. +<li><a accesskey="5" href="#anchor">anchor</a>: Defining arbitrary cross-reference targets. +</ul> + +<div class="node"> +<p><hr> +<a name="Two-Paths"></a>Next: <a rel="next" accesskey="n" href="#Node-Menu-Illustration">Node Menu Illustration</a>, +Up: <a rel="up" accesskey="u" href="#Nodes">Nodes</a> +<br> +</div> + +<h3 class="section">6.1 Two Paths</h3> + +<p>The node and menu commands and the chapter structuring commands are +technically independent of each other: + + <ul> +<li>In Info, node and menu commands provide structure. The chapter +structuring commands generate headings with different kinds of +underlining—asterisks for chapters, hyphens for sections, and so on; +they do nothing else. + + <li>In TeX, the chapter structuring commands generate chapter and section +numbers and tables of contents. The node and menu commands provide +information for cross references; they do nothing else. +</ul> + + <p>You can use node pointers and menus to structure an Info file any way +you want; and you can write a Texinfo file so that its Info output has a +different structure than its printed output. However, virtually all +Texinfo files are written such that the structure for the Info output +corresponds to the structure for the printed output. It is neither +convenient nor understandable to the reader to do otherwise. + + <p>Generally, printed output is structured in a tree-like hierarchy in +which the chapters are the major limbs from which the sections branch +out. Similarly, node pointers and menus are organized to create a +matching structure in the Info output. + +<div class="node"> +<p><hr> +<a name="Node-Menu-Illustration"></a>Next: <a rel="next" accesskey="n" href="#node">node</a>, +Previous: <a rel="previous" accesskey="p" href="#Two-Paths">Two Paths</a>, +Up: <a rel="up" accesskey="u" href="#Nodes">Nodes</a> +<br> +</div> + +<h3 class="section">6.2 Node and Menu Illustration</h3> + +<p>Here is a copy of the diagram shown earlier that illustrates a Texinfo +file with three chapters, each of which contains two sections. + + <p>The “root” is at the top of the diagram and the “leaves” are at the +bottom. This is how such a diagram is drawn conventionally; it +illustrates an upside-down tree. For this reason, the root node is +called the `Top' node, and `Up' node pointers carry you closer to the +root. + +<pre class="example"> Top + | + ------------------------------------- + | | | + Chapter 1 Chapter 2 Chapter 3 + | | | + -------- -------- -------- + | | | | | | + Section Section Section Section Section Section + 1.1 1.2 2.1 2.2 3.1 3.2 +</pre> + <p>The fully-written command to start Chapter 2 would be this: + +<pre class="example"> @node Chapter 2, Chapter 3, Chapter 1, Top + @comment node-name, next, previous, up +</pre> + <p class="noindent">This <code>@node</code> line says that the name of this node is “Chapter +2”, the name of the `Next' node is “Chapter 3”, the name of the +`Previous' node is “Chapter 1”, and the name of the `Up' node is +“Top”. You can omit writing out these node names if your document is +hierarchically organized (see <a href="#makeinfo-Pointer-Creation">makeinfo Pointer Creation</a>), but the +pointer relationships still obtain. + + <blockquote> +<b>Note:</b> <strong>Please Note:</strong> `Next' refers to the next node at the same +hierarchical level in the manual, not necessarily to the next node +within the Texinfo file. In the Texinfo file, the subsequent node may +be at a lower level—a section-level node most often follows a +chapter-level node, for example. `Next' and `Previous' refer to nodes +at the <em>same</em> hierarchical level. (The `Top' node contains the +exception to this rule. Since the `Top' node is the only node at that +level, `Next' refers to the first following node, which is almost always +a chapter or chapter-level node.) +</blockquote> + + <p>To go to Sections 2.1 and 2.2 using Info, you need a menu inside Chapter +2. (See <a href="#Menus">Menus</a>.) You would write the menu just +before the beginning of Section 2.1, like this: + +<pre class="example"> @menu + * Sect. 2.1:: Description of this section. + * Sect. 2.2:: + @end menu +</pre> + <p>Write the node for Sect. 2.1 like this: + +<pre class="example"> @node Sect. 2.1, Sect. 2.2, Chapter 2, Chapter 2 + @comment node-name, next, previous, up +</pre> + <p>In Info format, the `Next' and `Previous' pointers of a node usually +lead to other nodes at the same level—from chapter to chapter or from +section to section (sometimes, as shown, the `Previous' pointer points +up); an `Up' pointer usually leads to a node at the level above (closer +to the `Top' node); and a `Menu' leads to nodes at a level below (closer +to `leaves'). (A cross reference can point to a node at any level; +see <a href="#Cross-References">Cross References</a>.) + + <p>Usually, an <code>@node</code> command and a chapter structuring command are +used in sequence, along with indexing commands. (You may follow the +<code>@node</code> line with a comment line that reminds you which pointer is +which.) + + <p>Here is the beginning of the chapter in this manual called “Ending a +Texinfo File”. This shows an <code>@node</code> line followed by a comment +line, an <code>@chapter</code> line, and then by indexing lines. + +<pre class="example"> @node Ending a File, Structuring, Beginning a File, Top + @comment node-name, next, previous, up + @chapter Ending a Texinfo File + @cindex Ending a Texinfo file + @cindex Texinfo file ending + @cindex File ending +</pre> + <div class="node"> +<p><hr> +<a name="node"></a>Next: <a rel="next" accesskey="n" href="#makeinfo-Pointer-Creation">makeinfo Pointer Creation</a>, +Previous: <a rel="previous" accesskey="p" href="#Node-Menu-Illustration">Node Menu Illustration</a>, +Up: <a rel="up" accesskey="u" href="#Nodes">Nodes</a> +<br> +</div> + +<h3 class="section">6.3 The <code>@node</code> Command</h3> + +<p><a name="index-Node_002c-defined-300"></a><a name="index-node-301"></a> +A <dfn>node</dfn> is a segment of text that begins at an <code>@node</code> +command and continues until the next <code>@node</code> command. The +definition of node is different from that for chapter or section. A +chapter may contain sections and a section may contain subsections; +but a node cannot contain subnodes; the text of a node continues only +until the next <code>@node</code> command in the file. A node usually +contains only one chapter structuring command, the one that follows +the <code>@node</code> line. On the other hand, in printed output nodes +are used only for cross references, so a chapter or section may +contain any number of nodes. Indeed, a chapter usually contains +several nodes, one for each section, subsection, and +subsubsection. + + <p>To create a node, write an <code>@node</code> command at the beginning of a +line, and follow it with up to four arguments, separated by commas, on +the rest of the same line. The first argument is required; it is the +name of this node. The subsequent arguments are the names of the +`Next', `Previous', and `Up' pointers, in that order, and may be omitted +if your Texinfo document is hierarchically organized (see <a href="#makeinfo-Pointer-Creation">makeinfo Pointer Creation</a>). + + <p>You may insert spaces before each name if you wish; the spaces are +ignored. You must write the name of the node and (if present) the names +of the `Next', `Previous', and `Up' pointers all on the same line. +Otherwise, the formatters fail. (see <a href="info.html#Top">info</a>, for more +information about nodes in Info.) + + <p>Usually, you write one of the chapter-structuring command lines +immediately after an <code>@node</code> line—for example, an +<code>@section</code> or <code>@subsection</code> line. (See <a href="#Structuring-Command-Types">Structuring Command Types</a>.) + + <blockquote> +<b>Note:</b> The GNU Emacs Texinfo mode updating commands work +only with Texinfo files in which <code>@node</code> lines are followed by chapter +structuring lines. See <a href="#Updating-Requirements">Updating Requirements</a>. +</blockquote> + + <p>TeX uses <code>@node</code> lines to identify the names to use for cross +references. For this reason, you must write <code>@node</code> lines in a +Texinfo file that you intend to format for printing, even if you do not +intend to format it for Info. (Cross references, such as the one at the +end of this sentence, are made with <code>@xref</code> and related commands; +see <a href="#Cross-References">Cross References</a>.) + +<ul class="menu"> +<li><a accesskey="1" href="#Node-Names">Node Names</a>: How to choose node and pointer names. +<li><a accesskey="2" href="#Writing-a-Node">Writing a Node</a>: How to write an <code>@node</code> line. +<li><a accesskey="3" href="#Node-Line-Tips">Node Line Tips</a>: Keep names short. +<li><a accesskey="4" href="#Node-Line-Requirements">Node Line Requirements</a>: Keep names unique, without @-commands. +<li><a accesskey="5" href="#First-Node">First Node</a>: How to write a `Top' node. +<li><a accesskey="6" href="#makeinfo-top-command">makeinfo top command</a>: How to use the <code>@top</code> command. +</ul> + +<div class="node"> +<p><hr> +<a name="Node-Names"></a>Next: <a rel="next" accesskey="n" href="#Writing-a-Node">Writing a Node</a>, +Up: <a rel="up" accesskey="u" href="#node">node</a> +<br> +</div> + +<h4 class="subsection">6.3.1 Choosing Node and Pointer Names</h4> + +<p><a name="index-Node-names_002c-choosing-302"></a>The name of a node identifies the node. The pointers enable +you to reach other nodes and consist simply of the names of those nodes. + + <p>Normally, a node's `Up' pointer contains the name of the node whose menu +mentions that node. The node's `Next' pointer contains the name of the +node that follows that node in that menu and its `Previous' pointer +contains the name of the node that precedes it in that menu. When a +node's `Previous' node is the same as its `Up' node, both node pointers +name the same node. + + <p>Usually, the first node of a Texinfo file is the `Top' node, and its +`Up' and `Previous' pointers point to the <span class="file">dir</span> file, which +contains the main menu for all of Info. + + <p>The `Top' node itself contains the main or master menu for the manual. +Also, it is helpful to include a brief description of the manual in the +`Top' node. See <a href="#First-Node">First Node</a>, for information on how to write the +first node of a Texinfo file. + + <p>Even when you explicitly specify all pointers, that does not mean you +can write the nodes in the Texinfo source file in an arbitrary order! +Because TeX processes the file sequentially, irrespective of node +pointers, you must write the nodes in the order you wish them to appear +in the printed output. + +<div class="node"> +<p><hr> +<a name="Writing-a-Node"></a>Next: <a rel="next" accesskey="n" href="#Node-Line-Tips">Node Line Tips</a>, +Previous: <a rel="previous" accesskey="p" href="#Node-Names">Node Names</a>, +Up: <a rel="up" accesskey="u" href="#node">node</a> +<br> +</div> + +<h4 class="subsection">6.3.2 How to Write an <code>@node</code> Line</h4> + +<p><a name="index-Writing-an-_0040code_007b_0040_0040node_007d-line-303"></a><a name="index-_0040code_007b_0040_0040node_007d-line-writing-304"></a><a name="index-Node-line-writing-305"></a> +The easiest way to write an <code>@node</code> line is to write <code>@node</code> +at the beginning of a line and then the name of the node, like +this: + +<pre class="example"> @node <var>node-name</var> +</pre> + <p>If you are using GNU Emacs, you can use the update node commands +provided by Texinfo mode to insert the names of the pointers; or you +can leave the pointers out of the Texinfo file and let <code>makeinfo</code> +insert node pointers into the Info file it creates. (See <a href="#Texinfo-Mode">Texinfo Mode</a>, and <a href="#makeinfo-Pointer-Creation">makeinfo Pointer Creation</a>.) + + <p>Alternatively, you can insert the `Next', `Previous', and `Up' +pointers yourself. If you do this, you may find it helpful to use the +Texinfo mode keyboard command <kbd>C-c C-c n</kbd>. This command inserts +<span class="samp">@node</span> and a comment line listing the names of the pointers in +their proper order. The comment line helps you keep track of which +arguments are for which pointers. This comment line is especially useful +if you are not familiar with Texinfo. + + <p>The template for a fully-written-out node line with `Next', `Previous', +and `Up' pointers looks like this: + +<pre class="example"> @node <var>node-name</var>, <var>next</var>, <var>previous</var>, <var>up</var> +</pre> + <p>If you wish, you can ignore <code>@node</code> lines altogether in your first +draft and then use the <code>texinfo-insert-node-lines</code> command to +create <code>@node</code> lines for you. However, we do not recommend this +practice. It is better to name the node itself at the same time that +you write a segment so you can easily make cross references. A large +number of cross references are an especially important feature of a good +Info file. + + <p>After you have inserted an <code>@node</code> line, you should immediately +write an @-command for the chapter or section and insert its name. +Next (and this is important!), put in several index entries. Usually, +you will find at least two and often as many as four or five ways of +referring to the node in the index. Use them all. This will make it +much easier for people to find the node. + +<div class="node"> +<p><hr> +<a name="Node-Line-Tips"></a>Next: <a rel="next" accesskey="n" href="#Node-Line-Requirements">Node Line Requirements</a>, +Previous: <a rel="previous" accesskey="p" href="#Writing-a-Node">Writing a Node</a>, +Up: <a rel="up" accesskey="u" href="#node">node</a> +<br> +</div> + +<h4 class="subsection">6.3.3 <code>@node</code> Line Tips</h4> + +<p>Here are three suggestions: + + <ul> +<li>Try to pick node names that are informative but short. + + <p>In the Info file, the file name, node name, and pointer names are all +inserted on one line, which may run into the right edge of the window. +(This does not cause a problem with Info, but is ugly.) + + <li>Try to pick node names that differ from each other near the beginnings +of their names. This way, it is easy to use automatic name completion in +Info. + + <li>By convention, node names are capitalized just as they would be for +section or chapter titles—initial and significant words are +capitalized; others are not. +</ul> + +<div class="node"> +<p><hr> +<a name="Node-Line-Requirements"></a>Next: <a rel="next" accesskey="n" href="#First-Node">First Node</a>, +Previous: <a rel="previous" accesskey="p" href="#Node-Line-Tips">Node Line Tips</a>, +Up: <a rel="up" accesskey="u" href="#node">node</a> +<br> +</div> + +<h4 class="subsection">6.3.4 <code>@node</code> Line Requirements</h4> + +<p><a name="index-Node-line-requirements-306"></a><a name="index-Restrictions-on-node-names-307"></a>Here are several requirements for <code>@node</code> lines: + + +<a name="index-Unique-nodename-requirement-308"></a> +<a name="index-Node-name-must-be-unique-309"></a> +<ul><li>All the node names for a single Info file must be unique. + + <p>Duplicates confuse the Info movement commands. This means, for +example, that if you end every chapter with a summary, you must name +each summary node differently. You cannot just call each one +“Summary”. You may, however, duplicate the titles of chapters, sections, +and the like. Thus you can end each chapter in a book with a section +called “Summary”, so long as the node names for those sections are all +different. + + <li>A pointer name must be the name of a node. + + <p>The node to which a pointer points may come before or after the +node containing the pointer. + + <p><a name="index-_0040_0040_002dcommands-in-nodename-310"></a><a name="index-Node-name_002c-should-not-contain-_0040_0040_002dcommands-311"></a><li>@-commands in node names are not allowed. This includes punctuation +characters that are escaped with a <span class="samp">@</span>, such as <code>@</code> and +<code>{</code>, and accent commands such as <span class="samp">@'</span>. (For a few cases +when this is useful, Texinfo has limited support for using +@-commands<!-- /@w --> in node names; see <a href="#Pointer-Validation">Pointer Validation</a>.) Perhaps +this limitation will be removed some day. + + <li><a name="index-Colon-in-nodename-312"></a><a name="index-Comma-in-nodename-313"></a><a name="index-Parentheses-in-nodename-314"></a><a name="index-Period-in-nodename-315"></a><a name="index-Characters_002c-invalid-in-node-name-316"></a><a name="index-Invalid-characters-in-node-names-317"></a><a name="index-Node-names_002c-invalid-characters-in-318"></a>Unfortunately, you cannot use periods, commas, colons or parentheses +within a node name; these confuse the Texinfo processors. Perhaps +this limitation will be removed some day, too. + + <p>For example, the following is a section title in this manual: + + <pre class="smallexample"> @code{@@unnumberedsec}, @code{@@appendixsec}, @code{@@heading} + </pre> + <p class="noindent">But the corresponding node name lacks the commas and the @'s: + + <pre class="smallexample"> unnumberedsec appendixsec heading + </pre> + <p><a name="index-Case-in-node-name-319"></a><li>Case is significant in node names. + + <p><a name="index-White-space-in-node-name-320"></a><a name="index-Spaces-in-node-name-321"></a>Spaces before and after names on the <span class="samp">@node</span> line are ignored, +but spaces “inside” a name are significant. For example: + + <pre class="example"> @node foo bar, + @node foo bar , + @node foo bar , + </pre> + <p class="noindent">all define the same node, <span class="samp">foo bar</span>. References to the +node should all use that name, without the leading or trailing spaces, +but with the internal spaces. +</ul> + +<div class="node"> +<p><hr> +<a name="First-Node"></a>Next: <a rel="next" accesskey="n" href="#makeinfo-top-command">makeinfo top command</a>, +Previous: <a rel="previous" accesskey="p" href="#Node-Line-Requirements">Node Line Requirements</a>, +Up: <a rel="up" accesskey="u" href="#node">node</a> +<br> +</div> + +<h4 class="subsection">6.3.5 The First Node</h4> + +<p><a name="index-Top-node-is-first-322"></a><a name="index-First-node-323"></a> +The first node of a Texinfo file is the <dfn>Top</dfn> node, except in an +included file (see <a href="#Include-Files">Include Files</a>). The Top node should contain a +short summary, copying permissions, and a master menu. See <a href="#The-Top-Node">The Top Node</a>, for more information on the Top node contents and examples. + + <p>Here is a description of the node pointers to be used in the Top node: + + <ul> +<li><a name="index-Up-node-of-Top-node-324"></a><a name="index-_0028dir_0029-as-Up-node-of-Top-node-325"></a>The Top node (which must be named <span class="samp">top</span> or <span class="samp">Top</span>) should have +as its `Up' node the name of a node in another file, where there is a +menu that leads to this file. Specify the file name in parentheses. + + <p>Usually, all Info files are installed in the same Info directory tree; +in this case, use <span class="samp">(dir)</span> as the parent of the Top node; this is +short for <span class="samp">(dir)top</span>, and specifies the Top node in the <span class="file">dir</span> +file, which contains the main menu for the Info system as a whole. + + <li><a name="index-Previous-node-of-Top-node-326"></a>On the other hand, do not define the `Previous' node of the Top node to +be <span class="samp">(dir)</span>, as it causes confusing behavior for users: if you are +in the Top node and hits <DEL> to go backwards, you wind up in the +middle of the some other entry in the <span class="file">dir</span> file, which has nothing +to do with what you were reading. + + <li><a name="index-Next-node-of-Top-node-327"></a>The `Next' node of the Top node should be the first chapter in your +document. + + </ul> + + <p>See <a href="#Installing-an-Info-File">Installing an Info File</a>, for more information about installing +an Info file in the <span class="file">info</span> directory. + + <p>For concreteness, here is an example with explicit pointers (which you +can maintain automatically with the texinfo mode commands): + + <p>Or you can leave the pointers off entirely and let the tools implicitly +define them. This is recommended. Thus: + +<pre class="example"> @node Top +</pre> + <div class="node"> +<p><hr> +<a name="makeinfo-top-command"></a>Previous: <a rel="previous" accesskey="p" href="#First-Node">First Node</a>, +Up: <a rel="up" accesskey="u" href="#node">node</a> +<br> +</div> + +<h4 class="subsection">6.3.6 The <code>@top</code> Sectioning Command</h4> + +<p><a name="index-top-_0040r_007b_0028_0040_0040_002dcommand_0029_007d-328"></a> +A special sectioning command, <code>@top</code> should be used with the +<code>@node Top</code> line. The <code>@top</code> sectioning command tells +<code>makeinfo</code> that it marks the `Top' node in the file. It provides +the information that <code>makeinfo</code> needs to insert node pointers +automatically. Write the <code>@top</code> command at the beginning of the +line immediately following the <code>@node Top</code> line. Write the title +on the remaining part of the same line as the <code>@top</code> command. + + <p>In Info, the <code>@top</code> sectioning command causes the title to appear +on a line by itself, with a line of asterisks inserted underneath, as +other sectioning commands do. + + <p>In TeX and <code>texinfo-format-buffer</code>, the <code>@top</code> +sectioning command is merely a synonym for <code>@unnumbered</code>. +Neither of these formatters require an <code>@top</code> command, and do +nothing special with it. You can use <code>@chapter</code> or +<code>@unnumbered</code> after the <code>@node Top</code> line when you use +these formatters. Also, you can use <code>@chapter</code> or +<code>@unnumbered</code> when you use the Texinfo updating commands to +create or update pointers and menus. + + <p>Thus, in practice, a Top node starts like this: + +<pre class="example"> @node Top + @top Your Manual Title +</pre> + <div class="node"> +<p><hr> +<a name="makeinfo-Pointer-Creation"></a>Next: <a rel="next" accesskey="n" href="#anchor">anchor</a>, +Previous: <a rel="previous" accesskey="p" href="#node">node</a>, +Up: <a rel="up" accesskey="u" href="#Nodes">Nodes</a> +<br> +</div> + +<h3 class="section">6.4 Creating Pointers with <code>makeinfo</code></h3> + +<p><a name="index-Creating-pointers-with-_0040code_007bmakeinfo_007d-329"></a><a name="index-Pointer-creation-with-_0040code_007bmakeinfo_007d-330"></a><a name="index-Automatic-pointer-creation-with-_0040code_007bmakeinfo_007d-331"></a> +The <code>makeinfo</code> program has a feature for automatically determining +node pointers for a hierarchically organized document. + + <p>When you take advantage of this feature, you do not need to write the +`Next', `Previous', and `Up' pointers after the name of a node. +However, you must write a sectioning command, such as <code>@chapter</code> +or <code>@section</code>, on the line immediately following each truncated +<code>@node</code> line (except that comment lines may intervene). + + <p>In addition, you must follow the `Top' <code>@node</code> line with a line +beginning with <code>@top</code> to mark the `Top' node in the +file. See <a href="#makeinfo-top"><code>@top</code></a>. + + <p>Finally, you must write the name of each node (except for the `Top' +node) in a menu that is one or more hierarchical levels above the +node's hierarchical level. + + <p>This implicit node pointer insertion feature in <code>makeinfo</code> +relieves you from the need to update menus and pointers manually or +with Texinfo mode commands. (See <a href="#Updating-Nodes-and-Menus">Updating Nodes and Menus</a>.) + + <p>In most cases, you will want to take advantage of this feature and not +redundantly specify node pointers. However, Texinfo documents are not +required to be organized hierarchically or in fact to contain +sectioning commands at all (for example, if you never intend the +document to be printed). The special procedure for handling the short +text before a menu (see <a href="#Menus">Menus</a>) also disables this +feature, for that group of nodes. In those cases, you will need to +explicitly specify the pointers. + +<div class="node"> +<p><hr> +<a name="anchor"></a>Previous: <a rel="previous" accesskey="p" href="#makeinfo-Pointer-Creation">makeinfo Pointer Creation</a>, +Up: <a rel="up" accesskey="u" href="#Nodes">Nodes</a> +<br> +</div> + +<h3 class="section">6.5 <code>@anchor</code>: Defining Arbitrary Cross-reference Targets</h3> + +<p><a name="index-anchor-332"></a><a name="index-Anchors-333"></a><a name="index-Cross_002dreference-targets_002c-arbitrary-334"></a><a name="index-Targets-for-cross_002dreferences_002c-arbitrary-335"></a> +An <dfn>anchor</dfn> is a position in your document, labeled so that +cross-references can refer to it, just as they can to nodes. You create +an anchor with the <code>@anchor</code> command, and give the label as a +normal brace-delimited argument. For example: + +<pre class="example"> This marks the @anchor{x-spot}spot. + ... + @xref{x-spot,,the spot}. +</pre> + <p class="noindent">produces: + +<pre class="example"> This marks the spot. + ... + See [the spot], page 1. +</pre> + <p>As you can see, the <code>@anchor</code> command itself produces no output. +This example defines an anchor `x-spot' just before the word `spot'. +You can refer to it later with an <code>@xref</code> or other cross-reference +command, as shown. See <a href="#Cross-References">Cross References</a>, for details on the +cross-reference commands. + + <p>It is best to put <code>@anchor</code> commands just before the position you +wish to refer to; that way, the reader's eye is led on to the correct +text when they jump to the anchor. You can put the <code>@anchor</code> +command on a line by itself if that helps readability of the source. +Spaces are always ignored after <code>@anchor</code>. + + <p>Anchor names and node names may not conflict. Anchors and nodes are +given similar treatment in some ways; for example, the <code>goto-node</code> +command in standalone Info takes either an anchor name or a node name as +an argument. (See <a href="info-stnd.html#goto_002dnode">goto-node (GNU Info)</a>.) + +<div class="node"> +<p><hr> +<a name="Menus"></a>Next: <a rel="next" accesskey="n" href="#Cross-References">Cross References</a>, +Previous: <a rel="previous" accesskey="p" href="#Nodes">Nodes</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> +<br> +</div> + +<h2 class="chapter">7 Menus</h2> + +<p><a name="index-Menus-336"></a><a name="index-menu-337"></a> +<dfn>Menus</dfn> contain pointers to subordinate nodes. In online output, +you use menus to go to such nodes. Menus have no effect in printed +manuals and do not appear in them. + + <p>A node with a menu should not contain much text. If you find yourself +writing a lot of before a menu, we generally recommend moving most of +the text into a new subnode—all but a paragraph or two. Otherwise, +a reader with a terminal that displays only a few lines may miss the +menu and its associated text. As a practical matter, it is best to +locate a menu within 20 or so lines of the beginning of the node. + +<ul class="menu"> +<li><a accesskey="1" href="#Menu-Location">Menu Location</a>: Menus go at the ends of short nodes. +<li><a accesskey="2" href="#Writing-a-Menu">Writing a Menu</a>: What is a menu? +<li><a accesskey="3" href="#Menu-Parts">Menu Parts</a>: A menu entry has three parts. +<li><a accesskey="4" href="#Less-Cluttered-Menu-Entry">Less Cluttered Menu Entry</a>: Two part menu entry. +<li><a accesskey="5" href="#Menu-Example">Menu Example</a>: Two and three part menu entries. +<li><a accesskey="6" href="#Other-Info-Files">Other Info Files</a>: How to refer to a different Info file. +</ul> + +<div class="node"> +<p><hr> +<a name="Menu-Location"></a>Next: <a rel="next" accesskey="n" href="#Writing-a-Menu">Writing a Menu</a>, +Up: <a rel="up" accesskey="u" href="#Menus">Menus</a> +<br> +</div> + +<h3 class="section">7.1 Menu Location</h3> + +<p><a name="index-Menu-location-338"></a><a name="index-Location-of-menus-339"></a> +A menu must be located at the end of a node, without any regular text +or additional commands between the <code>@end menu</code> and the beginning +of the next node. (As a consequence, there may be at most one menu in +a node.) + + <p><a name="index-Info-format_002c-and-menus-340"></a>This is actually a useful restriction, since a reader who uses the +menu could easily miss any such text. Technically, it is necessary +because in Info format, there is no marker for the end of a menu, so +Info-reading programs would have no way to know when the menu ends and +normal text resumes. + + <p><a name="index-Hierarchical-documents_002c-and-menus-341"></a>Technically, menus can carry you to any node, regardless of the +structure of the document; even to nodes in a different Info file. +However, we do not recommend ever making use of this, because the +<span class="command">makeinfo</span> implicit pointer creation feature (see <a href="#makeinfo-Pointer-Creation">makeinfo Pointer Creation</a>) and GNU Emacs Texinfo mode updating commands work +only to create menus of subordinate nodes in a hierarchically +structured document. Instead, use cross references to refer to +arbitrary nodes. + + <p>In the past, we recommended using a <span class="samp">@heading</span> command within an +<code>@ifinfo</code> conditional instead of the normal sectioning commands +after a very short node with a menu. This had the advantage of making +the printed output look better, because there was no very short text +between two headings on the page. But aside from not working with +<span class="command">makeinfo</span>'s implicit pointer creation, it also makes the XML +output incorrect, since it does not reflect the true document +structure. So, unfortunately we can no longer recommend this. + +<div class="node"> +<p><hr> +<a name="Writing-a-Menu"></a>Next: <a rel="next" accesskey="n" href="#Menu-Parts">Menu Parts</a>, +Previous: <a rel="previous" accesskey="p" href="#Menu-Location">Menu Location</a>, +Up: <a rel="up" accesskey="u" href="#Menus">Menus</a> +<br> +</div> + +<h3 class="section">7.2 Writing a Menu</h3> + +<p><a name="index-Writing-a-menu-342"></a><a name="index-Menu-writing-343"></a> +A menu consists of an <code>@menu</code> command on a line by itself +followed by menu entry lines or menu comment lines and then by an +<code>@end menu</code> command on a line by itself. + + <p>A menu looks like this: + +<pre class="example"> @menu + Larger Units of Text + + * Files:: All about handling files. + * Multiples: Buffers. Multiple buffers; editing + several files at once. + @end menu +</pre> + <p>In a menu, every line that begins with an <span class="samp">* </span><!-- /@w --> is a <dfn>menu +entry</dfn>. (Note the space after the asterisk.) A line that does not +start with an <span class="samp">* </span><!-- /@w --> may also appear in a menu. Such a line is +not a menu entry but is a menu comment line that appears in the Info +file. In the example above, the line <span class="samp">Larger Units of Text</span> is a +menu comment line; the two lines starting with <span class="samp">* </span><!-- /@w --> are menu +<a name="index-Spaces_002c-in-menus-344"></a>entries. Space characters in a menu are preserved as-is; this allows +you to format the menu as you wish. + +<div class="node"> +<p><hr> +<a name="Menu-Parts"></a>Next: <a rel="next" accesskey="n" href="#Less-Cluttered-Menu-Entry">Less Cluttered Menu Entry</a>, +Previous: <a rel="previous" accesskey="p" href="#Writing-a-Menu">Writing a Menu</a>, +Up: <a rel="up" accesskey="u" href="#Menus">Menus</a> +<br> +</div> + +<h3 class="section">7.3 The Parts of a Menu</h3> + +<p><a name="index-Parts-of-a-menu-345"></a><a name="index-Menu-parts-346"></a><a name="index-_0040code_007b_0040_0040menu_007d-parts-347"></a> +A menu entry has three parts, only the second of which is required: + + <ol type=1 start=1> +<li>The menu entry name (optional). + + <li>The name of the node (required). + + <li>A description of the item (optional). + </ol> + + <p>The template for a menu entry looks like this: + +<pre class="example"> * <var>menu-entry-name</var>: <var>node-name</var>. <var>description</var> +</pre> + <p>Follow the menu entry name with a single colon and follow the node name +with tab, comma, period, or newline. + + <p>In Info, a user selects a node with the <kbd>m</kbd> (<code>Info-menu</code>) +command. The menu entry name is what the user types after the <kbd>m</kbd> +command. + + <p>The third part of a menu entry is a descriptive phrase or sentence. +Menu entry names and node names are often short; the description +explains to the reader what the node is about. A useful description +complements the node name rather than repeats it. The description, +which is optional, can spread over two or more lines; if it does, some +authors prefer to indent the second line while others prefer to align it +with the first (and all others). It's up to you. + +<div class="node"> +<p><hr> +<a name="Less-Cluttered-Menu-Entry"></a>Next: <a rel="next" accesskey="n" href="#Menu-Example">Menu Example</a>, +Previous: <a rel="previous" accesskey="p" href="#Menu-Parts">Menu Parts</a>, +Up: <a rel="up" accesskey="u" href="#Menus">Menus</a> +<br> +</div> + +<!-- node-name, next, previous, up --> +<h3 class="section">7.4 Less Cluttered Menu Entry</h3> + +<p><a name="index-Two-part-menu-entry-348"></a><a name="index-Double_002dcolon-menu-entries-349"></a><a name="index-Menu-entries-with-two-colons-350"></a><a name="index-Less-cluttered-menu-entry-351"></a><a name="index-Uncluttered-menu-entry-352"></a> +When the menu entry name and node name are the same, you can write +the name immediately after the asterisk and space at the beginning of +the line and follow the name with two colons. + + <p>For example, write + +<pre class="example"> * Name:: <var>description</var> +</pre> + <p class="noindent">instead of + +<pre class="example"> * Name: Name. <var>description</var> +</pre> + <p>You should use the node name for the menu entry name whenever possible, +since it reduces visual clutter in the menu. + +<div class="node"> +<p><hr> +<a name="Menu-Example"></a>Next: <a rel="next" accesskey="n" href="#Other-Info-Files">Other Info Files</a>, +Previous: <a rel="previous" accesskey="p" href="#Less-Cluttered-Menu-Entry">Less Cluttered Menu Entry</a>, +Up: <a rel="up" accesskey="u" href="#Menus">Menus</a> +<br> +</div> + +<!-- node-name, next, previous, up --> +<h3 class="section">7.5 A Menu Example</h3> + +<p><a name="index-Menu-example-353"></a><a name="index-Example-menu-354"></a> +A menu looks like this in Texinfo: + +<pre class="example"> @menu + * menu entry name: Node name. A short description. + * Node name:: This form is preferred. + @end menu +</pre> + <p class="noindent">This produces: + +<pre class="example"> * menu: + + * menu entry name: Node name. A short description. + * Node name:: This form is preferred. +</pre> + <p>Here is an example as you might see it in a Texinfo file: + +<pre class="example"> @menu + Larger Units of Text + + * Files:: All about handling files. + * Multiples: Buffers. Multiple buffers; editing + several files at once. + @end menu +</pre> + <p class="noindent">This produces: + +<pre class="example"> * menu: + Larger Units of Text + + * Files:: All about handling files. + * Multiples: Buffers. Multiple buffers; editing + several files at once. +</pre> + <p>In this example, the menu has two entries. <span class="samp">Files</span> is both a menu +entry name and the name of the node referred to by that name. +<span class="samp">Multiples</span> is the menu entry name; it refers to the node named +<span class="samp">Buffers</span>. The line <span class="samp">Larger Units of Text</span> is a comment; it +appears in the menu, but is not an entry. + + <p>Since no file name is specified with either <span class="samp">Files</span> or +<span class="samp">Buffers</span>, they must be the names of nodes in the same Info file +(see <a href="#Other-Info-Files">Referring to Other Info Files</a>). + +<div class="node"> +<p><hr> +<a name="Other-Info-Files"></a>Previous: <a rel="previous" accesskey="p" href="#Menu-Example">Menu Example</a>, +Up: <a rel="up" accesskey="u" href="#Menus">Menus</a> +<br> +</div> + +<!-- node-name, next, previous, up --> +<h3 class="section">7.6 Referring to Other Info Files</h3> + +<p><a name="index-Referring-to-other-Info-files-355"></a><a name="index-Nodes-in-other-Info-files-356"></a><a name="index-Other-Info-files_0027-nodes-357"></a><a name="index-Going-to-other-Info-files_0027-nodes-358"></a><a name="index-Info_003b-other-files_0027-nodes-359"></a> +You can create a menu entry that enables a reader in Info to go to a +node in another Info file by writing the file name in parentheses just +before the node name. In this case, you should use the three-part menu +entry format, which saves the reader from having to type the file +name. + + <p>The format looks like this: + +<pre class="example"> @menu + * <var>first-entry-name</var>:(<var>filename</var>)<var>nodename</var>. <var>description</var> + * <var>second-entry-name</var>:(<var>filename</var>)<var>second-node</var>. <var>description</var> + @end menu +</pre> + <p>For example, to refer directly to the <span class="samp">Outlining</span> and +<span class="samp">Rebinding</span> nodes in the <cite>Emacs Manual</cite>, you would write a +menu like this: + +<pre class="example"> @menu + * Outlining: (emacs)Outline Mode. The major mode for + editing outlines. + * Rebinding: (emacs)Rebinding. How to redefine the + meaning of a key. + @end menu +</pre> + <p>If you do not list the node name, but only name the file, then Info +presumes that you are referring to the `Top' node. + + <p>The <span class="file">dir</span> file that contains the main menu for Info has menu +entries that list only file names. These take you directly to the `Top' +nodes of each Info document. (See <a href="#Installing-an-Info-File">Installing an Info File</a>.) + + <p>For example: + +<pre class="example"> * Info: (info). Documentation browsing system. + * Emacs: (emacs). The extensible, self-documenting + text editor. +</pre> + <p class="noindent">(The <span class="file">dir</span> top level directory for the Info system is an Info file, +not a Texinfo file, but a menu entry looks the same in both types of +file.) + + <p>The GNU Emacs Texinfo mode menu updating commands only work with nodes +within the current buffer, so you cannot use them to create menus that +refer to other files. You must write such menus by hand. + +<div class="node"> +<p><hr> +<a name="Cross-References"></a>Next: <a rel="next" accesskey="n" href="#Marking-Text">Marking Text</a>, +Previous: <a rel="previous" accesskey="p" href="#Menus">Menus</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> +<br> +</div> + +<h2 class="chapter">8 Cross References</h2> + +<p><a name="index-Making-cross-references-360"></a><a name="index-Cross-references-361"></a><a name="index-References-362"></a> +<dfn>Cross references</dfn> are used to refer the reader to other parts of the +same or different Texinfo files. In Texinfo, nodes and anchors are the +places to which cross references can refer. + +<ul class="menu"> +<li><a accesskey="1" href="#References">References</a>: What cross references are for. +<li><a accesskey="2" href="#Cross-Reference-Commands">Cross Reference Commands</a>: A summary of the different commands. +<li><a accesskey="3" href="#Cross-Reference-Parts">Cross Reference Parts</a>: A cross reference has several parts. +<li><a accesskey="4" href="#xref">xref</a>: Begin a reference with `See' ... +<li><a accesskey="5" href="#Top-Node-Naming">Top Node Naming</a>: How to refer to the beginning of another file. +<li><a accesskey="6" href="#ref">ref</a>: A reference for the last part of a sentence. +<li><a accesskey="7" href="#pxref">pxref</a>: How to write a parenthetical cross reference. +<li><a accesskey="8" href="#inforef">inforef</a>: How to refer to an Info-only file. +<li><a accesskey="9" href="#uref">uref</a>: How to refer to a uniform resource locator. +</ul> + +<div class="node"> +<p><hr> +<a name="References"></a>Next: <a rel="next" accesskey="n" href="#Cross-Reference-Commands">Cross Reference Commands</a>, +Up: <a rel="up" accesskey="u" href="#Cross-References">Cross References</a> +<br> +</div> + +<h3 class="section">8.1 What References Are For</h3> + +<p>Often, but not always, a printed document should be designed so that +it can be read sequentially. People tire of flipping back and forth +to find information that should be presented to them as they need +it. + + <p>However, in any document, some information will be too detailed for +the current context, or incidental to it; use cross references to +provide access to such information. Also, an online help system or a +reference manual is not like a novel; few read such documents in +sequence from beginning to end. Instead, people look up what they +need. For this reason, such creations should contain many cross +references to help readers find other information that they may not +have read. + + <p>In a printed manual, a cross reference results in a page reference, +unless it is to another manual altogether, in which case the cross +reference names that manual. + + <p>In Info, a cross reference results in an entry that you can follow +using the Info <span class="samp">f</span> command. (see <a href="info.html#Help_002dXref">Following cross-references</a>.) + + <p>The various cross reference commands use nodes (or anchors, +see <a href="#anchor"><code>@anchor</code></a>) to define cross reference locations. +This is evident in Info, in which a cross reference takes you to the +specified location. TeX also uses nodes to define cross reference +locations, but the action is less obvious. When TeX generates a DVI +file, it records each node's page number and uses the page numbers in making +references. Thus, if you are writing a manual that will only be +printed, and will not be used online, you must nonetheless write +<code>@node</code> lines to name the places to which you make cross +references. + +<div class="node"> +<p><hr> +<a name="Cross-Reference-Commands"></a>Next: <a rel="next" accesskey="n" href="#Cross-Reference-Parts">Cross Reference Parts</a>, +Previous: <a rel="previous" accesskey="p" href="#References">References</a>, +Up: <a rel="up" accesskey="u" href="#Cross-References">Cross References</a> +<br> +</div> + +<!-- node-name, next, previous, up --> +<h3 class="section">8.2 Different Cross Reference Commands</h3> + +<p><a name="index-Different-cross-reference-commands-363"></a> +There are four different cross reference commands: + + <dl> +<dt><code>@xref</code><dd>Used to start a sentence in the printed manual saying `See <small class="dots">...</small>'<!-- /@w --> +or an Info cross-reference saying <span class="samp">*Note </span><var>name</var><span class="samp">: </span><var>node</var><span class="samp">.</span>. + + <br><dt><code>@ref</code><dd>Used within or, more often, at the end of a sentence; same as +<code>@xref</code> for Info; produces just the reference in the printed +manual without a preceding `See'. + + <br><dt><code>@pxref</code><dd>Used within parentheses to make a reference that suits both an Info +file and a printed book. Starts with a lower case `see' within the +printed manual. (<span class="samp">p</span> is for `parenthesis'.) + + <br><dt><code>@inforef</code><dd>Used to make a reference to an Info file for which there is no printed +manual. +</dl> + +<p class="noindent">(The <code>@cite</code> command is used to make references to books and +manuals for which there is no corresponding Info file and, therefore, +no node to which to point. See <a href="#cite"><code>@cite</code></a>.) + +<div class="node"> +<p><hr> +<a name="Cross-Reference-Parts"></a>Next: <a rel="next" accesskey="n" href="#xref">xref</a>, +Previous: <a rel="previous" accesskey="p" href="#Cross-Reference-Commands">Cross Reference Commands</a>, +Up: <a rel="up" accesskey="u" href="#Cross-References">Cross References</a> +<br> +</div> + +<!-- node-name, next, previous, up --> +<h3 class="section">8.3 Parts of a Cross Reference</h3> + +<p><a name="index-Cross-reference-parts-364"></a><a name="index-Parts-of-a-cross-reference-365"></a> +A cross reference command requires only one argument, which is the +name of the node to which it refers. But a cross reference command +may contain up to four additional arguments. By using these +arguments, you can provide a cross reference name for Info, a topic +description or section title for the printed output, the name of a +different Info file, and the name of a different printed +manual. + + <p>Here is a simple cross reference example: + +<pre class="example"> @xref{Node name}. +</pre> + <p class="noindent">which produces + +<pre class="example"> *Note Node name::. +</pre> + <p class="noindent">and + + <blockquote> +See Section <var>nnn</var> [Node name], page <var>ppp</var>. +</blockquote> + + <p>Here is an example of a full five-part cross reference: + +<pre class="example"> @xref{Node name, Cross Reference Name, Particular Topic, + info-file-name, A Printed Manual}, for details. +</pre> + <p class="noindent">which produces + +<pre class="example"> *Note Cross Reference Name: (info-file-name)Node name, + for details. +</pre> + <p class="noindent">in Info and + + <blockquote> +See section “Particular Topic” in <i>A Printed Manual</i>, for details. +</blockquote> + +<p class="noindent">in a printed book. + + <p>The five possible arguments for a cross reference are: + + <ol type=1 start=1> +<li>The node or anchor name (required). This is the location to which the +cross reference takes you. In a printed document, the location of the +node provides the page reference only for references within the same +document. + + <li>The cross reference name for the Info reference, if it is to be different +from the node name. If you include this argument, it becomes +the first part of the cross reference. It is usually omitted. + + <li>A topic description or section name. Often, this is the title of the +section. This is used as the name of the reference in the printed +manual. If omitted, the node name is used. + + <li>The name of the Info file in which the reference is located, if it is +different from the current file. You need not include any <span class="samp">.info</span> +suffix on the file name, since Info readers try appending it +automatically. + + <li>The name of a printed manual from a different Texinfo file. + </ol> + + <p>The template for a full five argument cross reference looks like +this: + +<pre class="example"> @xref{<var>node-name</var>, <var>cross-reference-name</var>, <var>title-or-topic</var>, + <var>info-file-name</var>, <var>printed-manual-title</var>}. +</pre> + <p>Cross references with one, two, three, four, and five arguments are +described separately following the description of <code>@xref</code>. + + <p>Write a node name in a cross reference in exactly the same way as in +the <code>@node</code> line, including the same capitalization; otherwise, the +formatters may not find the reference. + + <p>You can write cross reference commands within a paragraph, but note +how Info and TeX format the output of each of the various commands: +write <code>@xref</code> at the beginning of a sentence; write +<code>@pxref</code> only within parentheses, and so on. + +<div class="node"> +<p><hr> +<a name="xref"></a>Next: <a rel="next" accesskey="n" href="#Top-Node-Naming">Top Node Naming</a>, +Previous: <a rel="previous" accesskey="p" href="#Cross-Reference-Parts">Cross Reference Parts</a>, +Up: <a rel="up" accesskey="u" href="#Cross-References">Cross References</a> +<br> +</div> + +<!-- node-name, next, previous, up --> +<h3 class="section">8.4 <code>@xref</code></h3> + +<p><a name="index-xref-366"></a><a name="index-Cross-references-using-_0040code_007b_0040_0040xref_007d-367"></a><a name="index-References-using-_0040code_007b_0040_0040xref_007d-368"></a> +The <code>@xref</code> command generates a cross reference for the +beginning of a sentence. The Info formatting commands convert it into +an Info cross reference, which the Info <span class="samp">f</span> command can use to +bring you directly to another node. The TeX typesetting commands +convert it into a page reference, or a reference to another book or +manual. + +<ul class="menu"> +<li><a accesskey="1" href="#Reference-Syntax">Reference Syntax</a>: What a reference looks like and requires. +<li><a accesskey="2" href="#One-Argument">One Argument</a>: <code>@xref</code> with one argument. +<li><a accesskey="3" href="#Two-Arguments">Two Arguments</a>: <code>@xref</code> with two arguments. +<li><a accesskey="4" href="#Three-Arguments">Three Arguments</a>: <code>@xref</code> with three arguments. +<li><a accesskey="5" href="#Four-and-Five-Arguments">Four and Five Arguments</a>: <code>@xref</code> with four and five arguments. +</ul> + +<div class="node"> +<p><hr> +<a name="Reference-Syntax"></a>Next: <a rel="next" accesskey="n" href="#One-Argument">One Argument</a>, +Up: <a rel="up" accesskey="u" href="#xref">xref</a> +<br> +</div> + +<h4 class="subsection">8.4.1 What a Reference Looks Like and Requires</h4> + +<p>Most often, an Info cross reference looks like this: + +<pre class="example"> *Note <var>node-name</var>::. +</pre> + <p class="noindent">or like this + +<pre class="example"> *Note <var>cross-reference-name</var>: <var>node-name</var>. +</pre> + <p class="noindent">In TeX, a cross reference looks like this: + + <blockquote> +See Section <var>section-number</var> [<var>node-name</var>], page <var>page</var>. +</blockquote> + +<p class="noindent">or like this + + <blockquote> +See Section <var>section-number</var> [<var>title-or-topic</var>], page <var>page</var>. +</blockquote> + + <p>The <code>@xref</code> command does not generate a period or comma to end +the cross reference in either the Info file or the printed output. +You must write that period or comma yourself; otherwise, Info will not +recognize the end of the reference. (The <code>@pxref</code> command works +differently. See <a href="#pxref"><code>@pxref</code></a>.) + + <blockquote> +<b>Caution:</b> A period or comma <strong>must</strong> follow the closing +brace of an <code>@xref</code>. It is required to terminate the cross +reference. This period or comma will appear in the output, both in +the Info file and in the printed manual. +</blockquote> + + <p><code>@xref</code> must refer to an Info node by name. Use <code>@node</code> +to define the node (see <a href="#Writing-a-Node">Writing a Node</a>). + + <p><code>@xref</code> is followed by several arguments inside braces, separated by +commas. Whitespace before and after these commas is ignored. + + <p>A cross reference requires only the name of a node; but it may contain +up to four additional arguments. Each of these variations produces a +cross reference that looks somewhat different. + + <blockquote> +<b>Note:</b> Commas separate arguments in a cross reference; +avoid including them in the title or other part lest the formatters +mistake them for separators. +</blockquote> + +<div class="node"> +<p><hr> +<a name="One-Argument"></a>Next: <a rel="next" accesskey="n" href="#Two-Arguments">Two Arguments</a>, +Previous: <a rel="previous" accesskey="p" href="#Reference-Syntax">Reference Syntax</a>, +Up: <a rel="up" accesskey="u" href="#xref">xref</a> +<br> +</div> + +<h4 class="subsection">8.4.2 <code>@xref</code> with One Argument</h4> + +<p>The simplest form of <code>@xref</code> takes one argument, the name of +another node in the same Info file. The Info formatters produce +output that the Info readers can use to jump to the reference; TeX +produces output that specifies the page and section number for you. + +<p class="noindent">For example, + +<pre class="example"> @xref{Tropical Storms}. +</pre> + <p class="noindent">produces + +<pre class="example"> *Note Tropical Storms::. +</pre> + <p class="noindent">and + + <blockquote> +See Section 3.1 [Tropical Storms], page 24. +</blockquote> + +<p class="noindent">(Note that in the preceding example the closing brace is followed by a +period.) + + <p>You can write a clause after the cross reference, like this: + +<pre class="example"> @xref{Tropical Storms}, for more info. +</pre> + <p class="noindent">which produces + +<pre class="example"> *Note Tropical Storms::, for more info. +</pre> + <p class="noindent">and + + <blockquote> +See Section 3.1 [Tropical Storms], page 24, for more info. +</blockquote> + +<p class="noindent">(Note that in the preceding example the closing brace is followed by a +comma, and then by the clause, which is followed by a period.) + +<div class="node"> +<p><hr> +<a name="Two-Arguments"></a>Next: <a rel="next" accesskey="n" href="#Three-Arguments">Three Arguments</a>, +Previous: <a rel="previous" accesskey="p" href="#One-Argument">One Argument</a>, +Up: <a rel="up" accesskey="u" href="#xref">xref</a> +<br> +</div> + +<h4 class="subsection">8.4.3 <code>@xref</code> with Two Arguments</h4> + +<p>With two arguments, the second is used as the name of the Info cross +reference, while the first is still the name of the node to which the +cross reference points. + +<p class="noindent">The template is like this: + +<pre class="example"> @xref{<var>node-name</var>, <var>cross-reference-name</var>}. +</pre> + <p class="noindent">For example, + +<pre class="example"> @xref{Electrical Effects, Lightning}. +</pre> + <p class="noindent">produces: + +<pre class="example"> *Note Lightning: Electrical Effects. +</pre> + <p class="noindent">and + + <blockquote> +See Section 5.2 [Electrical Effects], page 57. +</blockquote> + +<p class="noindent">(Note that in the preceding example the closing brace is followed by a +period; and that the node name is printed, not the cross reference name.) + + <p>You can write a clause after the cross reference, like this: + +<pre class="example"> @xref{Electrical Effects, Lightning}, for more info. +</pre> + <p class="noindent">which produces +<pre class="example"> *Note Lightning: Electrical Effects, for more info. +</pre> + <p class="noindent">and + + <blockquote> +See Section 5.2 [Electrical Effects], page 57, for more info. +</blockquote> + +<p class="noindent">(Note that in the preceding example the closing brace is followed by a +comma, and then by the clause, which is followed by a period.) + +<div class="node"> +<p><hr> +<a name="Three-Arguments"></a>Next: <a rel="next" accesskey="n" href="#Four-and-Five-Arguments">Four and Five Arguments</a>, +Previous: <a rel="previous" accesskey="p" href="#Two-Arguments">Two Arguments</a>, +Up: <a rel="up" accesskey="u" href="#xref">xref</a> +<br> +</div> + +<h4 class="subsection">8.4.4 <code>@xref</code> with Three Arguments</h4> + +<p>A third argument replaces the node name in the TeX output. The third +argument should be the name of the section in the printed output, or +else state the topic discussed by that section. Often, you will want to +use initial upper case letters so it will be easier to read when the +reference is printed. Use a third argument when the node name is +unsuitable because of syntax or meaning. + + <p>Remember to avoid placing a comma within the title or topic section of +a cross reference, or within any other section. The formatters divide +cross references into arguments according to the commas; a comma +within a title or other section will divide it into two arguments. In +a reference, you need to write a title such as “Clouds, Mist, and +Fog” without the commas. + + <p>Also, remember to write a comma or period after the closing brace of an +<code>@xref</code> to terminate the cross reference. In the following +examples, a clause follows a terminating comma. + +<p class="noindent">The template is like this: + +<pre class="example"> @xref{<var>node-name</var>, <var>cross-reference-name</var>, <var>title-or-topic</var>}. +</pre> + <p class="noindent">For example, + +<pre class="example"> @xref{Electrical Effects, Lightning, Thunder and Lightning}, + for details. +</pre> + <p class="noindent">produces + +<pre class="example"> *Note Lightning: Electrical Effects, for details. +</pre> + <p class="noindent">and + + <blockquote> +See Section 5.2 [Thunder and Lightning], page 57, for details. +</blockquote> + + <p>If a third argument is given and the second one is empty, then the +third argument serves both. (Note how two commas, side by side, mark +the empty second argument.) + +<pre class="example"> @xref{Electrical Effects, , Thunder and Lightning}, + for details. +</pre> + <p class="noindent">produces + +<pre class="example"> *Note Thunder and Lightning: Electrical Effects, for details. +</pre> + <p class="noindent">and + + <blockquote> +See Section 5.2 [Thunder and Lightning], page 57, for details. +</blockquote> + + <p>As a practical matter, it is often best to write cross references with +just the first argument if the node name and the section title are the +same, and with the first and third arguments if the node name and title +are different. + + <p>Here are several examples from <cite>The GNU Awk User's Guide</cite>: + +<pre class="smallexample"> @xref{Sample Program}. + @xref{Glossary}. + @xref{Case-sensitivity, ,Case-sensitivity in Matching}. + @xref{Close Output, , Closing Output Files and Pipes}, + for more information. + @xref{Regexp, , Regular Expressions as Patterns}. +</pre> + <div class="node"> +<p><hr> +<a name="Four-and-Five-Arguments"></a>Previous: <a rel="previous" accesskey="p" href="#Three-Arguments">Three Arguments</a>, +Up: <a rel="up" accesskey="u" href="#xref">xref</a> +<br> +</div> + +<h4 class="subsection">8.4.5 <code>@xref</code> with Four and Five Arguments</h4> + +<p>In a cross reference, a fourth argument specifies the name of another +Info file, different from the file in which the reference appears, and +a fifth argument specifies its title as a printed manual. + + <p>Remember that a comma or period must follow the closing brace of an +<code>@xref</code> command to terminate the cross reference. In the +following examples, a clause follows a terminating comma. + +<p class="noindent">The template is: + +<pre class="example"> @xref{<var>node-name</var>, <var>cross-reference-name</var>, <var>title-or-topic</var>, + <var>info-file-name</var>, <var>printed-manual-title</var>}. +</pre> + <p class="noindent">For example, + +<pre class="example"> @xref{Electrical Effects, Lightning, Thunder and Lightning, + weather, An Introduction to Meteorology}, for details. +</pre> + <p class="noindent">produces + +<pre class="example"> *Note Lightning: (weather)Electrical Effects, for details. +</pre> + <p class="noindent">The name of the Info file is enclosed in parentheses and precedes +the name of the node. + +<p class="noindent">In a printed manual, the reference looks like this: + + <blockquote> +See section “Thunder and Lightning” in <i>An Introduction to +Meteorology</i>, for details. +</blockquote> + +<p class="noindent">The title of the printed manual is typeset in italics; and the +reference lacks a page number since TeX cannot know to which page a +reference refers when that reference is to another manual. + + <p>Often, you will leave out the second argument when you use the long +version of <code>@xref</code>. In this case, the third argument, the topic +description, will be used as the cross reference name in Info. + +<p class="noindent">The template looks like this: + +<pre class="example"> @xref{<var>node-name</var>, , <var>title-or-topic</var>, <var>info-file-name</var>, + <var>printed-manual-title</var>}, for details. +</pre> + <p class="noindent">which produces + +<pre class="example"> *Note <var>title-or-topic</var>: (<var>info-file-name</var>)<var>node-name</var>, for details. +</pre> + <p class="noindent">and + + <blockquote> +See section <var>title-or-topic</var> in <var>printed-manual-title</var>, for details. +</blockquote> + +<p class="noindent">For example, + +<pre class="example"> @xref{Electrical Effects, , Thunder and Lightning, + weather, An Introduction to Meteorology}, for details. +</pre> + <p class="noindent">produces + +<pre class="example"> *Note Thunder and Lightning: (weather)Electrical Effects, + for details. +</pre> + <p class="noindent">and + + <blockquote> +See section “Thunder and Lightning” in <i>An Introduction to +Meteorology</i>, for details. +</blockquote> + + <p>On rare occasions, you may want to refer to another Info file that +is within a single printed manual—when multiple Texinfo files are +incorporated into the same TeX run but make separate Info files. +In this case, you need to specify only the fourth argument, and not +the fifth. + +<div class="node"> +<p><hr> +<a name="Top-Node-Naming"></a>Next: <a rel="next" accesskey="n" href="#ref">ref</a>, +Previous: <a rel="previous" accesskey="p" href="#xref">xref</a>, +Up: <a rel="up" accesskey="u" href="#Cross-References">Cross References</a> +<br> +</div> + +<h3 class="section">8.5 Naming a `Top' Node</h3> + +<p><a name="index-Naming-a-_0060Top_0027-Node-in-references-369"></a><a name="index-_0040samp_007b_0040r_007bTop_007d_007d-node-naming-for-references-370"></a> +In a cross reference, you must always name a node. This means that in +order to refer to a whole manual, you must identify the `Top' node by +writing it as the first argument to the <code>@xref</code> command. (This +is different from the way you write a menu entry; see <a href="#Other-Info-Files">Referring to Other Info Files</a>.) At the same time, to +provide a meaningful section topic or title in the printed cross +reference (instead of the word `Top'), you must write an appropriate +entry for the third argument to the <code>@xref</code> command. + +<p class="noindent">Thus, to make a cross reference to <cite>The GNU Make Manual</cite>, +write: + +<pre class="example"> @xref{Top, , Overview, make, The GNU Make Manual}. +</pre> + <p class="noindent">which produces + +<pre class="example"> *Note Overview: (make)Top. +</pre> + <p class="noindent">and + + <blockquote> +See section “Overview” in <i>The GNU Make Manual</i>. +</blockquote> + +<p class="noindent">In this example, <span class="samp">Top</span> is the name of the first node, and +<span class="samp">Overview</span> is the name of the first section of the manual. + +<div class="node"> +<p><hr> +<a name="ref"></a>Next: <a rel="next" accesskey="n" href="#pxref">pxref</a>, +Previous: <a rel="previous" accesskey="p" href="#Top-Node-Naming">Top Node Naming</a>, +Up: <a rel="up" accesskey="u" href="#Cross-References">Cross References</a> +<br> +</div> + +<h3 class="section">8.6 <code>@ref</code></h3> + +<p><a name="index-Cross-references-using-_0040code_007b_0040_0040ref_007d-371"></a><a name="index-References-using-_0040code_007b_0040_0040ref_007d-372"></a><a name="index-ref-373"></a> +<code>@ref</code> is nearly the same as <code>@xref</code> except that it does +not generate a `See' in the printed output, just the reference itself. +This makes it useful as the last part of a sentence. + +<p class="noindent">For example, + + <p><a name="index-Hurricanes-374"></a> +<pre class="example"> For more information, see @ref{Hurricanes}. +</pre> + <p class="noindent">produces (in Info): + +<pre class="example"> For more information, see *Note Hurricanes::. +</pre> + <p class="noindent">and (in printed output): + + <blockquote> +For more information, see Section 8.2 [Hurricanes], page 123. +</blockquote> + + <p>The <code>@ref</code> command sometimes tempts writers to express +themselves in a manner that is suitable for a printed manual but looks +awkward in the Info format. Bear in mind that your audience will be +using both the printed and the Info format. For example: + + <p><a name="index-Sea-surges-375"></a> +<pre class="example"> Sea surges are described in @ref{Hurricanes}. +</pre> + <p class="noindent">looks ok in the printed output: + + <blockquote> +Sea surges are described in Section 6.7 [Hurricanes], page 72. +</blockquote> + +<p class="noindent">but is awkward to read in Info: + +<pre class="example"> Sea surges are described in *Note Hurricanes::. +</pre> + <blockquote> +<b>Caution:</b> You should write a period or comma immediately after an <code>@ref</code> +command with two or more arguments. Otherwise, Info will generate a +(grammatically incorrect) period, just so the cross-reference doesn't +fail completely. +</blockquote> + + <p>As a general rule, you should write a period or comma after every +<code>@ref</code> command. This works best in both the printed and the +Info output. + +<div class="node"> +<p><hr> +<a name="pxref"></a>Next: <a rel="next" accesskey="n" href="#inforef">inforef</a>, +Previous: <a rel="previous" accesskey="p" href="#ref">ref</a>, +Up: <a rel="up" accesskey="u" href="#Cross-References">Cross References</a> +<br> +</div> + +<h3 class="section">8.7 <code>@pxref</code></h3> + +<p><a name="index-Cross-references-using-_0040code_007b_0040_0040pxref_007d-376"></a><a name="index-References-using-_0040code_007b_0040_0040pxref_007d-377"></a><a name="index-pxref-378"></a> +The parenthetical reference command, <code>@pxref</code>, is nearly the +same as <code>@xref</code>, but you use it <em>only</em> inside parentheses +and you do <em>not</em> type a comma or period after the command's +closing brace. The command differs from <code>@xref</code> in two +ways: + + <ol type=1 start=1> +<li>TeX typesets the reference for the printed manual with a lower case +`see' rather than an upper case `See'. + + <li>The Info formatting commands automatically end the reference with a +closing colon or period. + </ol> + + <p>Because one type of formatting automatically inserts closing +punctuation and the other does not, you should use <code>@pxref</code> +<em>only</em> inside parentheses as part of another sentence. Also, you +yourself should not insert punctuation after the reference, as you do +with <code>@xref</code>. + + <p><code>@pxref</code> is designed so that the output looks right and works +right between parentheses both in printed output and in an Info file. +In a printed manual, a closing comma or period should not follow a +cross reference within parentheses; such punctuation is wrong. But in +an Info file, suitable closing punctuation must follow the cross +reference so Info can recognize its end. <code>@pxref</code> spares you +the need to use complicated methods to put a terminator into one form +of the output and not the other. + +<p class="noindent">With one argument, a parenthetical cross reference looks like +this: + + <p><a name="index-Flooding-379"></a> +<pre class="example"> ... storms cause flooding (@pxref{Hurricanes}) ... +</pre> + <p class="noindent">which produces + +<pre class="example"> ... storms cause flooding (*Note Hurricanes::) ... +</pre> + <p class="noindent">and + + <blockquote> +<small class="dots">...</small> storms cause flooding (see Section 6.7 [Hurricanes], page 72) <small class="dots">...</small> +</blockquote> + + <p>With two arguments, a parenthetical cross reference has this +template: + +<pre class="example"> ... (@pxref{<var>node-name</var>, <var>cross-reference-name</var>}) ... +</pre> + <p class="noindent">which produces + +<pre class="example"> ... (*Note <var>cross-reference-name</var>: <var>node-name</var>.) ... +</pre> + <p class="noindent">and + + <blockquote> +<small class="dots">...</small> (see Section <var>nnn</var> [<var>node-name</var>], page <var>ppp</var>) <small class="dots">...</small> +</blockquote> + + <p><code>@pxref</code> can be used with up to five arguments just like +<code>@xref</code> (see <a href="#xref"><code>@xref</code></a>). + + <blockquote> +<b>Caution:</b> Use <code>@pxref</code> only as a parenthetical +reference. Do not try to use <code>@pxref</code> as a clause in a sentence. +It will look bad in either the Info file, the printed output, or +both. +</blockquote> + + <p>Parenthetical cross references look best at the ends of sentences. +Although they technically work in the middle of a sentence, that +location breaks up the flow of reading. + +<div class="node"> +<p><hr> +<a name="inforef"></a>Next: <a rel="next" accesskey="n" href="#uref">uref</a>, +Previous: <a rel="previous" accesskey="p" href="#pxref">pxref</a>, +Up: <a rel="up" accesskey="u" href="#Cross-References">Cross References</a> +<br> +</div> + +<h3 class="section">8.8 <code>@inforef</code></h3> + +<p><a name="index-Cross-references-using-_0040code_007b_0040_0040inforef_007d-380"></a><a name="index-References-using-_0040code_007b_0040_0040inforef_007d-381"></a><a name="index-inforef-382"></a> +<code>@inforef</code> is used for cross references to Info files for which +there are no printed manuals. Even in a printed manual, +<code>@inforef</code> generates a reference directing the user to look in +an Info file. + + <p>The command takes either two or three arguments, in the following +order: + + <ol type=1 start=1> +<li>The node name. + + <li>The cross reference name (optional). + + <li>The Info file name. + </ol> + +<p class="noindent">Separate the arguments with commas, as with <code>@xref</code>. Also, you +must terminate the reference with a comma or period after the +<span class="samp">}</span>, as you do with <code>@xref</code>. + +<p class="noindent">The template is: + +<pre class="example"> @inforef{<var>node-name</var>, <var>cross-reference-name</var>, <var>info-file-name</var>}, +</pre> + <p class="noindent">Thus, + +<pre class="example"> @inforef{Advanced, Advanced Info commands, info}, + for more information. +</pre> + <p class="noindent">produces + +<pre class="example"> *Note Advanced Info commands: (info)Advanced, + for more information. +</pre> + <p class="noindent">and + + <blockquote> +See Info file <span class="file">info</span>, node <span class="samp">Advanced</span>, for more information. +</blockquote> + +<p class="noindent">Similarly, + +<pre class="example"> @inforef{Advanced, , info}, for more information. +</pre> + <p class="noindent">produces + +<pre class="example"> *Note (info)Advanced::, for more information. +</pre> + <p class="noindent">and + + <blockquote> +See Info file <span class="file">info</span>, node <span class="samp">Advanced</span>, for more information. +</blockquote> + + <p>The converse of <code>@inforef</code> is <code>@cite</code>, which is used to +refer to printed works for which no Info form exists. See <a href="#cite"><code>@cite</code></a>. + +<div class="node"> +<p><hr> +<a name="uref"></a>Previous: <a rel="previous" accesskey="p" href="#inforef">inforef</a>, +Up: <a rel="up" accesskey="u" href="#Cross-References">Cross References</a> +<br> +</div> + +<h3 class="section">8.9 <code>@url</code>, <code>@uref{</code><var>url</var><code>[, </code><var>text</var><code>][, </code><var>replacement</var><code>]}</code></h3> + +<p><a name="index-uref-383"></a><a name="index-Uniform-resource-locator_002c-referring-to-384"></a><a name="index-URL_002c-referring-to-385"></a> +<a name="index-_0040code_007bhref_007d_002c-producing-HTML-386"></a><code>@uref</code> produces a reference to a uniform resource locator (url). +It takes one mandatory argument, the url, and two optional arguments +which control the text that is displayed. In HTML output, <code>@uref</code> +produces a link you can follow. + + <p><code>@url</code> is a synonym for <code>@uref</code>. Originally, <code>@url</code> +had the meaning of <code>@indicateurl</code> +(see <a href="#indicateurl"><code>@indicateurl</code></a>), but in actual practice it +was misused the vast majority of the time. So we've changed the +definitions. + + <p>The second argument, if specified, is the text to display (the default +is the url itself); in Info and DVI output, but not in HTML output, the +url is also output. + + <p><a name="index-Man-page_002c-reference-to-387"></a>The third argument, if specified, is the text to display, but in this +case the url is <em>not</em> output in any format. This is useful when +the text is already sufficiently referential, as in a man page. If +the third argument is given, the second argument is ignored. + + <p>If the url is long enough to cause problems with line breaking, you +may find it useful to insert <code>@/</code> at places where a line break +would be acceptable (after <span class="samp">/</span> characters, for instance). This +tells TeX to allow (but not force) a line break at those places. +See <a href="#Line-Breaks">Line Breaks</a>. + + <p>Here is an example of the simple one argument form, where the url is +both the target and the text of the link: + +<pre class="example"> The official GNU ftp site is @uref{ftp://ftp.gnu.org/gnu}. +</pre> + <p class="noindent">produces: +<pre class="display"> The official GNU ftp site is <a href="ftp://ftp.gnu.org/gnu">ftp://ftp.gnu.org/gnu</a>. +</pre> + <p>An example of the two-argument form: +<pre class="example"> The official @uref{ftp://ftp.gnu.org/gnu, GNU ftp site} + holds programs and texts. +</pre> + <p class="noindent">produces: +<pre class="display"> The official <a href="ftp://ftp.gnu.org/gnu">GNU ftp site</a> + holds programs and texts. +</pre> + <p class="noindent">that is, the Info output is this: +<pre class="example"> The official GNU ftp site (ftp://ftp.gnu.org/gnu) + holds programs and texts. +</pre> + <p class="noindent">and the HTML output is this: +<pre class="example"> The official <a href="ftp://ftp.gnu.org/gnu">GNU ftp site</a> + holds programs and texts. +</pre> + <p>An example of the three-argument form: +<pre class="example"> The @uref{/man.cgi/1/ls,,ls(1)} program ... +</pre> + <p class="noindent">produces: +<pre class="display"> The <a href="/man.cgi/1/ls">ls(1)</a> program <small class="dots">...</small> +</pre> + <p class="noindent">but with HTML: +<pre class="example"> The <a href="/man.cgi/1/ls">ls(1)</a> program ... +</pre> + <p>To merely indicate a url without creating a link people can follow, use +<code>@indicateurl</code> (see <a href="#indicateurl"><code>@indicateurl</code></a>). + + <p>Some people prefer to display url's in the unambiguous format: + +<pre class="display"> <URL:http://<var>host</var>/<var>path</var>> +</pre> + <p class="noindent"><a name="index-_003cURL_003a-convention_002c-not-used-388"></a>You can use this form in the input file if you wish. We feel it's not +necessary to include the <span class="samp"><URL:</span> and <span class="samp">></span> in the output, +since any software that tries to detect url's in text already has to +detect them without the <span class="samp"><URL:</span> to be useful. + +<div class="node"> +<p><hr> +<a name="Marking-Text"></a>Next: <a rel="next" accesskey="n" href="#Quotations-and-Examples">Quotations and Examples</a>, +Previous: <a rel="previous" accesskey="p" href="#Cross-References">Cross References</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> +<br> +</div> + +<h2 class="chapter">9 Marking Words and Phrases</h2> + +<p><a name="index-Paragraph_002c-marking-text-within-389"></a><a name="index-Marking-words-and-phrases-390"></a><a name="index-Words-and-phrases_002c-marking-them-391"></a><a name="index-Marking-text-within-a-paragraph-392"></a><a name="index-Text_002c-marking-up-393"></a> +In Texinfo, you can mark words and phrases in a variety of ways. +The Texinfo formatters use this information to determine how to +highlight the text. +You can specify, for example, whether a word or phrase is a +defining occurrence, a metasyntactic variable, or a symbol used in a +program. Also, you can emphasize text, in several different ways. + +<ul class="menu"> +<li><a accesskey="1" href="#Indicating">Indicating</a>: How to indicate definitions, files, etc. +<li><a accesskey="2" href="#Emphasis">Emphasis</a>: How to emphasize text. +</ul> + +<div class="node"> +<p><hr> +<a name="Indicating"></a>Next: <a rel="next" accesskey="n" href="#Emphasis">Emphasis</a>, +Up: <a rel="up" accesskey="u" href="#Marking-Text">Marking Text</a> +<br> +</div> + +<h3 class="section">9.1 Indicating Definitions, Commands, etc.</h3> + +<p><a name="index-Highlighting-text-394"></a><a name="index-Indicating-commands_002c-definitions_002c-etc_002e-395"></a> +Texinfo has commands for indicating just what kind of object a piece of +text refers to. For example, metasyntactic variables are marked by +<code>@var</code>, and code by <code>@code</code>. Since the pieces of text are +labelled by commands that tell what kind of object they are, it is easy +to change the way the Texinfo formatters prepare such text. (Texinfo is +an <em>intentional</em> formatting language rather than a <em>typesetting</em> +formatting language.) + + <p>For example, in a printed manual, +code is usually illustrated in a typewriter font; +<code>@code</code> tells TeX to typeset this text in this font. But it +would be easy to change the way TeX highlights code to use another +font, and this change would not affect how keystroke examples are +highlighted. If straight typesetting commands were used in the body +of the file and you wanted to make a change, you would need to check +every single occurrence to make sure that you were changing code and +not something else that should not be changed. + +<ul class="menu"> +<li><a accesskey="1" href="#Useful-Highlighting">Useful Highlighting</a>: Highlighting provides useful information. +<li><a accesskey="2" href="#code">code</a>: Indicating program code. +<li><a accesskey="3" href="#kbd">kbd</a>: Showing keyboard input. +<li><a accesskey="4" href="#key">key</a>: Specifying keys. +<li><a accesskey="5" href="#samp">samp</a>: A literal sequence of characters. +<li><a accesskey="6" href="#verb">verb</a>: A verbatim sequence of characters. +<li><a accesskey="7" href="#var">var</a>: Indicating metasyntactic variables. +<li><a accesskey="8" href="#env">env</a>: Indicating environment variables. +<li><a accesskey="9" href="#file">file</a>: Indicating file names. +<li><a href="#command">command</a>: Indicating command names. +<li><a href="#option">option</a>: Indicating option names. +<li><a href="#dfn">dfn</a>: Specifying definitions. +<li><a href="#cite">cite</a>: Referring to books not in the Info system. +<li><a href="#acronym">acronym</a>: Indicating acronyms. +<li><a href="#indicateurl">indicateurl</a>: Indicating a World Wide Web reference. +<li><a href="#email">email</a>: Indicating an electronic mail address. +</ul> + +<div class="node"> +<p><hr> +<a name="Useful-Highlighting"></a>Next: <a rel="next" accesskey="n" href="#code">code</a>, +Up: <a rel="up" accesskey="u" href="#Indicating">Indicating</a> +<br> +</div> + +<h4 class="subsection">9.1.1 Highlighting Commands are Useful</h4> + +<p>The highlighting commands can be used to extract useful information +from the file, such as lists of functions or file names. It is +possible, for example, to write a program in Emacs Lisp (or a keyboard +macro) to insert an index entry after every paragraph that contains +words or phrases marked by a specified command. You could do this to +construct an index of functions if you had not already made the +entries. + + <p>The commands serve a variety of purposes: + + <dl> +<dt><code>@code{</code><var>sample-code</var><code>}</code><dd>Indicate text that is a literal example of a piece of a program. + + <br><dt><code>@kbd{</code><var>keyboard-characters</var><code>}</code><dd>Indicate keyboard input. + + <br><dt><code>@key{</code><var>key-name</var><code>}</code><dd>Indicate the conventional name for a key on a keyboard. + + <br><dt><code>@samp{</code><var>text</var><code>}</code><dd>Indicate text that is a literal example of a sequence of characters. + + <br><dt><code>@var{</code><var>metasyntactic-variable</var><code>}</code><dd>Indicate a metasyntactic variable. + + <br><dt><code>@env{</code><var>environment-variable</var><code>}</code><dd>Indicate an environment variable. + + <br><dt><code>@file{</code><var>file-name</var><code>}</code><dd>Indicate the name of a file. + + <br><dt><code>@command{</code><var>command-name</var><code>}</code><dd>Indicate the name of a command. + + <br><dt><code>@option{</code><var>option</var><code>}</code><dd>Indicate a command-line option. + + <br><dt><code>@dfn{</code><var>term</var><code>}</code><dd>Indicate the introductory or defining use of a term. + + <br><dt><code>@cite{</code><var>reference</var><code>}</code><dd>Indicate the name of a book. + + <br><dt><code>@acronym{</code><var>acronym</var><code>}</code><dd>Indicate an acronym. + + <br><dt><code>@indicateurl{</code><var>uniform-resource-locator</var><code>}</code><dd>Indicate a uniform resource locator for the World Wide Web. + + <br><dt><code>@email{</code><var>email-address</var><code>[, </code><var>displayed-text</var><code>]}</code><dd>Indicate an electronic mail address. + + </dl> + +<div class="node"> +<p><hr> +<a name="code"></a>Next: <a rel="next" accesskey="n" href="#kbd">kbd</a>, +Previous: <a rel="previous" accesskey="p" href="#Useful-Highlighting">Useful Highlighting</a>, +Up: <a rel="up" accesskey="u" href="#Indicating">Indicating</a> +<br> +</div> + +<h4 class="subsection">9.1.2 <code>@code</code>{<var>sample-code</var>}</h4> + +<p><a name="index-code-396"></a> +<a name="index-Syntactic-tokens_002c-indicating-397"></a>Use the <code>@code</code> command to indicate text that is a piece of a +program and which consists of entire syntactic tokens. Enclose the +text in braces. + + <p><a name="index-Expressions-in-a-program_002c-indicating-398"></a><a name="index-Keywords_002c-indicating-399"></a><a name="index-Reserved-words_002c-indicating-400"></a>Thus, you should use <code>@code</code> for an expression in a program, for +the name of a variable or function used in a program, or for a +keyword in a programming language. + + <p>Use <code>@code</code> for command names in languages that resemble +programming languages, such as Texinfo. For example, <code>@code</code> and +<code>@samp</code> are produced by writing <span class="samp">@code{@@code}</span> and +<span class="samp">@code{@@samp}</span> in the Texinfo source, respectively. + + <p><a name="index-Case_002c-not-altering-in-_0040code_007b_0040_0040code_007d-401"></a>It is incorrect to alter the case of a word inside an <code>@code</code> +command when it appears at the beginning of a sentence. Most computer +languages are case sensitive. In C, for example, <code>Printf</code> is +different from the identifier <code>printf</code>, and most likely is a +misspelling of it. Even in languages which are not case sensitive, it +is confusing to a human reader to see identifiers spelled in different +ways. Pick one spelling and always use that. If you do not want to +start a sentence with a command name written all in lower case, you +should rearrange the sentence. + + <p>In the printed manual, <code>@code</code> causes TeX to typeset the +argument in a typewriter face. In the Info file, it causes the Info +formatting commands to use single quotation marks around the text. + + <p>For example, + +<pre class="example"> The function returns @code{nil}. +</pre> + <p class="noindent">produces this in the printed manual: + + <blockquote> +The function returns <code>nil</code>. +</blockquote> + + <p>Here are some cases for which it is preferable not to use <code>@code</code>: + + <ul> +<li>For shell command names such as <span class="command">ls</span> (use <code>@command</code>). + + <li>For shell options such as <span class="samp">-c</span> when such options stand alone (use +<code>@option</code>). + + <li>Also, an entire shell command often looks better if written using +<code>@samp</code> rather than <code>@code</code>. In this case, the rule is to +choose the more pleasing format. + + <li>For environment variable such as <span class="env">TEXINPUTS</span> (use <code>@env</code>). + + <li>For a string of characters shorter than a syntactic token. For example, +if you are writing about <span class="samp">goto-ch</span>, which is just a part of the +name for the <code>goto-char</code> Emacs Lisp function, you should use +<code>@samp</code>. + + <li>In general, when writing about the characters used in a token; for +example, do not use <code>@code</code> when you are explaining what letters +or printable symbols can be used in the names of functions. (Use +<code>@samp</code>.) Also, you should not use <code>@code</code> to mark text +that is considered input to programs unless the input is written in a +language that is like a programming language. For example, you should +not use <code>@code</code> for the keystroke commands of GNU Emacs (use +<code>@kbd</code> instead) although you may use <code>@code</code> for the names +of the Emacs Lisp functions that the keystroke commands invoke. + + </ul> + + <p>Since <code>@command</code>, <code>@option</code>, and <code>@env</code> were +introduced relatively recently, it is acceptable to use <code>@code</code> or +<code>@samp</code> for command names, options, and environment variables. +The new commands allow you to express the markup more precisely, but +there is no real harm in using the older commands, and of course the +long-standing manuals do so. + +<div class="node"> +<p><hr> +<a name="kbd"></a>Next: <a rel="next" accesskey="n" href="#key">key</a>, +Previous: <a rel="previous" accesskey="p" href="#code">code</a>, +Up: <a rel="up" accesskey="u" href="#Indicating">Indicating</a> +<br> +</div> + +<h4 class="subsection">9.1.3 <code>@kbd</code>{<var>keyboard-characters</var>}</h4> + +<p><a name="index-kbd-402"></a><a name="index-Keyboard-input-403"></a> +Use the <code>@kbd</code> command for characters of input to be typed by +users. For example, to refer to the characters <kbd>M-a</kbd>, write: + +<pre class="example"> @kbd{M-a} +</pre> + <p class="noindent">and to refer to the characters <kbd>M-x shell</kbd>, write: + +<pre class="example"> @kbd{M-x shell} +</pre> + <p><a name="index-User-input-404"></a><a name="index-Slanted-typewriter-font_002c-for-_0040code_007b_0040_0040kbd_007d-405"></a>By default, the <code>@kbd</code> command produces a different font +(slanted typewriter instead of normal typewriter) in the printed +manual, so users can distinguish the characters that they are supposed +to type from those that the computer outputs. + + <p>In Info output, <code>@kbd</code> is usually the same as <code>@code</code>, +producing `quotes' around its argument. However, in typewriter-like +contexts such as the <code>@example</code> environment (see <a href="#example">example</a>) +and <code>@code</code> command itself, the quotes are omitted, since Info +format cannot use distinguishing fonts. + + <p><a name="index-kbdinputstyle-406"></a>Since the usage of <code>@kbd</code> varies from manual to manual, you can +control the font switching with the <code>@kbdinputstyle</code> command. +This command has no effect on Info output. Write this command at the +beginning of a line with a single word as an argument, one of the +following: + + <p><a name="index-distinct_0040r_007b_002c-value-for-_0040code_007b_0040_0040kbdinputstyle_007d_007d-407"></a><a name="index-example_0040r_007b_002c-value-for-_0040code_007b_0040_0040kbdinputstyle_007d_007d-408"></a><a name="index-code_0040r_007b_002c-value-for-_0040code_007b_0040_0040kbdinputstyle_007d_007d-409"></a> + <dl> +<dt><span class="samp">code</span><dd>Always use the same font for <code>@kbd</code> as <code>@code</code>. +<br><dt><span class="samp">example</span><dd>Use the distinguishing font for <code>@kbd</code> only in <code>@example</code> +and similar environments. +<br><dt><span class="samp">distinct</span><dd>(the default) Always use the distinguishing font for <code>@kbd</code>. +</dl> + + <p>You can embed another @-command inside the braces of an <code>@kbd</code> +command. Here, for example, is the way to describe a command that +would be described more verbosely as “press the <span class="samp">r</span> key and then +press the <RETURN> key”: + +<pre class="example"> @kbd{r @key{RET}} +</pre> + <p class="noindent">This produces: <kbd>r <RET></kbd>. (The present manual accepts the +default for <code>@kbdinputstyle</code>.) + + <p>You also use the <code>@kbd</code> command if you are spelling out the letters +you type; for example: + +<pre class="example"> To give the @code{logout} command, + type the characters @kbd{l o g o u t @key{RET}}. +</pre> + <p class="noindent">This produces: + + <blockquote> +To give the <code>logout</code> command, +type the characters <kbd>l o g o u t <RET></kbd>. +</blockquote> + + <p>(Also, this example shows that you can add spaces for clarity. If you +explicitly want to mention a space character as one of the characters of +input, write <kbd>@key{SPC}</kbd> for it.) + +<div class="node"> +<p><hr> +<a name="key"></a>Next: <a rel="next" accesskey="n" href="#samp">samp</a>, +Previous: <a rel="previous" accesskey="p" href="#kbd">kbd</a>, +Up: <a rel="up" accesskey="u" href="#Indicating">Indicating</a> +<br> +</div> + +<!-- node-name, next, previous, up --> +<h4 class="subsection">9.1.4 <code>@key</code>{<var>key-name</var>}</h4> + +<p><a name="index-key-410"></a> +Use the <code>@key</code> command for the conventional name for a key on a +keyboard, as in: + +<pre class="example"> @key{RET} +</pre> + <p>You can use the <code>@key</code> command within the argument of an +<code>@kbd</code> command when the sequence of characters to be typed +includes one or more keys that are described by name. + + <p>For example, to produce <kbd>C-x <ESC></kbd> you would type: + +<pre class="example"> @kbd{C-x @key{ESC}} +</pre> + <p>Here is a list of the recommended names for keys: +<a name="index-Recommended-names-for-keys-411"></a><a name="index-Keys_002c-recommended-names-412"></a><a name="index-Names-recommended-for-keys-413"></a><a name="index-Abbreviations-for-keys-414"></a> +<blockquote> + <dl> +<dt><tt>SPC</tt><dd>Space +<br><dt><tt>RET</tt><dd>Return +<br><dt><tt>LFD</tt><dd>Linefeed (however, since most keyboards nowadays do not have a Linefeed key, +it might be better to call this character <kbd>C-j</kbd>. +<br><dt><tt>TAB</tt><dd>Tab +<br><dt><tt>BS</tt><dd>Backspace +<br><dt><tt>ESC</tt><dd>Escape +<br><dt><tt>DEL</tt><dd>Delete +<br><dt><tt>SHIFT</tt><dd>Shift +<br><dt><tt>CTRL</tt><dd>Control +<br><dt><tt>META</tt><dd>Meta +</dl> + </blockquote> + + <p><a name="index-META-key-415"></a>There are subtleties to handling words like `meta' or `ctrl' that are +names of modifier keys. When mentioning a character in which the +modifier key is used, such as <kbd>Meta-a</kbd>, use the <code>@kbd</code> command +alone; do not use the <code>@key</code> command; but when you are referring +to the modifier key in isolation, use the <code>@key</code> command. For +example, write <span class="samp">@kbd{Meta-a}</span> to produce <kbd>Meta-a</kbd> and +<span class="samp">@key{META}</span> to produce <META>. + +<!-- I don't think this is a good explanation. --> +<!-- I think it will puzzle readers more than it clarifies matters. - rms. --> +<!-- In other words, use @code{@@kbd} for what you do, and use @code{@@key} --> +<!-- for what you talk about: ``Press @code{@@kbd@{M-a@}} to move point to --> +<!-- the beginning of the sentence. The @code{@@key@{META@}} key is often in --> +<!-- the lower left of the keyboard.''@refill --> +<div class="node"> +<p><hr> +<a name="samp"></a>Next: <a rel="next" accesskey="n" href="#verb">verb</a>, +Previous: <a rel="previous" accesskey="p" href="#key">key</a>, +Up: <a rel="up" accesskey="u" href="#Indicating">Indicating</a> +<br> +</div> + +<h4 class="subsection">9.1.5 <code>@samp</code>{<var>text</var>}</h4> + +<p><a name="index-samp-416"></a> +Use the <code>@samp</code> command to indicate text that is a literal example +or `sample' of a sequence of characters in a file, string, pattern, etc. +Enclose the text in braces. The argument appears within single +quotation marks in both the Info file and the printed manual; in +addition, it is printed in a fixed-width font. + +<pre class="example"> To match @samp{foo} at the end of the line, + use the regexp @samp{foo$}. +</pre> + <p class="noindent">produces + + <blockquote> +To match <span class="samp">foo</span> at the end of the line, use the regexp +<span class="samp">foo$</span>. +</blockquote> + + <p>Any time you are referring to single characters, you should use +<code>@samp</code> unless <code>@kbd</code> or <code>@key</code> is more appropriate. +Also, you may use <code>@samp</code> for entire statements in C and for entire +shell commands—in this case, <code>@samp</code> often looks better than +<code>@code</code>. Basically, <code>@samp</code> is a catchall for whatever is +not covered by <code>@code</code>, <code>@kbd</code>, or <code>@key</code>. + + <p>Only include punctuation marks within braces if they are part of the +string you are specifying. Write punctuation marks outside the braces +if those punctuation marks are part of the English text that surrounds +the string. In the following sentence, for example, the commas and +period are outside of the braces: + +<pre class="example"> In English, the vowels are @samp{a}, @samp{e}, + @samp{i}, @samp{o}, @samp{u}, and sometimes + @samp{y}. +</pre> + <p class="noindent">This produces: + + <blockquote> +In English, the vowels are <span class="samp">a</span>, <span class="samp">e</span>, +<span class="samp">i</span>, <span class="samp">o</span>, <span class="samp">u</span>, and sometimes +<span class="samp">y</span>. +</blockquote> + +<div class="node"> +<p><hr> +<a name="verb"></a>Next: <a rel="next" accesskey="n" href="#var">var</a>, +Previous: <a rel="previous" accesskey="p" href="#samp">samp</a>, +Up: <a rel="up" accesskey="u" href="#Indicating">Indicating</a> +<br> +</div> + +<h4 class="subsection">9.1.6 <code>@verb</code>{<char><var>text</var><char>}</h4> + +<p><a name="index-verb-417"></a><a name="index-Verbatim-in_002dline-text-418"></a> +<a name="index-Delimiter-character_002c-for-verbatim-419"></a>Use the <code>@verb</code> command to print a verbatim sequence of +characters. + + <p>Like LaTeX's <code>\verb</code> command, the verbatim text can be quoted using +any unique delimiter character. Enclose the verbatim text, including the +delimiters, in braces. Text is printed in a fixed-width font: + +<pre class="example"> How many @verb{|@|}-escapes does one need to print this + @verb{.@a @b @c.} string or @verb{+@'e?`!`{}\+} this? +</pre> + <p class="noindent">produces + +<pre class="example"> How many <tt>@</tt>-escapes does one need to print this + <tt>@a @b @c</tt> string or these <tt>@'e?`{}!`\</tt> this? +</pre> + <p>This is in contrast to <code>@samp</code> (see the previous section), +<code>@code</code>, and similar commands; in those cases, the argument is +normal Texinfo text, where the three characters <code>@{}</code> are +special. With <code>@verb</code>, nothing is special except the delimiter +character you choose. + + <p>It is not reliable to use <code>@verb</code> inside other Texinfo constructs. + +<div class="node"> +<p><hr> +<a name="var"></a>Next: <a rel="next" accesskey="n" href="#env">env</a>, +Previous: <a rel="previous" accesskey="p" href="#verb">verb</a>, +Up: <a rel="up" accesskey="u" href="#Indicating">Indicating</a> +<br> +</div> + +<h4 class="subsection">9.1.7 <code>@var</code>{<var>metasyntactic-variable</var>}</h4> + +<p><a name="index-var-420"></a> +Use the <code>@var</code> command to indicate metasyntactic variables. A +<dfn>metasyntactic variable</dfn> is something that stands for another piece of +text. For example, you should use a metasyntactic variable in the +documentation of a function to describe the arguments that are passed +to that function. + + <p>Do not use <code>@var</code> for the names of particular variables in +programming languages. These are specific names from a program, so +<code>@code</code> is correct for them (see <a href="#code">code</a>). For example, the +Emacs Lisp variable <code>texinfo-tex-command</code> is not a metasyntactic +variable; it is properly formatted using <code>@code</code>. + + <p>Do not use <code>@var</code> for environment variables either; <code>@env</code> +is correct for them (see the next section). + + <p>The effect of <code>@var</code> in the Info file is to change the case of the +argument to all upper case. In the printed manual and HTML output, the +argument is printed in slanted type. + + <p>For example, + +<pre class="example"> To delete file @var{filename}, + type @samp{rm @var{filename}}. +</pre> + <p class="noindent">produces + + <blockquote> +To delete file <var>filename</var>, type <span class="samp">rm </span><var>filename</var>. +</blockquote> + +<p class="noindent">(Note that <code>@var</code> may appear inside <code>@code</code>, +<code>@samp</code>, <code>@file</code>, etc.) + + <p>Write a metasyntactic variable all in lower case without spaces, and +use hyphens to make it more readable. Thus, the Texinfo source for +the illustration of how to begin a Texinfo manual looks like +this: + +<pre class="example"> \input texinfo + @@setfilename @var{info-file-name} + @@settitle @var{name-of-manual} +</pre> + <p class="noindent">This produces: + +<pre class="example"> \input texinfo + @setfilename <var>info-file-name</var> + @settitle <var>name-of-manual</var> +</pre> + <p>In some documentation styles, metasyntactic variables are shown with +angle brackets, for example: + +<pre class="example"> ..., type rm <filename> +</pre> + <p class="noindent">However, that is not the style that Texinfo uses. (You can, of +course, modify the sources to <span class="file">texinfo.tex</span> and the Info formatting commands +to output the <code><...></code> format if you wish.) + +<div class="node"> +<p><hr> +<a name="env"></a>Next: <a rel="next" accesskey="n" href="#file">file</a>, +Previous: <a rel="previous" accesskey="p" href="#var">var</a>, +Up: <a rel="up" accesskey="u" href="#Indicating">Indicating</a> +<br> +</div> + +<h4 class="subsection">9.1.8 <code>@env</code>{<var>environment-variable</var>}</h4> + +<p><a name="index-env-421"></a> +Use the <code>@env</code> command to indicate environment variables, as used +by many operating systems, including GNU. Do not use it for +metasyntactic variables; use <code>@var</code> instead (see the previous +section). + + <p><code>@env</code> is equivalent to <code>@code</code> in its effects. +For example: + +<pre class="example"> The @env{PATH} environment variable ... +</pre> + <p class="noindent">produces +<blockquote> +The <span class="env">PATH</span> environment variable <small class="dots">...</small> +</blockquote> + +<div class="node"> +<p><hr> +<a name="file"></a>Next: <a rel="next" accesskey="n" href="#command">command</a>, +Previous: <a rel="previous" accesskey="p" href="#env">env</a>, +Up: <a rel="up" accesskey="u" href="#Indicating">Indicating</a> +<br> +</div> + +<h4 class="subsection">9.1.9 <code>@file</code>{<var>file-name</var>}</h4> + +<p><a name="index-file-422"></a> +Use the <code>@file</code> command to indicate text that is the name of a +file, buffer, or directory, or is the name of a node in Info. You can +also use the command for file name suffixes. Do not use <code>@file</code> +for symbols in a programming language; use <code>@code</code>. + + <p>Currently, <code>@file</code> is equivalent to <code>@samp</code> in its effects. +For example, + +<pre class="example"> The @file{.el} files are in + the @file{/usr/local/emacs/lisp} directory. +</pre> + <p class="noindent">produces + + <blockquote> +The <span class="file">.el</span> files are in +the <span class="file">/usr/local/emacs/lisp</span> directory. +</blockquote> + +<div class="node"> +<p><hr> +<a name="command"></a>Next: <a rel="next" accesskey="n" href="#option">option</a>, +Previous: <a rel="previous" accesskey="p" href="#file">file</a>, +Up: <a rel="up" accesskey="u" href="#Indicating">Indicating</a> +<br> +</div> + +<h4 class="subsection">9.1.10 <code>@command</code>{<var>command-name</var>}</h4> + +<p><a name="index-command-423"></a><a name="index-Command-names_002c-indicating-424"></a><a name="index-Program-names_002c-indicating-425"></a> +Use the <code>@command</code> command to indicate command names, such as +<span class="command">ls</span> or <span class="command">cc</span>. + + <p><code>@command</code> is equivalent to <code>@code</code> in its effects. +For example: + +<pre class="example"> The command @command{ls} lists directory contents. +</pre> + <p class="noindent">produces +<blockquote> +The command <span class="command">ls</span> lists directory contents. +</blockquote> + + <p>You should write the name of a program in the ordinary text font, rather +than using <code>@command</code>, if you regard it as a new English word, +such as `Emacs' or `Bison'. + + <p>When writing an entire shell command invocation, as in <span class="samp">ls -l</span>, +you should use either <code>@samp</code> or <code>@code</code> at your discretion. + +<div class="node"> +<p><hr> +<a name="option"></a>Next: <a rel="next" accesskey="n" href="#dfn">dfn</a>, +Previous: <a rel="previous" accesskey="p" href="#command">command</a>, +Up: <a rel="up" accesskey="u" href="#Indicating">Indicating</a> +<br> +</div> + +<h4 class="subsection">9.1.11 <code>@option</code>{<var>option-name</var>}</h4> + +<p><a name="index-option-426"></a> +Use the <code>@option</code> command to indicate a command-line option; for +example, <span class="option">-l</span> or <span class="option">--version</span> or +<span class="option">--output=</span><var>filename</var>. + + <p><code>@option</code> is equivalent to <code>@samp</code> in its effects. +For example: + +<pre class="example"> The option @option{-l} produces a long listing. +</pre> + <p class="noindent">produces +<blockquote> +The option <span class="option">-l</span> produces a long listing. +</blockquote> + + <p>In tables, putting options inside <code>@code</code> produces a +more pleasing effect. + +<div class="node"> +<p><hr> +<a name="dfn"></a>Next: <a rel="next" accesskey="n" href="#cite">cite</a>, +Previous: <a rel="previous" accesskey="p" href="#option">option</a>, +Up: <a rel="up" accesskey="u" href="#Indicating">Indicating</a> +<br> +</div> + +<!-- node-name, next, previous, up --> +<h4 class="subsection">9.1.12 <code>@dfn</code>{<var>term</var>}</h4> + +<p><a name="index-dfn-427"></a> +Use the <code>@dfn</code> command to identify the introductory or defining +use of a technical term. Use the command only in passages whose +purpose is to introduce a term which will be used again or which the +reader ought to know. Mere passing mention of a term for the first +time does not deserve <code>@dfn</code>. The command generates italics in +the printed manual, and double quotation marks in the Info file. For +example: + +<pre class="example"> Getting rid of a file is called @dfn{deleting} it. +</pre> + <p class="noindent">produces + + <blockquote> +Getting rid of a file is called <dfn>deleting</dfn> it. +</blockquote> + + <p>As a general rule, a sentence containing the defining occurrence of a +term should be a definition of the term. The sentence does not need +to say explicitly that it is a definition, but it should contain the +information of a definition—it should make the meaning clear. + +<div class="node"> +<p><hr> +<a name="cite"></a>Next: <a rel="next" accesskey="n" href="#acronym">acronym</a>, +Previous: <a rel="previous" accesskey="p" href="#dfn">dfn</a>, +Up: <a rel="up" accesskey="u" href="#Indicating">Indicating</a> +<br> +</div> + +<h4 class="subsection">9.1.13 <code>@cite</code>{<var>reference</var>}</h4> + +<p><a name="index-cite-428"></a> +Use the <code>@cite</code> command for the name of a book that lacks a +companion Info file. The command produces italics in the printed +manual, and quotation marks in the Info file. + + <p>If a book is written in Texinfo, it is better to use a cross reference +command since a reader can easily follow such a reference in Info. +See <a href="#xref"><code>@xref</code></a>. + +<div class="node"> +<p><hr> +<a name="acronym"></a>Next: <a rel="next" accesskey="n" href="#indicateurl">indicateurl</a>, +Previous: <a rel="previous" accesskey="p" href="#cite">cite</a>, +Up: <a rel="up" accesskey="u" href="#Indicating">Indicating</a> +<br> +</div> + +<h4 class="subsection">9.1.14 <code>@acronym</code>{<var>acronym</var>[, <var>meaning</var>]}</h4> + +<p><a name="index-acronym-429"></a> +<a name="index-NASA_002c-as-acronym-430"></a><a name="index-F_002eB_002eI_002e_002c-as-acronym-431"></a><a name="index-Abbreviations_002c-tagging-432"></a><a name="index-Acronyms_002c-tagging-433"></a>Use the <code>@acronym</code> command for abbreviations written in all +capital letters, such as `<acronym>NASA</acronym>'. The abbreviation is given as +the single argument in braces, as in <span class="samp">@acronym{NASA}</span>. As +a matter of style, or for particular abbreviations, you may prefer to +use periods, as in <span class="samp">@acronym{F.B.I.}</span>. + + <p>If the acronym is at the end of a sentence, remember to use the +special <code>@.</code> and similar commands (see <a href="#Ending-a-Sentence">Ending a Sentence</a>). + + <p><a name="index-_003cacronym_003e-tag-434"></a>In TeX, the acronym is printed in slightly smaller font. In the +Info output, the argument is printed as-is. In HTML, Docbook, and +XML, the <code><acronym></code> tag is used. + + <p><code>@acronym</code> accepts an optional second argument, intended to be +used for the meaning of the acronym. If present, it is printed in +parentheses after the acronym. For instance (since GNU is a recursive +acronym, we use <code>@acronym</code> recursively): + +<pre class="example"> @acronym{GNU, @acronym{GNU}'s Not Unix} +</pre> + <p class="noindent">produces: + +<pre class="display"> <acronym title="GNU's Not Unix">GNU</acronym> (@acronym{GNU}'s Not Unix) +</pre> + <p>In some circumstances, it is conventional to print family names in all +capitals. Don't use <code>@acronym</code> for this, since a name is not an +acronym. Use <code>@sc</code> instead (see <a href="#Smallcaps">Smallcaps</a>). + +<div class="node"> +<p><hr> +<a name="indicateurl"></a>Next: <a rel="next" accesskey="n" href="#email">email</a>, +Previous: <a rel="previous" accesskey="p" href="#acronym">acronym</a>, +Up: <a rel="up" accesskey="u" href="#Indicating">Indicating</a> +<br> +</div> + +<h4 class="subsection">9.1.15 <code>@indicateurl</code>{<var>uniform-resource-locator</var>}</h4> + +<p><a name="index-indicateurl-435"></a><a name="index-Uniform-resource-locator_002c-indicating-436"></a><a name="index-URL_002c-indicating-437"></a> +Use the <code>@indicateurl</code> command to indicate a uniform resource +locator on the World Wide Web. This is analogous to <code>@file</code>, +<code>@var</code>, etc., and is purely for markup purposes. It does not +produce a link you can follow in HTML output (use the <code>@uref</code> +command for that, see <a href="#uref"><code>@uref</code></a>). It is useful for +url's which do not actually exist. For example: + +<pre class="example"> For example, the url might be @indicateurl{http://example.org/path}. +</pre> + <p class="noindent">which produces: + +<pre class="display"> For example, the url might be <<code>http://example.org/path</code>>. +</pre> + <div class="node"> +<p><hr> +<a name="email"></a>Previous: <a rel="previous" accesskey="p" href="#indicateurl">indicateurl</a>, +Up: <a rel="up" accesskey="u" href="#Indicating">Indicating</a> +<br> +</div> + +<h4 class="subsection">9.1.16 <code>@email</code>{<var>email-address</var>[, <var>displayed-text</var>]}</h4> + +<p><a name="index-email-438"></a> +Use the <code>@email</code> command to indicate an electronic mail address. +It takes one mandatory argument, the address, and one optional argument, the +text to display (the default is the address itself). + + <p><a name="index-Mailto-link-439"></a>In Info, the address is shown in angle brackets, preceded by the text +to display if any. In TeX, the angle brackets are omitted. In +HTML output, <code>@email</code> produces a <span class="samp">mailto</span> link that usually +brings up a mail composition window. For example: + +<pre class="example"> Send bug reports to @email{bug-texinfo@@gnu.org}, + suggestions to the @email{bug-texinfo@@gnu.org, same place}. +</pre> + <p class="noindent">produces +<pre class="display"> Send bug reports to <a href="mailto:bug-texinfo@gnu.org">bug-texinfo@gnu.org</a>, + suggestions to the <a href="mailto:bug-texinfo@gnu.org">same place</a>. +</pre> + <div class="node"> +<p><hr> +<a name="Emphasis"></a>Previous: <a rel="previous" accesskey="p" href="#Indicating">Indicating</a>, +Up: <a rel="up" accesskey="u" href="#Marking-Text">Marking Text</a> +<br> +</div> + +<!-- node-name, next, previous, up --> +<h3 class="section">9.2 Emphasizing Text</h3> + +<p><a name="index-Emphasizing-text-440"></a> +Usually, Texinfo changes the font to mark words in the text according to +what category the words belong to; an example is the <code>@code</code> command. +Most often, this is the best way to mark words. +However, sometimes you will want to emphasize text without indicating a +category. Texinfo has two commands to do this. Also, Texinfo has +several commands that specify the font in which TeX will typeset +text. These commands have no effect on Info and only one of them, +the <code>@r</code> command, has any regular use. + +<ul class="menu"> +<li><a accesskey="1" href="#emph-_0026-strong">emph & strong</a>: How to emphasize text in Texinfo. +<li><a accesskey="2" href="#Smallcaps">Smallcaps</a>: How to use the small caps font. +<li><a accesskey="3" href="#Fonts">Fonts</a>: Various font commands for printed output. +</ul> + +<div class="node"> +<p><hr> +<a name="emph-_0026-strong"></a>Next: <a rel="next" accesskey="n" href="#Smallcaps">Smallcaps</a>, +Up: <a rel="up" accesskey="u" href="#Emphasis">Emphasis</a> +<br> +</div> + +<h4 class="subsection">9.2.1 <code>@emph</code>{<var>text</var>} and <code>@strong</code>{<var>text</var>}</h4> + +<p><a name="index-Emphasizing-text_002c-font-for-441"></a><a name="index-emph-442"></a><a name="index-strong-443"></a> +The <code>@emph</code> and <code>@strong</code> commands are for emphasis; +<code>@strong</code> is stronger. In printed output, <code>@emph</code> produces +<em>italics</em> and <code>@strong</code> produces <strong>bold</strong>. + + <p>For example, + +<pre class="example"> @strong{Caution:} @samp{rm * .[^.]*} + removes @emph{all} files in the directory. +</pre> + <p class="noindent">produces the following in printed output and HTML: + + <blockquote> +<strong>Caution</strong>: <span class="samp">rm * .[^.]*</span> +removes <em>all</em> files in the directory. +</blockquote> + +<p class="noindent">and the following in Info: + +<pre class="example"> *Caution:* `rm * .[^.]*' removes _all_ + files in the directory. +</pre> + <p>The <code>@strong</code> command is seldom used except to mark what is, in +effect, a typographical element, such as the word `Caution' in the +preceding example. + + <p>In the Info output, <code>@emph</code> surrounds the text with underscores +(<span class="samp">_</span>), and <code>@strong</code> puts asterisks around the text. + + <blockquote> +<b>Caution:</b> Do not use <code>@strong</code> with the word <span class="samp">Note</span>; Info will +mistake the combination for a cross reference. (It's usually +redundant, anyway.) Use a phrase such as <strong>Please notice</strong> or +<strong>Caution</strong> instead, or the optional argument to +<code>@quotation</code>—<span class="samp">Note</span> is allowable there. +</blockquote> + +<div class="node"> +<p><hr> +<a name="Smallcaps"></a>Next: <a rel="next" accesskey="n" href="#Fonts">Fonts</a>, +Previous: <a rel="previous" accesskey="p" href="#emph-_0026-strong">emph & strong</a>, +Up: <a rel="up" accesskey="u" href="#Emphasis">Emphasis</a> +<br> +</div> + +<h4 class="subsection">9.2.2 <code>@sc</code>{<var>text</var>}: The Small Caps Font</h4> + +<p><a name="index-Small-caps-font-444"></a><a name="index-sc-_0040r_007b_0028small-caps-font_0029_007d-445"></a> +Use the <span class="samp">@sc</span> command to set text in <span class="sc">a small caps font</span> +(where possible). Write the text you want to be in small caps between +braces in lower case, like this: + +<pre class="example"> Richard @sc{Stallman} founded @acronym{GNU}. +</pre> + <p class="noindent">This produces: + +<pre class="display"> Richard <span class="sc">Stallman</span> founded <acronym title="GNU's Not Unix">GNU</acronym>. +</pre> + <p>As shown here, we recommend using <code>@acronym</code> for actual +abbreviations (see <a href="#acronym">acronym</a>), and reserving <code>@sc</code> for special +cases where you want small caps. The output is not the same +(<code>@acronym</code> prints in a smaller text font, not the small caps +font), but more importantly it describes the actual text more +accurately. + + <p>Family names are one case where small capitals are sometimes desirable, +also as shown here. + + <p><a name="index-_003csmall_003e-tag-446"></a>TeX typesets any uppercase letters between the braces of an +<code>@sc</code> command in full-size capitals; only lowercase letters are +printed in the small caps font. In the Info output, the argument to +<code>@sc</code> is printed in all upper case. In HTML, the argument is +uppercased and the output marked with the <code><small></code> tag to reduce +the font size. + + <p>Since it's redundant to mark all-uppercase text with <code>@sc</code>, +<span class="command">makeinfo</span> warns about such usage. + + <p>We recommend using regular mixed case wherever possible. + +<div class="node"> +<p><hr> +<a name="Fonts"></a>Previous: <a rel="previous" accesskey="p" href="#Smallcaps">Smallcaps</a>, +Up: <a rel="up" accesskey="u" href="#Emphasis">Emphasis</a> +<br> +</div> + +<h4 class="subsection">9.2.3 Fonts for Printing, Not Info</h4> + +<p><a name="index-Fonts-for-printing_002c-not-Info-447"></a><a name="index-i-_0040r_007b_0028italic-font_0029_007d-448"></a><a name="index-b-_0040r_007b_0028bold-font_0029_007d-449"></a><a name="index-t-_0040r_007b_0028typewriter-font_0029_007d-450"></a><a name="index-r-_0040r_007b_0028roman-font_0029_007d-451"></a> +Texinfo provides four font commands that specify font changes in the +printed manual and (where possible) in the HTML output, but have no +effect in the Info file. All four commands apply to an argument that +follows, surrounded by braces. + + <dl> +<dt><code>@i</code><dd><a name="index-Italic-font-452"></a>selects an <i>italic</i> font; + + <br><dt><code>@b</code><dd><a name="index-Bold-font-453"></a>selects <b>bold</b> face; + + <br><dt><code>@t</code><dd><a name="index-Monospace-font-454"></a><a name="index-Fixed_002dwidth-font-455"></a><a name="index-Typewriter-font-456"></a>selects the <tt>fixed-width</tt>, typewriter-style font used by <code>@code</code>; + + <br><dt><code>@r</code><dd><a name="index-Roman-font-457"></a>selects a <span class="roman">roman</span> font, which is the usual font in which text is printed. + + </dl> + + <p><a name="index-_003clineannotation_003e-Docbook-tag-458"></a>Only the <code>@r</code> command has much use: in example-like +environments, you can use the <code>@r</code> command to write comments in +the standard roman font instead of the fixed-width font. This looks +better in printed output, and produces a <code><lineannotation></code> tag +in Docbook output. + + <p>For example, + +<pre class="example"> @lisp + (+ 2 2) ; @r{Add two plus two.} + @end lisp +</pre> + <p class="noindent">produces + +<pre class="lisp"> (+ 2 2) ; <span class="roman">Add two plus two.</span> +</pre> + <p>In general, you should avoid using the other three font commands. If +you need to use one, it probably indicates a gap in the Texinfo +language. + +<div class="node"> +<p><hr> +<a name="Quotations-and-Examples"></a>Next: <a rel="next" accesskey="n" href="#Lists-and-Tables">Lists and Tables</a>, +Previous: <a rel="previous" accesskey="p" href="#Marking-Text">Marking Text</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> +<br> +</div> + +<h2 class="chapter">10 Quotations and Examples</h2> + +<p>Quotations and examples are blocks of text consisting of one or more +whole paragraphs that are set off from the bulk of the text and +treated differently. They are usually indented. + + <p>In Texinfo, you always begin a quotation or example by writing an +@-command at the beginning of a line by itself, and end it by writing +an <code>@end</code> command that is also at the beginning of a line by +itself. For instance, you begin an example by writing <code>@example</code> +by itself at the beginning of a line and end the example by writing +<code>@end example</code> on a line by itself, at the beginning of that +line. +<a name="index-end-459"></a> + +<ul class="menu"> +<li><a accesskey="1" href="#Block-Enclosing-Commands">Block Enclosing Commands</a>: Different constructs for different purposes. +<li><a accesskey="2" href="#quotation">quotation</a>: Writing a quotation. +<li><a accesskey="3" href="#example">example</a>: Writing an example in a fixed-width font. +<li><a accesskey="4" href="#verbatim">verbatim</a>: Writing a verbatim example. +<li><a accesskey="5" href="#verbatiminclude">verbatiminclude</a>: Including a file verbatim. +<li><a accesskey="6" href="#lisp">lisp</a>: Illustrating Lisp code. +<li><a accesskey="7" href="#small">small</a>: Examples in a smaller font. +<li><a accesskey="8" href="#display">display</a>: Writing an example in the current font. +<li><a accesskey="9" href="#format">format</a>: Writing an example without narrowed margins. +<li><a href="#exdent">exdent</a>: Undo indentation on a line. +<li><a href="#flushleft-_0026-flushright">flushleft & flushright</a>: Pushing text flush left or flush right. +<li><a href="#noindent">noindent</a>: Preventing paragraph indentation. +<li><a href="#indent">indent</a>: Forcing paragraph indentation. +<li><a href="#cartouche">cartouche</a>: Drawing rounded rectangles around examples. +</ul> + +<div class="node"> +<p><hr> +<a name="Block-Enclosing-Commands"></a>Next: <a rel="next" accesskey="n" href="#quotation">quotation</a>, +Up: <a rel="up" accesskey="u" href="#Quotations-and-Examples">Quotations and Examples</a> +<br> +</div> + +<h3 class="section">10.1 Block Enclosing Commands</h3> + +<p>Here are commands for quotations and examples, explained further in the +following sections: + + <dl> +<dt><code>@quotation</code><dd>Indicate text that is quoted. The text is filled, indented (from both +margins), and printed in a roman font by default. + + <br><dt><code>@example</code><dd>Illustrate code, commands, and the like. The text is printed +in a fixed-width font, and indented but not filled. + + <br><dt><code>@verbatim</code><dd>Mark a piece of text that is to be printed verbatim; no character +substitutions are made and all commands are ignored, until the next +<code>@end verbatim</code>. The text is printed in a fixed-width font, +and not indented or filled. Extra spaces and blank lines are +significant, and tabs are expanded. + + <br><dt><code>@smallexample</code><dd>Same as <code>@example</code>, except that in TeX this command typesets +text in a smaller font. + + <br><dt><code>@lisp</code><dd>Like <code>@example</code>, but specifically for illustrating Lisp code. The +text is printed in a fixed-width font, and indented but not filled. + + <br><dt><code>@smalllisp</code><dd>Is to <code>@lisp</code> as <code>@smallexample</code> is to <code>@example</code>. + + <br><dt><code>@display</code><dd>Display illustrative text. The text is indented but not filled, and +no font is selected (so, by default, the font is roman). + + <br><dt><code>@smalldisplay</code><dd>Is to <code>@display</code> as <code>@smallexample</code> is to <code>@example</code>. + + <br><dt><code>@format</code><dd>Like <code>@display</code> (the text is not filled and no font is selected), +but the text is not indented. + + <br><dt><code>@smallformat</code><dd>Is to <code>@format</code> as <code>@smallexample</code> is to <code>@example</code>. +</dl> + + <p>The <code>@exdent</code> command is used within the above constructs to +undo the indentation of a line. + + <p>The <code>@flushleft</code> and <code>@flushright</code> commands are used to line +up the left or right margins of unfilled text. + + <p>The <code>@noindent</code> command may be used after one of the above +constructs to prevent the following text from being indented as a new +paragraph. + + <p>You can use the <code>@cartouche</code> environment around one of the above +constructs to highlight the example or quotation by drawing a box with +rounded corners around it. See <a href="#cartouche">Drawing Cartouches Around Examples</a>. + +<div class="node"> +<p><hr> +<a name="quotation"></a>Next: <a rel="next" accesskey="n" href="#example">example</a>, +Previous: <a rel="previous" accesskey="p" href="#Block-Enclosing-Commands">Block Enclosing Commands</a>, +Up: <a rel="up" accesskey="u" href="#Quotations-and-Examples">Quotations and Examples</a> +<br> +</div> + +<h3 class="section">10.2 <code>@quotation</code>: Block quotations</h3> + +<p><a name="index-Quotations-460"></a><a name="index-quotation-461"></a> +The text of a quotation is processed normally (regular font, text is +filled) except that: + + <ul> +<li>the margins are closer to the center of the page, so the whole of the +quotation is indented; + + <li>the first lines of paragraphs are indented no more than other lines; + + <li>in the printed output, interparagraph spacing is reduced. +</ul> + + <blockquote> +This is an example of text written between an <code>@quotation</code> +command and an <code>@end quotation</code> command. An <code>@quotation</code> +command is most often used to indicate text that is excerpted from +another (real or hypothetical) printed work. +</blockquote> + + <p>Write an <code>@quotation</code> command as text on a line by itself. This +line will disappear from the output. Mark the end of the quotation +with a line beginning with and containing only <code>@end quotation</code>. +The <code>@end quotation</code> line will likewise disappear from the +output. + + <p><code>@quotation</code> takes one optional argument, given on the remainder +of the line. This text, if present, is included at the beginning of +the quotation in bold or otherwise emphasized, and followed with a +<span class="samp">:</span>. For example: + +<pre class="example"> @quotation Note + This is + a foo. + @end quotation +</pre> + <p class="noindent">produces + + <blockquote> +<b>Note:</b> This is +a foo. +</blockquote> + + <p>If the <code>@quotation</code> argument is exactly one of these words: + +<pre class="example"> Caution Important Note Tip Warning +</pre> + <p><a name="index-_003cnote_003e-Docbook-tag-462"></a><a name="index-_003cblockquote_003e-HTML-tag-463"></a>then the Docbook output uses corresponding special tags +(<code><note></code>, etc.) instead of the default <code><blockquote></code>. +HTML output always uses <code><blockquote></code>. + +<div class="node"> +<p><hr> +<a name="example"></a>Next: <a rel="next" accesskey="n" href="#verbatim">verbatim</a>, +Previous: <a rel="previous" accesskey="p" href="#quotation">quotation</a>, +Up: <a rel="up" accesskey="u" href="#Quotations-and-Examples">Quotations and Examples</a> +<br> +</div> + +<h3 class="section">10.3 <code>@example</code>: Example Text</h3> + +<p><a name="index-Examples_002c-formatting-them-464"></a><a name="index-Formatting-examples-465"></a><a name="index-example-466"></a> +The <code>@example</code> environment is used to indicate an example that +is not part of the running text, such as computer input or output. +Write an <code>@example</code> command at the beginning of a line by +itself. Mark the end of the example with an <code>@end example</code> +command, also written at the beginning of a line by itself. + + <p>An <code>@example</code> environment has the following characteristics: + + <ul> +<li>Each line in the input file is a line in the output; that is, +the source text is not filled as it normally is. +<li>Extra spaces and blank lines are significant. +<li>The output is indented. +<li>The output uses a fixed-width font. +<li>Texinfo commands <em>are</em> expanded; if you want the output to +be the input verbatim, use the <code>@verbatim</code> environment instead +(see <a href="#verbatim"><code>@verbatim</code></a>). +</ul> + + <p>For example, + +<pre class="example"> @example + cp foo @var{dest1}; \ + cp foo @var{dest2} + @end example +</pre> + <p class="noindent">produces + +<pre class="example"> cp foo <var>dest1</var>; \ + cp foo <var>dest2</var> +</pre> + <p>The lines containing <code>@example</code> and <code>@end example</code> will +disappear from the output. To make the output look good, you should +put a blank line before the <code>@example</code> and another blank line +after the <code>@end example</code>. Blank lines inside the beginning +<code>@example</code> and the ending <code>@end example</code>, on the other +hand, do appear in the output. + + <blockquote> +<b>Caution:</b> Do not use tabs in the lines of an example! (Or anywhere else in +Texinfo, except in verbatim environments.) TeX treats tabs as +single spaces, and that is not what they look like. In Emacs, you can +use <kbd>M-x untabify</kbd> to convert tabs in a region to multiple spaces. +</blockquote> + + <p>Examples are often, logically speaking, “in the middle” of a +paragraph, and the text that continues afterwards should not be +indented, as in the example above. The <code>@noindent</code> command +prevents a piece of text from being indented as if it were a new +paragraph (see <a href="#noindent"><code>@noindent</code></a>. + + <p>If you want to embed code fragments within sentences, instead of +displaying them, use the <code>@code</code> command or its relatives +(see <a href="#code"><code>@code</code></a>). + + <p>If you wish to write a “comment” on a line of an example in the +normal roman font, you can use the <code>@r</code> command (see <a href="#Fonts">Fonts</a>). + +<div class="node"> +<p><hr> +<a name="verbatim"></a>Next: <a rel="next" accesskey="n" href="#verbatiminclude">verbatiminclude</a>, +Previous: <a rel="previous" accesskey="p" href="#example">example</a>, +Up: <a rel="up" accesskey="u" href="#Quotations-and-Examples">Quotations and Examples</a> +<br> +</div> + +<h3 class="section">10.4 <code>@verbatim</code>: Literal Text</h3> + +<p><a name="index-verbatim-467"></a><a name="index-Verbatim-environment-468"></a> +Use the <code>@verbatim</code> environment for printing of text that may +contain special characters or commands that should not be interpreted, +such as computer input or output (<code>@example</code> interprets its text +as regular Texinfo commands). This is especially useful for including +automatically generated output in a Texinfo manual. Here is an example; +the output you see is just the same as the input, with a line +<code>@verbatim</code> before and a line <code>@end verbatim</code> after. + +<pre class="verbatim"> +This is an example of text written in a @verbatim +block. No character substitutions are made. All commands +are ignored, until `<at>end verbatim'. + +In the printed manual, the text is typeset in a +fixed-width font, and not indented or filled. All +spaces and blank lines are significant, including tabs. +</pre> + + <p>Write a <code>@verbatim</code> command at the beginning of a line by itself. +This line will disappear from the output. Mark the end of the verbatim +block with a <code>@end verbatim</code> command, also written at the +beginning of a line by itself. The <code>@end verbatim</code> will also +disappear from the output. + + <p>For example: +<!-- oops, got to trick this a bit: can't use @end verbatim inside @verbatim --> + +<pre class="example"><br><tt>@verbatim</tt><br> +<br><tt>{</tt><br> +<br><TAB><tt>@command with strange characters: @'e</tt><br> +<br><tt>expand<TAB>me</tt><br> +<br><tt>}</tt><br> +<br><tt>@end verbatim</tt><br> +</pre> + <p class="noindent">produces + +<pre class="verbatim"> +{ + @command with strange characters: @'e +expand me +} +</pre> + + <p>Since the lines containing <code>@verbatim</code> and <code>@end verbatim</code> +produce no output, typically you should put a blank line before the +<code>@verbatim</code> and another blank line after the <code>@end +verbatim</code>. Blank lines between the beginning <code>@verbatim</code> and +the ending <code>@end verbatim</code> will appear in the output. + + <p>It is not reliable to use <code>@verbatim</code> inside other Texinfo constructs. + +<div class="node"> +<p><hr> +<a name="verbatiminclude"></a>Next: <a rel="next" accesskey="n" href="#lisp">lisp</a>, +Previous: <a rel="previous" accesskey="p" href="#verbatim">verbatim</a>, +Up: <a rel="up" accesskey="u" href="#Quotations-and-Examples">Quotations and Examples</a> +<br> +</div> + +<h3 class="section">10.5 <code>@verbatiminclude</code> <var>file</var>: Include a File Verbatim</h3> + +<p><a name="index-Verbatim_002c-include-file-469"></a><a name="index-Including-a-file-verbatim-470"></a><a name="index-verbatiminclude-471"></a> +You can include the exact contents of a file in the document with the +<code>@verbatiminclude</code> command: + +<pre class="example"> @verbatiminclude <var>filename</var> +</pre> + <p>The contents of <var>filename</var> is printed in a verbatim environment +(see <a href="#verbatim"><code>@verbatim</code></a>). Generally, the file is printed +exactly as it is, with all special characters and white space +retained. No indentation is added; if you want indentation, enclose +the <code>@verbatiminclude</code> within <code>@example</code> +(see <a href="#example"><code>@example</code></a>). + + <p>The name of the file is taken literally, with a single exception: +<code>@value{</code><var>var</var><code>}</code> references are expanded. This makes it +possible to reliably include files in other directories in a +distribution, for instance: + +<pre class="example"> @include @value{top_srcdir}/NEWS +</pre> + <p class="noindent">(You still have to get <code>top_srcdir</code> defined in the +first place.) + +<div class="node"> +<p><hr> +<a name="lisp"></a>Next: <a rel="next" accesskey="n" href="#small">small</a>, +Previous: <a rel="previous" accesskey="p" href="#verbatiminclude">verbatiminclude</a>, +Up: <a rel="up" accesskey="u" href="#Quotations-and-Examples">Quotations and Examples</a> +<br> +</div> + +<h3 class="section">10.6 <code>@lisp</code>: Marking a Lisp Example</h3> + +<p><a name="index-lisp-472"></a><a name="index-Lisp-example-473"></a> +The <code>@lisp</code> command is used for Lisp code. It is synonymous +with the <code>@example</code> command. + +<pre class="lisp"> This is an example of text written between an + <code>@lisp</code> command and an <code>@end lisp</code> command. +</pre> + <p>Use <code>@lisp</code> instead of <code>@example</code> to preserve information +regarding the nature of the example. This is useful, for example, if +you write a function that evaluates only and all the Lisp code in a +Texinfo file. Then you can use the Texinfo file as a Lisp +library.<a rel="footnote" href="#fn-6" name="fnd-6"><sup>6</sup></a> + + <p>Mark the end of <code>@lisp</code> with <code>@end lisp</code> on a line by +itself. + +<div class="node"> +<p><hr> +<a name="small"></a>Next: <a rel="next" accesskey="n" href="#display">display</a>, +Previous: <a rel="previous" accesskey="p" href="#lisp">lisp</a>, +Up: <a rel="up" accesskey="u" href="#Quotations-and-Examples">Quotations and Examples</a> +<br> +</div> + +<h3 class="section">10.7 <code>@small...</code> Block Commands</h3> + +<p><a name="index-Small-examples-474"></a><a name="index-Examples-in-smaller-fonts-475"></a><a name="index-Lisp-examples-in-smaller-fonts-476"></a><a name="index-smalldisplay-477"></a><a name="index-smallexample-478"></a><a name="index-smallformat-479"></a><a name="index-smalllisp-480"></a> +In addition to the regular <code>@example</code> and <code>@lisp</code> commands, +Texinfo has “small” example-style commands. These are +<code>@smalldisplay</code>, <code>@smallexample</code>, <code>@smallformat</code>, and +<code>@smalllisp</code>. + + <p>In Info, the <code>@small...</code> commands are equivalent to their +non-small companion commands. + + <p>In TeX, however, the <code>@small...</code> commands typeset text in +a smaller font than the non-small example commands. Consequently, +many examples containing long lines fit on a page without needing to +be shortened. + + <p>Mark the end of an <code>@small...</code> block with a corresponding +<code>@end small...</code>. For example, pair <code>@smallexample</code> with +<code>@end smallexample</code>. + + <p>Here is an example of the font used by the <code>@small...</code> +commands (in Info, the output will be the same as usual): + +<pre class="smallexample"> ... to make sure that you have the freedom to + distribute copies of free software (and charge for + this service if you wish), that you receive source + code or can get it if you want it, that you can + change the software or use pieces of it in new free + programs; and that you know you can do these things. +</pre> + <p>The <code>@small...</code> commands make it easier to prepare manuals +without forcing you to edit examples by hand to fit them onto narrower +pages. + + <p>As a general rule, a printed document looks much better if you use +only one of (for instance) <code>@example</code> or <code>@smallexample</code> +consistently within a chapter. + +<div class="node"> +<p><hr> +<a name="display"></a>Next: <a rel="next" accesskey="n" href="#format">format</a>, +Previous: <a rel="previous" accesskey="p" href="#small">small</a>, +Up: <a rel="up" accesskey="u" href="#Quotations-and-Examples">Quotations and Examples</a> +<br> +</div> + +<h3 class="section">10.8 <code>@display</code> and <code>@smalldisplay</code></h3> + +<p><a name="index-Display-formatting-481"></a><a name="index-display-482"></a> +The <code>@display</code> command begins a kind of example. It is like the +<code>@example</code> command +except that, in +a printed manual, <code>@display</code> does not select the fixed-width +font. In fact, it does not specify the font at all, so that the text +appears in the same font it would have appeared in without the +<code>@display</code> command. + +<pre class="display"> This is an example of text written between an <code>@display</code> command + and an <code>@end display</code> command. The <code>@display</code> command + indents the text, but does not fill it. +</pre> + <p><a name="index-smalldisplay-483"></a>Texinfo also provides a command <code>@smalldisplay</code>, which is like +<code>@display</code> but uses a smaller font in <code>@smallbook</code> format. +See <a href="#small">small</a>. + +<div class="node"> +<p><hr> +<a name="format"></a>Next: <a rel="next" accesskey="n" href="#exdent">exdent</a>, +Previous: <a rel="previous" accesskey="p" href="#display">display</a>, +Up: <a rel="up" accesskey="u" href="#Quotations-and-Examples">Quotations and Examples</a> +<br> +</div> + +<h3 class="section">10.9 <code>@format</code> and <code>@smallformat</code></h3> + +<p><a name="index-format-484"></a> +The <code>@format</code> command is similar to <code>@example</code> except +that, in the printed manual, <code>@format</code> does not select the +fixed-width font and does not narrow the margins. + +<pre class="format">This is an example of text written between an <code>@format</code> command +and an <code>@end format</code> command. As you can see +from this example, +the <code>@format</code> command does not fill the text. +</pre> + <p><a name="index-smallformat-485"></a>Texinfo also provides a command <code>@smallformat</code>, which is like +<code>@format</code> but uses a smaller font in <code>@smallbook</code> format. +See <a href="#small">small</a>. + +<div class="node"> +<p><hr> +<a name="exdent"></a>Next: <a rel="next" accesskey="n" href="#flushleft-_0026-flushright">flushleft & flushright</a>, +Previous: <a rel="previous" accesskey="p" href="#format">format</a>, +Up: <a rel="up" accesskey="u" href="#Quotations-and-Examples">Quotations and Examples</a> +<br> +</div> + +<h3 class="section">10.10 <code>@exdent</code>: Undoing a Line's Indentation</h3> + +<p><a name="index-Indentation-undoing-486"></a><a name="index-exdent-487"></a> +The <code>@exdent</code> command removes any indentation a line might have. +The command is written at the beginning of a line and applies only to +the text that follows the command that is on the same line. Do not use +braces around the text. In a printed manual, the text on an +<code>@exdent</code> line is printed in the roman font. + + <p><code>@exdent</code> is usually used within examples. Thus, + +<pre class="example"> @example + This line follows an @@example command. + @exdent This line is exdented. + This line follows the exdented line. + The @@end example comes on the next line. + @end group +</pre> + <p class="noindent">produces + +<pre class="example"> This line follows an @example command. +<br>This line is exdented.<br> + This line follows the exdented line. + The @end example comes on the next line. +</pre> + <p>In practice, the <code>@exdent</code> command is rarely used. +Usually, you un-indent text by ending the example and +returning the page to its normal width. + +<div class="node"> +<p><hr> +<a name="flushleft-_0026-flushright"></a>Next: <a rel="next" accesskey="n" href="#noindent">noindent</a>, +Previous: <a rel="previous" accesskey="p" href="#exdent">exdent</a>, +Up: <a rel="up" accesskey="u" href="#Quotations-and-Examples">Quotations and Examples</a> +<br> +</div> + +<h3 class="section">10.11 <code>@flushleft</code> and <code>@flushright</code></h3> + +<p><a name="index-flushleft-488"></a><a name="index-flushright-489"></a><a name="index-Ragged-right-490"></a><a name="index-Ragged-left-491"></a> +The <code>@flushleft</code> and <code>@flushright</code> commands line up the +ends of lines on the left and right margins of a page, +but do not fill the text. The commands are written on lines of their +own, without braces. The <code>@flushleft</code> and <code>@flushright</code> +commands are ended by <code>@end flushleft</code> and <code>@end +flushright</code> commands on lines of their own. + + <p>For example, + +<pre class="example"> @flushleft + This text is + written flushleft. + @end flushleft +</pre> + <p class="noindent">produces + + <blockquote> + <div align="left">This text is + written flushleft. + </div> + </blockquote> + + <p><code>@flushright</code> produces the type of indentation often used in the +return address of letters. For example, + +<pre class="example"> @flushright + Here is an example of text written + flushright. The @code{@flushright} command + right justifies every line but leaves the + left end ragged. + @end flushright +</pre> + <p class="noindent">produces + + <div align="right">Here is an example of text written + <p>flushright. The <code>@flushright</code> command + <p>right justifies every line but leaves the + <p>left end ragged. + </div> + +<div class="node"> +<p><hr> +<a name="noindent"></a>Next: <a rel="next" accesskey="n" href="#indent">indent</a>, +Previous: <a rel="previous" accesskey="p" href="#flushleft-_0026-flushright">flushleft & flushright</a>, +Up: <a rel="up" accesskey="u" href="#Quotations-and-Examples">Quotations and Examples</a> +<br> +</div> + +<h3 class="section">10.12 <code>@noindent</code>: Omitting Indentation</h3> + +<p><a name="index-Omitting-indentation-492"></a><a name="index-Suppressing-indentation-493"></a><a name="index-Indentation_002c-omitting-494"></a><a name="index-noindent-495"></a> +An example or other inclusion can break a paragraph into segments. +Ordinarily, the formatters indent text that follows an example as a new +paragraph. You can prevent this on a case-by-case basis by writing +<code>@noindent</code> at the beginning of a line, preceding the continuation +text. You can also disable indentation for all paragraphs globally with +<code>@paragraphindent</code> (see <a href="#paragraphindent">Paragraph Indenting</a>). + + <p>It is best to write <code>@noindent</code> on a line by itself, since in most +environments, spaces following the command will not be ignored. It's ok +to use it at the beginning of a line, with text following, outside of +any environment. + + <p>For example: + +<pre class="example"> @example + This is an example + @end example + + @noindent + This line is not indented. As you can see, the + beginning of the line is fully flush left with the line + that follows after it. (This whole example is between + @code{@@display} and @code{@@end display}.) +</pre> + <p class="noindent">produces: + +<pre class="display"> + <pre class="example"> This is an example + </pre> + + <p class="noindent">This line is not indented. As you can see, the + beginning of the line is fully flush left with the line + that follows after it. (This whole example is between + <code>@display</code> and <code>@end display</code>.) + +</pre> + <p>To adjust the number of blank lines properly in the Info file output, +remember that the line containing <code>@noindent</code> does not generate a +blank line, and neither does the <code>@end example</code> line. + + <p>In the Texinfo source file for this manual, each line that says +`produces' is preceded by <code>@noindent</code>. + + <p>Do not put braces after an <code>@noindent</code> command; they are not +necessary, since <code>@noindent</code> is a command used outside of +paragraphs (see <a href="#Command-Syntax">Command Syntax</a>). + +<div class="node"> +<p><hr> +<a name="indent"></a>Next: <a rel="next" accesskey="n" href="#cartouche">cartouche</a>, +Previous: <a rel="previous" accesskey="p" href="#noindent">noindent</a>, +Up: <a rel="up" accesskey="u" href="#Quotations-and-Examples">Quotations and Examples</a> +<br> +</div> + +<h3 class="section">10.13 <code>@indent</code>: Forcing Indentation</h3> + +<p><a name="index-Forcing-indentation-496"></a><a name="index-Inserting-indentation-497"></a><a name="index-Indentation_002c-forcing-498"></a><a name="index-indent-499"></a> + + To complement the <code>@noindent</code> command (see the previous +section), Texinfo provides the <code>@indent</code> command that forces a +paragraph to be indented. This paragraph, for instance, is indented +using an <code>@indent</code> command. The first paragraph of a section is +the most likely place to use <code>@indent</code>, to override the normal +behavior of no indentation there (see <a href="#paragraphindent">paragraphindent</a>). + + <p>It is best to write <code>@indent</code> on a line by itself, since in most +environments, spaces following the command will not be ignored. The +<code>@indent</code> line will not generate a blank line in the Info output +within an environment. + + <p>However, it is ok to use it at the beginning of a line, with text +following, outside of any environment. + + <p>Do not put braces after an <code>@indent</code> command; they are not +necessary, since <code>@indent</code> is a command used outside of +paragraphs (see <a href="#Command-Syntax">Command Syntax</a>). + +<div class="node"> +<p><hr> +<a name="cartouche"></a>Previous: <a rel="previous" accesskey="p" href="#indent">indent</a>, +Up: <a rel="up" accesskey="u" href="#Quotations-and-Examples">Quotations and Examples</a> +<br> +</div> + +<h3 class="section">10.14 <code>@cartouche</code>: Rounded Rectangles Around Examples</h3> + +<p><a name="index-cartouche-500"></a><a name="index-Box-with-rounded-corners-501"></a><a name="index-Rounded-rectangles_002c-around-examples-502"></a> +In a printed manual, the <code>@cartouche</code> command draws a box with +rounded corners around its contents. In HTML, a normal rectangle is +drawn (that's the best HTML can do). <code>@cartouche</code> has no effect +in Info output. + + <p>You can use this command to further highlight an example or quotation. +For instance, you could write a manual in which one type of example is +surrounded by a cartouche for emphasis. + + <p>For example, + +<pre class="example"> @cartouche + @example + % pwd + /usr/local/share/emacs + @end example + @end cartouche +</pre> + <p class="noindent">surrounds the two-line example with a box with rounded corners, in the +printed manual. + + <p>The output from the example looks like this (if you're reading this in +Info, you'll see the <code>@cartouche</code> had no effect): + + <p><table class="cartouche" summary="cartouche" border="1"><tr><td> +<pre class="example"> % pwd + /usr/local/info +</pre> + </td></tr></table> + + <p>For proper output in HTML, it's necessary to put the +<code>@cartouche</code> around the <code>@example</code>, and not the other way +around. This limitation of <span class="command">makeinfo</span> may be removed one day. + + <p><code>@cartouche</code> also implies <code>@group</code> (see <a href="#group">group</a>). + +<div class="node"> +<p><hr> +<a name="Lists-and-Tables"></a>Next: <a rel="next" accesskey="n" href="#Special-Displays">Special Displays</a>, +Previous: <a rel="previous" accesskey="p" href="#Quotations-and-Examples">Quotations and Examples</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> +<br> +</div> + +<h2 class="chapter">11 Lists and Tables</h2> + +<p><a name="index-Making-lists-and-tables-503"></a><a name="index-Lists-and-tables_002c-making-504"></a><a name="index-Tables-and-lists_002c-making-505"></a> +Texinfo has several ways of making lists and tables. Lists can be +bulleted or numbered; two-column tables can highlight the items in +the first column; multi-column tables are also supported. + +<ul class="menu"> +<li><a accesskey="1" href="#Introducing-Lists">Introducing Lists</a>: Texinfo formats lists for you. +<li><a accesskey="2" href="#itemize">itemize</a>: How to construct a simple list. +<li><a accesskey="3" href="#enumerate">enumerate</a>: How to construct a numbered list. +<li><a accesskey="4" href="#Two_002dcolumn-Tables">Two-column Tables</a>: How to construct a two-column table. +<li><a accesskey="5" href="#Multi_002dcolumn-Tables">Multi-column Tables</a>: How to construct generalized tables. +</ul> + +<div class="node"> +<p><hr> +<a name="Introducing-Lists"></a>Next: <a rel="next" accesskey="n" href="#itemize">itemize</a>, +Up: <a rel="up" accesskey="u" href="#Lists-and-Tables">Lists and Tables</a> +<br> +</div> + +<h3 class="section">11.1 Introducing Lists</h3> + +<p>Texinfo automatically indents the text in lists or tables, and numbers +an enumerated list. This last feature is useful if you modify the +list, since you do not need to renumber it yourself. + + <p>Numbered lists and tables begin with the appropriate @-command at the +beginning of a line, and end with the corresponding <code>@end</code> +command on a line by itself. The table and itemized-list commands +also require that you write formatting information on the same line as +the beginning @-command. + + <p>Begin an enumerated list, for example, with an <code>@enumerate</code> +command and end the list with an <code>@end enumerate</code> command. +Begin an itemized list with an <code>@itemize</code> command, followed on +the same line by a formatting command such as <code>@bullet</code>, and end +the list with an <code>@end itemize</code> command. +<a name="index-end-506"></a> +Precede each element of a list with an <code>@item</code> or <code>@itemx</code> +command. + + <pre class="sp"> + +</pre> +Here is an itemized list of the different kinds of table and lists: + + <ul> +<li>Itemized lists with and without bullets. + + <li>Enumerated lists, using numbers or letters. + + <li>Two-column tables with highlighting. +</ul> + + <pre class="sp"> + +</pre> +Here is an enumerated list with the same items: + + <ol type=1 start=1> +<li>Itemized lists with and without bullets. + + <li>Enumerated lists, using numbers or letters. + + <li>Two-column tables with highlighting. + </ol> + + <pre class="sp"> + +</pre> +And here is a two-column table with the same items and their +@-commands<!-- /@w -->: + + <dl> +<dt><code>@itemize</code><dd>Itemized lists with and without bullets. + + <br><dt><code>@enumerate</code><dd>Enumerated lists, using numbers or letters. + + <br><dt><code>@table</code><dt><code>@ftable</code><dt><code>@vtable</code><dd>Two-column tables, optionally with indexing. +</dl> + +<div class="node"> +<p><hr> +<a name="itemize"></a>Next: <a rel="next" accesskey="n" href="#enumerate">enumerate</a>, +Previous: <a rel="previous" accesskey="p" href="#Introducing-Lists">Introducing Lists</a>, +Up: <a rel="up" accesskey="u" href="#Lists-and-Tables">Lists and Tables</a> +<br> +</div> + +<h3 class="section">11.2 <code>@itemize</code>: Making an Itemized List</h3> + +<p><a name="index-Itemization-507"></a><a name="index-itemize-508"></a> +The <code>@itemize</code> command produces sequences of indented +paragraphs, with a bullet or other mark inside the left margin +at the beginning of each paragraph for which such a mark is desired. + + <p><a name="index-_0040code_007b_0040_0040w_007d_002c-for-blank-items-509"></a>Begin an itemized list by writing <code>@itemize</code> at the beginning of +a line. Follow the command, on the same line, with a character or a +Texinfo command that generates a mark. Usually, you will write +<code>@bullet</code> after <code>@itemize</code>, but you can use +<code>@minus</code>, or any command or character that results in a single +character in the Info file. If you don't want any mark at all, use +<code>@w</code>. (When you write the mark command such as +<code>@bullet</code> after an <code>@itemize</code> command, you may omit the +<span class="samp">{}</span>.) If you don't specify a mark command, the default is +<code>@bullet</code>. + + <p>Write the text of the indented paragraphs themselves after the +<code>@itemize</code>, up to another line that says <code>@end +itemize</code>. + + <p><a name="index-item-510"></a>At the beginning of each paragraph for which a mark in the margin is +desired, write a line that starts with <code>@item</code>. It is ok to +have text following the <code>@item</code>. + + <p>Usually, you should put a blank line before an <code>@item</code>. This +puts a blank line in the Info file. (TeX inserts the proper +interline whitespace in either case.) Except when the entries are +very brief, these blank lines make the list look better. + + <p>Here is an example of the use of <code>@itemize</code>, followed by the +output it produces. <code>@bullet</code> produces an <span class="samp">*</span> in Info and a +round dot in TeX. + +<pre class="example"> @itemize @bullet + @item + Some text for foo. + + @item + Some text + for bar. + @end itemize +</pre> + <p class="noindent">This produces: + + <blockquote> + <ul> +<li>Some text for foo. + + <li>Some text +for bar. +</ul> + </blockquote> + + <p>Itemized lists may be embedded within other itemized lists. Here is a +list marked with dashes embedded in a list marked with bullets: + +<pre class="example"> @itemize @bullet + @item + First item. + + @itemize @minus + @item + Inner item. + + @item + Second inner item. + @end itemize + + @item + Second outer item. + @end itemize +</pre> + <p class="noindent">This produces: + + <blockquote> + <ul> +<li>First item. + + <ul> +<li>Inner item. + + <li>Second inner item. +</ul> + + <li>Second outer item. +</ul> + </blockquote> + +<div class="node"> +<p><hr> +<a name="enumerate"></a>Next: <a rel="next" accesskey="n" href="#Two_002dcolumn-Tables">Two-column Tables</a>, +Previous: <a rel="previous" accesskey="p" href="#itemize">itemize</a>, +Up: <a rel="up" accesskey="u" href="#Lists-and-Tables">Lists and Tables</a> +<br> +</div> + +<h3 class="section">11.3 <code>@enumerate</code>: Making a Numbered or Lettered List</h3> + +<p><a name="index-Enumeration-511"></a><a name="index-enumerate-512"></a> +<code>@enumerate</code> is like <code>@itemize</code> (see <a href="#itemize"><code>@itemize</code></a>), except that the labels on the items are +successive integers or letters instead of bullets. + + <p>Write the <code>@enumerate</code> command at the beginning of a line. The +command does not require an argument, but accepts either a number or a +letter as an option. Without an argument, <code>@enumerate</code> starts the +list with the number <span class="samp">1</span>. With a numeric argument, such as +<span class="samp">3</span>, the command starts the list with that number. With an upper +or lower case letter, such as <span class="samp">a</span> or <span class="samp">A</span>, the command starts +the list with that letter. + + <p>Write the text of the enumerated list in the same way as an itemized +list: write a line starting with <code>@item</code> at the beginning of +each paragraph that you want enumerated. It is ok to have text +following the <code>@item</code>. + + <p>You should put a blank line between entries in the list. +This generally makes it easier to read the Info file. + + <p>Here is an example of <code>@enumerate</code> without an argument: + +<pre class="example"> @enumerate + @item + Underlying causes. + + @item + Proximate causes. + @end enumerate +</pre> + <p class="noindent">This produces: + + <ol type=1 start=1> +<li>Underlying causes. + + <li>Proximate causes. + </ol> + <pre class="sp"> + +</pre> +Here is an example with an argument of <kbd>3</kbd>: + <pre class="sp"> + +</pre> +<pre class="example"> @enumerate 3 + @item + Predisposing causes. + + @item + Precipitating causes. + + @item + Perpetuating causes. + @end enumerate +</pre> + <p class="noindent">This produces: + + <ol type=1 start=3> +<li>Predisposing causes. + + <li>Precipitating causes. + + <li>Perpetuating causes. + </ol> + <pre class="sp"> + +</pre> +Here is a brief summary of the alternatives. The summary is constructed +using <code>@enumerate</code> with an argument of <kbd>a</kbd>. + <pre class="sp"> + +</pre> + <ol type=a start=1> +<li><code>@enumerate</code> + + <p>Without an argument, produce a numbered list, starting with the number +1. + + <li><code>@enumerate </code><var>positive-integer</var> + + <p>With a (positive) numeric argument, start a numbered list with that +number. You can use this to continue a list that you interrupted with +other text. + + <li><code>@enumerate </code><var>upper-case-letter</var> + + <p>With an upper case letter as argument, start a list +in which each item is marked +by a letter, beginning with that upper case letter. + + <li><code>@enumerate </code><var>lower-case-letter</var> + + <p>With a lower case letter as argument, start a list +in which each item is marked by +a letter, beginning with that lower case letter. + </ol> + + <p>You can also nest enumerated lists, as in an outline. + +<div class="node"> +<p><hr> +<a name="Two_002dcolumn-Tables"></a>Next: <a rel="next" accesskey="n" href="#Multi_002dcolumn-Tables">Multi-column Tables</a>, +Previous: <a rel="previous" accesskey="p" href="#enumerate">enumerate</a>, +Up: <a rel="up" accesskey="u" href="#Lists-and-Tables">Lists and Tables</a> +<br> +</div> + +<h3 class="section">11.4 Making a Two-column Table</h3> + +<p><a name="index-Tables_002c-making-two_002dcolumn-513"></a><a name="index-table-514"></a> +<code>@table</code> is similar to <code>@itemize</code> (see <a href="#itemize"><code>@itemize</code></a>), but allows you to specify a name or heading line for +each item. The <code>@table</code> command is used to produce two-column +tables, and is especially useful for glossaries, explanatory +exhibits, and command-line option summaries. + +<ul class="menu"> +<li><a accesskey="1" href="#table">table</a>: How to construct a two-column table. +<li><a accesskey="2" href="#ftable-vtable">ftable vtable</a>: Automatic indexing for two-column tables. +<li><a accesskey="3" href="#itemx">itemx</a>: How to put more entries in the first column. +</ul> + +<div class="node"> +<p><hr> +<a name="table"></a>Next: <a rel="next" accesskey="n" href="#ftable-vtable">ftable vtable</a>, +Up: <a rel="up" accesskey="u" href="#Two_002dcolumn-Tables">Two-column Tables</a> +<br> +</div> + +<h4 class="subsection">11.4.1 Using the <code>@table</code> Command</h4> + +<p><a name="index-Definition-lists_002c-typesetting-515"></a>Use the <code>@table</code> command to produce two-column tables. It is +usually listed for “definition lists” of various sorts, where you +have a list of terms and a brief text with each one. + + <p>Write the <code>@table</code> command at the beginning of a line, after a +blank line, and follow it on the same line with an argument that is a +Texinfo “indicating” command such as <code>@code</code>, <code>@samp</code>, +<code>@var</code>, <code>@option</code>, or <code>@kbd</code> (see <a href="#Indicating">Indicating</a>). + + <p>This command will be applied to the text that goes into the first +column of each item and thus determines how it will be highlighted. +For example, <code>@table @code</code> will cause the text in the first +column to be output as if it <code>@code</code> command. + + <p><a name="index-asis-516"></a>You may also use the <code>@asis</code> command as an argument to +<code>@table</code>. <code>@asis</code> is a command that does nothing; if you +use this command after <code>@table</code>, the first column entries are +output without added highlighting (“as is”). + + <p>The <code>@table</code> command works with other commands besides those +explicitly mentioned here. However, you can only use commands that +normally take arguments in braces. (In this case, however, you use +the command name without an argument, because the subsequent +<code>@item</code>'s will supply the argument.) + + <p><a name="index-item-517"></a>Begin each table entry with an <code>@item</code> command at the beginning +of a line. Write the first column text on the same line as the +<code>@item</code> command. Write the second column text on the line +following the <code>@item</code> line and on subsequent lines. (You do not +need to type anything for an empty second column entry.) You may +write as many lines of supporting text as you wish, even several +paragraphs. But only the text on the same line as the <code>@item</code> +will be placed in the first column (including any footnotes). + + <p>Normally, you should put a blank line before an <code>@item</code> line. +This puts a blank line in the Info file. Except when the entries are +very brief, a blank line looks better. + + <p>End the table with a line consisting of <code>@end table</code>, followed +by a blank line. TeX will always start a new paragraph after the +table, so the blank line is needed for the Info output to be analogous. + + <p>The following table, for example, highlights the text in the first +column with an <code>@samp</code> command: + +<pre class="example"> @table @samp + @item foo + This is the text for + @samp{foo}. + + @item bar + Text for @samp{bar}. + @end table +</pre> + <p class="noindent">This produces: + + <dl> +<dt><span class="samp">foo</span><dd>This is the text for +<span class="samp">foo</span>. +<br><dt><span class="samp">bar</span><dd>Text for <span class="samp">bar</span>. +</dl> + + <p>If you want to list two or more named items with a single block of +text, use the <code>@itemx</code> command. (See <a href="#itemx"><code>@itemx</code></a>.) + +<div class="node"> +<p><hr> +<a name="ftable-vtable"></a>Next: <a rel="next" accesskey="n" href="#itemx">itemx</a>, +Previous: <a rel="previous" accesskey="p" href="#table">table</a>, +Up: <a rel="up" accesskey="u" href="#Two_002dcolumn-Tables">Two-column Tables</a> +<br> +</div> + +<h4 class="subsection">11.4.2 <code>@ftable</code> and <code>@vtable</code></h4> + +<p><a name="index-Tables-with-indexes-518"></a><a name="index-Indexing-table-entries-automatically-519"></a><a name="index-ftable-520"></a><a name="index-vtable-521"></a> +The <code>@ftable</code> and <code>@vtable</code> commands are the same as the +<code>@table</code> command except that <code>@ftable</code> automatically enters +each of the items in the first column of the table into the index of +functions and <code>@vtable</code> automatically enters each of the items in +the first column of the table into the index of variables. This +simplifies the task of creating indices. Only the items on the same +line as the <code>@item</code> commands are indexed, and they are indexed in +exactly the form that they appear on that line. See <a href="#Indices">Indices</a>, +for more information about indices. + + <p>Begin a two-column table using <code>@ftable</code> or <code>@vtable</code> by +writing the @-command at the beginning of a line, followed on the same +line by an argument that is a Texinfo command such as <code>@code</code>, +exactly as you would for an <code>@table</code> command; and end the table +with an <code>@end ftable</code> or <code>@end vtable</code> command on a line by +itself. + + <p>See the example for <code>@table</code> in the previous section. + +<div class="node"> +<p><hr> +<a name="itemx"></a>Previous: <a rel="previous" accesskey="p" href="#ftable-vtable">ftable vtable</a>, +Up: <a rel="up" accesskey="u" href="#Two_002dcolumn-Tables">Two-column Tables</a> +<br> +</div> + +<h4 class="subsection">11.4.3 <code>@itemx</code></h4> + +<p><a name="index-Two-named-items-for-_0040code_007b_0040_0040table_007d-522"></a><a name="index-itemx-523"></a> +Use the <code>@itemx</code> command inside a table when you have two or more +first column entries for the same item, each of which should appear on a +line of its own. + + <p>Use <code>@item</code> for the first entry, and <code>@itemx</code> for all +subsequent entries; <code>@itemx</code> must always follow an <code>@item</code> +command, with no blank line intervening. + + <p>The <code>@itemx</code> command works exactly like <code>@item</code> except +that it does not generate extra vertical space above the first column +text. If you have multiple consecutive <code>@itemx</code> commands, do +not insert any blank lines between them. + + <p>For example, + +<pre class="example"> @table @code + @item upcase + @itemx downcase + These two functions accept a character or a string as + argument, and return the corresponding upper case (lower + case) character or string. + @end table +</pre> + <p class="noindent">This produces: + + <dl> +<dt><code>upcase</code><dt><code>downcase</code><dd>These two functions accept a character or a string as +argument, and return the corresponding upper case (lower +case) character or string. +</dl> + +<p class="noindent">(Note also that this example illustrates multi-line supporting text in +a two-column table.) + +<div class="node"> +<p><hr> +<a name="Multi_002dcolumn-Tables"></a>Previous: <a rel="previous" accesskey="p" href="#Two_002dcolumn-Tables">Two-column Tables</a>, +Up: <a rel="up" accesskey="u" href="#Lists-and-Tables">Lists and Tables</a> +<br> +</div> + +<h3 class="section">11.5 <code>@multitable</code>: Multi-column Tables</h3> + +<p><a name="index-Tables_002c-making-multi_002dcolumn-524"></a><a name="index-multitable-525"></a> +<code>@multitable</code> allows you to construct tables with any number of +columns, with each column having any width you like. + + <p>You define the column widths on the <code>@multitable</code> line itself, and +write each row of the actual table following an <code>@item</code> command, +with columns separated by an <code>@tab</code> command. Finally, <code>@end +multitable</code> completes the table. Details in the sections below. + +<ul class="menu"> +<li><a accesskey="1" href="#Multitable-Column-Widths">Multitable Column Widths</a>: Defining multitable column widths. +<li><a accesskey="2" href="#Multitable-Rows">Multitable Rows</a>: Defining multitable rows, with examples. +</ul> + +<div class="node"> +<p><hr> +<a name="Multitable-Column-Widths"></a>Next: <a rel="next" accesskey="n" href="#Multitable-Rows">Multitable Rows</a>, +Up: <a rel="up" accesskey="u" href="#Multi_002dcolumn-Tables">Multi-column Tables</a> +<br> +</div> + +<h4 class="subsection">11.5.1 Multitable Column Widths</h4> + +<p><a name="index-Multitable-column-widths-526"></a><a name="index-Column-widths_002c-defining-for-multitables-527"></a><a name="index-Widths_002c-defining-multitable-column-528"></a> +You can define the column widths for a multitable in two ways: as +fractions of the line length; or with a prototype row. Mixing the two +methods is not supported. In either case, the widths are defined +entirely on the same line as the <code>@multitable</code> command. + + <ol type=1 start=1> +<li><a name="index-columnfractions-529"></a><a name="index-Line-length_002c-column-widths-as-fraction-of-530"></a>To specify column widths as fractions of the line length, write +<code>@columnfractions</code> and the decimal numbers (presumably less than +1; a leading zero is allowed and ignored) after the +<code>@multitable</code> command, as in: + + <pre class="example"> @multitable @columnfractions .33 .33 .33 + </pre> + <p>The fractions need not add up exactly to 1.0, as these do not. This +allows you to produce tables that do not need the full line length. + + <li><a name="index-Prototype-row_002c-column-widths-defined-by-531"></a>To specify a prototype row, write the longest entry for each column +enclosed in braces after the <code>@multitable</code> command. For example: + + <pre class="example"> @multitable {some text for column one} {for column two} + </pre> + <p class="noindent">The first column will then have the width of the typeset `some text for +column one', and the second column the width of `for column two'. + + <p>The prototype entries need not appear in the table itself. + + <p>Although we used simple text in this example, the prototype entries can +contain Texinfo commands; markup commands such as <code>@code</code> are +particularly likely to be useful. + + </ol> + +<div class="node"> +<p><hr> +<a name="Multitable-Rows"></a>Previous: <a rel="previous" accesskey="p" href="#Multitable-Column-Widths">Multitable Column Widths</a>, +Up: <a rel="up" accesskey="u" href="#Multi_002dcolumn-Tables">Multi-column Tables</a> +<br> +</div> + +<h4 class="subsection">11.5.2 Multitable Rows</h4> + +<p><a name="index-Multitable-rows-532"></a><a name="index-Rows_002c-of-a-multitable-533"></a> +<a name="index-item-534"></a><a name="index-tab-535"></a>After the <code>@multitable</code> command defining the column widths (see +the previous section), you begin each row in the body of a multitable +with <code>@item</code>, and separate the column entries with <code>@tab</code>. +Line breaks are not special within the table body, and you may break +input lines in your source file as necessary. + + <p><a name="index-headitem-536"></a><a name="index-Heading-row_002c-in-table-537"></a><a name="index-_003cthead_003e-HTML-tag-538"></a>You can also use <code>@headitem</code> instead of <code>@item</code> to produce +a <dfn>heading row</dfn>. The TeX output for such a row is in bold, and +the HTML, XML, and Docbook output uses the <code><thead></code> tag. + + <p>Here is a complete example of a multi-column table (the text is from +<cite>The GNU Emacs Manual</cite>, see <a href="emacs.html#Split-Window">Splitting Windows (The GNU Emacs Manual)</a>): + +<pre class="example"> @multitable @columnfractions .15 .45 .4 + @headitem Key @tab Command @tab Description + @item C-x 2 + @tab @code{split-window-vertically} + @tab Split the selected window into two windows, + with one above the other. + @item C-x 3 + @tab @code{split-window-horizontally} + @tab Split the selected window into two windows + positioned side by side. + @item C-Mouse-2 + @tab + @tab In the mode line or scroll bar of a window, + split that window. + @end multitable +</pre> + <p class="noindent">produces: + + <p><table summary=""><tr align="left"><th valign="top" width="15%">Key </th><th valign="top" width="45%">Command </th><th valign="top" width="40%">Description +<br></th></tr><tr align="left"><td valign="top" width="15%">C-x 2 +</td><td valign="top" width="45%"><code>split-window-vertically</code> +</td><td valign="top" width="40%">Split the selected window into two windows, +with one above the other. +<br></td></tr><tr align="left"><td valign="top" width="15%">C-x 3 +</td><td valign="top" width="45%"><code>split-window-horizontally</code> +</td><td valign="top" width="40%">Split the selected window into two windows +positioned side by side. +<br></td></tr><tr align="left"><td valign="top" width="15%">C-Mouse-2 +</td><td valign="top" width="45%"> +</td><td valign="top" width="40%">In the mode line or scroll bar of a window, +split that window. + <br></td></tr></table> + +<div class="node"> +<p><hr> +<a name="Special-Displays"></a>Next: <a rel="next" accesskey="n" href="#Indices">Indices</a>, +Previous: <a rel="previous" accesskey="p" href="#Lists-and-Tables">Lists and Tables</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> +<br> +</div> + +<h2 class="chapter">12 Special Displays</h2> + +<p><a name="index-Special-displays-539"></a> +The commands in this chapter allow you to write text that is specially +displayed (output format permitting), outside of the normal document +flow. + + <p>One set of such commands is for creating “floats”, that is, figures, +tables, and the like, set off from the main text, possibly numbered, +captioned, and/or referred to from elsewhere in the document. Images +are often included in these displays. + + <p>Another group of commands is for creating footnotes in Texinfo. + +<ul class="menu"> +<li><a accesskey="1" href="#Floats">Floats</a>: Figures, tables, and the like. +<li><a accesskey="2" href="#Images">Images</a>: Including graphics and images. +<li><a accesskey="3" href="#Footnotes">Footnotes</a>: Writing footnotes. +</ul> + +<div class="node"> +<p><hr> +<a name="Floats"></a>Next: <a rel="next" accesskey="n" href="#Images">Images</a>, +Up: <a rel="up" accesskey="u" href="#Special-Displays">Special Displays</a> +<br> +</div> + +<h3 class="section">12.1 Floats</h3> + +<p><a name="index-Floats_002c-in-general-540"></a> +A <dfn>float</dfn> is a display which is set off from the main text. It is +typically labelled as being a “Figure”, “Table”, “Example”, or +some similar type. + + <p><a name="index-Floating_002c-not-yet-implemented-541"></a>A float is so-named because, in principle, it can be moved to the +bottom or top of the current page, or to a following page, in the +printed output. (Floating does not make sense in other output +formats.) In the present version of Texinfo, however, this floating +is unfortunately not yet implemented. Instead, the floating material +is simply output at the current location, more or less as if it were +an <code>@group</code> (see <a href="#group"><code>@group</code></a>). + +<ul class="menu"> +<li><a accesskey="1" href="#float">float</a>: Producing floating material. +<li><a accesskey="2" href="#caption-shortcaption">caption shortcaption</a>: Specifying descriptions for floats. +<li><a accesskey="3" href="#listoffloats">listoffloats</a>: A table of contents for floats. +</ul> + +<div class="node"> +<p><hr> +<a name="float"></a>Next: <a rel="next" accesskey="n" href="#caption-shortcaption">caption shortcaption</a>, +Up: <a rel="up" accesskey="u" href="#Floats">Floats</a> +<br> +</div> + +<h4 class="subsection">12.1.1 <code>@float</code> [<var>type</var>][,<var>label</var>]: Floating material</h4> + +<p><a name="index-float-542"></a><a name="index-Float-environment-543"></a> +To produce floating material, enclose the material you want to be +displayed separate between <code>@float</code> and <code>@end float</code> +commands, on lines by themselves. + + <p>Floating material uses <code>@image</code> to display an already-existing +graphic (see <a href="#Images">Images</a>), or <code>@multitable</code> to display a table +(see <a href="#Multi_002dcolumn-Tables">Multi-column Tables</a>). However, the contents of the float can +be anything. Here's an example with simple text: + +<pre class="example"> @float Figure,fig:ex1 + This is an example float. + @end float +</pre> + <p class="noindent">And the output: + + <div class="float"> +<a name="fig_003aex1"></a>This is an example float. +<p><strong class="float-caption">Figure 12.1</strong></p></div> + + <p>As shown in the example, <code>@float</code> takes two arguments (separated +by a comma), <var>type</var> and <var>label</var>. Both are optional. + + <dl> +<dt><var>type</var><dd>Specifies the sort of float this is; typically a word such as +“Figure”, “Table”, etc. If not given, and <var>label</var> is, any +cross-referencing will simply use a bare number. + + <br><dt><var>label</var><dd>Specifies a cross-reference label for this float. If given, this +float is automatically given a number, and will appear in any +<code>@listofloats</code> output (see <a href="#listoffloats">listoffloats</a>). Cross-references +to <var>label</var> are allowed. + + <p><a name="index-Floats_002c-making-unnumbered-544"></a><a name="index-Unnumbered-float_002c-creating-545"></a>On the other hand, if <var>label</var> is not given, then the float will +not be numbered and consequently will not appear in the +<code>@listoffloats</code> output or be cross-referenceable. +</dl> + +<p class="noindent">Normally, you specify both <var>type</var> and <var>label</var>, to get a +labeled and numbered float. + + <p><a name="index-Floats_002c-numbering-of-546"></a><a name="index-Numbering-of-floats-547"></a>In Texinfo, all floats are numbered the same way: with the chapter +number (or appendix letter), a period, and the float number, which +simply counts 1, 2, 3, <small class="dots">...</small>, and is reset at each chapter. Each +float type is counted independently. + + <p>Floats within an <code>@unnumbered</code> are numbered, or outside of any +chapter, are simply numbered consecutively from 1. + + <p>These numbering conventions are not, at present, changeable. + +<div class="node"> +<p><hr> +<a name="caption-shortcaption"></a>Next: <a rel="next" accesskey="n" href="#listoffloats">listoffloats</a>, +Previous: <a rel="previous" accesskey="p" href="#float">float</a>, +Up: <a rel="up" accesskey="u" href="#Floats">Floats</a> +<br> +</div> + +<h4 class="subsection">12.1.2 <code>@caption</code> & <code>@shortcaption</code></h4> + +<p><a name="index-caption-548"></a><a name="index-shortcaption-549"></a><a name="index-Captions_002c-for-floats-550"></a><a name="index-Short-captions_002c-for-lists-of-floats-551"></a> +You may write an <code>@caption</code> anywhere within a <code>@float</code> +environment, to define a caption for the float. It is not allowed in +any other context. <code>@caption</code> takes a single argument, enclosed +in braces. Here's an example: + +<pre class="example"> @float + An example float, with caption. + @caption{Caption for example float.} + @end float +</pre> + <p class="noindent">The output is: + + <div class="float"> +An example float, with caption. + + <p><strong class="float-caption">Caption for example float.</strong></p></div> + + <p><code>@caption</code> can appear anywhere within the float; it is not +processed until the <code>@end float</code>. The caption text is usually a +sentence or two, but may consist of several paragraphs if necessary. + + <p>In the output, the caption always appears below the float; this is not +currently changeable. It is preceded by the float type and/or number, +as specified to the <code>@float</code> command (see the previous section). + + <p>The <code>@shortcaption</code> command likewise may be used only within +<code>@float</code>, and takes a single argument in braces. The short +caption text is used instead of the caption text in a list of floats +(see the next section). Thus, you can write a long caption for the +main document, and a short title to appear in the list of floats. + +<div class="node"> +<p><hr> +<a name="listoffloats"></a>Previous: <a rel="previous" accesskey="p" href="#caption-shortcaption">caption shortcaption</a>, +Up: <a rel="up" accesskey="u" href="#Floats">Floats</a> +<br> +</div> + +<h4 class="subsection">12.1.3 <code>@listoffloats</code>: Tables of contents for floats</h4> + +<p><a name="index-listoffloats-552"></a><a name="index-List-of-floats-553"></a><a name="index-Floats_002c-list-of-554"></a><a name="index-Table-of-contents_002c-for-floats-555"></a> +You can write a <code>@listoffloats</code> command to generate a list of +floats for a given float type (see <a href="#float">float</a>), analogous to the +document's overall table of contents. Typically, it is written in its +own <code>@unnumbered</code> node to provide a heading and structure, +rather like <code>@printindex</code> (see <a href="#Printing-Indices-_0026-Menus">Printing Indices & Menus</a>). + + <p><code>@listoffloats</code> takes one optional argument, the float type. +Here's an example: + +<pre class="example"> @node List of Figures + @unnumbered List of Figures + @listoffloats Figure +</pre> + <p class="noindent">And the output from <code>@listoffloats</code>: + +<pre class="display"> + +<ul class="listoffloats"> + <li><a href="#fig_003aex1">Figure 12.1</a></li> +</ul> + + </pre> + <p>Without any argument, <code>@listoffloats</code> generates a list of +floats for which no float type was specified, i.e., no first argument +to the <code>@float</code> command (see <a href="#float">float</a>). + + <p>Each line in the list of floats contains the float type (if any), +the float number, and the caption, if any—the <code>@shortcaption</code> +argument, if it was specified, else the <code>@caption</code> argument. +In Info, the result is a menu where each float can be selected. In +HTML, each line is a link to the float. In printed output, the page +number is included. + + <p>Unnumbered floats (those without cross-reference labels) are omitted +from the list of floats. + +<div class="node"> +<p><hr> +<a name="Images"></a>Next: <a rel="next" accesskey="n" href="#Footnotes">Footnotes</a>, +Previous: <a rel="previous" accesskey="p" href="#Floats">Floats</a>, +Up: <a rel="up" accesskey="u" href="#Special-Displays">Special Displays</a> +<br> +</div> + +<h3 class="section">12.2 Inserting Images</h3> + +<p><a name="index-Images_002c-inserting-556"></a><a name="index-Pictures_002c-inserting-557"></a><a name="index-image-558"></a> +You can insert an image given in an external file with the +<code>@image</code> command. Although images can be used anywhere, +including the middle of a paragraph, we describe them in this chapter +since they are most often part of a displayed figure or example. + +<ul class="menu"> +<li><a accesskey="1" href="#Image-Syntax">Image Syntax</a> +<li><a accesskey="2" href="#Image-Scaling">Image Scaling</a> +</ul> + +<div class="node"> +<p><hr> +<a name="Image-Syntax"></a>Next: <a rel="next" accesskey="n" href="#Image-Scaling">Image Scaling</a>, +Up: <a rel="up" accesskey="u" href="#Images">Images</a> +<br> +</div> + +<h4 class="subsection">12.2.1 Image Syntax</h4> + +<p>Here is the basic synopsis of the <code>@image</code> command: + +<pre class="example"> @image{<var>filename</var><span class="roman">[,</span> <var>width</var><span class="roman">[,</span> <var>height</var><span class="roman">[,</span> <var>alttext</var><span class="roman">[, </span><var>extension</var><span class="roman">]]]]</span>} +</pre> + <p><a name="index-Formats-for-images-559"></a><a name="index-Image-formats-560"></a>The <var>filename</var> argument is mandatory, and must not have an +extension, because the different processors support different formats: + + <ul> +<li>TeX reads the file <var>filename</var><span class="file">.eps</span> (Encapsulated PostScript +format). +<li><a name="index-pdftex_0040r_007b_002c-and-images_007d-561"></a>PDFTeX reads <var>filename</var><span class="file">.pdf</span> (Adobe's Portable Document Format). +<li><code>makeinfo</code> includes <var>filename</var><span class="file">.txt</span> verbatim for +Info output (more or less as if it was an <code>@example</code>). +<li><code>makeinfo</code> uses the optional fifth argument <var>extension</var> to +<code>@image</code> for the filename extension, if it is specified. For example: + + <p><a name="index-XPM-image-format-562"></a> + <pre class="example"> @image{foo,,,,.xpm} + </pre> + <p class="noindent">will cause <code>makeinfo</code> to look for <span class="file">foo.xpm</span> before any others. + + </ul> + + <p>The <var>width</var> and <var>height</var> arguments are described in the next +section. + + <p><a name="index-Alt-attribute-for-images-563"></a><a name="index-Images_002c-alternate-text-for-564"></a>When producing html, <code>makeinfo</code> sets the <dfn>alt attribute</dfn> for +inline images to the optional <var>alttext</var> (fourth) argument to +<code>@image</code>, if supplied. If not supplied, <code>makeinfo</code> uses +the full file name of the image being displayed. If you want an empty +<code>alt</code> string, use <code>@-</code>. The <var>alttext</var> is taken as +Texinfo text, so special characters such as <span class="samp">"</span> and <span class="samp"><</span> and +<span class="samp">&</span> are escaped in the HTML and XML output. + + <p><a name="index-GIF-images_002c-unsupported-due-to-patents-565"></a><a name="index-PNG-image-format-566"></a><a name="index-JPG-image-format-567"></a>If you do not supply the optional <var>extension</var> (fifth) argument, +<code>makeinfo</code> first tries <var>filename</var><span class="file">.png</span>; if that does +not exist, it tries <var>filename</var><span class="file">.jpg</span>. If that does not exist +either, it complains. (We cannot support GIF format directly due to +software patents.) + + <p>In Info output, <code>makeinfo</code> writes a reference to the binary image +file (trying <var>filename</var> suffixed with <var>extension</var>, +<var>.extension</var>, <span class="file">.png</span>, or <span class="file">.jpg</span>, in that order) +if one exists. It also literally includes the <span class="file">.txt</span> file if one +exists. This way, Info readers which can display images (such as the +Emacs Info browser, running under X) can do so, whereas Info readers +which can only use text (such as the standalone Info reader) can +display the textual version. + + <p>The implementation of this is to put the following construct into the +Info output: + +<pre class="example"> ^@^H[image src="<var>binaryfile</var>" text="<var>txtfile</var>" + alt="<var>alttext</var> ... ^@^H] +</pre> + <p class="noindent">where <span class="samp">^@</span> and <span class="samp">^H</span> stand for the actual null and +backspace control characters. If one of the files is not present, the +corresponding argument is omitted. + + <p>The reason for mentioning this here is that older Info browsers (this +feature was introduced in Texinfo version 4.6) will display the above +literally, which, although not pretty, should not be harmful. + +<div class="node"> +<p><hr> +<a name="Image-Scaling"></a>Previous: <a rel="previous" accesskey="p" href="#Image-Syntax">Image Syntax</a>, +Up: <a rel="up" accesskey="u" href="#Images">Images</a> +<br> +</div> + +<h4 class="subsection">12.2.2 Image Scaling</h4> + +<p><a name="index-Images_002c-scaling-568"></a><a name="index-Scaling-images-569"></a><a name="index-Width-of-images-570"></a><a name="index-Height-of-images-571"></a><a name="index-Aspect-ratio-of-images-572"></a><a name="index-Distorting-images-573"></a>The optional <var>width</var> and <var>height</var> arguments to the +<code>@image</code> command (see the previous section) specify the size to +scale the image to. They are ignored for Info output. If neither is +specified, the image is presented in its natural size (given in the +file); if only one is specified, the other is scaled proportionately; +and if both are specified, both are respected, thus possibly distorting +the original image by changing its aspect ratio. + + <p><a name="index-Dimensions-and-image-sizes-574"></a>The <var>width</var> and <var>height</var> may be specified using any valid TeX +dimension, namely: + + <dl> +<dt>pt<dd><a name="index-Points-_0028dimension_0029-575"></a>point (72.27pt = 1in) +<br><dt>pc<dd><a name="index-Picas-576"></a>pica (1pc = 12pt) +<br><dt>bp<dd><a name="index-Big-points-577"></a>big point (72bp = 1in) +<br><dt>in<dd><a name="index-Inches-578"></a>inch +<br><dt>cm<dd><a name="index-Centimeters-579"></a>centimeter (2.54cm = 1in) +<br><dt>mm<dd><a name="index-Millimeters-580"></a>millimeter (10mm = 1cm) +<br><dt>dd<dd><a name="index-Did_0040_005eot-points-581"></a>didôt point (1157dd = 1238pt) +<br><dt>cc<dd><a name="index-Ciceros-582"></a>cicero (1cc = 12dd) +<br><dt>sp<dd><a name="index-Scaled-points-583"></a>scaled point (65536sp = 1pt) +</dl> + + <p><a name="index-ridt_002eeps-584"></a>For example, the following will scale a file <span class="file">ridt.eps</span> to one +inch vertically, with the width scaled proportionately: + +<pre class="example"> @image{ridt,,1in} +</pre> + <p><a name="index-epsf_002etex-585"></a>For <code>@image</code> to work with TeX, the file <span class="file">epsf.tex</span> must be +installed somewhere that TeX can find it. (The standard location is +<var>texmf</var><span class="file">/tex/generic/dvips/epsf.tex</span>, where <var>texmf</var> is a +root of your TeX directory tree.) This file is included in the +Texinfo distribution and is also available from +<a href="ftp://tug.org/tex/epsf.tex">ftp://tug.org/tex/epsf.tex</a>, among other places. + + <p><code>@image</code> can be used within a line as well as for displayed +figures. Therefore, if you intend it to be displayed, be sure to leave +a blank line before the command, or the output will run into the +preceding text. + + <p>Image scaling is presently implemented only in TeX, not in HTML or +any other sort of output. + +<div class="node"> +<p><hr> +<a name="Footnotes"></a>Previous: <a rel="previous" accesskey="p" href="#Images">Images</a>, +Up: <a rel="up" accesskey="u" href="#Special-Displays">Special Displays</a> +<br> +</div> + +<h3 class="section">12.3 Footnotes</h3> + +<p><a name="index-Footnotes-586"></a><a name="index-footnote-587"></a> +A <dfn>footnote</dfn> is for a reference that documents or elucidates the +primary text.<a rel="footnote" href="#fn-7" name="fnd-7"><sup>7</sup></a> Footnotes are distracting; use them +sparingly, if at all. Standard bibliographical references are better +placed in a bibliography at the end of a document than in footnotes +throughout. + +<ul class="menu"> +<li><a accesskey="1" href="#Footnote-Commands">Footnote Commands</a>: How to write a footnote in Texinfo. +<li><a accesskey="2" href="#Footnote-Styles">Footnote Styles</a>: Controlling how footnotes appear in Info. +</ul> + +<div class="node"> +<p><hr> +<a name="Footnote-Commands"></a>Next: <a rel="next" accesskey="n" href="#Footnote-Styles">Footnote Styles</a>, +Up: <a rel="up" accesskey="u" href="#Footnotes">Footnotes</a> +<br> +</div> + +<h4 class="subsection">12.3.1 Footnote Commands</h4> + +<p>In Texinfo, footnotes are created with the <code>@footnote</code> command. +This command is followed immediately by a left brace, then by the text +of the footnote, and then by a terminating right brace. Footnotes may +be of any length (they will be broken across pages if necessary), but +are usually short. The template is: + +<pre class="example"> ordinary text@footnote{<var>text of footnote</var>} +</pre> + <p>As shown here, the <code>@footnote</code> command should come right after the +text being footnoted, with no intervening space; otherwise, the footnote +marker might end up starting a line. + + <p>For example, this clause is followed by a sample footnote<a rel="footnote" href="#fn-8" name="fnd-8"><sup>8</sup></a>; in the Texinfo source, it looks like +this: + +<pre class="example"> ...a sample footnote@footnote{Here is the sample + footnote.}; in the Texinfo source... +</pre> + <p>As you can see, the source includes two punctuation marks next to each +other; in this case, <span class="samp">.};</span> is the sequence. This is normal (the +first ends the footnote and the second belongs to the sentence being +footnoted), so don't worry that it looks odd. + + <p>In a printed manual or book, the reference mark for a footnote is a +small, superscripted number; the text of the footnote appears at the +bottom of the page, below a horizontal line. + + <p>In Info, the reference mark for a footnote is a pair of parentheses +with the footnote number between them, like this: <span class="samp">(1)</span>. The +reference mark is followed by a cross-reference link to the footnote's +text. + + <p>In the HTML output, footnote references are marked with a small, +superscripted number which is rendered as a hypertext link to the +footnote text. + + <p>By the way, footnotes in the argument of an <code>@item</code> command for a +<code>@table</code> must be on the same line as the <code>@item</code> +(as usual). See <a href="#Two_002dcolumn-Tables">Two-column Tables</a>. + +<div class="node"> +<p><hr> +<a name="Footnote-Styles"></a>Previous: <a rel="previous" accesskey="p" href="#Footnote-Commands">Footnote Commands</a>, +Up: <a rel="up" accesskey="u" href="#Footnotes">Footnotes</a> +<br> +</div> + +<h4 class="subsection">12.3.2 Footnote Styles</h4> + +<p>Info has two footnote styles, which determine where the text of the +footnote is located: + + +<a name="index-_0040samp_007b_0040r_007bEnd_007d_007d-node-footnote-style-588"></a> +<ul><li>In the `End' node style, all the footnotes for a single node +are placed at the end of that node. The footnotes are separated from +the rest of the node by a line of dashes with the word +<span class="samp">Footnotes</span> within it. Each footnote begins with an +<span class="samp">(</span><var>n</var><span class="samp">)</span> reference mark. + + <p class="noindent">Here is an example of a single footnote in the end of node style: + + <pre class="example"> --------- Footnotes --------- + + (1) Here is a sample footnote. + </pre> + <p><a name="index-_0040samp_007b_0040r_007bSeparate_007d_007d-footnote-style-589"></a><li>In the `Separate' node style, all the footnotes for a single +node are placed in an automatically constructed node of +their own. In this style, a “footnote reference” follows +each <span class="samp">(</span><var>n</var><span class="samp">)</span> reference mark in the body of the +node. The footnote reference is actually a cross reference +which you use to reach the footnote node. + + <p>The name of the node with the footnotes is constructed +by appending <span class="samp">-Footnotes</span><!-- /@w --> to the name of the node +that contains the footnotes. (Consequently, the footnotes' +node for the <span class="file">Footnotes</span> node is +<span class="file">Footnotes-Footnotes</span><!-- /@w -->!) The footnotes' node has an +`Up' node pointer that leads back to its parent node. + + <p class="noindent">Here is how the first footnote in this manual looks after being +formatted for Info in the separate node style: + + <pre class="smallexample"> File: texinfo.info Node: Overview-Footnotes, Up: Overview + + (1) The first syllable of "Texinfo" is pronounced like "speck", not + "hex". ... + </pre> + </ul> + + <p>Unless your document has long and important footnotes (as in, say, +Gibbon's <cite>Decline and Fall <small class="dots">...</small></cite>), we recommend the <span class="samp">end</span> +style, as it is simpler for readers to follow. + + <p><a name="index-footnotestyle-590"></a>Use the <code>@footnotestyle</code> command to specify an Info file's +footnote style. Write this command at the beginning of a line followed +by an argument, either <span class="samp">end</span> for the end node style or +<span class="samp">separate</span> for the separate node style. + + <p>For example, + +<pre class="example"> @footnotestyle end +</pre> + <p class="noindent">or +<pre class="example"> @footnotestyle separate +</pre> + <p>Write an <code>@footnotestyle</code> command before or shortly after the +end-of-header line at the beginning of a Texinfo file. (If you +include the <code>@footnotestyle</code> command between the start-of-header +and end-of-header lines, the region formatting commands will format +footnotes as specified.) + + <p>If you do not specify a footnote style, the formatting commands use +their default style. Currently, <code>texinfo-format-buffer</code> and +<code>texinfo-format-region</code> use the `separate' style and +<code>makeinfo</code> uses the `end' style. + +<div class="node"> +<p><hr> +<a name="Indices"></a>Next: <a rel="next" accesskey="n" href="#Insertions">Insertions</a>, +Previous: <a rel="previous" accesskey="p" href="#Special-Displays">Special Displays</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> +<br> +</div> + +<h2 class="chapter">13 Indices</h2> + +<p><a name="index-Indices-591"></a> +Using Texinfo, you can generate indices without having to sort and +collate entries manually. In an index, the entries are listed in +alphabetical order, together with information on how to find the +discussion of each entry. In a printed manual, this information +consists of page numbers. In an Info file, this information is a menu +entry leading to the first node referenced. + + <p>Texinfo provides several predefined kinds of index: an index +for functions, an index for variables, an index for concepts, and so +on. You can combine indices or use them for other than their +canonical purpose. Lastly, you can define your own new indices. + + <p>See <a href="#Printing-Indices-_0026-Menus">Printing Indices & Menus</a>, for information on how to print +indices. + +<ul class="menu"> +<li><a accesskey="1" href="#Index-Entries">Index Entries</a>: Choose different words for index entries. +<li><a accesskey="2" href="#Predefined-Indices">Predefined Indices</a>: Use different indices for different kinds + of entries. +<li><a accesskey="3" href="#Indexing-Commands">Indexing Commands</a>: How to make an index entry. +<li><a accesskey="4" href="#Combining-Indices">Combining Indices</a>: How to combine indices. +<li><a accesskey="5" href="#New-Indices">New Indices</a>: How to define your own indices. +</ul> + +<div class="node"> +<p><hr> +<a name="Index-Entries"></a>Next: <a rel="next" accesskey="n" href="#Predefined-Indices">Predefined Indices</a>, +Up: <a rel="up" accesskey="u" href="#Indices">Indices</a> +<br> +</div> + +<h3 class="section">13.1 Making Index Entries</h3> + +<p><a name="index-Index-entries_002c-making-592"></a><a name="index-Entries_002c-making-index-593"></a> +When you are making index entries, it is good practice to think of the +different ways people may look for something. Different people +<em>do not</em> think of the same words when they look something up. A +helpful index will have items indexed under all the different words +that people may use. For example, one reader may think it obvious that +the two-letter names for indices should be listed under “Indices, +two-letter names”, since the word “Index” is the general concept. +But another reader may remember the specific concept of two-letter +names and search for the entry listed as “Two letter names for +indices”. A good index will have both entries and will help both +readers. + + <p>Like typesetting, the construction of an index is a highly skilled, +professional art, the subtleties of which are not appreciated until you +need to do it yourself. + + <p>See <a href="#Printing-Indices-_0026-Menus">Printing Indices & Menus</a>, for information about printing an index +at the end of a book or creating an index menu in an Info file. + +<div class="node"> +<p><hr> +<a name="Predefined-Indices"></a>Next: <a rel="next" accesskey="n" href="#Indexing-Commands">Indexing Commands</a>, +Previous: <a rel="previous" accesskey="p" href="#Index-Entries">Index Entries</a>, +Up: <a rel="up" accesskey="u" href="#Indices">Indices</a> +<br> +</div> + +<h3 class="section">13.2 Predefined Indices</h3> + +<p>Texinfo provides six predefined indices. Here are their nominal +meanings, abbreviations, and the corresponding index entry commands: + + <dl> +<dt><span class="samp">cp</span><dd><a name="index-_0040code_007bcp_007d-_0028concept_0029-index-594"></a>(<code>@cindex</code>) concept index, for general concepts. +<br><dt><span class="samp">fn</span><dd><a name="index-_0040code_007bfn_007d-_0028function_0029-index-595"></a>(<code>@findex</code>) function index, for function and function-like +names (such as entry points of libraries). +<br><dt><span class="samp">ky</span><dd><a name="index-_0040code_007bky_007d-_0028keystroke_0029-index-596"></a>(<code>@kindex</code>) keystroke index, for keyboard commands. +<br><dt><span class="samp">pg</span><dd><a name="index-_0040code_007bpg_007d-_0028program_0029-index-597"></a>(<code>@pindex</code>) program index, for names of programs. +<br><dt><span class="samp">tp</span><dd><a name="index-_0040code_007btp_007d-_0028data-type_0029-index-598"></a>(<code>@tindex</code>) data type index, for type names (such as structures +defined in header files). +<br><dt><span class="samp">vr</span><dd><a name="index-_0040code_007bvr_007d-_0028variable_0029-index-599"></a>(<code>@vindex</code>) variable index, for variable names (such as global +variables of libraries). +</dl> + +<p class="noindent">Not every manual needs all of these, and most manuals use only two or +three at most. The present manual, for example, has two indices: a +concept index and an @-command index (that is actually the function +index but is called a command index in the chapter heading). + + <p>You are not required to use the predefined indices strictly for their +canonical purposes. For example, suppose you wish to index some C +preprocessor macros. You could put them in the function index along +with actual functions, just by writing <code>@findex</code> commands for +them; then, when you print the “Function Index” as an unnumbered +chapter, you could give it the title `Function and Macro Index' and +all will be consistent for the reader. + + <p>On the other hand, it is best not to stray too far from the meaning of +the predefined indices. Otherwise, in the event that your text is +combined with other text from other manuals, the index entries will +not match up. Instead, define your own new index (see <a href="#New-Indices">New Indices</a>). + + <p>We recommend having a single index in the final document whenever +possible, however many source indices you use, since then readers have +only one place to look. Two or more source indices can be combined +into one output index using the <code>@synindex</code> or +<code>@syncodeindex</code> commands (see <a href="#Combining-Indices">Combining Indices</a>). + +<div class="node"> +<p><hr> +<a name="Indexing-Commands"></a>Next: <a rel="next" accesskey="n" href="#Combining-Indices">Combining Indices</a>, +Previous: <a rel="previous" accesskey="p" href="#Predefined-Indices">Predefined Indices</a>, +Up: <a rel="up" accesskey="u" href="#Indices">Indices</a> +<br> +</div> + +<h3 class="section">13.3 Defining the Entries of an Index</h3> + +<p><a name="index-Defining-indexing-entries-600"></a><a name="index-Index-entries-601"></a><a name="index-Entries-for-an-index-602"></a><a name="index-Specifying-index-entries-603"></a><a name="index-Creating-index-entries-604"></a> +The data to make an index come from many individual indexing commands +scattered throughout the Texinfo source file. Each command says to add +one entry to a particular index; after formatting, the index will give +the current page number or node name as the reference. + + <p>An index entry consists of an indexing command at the beginning of a +line followed, on the rest of the line, by the entry. + + <p>For example, this section begins with the following five entries for +the concept index: + +<pre class="example"> @cindex Defining indexing entries + @cindex Index entries, defining + @cindex Entries for an index + @cindex Specifying index entries + @cindex Creating index entries +</pre> + <p>Each predefined index has its own indexing command—<code>@cindex</code> +for the concept index, <code>@findex</code> for the function index, and so +on, as listed in the previous section. + + <p><a name="index-Writing-index-entries-605"></a><a name="index-Index-entry-writing-606"></a>Concept index entries consist of text. The best way to write an index +is to choose entries that are terse yet clear. If you can do this, +the index often looks better if the entries are not capitalized, but +written just as they would appear in the middle of a sentence. +(Capitalize proper names and acronyms that always call for upper case +letters.) This is the case convention we use in most GNU manuals' +indices. + + <p>If you don't see how to make an entry terse yet clear, make it longer +and clear—not terse and confusing. If many of the entries are several +words long, the index may look better if you use a different convention: +to capitalize the first word of each entry. But do not capitalize a +case-sensitive name such as a C or Lisp function name or a shell +command; that would be a spelling error. + + <p>Whichever case convention you use, please use it consistently! + + <p>Entries in indices other than the concept index are symbol names in +programming languages, or program names; these names are usually +case-sensitive, so use upper and lower case as required for them. + + <p><a name="index-Index-font-types-607"></a>By default, entries for a concept index are printed in a small roman +font and entries for the other indices are printed in a small +<code>@code</code> font. You may change the way part of an entry is +printed with the usual Texinfo commands, such as <code>@file</code> for +file names (see <a href="#Marking-Text">Marking Text</a>), and <code>@r</code> for the normal roman +font (see <a href="#Fonts">Fonts</a>). + + <blockquote> +<b>Caution:</b> Do not use a colon in an index entry. In Info, a colon separates the +menu entry name from the node name, so a colon in the entry itself +confuses Info. See <a href="#Menu-Parts">Menu Parts</a>, for more information about the +structure of a menu entry. +</blockquote> + +<div class="node"> +<p><hr> +<a name="Combining-Indices"></a>Next: <a rel="next" accesskey="n" href="#New-Indices">New Indices</a>, +Previous: <a rel="previous" accesskey="p" href="#Indexing-Commands">Indexing Commands</a>, +Up: <a rel="up" accesskey="u" href="#Indices">Indices</a> +<br> +</div> + +<h3 class="section">13.4 Combining Indices</h3> + +<p><a name="index-Combining-indices-608"></a><a name="index-Indices_002c-combining-them-609"></a> +Sometimes you will want to combine two disparate indices such as +functions and concepts, perhaps because you have few enough entries +that a separate index would look silly. + + <p>You could put functions into the concept index by writing +<code>@cindex</code> commands for them instead of <code>@findex</code> commands, +and produce a consistent manual by printing the concept index with the +title `Function and Concept Index' and not printing the `Function +Index' at all; but this is not a robust procedure. It works only if +your document is never included as part of another document that is +designed to have a separate function index; if your document were to +be included with such a document, the functions from your document and +those from the other would not end up together. Also, to make your +function names appear in the right font in the concept index, you +would need to enclose every one of them between the braces of +<code>@code</code>. + +<ul class="menu"> +<li><a accesskey="1" href="#syncodeindex">syncodeindex</a>: How to merge two indices, using <code>@code</code> + font for the merged-from index. +<li><a accesskey="2" href="#synindex">synindex</a>: How to merge two indices, using the + default font of the merged-to index. +</ul> + +<div class="node"> +<p><hr> +<a name="syncodeindex"></a>Next: <a rel="next" accesskey="n" href="#synindex">synindex</a>, +Up: <a rel="up" accesskey="u" href="#Combining-Indices">Combining Indices</a> +<br> +</div> + +<h4 class="subsection">13.4.1 <code>@syncodeindex</code></h4> + +<p><a name="index-syncodeindex-610"></a> +When you want to combine functions and concepts into one index, you +should index the functions with <code>@findex</code> and index the concepts +with <code>@cindex</code>, and use the <code>@syncodeindex</code> command to +redirect the function index entries into the concept index. + + <p>The <code>@syncodeindex</code> command takes two arguments; they are the name +of the index to redirect, and the name of the index to redirect it to. +The template looks like this: + +<pre class="example"> @syncodeindex <var>from</var> <var>to</var> +</pre> + <p><a name="index-Predefined-names-for-indices-611"></a><a name="index-Two-letter-names-for-indices-612"></a><a name="index-Indices_002c-two-letter-names-613"></a><a name="index-Names-for-indices-614"></a>For this purpose, the indices are given two-letter names: + + <dl> +<dt><span class="samp">cp</span><dd>concept index +<br><dt><span class="samp">fn</span><dd>function index +<br><dt><span class="samp">vr</span><dd>variable index +<br><dt><span class="samp">ky</span><dd>key index +<br><dt><span class="samp">pg</span><dd>program index +<br><dt><span class="samp">tp</span><dd>data type index +</dl> + + <p>Write an <code>@syncodeindex</code> command before or shortly after the +end-of-header line at the beginning of a Texinfo file. For example, +to merge a function index with a concept index, write the +following: + +<pre class="example"> @syncodeindex fn cp +</pre> + <p class="noindent">This will cause all entries designated for the function index to merge +in with the concept index instead. + + <p>To merge both a variables index and a function index into a concept +index, write the following: + +<pre class="example"> @syncodeindex vr cp + @syncodeindex fn cp +</pre> + <p><a name="index-Fonts-for-indices-615"></a>The <code>@syncodeindex</code> command puts all the entries from the `from' +index (the redirected index) into the <code>@code</code> font, overriding +whatever default font is used by the index to which the entries are +now directed. This way, if you direct function names from a function +index into a concept index, all the function names are printed in the +<code>@code</code> font as you would expect. + +<div class="node"> +<p><hr> +<a name="synindex"></a>Previous: <a rel="previous" accesskey="p" href="#syncodeindex">syncodeindex</a>, +Up: <a rel="up" accesskey="u" href="#Combining-Indices">Combining Indices</a> +<br> +</div> + +<h4 class="subsection">13.4.2 <code>@synindex</code></h4> + +<p><a name="index-synindex-616"></a> +The <code>@synindex</code> command is nearly the same as the +<code>@syncodeindex</code> command, except that it does not put the +`from' index entries into the <code>@code</code> font; rather it puts +them in the roman font. Thus, you use <code>@synindex</code> when you +merge a concept index into a function index. + + <p>See <a href="#Printing-Indices-_0026-Menus">Printing Indices & Menus</a>, for information about printing an index +at the end of a book or creating an index menu in an Info file. + +<div class="node"> +<p><hr> +<a name="New-Indices"></a>Previous: <a rel="previous" accesskey="p" href="#Combining-Indices">Combining Indices</a>, +Up: <a rel="up" accesskey="u" href="#Indices">Indices</a> +<br> +</div> + +<h3 class="section">13.5 Defining New Indices</h3> + +<p><a name="index-Defining-new-indices-617"></a><a name="index-Indices_002c-defining-new-618"></a><a name="index-New-index-defining-619"></a><a name="index-defindex-620"></a><a name="index-defcodeindex-621"></a> +In addition to the predefined indices, you may use the +<code>@defindex</code> and <code>@defcodeindex</code> commands to define new +indices. These commands create new indexing @-commands with which +you mark index entries. The <code>@defindex</code> command is used like +this: + +<pre class="example"> @defindex <var>name</var> +</pre> + <p>The name of an index should be a two letter word, such as <span class="samp">au</span>. +For example: + +<pre class="example"> @defindex au +</pre> + <p>This defines a new index, called the <span class="samp">au</span> index. At the same +time, it creates a new indexing command, <code>@auindex</code>, that you +can use to make index entries. Use this new indexing command just as +you would use a predefined indexing command. + + <p>For example, here is a section heading followed by a concept index +entry and two <span class="samp">au</span> index entries. + +<pre class="example"> @section Cognitive Semantics + @cindex kinesthetic image schemas + @auindex Johnson, Mark + @auindex Lakoff, George +</pre> + <p class="noindent">(Evidently, <span class="samp">au</span> serves here as an abbreviation for “author”.) + + <p>In general, Texinfo constructs the new indexing command by +concatenating the name of the index with <span class="samp">index</span>; thus, defining +an <span class="samp">xy</span> index leads to the automatic creation of an +<code>@xyindex</code> command. + + <p>Use the <code>@printindex</code> command to print the index, as you do with +the predefined indices. For example: + +<pre class="example"> @node Author Index + @unnumbered Author Index + + @printindex au +</pre> + <p>The <code>@defcodeindex</code> is like the <code>@defindex</code> command, +except that, in the printed output, it prints entries in an +<code>@code</code> font by default instead of a roman font. + + <p>You should define new indices before the end-of-header line of a +Texinfo file, and (of course) before any <code>@synindex</code> or +<code>@syncodeindex</code> commands (see <a href="#Texinfo-File-Header">Texinfo File Header</a>). + +<div class="node"> +<p><hr> +<a name="Insertions"></a>Next: <a rel="next" accesskey="n" href="#Breaks">Breaks</a>, +Previous: <a rel="previous" accesskey="p" href="#Indices">Indices</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> +<br> +</div> + +<h2 class="chapter">14 Special Insertions</h2> + +<p><a name="index-Inserting-special-characters-and-symbols-622"></a><a name="index-Special-insertions-623"></a> +Texinfo provides several commands for inserting characters that have +special meaning in Texinfo, such as braces, and for other graphic +elements that do not correspond to simple characters you can type. + +<ul class="menu"> +<li><a accesskey="1" href="#Atsign-Braces-Comma">Atsign Braces Comma</a>: Inserting @ and {} and ,. +<li><a accesskey="2" href="#Inserting-Space">Inserting Space</a>: How to insert the right amount of space + within a sentence. +<li><a accesskey="3" href="#Inserting-Accents">Inserting Accents</a>: How to insert accents and special characters. +<li><a accesskey="4" href="#Dots-Bullets">Dots Bullets</a>: How to insert dots and bullets. +<li><a accesskey="5" href="#TeX-and-copyright">TeX and copyright</a>: How to insert the TeX logo + and the copyright symbol. +<li><a accesskey="6" href="#pounds">pounds</a>: How to insert the pounds currency symbol. +<li><a accesskey="7" href="#minus">minus</a>: How to insert a minus sign. +<li><a accesskey="8" href="#math">math</a>: How to format a mathematical expression. +<li><a accesskey="9" href="#Glyphs">Glyphs</a>: How to indicate results of evaluation, + expansion of macros, errors, etc. +</ul> + +<div class="node"> +<p><hr> +<a name="Atsign-Braces-Comma"></a>Next: <a rel="next" accesskey="n" href="#Inserting-Space">Inserting Space</a>, +Up: <a rel="up" accesskey="u" href="#Insertions">Insertions</a> +<br> +</div> + +<h3 class="section">14.1 Inserting @ and {} and ,</h3> + +<p><a name="index-Special-characters_002c-inserting-624"></a><a name="index-Commands-to-insert-special-characters-625"></a> +<span class="samp">@</span> and curly braces are special characters in Texinfo. To insert +these characters so they appear in text, you must put an <span class="samp">@</span> in +front of these characters to prevent Texinfo from misinterpreting +them. + + <p>The comma `,' is a special character only in one uncommon context: +it separates arguments to commands that take multiple arguments. + +<ul class="menu"> +<li><a accesskey="1" href="#Inserting-an-Atsign">Inserting an Atsign</a> +<li><a accesskey="2" href="#Inserting-Braces">Inserting Braces</a> +<li><a accesskey="3" href="#Inserting-a-Comma">Inserting a Comma</a> +</ul> + +<div class="node"> +<p><hr> +<a name="Inserting-an-Atsign"></a>Next: <a rel="next" accesskey="n" href="#Inserting-Braces">Inserting Braces</a>, +Up: <a rel="up" accesskey="u" href="#Atsign-Braces-Comma">Atsign Braces Comma</a> +<br> +</div> + +<h4 class="subsection">14.1.1 Inserting `@' with <code>@@</code></h4> + +<p><a name="index-_0040_0040-_0040r_007b_0028literal-_0040samp_007b_0040_0040_007d_0029_007d-626"></a><a name="index-Inserting-_0040_0040-_0040r_007b_0028literal-_0040samp_007b_0040_0040_007d_0029_007d-627"></a> +<code>@@</code> stands for a single <span class="samp">@</span> in either printed or Info +output. + + <p>Do not put braces after an <code>@@</code> command. + +<div class="node"> +<p><hr> +<a name="Inserting-Braces"></a>Next: <a rel="next" accesskey="n" href="#Inserting-a-Comma">Inserting a Comma</a>, +Previous: <a rel="previous" accesskey="p" href="#Inserting-an-Atsign">Inserting an Atsign</a>, +Up: <a rel="up" accesskey="u" href="#Atsign-Braces-Comma">Atsign Braces Comma</a> +<br> +</div> + +<h4 class="subsection">14.1.2 Inserting `{' and `}' with <code>@{</code> and <code>@}</code></h4> + +<p><a name="index-Braces_002c-inserting-628"></a><a name="index-_0040_007b-_0040r_007b_0028literal-_0040samp_007b_0040_007b_007d_0029_007d-629"></a><a name="index-_0040_007d-_0040r_007b_0028literal-_0040samp_007b_0040_007d_007d_0029_007d-630"></a> +<code>@{</code> stands for a single <span class="samp">{</span> in either printed or Info +output. + + <p><code>@}</code> stands for a single <span class="samp">}</span> in either printed or Info +output. + + <p>Do not put braces after either an <code>@{</code> or an <code>@}</code> +command.ppp + +<div class="node"> +<p><hr> +<a name="Inserting-a-Comma"></a>Previous: <a rel="previous" accesskey="p" href="#Inserting-Braces">Inserting Braces</a>, +Up: <a rel="up" accesskey="u" href="#Atsign-Braces-Comma">Atsign Braces Comma</a> +<br> +</div> + +<h4 class="subsection">14.1.3 Inserting `,' with <code>@comma{}</code></h4> + +<p><a name="index-Commas_002c-inserting-631"></a><a name="index-comma-632"></a> +Ordinarily, a comma `,' is a normal character that can be simply typed +in your input where you need it. + + <p>However, Texinfo uses the comma as a special character in one uncommon +context: some commands, such as <code>@acronym</code> (see <a href="#acronym">acronym</a>) and +<code>@xref</code> (see <a href="#Cross-References">Cross References</a>), as well as user-defined +macros (see <a href="#Defining-Macros">Defining Macros</a>), can take more than one argument. In +these cases, the comma character is used to separate arguments. + + <p>Since a comma chacter would confuse Texinfo's parsing for these +commands, you must use the command <span class="samp">,</span> instead if you want +to have an actual comma in the output. Here are some examples: + +<pre class="example"> @acronym{ABC, A Bizarre @comma{}} + @xref{Comma,, The @comma{} symbol} + @mymac{One argument@comma{} containing a comma} +</pre> + <p>Although , can be used anywhere, there is no need for it +anywhere except in this unusual case. + +<div class="node"> +<p><hr> +<a name="Inserting-Space"></a>Next: <a rel="next" accesskey="n" href="#Inserting-Accents">Inserting Accents</a>, +Previous: <a rel="previous" accesskey="p" href="#Atsign-Braces-Comma">Atsign Braces Comma</a>, +Up: <a rel="up" accesskey="u" href="#Insertions">Insertions</a> +<br> +</div> + +<h3 class="section">14.2 Inserting Space</h3> + +<p><a name="index-Inserting-space-633"></a><a name="index-Spacing_002c-inserting-634"></a>The following sections describe commands that control spacing of various +kinds within and after sentences. + +<ul class="menu"> +<li><a accesskey="1" href="#Not-Ending-a-Sentence">Not Ending a Sentence</a>: Sometimes a . doesn't end a sentence. +<li><a accesskey="2" href="#Ending-a-Sentence">Ending a Sentence</a>: Sometimes it does. +<li><a accesskey="3" href="#Multiple-Spaces">Multiple Spaces</a>: Inserting multiple spaces. +<li><a accesskey="4" href="#dmn">dmn</a>: How to format a dimension. +</ul> + +<div class="node"> +<p><hr> +<a name="Not-Ending-a-Sentence"></a>Next: <a rel="next" accesskey="n" href="#Ending-a-Sentence">Ending a Sentence</a>, +Up: <a rel="up" accesskey="u" href="#Inserting-Space">Inserting Space</a> +<br> +</div> + +<h4 class="subsection">14.2.1 Not Ending a Sentence</h4> + +<p><a name="index-Not-ending-a-sentence-635"></a><a name="index-Sentence-non_002dending-punctuation-636"></a><a name="index-Periods_002c-inserting-637"></a>Depending on whether a period or exclamation point or question mark is +inside or at the end of a sentence, less or more space is inserted after +a period in a typeset manual. Since it is not always possible +to determine when a period ends a sentence and when it is used +in an abbreviation, special commands are needed in some circumstances. +Usually, Texinfo can guess how to handle periods, so you do not need to +use the special commands; you just enter a period as you would if you +were using a typewriter, which means you put two spaces after the +period, question mark, or exclamation mark that ends a sentence. + + <p><a name="index-_003ccolon_003e-_0040r_007b_0028suppress-end_002dof_002dsentence-space_0029_007d-638"></a>Use the <code>@:</code> command after a period, question mark, +exclamation mark, or colon that should not be followed by extra space. +For example, use <code>@:</code> after periods that end abbreviations +which are not at the ends of sentences. + + <p>For example, + +<pre class="example"> The s.o.p.@: has three parts ... + The s.o.p. has three parts ... +</pre> + <p class="noindent">produces + + <blockquote> +The s.o.p. has three parts <small class="dots">...</small><br> +The s.o.p. has three parts <small class="dots">...</small> +</blockquote> + +<p class="noindent">(Incidentally, <span class="samp">s.o.p.</span> is an abbreviation for “Standard Operating +Procedure”.) + + <p><code>@:</code> has no effect on the Info and HTML output. In Docbook and +XML, the previous punctuation character (.?!:) is output as an entity +instead of as the normal character: <span class="samp">&period; &quest; &excl; +&colon;</span>. This gives further processors a chance to notice and not +add the usual extra space. + + <p>Do not put braces after <code>@:</code> (or any non-alphabetic command). + +<div class="node"> +<p><hr> +<a name="Ending-a-Sentence"></a>Next: <a rel="next" accesskey="n" href="#Multiple-Spaces">Multiple Spaces</a>, +Previous: <a rel="previous" accesskey="p" href="#Not-Ending-a-Sentence">Not Ending a Sentence</a>, +Up: <a rel="up" accesskey="u" href="#Inserting-Space">Inserting Space</a> +<br> +</div> + +<h4 class="subsection">14.2.2 Ending a Sentence</h4> + +<p><a name="index-Ending-a-Sentence-639"></a><a name="index-Sentence-ending-punctuation-640"></a> +<a name="index-_002e--_0040r_007b_0028end-of-sentence_0029_007d-641"></a><a name="index-_0021-_0040r_007b_0028end-of-sentence_0029_007d-642"></a><a name="index-_003f-_0040r_007b_0028end-of-sentence_0029_007d-643"></a>Use <code>@.</code> instead of a period, <code>@!</code> instead of an +exclamation point, and <code>@?</code> instead of a question mark at the end +of a sentence that ends with a capital letter. Otherwise, TeX +will think the letter is an abbreviation and will not insert the correct +end-of-sentence spacing. Here is an example: + +<pre class="example"> Give it to M.I.B. and to M.E.W@. Also, give it to R.J.C@. + Give it to M.I.B. and to M.E.W. Also, give it to R.J.C. +</pre> + <p class="noindent">produces + + <blockquote> +Give it to M.I.B. and to M.E.W. Also, give it to R.J.C.<br> +Give it to M.I.B. and to M.E.W. Also, give it to R.J.C. +</blockquote> + + <p>In the Info file output, <code>@.</code> is equivalent to a simple +<span class="samp">.</span>; likewise for <code>@!</code> and <code>@?</code>. + + <p>The meanings of <code>@:</code> and <code>@.</code> in Texinfo are designed to +work well with the Emacs sentence motion commands (see <a href="emacs.html#Sentences">Sentences (The GNU Emacs Manual)</a>). + + <p>Do not put braces after any of these commands. + +<div class="node"> +<p><hr> +<a name="Multiple-Spaces"></a>Next: <a rel="next" accesskey="n" href="#dmn">dmn</a>, +Previous: <a rel="previous" accesskey="p" href="#Ending-a-Sentence">Ending a Sentence</a>, +Up: <a rel="up" accesskey="u" href="#Inserting-Space">Inserting Space</a> +<br> +</div> + +<h4 class="subsection">14.2.3 Multiple Spaces</h4> + +<p><a name="index-Multiple-spaces-644"></a><a name="index-Whitespace_002c-inserting-645"></a><a name="index-Space_002c-inserting-horizontal-646"></a><a name="index-_003cspace_003e-647"></a><a name="index-_003ctab_003e-648"></a><a name="index-_003cnewline_003e-649"></a> +Ordinarily, TeX collapses multiple whitespace characters (space, tab, +and newline) into a single space. Info output, on the other hand, +preserves whitespace as you type it, except for changing a newline into +a space; this is why it is important to put two spaces at the end of +sentences in Texinfo documents. + + <p>Occasionally, you may want to actually insert several consecutive +spaces, either for purposes of example (what your program does with +multiple spaces as input), or merely for purposes of appearance in +headings or lists. Texinfo supports three commands: +<code>@</code><kbd>SPACE</kbd>, <code>@</code><kbd>TAB</kbd>, and <code>@</code><kbd>NL</kbd>, all of +which insert a single space into the output. (Here, +<code>@</code><kbd>SPACE</kbd> represents an <span class="samp">@</span> character followed by a +space, i.e., <span class="samp">@ </span>, and <kbd>TAB</kbd> and <kbd>NL</kbd> represent the tab +character and end-of-line, i.e., when <span class="samp">@</span> is the last character on +a line.) + + <p>For example, +<pre class="example"> Spacey@ @ @ @ + example. +</pre> + <p class="noindent">produces + +<pre class="example"> Spacey example. +</pre> + <p>Other possible uses of <code>@</code><kbd>SPACE</kbd> have been subsumed by +<code>@multitable</code> (see <a href="#Multi_002dcolumn-Tables">Multi-column Tables</a>). + + <p>Do not follow any of these commands with braces. + + <p>To produce a non-breakable space, see <a href="#tie"><code>@tie</code></a>. + +<div class="node"> +<p><hr> +<a name="dmn"></a>Previous: <a rel="previous" accesskey="p" href="#Multiple-Spaces">Multiple Spaces</a>, +Up: <a rel="up" accesskey="u" href="#Inserting-Space">Inserting Space</a> +<br> +</div> + +<h4 class="subsection">14.2.4 <code>@dmn</code>{<var>dimension</var>}: Format a Dimension</h4> + +<p><a name="index-Thin-space-between-number_002c-dimension-650"></a><a name="index-Dimension-formatting-651"></a><a name="index-Format-a-dimension-652"></a><a name="index-dmn-653"></a> +At times, you may want to write <span class="samp">12pt</span> or +<span class="samp">8.5in</span> with little or no space between the number and the +abbreviation for the dimension. You can use the <code>@dmn</code> command +to do this. On seeing the command, TeX inserts just enough space +for proper typesetting; the Info formatting commands insert no space +at all, since the Info file does not require it. + + <p>To use the <code>@dmn</code> command, write the number and then follow it +immediately, with no intervening space, by <code>@dmn</code>, and then by +the dimension within braces. For example, + +<pre class="example"> A4 paper is 8.27@dmn{in} wide. +</pre> + <p class="noindent">produces + + <blockquote> +A4 paper is 8.27<span class="dmn">in</span> wide. +</blockquote> + + <p>Not everyone uses this style. Some people prefer <span class="samp">8.27 in.@:</span><!-- /@w --> +or <span class="samp">8.27 inches</span><!-- /@w --> to <span class="samp">8.27@dmn{in}</span> in the Texinfo file. +In these cases, however, the formatters may insert a line break between +the number and the dimension, so use <code>@w</code> (see <a href="#w">w</a>). Also, if +you write a period after an abbreviation within a sentence, you should +write <span class="samp">@:</span> after the period to prevent TeX from inserting extra +whitespace, as shown here. See <a href="#Not-Ending-a-Sentence">Not Ending a Sentence</a>. + +<div class="node"> +<p><hr> +<a name="Inserting-Accents"></a>Next: <a rel="next" accesskey="n" href="#Dots-Bullets">Dots Bullets</a>, +Previous: <a rel="previous" accesskey="p" href="#Inserting-Space">Inserting Space</a>, +Up: <a rel="up" accesskey="u" href="#Insertions">Insertions</a> +<br> +</div> + +<h3 class="section">14.3 Inserting Accents</h3> + +<p><a name="index-Inserting-accents-654"></a><a name="index-Accents_002c-inserting-655"></a><a name="index-Floating-accents_002c-inserting-656"></a> +Here is a table with the commands Texinfo provides for inserting +floating accents. The commands with non-alphabetic names do not take +braces around their argument (which is taken to be the next character). +(Exception: <code>@,</code> <em>does</em> take braces around its argument.) +This is so as to make the source as convenient to type and read as +possible, since accented characters are very common in some languages. + + <p>To get the true accented characters output in Info, and not just the +ASCII transliterations, you can use the <span class="option">--enable-encoding</span> +option to <span class="command">makeinfo</span> (see <a href="#makeinfo-options">makeinfo options</a>). + + <p><a name="index-_0022-_0040r_007b_0028umlaut-accent_0029_007d-657"></a><a name="index-Umlaut-accent-658"></a><a name="index-_0027-_0040r_007b_0028umlaut-accent_0029_007d-659"></a><a name="index-Acute-accent-660"></a><a name="index-_003d-_0040r_007b_0028macron-accent_0029_007d-661"></a><a name="index-Macron-accent-662"></a><a name="index-_005e-_0040r_007b_0028circumflex-accent_0029_007d-663"></a><a name="index-Circumflex-accent-664"></a><a name="index-_0060-_0040r_007b_0028grave-accent_0029_007d-665"></a><a name="index-Grave-accent-666"></a><a name="index-_007e-_0040r_007b_0028tilde-accent_0029_007d-667"></a><a name="index-Tilde-accent-668"></a><a name="index-_002c-_0040r_007b_0028cedilla-accent_0029_007d-669"></a><a name="index-Cedilla-accent-670"></a><a name="index-dotaccent-671"></a><a name="index-Dot-accent-672"></a><a name="index-H-_0040r_007b_0028Hungarian-umlaut-accent_0029_007d-673"></a><a name="index-Hungarian-umlaut-accent-674"></a><a name="index-ringaccent-675"></a><a name="index-Ring-accent-676"></a><a name="index-tieaccent-677"></a><a name="index-Tie_002dafter-accent-678"></a><a name="index-u-_0040r_007b_0028breve-accent_0029_007d-679"></a><a name="index-Breve-accent-680"></a><a name="index-ubaraccent-681"></a><a name="index-Underbar-accent-682"></a><a name="index-udotaccent-683"></a><a name="index-Underdot-accent-684"></a><a name="index-v-_0040r_007b_0028check-accent_0029_007d-685"></a><a name="index-Hacek-accent-686"></a><a name="index-Check-accent-687"></a><a name="index-Caron-accent-688"></a> + <p><table summary=""><tr align="left"><td valign="top">Command </td><td valign="top">Output </td><td valign="top">What +<br></td></tr><tr align="left"><td valign="top"><tt>@"o</tt> </td><td valign="top">ö </td><td valign="top">umlaut accent +<br></td></tr><tr align="left"><td valign="top"><tt>@'o</tt> </td><td valign="top">ó </td><td valign="top">acute accent +<br></td></tr><tr align="left"><td valign="top"><tt>@,{c}</tt> </td><td valign="top">ç </td><td valign="top">cedilla accent +<br></td></tr><tr align="left"><td valign="top"><tt>@=o</tt> </td><td valign="top">o¯ </td><td valign="top">macron/overbar accent +<br></td></tr><tr align="left"><td valign="top"><tt>@^o</tt> </td><td valign="top">ô </td><td valign="top">circumflex accent +<br></td></tr><tr align="left"><td valign="top"><tt>@`o</tt> </td><td valign="top">ò </td><td valign="top">grave accent +<br></td></tr><tr align="left"><td valign="top"><tt>@~o</tt> </td><td valign="top">õ </td><td valign="top">tilde accent +<br></td></tr><tr align="left"><td valign="top"><tt>@dotaccent{o}</tt> </td><td valign="top">o. </td><td valign="top">overdot accent +<br></td></tr><tr align="left"><td valign="top"><tt>@H{o}</tt> </td><td valign="top">o'' </td><td valign="top">long Hungarian umlaut +<br></td></tr><tr align="left"><td valign="top"><tt>@ringaccent{o}</tt> </td><td valign="top">o* </td><td valign="top">ring accent +<br></td></tr><tr align="left"><td valign="top"><tt>@tieaccent{oo}</tt> </td><td valign="top">oo[ </td><td valign="top">tie-after accent +<br></td></tr><tr align="left"><td valign="top"><tt>@u{o}</tt> </td><td valign="top">o( </td><td valign="top">breve accent +<br></td></tr><tr align="left"><td valign="top"><tt>@ubaraccent{o}</tt> </td><td valign="top">o_ </td><td valign="top">underbar accent +<br></td></tr><tr align="left"><td valign="top"><tt>@udotaccent{o}</tt> </td><td valign="top">.o </td><td valign="top">underdot accent +<br></td></tr><tr align="left"><td valign="top"><tt>@v{o}</tt> </td><td valign="top">o< </td><td valign="top">hacek/check/caron accent + <br></td></tr></table> + + <p>This table lists the Texinfo commands for inserting other characters +commonly used in languages other than English. + + <p><a name="index-questiondown-689"></a><a name="index-_0040questiondown_007b_007d-690"></a><a name="index-exclamdown-691"></a><a name="index-_0040exclamdown_007b_007d-692"></a><a name="index-aa-693"></a><a name="index-_0040aa_007b_007d-694"></a><a name="index-AA-695"></a><a name="index-_0040AA_007b_007d-696"></a><a name="index-ae-697"></a><a name="index-_0040ae_007b_007d-698"></a><a name="index-AE-699"></a><a name="index-_0040AE_007b_007d-700"></a><a name="index-dotless-701"></a><a name="index-_0040dotless_007bi_007d-_0028dotless-i_0029-702"></a><a name="index-_0040dotless_007bj_007d-_0028dotless-j_0029-703"></a><a name="index-Dotless-i_002c-j-704"></a><a name="index-l-705"></a><a name="index-_0040l_007b_007d-706"></a><a name="index-L-707"></a><a name="index-_0040L_007b_007d-708"></a><a name="index-o-709"></a><a name="index-_0040o_007b_007d-710"></a><a name="index-O-711"></a><a name="index-_0040O_007b_007d-712"></a><a name="index-oe-713"></a><a name="index-_0040oe_007b_007d-714"></a><a name="index-OE-715"></a><a name="index-_0040OE_007b_007d-716"></a><a name="index-Romance-ordinals-717"></a><a name="index-Ordinals_002c-Romance-718"></a><a name="index-Feminine-ordinal-719"></a><a name="index-ordf-720"></a><a name="index-_0040ordf_007b_007d-721"></a><a name="index-Masculine-ordinal-722"></a><a name="index-ordm-723"></a><a name="index-_0040ordm_007b_007d-724"></a><a name="index-ss-725"></a><a name="index-_0040ss_007b_007d-726"></a><a name="index-Es_002dzet-727"></a><a name="index-Sharp-S-728"></a><a name="index-German-S-729"></a> + <p><table summary=""><tr align="left"><td valign="top"><tt>@exclamdown{}</tt> </td><td valign="top">¡ </td><td valign="top">upside-down ! +<br></td></tr><tr align="left"><td valign="top"><tt>@questiondown{}</tt> </td><td valign="top">¿ </td><td valign="top">upside-down ? +<br></td></tr><tr align="left"><td valign="top"><tt>@aa{} @AA{}</tt> </td><td valign="top">å Å </td><td valign="top">a,A with circle +<br></td></tr><tr align="left"><td valign="top"><tt>@ae{} @AE{}</tt> </td><td valign="top">æ Æ </td><td valign="top">ae,AE ligatures +<br></td></tr><tr align="left"><td valign="top"><tt>@dotless{i}</tt> </td><td valign="top">i </td><td valign="top">dotless i +<br></td></tr><tr align="left"><td valign="top"><tt>@dotless{j}</tt> </td><td valign="top">j </td><td valign="top">dotless j +<br></td></tr><tr align="left"><td valign="top"><tt>@l{} @L{}</tt> </td><td valign="top">/l /L </td><td valign="top">suppressed-L,l +<br></td></tr><tr align="left"><td valign="top"><tt>@o{} @O{}</tt> </td><td valign="top">ø Ø </td><td valign="top">O,o with slash +<br></td></tr><tr align="left"><td valign="top"><tt>@oe{} @OE{}</tt> </td><td valign="top">œ Œ </td><td valign="top">oe,OE ligatures +<br></td></tr><tr align="left"><td valign="top"><tt>@ordf{} @ordm{}</tt> </td><td valign="top">ª º </td><td valign="top">Spanish ordinals +<br></td></tr><tr align="left"><td valign="top"><tt>@ss{}</tt> </td><td valign="top">ß </td><td valign="top">es-zet or sharp S + <br></td></tr></table> + +<div class="node"> +<p><hr> +<a name="Dots-Bullets"></a>Next: <a rel="next" accesskey="n" href="#TeX-and-copyright">TeX and copyright</a>, +Previous: <a rel="previous" accesskey="p" href="#Inserting-Accents">Inserting Accents</a>, +Up: <a rel="up" accesskey="u" href="#Insertions">Insertions</a> +<br> +</div> + +<h3 class="section">14.4 Inserting Ellipsis and Bullets</h3> + +<p><a name="index-Dots_002c-inserting-730"></a><a name="index-Bullets_002c-inserting-731"></a><a name="index-Ellipsis_002c-inserting-732"></a><a name="index-Inserting-ellipsis-733"></a><a name="index-Inserting-dots-734"></a><a name="index-Special-typesetting-commands-735"></a><a name="index-Typesetting-commands-for-dots_002c-etc_002e-736"></a> +An <dfn>ellipsis</dfn> (a line of dots) is not typeset as a string of +periods, so a special command is used for ellipsis in Texinfo. The +<code>@bullet</code> command is special, too. Each of these commands is +followed by a pair of braces, <span class="samp">{}</span>, without any whitespace +between the name of the command and the braces. (You need to use braces +with these commands because you can use them next to other text; without +the braces, the formatters would be confused. See <a href="#Command-Syntax">@-Command Syntax</a>, for further information.) + +<ul class="menu"> +<li><a accesskey="1" href="#dots">dots</a>: How to insert dots ... +<li><a accesskey="2" href="#bullet">bullet</a>: How to insert a bullet. +</ul> + +<div class="node"> +<p><hr> +<a name="dots"></a>Next: <a rel="next" accesskey="n" href="#bullet">bullet</a>, +Up: <a rel="up" accesskey="u" href="#Dots-Bullets">Dots Bullets</a> +<br> +</div> + +<h4 class="subsection">14.4.1 <code>@dots</code>{} (<small class="dots">...</small>) and <code>@enddots</code>{} (<small class="enddots">....</small>)</h4> + +<p><a name="index-dots-737"></a><a name="index-enddots-738"></a><a name="index-Inserting-dots-739"></a><a name="index-Dots_002c-inserting-740"></a> +Use the <code>@dots{}</code> command to generate an ellipsis, which is +three dots in a row, appropriately spaced <small class="dots">...</small> like so. Do +not simply write three periods in the input file; that would work for +the Info file output, but would produce the wrong amount of space +between the periods in the printed manual. + + <p>Similarly, the <code>@enddots{}</code> command generates an +end-of-sentence ellipsis, which has different spacing afterwards, +<small class="enddots">....</small> Look closely to see the difference. + +<div class="node"> +<p><hr> +<a name="bullet"></a>Previous: <a rel="previous" accesskey="p" href="#dots">dots</a>, +Up: <a rel="up" accesskey="u" href="#Dots-Bullets">Dots Bullets</a> +<br> +</div> + +<h4 class="subsection">14.4.2 <code>@bullet</code>{} (•)</h4> + +<p><a name="index-bullet-741"></a> +Use the <code>@bullet{}</code> command to generate a large round dot, or +the closest possible thing to one. In Info, an asterisk is used. + + <p>Here is a bullet: • + + <p>When you use <code>@bullet</code> in <code>@itemize</code>, you do not need to +type the braces, because <code>@itemize</code> supplies them. +(See <a href="#itemize"><code>@itemize</code></a>.) + +<div class="node"> +<p><hr> +<a name="TeX-and-copyright"></a>Next: <a rel="next" accesskey="n" href="#pounds">pounds</a>, +Previous: <a rel="previous" accesskey="p" href="#Dots-Bullets">Dots Bullets</a>, +Up: <a rel="up" accesskey="u" href="#Insertions">Insertions</a> +<br> +</div> + +<h3 class="section">14.5 Inserting TeX and Legal Symbols: ©, ®</h3> + +<p>The logo `TeX' is typeset in a special fashion and it needs an +@-command. The copyright and registered symbols, `©' and +`®', is also special. Each of these commands is +followed by a pair of braces, <span class="samp">{}</span>, without any whitespace +between the name of the command and the braces. + +<ul class="menu"> +<li><a accesskey="1" href="#tex">tex</a>: The TeX logos. +<li><a accesskey="2" href="#copyright-symbol">copyright symbol</a>: The copyright symbol (c in a circle). +<li><a accesskey="3" href="#registered-symbol">registered symbol</a>: The registered symbol (R in a circle). +</ul> + +<div class="node"> +<p><hr> +<a name="tex"></a>Next: <a rel="next" accesskey="n" href="#copyright-symbol">copyright symbol</a>, +Up: <a rel="up" accesskey="u" href="#TeX-and-copyright">TeX and copyright</a> +<br> +</div> + +<h4 class="subsection">14.5.1 <code>@TeX</code>{} (TeX) and <code>@LaTeX</code>{} (LaTeX)</h4> + +<p><a name="index-TeX-742"></a><a name="index-LaTeX-743"></a> +Use the <code>@TeX{}</code> command to generate `TeX'. In a printed +manual, this is a special logo that is different from three ordinary +letters. In Info, it just looks like <span class="samp">TeX</span>. + + <p>Similarly, use the <code>@LaTeX{}</code> command to generate `LaTeX', +which is even more special in printed manuals (and different from the +incorrect <code>La@TeX{}</code>. In Info, the result is just +<span class="samp">LaTeX</span>. (LaTeX is another macro package built on top of +TeX, very loosely analogous to Texinfo in that it emphasizes +logical structure, but much (much) larger.) + + <p>The spelling of these commands are unusual among Texinfo commands in +that they use both uppercase and lowercase letters. + +<div class="node"> +<p><hr> +<a name="copyright-symbol"></a>Next: <a rel="next" accesskey="n" href="#registered-symbol">registered symbol</a>, +Previous: <a rel="previous" accesskey="p" href="#tex">tex</a>, +Up: <a rel="up" accesskey="u" href="#TeX-and-copyright">TeX and copyright</a> +<br> +</div> + +<h4 class="subsection">14.5.2 <code>@copyright{}</code> (©)</h4> + +<p><a name="index-copyright-744"></a> +Use the <code>@copyright{}</code> command to generate the copyright +symbol, `©'. Where possible, this is a <span class="samp">c</span> +inside a circle; in Info, this is <span class="samp">(C)</span>. + +<div class="node"> +<p><hr> +<a name="registered-symbol"></a>Previous: <a rel="previous" accesskey="p" href="#copyright-symbol">copyright symbol</a>, +Up: <a rel="up" accesskey="u" href="#TeX-and-copyright">TeX and copyright</a> +<br> +</div> + +<h4 class="subsection">14.5.3 <code>@registeredsymbol{}</code> (®)</h4> + +<p><a name="index-registeredsymbol-745"></a> +Use the <code>@registeredsymbol{}</code> command to generate the +registered symbol, `®'. Where possible, this is an +<span class="samp">R</span> inside a circle; in Info, this is <span class="samp">(R)</span>. + +<div class="node"> +<p><hr> +<a name="pounds"></a>Next: <a rel="next" accesskey="n" href="#minus">minus</a>, +Previous: <a rel="previous" accesskey="p" href="#TeX-and-copyright">TeX and copyright</a>, +Up: <a rel="up" accesskey="u" href="#Insertions">Insertions</a> +<br> +</div> + +<h3 class="section">14.6 <code>@pounds</code>{} (£): Pounds Sterling</h3> + +<p><a name="index-pounds-746"></a> +Use the <code>@pounds{}</code> command to generate `£'. In a +printed manual, this is the symbol for the currency pounds sterling. +In Info, it is a <span class="samp">#</span>. Other currency symbols are unfortunately not +available. + +<div class="node"> +<p><hr> +<a name="minus"></a>Next: <a rel="next" accesskey="n" href="#math">math</a>, +Previous: <a rel="previous" accesskey="p" href="#pounds">pounds</a>, +Up: <a rel="up" accesskey="u" href="#Insertions">Insertions</a> +<br> +</div> + +<h3 class="section">14.7 <code>@minus</code>{} (−): Inserting a Minus Sign</h3> + +<p><a name="index-minus-747"></a> +<a name="index-Em-dash_002c-compared-to-minus-sign-748"></a><a name="index-Hyphen_002c-compared-to-minus-749"></a>Use the <code>@minus{}</code> command to generate a minus sign. In a +fixed-width font, this is a single hyphen, but in a proportional font, +the symbol is the customary length for a minus sign—a little longer +than a hyphen, shorter than an em-dash: + +<pre class="display"> <span class="samp">−</span> is a minus sign generated with <span class="samp">@minus{}</span>, + + `-' is a hyphen generated with the character <span class="samp">-</span>, + + `—' is an em-dash for text. +</pre> + <p class="noindent">In the fixed-width font used by Info, <code>@minus{}</code> is the same +as a hyphen. + + <p>You should not use <code>@minus{}</code> inside <code>@code</code> or +<code>@example</code> because the width distinction is not made in the +fixed-width font they use. + + <p>When you use <code>@minus</code> to specify the mark beginning each entry in +an itemized list, you do not need to type the braces +(see <a href="#itemize"><code>@itemize</code></a>). + +<div class="node"> +<p><hr> +<a name="math"></a>Next: <a rel="next" accesskey="n" href="#Glyphs">Glyphs</a>, +Previous: <a rel="previous" accesskey="p" href="#minus">minus</a>, +Up: <a rel="up" accesskey="u" href="#Insertions">Insertions</a> +<br> +</div> + +<h3 class="section">14.8 <code>@math</code>: Inserting Mathematical Expressions</h3> + +<p><a name="index-math-750"></a><a name="index-Mathematical-expressions-751"></a><a name="index-Formulas_002c-mathematical-752"></a> +You can write a short mathematical expression with the <code>@math</code> +command. Write the mathematical expression between braces, like this: + +<pre class="example"> @math{(a + b)(a + b) = a^2 + 2ab + b^2} +</pre> + <p class="noindent">This produces the following in Info and HTML: + +<pre class="example"> (a + b)(a + b) = a^2 + 2ab + b^2 +</pre> + <p>Thus, the <code>@math</code> command has no effect on the Info and HTML +output; <span class="command">makeinfo</span> just reproduces the input, it does not try +to interpret the mathematics in any way. + + <p><code>@math</code> implies <code>@tex</code>. This not only makes it possible to +write superscripts and subscripts (as in the above example), but also +allows you to use any of the plain TeX math control sequences. It's +conventional to use <span class="samp">\</span> instead of <span class="samp">@</span> for these commands. +As in: +<pre class="example"> @math{\sin 2\pi \equiv \cos 3\pi} +</pre> + <p class="noindent">which looks like the input in Info and HTML: +<pre class="example"> \sin 2\pi \equiv \cos 3\pi +</pre> + <p><a name="index-_005c-_0040r_007b_0028literal-_005c-in-_0040code_007b_0040_0040math_007d_0029_007d-753"></a>Since <span class="samp">\</span> is an escape character inside <code>@math</code>, you can use +<code>@\</code> to get a literal backslash (<code>\\</code> will work in TeX, +but you'll get the literal <span class="samp">\\</span> in Info). <code>@\</code> is not +defined outside of <code>@math</code>, since a <span class="samp">\</span> ordinarily produces a +literal <span class="samp">\</span>. + + <p><a name="index-Displayed-equations-754"></a><a name="index-Equations_002c-displayed-755"></a>For displayed equations, you must at present use TeX directly +(see <a href="#Raw-Formatter-Commands">Raw Formatter Commands</a>). + +<div class="node"> +<p><hr> +<a name="Glyphs"></a>Previous: <a rel="previous" accesskey="p" href="#math">math</a>, +Up: <a rel="up" accesskey="u" href="#Insertions">Insertions</a> +<br> +</div> + +<h3 class="section">14.9 Glyphs for Examples</h3> + +<p><a name="index-Glyphs-756"></a><a name="index-Examples_002c-glyphs-for-757"></a> +In Texinfo, code is often illustrated in examples that are delimited +by <code>@example</code> and <code>@end example</code>, or by <code>@lisp</code> and +<code>@end lisp</code>. In such examples, you can indicate the results of +evaluation or an expansion using <span class="samp">=></span> or +<span class="samp">==></span>. Likewise, there are commands to insert glyphs +to indicate +printed output, error messages, equivalence of expressions, and the +location of point. + + <p>The glyph-insertion commands do not need to be used within an example, but +most often they are. Every glyph-insertion command is followed by a pair of +left- and right-hand braces. + +<ul class="menu"> +<li><a accesskey="1" href="#Glyphs-Summary">Glyphs Summary</a> +<li><a accesskey="2" href="#result">result</a>: How to show the result of expression. +<li><a accesskey="3" href="#expansion">expansion</a>: How to indicate an expansion. +<li><a accesskey="4" href="#Print-Glyph">Print Glyph</a>: How to indicate printed output. +<li><a accesskey="5" href="#Error-Glyph">Error Glyph</a>: How to indicate an error message. +<li><a accesskey="6" href="#Equivalence">Equivalence</a>: How to indicate equivalence. +<li><a accesskey="7" href="#Point-Glyph">Point Glyph</a>: How to indicate the location of point. +</ul> + +<div class="node"> +<p><hr> +<a name="Glyphs-Summary"></a>Next: <a rel="next" accesskey="n" href="#result">result</a>, +Up: <a rel="up" accesskey="u" href="#Glyphs">Glyphs</a> +<br> +</div> + +<h4 class="subsection">14.9.1 Glyphs Summary</h4> + +<p>Here are the different glyph commands: + + <dl> +<dt>=><dd><code>@result{}</code> points to the result of an expression. + + <br><dt>==><dd><code>@expansion{}</code> shows the results of a macro expansion. + + <br><dt>-|<dd><code>@print{}</code> indicates printed output. + + <br><dt>error--><dd><code>@error{}</code> indicates that the following text is an error +message. + + <br><dt>==<dd><code>@equiv{}</code> indicates the exact equivalence of two forms. + + <br><dt>-!-<dd><code>@point{}</code> shows the location of point. +</dl> + +<ul class="menu"> +<li><a accesskey="1" href="#result">result</a> +<li><a accesskey="2" href="#expansion">expansion</a> +<li><a accesskey="3" href="#Print-Glyph">Print Glyph</a> +<li><a accesskey="4" href="#Error-Glyph">Error Glyph</a> +<li><a accesskey="5" href="#Equivalence">Equivalence</a> +<li><a accesskey="6" href="#Point-Glyph">Point Glyph</a> +</ul> + +<div class="node"> +<p><hr> +<a name="result"></a>Next: <a rel="next" accesskey="n" href="#expansion">expansion</a>, +Previous: <a rel="previous" accesskey="p" href="#Glyphs-Summary">Glyphs Summary</a>, +Up: <a rel="up" accesskey="u" href="#Glyphs">Glyphs</a> +<br> +</div> + +<h4 class="subsection">14.9.2 <code>@result{}</code> (=>): Indicating Evaluation</h4> + +<p><a name="index-Result-of-an-expression-758"></a><a name="index-Indicating-evaluation-759"></a><a name="index-Evaluation-glyph-760"></a><a name="index-Value-of-an-expression_002c-indicating-761"></a><a name="index-result-762"></a> +Use the <code>@result{}</code> command to indicate the result of +evaluating an expression. + + <p>The <code>@result{}</code> command is displayed as <span class="samp">=></span> in +Info and HTML and as a true double stemmed arrow in the printed output. + + <p>Thus, the following, + +<pre class="lisp"> (cdr '(1 2 3)) + => (2 3) +</pre> + <p class="noindent">may be read as “<code>(cdr '(1 2 3))</code> evaluates to <code>(2 3)</code>”. + +<div class="node"> +<p><hr> +<a name="expansion"></a>Next: <a rel="next" accesskey="n" href="#Print-Glyph">Print Glyph</a>, +Previous: <a rel="previous" accesskey="p" href="#result">result</a>, +Up: <a rel="up" accesskey="u" href="#Glyphs">Glyphs</a> +<br> +</div> + +<h4 class="subsection">14.9.3 <code>@expansion{}</code> (==>): Indicating an Expansion</h4> + +<p><a name="index-Expansion_002c-indicating-763"></a><a name="index-Macro-expansion_002c-indicating-764"></a><a name="index-expansion-765"></a> +When an expression is a macro call, it expands into a new expression. +You can indicate the result of the expansion with the +<code>@expansion{}</code> command. + + <p>The <code>@expansion{}</code> command is displayed as <span class="samp">==></span> +in Info and HTML, and as a long arrow with a flat base in the printed +output. + + <p>For example, the following + +<pre class="example"> @lisp + (third '(a b c)) + @expansion{} (car (cdr (cdr '(a b c)))) + @result{} c + @end lisp +</pre> + <p class="noindent">produces + +<pre class="lisp"> (third '(a b c)) + ==> (car (cdr (cdr '(a b c)))) + => c +</pre> + <p class="noindent">which may be read as: + + <blockquote> +<code>(third '(a b c))</code> expands to <code>(car (cdr (cdr '(a b c))))</code>; +the result of evaluating the expression is <code>c</code>. +</blockquote> + +<p class="noindent">Often, as in this case, an example looks better if the +<code>@expansion{}</code> and <code>@result{}</code> commands are indented. + +<div class="node"> +<p><hr> +<a name="Print-Glyph"></a>Next: <a rel="next" accesskey="n" href="#Error-Glyph">Error Glyph</a>, +Previous: <a rel="previous" accesskey="p" href="#expansion">expansion</a>, +Up: <a rel="up" accesskey="u" href="#Glyphs">Glyphs</a> +<br> +</div> + +<h4 class="subsection">14.9.4 <code>@print{}</code> (-|): Indicating Printed Output</h4> + +<p><a name="index-Printed-output_002c-indicating-766"></a><a name="index-print-767"></a> +Sometimes an expression will print output during its execution. You +can indicate the printed output with the <code>@print{}</code> command. + + <p>The <code>@print{}</code> command is displayed as <span class="samp">-|</span> in Info +and HTML and (similarly) as a horizontal dash butting against a +vertical bar in the printed output. + + <p>In the following example, the printed text is indicated with +<span class="samp">-|</span>, and the value of the expression follows on the +last line. + +<pre class="lisp"> (progn (print 'foo) (print 'bar)) + -| foo + -| bar + => bar +</pre> + <p class="noindent">In a Texinfo source file, this example is written as follows: + +<pre class="lisp"> @lisp + (progn (print 'foo) (print 'bar)) + @print{} foo + @print{} bar + @result{} bar + @end lisp +</pre> + <div class="node"> +<p><hr> +<a name="Error-Glyph"></a>Next: <a rel="next" accesskey="n" href="#Equivalence">Equivalence</a>, +Previous: <a rel="previous" accesskey="p" href="#Print-Glyph">Print Glyph</a>, +Up: <a rel="up" accesskey="u" href="#Glyphs">Glyphs</a> +<br> +</div> + +<h4 class="subsection">14.9.5 <code>@error{}</code> (error-->): Indicating an Error Message</h4> + +<p><a name="index-Error-message_002c-indicating-768"></a><a name="index-error-769"></a> +A piece of code may cause an error when you evaluate it. You can +designate the error message with the <code>@error{}</code> command. + + <p>The <code>@error{}</code> command is displayed as <span class="samp">error--></span> in Info +and HTML and as the word `error' in a box in the printed output. + + <p>Thus, + +<pre class="example"> @lisp + (+ 23 'x) + @error{} Wrong type argument: integer-or-marker-p, x + @end lisp +</pre> + <p class="noindent">produces + +<pre class="lisp"> (+ 23 'x) + error--> Wrong type argument: integer-or-marker-p, x +</pre> + <p class="noindent">This indicates that the following error message is printed +when you evaluate the expression: + +<pre class="lisp"> Wrong type argument: integer-or-marker-p, x +</pre> + <p><span class="samp">error--></span> itself is not part of the error message. + +<div class="node"> +<p><hr> +<a name="Equivalence"></a>Next: <a rel="next" accesskey="n" href="#Point-Glyph">Point Glyph</a>, +Previous: <a rel="previous" accesskey="p" href="#Error-Glyph">Error Glyph</a>, +Up: <a rel="up" accesskey="u" href="#Glyphs">Glyphs</a> +<br> +</div> + +<h4 class="subsection">14.9.6 <code>@equiv{}</code> (==): Indicating Equivalence</h4> + +<p><a name="index-Equivalence_002c-indicating-770"></a><a name="index-equiv-771"></a> +Sometimes two expressions produce identical results. You can indicate the +exact equivalence of two forms with the <code>@equiv{}</code> command. + + <p>The <code>@equiv{}</code> command is displayed as <span class="samp">==</span> in Info +and HTML and as a standard mathematical equivalence sign (three +parallel horizontal lines) in the printed output. + + <p>Thus, + +<pre class="example"> @lisp + (make-sparse-keymap) @equiv{} (list 'keymap) + @end lisp +</pre> + <p class="noindent">produces + +<pre class="lisp"> (make-sparse-keymap) == (list 'keymap) +</pre> + <p class="noindent">This indicates that evaluating <code>(make-sparse-keymap)</code> produces +identical results to evaluating <code>(list 'keymap)</code>. + +<div class="node"> +<p><hr> +<a name="Point-Glyph"></a>Previous: <a rel="previous" accesskey="p" href="#Equivalence">Equivalence</a>, +Up: <a rel="up" accesskey="u" href="#Glyphs">Glyphs</a> +<br> +</div> + +<h4 class="subsection">14.9.7 <code>@point{}</code> (-!-): Indicating Point in a Buffer</h4> + +<p><a name="index-Point_002c-indicating-in-a-buffer-772"></a><a name="index-point-773"></a> +Sometimes you need to show an example of text in an Emacs buffer. In +such examples, the convention is to include the entire contents of the +buffer in question between two lines of dashes containing the buffer +name. + + <p>You can use the <span class="samp">@point{}</span> command to show the location of point +in the text in the buffer. (The symbol for point, of course, is not +part of the text in the buffer; it indicates the place <em>between</em> +two characters where point is located.) + + <p>The <code>@point{}</code> command is displayed as <span class="samp">-!-</span> in Info +and HTML and as a small five pointed star in the printed +output. + + <p>The following example shows the contents of buffer <span class="file">foo</span> before +and after evaluating a Lisp command to insert the word <code>changed</code>. + +<pre class="example"> ---------- Buffer: foo ---------- + This is the -!-contents of foo. + ---------- Buffer: foo ---------- +</pre> + <pre class="example"> (insert "changed ") + => nil + ---------- Buffer: foo ---------- + This is the changed -!-contents of foo. + ---------- Buffer: foo ---------- +</pre> + <p>In a Texinfo source file, the example is written like this: + +<pre class="example"> @example + ---------- Buffer: foo ---------- + This is the @point{}contents of foo. + ---------- Buffer: foo ---------- + + (insert "changed ") + @result{} nil + ---------- Buffer: foo ---------- + This is the changed @point{}contents of foo. + ---------- Buffer: foo ---------- + @end example +</pre> + <div class="node"> +<p><hr> +<a name="Breaks"></a>Next: <a rel="next" accesskey="n" href="#Definition-Commands">Definition Commands</a>, +Previous: <a rel="previous" accesskey="p" href="#Insertions">Insertions</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> +<br> +</div> + +<h2 class="chapter">15 Forcing and Preventing Breaks</h2> + +<p><a name="index-Forcing-line-and-page-breaks-774"></a><a name="index-Making-line-and-page-breaks-775"></a><a name="index-Preventing-line-and-page-breaks-776"></a> +<a name="index-Line-breaks-777"></a>Usually, a Texinfo file is processed both by TeX and by one of the +Info formatting commands. Line, paragraph, or page breaks sometimes +occur in the `wrong' place in one or other form of output. You must +ensure that text looks right both in the printed manual and in the +Info file. + + <p><a name="index-White-space_002c-excessive-778"></a><a name="index-Page-breaks-779"></a>For example, in a printed manual, page breaks may occur awkwardly in +the middle of an example; to prevent this, you can hold text together +using a grouping command that keeps the text from being split across +two pages. Conversely, you may want to force a page break where none +would occur normally. Fortunately, problems like these do not often +arise. When they do, use the break, break prevention, or pagination +commands. + +<ul class="menu"> +<li><a accesskey="1" href="#Break-Commands">Break Commands</a>: Summary of break-related commands. +<li><a accesskey="2" href="#Line-Breaks">Line Breaks</a>: Forcing line breaks. +<li><a accesskey="3" href="#_002d-and-hyphenation">- and hyphenation</a>: Helping TeX with hyphenation points. +<li><a accesskey="4" href="#w">w</a>: Preventing unwanted line breaks in text. +<li><a accesskey="5" href="#tie">tie</a>: Inserting an unbreakable but varying space. +<li><a accesskey="6" href="#sp">sp</a>: Inserting blank lines. +<li><a accesskey="7" href="#page">page</a>: Forcing the start of a new page. +<li><a accesskey="8" href="#group">group</a>: Preventing unwanted page breaks. +<li><a accesskey="9" href="#need">need</a>: Another way to prevent unwanted page breaks. +</ul> + +<div class="node"> +<p><hr> +<a name="Break-Commands"></a>Next: <a rel="next" accesskey="n" href="#Line-Breaks">Line Breaks</a>, +Up: <a rel="up" accesskey="u" href="#Breaks">Breaks</a> +<br> +</div> + +<h3 class="section">15.1 Break Commands</h3> + +<p>The break commands create or allow line and paragraph breaks: + + <dl> +<dt><code>@*</code><dd>Force a line break. + + <br><dt><code>@sp </code><var>n</var><dd>Skip <var>n</var> blank lines. + + <br><dt><code>@-</code><dd>Insert a discretionary hyphen. + + <br><dt><code>@hyphenation{</code><var>hy-phen-a-ted words</var><code>}</code><dd>Define hyphen points in <var>hy-phen-a-ted words</var>. +</dl> + + <p>These commands hold text together on a single line: + + <dl> +<dt><code>@w{</code><var>text</var><code>}</code><dd>Prevent <var>text</var> from being split and hyphenated across two lines. +<br><dt><code>@tie{}</code><dd>Insert a normal interword space at which a line break may not occur. +</dl> + + <p>The pagination commands apply only to printed output, since Info +files do not have pages. + + <dl> +<dt><code>@page</code><dd>Start a new page in the printed manual. + + <br><dt><code>@group</code><dd>Hold text together that must appear on one printed page. + + <br><dt><code>@need </code><var>mils</var><dd>Start a new printed page if not enough space on this one. +</dl> + +<div class="node"> +<p><hr> +<a name="Line-Breaks"></a>Next: <a rel="next" accesskey="n" href="#_002d-and-hyphenation">- and hyphenation</a>, +Previous: <a rel="previous" accesskey="p" href="#Break-Commands">Break Commands</a>, +Up: <a rel="up" accesskey="u" href="#Breaks">Breaks</a> +<br> +</div> + +<h3 class="section">15.2 <code>@*</code> and <code>@/</code>: Generate and Allow Line Breaks</h3> + +<p><a name="index-_002a-_0040r_007b_0028force-line-break_0029_007d-780"></a><a name="index-_002f-_0040r_007b_0028allow-line-break_0029_007d-781"></a><a name="index-Line-breaks-782"></a><a name="index-Breaks-in-a-line-783"></a><a name="index-Force-line-break-784"></a><a name="index-Allow-line-break-785"></a> +The <code>@*</code> command forces a line break in both the printed manual and +in Info. The <code>@/</code> command allows a line break (printed manual only). + + <p>Here is an example with <code>@*</code>: + +<pre class="example"> This line @* is broken @*in two places. +</pre> + <p class="noindent">produces + +<pre class="example"> This line + is broken + in two places. +</pre> + <p>The <code>@/</code> command can be useful within a url +(see <a href="#uref"><code>@uref</code></a>), which tend to be long and are otherwise +unbreakable. For example: + +<pre class="example"> The official Texinfo home page is on the GNU web site: + @uref{http://www.gnu.org/@/software/@/gnu/@/texinfo}. +</pre> + <p class="noindent">produces + +<pre class="display"> The official Texinfo home page is on the GNU web site: + <a href="http://www.gnu.org/software/gnu/texinfo">http://www.gnu.org/software/gnu/texinfo</a>. +</pre> + <p class="noindent">Without the <code>@/</code> commands, TeX would have nowhere to +break the line. <code>@/</code> has no effect in the online output. + +<div class="node"> +<p><hr> +<a name="_002d-and-hyphenation"></a>Next: <a rel="next" accesskey="n" href="#w">w</a>, +Previous: <a rel="previous" accesskey="p" href="#Line-Breaks">Line Breaks</a>, +Up: <a rel="up" accesskey="u" href="#Breaks">Breaks</a> +<br> +</div> + +<h3 class="section">15.3 <code>@-</code> and <code>@hyphenation</code>: Helping TeX Hyphenate</h3> + +<p><a name="index-_002d-_0040r_007b_0028discretionary-hyphen_0029_007d-786"></a><a name="index-hyphenation-787"></a><a name="index-Hyphenation_002c-helping-_0040TeX_007b_007d-do-788"></a><a name="index-Fine_002dtuning_002c-and-hyphenation-789"></a> +Although TeX's hyphenation algorithm is generally pretty good, it +does miss useful hyphenation points from time to time. (Or, far more +rarely, insert an incorrect hyphenation.) So, for documents with an +unusual vocabulary or when fine-tuning for a printed edition, you may +wish to help TeX out. Texinfo supports two commands for this: + + <dl> +<dt><code>@-</code><dd>Insert a discretionary hyphen, i.e., a place where TeX can (but does +not have to) hyphenate. This is especially useful when you notice an +overfull hbox is due to TeX missing a hyphenation (see <a href="#Overfull-hboxes">Overfull hboxes</a>). TeX will not insert any hyphenation points itself into a +word containing <code>@-</code>. + + <br><dt><code>@hyphenation{</code><var>hy-phen-a-ted words</var><code>}</code><dd>Tell TeX how to hyphenate <var>hy-phen-a-ted words</var>. As shown, you +put a <span class="samp">-</span> at each hyphenation point. For example: + <pre class="example"> @hyphenation{man-u-script man-u-scripts} + </pre> + <p class="noindent">TeX only uses the specified hyphenation points when the +words match exactly, so give all necessary variants. +</dl> + + <p>Info output is not hyphenated, so these commands have no effect there. + +<div class="node"> +<p><hr> +<a name="w"></a>Next: <a rel="next" accesskey="n" href="#tie">tie</a>, +Previous: <a rel="previous" accesskey="p" href="#_002d-and-hyphenation">- and hyphenation</a>, +Up: <a rel="up" accesskey="u" href="#Breaks">Breaks</a> +<br> +</div> + +<h3 class="section">15.4 <code>@w</code>{<var>text</var>}: Prevent Line Breaks</h3> + +<p><a name="index-w-_0040r_007b_0028prevent-line-break_0029_007d-790"></a><a name="index-Line-breaks_002c-preventing-791"></a> +<code>@w{</code><var>text</var><code>}</code> outputs <var>text</var> and prohibits line breaks +within <var>text</var>, for both TeX and <span class="command">makeinfo</span>. + + <p><a name="index-Non_002dbreakable-space_002c-fixed-792"></a><a name="index-Unbreakable-space_002c-fixed-793"></a>Thus, you can use <code>@w</code> to produce a non-breakable space, fixed at +the width of a normal interword space: + +<pre class="example"> @w{ } @w{ } @w{ } indentation. +</pre> + <p class="noindent">produces: + +<pre class="display"> <!-- /@w --> <!-- /@w --> <!-- /@w --> indentation. +</pre> + <p>The space from <code>@w{ <!-- /@w -->}</code>, as well as being non-breakable, +also will not stretch or shrink. Sometimes that is what you want, for +instance if you're doing indenting manual. However, usually you want +a normal interword space that does stretch and shrink (in the printed +output); see the <code>@tie</code> command in the next section. + + <p><a name="index-Hyphenation_002c-preventing-794"></a>You can also use the <code>@w</code> command to prevent TeX from +automatically hyphenating a long name or phrase that happens to fall +near the end of a line. <span class="command">makeinfo</span> does not ever hyphenate +words. + + <p><a name="index-Keyword-expansion_002c-preventing-795"></a><a name="index-Version-control-keywords_002c-preventing-expansion-of-796"></a><a name="index-_0024Id-expansion_002c-preventing-797"></a>You can also use <code>@w</code> to avoid unwanted keyword expansion in +source control systems. For example, to literally write <tt>$<!-- /@w -->Id$</tt> +in your document, use <code>@w{$}Id$</code>. + +<div class="node"> +<p><hr> +<a name="tie"></a>Next: <a rel="next" accesskey="n" href="#sp">sp</a>, +Previous: <a rel="previous" accesskey="p" href="#w">w</a>, +Up: <a rel="up" accesskey="u" href="#Breaks">Breaks</a> +<br> +</div> + +<h3 class="section">15.5 <code>@tie{}</code>: Inserting an Unbreakable Space</h3> + +<p><a name="index-tie-_0040r_007b_0028unbreakable-interword-space_0029_007d-798"></a><a name="index-Tied-space-799"></a><a name="index-Non_002dbreakable-space_002c-variable-800"></a><a name="index-Unbreakable-space_002c-variable-801"></a> +The <code>@tie{}</code> command produces a normal interword space at which +a line break may not occur. Always write it with following (empty) +braces, as usual for commands used within a paragraph. Here's an +example: + +<pre class="example"> @TeX{} was written by Donald E.@tie{}Knuth. +</pre> + <p class="noindent">produces: + +<pre class="display"> TeX was written by Donald E. <!-- /@w -->Knuth. +</pre> + <p>There are two important differences between <code>@tie{}</code> and +<code>@w{ <!-- /@w -->}</code>: + + <ul> +<li>The space produced by <code>@tie{}</code> will stretch and shrink slightly +along with the normal interword spaces in the paragraph; the space +produced by <code>@w{ <!-- /@w -->}</code> will not vary. + + <li><code>@tie{}</code> allows hyphenation of the surrounding words, while +<code>@w{ <!-- /@w -->}</code> inhibits hyphenation of those words (for TeXnical +reasons, namely that it produces an <span class="samp">\hbox</span>). + + </ul> + +<div class="node"> +<p><hr> +<a name="sp"></a>Next: <a rel="next" accesskey="n" href="#page">page</a>, +Previous: <a rel="previous" accesskey="p" href="#tie">tie</a>, +Up: <a rel="up" accesskey="u" href="#Breaks">Breaks</a> +<br> +</div> + +<h3 class="section">15.6 <code>@sp</code> <var>n</var>: Insert Blank Lines</h3> + +<p><a name="index-sp-_0040r_007b_0028line-spacing_0029_007d-802"></a><a name="index-Space_002c-inserting-vertical-803"></a><a name="index-Blank-lines-804"></a><a name="index-Line-spacing-805"></a> +A line beginning with and containing only <code>@sp </code><var>n</var> +generates <var>n</var> blank lines of space in both the printed manual and +the Info file. <code>@sp</code> also forces a paragraph break. For +example, + +<pre class="example"> @sp 2 +</pre> + <p class="noindent">generates two blank lines. + + <p>The <code>@sp</code> command is most often used in the title page. + +<div class="node"> +<p><hr> +<a name="page"></a>Next: <a rel="next" accesskey="n" href="#group">group</a>, +Previous: <a rel="previous" accesskey="p" href="#sp">sp</a>, +Up: <a rel="up" accesskey="u" href="#Breaks">Breaks</a> +<br> +</div> + +<h3 class="section">15.7 <code>@page</code>: Start a New Page</h3> + +<p><a name="index-Page-breaks-806"></a><a name="index-page-807"></a> +A line containing only <code>@page</code> starts a new page in a printed +manual. The command has no effect on Info files since they are not +paginated. An <code>@page</code> command is often used in the <code>@titlepage</code> +section of a Texinfo file to start the copyright page. + +<div class="node"> +<p><hr> +<a name="group"></a>Next: <a rel="next" accesskey="n" href="#need">need</a>, +Previous: <a rel="previous" accesskey="p" href="#page">page</a>, +Up: <a rel="up" accesskey="u" href="#Breaks">Breaks</a> +<br> +</div> + +<!-- node-name, next, previous, up --> +<h3 class="section">15.8 <code>@group</code>: Prevent Page Breaks</h3> + +<p><a name="index-Group-_0028hold-text-together-vertically_0029-808"></a><a name="index-Holding-text-together-vertically-809"></a><a name="index-Vertically-holding-text-together-810"></a><a name="index-group-811"></a> +The <code>@group</code> command (on a line by itself) is used inside an +<code>@example</code> or similar construct to begin an unsplittable vertical +group, which will appear entirely on one page in the printed output. +The group is terminated by a line containing only <code>@end group</code>. +These two lines produce no output of their own, and in the Info file +output they have no effect at all. + +<!-- Once said that these environments --> +<!-- turn off vertical spacing between ``paragraphs''. --> +<!-- Also, quotation used to work, but doesn't in texinfo-2.72 --> +<p>Although <code>@group</code> would make sense conceptually in a wide +variety of contexts, its current implementation works reliably only +within <code>@example</code> and variants, and within <code>@display</code>, +<code>@format</code>, <code>@flushleft</code> and <code>@flushright</code>. +See <a href="#Quotations-and-Examples">Quotations and Examples</a>. (What all these commands have in +common is that each line of input produces a line of output.) In +other contexts, <code>@group</code> can cause anomalous vertical +spacing. + + <p>This formatting requirement means that you should write: + +<pre class="example"> @example + @group + ... + @end group + @end example +</pre> + <p class="noindent">with the <code>@group</code> and <code>@end group</code> commands inside the +<code>@example</code> and <code>@end example</code> commands. + + <p>The <code>@group</code> command is most often used to hold an example +together on one page. In this Texinfo manual, more than 100 examples +contain text that is enclosed between <code>@group</code> and <code>@end +group</code>. + + <p>If you forget to end a group, you may get strange and unfathomable +error messages when you run TeX. This is because TeX keeps +trying to put the rest of the Texinfo file onto the one page and does +not start to generate error messages until it has processed +considerable text. It is a good rule of thumb to look for a missing +<code>@end group</code> if you get incomprehensible error messages in +TeX. + +<div class="node"> +<p><hr> +<a name="need"></a>Previous: <a rel="previous" accesskey="p" href="#group">group</a>, +Up: <a rel="up" accesskey="u" href="#Breaks">Breaks</a> +<br> +</div> + +<!-- node-name, next, previous, up --> +<h3 class="section">15.9 <code>@need </code><var>mils</var>: Prevent Page Breaks</h3> + +<p><a name="index-Need-space-at-page-bottom-812"></a><a name="index-need-813"></a> +A line containing only <code>@need </code><var>n</var> starts +a new page in a printed manual if fewer than <var>n</var> mils (thousandths +of an inch) remain on the current page. Do not use +braces around the argument <var>n</var>. The <code>@need</code> command has no +effect on Info files since they are not paginated. + + <p>This paragraph is preceded by an <code>@need</code> command that tells +TeX to start a new page if fewer than 800 mils (eight-tenths +inch) remain on the page. It looks like this: + +<pre class="example"> @need 800 + This paragraph is preceded by ... +</pre> + <p>The <code>@need</code> command is useful for preventing orphans (single +lines at the bottoms of printed pages). + +<div class="node"> +<p><hr> +<a name="Definition-Commands"></a>Next: <a rel="next" accesskey="n" href="#Conditionals">Conditionals</a>, +Previous: <a rel="previous" accesskey="p" href="#Breaks">Breaks</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> +<br> +</div> + +<h2 class="chapter">16 Definition Commands</h2> + +<p><a name="index-Definition-commands-814"></a> +The <code>@deffn</code> command and the other <dfn>definition commands</dfn> +enable you to describe functions, variables, macros, commands, user +options, special forms and other such artifacts in a uniform +format. + + <p>In the Info file, a definition causes the entity +category—`Function', `Variable', or whatever—to appear at the +beginning of the first line of the definition, followed by the +entity's name and arguments. In the printed manual, the command +causes TeX to print the entity's name and its arguments on the left +margin and print the category next to the right margin. In both +output formats, the body of the definition is indented. Also, the +name of the entity is entered into the appropriate index: +<code>@deffn</code> enters the name into the index of functions, +<code>@defvr</code> enters it into the index of variables, and so +on (see <a href="#Predefined-Indices">Predefined Indices</a>). + + <p>A manual need not and should not contain more than one definition for +a given name. An appendix containing a summary should use +<code>@table</code> rather than the definition commands. + +<ul class="menu"> +<li><a accesskey="1" href="#Def-Cmd-Template">Def Cmd Template</a>: Writing descriptions using definition commands. +<li><a accesskey="2" href="#Def-Cmd-Continuation-Lines">Def Cmd Continuation Lines</a>: Continuing the heading over source lines. +<li><a accesskey="3" href="#Optional-Arguments">Optional Arguments</a>: Handling optional and repeated arguments. +<li><a accesskey="4" href="#deffnx">deffnx</a>: Group two or more `first' lines. +<li><a accesskey="5" href="#Def-Cmds-in-Detail">Def Cmds in Detail</a>: Reference for all the definition commands. +<li><a accesskey="6" href="#Def-Cmd-Conventions">Def Cmd Conventions</a>: Conventions for writing definitions. +<li><a accesskey="7" href="#Sample-Function-Definition">Sample Function Definition</a>: An example. +</ul> + +<div class="node"> +<p><hr> +<a name="Def-Cmd-Template"></a>Next: <a rel="next" accesskey="n" href="#Def-Cmd-Continuation-Lines">Def Cmd Continuation Lines</a>, +Up: <a rel="up" accesskey="u" href="#Definition-Commands">Definition Commands</a> +<br> +</div> + +<h3 class="section">16.1 The Template for a Definition</h3> + +<p><a name="index-Definition-template-815"></a><a name="index-Template-for-a-definition-816"></a> +The <code>@deffn</code> command is used for definitions of entities that +resemble functions. To write a definition using the <code>@deffn</code> +command, write the <code>@deffn</code> command at the beginning of a line +and follow it on the same line by the category of the entity, the name +of the entity itself, and its arguments (if any). Then write the body +of the definition on succeeding lines. (You may embed examples in the +body.) Finally, end the definition with an <code>@end deffn</code> command +written on a line of its own. + + <p>The other definition commands follow the same format: a line with the +<code>@def...</code> command and whatever arguments are appropriate for +that command; the body of the definition; and a corresponding +<code>@end</code> line. + + <p>The template for a definition looks like this: + +<pre class="example"> @deffn <var>category</var> <var>name</var> <var>arguments</var>... + <var>body-of-definition</var> + @end deffn +</pre> + <p class="noindent">For example, + +<pre class="example"> @deffn Command forward-word count + This command moves point forward @var{count} words + (or backward if @var{count} is negative). ... + @end deffn +</pre> + <p class="noindent">produces + + <blockquote> + + <div class="defun"> +— Command: <b>forward-word</b><var> count<a name="index-forward_002dword-817"></a></var><br> +<blockquote><p>This function moves point forward <var>count</var> words +(or backward if <var>count</var> is negative). <small class="dots">...</small> +</p></blockquote></div> + </blockquote> + + <p>Capitalize the category name like a title. If the name of the +category contains spaces, as in the phrase `Interactive Command', +enclose it in braces. For example: + +<pre class="example"> @deffn {Interactive Command} isearch-forward + ... + @end deffn +</pre> + <p class="noindent">Otherwise, the second word will be mistaken for the name of the +entity. As a general rule, when any of the arguments in the heading +line <em>except</em> the last one are more than one word, you need to +enclose them in braces. + + <p>Some of the definition commands are more general than others. The +<code>@deffn</code> command, for example, is the general definition command +for functions and the like—for entities that may take arguments. +When you use this command, you specify the category to which the +entity belongs. Three predefined, specialized variations +(<code>@defun</code>, <code>@defmac</code>, and <code>@defspec</code>) specify the +category for you: “Function”, “Macro”, and “Special Form” +respectively. (In Lisp, a special form is an entity much like a +function.) Similarly, the general <code>@defvr</code> command is +accompanied by several specialized variations for describing +particular kinds of variables. + + <p>See <a href="#Sample-Function-Definition">Sample Function Definition</a>, for a detailed example of a +function definition, including the use of <code>@example</code> inside the +definition. + + <p><a name="index-Macros-in-definition-commands-818"></a>Unfortunately, due to implementation difficulties, macros are not expanded +in <code>@deffn</code> and all the other definition commands. + +<div class="node"> +<p><hr> +<a name="Def-Cmd-Continuation-Lines"></a>Next: <a rel="next" accesskey="n" href="#Optional-Arguments">Optional Arguments</a>, +Previous: <a rel="previous" accesskey="p" href="#Def-Cmd-Template">Def Cmd Template</a>, +Up: <a rel="up" accesskey="u" href="#Definition-Commands">Definition Commands</a> +<br> +</div> + +<h3 class="section">16.2 Definition Command Continuation Lines</h3> + +<p><a name="index-Continuation-lines-in-definition-commands-819"></a><a name="index-Definition-command-headings_002c-continuing-820"></a><a name="index-_0040samp_007b_0040_0040_007d-as-continuation-in-definition-commands-821"></a> +The heading line of a definition command can get very long. +Therefore, Texinfo has a special syntax allowing them to be continued +over multiple lines of the source file: a lone <span class="samp">@</span> at the end of +each line to be continued. Here's an example: + +<pre class="example"> @defun fn-name @ + arg1 arg2 arg3 + This is the basic continued defun. + @end defun +</pre> + <p class="noindent">produces: + +<div class="defun"> +— Function: <b>fn-name</b><var> arg1 arg2 arg3<a name="index-fn_002dname-822"></a></var><br> +<blockquote><p>This is the basic continued defun. +</p></blockquote></div> + +<p class="noindent">As you can see, the continued lines are combined, as if they had been +typed on one source line. + + <p>Although this example only shows a one-line continuation, +continuations may extend over any number of lines; simply put an +<code>@</code> at the end of each line to be continued. + + <p>The <code>@</code> character does not have to be the last character on the +physical line: whitespace is allowed (and ignored) afterwards. + + <p><a name="index-Whitespace_002c-collapsed-around-continuations-823"></a><a name="index-Collapsing-whitespace-around-continuations-824"></a>In general, any number of spaces or tabs around the <code>@</code> +continuation character, both on the line with the <code>@</code> and on the +continued line, are collapsed into a single space. There is one +exception: the Texinfo processors will not fully collapse whitespace +around a continuation inside braces. For example: + +<pre class="example"> @deffn {Category @ + Name} ... +</pre> + <p class="noindent">The output (not shown) has excess space between `Category' +and `Name'. In this case, simply elide any unwanted whitespace in +your input, or put the continuation <code>@</code> outside braces. + + <p><code>@</code> does not (currently) function as a continuation character in +<em>any</em> other context. Ordinarily, <span class="samp">@</span> followed by a +whitespace character (space, tab, newline) produces a normal interword +space (see <a href="#Multiple-Spaces">Multiple Spaces</a>). + +<div class="node"> +<p><hr> +<a name="Optional-Arguments"></a>Next: <a rel="next" accesskey="n" href="#deffnx">deffnx</a>, +Previous: <a rel="previous" accesskey="p" href="#Def-Cmd-Continuation-Lines">Def Cmd Continuation Lines</a>, +Up: <a rel="up" accesskey="u" href="#Definition-Commands">Definition Commands</a> +<br> +</div> + +<h3 class="section">16.3 Optional and Repeated Arguments</h3> + +<p><a name="index-Optional-and-repeated-arguments-825"></a><a name="index-Repeated-and-optional-arguments-826"></a><a name="index-Arguments_002c-repeated-and-optional-827"></a><a name="index-Syntax_002c-optional-_0026-repeated-arguments-828"></a><a name="index-Meta_002dsyntactic-chars-for-arguments-829"></a> +Some entities take optional or repeated arguments, which may be +specified by a distinctive glyph that uses square brackets and +ellipses. For example<!-- /@w -->, a special form often breaks its argument list +into separate arguments in more complicated ways than a +straightforward function. + +<!-- This is consistent with Emacs Lisp Reference manual --> +<p>An argument enclosed within square brackets is optional. +Thus, [<var>optional-arg</var>] means that <var>optional-arg</var> is optional. +An argument followed by an ellipsis is optional +and may be repeated more than once. +<!-- This is consistent with Emacs Lisp Reference manual --> +Thus, <var>repeated-args</var><span class="samp">...</span> stands for zero or more +arguments. Parentheses are used when several arguments are grouped +into additional levels of list structure in Lisp. + + <p>Here is the <code>@defspec</code> line of an example of an imaginary +special form: + + <blockquote> + + <div class="defun"> +— Special Form: <b>foobar</b> (<var>var </var>[<var>from to </var>[<var>inc</var>]])<var> body<small class="dots">...</small><a name="index-foobar-830"></a></var><br> +</div> + </blockquote> + +<p class="noindent">In this example, the arguments <var>from</var> and <var>to</var> are optional, +but must both be present or both absent. If they are present, +<var>inc</var> may optionally be specified as well. These arguments are +grouped with the argument <var>var</var> into a list, to distinguish them +from <var>body</var>, which includes all remaining elements of the +form. + + <p>In a Texinfo source file, this <code>@defspec</code> line is written like +this (except it would not be split over two lines, as it is in this +example). + +<pre class="example"> @defspec foobar (@var{var} [@var{from} @var{to} + [@var{inc}]]) @var{body}@dots{} +</pre> + <p class="noindent">The function is listed in the Command and Variable Index under +<span class="samp">foobar</span>. + +<div class="node"> +<p><hr> +<a name="deffnx"></a>Next: <a rel="next" accesskey="n" href="#Def-Cmds-in-Detail">Def Cmds in Detail</a>, +Previous: <a rel="previous" accesskey="p" href="#Optional-Arguments">Optional Arguments</a>, +Up: <a rel="up" accesskey="u" href="#Definition-Commands">Definition Commands</a> +<br> +</div> + +<h3 class="section">16.4 Two or More `First' Lines</h3> + +<p><a name="index-Two-_0060First_0027-Lines-for-_0040code_007b_0040_0040deffn_007d-831"></a><a name="index-Grouping-two-definitions-together-832"></a><a name="index-Definitions-grouped-together-833"></a><a name="index-deffnx-834"></a> +To create two or more `first' or header lines for a definition, follow +the first <code>@deffn</code> line by a line beginning with <code>@deffnx</code>. +The <code>@deffnx</code> command works exactly like <code>@deffn</code> +except that it does not generate extra vertical white space between it +and the preceding line. + + <p>For example, + +<pre class="example"> @deffn {Interactive Command} isearch-forward + @deffnx {Interactive Command} isearch-backward + These two search commands are similar except ... + @end deffn +</pre> + <p class="noindent">produces + +<div class="defun"> +— Interactive Command: <b>isearch-forward</b><var><a name="index-isearch_002dforward-835"></a></var><br> +— Interactive Command: <b>isearch-backward</b><var><a name="index-isearch_002dbackward-836"></a></var><br> +<blockquote><p>These two search commands are similar except <small class="dots">...</small> +</p></blockquote></div> + + <p>Each definition command has an `x' form: <code>@defunx</code>, +<code>@defvrx</code>, <code>@deftypefunx</code>, etc. + + <p>The `x' forms work similarly to <code>@itemx</code> (see <a href="#itemx">itemx</a>). + +<div class="node"> +<p><hr> +<a name="Def-Cmds-in-Detail"></a>Next: <a rel="next" accesskey="n" href="#Def-Cmd-Conventions">Def Cmd Conventions</a>, +Previous: <a rel="previous" accesskey="p" href="#deffnx">deffnx</a>, +Up: <a rel="up" accesskey="u" href="#Definition-Commands">Definition Commands</a> +<br> +</div> + +<h3 class="section">16.5 The Definition Commands</h3> + +<p>Texinfo provides more than a dozen definition commands, all of which +are described in this section. + + <p>The definition commands automatically enter the name of the entity in +the appropriate index: for example, <code>@deffn</code>, <code>@defun</code>, +and <code>@defmac</code> enter function names in the index of functions; +<code>@defvr</code> and <code>@defvar</code> enter variable names in the index +of variables. + + <p>Although the examples that follow mostly illustrate Lisp, the commands +can be used for other programming languages. + +<ul class="menu"> +<li><a accesskey="1" href="#Functions-Commands">Functions Commands</a>: Commands for functions and similar entities. +<li><a accesskey="2" href="#Variables-Commands">Variables Commands</a>: Commands for variables and similar entities. +<li><a accesskey="3" href="#Typed-Functions">Typed Functions</a>: Commands for functions in typed languages. +<li><a accesskey="4" href="#Typed-Variables">Typed Variables</a>: Commands for variables in typed languages. +<li><a accesskey="5" href="#Data-Types">Data Types</a>: The definition command for data types. +<li><a accesskey="6" href="#Abstract-Objects">Abstract Objects</a>: Commands for object-oriented programming. +</ul> + +<div class="node"> +<p><hr> +<a name="Functions-Commands"></a>Next: <a rel="next" accesskey="n" href="#Variables-Commands">Variables Commands</a>, +Up: <a rel="up" accesskey="u" href="#Def-Cmds-in-Detail">Def Cmds in Detail</a> +<br> +</div> + +<h4 class="subsection">16.5.1 Functions and Similar Entities</h4> + +<p>This section describes the commands for describing functions and similar +entities: + + +<a name="index-deffn-837"></a> +<dl><dt><code>@deffn </code><var>category</var> <var>name</var> <var>arguments</var><code>...</code><dd>The <code>@deffn</code> command is the general definition command for +functions, interactive commands, and similar entities that may take +arguments. You must choose a term to describe the category of entity +being defined; for example, “Function” could be used if the entity is +a function. The <code>@deffn</code> command is written at the beginning of a +line and is followed on the same line by the category of entity being +described, the name of this particular entity, and its arguments, if +any. Terminate the definition with <code>@end deffn</code> on a line of its +own. + + <p>For example, here is a definition: + + <pre class="example"> @deffn Command forward-char nchars + Move point forward @var{nchars} characters. + @end deffn + </pre> + <p class="noindent">This shows a rather terse definition for a “command” named +<code>forward-char</code> with one argument, <var>nchars</var>. + + <p><code>@deffn</code> and prints argument names such as <var>nchars</var> in slanted +type in the printed output, because we think of these names as +metasyntactic variables—they stand for the actual argument values. +Within the text of the description, however, write an argument name +explicitly with <code>@var</code> to refer to the value of the argument. +In the example above, we used <span class="samp">@var{nchars}</span> in this way. + + <p>In the unusual case when an argument name contains <span class="samp">--</span>, or +another character sequence which is treated specially +(see <a href="#Conventions">Conventions</a>), use <code>@var</code> around the argument. This +causes the name to be printed in slanted typewriter, instead of the +regular slanted font, exactly as input. +<!-- except for ?` and !`, but we won't explain that. --> + + <p>The template for <code>@deffn</code> is: + + <pre class="example"> @deffn <var>category</var> <var>name</var> <var>arguments</var>... + <var>body-of-definition</var> + @end deffn + </pre> + <p><a name="index-defun-838"></a><br><dt><code>@defun </code><var>name</var> <var>arguments</var><code>...</code><dd>The <code>@defun</code> command is the definition command for functions. +<code>@defun</code> is equivalent to <span class="samp">@deffn Function ...</span>. +Terminate the definition with <code>@end defun</code> on a line of its own. +Thus, the template is: + + <pre class="example"> @defun <var>function-name</var> <var>arguments</var>... + <var>body-of-definition</var> + @end defun + </pre> + <p><a name="index-defmac-839"></a><br><dt><code>@defmac </code><var>name</var> <var>arguments</var><code>...</code><dd>The <code>@defmac</code> command is the definition command for macros. +<code>@defmac</code> is equivalent to <span class="samp">@deffn Macro ...</span> and +works like <code>@defun</code>. + + <p><a name="index-defspec-840"></a><br><dt><code>@defspec </code><var>name</var> <var>arguments</var><code>...</code><dd>The <code>@defspec</code> command is the definition command for special +forms. (In Lisp, a special form is an entity much like a function, +see <a href="elisp.html#Special-Forms">Special Forms (GNU Emacs Lisp Reference Manual)</a>.) +<code>@defspec</code> is equivalent to <span class="samp">@deffn {Special Form} +...</span> and works like <code>@defun</code>. +</dl> + + <p>All these commands create entries in the index of functions. + +<div class="node"> +<p><hr> +<a name="Variables-Commands"></a>Next: <a rel="next" accesskey="n" href="#Typed-Functions">Typed Functions</a>, +Previous: <a rel="previous" accesskey="p" href="#Functions-Commands">Functions Commands</a>, +Up: <a rel="up" accesskey="u" href="#Def-Cmds-in-Detail">Def Cmds in Detail</a> +<br> +</div> + +<h4 class="subsection">16.5.2 Variables and Similar Entities</h4> + +<p>Here are the commands for defining variables and similar +entities: + + +<a name="index-defvr-841"></a> +<dl><dt><code>@defvr </code><var>category</var> <var>name</var><dd>The <code>@defvr</code> command is a general definition command for +something like a variable—an entity that records a value. You must +choose a term to describe the category of entity being defined; for +example, “Variable” could be used if the entity is a variable. +Write the <code>@defvr</code> command at the beginning of a line and +follow it on the same line by the category of the entity and the +name of the entity. + + <p>Capitalize the category name like a title. If the name of the category +contains spaces, as in the name “User Option”, enclose it in braces. +Otherwise, the second word will be mistaken for the name of the entity. +For example, + + <pre class="example"> @defvr {User Option} fill-column + This buffer-local variable specifies + the maximum width of filled lines. + ... + @end defvr + </pre> + <p>Terminate the definition with <code>@end defvr</code> on a line of its +own. + + <p>The template is: + + <pre class="example"> @defvr <var>category</var> <var>name</var> + <var>body-of-definition</var> + @end defvr + </pre> + <p><code>@defvr</code> creates an entry in the index of variables for <var>name</var>. + + <p><a name="index-defvar-842"></a><br><dt><code>@defvar </code><var>name</var><dd>The <code>@defvar</code> command is the definition command for variables. +<code>@defvar</code> is equivalent to <span class="samp">@defvr Variable +...</span>. + + <p>For example: + + <pre class="example"> @defvar kill-ring + ... + @end defvar + </pre> + <p>The template is: + + <pre class="example"> @defvar <var>name</var> + <var>body-of-definition</var> + @end defvar + </pre> + <p><code>@defvar</code> creates an entry in the index of variables for +<var>name</var>. + + <p><a name="index-defopt-843"></a><br><dt><code>@defopt </code><var>name</var><dd><a name="index-User-options_002c-marking-844"></a>The <code>@defopt</code> command is the definition command for <dfn>user +options</dfn>, i.e., variables intended for users to change according to +taste; Emacs has many such (see <a href="emacs.html#Variables">Variables (The GNU Emacs Manual)</a>). <code>@defopt</code> is equivalent to <span class="samp">@defvr {User +Option} ...</span> and works like <code>@defvar</code>. It creates an entry +in the index of variables. +</dl> + +<div class="node"> +<p><hr> +<a name="Typed-Functions"></a>Next: <a rel="next" accesskey="n" href="#Typed-Variables">Typed Variables</a>, +Previous: <a rel="previous" accesskey="p" href="#Variables-Commands">Variables Commands</a>, +Up: <a rel="up" accesskey="u" href="#Def-Cmds-in-Detail">Def Cmds in Detail</a> +<br> +</div> + +<h4 class="subsection">16.5.3 Functions in Typed Languages</h4> + +<p>The <code>@deftypefn</code> command and its variations are for describing +functions in languages in which you must declare types of variables and +functions, such as C and C++. + + +<a name="index-deftypefn-845"></a> +<dl><dt><code>@deftypefn </code><var>category</var> <var>data-type</var> <var>name</var> <var>arguments</var><code>...</code><dd>The <code>@deftypefn</code> command is the general definition command for +functions and similar entities that may take arguments and that are +typed. The <code>@deftypefn</code> command is written at the beginning of +a line and is followed on the same line by the category of entity +being described, the type of the returned value, the name of this +particular entity, and its arguments, if any. + + <p class="noindent">For example, + + <pre class="example"> @deftypefn {Library Function} int foobar + (int @var{foo}, float @var{bar}) + ... + @end deftypefn + </pre> + <p class="noindent">(where the text before the “<small class="dots">...</small>”, shown above as two lines, would +actually be a single line in a real Texinfo file) produces the following +in Info: + + <pre class="smallexample"> -- Library Function: int foobar (int FOO, float BAR) + ... + </pre> + <p>This means that <code>foobar</code> is a “library function” that returns an +<code>int</code>, and its arguments are <var>foo</var> (an <code>int</code>) and +<var>bar</var> (a <code>float</code>). + + <p>Since in typed languages, the actual names of the arguments are +typically scattered among data type names and keywords, Texinfo cannot +find them without help. You can either (a) <!-- /@w -->write everything +as straight text, and it will be printed in slanted type; (b) <!-- /@w -->use +<code>@var</code> for the variable names, which will uppercase the +variable names in Info and use the slanted typewriter font in printed +output; (c) <!-- /@w -->use <code>@var</code> for the variable names and +<code>@code</code> for the type names and keywords, which will be dutifully +obeyed. + + <p>The template for <code>@deftypefn</code> is: + + <pre class="example"> @deftypefn <var>category</var> <var>data-type</var> <var>name</var> <var>arguments</var> ... + <var>body-of-description</var> + @end deftypefn + </pre> + <p class="noindent">Note that if the <var>category</var> or <var>data type</var> is more than one +word then it must be enclosed in braces to make it a single argument. + + <p>If you are describing a procedure in a language that has packages, +such as Ada, you might consider using <code>@deftypefn</code> in a manner +somewhat contrary to the convention described in the preceding +paragraphs. For example: + + <pre class="example"> @deftypefn stacks private push @ + (@var{s}:in out stack; @ + @var{n}:in integer) + ... + @end deftypefn + </pre> + <p class="noindent">(The <code>@deftypefn</code> arguments are shown using continuations +(see <a href="#Def-Cmd-Continuation-Lines">Def Cmd Continuation Lines</a>), but could be on a single line in +a real Texinfo file.) + + <p>In this instance, the procedure is classified as belonging to the +package <code>stacks</code> rather than classified as a `procedure' and its +data type is described as <code>private</code>. (The name of the procedure +is <code>push</code>, and its arguments are <var>s</var> and <var>n</var>.) + + <p><code>@deftypefn</code> creates an entry in the index of functions for +<var>name</var>. + + <br><dt><code>@deftypefun </code><var>data-type</var> <var>name</var> <var>arguments</var><code>...</code><dd><a name="index-deftypefun-846"></a>The <code>@deftypefun</code> command is the specialized definition command +for functions in typed languages. The command is equivalent to +<span class="samp">@deftypefn Function ...</span>. The template is: + + <pre class="example"> @deftypefun <var>type</var> <var>name</var> <var>arguments</var>... + <var>body-of-description</var> + @end deftypefun + </pre> + <p><code>@deftypefun</code> creates an entry in the index of functions for +<var>name</var>. + + </dl> + +<div class="node"> +<p><hr> +<a name="Typed-Variables"></a>Next: <a rel="next" accesskey="n" href="#Data-Types">Data Types</a>, +Previous: <a rel="previous" accesskey="p" href="#Typed-Functions">Typed Functions</a>, +Up: <a rel="up" accesskey="u" href="#Def-Cmds-in-Detail">Def Cmds in Detail</a> +<br> +</div> + +<h4 class="subsection">16.5.4 Variables in Typed Languages</h4> + +<p>Variables in typed languages are handled in a manner similar to +functions in typed languages. See <a href="#Typed-Functions">Typed Functions</a>. The general +definition command <code>@deftypevr</code> corresponds to +<code>@deftypefn</code> and the specialized definition command +<code>@deftypevar</code> corresponds to <code>@deftypefun</code>. + + +<a name="index-deftypevr-847"></a> +<dl><dt><code>@deftypevr </code><var>category</var> <var>data-type</var> <var>name</var><dd>The <code>@deftypevr</code> command is the general definition command for +something like a variable in a typed language—an entity that records +a value. You must choose a term to describe the category of the +entity being defined; for example, “Variable” could be used if the +entity is a variable. + + <p>The <code>@deftypevr</code> command is written at the beginning of a line +and is followed on the same line by the category of the entity +being described, the data type, and the name of this particular +entity. + + <p class="noindent">For example: + + <pre class="example"> @deftypevr {Global Flag} int enable + ... + @end deftypevr + </pre> + <p class="noindent">produces the following in Info: + + <pre class="example"> -- Global Flag: int enable + ... + </pre> + <p>The template is: + + <pre class="example"> @deftypevr <var>category</var> <var>data-type</var> <var>name</var> + <var>body-of-description</var> + @end deftypevr + </pre> + <p><a name="index-deftypevar-848"></a><br><dt><code>@deftypevar </code><var>data-type</var> <var>name</var><dd>The <code>@deftypevar</code> command is the specialized definition command +for variables in typed languages. <code>@deftypevar</code> is equivalent +to <span class="samp">@deftypevr Variable ...</span>. The template is: + + <pre class="example"> @deftypevar <var>data-type</var> <var>name</var> + <var>body-of-description</var> + @end deftypevar + </pre> + </dl> + + <p>These commands create entries in the index of variables. + +<div class="node"> +<p><hr> +<a name="Data-Types"></a>Next: <a rel="next" accesskey="n" href="#Abstract-Objects">Abstract Objects</a>, +Previous: <a rel="previous" accesskey="p" href="#Typed-Variables">Typed Variables</a>, +Up: <a rel="up" accesskey="u" href="#Def-Cmds-in-Detail">Def Cmds in Detail</a> +<br> +</div> + +<h4 class="subsection">16.5.5 Data Types</h4> + +<p>Here is the command for data types: + + +<a name="index-deftp-849"></a> +<dl><dt><code>@deftp </code><var>category</var> <var>name</var> <var>attributes</var><code>...</code><dd>The <code>@deftp</code> command is the generic definition command for data +types. The command is written at the beginning of a line and is +followed on the same line by the category, by the name of the type +(which is a word like <code>int</code> or <code>float</code>), and then by names of +attributes of objects of that type. Thus, you could use this command +for describing <code>int</code> or <code>float</code>, in which case you could use +<code>data type</code> as the category. (A data type is a category of +certain objects for purposes of deciding which operations can be +performed on them.) + + <p>In Lisp, for example, <dfn>pair</dfn> names a particular data +type, and an object of that type has two slots called the +<span class="sc">car</span> and the <span class="sc">cdr</span>. Here is how you would write the first line +of a definition of <code>pair</code>. + + <pre class="example"> @deftp {Data type} pair car cdr + ... + @end deftp + </pre> + <p>The template is: + + <pre class="example"> @deftp <var>category</var> <var>name-of-type</var> <var>attributes</var>... + <var>body-of-definition</var> + @end deftp + </pre> + <p><code>@deftp</code> creates an entry in the index of data types. +</dl> + +<div class="node"> +<p><hr> +<a name="Abstract-Objects"></a>Previous: <a rel="previous" accesskey="p" href="#Data-Types">Data Types</a>, +Up: <a rel="up" accesskey="u" href="#Def-Cmds-in-Detail">Def Cmds in Detail</a> +<br> +</div> + +<h4 class="subsection">16.5.6 Object-Oriented Programming</h4> + +<p><a name="index-Object_002doriented-programming-850"></a> +Here are the commands for formatting descriptions about abstract +objects, such as are used in object-oriented programming. A class is +a defined type of abstract object. An instance of a class is a +particular object that has the type of the class. An instance +variable is a variable that belongs to the class but for which each +instance has its own value. + +<ul class="menu"> +<li><a accesskey="1" href="#Object_002dOriented-Variables">Variables</a> +<li><a accesskey="2" href="#Object_002dOriented-Methods">Methods</a> +</ul> + +<div class="node"> +<p><hr> +<a name="Object_002dOriented-Variables"></a>Next: <a rel="next" accesskey="n" href="#Object_002dOriented-Methods">Object-Oriented Methods</a>, +Up: <a rel="up" accesskey="u" href="#Abstract-Objects">Abstract Objects</a> +<br> +</div> + +<h5 class="subsubsection">16.5.6.1 Object-Oriented Variables</h5> + +<p><a name="index-Variables_002c-object_002doriented-851"></a> +These commands allow you to define different sorts of variables in +object-oriented programming languages. + + <dl> +<dt><code>@defcv </code><var>category</var> <var>class</var> <var>name</var><dd><a name="index-defcv-852"></a>The <code>@defcv</code> command is the general definition command for +variables associated with classes in object-oriented programming. The +<code>@defcv</code> command is followed by three arguments: the category of +thing being defined, the class to which it belongs, and its +name. For instance: + + <pre class="example"> @defcv {Class Option} Window border-pattern + ... + @end defcv + </pre> + <p class="noindent">produces: + + <div class="defun"> +— Class Option of Window: <b>border-pattern</b><var><a name="index-border_002dpattern-853"></a></var><br> +<blockquote><small class="dots">...</small> +</blockquote></div> + + <p><code>@defcv</code> creates an entry in the index of variables. + + <br><dt><code>@deftypecv </code><var>category</var> <var>class</var> <var>data-type</var> <var>name</var><dd><a name="index-deftypecv-854"></a>The <code>@deftypecv</code> command is the definition command for typed +class variables in object-oriented programming. It is analogous to +<code>@defcv</code> with the addition of the <var>data-type</var> parameter to +specify the type of the instance variable. Ordinarily, the data type +is a programming language construct that should be marked with +<code>@code</code>. For instance: + + <pre class="example"> @deftypecv {Class Option} Window @code{int} border-pattern + ... + @end deftypecv + </pre> + <p class="noindent">produces: + + <div class="defun"> +— Class Option of Window: <code>int</code> <b>border-pattern</b><var><a name="index-border_002dpattern-855"></a></var><br> +<blockquote><small class="dots">...</small> +</blockquote></div> + + <p><code>@deftypecv</code> creates an entry in the index of variables. + + <br><dt><code>@defivar </code><var>class</var> <var>name</var><dd><a name="index-defivar-856"></a>The <code>@defivar</code> command is the definition command for instance +variables in object-oriented programming. <code>@defivar</code> is +equivalent to <span class="samp">@defcv {Instance Variable} ...</span>. For +instance: + + <pre class="example"> @defivar Window border-pattern + ... + @end defivar + </pre> + <p class="noindent">produces: + + <div class="defun"> +— Instance Variable of Window: <b>border-pattern</b><var><a name="index-border_002dpattern-857"></a></var><br> +<blockquote><small class="dots">...</small> +</blockquote></div> + + <p><code>@defivar</code> creates an entry in the index of variables. + + <br><dt><code>@deftypeivar </code><var>class</var> <var>data-type</var> <var>name</var><dd><a name="index-deftypeivar-858"></a>The <code>@deftypeivar</code> command is the definition command for typed +instance variables in object-oriented programming. It is analogous to +<code>@defivar</code> with the addition of the <var>data-type</var> parameter to +specify the type of the instance variable. Ordinarily, the data type +is a programming language construct that should be marked with +<code>@code</code>. For instance: + + <pre class="example"> @deftypeivar Window @code{int} border-pattern + ... + @end deftypeivar + </pre> + <p class="noindent">produces: + + <div class="defun"> +— Instance Variable of Window: <code>int</code> <b>border-pattern</b><var><a name="index-border_002dpattern-of-Window-859"></a></var><br> +<blockquote><small class="dots">...</small> +</blockquote></div> + + <p><code>@deftypeivar</code> creates an entry in the index of variables. + + </dl> + +<div class="node"> +<p><hr> +<a name="Object_002dOriented-Methods"></a>Previous: <a rel="previous" accesskey="p" href="#Object_002dOriented-Variables">Object-Oriented Variables</a>, +Up: <a rel="up" accesskey="u" href="#Abstract-Objects">Abstract Objects</a> +<br> +</div> + +<h5 class="subsubsection">16.5.6.2 Object-Oriented Methods</h5> + +<p><a name="index-Methods_002c-object_002doriented-860"></a> +These commands allow you to define different sorts of function-like +entities resembling methods in object-oriented programming languages. +These entities take arguments, as functions do, but are associated with +particular classes of objects. + + +<a name="index-defop-861"></a> +<dl><dt><code>@defop </code><var>category</var> <var>class</var> <var>name</var> <var>arguments</var><code>...</code><dd>The <code>@defop</code> command is the general definition command for these +method-like entities. + + <p>For example, some systems have constructs called <dfn>wrappers</dfn> that +are associated with classes as methods are, but that act more like +macros than like functions. You could use <code>@defop Wrapper</code> to +describe one of these. + + <p>Sometimes it is useful to distinguish methods and <dfn>operations</dfn>. +You can think of an operation as the specification for a method. +Thus, a window system might specify that all window classes have a +method named <code>expose</code>; we would say that this window system +defines an <code>expose</code> operation on windows in general. Typically, +the operation has a name and also specifies the pattern of arguments; +all methods that implement the operation must accept the same +arguments, since applications that use the operation do so without +knowing which method will implement it. + + <p>Often it makes more sense to document operations than methods. For +example, window application developers need to know about the +<code>expose</code> operation, but need not be concerned with whether a +given class of windows has its own method to implement this operation. +To describe this operation, you would write: + + <pre class="example"> @defop Operation windows expose + </pre> + <p>The <code>@defop</code> command is written at the beginning of a line and +is followed on the same line by the overall name of the category of +operation, the name of the class of the operation, the name of the +operation, and its arguments, if any. + + <p>The template is: + <pre class="example"> @defop <var>category</var> <var>class</var> <var>name</var> <var>arguments</var>... + <var>body-of-definition</var> + @end defop + </pre> + <p><code>@defop</code> creates an entry, such as `<code>expose</code> on +<code>windows</code>', in the index of functions. + + <p><a name="index-deftypeop-862"></a><br><dt><code>@deftypeop </code><var>category</var> <var>class</var> <var>data-type</var> <var>name</var> <var>arguments</var><code>...</code><dd>The <code>@deftypeop</code> command is the definition command for typed +operations in object-oriented programming. It is similar to +<code>@defop</code> with the addition of the <var>data-type</var> parameter to +specify the return type of the method. <code>@deftypeop</code> creates an +entry in the index of functions. + + <br><dt><code>@defmethod </code><var>class</var> <var>name</var> <var>arguments</var><code>...</code><dd><a name="index-defmethod-863"></a>The <code>@defmethod</code> command is the definition command for methods +in object-oriented programming. A method is a kind of function that +implements an operation for a particular class of objects and its +subclasses. + + <p><code>@defmethod</code> is equivalent to <span class="samp">@defop Method ...</span>. +The command is written at the beginning of a line and is followed by +the name of the class of the method, the name of the method, and its +arguments, if any. + + <p class="noindent">For example: + <pre class="example"> @defmethod <code>bar-class</code> bar-method argument + ... + @end defmethod + </pre> + <p class="noindent">illustrates the definition for a method called <code>bar-method</code> of +the class <code>bar-class</code>. The method takes an argument. + + <p><code>@defmethod</code> creates an entry in the index of functions. + + <br><dt><code>@deftypemethod </code><var>class</var> <var>data-type</var> <var>name</var> <var>arguments</var><code>...</code><dd><a name="index-defmethod-864"></a>The <code>@deftypemethod</code> command is the definition command for methods +in object-oriented typed languages, such as C++ and Java. It is similar +to the <code>@defmethod</code> command with the addition of the +<var>data-type</var> parameter to specify the return type of the method. +<code>@deftypemethod</code> creates an entry in the index of functions. + + </dl> + +<div class="node"> +<p><hr> +<a name="Def-Cmd-Conventions"></a>Next: <a rel="next" accesskey="n" href="#Sample-Function-Definition">Sample Function Definition</a>, +Previous: <a rel="previous" accesskey="p" href="#Def-Cmds-in-Detail">Def Cmds in Detail</a>, +Up: <a rel="up" accesskey="u" href="#Definition-Commands">Definition Commands</a> +<br> +</div> + +<h3 class="section">16.6 Conventions for Writing Definitions</h3> + +<p><a name="index-Definition-conventions-865"></a><a name="index-Conventions-for-writing-definitions-866"></a> +When you write a definition using <code>@deffn</code>, <code>@defun</code>, or +one of the other definition commands, please take care to use +arguments that indicate the meaning, as with the <var>count</var> argument +to the <code>forward-word</code> function. Also, if the name of an argument +contains the name of a type, such as <var>integer</var>, take care that the +argument actually is of that type. + +<div class="node"> +<p><hr> +<a name="Sample-Function-Definition"></a>Previous: <a rel="previous" accesskey="p" href="#Def-Cmd-Conventions">Def Cmd Conventions</a>, +Up: <a rel="up" accesskey="u" href="#Definition-Commands">Definition Commands</a> +<br> +</div> + +<h3 class="section">16.7 A Sample Function Definition</h3> + +<p><a name="index-Function-definitions-867"></a><a name="index-Command-definitions-868"></a><a name="index-Macro-definitions-869"></a><a name="index-Sample-function-definition-870"></a> +A function definition uses the <code>@defun</code> and <code>@end defun</code> +commands. The name of the function follows immediately after the +<code>@defun</code> command and it is followed, on the same line, by the +parameter list. + + <p>Here is a definition from <a href="elisp.html#Calling-Functions">Calling Functions (The GNU Emacs Lisp Reference Manual)</a>. + + <blockquote> + + <div class="defun"> +— Function: <b>apply</b><var> function &rest arguments<a name="index-apply-871"></a></var><br> +<blockquote><p><code>apply</code> calls <var>function</var> with <var>arguments</var>, just +like <code>funcall</code> but with one difference: the last of +<var>arguments</var> is a list of arguments to give to +<var>function</var>, rather than a single argument. We also say +that this list is <dfn>appended</dfn> to the other arguments. + + <p><code>apply</code> returns the result of calling <var>function</var>. +As with <code>funcall</code>, <var>function</var> must either be a Lisp +function or a primitive function; special forms and macros +do not make sense in <code>apply</code>. + + <pre class="example"> (setq f 'list) + => list + (apply f 'x 'y 'z) + error--> Wrong type argument: listp, z + (apply '+ 1 2 '(3 4)) + => 10 + (apply '+ '(1 2 3 4)) + => 10 + + (apply 'append '((a b c) nil (x y z) nil)) + => (a b c x y z) + </pre> + <p>An interesting example of using <code>apply</code> is found in the description +of <code>mapcar</code>. +</p></blockquote></div> + </blockquote> + + <p>In the Texinfo source file, this example looks like this: + +<pre class="example"> @defun apply function &rest arguments + @code{apply} calls @var{function} with + @var{arguments}, just like @code{funcall} but with one + difference: the last of @var{arguments} is a list of + arguments to give to @var{function}, rather than a single + argument. We also say that this list is @dfn{appended} + to the other arguments. + + @code{apply} returns the result of calling + @var{function}. As with @code{funcall}, + @var{function} must either be a Lisp function or a + primitive function; special forms and macros do not make + sense in @code{apply}. + + @example + (setq f 'list) + @result{} list + (apply f 'x 'y 'z) + @error{} Wrong type argument: listp, z + (apply '+ 1 2 '(3 4)) + @result{} 10 + (apply '+ '(1 2 3 4)) + @result{} 10 + + (apply 'append '((a b c) nil (x y z) nil)) + @result{} (a b c x y z) + @end example + + An interesting example of using @code{apply} is found + in the description of @code{mapcar}. + @end defun +</pre> + <p class="noindent">In this manual, this function is listed in the Command and Variable +Index under <code>apply</code>. + + <p>Ordinary variables and user options are described using a format like +that for functions except that variables do not take arguments. + +<div class="node"> +<p><hr> +<a name="Conditionals"></a>Next: <a rel="next" accesskey="n" href="#Internationalization">Internationalization</a>, +Previous: <a rel="previous" accesskey="p" href="#Definition-Commands">Definition Commands</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> +<br> +</div> + +<h2 class="chapter">17 Conditionally Visible Text</h2> + +<p><a name="index-Conditionally-visible-text-872"></a><a name="index-Text_002c-conditionally-visible-873"></a><a name="index-Visibility-of-conditional-text-874"></a><a name="index-If-text-conditionally-visible-875"></a> +The <dfn>conditional commands</dfn> allow you to use different text for +different output formats, or for general conditions that you define. +For example, you can use them to specify different text for the +printed manual and the Info output. + + <p>The conditional commands comprise the following categories. + + <ul> +<li>Commands specific to an output format (Info, TeX, HTML, <small class="dots">...</small>). + + <li>Commands specific to any output format <em>other</em> than a given +one (not Info, not TeX, <small class="dots">...</small>). + + <li>`Raw' formatter text for any output format, passed straight +through with no interpretation of @-commands. + + <li>Format-independent variable substitutions, and testing if a variable +is set or clear. + + </ul> + +<ul class="menu"> +<li><a accesskey="1" href="#Conditional-Commands">Conditional Commands</a>: Text for a given format. +<li><a accesskey="2" href="#Conditional-Not-Commands">Conditional Not Commands</a>: Text for any format other than a given one. +<li><a accesskey="3" href="#Raw-Formatter-Commands">Raw Formatter Commands</a>: Using raw formatter commands. +<li><a accesskey="4" href="#set-clear-value">set clear value</a>: Variable tests and substitutions. +<li><a accesskey="5" href="#Conditional-Nesting">Conditional Nesting</a>: Using conditionals inside conditionals. +</ul> + +<div class="node"> +<p><hr> +<a name="Conditional-Commands"></a>Next: <a rel="next" accesskey="n" href="#Conditional-Not-Commands">Conditional Not Commands</a>, +Up: <a rel="up" accesskey="u" href="#Conditionals">Conditionals</a> +<br> +</div> + +<h3 class="section">17.1 Conditional Commands</h3> + +<p>Texinfo has an <code>@if</code><var>format</var> environment for each output +format, to allow conditional inclusion of text for a particular output +format. + + <p><a name="index-ifinfo-876"></a><code>@ifinfo</code> begins segments of text that should be ignored by +TeX when it typesets the printed manual, and by <span class="command">makeinfo</span> +when not producing Info output. The segment of text appears only in +the Info file and, for historical compatibility, the plain text +output. + + <p><a name="index-ifdocbook-877"></a><a name="index-ifhtml-878"></a><a name="index-ifplaintext-879"></a><a name="index-iftex-880"></a><a name="index-ifxml-881"></a>The environments for the other formats are analogous: + + <dl> +<dt><code>@ifdocbook ... @end ifdocbook</code><dd>Text to appear only in the Docbook output. + + <br><dt><code>@ifhtml ... @end ifhtml</code><dd>Text to appear only in the HTML output. + + <br><dt><code>@ifplaintext ... @end ifplaintext</code><dd>Text to appear only in the plain text output. + + <br><dt><code>@iftex ... @end iftex</code><dd>Text to appear only in the printed manual. + + <br><dt><code>@ifxml ... @end ifxml</code><dd>Text to appear only in the XML output. +</dl> + + <p>The <code>@if...</code> and <code>@end if...</code> commands must appear +on lines by themselves in your source file. + + <p>Here is an example showing all these conditionals: + +<pre class="example"> @iftex + This text will appear only in the printed manual. + @end iftex + @ifinfo + However, this text will appear only in Info and plain text. + @end ifinfo + @ifhtml + And this text will only appear in HTML. + @end ifhtml + @ifplaintext + Whereas this text will only appear in plain text. + @end ifplaintext + @ifxml + Notwithstanding that this will only appear in XML. + @end ifxml + @ifdocbook + Nevertheless, this will only appear in Docbook. + @end ifdocbook +</pre> + <p class="noindent">The preceding example produces the following line: + + <p>And this text will only appear in HTML. + +<p class="noindent">Notice that you only see one of the input lines, depending on which +version of the manual you are reading. + +<div class="node"> +<p><hr> +<a name="Conditional-Not-Commands"></a>Next: <a rel="next" accesskey="n" href="#Raw-Formatter-Commands">Raw Formatter Commands</a>, +Previous: <a rel="previous" accesskey="p" href="#Conditional-Commands">Conditional Commands</a>, +Up: <a rel="up" accesskey="u" href="#Conditionals">Conditionals</a> +<br> +</div> + +<h3 class="section">17.2 Conditional Not Commands</h3> + +<p><a name="index-ifnotdocbook-882"></a><a name="index-ifnothtml-883"></a><a name="index-ifnotinfo-884"></a><a name="index-ifnotplaintext-885"></a><a name="index-ifnottex-886"></a><a name="index-ifnotxml-887"></a> +You can specify text to be included in any output format <em>other</em> +than a given one with the <code>@ifnot...</code> environments: + +<pre class="example"> @ifnotdocbook ... @end ifnotdocbook + @ifnothtml ... @end ifnothtml + @ifnotinfo ... @end ifnotinfo + @ifnotplaintext ... @end ifnotplaintext + @ifnottex ... @end ifnottex + @ifnotxml ... @end ifnotxml +</pre> + <p class="noindent">The <code>@ifnot...</code> command and the <code>@end</code> command must +appear on lines by themselves in your actual source file. + + <p>If the output file is being made in the given format, the +region is <em>ignored</em>. Otherwise, it is included. + + <p>There is one exception (for historical compatibility): +<code>@ifnotinfo</code> text is omitted for both Info and plain text +output, not just Info. To specify text which appears only in Info and +not in plain text, use <code>@ifnotplaintext</code>, like this: + +<pre class="example"> @ifinfo + @ifnotplaintext + This will be in Info, but not plain text. + @end ifnotplaintext + @end ifinfo +</pre> + <p>The regions delimited by these commands are ordinary Texinfo source as +with <code>@iftex</code>, not raw formatter source as with <code>@tex</code> +(see <a href="#Raw-Formatter-Commands">Raw Formatter Commands</a>). + +<div class="node"> +<p><hr> +<a name="Raw-Formatter-Commands"></a>Next: <a rel="next" accesskey="n" href="#set-clear-value">set clear value</a>, +Previous: <a rel="previous" accesskey="p" href="#Conditional-Not-Commands">Conditional Not Commands</a>, +Up: <a rel="up" accesskey="u" href="#Conditionals">Conditionals</a> +<br> +</div> + +<h3 class="section">17.3 Raw Formatter Commands</h3> + +<p><a name="index-Raw-formatter-commands-888"></a><a name="index-_0040TeX_007b_007d-commands_002c-using-ordinary-889"></a><a name="index-Ordinary-_0040TeX_007b_007d-commands_002c-using-890"></a><a name="index-Commands-using-raw-_0040TeX_007b_007d-891"></a><a name="index-Docbook_002c-including-raw-892"></a><a name="index-HTML_002c-including-raw-893"></a><a name="index-XML_002c-including-raw-894"></a><a name="index-Plain-_0040TeX_007b_007d-895"></a> +Inside a region delineated by <code>@iftex</code> and <code>@end iftex</code>, +you can embed some raw TeX commands. The Texinfo processors will +ignore such a region unless TeX output is being produced. You can +write the TeX commands as you would write them in a normal TeX +file, except that you must replace the <span class="samp">\</span> used by TeX with an +<span class="samp">@</span>. For example, in the <code>@titlepage</code> section of a +Texinfo file, you can use the TeX command <code>@vskip</code> to format +the copyright page. (The <code>@titlepage</code> command causes Info to +ignore the region automatically, as it does with the <code>@iftex</code> +command.) + + <p>However, most features of plain TeX will not work within +<code>@iftex</code>, as they are overridden by Texinfo features. The +purpose of <code>@iftex</code> is to provide conditional processing for the +Texinfo source, not provide access to underlying formatting features. + + <p><a name="index-tex-896"></a>You can enter plain TeX completely, and use <span class="samp">\</span> in the TeX +commands, by delineating a region with the <code>@tex</code> and <code>@end +tex</code> commands. All plain TeX commands and category codes are +restored within an <code>@tex</code> region. The sole exception is that the +<code>@</code> character still introduces a command, so that <code>@end tex</code> +can be recognized properly. As with <code>@iftex</code>, Texinfo +processors will ignore such a region unless TeX output is being produced. + + <p><a name="index-_005cgdef-_0040r_007bwithin-_0040code_007b_0040_0040tex_007d_007d-897"></a>In complex cases, you may wish to define new TeX macros within +<code>@tex</code>. You must use <code>\gdef</code> to do this, not <code>\def</code>, +because <code>@tex</code> regions are processed in a TeX group. + + <p><a name="index-Mathematical-expressions-898"></a>As an example, here is a mathematical expression written in plain TeX: + +<pre class="example"> @tex + $$ \chi^2 = \sum_{i=1}^N + \left (y_i - (a + b x_i) + \over \sigma_i\right)^2 $$ + @end tex +</pre> + <p class="noindent">The output of this example will appear only in a printed manual. If +you are reading this in Info, you will not see the equation that appears +in the printed manual. + + <p><a name="index-ifhtml-899"></a><a name="index-html-900"></a>Analogously, you can use <code>@ifhtml ... @end ifhtml</code> to delimit +a region to be included in HTML output only, and <code>@html ... +@end html</code> for a region of raw HTML. + + <p><a name="index-ifxml-901"></a><a name="index-xml-902"></a>Likewise, you can use <code>@ifxml ... @end ifxml</code> to delimit +a region to be included in XML output only, and <code>@xml ... +@end xml</code> for a region of raw XML. + + <p><a name="index-ifdocbook-903"></a><a name="index-docbook-904"></a>Again likewise, you can use <code>@ifdocbook ... @end ifdocbook</code> +to delimit a region to be included in Docbook output only, and +<code>@docbook ... @end docbook</code> for a region of raw Docbook. + + <p>In all cases, the exception to the raw processing is that <code>@</code> is +still an escape character, so the <code>@end</code> command can be +recognized. + +<div class="node"> +<p><hr> +<a name="set-clear-value"></a>Next: <a rel="next" accesskey="n" href="#Conditional-Nesting">Conditional Nesting</a>, +Previous: <a rel="previous" accesskey="p" href="#Raw-Formatter-Commands">Raw Formatter Commands</a>, +Up: <a rel="up" accesskey="u" href="#Conditionals">Conditionals</a> +<br> +</div> + +<h3 class="section">17.4 <code>@set</code>, <code>@clear</code>, and <code>@value</code></h3> + +<p>You can direct the Texinfo formatting commands to format or ignore parts +of a Texinfo file with the <code>@set</code>, <code>@clear</code>, <code>@ifset</code>, +and <code>@ifclear</code> commands. + + <p>Here are brief descriptions of these commands, see the following +sections for more details: + + <dl> +<dt><code>@set </code><var>flag</var><code> [</code><var>value</var><code>]</code><dd>Set the variable <var>flag</var>, to the optional <var>value</var> if specifed. + + <br><dt><code>@clear </code><var>flag</var><dd>Undefine the variable <var>flag</var>, whether or not it was previously defined. + + <br><dt><code>@ifset </code><var>flag</var><dd>If <var>flag</var> is set, text through the next <code>@end ifset</code> command +is formatted. If <var>flag</var> is clear, text through the following +<code>@end ifset</code> command is ignored. + + <br><dt><code>@ifclear </code><var>flag</var><dd>If <var>flag</var> is set, text through the next <code>@end ifclear</code> command +is ignored. If <var>flag</var> is clear, text through the following +<code>@end ifclear</code> command is formatted. +</dl> + +<ul class="menu"> +<li><a accesskey="1" href="#set-value">set value</a>: Expand a flag variable to a string. +<li><a accesskey="2" href="#ifset-ifclear">ifset ifclear</a>: Format a region if a flag is set. +<li><a accesskey="3" href="#value-Example">value Example</a>: An easy way to update edition information. +</ul> + +<div class="node"> +<p><hr> +<a name="set-value"></a>Next: <a rel="next" accesskey="n" href="#ifset-ifclear">ifset ifclear</a>, +Up: <a rel="up" accesskey="u" href="#set-clear-value">set clear value</a> +<br> +</div> + +<h4 class="subsection">17.4.1 <code>@set</code> and <code>@value</code></h4> + +<p><a name="index-value-905"></a> +You use the <code>@set</code> command to specify a value for a flag, which +is later expanded by the <code>@value</code> command. + + <p>A <dfn>flag</dfn> (aka <dfn>variable</dfn>) is an identifier. It is best to use +only letters and numerals in a flag name, not <span class="samp">-</span> or +<span class="samp">_</span>—they will work in some contexts, but not all, due to +limitations in TeX. + + <p>The value is the remainder of the input line, and can contain anything. + + <p>Write the <code>@set</code> command like this: + +<pre class="example"> @set foo This is a string. +</pre> + <p class="noindent">This sets the value of the flag <code>foo</code> to “This is a string.”. + + <p>The Texinfo formatters then replace an <code>@value{</code><var>flag</var><code>}</code> +command with the string to which <var>flag</var> is set. Thus, when +<code>foo</code> is set as shown above, the Texinfo formatters convert this: + +<pre class="example"> @value{foo} +<br><span class="roman">to this:</span><br> + This is a string. +</pre> + <p>You can write an <code>@value</code> command within a paragraph; but you +must write an <code>@set</code> command on a line of its own. + + <p>If you write the <code>@set</code> command like this: + +<pre class="example"> @set foo +</pre> + <p class="noindent">without specifying a string, the value of <code>foo</code> is the empty string. + + <p>If you clear a previously set flag with <code>@clear </code><var>flag</var>, a +subsequent <code>@value{flag}</code> command will report an error. + + <p>For example, if you set <code>foo</code> as follows: + +<pre class="example"> @set howmuch very, very, very +</pre> + <p class="noindent">then the formatters transform + +<pre class="example"> It is a @value{howmuch} wet day. +<br><span class="roman">into</span><br> + It is a very, very, very wet day. +</pre> + <p>If you write + +<pre class="example"> @clear howmuch +</pre> + <p class="noindent">then the formatters transform + +<pre class="example"> It is a @value{howmuch} wet day. +<br><span class="roman">into</span><br> + It is a {No value for "howmuch"} wet day. +</pre> + <div class="node"> +<p><hr> +<a name="ifset-ifclear"></a>Next: <a rel="next" accesskey="n" href="#value-Example">value Example</a>, +Previous: <a rel="previous" accesskey="p" href="#set-value">set value</a>, +Up: <a rel="up" accesskey="u" href="#set-clear-value">set clear value</a> +<br> +</div> + +<h4 class="subsection">17.4.2 <code>@ifset</code> and <code>@ifclear</code></h4> + +<p><a name="index-ifset-906"></a>When a <var>flag</var> is set, the Texinfo formatting commands format text +between subsequent pairs of <code>@ifset </code><var>flag</var> and <code>@end +ifset</code> commands. When the <var>flag</var> is cleared, the Texinfo formatting +commands do <em>not</em> format the text. <code>@ifclear</code> operates +analogously. + + <p>Write the conditionally formatted text between <code>@ifset </code><var>flag</var> +and <code>@end ifset</code> commands, like this: + +<pre class="example"> @ifset <var>flag</var> + <var>conditional-text</var> + @end ifset +</pre> + <p>For example, you can create one document that has two variants, such as +a manual for a `large' and `small' model: + + <p><a name="index-Shrubbery-907"></a> +<pre class="example"> You can use this machine to dig up shrubs + without hurting them. + + @set large + + @ifset large + It can also dig up fully grown trees. + @end ifset + + Remember to replant promptly ... +</pre> + <p class="noindent">In the example, the formatting commands will format the text between +<code>@ifset large</code> and <code>@end ifset</code> because the <code>large</code> +flag is set. + + <p>When <var>flag</var> is cleared, the Texinfo formatting commands do +<em>not</em> format the text between <code>@ifset </code><var>flag</var> and +<code>@end ifset</code>; that text is ignored and does not appear in either +printed or Info output. + + <p>For example, if you clear the flag of the preceding example by writing +an <code>@clear large</code> command after the <code>@set large</code> command +(but before the conditional text), then the Texinfo formatting commands +ignore the text between the <code>@ifset large</code> and <code>@end ifset</code> +commands. In the formatted output, that text does not appear; in both +printed and Info output, you see only the lines that say, “You can use +this machine to dig up shrubs without hurting them. Remember to replant +promptly <small class="dots">...</small>”. + + <p><a name="index-ifclear-908"></a>If a flag is cleared with an <code>@clear </code><var>flag</var> command, then +the formatting commands format text between subsequent pairs of +<code>@ifclear</code> and <code>@end ifclear</code> commands. But if the flag +is set with <code>@set </code><var>flag</var>, then the formatting commands do +<em>not</em> format text between an <code>@ifclear</code> and an <code>@end +ifclear</code> command; rather, they ignore that text. An <code>@ifclear</code> +command looks like this: + +<pre class="example"> @ifclear <var>flag</var> +</pre> + <div class="node"> +<p><hr> +<a name="value-Example"></a>Previous: <a rel="previous" accesskey="p" href="#ifset-ifclear">ifset ifclear</a>, +Up: <a rel="up" accesskey="u" href="#set-clear-value">set clear value</a> +<br> +</div> + +<h4 class="subsection">17.4.3 <code>@value</code> Example</h4> + +<p>You can use the <code>@value</code> command to minimize the number of +places you need to change when you record an update to a manual. +See <a href="#GNU-Sample-Texts">GNU Sample Texts</a>, for the full text of an example of using this +to work with Automake distributions. + + <p>This example is adapted from <a href="make.html#Top">Overview (The GNU Make Manual)</a>. + + <ol type=1 start=1> +<li>Set the flags: + + <pre class="example"> @set EDITION 0.35 Beta + @set VERSION 3.63 Beta + @set UPDATED 14 August 1992 + @set UPDATE-MONTH August 1992 + </pre> + <li>Write text for the <code>@copying</code> section (see <a href="#copying">copying</a>): + + <pre class="example"> @copying + This is Edition @value{EDITION}, + last updated @value{UPDATED}, + of @cite{The GNU Make Manual}, + for @code{make}, version @value{VERSION}. + + Copyright ... + + Permission is granted ... + @end copying + </pre> + <li>Write text for the title page, for people reading the printed manual: + + <pre class="example"> @titlepage + @title GNU Make + @subtitle A Program for Directing Recompilation + @subtitle Edition @value{EDITION}, ... + @subtitle @value{UPDATE-MONTH} + @page + @insertcopying + ... + @end titlepage + </pre> + <p class="noindent">(On a printed cover, a date listing the month and the year looks less +fussy than a date listing the day as well as the month and year.) + + <li>Write text for the Top node, for people reading the Info file: + + <pre class="example"> @ifnottex + @node Top + @top Make + + @insertcopying + ... + @end ifnottex + </pre> + <p>After you format the manual, the <code>@value</code> constructs have been +expanded, so the output contains text like this: + + <pre class="example"> This is Edition 0.35 Beta, last updated 14 August 1992, + of `The GNU Make Manual', for `make', Version 3.63 Beta. + </pre> + </ol> + + <p>When you update the manual, you change only the values of the flags; you +do not need to edit the three sections. + +<div class="node"> +<p><hr> +<a name="Conditional-Nesting"></a>Previous: <a rel="previous" accesskey="p" href="#set-clear-value">set clear value</a>, +Up: <a rel="up" accesskey="u" href="#Conditionals">Conditionals</a> +<br> +</div> + +<h3 class="section">17.5 Conditional Nesting</h3> + +<p><a name="index-Conditionals_002c-nested-909"></a><a name="index-Nesting-conditionals-910"></a> +Conditionals can be nested; however, the details are a little tricky. +The difficulty comes with failing conditionals, such as +<code>@ifhtml</code> when HTML is not being produced, where the included +text is to be ignored. However, it is not to be <em>completely</em> +ignored, since it is useful to have one <code>@ifset</code> inside another, +for example—that is a way to include text only if two conditions are +met. Here's an example: + +<pre class="example"> @ifset somevar + @ifset anothervar + Both somevar and anothervar are set. + @end ifset + @ifclear anothervar + Somevar is set, anothervar is not. + @end ifclear + @end ifset +</pre> + <p>Technically, Texinfo requires that for a failing conditional, the +ignored text must be properly nested with respect to that failing +conditional. Unfortunately, it's not always feasible to check that +<em>all</em> conditionals are properly nested, because then the +processors could have to fully interpret the ignored text, which +defeats the purpose of the command. Here's an example illustrating +these rules: + +<pre class="example"> @ifset a + @ifset b + @ifclear ok - ok, ignored + @end junky - ok, ignored + @end ifset + @c WRONG - missing @end ifset. +</pre> + <p>Finally, as mentioned above, all conditional commands must be on lines +by themselves, with no text (even spaces) before or after. Otherwise, +the processors cannot reliably determine which commands to consider +for nesting purposes. + +<div class="node"> +<p><hr> +<a name="Internationalization"></a>Next: <a rel="next" accesskey="n" href="#Defining-New-Texinfo-Commands">Defining New Texinfo Commands</a>, +Previous: <a rel="previous" accesskey="p" href="#Conditionals">Conditionals</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> +<br> +</div> + +<h2 class="chapter">18 Internationalization</h2> + +<p><a name="index-Internationalization-911"></a>Texinfo has some support for writing in languages other than English, +although this area still needs considerable work. + + <p>For a list of the various accented and special characters Texinfo +supports, see <a href="#Inserting-Accents">Inserting Accents</a>. + +<ul class="menu"> +<li><a accesskey="1" href="#documentlanguage">documentlanguage</a>: Declaring the current language. +<li><a accesskey="2" href="#documentencoding">documentencoding</a>: Declaring the input encoding. +</ul> + +<div class="node"> +<p><hr> +<a name="documentlanguage"></a>Next: <a rel="next" accesskey="n" href="#documentencoding">documentencoding</a>, +Up: <a rel="up" accesskey="u" href="#Internationalization">Internationalization</a> +<br> +</div> + +<h3 class="section">18.1 <code>@documentlanguage </code><var>cc</var>: Set the Document Language</h3> + +<p><a name="index-documentlanguage-912"></a><a name="index-Language_002c-declaring-913"></a><a name="index-Document-language_002c-declaring-914"></a> +The <code>@documentlanguage</code> command declares the current document +language. Write it on a line by itself, with a two-letter ISO-639 +language code following (list is included below). If you have a +multilingual document, the intent is to be able to use this command +multiple times, to declare each language change. If the command is not +used at all, the default is <code>en</code> for English. + + <p><a name="index-_0040file_007btxi_002d_0040var_007bcc_007d_002etex_007d-915"></a>At present, this command is ignored in Info and HTML output. For +TeX, it causes the file <span class="file">txi-</span><var>cc</var><span class="file">.tex</span> to be read (if it +exists). Such a file appropriately redefines the various English words +used in TeX output, such as `Chapter', `See', and so on. + + <p><a name="index-Hyphenation-patterns_002c-language_002ddependent-916"></a>It would be good if this command also changed TeX's ideas of the +current hyphenation patterns (via the TeX primitive +<code>\language</code>), but this is unfortunately not currently implemented. + + <p><a name="index-ISO-639-codes-917"></a><a name="index-Language-codes-918"></a>Hereare the valid language codes, from ISO-639. + + <p><table summary=""><tr align="left"><td valign="top" width="7%"><code>aa</code> </td><td valign="top" width="26%">Afar </td><td valign="top" width="7%"> +<code>ab</code> </td><td valign="top" width="26%">Abkhazian </td><td valign="top" width="7%"> +<code>af</code> </td><td valign="top" width="26%">Afrikaans +<br></td></tr><tr align="left"><td valign="top" width="7%"><code>am</code> </td><td valign="top" width="26%">Amharic </td><td valign="top" width="7%"> +<code>ar</code> </td><td valign="top" width="26%">Arabic </td><td valign="top" width="7%"> +<code>as</code> </td><td valign="top" width="26%">Assamese +<br></td></tr><tr align="left"><td valign="top" width="7%"><code>ay</code> </td><td valign="top" width="26%">Aymara </td><td valign="top" width="7%"> +<code>az</code> </td><td valign="top" width="26%">Azerbaijani </td><td valign="top" width="7%"> +<code>ba</code> </td><td valign="top" width="26%">Bashkir +<br></td></tr><tr align="left"><td valign="top" width="7%"><code>be</code> </td><td valign="top" width="26%">Byelorussian </td><td valign="top" width="7%"> +<code>bg</code> </td><td valign="top" width="26%">Bulgarian </td><td valign="top" width="7%"> +<code>bh</code> </td><td valign="top" width="26%">Bihari +<br></td></tr><tr align="left"><td valign="top" width="7%"><code>bi</code> </td><td valign="top" width="26%">Bislama </td><td valign="top" width="7%"> +<code>bn</code> </td><td valign="top" width="26%">Bengali; Bangla </td><td valign="top" width="7%"> +<code>bo</code> </td><td valign="top" width="26%">Tibetan +<br></td></tr><tr align="left"><td valign="top" width="7%"><code>br</code> </td><td valign="top" width="26%">Breton </td><td valign="top" width="7%"> +<code>ca</code> </td><td valign="top" width="26%">Catalan </td><td valign="top" width="7%"> +<code>co</code> </td><td valign="top" width="26%">Corsican +<br></td></tr><tr align="left"><td valign="top" width="7%"><code>cs</code> </td><td valign="top" width="26%">Czech </td><td valign="top" width="7%"> +<code>cy</code> </td><td valign="top" width="26%">Welsh </td><td valign="top" width="7%"> +<code>da</code> </td><td valign="top" width="26%">Danish +<br></td></tr><tr align="left"><td valign="top" width="7%"><code>de</code> </td><td valign="top" width="26%">German </td><td valign="top" width="7%"> +<code>dz</code> </td><td valign="top" width="26%">Bhutani </td><td valign="top" width="7%"> +<code>el</code> </td><td valign="top" width="26%">Greek +<br></td></tr><tr align="left"><td valign="top" width="7%"><code>en</code> </td><td valign="top" width="26%">English </td><td valign="top" width="7%"> +<code>eo</code> </td><td valign="top" width="26%">Esperanto </td><td valign="top" width="7%"> +<code>es</code> </td><td valign="top" width="26%">Spanish +<br></td></tr><tr align="left"><td valign="top" width="7%"><code>et</code> </td><td valign="top" width="26%">Estonian </td><td valign="top" width="7%"> +<code>eu</code> </td><td valign="top" width="26%">Basque </td><td valign="top" width="7%"> +<code>fa</code> </td><td valign="top" width="26%">Persian +<br></td></tr><tr align="left"><td valign="top" width="7%"><code>fi</code> </td><td valign="top" width="26%">Finnish </td><td valign="top" width="7%"> +<code>fj</code> </td><td valign="top" width="26%">Fiji </td><td valign="top" width="7%"> +<code>fo</code> </td><td valign="top" width="26%">Faroese +<br></td></tr><tr align="left"><td valign="top" width="7%"><code>fr</code> </td><td valign="top" width="26%">French </td><td valign="top" width="7%"> +<code>fy</code> </td><td valign="top" width="26%">Frisian </td><td valign="top" width="7%"> +<code>ga</code> </td><td valign="top" width="26%">Irish +<br></td></tr><tr align="left"><td valign="top" width="7%"><code>gd</code> </td><td valign="top" width="26%">Scots Gaelic </td><td valign="top" width="7%"> +<code>gl</code> </td><td valign="top" width="26%">Galician </td><td valign="top" width="7%"> +<code>gn</code> </td><td valign="top" width="26%">Guarani +<br></td></tr><tr align="left"><td valign="top" width="7%"><code>gu</code> </td><td valign="top" width="26%">Gujarati </td><td valign="top" width="7%"> +<code>ha</code> </td><td valign="top" width="26%">Hausa </td><td valign="top" width="7%"> +<code>he</code> </td><td valign="top" width="26%">Hebrew +<br></td></tr><tr align="left"><td valign="top" width="7%"><code>hi</code> </td><td valign="top" width="26%">Hindi </td><td valign="top" width="7%"> +<code>hr</code> </td><td valign="top" width="26%">Croatian </td><td valign="top" width="7%"> +<code>hu</code> </td><td valign="top" width="26%">Hungarian +<br></td></tr><tr align="left"><td valign="top" width="7%"><code>hy</code> </td><td valign="top" width="26%">Armenian </td><td valign="top" width="7%"> +<code>ia</code> </td><td valign="top" width="26%">Interlingua </td><td valign="top" width="7%"> +<code>id</code> </td><td valign="top" width="26%">Indonesian +<br></td></tr><tr align="left"><td valign="top" width="7%"><code>ie</code> </td><td valign="top" width="26%">Interlingue </td><td valign="top" width="7%"> +<code>ik</code> </td><td valign="top" width="26%">Inupiak </td><td valign="top" width="7%"> +<code>is</code> </td><td valign="top" width="26%">Icelandic +<br></td></tr><tr align="left"><td valign="top" width="7%"><code>it</code> </td><td valign="top" width="26%">Italian </td><td valign="top" width="7%"> +<code>iu</code> </td><td valign="top" width="26%">Inuktitut </td><td valign="top" width="7%"> +<code>ja</code> </td><td valign="top" width="26%">Japanese +<br></td></tr><tr align="left"><td valign="top" width="7%"><code>jw</code> </td><td valign="top" width="26%">Javanese </td><td valign="top" width="7%"> +<code>ka</code> </td><td valign="top" width="26%">Georgian </td><td valign="top" width="7%"> +<code>kk</code> </td><td valign="top" width="26%">Kazakh +<br></td></tr><tr align="left"><td valign="top" width="7%"><code>kl</code> </td><td valign="top" width="26%">Greenlandic </td><td valign="top" width="7%"> +<code>km</code> </td><td valign="top" width="26%">Cambodian </td><td valign="top" width="7%"> +<code>kn</code> </td><td valign="top" width="26%">Kannada +<br></td></tr><tr align="left"><td valign="top" width="7%"><code>ks</code> </td><td valign="top" width="26%">Kashmiri </td><td valign="top" width="7%"> +<code>ko</code> </td><td valign="top" width="26%">Korean </td><td valign="top" width="7%"> +<code>ku</code> </td><td valign="top" width="26%">Kurdish +<br></td></tr><tr align="left"><td valign="top" width="7%"><code>ky</code> </td><td valign="top" width="26%">Kirghiz </td><td valign="top" width="7%"> +<code>la</code> </td><td valign="top" width="26%">Latin </td><td valign="top" width="7%"> +<code>ln</code> </td><td valign="top" width="26%">Lingala +<br></td></tr><tr align="left"><td valign="top" width="7%"><code>lt</code> </td><td valign="top" width="26%">Lithuanian </td><td valign="top" width="7%"> +<code>lo</code> </td><td valign="top" width="26%">Laothian </td><td valign="top" width="7%"> +<code>lv</code> </td><td valign="top" width="26%">Latvian, Lettish +<br></td></tr><tr align="left"><td valign="top" width="7%"><code>mg</code> </td><td valign="top" width="26%">Malagasy </td><td valign="top" width="7%"> +<code>mi</code> </td><td valign="top" width="26%">Maori </td><td valign="top" width="7%"> +<code>mk</code> </td><td valign="top" width="26%">Macedonian +<br></td></tr><tr align="left"><td valign="top" width="7%"><code>ml</code> </td><td valign="top" width="26%">Malayalam </td><td valign="top" width="7%"> +<code>mn</code> </td><td valign="top" width="26%">Mongolian </td><td valign="top" width="7%"> +<code>mo</code> </td><td valign="top" width="26%">Moldavian +<br></td></tr><tr align="left"><td valign="top" width="7%"><code>mr</code> </td><td valign="top" width="26%">Marathi </td><td valign="top" width="7%"> +<code>ms</code> </td><td valign="top" width="26%">Malay </td><td valign="top" width="7%"> +<code>mt</code> </td><td valign="top" width="26%">Maltese +<br></td></tr><tr align="left"><td valign="top" width="7%"><code>my</code> </td><td valign="top" width="26%">Burmese </td><td valign="top" width="7%"> +<code>na</code> </td><td valign="top" width="26%">Nauru </td><td valign="top" width="7%"> +<code>ne</code> </td><td valign="top" width="26%">Nepali +<br></td></tr><tr align="left"><td valign="top" width="7%"><code>nl</code> </td><td valign="top" width="26%">Dutch </td><td valign="top" width="7%"> +<code>no</code> </td><td valign="top" width="26%">Norwegian </td><td valign="top" width="7%"> +<code>oc</code> </td><td valign="top" width="26%">Occitan +<br></td></tr><tr align="left"><td valign="top" width="7%"><code>om</code> </td><td valign="top" width="26%">(Afan) Oromo </td><td valign="top" width="7%"> +<code>or</code> </td><td valign="top" width="26%">Oriya </td><td valign="top" width="7%"> +<code>pa</code> </td><td valign="top" width="26%">Punjabi +<br></td></tr><tr align="left"><td valign="top" width="7%"><code>pl</code> </td><td valign="top" width="26%">Polish </td><td valign="top" width="7%"> +<code>ps</code> </td><td valign="top" width="26%">Pashto, Pushto </td><td valign="top" width="7%"> +<code>pt</code> </td><td valign="top" width="26%">Portuguese +<br></td></tr><tr align="left"><td valign="top" width="7%"><code>qu</code> </td><td valign="top" width="26%">Quechua </td><td valign="top" width="7%"> +<code>rm</code> </td><td valign="top" width="26%">Rhaeto-Romance </td><td valign="top" width="7%"> +<code>rn</code> </td><td valign="top" width="26%">Kirundi +<br></td></tr><tr align="left"><td valign="top" width="7%"><code>ro</code> </td><td valign="top" width="26%">Romanian </td><td valign="top" width="7%"> +<code>ru</code> </td><td valign="top" width="26%">Russian </td><td valign="top" width="7%"> +<code>rw</code> </td><td valign="top" width="26%">Kinyarwanda +<br></td></tr><tr align="left"><td valign="top" width="7%"><code>sa</code> </td><td valign="top" width="26%">Sanskrit </td><td valign="top" width="7%"> +<code>sd</code> </td><td valign="top" width="26%">Sindhi </td><td valign="top" width="7%"> +<code>sg</code> </td><td valign="top" width="26%">Sangro +<br></td></tr><tr align="left"><td valign="top" width="7%"><code>sh</code> </td><td valign="top" width="26%">Serbo-Croatian </td><td valign="top" width="7%"> +<code>si</code> </td><td valign="top" width="26%">Sinhalese </td><td valign="top" width="7%"> +<code>sk</code> </td><td valign="top" width="26%">Slovak +<br></td></tr><tr align="left"><td valign="top" width="7%"><code>sl</code> </td><td valign="top" width="26%">Slovenian </td><td valign="top" width="7%"> +<code>sm</code> </td><td valign="top" width="26%">Samoan </td><td valign="top" width="7%"> +<code>sn</code> </td><td valign="top" width="26%">Shona +<br></td></tr><tr align="left"><td valign="top" width="7%"><code>so</code> </td><td valign="top" width="26%">Somali </td><td valign="top" width="7%"> +<code>sq</code> </td><td valign="top" width="26%">Albanian </td><td valign="top" width="7%"> +<code>sr</code> </td><td valign="top" width="26%">Serbian +<br></td></tr><tr align="left"><td valign="top" width="7%"><code>ss</code> </td><td valign="top" width="26%">Siswati </td><td valign="top" width="7%"> +<code>st</code> </td><td valign="top" width="26%">Sesotho </td><td valign="top" width="7%"> +<code>su</code> </td><td valign="top" width="26%">Sundanese +<br></td></tr><tr align="left"><td valign="top" width="7%"><code>sv</code> </td><td valign="top" width="26%">Swedish </td><td valign="top" width="7%"> +<code>sw</code> </td><td valign="top" width="26%">Swahili </td><td valign="top" width="7%"> +<code>ta</code> </td><td valign="top" width="26%">Tamil +<br></td></tr><tr align="left"><td valign="top" width="7%"><code>te</code> </td><td valign="top" width="26%">Telugu </td><td valign="top" width="7%"> +<code>tg</code> </td><td valign="top" width="26%">Tajik </td><td valign="top" width="7%"> +<code>th</code> </td><td valign="top" width="26%">Thai +<br></td></tr><tr align="left"><td valign="top" width="7%"><code>ti</code> </td><td valign="top" width="26%">Tigrinya </td><td valign="top" width="7%"> +<code>tk</code> </td><td valign="top" width="26%">Turkmen </td><td valign="top" width="7%"> +<code>tl</code> </td><td valign="top" width="26%">Tagalog +<br></td></tr><tr align="left"><td valign="top" width="7%"><code>tn</code> </td><td valign="top" width="26%">Setswana </td><td valign="top" width="7%"> +<code>to</code> </td><td valign="top" width="26%">Tonga </td><td valign="top" width="7%"> +<code>tr</code> </td><td valign="top" width="26%">Turkish +<br></td></tr><tr align="left"><td valign="top" width="7%"><code>ts</code> </td><td valign="top" width="26%">Tsonga </td><td valign="top" width="7%"> +<code>tt</code> </td><td valign="top" width="26%">Tatar </td><td valign="top" width="7%"> +<code>tw</code> </td><td valign="top" width="26%">Twi +<br></td></tr><tr align="left"><td valign="top" width="7%"><code>ug</code> </td><td valign="top" width="26%">Uighur </td><td valign="top" width="7%"> +<code>uk</code> </td><td valign="top" width="26%">Ukrainian </td><td valign="top" width="7%"> +<code>ur</code> </td><td valign="top" width="26%">Urdu +<br></td></tr><tr align="left"><td valign="top" width="7%"><code>uz</code> </td><td valign="top" width="26%">Uzbek </td><td valign="top" width="7%"> +<code>vi</code> </td><td valign="top" width="26%">Vietnamese </td><td valign="top" width="7%"> +<code>vo</code> </td><td valign="top" width="26%">Volapuk +<br></td></tr><tr align="left"><td valign="top" width="7%"><code>wo</code> </td><td valign="top" width="26%">Wolof </td><td valign="top" width="7%"> +<code>xh</code> </td><td valign="top" width="26%">Xhosa </td><td valign="top" width="7%"> +<code>yi</code> </td><td valign="top" width="26%">Yiddish +<br></td></tr><tr align="left"><td valign="top" width="7%"><code>yo</code> </td><td valign="top" width="26%">Yoruba </td><td valign="top" width="7%"> +<code>za</code> </td><td valign="top" width="26%">Zhuang </td><td valign="top" width="7%"> +<code>zh</code> </td><td valign="top" width="26%">Chinese +<br></td></tr><tr align="left"><td valign="top" width="7%"><code>zu</code> </td><td valign="top" width="26%">Zulu + <br></td></tr></table> + +<div class="node"> +<p><hr> +<a name="documentencoding"></a>Previous: <a rel="previous" accesskey="p" href="#documentlanguage">documentlanguage</a>, +Up: <a rel="up" accesskey="u" href="#Internationalization">Internationalization</a> +<br> +</div> + +<h3 class="section">18.2 <code>@documentencoding </code><var>enc</var>: Set Input Encoding</h3> + +<p><a name="index-documentencoding-919"></a><a name="index-Encoding_002c-declaring-920"></a><a name="index-Input-encoding_002c-declaring-921"></a><a name="index-Character-set_002c-declaring-922"></a><a name="index-Document-input-encoding-923"></a> +The <code>@documentencoding</code> command declares the input document +encoding. Write it on a line by itself, with a valid encoding +specification following. + + <p>At present, Texinfo supports only three encodings: + + <dl> +<dt><code>US-ASCII</code><dd>This has no particular effect, but it's included for completeness. +<dt><code>ISO-8859-1</code><br><dt><code>ISO-8859-2</code><dd>These specify the standard encodings for Western European and +Eastern European languages, respectively. A full description of the +encodings is beyond our scope here; +<a href="http://czyborra.com/charsets/iso8859.html">http://czyborra.com/charsets/iso8859.html</a> is one of many useful +references. +</dl> + + <p>Specifying an encoding <var>enc</var> has the following effects: + + <p><a name="index-_002d_002denable_002dencoding-924"></a><a name="index-Local-Variables_003a-section_002c-for-encoding-925"></a><a name="index-Info-output_002c-and-encoding-926"></a>In Info output, if the option <span class="option">--enable-encoding</span> is also given +to <span class="command">makeinfo</span>, a so-called `Local Variables' section +(see <a href="emacs.html#File-Variables">File Variables (The GNU Emacs Manual)</a>) is output +including <var>enc</var>. This allows Info readers to set the encoding +appropriately: + +<pre class="example"> Local Variables: + coding: <var>enc</var> + End: +</pre> + <p><a name="index-HTML-output_002c-and-encodings-927"></a><a name="index-_0040code_007bhttp_002dequiv_007d_002c-and-charset-specification-928"></a><a name="index-_0040code_007b_003cmeta_003e_007d-HTML-tag_002c-and-charset-specification-929"></a>In HTML output, a <span class="samp"><meta></span> tag is output, in the <span class="samp"><head></span> +section of the HTML, that specifies <var>enc</var>. Web servers and +browsers cooperate to use this information so the correct encoding is +used to display the page. + +<pre class="example"> <meta http-equiv="Content-Type" content="text/html; + charset=<var>enc</var>"> +</pre> + <p>In all other cases, it is recognized but ignored. + +<div class="node"> +<p><hr> +<a name="Defining-New-Texinfo-Commands"></a>Next: <a rel="next" accesskey="n" href="#Hardcopy">Hardcopy</a>, +Previous: <a rel="previous" accesskey="p" href="#Internationalization">Internationalization</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> +<br> +</div> + +<h2 class="chapter">19 Defining New Texinfo Commands</h2> + +<p><a name="index-Macros-930"></a><a name="index-Defining-new-Texinfo-commands-931"></a><a name="index-New-Texinfo-commands_002c-defining-932"></a><a name="index-Texinfo-commands_002c-defining-new-933"></a><a name="index-User_002ddefined-Texinfo-commands-934"></a> +Texinfo provides several ways to define new commands: + + <ul> +<li>A Texinfo <dfn>macro</dfn> allows you to define a new Texinfo command as any +sequence of text and/or existing commands (including other macros). The +macro can have any number of <dfn>parameters</dfn>—text you supply each +time you use the macro. + + <p>Incidentally, these macros have nothing to do with the <code>@defmac</code> +command, which is for documenting macros in the subject of the manual +(see <a href="#Def-Cmd-Template">Def Cmd Template</a>). + + <li><span class="samp">@alias</span> is a convenient way to define a new name for an existing +command. + + <li><span class="samp">@definfoenclose</span> allows you to define new commands with +customized output in the Info file. + + </ul> + +<ul class="menu"> +<li><a accesskey="1" href="#Defining-Macros">Defining Macros</a>: Defining and undefining new commands. +<li><a accesskey="2" href="#Invoking-Macros">Invoking Macros</a>: Using a macro, once you've defined it. +<li><a accesskey="3" href="#Macro-Details">Macro Details</a>: Limitations of Texinfo macros. +<li><a accesskey="4" href="#alias">alias</a>: Command aliases. +<li><a accesskey="5" href="#definfoenclose">definfoenclose</a>: Customized highlighting. +</ul> + +<div class="node"> +<p><hr> +<a name="Defining-Macros"></a>Next: <a rel="next" accesskey="n" href="#Invoking-Macros">Invoking Macros</a>, +Up: <a rel="up" accesskey="u" href="#Defining-New-Texinfo-Commands">Defining New Texinfo Commands</a> +<br> +</div> + +<h3 class="section">19.1 Defining Macros</h3> + +<p><a name="index-Defining-macros-935"></a><a name="index-Macro-definitions-936"></a> +<a name="index-macro-937"></a>You use the Texinfo <code>@macro</code> command to define a macro, like this: + +<pre class="example"> @macro <var>macroname</var>{<var>param1</var>, <var>param2</var>, ...} + <var>text</var> ... \<var>param1</var>\ ... + @end macro +</pre> + <p>The <dfn>parameters</dfn> <var>param1</var>, <var>param2</var>, <small class="dots">...</small> correspond to +arguments supplied when the macro is subsequently used in the document +(described in the next section). + + <p><a name="index-Macro-names_002c-valid-characters-in-938"></a><a name="index-Names-of-macros_002c-valid-characters-of-939"></a>For a macro to work consistently with TeX, <var>macroname</var> must +consist entirely of letters: no digits, hyphens, underscores, or other +special characters. So, we recommend using only letters. However, +<span class="command">makeinfo</span> will accept anything except <span class="samp">{}_^=</span>; +<span class="samp">_</span> and <span class="samp">^</span> are excluded so that macros can be called in +<code>@math</code> mode without a following space +(see <a href="#math"><code>@math</code></a>). + + <p>If a macro needs no parameters, you can define it either with an empty +list (<span class="samp">@macro foo {}</span>) or with no braces at all (<span class="samp">@macro +foo</span>). + + <p><a name="index-Body-of-a-macro-940"></a><a name="index-Mutually-recursive-macros-941"></a><a name="index-Recursion_002c-mutual-942"></a>The definition or <dfn>body</dfn> of the macro can contain most Texinfo +commands, including previously-defined macros. Not-yet-defined macro +invocations are not allowed; thus, it is not possible to have mutually +recursive Texinfo macros. Also, a macro definition that defines another +macro does not work in TeX due to limitations in the design of +<code>@macro</code>. + + <p><a name="index-Parameters-to-macros-943"></a>In the macro body, instances of a parameter name surrounded by +backslashes, as in <span class="samp">\</span><var>param1</var><span class="samp">\</span> in the example above, are +replaced by the corresponding argument from the macro invocation. You +can use parameter names any number of times in the body, including zero. + + <p><a name="index-Backslash-in-macros-944"></a>To get a single <span class="samp">\</span> in the macro expansion, use <span class="samp">\\</span>. Any +other use of <span class="samp">\</span> in the body yields a warning. + + <p><a name="index-Spaces-in-macros-945"></a><a name="index-Whitespace-in-macros-946"></a>The newlines after the <code>@macro</code> line and before the <code>@end +macro</code> line are ignored, that is, not included in the macro body. All +other whitespace is treated according to the usual Texinfo rules. + + <p><a name="index-Recursive-macro-invocations-947"></a><a name="index-rmacro-948"></a>To allow a macro to be used recursively, that is, in an argument to a +call to itself, you must define it with <span class="samp">@rmacro</span>, like this: + +<pre class="example"> @rmacro rmac {arg} + a\arg\b + @end rmacro + ... + @rmac{1@rmac{text}2} +</pre> + <p>This produces the output `a1atextb2b'. With <span class="samp">@macro</span> instead of +<span class="samp">@rmacro</span>, an error message is given. + + <p><a name="index-unmacro-949"></a><a name="index-Macros_002c-undefining-950"></a><a name="index-Undefining-macros-951"></a>You can undefine a macro <var>foo</var> with <code>@unmacro </code><var>foo</var>. +It is not an error to undefine a macro that is already undefined. +For example: + +<pre class="example"> @unmacro foo +</pre> + <div class="node"> +<p><hr> +<a name="Invoking-Macros"></a>Next: <a rel="next" accesskey="n" href="#Macro-Details">Macro Details</a>, +Previous: <a rel="previous" accesskey="p" href="#Defining-Macros">Defining Macros</a>, +Up: <a rel="up" accesskey="u" href="#Defining-New-Texinfo-Commands">Defining New Texinfo Commands</a> +<br> +</div> + +<h3 class="section">19.2 Invoking Macros</h3> + +<p><a name="index-Invoking-macros-952"></a><a name="index-Expanding-macros-953"></a><a name="index-Running-macros-954"></a><a name="index-Macro-invocation-955"></a> +After a macro is defined (see the previous section), you can use +(<dfn>invoke</dfn>) it in your document like this: + +<pre class="example"> @<var>macroname</var> {<var>arg1</var>, <var>arg2</var>, ...} +</pre> + <p class="noindent">and the result will be just as if you typed the body of +<var>macroname</var> at that spot. For example: + +<pre class="example"> @macro foo {p, q} + Together: \p\ & \q\. + @end macro + @foo{a, b} +</pre> + <p class="noindent">produces: + +<pre class="display"> Together: a & b. +</pre> + <p><a name="index-Backslash_002c-and-macros-956"></a>Thus, the arguments and parameters are separated by commas and delimited +by braces; any whitespace after (but not before) a comma is ignored. +The braces are required in the invocation (but not the definition), even +when the macro takes no arguments, consistent with all other Texinfo +commands. For example: + +<pre class="example"> @macro argless {} + No arguments here. + @end macro + @argless{} +</pre> + <p class="noindent">produces: + +<pre class="display"> No arguments here. +</pre> + <p><a name="index-Comma_002c-in-macro-arguments-957"></a><a name="index-Braces_002c-in-macro-arguments-958"></a>To insert a comma, brace, or backslash in an argument, prepend a +backslash, as in + +<pre class="example"> @<var>macname</var> {\\\{\}\,} +</pre> + <p class="noindent">which will pass the (almost certainly error-producing) argument +<span class="samp">\{},</span> to <var>macname</var>. However, commas in parameters, even +if escaped by a backslash, might cause trouble in TeX. + + <p>If the macro is defined to take a single argument, and is invoked +without any braces, the entire rest of the line after the macro name is +supplied as the argument. For example: + +<pre class="example"> @macro bar {p} + Twice: \p\ & \p\. + @end macro + @bar aah +</pre> + <p class="noindent">produces: + +<!-- Sorry for cheating, but let's not require macros to process the manual. --> +<pre class="display"> Twice: aah & aah. +</pre> + <p>If the macro is defined to take a single argument, and is invoked with +braces, the braced text is passed as the argument, regardless of +commas. For example: + +<pre class="example"> @macro bar {p} + Twice: \p\ & \p\. + @end macro + @bar{a,b} +</pre> + <p class="noindent">produces: + +<pre class="display"> Twice: a,b & a,b. +</pre> + <div class="node"> +<p><hr> +<a name="Macro-Details"></a>Next: <a rel="next" accesskey="n" href="#alias">alias</a>, +Previous: <a rel="previous" accesskey="p" href="#Invoking-Macros">Invoking Macros</a>, +Up: <a rel="up" accesskey="u" href="#Defining-New-Texinfo-Commands">Defining New Texinfo Commands</a> +<br> +</div> + +<h3 class="section">19.3 Macro Details</h3> + +<p><a name="index-Macro-details-959"></a><a name="index-Details-of-macro-usage-960"></a> +Due to unavoidable limitations, certain macro-related constructs cause +problems with TeX. If you get macro-related errors when producing +the printed version of a manual, try expanding the macros with +<span class="command">makeinfo</span> by invoking <span class="command">texi2dvi</span> with the <span class="samp">-E</span> +option (see <a href="#Format-with-texi2dvi">Format with texi2dvi</a>). + + <ul> +<li>As mentioned earlier, macro names must consist entirely of letters. + + <li>It is not advisable to redefine any TeX primitive, plain, or +Texinfo command name as a macro. Unfortunately this is a very large +set of names, and the possible resulting errors are completely random. + + <li>All macros are expanded inside at least one TeX group. This means +that <code>@set</code> and other such commands have no effect inside a +macro. + + <li>Macros containing a command which must be on a line by itself, such as a +conditional, cannot be invoked in the middle of a line. + + <li>Commas in macro arguments, even if escaped by a backslash, don't +always work. + + <li>It is best to avoid comments inside macro definitions. + + <li>Macro arguments cannot cross lines. + + <li>Macros cannot define macros in the natural way. To do this, you must +use conditionals and raw TeX. For example: + + <pre class="example"> @ifnottex + @macro ctor {name, arg} + @macro \name\ + something involving \arg\ somehow + @end macro + @end macro + @end ifnottex + @tex + \gdef\ctor#1{\ctorx#1,} + \gdef\ctorx#1,#2,{\def#1{something involving #2 somehow}} + @end tex + </pre> + </ul> + + <p>The <span class="command">makeinfo</span> implementation also has limitations: + + <ul> +<li><code>@verbatim</code> and macros do not mix; for instance, you can't start +a verbatim block inside a macro and end it outside. +(See <a href="#verbatim">verbatim</a>.) Starting any environment inside a macro and ending +it outside may or may not work, for that matter. + + <li>Macros that completely define macros are ok, but it's not possible to +have incorrectly nested macro definitions. That is, <code>@macro</code> +and <code>@end macro</code> (likewise for <code>@rmacro</code>) must be +correctly paired. For example, you cannot start a macro definition +within a macro, and then end the nested definition outside the macro. + + <li><code>@rmacro</code> is a kludge. + + </ul> + + <p>One more limitation is common to both implementations: white space is +ignored at the beginnings of lines. + + <p>Future major revisions of Texinfo may ease some of these limitations +(by introducing a new macro syntax). + +<div class="node"> +<p><hr> +<a name="alias"></a>Next: <a rel="next" accesskey="n" href="#definfoenclose">definfoenclose</a>, +Previous: <a rel="previous" accesskey="p" href="#Macro-Details">Macro Details</a>, +Up: <a rel="up" accesskey="u" href="#Defining-New-Texinfo-Commands">Defining New Texinfo Commands</a> +<br> +</div> + +<h3 class="section">19.4 <span class="samp">@alias </span><var>new</var><span class="samp">=</span><var>existing</var></h3> + +<p><a name="index-Aliases_002c-command-961"></a><a name="index-Command-aliases-962"></a><a name="index-alias-963"></a> +The <span class="samp">@alias</span> command defines a new command to be just like an +existing one. This is useful for defining additional markup names, thus +preserving semantic information in the input even though the output +result may be the same. + + <p>Write the <span class="samp">@alias</span> command on a line by itself, followed by the +new command name, an equals sign, and the existing command name. +Whitespace around the equals sign is ignored. Thus: +<pre class="example"> @alias <var>new</var> = <var>existing</var> +</pre> + <p>For example, if your document contains citations for both books and +some other media (movies, for example), you might like to define a +macro <code>@moviecite{}</code> that does the same thing as an ordinary +<code>@cite{}</code> but conveys the extra semantic information as well. +You'd do this as follows: + +<pre class="example"> @alias moviecite = cite +</pre> + <p>Macros do not always have the same effect as aliases, due to vagaries +of argument parsing. Also, aliases are much simpler to define than +macros. So the command is not redundant. (It was also heavily used +in the Jargon File!) + + <p>Aliases must not be recursive, directly or indirectly. + + <p>It is not advisable to redefine any TeX primitive, plain, or +Texinfo command name as an alias. Unfortunately this is a very large +set of names, and the possible resulting errors are completely random. + +<div class="node"> +<p><hr> +<a name="definfoenclose"></a>Previous: <a rel="previous" accesskey="p" href="#alias">alias</a>, +Up: <a rel="up" accesskey="u" href="#Defining-New-Texinfo-Commands">Defining New Texinfo Commands</a> +<br> +</div> + +<h3 class="section">19.5 <span class="samp">definfoenclose</span>: Customized Highlighting</h3> + +<p><a name="index-Highlighting_002c-customized-964"></a><a name="index-Customized-highlighting-965"></a><a name="index-definfoenclose-966"></a> +A <code>@definfoenclose</code> command may be used to define a highlighting +command for Info, but not for TeX. A command defined using +<code>@definfoenclose</code> marks text by enclosing it in strings that +precede and follow the text. You can use this to get closer control of +your Info output. + + <p>Presumably, if you define a command with <code>@definfoenclose</code> for Info, +you will create a corresponding command for TeX, either in +<span class="file">texinfo.tex</span>, <span class="file">texinfo.cnf</span>, or within an <span class="samp">@iftex</span> in +your document. + + <p>Write a <code>@definfoenclose</code> command on a line and follow it with +three arguments separated by commas. The first argument to +<code>@definfoenclose</code> is the @-command name (without the <code>@</code>); +the second argument is the Info start delimiter string; and the third +argument is the Info end delimiter string. The latter two arguments +enclose the highlighted text in the Info file. A delimiter string may +contain spaces. Neither the start nor end delimiter is required. If +you do not want a start delimiter but do want an end delimiter, you must +follow the command name with two commas in a row; otherwise, the Info +formatting commands will naturally misinterpret the end delimiter string +you intended as the start delimiter string. + + <p>If you do a <code>@definfoenclose</code> on the name of a pre-defined macro +(such as <code>@emph</code>, <code>@strong</code>, <code>@t</code>, or <code>@i</code>), the +enclosure definition will override the built-in definition. + + <p>An enclosure command defined this way takes one argument in braces; this +is intended for new markup commands (see <a href="#Marking-Text">Marking Text</a>). + + <p><a name="index-phoo-967"></a>For example, you can write: + +<pre class="example"> @definfoenclose phoo,//,\\ +</pre> + <p class="noindent">near the beginning of a Texinfo file to define <code>@phoo</code> as an Info +formatting command that inserts `//' before and `\\' after the argument +to <code>@phoo</code>. You can then write <code>@phoo{bar}</code> wherever you +want `//bar\\' highlighted in Info. + + <p>Also, for TeX formatting, you could write + +<pre class="example"> @iftex + @global@let@phoo=@i + @end iftex +</pre> + <p class="noindent">to define <code>@phoo</code> as a command that causes TeX to typeset the +argument to <code>@phoo</code> in italics. + + <p>Each definition applies to its own formatter: one for TeX, the other +for <code>texinfo-format-buffer</code> or <code>texinfo-format-region</code>. The +<code>@definfoenclose</code> command need not be within <span class="samp">@ifinfo</span>, but +the raw TeX commands do need to be in <span class="samp">@iftex</span>. + + <p><a name="index-headword-968"></a>Here is another example: write + +<pre class="example"> @definfoenclose headword, , : +</pre> + <p class="noindent">near the beginning of the file, to define <code>@headword</code> as an Info +formatting command that inserts nothing before and a colon after the +argument to <code>@headword</code>. + + <p><span class="samp">@definfoenclose</span> definitions must not be recursive, directly or +indirectly. + +<div class="node"> +<p><hr> +<a name="Hardcopy"></a>Next: <a rel="next" accesskey="n" href="#Creating-and-Installing-Info-Files">Creating and Installing Info Files</a>, +Previous: <a rel="previous" accesskey="p" href="#Defining-New-Texinfo-Commands">Defining New Texinfo Commands</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> +<br> +</div> + +<h2 class="chapter">20 Formatting and Printing Hardcopy</h2> + +<p><a name="index-Format-and-print-hardcopy-969"></a><a name="index-Printing-hardcopy-970"></a><a name="index-Hardcopy_002c-printing-it-971"></a><a name="index-Making-a-printed-manual-972"></a><a name="index-Sorting-indices-973"></a><a name="index-Indices_002c-sorting-974"></a><a name="index-_0040TeX_007b_007d-index-sorting-975"></a><a name="index-texindex-976"></a> +There are three major shell commands for making a printed manual from a +Texinfo file: one for converting the Texinfo file into a file that will be +printed, a second for sorting indices, and a third for printing the +formatted document. When you use the shell commands, you can either +work directly in the operating system shell or work within a shell +inside GNU Emacs. + + <p>If you are using GNU Emacs, you can use commands provided by Texinfo +mode instead of shell commands. In addition to the three commands to +format a file, sort the indices, and print the result, Texinfo mode +offers key bindings for commands to recenter the output buffer, show the +print queue, and delete a job from the print queue. + +<ul class="menu"> +<li><a accesskey="1" href="#Use-TeX">Use TeX</a>: Use TeX to format for hardcopy. +<li><a accesskey="2" href="#Format-with-tex_002ftexindex">Format with tex/texindex</a>: How to format with explicit shell commands. +<li><a accesskey="3" href="#Format-with-texi2dvi">Format with texi2dvi</a>: A simpler way to format. +<li><a accesskey="4" href="#Print-with-lpr">Print with lpr</a>: How to print. +<li><a accesskey="5" href="#Within-Emacs">Within Emacs</a>: How to format and print from an Emacs shell. +<li><a accesskey="6" href="#Texinfo-Mode-Printing">Texinfo Mode Printing</a>: How to format and print in Texinfo mode. +<li><a accesskey="7" href="#Compile_002dCommand">Compile-Command</a>: How to print using Emacs's compile command. +<li><a accesskey="8" href="#Requirements-Summary">Requirements Summary</a>: TeX formatting requirements summary. +<li><a accesskey="9" href="#Preparing-for-TeX">Preparing for TeX</a>: What to do before you use TeX. +<li><a href="#Overfull-hboxes">Overfull hboxes</a>: What are and what to do with overfull hboxes. +<li><a href="#smallbook">smallbook</a>: How to print small format books and manuals. +<li><a href="#A4-Paper">A4 Paper</a>: How to print on A4 or A5 paper. +<li><a href="#pagesizes">pagesizes</a>: How to print with customized page sizes. +<li><a href="#Cropmarks-and-Magnification">Cropmarks and Magnification</a>: How to print marks to indicate the size + of pages and how to print scaled up output. +<li><a href="#PDF-Output">PDF Output</a>: Portable Document Format output. +<li><a href="#Obtaining-TeX">Obtaining TeX</a>: How to Obtain TeX. +</ul> + +<div class="node"> +<p><hr> +<a name="Use-TeX"></a>Next: <a rel="next" accesskey="n" href="#Format-with-tex_002ftexindex">Format with tex/texindex</a>, +Up: <a rel="up" accesskey="u" href="#Hardcopy">Hardcopy</a> +<br> +</div> + +<h3 class="section">20.1 Use TeX</h3> + +<p>The typesetting program called TeX is used for formatting a Texinfo +file. TeX is a very powerful typesetting program and, if used correctly, +does an exceptionally good job. (See <a href="#Obtaining-TeX">How to Obtain TeX</a>, for information on how to obtain TeX.) + + <p>The standalone <code>makeinfo</code> program and Emacs functions +<code>texinfo-format-region</code> and <code>texinfo-format-buffer</code> commands +read the very same @-commands in the Texinfo file as does TeX, but +process them differently to make an Info file (see <a href="#Creating-an-Info-File">Creating an Info File</a>). + +<div class="node"> +<p><hr> +<a name="Format-with-tex_002ftexindex"></a>Next: <a rel="next" accesskey="n" href="#Format-with-texi2dvi">Format with texi2dvi</a>, +Previous: <a rel="previous" accesskey="p" href="#Use-TeX">Use TeX</a>, +Up: <a rel="up" accesskey="u" href="#Hardcopy">Hardcopy</a> +<br> +</div> + +<h3 class="section">20.2 Format with <code>tex</code> and <code>texindex</code></h3> + +<p><a name="index-Shell-formatting-with-_0040code_007btex_007d-and-_0040code_007btexindex_007d-977"></a><a name="index-Formatting-with-_0040code_007btex_007d-and-_0040code_007btexindex_007d-978"></a><a name="index-DVI-file-979"></a> +You can format the Texinfo file with the shell command <code>tex</code> +followed by the name of the Texinfo file. For example: + +<pre class="example"> tex foo.texi +</pre> + <p class="noindent">TeX will produce a <dfn>DVI file</dfn> as well as several auxiliary +files containing information for indices, cross references, etc. The +DVI file (for <dfn>DeVice Independent</dfn> file) can be printed on virtually +any device (see the following sections). + + <p><a name="index-texindex-980"></a>The <code>tex</code> formatting command itself does not sort the indices; it +writes an output file of unsorted index data. (The <code>texi2dvi</code> +command automatically generates indices; see <a href="#Format-with-texi2dvi">Format with <code>texi2dvi</code></a>.) To generate a printed index after +running the <code>tex</code> command, you first need a sorted index to work +from. The <code>texindex</code> command sorts indices. (The source file +<span class="file">texindex.c</span> comes as part of the standard Texinfo distribution, +among other places.) + + <p><a name="index-Names-of-index-files-981"></a><a name="index-Index-file-names-982"></a>The <code>tex</code> formatting command outputs unsorted index files under +names that obey a standard convention: the name of your main input file +with any <span class="samp">.tex</span> (or similar, see <a href="web2c.html#tex-invocation">tex invocation (Web2c)</a>) extension removed, followed by the two letter names of indices. +For example, the raw index output files for the input file +<span class="file">foo.texinfo</span> would be <span class="file">foo.cp</span>, <span class="file">foo.vr</span>, <span class="file">foo.fn</span>, +<span class="file">foo.tp</span>, <span class="file">foo.pg</span> and <span class="file">foo.ky</span>. Those are exactly the +arguments to give to <code>texindex</code>. + + <p><a name="index-Wildcards-983"></a><a name="index-Globbing-984"></a>Instead of specifying all the unsorted index file names explicitly, you +can use <span class="samp">??</span> as shell wildcards and give the command in this +form: + +<pre class="example"> texindex foo.?? +</pre> + <p class="noindent">This command will run <code>texindex</code> on all the unsorted index files, +including any that you have defined yourself using <code>@defindex</code> +or <code>@defcodeindex</code>. (You may execute <span class="samp">texindex foo.??</span> +even if there are similarly named files with two letter extensions +that are not index files, such as <span class="samp">foo.el</span>. The <code>texindex</code> +command reports but otherwise ignores such files.) + + <p>For each file specified, <code>texindex</code> generates a sorted index file +whose name is made by appending <span class="samp">s</span> to the input file name. The +<code>@printindex</code> command looks for a file with that name +(see <a href="#Printing-Indices-_0026-Menus">Printing Indices & Menus</a>). <code>texindex</code> does not alter the +raw index output file. + + <p>After you have sorted the indices, you need to rerun <code>tex</code> on the +Texinfo file. This regenerates the DVI file, this time with +up-to-date index entries. + + <p>Finally, you may need to run <code>tex</code> one more time, to get the page +numbers in the cross-references correct. + + <p>To summarize, this is a five step process: + + <ol type=1 start=1> +<li>Run <code>tex</code> on your Texinfo file. This generates a DVI file (with +undefined cross-references and no indices), and the raw index files +(with two letter extensions). + + <li>Run <code>texindex</code> on the raw index files. This creates the +corresponding sorted index files (with three letter extensions). + + <li>Run <code>tex</code> again on your Texinfo file. This regenerates the DVI +file, this time with indices and defined cross-references, but with page +numbers for the cross-references from last time, generally incorrect. + + <li>Sort the indices again, with <code>texindex</code>. + + <li>Run <code>tex</code> one last time. This time the correct page numbers are +written for the cross-references. + </ol> + + <p><a name="index-texi2dvi-985"></a>Alternatively, it's a one-step process: run <code>texi2dvi</code> +(see <a href="#Format-with-texi2dvi">Format with texi2dvi</a>). + + <p>You need not run <code>texindex</code> each time after you run <code>tex</code>. If +you do not, on the next run, the <code>tex</code> formatting command will use +whatever sorted index files happen to exist from the previous use of +<code>texindex</code>. This is usually ok while you are debugging. + + <p><a name="index-Auxiliary-files_002c-avoiding-986"></a><a name="index-novalidate-987"></a><a name="index-Pointer-validation_002c-suppressing-988"></a><a name="index-Chapters_002c-formatting-one-at-a-time-989"></a>Sometimes you may wish to print a document while you know it is +incomplete, or to print just one chapter of a document. In that case, +the usual auxiliary files that TeX creates and warnings TeX gives +when cross-references are not satisfied are just nuisances. You can +avoid them with the <code>@novalidate</code> command, which you must give +<em>before</em> the <code>@setfilename</code> command +(see <a href="#setfilename"><code>@setfilename</code></a>). Thus, the beginning of +your file would look approximately like this: + +<pre class="example"> \input texinfo + @novalidate + @setfilename myfile.info + ... +</pre> + <p class="noindent"><code>@novalidate</code> also turns off validation in +<code>makeinfo</code>, just like its <code>--no-validate</code> option +(see <a href="#Pointer-Validation">Pointer Validation</a>). + +<div class="node"> +<p><hr> +<a name="Format-with-texi2dvi"></a>Next: <a rel="next" accesskey="n" href="#Print-with-lpr">Print with lpr</a>, +Previous: <a rel="previous" accesskey="p" href="#Format-with-tex_002ftexindex">Format with tex/texindex</a>, +Up: <a rel="up" accesskey="u" href="#Hardcopy">Hardcopy</a> +<br> +</div> + +<h3 class="section">20.3 Format with <code>texi2dvi</code></h3> + +<p><a name="index-texi2dvi-_0040r_007b_0028shell-script_0029_007d-990"></a> +The <code>texi2dvi</code> command automatically runs both TeX and +<span class="command">texindex</span> as many times as necessary to produce a DVI file +with sorted indices and all cross-references resolved. It is +therefore simpler than manually executing the +<code>tex</code>—<code>texindex</code>—<code>tex</code>—<code>tex</code> sequence +described in the previous section. + + <p>To run <code>texi2dvi</code> on an input file <span class="file">foo.texi</span>, do this (where +<span class="samp">prompt$ </span> is your shell prompt): + +<pre class="example"> prompt$ <kbd>texi2dvi foo.texi</kbd> +</pre> + <p>As shown in this example, the input filenames to <code>texi2dvi</code> must +include any extension (<span class="samp">.texi</span>, <span class="samp">.texinfo</span>, etc.). Under +MS-DOS and perhaps in other circumstances, you may need to run <span class="samp">sh +texi2dvi foo.texi</span> instead of relying on the operating system to invoke +the shell on the <span class="samp">texi2dvi</span> script. + + <p>Perhaps the most useful option to <code>texi2dvi</code> is +<span class="samp">--command=</span><var>cmd</var>. This inserts <var>cmd</var> on a line by itself +after the <code>@setfilename</code> in a temporary copy of the input file +before running TeX. With this, you can specify different printing +formats, such as <code>@smallbook</code> (see <a href="#smallbook">smallbook</a>), +<code>@afourpaper</code> (see <a href="#A4-Paper">A4 Paper</a>), or <code>@pagesizes</code> +(see <a href="#pagesizes">pagesizes</a>), without actually changing the document source. +(You can also do this on a site-wide basis with <span class="file">texinfo.cnf</span>; +see <a href="#Preparing-for-TeX">Preparing for TeX</a>). + + <p><a name="index-_0040LaTeX_007b_007d_002c-processing-with-_0040command_007btexi2dvi_007d-991"></a><span class="command">texi2dvi</span> can also be used to process LaTeX files; simply +run <span class="samp">texi2dvi filename.ext</span>. + + <p>For a list of other options, run <span class="samp">texi2dvi --help</span>. + +<div class="node"> +<p><hr> +<a name="Print-with-lpr"></a>Next: <a rel="next" accesskey="n" href="#Within-Emacs">Within Emacs</a>, +Previous: <a rel="previous" accesskey="p" href="#Format-with-texi2dvi">Format with texi2dvi</a>, +Up: <a rel="up" accesskey="u" href="#Hardcopy">Hardcopy</a> +<br> +</div> + +<h3 class="section">20.4 Shell Print Using <code>lpr -d</code></h3> + +<p><a name="index-lpr-_0040r_007b_0028DVI-print-command_0029_007d-992"></a> +The precise command to print a DVI file depends on your system +installation. Two common ones are <span class="samp">dvips foo.dvi -o</span> and <span class="samp">lpr +-d foo.dvi</span>. + + <p>For example, the following commands will (perhaps) suffice to sort the +indices, format, and print the <cite>Bison Manual</cite>: + +<pre class="example"> tex bison.texinfo + texindex bison.?? + tex bison.texinfo + lpr -d bison.dvi +</pre> + <p class="noindent">(Remember that the shell commands may be different at your site; but +these are commonly used versions.) + + <p>Using the <code>texi2dvi</code> shell script (see the previous section): + +<pre class="example"> texi2dvi bison.texinfo + lpr -d bison.dvi + # or perhaps dvips bison.dvi -o +</pre> + <p><a name="index-Shell-printing_002c-on-MS_002dDOS_002fMS_002dWindows-993"></a><a name="index-Printing-DVI-files_002c-on-MS_002dDOS_002fMS_002dWindows-994"></a><a name="index-lpr_0040r_007b_002dd_002c-replacements-on-MS_002dDOS_002fMS_002dWindows_007d-995"></a><code>lpr</code> is a standard program on Unix systems, but it is usually +absent on MS-DOS/MS-Windows. Some network packages come with a +program named <code>lpr</code>, but these are usually limited to sending files +to a print server over the network, and generally don't support the +<span class="samp">-d</span> option. If you are unfortunate enough to work on one of these +systems, you have several alternative ways of printing DVI files: + + <ul> +<li>Find and install a Unix-like <code>lpr</code> program, or its clone. +If you can do that, you will be able to print DVI files just like +described above. + + <li>Send the DVI files to a network printer queue for DVI files. +Some network printers have special queues for printing DVI files. You +should be able to set up your network software to send files to that +queue. In some cases, the version of <code>lpr</code> which comes with your +network software will have a special option to send a file to specific +queues, like this: + + <pre class="example"> lpr -Qdvi -hprint.server.domain bison.dvi + </pre> + <li>Convert the DVI file to a Postscript or PCL file and send it to your +local printer. See <a href="dvips.html#Invoking-Dvips">Invoking Dvips (Dvips)</a>, and the man +pages for <code>dvilj</code>, for detailed description of these tools. Once +the DVI file is converted to the format your local printer understands +directly, just send it to the appropriate port, usually <span class="samp">PRN</span>. +</ul> + +<div class="node"> +<p><hr> +<a name="Within-Emacs"></a>Next: <a rel="next" accesskey="n" href="#Texinfo-Mode-Printing">Texinfo Mode Printing</a>, +Previous: <a rel="previous" accesskey="p" href="#Print-with-lpr">Print with lpr</a>, +Up: <a rel="up" accesskey="u" href="#Hardcopy">Hardcopy</a> +<br> +</div> + +<h3 class="section">20.5 From an Emacs Shell</h3> + +<p><a name="index-Print_002c-format-from-Emacs-shell-996"></a><a name="index-Format_002c-print-from-Emacs-shell-997"></a><a name="index-Shell_002c-format_002c-print-from-998"></a><a name="index-Emacs-shell_002c-format_002c-print-from-999"></a><a name="index-GNU-Emacs-shell_002c-format_002c-print-from-1000"></a> +You can give formatting and printing commands from a shell within GNU +Emacs. To create a shell within Emacs, type <kbd>M-x shell</kbd>. In this +shell, you can format and print the document. See <a href="#Hardcopy">Format and Print Hardcopy</a>, for details. + + <p>You can switch to and from the shell buffer while <code>tex</code> is +running and do other editing. If you are formatting a long document +on a slow machine, this can be very convenient. + + <p>You can also use <code>texi2dvi</code> from an Emacs shell. For example, +here is how to use <code>texi2dvi</code> to format and print <cite>Using and +Porting GNU CC</cite> from a shell within Emacs: + +<pre class="example"> texi2dvi gcc.texinfo + lpr -d gcc.dvi +</pre> + <p>See the next section for more information about formatting +and printing in Texinfo mode. + +<div class="node"> +<p><hr> +<a name="Texinfo-Mode-Printing"></a>Next: <a rel="next" accesskey="n" href="#Compile_002dCommand">Compile-Command</a>, +Previous: <a rel="previous" accesskey="p" href="#Within-Emacs">Within Emacs</a>, +Up: <a rel="up" accesskey="u" href="#Hardcopy">Hardcopy</a> +<br> +</div> + +<h3 class="section">20.6 Formatting and Printing in Texinfo Mode</h3> + +<p><a name="index-Region-printing-in-Texinfo-mode-1001"></a><a name="index-Format-and-print-in-Texinfo-mode-1002"></a><a name="index-Print-and-format-in-Texinfo-mode-1003"></a> +Texinfo mode provides several predefined key commands for TeX +formatting and printing. These include commands for sorting indices, +looking at the printer queue, killing the formatting job, and +recentering the display of the buffer in which the operations +occur. + + <dl> +<dt><kbd>C-c C-t C-b</kbd><dt><kbd>M-x texinfo-tex-buffer</kbd><dd>Run <code>texi2dvi</code> on the current buffer. + + <br><dt><kbd>C-c C-t C-r</kbd><dt><kbd>M-x texinfo-tex-region</kbd><dd>Run TeX on the current region. + + <br><dt><kbd>C-c C-t C-i</kbd><dt><kbd>M-x texinfo-texindex</kbd><dd>Sort the indices of a Texinfo file formatted with +<code>texinfo-tex-region</code>. + + <br><dt><kbd>C-c C-t C-p</kbd><dt><kbd>M-x texinfo-tex-print</kbd><dd>Print a DVI file that was made with <code>texinfo-tex-region</code> or +<code>texinfo-tex-buffer</code>. + + <br><dt><kbd>C-c C-t C-q</kbd><dt><kbd>M-x tex-show-print-queue</kbd><dd>Show the print queue. + + <br><dt><kbd>C-c C-t C-d</kbd><dt><kbd>M-x texinfo-delete-from-print-queue</kbd><dd>Delete a job from the print queue; you will be prompted for the job +number shown by a preceding <kbd>C-c C-t C-q</kbd> command +(<code>texinfo-show-tex-print-queue</code>). + + <br><dt><kbd>C-c C-t C-k</kbd><dt><kbd>M-x tex-kill-job</kbd><dd>Kill the currently running TeX job started by either +<code>texinfo-tex-region</code> or <code>texinfo-tex-buffer</code>, or any other +process running in the Texinfo shell buffer. + + <br><dt><kbd>C-c C-t C-x</kbd><dt><kbd>M-x texinfo-quit-job</kbd><dd>Quit a TeX formatting job that has stopped because of an error by +sending an <x> to it. When you do this, TeX preserves a record +of what it did in a <span class="file">.log</span> file. + + <br><dt><kbd>C-c C-t C-l</kbd><dt><kbd>M-x tex-recenter-output-buffer</kbd><dd>Redisplay the shell buffer in which the TeX printing and formatting +commands are run to show its most recent output. +</dl> + + <p>Thus, the usual sequence of commands for formatting a buffer is as +follows (with comments to the right): + +<pre class="example"> C-c C-t C-b <span class="roman">Run </span><code>texi2dvi</code><span class="roman"> on the buffer.</span> + C-c C-t C-p <span class="roman">Print the DVI file.</span> + C-c C-t C-q <span class="roman">Display the printer queue.</span> +</pre> + <p>The Texinfo mode TeX formatting commands start a subshell in Emacs +called the <span class="file">*tex-shell*</span>. The <code>texinfo-tex-command</code>, +<code>texinfo-texindex-command</code>, and <code>tex-dvi-print-command</code> +commands are all run in this shell. + + <p>You can watch the commands operate in the <span class="samp">*tex-shell*</span> buffer, +and you can switch to and from and use the <span class="samp">*tex-shell*</span> buffer +as you would any other shell buffer. + + <p>The formatting and print commands depend on the values of several variables. +The default values are: + +<pre class="example"> <span class="roman">Variable</span> <span class="roman">Default value</span> + + texinfo-texi2dvi-command "texi2dvi" + texinfo-tex-command "tex" + texinfo-texindex-command "texindex" + texinfo-delete-from-print-queue-command "lprm" + texinfo-tex-trailer "@bye" + tex-start-of-header "%**start" + tex-end-of-header "%**end" + tex-dvi-print-command "lpr -d" + tex-show-queue-command "lpq" +</pre> + <p>You can change the values of these variables with the <kbd>M-x +set-variable</kbd> command (see <a href="emacs.html#Examining">Examining and Setting Variables (The GNU Emacs Manual)</a>), or with your <span class="file">.emacs</span> +initialization file (see <a href="emacs.html#Init-File">Init File (The GNU Emacs Manual)</a>). + + <p><a name="index-Customize-Emacs-package-_0028_0040t_007bDevelopment_002fDocs_002fTexinfo_007d_0029-1004"></a>Beginning with version 20, GNU Emacs offers a user-friendly interface, +called <dfn>Customize</dfn>, for changing values of user-definable variables. +See <a href="emacs.html#Easy-Customization">Easy Customization Interface (The GNU Emacs Manual)</a>, for more details about this. The Texinfo variables can +be found in the <span class="samp">Development/Docs/Texinfo</span> group, once you invoke +the <kbd>M-x customize</kbd> command. + +<div class="node"> +<p><hr> +<a name="Compile_002dCommand"></a>Next: <a rel="next" accesskey="n" href="#Requirements-Summary">Requirements Summary</a>, +Previous: <a rel="previous" accesskey="p" href="#Texinfo-Mode-Printing">Texinfo Mode Printing</a>, +Up: <a rel="up" accesskey="u" href="#Hardcopy">Hardcopy</a> +<br> +</div> + +<h3 class="section">20.7 Using the Local Variables List</h3> + +<p><a name="index-Local-variables-1005"></a><a name="index-Compile-command-for-formatting-1006"></a><a name="index-Format-with-the-compile-command-1007"></a> +Yet another way to apply the TeX formatting command to a Texinfo file +is to put that command in a <dfn>local variables list</dfn> at the end of the +Texinfo file. You can then specify the <code>tex</code> or <code>texi2dvi</code> +commands as a <code>compile-command</code> and have Emacs run it by typing +<kbd>M-x compile</kbd>. This creates a special shell called the +<span class="file">*compilation*</span> buffer in which Emacs runs the compile command. +For example, at the end of the <span class="file">gdb.texinfo</span> file, after the +<code>@bye</code>, you could put the following: + +<pre class="example"> Local Variables: + compile-command: "texi2dvi gdb.texinfo" + End: +</pre> + <p class="noindent">This technique is most often used by programmers who also compile programs +this way; see <a href="emacs.html#Compilation">Compilation (The GNU Emacs Manual)</a>. + +<div class="node"> +<p><hr> +<a name="Requirements-Summary"></a>Next: <a rel="next" accesskey="n" href="#Preparing-for-TeX">Preparing for TeX</a>, +Previous: <a rel="previous" accesskey="p" href="#Compile_002dCommand">Compile-Command</a>, +Up: <a rel="up" accesskey="u" href="#Hardcopy">Hardcopy</a> +<br> +</div> + +<h3 class="section">20.8 TeX Formatting Requirements Summary</h3> + +<p><a name="index-Requirements-for-formatting-1008"></a><a name="index-Minimal-requirements-for-formatting-1009"></a><a name="index-Formatting-requirements-1010"></a> +Every Texinfo file that is to be input to TeX must begin with a +<code>\input</code> command and must contain an <code>@setfilename</code> command: + +<pre class="example"> \input texinfo + @setfilename <var>arg-not-used-by-TeX</var> +</pre> + <p class="noindent">The first command instructs TeX to load the macros it needs to +process a Texinfo file and the second command opens auxiliary files. + + <p>Every Texinfo file must end with a line that terminates TeX's +processing and forces out unfinished pages: + +<pre class="example"> @bye +</pre> + <p>Strictly speaking, these lines are all a Texinfo file needs to be +processed successfully by TeX. + + <p>Usually, however, the beginning includes an <code>@settitle</code> command to +define the title of the printed manual, an <code>@setchapternewpage</code> +command, a title page, a copyright page, and permissions. Besides an +<code>@bye</code>, the end of a file usually includes indices and a table of +contents. (And of course most manuals contain a body of text as well.) + + <p>For more information, see: + + <ul> +<li><a href="#settitle"><code>@settitle</code></a>. +<li><a href="#setchapternewpage"><code>@setchapternewpage</code></a>. +<li><a href="#Headings">Page Headings</a>. +<li><a href="#Titlepage-_0026-Copyright-Page">Titlepage & Copyright Page</a>. +<li><a href="#Printing-Indices-_0026-Menus">Printing Indices & Menus</a>. +<li><a href="#Contents">Contents</a>. +</ul> + +<div class="node"> +<p><hr> +<a name="Preparing-for-TeX"></a>Next: <a rel="next" accesskey="n" href="#Overfull-hboxes">Overfull hboxes</a>, +Previous: <a rel="previous" accesskey="p" href="#Requirements-Summary">Requirements Summary</a>, +Up: <a rel="up" accesskey="u" href="#Hardcopy">Hardcopy</a> +<br> +</div> + +<h3 class="section">20.9 Preparing for TeX</h3> + +<p><a name="index-Preparing-for-_0040TeX_007b_007d-1011"></a><a name="index-_0040TeX_007b_007d-input-initialization-1012"></a><a name="index-_0040b_007b_002eprofile_007d-initialization-file-1013"></a><a name="index-_0040b_007b_002ecshrc_007d-initialization-file-1014"></a><a name="index-Initialization-file-for-_0040TeX_007b_007d-input-1015"></a> +TeX needs to know where to find the <span class="file">texinfo.tex</span> file that the +<span class="samp">\input texinfo</span> command on the first line reads. The +<span class="file">texinfo.tex</span> file tells TeX how to handle @-commands; it is +included in all standard GNU distributions. The latest version is +always available from the Texinfo source repository: +<pre class="smalldisplay"> <a href="http://savannah.gnu.org/cgi-bin/viewcvs/texinfo/texinfo/doc/texinfo.tex?rev=HEAD">http://savannah.gnu.org/cgi-bin/viewcvs/texinfo/texinfo/doc/texinfo.tex?rev=HEAD</a> +</pre> + <p><a name="index-texinfo_002etex_0040r_007b_002c-installing_007d-1016"></a> +Usually, the installer has put the <span class="file">texinfo.tex</span> file in the +default directory that contains TeX macros when GNU Texinfo, Emacs or +other GNU software is installed. In this case, TeX will find the +file and you do not need to do anything special. If this has not been +done, you can put <span class="file">texinfo.tex</span> in the current directory when you +run TeX, and TeX will find it there. + + <p><a name="index-epsf_002etex_0040r_007b_002c-installing_007d-1017"></a>Also, you should install <span class="file">epsf.tex</span>, if it is not already installed +from another distribution. More details are at the end of the description +of the <code>@image</code> command (see <a href="#Images">Images</a>). + + <p><a name="index-pdfcolor_002etex_0040r_007b_002c-installing_007d-1018"></a>Likewise for <span class="file">pdfcolor.tex</span>, if it is not already installed and you +use pdftex. + + <p><a name="index-texinfo_002ecnf-_0040r_007binstallation_007d-1019"></a><a name="index-Customizing-of-_0040TeX_007b_007d-for-Texinfo-1020"></a><a name="index-Site_002dwide-Texinfo-configuration-file-1021"></a>Optionally, you may create an additional <span class="file">texinfo.cnf</span>, and install +it as well. This file is read by TeX when the <code>@setfilename</code> +command is executed (see <a href="#setfilename"><code>@setfilename</code></a>). You can put any +commands you like there, according to local site-wide conventions. They +will be read by TeX when processing any Texinfo document. For +example, if <span class="file">texinfo.cnf</span> contains the line <span class="samp">@afourpaper</span> +(see <a href="#A4-Paper">A4 Paper</a>), then all Texinfo documents will be processed with +that page size in effect. If you have nothing to put in +<span class="file">texinfo.cnf</span>, you do not need to create it. + + <p><a name="index-Environment-variable-_0040code_007bTEXINPUTS_007d-1022"></a><a name="index-TEXINPUTS-1023"></a>If neither of the above locations for these system files suffice for +you, you can specify the directories explicitly. For +<span class="file">texinfo.tex</span>, you can do this by writing the complete path for the +file after the <code>\input</code> command. Another way, that works for both +<span class="file">texinfo.tex</span> and <span class="file">texinfo.cnf</span> (and any other file TeX +might read), is to set the <code>TEXINPUTS</code> environment variable in your +<span class="file">.cshrc</span> or <span class="file">.profile</span> file. + + <p>Which you use of <span class="file">.cshrc</span> or <span class="file">.profile</span> depends on +whether you use a Bourne shell-compatible (<code>sh</code>, <code>bash</code>, +<code>ksh</code>, <small class="dots">...</small>) or C shell-compatible (<code>csh</code>, <code>tcsh</code>) +command interpreter. The latter read the <span class="file">.cshrc</span> file for +initialization information, and the former read <span class="file">.profile</span>. + + <p>In a <span class="file">.cshrc</span> file, you could use the following <code>csh</code> command +sequence: + +<pre class="example"> setenv TEXINPUTS .:/home/me/mylib: +</pre> + <p>In a <span class="file">.profile</span> file, you could use the following <code>sh</code> command +sequence: + +<pre class="example"> TEXINPUTS=.:/home/me/mylib: + export TEXINPUTS +</pre> + <p>On MS-DOS/MS-Windows, you would say it like this<a rel="footnote" href="#fn-9" name="fnd-9"><sup>9</sup></a>: + +<pre class="example"> set TEXINPUTS=.;d:/home/me/mylib;c: +</pre> + <p class="noindent">It is customary for DOS/Windows users to put such commands in the +<span class="file">autoexec.bat</span> file, or in the Windows Registry. + +<p class="noindent">These settings would cause TeX to look for <span class="file">\input</span> file first +in the current directory, indicated by the <span class="samp">.</span>, then in a +hypothetical user <span class="samp">me</span>'s <span class="file">mylib</span> directory, and finally in +the system directories. (A leading, trailing, or doubled <span class="samp">:</span> +indicates searching the system directories at that point.) + + <p><a name="index-Dumping-a-_002efmt-file-1024"></a><a name="index-Format-file_002c-dumping-1025"></a>Finally, you may wish to dump a <span class="file">.fmt</span> file (see <a href="web2c.html#Memory-dumps">Memory dumps (Web2c)</a>) so that TeX can load Texinfo faster. (The +disadvantage is that then updating <span class="file">texinfo.tex</span> requires +redumping.) You can do this by running this command, assuming +<span class="file">epsf.tex</span> is findable by TeX: + +<pre class="example"> initex texinfo @dump +</pre> + <p>(<code>dump</code> is a TeX primitive.) Then, move <span class="file">texinfo.fmt</span> to +wherever your <code>.fmt</code> files are found; typically, this will be in the +subdirectory <span class="file">web2c</span> of your TeX installation. + +<div class="node"> +<p><hr> +<a name="Overfull-hboxes"></a>Next: <a rel="next" accesskey="n" href="#smallbook">smallbook</a>, +Previous: <a rel="previous" accesskey="p" href="#Preparing-for-TeX">Preparing for TeX</a>, +Up: <a rel="up" accesskey="u" href="#Hardcopy">Hardcopy</a> +<br> +</div> + +<h3 class="section">20.10 Overfull “hboxes”</h3> + +<p><a name="index-Overfull-_0040samp_007bhboxes_007d-1026"></a><a name="index-_0040samp_007bhboxes_007d_002c-overfull-1027"></a><a name="index-Final-output-1028"></a> +TeX is sometimes unable to typeset a line without extending it into +the right margin. This can occur when TeX comes upon what it +interprets as a long word that it cannot hyphenate, such as an +electronic mail network address or a very long title. When this +happens, TeX prints an error message like this: + +<pre class="example"> Overfull @hbox (20.76302pt too wide) +</pre> + <p><a name="index-hbox-1029"></a>(In TeX, lines are in “horizontal boxes”, hence the term, “hbox”. +<span class="samp">@hbox</span> is a TeX primitive not needed in the Texinfo language.) + + <p>TeX also provides the line number in the Texinfo source file and +the text of the offending line, which is marked at all the places that +TeX considered hyphenation. +See <a href="#Debugging-with-TeX">Catching Errors with TeX Formatting</a>, +for more information about typesetting errors. + + <p>If the Texinfo file has an overfull hbox, you can rewrite the sentence +so the overfull hbox does not occur, or you can decide to leave it. A +small excursion into the right margin often does not matter and may not +even be noticeable. + + <p>If you have many overfull boxes and/or an antipathy to rewriting, you +can coerce TeX into greatly increasing the allowable interword +spacing, thus (if you're lucky) avoiding many of the bad line breaks, +like this: + + <p><a name="index-_005cemergencystretch-1030"></a> +<pre class="example"> @tex + \global\emergencystretch = .9\hsize + @end tex +</pre> + <p class="noindent">(You should adjust the fraction as needed.) This huge value for +<code>\emergencystretch</code> cannot be the default, since then the typeset +output would generally be of noticeably lower quality; the default +is <span class="samp">.15\hsize</span>. <code>\hsize</code> is the TeX dimension +containing the current line width. + + <p><a name="index-Black-rectangle-in-hardcopy-1031"></a><a name="index-Rectangle_002c-black-in-hardcopy-1032"></a><a name="index-Box_002c-ugly-black-in-hardcopy-1033"></a><a name="index-Ugly-black-rectangles-in-hardcopy-1034"></a>For what overfull boxes you have, however, TeX will print a large, +ugly, black rectangle beside the line that contains the overfull hbox +unless told otherwise. This is so you will notice the location of the +problem if you are correcting a draft. + + <p><a name="index-finalout-1035"></a>To prevent such a monstrosity from marring your final printout, write +the following in the beginning of the Texinfo file on a line of its own, +before the <code>@titlepage</code> command: + +<pre class="example"> @finalout +</pre> + <div class="node"> +<p><hr> +<a name="smallbook"></a>Next: <a rel="next" accesskey="n" href="#A4-Paper">A4 Paper</a>, +Previous: <a rel="previous" accesskey="p" href="#Overfull-hboxes">Overfull hboxes</a>, +Up: <a rel="up" accesskey="u" href="#Hardcopy">Hardcopy</a> +<br> +</div> + +<h3 class="section">20.11 Printing “Small” Books</h3> + +<p><a name="index-smallbook-1036"></a><a name="index-Small-book-size-1037"></a><a name="index-Book_002c-printing-small-1038"></a><a name="index-Page-sizes-for-books-1039"></a><a name="index-Size-of-printed-book-1040"></a> +By default, TeX typesets pages for printing in an 8.5 by 11 inch +format. However, you can direct TeX to typeset a document in a 7 by +9.25 inch format that is suitable for bound books by inserting the +following command on a line by itself at the beginning of the Texinfo +file, before the title page: + +<pre class="example"> @smallbook +</pre> + <p class="noindent">(Since many books are about 7 by 9.25 inches, this command might better +have been called the <code>@regularbooksize</code> command, but it came to be +called the <code>@smallbook</code> command by comparison to the 8.5 by 11 +inch format.) + + <p>If you write the <code>@smallbook</code> command between the +start-of-header and end-of-header lines, the Texinfo mode TeX +region formatting command, <code>texinfo-tex-region</code>, will format the +region in “small” book size (see <a href="#Start-of-Header">Start of Header</a>). + + <p>See <a href="#small">small</a>, for information about +commands that make it easier to produce examples for a smaller manual. + + <p>See <a href="#Format-with-texi2dvi">Format with texi2dvi</a>, and <a href="#Preparing-for-TeX">Preparing for TeX</a>, for other ways to format with <code>@smallbook</code> that do not +require changing the source file. + +<div class="node"> +<p><hr> +<a name="A4-Paper"></a>Next: <a rel="next" accesskey="n" href="#pagesizes">pagesizes</a>, +Previous: <a rel="previous" accesskey="p" href="#smallbook">smallbook</a>, +Up: <a rel="up" accesskey="u" href="#Hardcopy">Hardcopy</a> +<br> +</div> + +<h3 class="section">20.12 Printing on A4 Paper</h3> + +<p><a name="index-A4-paper_002c-printing-on-1041"></a><a name="index-A5-paper_002c-printing-on-1042"></a><a name="index-Paper-size_002c-A4-1043"></a><a name="index-European-A4-paper-1044"></a><a name="index-afourpaper-1045"></a> +You can tell TeX to format a document for printing on European size +A4 paper (or A5) with the <code>@afourpaper</code> (or <code>@afivepaper</code>) +command. Write the command on a line by itself near the beginning of +the Texinfo file, before the title page. For example, this is how you +would write the header for this manual: + +<pre class="example"> \input texinfo @c -*-texinfo-*- + @c %**start of header + @setfilename texinfo + @settitle Texinfo + @afourpaper + @c %**end of header +</pre> + <p>See <a href="#Format-with-texi2dvi">Format with texi2dvi</a>, and <a href="#Preparing-for-TeX">Preparing for TeX</a>, for other ways to format for different paper sizes that do not +require changing the source file. + + <p><a name="index-afourlatex-1046"></a><a name="index-afourwide-1047"></a>You may or may not prefer the formatting that results from the command +<code>@afourlatex</code>. There's also <code>@afourwide</code> for A4 paper in +wide format. + +<div class="node"> +<p><hr> +<a name="pagesizes"></a>Next: <a rel="next" accesskey="n" href="#Cropmarks-and-Magnification">Cropmarks and Magnification</a>, +Previous: <a rel="previous" accesskey="p" href="#A4-Paper">A4 Paper</a>, +Up: <a rel="up" accesskey="u" href="#Hardcopy">Hardcopy</a> +<br> +</div> + +<h3 class="section">20.13 <code>@pagesizes</code> [<var>width</var>][, <var>height</var>]: Custom Page Sizes</h3> + +<p><a name="index-pagesizes-1048"></a><a name="index-Custom-page-sizes-1049"></a><a name="index-Page-sizes_002c-customized-1050"></a><a name="index-Text-width-and-height-1051"></a><a name="index-Width-of-text-area-1052"></a><a name="index-Height-of-text-area-1053"></a><a name="index-Depth-of-text-area-1054"></a> +You can explicitly specify the height and (optionally) width of the main +text area on the page with the <code>@pagesizes</code> command. Write this +on a line by itself near the beginning of the Texinfo file, before the +title page. The height comes first, then the width if desired, +separated by a comma. Examples: + +<pre class="example"> @pagesizes 200mm,150mm <!-- for b5 paper --> +</pre> + <p class="noindent">and +<pre class="example"> @pagesizes 11.5in <!-- for legal paper --> +</pre> + <p><a name="index-B5-paper_002c-printing-on-1055"></a><a name="index-Legal-paper_002c-printing-on-1056"></a>This would be reasonable for printing on B5-size paper. To emphasize, +this command specifies the size of the <em>text area</em>, not the size of +the paper (which is 250<span class="dmn">mm</span> by 177<span class="dmn">mm</span> for B5, 14<span class="dmn">in</span> by +8.5<span class="dmn">in</span> for legal). + + <p><a name="index-Margins-on-page_002c-not-controllable-1057"></a>To make more elaborate changes, such as changing any of the page +margins, you must define a new command in <span class="file">texinfo.tex</span> (or +<span class="file">texinfo.cnf</span>, see <a href="#Preparing-for-TeX">Preparing for TeX</a>). + + <p>See <a href="#Format-with-texi2dvi">Format with texi2dvi</a>, and <a href="#Preparing-for-TeX">Preparing for TeX</a>, for other ways to specify <code>@pagesizes</code> that do not +require changing the source file. + + <p><code>@pagesizes</code> is ignored by <code>makeinfo</code>. + +<div class="node"> +<p><hr> +<a name="Cropmarks-and-Magnification"></a>Next: <a rel="next" accesskey="n" href="#PDF-Output">PDF Output</a>, +Previous: <a rel="previous" accesskey="p" href="#pagesizes">pagesizes</a>, +Up: <a rel="up" accesskey="u" href="#Hardcopy">Hardcopy</a> +<br> +</div> + +<h3 class="section">20.14 Cropmarks and Magnification</h3> + +<p><a name="index-cropmarks-1058"></a><a name="index-Cropmarks-for-printing-1059"></a><a name="index-Printing-cropmarks-1060"></a>You can (attempt to) direct TeX to print cropmarks at the corners of +pages with the <code>@cropmarks</code> command. Write the <code>@cropmarks</code> +command on a line by itself between <code>@iftex</code> and <code>@end +iftex</code> lines near the beginning of the Texinfo file, before the title +page, like this: + +<pre class="example"> @iftex + @cropmarks + @end iftex +</pre> + <p>This command is mainly for printers that typeset several pages on one +sheet of film; but you can attempt to use it to mark the corners of a +book set to 7 by 9.25 inches with the <code>@smallbook</code> command. +(Printers will not produce cropmarks for regular sized output that is +printed on regular sized paper.) Since different printing machines work +in different ways, you should explore the use of this command with a +spirit of adventure. You may have to redefine the command in +<span class="file">texinfo.tex</span>. + + <p><a name="index-_005cmag-_0040r_007b_0028raw-_0040TeX_007b_007d-magnification_0029_007d-1061"></a><a name="index-Magnified-printing-1062"></a><a name="index-Larger-or-smaller-pages-1063"></a>You can attempt to direct TeX to typeset pages larger or smaller than +usual with the <code>\mag</code> TeX command. Everything that is typeset +is scaled proportionally larger or smaller. (<code>\mag</code> stands for +“magnification”.) This is <em>not</em> a Texinfo @-command, but is a +plain TeX command that is prefixed with a backslash. You have to +write this command between <code>@tex</code> and <code>@end tex</code> +(see <a href="#Raw-Formatter-Commands">Raw Formatter Commands</a>). + + <p>Follow the <code>\mag</code> command with an <span class="samp">=</span> and then a number that +is 1000 times the magnification you desire. For example, to print pages +at 1.2 normal size, write the following near the beginning of the +Texinfo file, before the title page: + +<pre class="example"> @tex + \mag=1200 + @end tex +</pre> + <p>With some printing technologies, you can print normal-sized copies that +look better than usual by giving a larger-than-normal master to your +print shop. They do the reduction, thus effectively increasing the +resolution. + + <p>Depending on your system, DVI files prepared with a +nonstandard-<code>\mag</code> may not print or may print only with certain +magnifications. Be prepared to experiment. + +<div class="node"> +<p><hr> +<a name="PDF-Output"></a>Next: <a rel="next" accesskey="n" href="#Obtaining-TeX">Obtaining TeX</a>, +Previous: <a rel="previous" accesskey="p" href="#Cropmarks-and-Magnification">Cropmarks and Magnification</a>, +Up: <a rel="up" accesskey="u" href="#Hardcopy">Hardcopy</a> +<br> +</div> + +<h3 class="section">20.15 PDF Output</h3> + +<p><a name="index-PDF-output-1064"></a> +<a name="index-pdftex-1065"></a>You can generate a PDF output file from Texinfo source by using the +<span class="command">pdftex</span> program to process your file instead of plain +<span class="command">tex</span>. That is, run <span class="samp">pdftex foo.texi</span> instead of <span class="samp">tex +foo.texi</span>, or give the <span class="samp">--pdf</span> option to <span class="command">texi2dvi</span>. + + <p><dfn>PDF</dfn> stands for `Portable Document Format'. It was invented by +Adobe Systems some years ago for document interchange, based on their +PostScript language. A <a href="http://www.foolabs.com/xpdf/">PDF reader</a> for the X window system is freely available, as is the +<a href="http://partners.adobe.com/asn/developer/technotes/">definition of the file format</a>. At present, there are no <span class="samp">@ifpdf</span> or +<span class="samp">@pdf</span> commands as with the other output formats. + + <p>Despite the `portable' in the name, PDF files are nowhere near as +portable in practice as the plain ASCII formats (Info, HTML) that +Texinfo supports (DVI portability is arguable). They also tend to be +much larger. Nevertheless, a PDF file does preserve an actual printed +document on a screen as faithfully as possible, so it has its place. + +<div class="node"> +<p><hr> +<a name="Obtaining-TeX"></a>Previous: <a rel="previous" accesskey="p" href="#PDF-Output">PDF Output</a>, +Up: <a rel="up" accesskey="u" href="#Hardcopy">Hardcopy</a> +<br> +</div> + +<h3 class="section">20.16 How to Obtain TeX</h3> + +<p><a name="index-Obtaining-_0040TeX_007b_007d-1066"></a><a name="index-_0040TeX_007b_007d_002c-how-to-obtain-1067"></a> +<!-- !!! Here is information about obtaining TeX. Update it whenever. --> +<!-- !!! Also consider updating TeX.README on ftp.gnu.org. --> +<!-- Updated by RJC on 1 March 1995, conversation with MacKay. --> +<!-- Updated by kb@cs.umb.edu on 29 July 1996. --> +<!-- Updated by kb@cs.umb.edu on 25 April 1997. --> +<!-- Updated by kb@cs.umb.edu on 27 February 1998. --> +TeX is freely redistributable. You can obtain TeX for Unix +systems via anonymous ftp or on physical media. The core material +consists of the Web2c TeX distribution (<a href="http://tug.org/web2c">http://tug.org/web2c</a>). + + <p>Instructions for retrieval by anonymous ftp and information on other +available distributions: +<a href="http://tug.org/unixtex.ftp">http://tug.org/unixtex.ftp</a>. + + <p>The Free Software Foundation provides a core distribution on its Source +Code CD-ROM suitable for printing Texinfo manuals. To order it, contact: + +<pre class="display"> Free Software Foundation, Inc. + 59 Temple Place Suite 330 + Boston, MA 02111-1307 + USA + Telephone: +1-617-542-5942<!-- /@w --> + Fax: (including Japan) +1-617-542-2652<!-- /@w --> + Free Dial Fax (in Japan): + <!-- /@w --> <!-- /@w --> <!-- /@w --> 0031-13-2473 (KDD) + <!-- /@w --> <!-- /@w --> <!-- /@w --> 0066-3382-0158 (IDC) + Electronic mail: <code>gnu@gnu.org</code> +</pre> + <p>Many other TeX distributions are available; see +<a href="http://tug.org/">http://tug.org/</a>. + +<div class="node"> +<p><hr> +<a name="Creating-and-Installing-Info-Files"></a>Next: <a rel="next" accesskey="n" href="#Generating-HTML">Generating HTML</a>, +Previous: <a rel="previous" accesskey="p" href="#Hardcopy">Hardcopy</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> +<br> +</div> + +<h2 class="chapter">21 Creating and Installing Info Files</h2> + +<p>This chapter describes how to create and install Info files. See <a href="#Info-Files">Info Files</a>, for general information about the file format itself. + +<ul class="menu"> +<li><a accesskey="1" href="#Creating-an-Info-File">Creating an Info File</a> +<li><a accesskey="2" href="#Installing-an-Info-File">Installing an Info File</a> +</ul> + +<div class="node"> +<p><hr> +<a name="Creating-an-Info-File"></a>Next: <a rel="next" accesskey="n" href="#Installing-an-Info-File">Installing an Info File</a>, +Up: <a rel="up" accesskey="u" href="#Creating-and-Installing-Info-Files">Creating and Installing Info Files</a> +<br> +</div> + +<h3 class="section">21.1 Creating an Info File</h3> + +<p><a name="index-Creating-an-Info-file-1068"></a><a name="index-Info_002c-creating-an-online-file-1069"></a><a name="index-Formatting-a-file-for-Info-1070"></a> +<code>makeinfo</code> is a program that converts a Texinfo file into an Info +file, HTML file, or plain text. <code>texinfo-format-region</code> and +<code>texinfo-format-buffer</code> are GNU Emacs functions that convert +Texinfo to Info. + + <p>For information on installing the Info file in the Info system, +see <a href="#Installing-an-Info-File">Installing an Info File</a>. + +<ul class="menu"> +<li><a accesskey="1" href="#makeinfo-advantages">makeinfo advantages</a>: <code>makeinfo</code> provides better error checking. +<li><a accesskey="2" href="#Invoking-makeinfo">Invoking makeinfo</a>: How to run <code>makeinfo</code> from a shell. +<li><a accesskey="3" href="#makeinfo-options">makeinfo options</a>: Specify fill-column and other options. +<li><a accesskey="4" href="#Pointer-Validation">Pointer Validation</a>: How to check that pointers point somewhere. +<li><a accesskey="5" href="#makeinfo-in-Emacs">makeinfo in Emacs</a>: How to run <code>makeinfo</code> from Emacs. +<li><a accesskey="6" href="#texinfo_002dformat-commands">texinfo-format commands</a>: Two Info formatting commands written + in Emacs Lisp are an alternative + to <code>makeinfo</code>. +<li><a accesskey="7" href="#Batch-Formatting">Batch Formatting</a>: How to format for Info in Emacs Batch mode. +<li><a accesskey="8" href="#Tag-and-Split-Files">Tag and Split Files</a>: How tagged and split files help Info + to run better. +</ul> + +<div class="node"> +<p><hr> +<a name="makeinfo-advantages"></a>Next: <a rel="next" accesskey="n" href="#Invoking-makeinfo">Invoking makeinfo</a>, +Up: <a rel="up" accesskey="u" href="#Creating-an-Info-File">Creating an Info File</a> +<br> +</div> + +<h4 class="subsection">21.1.1 <code>makeinfo</code> Preferred</h4> + +<p>The <code>makeinfo</code> utility creates an Info file from a Texinfo source +file more quickly than either of the Emacs formatting commands and +provides better error messages. We recommend it. <code>makeinfo</code> is a +C program that is independent of Emacs. You do not need to run Emacs to +use <code>makeinfo</code>, which means you can use <code>makeinfo</code> on machines +that are too small to run Emacs. You can run <code>makeinfo</code> in any one +of three ways: from an operating system shell, from a shell inside +Emacs, or by typing the <kbd>C-c C-m C-r</kbd> or the <kbd>C-c C-m C-b</kbd> +command in Texinfo mode in Emacs. + + <p>The <code>texinfo-format-region</code> and the <code>texinfo-format-buffer</code> +commands are useful if you cannot run <code>makeinfo</code>. Also, in some +circumstances, they format short regions or buffers more quickly than +<code>makeinfo</code>. + +<div class="node"> +<p><hr> +<a name="Invoking-makeinfo"></a>Next: <a rel="next" accesskey="n" href="#makeinfo-options">makeinfo options</a>, +Previous: <a rel="previous" accesskey="p" href="#makeinfo-advantages">makeinfo advantages</a>, +Up: <a rel="up" accesskey="u" href="#Creating-an-Info-File">Creating an Info File</a> +<br> +</div> + +<h4 class="subsection">21.1.2 Running <code>makeinfo</code> from a Shell</h4> + +<p><a name="index-makeinfo-1071"></a> +To create an Info file from a Texinfo file, invoke <span class="command">makeinfo</span> +followed by the name of the Texinfo file. Thus, to create the Info +file for Bison, type the following to the shell: + +<pre class="example"> makeinfo bison.texinfo +</pre> + <p>(You can run a shell inside Emacs by typing <kbd>M-x shell</kbd>.) + + <p><span class="command">makeinfo</span> has many options to control its actions and output; +see the next section. + +<div class="node"> +<p><hr> +<a name="makeinfo-options"></a>Next: <a rel="next" accesskey="n" href="#Pointer-Validation">Pointer Validation</a>, +Previous: <a rel="previous" accesskey="p" href="#Invoking-makeinfo">Invoking makeinfo</a>, +Up: <a rel="up" accesskey="u" href="#Creating-an-Info-File">Creating an Info File</a> +<br> +</div> + +<h4 class="subsection">21.1.3 Options for <code>makeinfo</code></h4> + +<p><a name="index-_0040code_007bmakeinfo_007d-options-1072"></a><a name="index-Options-for-_0040code_007bmakeinfo_007d-1073"></a> +The <span class="command">makeinfo</span> program accepts many options. Perhaps the most +commonly needed are those that change the output format. By default, +<span class="command">makeinfo</span> outputs Info files. + + <p>Each command line option is a word preceded by <span class="samp">--</span> or a letter +preceded by <span class="samp">-</span>. You can use abbreviations for the long option +names as long as they are unique. + + <p>For example, you could use the following shell command to create an Info +file for <span class="file">bison.texinfo</span> in which each line is filled to only 68 +columns: + +<pre class="example"> makeinfo --fill-column=68 bison.texinfo +</pre> + <p>You can write two or more options in sequence, like this: + +<pre class="example"> makeinfo --no-split --fill-column=70 ... +</pre> + <p class="noindent">This would keep the Info file together as one possibly very long +file and would also set the fill column to 70. + + <p>The options are: + + <dl> +<dt><code>-D </code><var>var</var><dd><a name="index-_002dD-_0040var_007bvar_007d-1074"></a>Cause the variable <var>var</var> to be defined. This is equivalent to +<code>@set </code><var>var</var> in the Texinfo file (see <a href="#set-clear-value">set clear value</a>). + + <br><dt><code>--commands-in-node-names</code><dd><a name="index-_002d_002dcommands_002din_002dnode_002dnames-1075"></a>Allow <code>@</code>-commands in node names. This is not recommended, as it +can probably never be implemented in TeX. It also makes +<code>makeinfo</code> much slower. Also, this option is ignored when +<span class="samp">--no-validate</span> is used. See <a href="#Pointer-Validation">Pointer Validation</a>, for more +details. + + <br><dt><code>--css-include=</code><var>file</var><dd><a name="index-_002d_002dcss_002dinclude-1076"></a>Include the contents of <var>file</var>, which should contain cascading +style sheets specifications, in the <span class="samp"><style></span> block of the HTML +output. See <a href="#HTML-CSS">HTML CSS</a>. If <var>file</var> is <span class="samp">-</span>, read standard +input. + + <br><dt><code>--docbook</code><dd><a name="index-_002d_002ddocbook-1077"></a>Generate Docbook output rather than Info. + + <br><dt><code>--enable-encoding</code><dd><a name="index-_002d_002denable_002dencoding-1078"></a>Output accented and special characters in Info or plain text output +based on <span class="samp">@documentencoding</span>. +See <a href="#documentencoding"><code>documentencoding</code></a>, and <a href="#Inserting-Accents">Inserting Accents</a>. + + <br><dt><code>--error-limit=</code><var>limit</var><dt><code>-e </code><var>limit</var><dd><a name="index-_002d_002derror_002dlimit_003d_0040var_007blimit_007d-1079"></a><a name="index-_002de-_0040var_007blimit_007d-1080"></a>Set the maximum number of errors that <code>makeinfo</code> will report +before exiting (on the assumption that continuing would be useless); +default 100. + + <br><dt><code>--fill-column=</code><var>width</var><dt><code>-f </code><var>width</var><dd><a name="index-_002d_002dfill_002dcolumn_003d_0040var_007bwidth_007d-1081"></a><a name="index-_002df-_0040var_007bwidth_007d-1082"></a>Specify the maximum number of columns in a line; this is the right-hand +edge of a line. Paragraphs that are filled will be filled to this +width. (Filling is the process of breaking up and connecting lines so +that lines are the same length as or shorter than the number specified +as the fill column. Lines are broken between words.) The default value +is 72. Ignored with <span class="samp">--html</span>. + + <br><dt><code>--footnote-style=</code><var>style</var><dt><code>-s </code><var>style</var><dd><a name="index-_002d_002dfootnote_002dstyle_003d_0040var_007bstyle_007d-1083"></a><a name="index-_002ds-_0040var_007bstyle_007d-1084"></a>Set the footnote style to <var>style</var>, either <span class="samp">end</span> for the end +node style (the default) or <span class="samp">separate</span> for the separate node style. +The value set by this option overrides the value set in a Texinfo file +by an <code>@footnotestyle</code> command (see <a href="#Footnotes">Footnotes</a>). When the +footnote style is <span class="samp">separate</span>, <code>makeinfo</code> makes a new node +containing the footnotes found in the current node. When the footnote +style is <span class="samp">end</span>, <code>makeinfo</code> places the footnote references at +the end of the current node. Ignored with <span class="samp">--html</span>. + + <br><dt><code>--force</code><dt><code>-F</code><dd><a name="index-_002d_002dforce-1085"></a><a name="index-_002dF-1086"></a>Ordinarily, if the input file has errors, the output files are not +created. With this option, they are preserved. + + <br><dt><code>--help</code><dt><code>-h</code><dd><a name="index-_002d_002dhelp-1087"></a><a name="index-_002dh-1088"></a>Print a usage message listing all available options, then exit successfully. + + <br><dt><code>--html</code><dd><a name="index-_002d_002dhtml-1089"></a>Generate HTML output rather than Info. See <a href="#Generating-HTML">Generating HTML</a>. By +default, the HTML output is split into one output file per Texinfo +source node, and the split output is written into a subdirectory with +the name of the top-level info file. + + <br><dt><code>-I </code><var>dir</var><dd><a name="index-_002dI-_0040var_007bdir_007d-1090"></a>Append <var>dir</var> to the directory search list for finding files that +are included using the <code>@include</code> command. By default, +<code>makeinfo</code> searches only the current directory. If <var>dir</var> is +not given, the current directory <span class="file">.</span> is appended. Note that +<var>dir</var> can actually be a list of several directories separated by the +usual path separator character (<span class="samp">:</span> on Unix, <span class="samp">;</span> on +MS-DOS/MS-Windows). + + <br><dt><code>--ifdocbook</code><dd><a name="index-_002d_002difdocbook-1091"></a><dt><code>--ifhtml</code><dd><a name="index-_002d_002difhtml-1092"></a><dt><code>--ifinfo</code><dd><a name="index-_002d_002difinfo-1093"></a><dt><code>--ifplaintext</code><dd><a name="index-_002d_002difplaintext-1094"></a><dt><code>--iftex</code><dd><a name="index-_002d_002diftex-1095"></a><dt><code>--ifxml</code><dd><a name="index-_002d_002difxml-1096"></a>For the specified format, process <span class="samp">@if</span><var>format</var> and +<span class="samp">@</span><var>format</var> commands even if not generating the given output +format. For instance, if <span class="option">--iftex</span> is specified, then +<span class="samp">@iftex</span> and <span class="samp">@tex</span> blocks will be read. This can be useful +when postprocessing the output. + + <br><dt><code>--macro-expand=</code><var>file</var><dt><code>-E </code><var>file</var><dd><a name="index-_002d_002dmacro_002dexpand_003d_0040var_007bfile_007d-1097"></a><a name="index-_002dE-_0040var_007bfile_007d-1098"></a>Output the Texinfo source with all the macros expanded to the named +file. Normally, the results of macro expansion are used internally by +<code>makeinfo</code> and then discarded. This option is used by +<span class="command">texi2dvi</span>. + + <br><dt><code>--no-headers</code><dd><a name="index-_002d_002dno_002dheaders-1099"></a><a name="index-Plain-text-output-1100"></a><a name="index-ASCII-text-output-1101"></a><a name="index-Generating-plain-text-files-1102"></a><a name="index-_0040file_007bINSTALL_007d-file_002c-generating-1103"></a><a name="index-Node-separators_002c-omitting-1104"></a><a name="index-Menus_002c-omitting-1105"></a>For Info output, do not include menus or node separator lines in the +output, and implicitly <span class="option">--enable-encoding</span> (see above). This +results in a simple plain text file that you can (for example) send in +email without complications, or include in a distribution (as in an +<span class="file">INSTALL</span> file). + + <p><a name="index-Navigation-links_002c-omitting-1106"></a>For HTML output, likewise omit menus. And if <span class="samp">--no-split</span> is also +specified, do not include a navigation links at the top of each node +(these are never included in the default case of split output). +See <a href="#Generating-HTML">Generating HTML</a>. + + <p>In both cases, ignore <code>@setfilename</code> and write to standard +output by default—can be overridden with <span class="option">-o</span>. + + <br><dt><code>--no-ifdocbook</code><dd><a name="index-_002d_002dno_002difdocbook-1107"></a><dt><code>--no-ifhtml</code><dd><a name="index-_002d_002dno_002difhtml-1108"></a><dt><code>--no-ifinfo</code><dd><a name="index-_002d_002dno_002difinfo-1109"></a><dt><code>--no-ifplaintext</code><dd><a name="index-_002d_002dno_002difplaintext-1110"></a><dt><code>--no-iftex</code><dd><a name="index-_002d_002dno_002diftex-1111"></a><dt><code>--no-ifxml</code><dd><a name="index-_002d_002dno_002difxml-1112"></a>Do not process <span class="samp">@if</span><var>format</var> and <span class="samp">@</span><var>format</var> +commands even if generating the given format. For instance, if +<span class="option">--no-ifhtml</span> is specified, then <span class="samp">@ifhtml</span> and +<span class="samp">@html</span> blocks will not be read. + + <br><dt><code>--no-split</code><dd><a name="index-_002d_002dno_002dsplit-1113"></a><a name="index-Splitting-of-output-files-1114"></a><a name="index-Output-file-splitting-1115"></a>Suppress the splitting stage of <code>makeinfo</code>. By default, large +output files (where the size is greater than 70k bytes) are split into +smaller subfiles. For Info output, each one is approximately 50k bytes. +For HTML output, each file contains one node (see <a href="#Generating-HTML">Generating HTML</a>). + + <br><dt><code>--no-pointer-validate</code><dt><code>--no-validate</code><dd><a name="index-_002d_002dno_002dpointer_002dvalidate-1116"></a><a name="index-_002d_002dno_002dvalidate-1117"></a><a name="index-Pointer-validation_002c-suppressing-1118"></a>Suppress the pointer-validation phase of <code>makeinfo</code>. This can also +be done with the <code>@novalidate</code> command (see <a href="#Use-TeX">Use TeX</a>). Normally, after a Texinfo file is processed, some consistency +checks are made to ensure that cross references can be resolved, etc. +See <a href="#Pointer-Validation">Pointer Validation</a>. + + <br><dt><code>--no-warn</code><dd><a name="index-_002d_002dno_002dwarn-1119"></a>Suppress warning messages (but <em>not</em> error messages). You might +want this if the file you are creating has examples of Texinfo cross +references within it, and the nodes that are referenced do not actually +exist. + + <br><dt><code>--number-sections</code><dd><a name="index-_002d_002dnumber_002dsections-1120"></a>Output chapter, section, and appendix numbers as in printed manuals. + + <br><dt><code>--no-number-footnotes</code><dd><a name="index-_002d_002dno_002dnumber_002dfootnotes-1121"></a>Suppress automatic footnote numbering. By default, <code>makeinfo</code> +numbers each footnote sequentially in a single node, resetting the +current footnote number to 1 at the start of each node. + + <br><dt><code>--output=</code><var>file</var><dt><code>-o </code><var>file</var><dd><a name="index-_002d_002doutput_003d_0040var_007bfile_007d-1122"></a><a name="index-_002do-_0040var_007bfile_007d-1123"></a>Specify that the output should be directed to <var>file</var> and not to the +file name specified in the <code>@setfilename</code> command found in the +Texinfo source (see <a href="#setfilename">setfilename</a>). If <var>file</var> is <span class="samp">-</span>, output +goes to standard output and <span class="samp">--no-split</span> is implied. For split +HTML output, <var>file</var> is the name for the directory into which all +HTML nodes are written (see <a href="#Generating-HTML">Generating HTML</a>). + + <br><dt><code>-P </code><var>dir</var><dd><a name="index-_002dP-_0040var_007bdir_007d-1124"></a>Prepend <var>dir</var> to the directory search list for <code>@include</code>. +If <var>dir</var> is not given, the current directory <span class="file">.</span> is prepended. +See <span class="samp">-I</span> for more details. + + <br><dt><code>--paragraph-indent=</code><var>indent</var><dt><code>-p </code><var>indent</var><dd><a name="index-_002d_002dparagraph_002dindent_003d_0040var_007bindent_007d-1125"></a><a name="index-_002dp-_0040var_007bindent_007d-1126"></a>Set the paragraph indentation style to <var>indent</var>. The value set by +this option overrides the value set in a Texinfo file by an +<code>@paragraphindent</code> command (see <a href="#paragraphindent">paragraphindent</a>). The value +of <var>indent</var> is interpreted as follows: + + <dl> +<dt><span class="samp">asis</span><dd>Preserve any existing indentation at the starts of paragraphs. + + <br><dt><span class="samp">0</span> or <span class="samp">none</span><dd>Delete any existing indentation. + + <br><dt><var>num</var><dd>Indent each paragraph by <var>num</var> spaces. +</dl> + + <br><dt><code>--reference-limit=</code><var>limit</var><dt><code>-r </code><var>limit</var><dd><a name="index-_002d_002dreference_002dlimit_003d_0040var_007blimit_007d-1127"></a><a name="index-_002dr-_0040var_007blimit_007d-1128"></a>Set the value of the number of references to a node that +<code>makeinfo</code> will make without reporting a warning. If a node has more +than this number of references in it, <code>makeinfo</code> will make the +references but also report a warning. The default is 1000. + + <br><dt><code>--split-size=</code><var>num</var><dd><a name="index-_002d_002dsplit_002dsize_003d_0040var_007bnum_007d-1129"></a>Keep Info files to at most <var>num</var> characters; default is 300,000. + + <br><dt><code>-U </code><var>var</var><dd>Cause <var>var</var> to be undefined. This is equivalent to +<code>@clear </code><var>var</var> in the Texinfo file (see <a href="#set-clear-value">set clear value</a>). + + <br><dt><code>--verbose</code><dd><a name="index-_002d_002dverbose-1130"></a>Cause <code>makeinfo</code> to display messages saying what it is doing. +Normally, <code>makeinfo</code> only outputs messages if there are errors or +warnings. + + <br><dt><code>--version</code><dt><code>-V</code><dd><a name="index-_002d_002dversion-1131"></a><a name="index-_002dV-1132"></a>Print the version number, then exit successfully. + + <br><dt><code>--xml</code><dd><a name="index-_002d_002dxml-1133"></a>Generate XML output rather than Info. + + </dl> + + <p><a name="index-TEXINFO_005fOUTPUT_005fFORMAT-1134"></a><a name="index-Environment-variable-_0040code_007bTEXINFO_005fOUTPUT_005fFORMAT_007d-1135"></a><span class="command">makeinfo</span> also reads the environment variable +<span class="env">TEXINFO_OUTPUT_FORMAT</span> to determine the output format, if not +overridden by a command line option. The possible values are: + +<pre class="example"> docbook html info plaintext xml +</pre> + <p>If not set, Info output is the default. + +<div class="node"> +<p><hr> +<a name="Pointer-Validation"></a>Next: <a rel="next" accesskey="n" href="#makeinfo-in-Emacs">makeinfo in Emacs</a>, +Previous: <a rel="previous" accesskey="p" href="#makeinfo-options">makeinfo options</a>, +Up: <a rel="up" accesskey="u" href="#Creating-an-Info-File">Creating an Info File</a> +<br> +</div> + +<h4 class="subsection">21.1.4 Pointer Validation</h4> + +<p><a name="index-Pointer-validation-with-_0040code_007bmakeinfo_007d-1136"></a><a name="index-Validation-of-pointers-1137"></a> +If you do not suppress pointer validation with the <span class="samp">--no-validate</span> +option or the <code>@novalidate</code> command in the source file (see <a href="#Use-TeX">Use TeX</a>), <code>makeinfo</code> will check the validity of the final +Info file. Mostly, this means ensuring that nodes you have referenced +really exist. Here is a complete list of what is checked: + + <ol type=1 start=1> +<li>If a `Next', `Previous', or `Up' node reference is a reference to a +node in the current file and is not an external reference such as to +<span class="file">(dir)</span>, then the referenced node must exist. + + <li>In every node, if the `Previous' node is different from the `Up' node, +then the node pointed to by the `Previous' field must have a `Next' +field which points back to this node. + + <li>Every node except the `Top' node must have an `Up' pointer. + + <li>The node referenced by an `Up' pointer must itself reference the current +node through a menu item, unless the node referenced by `Up' +has the form `(<var>file</var>)'. + + <li>If the `Next' reference of a node is not the same as the `Next' reference +of the `Up' reference, then the node referenced by the `Next' pointer +must have a `Previous' pointer that points back to the current node. +This rule allows the last node in a section to point to the first node +of the next chapter. + + <li>Every node except `Top' should be referenced by at least one other node, +either via the `Previous' or `Next' links, or via a menu or a +cross-reference. + </ol> + + <p><a name="index-_0040_0040_002dcommands-in-_0040_0040node_002c-limited-support-1138"></a>Some Texinfo documents might fail during the validation phase because +they use commands like <code>@value</code> and <code>@definfoenclose</code> in +node definitions and cross-references inconsistently. Consider the +following example: + +<pre class="example"> @set nodename Node 1 + + @node @value{nodename}, Node 2, Top, Top + + This is node 1. + + @node Node 2, , Node 1, Top + + This is node 2. +</pre> + <p class="noindent">Here, the node “Node 1” was referenced both verbatim and through +<code>@value</code>. + + <p>By default, <code>makeinfo</code> fails such cases, because node names are not +fully expanded until they are written to the output file. You should +always try to reference nodes consistently; e.g., in the above example, +the second <code>@node</code> line should have also used <code>@value</code>. +However, if, for some reason, you <em>must</em> reference node names +inconsistently, and <code>makeinfo</code> fails to validate the file, you can +use the <span class="samp">--commands-in-node-names</span> option to force <code>makeinfo</code> +to perform the expensive expansion of all node names it finds in the +document. This might considerably slow down the program, though; +twofold increase in conversion time was measured for large documents +such as the Jargon file. + + <p><a name="index-_0040_0040value-in-_0040_0040node-lines-1139"></a>The support for <code>@</code>-commands in <code>@node</code> directives is not +general enough to be freely used. For example, if the example above +redefined <code>nodename</code> somewhere in the document, <code>makeinfo</code> +will fail to convert it, even if invoked with the +<span class="samp">--commands-in-node-names</span> option. + + <p><span class="samp">--commands-in-node-names</span> has no effect if the <span class="samp">--no-validate</span> +option is given. + +<div class="node"> +<p><hr> +<a name="makeinfo-in-Emacs"></a>Next: <a rel="next" accesskey="n" href="#texinfo_002dformat-commands">texinfo-format commands</a>, +Previous: <a rel="previous" accesskey="p" href="#Pointer-Validation">Pointer Validation</a>, +Up: <a rel="up" accesskey="u" href="#Creating-an-Info-File">Creating an Info File</a> +<br> +</div> + +<h4 class="subsection">21.1.5 Running <code>makeinfo</code> Within Emacs</h4> + +<p><a name="index-Running-_0040code_007bmakeinfo_007d-in-Emacs-1140"></a><a name="index-_0040code_007bmakeinfo_007d-inside-Emacs-1141"></a><a name="index-Shell_002c-running-_0040code_007bmakeinfo_007d-in-1142"></a> +You can run <code>makeinfo</code> in GNU Emacs Texinfo mode by using either the +<code>makeinfo-region</code> or the <code>makeinfo-buffer</code> commands. In +Texinfo mode, the commands are bound to <kbd>C-c C-m C-r</kbd> and <kbd>C-c +C-m C-b</kbd> by default. + + <dl> +<dt><kbd>C-c C-m C-r</kbd><dt><kbd>M-x makeinfo-region</kbd><dd>Format the current region for Info. +<a name="index-makeinfo_002dregion-1143"></a> +<br><dt><kbd>C-c C-m C-b</kbd><dt><kbd>M-x makeinfo-buffer</kbd><dd>Format the current buffer for Info. +<a name="index-makeinfo_002dbuffer-1144"></a></dl> + + <p>When you invoke <code>makeinfo-region</code> the output goes to a temporary +buffer. When you invoke <code>makeinfo-buffer</code> output goes to the +file set with <code>@setfilename</code> (see <a href="#setfilename">setfilename</a>). + + <p>The Emacs <code>makeinfo-region</code> and <code>makeinfo-buffer</code> commands +run the <code>makeinfo</code> program in a temporary shell buffer. If +<code>makeinfo</code> finds any errors, Emacs displays the error messages in +the temporary buffer. + + <p><a name="index-Errors_002c-parsing-1145"></a><a name="index-Parsing-errors-1146"></a><a name="index-next_002derror-1147"></a>You can parse the error messages by typing <kbd>C-x `</kbd> +(<code>next-error</code>). This causes Emacs to go to and position the +cursor on the line in the Texinfo source that <code>makeinfo</code> thinks +caused the error. See <a href="emacs.html#Compilation">Running <code>make</code> or Compilers Generally (The GNU Emacs Manual)</a>, for more +information about using the <code>next-error</code> command. + + <p>In addition, you can kill the shell in which the <code>makeinfo</code> +command is running or make the shell buffer display its most recent +output. + + <dl> +<dt><kbd>C-c C-m C-k</kbd><dt><kbd>M-x makeinfo-kill-job</kbd><dd><a name="index-makeinfo_002dkill_002djob-1148"></a>Kill the current running <code>makeinfo</code> job +(from <code>makeinfo-region</code> or <code>makeinfo-buffer</code>). + + <br><dt><kbd>C-c C-m C-l</kbd><dt><kbd>M-x makeinfo-recenter-output-buffer</kbd><dd><a name="index-makeinfo_002drecenter_002doutput_002dbuffer-1149"></a>Redisplay the <code>makeinfo</code> shell buffer to display its most recent +output. +</dl> + +<p class="noindent">(Note that the parallel commands for killing and recentering a TeX +job are <kbd>C-c C-t C-k</kbd> and <kbd>C-c C-t C-l</kbd>. See <a href="#Texinfo-Mode-Printing">Texinfo Mode Printing</a>.) + + <p>You can specify options for <code>makeinfo</code> by setting the +<code>makeinfo-options</code> variable with either the <kbd>M-x +customize</kbd> or the <kbd>M-x set-variable</kbd> command, or by setting the +variable in your <span class="file">.emacs</span> initialization file. + + <p>For example, you could write the following in your <span class="file">.emacs</span> file: + +<pre class="example"> (setq makeinfo-options + "--paragraph-indent=0 --no-split + --fill-column=70 --verbose") +</pre> + <p class="noindent"><!-- If you write these three cross references using xref, you see --> +<!-- three references to the same named manual, which looks strange. --> +For more information, see<br> +<a href="emacs.html#Easy-Customization">Easy Customization Interface (The GNU Emacs Manual)</a>,<br> +<a href="emacs.html#Examining">Examining and Setting Variables (The GNU Emacs Manual)</a>,<br> +<a href="emacs.html#Init-File">Init File (The GNU Emacs Manual)</a>, and<br> +<a href="#makeinfo-options">Options for <code>makeinfo</code></a>. + +<div class="node"> +<p><hr> +<a name="texinfo_002dformat-commands"></a>Next: <a rel="next" accesskey="n" href="#Batch-Formatting">Batch Formatting</a>, +Previous: <a rel="previous" accesskey="p" href="#makeinfo-in-Emacs">makeinfo in Emacs</a>, +Up: <a rel="up" accesskey="u" href="#Creating-an-Info-File">Creating an Info File</a> +<br> +</div> + +<h4 class="subsection">21.1.6 The <code>texinfo-format...</code> Commands</h4> + +<p>In GNU Emacs in Texinfo mode, you can format part or all of a Texinfo +file with the <code>texinfo-format-region</code> command. This formats the +current region and displays the formatted text in a temporary buffer +called <span class="samp">*Info Region*</span>. + + <p>Similarly, you can format a buffer with the +<code>texinfo-format-buffer</code> command. This command creates a new +buffer and generates the Info file in it. Typing <kbd>C-x C-s</kbd> will +save the Info file under the name specified by the +<code>@setfilename</code> line which must be near the beginning of the +Texinfo file. + + <dl> +<dt><kbd>C-c C-e C-r</kbd><dt><code>texinfo-format-region</code><dd><a name="index-texinfo_002dformat_002dregion-1150"></a>Format the current region for Info. + + <br><dt><kbd>C-c C-e C-b</kbd><dt><code>texinfo-format-buffer</code><dd><a name="index-texinfo_002dformat_002dbuffer-1151"></a>Format the current buffer for Info. +</dl> + + <p>The <code>texinfo-format-region</code> and <code>texinfo-format-buffer</code> +commands provide you with some error checking, and other functions can +provide you with further help in finding formatting errors. These +procedures are described in an appendix; see <a href="#Catching-Mistakes">Catching Mistakes</a>. +However, the <code>makeinfo</code> program is often faster and +provides better error checking (see <a href="#makeinfo-in-Emacs">makeinfo in Emacs</a>). + +<div class="node"> +<p><hr> +<a name="Batch-Formatting"></a>Next: <a rel="next" accesskey="n" href="#Tag-and-Split-Files">Tag and Split Files</a>, +Previous: <a rel="previous" accesskey="p" href="#texinfo_002dformat-commands">texinfo-format commands</a>, +Up: <a rel="up" accesskey="u" href="#Creating-an-Info-File">Creating an Info File</a> +<br> +</div> + +<!-- node-name, next, previous, up --> +<h4 class="subsection">21.1.7 Batch Formatting</h4> + +<p><a name="index-Batch-formatting-for-Info-1152"></a><a name="index-Info-batch-formatting-1153"></a> +You can format Texinfo files for Info using <code>batch-texinfo-format</code> +and Emacs Batch mode. You can run Emacs in Batch mode from any shell, +including a shell inside of Emacs. (See <a href="emacs.html#Command-Arguments">Command Arguments (The GNU Emacs Manual)</a>.) + + <p>Here is a shell command to format all the files that end in +<span class="file">.texinfo</span> in the current directory: + +<pre class="example"> emacs -batch -funcall batch-texinfo-format *.texinfo +</pre> + <p class="noindent">Emacs processes all the files listed on the command line, even if an +error occurs while attempting to format some of them. + + <p>Run <code>batch-texinfo-format</code> only with Emacs in Batch mode as shown; +it is not interactive. It kills the Batch mode Emacs on completion. + + <p><code>batch-texinfo-format</code> is convenient if you lack <code>makeinfo</code> +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 +<code>texinfo-format-region</code> or <code>texinfo-format-buffer</code>, you cannot +use that Emacs for anything else until the command finishes.) + +<div class="node"> +<p><hr> +<a name="Tag-and-Split-Files"></a>Previous: <a rel="previous" accesskey="p" href="#Batch-Formatting">Batch Formatting</a>, +Up: <a rel="up" accesskey="u" href="#Creating-an-Info-File">Creating an Info File</a> +<br> +</div> + +<!-- node-name, next, previous, up --> +<h4 class="subsection">21.1.8 Tag Files and Split Files</h4> + +<p><a name="index-Making-a-tag-table-automatically-1154"></a><a name="index-Tag-table_002c-making-automatically-1155"></a> +If a Texinfo file has more than 30,000 bytes, +<code>texinfo-format-buffer</code> automatically creates a tag table +for its Info file; <code>makeinfo</code> always creates a tag table. With +a <dfn>tag table</dfn>, Info can jump to new nodes more quickly than it can +otherwise. + + <p><a name="index-Indirect-subfiles-1156"></a>In addition, if the Texinfo file contains more than about 300,000 +bytes, <code>texinfo-format-buffer</code> and <code>makeinfo</code> split the +large Info file into shorter <dfn>indirect</dfn> 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 <dfn>include files</dfn> were designed as +a way to create a single, large printed manual out of the smaller Info +files. See <a href="#Include-Files">Include Files</a>, for more information. Include files are +still used for very large documents, such as <cite>The Emacs Lisp +Reference Manual</cite>, in which each chapter is a separate file.) + + <p>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 +<dfn>indirect</dfn> files. + + <p>The split-off files have names that are created by appending <span class="samp">-1</span><!-- /@w -->, +<span class="samp">-2</span><!-- /@w -->, <span class="samp">-3</span><!-- /@w --> and so on to the file name specified by the +<code>@setfilename</code> command. The shortened version of the original file +continues to have the name specified by <code>@setfilename</code>. + + <p>At one stage in writing this document, for example, the Info file was saved +as the file <span class="file">test-texinfo</span> and that file looked like this: + +<pre class="example"> 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 + ... +</pre> + <p class="noindent">(But <span class="file">test-texinfo</span> had far more nodes than are shown here.) Each of +the split-off, indirect files, <span class="file">test-texinfo-1</span>, +<span class="file">test-texinfo-2</span>, and <span class="file">test-texinfo-3</span>, is listed in this file +after the line that says <span class="samp">Indirect:</span>. The tag table is listed after +the line that says <span class="samp">Tag table:</span>. + + <p>In the list of indirect files, the number following the file name +records the cumulative number of bytes in the preceding indirect files, +not counting the file list itself, the tag table, or the permissions +text in each file. In the tag table, the number following the node name +records the location of the beginning of the node, in bytes from the +beginning of the (unsplit) output. + + <p>If you are using <code>texinfo-format-buffer</code> to create Info files, +you may want to run the <code>Info-validate</code> command. (The +<code>makeinfo</code> command does such a good job on its own, you do not +need <code>Info-validate</code>.) However, you cannot run the <kbd>M-x +Info-validate</kbd> 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 <a href="#Using-Info_002dvalidate">Using Info-validate</a>. + +<div class="node"> +<p><hr> +<a name="Installing-an-Info-File"></a>Previous: <a rel="previous" accesskey="p" href="#Creating-an-Info-File">Creating an Info File</a>, +Up: <a rel="up" accesskey="u" href="#Creating-and-Installing-Info-Files">Creating and Installing Info Files</a> +<br> +</div> + +<h3 class="section">21.2 Installing an Info File</h3> + +<p><a name="index-Installing-an-Info-file-1157"></a><a name="index-Info-file-installation-1158"></a><a name="index-_0040file_007bdir_007d-directory-for-Info-installation-1159"></a> +Info files are usually kept in the <span class="file">info</span> directory. You can read +Info files using the standalone Info program or the Info reader built +into Emacs. (see <a href="info.html#Top">info</a>, for an introduction to Info.) + +<ul class="menu"> +<li><a accesskey="1" href="#Directory-File">Directory File</a>: The top level menu for all Info files. +<li><a accesskey="2" href="#New-Info-File">New Info File</a>: Listing a new Info file. +<li><a accesskey="3" href="#Other-Info-Directories">Other Info Directories</a>: How to specify Info files that are + located in other directories. +<li><a accesskey="4" href="#Installing-Dir-Entries">Installing Dir Entries</a>: How to specify what menu entry to add + to the Info directory. +<li><a accesskey="5" href="#Invoking-install_002dinfo">Invoking install-info</a>: <code>install-info</code> options. +</ul> + +<div class="node"> +<p><hr> +<a name="Directory-File"></a>Next: <a rel="next" accesskey="n" href="#New-Info-File">New Info File</a>, +Up: <a rel="up" accesskey="u" href="#Installing-an-Info-File">Installing an Info File</a> +<br> +</div> + +<h4 class="subsection">21.2.1 The Directory File <span class="file">dir</span></h4> + +<p>For Info to work, the <span class="file">info</span> directory must contain a file that +serves as a top level directory for the Info system. By convention, +this file is called <span class="file">dir</span>. (You can find the location of this file +within Emacs by typing <kbd>C-h i</kbd> to enter Info and then typing +<kbd>C-x C-f</kbd> to see the pathname to the <span class="file">info</span> directory.) + + <p>The <span class="file">dir</span> 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: + +<pre class="example"> * 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. + ... +</pre> + <p>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. See <a href="#Other-Info-Files">Nodes in Other Info Files</a>.) + + <p>Thus, the <span class="samp">Info</span> entry points to the `Top' node of the +<span class="file">info</span> file and the <span class="samp">Emacs</span> entry points to the `Top' node +of the <span class="file">emacs</span> file. + + <p>In each of the Info files, the `Up' pointer of the `Top' node refers +back to the <code>dir</code> file. For example, the line for the `Top' +node of the Emacs manual looks like this in Info: + +<pre class="example"> File: emacs Node: Top, Up: (DIR), Next: Distrib +</pre> + <p class="noindent">In this case, the <span class="file">dir</span> file name is written in upper case +letters—it can be written in either upper or lower case. This is not +true in general, it is a special case for <span class="file">dir</span>. + +<div class="node"> +<p><hr> +<a name="New-Info-File"></a>Next: <a rel="next" accesskey="n" href="#Other-Info-Directories">Other Info Directories</a>, +Previous: <a rel="previous" accesskey="p" href="#Directory-File">Directory File</a>, +Up: <a rel="up" accesskey="u" href="#Installing-an-Info-File">Installing an Info File</a> +<br> +</div> + +<h4 class="subsection">21.2.2 Listing a New Info File</h4> + +<p><a name="index-Adding-a-new-Info-file-1160"></a><a name="index-Listing-a-new-Info-file-1161"></a><a name="index-New-Info-file_002c-listing-it-in-_0040file_007bdir_007d-file-1162"></a><a name="index-Info-file_002c-listing-a-new-1163"></a><a name="index-_0040file_007bdir_007d-file-listing-1164"></a> +To add a new Info file to your system, you must write a menu entry to +add to the menu in the <span class="file">dir</span> file in the <span class="file">info</span> directory. +For example, if you were adding documentation for GDB, you would write +the following new entry: + +<pre class="example"> * GDB: (gdb). The source-level C debugger. +</pre> + <p class="noindent">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. + + <p>The name of an Info file often has a <span class="file">.info</span> extension. Thus, the +Info file for GDB might be called either <span class="file">gdb</span> or <span class="file">gdb.info</span>. +The Info reader programs automatically try the file name both with and +without <span class="file">.info</span><a rel="footnote" href="#fn-10" name="fnd-10"><sup>10</sup></a>; so it is better to avoid +clutter and not to write <span class="samp">.info</span> explicitly in the menu entry. For +example, the GDB menu entry should use just <span class="samp">gdb</span> for the file +name, not <span class="samp">gdb.info</span>. + +<div class="node"> +<p><hr> +<a name="Other-Info-Directories"></a>Next: <a rel="next" accesskey="n" href="#Installing-Dir-Entries">Installing Dir Entries</a>, +Previous: <a rel="previous" accesskey="p" href="#New-Info-File">New Info File</a>, +Up: <a rel="up" accesskey="u" href="#Installing-an-Info-File">Installing an Info File</a> +<br> +</div> + +<h4 class="subsection">21.2.3 Info Files in Other Directories</h4> + +<p><a name="index-Installing-Info-in-another-directory-1165"></a><a name="index-Info-installed-in-another-directory-1166"></a><a name="index-Another-Info-directory-1167"></a><a name="index-_0040file_007bdir_007d-files-and-Info-directories-1168"></a> +If an Info file is not in the <span class="file">info</span> directory, there are three +ways to specify its location: + + <ol type=1 start=1> +<li>Write the pathname in the <span class="file">dir</span> file as the second part of the menu. + + <li>If you are using Emacs, list the name of the file in a second <span class="file">dir</span> +file, in its directory; and then add the name of that directory to the +<code>Info-directory-list</code> variable in your personal or site +initialization file. + + <p>This variable tells Emacs where to look for <span class="file">dir</span> files (the files +must be named <span class="file">dir</span>). Emacs merges the files named <span class="file">dir</span> from +each of the listed directories. (In Emacs version 18, you can set the +<code>Info-directory</code> variable to the name of only one +directory.) + + <li>Specify the Info directory name in the <code>INFOPATH</code> environment +variable in your <span class="file">.profile</span> or <span class="file">.cshrc</span> initialization file. +(Only you and others who set this environment variable will be able to +find Info files whose location is specified this way.) + </ol> + + <p>For example, to reach a test file in the <span class="file">/home/bob/info</span> +directory, you could add an entry like this to the menu in the +standard <span class="file">dir</span> file: + +<pre class="example"> * Test: (/home/bob/info/info-test). Bob's own test file. +</pre> + <p class="noindent">In this case, the absolute file name of the <span class="file">info-test</span> file is +written as the second part of the menu entry. + + <p>Alternatively, you could write the following in your <span class="file">.emacs</span> file: + + <p><a name="index-Info_002ddirectory_002dlist-1169"></a> +<pre class="example"> (require 'info) + (setq Info-directory-list + (cons (expand-file-name "/home/bob/info") + Info-directory-list)) +</pre> + <p>This tells Emacs to merge the system <span class="file">dir</span> file with the <span class="file">dir</span> +file in <span class="file">/home/bob/info</span>. Thus, Info will list the +<span class="file">/home/bob/info/info-test</span> file as a menu entry in the +<span class="file">/home/bob/info/dir</span> file. Emacs does the merging only when +<kbd>M-x info</kbd> is first run, so if you want to set +<code>Info-directory-list</code> in an Emacs session where you've already run +<code>info</code>, you must <code>(setq Info-dir-contents nil)</code> to force Emacs +to recompose the <span class="file">dir</span> file. + + <p><a name="index-INFOPATH-1170"></a><a name="index-Environment-variable-_0040code_007bINFOPATH_007d-1171"></a>Finally, you can tell Info where to look by setting the <code>INFOPATH</code> +environment variable in your shell startup file, such as <span class="file">.cshrc</span>, +<span class="file">.profile</span> or <span class="file">autoexec.bat</span>. If you use a Bourne-compatible +shell such as <code>sh</code> or <code>bash</code> for your shell command +interpreter, you set the <code>INFOPATH</code> environment variable in the +<span class="file">.profile</span> initialization file; but if you use <code>csh</code> or +<code>tcsh</code>, you set the variable in the <span class="file">.cshrc</span> initialization +file. On MS-DOS/MS-Windows systems, you must set <code>INFOPATH</code> in +your <span class="file">autoexec.bat</span> file or in the Registry. Each type of shell +uses a different syntax. + + <ul> +<li>In a <span class="file">.cshrc</span> file, you could set the <code>INFOPATH</code> +variable as follows: + + <pre class="smallexample"> setenv INFOPATH .:~/info:/usr/local/emacs/info + </pre> + <li>In a <span class="file">.profile</span> file, you would achieve the same effect by +writing: + + <pre class="smallexample"> INFOPATH=.:$HOME/info:/usr/local/emacs/info + export INFOPATH + </pre> + <li><a name="index-autoexec_002ebat-1172"></a>In a <span class="file">autoexec.bat</span> file, you write this command<a rel="footnote" href="#fn-11" name="fnd-11"><sup>11</sup></a>: + + <pre class="smallexample"> set INFOPATH=.;%HOME%/info;c:/usr/local/emacs/info + </pre> + </ul> + +<p class="noindent">The <span class="samp">.</span> indicates the current directory as usual. Emacs uses the +<code>INFOPATH</code> environment variable to initialize the value of Emacs's +own <code>Info-directory-list</code> variable. The stand-alone Info reader +merges any files named <span class="file">dir</span> in any directory listed in the +<span class="env">INFOPATH</span> variable into a single menu presented to you in the node +called <span class="samp">(dir)Top</span>. + + <p><a name="index-Colon_002c-last-in-_0040env_007bINFOPATH_007d-1173"></a>However you set <span class="env">INFOPATH</span>, if its last character is a +colon<a rel="footnote" href="#fn-12" name="fnd-12"><sup>12</sup></a>, 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 <code>sh</code> syntax): + +<pre class="example"> INFOPATH=/local/info: + export INFOPATH +</pre> + <p class="noindent">will search <span class="file">/local/info</span> first, then the standard directories. +Leading or doubled colons are not treated specially. + + <p><a name="index-_0040file_007bdir_007d-file_002c-creating-your-own-1174"></a>When you create your own <span class="file">dir</span> file for use with +<code>Info-directory-list</code> or <span class="env">INFOPATH</span>, it's easiest to start by +copying an existing <span class="file">dir</span> file and replace all the text after the +<span class="samp">* Menu:</span> with your desired entries. That way, the punctuation and +special CTRL-_ characters that Info needs will be present. + +<div class="node"> +<p><hr> +<a name="Installing-Dir-Entries"></a>Next: <a rel="next" accesskey="n" href="#Invoking-install_002dinfo">Invoking install-info</a>, +Previous: <a rel="previous" accesskey="p" href="#Other-Info-Directories">Other Info Directories</a>, +Up: <a rel="up" accesskey="u" href="#Installing-an-Info-File">Installing an Info File</a> +<br> +</div> + +<h4 class="subsection">21.2.4 Installing Info Directory Files</h4> + +<p>When you install an Info file onto your system, you can use the program +<code>install-info</code> to update the Info directory file <span class="file">dir</span>. +Normally the makefile for the package runs <code>install-info</code>, just +after copying the Info file into its proper installed location. + + <p><a name="index-dircategory-1175"></a><a name="index-direntry-1176"></a>In order for the Info file to work with <code>install-info</code>, you include +the commands <code>@dircategory</code> and +<code>@direntry</code><small class="dots">...</small><code>@end direntry</code> in the Texinfo source +file. Use <code>@direntry</code> to specify the menu entries to add to the +Info directory file, and use <code>@dircategory</code> to specify which part +of the Info directory to put it in. Here is how these commands are used +in this manual: + +<pre class="smallexample"> @dircategory Texinfo documentation system + @direntry + * Texinfo: (texinfo). The GNU documentation format. + * install-info: (texinfo)Invoking install-info. ... + ... + @end direntry +</pre> + <p>Here's what this produces in the Info file: + +<pre class="smallexample"> 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 +</pre> + <p class="noindent">The <code>install-info</code> program sees these lines in the Info file, and +that is how it knows what to do. + + <p>Always use the <code>@direntry</code> and <code>@dircategory</code> commands near +the beginning of the Texinfo input, before the first <code>@node</code> +command. If you use them later on in the input, <code>install-info</code> +will not notice them. + + <p>If you use <code>@dircategory</code> more than once in the Texinfo source, +each usage specifies the `current' category; any subsequent +<code>@direntry</code> commands will add to that category. + + <p><a name="index-Free-Software-Directory-1177"></a><a name="index-Dir-categories_002c-choosing-1178"></a><a name="index-Categories_002c-choosing-1179"></a>When choosing a category name for the <code>@dircategory</code> command, we +recommend consulting the <a href="http://www.gnu.org/directory">Free Software Directory</a>. If your program is not listed there, +or listed incorrectly or incompletely, please report the situation to +the directory maintainers (<a href="mailto:bug-directory@gnu.org">bug-directory@gnu.org</a>) so that the +category names can be kept in sync. + + <p>Here are a few examples (see the <span class="file">util/dir-example</span> file in the +Texinfo distribution for large sample <code>dir</code> file): + +<pre class="display"> Emacs + Localization + Printing + Software development + Software libraries + Text creation and manipulation +</pre> + <p><a name="index-Invoking-nodes_002c-including-in-dir-file-1180"></a>Each `Invoking' node for every program installed should have a +corresponding <code>@direntry</code>. This lets users easily find the +documentation for the different programs they can run, as with the +traditional <span class="command">man</span> system. + +<div class="node"> +<p><hr> +<a name="Invoking-install_002dinfo"></a>Previous: <a rel="previous" accesskey="p" href="#Installing-Dir-Entries">Installing Dir Entries</a>, +Up: <a rel="up" accesskey="u" href="#Installing-an-Info-File">Installing an Info File</a> +<br> +</div> + +<h4 class="subsection">21.2.5 Invoking <span class="command">install-info</span></h4> + +<p><a name="index-install_002dinfo-1181"></a> +<code>install-info</code> inserts menu entries from an Info file into the +top-level <span class="file">dir</span> file in the Info system (see the previous sections +for an explanation of how the <span class="file">dir</span> file works). It's most often +run as part of software installation, or when constructing a <span class="file">dir</span> file +for all manuals on a system. Synopsis: + +<pre class="example"> install-info [<var>option</var>]... [<var>info-file</var> [<var>dir-file</var>]] +</pre> + <p>If <var>info-file</var> or <var>dir-file</var> are not specified, the options +(described below) that define them must be. There are no compile-time +defaults, and standard input is never used. <code>install-info</code> can +read only one Info file and write only one <span class="file">dir</span> file per invocation. + + <p><a name="index-_0040file_007bdir_007d_002c-created-by-_0040code_007binstall_002dinfo_007d-1182"></a>If <var>dir-file</var> (however specified) does not exist, +<code>install-info</code> creates it if possible (with no entries). + + <p><a name="index-Compressed-files_002c-reading-1183"></a><a name="index-Dir-files_002c-compressed-1184"></a>If any input file is compressed with <code>gzip</code> (see <a href="gzip.html#Invoking-gzip">Invoking gzip (Gzip)</a>), <code>install-info</code> automatically uncompresses it +for reading. And if <var>dir-file</var> is compressed, <code>install-info</code> +also automatically leaves it compressed after writing any changes. +If <var>dir-file</var> itself does not exist, <code>install-info</code> tries to +open <var>dir-file</var><span class="file">.gz</span>. + + <p>Options: + + <dl> +<dt><code>--delete</code><dd><a name="index-_002d_002ddelete-1185"></a>Delete the entries in <var>info-file</var> from <var>dir-file</var>. The file +name in the entry in <var>dir-file</var> must be <var>info-file</var> (except for +an optional <span class="samp">.info</span> in either one). Don't insert any new entries. + + <br><dt><code>--dir-file=</code><var>name</var><dt><code>-d </code><var>name</var><dd><a name="index-_002d_002ddir_002dfile_003d_0040var_007bname_007d-1186"></a><a name="index-_002dd-_0040var_007bname_007d-1187"></a>Specify file name of the Info directory file. This is equivalent to +using the <var>dir-file</var> argument. + + <br><dt><code>--entry=</code><var>text</var><dt><code>-e </code><var>text</var><dd><a name="index-_002d_002dentry_003d_0040var_007btext_007d-1188"></a><a name="index-_002de-_0040var_007btext_007d-1189"></a>Insert <var>text</var> as an Info directory entry; <var>text</var> 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. + + <br><dt><code>--help</code><dt><code>-h</code><dd><a name="index-_002d_002dhelp-1190"></a><a name="index-_002dh-1191"></a>Display a usage message listing basic usage and all available options, +then exit successfully. + + <br><dt><code>--info-file=</code><var>file</var><dt><code>-i </code><var>file</var><dd><a name="index-_002d_002dinfo_002dfile_003d_0040var_007bfile_007d-1192"></a><a name="index-_002di-_0040var_007bfile_007d-1193"></a>Specify Info file to install in the directory. +Equivalent to using the <var>info-file</var> argument. + + <br><dt><code>--info-dir=</code><var>dir</var><dt><code>-D </code><var>dir</var><dd><a name="index-_002d_002dinfo_002ddir_003d_0040var_007bdir_007d-1194"></a><a name="index-_002dD-_0040var_007bdir_007d-1195"></a>Specify the directory where the directory file <span class="file">dir</span> resides. +Equivalent to <span class="samp">--dir-file=</span><var>dir</var><span class="samp">/dir</span>. + + <br><dt><code>--item=</code><var>text</var><dd><a name="index-_002d_002ditem_003d_0040var_007btext_007d-1196"></a>Same as <span class="samp">--entry=</span><var>text</var>. An Info directory entry is actually +a menu item. + + <br><dt><code>--quiet</code><dd><a name="index-_002d_002dquiet-1197"></a>Suppress warnings. + + <br><dt><code>--remove</code><dt><code>-r</code><dd><a name="index-_002d_002dremove-1198"></a><a name="index-_002dr-1199"></a>Same as <span class="samp">--delete</span>. + + <br><dt><code>--section=</code><var>sec</var><dt><code>-s </code><var>sec</var><dd><a name="index-_002d_002dsection_003d_0040var_007bsec_007d-1200"></a><a name="index-_002ds-_0040var_007bsec_007d-1201"></a>Put this file's entries in section <var>sec</var> 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. + + <br><dt><code>--version</code><dt><code>-V</code><dd><a name="index-_002d_002dversion-1202"></a><a name="index-_002dV-1203"></a><a name="index-Version-number_002c-for-install_002dinfo-1204"></a>Display version information and exit successfully. + + </dl> + +<div class="node"> +<p><hr> +<a name="Generating-HTML"></a>Next: <a rel="next" accesskey="n" href="#Command-List">Command List</a>, +Previous: <a rel="previous" accesskey="p" href="#Creating-and-Installing-Info-Files">Creating and Installing Info Files</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> +<br> +</div> + +<h2 class="chapter">22 Generating HTML</h2> + +<p><a name="index-HTML-output-1205"></a> +<span class="command">makeinfo</span> generates Info output by default, but given the +<span class="option">--html</span> option, it will generate HTML, for web browsers and +other programs. This chapter gives some details on such HTML output. + + <p><span class="command">makeinfo</span> can also write in XML and Docbook format, but we do +not as yet describe these further. See <a href="#Output-Formats">Output Formats</a>, for a brief +overview of all the output formats. + +<ul class="menu"> +<li><a accesskey="1" href="#HTML-Translation">HTML Translation</a>: Details of the HTML output. +<li><a accesskey="2" href="#HTML-Splitting">HTML Splitting</a>: How HTML output is split. +<li><a accesskey="3" href="#HTML-CSS">HTML CSS</a>: Influencing HTML output with Cascading Style Sheets. +<li><a accesskey="4" href="#HTML-Xref">HTML Xref</a>: Cross-references in HTML output. +</ul> + +<div class="node"> +<p><hr> +<a name="HTML-Translation"></a>Next: <a rel="next" accesskey="n" href="#HTML-Splitting">HTML Splitting</a>, +Up: <a rel="up" accesskey="u" href="#Generating-HTML">Generating HTML</a> +<br> +</div> + +<h3 class="section">22.1 HTML Translation</h3> + +<p><span class="command">makeinfo</span> will include segments of Texinfo source between +<code>@ifhtml</code> and <code>@end ifhtml</code> in the HTML output (but not +any of the other conditionals, by default). Source between +<code>@html</code> and <code>@end html</code> is passed without change to the +output (i.e., suppressing the normal escaping of input <span class="samp"><</span>, +<span class="samp">></span> and <span class="samp">&</span> characters which have special significance in +HTML). See <a href="#Conditional-Commands">Conditional Commands</a>. + + <p><a name="index-_002d_002dfootnote_002dstyle_0040r_007b_002c-ignored-in-HTML-output_007d-1206"></a>The <span class="option">--footnote-style</span> option is currently ignored for HTML output; +footnotes are always linked to the end of the output file. + + <p><a name="index-Navigation-bar_002c-in-HTML-output-1207"></a>By default, a navigation bar is inserted at the start of each node, +analogous to Info output. The <span class="samp">--no-headers</span> option suppresses +this if used with <span class="samp">--no-split</span>. Header <code><link></code> elements in +split output can support info-like navigation with browsers like Lynx +and Emacs W3<!-- /@w --> which implement this HTML <!-- /@w -->1.0 feature. + + <p><a name="index-HTML-output_002c-browser-compatibility-of-1208"></a>The HTML generated is mostly standard (i.e., HTML <!-- /@w -->2.0, RFC-1866). +One exception is that HTML <!-- /@w -->3.2 tables are generated from the +<code>@multitable</code> command, but tagged to degrade as well as possible +in browsers without table support. The HTML <!-- /@w -->4 <span class="samp">lang</span> +attribute on the <span class="samp"><html></span> attribute is also used. (Please report +output from an error-free run of <code>makeinfo</code> which has browser +portability problems as a bug.) + +<div class="node"> +<p><hr> +<a name="HTML-Splitting"></a>Next: <a rel="next" accesskey="n" href="#HTML-CSS">HTML CSS</a>, +Previous: <a rel="previous" accesskey="p" href="#HTML-Translation">HTML Translation</a>, +Up: <a rel="up" accesskey="u" href="#Generating-HTML">Generating HTML</a> +<br> +</div> + +<h3 class="section">22.2 HTML Splitting</h3> + +<p><a name="index-Split-HTML-output-1209"></a><a name="index-HTML-output_002c-split-1210"></a> +When splitting output (which is the default), <span class="command">makeinfo</span> +writes HTML output into (generally) one output file per Texinfo source +<code>@node</code>. + + <p>The output file name is the node name with special characters replaced +by <span class="samp">-</span>'s, so it can work as a filename. In the unusual case of +two different nodes having the same name after this treatment, they +are written consecutively to the same file, with HTML anchors so each +can be referred to separately. If <span class="command">makeinfo</span> is run on a +system which does not distinguish case in filenames, nodes which are +the same except for case will also be folded into the same output +file. + + <p>When splitting, the HTML output files are written into a subdirectory, +with the name chosen as follows: + <ol type=1 start=1> +<li><span class="command">makeinfo</span> first tries the subdirectory with the base name +from <code>@setfilename</code> (that is, any extension is removed). For +example, HTML output for <code>@setfilename gcc.info</code> would be +written into a subdirectory named <span class="samp">gcc</span>. + + <li>If that directory cannot be created for any reason, then +<span class="command">makeinfo</span> tries appending <span class="samp">.html</span> to the directory name. +For example, output for <code>@setfilename texinfo</code> would be written +to <span class="samp">texinfo.html</span>. + + <li>If the <var>name</var><span class="samp">.html</span> directory can't be +created either, <code>makeinfo</code> gives up. + + </ol> + +<p class="noindent">In any case, the top-level output file within the directory +is always named <span class="samp">index.html</span>. + + <p>Monolithic output (<code>--no-split</code>) is named according to +<code>@setfilename</code> (with any <span class="samp">.info</span> extension is replaced with +<span class="samp">.html</span>) or <code>--output</code> (the argument is used literally). + +<div class="node"> +<p><hr> +<a name="HTML-CSS"></a>Next: <a rel="next" accesskey="n" href="#HTML-Xref">HTML Xref</a>, +Previous: <a rel="previous" accesskey="p" href="#HTML-Splitting">HTML Splitting</a>, +Up: <a rel="up" accesskey="u" href="#Generating-HTML">Generating HTML</a> +<br> +</div> + +<h3 class="section">22.3 HTML CSS</h3> + +<p><a name="index-HTML_002c-and-CSS-1211"></a><a name="index-CSS_002c-and-HTML-output-1212"></a><a name="index-Cascading-Style-Sheets_002c-and-HTML-output-1213"></a> +Cascading Style Sheets (CSS for short) is an Internet standard for +influencing the display of HTML documents: see +<a href="http://www.w3.org/Style/CSS/">http://www.w3.org/Style/CSS/</a>. + + <p>By default, <span class="command">makeinfo</span> includes a few simple CSS commands to +better implement the appearance of some of the environments. Here +are two of them, as an example: + +<pre class="example"> pre.display { font-family:inherit } + pre.smalldisplay { font-family:inherit; font-size:smaller } +</pre> + <p>A full explanation of CSS is (far) beyond this manual; please see the +reference above. In brief, however, this specification tells the web +browser to use a `smaller' font size for <code>@smalldisplay</code> text, +and to use the `inherited' font (generally a regular roman typeface) +for both <code>@smalldisplay</code> and <code>@display</code>. By default, the +HTML <span class="samp"><pre></span> command uses a monospaced font. + + <p>You can influence the CSS in the HTML output with the +<span class="option">--css-include=</span><var>file</var> option to <span class="command">makeinfo</span>. This +includes the contents <var>file</var> in the HTML output, as you might +expect. However, the details are somewhat tricky, as described in the +following, to provide maximum flexibility. + + <p><a name="index-_0040_0040import-specifications_002c-in-CSS-files-1214"></a>The CSS file may begin with so-called <span class="samp">@import</span> 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 <span class="command">makeinfo</span> handles them. + + <p><a name="index-Comments_002c-in-CSS-files-1215"></a>There can be more than one <span class="samp">@import</span>, but they have to come +first in the file, with only whitespace and comments interspersed, no +normal definitions. (Technical exception: an <span class="samp">@charset</span> +directive may precede the <span class="samp">@import</span>'s. This does not alter +<span class="command">makeinfo</span>'s behavior, it just copies the <span class="samp">@charset</span> if +present.) Comments in CSS files are delimited by <span class="samp">/* ... */</span>, as +in C. An <span class="samp">@import</span> directive must be in one of these two forms: + +<pre class="example"> @import url(http://example.org/foo.css); + @import "http://example.net/bar.css"; +</pre> + <p>As far as <span class="command">makeinfo</span> is concerned, the crucial characters are +the <span class="samp">@</span> at the beginning and the semicolon terminating the +directive. When reading the CSS file, it simply copies any such +<span class="samp">@</span>-directive into the output, as follows: + + <ul> +<li>If <var>file</var> contains only normal CSS declarations, it is +included after <span class="command">makeinfo</span>'s default CSS, thus overriding it. + + <li>If <var>file</var> begins with <span class="samp">@import</span> specifications (see +below), then the <span class="samp">import</span>'s are included first (they have to come +first, according to the standard), and then <span class="command">makeinfo</span>'s +default CSS is included. If you need to override <span class="command">makeinfo</span>'s +defaults from an <span class="samp">@import</span>, you can do so with the <span class="samp">! +important</span> CSS construct, as in: + <pre class="example"> pre.smallexample { font-size: inherit ! important } + </pre> + <li>If <var>file</var> contains both <span class="samp">@import</span> and inline CSS +specifications, the <span class="samp">@import</span>'s are included first, then +<span class="command">makeinfo</span>'s defaults, and lastly the inline CSS from +<var>file</var>. + + <li>Any @-directive other than <span class="samp">@import</span> and <span class="samp">@charset</span> +is treated as a CSS declaration, meaning <span class="command">makeinfo</span> includes +its default CSS and then the rest of the file. + + </ul> + + <p>If the CSS file is malformed or erroneous, <span class="command">makeinfo</span>'s output +is unspecified. <span class="command">makeinfo</span> does not try to interpret the +meaning of the CSS file in any way; it just looks for the special +<span class="samp">@</span> and <span class="samp">;</span> characters and blindly copies the text into the +output. Comments in the CSS file may or may not be included in the +output. + +<div class="node"> +<p><hr> +<a name="HTML-Xref"></a>Previous: <a rel="previous" accesskey="p" href="#HTML-CSS">HTML CSS</a>, +Up: <a rel="up" accesskey="u" href="#Generating-HTML">Generating HTML</a> +<br> +</div> + +<h3 class="section">22.4 HTML Cross-references</h3> + +<p><a name="index-HTML-cross_002dreferences-1216"></a><a name="index-Cross_002dreferences_002c-in-HTML-output-1217"></a> +Cross-references between Texinfo manuals in HTML format amount, in the +end, to a standard HTML <code><a></code> 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 +<span class="command">texi2html</span>, by writing mutually compatible HTML files. + + <p>This algorithm may or may not be used for links <em>within</em> HTML +output for a Texinfo file. Since no issues of compatibility arise in +such cases, we do not need to specify this. + + <p>We try to support references to such “external” manuals in both +monolithic and split forms. A <dfn>monolithic</dfn> (mono) manual is +entirely contained in one file, and a <dfn>split</dfn> manual has a file +for each node. (See <a href="#HTML-Splitting">HTML Splitting</a>.) + + <p><a name="index-Dumas_002c-Patrice-1218"></a>Acknowledgement: this algorithm was primarily devised by Patrice Dumas +in 2003–04. + +<ul class="menu"> +<li><a accesskey="1" href="#HTML-Xref-Link-Basics">Link Basics</a> +<li><a accesskey="2" href="#HTML-Xref-Node-Name-Expansion">Node Expansion</a> +<li><a accesskey="3" href="#HTML-Xref-Command-Expansion">Command Expansion</a> +<li><a accesskey="4" href="#HTML-Xref-8_002dbit-Character-Expansion">8-bit Expansion</a> +<li><a accesskey="5" href="#HTML-Xref-Mismatch">Mismatch</a> +</ul> + +<div class="node"> +<p><hr> +<a name="HTML-Xref-Link-Basics"></a>Next: <a rel="next" accesskey="n" href="#HTML-Xref-Node-Name-Expansion">HTML Xref Node Name Expansion</a>, +Up: <a rel="up" accesskey="u" href="#HTML-Xref">HTML Xref</a> +<br> +</div> + +<h4 class="subsection">22.4.1 HTML Cross-reference Link Basics</h4> + +<p><a name="index-HTML-cross_002dreference-link-basics-1219"></a> +For our purposes, an HTML link consists of four components: a host +name, a directory part, a file part, and a target part. We +always assume the <code>http</code> protocol. For example: + +<pre class="example"> http://<var>host</var>/<var>dir</var>/<var>file</var>.html#<var>target</var> +</pre> + <p>The information to construct a link comes from the node name and +manual name in the cross-reference command in the Texinfo source +(see <a href="#Cross-References">Cross References</a>), and from <dfn>external information</dfn>, which +is currently simply hardwired. In the future, it may come from an +external data file. + + <p>We now consider each part in turn. + + <p>The <var>host</var> is hardwired to be the local host. This could either +be the literal string <span class="samp">localhost</span>, or, according to the rules for +HTML links, the <span class="samp">http://localhost/</span> could be omitted entirely. + + <p>The <var>dir</var> and <var>file</var> parts are more complicated, and depend on +the relative split/mono nature of both the manual being processed and +the manual that the cross-reference refers to. The underlying idea is +that there is one directory for Texinfo manuals in HTML, and each +manual is either available as a monolithic file <span class="file">manual.html</span>, or a +split subdirectory <span class="file">manual/*.html</span>. Here are the cases: + + <ul> +<li>If the present manual is split, and the referent manual is also split, +the directory is <span class="samp">../</span><var>referent/</var> and the file is the +expanded node name (described later). + + <li>If the present manual is split, and the referent manual is mono, the +directory is <span class="samp">../</span> and the file is <var>referent</var><span class="file">.html</span>. + + <li>If the present manual is mono, and the referent manual is split, the +directory is <var>referent</var><span class="file">/</span> and the file is the expanded node +name. + + <li>If the present manual is mono, and the referent manual is also mono, +the directory is <span class="file">./</span> (or just the empty string), and the file is +<var>referent</var><span class="file">.html</span>. + + </ul> + + <p>Any directory part in the filename argument of the source +cross-reference command is ignored. Thus, <code>@xref{,,,../foo}</code> +and <code>@xref{,,,foo}</code> both use <span class="samp">foo</span> 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. + + <p>Finally, the <var>target</var> part is always the expanded node name. + + <p>Whether the present manual is split or mono is determined by user +option; <span class="command">makeinfo</span> defaults to split, with the +<span class="option">--no-split</span> option overriding this. + + <p>Whether the referent manual is split or mono is another bit of the +external information. For now, <span class="command">makeinfo</span> simply assumes the +referent manual is the same as the present manual. + + <p>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. See <a href="#HTML-Xref-Mismatch">HTML Xref Mismatch</a>. + +<div class="node"> +<p><hr> +<a name="HTML-Xref-Node-Name-Expansion"></a>Next: <a rel="next" accesskey="n" href="#HTML-Xref-Command-Expansion">HTML Xref Command Expansion</a>, +Previous: <a rel="previous" accesskey="p" href="#HTML-Xref-Link-Basics">HTML Xref Link Basics</a>, +Up: <a rel="up" accesskey="u" href="#HTML-Xref">HTML Xref</a> +<br> +</div> + +<h4 class="subsection">22.4.2 HTML Cross-reference Node Name Expansion</h4> + +<p><a name="index-HTML-cross_002dreference-node-name-expansion-1220"></a><a name="index-node-name-expansion_002c-in-HTML-cross_002dreferences-1221"></a><a name="index-expansion_002c-of-node-names-in-HTML-cross_002dreferences-1222"></a> +As mentioned in the previous section, the key part of the HTML +cross-reference algorithm is the conversion of node names in the +Texinfo source into strings suitable for HTML identifiers and +filenames. The restrictions are similar for each: plain ASCII +letters, numbers, and the <span class="samp">-</span> and <span class="samp">_</span> characters are all +that can be used. + + <p>Cross-references in Texinfo can actually refer either to nodes or +anchors (see <a href="#anchor">anchor</a>), but anchors are treated identically to nodes +in this context, so we'll continue to say “node” names for +simplicity. + + <p>(@-commands and 8-bit characters are not presently handled by +<span class="command">makeinfo</span> for HTML cross-references. See the next section.) + + <p>A special exception: the Top node (see <a href="#The-Top-Node">The Top Node</a>) is always +mapped to the file <span class="file">index.html</span>, to match web server software. +However, the HTML <em>target</em> is <span class="samp">Top</span>. Thus (in the split case): +<pre class="example"> @xref{Top, Introduction,, emacs, The GNU Emacs Manual}. + => <a href="emacs/index.html#Top"> +</pre> + <ol type=1 start=1> +<li>The standard ASCII letters (a-z and A-z), and numbers (0-9) are not +modified. All other characters are changed as specified below. + + <li>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.) + + <li>Leading and trailing spaces are removed. + + <li>After the above has been applied, each remaining space character is +converted into a <span class="samp">-</span> character. + + <li>Other ASCII 7-bit characters are transformed into <span class="samp">_00</span><var>xx</var>, +where <var>xx</var> is the ASCII character code in (lowercase) hexadecimal. +This includes <span class="samp">_</span>, which is mapped to <span class="samp">_005f</span>. + + </ol> + + <p>For example: + +<pre class="example"> @node A node --- with _'% + => A-node-_002d_002d_002d-with-_005f_0027_0025 +</pre> + <p>Notice in particular: + + <ul> +<li><span class="samp">_</span> => <span class="samp">_005f</span> +<li><span class="samp">-</span> => <span class="samp">_002d</span> +<li><span class="samp">A node</span> => <span class="samp">A-node</span> +</ul> + + <p>On case-folding computer systems, nodes differing only by case will be +mapped to the same file. + + <p>In particular, as mentioned above, Top always maps to the file +<span class="file">index.html</span>. Thus, on a case-folding system, Top and a node +named `Index' will both be written to <span class="file">index.html</span>. + + <p>Fortunately, the targets serve to distinguish these cases, since HTML +target names are always case-sensitive, independent of operating +system. + +<div class="node"> +<p><hr> +<a name="HTML-Xref-Command-Expansion"></a>Next: <a rel="next" accesskey="n" href="#HTML-Xref-8_002dbit-Character-Expansion">HTML Xref 8-bit Character Expansion</a>, +Previous: <a rel="previous" accesskey="p" href="#HTML-Xref-Node-Name-Expansion">HTML Xref Node Name Expansion</a>, +Up: <a rel="up" accesskey="u" href="#HTML-Xref">HTML Xref</a> +<br> +</div> + +<h4 class="subsection">22.4.3 HTML Cross-reference Command Expansion</h4> + +<p><a name="index-HTML-cross_002dreference-command-expansion-1223"></a> +In standard Texinfo, node names may not contain @-commands. +<span class="command">makeinfo</span> has an option <span class="option">--commands-in-node-names</span> +which partially supports it (see <a href="#Invoking-makeinfo">Invoking makeinfo</a>), but it is not +robust and not recommended. + + <p>Thus, <span class="command">makeinfo</span> also does not fully implement this part of +the HTML cross-reference algorithm, but it is documented here for the +sake of completeness. + + <p>First, comments are removed. + + <p>Next, any <code>@value</code> commands (see <a href="#set-value">set value</a>) and macro invocations +(see <a href="#Invoking-Macros">Invoking Macros</a>) are fully expanded. + + <p>Then, for the following commands, the command name and braces are removed, +the text of the argument is recursively transformed: +<pre class="example"> @asis @b @cite @code @command @dfn @dmn @dotless + @emph @env @file @indicateurl @kbd @key + @samp @sc @strong @t @var @w +</pre> + <p class="noindent">For <code>@sc</code>, any letters are capitalized. + + <p>The following commands are replaced by constant text, as shown. If +any of these commands have non-empty arguments, as in +<code>@TeX{bad}</code>, it is an error, and the result is unspecified. +`(space)' means a space character, `(nothing)' means the empty string, +etc. The notation `U+<var>xxxx</var>' means Unicode code point <var>xxxx</var>. +There are further transformations of many of these expansions for the +final file or target name, such as space characters to <span class="samp">-</span>, etc., +according to the other rules. + + <p><table summary=""><tr align="left"><td valign="top" width="30%"><code>@(newline)</code> </td><td valign="top" width="50%">(space) +<br></td></tr><tr align="left"><td valign="top" width="30%"><code>@(space)</code> </td><td valign="top" width="50%">(space) +<br></td></tr><tr align="left"><td valign="top" width="30%"><code>@(tab)</code> </td><td valign="top" width="50%">(space) +<br></td></tr><tr align="left"><td valign="top" width="30%"><code>@!</code> </td><td valign="top" width="50%"><span class="samp">!</span> +<br></td></tr><tr align="left"><td valign="top" width="30%"><code>@*</code> </td><td valign="top" width="50%">(space) +<br></td></tr><tr align="left"><td valign="top" width="30%"><code>@-</code> </td><td valign="top" width="50%">(nothing) +<br></td></tr><tr align="left"><td valign="top" width="30%"><code>@.</code> </td><td valign="top" width="50%"><span class="samp">.</span> +<br></td></tr><tr align="left"><td valign="top" width="30%"><code>@:</code> </td><td valign="top" width="50%">(nothing) +<br></td></tr><tr align="left"><td valign="top" width="30%"><code>@?</code> </td><td valign="top" width="50%"><span class="samp">?</span> +<br></td></tr><tr align="left"><td valign="top" width="30%"><code>@@</code> </td><td valign="top" width="50%"><span class="samp">@</span> +<br></td></tr><tr align="left"><td valign="top" width="30%"><code>@{</code> </td><td valign="top" width="50%"><span class="samp">{</span> +<br></td></tr><tr align="left"><td valign="top" width="30%"><code>@}</code> </td><td valign="top" width="50%"><span class="samp">}</span> +<br></td></tr><tr align="left"><td valign="top" width="30%"><code>@LaTeX</code> </td><td valign="top" width="50%"><span class="samp">LaTeX</span> +<br></td></tr><tr align="left"><td valign="top" width="30%"><code>@TeX</code> </td><td valign="top" width="50%"><span class="samp">TeX</span> +<br></td></tr><tr align="left"><td valign="top" width="30%"><code>@bullet</code> </td><td valign="top" width="50%">U+2022 +<br></td></tr><tr align="left"><td valign="top" width="30%"><code>@comma</code> </td><td valign="top" width="50%"><span class="samp">,</span> +<br></td></tr><tr align="left"><td valign="top" width="30%"><code>@copyright</code> </td><td valign="top" width="50%">U+00A9 +<br></td></tr><tr align="left"><td valign="top" width="30%"><code>@dots</code> </td><td valign="top" width="50%">U+2026 +<br></td></tr><tr align="left"><td valign="top" width="30%"><code>@enddots</code> </td><td valign="top" width="50%"><span class="samp">...</span> +<br></td></tr><tr align="left"><td valign="top" width="30%"><code>@equiv</code> </td><td valign="top" width="50%">U+2261 +<br></td></tr><tr align="left"><td valign="top" width="30%"><code>@error</code> </td><td valign="top" width="50%"><span class="samp">error--></span> +<br></td></tr><tr align="left"><td valign="top" width="30%"><code>@exclamdown</code> </td><td valign="top" width="50%">U+00A1 +<br></td></tr><tr align="left"><td valign="top" width="30%"><code>@expansion</code> </td><td valign="top" width="50%">U+2192 +<br></td></tr><tr align="left"><td valign="top" width="30%"><code>@minus</code> </td><td valign="top" width="50%">U+2212 +<br></td></tr><tr align="left"><td valign="top" width="30%"><code>@ordf</code> </td><td valign="top" width="50%">U+00AA +<br></td></tr><tr align="left"><td valign="top" width="30%"><code>@ordm</code> </td><td valign="top" width="50%">U+00BA +<br></td></tr><tr align="left"><td valign="top" width="30%"><code>@point</code> </td><td valign="top" width="50%">U+2217 +<br></td></tr><tr align="left"><td valign="top" width="30%"><code>@pounds</code> </td><td valign="top" width="50%">U+00A3 +<br></td></tr><tr align="left"><td valign="top" width="30%"><code>@print</code> </td><td valign="top" width="50%"><span class="samp">-|</span> +<br></td></tr><tr align="left"><td valign="top" width="30%"><code>@questiondown</code> </td><td valign="top" width="50%">U+00BF +<br></td></tr><tr align="left"><td valign="top" width="30%"><code>@registeredsymbol</code> </td><td valign="top" width="50%">U+00AE +<br></td></tr><tr align="left"><td valign="top" width="30%"><code>@result</code> </td><td valign="top" width="50%">U+21D2 +<br></td></tr><tr align="left"><td valign="top" width="30%"><code>@tie</code> </td><td valign="top" width="50%">(space) + <br></td></tr></table> + + <p>An <code>@acronym</code> command is replaced by the first argument, +followed by the second argument in parentheses, if present. +See <a href="#acronym">acronym</a>. + + <p>An <code>@email</code> command is replaced by the <var>text</var> argument if +present, else the address. See <a href="#email">email</a>. + + <p>An <code>@image</code> command is replaced by the filename (first) +argument. See <a href="#Images">Images</a>. + + <p>A <code>@verb</code> command is replaced by its transformed argument. +See <a href="#verb">verb</a>. + + <p>Any other command is an error, and the result is unspecified. + +<div class="node"> +<p><hr> +<a name="HTML-Xref-8_002dbit-Character-Expansion"></a>Next: <a rel="next" accesskey="n" href="#HTML-Xref-Mismatch">HTML Xref Mismatch</a>, +Previous: <a rel="previous" accesskey="p" href="#HTML-Xref-Command-Expansion">HTML Xref Command Expansion</a>, +Up: <a rel="up" accesskey="u" href="#HTML-Xref">HTML Xref</a> +<br> +</div> + +<h4 class="subsection">22.4.4 HTML Cross-reference 8-bit Character Expansion</h4> + +<p><a name="index-HTML-cross_002dreference-8_002dbit-character-expansion-1224"></a><a name="index-8_002dbit-characters_002c-in-HTML-cross_002dreferences-1225"></a><a name="index-Expansion-of-8_002dbit-characters-in-HTML-cross_002dreferences-1226"></a> +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.) + + <p>These will then be further transformed by the rules above into the +string <span class="samp">_</span><var>xxxx</var>, where <var>xxxx</var> is the code point in hex. + + <p>For example, combining this rule and the previous section: + +<pre class="example"> @node @b{A} @TeX{} @u{B} @point{}@enddots{} + => A-TeX-B_0306-_2605_002e_002e_002e +</pre> + <p>Notice: 1) <!-- /@w --><code>@enddots</code> expands to three periods which in turn expands +to three <span class="samp">_002e</span>'s; 2) <!-- /@w --><code>@u{B}</code> is a `B' with a breve +accent, which does not exist as a pre-accented Unicode character, +therefore expands to <span class="samp">B_0306</span> (B with combining breve). + + <p>For the definition of Unicode Normalization Form C, see Unicode report +UAX#15, <a href="http://www.unicode.org/reports/tr15/">http://www.unicode.org/reports/tr15/</a>. Many related +documents and implementations are available elsewhere on the web. + +<div class="node"> +<p><hr> +<a name="HTML-Xref-Mismatch"></a>Previous: <a rel="previous" accesskey="p" href="#HTML-Xref-8_002dbit-Character-Expansion">HTML Xref 8-bit Character Expansion</a>, +Up: <a rel="up" accesskey="u" href="#HTML-Xref">HTML Xref</a> +<br> +</div> + +<h4 class="subsection">22.4.5 HTML Cross-reference Mismatch</h4> + +<p><a name="index-HTML-cross_002dreference-mismatch-1227"></a><a name="index-Mismatched-HTML-cross_002dreference-source-and-target-1228"></a> +As mentioned earlier (see <a href="#HTML-Xref-Link-Basics">HTML Xref Link Basics</a>), the generating +software has to guess whether a given manual being cross-referenced is +available in split or monolithic form—and, inevitably, it might +guess wrong. However, it is possible when the referent manual itself +is generated, it is possible to handle at least some mismatches. + + <p>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 +<span class="file">manual/</span> subdirectory full of HTML files which redirect back to +the monolithic <span class="file">manual.html</span>. Since this is essentially the same +as a split manual in the first place, it's not very appealing. + + <p>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 +<span class="file">manual.html</span> to the different <span class="file">manual/node.html</span> files. +Here's an example: + +<pre class="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:; + } + } +</pre> + <p>Then, in the <code><body></code> tag of <span class="file">manual.html</span>: + +<pre class="example"> <body onLoad="redirect();"> +</pre> + <p>Once again, this is something the software which generated the +<em>referent</em> manual has to do in advance, it's not something the +software generating the actual cross-reference in the present manual +can control. + + <p>Ultimately, we hope to allow for an external configuration file to +control which manuals are available from where, and how. + +<div class="node"> +<p><hr> +<a name="Command-List"></a>Next: <a rel="next" accesskey="n" href="#Tips">Tips</a>, +Previous: <a rel="previous" accesskey="p" href="#Generating-HTML">Generating HTML</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> +<br> +</div> + +<h2 class="appendix">Appendix A @-Command List</h2> + +<p><a name="index-Alphabetical-_0040_0040_002dcommand-list-1229"></a><a name="index-List-of--_0040_0040_002dcommands-1230"></a><a name="index-_0040_0040_002dcommand-list-1231"></a><a name="index-Reference-to-_0040_0040_002dcommands-1232"></a> +Here is an alphabetical list of the @-commands in Texinfo. Square +brackets, <tt>[</tt> <!-- /@w --><tt>]</tt>, indicate optional arguments; an ellipsis, +<span class="samp">...</span>, indicates repeated text. + + <p>More specifics on the general syntax of different @-commands are +given in the section below. + +<ul class="menu"> +<li><a accesskey="1" href="#Command-Syntax">Command Syntax</a>: General syntax for varieties of @-commands. +</ul> + + <pre class="sp"> + +</pre> + <dl> +<dt><code>@</code><var>whitespace</var><dd>An <code>@</code> followed by a space, tab, or newline produces a normal, +stretchable, interword space. See <a href="#Multiple-Spaces">Multiple Spaces</a>. + + <br><dt><code>@!</code><dd>Generate an exclamation point that really does end a sentence (usually +after an end-of-sentence capital letter). See <a href="#Ending-a-Sentence">Ending a Sentence</a>. + + <br><dt><code>@"</code><dt><code>@'</code><dd>Generate an umlaut or acute accent, respectively, over the next +character, as in ö and ó. See <a href="#Inserting-Accents">Inserting Accents</a>. + + <br><dt><code>@*</code><dd>Force a line break. See <a href="#Line-Breaks">Line Breaks</a>. + + <br><dt><code>@,{</code><var>c</var><code>}</code><dd>Generate a cedilla accent under <var>c</var>, as in ç. See <a href="#Inserting-Accents">Inserting Accents</a>. + + <br><dt><code>@-</code><dd>Insert a discretionary hyphenation point. See <a href="#_002d-and-hyphenation">- and hyphenation</a>. + + <br><dt><code>@.</code><dd>Produce a period that really does end a sentence (usually after an +end-of-sentence capital letter). See <a href="#Ending-a-Sentence">Ending a Sentence</a>. + + <br><dt><code>@/</code><dd>Produces no output, but allows a line break. See <a href="#Line-Breaks">Line Breaks</a>. + + <br><dt><code>@:</code><dd>Indicate to TeX that an immediately preceding period, question +mark, exclamation mark, or colon does not end a sentence. Prevent +TeX from inserting extra whitespace as it does at the end of a +sentence. The command has no effect on the Info file output. +See <a href="#Not-Ending-a-Sentence">Not Ending a Sentence</a>. + + <br><dt><code>@=</code><dd>Generate a macron (bar) accent over the next character, as in o¯. +See <a href="#Inserting-Accents">Inserting Accents</a>. + + <br><dt><code>@?</code><dd>Generate a question mark that really does end a sentence (usually after +an end-of-sentence capital letter). See <a href="#Ending-a-Sentence">Ending a Sentence</a>. + + <br><dt><code>@@</code><dd>Stands for an at sign, <span class="samp">@</span>. +See <a href="#Atsign-Braces-Comma">Inserting @ and {} and ,</a>. + + <br><dt><code>@\</code><dd>Stands for a backslash (<span class="samp">\</span>) inside <code>@math</code>. +See <a href="#math"><code>math</code></a>. + + <br><dt><code>@^</code><dt><code>@`</code><dd>Generate a circumflex (hat) or grave accent, respectively, over the next +character, as in ô and è. +See <a href="#Inserting-Accents">Inserting Accents</a>. + + <br><dt><code>@{</code><dd>Stands for a left brace, <span class="samp">{</span>. +See <a href="#Atsign-Braces-Comma">Inserting @ and {} and ,</a>. + + <br><dt><code>@}</code><dd>Stands for a right-hand brace, <span class="samp">}</span>.<br> +See <a href="#Atsign-Braces-Comma">Inserting @ and {} and ,</a>. + + <br><dt><code>@~</code><dd>Generate a tilde accent over the next character, as in Ñ. +See <a href="#Inserting-Accents">Inserting Accents</a>. + + <br><dt><code>@AA{}</code><dt><code>@aa{}</code><dd>Generate the uppercase and lowercase Scandinavian A-ring letters, +respectively: Å, å. See <a href="#Inserting-Accents">Inserting Accents</a>. + + <br><dt><code>@acronym{</code><var>abbrev</var><code>}</code><dd>Tag <var>abbrev</var> as an acronym, that is, an abbreviation written in all +capital letters, such as `NASA'. See <a href="#acronym"><code>acronym</code></a>. + + <br><dt><code>@AE{}</code><dt><code>@ae{}</code><dd>Generate the uppercase and lowercase AE ligatures, respectively: +Æ, æ. See <a href="#Inserting-Accents">Inserting Accents</a>. + + <dt><code>@afivepaper</code><dd>Change page dimensions for the A5 paper size. See <a href="#A4-Paper">A4 Paper</a>. + + <br><dt><code>@afourlatex</code><dt><code>@afourpaper</code><dt><code>@afourwide</code><dd>Change page dimensions for the A4 paper size. See <a href="#A4-Paper">A4 Paper</a>. + + <br><dt><code>@alias </code><var>new</var><code>=</code><var>existing</var><dd>Make the command <span class="samp">@</span><var>new</var> an alias for the existing command +<span class="samp">@</span><var>existing</var>. See <a href="#alias">alias</a>. + + <br><dt><code>@anchor{</code><var>name</var><code>}</code><dd>Define <var>name</var> as the current location for use as a cross-reference +target. See <a href="#anchor"><code>@anchor</code></a>. + + <br><dt><code>@appendix </code><var>title</var><dd>Begin an appendix. The title appears in the table +of contents of a printed manual. In Info, the title is +underlined with asterisks. See <a href="#unnumbered-_0026-appendix">The <code>@unnumbered</code> and <code>@appendix</code> Commands</a>. + + <br><dt><code>@appendixsec </code><var>title</var><dt><code>@appendixsection </code><var>title</var><dd>Begin an appendix section within an appendix. The section title appears +in the table of contents of a printed manual. In Info, the title is +underlined with equal signs. <code>@appendixsection</code> is a longer +spelling of the <code>@appendixsec</code> command. See <a href="#unnumberedsec-appendixsec-heading">Section Commands</a>. + + <br><dt><code>@appendixsubsec </code><var>title</var><dd>Begin an appendix subsection within an appendix. The title appears +in the table of contents of a printed manual. In Info, the title is +underlined with hyphens. See <a href="#unnumberedsubsec-appendixsubsec-subheading">Subsection Commands</a>. + + <br><dt><code>@appendixsubsubsec </code><var>title</var><dd>Begin an appendix subsubsection within an appendix subsection. The +title appears in the table of contents of a printed manual. In Info, +the title is underlined with periods. See <a href="#subsubsection">The `subsub' Commands</a>. + + <br><dt><code>@asis</code><dd>Used following <code>@table</code>, <code>@ftable</code>, and <code>@vtable</code> to +print the table's first column without highlighting (“as is”). +See <a href="#Two_002dcolumn-Tables">Making a Two-column Table</a>. + + <br><dt><code>@author </code><var>author</var><dd>Typeset <var>author</var> flushleft and underline it. See <a href="#title-subtitle-author">The <code>@title</code> and <code>@author</code> Commands</a>. + + <br><dt><code>@b{</code><var>text</var><code>}</code><dd>Print <var>text</var> in <b>bold</b> font. No effect in Info. See <a href="#Fonts">Fonts</a>. + + <br><dt><code>@bullet{}</code><dd>Generate a large round dot, or the closest possible +thing to one. See <a href="#bullet"><code>@bullet</code></a>. + + <br><dt><code>@bye</code><dd>Stop formatting a file. The formatters do not see the contents of a +file following an <code>@bye</code> command. See <a href="#Ending-a-File">Ending a File</a>. + + <br><dt><code>@c </code><var>comment</var><dd>Begin a comment in Texinfo. The rest of the line does not appear in +either the Info file or the printed manual. A synonym for +<code>@comment</code>. See <a href="#Comments">Comments</a>. + + <br><dt><code>@caption</code><dd>Define the full caption for a <code>@float</code>. See <a href="#caption-shortcaption">caption shortcaption</a>. + + <br><dt><code>@cartouche</code><dd>Highlight an example or quotation by drawing a box with rounded +corners around it. Pair with <code>@end cartouche</code>. No effect in +Info. See <a href="#cartouche">Drawing Cartouches Around Examples</a>.) + + <br><dt><code>@center </code><var>line-of-text</var><dd>Center the line of text following the command. +See <a href="#titlefont-center-sp"><code>@center</code></a>. + + <br><dt><code>@centerchap </code><var>line-of-text</var><dd>Like <code>@chapter</code>, but centers the chapter title. See <a href="#chapter"><code>@chapter</code></a>. + + <br><dt><code>@chapheading </code><var>title</var><dd>Print a chapter-like heading in the text, but not in the table of +contents of a printed manual. In Info, the title is underlined with +asterisks. See <a href="#majorheading-_0026-chapheading"><code>@majorheading</code> and <code>@chapheading</code></a>. + + <br><dt><code>@chapter </code><var>title</var><dd>Begin a chapter. The chapter title appears in the table of +contents of a printed manual. In Info, the title is underlined with +asterisks. See <a href="#chapter"><code>@chapter</code></a>. + + <br><dt><code>@cindex </code><var>entry</var><dd>Add <var>entry</var> to the index of concepts. See <a href="#Index-Entries">Defining the Entries of an Index</a>. + + <br><dt><code>@cite{</code><var>reference</var><code>}</code><dd>Highlight the name of a book or other reference that lacks a +companion Info file. See <a href="#cite"><code>@cite</code></a>. + + <br><dt><code>@clear </code><var>flag</var><dd>Unset <var>flag</var>, preventing the Texinfo formatting commands from +formatting text between subsequent pairs of <code>@ifset </code><var>flag</var> +and <code>@end ifset</code> commands, and preventing +<code>@value{</code><var>flag</var><code>}</code> from expanding to the value to which +<var>flag</var> is set. +See <a href="#set-clear-value"><code>@set</code> <code>@clear</code> <code>@value</code></a>. + + <br><dt><code>@code{</code><var>sample-code</var><code>}</code><dd>Highlight text that is an expression, a syntactically complete token +of a program, or a program name. See <a href="#code"><code>@code</code></a>. + + <br><dt><code>@comma{}</code><dd>Insert a comma `,' character; only needed when a literal comma would +be taken as an argument separator. See <a href="#Inserting-a-Comma">Inserting a Comma</a>. + + <br><dt><code>@command{</code><var>command-name</var><code>}</code><dd>Indicate a command name, such as <span class="command">ls</span>. +See <a href="#command"><code>@command</code></a>. + + <br><dt><code>@comment </code><var>comment</var><dd>Begin a comment in Texinfo. The rest of the line does not appear in +either the Info file or the printed manual. A synonym for <code>@c</code>. +See <a href="#Comments">Comments</a>. + + <br><dt><code>@contents</code><dd>Print a complete table of contents. Has no effect in Info, which uses +menus instead. See <a href="#Contents">Generating a Table of Contents</a>. + + <br><dt><code>@copyright{}</code><dd>Generate the copyright symbol ©. See <a href="#copyright-symbol"><code>@copyright{}</code></a>. + + <br><dt><code>@defcodeindex </code><var>index-name</var><dd>Define a new index and its indexing command. Print entries in an +<code>@code</code> font. See <a href="#New-Indices">Defining New Indices</a>. + + <br><dt><code>@defcv </code><var>category</var> <var>class</var> <var>name</var><dt><code>@defcvx </code><var>category</var> <var>class</var> <var>name</var><dd>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. +See <a href="#Definition-Commands">Definition Commands</a>, and <a href="#deffnx">Def Cmds in Detail</a>. + + <br><dt><code>@deffn </code><var>category</var> <var>name</var> <var>arguments</var><code>...</code><dt><code>@deffnx </code><var>category</var> <var>name</var> <var>arguments</var><code>...</code><dd>Format a description for a function, interactive command, or similar +entity that may take arguments. <code>@deffn</code> takes as arguments the +category of entity being described, the name of this particular +entity, and its arguments, if any. See <a href="#Definition-Commands">Definition Commands</a>. + + <br><dt><code>@defindex </code><var>index-name</var><dd>Define a new index and its indexing command. Print entries in a roman +font. See <a href="#New-Indices">Defining New Indices</a>. + + <br><dt><code>@definfoenclose </code><var>newcmd</var><code>, </code><var>before</var><code>, </code><var>after</var><code>,</code><dd>Create new @-command <var>newcmd</var> for Info that marks text by enclosing +it in strings that precede and follow the text. See <a href="#definfoenclose">definfoenclose</a>. + + <br><dt><code>@defivar </code><var>class</var> <var>instance-variable-name</var><dt><code>@defivarx </code><var>class</var> <var>instance-variable-name</var><dd>This command formats a description for an instance variable in +object-oriented programming. The command is equivalent to <span class="samp">@defcv +{Instance Variable} ...</span>. See <a href="#Definition-Commands">Definition Commands</a>, and +<a href="#deffnx">Def Cmds in Detail</a>. + + <br><dt><code>@defmac </code><var>macroname</var> <var>arguments</var><code>...</code><dt><code>@defmacx </code><var>macroname</var> <var>arguments</var><code>...</code><dd>Format a description for a macro. The command is equivalent to +<span class="samp">@deffn Macro ...</span>. See <a href="#Definition-Commands">Definition Commands</a>, and +<a href="#deffnx">Def Cmds in Detail</a>. + + <br><dt><code>@defmethod </code><var>class</var> <var>method-name</var> <var>arguments</var><code>...</code><dt><code>@defmethodx </code><var>class</var> <var>method-name</var> <var>arguments</var><code>...</code><dd>Format a description for a method in object-oriented programming. The +command is equivalent to <span class="samp">@defop Method ...</span>. Takes as +arguments the name of the class of the method, the name of the +method, and its arguments, if any. See <a href="#Definition-Commands">Definition Commands</a>, and +<a href="#deffnx">Def Cmds in Detail</a>. + + <br><dt><code>@defop </code><var>category</var> <var>class</var> <var>name</var> <var>arguments</var><code>...</code><dt><code>@defopx </code><var>category</var> <var>class</var> <var>name</var> <var>arguments</var><code>...</code><dd>Format a description for an operation in object-oriented programming. +<code>@defop</code> takes as arguments the overall name of the category of +operation, the name of the class of the operation, the name of the +operation, and its arguments, if any. See <a href="#Definition-Commands">Definition Commands</a>, and <a href="#Abstract-Objects">Abstract Objects</a>. + + <br><dt><code>@defopt </code><var>option-name</var><dt><code>@defoptx </code><var>option-name</var><dd>Format a description for a user option. The command is equivalent to +<span class="samp">@defvr {User Option} ...</span>. See <a href="#Definition-Commands">Definition Commands</a>, and +<a href="#deffnx">Def Cmds in Detail</a>. + + <br><dt><code>@defspec </code><var>special-form-name</var> <var>arguments</var><code>...</code><dt><code>@defspecx </code><var>special-form-name</var> <var>arguments</var><code>...</code><dd>Format a description for a special form. The command is equivalent to +<span class="samp">@deffn {Special Form} ...</span>. See <a href="#Definition-Commands">Definition Commands</a>, +and <a href="#deffnx">Def Cmds in Detail</a>. + + <br><dt><code>@deftp </code><var>category</var> <var>name-of-type</var> <var>attributes</var><code>...</code><dt><code>@deftpx </code><var>category</var> <var>name-of-type</var> <var>attributes</var><code>...</code><dd>Format a description for a data type. <code>@deftp</code> takes as arguments +the category, the name of the type (which is a word like <span class="samp">int</span> or +<span class="samp">float</span>), and then the names of attributes of objects of that type. +See <a href="#Definition-Commands">Definition Commands</a>, and <a href="#Data-Types">Data Types</a>. + + <br><dt><code>@deftypecv </code><var>category</var> <var>class</var> <var>data-type</var> <var>name</var><dt><code>@deftypecvx </code><var>category</var> <var>class</var> <var>data-type</var> <var>name</var><dd>Format a description for a typed class variable in object-oriented programming. +See <a href="#Definition-Commands">Definition Commands</a>, and <a href="#Abstract-Objects">Abstract Objects</a>. + + <br><dt><code>@deftypefn </code><var>classification</var> <var>data-type</var> <var>name</var> <var>arguments</var><code>...</code><dt><code>@deftypefnx </code><var>classification</var> <var>data-type</var> <var>name</var> <var>arguments</var><code>...</code><dd>Format a description for a function or similar entity that may take +arguments and that is typed. <code>@deftypefn</code> takes as arguments the +classification of entity being described, the type, the name of the +entity, and its arguments, if any. See <a href="#Definition-Commands">Definition Commands</a>, and +<a href="#deffnx">Def Cmds in Detail</a>. + + <br><dt><code>@deftypefun </code><var>data-type</var> <var>function-name</var> <var>arguments</var><code>...</code><dt><code>@deftypefunx </code><var>data-type</var> <var>function-name</var> <var>arguments</var><code>...</code><dd>Format a description for a function in a typed language. +The command is equivalent to <span class="samp">@deftypefn Function ...</span>. +See <a href="#Definition-Commands">Definition Commands</a>, and <a href="#deffnx">Def Cmds in Detail</a>. + + <br><dt><code>@deftypeivar </code><var>class</var> <var>data-type</var> <var>variable-name</var><dt><code>@deftypeivarx </code><var>class</var> <var>data-type</var> <var>variable-name</var><dd>Format a description for a typed instance variable in object-oriented +programming. See <a href="#Definition-Commands">Definition Commands</a>, and <a href="#Abstract-Objects">Abstract Objects</a>. + + <br><dt><code>@deftypemethod </code><var>class</var> <var>data-type</var> <var>method-name</var> <var>arguments</var><code>...</code><dt><code>@deftypemethodx </code><var>class</var> <var>data-type</var> <var>method-name</var> <var>arguments</var><code>...</code><dd>Format a description for a typed method in object-oriented programming. +See <a href="#Definition-Commands">Definition Commands</a>, and <a href="#deffnx">Def Cmds in Detail</a>. + + <br><dt><code>@deftypeop </code><var>category</var> <var>class</var> <var>data-type</var> <var>name</var> <var>arguments</var><code>...</code><dt><code>@deftypeopx </code><var>category</var> <var>class</var> <var>data-type</var> <var>name</var> <var>arguments</var><code>...</code><dd>Format a description for a typed operation in object-oriented programming. +See <a href="#Definition-Commands">Definition Commands</a>, and <a href="#Abstract-Objects">Abstract Objects</a>. + + <br><dt><code>@deftypevar </code><var>data-type</var> <var>variable-name</var><dt><code>@deftypevarx </code><var>data-type</var> <var>variable-name</var><dd>Format a description for a variable in a typed language. The command is +equivalent to <span class="samp">@deftypevr Variable ...</span>. See <a href="#Definition-Commands">Definition Commands</a>, and <a href="#deffnx">Def Cmds in Detail</a>. + + <br><dt><code>@deftypevr </code><var>classification</var> <var>data-type</var> <var>name</var><dt><code>@deftypevrx </code><var>classification</var> <var>data-type</var> <var>name</var><dd>Format a description for something like a variable in a typed +language—an entity that records a value. Takes as arguments the +classification of entity being described, the type, and the name of the +entity. See <a href="#Definition-Commands">Definition Commands</a>, and <a href="#deffnx">Def Cmds in Detail</a>. + + <br><dt><code>@defun </code><var>function-name</var> <var>arguments</var><code>...</code><dt><code>@defunx </code><var>function-name</var> <var>arguments</var><code>...</code><dd>Format a description for functions. The command is equivalent to +<span class="samp">@deffn Function ...</span>. See <a href="#Definition-Commands">Definition Commands</a>, and +<a href="#deffnx">Def Cmds in Detail</a>. + + <br><dt><code>@defvar </code><var>variable-name</var><dt><code>@defvarx </code><var>variable-name</var><dd>Format a description for variables. The command is equivalent to +<span class="samp">@defvr Variable ...</span>. See <a href="#Definition-Commands">Definition Commands</a>, and +<a href="#deffnx">Def Cmds in Detail</a>. + + <br><dt><code>@defvr </code><var>category</var> <var>name</var><dt><code>@defvrx </code><var>category</var> <var>name</var><dd>Format a description for any kind of variable. <code>@defvr</code> takes +as arguments the category of the entity and the name of the entity. +See <a href="#Definition-Commands">Definition Commands</a>, +and <a href="#deffnx">Def Cmds in Detail</a>. + + <br><dt><code>@detailmenu</code><dd>Avoid <code>makeinfo</code> confusion stemming from the detailed node listing +in a master menu. See <a href="#Master-Menu-Parts">Master Menu Parts</a>. + + <br><dt><code>@dfn{</code><var>term</var><code>}</code><dd>Highlight the introductory or defining use of a term. +See <a href="#dfn"><code>@dfn</code></a>. + + <br><dt><code>@dircategory </code><var>dirpart</var><dd>Specify a part of the Info directory menu where this file's entry should +go. See <a href="#Installing-Dir-Entries">Installing Dir Entries</a>. + + <br><dt><code>@direntry</code><dd>Begin the Info directory menu entry for this file. Pair with +<code>@end direntry</code>. See <a href="#Installing-Dir-Entries">Installing Dir Entries</a>. + + <br><dt><code>@display</code><dd>Begin a kind of example. Like <code>@example</code> (indent text, do not +fill), but do not select a new font. Pair with <code>@end display</code>. +See <a href="#display"><code>@display</code></a>. + + <br><dt><code>@dmn{</code><var>dimension</var><code>}</code><dd>Format a unit of measure, as in 12<span class="dmn">pt</span>. Causes TeX to insert a +thin space before <var>dimension</var>. No effect in Info. +See <a href="#dmn"><code>@dmn</code></a>. + + <br><dt><code>@docbook</code><dd>Enter Docbook completely. Pair with <code>@end docbook</code>. See <a href="#Raw-Formatter-Commands">Raw Formatter Commands</a>. + + <br><dt><code>@documentdescription</code><dd>Set the document description text, included in the HTML output. Pair +with <code>@end documentdescription</code>. See <a href="#documentdescription"><code>@documentdescription</code></a>. + + <br><dt><code>@documentencoding </code><var>enc</var><dd>Declare the input encoding to be <var>enc</var>. +See <a href="#documentencoding"><code>@documentencoding</code></a>. + + <br><dt><code>@documentlanguage </code><var>CC</var><dd>Declare the document language as the two-character ISO-639 abbreviation +<var>CC</var>. See <a href="#documentlanguage"><code>@documentlanguage</code></a>. + + <br><dt><code>@dotaccent{</code><var>c</var><code>}</code><dd>Generate a dot accent over the character <var>c</var>, as in o.. +See <a href="#Inserting-Accents">Inserting Accents</a>. + + <br><dt><code>@dots{}</code><dd>Insert an ellipsis: <span class="samp">...</span>. +See <a href="#dots"><code>@dots</code></a>. + + <br><dt><code>@email{</code><var>address</var><code>[, </code><var>displayed-text</var><code>]}</code><dd>Indicate an electronic mail address. +See <a href="#email"><code>@email</code></a>. + + <br><dt><code>@emph{</code><var>text</var><code>}</code><dd>Highlight <var>text</var>; text is displayed in <em>italics</em> in printed +output, and surrounded by asterisks in Info. See <a href="#Emphasis">Emphasizing Text</a>. + + <br><dt><code>@end </code><var>environment</var><dd>Ends <var>environment</var>, as in <span class="samp">@end example</span>. See <a href="#Formatting-Commands">@-commands</a>. + + <br><dt><code>@env{</code><var>environment-variable</var><code>}</code><dd>Indicate an environment variable name, such as <span class="env">PATH</span>. +See <a href="#env"><code>@env</code></a>. + + <br><dt><code>@enddots{}</code><dd>Generate an end-of-sentence of ellipsis, like this <small class="enddots">....</small> +See <a href="#dots"><code>@dots{}</code></a>. + + <br><dt><code>@enumerate [</code><var>number-or-letter</var><code>]</code><dd>Begin a numbered list, using <code>@item</code> for each entry. +Optionally, start list with <var>number-or-letter</var>. Pair with +<code>@end enumerate</code>. See <a href="#enumerate"><code>@enumerate</code></a>. + + <br><dt><code>@equiv{}</code><dd>Indicate to the reader the exact equivalence of two forms with a +glyph: <span class="samp">==</span>. See <a href="#Equivalence">Equivalence</a>. + + <br><dt><code>@error{}</code><dd>Indicate to the reader with a glyph that the following text is +an error message: <span class="samp">error--></span>. See <a href="#Error-Glyph">Error Glyph</a>. + + <br><dt><code>@evenfooting [</code><var>left</var><code>] @| [</code><var>center</var><code>] @| [</code><var>right</var><code>]</code><dt><code>@evenheading [</code><var>left</var><code>] @| [</code><var>center</var><code>] @| [</code><var>right</var><code>]</code><dd>Specify page footings resp. headings for even-numbered (left-hand) +pages. See <a href="#Custom-Headings">How to Make Your Own Headings</a>. + + <br><dt><code>@everyfooting [</code><var>left</var><code>] @| [</code><var>center</var><code>] @| [</code><var>right</var><code>]</code><dt><code>@everyheading [</code><var>left</var><code>] @| [</code><var>center</var><code>] @| [</code><var>right</var><code>]</code><dd>Specify page footings resp. headings for every page. Not relevant to +Info. See <a href="#Custom-Headings">How to Make Your Own Headings</a>. + + <br><dt><code>@example</code><dd>Begin an example. Indent text, do not fill, and select fixed-width font. +Pair with <code>@end example</code>. See <a href="#example"><code>@example</code></a>. + + <br><dt><code>@exampleindent </code><var>indent</var><dd>Indent example-like environments by <var>indent</var> number of spaces +(perhaps 0). See <a href="#exampleindent">Paragraph Indenting</a>. + + <br><dt><code>@exclamdown{}</code><dd>Produce an upside-down exclamation point. See <a href="#Inserting-Accents">Inserting Accents</a>. + + <br><dt><code>@exdent </code><var>line-of-text</var><dd>Remove any indentation a line might have. See <a href="#exdent">Undoing the Indentation of a Line</a>. + + <br><dt><code>@expansion{}</code><dd>Indicate the result of a macro expansion to the reader with a special +glyph: <span class="samp">==></span>. +See <a href="#expansion">==> Indicating an Expansion</a>. + + <br><dt><code>@file{</code><var>filename</var><code>}</code><dd>Highlight the name of a file, buffer, node, or directory. See <a href="#file"><code>@file</code></a>. + + <br><dt><code>@finalout</code><dd>Prevent TeX from printing large black warning rectangles beside +over-wide lines. See <a href="#Overfull-hboxes">Overfull hboxes</a>. + + <br><dt><code>@findex </code><var>entry</var><dd>Add <var>entry</var> to the index of functions. See <a href="#Index-Entries">Defining the Entries of an Index</a>. + + <br><dt><code>@float</code><dd>Environment to define floating material. Pair with <code>@end float</code>. +See <a href="#Floats">Floats</a>. + + <br><dt><code>@flushleft</code><dt><code>@flushright</code><dd>Left justify every line but leave the right end ragged. +Leave font as is. Pair with <code>@end flushleft</code>. +<code>@flushright</code> analogous. +See <a href="#flushleft-_0026-flushright"><code>@flushleft</code> and <code>@flushright</code></a>. + + <br><dt><code>@footnote{</code><var>text-of-footnote</var><code>}</code><dd>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. +See <a href="#Footnotes">Footnotes</a>. + + <br><dt><code>@footnotestyle </code><var>style</var><dd>Specify an Info file's footnote style, either <span class="samp">end</span> for the end +node style or <span class="samp">separate</span> for the separate node style. +See <a href="#Footnotes">Footnotes</a>. + + <br><dt><code>@format</code><dd>Begin a kind of example. Like <code>@display</code>, but do not narrow the +margins. Pair with <code>@end format</code>. See <a href="#example"><code>@example</code></a>. + + <br><dt><code>@ftable </code><var>formatting-command</var><dd>Begin a two-column table, using <code>@item</code> for each entry. +Automatically enter each of the items in the first column into the +index of functions. Pair with <code>@end ftable</code>. The same as +<code>@table</code>, except for indexing. See <a href="#ftable-vtable"><code>@ftable</code> and <code>@vtable</code></a>. + + <br><dt><code>@group</code><dd>Hold text together that must appear on one printed page. Pair with +<code>@end group</code>. Not relevant to Info. See <a href="#group"><code>@group</code></a>. + + <br><dt><code>@H{</code><var>c</var><code>}</code><dd>Generate the long Hungarian umlaut accent over <var>c</var>, as in o''. + + <br><dt><code>@heading </code><var>title</var><dd>Print an unnumbered section-like heading in the text, but not in the +table of contents of a printed manual. In Info, the title is +underlined with equal signs. See <a href="#unnumberedsec-appendixsec-heading">Section Commands</a>. + + <br><dt><code>@headings </code><var>on-off-single-double</var><dd>Turn page headings on or off, and/or specify single-sided or double-sided +page headings for printing. See <a href="#headings-on-off">The <code>@headings</code> Command</a>. + + <br><dt><code>@html</code><dd>Enter HTML completely. Pair with <code>@end html</code>. See <a href="#Raw-Formatter-Commands">Raw Formatter Commands</a>. + + <br><dt><code>@hyphenation{</code><var>hy-phen-a-ted words</var><code>}</code><dd>Explicitly define hyphenation points. See <a href="#_002d-and-hyphenation"><code>@-</code> and <code>@hyphenation</code></a>. + + <br><dt><code>@i{</code><var>text</var><code>}</code><dd>Print <var>text</var> in <i>italic</i> font. No effect in Info. See <a href="#Fonts">Fonts</a>. + + <br><dt><code>@ifclear </code><var>flag</var><dd>If <var>flag</var> is cleared, the Texinfo formatting commands format text +between <code>@ifclear </code><var>flag</var> and the following <code>@end +ifclear</code> command. +See <a href="#set-clear-value"><code>@set</code> <code>@clear</code> <code>@value</code></a>. + + <br><dt><code>@ifdocbook</code><dt><code>@ifhtml</code><dt><code>@ifinfo</code><dd>Begin text that will appear only in the given output format. +<code>@ifinfo</code> output appears in both Info and (for historical +compatibility) plain text output. Pair with <code>@end ifdocbook</code> +resp. <code>@end ifhtml</code> resp. <code>@end ifinfo</code>. +See <a href="#Conditionals">Conditionals</a>. + + <br><dt><code>@ifnotdocbook</code><dt><code>@ifnothtml</code><dt><code>@ifnotinfo</code><dt><code>@ifnotplaintext</code><dt><code>@ifnottex</code><dt><code>@ifnotxml</code><dd>Begin a stretch of text that will be ignored in one output format but +not the others. The text appears in the formats not specified: +<code>@ifnothtml</code> text is omitted from html output, etc. The exception +is <code>@ifnotinfo</code> text, which is omitted from plain text output as +well as Info output. Pair with the corresponding <code>@end +ifnot</code><var>format</var>. See <a href="#Conditionals">Conditionals</a>. + + <br><dt><code>@ifplaintext</code><dd>Begin text that will appear only in the plain text output. +Pair with <code>@end ifplaintext</code>. See <a href="#Conditionals">Conditionals</a>. + + <br><dt><code>@ifset </code><var>flag</var><dd>If <var>flag</var> is set, the Texinfo formatting commands format text +between <code>@ifset </code><var>flag</var> and the following <code>@end ifset</code> +command. +See <a href="#set-clear-value"><code>@set</code> <code>@clear</code> <code>@value</code></a>. + + <br><dt><code>@iftex</code><dd>Begin text that will not appear in the Info file or other output, but +will be processed only by TeX. Pair with <code>@end iftex</code>. +See <a href="#Conditionals">Conditionally Visible Text</a>. + + <br><dt><code>@ifxml</code><dd>Begin text that will appear only in the XML output. Pair with +<code>@end ifxml</code>. See <a href="#Conditionals">Conditionals</a>. + + <br><dt><code>@ignore</code><dd>Begin text that will not appear in any output. Pair with <code>@end +ignore</code>. See <a href="#Comments">Comments and Ignored Text</a>. + + <br><dt><code>@image{</code><var>filename</var><code>, [</code><var>width</var><code>], [</code><var>height</var><code>], [</code><var>alt</var><code>], [</code><var>ext</var><code>]}</code><dd>Include graphics image in external <var>filename</var> scaled to the given +<var>width</var> and/or <var>height</var>, using <var>alt</var> text and looking for +<var>filename</var><span class="samp">.</span><var>ext</var> in HTML. See <a href="#Images">Images</a>. + + <br><dt><code>@include </code><var>filename</var><dd>Incorporate the contents of the file <var>filename</var> into the Info file +or printed document. See <a href="#Include-Files">Include Files</a>. + + <br><dt><code>@indicateurl{</code><var>indicateurl</var><code>}</code><dd>Indicate text that is a uniform resource locator for the World Wide +Web. See <a href="#indicateurl"><code>@indicateurl</code></a>. + + <br><dt><code>@inforef{</code><var>node-name</var><code>, [</code><var>entry-name</var><code>], </code><var>info-file-name</var><code>}</code><dd>Make a cross reference to an Info file for which there is no printed +manual. See <a href="#inforef">Cross references using <code>@inforef</code></a>. + + <br><dt><code>\input </code><var>macro-definitions-file</var><dd>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 +<span class="file">texinfo</span> macro definitions file. The backslash in <code>\input</code> +is used instead of an <code>@</code> because TeX does not +recognize <code>@</code> until after it has read the definitions file. +See <a href="#Texinfo-File-Header">Texinfo File Header</a>. + + <br><dt><code>@item</code><dd>Indicate the beginning of a marked paragraph for <code>@itemize</code> and +<code>@enumerate</code>; indicate the beginning of the text of a first column +entry for <code>@table</code>, <code>@ftable</code>, and <code>@vtable</code>. +See <a href="#Lists-and-Tables">Lists and Tables</a>. + + <br><dt><code>@itemize </code><var>mark-generating-character-or-command</var><dd>Produce a sequence of indented paragraphs, with a mark inside the left +margin at the beginning of each paragraph. Pair with <code>@end +itemize</code>. See <a href="#itemize"><code>@itemize</code></a>. + + <br><dt><code>@itemx</code><dd>Like <code>@item</code> but do not generate extra vertical space above the +item text. See <a href="#itemx"><code>@itemx</code></a>. + + <br><dt><code>@kbd{</code><var>keyboard-characters</var><code>}</code><dd>Indicate text that is characters of input to be typed by +users. See <a href="#kbd"><code>@kbd</code></a>. + + <br><dt><code>@kbdinputstyle </code><var>style</var><dd>Specify when <code>@kbd</code> should use a font distinct from <code>@code</code>. +See <a href="#kbd"><code>@kbd</code></a>. + + <br><dt><code>@key{</code><var>key-name</var><code>}</code><dd>Indicate a name for a key on a keyboard. +See <a href="#key"><code>@key</code></a>. + + <br><dt><code>@kindex </code><var>entry</var><dd>Add <var>entry</var> to the index of keys. +See <a href="#Index-Entries">Defining the Entries of an Index</a>. + + <br><dt><code>@L{}</code><dt><code>@l{}</code><dd>Generate the uppercase and lowercase Polish suppressed-L letters, +respectively: /L, /l. + + <br><dt><code>@LaTeX{}</code><dd>Insert the logo LaTeX. See <a href="#tex">TeX and LaTeX</a>. + + <br><dt><code>@lisp</code><dd>Begin an example of Lisp code. Indent text, do not fill, and select +fixed-width font. Pair with <code>@end lisp</code>. See <a href="#lisp"><code>@lisp</code></a>. + + <br><dt><code>@listoffloats</code><dd>Produce a table-of-contents-like listing of <code>@float</code>s. +See <a href="#listoffloats">listoffloats</a>. + + <br><dt><code>@lowersections</code><dd>Change subsequent chapters to sections, sections to subsections, and so +on. See <a href="#Raise_002flower-sections"><code>@raisesections</code> and <code>@lowersections</code></a>. + + <br><dt><code>@macro </code><var>macroname</var><code> {</code><var>params</var><code>}</code><dd>Define a new Texinfo command <code>@</code><var>macroname</var><code>{</code><var>params</var><code>}</code>. +Only supported by <code>makeinfo</code> and <code>texi2dvi</code>. See <a href="#Defining-Macros">Defining Macros</a>. + + <br><dt><code>@majorheading </code><var>title</var><dd>Print a chapter-like heading in the text, but not in the table of +contents of a printed manual. Generate more vertical whitespace before +the heading than the <code>@chapheading</code> command. See <a href="#majorheading-_0026-chapheading"><code>@majorheading</code> and <code>@chapheading</code></a>. + + <br><dt><code>@math{</code><var>mathematical-expression</var><code>}</code><dd>Format a mathematical expression. +See <a href="#math"><code>@math</code>: Inserting Mathematical Expressions</a>. + + <br><dt><code>@menu</code><dd>Mark the beginning of a menu of nodes in Info. No effect in a printed +manual. Pair with <code>@end menu</code>. See <a href="#Menus">Menus</a>. + + <br><dt><code>@minus{}</code><dd>Generate a minus sign, `−'. See <a href="#minus"><code>@minus</code></a>. + + <br><dt><code>@multitable </code><var>column-width-spec</var><dd>Begin a multi-column table. Pair with <code>@end multitable</code>. +See <a href="#Multitable-Column-Widths">Multitable Column Widths</a>. + + <br><dt><code>@need </code><var>n</var><dd>Start a new page in a printed manual if fewer than <var>n</var> mils +(thousandths of an inch) remain on the current page. See <a href="#need"><code>@need</code></a>. + + <br><dt><code>@node </code><var>name</var><code>, </code><var>next</var><code>, </code><var>previous</var><code>, </code><var>up</var><dd>Define the beginning of a new node in Info, and serve as a locator for +references for TeX. See <a href="#node"><code>@node</code></a>. + + <br><dt><code>@noindent</code><dd>Prevent text from being indented as if it were a new paragraph. +See <a href="#noindent"><code>@noindent</code></a>. + + <br><dt><code>@novalidate</code><dd>Suppress validation of node references, omit creation of auxiliary files +with TeX. Use before <code>@setfilename</code>. See <a href="#Pointer-Validation">Pointer Validation</a>. + + <br><dt><code>@O{}</code><dt><code>@o{}</code><dd>Generate the uppercase and lowercase O-with-slash letters, respectively: +Ø, ø. + + <br><dt><code>@oddfooting [</code><var>left</var><code>] @| [</code><var>center</var><code>] @| [</code><var>right</var><code>]</code><dt><code>@oddheading [</code><var>left</var><code>] @| [</code><var>center</var><code>] @| [</code><var>right</var><code>]</code><dd>Specify page footings resp. headings for odd-numbered (right-hand) +pages. See <a href="#Custom-Headings">How to Make Your Own Headings</a>. + + <br><dt><code>@OE{}</code><dt><code>@oe{}</code><dd>Generate the uppercase and lowercase OE ligatures, respectively: +Œ, œ. See <a href="#Inserting-Accents">Inserting Accents</a>. + + <br><dt><code>@option{</code><var>option-name</var><code>}</code><dd>Indicate a command-line option, such as <span class="option">-l</span> or <span class="option">--help</span>. +See <a href="#option"><code>@option</code></a>. + + <br><dt><code>@page</code><dd>Start a new page in a printed manual. No effect in Info. +See <a href="#page"><code>@page</code></a>. + + <br><dt><code>@pagesizes [</code><var>width</var><code>][, </code><var>height</var><code>]</code><dd>Change page dimensions. See <a href="#pagesizes">pagesizes</a>. + + <br><dt><code>@paragraphindent </code><var>indent</var><dd>Indent paragraphs by <var>indent</var> number of spaces (perhaps 0); preserve +source file indentation if <var>indent</var> is <code>asis</code>. +See <a href="#paragraphindent">Paragraph Indenting</a>. + + <br><dt><code>@pindex </code><var>entry</var><dd>Add <var>entry</var> to the index of programs. See <a href="#Index-Entries">Defining the Entries of an Index</a>. + + <br><dt><code>@point{}</code><dd>Indicate the position of point in a buffer to the reader with a +glyph: <span class="samp">-!-</span>. See <a href="#Point-Glyph">Indicating Point in a Buffer</a>. + + <br><dt><code>@pounds{}</code><dd>Generate the pounds sterling currency sign. +See <a href="#pounds"><code>@pounds{}</code></a>. + + <br><dt><code>@print{}</code><dd>Indicate printed output to the reader with a glyph: +<span class="samp">-|</span>. See <a href="#Print-Glyph">Print Glyph</a>. + + <br><dt><code>@printindex </code><var>index-name</var><dd>Print an alphabetized two-column index in a printed manual or generate +an alphabetized menu of index entries for Info. See <a href="#Printing-Indices-_0026-Menus">Printing Indices & Menus</a>. + + <br><dt><code>@pxref{</code><var>node-name</var><code>, [</code><var>entry</var><code>], [</code><var>topic-or-title</var><code>], [</code><var>info-file</var><code>], [</code><var>manual</var><code>]}</code><dd>Make a reference that starts with a lower case `see' in a printed +manual. Use within parentheses only. Do not follow command with a +punctuation mark—the Info formatting commands automatically insert +terminating punctuation as needed. Only the first argument is mandatory. +See <a href="#pxref"><code>@pxref</code></a>. + + <br><dt><code>@questiondown{}</code><dd>Generate an upside-down question mark. See <a href="#Inserting-Accents">Inserting Accents</a>. + + <br><dt><code>@quotation</code><dd>Narrow the margins to indicate text that is quoted from another real +or imaginary work. Takes optional argument of prefix text. Pair with +<code>@end quotation</code>. See <a href="#quotation"><code>@quotation</code></a>. + + <br><dt><code>@r{</code><var>text</var><code>}</code><dd>Print <var>text</var> in <span class="roman">roman</span> font. No effect in Info. +See <a href="#Fonts">Fonts</a>. + + <br><dt><code>@raisesections</code><dd>Change subsequent sections to chapters, subsections to sections, and so +on. See <a href="#Raise_002flower-sections"><code>@raisesections</code> and <code>@lowersections</code></a>. + + <br><dt><code>@ref{</code><var>node-name</var><code>, [</code><var>entry</var><code>], [</code><var>topic-or-title</var><code>], [</code><var>info-file</var><code>], [</code><var>manual</var><code>]}</code><dd>Make a reference. In a printed manual, the reference does not start +with a `See'. Follow command with a punctuation mark. Only the first +argument is mandatory. See <a href="#ref"><code>@ref</code></a>. + + <br><dt><code>@refill</code><dd>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. + + <br><dt><code>@registeredsymbol{}</code><dd>Generate the legal symbol ®. See <a href="#registered-symbol"><code>@registeredsymbol{}</code></a>. + + <br><dt><code>@result{}</code><dd>Indicate the result of an expression to the reader with a special +glyph: <span class="samp">=></span>. See <a href="#result"><code>@result</code></a>. + + <br><dt><code>@ringaccent{</code><var>c</var><code>}</code><dd>Generate a ring accent over the next character, as in o*. +See <a href="#Inserting-Accents">Inserting Accents</a>. + + <br><dt><code>@samp{</code><var>text</var><code>}</code><dd>Highlight <var>text</var> that is a literal example of a sequence of +characters. Used for single characters, for statements, and often for +entire shell commands. See <a href="#samp"><code>@samp</code></a>. + + <br><dt><code>@sc{</code><var>text</var><code>}</code><dd>Set <var>text</var> in a printed output in <span class="sc">the small caps font</span> and +set text in the Info file in uppercase letters. +See <a href="#Smallcaps">Smallcaps</a>. + + <br><dt><code>@section </code><var>title</var><dd>Begin a section within a chapter. In a printed manual, the section +title is numbered and appears in the table of contents. In Info, the +title is underlined with equal signs. See <a href="#section"><code>@section</code></a>. + + <br><dt><code>@set </code><var>flag</var><code> [</code><var>string</var><code>]</code><dd>Make <var>flag</var> active, causing the Texinfo formatting commands to +format text between subsequent pairs of <code>@ifset </code><var>flag</var> and +<code>@end ifset</code> commands. Optionally, set value of <var>flag</var> to +<var>string</var>. +See <a href="#set-clear-value"><code>@set</code> <code>@clear</code> <code>@value</code></a>. + + <br><dt><code>@setchapternewpage </code><var>on-off-odd</var><dd>Specify whether chapters start on new pages, and if so, whether on +odd-numbered (right-hand) new pages. See <a href="#setchapternewpage"><code>@setchapternewpage</code></a>. + + <br><dt><code>@setcontentsaftertitlepage</code><dd>Put the table of contents after the <span class="samp">@end titlepage</span> even if the +<code>@contents</code> command is not there. See <a href="#Contents">Contents</a>. + + <br><dt><code>@setfilename </code><var>info-file-name</var><dd>Provide a name to be used by the Info file. This command is essential +for TeX formatting as well, even though it produces no output. +See <a href="#setfilename"><code>@setfilename</code></a>. + + <br><dt><code>@setshortcontentsaftertitlepage</code><dd>Place the short table of contents after the <span class="samp">@end titlepage</span> +command even if the <code>@shortcontents</code> command is not there. +See <a href="#Contents">Contents</a>. + + <br><dt><code>@settitle </code><var>title</var><dd>Provide a title for page headers in a printed manual, and the default +document description for HTML <span class="samp"><head></span>. +See <a href="#settitle"><code>@settitle</code></a>. + + <br><dt><code>@shortcaption</code><dd>Define the short caption for a <code>@float</code>. See <a href="#caption-shortcaption">caption shortcaption</a>. + + <br><dt><code>@shortcontents</code><dd>Print a short table of contents. Not relevant to Info, which uses +menus rather than tables of contents. A synonym for +<code>@summarycontents</code>. See <a href="#Contents">Generating a Table of Contents</a>. + + <br><dt><code>@shorttitlepage </code><var>title</var><dd>Generate a minimal title page. See <a href="#titlepage"><code>@titlepage</code></a>. + + <br><dt><code>@smallbook</code><dd>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. See <a href="#smallbook">Printing Small Books</a>. Also, see <a href="#small">small</a>. + + <br><dt><code>@smalldisplay</code><dd>Begin a kind of example. Like <code>@smallexample</code> (narrow margins, no +filling), but do not select the fixed-width font. Pair with <code>@end +smalldisplay</code>. See <a href="#small">small</a>. + + <br><dt><code>@smallexample</code><dd>Indent text to indicate an example. Do not fill, select fixed-width +font, narrow the margins. In printed manuals, print text in a smaller +font than with <code>@example</code>. Pair with <code>@end smallexample</code>. +See <a href="#small">small</a>. + + <br><dt><code>@smallformat</code><dd>Begin a kind of example. Like <code>@smalldisplay</code>, but do not narrow +the margins. Pair with <code>@end smallformat</code>. See <a href="#small">small</a>. + + <br><dt><code>@smalllisp</code><dd>Begin an example of Lisp code. Same as <code>@smallexample</code>. Pair +with <code>@end smalllisp</code>. See <a href="#small">small</a>. + + <br><dt><code>@sp </code><var>n</var><dd>Skip <var>n</var> blank lines. See <a href="#sp"><code>@sp</code></a>. + + <br><dt><code>@ss{}</code><dd>Generate the German sharp-S es-zet letter, ß. See <a href="#Inserting-Accents">Inserting Accents</a>. + + <br><dt><code>@strong {</code><var>text</var><code>}</code><dd>Emphasize <var>text</var> by typesetting it in a <strong>bold</strong> font for the +printed manual and by surrounding it with asterisks for Info. +See <a href="#emph-_0026-strong">Emphasizing Text</a>. + + <br><dt><code>@subheading </code><var>title</var><dd>Print an unnumbered subsection-like heading in the text, but not in +the table of contents of a printed manual. In Info, the title is +underlined with hyphens. See <a href="#unnumberedsubsec-appendixsubsec-subheading"><code>@unnumberedsubsec</code> <code>@appendixsubsec</code> <code>@subheading</code></a>. + + <br><dt><code>@subsection </code><var>title</var><dd>Begin a subsection within a section. In a printed manual, the +subsection title is numbered and appears in the table of contents. In +Info, the title is underlined with hyphens. See <a href="#subsection"><code>@subsection</code></a>. + + <br><dt><code>@subsubheading </code><var>title</var><dd>Print an unnumbered subsubsection-like heading in the text, but not in +the table of contents of a printed manual. In Info, the title is +underlined with periods. See <a href="#subsubsection">The `subsub' Commands</a>. + + <br><dt><code>@subsubsection </code><var>title</var><dd>Begin a subsubsection within a subsection. In a printed manual, +the subsubsection title is numbered and appears in the table of +contents. In Info, the title is underlined with periods. +See <a href="#subsubsection">The `subsub' Commands</a>. + + <br><dt><code>@subtitle </code><var>title</var><dd>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. See <a href="#title-subtitle-author"><code>@title</code> <code>@subtitle</code> and <code>@author</code> Commands</a>. + + <br><dt><code>@summarycontents</code><dd>Print a short table of contents. Not relevant to Info, which uses +menus rather than tables of contents. A synonym for +<code>@shortcontents</code>. See <a href="#Contents">Generating a Table of Contents</a>. + + <br><dt><code>@syncodeindex </code><var>from-index</var> <var>into-index</var><dd>Merge the index named in the first argument into the index named in +the second argument, printing the entries from the first index in +<code>@code</code> font. See <a href="#Combining-Indices">Combining Indices</a>. + + <br><dt><code>@synindex </code><var>from-index</var> <var>into-index</var><dd>Merge the index named in the first argument into the index named in +the second argument. Do not change the font of <var>from-index</var> +entries. See <a href="#Combining-Indices">Combining Indices</a>. + + <br><dt><code>@t{</code><var>text</var><code>}</code><dd>Print <var>text</var> in a <tt>fixed-width</tt>, typewriter-like font. +No effect in Info. See <a href="#Fonts">Fonts</a>. + + <br><dt><code>@tab</code><dd>Separate columns in a multitable. See <a href="#Multitable-Rows">Multitable Rows</a>. + + <br><dt><code>@table </code><var>formatting-command</var><dd>Begin a two-column table, using <code>@item</code> for each entry. Write +each first column entry on the same line as <code>@item</code>. First +column entries are printed in the font resulting from +<var>formatting-command</var>. Pair with <code>@end table</code>. +See <a href="#Two_002dcolumn-Tables">Making a Two-column Table</a>. +Also see <a href="#ftable-vtable"><code>@ftable</code> and <code>@vtable</code></a>, +and <a href="#itemx"><code>@itemx</code></a>. + + <br><dt><code>@TeX{}</code><dd>Insert the logo TeX. See <a href="#tex">TeX and LaTeX</a>. + + <br><dt><code>@tex</code><dd>Enter TeX completely. Pair with <code>@end tex</code>. See <a href="#Raw-Formatter-Commands">Raw Formatter Commands</a>. + + <br><dt><code>@thischapter</code><dt><code>@thischaptername</code><dt><code>@thisfile</code><dt><code>@thispage</code><dt><code>@thistitle</code><dd>Only allowed in a heading or footing. Stands for the number and name of +the current chapter (in the format `Chapter 1: Title'), the chapter name +only, the filename, the current page number, and the title of the +document, respectively. See <a href="#Custom-Headings">How to Make Your Own Headings</a>. + + <br><dt><code>@tie{}</code><dd>Generate a normal interword space at which a line break is not allowed. +See <a href="#tie"><code>@tie{}</code></a>. + + <br><dt><code>@tieaccent{</code><var>cc</var><code>}</code><dd>Generate a tie-after accent over the next two characters <var>cc</var>, as in +`oo['. See <a href="#Inserting-Accents">Inserting Accents</a>. + + <br><dt><code>@tindex </code><var>entry</var><dd>Add <var>entry</var> to the index of data types. See <a href="#Index-Entries">Defining the Entries of an Index</a>. + + <br><dt><code>@title </code><var>title</var><dd>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. See <a href="#title-subtitle-author">The <code>@title</code> <code>@subtitle</code> and <code>@author</code> Commands</a>. + + <br><dt><code>@titlefont{</code><var>text</var><code>}</code><dd>In a printed manual, print <var>text</var> in a larger than normal font. +Not relevant to Info, which does not have title pages. +See <a href="#titlefont-center-sp">The <code>@titlefont</code> <code>@center</code> and <code>@sp</code> Commands</a>. + + <br><dt><code>@titlepage</code><dd>Indicate to Texinfo the beginning of the title page. Write command on +a line of its own. Pair with <code>@end titlepage</code>. Nothing between +<code>@titlepage</code> and <code>@end titlepage</code> appears in Info. +See <a href="#titlepage"><code>@titlepage</code></a>. + + <br><dt><code>@today{}</code><dd>Insert the current date, in `1 Jan 1900' style. See <a href="#Custom-Headings">How to Make Your Own Headings</a>. + + <br><dt><code>@top </code><var>title</var><dd>In a Texinfo file to be formatted with <code>makeinfo</code>, identify the +topmost <code>@node</code> in the file, which must be written on the line +immediately preceding the <code>@top</code> command. Used for +<code>makeinfo</code>'s node pointer insertion feature. The title is +underlined with asterisks. Both the <code>@node</code> line and the <code>@top</code> +line normally should be enclosed by <code>@ifnottex</code> and <code>@end +ifnottex</code>. In TeX and <code>texinfo-format-buffer</code>, the <code>@top</code> +command is merely a synonym for <code>@unnumbered</code>. See <a href="#makeinfo-Pointer-Creation">Creating Pointers with <code>makeinfo</code></a>. + + <br><dt><code>@u{</code><var>c</var><code>}</code><dt><code>@ubaraccent{</code><var>c</var><code>}</code><dt><code>@udotaccent{</code><var>c</var><code>}</code><dd>Generate a breve, underbar, or underdot accent, respectively, over or +under the character <var>c</var>, as in o(, o_, +.o. See <a href="#Inserting-Accents">Inserting Accents</a>. + + <br><dt><code>@unnumbered </code><var>title</var><dd>In a printed manual, begin a chapter that appears without chapter +numbers of any kind. The title appears in the table of contents of a +printed manual. In Info, the title is underlined with asterisks. +See <a href="#unnumbered-_0026-appendix"><code>@unnumbered</code> and <code>@appendix</code></a>. + + <br><dt><code>@unnumberedsec </code><var>title</var><dd>In a printed manual, begin a section that appears without section +numbers of any kind. The title appears in the table of contents of a +printed manual. In Info, the title is underlined with equal signs. +See <a href="#unnumberedsec-appendixsec-heading">Section Commands</a>. + + <br><dt><code>@unnumberedsubsec </code><var>title</var><dd>In a printed manual, begin an unnumbered subsection within a +chapter. The title appears in the table of contents of a printed +manual. In Info, the title is underlined with hyphens. +See <a href="#unnumberedsubsec-appendixsubsec-subheading"><code>@unnumberedsubsec</code> <code>@appendixsubsec</code> <code>@subheading</code></a>. + + <br><dt><code>@unnumberedsubsubsec </code><var>title</var><dd>In a printed manual, begin an unnumbered subsubsection within a +chapter. The title appears in the table of contents of a printed +manual. In Info, the title is underlined with periods. +See <a href="#subsubsection">The `subsub' Commands</a>. + + <br><dt><code>@uref{</code><var>url</var><code>[, </code><var>displayed-text</var><code>][, </code><var>replacement</var><code>}</code><dt><code>@url{</code><var>url</var><code>[, </code><var>displayed-text</var><code>][, </code><var>replacement</var><code>}</code><dd>Define a cross reference to an external uniform resource locator for the +World Wide Web. See <a href="#uref"><code>@uref</code></a>. + + <br><dt><code>@v{</code><var>c</var><code>}</code><dd>Generate check accent over the character <var>c</var>, as in o<. +See <a href="#Inserting-Accents">Inserting Accents</a>. + + <br><dt><code>@value{</code><var>flag</var><code>}</code><dd>Replace <var>flag</var> with the value to which it is set by <code>@set +</code><var>flag</var>. +See <a href="#set-clear-value"><code>@set</code> <code>@clear</code> <code>@value</code></a>. + + <br><dt><code>@var{</code><var>metasyntactic-variable</var><code>}</code><dd>Highlight a metasyntactic variable, which is something that stands for +another piece of text. See <a href="#var">Indicating Metasyntactic Variables</a>. + + <br><dt><code>@verb{</code><var>delim</var> <var>literal</var> <var>delim</var><code>}</code><dd>Output <var>literal</var>, delimited by the single character <var>delim</var>, +exactly as is (in the fixed-width font), including any whitespace or +Texinfo special characters. See <a href="#verb"><code>verb</code></a>. + + <br><dt><code>@verbatim</code><dd>Output the text of the environment exactly as is (in the fixed-width +font). Pair with <code>@end verbatim</code>. See <a href="#verbatim"><code>verbatim</code></a>. + + <br><dt><code>@verbatiminclude </code><var>filename</var><dd>Output the contents of <var>filename</var> exactly as is (in the fixed-width font). +See <a href="#verbatiminclude"><code>verbatiminclude</code></a>. + + <br><dt><code>@vindex </code><var>entry</var><dd>Add <var>entry</var> to the index of variables. See <a href="#Index-Entries">Defining the Entries of an Index</a>. + + <br><dt><code>@vskip </code><var>amount</var><dd>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 <span class="samp">0pt plus +1filll</span>. (Note spelling of <span class="samp">filll</span>.) <code>@vskip</code> may be used +only in contexts ignored for Info. See <a href="#Copyright">Copyright</a>. + + <br><dt><code>@vtable </code><var>formatting-command</var><dd>Begin a two-column table, using <code>@item</code> for each entry. +Automatically enter each of the items in the first column into the +index of variables. Pair with <code>@end vtable</code>. The same as +<code>@table</code>, except for indexing. See <a href="#ftable-vtable"><code>@ftable</code> and <code>@vtable</code></a>. + + <br><dt><code>@w{</code><var>text</var><code>}</code><dd>Prevent <var>text</var> from being split across two lines. +See <a href="#w"><code>@w</code></a>. + + <br><dt><code>@xml</code><dd>Enter XML completely. Pair with <code>@end xml</code>. See <a href="#Raw-Formatter-Commands">Raw Formatter Commands</a>. + + <br><dt><code>@xref{</code><var>node-name</var><code>, [</code><var>entry</var><code>], [</code><var>topic-or-title</var><code>], [</code><var>info-file</var><code>], [</code><var>manual</var><code>]}</code><dd>Make a reference that starts with `See' in a printed manual. Follow +command with a punctuation mark. Only the first argument is +mandatory. See <a href="#xref"><code>@xref</code></a>. +</dl> + +<div class="node"> +<p><hr> +<a name="Command-Syntax"></a>Up: <a rel="up" accesskey="u" href="#Command-List">Command List</a> +<br> +</div> + +<h3 class="section">A.1 @-Command Syntax</h3> + +<p><a name="index-_0040_0040_002dcommand-syntax-1233"></a><a name="index-Syntax_002c-of-_0040_0040_002dcommands-1234"></a><a name="index-Command-syntax-1235"></a> +The character <span class="samp">@</span> is used to start special Texinfo commands. +(It has the same meaning that <span class="samp">\</span> has in plain TeX.) Texinfo +has four types of @-command: + + <dl> +<dt>1. Non-alphabetic commands.<dd>These commands consist of an @ followed by a punctuation mark or other +character that is not part of the alphabet. Non-alphabetic commands are +almost always part of the text within a paragraph, and never take any +argument. The two characters (@ and the other one) are complete in +themselves; none is followed by braces. The non-alphabetic commands +are: <code>@.</code>, <code>@:</code>, <code>@*</code>, <code>@</code><kbd>SPACE</kbd>, +<code>@</code><kbd>TAB</kbd>, <code>@</code><kbd>NL</kbd>, <code>@@</code>, <code>@{</code>, and +<code>@}</code>. + + <br><dt>2. Alphabetic commands that do not require arguments.<dd>These commands start with @ followed by a word followed by left- and +right-hand braces. These commands insert special symbols in the +document; they do not require arguments. For example, +<code>@dots{}</code> => <span class="samp">...</span>, <code>@equiv{}</code> +=> <span class="samp">==</span>, <code>@TeX{}</code> => `TeX', +and <code>@bullet{}</code> => <span class="samp">•</span>. + + <br><dt>3. Alphabetic commands that require arguments within braces.<dd>These commands start with @ followed by a letter or a word, followed by an +argument within braces. For example, the command <code>@dfn</code> indicates +the introductory or defining use of a term; it is used as follows: <span class="samp">In +Texinfo, @@-commands are @dfn{mark-up} commands.</span> + + <br><dt>4. Alphabetic commands that occupy an entire line.<dd>These commands occupy an entire line. The line starts with @, +followed by the name of the command (a word); for example, <code>@center</code> +or <code>@cindex</code>. 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. +</dl> + + <p><a name="index-Braces-and-argument-syntax-1236"></a>Thus, the alphabetic commands fall into classes that have +different argument syntaxes. You cannot tell to which class a command +belongs by the appearance of its name, but you can tell by the +command's meaning: if the command stands for a glyph, it is in +class 2 and does not require an argument; if it makes sense to use the +command together with other text as part of a paragraph, the command +is in class 3 and must be followed by an argument in braces; +otherwise, it is in class 4 and uses the rest of the line as its +argument. + + <p>The purpose of having a different syntax for commands of classes 3 and +4 is to make Texinfo files easier to read, and also to help the GNU +Emacs paragraph and filling commands work properly. There is only one +exception to this rule: the command <code>@refill</code>, which is always +used at the end of a paragraph immediately following the final period +or other punctuation character. <code>@refill</code> takes no argument and +does <em>not</em> require braces. <code>@refill</code> 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. + +<div class="node"> +<p><hr> +<a name="Tips"></a>Next: <a rel="next" accesskey="n" href="#Sample-Texinfo-Files">Sample Texinfo Files</a>, +Previous: <a rel="previous" accesskey="p" href="#Command-List">Command List</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> +<br> +</div> + +<h2 class="appendix">Appendix B Tips and Hints</h2> + +<p>Here are some tips for writing Texinfo documentation: + + <p><a name="index-Tips-1237"></a><a name="index-Usage-tips-1238"></a><a name="index-Hints-1239"></a> + <ul> +<li>Write in the present tense, not in the past or the future. + + <li>Write actively! For example, write “We recommend that <small class="dots">...</small>” rather +than “It is recommended that <small class="dots">...</small>”. + + <li>Use 70 or 72 as your fill column. Longer lines are hard to read. + + <li>Include a copyright notice and copying permissions. +</ul> + +<h5 class="subsubheading">Index, Index, Index!</h5> + +<p>Write many index entries, in different ways. +Readers like indices; they are helpful and convenient. + + <p>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. + + <p>Here are more hints we have found valuable: + + <ul> +<li>Write each index entry differently, so each entry refers to a different +place in the document. + + <li>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. + + <li>Consistently capitalize the first word of every concept index entry, +or else consistently use lower case. Terse entries often call for +lower case; longer entries for capitalization. Whichever case +convention you use, please use one or the other consistently! Mixing +the two styles looks bad. + + <li>Always capitalize or use upper case for those words in an index for +which this is proper, such as names of countries or acronyms. Always +use the appropriate case for case-sensitive names, such as those in C or +Lisp. + + <li>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. + + <p>In the example that follows, a blank line comes after the index +entry for “Leaping”: + + <pre class="example"> @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. + </pre> + <p class="noindent">(Note that the example shows entries for the same concept that are +written in different ways—<span class="samp">Lazy dog</span>, and <span class="samp">Dog, lazy</span>—so +readers can look up the concept in different ways.) +</ul> + +<h5 class="subsubheading">Blank Lines</h5> + + <ul> +<li>Insert a blank line between a sectioning command and the first following +sentence or paragraph, or between the indexing commands associated with +the sectioning command and the first following sentence or paragraph, as +shown in the tip on indexing. Otherwise, a formatter may fold title and +paragraph together. + + <li>Always insert a blank line before an <code>@table</code> command and after an +<code>@end table</code> command; but never insert a blank line after an +<code>@table</code> command or before an <code>@end table</code> command. + + <p>For example, + + <pre class="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, ... + </pre> + <p>Insert blank lines before and after <code>@itemize</code> <small class="dots">...</small> <code>@end +itemize</code> and <code>@enumerate</code> <small class="dots">...</small> <code>@end enumerate</code> in the +same way. +</ul> + +<h5 class="subsubheading">Complete Phrases</h5> + +<p>Complete phrases are easier to read than <small class="dots">...</small> + + <ul> +<li>Write entries in an itemized list as complete sentences; or at least, as +complete phrases. Incomplete expressions <small class="dots">...</small> awkward <small class="dots">...</small> like +this. + + <li>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. +</ul> + +<h5 class="subsubheading">Editions, Dates and Versions</h5> + +<p>Include edition numbers, version numbers, and dates in the +<code>@copying</code> text (for people reading the Texinfo file, and for the +legal copyright in the output files). Then use <code>@insertcopying</code> +in the <code>@titlepage</code> section (for people reading the printed +output) and the Top node (for people reading the online output). + + <p>It is easiest to do this using <code>@set</code> and <code>@value</code>. +See <a href="#value-Example"><code>@value</code> Example</a>, and <a href="#GNU-Sample-Texts">GNU Sample Texts</a>. + +<h5 class="subsubheading">Definition Commands</h5> + +<p>Definition commands are <code>@deffn</code>, <code>@defun</code>, +<code>@defmac</code>, and the like, and enable you to write descriptions in +a uniform format. + + <ul> +<li>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. + + <li>Use <code>@table</code> <small class="dots">...</small> <code>@end table</code> in an appendix that +contains a summary of functions, not <code>@deffn</code> or other definition +commands. +</ul> + +<h5 class="subsubheading">Capitalization</h5> + + <ul> +<li>Capitalize “Texinfo”; it is a name. Do not write the <span class="samp">x</span> or +<span class="samp">i</span> in upper case. + + <li>Capitalize “Info”; it is a name. + + <li>Write TeX using the <code>@TeX{}</code> command. Note the uppercase +<span class="samp">T</span> and <span class="samp">X</span>. This command causes the formatters to +typeset the name according to the wishes of Donald Knuth, who wrote +TeX. +</ul> + +<h5 class="subsubheading">Spaces</h5> + +<p>Do not use spaces to format a Texinfo file, except inside of +<code>@example</code> <small class="dots">...</small> <code>@end example</code> and other literal +environments and commands. + + <p>For example, TeX fills the following: + +<pre class="example"> @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. +</pre> + <p class="noindent">so it looks like this: + + <blockquote> +`C-x v' `M-x vc-next-action' Perform the next logical operation on the +version-controlled file corresponding to the current buffer. +</blockquote> + +<p class="noindent">In this case, the text should be formatted with +<code>@table</code>, <code>@item</code>, and <code>@itemx</code>, to create a table. + +<h5 class="subsubheading">@code, @samp, @var, and <span class="samp">---</span></h5> + + <ul> +<li>Use <code>@code</code> around Lisp symbols, including command names. +For example, + + <pre class="example"> The main function is @code{vc-next-action}, ... + </pre> + <li>Avoid putting letters such as <span class="samp">s</span> immediately after an +<span class="samp">@code</span>. Such letters look bad. + + <li>Use <code>@var</code> around meta-variables. Do not write angle brackets +around them. + + <li>Use three hyphens in a row, <span class="samp">---</span>, to indicate a long dash. TeX +typesets these as a long dash and the Info formatters reduce three +hyphens to two. +</ul> + +<h5 class="subsubheading">Periods Outside of Quotes</h5> + +<p>Place periods and other punctuation marks <em>outside</em> of quotations, +unless the punctuation is part of the quotation. This practice goes +against publishing conventions in the United States, but enables the +reader to distinguish between the contents of the quotation and the +whole passage. + + <p>For example, you should write the following sentence with the period +outside the end quotation marks: + +<pre class="example"> Evidently, <span class="samp">au</span> is an abbreviation for ``author''. +</pre> + <p class="noindent">since <span class="samp">au</span> does <em>not</em> serve as an abbreviation for +<span class="samp">author.</span> (with a period following the word). + +<h5 class="subsubheading">Introducing New Terms</h5> + + <ul> +<li>Introduce new terms so that a reader who does not know them can +understand them from context; or write a definition for the term. + + <p>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. + + <blockquote> +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. +</blockquote> + + <li>Use the <code>@dfn</code> 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. +</ul> + +<h5 class="subsubheading">@pxref</h5> + +<!-- !!! maybe include this in the tips on pxref --> +<p>Absolutely never use <code>@pxref</code> except in the special context for +which it is designed: inside parentheses, with the closing parenthesis +following immediately after the closing brace. One formatter +automatically inserts closing punctuation and the other does not. This +means that the output looks right both in printed output and in an Info +file, but only when the command is used inside parentheses. + +<h5 class="subsubheading">Invoking from a Shell</h5> + +<p>You can invoke programs such as Emacs, GCC, and <code>gawk</code> 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. + + <p>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. + +<h5 class="subsubheading">ANSI C Syntax</h5> + +<p>When you use <code>@example</code> to describe a C function's calling +conventions, use the ANSI C syntax, like this: + +<pre class="example"> void dld_init (char *@var{path}); +</pre> + <p class="noindent">And in the subsequent discussion, refer to the argument values by +writing the same argument names, again highlighted with +<code>@var</code>. + + <p>Avoid the obsolete style that looks like this: + +<pre class="example"> #include <dld.h> + + dld_init (path) + char *path; +</pre> + <p>Also, it is best to avoid writing <code>#include</code> above the +declaration just to indicate that the function is declared in a +header file. The practice may give the misimpression that the +<code>#include</code> 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. + +<h5 class="subsubheading">Bad Examples</h5> + +<p>Here are several examples of bad writing to avoid: + + <p>In this example, say, “ <small class="dots">...</small> you must <code>@dfn</code>{check +in} the new version.” That flows better. + + <blockquote> +When you are done editing the file, you must perform a +<code>@dfn</code>{check in}. +</blockquote> + + <p>In the following example, say, “<small class="dots">...</small> makes a unified interface such as VC +mode possible.” + + <blockquote> +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). +</blockquote> + + <p>And in this example, you should specify what `it' refers to: + + <blockquote> +If you are working with other people, it assists in coordinating +everyone's changes so they do not step on each other. +</blockquote> + +<h5 class="subsubheading">And Finally <small class="dots">...</small></h5> + + <ul> +<li>Pronounce TeX as if the <span class="samp">X</span> were a Greek `chi', as the last +sound in the name `Bach'. But pronounce Texinfo as in `speck': +“teckinfo”. + + <li>Write notes for yourself at the very end of a Texinfo file after the +<code>@bye</code>. None of the formatters process text after the +<code>@bye</code>; it is as if the text were within <code>@ignore</code> <small class="dots">...</small> +<code>@end ignore</code>. +</ul> + +<div class="node"> +<p><hr> +<a name="Sample-Texinfo-Files"></a>Next: <a rel="next" accesskey="n" href="#Include-Files">Include Files</a>, +Previous: <a rel="previous" accesskey="p" href="#Tips">Tips</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> +<br> +</div> + +<h2 class="appendix">Appendix C Sample Texinfo Files</h2> + +<p><a name="index-Sample-Texinfo-files-1240"></a> +The first example is from the first chapter (see <a href="#Short-Sample">Short Sample</a>), +given here in its entirety, without commentary. The second +includes the full texts to be used in GNU manuals. + +<ul class="menu"> +<li><a accesskey="1" href="#Short-Sample-Texinfo-File">Short Sample Texinfo File</a> +<li><a accesskey="2" href="#GNU-Sample-Texts">GNU Sample Texts</a> +<li><a accesskey="3" href="#Verbatim-Copying-License">Verbatim Copying License</a> +<li><a accesskey="4" href="#All_002dpermissive-Copying-License">All-permissive Copying License</a> +</ul> + +<div class="node"> +<p><hr> +<a name="Short-Sample-Texinfo-File"></a>Next: <a rel="next" accesskey="n" href="#GNU-Sample-Texts">GNU Sample Texts</a>, +Up: <a rel="up" accesskey="u" href="#Sample-Texinfo-Files">Sample Texinfo Files</a> +<br> +</div> + +<h3 class="section">C.1 Short Sample</h3> + +<p><a name="index-Sample-Texinfo-file_002c-no-comments-1241"></a> +Here is a complete, short sample Texinfo file, without any commentary. +You can see this file, with comments, in the first chapter. See <a href="#Short-Sample">Short Sample</a>. + + <p>In a nutshell: The <span class="command">makeinfo</span> program transforms a Texinfo +source file such as this into an Info file or HTML; and TeX typesets +it for a printed manual. + + <pre class="sp"> + +</pre> +<pre class="example"> \input texinfo @c -*-texinfo-*- + @c %**start of header + @setfilename sample.info + @settitle Sample Manual 1.0 + @c %**end of header + + @copying + This is a short example of a complete Texinfo file. + + Copyright (C) 2004 Free Software Foundation, Inc. + @end copying + + @titlepage + @title Sample Title + @page + @vskip 0pt plus 1filll + @insertcopying + @end titlepage + + @c Output the table of the contents at the beginning. + @contents + + @ifnottex + @node Top + @top GNU Sample + + @insertcopying + @end ifnottex + + @menu + * First Chapter:: The first chapter is the + only chapter in this sample. + * Index:: Complete index. + @end menu + + + @node First Chapter + @chapter First Chapter + + @cindex chapter, first + + This is the first chapter. + @cindex index entry, another + + Here is a numbered list. + + @enumerate + @item + This is the first item. + + @item + This is the second item. + @end enumerate + + + @node Index + @unnumbered Index + + @printindex cp + + @bye +</pre> + <div class="node"> +<p><hr> +<a name="GNU-Sample-Texts"></a>Next: <a rel="next" accesskey="n" href="#Verbatim-Copying-License">Verbatim Copying License</a>, +Previous: <a rel="previous" accesskey="p" href="#Short-Sample-Texinfo-File">Short Sample Texinfo File</a>, +Up: <a rel="up" accesskey="u" href="#Sample-Texinfo-Files">Sample Texinfo Files</a> +<br> +</div> + +<h3 class="section">C.2 GNU Sample Texts</h3> + +<p><a name="index-GNU-sample-texts-1242"></a><a name="index-Sample-texts_002c-GNU-1243"></a><a name="index-Full-texts_002c-GNU-1244"></a> +Following is a sample Texinfo document with the full texts that should +be used in GNU manuals. + + <p>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. + + <p>See <a href="#Short-Sample">Short Sample</a>, for a minimal example of a Texinfo file. +See <a href="#Beginning-a-File">Beginning a File</a>, for a full explanation of that minimal +example. + + <p>Here are some notes on the example: + + <ul> +<li><a name="index-_0024Id-1245"></a><a name="index-CVS-_0024Id-1246"></a><a name="index-RCS-_0024Id-1247"></a><a name="index-Documentation-identification-1248"></a><a name="index-Identification-of-documentation-1249"></a>The <span class="samp">$Id:</span> comment is for the CVS (see <a href="cvs.html#Top">Overview (Concurrent Versions System)</a>) or RCS (see rcsintro(1)) version control +systems, which expand it into a string such as: + <pre class="example"> $Id: texinfo.txi,v 1.52 2004/04/09 21:30:07 karl Exp $ + </pre> + <p>(This is useful in all sources that use version control, not just manuals.) +You may wish to include the <span class="samp">$Id:</span> comment in the <code>@copying</code> +text, if you want a completely unambiguous reference to the +documentation version. + + <p>If you want to literally write <tt>$<!-- /@w -->Id$</tt>, use <code>@w</code>: +<code>@w{$}Id$</code>. + + <li><a name="index-automake_0040r_007b_002c-and-version-info_007d-1250"></a><a name="index-UPDATED-_0040r_007bAutomake-variable_007d-1251"></a><a name="index-VERSION-_0040r_007bAutomake-variable_007d-1252"></a><a name="index-time_002dstamp_002eel-1253"></a>The <span class="file">version.texi</span> in the <code>@include</code> command is maintained +automatically by Automake (see <a href="automake.html#Top">Introduction (GNU Automake)</a>). It sets the <span class="samp">VERSION</span> and <span class="samp">UPDATED</span> values used +elsewhere. If your distribution doesn't use Automake, but you do use +Emacs, you may find the time-stamp.el package helpful (see <a href="emacs.html#Time-Stamps">Time Stamps (The GNU Emacs Manual)</a>). + + <li>The <code>@syncodeindex</code> command reflects the recommendation to use +only one index where possible, to make it easier for readers to look up +index entries. + + <li>The <code>@dircategory</code> is for constructing the Info directory. +See <a href="#Installing-Dir-Entries">Installing Dir Entries</a>, which includes a variety of recommended +category names. + + <li>The `Invoking' node is a GNU standard to help users find the basic +information about command-line usage of a given program. See <a href="standards.html#Manual-Structure-Details">Manual Structure Details (GNU Coding Standards)</a>. + + <li><a name="index-GNU-Free-Documentation-License_002c-including-entire-1254"></a><a name="index-Free-Documentation-License_002c-including-entire-1255"></a>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 <span class="file">fdl.texi</span> file +is available on the GNU machines and in the Texinfo and other GNU +source distributions. + + <p>The FDL provides for omitting itself under certain conditions, but in +that case the sample texts given here have to be modified. See <a href="#GNU-Free-Documentation-License">GNU Free Documentation License</a>. + + <li>If your manual has invariant sections (again, see the license itself for +details), then don't forget to change the text here accordingly. + + <li>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. See <a href="#Verbatim-Copying-License">Verbatim Copying License</a>. + + </ul> + + <p>Here is the sample document: + +<pre class="verbatim"> +\input texinfo @c -*-texinfo-*- +@comment $Id: texinfo.txi,v 1.52 2004/04/09 21:30:07 karl Exp $ +@comment %**start of header +@setfilename sample.info +@include version.texi +@settitle GNU Sample @value{VERSION} +@syncodeindex pg cp +@comment %**end of header +@copying +This manual is for GNU Sample +(version @value{VERSION}, @value{UPDATED}), +which is an example in the Texinfo documentation. + +Copyright @copyright{} 2004 Free Software Foundation, Inc. + +@quotation +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.1 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,'' +and with the Back-Cover Texts as in (a) below. A copy of the +license is included in the section entitled ``GNU Free Documentation +License.'' + +(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify +this GNU Manual, like GNU software. Copies published by the Free +Software Foundation raise funds for GNU development.'' +@end quotation +@end copying + +@dircategory Texinfo documentation system +@direntry +* sample: (sample)Invoking sample. +@end direntry + +@titlepage +@title GNU Sample +@subtitle for version @value{VERSION}, @value{UPDATED} +@author A.U. Thor (@email{bug-texinfo@@gnu.org}) +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@contents + +@ifnottex +@node Top +@top GNU Sample + +@insertcopying +@end ifnottex + +@menu +* Invoking sample:: +* Copying This Manual:: +* Index:: +@end menu + + +@node Invoking sample +@chapter Invoking sample + +@pindex sample +@cindex invoking @command{sample} + +This is a sample manual. There is no sample program to +invoke, but if there was, you could see its basic usage +and command line options here. + + +@node Copying This Manual +@appendix Copying This Manual + +@menu +* GNU Free Documentation License:: License for copying this manual. +@end menu + +@include fdl.texi + + +@node Index +@unnumbered Index + +@printindex cp + +@bye +</pre> + +<div class="node"> +<p><hr> +<a name="Verbatim-Copying-License"></a>Next: <a rel="next" accesskey="n" href="#All_002dpermissive-Copying-License">All-permissive Copying License</a>, +Previous: <a rel="previous" accesskey="p" href="#GNU-Sample-Texts">GNU Sample Texts</a>, +Up: <a rel="up" accesskey="u" href="#Sample-Texinfo-Files">Sample Texinfo Files</a> +<br> +</div> + +<h3 class="section">C.3 Verbatim Copying License</h3> + +<p><a name="index-Verbatim-copying-license-1256"></a><a name="index-License-for-verbatim-copying-1257"></a> +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. + + <p>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. + + <p>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. + +<pre class="verbatim"> +@copying +This document is a sample for allowing verbatim copying only. + +Copyright @copyright{} 2004 Free Software Foundation, Inc. + +@quotation +Permission is granted to make and distribute verbatim copies +of this entire document without royalty provided the +copyright notice and this permission notice are preserved. +@end quotation +@end copying +</pre> + +<div class="node"> +<p><hr> +<a name="All_002dpermissive-Copying-License"></a>Previous: <a rel="previous" accesskey="p" href="#Verbatim-Copying-License">Verbatim Copying License</a>, +Up: <a rel="up" accesskey="u" href="#Sample-Texinfo-Files">Sample Texinfo Files</a> +<br> +</div> + +<h3 class="section">C.4 All-permissive Copying License</h3> + +<p><a name="index-All_002dpermissive-copying-license-1258"></a><a name="index-License-for-all_002dpermissive-copying-1259"></a> +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. + + <p>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. + + <p>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. + +<pre class="example"> Copyright © 2004 Free Software Foundation, Inc. + + Copying and distribution of this file, with or without modification, + are permitted in any medium without royalty provided the copyright + notice and this notice are preserved. +</pre> + <div class="node"> +<p><hr> +<a name="Include-Files"></a>Next: <a rel="next" accesskey="n" href="#Headings">Headings</a>, +Previous: <a rel="previous" accesskey="p" href="#Sample-Texinfo-Files">Sample Texinfo Files</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> +<br> +</div> + +<h2 class="appendix">Appendix D Include Files</h2> + +<p><a name="index-Include-files-1260"></a> +When TeX or an Info formatting command sees an <code>@include</code> +command in a Texinfo file, it processes the contents of the file named +by the command and incorporates them into the DVI or Info file being +created. Index entries from the included file are incorporated into +the indices of the output file. + + <p>Include files let you keep a single large document as a collection of +conveniently small parts. + +<ul class="menu"> +<li><a accesskey="1" href="#Using-Include-Files">Using Include Files</a>: How to use the <code>@include</code> command. +<li><a accesskey="2" href="#texinfo_002dmultiple_002dfiles_002dupdate">texinfo-multiple-files-update</a>: How to create and update nodes and + menus when using included files. +<li><a accesskey="3" href="#Include-Files-Requirements">Include Files Requirements</a>: <code>texinfo-multiple-files-update</code> needs. +<li><a accesskey="4" href="#Sample-Include-File">Sample Include File</a>: A sample outer file with included files + within it; and a sample included file. +<li><a accesskey="5" href="#Include-Files-Evolution">Include Files Evolution</a>: How use of the <code>@include</code> command + has changed over time. +</ul> + +<div class="node"> +<p><hr> +<a name="Using-Include-Files"></a>Next: <a rel="next" accesskey="n" href="#texinfo_002dmultiple_002dfiles_002dupdate">texinfo-multiple-files-update</a>, +Up: <a rel="up" accesskey="u" href="#Include-Files">Include Files</a> +<br> +</div> + +<h3 class="section">D.1 How to Use Include Files</h3> + +<p><a name="index-include-1261"></a> +To include another file within a Texinfo file, write the +<code>@include</code> command at the beginning of a line and follow it on +the same line by the name of a file to be included. For example: + +<pre class="example"> @include buffers.texi +</pre> + <p>The name of the file is taken literally, with a single exception: +<code>@value{</code><var>var</var><code>}</code> references are expanded. This makes it +possible to reliably include files in other directories in a +distribution. See <a href="#verbatiminclude"><code>@verbatiminclude</code></a>, for +an example. + + <p>An included file should simply be a segment of text that you expect to +be included as is into the overall or <dfn>outer</dfn> Texinfo file; it +should not contain the standard beginning and end parts of a Texinfo +file. In particular, you should not start an included file with a +line saying <span class="samp">\input texinfo</span>; if you do, that phrase is inserted +into the output file as is. Likewise, you should not end an included +file with an <code>@bye</code> command; nothing after <code>@bye</code> is +formatted. + + <p>In the past, you were required to write an <code>@setfilename</code> line at the +beginning of an included file, but no longer. Now, it does not matter +whether you write such a line. If an <code>@setfilename</code> line exists +in an included file, it is ignored. + + <p>Conventionally, an included file begins with an <code>@node</code> line that +is followed by an <code>@chapter</code> line. Each included file is one +chapter. This makes it easy to use the regular node and menu creating +and updating commands to create the node pointers and menus within the +included file. However, the simple Emacs node and menu creating and +updating commands do not work with multiple Texinfo files. Thus you +cannot use these commands to fill in the `Next', `Previous', and `Up' +pointers of the <code>@node</code> line that begins the included file. Also, +you cannot use the regular commands to create a master menu for the +whole file. Either you must insert the menus and the `Next', +`Previous', and `Up' pointers by hand, or you must use the GNU Emacs +Texinfo mode command, <code>texinfo-multiple-files-update</code>, that is +designed for <code>@include</code> files. + + <p>When an included file does not have any node lines in it, the +multiple files update command does not try to create a menu entry +for it. Consequently, you can include any file, such as a +version or an update file without node lines, not just files that +are chapters. Small includable files like this are created by +Automake (see <a href="#GNU-Sample-Texts">GNU Sample Texts</a>). + +<div class="node"> +<p><hr> +<a name="texinfo_002dmultiple_002dfiles_002dupdate"></a>Next: <a rel="next" accesskey="n" href="#Include-Files-Requirements">Include Files Requirements</a>, +Previous: <a rel="previous" accesskey="p" href="#Using-Include-Files">Using Include Files</a>, +Up: <a rel="up" accesskey="u" href="#Include-Files">Include Files</a> +<br> +</div> + +<h3 class="section">D.2 <code>texinfo-multiple-files-update</code></h3> + +<p><a name="index-texinfo_002dmultiple_002dfiles_002dupdate-1262"></a> +GNU Emacs Texinfo mode provides the <code>texinfo-multiple-files-update</code> +command. This command creates or updates `Next', `Previous', and `Up' +pointers of included files as well as those in the outer or overall +Texinfo file, and it creates or updates a main menu in the outer file. +Depending whether you call it with optional arguments, the command +updates only the pointers in the first <code>@node</code> line of the +included files or all of them: + + <dl> +<dt><kbd>M-x texinfo-multiple-files-update</kbd><dd>Called without any arguments: + + <ul> +<li>Create or update the `Next', `Previous', and `Up' pointers of the +first <code>@node</code> line in each file included in an outer or overall +Texinfo file. + + <li>Create or update the `Top' level node pointers of the outer or +overall file. + + <li>Create or update a main menu in the outer file. +</ul> + + <br><dt><kbd>C-u M-x texinfo-multiple-files-update</kbd><dd>Called with <kbd>C-u</kbd> as a prefix argument: + + <ul> +<li>Create or update pointers in the first <code>@node</code> line in each +included file. + + <li>Create or update the `Top' level node pointers of the outer file. + + <li>Create and insert a master menu in the outer file. The master menu +is made from all the menus in all the included files. +</ul> + + <br><dt><kbd>C-u 8 M-x texinfo-multiple-files-update</kbd><dd>Called with a numeric prefix argument, such as <kbd>C-u 8</kbd>: + + <ul> +<li>Create or update <strong>all</strong> the `Next', `Previous', and `Up' pointers +of all the included files. + + <li>Create or update <strong>all</strong> the menus of all the included +files. + + <li>Create or update the `Top' level node pointers of the outer or +overall file. + + <li>And then create a master menu in the outer file. This is similar to +invoking <code>texinfo-master-menu</code> with an argument when you are +working with just one file. +</ul> + </dl> + + <p>Note the use of the prefix argument in interactive use: with a regular +prefix argument, just <kbd>C-u</kbd><!-- /@w -->, the +<code>texinfo-multiple-files-update</code> command inserts a master menu; +with a numeric prefix argument, such as <kbd>C-u 8</kbd>, the command +updates <strong>every</strong> pointer and menu in <strong>all</strong> the files and then inserts a +master menu. + +<div class="node"> +<p><hr> +<a name="Include-Files-Requirements"></a>Next: <a rel="next" accesskey="n" href="#Sample-Include-File">Sample Include File</a>, +Previous: <a rel="previous" accesskey="p" href="#texinfo_002dmultiple_002dfiles_002dupdate">texinfo-multiple-files-update</a>, +Up: <a rel="up" accesskey="u" href="#Include-Files">Include Files</a> +<br> +</div> + +<h3 class="section">D.3 Include Files Requirements</h3> + +<p><a name="index-Include-files-requirements-1263"></a><a name="index-Requirements-for-include-files-1264"></a> +If you plan to use the <code>texinfo-multiple-files-update</code> command, +the outer Texinfo file that lists included files within it should +contain nothing but the beginning and end parts of a Texinfo file, and +a number of <code>@include</code> commands listing the included files. It +should not even include indices, which should be listed in an included +file of their own. + + <p>Moreover, each of the included files must contain exactly one highest +level node (conventionally, <code>@chapter</code> or equivalent), +and this node must be the first node in the included file. +Furthermore, each of these highest level nodes in each included file +must be at the same hierarchical level in the file structure. +Usually, each is an <code>@chapter</code>, an <code>@appendix</code>, or an +<code>@unnumbered</code> node. Thus, normally, each included file contains +one, and only one, chapter or equivalent-level node. + + <p>The outer file should contain only <em>one</em> node, the `Top' node. It +should <em>not</em> contain any nodes besides the single `Top' node. The +<code>texinfo-multiple-files-update</code> command will not process +them. + +<div class="node"> +<p><hr> +<a name="Sample-Include-File"></a>Next: <a rel="next" accesskey="n" href="#Include-Files-Evolution">Include Files Evolution</a>, +Previous: <a rel="previous" accesskey="p" href="#Include-Files-Requirements">Include Files Requirements</a>, +Up: <a rel="up" accesskey="u" href="#Include-Files">Include Files</a> +<br> +</div> + +<h3 class="section">D.4 Sample File with <code>@include</code></h3> + +<p><a name="index-Sample-_0040code_007b_0040_0040include_007d-file-1265"></a><a name="index-Include-file-sample-1266"></a><a name="index-_0040code_007b_0040_0040include_007d-file-sample-1267"></a> +Here is an example of an outer Texinfo file with <code>@include</code> files +within it before running <code>texinfo-multiple-files-update</code>, which +would insert a main or master menu: + +<pre class="example"> \input texinfo @c -*-texinfo-*- + <!-- %**start of header --> + @setfilename include-example.info + @settitle Include Example + <!-- %**end of header --> + + ... See <a href="#Sample-Texinfo-Files">Sample Texinfo Files</a>, for + examples of the rest of the frontmatter ... + + @ifnottex + @node Top + @top Include Example + @end ifnottex + + @include foo.texinfo + @include bar.texinfo + @include concept-index.texinfo + @bye +</pre> + <p>An included file, such as <span class="file">foo.texinfo</span>, might look like this: + +<pre class="example"> @node First + @chapter First Chapter + + Contents of first chapter ... +</pre> + <p>The full contents of <span class="file">concept-index.texinfo</span> might be as simple as this: + +<pre class="example"> @node Concept Index + @unnumbered Concept Index + + @printindex cp +</pre> + <p>The outer Texinfo source file for <cite>The GNU Emacs Lisp Reference +Manual</cite> is named <span class="file">elisp.texi</span>. This outer file contains a master +menu with 417 entries and a list of 41 <code>@include</code> +files. + +<div class="node"> +<p><hr> +<a name="Include-Files-Evolution"></a>Previous: <a rel="previous" accesskey="p" href="#Sample-Include-File">Sample Include File</a>, +Up: <a rel="up" accesskey="u" href="#Include-Files">Include Files</a> +<br> +</div> + +<h3 class="section">D.5 Evolution of Include Files</h3> + +<p>When Info was first created, it was customary to create many small +Info files on one subject. Each Info file was formatted from its own +Texinfo source file. This custom meant that Emacs did not need to +make a large buffer to hold the whole of a large Info file when +someone wanted information; instead, Emacs allocated just enough +memory for the small Info file that contained the particular +information sought. This way, Emacs could avoid wasting memory. + + <p>References from one file to another were made by referring to the file +name as well as the node name. (See <a href="#Other-Info-Files">Referring to Other Info Files</a>. Also, see <a href="#Four-and-Five-Arguments"><code>@xref</code> with Four and Five Arguments</a>.) + + <p>Include files were designed primarily as a way to create a single, +large printed manual out of several smaller Info files. In a printed +manual, all the references were within the same document, so TeX +could automatically determine the references' page numbers. The Info +formatting commands used include files only for creating joint +indices; each of the individual Texinfo files had to be formatted for +Info individually. (Each, therefore, required its own +<code>@setfilename</code> line.) + + <p>However, because large Info files are now split automatically, it is +no longer necessary to keep them small. + + <p>Nowadays, multiple Texinfo files are used mostly for large documents, +such as <cite>The GNU Emacs Lisp Reference Manual</cite>, and for projects +in which several different people write different sections of a +document simultaneously. + + <p>In addition, the Info formatting commands have been extended to work +with the <code>@include</code> command so as to create a single large Info +file that is split into smaller files if necessary. This means that +you can write menus and cross references without naming the different +Texinfo files. + +<div class="node"> +<p><hr> +<a name="Headings"></a>Next: <a rel="next" accesskey="n" href="#Catching-Mistakes">Catching Mistakes</a>, +Previous: <a rel="previous" accesskey="p" href="#Include-Files">Include Files</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> +<br> +</div> + +<h2 class="appendix">Appendix E Page Headings</h2> + +<p><a name="index-Headings-1268"></a><a name="index-Footings-1269"></a><a name="index-Page-numbering-1270"></a><a name="index-Page-headings-1271"></a><a name="index-Formatting-headings-and-footings-1272"></a> +Most printed manuals contain headings along the top of every page +except the title and copyright pages. Some manuals also contain +footings. (Headings and footings have no meaning to Info, which is +not paginated.) + +<ul class="menu"> +<li><a accesskey="1" href="#Headings-Introduced">Headings Introduced</a>: Conventions for using page headings. +<li><a accesskey="2" href="#Heading-Format">Heading Format</a>: Standard page heading formats. +<li><a accesskey="3" href="#Heading-Choice">Heading Choice</a>: How to specify the type of page heading. +<li><a accesskey="4" href="#Custom-Headings">Custom Headings</a>: How to create your own headings and footings. +</ul> + +<div class="node"> +<p><hr> +<a name="Headings-Introduced"></a>Next: <a rel="next" accesskey="n" href="#Heading-Format">Heading Format</a>, +Up: <a rel="up" accesskey="u" href="#Headings">Headings</a> +<br> +</div> + +<h3 class="section">E.1 Headings Introduced</h3> + +<p>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. + + <p>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. + + <p>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. + + <p>The <code>@setchapternewpage</code> 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. + + <p>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. + +<div class="node"> +<p><hr> +<a name="Heading-Format"></a>Next: <a rel="next" accesskey="n" href="#Heading-Choice">Heading Choice</a>, +Previous: <a rel="previous" accesskey="p" href="#Headings-Introduced">Headings Introduced</a>, +Up: <a rel="up" accesskey="u" href="#Headings">Headings</a> +<br> +</div> + +<!-- node-name, next, previous, up --> +<h3 class="section">E.2 Standard Heading Formats</h3> + +<p>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. + + <p>By default, nothing is specified for the footing of a Texinfo file, +so the footing remains blank. + + <p>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. + + <p>A single-sided page looks like this: + +<pre class="example"> _______________________ + | | + | chapter page number | + | | + | Start of text ... | + | ... | + | | +</pre> + <p>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.) + + <p>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 +<code>@settitle</code> 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. + + <p>Two pages, side by side as in an open book, look like this: + +<pre class="example"> _______________________ _______________________ + | | | | + | page number title | | chapter page number | + | | | | + | Start of text ... | | More text ... | + | ... | | ... | + | | | | +</pre> + <p class="noindent">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. + +<div class="node"> +<p><hr> +<a name="Heading-Choice"></a>Next: <a rel="next" accesskey="n" href="#Custom-Headings">Custom Headings</a>, +Previous: <a rel="previous" accesskey="p" href="#Heading-Format">Heading Format</a>, +Up: <a rel="up" accesskey="u" href="#Headings">Headings</a> +<br> +</div> + +<!-- node-name, next, previous, up --> +<h3 class="section">E.3 Specifying the Type of Heading</h3> + +<p>TeX does not begin to generate page headings for a standard Texinfo +file until it reaches the <code>@end titlepage</code> command. Thus, the +title and copyright pages are not numbered. The <code>@end +titlepage</code> command causes TeX to begin to generate page headings +according to a standard format specified by the +<code>@setchapternewpage</code> command that precedes the +<code>@titlepage</code> section. + + <p>There are four possibilities: + + <dl> +<dt>No <code>@setchapternewpage</code> command<dd>Cause TeX to specify the single-sided heading format, with chapters +on new pages. This is the same as <code>@setchapternewpage on</code>. + + <br><dt><code>@setchapternewpage on</code><dd>Specify the single-sided heading format, with chapters on new pages. + + <br><dt><code>@setchapternewpage off</code><dd>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 <code>@headings double</code> command; see +<a href="#headings-on-off">The <code>@headings</code> Command</a>.) + + <br><dt><code>@setchapternewpage odd</code><dd>Specify the double-sided heading format, with chapters on new pages. +</dl> + +<p class="noindent">Texinfo lacks an <code>@setchapternewpage even</code> command. + +<div class="node"> +<p><hr> +<a name="Custom-Headings"></a>Previous: <a rel="previous" accesskey="p" href="#Heading-Choice">Heading Choice</a>, +Up: <a rel="up" accesskey="u" href="#Headings">Headings</a> +<br> +</div> + +<!-- node-name, next, previous, up --> +<h3 class="section">E.4 How to Make Your Own Headings</h3> + +<p>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. + + <p>Texinfo provides six commands for specifying headings and +footings: + <ul> +<li><code>@everyheading</code> <code>@everyfooting</code> generate page headers and +footers that are the same for both even- and odd-numbered pages. +<li><code>@evenheading</code> and <code>@evenfooting</code> command generate headers +and footers for even-numbered (left-hand) pages. +<li><code>@oddheading</code> and <code>@oddfooting</code> generate headers and footers +for odd-numbered (right-hand) pages. +</ul> + + <p>Write custom heading specifications in the Texinfo file immediately +after the <code>@end titlepage</code> command. +You must cancel the predefined heading commands with the +<code>@headings off</code> command before defining your own +specifications. + + <p>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: + +<pre class="example"> @headings off + @everyheading @thischapter @| @thispage @| @today{} +</pre> + <p class="noindent">You need to divide the left part from the central part and the central +part from the right part by inserting <span class="samp">@|</span> between parts. +Otherwise, the specification command will not be able to tell where +the text for one part ends and the next part begins. + + <p>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. + + <p>Here are the six heading and footing commands: + + <p><a name="index-everyheading-1273"></a><a name="index-everyfooting-1274"></a> + <dl> +<dt><code>@everyheading </code><var>left</var><code> @| </code><var>center</var><code> @| </code><var>right</var><dt><code>@everyfooting </code><var>left</var><code> @| </code><var>center</var><code> @| </code><var>right</var><dd> +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. + + <p><a name="index-evenheading-1275"></a><a name="index-evenfooting-1276"></a><a name="index-oddheading-1277"></a><a name="index-oddfooting-1278"></a><br><dt><code>@evenheading </code><var>left</var><code> @| </code><var>center</var><code> @| </code><var>right</var><dt><code>@oddheading </code><var>left</var><code> @| </code><var>center</var><code> @| </code><var>right</var><dt><code>@evenfooting </code><var>left</var><code> @| </code><var>center</var><code> @| </code><var>right</var><dt><code>@oddfooting </code><var>left</var><code> @| </code><var>center</var><code> @| </code><var>right</var><dd> +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. +</dl> + + <p>Use the <span class="samp">@this...</span> series of @-commands to +provide the names of chapters +and sections and the page number. You can use the +<span class="samp">@this...</span> 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 <code>@iftex</code> and <code>@end iftex</code> commands. + + <p>Here are the <span class="samp">@this...</span> commands: + + +<a name="index-thispage-1279"></a> +<dl><dt><code>@thispage</code><dd>Expands to the current page number. +<!-- !!! Karl Berry says that `thissection' can fail on page breaks. --> + + <p><a name="index-thischaptername-1280"></a><br><dt><code>@thischaptername</code><dd>Expands to the name of the current chapter. + + <p><a name="index-thischapter-1281"></a><br><dt><code>@thischapter</code><dd>Expands to the number and name of the current +chapter, in the format `Chapter 1: Title'. + + <p><a name="index-thistitle-1282"></a><br><dt><code>@thistitle</code><dd>Expands to the name of the document, as specified by the +<code>@settitle</code> command. + + <p><a name="index-thisfile-1283"></a><br><dt><code>@thisfile</code><dd>For <code>@include</code> files only: expands to the name of the current +<code>@include</code> file. If the current Texinfo source file is not an +<code>@include</code> file, this command has no effect. This command does +<em>not</em> provide the name of the current Texinfo source file unless +it is an <code>@include</code> file. (See <a href="#Include-Files">Include Files</a>, for more +information about <code>@include</code> files.) +</dl> + +<p class="noindent">You can also use the <code>@today{}</code> command, which expands to the +current date, in `1 Jan 1900' format. +<a name="index-today-1284"></a> +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: + +<pre class="example"> @headings off + @everyheading @emph{Draft!} @| @thispage @| @thischapter + @everyfooting @| @| Version: 0.27: @today{} +</pre> + <p>Beware of overlong titles: they may overlap another part of the +header or footer and blot it out. + +<div class="node"> +<p><hr> +<a name="Catching-Mistakes"></a>Next: <a rel="next" accesskey="n" href="#Copying-This-Manual">Copying This Manual</a>, +Previous: <a rel="previous" accesskey="p" href="#Headings">Headings</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> +<br> +</div> + +<h2 class="appendix">Appendix F Formatting Mistakes</h2> + +<p><a name="index-Structure_002c-catching-mistakes-in-1285"></a><a name="index-Nodes_002c-catching-mistakes-1286"></a><a name="index-Catching-mistakes-1287"></a><a name="index-Correcting-mistakes-1288"></a><a name="index-Mistakes_002c-catching-1289"></a><a name="index-Problems_002c-catching-1290"></a><a name="index-Debugging-the-Texinfo-structure-1291"></a> +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. + + <p>Emacs has two tools for catching the @-command mistakes and two for +catching structuring mistakes. + + <p>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. + + <p>For finding problems with the structure of nodes and chapters, you can use +<kbd>C-c C-s</kbd> (<code>texinfo-show-structure</code>) and the related <code>occur</code> +command and you can use the <kbd>M-x Info-validate</kbd> command. + +<ul class="menu"> +<li><a accesskey="1" href="#makeinfo-Preferred">makeinfo Preferred</a>: <code>makeinfo</code> finds errors. +<li><a accesskey="2" href="#Debugging-with-Info">Debugging with Info</a>: How to catch errors with Info formatting. +<li><a accesskey="3" href="#Debugging-with-TeX">Debugging with TeX</a>: How to catch errors with TeX formatting. +<li><a accesskey="4" href="#Using-texinfo_002dshow_002dstructure">Using texinfo-show-structure</a>: How to use <code>texinfo-show-structure</code>. +<li><a accesskey="5" href="#Using-occur">Using occur</a>: How to list all lines containing a pattern. +<li><a accesskey="6" href="#Running-Info_002dValidate">Running Info-Validate</a>: How to find badly referenced nodes. +</ul> + +<div class="node"> +<p><hr> +<a name="makeinfo-Preferred"></a>Next: <a rel="next" accesskey="n" href="#Debugging-with-Info">Debugging with Info</a>, +Up: <a rel="up" accesskey="u" href="#Catching-Mistakes">Catching Mistakes</a> +<br> +</div> + +<h3 class="section">F.1 <code>makeinfo</code> Find Errors</h3> + +<p>The <code>makeinfo</code> program does an excellent job of catching errors +and reporting them—far better than <code>texinfo-format-region</code> or +<code>texinfo-format-buffer</code>. In addition, the various functions for +automatically creating and updating node pointers and menus remove +many opportunities for human error. + + <p>If you can, use the updating commands to create and insert pointers +and menus. These prevent many errors. Then use <code>makeinfo</code> (or +its Texinfo mode manifestations, <code>makeinfo-region</code> and +<code>makeinfo-buffer</code>) to format your file and check for other +errors. This is the best way to work with Texinfo. But if you +cannot use <code>makeinfo</code>, or your problem is very puzzling, then you +may want to use the tools described in this appendix. + +<div class="node"> +<p><hr> +<a name="Debugging-with-Info"></a>Next: <a rel="next" accesskey="n" href="#Debugging-with-TeX">Debugging with TeX</a>, +Previous: <a rel="previous" accesskey="p" href="#makeinfo-Preferred">makeinfo Preferred</a>, +Up: <a rel="up" accesskey="u" href="#Catching-Mistakes">Catching Mistakes</a> +<br> +</div> + +<!-- node-name, next, previous, up --> +<h3 class="section">F.2 Catching Errors with Info Formatting</h3> + +<p><a name="index-Catching-errors-with-Info-formatting-1292"></a><a name="index-Debugging-with-Info-formatting-1293"></a> +After you have written part of a Texinfo file, you can use the +<code>texinfo-format-region</code> or the <code>makeinfo-region</code> command to +see whether the region formats properly. + + <p>Most likely, however, you are reading this section because for some +reason you cannot use the <code>makeinfo-region</code> command; therefore, the +rest of this section presumes that you are using +<code>texinfo-format-region</code>. + + <p>If you have made a mistake with an @-command, +<code>texinfo-format-region</code> 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 <span class="samp">*Info Region*</span> 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). + + <p>For example, if you accidentally end a menu with the command <code>@end +menus</code> with an `s' on the end, instead of with <code>@end menu</code>, you +will see an error message that says: + +<pre class="example"> @end menus is not handled by texinfo +</pre> + <p class="noindent">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: + +<pre class="example"> ---------- 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* ---------- +</pre> + <p>The <code>texinfo-format-region</code> command sometimes provides slightly +odd error messages. For example, the following cross reference fails to format: + +<pre class="example"> (@xref{Catching Mistakes, for more info.) +</pre> + <p class="noindent">In this case, <code>texinfo-format-region</code> detects the missing closing +brace but displays a message that says <span class="samp">Unbalanced parentheses</span> +rather than <span class="samp">Unbalanced braces</span>. This is because the formatting +command looks for mismatches between braces as if they were +parentheses. + + <p>Sometimes <code>texinfo-format-region</code> fails to detect mistakes. For +example, in the following, the closing brace is swapped with the +closing parenthesis: + +<pre class="example"> (@xref{Catching Mistakes), for more info.} +</pre> + <p class="noindent">Formatting produces: +<pre class="example"> (*Note for more info.: Catching Mistakes) +</pre> + <p>The only way for you to detect this error is to realize that the +reference should have looked like this: + +<pre class="example"> (*Note Catching Mistakes::, for more info.) +</pre> + <p>Incidentally, if you are reading this node in Info and type <kbd>f +<RET></kbd> (<code>Info-follow-reference</code>), you will generate an error +message that says: + +<pre class="example"> No such node: "Catching Mistakes) The only way ... +</pre> + <p class="noindent">This is because Info perceives the example of the error as the first +cross reference in this node and if you type a <RET> immediately +after typing the Info <kbd>f</kbd> command, Info will attempt to go to the +referenced node. If you type <kbd>f catch <TAB> <RET></kbd>, 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 <kbd>l</kbd> +(<code>Info-last</code>).) + +<!-- !!! section on using Elisp debugger ignored. --> +<div class="node"> +<p><hr> +<a name="Debugging-with-TeX"></a>Next: <a rel="next" accesskey="n" href="#Using-texinfo_002dshow_002dstructure">Using texinfo-show-structure</a>, +Previous: <a rel="previous" accesskey="p" href="#Debugging-with-Info">Debugging with Info</a>, +Up: <a rel="up" accesskey="u" href="#Catching-Mistakes">Catching Mistakes</a> +<br> +</div> + +<!-- node-name, next, previous, up --> +<h3 class="section">F.3 Catching Errors with TeX Formatting</h3> + +<p><a name="index-Catching-errors-with-_0040TeX_007b_007d-formatting-1294"></a><a name="index-Debugging-with-_0040TeX_007b_007d-formatting-1295"></a> +You can also catch mistakes when you format a file with TeX. + + <p>Usually, you will want to do this after you have run +<code>texinfo-format-buffer</code> (or, better, <code>makeinfo-buffer</code>) on +the same file, because <code>texinfo-format-buffer</code> sometimes displays +error messages that make more sense than TeX. (See <a href="#Debugging-with-Info">Debugging with Info</a>, for more information.) + + <p>For example, TeX was run on a Texinfo file, part of which is shown +here: + +<pre class="example"> ---------- 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 ---------- +</pre> + <p class="noindent">(The cross reference lacks a closing brace.) +TeX produced the following output, after which it stopped: + +<pre class="example"> ---------- Buffer: *tex-shell* ---------- + Runaway argument? + {sorting indices, for more information about sorting + indices.) @refill @ETC. + ! Paragraph ended before @xref was complete. + <to be read again> + @par + l.27 + + ? + ---------- Buffer: *tex-shell* ---------- +</pre> + <p>In this case, TeX produced an accurate and +understandable error message: + +<pre class="example"> Paragraph ended before @xref was complete. +</pre> + <p class="noindent"><span class="samp">@par</span> is an internal TeX command of no relevance to Texinfo. +<span class="samp">l.27</span> means that TeX detected the problem on line 27 of the +Texinfo file. The <span class="samp">?</span> is the prompt TeX uses in this +circumstance. + + <p>Unfortunately, TeX is not always so helpful, and sometimes you must +truly be a Sherlock Holmes to discover what went wrong. + + <p>In any case, if you run into a problem like this, you can do one of three +things. + + <ol type=1 start=1> +<li>You can tell TeX to continue running and ignore just this error by +typing <RET> at the <span class="samp">?</span> prompt. + + <li>You can tell TeX to continue running and to ignore all errors as best +it can by typing <kbd>r <RET></kbd> at the <span class="samp">?</span> prompt. + + <p>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 <kbd>C-c</kbd> (or +<kbd>C-c C-c</kbd>, if you are running a shell inside Emacs). + + <li>You can tell TeX to stop this run by typing <kbd>x <RET></kbd> +at the <span class="samp">?</span> prompt. + </ol> + + <p>If you are running TeX inside Emacs, you need to switch to the shell +buffer and line at which TeX offers the <span class="samp">?</span> prompt. + + <p>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 <code>@end itemize</code> command, TeX will +write a DVI file that you can print out. The only error message that +TeX will give you is the somewhat mysterious comment that + +<pre class="example"> (@end occurred inside a group at level 1) +</pre> + <p class="noindent">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 <code>@end</code> +command somewhere in the file; but that it could not determine where +it was needed. + + <p>Another source of notoriously hard-to-find errors is a missing +<code>@end group</code> command. If you ever are stumped by +incomprehensible errors, look for a missing <code>@end group</code> command +first. + + <p>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 <span class="samp">*</span> indicates that TeX is waiting for input. + +<pre class="example"> This is TeX, Version 3.14159 (Web2c 7.0) + (test.texinfo [1]) + * +</pre> + <p class="noindent">In this case, simply type <kbd>\end <RET></kbd> after the asterisk. Then +write the header lines in the Texinfo file and run the TeX command +again. (Note the use of the backslash, <span class="samp">\</span>. TeX uses <span class="samp">\</span> +instead of <span class="samp">@</span>; and in this circumstance, you are working +directly with TeX, not with Texinfo.) + +<div class="node"> +<p><hr> +<a name="Using-texinfo_002dshow_002dstructure"></a>Next: <a rel="next" accesskey="n" href="#Using-occur">Using occur</a>, +Previous: <a rel="previous" accesskey="p" href="#Debugging-with-TeX">Debugging with TeX</a>, +Up: <a rel="up" accesskey="u" href="#Catching-Mistakes">Catching Mistakes</a> +<br> +</div> + +<!-- node-name, next, previous, up --> +<h3 class="section">F.4 Using <code>texinfo-show-structure</code></h3> + +<p><a name="index-Showing-the-structure-of-a-file-1296"></a><a name="index-texinfo_002dshow_002dstructure-1297"></a> +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. + + <p>In GNU Emacs, in Texinfo mode, the <code>texinfo-show-structure</code> +command lists all the lines that begin with the @-commands that +specify the structure: <code>@chapter</code>, <code>@section</code>, +<code>@appendix</code>, and so on. With an argument (<kbd>C-u</kbd><!-- /@w --> +as prefix argument, if interactive), +the command also shows the <code>@node</code> lines. The +<code>texinfo-show-structure</code> command is bound to <kbd>C-c C-s</kbd> in +Texinfo mode, by default. + + <p>The lines are displayed in a buffer called the <span class="samp">*Occur*</span> buffer, +indented by hierarchical level. For example, here is a part of what was +produced by running <code>texinfo-show-structure</code> on this manual: + +<pre class="example"> 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 + ... +</pre> + <p>This says that lines 4337, 4393, and 4417 of <span class="file">texinfo.texi</span> begin +with the <code>@section</code>, <code>@subheading</code>, and <code>@subsection</code> +commands respectively. If you move your cursor into the <span class="samp">*Occur*</span> +window, you can position the cursor over one of the lines and use the +<kbd>C-c C-c</kbd> command (<code>occur-mode-goto-occurrence</code>), to jump to +the corresponding spot in the Texinfo file. See <a href="emacs.html#Other-Repeating-Search">Using Occur (The GNU Emacs Manual)</a>, for more +information about <code>occur-mode-goto-occurrence</code>. + + <p>The first line in the <span class="samp">*Occur*</span> window describes the <dfn>regular +expression</dfn> specified by <var>texinfo-heading-pattern</var>. This regular +expression is the pattern that <code>texinfo-show-structure</code> looks for. +See <a href="emacs.html#Regexps">Using Regular Expressions (The GNU Emacs Manual)</a>, +for more information. + + <p>When you invoke the <code>texinfo-show-structure</code> 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 <kbd>C-x n n</kbd> (<code>narrow-to-region</code>) command to mark the +region. (See <a href="emacs.html#Narrowing">Narrowing (The GNU Emacs Manual)</a>.) This is +how the example used above was generated. (To see the whole buffer +again, use <kbd>C-x n w</kbd> (<code>widen</code>).) + + <p>If you call <code>texinfo-show-structure</code> with a prefix argument by +typing <kbd>C-u C-c C-s</kbd><!-- /@w -->, it will list lines beginning with +<code>@node</code> as well as the lines beginning with the @-sign commands +for <code>@chapter</code>, <code>@section</code>, and the like. + + <p>You can remind yourself of the structure of a Texinfo file by looking at +the list in the <span class="samp">*Occur*</span> window; and if you have mis-named a node +or left out a section, you can correct the mistake. + +<div class="node"> +<p><hr> +<a name="Using-occur"></a>Next: <a rel="next" accesskey="n" href="#Running-Info_002dValidate">Running Info-Validate</a>, +Previous: <a rel="previous" accesskey="p" href="#Using-texinfo_002dshow_002dstructure">Using texinfo-show-structure</a>, +Up: <a rel="up" accesskey="u" href="#Catching-Mistakes">Catching Mistakes</a> +<br> +</div> + +<!-- node-name, next, previous, up --> +<h3 class="section">F.5 Using <code>occur</code></h3> + +<p><a name="index-Occurrences_002c-listing-with-_0040code_007b_0040_0040occur_007d-1298"></a><a name="index-occur-1299"></a> +Sometimes the <code>texinfo-show-structure</code> 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 +<code>texinfo-show-structure</code>. In this case, you can use the <code>occur</code> +command directly. To do this, type + +<pre class="example"> <kbd>M-x occur</kbd> +</pre> + <p class="noindent">and then, when prompted, type a <dfn>regexp</dfn>, a regular expression for +the pattern you want to match. (See <a href="emacs.html#Regexps">Regular Expressions (The GNU Emacs Manual)</a>.) The <code>occur</code> command works from +the current location of the cursor in the buffer to the end of the +buffer. If you want to run <code>occur</code> on the whole buffer, place +the cursor at the beginning of the buffer. + + <p>For example, to see all the lines that contain the word +<span class="samp">@chapter</span> in them, just type <span class="samp">@chapter</span>. This will +produce a list of the chapters. It will also list all the sentences +with <span class="samp">@chapter</span> in the middle of the line. + + <p>If you want to see only those lines that start with the word +<span class="samp">@chapter</span>, type <span class="samp">^@chapter</span> when prompted by +<code>occur</code>. If you want to see all the lines that end with a word +or phrase, end the last word with a <span class="samp">$</span>; for example, +<span class="samp">catching mistakes$</span>. 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. + + <p>See <a href="emacs.html#Other-Repeating-Search">Using Occur (The GNU Emacs Manual)</a>, +for more information. + +<div class="node"> +<p><hr> +<a name="Running-Info_002dValidate"></a>Previous: <a rel="previous" accesskey="p" href="#Using-occur">Using occur</a>, +Up: <a rel="up" accesskey="u" href="#Catching-Mistakes">Catching Mistakes</a> +<br> +</div> + +<!-- node-name, next, previous, up --> +<h3 class="section">F.6 Finding Badly Referenced Nodes</h3> + +<p><a name="index-Info_002dvalidate-1300"></a><a name="index-Nodes_002c-checking-for-badly-referenced-1301"></a><a name="index-Checking-for-badly-referenced-nodes-1302"></a><a name="index-Looking-for-badly-referenced-nodes-1303"></a><a name="index-Finding-badly-referenced-nodes-1304"></a><a name="index-Badly-referenced-nodes-1305"></a> +You can use the <code>Info-validate</code> 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 <code>Info-validate</code> command works only on Info +files, not on Texinfo files. + + <p>The <code>makeinfo</code> program validates pointers automatically, so you +do not need to use the <code>Info-validate</code> command if you are using +<code>makeinfo</code>. You only may need to use <code>Info-validate</code> if you +are unable to run <code>makeinfo</code> and instead must create an Info file +using <code>texinfo-format-region</code> or <code>texinfo-format-buffer</code>, or +if you write an Info file from scratch. + +<ul class="menu"> +<li><a accesskey="1" href="#Using-Info_002dvalidate">Using Info-validate</a>: How to run <code>Info-validate</code>. +<li><a accesskey="2" href="#Unsplit">Unsplit</a>: How to create an unsplit file. +<li><a accesskey="3" href="#Tagifying">Tagifying</a>: How to tagify a file. +<li><a accesskey="4" href="#Splitting">Splitting</a>: How to split a file manually. +</ul> + +<div class="node"> +<p><hr> +<a name="Using-Info_002dvalidate"></a>Next: <a rel="next" accesskey="n" href="#Unsplit">Unsplit</a>, +Up: <a rel="up" accesskey="u" href="#Running-Info_002dValidate">Running Info-Validate</a> +<br> +</div> + +<h4 class="subsection">F.6.1 Running <code>Info-validate</code></h4> + +<p><a name="index-Running-_0040code_007bInfo_002dvalidate_007d-1306"></a><a name="index-Info-validating-a-large-file-1307"></a><a name="index-Validating-a-large-file-1308"></a> +To use <code>Info-validate</code>, visit the Info file you wish to check and +type: + +<pre class="example"> M-x Info-validate +</pre> + <p class="noindent">Note that the <code>Info-validate</code> command requires an upper case +`I'. You may also need to create a tag table before running +<code>Info-validate</code>. See <a href="#Tagifying">Tagifying</a>. + + <p>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 <span class="samp">*problems in +info file*</span>. + + <p>For example, <code>Info-validate</code> was run on a test file that contained +only the first node of this manual. One of the messages said: + +<pre class="example"> In node "Overview", invalid Next: Texinfo Mode +</pre> + <p class="noindent">This meant that the node called <span class="samp">Overview</span> 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). + + <p>Now suppose we add a node named <span class="samp">Texinfo Mode</span> to our test case +but we do not specify a `Previous' for this node. Then we will get +the following error message: + +<pre class="example"> In node "Texinfo Mode", should have Previous: Overview +</pre> + <p class="noindent">This is because every `Next' pointer should be matched by a +`Previous' (in the node where the `Next' points) which points back. + + <p><code>Info-validate</code> also checks that all menu entries and cross references +point to actual nodes. + + <p><code>Info-validate</code> requires a tag table and does not work with files +that have been split. (The <code>texinfo-format-buffer</code> command +automatically splits large files.) In order to use <code>Info-validate</code> +on a large file, you must run <code>texinfo-format-buffer</code> with an +argument so that it does not split the Info file; and you must create a +tag table for the unsplit file. + +<div class="node"> +<p><hr> +<a name="Unsplit"></a>Next: <a rel="next" accesskey="n" href="#Tagifying">Tagifying</a>, +Previous: <a rel="previous" accesskey="p" href="#Using-Info_002dvalidate">Using Info-validate</a>, +Up: <a rel="up" accesskey="u" href="#Running-Info_002dValidate">Running Info-Validate</a> +<br> +</div> + +<!-- node-name, next, previous, up --> +<h4 class="subsection">F.6.2 Creating an Unsplit File</h4> + +<p><a name="index-Creating-an-unsplit-file-1309"></a><a name="index-Unsplit-file-creation-1310"></a> +You can run <code>Info-validate</code> 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 +<code>texinfo-format-buffer</code> or <code>makeinfo-buffer</code> 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 <code>Info-validate</code> and look for badly referenced +nodes. + + <p>The first step is to create an unsplit Info file. To prevent +<code>texinfo-format-buffer</code> from splitting a Texinfo file into +smaller Info files, give a prefix to the <kbd>M-x +texinfo-format-buffer</kbd> command: + +<pre class="example"> C-u M-x texinfo-format-buffer +</pre> + <p class="noindent">or else + +<pre class="example"> C-u C-c C-e C-b +</pre> + <p class="noindent">When you do this, Texinfo will not split the file and will not create +a tag table for it. +<a name="index-Making-a-tag-table-manually-1311"></a><a name="index-Tag-table_002c-making-manually-1312"></a> +<div class="node"> +<p><hr> +<a name="Tagifying"></a>Next: <a rel="next" accesskey="n" href="#Splitting">Splitting</a>, +Previous: <a rel="previous" accesskey="p" href="#Unsplit">Unsplit</a>, +Up: <a rel="up" accesskey="u" href="#Running-Info_002dValidate">Running Info-Validate</a> +<br> +</div> + +<h4 class="subsection">F.6.3 Tagifying a File</h4> + +<p>After creating an unsplit Info file, you must create a tag table for +it. Visit the Info file you wish to tagify and type: + +<pre class="example"> M-x Info-tagify +</pre> + <p class="noindent">(Note the upper case <span class="samp">I</span> in <code>Info-tagify</code>.) This creates an +Info file with a tag table that you can validate. + + <p>The third step is to validate the Info file: + +<pre class="example"> M-x Info-validate +</pre> + <p class="noindent">(Note the upper case <span class="samp">I</span> in <code>Info-validate</code>.) +In brief, the steps are: + +<pre class="example"> C-u M-x texinfo-format-buffer + M-x Info-tagify + M-x Info-validate +</pre> + <p>After you have validated the node structure, you can rerun +<code>texinfo-format-buffer</code> 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. + +<div class="node"> +<p><hr> +<a name="Splitting"></a>Previous: <a rel="previous" accesskey="p" href="#Tagifying">Tagifying</a>, +Up: <a rel="up" accesskey="u" href="#Running-Info_002dValidate">Running Info-Validate</a> +<br> +</div> + +<!-- node-name, next, previous, up --> +<h4 class="subsection">F.6.4 Splitting a File Manually</h4> + +<p><a name="index-Splitting-an-Info-file-manually-1313"></a><a name="index-Info-file_002c-splitting-manually-1314"></a> +You should split a large file or else let the +<code>texinfo-format-buffer</code> or <code>makeinfo-buffer</code> command do it +for you automatically. (Generally you will let one of the formatting +commands do this job for you. See <a href="#Creating-an-Info-File">Creating an Info File</a>.) + + <p>The split-off files are called the indirect subfiles. + + <p>Info files are split to save memory. With smaller files, Emacs does not +have make such a large buffer to hold the information. + + <p>If an Info file has more than 30 nodes, you should also make a tag +table for it. See <a href="#Using-Info_002dvalidate">Using Info-validate</a>, 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 +<code>Info-validate</code>.) + +<!-- Info-split is autoloaded in `loaddefs.el' in Emacs 18.51 --> +<p>Visit the Info file you wish to tagify and split and type the two +commands: + +<pre class="example"> M-x Info-tagify + M-x Info-split +</pre> + <p class="noindent">(Note that the <span class="samp">I</span> in <span class="samp">Info</span> is upper case.) + + <p>When you use the <code>Info-split</code> 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 <span class="samp">-</span> and a number to the original file name. + + <p>The primary file still functions as an Info file, but it contains just +the tag table and a directory of subfiles. + +<!-- These are no longer ``new'', and the explanations --> +<!-- are all given elsewhere anyway, I think. -karl, 25apr97. --> +<!-- So ignore the entire appendix. --> +<div class="node"> +<p><hr> +<a name="Copying-This-Manual"></a>Next: <a rel="next" accesskey="n" href="#Command-and-Variable-Index">Command and Variable Index</a>, +Previous: <a rel="previous" accesskey="p" href="#Catching-Mistakes">Catching Mistakes</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> +<br> +</div> + +<h2 class="appendix">Appendix G Copying This Manual</h2> + +<ul class="menu"> +<li><a accesskey="1" href="#GNU-Free-Documentation-License">GNU Free Documentation License</a>: License for copying this manual. +</ul> + +<div class="node"> +<p><hr> +<a name="GNU-Free-Documentation-License"></a>Up: <a rel="up" accesskey="u" href="#Copying-This-Manual">Copying This Manual</a> +<br> +</div> + +<h3 class="appendixsec">G.1 GNU Free Documentation License</h3> + +<p><a name="index-FDL_002c-GNU-Free-Documentation-License-1315"></a><div align="center">Version 1.2, November 2002</div> + +<pre class="display"> Copyright © 2000,2001,2002 Free Software Foundation, Inc. + 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA + + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. +</pre> + <ol type=1 start=0> +<li>PREAMBLE + + <p>The purpose of this License is to make a manual, textbook, or other +functional and useful document <dfn>free</dfn> in the sense of freedom: to +assure everyone the effective freedom to copy and redistribute it, +with or without modifying it, either commercially or noncommercially. +Secondarily, this License preserves for the author and publisher a way +to get credit for their work, while not being considered responsible +for modifications made by others. + + <p>This License is a kind of “copyleft”, which means that derivative +works of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft +license designed for free software. + + <p>We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference. + + <li>APPLICABILITY AND DEFINITIONS + + <p>This License applies to any manual or other work, in any medium, that +contains a notice placed by the copyright holder saying it can be +distributed under the terms of this License. Such a notice grants a +world-wide, royalty-free license, unlimited in duration, to use that +work under the conditions stated herein. The “Document”, below, +refers to any such manual or work. Any member of the public is a +licensee, and is addressed as “you”. You accept the license if you +copy, modify or distribute the work in a way requiring permission +under copyright law. + + <p>A “Modified Version” of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. + + <p>A “Secondary Section” is a named appendix or a front-matter section +of the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall +subject (or to related matters) and contains nothing that could fall +directly within that overall subject. (Thus, if the Document is in +part a textbook of mathematics, a Secondary Section may not explain +any mathematics.) The relationship could be a matter of historical +connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding +them. + + <p>The “Invariant Sections” are certain Secondary Sections whose titles +are designated, as being those of Invariant Sections, in the notice +that says that the Document is released under this License. If a +section does not fit the above definition of Secondary then it is not +allowed to be designated as Invariant. The Document may contain zero +Invariant Sections. If the Document does not identify any Invariant +Sections then there are none. + + <p>The “Cover Texts” are certain short passages of text that are listed, +as Front-Cover Texts or Back-Cover Texts, in the notice that says that +the Document is released under this License. A Front-Cover Text may +be at most 5 words, and a Back-Cover Text may be at most 25 words. + + <p>A “Transparent” copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, that is suitable for revising the document +straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available +drawing editor, and that is suitable for input to text formatters or +for automatic translation to a variety of formats suitable for input +to text formatters. A copy made in an otherwise Transparent file +format whose markup, or absence of markup, has been arranged to thwart +or discourage subsequent modification by readers is not Transparent. +An image format is not Transparent if used for any substantial amount +of text. A copy that is not “Transparent” is called “Opaque”. + + <p>Examples of suitable formats for Transparent copies include plain +<span class="sc">ascii</span> without markup, Texinfo input format, LaTeX input +format, <acronym>SGML</acronym> or <acronym>XML</acronym> using a publicly available +<acronym>DTD</acronym>, and standard-conforming simple <acronym>HTML</acronym>, +PostScript or <acronym>PDF</acronym> designed for human modification. Examples +of transparent image formats include <acronym>PNG</acronym>, <acronym>XCF</acronym> and +<acronym>JPG</acronym>. Opaque formats include proprietary formats that can be +read and edited only by proprietary word processors, <acronym>SGML</acronym> or +<acronym>XML</acronym> for which the <acronym>DTD</acronym> and/or processing tools are +not generally available, and the machine-generated <acronym>HTML</acronym>, +PostScript or <acronym>PDF</acronym> produced by some word processors for +output purposes only. + + <p>The “Title Page” means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, “Title Page” means +the text near the most prominent appearance of the work's title, +preceding the beginning of the body of the text. + + <p>A section “Entitled XYZ” means a named subunit of the Document whose +title either is precisely XYZ or contains XYZ in parentheses following +text that translates XYZ in another language. (Here XYZ stands for a +specific section name mentioned below, such as “Acknowledgements”, +“Dedications”, “Endorsements”, or “History”.) To “Preserve the Title” +of such a section when you modify the Document means that it remains a +section “Entitled XYZ” according to this definition. + + <p>The Document may include Warranty Disclaimers next to the notice which +states that this License applies to the Document. These Warranty +Disclaimers are considered to be included by reference in this +License, but only as regards disclaiming warranties: any other +implication that these Warranty Disclaimers may have is void and has +no effect on the meaning of this License. + + <li>VERBATIM COPYING + + <p>You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies +to the Document are reproduced in all copies, and that you add no other +conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in section 3. + + <p>You may also lend copies, under the same conditions stated above, and +you may publicly display copies. + + <li>COPYING IN QUANTITY + + <p>If you publish printed copies (or copies in media that commonly have +printed covers) of the Document, numbering more than 100, and the +Document's license notice requires Cover Texts, you must enclose the +copies in covers that carry, clearly and legibly, all these Cover +Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on +the back cover. Both covers must also clearly and legibly identify +you as the publisher of these copies. The front cover must present +the full title with all words of the title equally prominent and +visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve +the title of the Document and satisfy these conditions, can be treated +as verbatim copying in other respects. + + <p>If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. + + <p>If you publish or distribute Opaque copies of the Document numbering +more than 100, you must either include a machine-readable Transparent +copy along with each Opaque copy, or state in or with each Opaque copy +a computer-network location from which the general network-using +public has access to download using public-standard network protocols +a complete Transparent copy of the Document, free of added material. +If you use the latter option, you must take reasonably prudent steps, +when you begin distribution of Opaque copies in quantity, to ensure +that this Transparent copy will remain thus accessible at the stated +location until at least one year after the last time you distribute an +Opaque copy (directly or through your agents or retailers) of that +edition to the public. + + <p>It is requested, but not required, that you contact the authors of the +Document well before redistributing any large number of copies, to give +them a chance to provide you with an updated version of the Document. + + <li>MODIFICATIONS + + <p>You may copy and distribute a Modified Version of the Document under +the conditions of sections 2 and 3 above, provided that you release +the Modified Version under precisely this License, with the Modified +Version filling the role of the Document, thus licensing distribution +and modification of the Modified Version to whoever possesses a copy +of it. In addition, you must do these things in the Modified Version: + + <ol type=A start=1> +<li>Use in the Title Page (and on the covers, if any) a title distinct +from that of the Document, and from those of previous versions +(which should, if there were any, be listed in the History section +of the Document). You may use the same title as a previous version +if the original publisher of that version gives permission. + + <li>List on the Title Page, as authors, one or more persons or entities +responsible for authorship of the modifications in the Modified +Version, together with at least five of the principal authors of the +Document (all of its principal authors, if it has fewer than five), +unless they release you from this requirement. + + <li>State on the Title page the name of the publisher of the +Modified Version, as the publisher. + + <li>Preserve all the copyright notices of the Document. + + <li>Add an appropriate copyright notice for your modifications +adjacent to the other copyright notices. + + <li>Include, immediately after the copyright notices, a license notice +giving the public permission to use the Modified Version under the +terms of this License, in the form shown in the Addendum below. + + <li>Preserve in that license notice the full lists of Invariant Sections +and required Cover Texts given in the Document's license notice. + + <li>Include an unaltered copy of this License. + + <li>Preserve the section Entitled “History”, Preserve its Title, and add +to it an item stating at least the title, year, new authors, and +publisher of the Modified Version as given on the Title Page. If +there is no section Entitled “History” in the Document, create one +stating the title, year, authors, and publisher of the Document as +given on its Title Page, then add an item describing the Modified +Version as stated in the previous sentence. + + <li>Preserve the network location, if any, given in the Document for +public access to a Transparent copy of the Document, and likewise +the network locations given in the Document for previous versions +it was based on. These may be placed in the “History” section. +You may omit a network location for a work that was published at +least four years before the Document itself, or if the original +publisher of the version it refers to gives permission. + + <li>For any section Entitled “Acknowledgements” or “Dedications”, Preserve +the Title of the section, and preserve in the section all the +substance and tone of each of the contributor acknowledgements and/or +dedications given therein. + + <li>Preserve all the Invariant Sections of the Document, +unaltered in their text and in their titles. Section numbers +or the equivalent are not considered part of the section titles. + + <li>Delete any section Entitled “Endorsements”. Such a section +may not be included in the Modified Version. + + <li>Do not retitle any existing section to be Entitled “Endorsements” or +to conflict in title with any Invariant Section. + + <li>Preserve any Warranty Disclaimers. + </ol> + + <p>If the Modified Version includes new front-matter sections or +appendices that qualify as Secondary Sections and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the +list of Invariant Sections in the Modified Version's license notice. +These titles must be distinct from any other section titles. + + <p>You may add a section Entitled “Endorsements”, provided it contains +nothing but endorsements of your Modified Version by various +parties—for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of a +standard. + + <p>You may add a passage of up to five words as a Front-Cover Text, and a +passage of up to 25 words as a Back-Cover Text, to the end of the list +of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already +includes a cover text for the same cover, previously added by you or +by arrangement made by the same entity you are acting on behalf of, +you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. + + <p>The author(s) and publisher(s) of the Document do not by this License +give permission to use their names for publicity for or to assert or +imply endorsement of any Modified Version. + + <li>COMBINING DOCUMENTS + + <p>You may combine the Document with other documents released under this +License, under the terms defined in section 4 above for modified +versions, provided that you include in the combination all of the +Invariant Sections of all of the original documents, unmodified, and +list them all as Invariant Sections of your combined work in its +license notice, and that you preserve all their Warranty Disclaimers. + + <p>The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name but +different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original +author or publisher of that section if known, or else a unique number. +Make the same adjustment to the section titles in the list of +Invariant Sections in the license notice of the combined work. + + <p>In the combination, you must combine any sections Entitled “History” +in the various original documents, forming one section Entitled +“History”; likewise combine any sections Entitled “Acknowledgements”, +and any sections Entitled “Dedications”. You must delete all +sections Entitled “Endorsements.” + + <li>COLLECTIONS OF DOCUMENTS + + <p>You may make a collection consisting of the Document and other documents +released under this License, and replace the individual copies of this +License in the various documents with a single copy that is included in +the collection, provided that you follow the rules of this License for +verbatim copying of each of the documents in all other respects. + + <p>You may extract a single document from such a collection, and distribute +it individually under this License, provided you insert a copy of this +License into the extracted document, and follow this License in all +other respects regarding verbatim copying of that document. + + <li>AGGREGATION WITH INDEPENDENT WORKS + + <p>A compilation of the Document or its derivatives with other separate +and independent documents or works, in or on a volume of a storage or +distribution medium, is called an “aggregate” if the copyright +resulting from the compilation is not used to limit the legal rights +of the compilation's users beyond what the individual works permit. +When the Document is included in an aggregate, this License does not +apply to the other works in the aggregate which are not themselves +derivative works of the Document. + + <p>If the Cover Text requirement of section 3 is applicable to these +copies of the Document, then if the Document is less than one half of +the entire aggregate, the Document's Cover Texts may be placed on +covers that bracket the Document within the aggregate, or the +electronic equivalent of covers if the Document is in electronic form. +Otherwise they must appear on printed covers that bracket the whole +aggregate. + + <li>TRANSLATION + + <p>Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of section 4. +Replacing Invariant Sections with translations requires special +permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include a +translation of this License, and all the license notices in the +Document, and any Warranty Disclaimers, provided that you also include +the original English version of this License and the original versions +of those notices and disclaimers. In case of a disagreement between +the translation and the original version of this License or a notice +or disclaimer, the original version will prevail. + + <p>If a section in the Document is Entitled “Acknowledgements”, +“Dedications”, or “History”, the requirement (section 4) to Preserve +its Title (section 1) will typically require changing the actual +title. + + <li>TERMINATION + + <p>You may not copy, modify, sublicense, or distribute the Document except +as expressly provided for under this License. Any other attempt to +copy, modify, sublicense or distribute the Document is void, and will +automatically terminate your rights under this License. However, +parties who have received copies, or rights, from you under this +License will not have their licenses terminated so long as such +parties remain in full compliance. + + <li>FUTURE REVISIONS OF THIS LICENSE + + <p>The Free Software Foundation may publish new, revised versions +of the GNU Free Documentation License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. See +<a href="http://www.gnu.org/copyleft/">http://www.gnu.org/copyleft/</a>. + + <p>Each version of the License is given a distinguishing version number. +If the Document specifies that a particular numbered version of this +License “or any later version” applies to it, you have the option of +following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation. + </ol> + +<h4 class="appendixsubsec">G.1.1 ADDENDUM: How to use this License for your documents</h4> + +<p>To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and +license notices just after the title page: + +<pre class="smallexample"> Copyright (C) <var>year</var> <var>your name</var>. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.2 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover + Texts. A copy of the license is included in the section entitled ``GNU + Free Documentation License''. +</pre> + <p>If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, +replace the “with...Texts.” line with this: + +<pre class="smallexample"> with the Invariant Sections being <var>list their titles</var>, with + the Front-Cover Texts being <var>list</var>, and with the Back-Cover Texts + being <var>list</var>. +</pre> + <p>If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + + <p>If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, +to permit their use in free software. + +<!-- Local Variables: --> +<!-- ispell-local-pdict: "ispell-dict" --> +<!-- End: --> +<div class="node"> +<p><hr> +<a name="Command-and-Variable-Index"></a>Next: <a rel="next" accesskey="n" href="#Concept-Index">Concept Index</a>, +Previous: <a rel="previous" accesskey="p" href="#Copying-This-Manual">Copying This Manual</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> +<br> +</div> + +<h2 class="unnumbered">Command and Variable Index</h2> + +<p>This is an alphabetical list of all the @-commands, assorted Emacs Lisp +functions, and several variables. To make the list easier to use, the +commands are listed without their preceding <span class="samp">@</span>. + + + +<ul class="index-fn" compact> +<li><a href="#index-_0021-_0040r_007b_0028end-of-sentence_0029_007d-642"><code>! </code><span class="roman">(end of sentence)</span></a>: <a href="#Ending-a-Sentence">Ending a Sentence</a></li> +<li><a href="#index-_0022-_0040r_007b_0028umlaut-accent_0029_007d-657"><code>" </code><span class="roman">(umlaut accent)</span></a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-_0027-_0040r_007b_0028umlaut-accent_0029_007d-659"><code>' </code><span class="roman">(umlaut accent)</span></a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-_002a-_0040r_007b_0028force-line-break_0029_007d-780"><code>* </code><span class="roman">(force line break)</span></a>: <a href="#Line-Breaks">Line Breaks</a></li> +<li><a href="#index-_002c-_0040r_007b_0028cedilla-accent_0029_007d-669"><code>, </code><span class="roman">(cedilla accent)</span></a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-_002d-_0040r_007b_0028discretionary-hyphen_0029_007d-786"><code>- </code><span class="roman">(discretionary hyphen)</span></a>: <a href="#_002d-and-hyphenation">- and hyphenation</a></li> +<li><a href="#index-_002e--_0040r_007b_0028end-of-sentence_0029_007d-641"><code>. </code><span class="roman">(end of sentence)</span></a>: <a href="#Ending-a-Sentence">Ending a Sentence</a></li> +<li><a href="#index-_002f-_0040r_007b_0028allow-line-break_0029_007d-781"><code>/ </code><span class="roman">(allow line break)</span></a>: <a href="#Line-Breaks">Line Breaks</a></li> +<li><a href="#index-_003ccolon_003e-_0040r_007b_0028suppress-end_002dof_002dsentence-space_0029_007d-638"><code><colon> </code><span class="roman">(suppress end-of-sentence space)</span></a>: <a href="#Not-Ending-a-Sentence">Not Ending a Sentence</a></li> +<li><a href="#index-_003cnewline_003e-649"><code><newline></code></a>: <a href="#Multiple-Spaces">Multiple Spaces</a></li> +<li><a href="#index-_003cspace_003e-647"><code><space></code></a>: <a href="#Multiple-Spaces">Multiple Spaces</a></li> +<li><a href="#index-_003ctab_003e-648"><code><tab></code></a>: <a href="#Multiple-Spaces">Multiple Spaces</a></li> +<li><a href="#index-_003d-_0040r_007b_0028macron-accent_0029_007d-661"><code>= </code><span class="roman">(macron accent)</span></a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-_003f-_0040r_007b_0028end-of-sentence_0029_007d-643"><code>? </code><span class="roman">(end of sentence)</span></a>: <a href="#Ending-a-Sentence">Ending a Sentence</a></li> +<li><a href="#index-_0040_0040-_0040r_007b_0028literal-_0040samp_007b_0040_0040_007d_0029_007d-626"><code>@ </code><span class="roman">(literal @)</span></a>: <a href="#Inserting-an-Atsign">Inserting an Atsign</a></li> +<li><a href="#index-_005c-_0040r_007b_0028literal-_005c-in-_0040code_007b_0040_0040math_007d_0029_007d-753"><code>\ </code><span class="roman">(literal \ in </span><code>@math</code><span class="roman">)</span></a>: <a href="#math">math</a></li> +<li><a href="#index-_005cemergencystretch-1030"><code>\emergencystretch</code></a>: <a href="#Overfull-hboxes">Overfull hboxes</a></li> +<li><a href="#index-_005cgdef-_0040r_007bwithin-_0040code_007b_0040_0040tex_007d_007d-897"><code>\gdef </code><span class="roman">within </span><code>@tex</code></a>: <a href="#Raw-Formatter-Commands">Raw Formatter Commands</a></li> +<li><a href="#index-_005cinput-_0040r_007b_0028raw-_0040TeX_007b_007d-startup_0029_007d-76"><code>\input </code><span class="roman">(raw TeX startup)</span></a>: <a href="#Minimum">Minimum</a></li> +<li><a href="#index-_005cmag-_0040r_007b_0028raw-_0040TeX_007b_007d-magnification_0029_007d-1061"><code>\mag </code><span class="roman">(raw TeX magnification)</span></a>: <a href="#Cropmarks-and-Magnification">Cropmarks and Magnification</a></li> +<li><a href="#index-_005e-_0040r_007b_0028circumflex-accent_0029_007d-663"><code>^ </code><span class="roman">(circumflex accent)</span></a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-_0060-_0040r_007b_0028grave-accent_0029_007d-665"><code>` </code><span class="roman">(grave accent)</span></a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-AA-695"><code>AA</code></a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-aa-693"><code>aa</code></a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-acronym-429"><code>acronym</code></a>: <a href="#acronym">acronym</a></li> +<li><a href="#index-AE-699"><code>AE</code></a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-ae-697"><code>ae</code></a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-afourlatex-1046"><code>afourlatex</code></a>: <a href="#A4-Paper">A4 Paper</a></li> +<li><a href="#index-afourpaper-1045"><code>afourpaper</code></a>: <a href="#A4-Paper">A4 Paper</a></li> +<li><a href="#index-afourwide-1047"><code>afourwide</code></a>: <a href="#A4-Paper">A4 Paper</a></li> +<li><a href="#index-alias-963"><code>alias</code></a>: <a href="#alias">alias</a></li> +<li><a href="#index-anchor-332"><code>anchor</code></a>: <a href="#anchor">anchor</a></li> +<li><a href="#index-appendix-276"><code>appendix</code></a>: <a href="#unnumbered-_0026-appendix">unnumbered & appendix</a></li> +<li><a href="#index-appendixsec-281"><code>appendixsec</code></a>: <a href="#unnumberedsec-appendixsec-heading">unnumberedsec appendixsec heading</a></li> +<li><a href="#index-appendixsection-283"><code>appendixsection</code></a>: <a href="#unnumberedsec-appendixsec-heading">unnumberedsec appendixsec heading</a></li> +<li><a href="#index-appendixsubsec-287"><code>appendixsubsec</code></a>: <a href="#unnumberedsubsec-appendixsubsec-subheading">unnumberedsubsec appendixsubsec subheading</a></li> +<li><a href="#index-appendixsubsubsec-292"><code>appendixsubsubsec</code></a>: <a href="#subsubsection">subsubsection</a></li> +<li><a href="#index-apply-871"><code>apply</code></a>: <a href="#Sample-Function-Definition">Sample Function Definition</a></li> +<li><a href="#index-asis-516"><code>asis</code></a>: <a href="#table">table</a></li> +<li><a href="#index-author-204"><code>author</code></a>: <a href="#title-subtitle-author">title subtitle author</a></li> +<li><a href="#index-b-_0040r_007b_0028bold-font_0029_007d-449"><code>b </code><span class="roman">(bold font)</span></a>: <a href="#Fonts">Fonts</a></li> +<li><a href="#index-bullet-741"><code>bullet</code></a>: <a href="#bullet">bullet</a></li> +<li><a href="#index-bye-269"><code>bye</code></a>: <a href="#File-End">File End</a></li> +<li><a href="#index-bye-263"><code>bye</code></a>: <a href="#Ending-a-File">Ending a File</a></li> +<li><a href="#index-c-_0040r_007b_0028comment_0029_007d-68"><code>c </code><span class="roman">(comment)</span></a>: <a href="#Comments">Comments</a></li> +<li><a href="#index-caption-548"><code>caption</code></a>: <a href="#caption-shortcaption">caption shortcaption</a></li> +<li><a href="#index-cartouche-500"><code>cartouche</code></a>: <a href="#cartouche">cartouche</a></li> +<li><a href="#index-center-200"><code>center</code></a>: <a href="#titlefont-center-sp">titlefont center sp</a></li> +<li><a href="#index-centerchap-274"><code>centerchap</code></a>: <a href="#chapter">chapter</a></li> +<li><a href="#index-chapheading-278"><code>chapheading</code></a>: <a href="#majorheading-_0026-chapheading">majorheading & chapheading</a></li> +<li><a href="#index-chapter-273"><code>chapter</code></a>: <a href="#chapter">chapter</a></li> +<li><a href="#index-cite-428"><code>cite</code></a>: <a href="#cite">cite</a></li> +<li><a href="#index-code-396"><code>code</code></a>: <a href="#code">code</a></li> +<li><a href="#index-columnfractions-529"><code>columnfractions</code></a>: <a href="#Multitable-Column-Widths">Multitable Column Widths</a></li> +<li><a href="#index-comma-632"><code>comma</code></a>: <a href="#Inserting-a-Comma">Inserting a Comma</a></li> +<li><a href="#index-command-423"><code>command</code></a>: <a href="#command">command</a></li> +<li><a href="#index-comment-67"><code>comment</code></a>: <a href="#Comments">Comments</a></li> +<li><a href="#index-contents-218"><code>contents</code></a>: <a href="#Contents">Contents</a></li> +<li><a href="#index-copying-180"><code>copying</code></a>: <a href="#copying">copying</a></li> +<li><a href="#index-copyright-181"><code>copyright</code></a>: <a href="#copying">copying</a></li> +<li><a href="#index-copyright-744"><code>copyright</code></a>: <a href="#copyright-symbol">copyright symbol</a></li> +<li><a href="#index-cropmarks-1058"><code>cropmarks</code></a>: <a href="#Cropmarks-and-Magnification">Cropmarks and Magnification</a></li> +<li><a href="#index-defcodeindex-621"><code>defcodeindex</code></a>: <a href="#New-Indices">New Indices</a></li> +<li><a href="#index-defcv-852"><code>defcv</code></a>: <a href="#Object_002dOriented-Variables">Object-Oriented Variables</a></li> +<li><a href="#index-deffn-837"><code>deffn</code></a>: <a href="#Functions-Commands">Functions Commands</a></li> +<li><a href="#index-deffnx-834"><code>deffnx</code></a>: <a href="#deffnx">deffnx</a></li> +<li><a href="#index-defindex-620"><code>defindex</code></a>: <a href="#New-Indices">New Indices</a></li> +<li><a href="#index-definfoenclose-966"><code>definfoenclose</code></a>: <a href="#definfoenclose">definfoenclose</a></li> +<li><a href="#index-defivar-856"><code>defivar</code></a>: <a href="#Object_002dOriented-Variables">Object-Oriented Variables</a></li> +<li><a href="#index-defmac-839"><code>defmac</code></a>: <a href="#Functions-Commands">Functions Commands</a></li> +<li><a href="#index-defmethod-864"><code>defmethod</code></a>: <a href="#Object_002dOriented-Methods">Object-Oriented Methods</a></li> +<li><a href="#index-defop-861"><code>defop</code></a>: <a href="#Object_002dOriented-Methods">Object-Oriented Methods</a></li> +<li><a href="#index-defopt-843"><code>defopt</code></a>: <a href="#Variables-Commands">Variables Commands</a></li> +<li><a href="#index-defspec-840"><code>defspec</code></a>: <a href="#Functions-Commands">Functions Commands</a></li> +<li><a href="#index-deftp-849"><code>deftp</code></a>: <a href="#Data-Types">Data Types</a></li> +<li><a href="#index-deftypecv-854"><code>deftypecv</code></a>: <a href="#Object_002dOriented-Variables">Object-Oriented Variables</a></li> +<li><a href="#index-deftypefn-845"><code>deftypefn</code></a>: <a href="#Typed-Functions">Typed Functions</a></li> +<li><a href="#index-deftypefun-846"><code>deftypefun</code></a>: <a href="#Typed-Functions">Typed Functions</a></li> +<li><a href="#index-deftypeivar-858"><code>deftypeivar</code></a>: <a href="#Object_002dOriented-Variables">Object-Oriented Variables</a></li> +<li><a href="#index-deftypeop-862"><code>deftypeop</code></a>: <a href="#Object_002dOriented-Methods">Object-Oriented Methods</a></li> +<li><a href="#index-deftypevar-848"><code>deftypevar</code></a>: <a href="#Typed-Variables">Typed Variables</a></li> +<li><a href="#index-deftypevr-847"><code>deftypevr</code></a>: <a href="#Typed-Variables">Typed Variables</a></li> +<li><a href="#index-defun-838"><code>defun</code></a>: <a href="#Functions-Commands">Functions Commands</a></li> +<li><a href="#index-defvar-842"><code>defvar</code></a>: <a href="#Variables-Commands">Variables Commands</a></li> +<li><a href="#index-defvr-841"><code>defvr</code></a>: <a href="#Variables-Commands">Variables Commands</a></li> +<li><a href="#index-dfn-427"><code>dfn</code></a>: <a href="#dfn">dfn</a></li> +<li><a href="#index-dircategory-1175"><code>dircategory</code></a>: <a href="#Installing-Dir-Entries">Installing Dir Entries</a></li> +<li><a href="#index-direntry-1176"><code>direntry</code></a>: <a href="#Installing-Dir-Entries">Installing Dir Entries</a></li> +<li><a href="#index-display-482"><code>display</code></a>: <a href="#display">display</a></li> +<li><a href="#index-dmn-653"><code>dmn</code></a>: <a href="#dmn">dmn</a></li> +<li><a href="#index-docbook-904"><code>docbook</code></a>: <a href="#Raw-Formatter-Commands">Raw Formatter Commands</a></li> +<li><a href="#index-documentdescription-238"><code>documentdescription</code></a>: <a href="#documentdescription">documentdescription</a></li> +<li><a href="#index-documentencoding-919"><code>documentencoding</code></a>: <a href="#documentencoding">documentencoding</a></li> +<li><a href="#index-documentlanguage-912"><code>documentlanguage</code></a>: <a href="#documentlanguage">documentlanguage</a></li> +<li><a href="#index-dotaccent-671"><code>dotaccent</code></a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-dotless-701"><code>dotless</code></a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-dots-737"><code>dots</code></a>: <a href="#dots">dots</a></li> +<li><a href="#index-email-438"><code>email</code></a>: <a href="#email">email</a></li> +<li><a href="#index-emph-442"><code>emph</code></a>: <a href="#emph-_0026-strong">emph & strong</a></li> +<li><a href="#index-end-506"><code>end</code></a>: <a href="#Introducing-Lists">Introducing Lists</a></li> +<li><a href="#index-end-459"><code>end</code></a>: <a href="#Quotations-and-Examples">Quotations and Examples</a></li> +<li><a href="#index-end-titlepage-210"><code>end titlepage</code></a>: <a href="#end-titlepage">end titlepage</a></li> +<li><a href="#index-enddots-738"><code>enddots</code></a>: <a href="#dots">dots</a></li> +<li><a href="#index-enumerate-512"><code>enumerate</code></a>: <a href="#enumerate">enumerate</a></li> +<li><a href="#index-env-421"><code>env</code></a>: <a href="#env">env</a></li> +<li><a href="#index-equiv-771"><code>equiv</code></a>: <a href="#Equivalence">Equivalence</a></li> +<li><a href="#index-error-769"><code>error</code></a>: <a href="#Error-Glyph">Error Glyph</a></li> +<li><a href="#index-evenfooting-1276"><code>evenfooting</code></a>: <a href="#Custom-Headings">Custom Headings</a></li> +<li><a href="#index-evenheading-1275"><code>evenheading</code></a>: <a href="#Custom-Headings">Custom Headings</a></li> +<li><a href="#index-everyfooting-1274"><code>everyfooting</code></a>: <a href="#Custom-Headings">Custom Headings</a></li> +<li><a href="#index-everyheading-1273"><code>everyheading</code></a>: <a href="#Custom-Headings">Custom Headings</a></li> +<li><a href="#index-example-466"><code>example</code></a>: <a href="#example">example</a></li> +<li><a href="#index-exampleindent-254"><code>exampleindent</code></a>: <a href="#exampleindent">exampleindent</a></li> +<li><a href="#index-exclamdown-691"><code>exclamdown</code></a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-exdent-487"><code>exdent</code></a>: <a href="#exdent">exdent</a></li> +<li><a href="#index-expansion-765"><code>expansion</code></a>: <a href="#expansion">expansion</a></li> +<li><a href="#index-file-422"><code>file</code></a>: <a href="#file">file</a></li> +<li><a href="#index-filll-_0040r_007b_0040TeX_007b_007d-dimension_007d-209"><code>filll </code><span class="roman">TeX dimension</span></a>: <a href="#Copyright">Copyright</a></li> +<li><a href="#index-finalout-1035"><code>finalout</code></a>: <a href="#Overfull-hboxes">Overfull hboxes</a></li> +<li><a href="#index-firstparagraphindent-250"><code>firstparagraphindent</code></a>: <a href="#firstparagraphindent">firstparagraphindent</a></li> +<li><a href="#index-float-542"><code>float</code></a>: <a href="#float">float</a></li> +<li><a href="#index-flushleft-488"><code>flushleft</code></a>: <a href="#flushleft-_0026-flushright">flushleft & flushright</a></li> +<li><a href="#index-flushright-489"><code>flushright</code></a>: <a href="#flushleft-_0026-flushright">flushleft & flushright</a></li> +<li><a href="#index-fn_002dname-822"><code>fn-name</code></a>: <a href="#Def-Cmd-Continuation-Lines">Def Cmd Continuation Lines</a></li> +<li><a href="#index-foobar-830"><code>foobar</code></a>: <a href="#Optional-Arguments">Optional Arguments</a></li> +<li><a href="#index-footnote-587"><code>footnote</code></a>: <a href="#Footnotes">Footnotes</a></li> +<li><a href="#index-footnotestyle-590"><code>footnotestyle</code></a>: <a href="#Footnote-Styles">Footnote Styles</a></li> +<li><a href="#index-format-484"><code>format</code></a>: <a href="#format">format</a></li> +<li><a href="#index-forward_002dword-817"><code>forward-word</code></a>: <a href="#Def-Cmd-Template">Def Cmd Template</a></li> +<li><a href="#index-ftable-520"><code>ftable</code></a>: <a href="#ftable-vtable">ftable vtable</a></li> +<li><a href="#index-group-811"><code>group</code></a>: <a href="#group">group</a></li> +<li><a href="#index-H-_0040r_007b_0028Hungarian-umlaut-accent_0029_007d-673"><code>H </code><span class="roman">(Hungarian umlaut accent)</span></a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-hbox-1029"><code>hbox</code></a>: <a href="#Overfull-hboxes">Overfull hboxes</a></li> +<li><a href="#index-heading-282"><code>heading</code></a>: <a href="#unnumberedsec-appendixsec-heading">unnumberedsec appendixsec heading</a></li> +<li><a href="#index-headings-214"><code>headings</code></a>: <a href="#headings-on-off">headings on off</a></li> +<li><a href="#index-headitem-536"><code>headitem</code></a>: <a href="#Multitable-Rows">Multitable Rows</a></li> +<li><a href="#index-headword-968"><code>headword</code></a>: <a href="#definfoenclose">definfoenclose</a></li> +<li><a href="#index-html-900"><code>html</code></a>: <a href="#Raw-Formatter-Commands">Raw Formatter Commands</a></li> +<li><a href="#index-hyphenation-787"><code>hyphenation</code></a>: <a href="#_002d-and-hyphenation">- and hyphenation</a></li> +<li><a href="#index-i-_0040r_007b_0028italic-font_0029_007d-448"><code>i </code><span class="roman">(italic font)</span></a>: <a href="#Fonts">Fonts</a></li> +<li><a href="#index-ifclear-908"><code>ifclear</code></a>: <a href="#ifset-ifclear">ifset ifclear</a></li> +<li><a href="#index-ifdocbook-903"><code>ifdocbook</code></a>: <a href="#Raw-Formatter-Commands">Raw Formatter Commands</a></li> +<li><a href="#index-ifdocbook-877"><code>ifdocbook</code></a>: <a href="#Conditional-Commands">Conditional Commands</a></li> +<li><a href="#index-ifhtml-899"><code>ifhtml</code></a>: <a href="#Raw-Formatter-Commands">Raw Formatter Commands</a></li> +<li><a href="#index-ifhtml-878"><code>ifhtml</code></a>: <a href="#Conditional-Commands">Conditional Commands</a></li> +<li><a href="#index-ifinfo-876"><code>ifinfo</code></a>: <a href="#Conditional-Commands">Conditional Commands</a></li> +<li><a href="#index-ifnotdocbook-882"><code>ifnotdocbook</code></a>: <a href="#Conditional-Not-Commands">Conditional Not Commands</a></li> +<li><a href="#index-ifnothtml-883"><code>ifnothtml</code></a>: <a href="#Conditional-Not-Commands">Conditional Not Commands</a></li> +<li><a href="#index-ifnotinfo-884"><code>ifnotinfo</code></a>: <a href="#Conditional-Not-Commands">Conditional Not Commands</a></li> +<li><a href="#index-ifnotplaintext-885"><code>ifnotplaintext</code></a>: <a href="#Conditional-Not-Commands">Conditional Not Commands</a></li> +<li><a href="#index-ifnottex-886"><code>ifnottex</code></a>: <a href="#Conditional-Not-Commands">Conditional Not Commands</a></li> +<li><a href="#index-ifnotxml-887"><code>ifnotxml</code></a>: <a href="#Conditional-Not-Commands">Conditional Not Commands</a></li> +<li><a href="#index-ifplaintext-879"><code>ifplaintext</code></a>: <a href="#Conditional-Commands">Conditional Commands</a></li> +<li><a href="#index-ifset-906"><code>ifset</code></a>: <a href="#ifset-ifclear">ifset ifclear</a></li> +<li><a href="#index-iftex-880"><code>iftex</code></a>: <a href="#Conditional-Commands">Conditional Commands</a></li> +<li><a href="#index-ifxml-901"><code>ifxml</code></a>: <a href="#Raw-Formatter-Commands">Raw Formatter Commands</a></li> +<li><a href="#index-ifxml-881"><code>ifxml</code></a>: <a href="#Conditional-Commands">Conditional Commands</a></li> +<li><a href="#index-ignore-71"><code>ignore</code></a>: <a href="#Comments">Comments</a></li> +<li><a href="#index-image-558"><code>image</code></a>: <a href="#Images">Images</a></li> +<li><a href="#index-include-1261"><code>include</code></a>: <a href="#Using-Include-Files">Using Include Files</a></li> +<li><a href="#index-indent-499"><code>indent</code></a>: <a href="#indent">indent</a></li> +<li><a href="#index-indicateurl-435"><code>indicateurl</code></a>: <a href="#indicateurl">indicateurl</a></li> +<li><a href="#index-Info_002dvalidate-1300"><code>Info-validate</code></a>: <a href="#Running-Info_002dValidate">Running Info-Validate</a></li> +<li><a href="#index-inforef-382"><code>inforef</code></a>: <a href="#inforef">inforef</a></li> +<li><a href="#index-insertcopying-187"><code>insertcopying</code></a>: <a href="#insertcopying">insertcopying</a></li> +<li><a href="#index-isearch_002dbackward-836"><code>isearch-backward</code></a>: <a href="#deffnx">deffnx</a></li> +<li><a href="#index-isearch_002dforward-835"><code>isearch-forward</code></a>: <a href="#deffnx">deffnx</a></li> +<li><a href="#index-item-534"><code>item</code></a>: <a href="#Multitable-Rows">Multitable Rows</a></li> +<li><a href="#index-item-517"><code>item</code></a>: <a href="#table">table</a></li> +<li><a href="#index-item-510"><code>item</code></a>: <a href="#itemize">itemize</a></li> +<li><a href="#index-itemize-508"><code>itemize</code></a>: <a href="#itemize">itemize</a></li> +<li><a href="#index-itemx-523"><code>itemx</code></a>: <a href="#itemx">itemx</a></li> +<li><a href="#index-kbd-402"><code>kbd</code></a>: <a href="#kbd">kbd</a></li> +<li><a href="#index-kbdinputstyle-406"><code>kbdinputstyle</code></a>: <a href="#kbd">kbd</a></li> +<li><a href="#index-key-410"><code>key</code></a>: <a href="#key">key</a></li> +<li><a href="#index-l-705"><code>l</code></a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-L-707"><code>L</code></a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-LaTeX-743"><code>LaTeX</code></a>: <a href="#tex">tex</a></li> +<li><a href="#index-lisp-472"><code>lisp</code></a>: <a href="#lisp">lisp</a></li> +<li><a href="#index-listoffloats-552"><code>listoffloats</code></a>: <a href="#listoffloats">listoffloats</a></li> +<li><a href="#index-lowersections-295"><code>lowersections</code></a>: <a href="#Raise_002flower-sections">Raise/lower sections</a></li> +<li><a href="#index-macro-937"><code>macro</code></a>: <a href="#Defining-Macros">Defining Macros</a></li> +<li><a href="#index-majorheading-277"><code>majorheading</code></a>: <a href="#majorheading-_0026-chapheading">majorheading & chapheading</a></li> +<li><a href="#index-makeinfo_002dbuffer-1144"><code>makeinfo-buffer</code></a>: <a href="#makeinfo-in-Emacs">makeinfo in Emacs</a></li> +<li><a href="#index-makeinfo_002dkill_002djob-1148"><code>makeinfo-kill-job</code></a>: <a href="#makeinfo-in-Emacs">makeinfo in Emacs</a></li> +<li><a href="#index-makeinfo_002drecenter_002doutput_002dbuffer-1149"><code>makeinfo-recenter-output-buffer</code></a>: <a href="#makeinfo-in-Emacs">makeinfo in Emacs</a></li> +<li><a href="#index-makeinfo_002dregion-1143"><code>makeinfo-region</code></a>: <a href="#makeinfo-in-Emacs">makeinfo in Emacs</a></li> +<li><a href="#index-math-750"><code>math</code></a>: <a href="#math">math</a></li> +<li><a href="#index-menu-337"><code>menu</code></a>: <a href="#Menus">Menus</a></li> +<li><a href="#index-minus-747"><code>minus</code></a>: <a href="#minus">minus</a></li> +<li><a href="#index-multitable-525"><code>multitable</code></a>: <a href="#Multi_002dcolumn-Tables">Multi-column Tables</a></li> +<li><a href="#index-need-813"><code>need</code></a>: <a href="#need">need</a></li> +<li><a href="#index-next_002derror-1147"><code>next-error</code></a>: <a href="#makeinfo-in-Emacs">makeinfo in Emacs</a></li> +<li><a href="#index-node-301"><code>node</code></a>: <a href="#node">node</a></li> +<li><a href="#index-noindent-495"><code>noindent</code></a>: <a href="#noindent">noindent</a></li> +<li><a href="#index-novalidate-987"><code>novalidate</code></a>: <a href="#Format-with-tex_002ftexindex">Format with tex/texindex</a></li> +<li><a href="#index-o-709"><code>o</code></a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-O-711"><code>O</code></a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-occur-1299"><code>occur</code></a>: <a href="#Using-occur">Using occur</a></li> +<li><a href="#index-occur_002dmode_002dgoto_002doccurrence-125"><code>occur-mode-goto-occurrence</code></a>: <a href="#Showing-the-Structure">Showing the Structure</a></li> +<li><a href="#index-oddfooting-1278"><code>oddfooting</code></a>: <a href="#Custom-Headings">Custom Headings</a></li> +<li><a href="#index-oddheading-1277"><code>oddheading</code></a>: <a href="#Custom-Headings">Custom Headings</a></li> +<li><a href="#index-oe-713"><code>oe</code></a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-OE-715"><code>OE</code></a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-option-426"><code>option</code></a>: <a href="#option">option</a></li> +<li><a href="#index-ordf-720"><code>ordf</code></a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-ordm-723"><code>ordm</code></a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-page-807"><code>page</code></a>: <a href="#page">page</a></li> +<li><a href="#index-page_0040r_007b_002c-within-_0040code_007b_0040_0040titlepage_007d_007d-195"><code>page</code><span class="roman">, within </span><code>@titlepage</code></a>: <a href="#titlepage">titlepage</a></li> +<li><a href="#index-pagesizes-1048"><code>pagesizes</code></a>: <a href="#pagesizes">pagesizes</a></li> +<li><a href="#index-paragraphindent-244"><code>paragraphindent</code></a>: <a href="#paragraphindent">paragraphindent</a></li> +<li><a href="#index-phoo-967"><code>phoo</code></a>: <a href="#definfoenclose">definfoenclose</a></li> +<li><a href="#index-point-773"><code>point</code></a>: <a href="#Point-Glyph">Point Glyph</a></li> +<li><a href="#index-pounds-746"><code>pounds</code></a>: <a href="#pounds">pounds</a></li> +<li><a href="#index-print-767"><code>print</code></a>: <a href="#Print-Glyph">Print Glyph</a></li> +<li><a href="#index-printindex-268"><code>printindex</code></a>: <a href="#Printing-Indices-_0026-Menus">Printing Indices & Menus</a></li> +<li><a href="#index-pxref-378"><code>pxref</code></a>: <a href="#pxref">pxref</a></li> +<li><a href="#index-questiondown-689"><code>questiondown</code></a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-quotation-461"><code>quotation</code></a>: <a href="#quotation">quotation</a></li> +<li><a href="#index-r-_0040r_007b_0028roman-font_0029_007d-451"><code>r </code><span class="roman">(roman font)</span></a>: <a href="#Fonts">Fonts</a></li> +<li><a href="#index-raisesections-294"><code>raisesections</code></a>: <a href="#Raise_002flower-sections">Raise/lower sections</a></li> +<li><a href="#index-ref-373"><code>ref</code></a>: <a href="#ref">ref</a></li> +<li><a href="#index-registeredsymbol-745"><code>registeredsymbol</code></a>: <a href="#registered-symbol">registered symbol</a></li> +<li><a href="#index-result-762"><code>result</code></a>: <a href="#result">result</a></li> +<li><a href="#index-ringaccent-675"><code>ringaccent</code></a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-rmacro-948"><code>rmacro</code></a>: <a href="#Defining-Macros">Defining Macros</a></li> +<li><a href="#index-samp-416"><code>samp</code></a>: <a href="#samp">samp</a></li> +<li><a href="#index-sc-_0040r_007b_0028small-caps-font_0029_007d-445"><code>sc </code><span class="roman">(small caps font)</span></a>: <a href="#Smallcaps">Smallcaps</a></li> +<li><a href="#index-section-279"><code>section</code></a>: <a href="#section">section</a></li> +<li><a href="#index-setchapternewpage-241"><code>setchapternewpage</code></a>: <a href="#setchapternewpage">setchapternewpage</a></li> +<li><a href="#index-setcontentsaftertitlepage-221"><code>setcontentsaftertitlepage</code></a>: <a href="#Contents">Contents</a></li> +<li><a href="#index-setfilename-167"><code>setfilename</code></a>: <a href="#setfilename">setfilename</a></li> +<li><a href="#index-setshortcontentsaftertitlepage-222"><code>setshortcontentsaftertitlepage</code></a>: <a href="#Contents">Contents</a></li> +<li><a href="#index-settitle-175"><code>settitle</code></a>: <a href="#settitle">settitle</a></li> +<li><a href="#index-shortcaption-549"><code>shortcaption</code></a>: <a href="#caption-shortcaption">caption shortcaption</a></li> +<li><a href="#index-shortcontents-220"><code>shortcontents</code></a>: <a href="#Contents">Contents</a></li> +<li><a href="#index-shorttitlepage-196"><code>shorttitlepage</code></a>: <a href="#titlepage">titlepage</a></li> +<li><a href="#index-smallbook-1036"><code>smallbook</code></a>: <a href="#smallbook">smallbook</a></li> +<li><a href="#index-smalldisplay-477"><code>smalldisplay</code></a>: <a href="#small">small</a></li> +<li><a href="#index-smalldisplay-483"><code>smalldisplay</code></a>: <a href="#display">display</a></li> +<li><a href="#index-smallexample-478"><code>smallexample</code></a>: <a href="#small">small</a></li> +<li><a href="#index-smallformat-485"><code>smallformat</code></a>: <a href="#format">format</a></li> +<li><a href="#index-smallformat-479"><code>smallformat</code></a>: <a href="#small">small</a></li> +<li><a href="#index-smalllisp-480"><code>smalllisp</code></a>: <a href="#small">small</a></li> +<li><a href="#index-sp-_0040r_007b_0028line-spacing_0029_007d-802"><code>sp </code><span class="roman">(line spacing)</span></a>: <a href="#sp">sp</a></li> +<li><a href="#index-sp-_0040r_007b_0028titlepage-line-spacing_0029_007d-201"><code>sp </code><span class="roman">(titlepage line spacing)</span></a>: <a href="#titlefont-center-sp">titlefont center sp</a></li> +<li><a href="#index-ss-725"><code>ss</code></a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-strong-443"><code>strong</code></a>: <a href="#emph-_0026-strong">emph & strong</a></li> +<li><a href="#index-subheading-288"><code>subheading</code></a>: <a href="#unnumberedsubsec-appendixsubsec-subheading">unnumberedsubsec appendixsubsec subheading</a></li> +<li><a href="#index-subsection-284"><code>subsection</code></a>: <a href="#subsection">subsection</a></li> +<li><a href="#index-subsubheading-293"><code>subsubheading</code></a>: <a href="#subsubsection">subsubsection</a></li> +<li><a href="#index-subsubsection-290"><code>subsubsection</code></a>: <a href="#subsubsection">subsubsection</a></li> +<li><a href="#index-subtitle-203"><code>subtitle</code></a>: <a href="#title-subtitle-author">title subtitle author</a></li> +<li><a href="#index-summarycontents-219"><code>summarycontents</code></a>: <a href="#Contents">Contents</a></li> +<li><a href="#index-syncodeindex-610"><code>syncodeindex</code></a>: <a href="#syncodeindex">syncodeindex</a></li> +<li><a href="#index-synindex-616"><code>synindex</code></a>: <a href="#synindex">synindex</a></li> +<li><a href="#index-t-_0040r_007b_0028typewriter-font_0029_007d-450"><code>t </code><span class="roman">(typewriter font)</span></a>: <a href="#Fonts">Fonts</a></li> +<li><a href="#index-tab-535"><code>tab</code></a>: <a href="#Multitable-Rows">Multitable Rows</a></li> +<li><a href="#index-table-514"><code>table</code></a>: <a href="#Two_002dcolumn-Tables">Two-column Tables</a></li> +<li><a href="#index-tex-896"><code>tex</code></a>: <a href="#Raw-Formatter-Commands">Raw Formatter Commands</a></li> +<li><a href="#index-TeX-742"><code>TeX</code></a>: <a href="#tex">tex</a></li> +<li><a href="#index-texinfo_002dall_002dmenus_002dupdate-136"><code>texinfo-all-menus-update</code></a>: <a href="#Updating-Commands">Updating Commands</a></li> +<li><a href="#index-texinfo_002devery_002dnode_002dupdate-135"><code>texinfo-every-node-update</code></a>: <a href="#Updating-Commands">Updating Commands</a></li> +<li><a href="#index-texinfo_002dformat_002dbuffer-1151"><code>texinfo-format-buffer</code></a>: <a href="#texinfo_002dformat-commands">texinfo-format commands</a></li> +<li><a href="#index-texinfo_002dformat_002dbuffer-147"><code>texinfo-format-buffer</code></a>: <a href="#Info-Formatting">Info Formatting</a></li> +<li><a href="#index-texinfo_002dformat_002dregion-1150"><code>texinfo-format-region</code></a>: <a href="#texinfo_002dformat-commands">texinfo-format commands</a></li> +<li><a href="#index-texinfo_002dformat_002dregion-146"><code>texinfo-format-region</code></a>: <a href="#Info-Formatting">Info Formatting</a></li> +<li><a href="#index-texinfo_002dindent_002dmenu_002ddescription-141"><code>texinfo-indent-menu-description</code></a>: <a href="#Other-Updating-Commands">Other Updating Commands</a></li> +<li><a href="#index-texinfo_002dinsert_002d_0040_0040code-101"><code>texinfo-insert-@code</code></a>: <a href="#Inserting">Inserting</a></li> +<li><a href="#index-texinfo_002dinsert_002d_0040_0040dfn-102"><code>texinfo-insert-@dfn</code></a>: <a href="#Inserting">Inserting</a></li> +<li><a href="#index-texinfo_002dinsert_002d_0040_0040end-103"><code>texinfo-insert-@end</code></a>: <a href="#Inserting">Inserting</a></li> +<li><a href="#index-texinfo_002dinsert_002d_0040_0040example-111"><code>texinfo-insert-@example</code></a>: <a href="#Inserting">Inserting</a></li> +<li><a href="#index-texinfo_002dinsert_002d_0040_0040item-104"><code>texinfo-insert-@item</code></a>: <a href="#Inserting">Inserting</a></li> +<li><a href="#index-texinfo_002dinsert_002d_0040_0040kbd-105"><code>texinfo-insert-@kbd</code></a>: <a href="#Inserting">Inserting</a></li> +<li><a href="#index-texinfo_002dinsert_002d_0040_0040node-106"><code>texinfo-insert-@node</code></a>: <a href="#Inserting">Inserting</a></li> +<li><a href="#index-texinfo_002dinsert_002d_0040_0040noindent-107"><code>texinfo-insert-@noindent</code></a>: <a href="#Inserting">Inserting</a></li> +<li><a href="#index-texinfo_002dinsert_002d_0040_0040samp-108"><code>texinfo-insert-@samp</code></a>: <a href="#Inserting">Inserting</a></li> +<li><a href="#index-texinfo_002dinsert_002d_0040_0040table-109"><code>texinfo-insert-@table</code></a>: <a href="#Inserting">Inserting</a></li> +<li><a href="#index-texinfo_002dinsert_002d_0040_0040var-110"><code>texinfo-insert-@var</code></a>: <a href="#Inserting">Inserting</a></li> +<li><a href="#index-texinfo_002dinsert_002dbraces-112"><code>texinfo-insert-braces</code></a>: <a href="#Inserting">Inserting</a></li> +<li><a href="#index-texinfo_002dinsert_002dnode_002dlines-139"><code>texinfo-insert-node-lines</code></a>: <a href="#Other-Updating-Commands">Other Updating Commands</a></li> +<li><a href="#index-texinfo_002dmake_002dmenu-134"><code>texinfo-make-menu</code></a>: <a href="#Updating-Commands">Updating Commands</a></li> +<li><a href="#index-texinfo_002dmaster_002dmenu-132"><code>texinfo-master-menu</code></a>: <a href="#Updating-Commands">Updating Commands</a></li> +<li><a href="#index-texinfo_002dmultiple_002dfiles_002dupdate-1262"><code>texinfo-multiple-files-update</code></a>: <a href="#texinfo_002dmultiple_002dfiles_002dupdate">texinfo-multiple-files-update</a></li> +<li><a href="#index-texinfo_002dmultiple_002dfiles_002dupdate-_0040r_007b_0028in-brief_0029_007d-140"><code>texinfo-multiple-files-update </code><span class="roman">(in brief)</span></a>: <a href="#Other-Updating-Commands">Other Updating Commands</a></li> +<li><a href="#index-texinfo_002dsequential_002dnode_002dupdate-142"><code>texinfo-sequential-node-update</code></a>: <a href="#Other-Updating-Commands">Other Updating Commands</a></li> +<li><a href="#index-texinfo_002dshow_002dstructure-124"><code>texinfo-show-structure</code></a>: <a href="#Showing-the-Structure">Showing the Structure</a></li> +<li><a href="#index-texinfo_002dshow_002dstructure-1297"><code>texinfo-show-structure</code></a>: <a href="#Using-texinfo_002dshow_002dstructure">Using texinfo-show-structure</a></li> +<li><a href="#index-texinfo_002dstart_002dmenu_002ddescription-114"><code>texinfo-start-menu-description</code></a>: <a href="#Inserting">Inserting</a></li> +<li><a href="#index-texinfo_002dtex_002dbuffer-153"><code>texinfo-tex-buffer</code></a>: <a href="#Printing">Printing</a></li> +<li><a href="#index-texinfo_002dtex_002dprint-155"><code>texinfo-tex-print</code></a>: <a href="#Printing">Printing</a></li> +<li><a href="#index-texinfo_002dtex_002dregion-154"><code>texinfo-tex-region</code></a>: <a href="#Printing">Printing</a></li> +<li><a href="#index-texinfo_002dupdate_002dnode-133"><code>texinfo-update-node</code></a>: <a href="#Updating-Commands">Updating Commands</a></li> +<li><a href="#index-thischapter-1281"><code>thischapter</code></a>: <a href="#Custom-Headings">Custom Headings</a></li> +<li><a href="#index-thischaptername-1280"><code>thischaptername</code></a>: <a href="#Custom-Headings">Custom Headings</a></li> +<li><a href="#index-thisfile-1283"><code>thisfile</code></a>: <a href="#Custom-Headings">Custom Headings</a></li> +<li><a href="#index-thispage-1279"><code>thispage</code></a>: <a href="#Custom-Headings">Custom Headings</a></li> +<li><a href="#index-thistitle-1282"><code>thistitle</code></a>: <a href="#Custom-Headings">Custom Headings</a></li> +<li><a href="#index-tie-_0040r_007b_0028unbreakable-interword-space_0029_007d-798"><code>tie </code><span class="roman">(unbreakable interword space)</span></a>: <a href="#tie">tie</a></li> +<li><a href="#index-tieaccent-677"><code>tieaccent</code></a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-title-202"><code>title</code></a>: <a href="#title-subtitle-author">title subtitle author</a></li> +<li><a href="#index-titlefont-199"><code>titlefont</code></a>: <a href="#titlefont-center-sp">titlefont center sp</a></li> +<li><a href="#index-titlepage-194"><code>titlepage</code></a>: <a href="#titlepage">titlepage</a></li> +<li><a href="#index-today-1284"><code>today</code></a>: <a href="#Custom-Headings">Custom Headings</a></li> +<li><a href="#index-top-227"><code>top</code></a>: <a href="#The-Top-Node">The Top Node</a></li> +<li><a href="#index-top-_0040r_007b_0028_0040_0040_002dcommand_0029_007d-328"><code>top </code><span class="roman">(@-command)</span></a>: <a href="#makeinfo-top-command">makeinfo top command</a></li> +<li><a href="#index-u-_0040r_007b_0028breve-accent_0029_007d-679"><code>u </code><span class="roman">(breve accent)</span></a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-ubaraccent-681"><code>ubaraccent</code></a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-udotaccent-683"><code>udotaccent</code></a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-unmacro-949"><code>unmacro</code></a>: <a href="#Defining-Macros">Defining Macros</a></li> +<li><a href="#index-unnumbered-275"><code>unnumbered</code></a>: <a href="#unnumbered-_0026-appendix">unnumbered & appendix</a></li> +<li><a href="#index-unnumberedsec-280"><code>unnumberedsec</code></a>: <a href="#unnumberedsec-appendixsec-heading">unnumberedsec appendixsec heading</a></li> +<li><a href="#index-unnumberedsubsec-286"><code>unnumberedsubsec</code></a>: <a href="#unnumberedsubsec-appendixsubsec-subheading">unnumberedsubsec appendixsubsec subheading</a></li> +<li><a href="#index-unnumberedsubsubsec-291"><code>unnumberedsubsubsec</code></a>: <a href="#subsubsection">subsubsection</a></li> +<li><a href="#index-up_002dlist-113"><code>up-list</code></a>: <a href="#Inserting">Inserting</a></li> +<li><a href="#index-uref-383"><code>uref</code></a>: <a href="#uref">uref</a></li> +<li><a href="#index-v-_0040r_007b_0028check-accent_0029_007d-685"><code>v </code><span class="roman">(check accent)</span></a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-value-905"><code>value</code></a>: <a href="#set-value">set value</a></li> +<li><a href="#index-var-420"><code>var</code></a>: <a href="#var">var</a></li> +<li><a href="#index-verb-417"><code>verb</code></a>: <a href="#verb">verb</a></li> +<li><a href="#index-verbatim-467"><code>verbatim</code></a>: <a href="#verbatim">verbatim</a></li> +<li><a href="#index-verbatiminclude-471"><code>verbatiminclude</code></a>: <a href="#verbatiminclude">verbatiminclude</a></li> +<li><a href="#index-vskip-_0040r_007b_0040TeX_007b_007d-vertical-skip_007d-208"><code>vskip </code><span class="roman">TeX vertical skip</span></a>: <a href="#Copyright">Copyright</a></li> +<li><a href="#index-vtable-521"><code>vtable</code></a>: <a href="#ftable-vtable">ftable vtable</a></li> +<li><a href="#index-w-_0040r_007b_0028prevent-line-break_0029_007d-790"><code>w </code><span class="roman">(prevent line break)</span></a>: <a href="#w">w</a></li> +<li><a href="#index-xml-902"><code>xml</code></a>: <a href="#Raw-Formatter-Commands">Raw Formatter Commands</a></li> +<li><a href="#index-xref-366"><code>xref</code></a>: <a href="#xref">xref</a></li> +<li><a href="#index-_0040_007b-_0040r_007b_0028literal-_0040samp_007b_0040_007b_007d_0029_007d-629"><code>{ </code><span class="roman">(literal {)</span></a>: <a href="#Inserting-Braces">Inserting Braces</a></li> +<li><a href="#index-_0040_007d-_0040r_007b_0028literal-_0040samp_007b_0040_007d_007d_0029_007d-630"><code>} </code><span class="roman">(literal })</span></a>: <a href="#Inserting-Braces">Inserting Braces</a></li> +<li><a href="#index-_007e-_0040r_007b_0028tilde-accent_0029_007d-667"><code>~ </code><span class="roman">(tilde accent)</span></a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +</ul><div class="node"> +<p><hr> +<a name="Concept-Index"></a>Previous: <a rel="previous" accesskey="p" href="#Command-and-Variable-Index">Command and Variable Index</a>, +Up: <a rel="up" accesskey="u" href="#Top">Top</a> +<br> +</div> + +<h2 class="unnumbered">Concept Index</h2> + + + +<ul class="index-cp" compact> +<li><a href="#index-_0040exclamdown_007b_007d-692">¡</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-_0024Id-1245">$Id</a>: <a href="#GNU-Sample-Texts">GNU Sample Texts</a></li> +<li><a href="#index-_0024Id-expansion_002c-preventing-797">$Id expansion, preventing</a>: <a href="#w">w</a></li> +<li><a href="#index-_0028dir_0029-as-Up-node-of-Top-node-325">(dir) as Up node of Top node</a>: <a href="#First-Node">First Node</a></li> +<li><a href="#index-_002d_002dcommands_002din_002dnode_002dnames-1075"><code>--commands-in-node-names</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> +<li><a href="#index-_002d_002dcss_002dinclude-1076"><code>--css-include</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> +<li><a href="#index-_002d_002ddelete-1185"><code>--delete</code></a>: <a href="#Invoking-install_002dinfo">Invoking install-info</a></li> +<li><a href="#index-_002d_002ddir_002dfile_003d_0040var_007bname_007d-1186"><code>--dir-file=</code><var>name</var></a>: <a href="#Invoking-install_002dinfo">Invoking install-info</a></li> +<li><a href="#index-_002d_002ddocbook-1077"><code>--docbook</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> +<li><a href="#index-_002d_002denable_002dencoding-1078"><code>--enable-encoding</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> +<li><a href="#index-_002d_002denable_002dencoding-924"><code>--enable-encoding</code></a>: <a href="#documentencoding">documentencoding</a></li> +<li><a href="#index-_002d_002dentry_003d_0040var_007btext_007d-1188"><code>--entry=</code><var>text</var></a>: <a href="#Invoking-install_002dinfo">Invoking install-info</a></li> +<li><a href="#index-_002d_002derror_002dlimit_003d_0040var_007blimit_007d-1079"><code>--error-limit=</code><var>limit</var></a>: <a href="#makeinfo-options">makeinfo options</a></li> +<li><a href="#index-_002d_002dfill_002dcolumn_003d_0040var_007bwidth_007d-1081"><code>--fill-column=</code><var>width</var></a>: <a href="#makeinfo-options">makeinfo options</a></li> +<li><a href="#index-_002d_002dfootnote_002dstyle_0040r_007b_002c-ignored-in-HTML-output_007d-1206"><code>--footnote-style</code><span class="roman">, ignored in HTML output</span></a>: <a href="#HTML-Translation">HTML Translation</a></li> +<li><a href="#index-_002d_002dfootnote_002dstyle_003d_0040var_007bstyle_007d-1083"><code>--footnote-style=</code><var>style</var></a>: <a href="#makeinfo-options">makeinfo options</a></li> +<li><a href="#index-_002d_002dforce-1085"><code>--force</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> +<li><a href="#index-_002d_002dhelp-1087"><code>--help</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> +<li><a href="#index-_002d_002dhelp-1190"><code>--help</code></a>: <a href="#Invoking-install_002dinfo">Invoking install-info</a></li> +<li><a href="#index-_002d_002dhtml-1089"><code>--html</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> +<li><a href="#index-_002d_002difdocbook-1091"><code>--ifdocbook</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> +<li><a href="#index-_002d_002difhtml-1092"><code>--ifhtml</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> +<li><a href="#index-_002d_002difinfo-1093"><code>--ifinfo</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> +<li><a href="#index-_002d_002difplaintext-1094"><code>--ifplaintext</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> +<li><a href="#index-_002d_002diftex-1095"><code>--iftex</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> +<li><a href="#index-_002d_002difxml-1096"><code>--ifxml</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> +<li><a href="#index-_002d_002dinfo_002ddir_003d_0040var_007bdir_007d-1194"><code>--info-dir=</code><var>dir</var></a>: <a href="#Invoking-install_002dinfo">Invoking install-info</a></li> +<li><a href="#index-_002d_002dinfo_002dfile_003d_0040var_007bfile_007d-1192"><code>--info-file=</code><var>file</var></a>: <a href="#Invoking-install_002dinfo">Invoking install-info</a></li> +<li><a href="#index-_002d_002ditem_003d_0040var_007btext_007d-1196"><code>--item=</code><var>text</var></a>: <a href="#Invoking-install_002dinfo">Invoking install-info</a></li> +<li><a href="#index-_002d_002dmacro_002dexpand_003d_0040var_007bfile_007d-1097"><code>--macro-expand=</code><var>file</var></a>: <a href="#makeinfo-options">makeinfo options</a></li> +<li><a href="#index-_002d_002dno_002dheaders-1099"><code>--no-headers</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> +<li><a href="#index-_002d_002dno_002difdocbook-1107"><code>--no-ifdocbook</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> +<li><a href="#index-_002d_002dno_002difhtml-1108"><code>--no-ifhtml</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> +<li><a href="#index-_002d_002dno_002difinfo-1109"><code>--no-ifinfo</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> +<li><a href="#index-_002d_002dno_002difplaintext-1110"><code>--no-ifplaintext</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> +<li><a href="#index-_002d_002dno_002diftex-1111"><code>--no-iftex</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> +<li><a href="#index-_002d_002dno_002difxml-1112"><code>--no-ifxml</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> +<li><a href="#index-_002d_002dno_002dnumber_002dfootnotes-1121"><code>--no-number-footnotes</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> +<li><a href="#index-_002d_002dno_002dpointer_002dvalidate-1116"><code>--no-pointer-validate</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> +<li><a href="#index-_002d_002dno_002dsplit-1113"><code>--no-split</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> +<li><a href="#index-_002d_002dno_002dvalidate-1117"><code>--no-validate</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> +<li><a href="#index-_002d_002dno_002dwarn-1119"><code>--no-warn</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> +<li><a href="#index-_002d_002dnumber_002dsections-1120"><code>--number-sections</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> +<li><a href="#index-_002d_002doutput_003d_0040var_007bfile_007d-1122"><code>--output=</code><var>file</var></a>: <a href="#makeinfo-options">makeinfo options</a></li> +<li><a href="#index-_002d_002dparagraph_002dindent_003d_0040var_007bindent_007d-1125"><code>--paragraph-indent=</code><var>indent</var></a>: <a href="#makeinfo-options">makeinfo options</a></li> +<li><a href="#index-_002d_002dquiet-1197"><code>--quiet</code></a>: <a href="#Invoking-install_002dinfo">Invoking install-info</a></li> +<li><a href="#index-_002d_002dreference_002dlimit_003d_0040var_007blimit_007d-1127"><code>--reference-limit=</code><var>limit</var></a>: <a href="#makeinfo-options">makeinfo options</a></li> +<li><a href="#index-_002d_002dremove-1198"><code>--remove</code></a>: <a href="#Invoking-install_002dinfo">Invoking install-info</a></li> +<li><a href="#index-_002d_002dsection_003d_0040var_007bsec_007d-1200"><code>--section=</code><var>sec</var></a>: <a href="#Invoking-install_002dinfo">Invoking install-info</a></li> +<li><a href="#index-_002d_002dsplit_002dsize_003d_0040var_007bnum_007d-1129"><code>--split-size=</code><var>num</var></a>: <a href="#makeinfo-options">makeinfo options</a></li> +<li><a href="#index-_002d_002dverbose-1130"><code>--verbose</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> +<li><a href="#index-_002d_002dversion-1131"><code>--version</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> +<li><a href="#index-_002d_002dversion-1202"><code>--version</code></a>: <a href="#Invoking-install_002dinfo">Invoking install-info</a></li> +<li><a href="#index-_002d_002dxml-1133"><code>--xml</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> +<li><a href="#index-_002dD-_0040var_007bdir_007d-1195"><code>-D </code><var>dir</var></a>: <a href="#Invoking-install_002dinfo">Invoking install-info</a></li> +<li><a href="#index-_002dd-_0040var_007bname_007d-1187"><code>-d </code><var>name</var></a>: <a href="#Invoking-install_002dinfo">Invoking install-info</a></li> +<li><a href="#index-_002dD-_0040var_007bvar_007d-1074"><code>-D </code><var>var</var></a>: <a href="#makeinfo-options">makeinfo options</a></li> +<li><a href="#index-_002dE-_0040var_007bfile_007d-1098"><code>-E </code><var>file</var></a>: <a href="#makeinfo-options">makeinfo options</a></li> +<li><a href="#index-_002de-_0040var_007blimit_007d-1080"><code>-e </code><var>limit</var></a>: <a href="#makeinfo-options">makeinfo options</a></li> +<li><a href="#index-_002de-_0040var_007btext_007d-1189"><code>-e </code><var>text</var></a>: <a href="#Invoking-install_002dinfo">Invoking install-info</a></li> +<li><a href="#index-_002dF-1086"><code>-F</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> +<li><a href="#index-_002df-_0040var_007bwidth_007d-1082"><code>-f </code><var>width</var></a>: <a href="#makeinfo-options">makeinfo options</a></li> +<li><a href="#index-_002dh-1088"><code>-h</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> +<li><a href="#index-_002dh-1191"><code>-h</code></a>: <a href="#Invoking-install_002dinfo">Invoking install-info</a></li> +<li><a href="#index-_002dI-_0040var_007bdir_007d-1090"><code>-I </code><var>dir</var></a>: <a href="#makeinfo-options">makeinfo options</a></li> +<li><a href="#index-_002di-_0040var_007bfile_007d-1193"><code>-i </code><var>file</var></a>: <a href="#Invoking-install_002dinfo">Invoking install-info</a></li> +<li><a href="#index-_002do-_0040var_007bfile_007d-1123"><code>-o </code><var>file</var></a>: <a href="#makeinfo-options">makeinfo options</a></li> +<li><a href="#index-_002dP-_0040var_007bdir_007d-1124"><code>-P </code><var>dir</var></a>: <a href="#makeinfo-options">makeinfo options</a></li> +<li><a href="#index-_002dp-_0040var_007bindent_007d-1126"><code>-p </code><var>indent</var></a>: <a href="#makeinfo-options">makeinfo options</a></li> +<li><a href="#index-_002dr-1199"><code>-r</code></a>: <a href="#Invoking-install_002dinfo">Invoking install-info</a></li> +<li><a href="#index-_002dr-_0040var_007blimit_007d-1128"><code>-r </code><var>limit</var></a>: <a href="#makeinfo-options">makeinfo options</a></li> +<li><a href="#index-_002ds-_0040var_007bsec_007d-1201"><code>-s </code><var>sec</var></a>: <a href="#Invoking-install_002dinfo">Invoking install-info</a></li> +<li><a href="#index-_002ds-_0040var_007bstyle_007d-1084"><code>-s </code><var>style</var></a>: <a href="#makeinfo-options">makeinfo options</a></li> +<li><a href="#index-_002dV-1132"><code>-V</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> +<li><a href="#index-_002dV-1203"><code>-V</code></a>: <a href="#Invoking-install_002dinfo">Invoking install-info</a></li> +<li><a href="#index-_0040b_007b_002ecshrc_007d-initialization-file-1014"><b>.cshrc</b> initialization file</a>: <a href="#Preparing-for-TeX">Preparing for TeX</a></li> +<li><a href="#index-_0040b_007b_002eprofile_007d-initialization-file-1013"><b>.profile</b> initialization file</a>: <a href="#Preparing-for-TeX">Preparing for TeX</a></li> +<li><a href="#index-_0040L_007b_007d-708">/L</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-_0040l_007b_007d-706">/l</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-_0040o_007b_007d-710">ø</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-_0040O_007b_007d-712">Ø</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-8_002dbit-characters_002c-in-HTML-cross_002dreferences-1225">8-bit characters, in HTML cross-references</a>: <a href="#HTML-Xref-8_002dbit-Character-Expansion">HTML Xref 8-bit Character Expansion</a></li> +<li><a href="#index-_003cacronym_003e-tag-434"><acronym> tag</a>: <a href="#acronym">acronym</a></li> +<li><a href="#index-_003cblockquote_003e-HTML-tag-463"><blockquote> HTML tag</a>: <a href="#quotation">quotation</a></li> +<li><a href="#index-_003clineannotation_003e-Docbook-tag-458"><lineannotation> Docbook tag</a>: <a href="#Fonts">Fonts</a></li> +<li><a href="#index-_0040code_007b_003cmeta_003e_007d-HTML-tag_002c-and-charset-specification-929"><code><meta></code> HTML tag, and charset specification</a>: <a href="#documentencoding">documentencoding</a></li> +<li><a href="#index-_003cmeta_003e-HTML-tag_002c-and-document-description-237"><meta> HTML tag, and document description</a>: <a href="#documentdescription">documentdescription</a></li> +<li><a href="#index-_003cnote_003e-Docbook-tag-462"><note> Docbook tag</a>: <a href="#quotation">quotation</a></li> +<li><a href="#index-_003csmall_003e-tag-446"><small> tag</a>: <a href="#Smallcaps">Smallcaps</a></li> +<li><a href="#index-_003cthead_003e-HTML-tag-538"><thead> HTML tag</a>: <a href="#Multitable-Rows">Multitable Rows</a></li> +<li><a href="#index-_003ctitle_003e-HTML-tag-176"><title> HTML tag</a>: <a href="#settitle">settitle</a></li> +<li><a href="#index-_003cURL_003a-convention_002c-not-used-388"><URL: convention, not used</a>: <a href="#uref">uref</a></li> +<li><a href="#index-_0040questiondown_007b_007d-690">¿</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-_0040samp_007b_0040_0040_007d-as-continuation-in-definition-commands-821"><span class="samp">@</span> as continuation in definition commands</a>: <a href="#Def-Cmd-Continuation-Lines">Def Cmd Continuation Lines</a></li> +<li><a href="#index-_0040_0040_002dcommand-list-1231">@-command list</a>: <a href="#Command-List">Command List</a></li> +<li><a href="#index-_0040_0040_002dcommand-syntax-1233">@-command syntax</a>: <a href="#Command-Syntax">Command Syntax</a></li> +<li><a href="#index-_0040_0040_002dcommands-46">@-commands</a>: <a href="#Formatting-Commands">Formatting Commands</a></li> +<li><a href="#index-_0040_0040_002dcommands-in-_0040_0040node_002c-limited-support-1138">@-commands in @node, limited support</a>: <a href="#Pointer-Validation">Pointer Validation</a></li> +<li><a href="#index-_0040_0040_002dcommands-in-nodename-310">@-commands in nodename</a>: <a href="#Node-Line-Requirements">Node Line Requirements</a></li> +<li><a href="#index-_0040_0040import-specifications_002c-in-CSS-files-1214">@import specifications, in CSS files</a>: <a href="#HTML-CSS">HTML CSS</a></li> +<li><a href="#index-_0040code_007b_0040_0040include_007d-file-sample-1267"><code>@include</code> file sample</a>: <a href="#Sample-Include-File">Sample Include File</a></li> +<li><a href="#index-_0040code_007b_0040_0040menu_007d-parts-347"><code>@menu</code> parts</a>: <a href="#Menu-Parts">Menu Parts</a></li> +<li><a href="#index-_0040code_007b_0040_0040node_007d-line-writing-304"><code>@node</code> line writing</a>: <a href="#Writing-a-Node">Writing a Node</a></li> +<li><a href="#index-_0040_0040value-in-_0040_0040node-lines-1139">@value in @node lines</a>: <a href="#Pointer-Validation">Pointer Validation</a></li> +<li><a href="#index-_0040code_007b_0040_0040w_007d_002c-for-blank-items-509"><code>@w</code>, for blank items</a>: <a href="#itemize">itemize</a></li> +<li><a href="#index-_0040samp_007b_005cinput_007d-source-line-ignored-170"><span class="samp">\input</span> source line ignored</a>: <a href="#setfilename">setfilename</a></li> +<li><a href="#index-_0040ordf_007b_007d-721">ª</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-A4-paper_002c-printing-on-1041">A4 paper, printing on</a>: <a href="#A4-Paper">A4 Paper</a></li> +<li><a href="#index-A5-paper_002c-printing-on-1042">A5 paper, printing on</a>: <a href="#A4-Paper">A4 Paper</a></li> +<li><a href="#index-_0040AA_007b_007d-696">Å</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-_0040aa_007b_007d-694">å</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-Abbreviations-for-keys-414">Abbreviations for keys</a>: <a href="#key">key</a></li> +<li><a href="#index-Abbreviations_002c-tagging-432">Abbreviations, tagging</a>: <a href="#acronym">acronym</a></li> +<li><a href="#index-Abstract-of-document-236">Abstract of document</a>: <a href="#documentdescription">documentdescription</a></li> +<li><a href="#index-Accents_002c-inserting-655">Accents, inserting</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-Acronyms_002c-tagging-433">Acronyms, tagging</a>: <a href="#acronym">acronym</a></li> +<li><a href="#index-Acute-accent-660">Acute accent</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-Adding-a-new-Info-file-1160">Adding a new Info file</a>: <a href="#New-Info-File">New Info File</a></li> +<li><a href="#index-_0040ae_007b_007d-698">æ</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-_0040AE_007b_007d-700">Æ</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-Aliases_002c-command-961">Aliases, command</a>: <a href="#alias">alias</a></li> +<li><a href="#index-All_002dpermissive-copying-license-1258">All-permissive copying license</a>: <a href="#All_002dpermissive-Copying-License">All-permissive Copying License</a></li> +<li><a href="#index-Allow-line-break-785">Allow line break</a>: <a href="#Line-Breaks">Line Breaks</a></li> +<li><a href="#index-Alphabetical-_0040_0040_002dcommand-list-1229">Alphabetical @-command list</a>: <a href="#Command-List">Command List</a></li> +<li><a href="#index-Alt-attribute-for-images-563">Alt attribute for images</a>: <a href="#Image-Syntax">Image Syntax</a></li> +<li><a href="#index-Anchors-333">Anchors</a>: <a href="#anchor">anchor</a></li> +<li><a href="#index-Another-Info-directory-1167">Another Info directory</a>: <a href="#Other-Info-Directories">Other Info Directories</a></li> +<li><a href="#index-Arguments_002c-repeated-and-optional-827">Arguments, repeated and optional</a>: <a href="#Optional-Arguments">Optional Arguments</a></li> +<li><a href="#index-ASCII-text-output-1101">ASCII text output</a>: <a href="#makeinfo-options">makeinfo options</a></li> +<li><a href="#index-Aspect-ratio-of-images-572">Aspect ratio of images</a>: <a href="#Image-Scaling">Image Scaling</a></li> +<li><a href="#index-autoexec_002ebat-1172"><code>autoexec.bat</code></a>: <a href="#Other-Info-Directories">Other Info Directories</a></li> +<li><a href="#index-automake_0040r_007b_002c-and-version-info_007d-1250"><code>automake</code><span class="roman">, and version info</span></a>: <a href="#GNU-Sample-Texts">GNU Sample Texts</a></li> +<li><a href="#index-Automatic-pointer-creation-with-_0040code_007bmakeinfo_007d-331">Automatic pointer creation with <code>makeinfo</code></a>: <a href="#makeinfo-Pointer-Creation">makeinfo Pointer Creation</a></li> +<li><a href="#index-Automatically-insert-nodes_002c-menus-131">Automatically insert nodes, menus</a>: <a href="#Updating-Nodes-and-Menus">Updating Nodes and Menus</a></li> +<li><a href="#index-Auxiliary-files_002c-avoiding-986">Auxiliary files, avoiding</a>: <a href="#Format-with-tex_002ftexindex">Format with tex/texindex</a></li> +<li><a href="#index-B5-paper_002c-printing-on-1055">B5 paper, printing on</a>: <a href="#pagesizes">pagesizes</a></li> +<li><a href="#index-Back_002dend-output-formats-15">Back-end output formats</a>: <a href="#Output-Formats">Output Formats</a></li> +<li><a href="#index-Backslash-in-macros-944">Backslash in macros</a>: <a href="#Defining-Macros">Defining Macros</a></li> +<li><a href="#index-Backslash_002c-and-macros-956">Backslash, and macros</a>: <a href="#Invoking-Macros">Invoking Macros</a></li> +<li><a href="#index-Badly-referenced-nodes-1305">Badly referenced nodes</a>: <a href="#Running-Info_002dValidate">Running Info-Validate</a></li> +<li><a href="#index-Bastard-title-page-197">Bastard title page</a>: <a href="#titlepage">titlepage</a></li> +<li><a href="#index-Batch-formatting-for-Info-1152">Batch formatting for Info</a>: <a href="#Batch-Formatting">Batch Formatting</a></li> +<li><a href="#index-Beebe_002c-Nelson-27">Beebe, Nelson</a>: <a href="#Output-Formats">Output Formats</a></li> +<li><a href="#index-Beginning-a-Texinfo-file-156">Beginning a Texinfo file</a>: <a href="#Beginning-a-File">Beginning a File</a></li> +<li><a href="#index-Beginning-line-of-a-Texinfo-file-164">Beginning line of a Texinfo file</a>: <a href="#First-Line">First Line</a></li> +<li><a href="#index-Berry_002c-Karl-81">Berry, Karl</a>: <a href="#History">History</a></li> +<li><a href="#index-Big-points-577">Big points</a>: <a href="#Image-Scaling">Image Scaling</a></li> +<li><a href="#index-Black-rectangle-in-hardcopy-1031">Black rectangle in hardcopy</a>: <a href="#Overfull-hboxes">Overfull hboxes</a></li> +<li><a href="#index-Blank-lines-804">Blank lines</a>: <a href="#sp">sp</a></li> +<li><a href="#index-Blank-lines_002c-as-paragraph-separator-55">Blank lines, as paragraph separator</a>: <a href="#Conventions">Conventions</a></li> +<li><a href="#index-Body-of-a-macro-940">Body of a macro</a>: <a href="#Defining-Macros">Defining Macros</a></li> +<li><a href="#index-Bold-font-453">Bold font</a>: <a href="#Fonts">Fonts</a></li> +<li><a href="#index-Bolio-92">Bolio</a>: <a href="#History">History</a></li> +<li><a href="#index-Book-characteristics_002c-printed-42">Book characteristics, printed</a>: <a href="#Printed-Books">Printed Books</a></li> +<li><a href="#index-Book_002c-printing-small-1038">Book, printing small</a>: <a href="#smallbook">smallbook</a></li> +<li><a href="#index-border_002dpattern-853"><code>border-pattern</code></a>: <a href="#Object_002dOriented-Variables">Object-Oriented Variables</a></li> +<li><a href="#index-border_002dpattern-of-Window-859"><code>border-pattern of Window</code></a>: <a href="#Object_002dOriented-Variables">Object-Oriented Variables</a></li> +<li><a href="#index-Bo_0040TeX_007b_007d-93">BoTeX</a>: <a href="#History">History</a></li> +<li><a href="#index-Box-with-rounded-corners-501">Box with rounded corners</a>: <a href="#cartouche">cartouche</a></li> +<li><a href="#index-Box_002c-ugly-black-in-hardcopy-1033">Box, ugly black in hardcopy</a>: <a href="#Overfull-hboxes">Overfull hboxes</a></li> +<li><a href="#index-Braces-and-argument-syntax-1236">Braces and argument syntax</a>: <a href="#Command-Syntax">Command Syntax</a></li> +<li><a href="#index-Braces_002c-in-macro-arguments-958">Braces, in macro arguments</a>: <a href="#Invoking-Macros">Invoking Macros</a></li> +<li><a href="#index-Braces_002c-inserting-628">Braces, inserting</a>: <a href="#Inserting-Braces">Inserting Braces</a></li> +<li><a href="#index-Braces_002c-when-to-use-48">Braces, when to use</a>: <a href="#Formatting-Commands">Formatting Commands</a></li> +<li><a href="#index-Breaks-in-a-line-783">Breaks in a line</a>: <a href="#Line-Breaks">Line Breaks</a></li> +<li><a href="#index-Breve-accent-680">Breve accent</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-Buffer-formatting-and-printing-151">Buffer formatting and printing</a>: <a href="#Printing">Printing</a></li> +<li><a href="#index-Bugs_002c-reporting-5">Bugs, reporting</a>: <a href="#Reporting-Bugs">Reporting Bugs</a></li> +<li><a href="#index-Bullets_002c-inserting-731">Bullets, inserting</a>: <a href="#Dots-Bullets">Dots Bullets</a></li> +<li><a href="#index-Captions_002c-for-floats-550">Captions, for floats</a>: <a href="#caption-shortcaption">caption shortcaption</a></li> +<li><a href="#index-Caron-accent-688">Caron accent</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-Cascading-Style-Sheets_002c-and-HTML-output-1213">Cascading Style Sheets, and HTML output</a>: <a href="#HTML-CSS">HTML CSS</a></li> +<li><a href="#index-Case-in-node-name-319">Case in node name</a>: <a href="#Node-Line-Requirements">Node Line Requirements</a></li> +<li><a href="#index-Case_002c-not-altering-in-_0040code_007b_0040_0040code_007d-401">Case, not altering in <code>@code</code></a>: <a href="#code">code</a></li> +<li><a href="#index-Catching-errors-with-Info-formatting-1292">Catching errors with Info formatting</a>: <a href="#Debugging-with-Info">Debugging with Info</a></li> +<li><a href="#index-Catching-errors-with-_0040TeX_007b_007d-formatting-1294">Catching errors with TeX formatting</a>: <a href="#Debugging-with-TeX">Debugging with TeX</a></li> +<li><a href="#index-Catching-mistakes-1287">Catching mistakes</a>: <a href="#Catching-Mistakes">Catching Mistakes</a></li> +<li><a href="#index-Categories_002c-choosing-1179">Categories, choosing</a>: <a href="#Installing-Dir-Entries">Installing Dir Entries</a></li> +<li><a href="#index-Cedilla-accent-670">Cedilla accent</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-Centimeters-579">Centimeters</a>: <a href="#Image-Scaling">Image Scaling</a></li> +<li><a href="#index-Chapter-structuring-270">Chapter structuring</a>: <a href="#Structuring">Structuring</a></li> +<li><a href="#index-Chapters_002c-formatting-one-at-a-time-989">Chapters, formatting one at a time</a>: <a href="#Format-with-tex_002ftexindex">Format with tex/texindex</a></li> +<li><a href="#index-Character-set_002c-declaring-922">Character set, declaring</a>: <a href="#documentencoding">documentencoding</a></li> +<li><a href="#index-Characteristics_002c-printed-books-or-manuals-44">Characteristics, printed books or manuals</a>: <a href="#Printed-Books">Printed Books</a></li> +<li><a href="#index-Characters_002c-basic-input-52">Characters, basic input</a>: <a href="#Conventions">Conventions</a></li> +<li><a href="#index-Characters_002c-invalid-in-node-name-316">Characters, invalid in node name</a>: <a href="#Node-Line-Requirements">Node Line Requirements</a></li> +<li><a href="#index-Chassell_002c-Robert-J_002e-79">Chassell, Robert J.</a>: <a href="#History">History</a></li> +<li><a href="#index-Check-accent-687">Check accent</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-Checking-for-badly-referenced-nodes-1302">Checking for badly referenced nodes</a>: <a href="#Running-Info_002dValidate">Running Info-Validate</a></li> +<li><a href="#index-Checklist-for-bug-reports-8">Checklist for bug reports</a>: <a href="#Reporting-Bugs">Reporting Bugs</a></li> +<li><a href="#index-Ciceros-582">Ciceros</a>: <a href="#Image-Scaling">Image Scaling</a></li> +<li><a href="#index-Circumflex-accent-664">Circumflex accent</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-code_0040r_007b_002c-value-for-_0040code_007b_0040_0040kbdinputstyle_007d_007d-409"><code>code</code><span class="roman">, value for </span><code>@kbdinputstyle</code></a>: <a href="#kbd">kbd</a></li> +<li><a href="#index-Collapsing-whitespace-around-continuations-824">Collapsing whitespace around continuations</a>: <a href="#Def-Cmd-Continuation-Lines">Def Cmd Continuation Lines</a></li> +<li><a href="#index-Colon-in-nodename-312">Colon in nodename</a>: <a href="#Node-Line-Requirements">Node Line Requirements</a></li> +<li><a href="#index-Colon_002c-last-in-_0040env_007bINFOPATH_007d-1173">Colon, last in <span class="env">INFOPATH</span></a>: <a href="#Other-Info-Directories">Other Info Directories</a></li> +<li><a href="#index-Column-widths_002c-defining-for-multitables-527">Column widths, defining for multitables</a>: <a href="#Multitable-Column-Widths">Multitable Column Widths</a></li> +<li><a href="#index-Combining-indices-608">Combining indices</a>: <a href="#Combining-Indices">Combining Indices</a></li> +<li><a href="#index-Comma-in-nodename-313">Comma in nodename</a>: <a href="#Node-Line-Requirements">Node Line Requirements</a></li> +<li><a href="#index-Comma_002c-in-macro-arguments-957">Comma, in macro arguments</a>: <a href="#Invoking-Macros">Invoking Macros</a></li> +<li><a href="#index-Command-aliases-962">Command aliases</a>: <a href="#alias">alias</a></li> +<li><a href="#index-Command-definitions-868">Command definitions</a>: <a href="#Sample-Function-Definition">Sample Function Definition</a></li> +<li><a href="#index-Command-names_002c-indicating-424">Command names, indicating</a>: <a href="#command">command</a></li> +<li><a href="#index-Command-syntax-1235">Command syntax</a>: <a href="#Command-Syntax">Command Syntax</a></li> +<li><a href="#index-Commands-to-insert-special-characters-625">Commands to insert special characters</a>: <a href="#Atsign-Braces-Comma">Atsign Braces Comma</a></li> +<li><a href="#index-Commands-using-raw-_0040TeX_007b_007d-891">Commands using raw TeX</a>: <a href="#Raw-Formatter-Commands">Raw Formatter Commands</a></li> +<li><a href="#index-Commands_002c-inserting-them-100">Commands, inserting them</a>: <a href="#Inserting">Inserting</a></li> +<li><a href="#index-Commas_002c-inserting-631">Commas, inserting</a>: <a href="#Inserting-a-Comma">Inserting a Comma</a></li> +<li><a href="#index-Comments-66">Comments</a>: <a href="#Comments">Comments</a></li> +<li><a href="#index-Comments_002c-in-CSS-files-1215">Comments, in CSS files</a>: <a href="#HTML-CSS">HTML CSS</a></li> +<li><a href="#index-Compile-command-for-formatting-1006">Compile command for formatting</a>: <a href="#Compile_002dCommand">Compile-Command</a></li> +<li><a href="#index-Compressed-files_002c-reading-1183">Compressed files, reading</a>: <a href="#Invoking-install_002dinfo">Invoking install-info</a></li> +<li><a href="#index-Conditionally-visible-text-872">Conditionally visible text</a>: <a href="#Conditionals">Conditionals</a></li> +<li><a href="#index-Conditionals_002c-nested-909">Conditionals, nested</a>: <a href="#Conditional-Nesting">Conditional Nesting</a></li> +<li><a href="#index-Conditions-for-copying-Texinfo-2">Conditions for copying Texinfo</a>: <a href="#Copying-Conditions">Copying Conditions</a></li> +<li><a href="#index-Contents_002c-after-title-page-223">Contents, after title page</a>: <a href="#Contents">Contents</a></li> +<li><a href="#index-Contents_002c-Table-of-216">Contents, Table of</a>: <a href="#Contents">Contents</a></li> +<li><a href="#index-Contents_002dlike-outline-of-file-structure-121">Contents-like outline of file structure</a>: <a href="#Showing-the-Structure">Showing the Structure</a></li> +<li><a href="#index-Continuation-lines-in-definition-commands-819">Continuation lines in definition commands</a>: <a href="#Def-Cmd-Continuation-Lines">Def Cmd Continuation Lines</a></li> +<li><a href="#index-Conventions-for-writing-definitions-866">Conventions for writing definitions</a>: <a href="#Def-Cmd-Conventions">Def Cmd Conventions</a></li> +<li><a href="#index-Conventions_002c-syntactic-51">Conventions, syntactic</a>: <a href="#Conventions">Conventions</a></li> +<li><a href="#index-Copying-conditions-1">Copying conditions</a>: <a href="#Copying-Conditions">Copying Conditions</a></li> +<li><a href="#index-Copying-Permissions-179">Copying Permissions</a>: <a href="#Document-Permissions">Document Permissions</a></li> +<li><a href="#index-Copying-software-256">Copying software</a>: <a href="#Software-Copying-Permissions">Software Copying Permissions</a></li> +<li><a href="#index-Copying-text_002c-including-188">Copying text, including</a>: <a href="#insertcopying">insertcopying</a></li> +<li><a href="#index-Copyright-holder-for-FSF-works-184">Copyright holder for FSF works</a>: <a href="#copying">copying</a></li> +<li><a href="#index-Copyright-page-205">Copyright page</a>: <a href="#Copyright">Copyright</a></li> +<li><a href="#index-Copyright-page_002c-for-plain-text-192">Copyright page, for plain text</a>: <a href="#Titlepage-_0026-Copyright-Page">Titlepage & Copyright Page</a></li> +<li><a href="#index-Copyright-word_002c-always-in-English-182">Copyright word, always in English</a>: <a href="#copying">copying</a></li> +<li><a href="#index-Correcting-mistakes-1288">Correcting mistakes</a>: <a href="#Catching-Mistakes">Catching Mistakes</a></li> +<li><a href="#index-_0040code_007bcp_007d-_0028concept_0029-index-594"><code>cp</code> (concept) index</a>: <a href="#Predefined-Indices">Predefined Indices</a></li> +<li><a href="#index-Create-nodes_002c-menus-automatically-129">Create nodes, menus automatically</a>: <a href="#Updating-Nodes-and-Menus">Updating Nodes and Menus</a></li> +<li><a href="#index-Creating-an-Info-file-1068">Creating an Info file</a>: <a href="#Creating-an-Info-File">Creating an Info File</a></li> +<li><a href="#index-Creating-an-unsplit-file-1309">Creating an unsplit file</a>: <a href="#Unsplit">Unsplit</a></li> +<li><a href="#index-Creating-index-entries-604">Creating index entries</a>: <a href="#Indexing-Commands">Indexing Commands</a></li> +<li><a href="#index-Creating-pointers-with-_0040code_007bmakeinfo_007d-329">Creating pointers with <code>makeinfo</code></a>: <a href="#makeinfo-Pointer-Creation">makeinfo Pointer Creation</a></li> +<li><a href="#index-Cropmarks-for-printing-1059">Cropmarks for printing</a>: <a href="#Cropmarks-and-Magnification">Cropmarks and Magnification</a></li> +<li><a href="#index-Cross-reference-parts-364">Cross reference parts</a>: <a href="#Cross-Reference-Parts">Cross Reference Parts</a></li> +<li><a href="#index-Cross-references-361">Cross references</a>: <a href="#Cross-References">Cross References</a></li> +<li><a href="#index-Cross-references-using-_0040code_007b_0040_0040inforef_007d-380">Cross references using <code>@inforef</code></a>: <a href="#inforef">inforef</a></li> +<li><a href="#index-Cross-references-using-_0040code_007b_0040_0040pxref_007d-376">Cross references using <code>@pxref</code></a>: <a href="#pxref">pxref</a></li> +<li><a href="#index-Cross-references-using-_0040code_007b_0040_0040ref_007d-371">Cross references using <code>@ref</code></a>: <a href="#ref">ref</a></li> +<li><a href="#index-Cross-references-using-_0040code_007b_0040_0040xref_007d-367">Cross references using <code>@xref</code></a>: <a href="#xref">xref</a></li> +<li><a href="#index-Cross_002dreference-targets_002c-arbitrary-334">Cross-reference targets, arbitrary</a>: <a href="#anchor">anchor</a></li> +<li><a href="#index-Cross_002dreferences_002c-in-HTML-output-1217">Cross-references, in HTML output</a>: <a href="#HTML-Xref">HTML Xref</a></li> +<li><a href="#index-CSS_002c-and-HTML-output-1212">CSS, and HTML output</a>: <a href="#HTML-CSS">HTML CSS</a></li> +<li><a href="#index-Custom-page-sizes-1049">Custom page sizes</a>: <a href="#pagesizes">pagesizes</a></li> +<li><a href="#index-Customize-Emacs-package-_0028_0040t_007bDevelopment_002fDocs_002fTexinfo_007d_0029-1004">Customize Emacs package (<tt>Development/Docs/Texinfo</tt>)</a>: <a href="#Texinfo-Mode-Printing">Texinfo Mode Printing</a></li> +<li><a href="#index-Customized-highlighting-965">Customized highlighting</a>: <a href="#definfoenclose">definfoenclose</a></li> +<li><a href="#index-Customizing-of-_0040TeX_007b_007d-for-Texinfo-1020">Customizing of TeX for Texinfo</a>: <a href="#Preparing-for-TeX">Preparing for TeX</a></li> +<li><a href="#index-CVS-_0024Id-1246">CVS $Id</a>: <a href="#GNU-Sample-Texts">GNU Sample Texts</a></li> +<li><a href="#index-Dashes-in-source-61">Dashes in source</a>: <a href="#Conventions">Conventions</a></li> +<li><a href="#index-Debugging-the-Texinfo-structure-1291">Debugging the Texinfo structure</a>: <a href="#Catching-Mistakes">Catching Mistakes</a></li> +<li><a href="#index-Debugging-with-Info-formatting-1293">Debugging with Info formatting</a>: <a href="#Debugging-with-Info">Debugging with Info</a></li> +<li><a href="#index-Debugging-with-_0040TeX_007b_007d-formatting-1295">Debugging with TeX formatting</a>: <a href="#Debugging-with-TeX">Debugging with TeX</a></li> +<li><a href="#index-Defining-indexing-entries-600">Defining indexing entries</a>: <a href="#Indexing-Commands">Indexing Commands</a></li> +<li><a href="#index-Defining-macros-935">Defining macros</a>: <a href="#Defining-Macros">Defining Macros</a></li> +<li><a href="#index-Defining-new-indices-617">Defining new indices</a>: <a href="#New-Indices">New Indices</a></li> +<li><a href="#index-Defining-new-Texinfo-commands-931">Defining new Texinfo commands</a>: <a href="#Defining-New-Texinfo-Commands">Defining New Texinfo Commands</a></li> +<li><a href="#index-Definition-command-headings_002c-continuing-820">Definition command headings, continuing</a>: <a href="#Def-Cmd-Continuation-Lines">Def Cmd Continuation Lines</a></li> +<li><a href="#index-Definition-commands-814">Definition commands</a>: <a href="#Definition-Commands">Definition Commands</a></li> +<li><a href="#index-Definition-conventions-865">Definition conventions</a>: <a href="#Def-Cmd-Conventions">Def Cmd Conventions</a></li> +<li><a href="#index-Definition-lists_002c-typesetting-515">Definition lists, typesetting</a>: <a href="#table">table</a></li> +<li><a href="#index-Definition-template-815">Definition template</a>: <a href="#Def-Cmd-Template">Def Cmd Template</a></li> +<li><a href="#index-Definitions-grouped-together-833">Definitions grouped together</a>: <a href="#deffnx">deffnx</a></li> +<li><a href="#index-Delimiter-character_002c-for-verbatim-419">Delimiter character, for verbatim</a>: <a href="#verb">verb</a></li> +<li><a href="#index-Depth-of-text-area-1054">Depth of text area</a>: <a href="#pagesizes">pagesizes</a></li> +<li><a href="#index-Description-for-menu_002c-start-116">Description for menu, start</a>: <a href="#Inserting">Inserting</a></li> +<li><a href="#index-Description-of-document-234">Description of document</a>: <a href="#documentdescription">documentdescription</a></li> +<li><a href="#index-Details-of-macro-usage-960">Details of macro usage</a>: <a href="#Macro-Details">Macro Details</a></li> +<li><a href="#index-Did_0040_005eot-points-581">Didôt points</a>: <a href="#Image-Scaling">Image Scaling</a></li> +<li><a href="#index-Different-cross-reference-commands-363">Different cross reference commands</a>: <a href="#Cross-Reference-Commands">Cross Reference Commands</a></li> +<li><a href="#index-Dimension-formatting-651">Dimension formatting</a>: <a href="#dmn">dmn</a></li> +<li><a href="#index-Dimensions-and-image-sizes-574">Dimensions and image sizes</a>: <a href="#Image-Scaling">Image Scaling</a></li> +<li><a href="#index-Dir-categories_002c-choosing-1178">Dir categories, choosing</a>: <a href="#Installing-Dir-Entries">Installing Dir Entries</a></li> +<li><a href="#index-_0040file_007bdir_007d-directory-for-Info-installation-1159"><span class="file">dir</span> directory for Info installation</a>: <a href="#Installing-an-Info-File">Installing an Info File</a></li> +<li><a href="#index-_0040file_007bdir_007d-file-listing-1164"><span class="file">dir</span> file listing</a>: <a href="#New-Info-File">New Info File</a></li> +<li><a href="#index-_0040file_007bdir_007d-file_002c-creating-your-own-1174"><span class="file">dir</span> file, creating your own</a>: <a href="#Other-Info-Directories">Other Info Directories</a></li> +<li><a href="#index-_0040file_007bdir_007d-files-and-Info-directories-1168"><span class="file">dir</span> files and Info directories</a>: <a href="#Other-Info-Directories">Other Info Directories</a></li> +<li><a href="#index-Dir-files_002c-compressed-1184">Dir files, compressed</a>: <a href="#Invoking-install_002dinfo">Invoking install-info</a></li> +<li><a href="#index-_0040file_007bdir_007d_002c-created-by-_0040code_007binstall_002dinfo_007d-1182"><span class="file">dir</span>, created by <code>install-info</code></a>: <a href="#Invoking-install_002dinfo">Invoking install-info</a></li> +<li><a href="#index-Display-formatting-481">Display formatting</a>: <a href="#display">display</a></li> +<li><a href="#index-Displayed-equations-754">Displayed equations</a>: <a href="#math">math</a></li> +<li><a href="#index-distinct_0040r_007b_002c-value-for-_0040code_007b_0040_0040kbdinputstyle_007d_007d-407"><code>distinct</code><span class="roman">, value for </span><code>@kbdinputstyle</code></a>: <a href="#kbd">kbd</a></li> +<li><a href="#index-Distorting-images-573">Distorting images</a>: <a href="#Image-Scaling">Image Scaling</a></li> +<li><a href="#index-Distribution-257">Distribution</a>: <a href="#Software-Copying-Permissions">Software Copying Permissions</a></li> +<li><a href="#index-Docbook-output-32">Docbook output</a>: <a href="#Output-Formats">Output Formats</a></li> +<li><a href="#index-Docbook_002c-including-raw-892">Docbook, including raw</a>: <a href="#Raw-Formatter-Commands">Raw Formatter Commands</a></li> +<li><a href="#index-Document-description-233">Document description</a>: <a href="#documentdescription">documentdescription</a></li> +<li><a href="#index-Document-input-encoding-923">Document input encoding</a>: <a href="#documentencoding">documentencoding</a></li> +<li><a href="#index-Document-language_002c-declaring-914">Document language, declaring</a>: <a href="#documentlanguage">documentlanguage</a></li> +<li><a href="#index-Document-Permissions-178">Document Permissions</a>: <a href="#Document-Permissions">Document Permissions</a></li> +<li><a href="#index-Documentation-identification-1248">Documentation identification</a>: <a href="#GNU-Sample-Texts">GNU Sample Texts</a></li> +<li><a href="#index-Dot-accent-672">Dot accent</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-Dotless-i_002c-j-704">Dotless i, j</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-Dots_002c-inserting-730">Dots, inserting</a>: <a href="#Dots-Bullets">Dots Bullets</a></li> +<li><a href="#index-Dots_002c-inserting-740">Dots, inserting</a>: <a href="#dots">dots</a></li> +<li><a href="#index-Double_002dcolon-menu-entries-349">Double-colon menu entries</a>: <a href="#Less-Cluttered-Menu-Entry">Less Cluttered Menu Entry</a></li> +<li><a href="#index-DTD_002c-for-Texinfo-XML-30">DTD, for Texinfo XML</a>: <a href="#Output-Formats">Output Formats</a></li> +<li><a href="#index-Dumas_002c-Patrice-1218">Dumas, Patrice</a>: <a href="#HTML-Xref">HTML Xref</a></li> +<li><a href="#index-Dumping-a-_002efmt-file-1024">Dumping a .fmt file</a>: <a href="#Preparing-for-TeX">Preparing for TeX</a></li> +<li><a href="#index-DVI-file-979">DVI file</a>: <a href="#Format-with-tex_002ftexindex">Format with tex/texindex</a></li> +<li><a href="#index-DVI-output-23">DVI output</a>: <a href="#Output-Formats">Output Formats</a></li> +<li><a href="#index-dvips-24"><code>dvips</code></a>: <a href="#Output-Formats">Output Formats</a></li> +<li><a href="#index-Ellipsis_002c-inserting-732">Ellipsis, inserting</a>: <a href="#Dots-Bullets">Dots Bullets</a></li> +<li><a href="#index-Em-dash_002c-compared-to-minus-sign-748">Em dash, compared to minus sign</a>: <a href="#minus">minus</a></li> +<li><a href="#index-Em-dash_002c-producing-63">Em dash, producing</a>: <a href="#Conventions">Conventions</a></li> +<li><a href="#index-Emacs-97">Emacs</a>: <a href="#Texinfo-Mode">Texinfo Mode</a></li> +<li><a href="#index-Emacs-shell_002c-format_002c-print-from-999">Emacs shell, format, print from</a>: <a href="#Within-Emacs">Within Emacs</a></li> +<li><a href="#index-Emacs_002dW3-22">Emacs-W3</a>: <a href="#Output-Formats">Output Formats</a></li> +<li><a href="#index-Emphasizing-text-440">Emphasizing text</a>: <a href="#Emphasis">Emphasis</a></li> +<li><a href="#index-Emphasizing-text_002c-font-for-441">Emphasizing text, font for</a>: <a href="#emph-_0026-strong">emph & strong</a></li> +<li><a href="#index-En-dash_002c-producing-64">En dash, producing</a>: <a href="#Conventions">Conventions</a></li> +<li><a href="#index-Encoding_002c-declaring-920">Encoding, declaring</a>: <a href="#documentencoding">documentencoding</a></li> +<li><a href="#index-_0040samp_007b_0040r_007bEnd_007d_007d-node-footnote-style-588"><span class="samp">End</span> node footnote style</a>: <a href="#Footnote-Styles">Footnote Styles</a></li> +<li><a href="#index-End-of-header-line-177">End of header line</a>: <a href="#End-of-Header">End of Header</a></li> +<li><a href="#index-End-titlepage-starts-headings-213">End titlepage starts headings</a>: <a href="#end-titlepage">end titlepage</a></li> +<li><a href="#index-Ending-a-Sentence-639">Ending a Sentence</a>: <a href="#Ending-a-Sentence">Ending a Sentence</a></li> +<li><a href="#index-Ending-a-Texinfo-file-260">Ending a Texinfo file</a>: <a href="#Ending-a-File">Ending a File</a></li> +<li><a href="#index-Entries-for-an-index-602">Entries for an index</a>: <a href="#Indexing-Commands">Indexing Commands</a></li> +<li><a href="#index-Entries_002c-making-index-593">Entries, making index</a>: <a href="#Index-Entries">Index Entries</a></li> +<li><a href="#index-Enumeration-511">Enumeration</a>: <a href="#enumerate">enumerate</a></li> +<li><a href="#index-Environment-indentation-252">Environment indentation</a>: <a href="#exampleindent">exampleindent</a></li> +<li><a href="#index-Environment-variable-_0040code_007bINFOPATH_007d-1171">Environment variable <code>INFOPATH</code></a>: <a href="#Other-Info-Directories">Other Info Directories</a></li> +<li><a href="#index-Environment-variable-_0040code_007bTEXINFO_005fOUTPUT_005fFORMAT_007d-1135">Environment variable <code>TEXINFO_OUTPUT_FORMAT</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> +<li><a href="#index-Environment-variable-_0040code_007bTEXINPUTS_007d-1022">Environment variable <code>TEXINPUTS</code></a>: <a href="#Preparing-for-TeX">Preparing for TeX</a></li> +<li><a href="#index-epsf_002etex-585"><code>epsf.tex</code></a>: <a href="#Image-Scaling">Image Scaling</a></li> +<li><a href="#index-epsf_002etex_0040r_007b_002c-installing_007d-1017"><code>epsf.tex</code><span class="roman">, installing</span></a>: <a href="#Preparing-for-TeX">Preparing for TeX</a></li> +<li><a href="#index-Equations_002c-displayed-755">Equations, displayed</a>: <a href="#math">math</a></li> +<li><a href="#index-Equivalence_002c-indicating-770">Equivalence, indicating</a>: <a href="#Equivalence">Equivalence</a></li> +<li><a href="#index-Error-message_002c-indicating-768">Error message, indicating</a>: <a href="#Error-Glyph">Error Glyph</a></li> +<li><a href="#index-Errors_002c-parsing-1145">Errors, parsing</a>: <a href="#makeinfo-in-Emacs">makeinfo in Emacs</a></li> +<li><a href="#index-Es_002dzet-727">Es-zet</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-European-A4-paper-1044">European A4 paper</a>: <a href="#A4-Paper">A4 Paper</a></li> +<li><a href="#index-Evaluation-glyph-760">Evaluation glyph</a>: <a href="#result">result</a></li> +<li><a href="#index-Example-beginning-of-Texinfo-file-160">Example beginning of Texinfo file</a>: <a href="#Sample-Beginning">Sample Beginning</a></li> +<li><a href="#index-Example-indentation-253">Example indentation</a>: <a href="#exampleindent">exampleindent</a></li> +<li><a href="#index-Example-menu-354">Example menu</a>: <a href="#Menu-Example">Menu Example</a></li> +<li><a href="#index-example_0040r_007b_002c-value-for-_0040code_007b_0040_0040kbdinputstyle_007d_007d-408"><code>example</code><span class="roman">, value for </span><code>@kbdinputstyle</code></a>: <a href="#kbd">kbd</a></li> +<li><a href="#index-Examples-in-smaller-fonts-475">Examples in smaller fonts</a>: <a href="#small">small</a></li> +<li><a href="#index-Examples_002c-formatting-them-464">Examples, formatting them</a>: <a href="#example">example</a></li> +<li><a href="#index-Examples_002c-glyphs-for-757">Examples, glyphs for</a>: <a href="#Glyphs">Glyphs</a></li> +<li><a href="#index-Expanding-macros-953">Expanding macros</a>: <a href="#Invoking-Macros">Invoking Macros</a></li> +<li><a href="#index-Expansion-of-8_002dbit-characters-in-HTML-cross_002dreferences-1226">Expansion of 8-bit characters in HTML cross-references</a>: <a href="#HTML-Xref-8_002dbit-Character-Expansion">HTML Xref 8-bit Character Expansion</a></li> +<li><a href="#index-Expansion_002c-indicating-763">Expansion, indicating</a>: <a href="#expansion">expansion</a></li> +<li><a href="#index-expansion_002c-of-node-names-in-HTML-cross_002dreferences-1222">expansion, of node names in HTML cross-references</a>: <a href="#HTML-Xref-Node-Name-Expansion">HTML Xref Node Name Expansion</a></li> +<li><a href="#index-Expressions-in-a-program_002c-indicating-398">Expressions in a program, indicating</a>: <a href="#code">code</a></li> +<li><a href="#index-F_002eB_002eI_002e_002c-as-acronym-431">F.B.I., as acronym</a>: <a href="#acronym">acronym</a></li> +<li><a href="#index-FDL_002c-GNU-Free-Documentation-License-1315">FDL, GNU Free Documentation License</a>: <a href="#GNU-Free-Documentation-License">GNU Free Documentation License</a></li> +<li><a href="#index-Feminine-ordinal-719">Feminine ordinal</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-File-beginning-158">File beginning</a>: <a href="#Beginning-a-File">Beginning a File</a></li> +<li><a href="#index-File-ending-262">File ending</a>: <a href="#Ending-a-File">Ending a File</a></li> +<li><a href="#index-File-name-collision-172">File name collision</a>: <a href="#setfilename">setfilename</a></li> +<li><a href="#index-File-section-structure_002c-showing-it-122">File section structure, showing it</a>: <a href="#Showing-the-Structure">Showing the Structure</a></li> +<li><a href="#index-Final-output-1028">Final output</a>: <a href="#Overfull-hboxes">Overfull hboxes</a></li> +<li><a href="#index-Finding-badly-referenced-nodes-1304">Finding badly referenced nodes</a>: <a href="#Running-Info_002dValidate">Running Info-Validate</a></li> +<li><a href="#index-Fine_002dtuning_002c-and-hyphenation-789">Fine-tuning, and hyphenation</a>: <a href="#_002d-and-hyphenation">- and hyphenation</a></li> +<li><a href="#index-First-line-of-a-Texinfo-file-163">First line of a Texinfo file</a>: <a href="#First-Line">First Line</a></li> +<li><a href="#index-First-node-323">First node</a>: <a href="#First-Node">First Node</a></li> +<li><a href="#index-First-paragraph_002c-suppressing-indentation-of-245">First paragraph, suppressing indentation of</a>: <a href="#firstparagraphindent">firstparagraphindent</a></li> +<li><a href="#index-Fixed_002dwidth-font-455">Fixed-width font</a>: <a href="#Fonts">Fonts</a></li> +<li><a href="#index-Float-environment-543">Float environment</a>: <a href="#float">float</a></li> +<li><a href="#index-Floating-accents_002c-inserting-656">Floating accents, inserting</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-Floating_002c-not-yet-implemented-541">Floating, not yet implemented</a>: <a href="#Floats">Floats</a></li> +<li><a href="#index-Floats_002c-in-general-540">Floats, in general</a>: <a href="#Floats">Floats</a></li> +<li><a href="#index-Floats_002c-list-of-554">Floats, list of</a>: <a href="#listoffloats">listoffloats</a></li> +<li><a href="#index-Floats_002c-making-unnumbered-544">Floats, making unnumbered</a>: <a href="#float">float</a></li> +<li><a href="#index-Floats_002c-numbering-of-546">Floats, numbering of</a>: <a href="#float">float</a></li> +<li><a href="#index-Flooding-379">Flooding</a>: <a href="#pxref">pxref</a></li> +<li><a href="#index-_0040code_007bfn_007d-_0028function_0029-index-595"><code>fn</code> (function) index</a>: <a href="#Predefined-Indices">Predefined Indices</a></li> +<li><a href="#index-Fonts-for-indices-615">Fonts for indices</a>: <a href="#syncodeindex">syncodeindex</a></li> +<li><a href="#index-Fonts-for-printing_002c-not-Info-447">Fonts for printing, not Info</a>: <a href="#Fonts">Fonts</a></li> +<li><a href="#index-Footings-1269">Footings</a>: <a href="#Headings">Headings</a></li> +<li><a href="#index-Footnotes-586">Footnotes</a>: <a href="#Footnotes">Footnotes</a></li> +<li><a href="#index-Force-line-break-784">Force line break</a>: <a href="#Line-Breaks">Line Breaks</a></li> +<li><a href="#index-Forcing-indentation-496">Forcing indentation</a>: <a href="#indent">indent</a></li> +<li><a href="#index-Forcing-line-and-page-breaks-774">Forcing line and page breaks</a>: <a href="#Breaks">Breaks</a></li> +<li><a href="#index-Format-a-dimension-652">Format a dimension</a>: <a href="#dmn">dmn</a></li> +<li><a href="#index-Format-and-print-hardcopy-969">Format and print hardcopy</a>: <a href="#Hardcopy">Hardcopy</a></li> +<li><a href="#index-Format-and-print-in-Texinfo-mode-1002">Format and print in Texinfo mode</a>: <a href="#Texinfo-Mode-Printing">Texinfo Mode Printing</a></li> +<li><a href="#index-Format-file_002c-dumping-1025">Format file, dumping</a>: <a href="#Preparing-for-TeX">Preparing for TeX</a></li> +<li><a href="#index-Format-with-the-compile-command-1007">Format with the compile command</a>: <a href="#Compile_002dCommand">Compile-Command</a></li> +<li><a href="#index-Format_002c-print-from-Emacs-shell-997">Format, print from Emacs shell</a>: <a href="#Within-Emacs">Within Emacs</a></li> +<li><a href="#index-Formats-for-images-559">Formats for images</a>: <a href="#Image-Syntax">Image Syntax</a></li> +<li><a href="#index-Formatting-a-file-for-Info-1070">Formatting a file for Info</a>: <a href="#Creating-an-Info-File">Creating an Info File</a></li> +<li><a href="#index-Formatting-commands-47">Formatting commands</a>: <a href="#Formatting-Commands">Formatting Commands</a></li> +<li><a href="#index-Formatting-examples-465">Formatting examples</a>: <a href="#example">example</a></li> +<li><a href="#index-Formatting-for-Info-143">Formatting for Info</a>: <a href="#Info-Formatting">Info Formatting</a></li> +<li><a href="#index-Formatting-for-printing-148">Formatting for printing</a>: <a href="#Printing">Printing</a></li> +<li><a href="#index-Formatting-headings-and-footings-1272">Formatting headings and footings</a>: <a href="#Headings">Headings</a></li> +<li><a href="#index-Formatting-requirements-1010">Formatting requirements</a>: <a href="#Requirements-Summary">Requirements Summary</a></li> +<li><a href="#index-Formatting-with-_0040code_007btex_007d-and-_0040code_007btexindex_007d-978">Formatting with <code>tex</code> and <code>texindex</code></a>: <a href="#Format-with-tex_002ftexindex">Format with tex/texindex</a></li> +<li><a href="#index-Formulas_002c-mathematical-752">Formulas, mathematical</a>: <a href="#math">math</a></li> +<li><a href="#index-Fox_002c-Brian-80">Fox, Brian</a>: <a href="#History">History</a></li> +<li><a href="#index-Free-Documentation-License_002c-including-entire-1255">Free Documentation License, including entire</a>: <a href="#GNU-Sample-Texts">GNU Sample Texts</a></li> +<li><a href="#index-Free-Software-Directory-1177">Free Software Directory</a>: <a href="#Installing-Dir-Entries">Installing Dir Entries</a></li> +<li><a href="#index-Frequently-used-commands_002c-inserting-99">Frequently used commands, inserting</a>: <a href="#Inserting">Inserting</a></li> +<li><a href="#index-Frontmatter_002c-text-in-159">Frontmatter, text in</a>: <a href="#Beginning-a-File">Beginning a File</a></li> +<li><a href="#index-Full-texts_002c-GNU-1244">Full texts, GNU</a>: <a href="#GNU-Sample-Texts">GNU Sample Texts</a></li> +<li><a href="#index-Function-definitions-867">Function definitions</a>: <a href="#Sample-Function-Definition">Sample Function Definition</a></li> +<li><a href="#index-General-syntactic-conventions-49">General syntactic conventions</a>: <a href="#Conventions">Conventions</a></li> +<li><a href="#index-Generating-menus-with-indices-266">Generating menus with indices</a>: <a href="#Printing-Indices-_0026-Menus">Printing Indices & Menus</a></li> +<li><a href="#index-Generating-plain-text-files-1102">Generating plain text files</a>: <a href="#makeinfo-options">makeinfo options</a></li> +<li><a href="#index-German-S-729">German S</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-GIF-images_002c-unsupported-due-to-patents-565">GIF images, unsupported due to patents</a>: <a href="#Image-Syntax">Image Syntax</a></li> +<li><a href="#index-Global-Document-Commands-232">Global Document Commands</a>: <a href="#Global-Document-Commands">Global Document Commands</a></li> +<li><a href="#index-Globbing-984">Globbing</a>: <a href="#Format-with-tex_002ftexindex">Format with tex/texindex</a></li> +<li><a href="#index-Glyphs-756">Glyphs</a>: <a href="#Glyphs">Glyphs</a></li> +<li><a href="#index-GNU-Emacs-96">GNU Emacs</a>: <a href="#Texinfo-Mode">Texinfo Mode</a></li> +<li><a href="#index-GNU-Emacs-shell_002c-format_002c-print-from-1000">GNU Emacs shell, format, print from</a>: <a href="#Within-Emacs">Within Emacs</a></li> +<li><a href="#index-GNU-Free-Documentation-License_002c-including-entire-1254">GNU Free Documentation License, including entire</a>: <a href="#GNU-Sample-Texts">GNU Sample Texts</a></li> +<li><a href="#index-GNU-sample-texts-1242">GNU sample texts</a>: <a href="#GNU-Sample-Texts">GNU Sample Texts</a></li> +<li><a href="#index-Going-to-other-Info-files_0027-nodes-358">Going to other Info files' nodes</a>: <a href="#Other-Info-Files">Other Info Files</a></li> +<li><a href="#index-Grave-accent-666">Grave accent</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-Grave-accent_002c-vs_002e_0040_003a-left-quote-59">Grave accent, vs. left quote</a>: <a href="#Conventions">Conventions</a></li> +<li><a href="#index-Group-_0028hold-text-together-vertically_0029-808">Group (hold text together vertically)</a>: <a href="#group">group</a></li> +<li><a href="#index-Grouping-two-definitions-together-832">Grouping two definitions together</a>: <a href="#deffnx">deffnx</a></li> +<li><a href="#index-Hacek-accent-686">Hacek accent</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-Hardcopy_002c-printing-it-971">Hardcopy, printing it</a>: <a href="#Hardcopy">Hardcopy</a></li> +<li><a href="#index-_0040samp_007bhboxes_007d_002c-overfull-1027"><span class="samp">hboxes</span>, overfull</a>: <a href="#Overfull-hboxes">Overfull hboxes</a></li> +<li><a href="#index-Header-for-Texinfo-files-161">Header for Texinfo files</a>: <a href="#Texinfo-File-Header">Texinfo File Header</a></li> +<li><a href="#index-Header-of-a-Texinfo-file-165">Header of a Texinfo file</a>: <a href="#First-Line">First Line</a></li> +<li><a href="#index-Heading-row_002c-in-table-537">Heading row, in table</a>: <a href="#Multitable-Rows">Multitable Rows</a></li> +<li><a href="#index-Headings-1268">Headings</a>: <a href="#Headings">Headings</a></li> +<li><a href="#index-Headings_002c-indentation-after-249">Headings, indentation after</a>: <a href="#firstparagraphindent">firstparagraphindent</a></li> +<li><a href="#index-Headings_002c-page_002c-begin-to-appear-211">Headings, page, begin to appear</a>: <a href="#end-titlepage">end titlepage</a></li> +<li><a href="#index-Height-of-images-571">Height of images</a>: <a href="#Image-Scaling">Image Scaling</a></li> +<li><a href="#index-Height-of-text-area-1053">Height of text area</a>: <a href="#pagesizes">pagesizes</a></li> +<li><a href="#index-help2man-34"><code>help2man</code></a>: <a href="#Output-Formats">Output Formats</a></li> +<li><a href="#index-Hierarchical-documents_002c-and-menus-341">Hierarchical documents, and menus</a>: <a href="#Menu-Location">Menu Location</a></li> +<li><a href="#index-Highlighting-text-394">Highlighting text</a>: <a href="#Indicating">Indicating</a></li> +<li><a href="#index-Highlighting_002c-customized-964">Highlighting, customized</a>: <a href="#definfoenclose">definfoenclose</a></li> +<li><a href="#index-Hints-1239">Hints</a>: <a href="#Tips">Tips</a></li> +<li><a href="#index-History-of-Texinfo-90">History of Texinfo</a>: <a href="#History">History</a></li> +<li><a href="#index-Holder-of-copyright-for-FSF-works-185">Holder of copyright for FSF works</a>: <a href="#copying">copying</a></li> +<li><a href="#index-Holding-text-together-vertically-809">Holding text together vertically</a>: <a href="#group">group</a></li> +<li><a href="#index-_0040code_007bhref_007d_002c-producing-HTML-386"><code>href</code>, producing HTML</a>: <a href="#uref">uref</a></li> +<li><a href="#index-HTML-cross_002dreference-8_002dbit-character-expansion-1224">HTML cross-reference 8-bit character expansion</a>: <a href="#HTML-Xref-8_002dbit-Character-Expansion">HTML Xref 8-bit Character Expansion</a></li> +<li><a href="#index-HTML-cross_002dreference-command-expansion-1223">HTML cross-reference command expansion</a>: <a href="#HTML-Xref-Command-Expansion">HTML Xref Command Expansion</a></li> +<li><a href="#index-HTML-cross_002dreference-link-basics-1219">HTML cross-reference link basics</a>: <a href="#HTML-Xref-Link-Basics">HTML Xref Link Basics</a></li> +<li><a href="#index-HTML-cross_002dreference-mismatch-1227">HTML cross-reference mismatch</a>: <a href="#HTML-Xref-Mismatch">HTML Xref Mismatch</a></li> +<li><a href="#index-HTML-cross_002dreference-node-name-expansion-1220">HTML cross-reference node name expansion</a>: <a href="#HTML-Xref-Node-Name-Expansion">HTML Xref Node Name Expansion</a></li> +<li><a href="#index-HTML-cross_002dreferences-1216">HTML cross-references</a>: <a href="#HTML-Xref">HTML Xref</a></li> +<li><a href="#index-HTML-output-1205">HTML output</a>: <a href="#Generating-HTML">Generating HTML</a></li> +<li><a href="#index-HTML-output-18">HTML output</a>: <a href="#Output-Formats">Output Formats</a></li> +<li><a href="#index-HTML-output_002c-and-encodings-927">HTML output, and encodings</a>: <a href="#documentencoding">documentencoding</a></li> +<li><a href="#index-HTML-output_002c-browser-compatibility-of-1208">HTML output, browser compatibility of</a>: <a href="#HTML-Translation">HTML Translation</a></li> +<li><a href="#index-HTML-output_002c-split-1210">HTML output, split</a>: <a href="#HTML-Splitting">HTML Splitting</a></li> +<li><a href="#index-HTML_002c-and-CSS-1211">HTML, and CSS</a>: <a href="#HTML-CSS">HTML CSS</a></li> +<li><a href="#index-HTML_002c-including-raw-893">HTML, including raw</a>: <a href="#Raw-Formatter-Commands">Raw Formatter Commands</a></li> +<li><a href="#index-_0040code_007bhttp_002dequiv_007d_002c-and-charset-specification-928"><code>http-equiv</code>, and charset specification</a>: <a href="#documentencoding">documentencoding</a></li> +<li><a href="#index-Hungarian-umlaut-accent-674">Hungarian umlaut accent</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-Hurricanes-374">Hurricanes</a>: <a href="#ref">ref</a></li> +<li><a href="#index-Hyphen_002c-compared-to-minus-749">Hyphen, compared to minus</a>: <a href="#minus">minus</a></li> +<li><a href="#index-Hyphenation-patterns_002c-language_002ddependent-916">Hyphenation patterns, language-dependent</a>: <a href="#documentlanguage">documentlanguage</a></li> +<li><a href="#index-Hyphenation_002c-helping-_0040TeX_007b_007d-do-788">Hyphenation, helping TeX do</a>: <a href="#_002d-and-hyphenation">- and hyphenation</a></li> +<li><a href="#index-Hyphenation_002c-preventing-794">Hyphenation, preventing</a>: <a href="#w">w</a></li> +<li><a href="#index-Hyphens-in-source_002c-two-or-three-in-a-row-62">Hyphens in source, two or three in a row</a>: <a href="#Conventions">Conventions</a></li> +<li><a href="#index-_0040dotless_007bi_007d-_0028dotless-i_0029-702">i (dotless i)</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-Identification-of-documentation-1249">Identification of documentation</a>: <a href="#GNU-Sample-Texts">GNU Sample Texts</a></li> +<li><a href="#index-If-text-conditionally-visible-875">If text conditionally visible</a>: <a href="#Conditionals">Conditionals</a></li> +<li><a href="#index-Ignored-before-_0040code_007b_0040_0040setfilename_007d-169">Ignored before <code>@setfilename</code></a>: <a href="#setfilename">setfilename</a></li> +<li><a href="#index-Ignored-text-69">Ignored text</a>: <a href="#Comments">Comments</a></li> +<li><a href="#index-Image-formats-560">Image formats</a>: <a href="#Image-Syntax">Image Syntax</a></li> +<li><a href="#index-Images_002c-alternate-text-for-564">Images, alternate text for</a>: <a href="#Image-Syntax">Image Syntax</a></li> +<li><a href="#index-Images_002c-inserting-556">Images, inserting</a>: <a href="#Images">Images</a></li> +<li><a href="#index-Images_002c-scaling-568">Images, scaling</a>: <a href="#Image-Scaling">Image Scaling</a></li> +<li><a href="#index-Inches-578">Inches</a>: <a href="#Image-Scaling">Image Scaling</a></li> +<li><a href="#index-Include-file-sample-1266">Include file sample</a>: <a href="#Sample-Include-File">Sample Include File</a></li> +<li><a href="#index-Include-files-1260">Include files</a>: <a href="#Include-Files">Include Files</a></li> +<li><a href="#index-Include-files-requirements-1263">Include files requirements</a>: <a href="#Include-Files-Requirements">Include Files Requirements</a></li> +<li><a href="#index-Include-files_002c-and-section-levels-299">Include files, and section levels</a>: <a href="#Raise_002flower-sections">Raise/lower sections</a></li> +<li><a href="#index-Including-a-file-verbatim-470">Including a file verbatim</a>: <a href="#verbatiminclude">verbatiminclude</a></li> +<li><a href="#index-Including-permissions-text-190">Including permissions text</a>: <a href="#insertcopying">insertcopying</a></li> +<li><a href="#index-Indentation-undoing-486">Indentation undoing</a>: <a href="#exdent">exdent</a></li> +<li><a href="#index-Indentation_002c-forcing-498">Indentation, forcing</a>: <a href="#indent">indent</a></li> +<li><a href="#index-Indentation_002c-omitting-494">Indentation, omitting</a>: <a href="#noindent">noindent</a></li> +<li><a href="#index-Indenting-environments-251">Indenting environments</a>: <a href="#exampleindent">exampleindent</a></li> +<li><a href="#index-Indenting-paragraphs_002c-control-of-242">Indenting paragraphs, control of</a>: <a href="#paragraphindent">paragraphindent</a></li> +<li><a href="#index-Indenting_002c-suppressing-of-first-paragraph-248">Indenting, suppressing of first paragraph</a>: <a href="#firstparagraphindent">firstparagraphindent</a></li> +<li><a href="#index-Index-entries-601">Index entries</a>: <a href="#Indexing-Commands">Indexing Commands</a></li> +<li><a href="#index-Index-entries_002c-making-592">Index entries, making</a>: <a href="#Index-Entries">Index Entries</a></li> +<li><a href="#index-Index-entry-writing-606">Index entry writing</a>: <a href="#Indexing-Commands">Indexing Commands</a></li> +<li><a href="#index-Index-file-names-982">Index file names</a>: <a href="#Format-with-tex_002ftexindex">Format with tex/texindex</a></li> +<li><a href="#index-Index-font-types-607">Index font types</a>: <a href="#Indexing-Commands">Indexing Commands</a></li> +<li><a href="#index-Indexing-table-entries-automatically-519">Indexing table entries automatically</a>: <a href="#ftable-vtable">ftable vtable</a></li> +<li><a href="#index-Indicating-commands_002c-definitions_002c-etc_002e-395">Indicating commands, definitions, etc.</a>: <a href="#Indicating">Indicating</a></li> +<li><a href="#index-Indicating-evaluation-759">Indicating evaluation</a>: <a href="#result">result</a></li> +<li><a href="#index-Indices-591">Indices</a>: <a href="#Indices">Indices</a></li> +<li><a href="#index-Indices_002c-combining-them-609">Indices, combining them</a>: <a href="#Combining-Indices">Combining Indices</a></li> +<li><a href="#index-Indices_002c-defining-new-618">Indices, defining new</a>: <a href="#New-Indices">New Indices</a></li> +<li><a href="#index-Indices_002c-printing-and-menus-265">Indices, printing and menus</a>: <a href="#Printing-Indices-_0026-Menus">Printing Indices & Menus</a></li> +<li><a href="#index-Indices_002c-sorting-974">Indices, sorting</a>: <a href="#Hardcopy">Hardcopy</a></li> +<li><a href="#index-Indices_002c-two-letter-names-613">Indices, two letter names</a>: <a href="#syncodeindex">syncodeindex</a></li> +<li><a href="#index-Indirect-subfiles-1156">Indirect subfiles</a>: <a href="#Tag-and-Split-Files">Tag and Split Files</a></li> +<li><a href="#index-Info-batch-formatting-1153">Info batch formatting</a>: <a href="#Batch-Formatting">Batch Formatting</a></li> +<li><a href="#index-Info-file-installation-1158">Info file installation</a>: <a href="#Installing-an-Info-File">Installing an Info File</a></li> +<li><a href="#index-Info-file-name_002c-choosing-173">Info file name, choosing</a>: <a href="#setfilename">setfilename</a></li> +<li><a href="#index-Info-file_002c-listing-a-new-1163">Info file, listing a new</a>: <a href="#New-Info-File">New Info File</a></li> +<li><a href="#index-Info-file_002c-splitting-manually-1314">Info file, splitting manually</a>: <a href="#Splitting">Splitting</a></li> +<li><a href="#index-Info-files-38">Info files</a>: <a href="#Info-Files">Info Files</a></li> +<li><a href="#index-Info-format_002c-and-menus-340">Info format, and menus</a>: <a href="#Menu-Location">Menu Location</a></li> +<li><a href="#index-Info-formatting-145">Info formatting</a>: <a href="#Info-Formatting">Info Formatting</a></li> +<li><a href="#index-Info-installed-in-another-directory-1166">Info installed in another directory</a>: <a href="#Other-Info-Directories">Other Info Directories</a></li> +<li><a href="#index-Info-output-16">Info output</a>: <a href="#Output-Formats">Output Formats</a></li> +<li><a href="#index-Info-output_002c-and-encoding-926">Info output, and encoding</a>: <a href="#documentencoding">documentencoding</a></li> +<li><a href="#index-Info-validating-a-large-file-1307">Info validating a large file</a>: <a href="#Using-Info_002dvalidate">Using Info-validate</a></li> +<li><a href="#index-Info_002c-creating-an-online-file-1069">Info, creating an online file</a>: <a href="#Creating-an-Info-File">Creating an Info File</a></li> +<li><a href="#index-Info_002ddirectory_002dlist-1169"><code>Info-directory-list</code></a>: <a href="#Other-Info-Directories">Other Info Directories</a></li> +<li><a href="#index-Info_003b-other-files_0027-nodes-359">Info; other files' nodes</a>: <a href="#Other-Info-Files">Other Info Files</a></li> +<li><a href="#index-INFOPATH-1170"><code>INFOPATH</code></a>: <a href="#Other-Info-Directories">Other Info Directories</a></li> +<li><a href="#index-Initialization-file-for-_0040TeX_007b_007d-input-1015">Initialization file for TeX input</a>: <a href="#Preparing-for-TeX">Preparing for TeX</a></li> +<li><a href="#index-Input-encoding_002c-declaring-921">Input encoding, declaring</a>: <a href="#documentencoding">documentencoding</a></li> +<li><a href="#index-Insert-nodes_002c-menus-automatically-130">Insert nodes, menus automatically</a>: <a href="#Updating-Nodes-and-Menus">Updating Nodes and Menus</a></li> +<li><a href="#index-Inserting-_0040_0040-_0040r_007b_0028literal-_0040samp_007b_0040_0040_007d_0029_007d-627">Inserting @ <span class="roman">(literal @)</span></a>: <a href="#Inserting-an-Atsign">Inserting an Atsign</a></li> +<li><a href="#index-Inserting-accents-654">Inserting accents</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-Inserting-dots-734">Inserting dots</a>: <a href="#Dots-Bullets">Dots Bullets</a></li> +<li><a href="#index-Inserting-dots-739">Inserting dots</a>: <a href="#dots">dots</a></li> +<li><a href="#index-Inserting-ellipsis-733">Inserting ellipsis</a>: <a href="#Dots-Bullets">Dots Bullets</a></li> +<li><a href="#index-Inserting-frequently-used-commands-98">Inserting frequently used commands</a>: <a href="#Inserting">Inserting</a></li> +<li><a href="#index-Inserting-indentation-497">Inserting indentation</a>: <a href="#indent">indent</a></li> +<li><a href="#index-Inserting-space-633">Inserting space</a>: <a href="#Inserting-Space">Inserting Space</a></li> +<li><a href="#index-Inserting-special-characters-and-symbols-622">Inserting special characters and symbols</a>: <a href="#Insertions">Insertions</a></li> +<li><a href="#index-_0040file_007bINSTALL_007d-file_002c-generating-1103"><span class="file">INSTALL</span> file, generating</a>: <a href="#makeinfo-options">makeinfo options</a></li> +<li><a href="#index-install_002dinfo-1181"><code>install-info</code></a>: <a href="#Invoking-install_002dinfo">Invoking install-info</a></li> +<li><a href="#index-Installing-an-Info-file-1157">Installing an Info file</a>: <a href="#Installing-an-Info-File">Installing an Info File</a></li> +<li><a href="#index-Installing-Info-in-another-directory-1165">Installing Info in another directory</a>: <a href="#Other-Info-Directories">Other Info Directories</a></li> +<li><a href="#index-Internationalization-911">Internationalization</a>: <a href="#Internationalization">Internationalization</a></li> +<li><a href="#index-Introduction-to-Texinfo-12">Introduction to Texinfo</a>: <a href="#Using-Texinfo">Using Texinfo</a></li> +<li><a href="#index-Introduction_002c-as-part-of-file-259">Introduction, as part of file</a>: <a href="#Software-Copying-Permissions">Software Copying Permissions</a></li> +<li><a href="#index-Invalid-characters-in-node-names-317">Invalid characters in node names</a>: <a href="#Node-Line-Requirements">Node Line Requirements</a></li> +<li><a href="#index-Invoking-macros-952">Invoking macros</a>: <a href="#Invoking-Macros">Invoking Macros</a></li> +<li><a href="#index-Invoking-nodes_002c-including-in-dir-file-1180">Invoking nodes, including in dir file</a>: <a href="#Installing-Dir-Entries">Installing Dir Entries</a></li> +<li><a href="#index-ISO-639-codes-917">ISO 639 codes</a>: <a href="#documentlanguage">documentlanguage</a></li> +<li><a href="#index-Italic-font-452">Italic font</a>: <a href="#Fonts">Fonts</a></li> +<li><a href="#index-Itemization-507">Itemization</a>: <a href="#itemize">itemize</a></li> +<li><a href="#index-_0040dotless_007bj_007d-_0028dotless-j_0029-703">j (dotless j)</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-JPG-image-format-567">JPG image format</a>: <a href="#Image-Syntax">Image Syntax</a></li> +<li><a href="#index-Keyboard-input-403">Keyboard input</a>: <a href="#kbd">kbd</a></li> +<li><a href="#index-Keys_002c-recommended-names-412">Keys, recommended names</a>: <a href="#key">key</a></li> +<li><a href="#index-Keyword-expansion_002c-preventing-795">Keyword expansion, preventing</a>: <a href="#w">w</a></li> +<li><a href="#index-Keywords_002c-indicating-399">Keywords, indicating</a>: <a href="#code">code</a></li> +<li><a href="#index-Knuth_002c-Donald-45">Knuth, Donald</a>: <a href="#Printed-Books">Printed Books</a></li> +<li><a href="#index-_0040code_007bky_007d-_0028keystroke_0029-index-596"><code>ky</code> (keystroke) index</a>: <a href="#Predefined-Indices">Predefined Indices</a></li> +<li><a href="#index-Language-codes-918">Language codes</a>: <a href="#documentlanguage">documentlanguage</a></li> +<li><a href="#index-Language_002c-declaring-913">Language, declaring</a>: <a href="#documentlanguage">documentlanguage</a></li> +<li><a href="#index-Larger-or-smaller-pages-1063">Larger or smaller pages</a>: <a href="#Cropmarks-and-Magnification">Cropmarks and Magnification</a></li> +<li><a href="#index-_0040LaTeX_007b_007d_002c-processing-with-_0040command_007btexi2dvi_007d-991">LaTeX, processing with <span class="command">texi2dvi</span></a>: <a href="#Format-with-texi2dvi">Format with texi2dvi</a></li> +<li><a href="#index-Legal-paper_002c-printing-on-1056">Legal paper, printing on</a>: <a href="#pagesizes">pagesizes</a></li> +<li><a href="#index-Length-of-file-names-171">Length of file names</a>: <a href="#setfilename">setfilename</a></li> +<li><a href="#index-Less-cluttered-menu-entry-351">Less cluttered menu entry</a>: <a href="#Less-Cluttered-Menu-Entry">Less Cluttered Menu Entry</a></li> +<li><a href="#index-License-agreement-258">License agreement</a>: <a href="#Software-Copying-Permissions">Software Copying Permissions</a></li> +<li><a href="#index-License-for-all_002dpermissive-copying-1259">License for all-permissive copying</a>: <a href="#All_002dpermissive-Copying-License">All-permissive Copying License</a></li> +<li><a href="#index-License-for-verbatim-copying-1257">License for verbatim copying</a>: <a href="#Verbatim-Copying-License">Verbatim Copying License</a></li> +<li><a href="#index-Line-breaks-782">Line breaks</a>: <a href="#Line-Breaks">Line Breaks</a></li> +<li><a href="#index-Line-breaks-777">Line breaks</a>: <a href="#Breaks">Breaks</a></li> +<li><a href="#index-Line-breaks_002c-preventing-791">Line breaks, preventing</a>: <a href="#w">w</a></li> +<li><a href="#index-Line-length_002c-column-widths-as-fraction-of-530">Line length, column widths as fraction of</a>: <a href="#Multitable-Column-Widths">Multitable Column Widths</a></li> +<li><a href="#index-Line-spacing-805">Line spacing</a>: <a href="#sp">sp</a></li> +<li><a href="#index-Lisp-example-473">Lisp example</a>: <a href="#lisp">lisp</a></li> +<li><a href="#index-Lisp-examples-in-smaller-fonts-476">Lisp examples in smaller fonts</a>: <a href="#small">small</a></li> +<li><a href="#index-List-of--_0040_0040_002dcommands-1230">List of @-commands</a>: <a href="#Command-List">Command List</a></li> +<li><a href="#index-List-of-floats-553">List of floats</a>: <a href="#listoffloats">listoffloats</a></li> +<li><a href="#index-Listing-a-new-Info-file-1161">Listing a new Info file</a>: <a href="#New-Info-File">New Info File</a></li> +<li><a href="#index-Lists-and-tables_002c-making-504">Lists and tables, making</a>: <a href="#Lists-and-Tables">Lists and Tables</a></li> +<li><a href="#index-Local-variables-1005">Local variables</a>: <a href="#Compile_002dCommand">Compile-Command</a></li> +<li><a href="#index-Local-Variables_003a-section_002c-for-encoding-925">Local Variables: section, for encoding</a>: <a href="#documentencoding">documentencoding</a></li> +<li><a href="#index-Location-of-menus-339">Location of menus</a>: <a href="#Menu-Location">Menu Location</a></li> +<li><a href="#index-Looking-for-badly-referenced-nodes-1303">Looking for badly referenced nodes</a>: <a href="#Running-Info_002dValidate">Running Info-Validate</a></li> +<li><a href="#index-Lowering-and-raising-sections-297">Lowering and raising sections</a>: <a href="#Raise_002flower-sections">Raise/lower sections</a></li> +<li><a href="#index-lpr-_0040r_007b_0028DVI-print-command_0029_007d-992"><code>lpr </code><span class="roman">(DVI print command)</span></a>: <a href="#Print-with-lpr">Print with lpr</a></li> +<li><a href="#index-lpr_0040r_007b_002dd_002c-replacements-on-MS_002dDOS_002fMS_002dWindows_007d-995"><code>lpr</code><span class="roman">-d, replacements on MS-DOS/MS-Windows</span></a>: <a href="#Print-with-lpr">Print with lpr</a></li> +<li><a href="#index-Lynx-21">Lynx</a>: <a href="#Output-Formats">Output Formats</a></li> +<li><a href="#index-Macro-definitions-936">Macro definitions</a>: <a href="#Defining-Macros">Defining Macros</a></li> +<li><a href="#index-Macro-definitions-869">Macro definitions</a>: <a href="#Sample-Function-Definition">Sample Function Definition</a></li> +<li><a href="#index-Macro-details-959">Macro details</a>: <a href="#Macro-Details">Macro Details</a></li> +<li><a href="#index-Macro-expansion_002c-indicating-764">Macro expansion, indicating</a>: <a href="#expansion">expansion</a></li> +<li><a href="#index-Macro-invocation-955">Macro invocation</a>: <a href="#Invoking-Macros">Invoking Macros</a></li> +<li><a href="#index-Macro-names_002c-valid-characters-in-938">Macro names, valid characters in</a>: <a href="#Defining-Macros">Defining Macros</a></li> +<li><a href="#index-Macron-accent-662">Macron accent</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-Macros-930">Macros</a>: <a href="#Defining-New-Texinfo-Commands">Defining New Texinfo Commands</a></li> +<li><a href="#index-Macros-in-definition-commands-818">Macros in definition commands</a>: <a href="#Def-Cmd-Template">Def Cmd Template</a></li> +<li><a href="#index-Macros_002c-undefining-950">Macros, undefining</a>: <a href="#Defining-Macros">Defining Macros</a></li> +<li><a href="#index-Magnified-printing-1062">Magnified printing</a>: <a href="#Cropmarks-and-Magnification">Cropmarks and Magnification</a></li> +<li><a href="#index-Mailto-link-439">Mailto link</a>: <a href="#email">email</a></li> +<li><a href="#index-makeinfo-1071"><code>makeinfo</code></a>: <a href="#Invoking-makeinfo">Invoking makeinfo</a></li> +<li><a href="#index-_0040code_007bmakeinfo_007d-inside-Emacs-1141"><code>makeinfo</code> inside Emacs</a>: <a href="#makeinfo-in-Emacs">makeinfo in Emacs</a></li> +<li><a href="#index-_0040code_007bmakeinfo_007d-options-1072"><code>makeinfo</code> options</a>: <a href="#makeinfo-options">makeinfo options</a></li> +<li><a href="#index-Making-a-printed-manual-972">Making a printed manual</a>: <a href="#Hardcopy">Hardcopy</a></li> +<li><a href="#index-Making-a-tag-table-automatically-1154">Making a tag table automatically</a>: <a href="#Tag-and-Split-Files">Tag and Split Files</a></li> +<li><a href="#index-Making-a-tag-table-manually-1311">Making a tag table manually</a>: <a href="#Unsplit">Unsplit</a></li> +<li><a href="#index-Making-cross-references-360">Making cross references</a>: <a href="#Cross-References">Cross References</a></li> +<li><a href="#index-Making-line-and-page-breaks-775">Making line and page breaks</a>: <a href="#Breaks">Breaks</a></li> +<li><a href="#index-Making-lists-and-tables-503">Making lists and tables</a>: <a href="#Lists-and-Tables">Lists and Tables</a></li> +<li><a href="#index-Man-page-output_002c-not-supported-33">Man page output, not supported</a>: <a href="#Output-Formats">Output Formats</a></li> +<li><a href="#index-Man-page_002c-reference-to-387">Man page, reference to</a>: <a href="#uref">uref</a></li> +<li><a href="#index-Manual-characteristics_002c-printed-41">Manual characteristics, printed</a>: <a href="#Printed-Books">Printed Books</a></li> +<li><a href="#index-Margins-on-page_002c-not-controllable-1057">Margins on page, not controllable</a>: <a href="#pagesizes">pagesizes</a></li> +<li><a href="#index-Marking-text-within-a-paragraph-392">Marking text within a paragraph</a>: <a href="#Marking-Text">Marking Text</a></li> +<li><a href="#index-Marking-words-and-phrases-390">Marking words and phrases</a>: <a href="#Marking-Text">Marking Text</a></li> +<li><a href="#index-Masculine-ordinal-722">Masculine ordinal</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-Master-menu-229">Master menu</a>: <a href="#Master-Menu-Parts">Master Menu Parts</a></li> +<li><a href="#index-Mathematical-expressions-751">Mathematical expressions</a>: <a href="#math">math</a></li> +<li><a href="#index-Mathematical-expressions-898">Mathematical expressions</a>: <a href="#Raw-Formatter-Commands">Raw Formatter Commands</a></li> +<li><a href="#index-Menu-description_002c-start-115">Menu description, start</a>: <a href="#Inserting">Inserting</a></li> +<li><a href="#index-Menu-entries-with-two-colons-350">Menu entries with two colons</a>: <a href="#Less-Cluttered-Menu-Entry">Less Cluttered Menu Entry</a></li> +<li><a href="#index-Menu-example-353">Menu example</a>: <a href="#Menu-Example">Menu Example</a></li> +<li><a href="#index-Menu-location-338">Menu location</a>: <a href="#Menu-Location">Menu Location</a></li> +<li><a href="#index-Menu-parts-346">Menu parts</a>: <a href="#Menu-Parts">Menu Parts</a></li> +<li><a href="#index-Menu-writing-343">Menu writing</a>: <a href="#Writing-a-Menu">Writing a Menu</a></li> +<li><a href="#index-Menu_002c-master-230">Menu, master</a>: <a href="#Master-Menu-Parts">Master Menu Parts</a></li> +<li><a href="#index-Menus-336">Menus</a>: <a href="#Menus">Menus</a></li> +<li><a href="#index-Menus-generated-with-indices-267">Menus generated with indices</a>: <a href="#Printing-Indices-_0026-Menus">Printing Indices & Menus</a></li> +<li><a href="#index-Menus_002c-omitting-1105">Menus, omitting</a>: <a href="#makeinfo-options">makeinfo options</a></li> +<li><a href="#index-META-key-415">META key</a>: <a href="#key">key</a></li> +<li><a href="#index-Meta_002dsyntactic-chars-for-arguments-829">Meta-syntactic chars for arguments</a>: <a href="#Optional-Arguments">Optional Arguments</a></li> +<li><a href="#index-Methods_002c-object_002doriented-860">Methods, object-oriented</a>: <a href="#Object_002dOriented-Methods">Object-Oriented Methods</a></li> +<li><a href="#index-Millimeters-580">Millimeters</a>: <a href="#Image-Scaling">Image Scaling</a></li> +<li><a href="#index-Minimal-requirements-for-formatting-1009">Minimal requirements for formatting</a>: <a href="#Requirements-Summary">Requirements Summary</a></li> +<li><a href="#index-Minimal-Texinfo-file-_0028requirements_0029-72">Minimal Texinfo file (requirements)</a>: <a href="#Minimum">Minimum</a></li> +<li><a href="#index-Mismatched-HTML-cross_002dreference-source-and-target-1228">Mismatched HTML cross-reference source and target</a>: <a href="#HTML-Xref-Mismatch">HTML Xref Mismatch</a></li> +<li><a href="#index-Mistakes_002c-catching-1289">Mistakes, catching</a>: <a href="#Catching-Mistakes">Catching Mistakes</a></li> +<li><a href="#index-Mode_002c-using-Texinfo-95">Mode, using Texinfo</a>: <a href="#Texinfo-Mode">Texinfo Mode</a></li> +<li><a href="#index-Monospace-font-454">Monospace font</a>: <a href="#Fonts">Fonts</a></li> +<li><a href="#index-Mozilla-20">Mozilla</a>: <a href="#Output-Formats">Output Formats</a></li> +<li><a href="#index-Multiple-dashes-in-source-60">Multiple dashes in source</a>: <a href="#Conventions">Conventions</a></li> +<li><a href="#index-Multiple-spaces-644">Multiple spaces</a>: <a href="#Multiple-Spaces">Multiple Spaces</a></li> +<li><a href="#index-Multitable-column-widths-526">Multitable column widths</a>: <a href="#Multitable-Column-Widths">Multitable Column Widths</a></li> +<li><a href="#index-Multitable-rows-532">Multitable rows</a>: <a href="#Multitable-Rows">Multitable Rows</a></li> +<li><a href="#index-Must-have-in-Texinfo-file-73">Must have in Texinfo file</a>: <a href="#Minimum">Minimum</a></li> +<li><a href="#index-Mutually-recursive-macros-941">Mutually recursive macros</a>: <a href="#Defining-Macros">Defining Macros</a></li> +<li><a href="#index-Names-for-indices-614">Names for indices</a>: <a href="#syncodeindex">syncodeindex</a></li> +<li><a href="#index-Names-of-index-files-981">Names of index files</a>: <a href="#Format-with-tex_002ftexindex">Format with tex/texindex</a></li> +<li><a href="#index-Names-of-macros_002c-valid-characters-of-939">Names of macros, valid characters of</a>: <a href="#Defining-Macros">Defining Macros</a></li> +<li><a href="#index-Names-recommended-for-keys-413">Names recommended for keys</a>: <a href="#key">key</a></li> +<li><a href="#index-Naming-a-_0060Top_0027-Node-in-references-369">Naming a `Top' Node in references</a>: <a href="#Top-Node-Naming">Top Node Naming</a></li> +<li><a href="#index-NASA_002c-as-acronym-430">NASA, as acronym</a>: <a href="#acronym">acronym</a></li> +<li><a href="#index-Navigation-bar_002c-in-HTML-output-1207">Navigation bar, in HTML output</a>: <a href="#HTML-Translation">HTML Translation</a></li> +<li><a href="#index-Navigation-links_002c-omitting-1106">Navigation links, omitting</a>: <a href="#makeinfo-options">makeinfo options</a></li> +<li><a href="#index-Need-space-at-page-bottom-812">Need space at page bottom</a>: <a href="#need">need</a></li> +<li><a href="#index-Nesting-conditionals-910">Nesting conditionals</a>: <a href="#Conditional-Nesting">Conditional Nesting</a></li> +<li><a href="#index-New-index-defining-619">New index defining</a>: <a href="#New-Indices">New Indices</a></li> +<li><a href="#index-New-Info-file_002c-listing-it-in-_0040file_007bdir_007d-file-1162">New Info file, listing it in <span class="file">dir</span> file</a>: <a href="#New-Info-File">New Info File</a></li> +<li><a href="#index-New-Texinfo-commands_002c-defining-932">New Texinfo commands, defining</a>: <a href="#Defining-New-Texinfo-Commands">Defining New Texinfo Commands</a></li> +<li><a href="#index-Newlines_002c-as-blank-lines-56">Newlines, as blank lines</a>: <a href="#Conventions">Conventions</a></li> +<li><a href="#index-Next-node-of-Top-node-327">Next node of Top node</a>: <a href="#First-Node">First Node</a></li> +<li><a href="#index-Node-line-requirements-306">Node line requirements</a>: <a href="#Node-Line-Requirements">Node Line Requirements</a></li> +<li><a href="#index-Node-line-writing-305">Node line writing</a>: <a href="#Writing-a-Node">Writing a Node</a></li> +<li><a href="#index-node-name-expansion_002c-in-HTML-cross_002dreferences-1221">node name expansion, in HTML cross-references</a>: <a href="#HTML-Xref-Node-Name-Expansion">HTML Xref Node Name Expansion</a></li> +<li><a href="#index-Node-name-must-be-unique-309">Node name must be unique</a>: <a href="#Node-Line-Requirements">Node Line Requirements</a></li> +<li><a href="#index-Node-name_002c-should-not-contain-_0040_0040_002dcommands-311">Node name, should not contain @-commands</a>: <a href="#Node-Line-Requirements">Node Line Requirements</a></li> +<li><a href="#index-Node-names_002c-choosing-302">Node names, choosing</a>: <a href="#Node-Names">Node Names</a></li> +<li><a href="#index-Node-names_002c-invalid-characters-in-318">Node names, invalid characters in</a>: <a href="#Node-Line-Requirements">Node Line Requirements</a></li> +<li><a href="#index-Node-separators_002c-omitting-1104">Node separators, omitting</a>: <a href="#makeinfo-options">makeinfo options</a></li> +<li><a href="#index-Node_002c-_0060Top_0027-226">Node, `Top'</a>: <a href="#The-Top-Node">The Top Node</a></li> +<li><a href="#index-Node_002c-defined-300">Node, defined</a>: <a href="#node">node</a></li> +<li><a href="#index-Nodes-in-other-Info-files-356">Nodes in other Info files</a>: <a href="#Other-Info-Files">Other Info Files</a></li> +<li><a href="#index-Nodes_002c-catching-mistakes-1286">Nodes, catching mistakes</a>: <a href="#Catching-Mistakes">Catching Mistakes</a></li> +<li><a href="#index-Nodes_002c-checking-for-badly-referenced-1301">Nodes, checking for badly referenced</a>: <a href="#Running-Info_002dValidate">Running Info-Validate</a></li> +<li><a href="#index-Non_002dbreakable-space_002c-fixed-792">Non-breakable space, fixed</a>: <a href="#w">w</a></li> +<li><a href="#index-Non_002dbreakable-space_002c-variable-800">Non-breakable space, variable</a>: <a href="#tie">tie</a></li> +<li><a href="#index-Not-ending-a-sentence-635">Not ending a sentence</a>: <a href="#Not-Ending-a-Sentence">Not Ending a Sentence</a></li> +<li><a href="#index-Numbering-of-floats-547">Numbering of floats</a>: <a href="#float">float</a></li> +<li><a href="#index-_0040ordm_007b_007d-724">º</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-O_0027Dea_002c-Brendan-35">O'Dea, Brendan</a>: <a href="#Output-Formats">Output Formats</a></li> +<li><a href="#index-Object_002doriented-programming-850">Object-oriented programming</a>: <a href="#Abstract-Objects">Abstract Objects</a></li> +<li><a href="#index-Obtaining-_0040TeX_007b_007d-1066">Obtaining TeX</a>: <a href="#Obtaining-TeX">Obtaining TeX</a></li> +<li><a href="#index-Occurrences_002c-listing-with-_0040code_007b_0040_0040occur_007d-1298">Occurrences, listing with <code>@occur</code></a>: <a href="#Using-occur">Using occur</a></li> +<li><a href="#index-_0040OE_007b_007d-716">Œ</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-_0040oe_007b_007d-714">œ</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-Omitting-indentation-492">Omitting indentation</a>: <a href="#noindent">noindent</a></li> +<li><a href="#index-Optional-and-repeated-arguments-825">Optional and repeated arguments</a>: <a href="#Optional-Arguments">Optional Arguments</a></li> +<li><a href="#index-Options-for-_0040code_007bmakeinfo_007d-1073">Options for <code>makeinfo</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> +<li><a href="#index-Ordinals_002c-Romance-718">Ordinals, Romance</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-Ordinary-_0040TeX_007b_007d-commands_002c-using-890">Ordinary TeX commands, using</a>: <a href="#Raw-Formatter-Commands">Raw Formatter Commands</a></li> +<li><a href="#index-Other-Info-files_0027-nodes-357">Other Info files' nodes</a>: <a href="#Other-Info-Files">Other Info Files</a></li> +<li><a href="#index-Outline-of-file-structure_002c-showing-it-120">Outline of file structure, showing it</a>: <a href="#Showing-the-Structure">Showing the Structure</a></li> +<li><a href="#index-Output-file-splitting-1115">Output file splitting</a>: <a href="#makeinfo-options">makeinfo options</a></li> +<li><a href="#index-Output-formats-14">Output formats</a>: <a href="#Output-Formats">Output Formats</a></li> +<li><a href="#index-Output-formats_002c-supporting-more-36">Output formats, supporting more</a>: <a href="#Output-Formats">Output Formats</a></li> +<li><a href="#index-Overfull-_0040samp_007bhboxes_007d-1026">Overfull <span class="samp">hboxes</span></a>: <a href="#Overfull-hboxes">Overfull hboxes</a></li> +<li><a href="#index-Overview-of-Texinfo-3">Overview of Texinfo</a>: <a href="#Overview">Overview</a></li> +<li><a href="#index-Owner-of-copyright-for-FSF-works-186">Owner of copyright for FSF works</a>: <a href="#copying">copying</a></li> +<li><a href="#index-Page-breaks-779">Page breaks</a>: <a href="#Breaks">Breaks</a></li> +<li><a href="#index-Page-breaks-806">Page breaks</a>: <a href="#page">page</a></li> +<li><a href="#index-Page-delimiter-in-Texinfo-mode-127">Page delimiter in Texinfo mode</a>: <a href="#Showing-the-Structure">Showing the Structure</a></li> +<li><a href="#index-Page-headings-1271">Page headings</a>: <a href="#Headings">Headings</a></li> +<li><a href="#index-Page-numbering-1270">Page numbering</a>: <a href="#Headings">Headings</a></li> +<li><a href="#index-Page-sizes-for-books-1039">Page sizes for books</a>: <a href="#smallbook">smallbook</a></li> +<li><a href="#index-Page-sizes_002c-customized-1050">Page sizes, customized</a>: <a href="#pagesizes">pagesizes</a></li> +<li><a href="#index-page_002ddelimiter-126"><code>page-delimiter</code></a>: <a href="#Showing-the-Structure">Showing the Structure</a></li> +<li><a href="#index-Pages_002c-starting-odd-240">Pages, starting odd</a>: <a href="#setchapternewpage">setchapternewpage</a></li> +<li><a href="#index-Paper-size_002c-A4-1043">Paper size, A4</a>: <a href="#A4-Paper">A4 Paper</a></li> +<li><a href="#index-Paragraph-indentation-control-243">Paragraph indentation control</a>: <a href="#paragraphindent">paragraphindent</a></li> +<li><a href="#index-Paragraph-separator-54">Paragraph separator</a>: <a href="#Conventions">Conventions</a></li> +<li><a href="#index-Paragraph_002c-marking-text-within-389">Paragraph, marking text within</a>: <a href="#Marking-Text">Marking Text</a></li> +<li><a href="#index-Parameters-to-macros-943">Parameters to macros</a>: <a href="#Defining-Macros">Defining Macros</a></li> +<li><a href="#index-Parentheses-in-nodename-314">Parentheses in nodename</a>: <a href="#Node-Line-Requirements">Node Line Requirements</a></li> +<li><a href="#index-Parsing-errors-1146">Parsing errors</a>: <a href="#makeinfo-in-Emacs">makeinfo in Emacs</a></li> +<li><a href="#index-Part-of-file-formatting-and-printing-152">Part of file formatting and printing</a>: <a href="#Printing">Printing</a></li> +<li><a href="#index-Parts-of-a-cross-reference-365">Parts of a cross reference</a>: <a href="#Cross-Reference-Parts">Cross Reference Parts</a></li> +<li><a href="#index-Parts-of-a-master-menu-231">Parts of a master menu</a>: <a href="#Master-Menu-Parts">Master Menu Parts</a></li> +<li><a href="#index-Parts-of-a-menu-345">Parts of a menu</a>: <a href="#Menu-Parts">Menu Parts</a></li> +<li><a href="#index-Patches_002c-contributing-9">Patches, contributing</a>: <a href="#Reporting-Bugs">Reporting Bugs</a></li> +<li><a href="#index-PDF-output-1064">PDF output</a>: <a href="#PDF-Output">PDF Output</a></li> +<li><a href="#index-PDF-output-26">PDF output</a>: <a href="#Output-Formats">Output Formats</a></li> +<li><a href="#index-pdfcolor_002etex_0040r_007b_002c-installing_007d-1018"><code>pdfcolor.tex</code><span class="roman">, installing</span></a>: <a href="#Preparing-for-TeX">Preparing for TeX</a></li> +<li><a href="#index-pdftex-1065"><code>pdftex</code></a>: <a href="#PDF-Output">PDF Output</a></li> +<li><a href="#index-pdftex-28"><code>pdftex</code></a>: <a href="#Output-Formats">Output Formats</a></li> +<li><a href="#index-pdftex_0040r_007b_002c-and-images_007d-561"><code>pdftex</code><span class="roman">, and images</span></a>: <a href="#Image-Syntax">Image Syntax</a></li> +<li><a href="#index-Period-in-nodename-315">Period in nodename</a>: <a href="#Node-Line-Requirements">Node Line Requirements</a></li> +<li><a href="#index-Periods_002c-inserting-637">Periods, inserting</a>: <a href="#Not-Ending-a-Sentence">Not Ending a Sentence</a></li> +<li><a href="#index-Permissions-text_002c-including-189">Permissions text, including</a>: <a href="#insertcopying">insertcopying</a></li> +<li><a href="#index-Permissions_002c-printed-207">Permissions, printed</a>: <a href="#Copyright">Copyright</a></li> +<li><a href="#index-_0040code_007bpg_007d-_0028program_0029-index-597"><code>pg</code> (program) index</a>: <a href="#Predefined-Indices">Predefined Indices</a></li> +<li><a href="#index-Picas-576">Picas</a>: <a href="#Image-Scaling">Image Scaling</a></li> +<li><a href="#index-Pictures_002c-inserting-557">Pictures, inserting</a>: <a href="#Images">Images</a></li> +<li><a href="#index-Pinard_002c-Fran_0040_002c_007bc_007dois-82">Pinard, François</a>: <a href="#History">History</a></li> +<li><a href="#index-Plain-_0040TeX_007b_007d-895">Plain TeX</a>: <a href="#Raw-Formatter-Commands">Raw Formatter Commands</a></li> +<li><a href="#index-Plain-text-output-1100">Plain text output</a>: <a href="#makeinfo-options">makeinfo options</a></li> +<li><a href="#index-Plain-text-output-17">Plain text output</a>: <a href="#Output-Formats">Output Formats</a></li> +<li><a href="#index-PNG-image-format-566">PNG image format</a>: <a href="#Image-Syntax">Image Syntax</a></li> +<li><a href="#index-Point_002c-indicating-in-a-buffer-772">Point, indicating in a buffer</a>: <a href="#Point-Glyph">Point Glyph</a></li> +<li><a href="#index-Pointer-creation-with-_0040code_007bmakeinfo_007d-330">Pointer creation with <code>makeinfo</code></a>: <a href="#makeinfo-Pointer-Creation">makeinfo Pointer Creation</a></li> +<li><a href="#index-Pointer-validation-with-_0040code_007bmakeinfo_007d-1136">Pointer validation with <code>makeinfo</code></a>: <a href="#Pointer-Validation">Pointer Validation</a></li> +<li><a href="#index-Pointer-validation_002c-suppressing-988">Pointer validation, suppressing</a>: <a href="#Format-with-tex_002ftexindex">Format with tex/texindex</a></li> +<li><a href="#index-Pointer-validation_002c-suppressing-1118">Pointer validation, suppressing</a>: <a href="#makeinfo-options">makeinfo options</a></li> +<li><a href="#index-Points-_0028dimension_0029-575">Points (dimension)</a>: <a href="#Image-Scaling">Image Scaling</a></li> +<li><a href="#index-Predefined-names-for-indices-611">Predefined names for indices</a>: <a href="#syncodeindex">syncodeindex</a></li> +<li><a href="#index-Preparing-for-_0040TeX_007b_007d-1011">Preparing for TeX</a>: <a href="#Preparing-for-TeX">Preparing for TeX</a></li> +<li><a href="#index-Preventing-first-paragraph-indentation-247">Preventing first paragraph indentation</a>: <a href="#firstparagraphindent">firstparagraphindent</a></li> +<li><a href="#index-Preventing-line-and-page-breaks-776">Preventing line and page breaks</a>: <a href="#Breaks">Breaks</a></li> +<li><a href="#index-Previous-node-of-Top-node-326">Previous node of Top node</a>: <a href="#First-Node">First Node</a></li> +<li><a href="#index-Print-and-format-in-Texinfo-mode-1003">Print and format in Texinfo mode</a>: <a href="#Texinfo-Mode-Printing">Texinfo Mode Printing</a></li> +<li><a href="#index-Print_002c-format-from-Emacs-shell-996">Print, format from Emacs shell</a>: <a href="#Within-Emacs">Within Emacs</a></li> +<li><a href="#index-Printed-book-and-manual-characteristics-40">Printed book and manual characteristics</a>: <a href="#Printed-Books">Printed Books</a></li> +<li><a href="#index-Printed-output_002c-indicating-766">Printed output, indicating</a>: <a href="#Print-Glyph">Print Glyph</a></li> +<li><a href="#index-Printed-permissions-206">Printed permissions</a>: <a href="#Copyright">Copyright</a></li> +<li><a href="#index-Printing-a-region-or-buffer-149">Printing a region or buffer</a>: <a href="#Printing">Printing</a></li> +<li><a href="#index-Printing-an-index-264">Printing an index</a>: <a href="#Printing-Indices-_0026-Menus">Printing Indices & Menus</a></li> +<li><a href="#index-Printing-cropmarks-1060">Printing cropmarks</a>: <a href="#Cropmarks-and-Magnification">Cropmarks and Magnification</a></li> +<li><a href="#index-Printing-DVI-files_002c-on-MS_002dDOS_002fMS_002dWindows-994">Printing DVI files, on MS-DOS/MS-Windows</a>: <a href="#Print-with-lpr">Print with lpr</a></li> +<li><a href="#index-Printing-hardcopy-970">Printing hardcopy</a>: <a href="#Hardcopy">Hardcopy</a></li> +<li><a href="#index-Problems_002c-catching-1290">Problems, catching</a>: <a href="#Catching-Mistakes">Catching Mistakes</a></li> +<li><a href="#index-Program-names_002c-indicating-425">Program names, indicating</a>: <a href="#command">command</a></li> +<li><a href="#index-Prototype-row_002c-column-widths-defined-by-531">Prototype row, column widths defined by</a>: <a href="#Multitable-Column-Widths">Multitable Column Widths</a></li> +<li><a href="#index-Quotation-characters-_0028_0060_0027_0029_002c-in-source-57">Quotation characters (`'), in source</a>: <a href="#Conventions">Conventions</a></li> +<li><a href="#index-Quotations-460">Quotations</a>: <a href="#quotation">quotation</a></li> +<li><a href="#index-Ragged-left-491">Ragged left</a>: <a href="#flushleft-_0026-flushright">flushleft & flushright</a></li> +<li><a href="#index-Ragged-right-490">Ragged right</a>: <a href="#flushleft-_0026-flushright">flushleft & flushright</a></li> +<li><a href="#index-Raising-and-lowering-sections-296">Raising and lowering sections</a>: <a href="#Raise_002flower-sections">Raise/lower sections</a></li> +<li><a href="#index-Raw-formatter-commands-888">Raw formatter commands</a>: <a href="#Raw-Formatter-Commands">Raw Formatter Commands</a></li> +<li><a href="#index-RCS-_0024Id-1247">RCS $Id</a>: <a href="#GNU-Sample-Texts">GNU Sample Texts</a></li> +<li><a href="#index-Recommended-names-for-keys-411">Recommended names for keys</a>: <a href="#key">key</a></li> +<li><a href="#index-Rectangle_002c-black-in-hardcopy-1032">Rectangle, black in hardcopy</a>: <a href="#Overfull-hboxes">Overfull hboxes</a></li> +<li><a href="#index-Recursion_002c-mutual-942">Recursion, mutual</a>: <a href="#Defining-Macros">Defining Macros</a></li> +<li><a href="#index-Recursive-macro-invocations-947">Recursive macro invocations</a>: <a href="#Defining-Macros">Defining Macros</a></li> +<li><a href="#index-Reference-to-_0040_0040_002dcommands-1232">Reference to @-commands</a>: <a href="#Command-List">Command List</a></li> +<li><a href="#index-References-362">References</a>: <a href="#Cross-References">Cross References</a></li> +<li><a href="#index-References-using-_0040code_007b_0040_0040inforef_007d-381">References using <code>@inforef</code></a>: <a href="#inforef">inforef</a></li> +<li><a href="#index-References-using-_0040code_007b_0040_0040pxref_007d-377">References using <code>@pxref</code></a>: <a href="#pxref">pxref</a></li> +<li><a href="#index-References-using-_0040code_007b_0040_0040ref_007d-372">References using <code>@ref</code></a>: <a href="#ref">ref</a></li> +<li><a href="#index-References-using-_0040code_007b_0040_0040xref_007d-368">References using <code>@xref</code></a>: <a href="#xref">xref</a></li> +<li><a href="#index-Referring-to-other-Info-files-355">Referring to other Info files</a>: <a href="#Other-Info-Files">Other Info Files</a></li> +<li><a href="#index-Region-formatting-and-printing-150">Region formatting and printing</a>: <a href="#Printing">Printing</a></li> +<li><a href="#index-Region-printing-in-Texinfo-mode-1001">Region printing in Texinfo mode</a>: <a href="#Texinfo-Mode-Printing">Texinfo Mode Printing</a></li> +<li><a href="#index-Reid_002c-Brian-89">Reid, Brian</a>: <a href="#History">History</a></li> +<li><a href="#index-Repeated-and-optional-arguments-826">Repeated and optional arguments</a>: <a href="#Optional-Arguments">Optional Arguments</a></li> +<li><a href="#index-Reporting-bugs-7">Reporting bugs</a>: <a href="#Reporting-Bugs">Reporting Bugs</a></li> +<li><a href="#index-Required-in-Texinfo-file-74">Required in Texinfo file</a>: <a href="#Minimum">Minimum</a></li> +<li><a href="#index-Requirements-for-formatting-1008">Requirements for formatting</a>: <a href="#Requirements-Summary">Requirements Summary</a></li> +<li><a href="#index-Requirements-for-include-files-1264">Requirements for include files</a>: <a href="#Include-Files-Requirements">Include Files Requirements</a></li> +<li><a href="#index-Requirements-for-updating-commands-138">Requirements for updating commands</a>: <a href="#Updating-Requirements">Updating Requirements</a></li> +<li><a href="#index-Reserved-words_002c-indicating-400">Reserved words, indicating</a>: <a href="#code">code</a></li> +<li><a href="#index-Restrictions-on-node-names-307">Restrictions on node names</a>: <a href="#Node-Line-Requirements">Node Line Requirements</a></li> +<li><a href="#index-Result-of-an-expression-758">Result of an expression</a>: <a href="#result">result</a></li> +<li><a href="#index-ridt_002eeps-584"><code>ridt.eps</code></a>: <a href="#Image-Scaling">Image Scaling</a></li> +<li><a href="#index-Ring-accent-676">Ring accent</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-Roman-font-457">Roman font</a>: <a href="#Fonts">Fonts</a></li> +<li><a href="#index-Romance-ordinals-717">Romance ordinals</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-Rounded-rectangles_002c-around-examples-502">Rounded rectangles, around examples</a>: <a href="#cartouche">cartouche</a></li> +<li><a href="#index-Rows_002c-of-a-multitable-533">Rows, of a multitable</a>: <a href="#Multitable-Rows">Multitable Rows</a></li> +<li><a href="#index-Running-an-Info-formatter-144">Running an Info formatter</a>: <a href="#Info-Formatting">Info Formatting</a></li> +<li><a href="#index-Running-_0040code_007bInfo_002dvalidate_007d-1306">Running <code>Info-validate</code></a>: <a href="#Using-Info_002dvalidate">Using Info-validate</a></li> +<li><a href="#index-Running-macros-954">Running macros</a>: <a href="#Invoking-Macros">Invoking Macros</a></li> +<li><a href="#index-Running-_0040code_007bmakeinfo_007d-in-Emacs-1140">Running <code>makeinfo</code> in Emacs</a>: <a href="#makeinfo-in-Emacs">makeinfo in Emacs</a></li> +<li><a href="#index-Sample-_0040code_007b_0040_0040include_007d-file-1265">Sample <code>@include</code> file</a>: <a href="#Sample-Include-File">Sample Include File</a></li> +<li><a href="#index-Sample-function-definition-870">Sample function definition</a>: <a href="#Sample-Function-Definition">Sample Function Definition</a></li> +<li><a href="#index-Sample-Texinfo-file_002c-no-comments-1241">Sample Texinfo file, no comments</a>: <a href="#Short-Sample-Texinfo-File">Short Sample Texinfo File</a></li> +<li><a href="#index-Sample-Texinfo-file_002c-with-comments-77">Sample Texinfo file, with comments</a>: <a href="#Short-Sample">Short Sample</a></li> +<li><a href="#index-Sample-Texinfo-files-1240">Sample Texinfo files</a>: <a href="#Sample-Texinfo-Files">Sample Texinfo Files</a></li> +<li><a href="#index-Sample-texts_002c-GNU-1243">Sample texts, GNU</a>: <a href="#GNU-Sample-Texts">GNU Sample Texts</a></li> +<li><a href="#index-Scaled-points-583">Scaled points</a>: <a href="#Image-Scaling">Image Scaling</a></li> +<li><a href="#index-Scaling-images-569">Scaling images</a>: <a href="#Image-Scaling">Image Scaling</a></li> +<li><a href="#index-Schwab_002c-Andreas-86">Schwab, Andreas</a>: <a href="#History">History</a></li> +<li><a href="#index-Scribe-88">Scribe</a>: <a href="#History">History</a></li> +<li><a href="#index-Sea-surges-375">Sea surges</a>: <a href="#ref">ref</a></li> +<li><a href="#index-Section-structure-of-a-file_002c-showing-it-118">Section structure of a file, showing it</a>: <a href="#Showing-the-Structure">Showing the Structure</a></li> +<li><a href="#index-Sections_002c-raising-and-lowering-298">Sections, raising and lowering</a>: <a href="#Raise_002flower-sections">Raise/lower sections</a></li> +<li><a href="#index-Sentence-ending-punctuation-640">Sentence ending punctuation</a>: <a href="#Ending-a-Sentence">Ending a Sentence</a></li> +<li><a href="#index-Sentence-non_002dending-punctuation-636">Sentence non-ending punctuation</a>: <a href="#Not-Ending-a-Sentence">Not Ending a Sentence</a></li> +<li><a href="#index-_0040samp_007b_0040r_007bSeparate_007d_007d-footnote-style-589"><span class="samp">Separate</span> footnote style</a>: <a href="#Footnote-Styles">Footnote Styles</a></li> +<li><a href="#index-SGML_002dtools-output-format-37">SGML-tools output format</a>: <a href="#Output-Formats">Output Formats</a></li> +<li><a href="#index-Sharp-S-728">Sharp S</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-Shell-formatting-with-_0040code_007btex_007d-and-_0040code_007btexindex_007d-977">Shell formatting with <code>tex</code> and <code>texindex</code></a>: <a href="#Format-with-tex_002ftexindex">Format with tex/texindex</a></li> +<li><a href="#index-Shell-printing_002c-on-MS_002dDOS_002fMS_002dWindows-993">Shell printing, on MS-DOS/MS-Windows</a>: <a href="#Print-with-lpr">Print with lpr</a></li> +<li><a href="#index-Shell_002c-format_002c-print-from-998">Shell, format, print from</a>: <a href="#Within-Emacs">Within Emacs</a></li> +<li><a href="#index-Shell_002c-running-_0040code_007bmakeinfo_007d-in-1142">Shell, running <code>makeinfo</code> in</a>: <a href="#makeinfo-in-Emacs">makeinfo in Emacs</a></li> +<li><a href="#index-Short-captions_002c-for-lists-of-floats-551">Short captions, for lists of floats</a>: <a href="#caption-shortcaption">caption shortcaption</a></li> +<li><a href="#index-Short-table-of-contents-217">Short table of contents</a>: <a href="#Contents">Contents</a></li> +<li><a href="#index-Showing-the-section-structure-of-a-file-117">Showing the section structure of a file</a>: <a href="#Showing-the-Structure">Showing the Structure</a></li> +<li><a href="#index-Showing-the-structure-of-a-file-1296">Showing the structure of a file</a>: <a href="#Using-texinfo_002dshow_002dstructure">Using texinfo-show-structure</a></li> +<li><a href="#index-Shrubbery-907">Shrubbery</a>: <a href="#ifset-ifclear">ifset ifclear</a></li> +<li><a href="#index-Site_002dwide-Texinfo-configuration-file-1021">Site-wide Texinfo configuration file</a>: <a href="#Preparing-for-TeX">Preparing for TeX</a></li> +<li><a href="#index-Size-of-printed-book-1040">Size of printed book</a>: <a href="#smallbook">smallbook</a></li> +<li><a href="#index-Slanted-typewriter-font_002c-for-_0040code_007b_0040_0040kbd_007d-405">Slanted typewriter font, for <code>@kbd</code></a>: <a href="#kbd">kbd</a></li> +<li><a href="#index-Small-book-size-1037">Small book size</a>: <a href="#smallbook">smallbook</a></li> +<li><a href="#index-Small-caps-font-444">Small caps font</a>: <a href="#Smallcaps">Smallcaps</a></li> +<li><a href="#index-Small-examples-474">Small examples</a>: <a href="#small">small</a></li> +<li><a href="#index-Software-copying-permissions-255">Software copying permissions</a>: <a href="#Software-Copying-Permissions">Software Copying Permissions</a></li> +<li><a href="#index-Sorting-indices-973">Sorting indices</a>: <a href="#Hardcopy">Hardcopy</a></li> +<li><a href="#index-Source-file-format-13">Source file format</a>: <a href="#Using-Texinfo">Using Texinfo</a></li> +<li><a href="#index-Source-files_002c-characters-used-53">Source files, characters used</a>: <a href="#Conventions">Conventions</a></li> +<li><a href="#index-Space_002c-inserting-horizontal-646">Space, inserting horizontal</a>: <a href="#Multiple-Spaces">Multiple Spaces</a></li> +<li><a href="#index-Space_002c-inserting-vertical-803">Space, inserting vertical</a>: <a href="#sp">sp</a></li> +<li><a href="#index-Spaces-in-macros-945">Spaces in macros</a>: <a href="#Defining-Macros">Defining Macros</a></li> +<li><a href="#index-Spaces-in-node-name-321">Spaces in node name</a>: <a href="#Node-Line-Requirements">Node Line Requirements</a></li> +<li><a href="#index-Spaces_002c-in-menus-344">Spaces, in menus</a>: <a href="#Writing-a-Menu">Writing a Menu</a></li> +<li><a href="#index-Spacing_002c-inserting-634">Spacing, inserting</a>: <a href="#Inserting-Space">Inserting Space</a></li> +<li><a href="#index-Special-characters_002c-inserting-624">Special characters, inserting</a>: <a href="#Atsign-Braces-Comma">Atsign Braces Comma</a></li> +<li><a href="#index-Special-displays-539">Special displays</a>: <a href="#Special-Displays">Special Displays</a></li> +<li><a href="#index-Special-insertions-623">Special insertions</a>: <a href="#Insertions">Insertions</a></li> +<li><a href="#index-Special-typesetting-commands-735">Special typesetting commands</a>: <a href="#Dots-Bullets">Dots Bullets</a></li> +<li><a href="#index-Specifying-index-entries-603">Specifying index entries</a>: <a href="#Indexing-Commands">Indexing Commands</a></li> +<li><a href="#index-Split-HTML-output-1209">Split HTML output</a>: <a href="#HTML-Splitting">HTML Splitting</a></li> +<li><a href="#index-Splitting-an-Info-file-manually-1313">Splitting an Info file manually</a>: <a href="#Splitting">Splitting</a></li> +<li><a href="#index-Splitting-of-output-files-1114">Splitting of output files</a>: <a href="#makeinfo-options">makeinfo options</a></li> +<li><a href="#index-_0040ss_007b_007d-726">ß</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-Stallman_002c-Richard-M_002e-78">Stallman, Richard M.</a>: <a href="#History">History</a></li> +<li><a href="#index-Start-of-header-line-166">Start of header line</a>: <a href="#Start-of-Header">Start of Header</a></li> +<li><a href="#index-Starting-chapters-239">Starting chapters</a>: <a href="#setchapternewpage">setchapternewpage</a></li> +<li><a href="#index-Structure-of-a-file_002c-showing-it-119">Structure of a file, showing it</a>: <a href="#Showing-the-Structure">Showing the Structure</a></li> +<li><a href="#index-Structure_002c-catching-mistakes-in-1285">Structure, catching mistakes in</a>: <a href="#Catching-Mistakes">Catching Mistakes</a></li> +<li><a href="#index-Structuring-of-chapters-271">Structuring of chapters</a>: <a href="#Structuring">Structuring</a></li> +<li><a href="#index-Subsection_002dlike-commands-285">Subsection-like commands</a>: <a href="#unnumberedsubsec-appendixsubsec-subheading">unnumberedsubsec appendixsubsec subheading</a></li> +<li><a href="#index-Subsub-commands-289">Subsub commands</a>: <a href="#subsubsection">subsubsection</a></li> +<li><a href="#index-Suggestions-for-Texinfo_002c-making-6">Suggestions for Texinfo, making</a>: <a href="#Reporting-Bugs">Reporting Bugs</a></li> +<li><a href="#index-Summary-of-document-235">Summary of document</a>: <a href="#documentdescription">documentdescription</a></li> +<li><a href="#index-Suppressing-first-paragraph-indentation-246">Suppressing first paragraph indentation</a>: <a href="#firstparagraphindent">firstparagraphindent</a></li> +<li><a href="#index-Suppressing-indentation-493">Suppressing indentation</a>: <a href="#noindent">noindent</a></li> +<li><a href="#index-Syntactic-conventions-50">Syntactic conventions</a>: <a href="#Conventions">Conventions</a></li> +<li><a href="#index-Syntactic-tokens_002c-indicating-397">Syntactic tokens, indicating</a>: <a href="#code">code</a></li> +<li><a href="#index-Syntax_002c-of-_0040_0040_002dcommands-1234">Syntax, of @-commands</a>: <a href="#Command-Syntax">Command Syntax</a></li> +<li><a href="#index-Syntax_002c-optional-_0026-repeated-arguments-828">Syntax, optional & repeated arguments</a>: <a href="#Optional-Arguments">Optional Arguments</a></li> +<li><a href="#index-Table-of-contents-215">Table of contents</a>: <a href="#Contents">Contents</a></li> +<li><a href="#index-Table-of-contents_002c-after-title-page-224">Table of contents, after title page</a>: <a href="#Contents">Contents</a></li> +<li><a href="#index-Table-of-contents_002c-for-floats-555">Table of contents, for floats</a>: <a href="#listoffloats">listoffloats</a></li> +<li><a href="#index-Tables-and-lists_002c-making-505">Tables and lists, making</a>: <a href="#Lists-and-Tables">Lists and Tables</a></li> +<li><a href="#index-Tables-with-indexes-518">Tables with indexes</a>: <a href="#ftable-vtable">ftable vtable</a></li> +<li><a href="#index-Tables_002c-making-multi_002dcolumn-524">Tables, making multi-column</a>: <a href="#Multi_002dcolumn-Tables">Multi-column Tables</a></li> +<li><a href="#index-Tables_002c-making-two_002dcolumn-513">Tables, making two-column</a>: <a href="#Two_002dcolumn-Tables">Two-column Tables</a></li> +<li><a href="#index-Tabs_003b-don_0027t-use_0021-65">Tabs; don't use!</a>: <a href="#Conventions">Conventions</a></li> +<li><a href="#index-Tag-table_002c-making-automatically-1155">Tag table, making automatically</a>: <a href="#Tag-and-Split-Files">Tag and Split Files</a></li> +<li><a href="#index-Tag-table_002c-making-manually-1312">Tag table, making manually</a>: <a href="#Unsplit">Unsplit</a></li> +<li><a href="#index-Targets-for-cross_002dreferences_002c-arbitrary-335">Targets for cross-references, arbitrary</a>: <a href="#anchor">anchor</a></li> +<li><a href="#index-Template-for-a-definition-816">Template for a definition</a>: <a href="#Def-Cmd-Template">Def Cmd Template</a></li> +<li><a href="#index-_0040TeX_007b_007d-commands_002c-using-ordinary-889">TeX commands, using ordinary</a>: <a href="#Raw-Formatter-Commands">Raw Formatter Commands</a></li> +<li><a href="#index-_0040TeX_007b_007d-index-sorting-975">TeX index sorting</a>: <a href="#Hardcopy">Hardcopy</a></li> +<li><a href="#index-_0040TeX_007b_007d-input-initialization-1012">TeX input initialization</a>: <a href="#Preparing-for-TeX">Preparing for TeX</a></li> +<li><a href="#index-_0040TeX_007b_007d_002c-how-to-obtain-1067">TeX, how to obtain</a>: <a href="#Obtaining-TeX">Obtaining TeX</a></li> +<li><a href="#index-texi2dvi-985"><code>texi2dvi</code></a>: <a href="#Format-with-tex_002ftexindex">Format with tex/texindex</a></li> +<li><a href="#index-texi2dvi-_0040r_007b_0028shell-script_0029_007d-990"><code>texi2dvi </code><span class="roman">(shell script)</span></a>: <a href="#Format-with-texi2dvi">Format with texi2dvi</a></li> +<li><a href="#index-texi2roff_0040r_007b_002c-unsupported-software_007d-1316"><code>texi2roff</code><span class="roman">, unsupported software</span></a>: <a href="#Footnotes">Footnotes</a></li> +<li><a href="#index-texindex-980"><code>texindex</code></a>: <a href="#Format-with-tex_002ftexindex">Format with tex/texindex</a></li> +<li><a href="#index-texindex-976"><code>texindex</code></a>: <a href="#Hardcopy">Hardcopy</a></li> +<li><a href="#index-Texinfo-commands_002c-defining-new-933">Texinfo commands, defining new</a>: <a href="#Defining-New-Texinfo-Commands">Defining New Texinfo Commands</a></li> +<li><a href="#index-Texinfo-file-beginning-157">Texinfo file beginning</a>: <a href="#Beginning-a-File">Beginning a File</a></li> +<li><a href="#index-Texinfo-file-ending-261">Texinfo file ending</a>: <a href="#Ending-a-File">Ending a File</a></li> +<li><a href="#index-Texinfo-file-header-162">Texinfo file header</a>: <a href="#Texinfo-File-Header">Texinfo File Header</a></li> +<li><a href="#index-Texinfo-file-minimum-75">Texinfo file minimum</a>: <a href="#Minimum">Minimum</a></li> +<li><a href="#index-Texinfo-file-section-structure_002c-showing-it-123">Texinfo file section structure, showing it</a>: <a href="#Showing-the-Structure">Showing the Structure</a></li> +<li><a href="#index-Texinfo-history-91">Texinfo history</a>: <a href="#History">History</a></li> +<li><a href="#index-Texinfo-mode-94">Texinfo mode</a>: <a href="#Texinfo-Mode">Texinfo Mode</a></li> +<li><a href="#index-Texinfo-overview-4">Texinfo overview</a>: <a href="#Overview">Overview</a></li> +<li><a href="#index-Texinfo-printed-book-characteristics-43">Texinfo printed book characteristics</a>: <a href="#Printed-Books">Printed Books</a></li> +<li><a href="#index-Texinfo-requires-_0040code_007b_0040_0040setfilename_007d-168">Texinfo requires <code>@setfilename</code></a>: <a href="#setfilename">setfilename</a></li> +<li><a href="#index-Texinfo_002c-introduction-to-11">Texinfo, introduction to</a>: <a href="#Using-Texinfo">Using Texinfo</a></li> +<li><a href="#index-texinfo_002ecnf-174"><code>texinfo.cnf</code></a>: <a href="#setfilename">setfilename</a></li> +<li><a href="#index-texinfo_002ecnf-_0040r_007binstallation_007d-1019"><code>texinfo.cnf </code><span class="roman">installation</span></a>: <a href="#Preparing-for-TeX">Preparing for TeX</a></li> +<li><a href="#index-texinfo_002edtd-31"><code>texinfo.dtd</code></a>: <a href="#Output-Formats">Output Formats</a></li> +<li><a href="#index-texinfo_002etex_0040r_007b_002c-installing_007d-1016"><code>texinfo.tex</code><span class="roman">, installing</span></a>: <a href="#Preparing-for-TeX">Preparing for TeX</a></li> +<li><a href="#index-TEXINFO_005fOUTPUT_005fFORMAT-1134"><code>TEXINFO_OUTPUT_FORMAT</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> +<li><a href="#index-TEXINPUTS-1023"><code>TEXINPUTS</code></a>: <a href="#Preparing-for-TeX">Preparing for TeX</a></li> +<li><a href="#index-Text-width-and-height-1051">Text width and height</a>: <a href="#pagesizes">pagesizes</a></li> +<li><a href="#index-Text_002c-conditionally-visible-873">Text, conditionally visible</a>: <a href="#Conditionals">Conditionals</a></li> +<li><a href="#index-Text_002c-marking-up-393">Text, marking up</a>: <a href="#Marking-Text">Marking Text</a></li> +<li><a href="#index-Thin-space-between-number_002c-dimension-650">Thin space between number, dimension</a>: <a href="#dmn">dmn</a></li> +<li><a href="#index-Tie_002dafter-accent-678">Tie-after accent</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-Tied-space-799">Tied space</a>: <a href="#tie">tie</a></li> +<li><a href="#index-Tilde-accent-668">Tilde accent</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-time_002dstamp_002eel-1253"><code>time-stamp.el</code></a>: <a href="#GNU-Sample-Texts">GNU Sample Texts</a></li> +<li><a href="#index-Tips-1237">Tips</a>: <a href="#Tips">Tips</a></li> +<li><a href="#index-Title-page-193">Title page</a>: <a href="#titlepage">titlepage</a></li> +<li><a href="#index-Title-page_002c-bastard-198">Title page, bastard</a>: <a href="#titlepage">titlepage</a></li> +<li><a href="#index-Title-page_002c-for-plain-text-191">Title page, for plain text</a>: <a href="#Titlepage-_0026-Copyright-Page">Titlepage & Copyright Page</a></li> +<li><a href="#index-Titlepage-end-starts-headings-212">Titlepage end starts headings</a>: <a href="#end-titlepage">end titlepage</a></li> +<li><a href="#index-Top-node-225">Top node</a>: <a href="#The-Top-Node">The Top Node</a></li> +<li><a href="#index-Top-node-example-228">Top node example</a>: <a href="#Top-Node-Example">Top Node Example</a></li> +<li><a href="#index-Top-node-is-first-322">Top node is first</a>: <a href="#First-Node">First Node</a></li> +<li><a href="#index-_0040samp_007b_0040r_007bTop_007d_007d-node-naming-for-references-370"><span class="samp">Top</span> node naming for references</a>: <a href="#Top-Node-Naming">Top Node Naming</a></li> +<li><a href="#index-_0040code_007btp_007d-_0028data-type_0029-index-598"><code>tp</code> (data type) index</a>: <a href="#Predefined-Indices">Predefined Indices</a></li> +<li><a href="#index-Tree-structuring-272">Tree structuring</a>: <a href="#Tree-Structuring">Tree Structuring</a></li> +<li><a href="#index-Two-_0060First_0027-Lines-for-_0040code_007b_0040_0040deffn_007d-831">Two `First' Lines for <code>@deffn</code></a>: <a href="#deffnx">deffnx</a></li> +<li><a href="#index-Two-letter-names-for-indices-612">Two letter names for indices</a>: <a href="#syncodeindex">syncodeindex</a></li> +<li><a href="#index-Two-named-items-for-_0040code_007b_0040_0040table_007d-522">Two named items for <code>@table</code></a>: <a href="#itemx">itemx</a></li> +<li><a href="#index-Two-part-menu-entry-348">Two part menu entry</a>: <a href="#Less-Cluttered-Menu-Entry">Less Cluttered Menu Entry</a></li> +<li><a href="#index-_0040file_007btxi_002d_0040var_007bcc_007d_002etex_007d-915"><span class="file">txi-</span><var>cc</var><span class="file">.tex</span></a>: <a href="#documentlanguage">documentlanguage</a></li> +<li><a href="#index-Typesetting-commands-for-dots_002c-etc_002e-736">Typesetting commands for dots, etc.</a>: <a href="#Dots-Bullets">Dots Bullets</a></li> +<li><a href="#index-Typewriter-font-456">Typewriter font</a>: <a href="#Fonts">Fonts</a></li> +<li><a href="#index-Ugly-black-rectangles-in-hardcopy-1034">Ugly black rectangles in hardcopy</a>: <a href="#Overfull-hboxes">Overfull hboxes</a></li> +<li><a href="#index-Umlaut-accent-658">Umlaut accent</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-Unbreakable-space_002c-fixed-793">Unbreakable space, fixed</a>: <a href="#w">w</a></li> +<li><a href="#index-Unbreakable-space_002c-variable-801">Unbreakable space, variable</a>: <a href="#tie">tie</a></li> +<li><a href="#index-Uncluttered-menu-entry-352">Uncluttered menu entry</a>: <a href="#Less-Cluttered-Menu-Entry">Less Cluttered Menu Entry</a></li> +<li><a href="#index-Undefining-macros-951">Undefining macros</a>: <a href="#Defining-Macros">Defining Macros</a></li> +<li><a href="#index-Underbar-accent-682">Underbar accent</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-Underdot-accent-684">Underdot accent</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> +<li><a href="#index-Unicode-quotation-characters-58">Unicode quotation characters</a>: <a href="#Conventions">Conventions</a></li> +<li><a href="#index-Uniform-resource-locator_002c-indicating-436">Uniform resource locator, indicating</a>: <a href="#indicateurl">indicateurl</a></li> +<li><a href="#index-Uniform-resource-locator_002c-referring-to-384">Uniform resource locator, referring to</a>: <a href="#uref">uref</a></li> +<li><a href="#index-Unique-nodename-requirement-308">Unique nodename requirement</a>: <a href="#Node-Line-Requirements">Node Line Requirements</a></li> +<li><a href="#index-Unnumbered-float_002c-creating-545">Unnumbered float, creating</a>: <a href="#float">float</a></li> +<li><a href="#index-Unprocessed-text-70">Unprocessed text</a>: <a href="#Comments">Comments</a></li> +<li><a href="#index-Unsplit-file-creation-1310">Unsplit file creation</a>: <a href="#Unsplit">Unsplit</a></li> +<li><a href="#index-Up-node-of-Top-node-324">Up node of Top node</a>: <a href="#First-Node">First Node</a></li> +<li><a href="#index-UPDATED-_0040r_007bAutomake-variable_007d-1251"><code>UPDATED </code><span class="roman">Automake variable</span></a>: <a href="#GNU-Sample-Texts">GNU Sample Texts</a></li> +<li><a href="#index-Updating-nodes-and-menus-128">Updating nodes and menus</a>: <a href="#Updating-Nodes-and-Menus">Updating Nodes and Menus</a></li> +<li><a href="#index-Updating-requirements-137">Updating requirements</a>: <a href="#Updating-Requirements">Updating Requirements</a></li> +<li><a href="#index-URI-syntax-for-Info-39">URI syntax for Info</a>: <a href="#Info-Files">Info Files</a></li> +<li><a href="#index-URL_002c-indicating-437">URL, indicating</a>: <a href="#indicateurl">indicateurl</a></li> +<li><a href="#index-URL_002c-referring-to-385">URL, referring to</a>: <a href="#uref">uref</a></li> +<li><a href="#index-Usage-tips-1238">Usage tips</a>: <a href="#Tips">Tips</a></li> +<li><a href="#index-User-input-404">User input</a>: <a href="#kbd">kbd</a></li> +<li><a href="#index-User-options_002c-marking-844">User options, marking</a>: <a href="#Variables-Commands">Variables Commands</a></li> +<li><a href="#index-User_002ddefined-Texinfo-commands-934">User-defined Texinfo commands</a>: <a href="#Defining-New-Texinfo-Commands">Defining New Texinfo Commands</a></li> +<li><a href="#index-Using-Texinfo-in-general-10">Using Texinfo in general</a>: <a href="#Using-Texinfo">Using Texinfo</a></li> +<li><a href="#index-Validating-a-large-file-1308">Validating a large file</a>: <a href="#Using-Info_002dvalidate">Using Info-validate</a></li> +<li><a href="#index-Validation-of-pointers-1137">Validation of pointers</a>: <a href="#Pointer-Validation">Pointer Validation</a></li> +<li><a href="#index-Value-of-an-expression_002c-indicating-761">Value of an expression, indicating</a>: <a href="#result">result</a></li> +<li><a href="#index-Variables_002c-object_002doriented-851">Variables, object-oriented</a>: <a href="#Object_002dOriented-Variables">Object-Oriented Variables</a></li> +<li><a href="#index-Verbatim-copying-license-1256">Verbatim copying license</a>: <a href="#Verbatim-Copying-License">Verbatim Copying License</a></li> +<li><a href="#index-Verbatim-environment-468">Verbatim environment</a>: <a href="#verbatim">verbatim</a></li> +<li><a href="#index-Verbatim-in_002dline-text-418">Verbatim in-line text</a>: <a href="#verb">verb</a></li> +<li><a href="#index-Verbatim_002c-include-file-469">Verbatim, include file</a>: <a href="#verbatiminclude">verbatiminclude</a></li> +<li><a href="#index-VERSION-_0040r_007bAutomake-variable_007d-1252"><code>VERSION </code><span class="roman">Automake variable</span></a>: <a href="#GNU-Sample-Texts">GNU Sample Texts</a></li> +<li><a href="#index-Version-control-keywords_002c-preventing-expansion-of-796">Version control keywords, preventing expansion of</a>: <a href="#w">w</a></li> +<li><a href="#index-Version-number_002c-for-install_002dinfo-1204">Version number, for install-info</a>: <a href="#Invoking-install_002dinfo">Invoking install-info</a></li> +<li><a href="#index-Vertically-holding-text-together-810">Vertically holding text together</a>: <a href="#group">group</a></li> +<li><a href="#index-Visibility-of-conditional-text-874">Visibility of conditional text</a>: <a href="#Conditionals">Conditionals</a></li> +<li><a href="#index-_0040code_007bvr_007d-_0028variable_0029-index-599"><code>vr</code> (variable) index</a>: <a href="#Predefined-Indices">Predefined Indices</a></li> +<li><a href="#index-W3-consortium-19">W3 consortium</a>: <a href="#Output-Formats">Output Formats</a></li> +<li><a href="#index-Weinberg_002c-Zack-87">Weinberg, Zack</a>: <a href="#History">History</a></li> +<li><a href="#index-Weisshaus_002c-Melissa-84">Weisshaus, Melissa</a>: <a href="#History">History</a></li> +<li><a href="#index-White-space-in-node-name-320">White space in node name</a>: <a href="#Node-Line-Requirements">Node Line Requirements</a></li> +<li><a href="#index-White-space_002c-excessive-778">White space, excessive</a>: <a href="#Breaks">Breaks</a></li> +<li><a href="#index-Whitespace-in-macros-946">Whitespace in macros</a>: <a href="#Defining-Macros">Defining Macros</a></li> +<li><a href="#index-Whitespace_002c-collapsed-around-continuations-823">Whitespace, collapsed around continuations</a>: <a href="#Def-Cmd-Continuation-Lines">Def Cmd Continuation Lines</a></li> +<li><a href="#index-Whitespace_002c-inserting-645">Whitespace, inserting</a>: <a href="#Multiple-Spaces">Multiple Spaces</a></li> +<li><a href="#index-Width-of-images-570">Width of images</a>: <a href="#Image-Scaling">Image Scaling</a></li> +<li><a href="#index-Width-of-text-area-1052">Width of text area</a>: <a href="#pagesizes">pagesizes</a></li> +<li><a href="#index-Widths_002c-defining-multitable-column-528">Widths, defining multitable column</a>: <a href="#Multitable-Column-Widths">Multitable Column Widths</a></li> +<li><a href="#index-Wildcards-983">Wildcards</a>: <a href="#Format-with-tex_002ftexindex">Format with tex/texindex</a></li> +<li><a href="#index-Words-and-phrases_002c-marking-them-391">Words and phrases, marking them</a>: <a href="#Marking-Text">Marking Text</a></li> +<li><a href="#index-Writing-a-menu-342">Writing a menu</a>: <a href="#Writing-a-Menu">Writing a Menu</a></li> +<li><a href="#index-Writing-an-_0040code_007b_0040_0040node_007d-line-303">Writing an <code>@node</code> line</a>: <a href="#Writing-a-Node">Writing a Node</a></li> +<li><a href="#index-Writing-index-entries-605">Writing index entries</a>: <a href="#Indexing-Commands">Indexing Commands</a></li> +<li><a href="#index-xdvi-25"><code>xdvi</code></a>: <a href="#Output-Formats">Output Formats</a></li> +<li><a href="#index-XML-output-29">XML output</a>: <a href="#Output-Formats">Output Formats</a></li> +<li><a href="#index-XML_002c-including-raw-894">XML, including raw</a>: <a href="#Raw-Formatter-Commands">Raw Formatter Commands</a></li> +<li><a href="#index-XPM-image-format-562"><code>XPM image format</code></a>: <a href="#Image-Syntax">Image Syntax</a></li> +<li><a href="#index-Years_002c-in-copyright-line-183">Years, in copyright line</a>: <a href="#copying">copying</a></li> +<li><a href="#index-Zaretskii_002c-Eli-85">Zaretskii, Eli</a>: <a href="#History">History</a></li> +<li><a href="#index-Zuhn_002c-David-D_002e-83">Zuhn, David D.</a>: <a href="#History">History</a></li> +</ul><div class="footnote"> +<hr> +<a name="texinfo-footnotes-in-document"></a><h4>Footnotes</h4><p class="footnote"><small>[<a name="fn-1" href="#fnd-1">1</a>]</small> The first syllable of “Texinfo” is pronounced +like “speck”, not “hex”. This odd pronunciation is derived from, +but is not the same as, the pronunciation of TeX. In the word +TeX, the <span class="samp">X</span> is actually the Greek letter “chi” rather than +the English letter “ex”. Pronounce TeX as if the <span class="samp">X</span> were the +last sound in the name `Bach'; but pronounce Texinfo as if the <span class="samp">x</span> +were a `k'. Spell “Texinfo” with a capital “T” and the other +letters in lower case.</p> + + <p class="footnote"><small>[<a name="fn-2" href="#fnd-2">2</a>]</small> In some documents, the first child has no `Previous' +pointer. Occasionally, the last child has the node name of the next +following higher level node as its `Next' pointer.</p> + + <p class="footnote"><small>[<a name="fn-3" href="#fnd-3">3</a>]</small> You can also use the +<a name="index-texi2roff_0040r_007b_002c-unsupported-software_007d-1316"></a><a href="ftp://tug.org/texi2roff.tar.gz"><code>texi2roff</code></a> program if you +do not have TeX; since Texinfo is designed for use with TeX, +<code>texi2roff</code> is not described here. <code>texi2roff</code> is not part of +the standard GNU distribution and is not maintained or up-to-date with +all the Texinfo features described in this manual.</p> + + <p class="footnote"><small>[<a name="fn-4" href="#fnd-4">4</a>]</small> The word +<dfn>argument</dfn> comes from the way it is used in mathematics and does not +refer to a dispute between two people; it refers to the information +presented to the command. According to the <cite>Oxford English +Dictionary</cite>, the word derives from the Latin for <dfn>to make clear, +prove</dfn>; thus it came to mean `the evidence offered as proof', which is +to say, `the information offered', which led to its mathematical +meaning. In its other thread of derivation, the word came to mean `to +assert in a manner against which others may make counter assertions', +which led to the meaning of `argument' as a dispute.</p> + + <p class="footnote"><small>[<a name="fn-5" href="#fnd-5">5</a>]</small> We have found +that it is helpful to refer to versions of independent manuals as +`editions' and versions of programs as `versions'; otherwise, we find we +are liable to confuse each other in conversation by referring to both +the documentation and the software with the same words.</p> + + <p class="footnote"><small>[<a name="fn-6" href="#fnd-6">6</a>]</small> It would be straightforward to extend Texinfo to work +in a similar fashion for C, Fortran, or other languages.</p> + + <p class="footnote"><small>[<a name="fn-7" href="#fnd-7">7</a>]</small> A footnote should complement or expand upon +the primary text, but a reader should not need to read a footnote to +understand the primary text. For a thorough discussion of footnotes, +see <cite>The Chicago Manual of Style</cite>, which is published by the +University of Chicago Press.</p> + + <p class="footnote"><small>[<a name="fn-8" href="#fnd-8">8</a>]</small> Here +is the sample footnote.</p> + + <p class="footnote"><small>[<a name="fn-9" href="#fnd-9">9</a>]</small> Note the use +of the <span class="samp">;</span> character, instead of <span class="samp">:</span>, as directory separator +on these systems.</p> + + <p class="footnote"><small>[<a name="fn-10" href="#fnd-10">10</a>]</small> On MS-DOS/MS-Windows systems, Info will +try the <span class="file">.inf</span> extension as well.</p> + + <p class="footnote"><small>[<a name="fn-11" href="#fnd-11">11</a>]</small> Note the +use of <span class="samp">;</span> as the directory separator, and a different syntax for +using values of other environment variables.</p> + + <p class="footnote"><small>[<a name="fn-12" href="#fnd-12">12</a>]</small> On MS-DOS/MS-Windows systems, use semi-colon instead.</p> + + <p><hr></div> + +</body></html> + diff --git a/Master/texmf/doc/texinfo/texinfo.pdf b/Master/texmf/doc/texinfo/texinfo.pdf Binary files differnew file mode 100644 index 00000000000..74d214b6799 --- /dev/null +++ b/Master/texmf/doc/texinfo/texinfo.pdf |