diff options
| author | Karl Berry <karl@freefriends.org> | 2009-05-16 18:46:28 +0000 |
|---|---|---|
| committer | Karl Berry <karl@freefriends.org> | 2009-05-16 18:46:28 +0000 |
| commit | 6fd7d96728e3989b43117982795411c60eb7b910 (patch) | |
| tree | e380d5fd1dc9c8924fa0186bc185b5b14902c5ac | |
| parent | 49c1c71f4dcefd54b2ecc7e89fe17eaf626e8fe6 (diff) | |
remove texinfo, add texlive
git-svn-id: svn://tug.org/texlive/trunk@13121 c570f23f-e606-0410-a88d-b1316a301751
| -rw-r--r-- | Master/texmf/doc/texinfo/info-stnd.html | 2080 | ||||
| -rw-r--r-- | Master/texmf/doc/texinfo/info-stnd.pdf | bin | 309610 -> 0 bytes | |||
| -rw-r--r-- | Master/texmf/doc/texinfo/info.html | 1619 | ||||
| -rw-r--r-- | Master/texmf/doc/texinfo/info.pdf | bin | 218647 -> 0 bytes | |||
| -rw-r--r-- | Master/texmf/doc/texinfo/texinfo.html | 21165 | ||||
| -rw-r--r-- | Master/texmf/doc/texinfo/texinfo.pdf | bin | 1685490 -> 0 bytes |
6 files changed, 0 insertions, 24864 deletions
diff --git a/Master/texmf/doc/texinfo/info-stnd.html b/Master/texmf/doc/texinfo/info-stnd.html deleted file mode 100644 index abf2bb1c6e0..00000000000 --- a/Master/texmf/doc/texinfo/info-stnd.html +++ /dev/null @@ -1,2080 +0,0 @@ -<html lang="en"> -<head> -<title>GNU Info 4.12</title> -<meta http-equiv="Content-Type" content="text/html"> -<meta name="description" content="GNU Info 4.12"> -<meta name="generator" content="makeinfo 4.12"> -<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.12, 5 March 2008), -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, 2005, 2006, 2007, 2008 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.2 or any later version published by the Free Software - Foundation; with no Invariant Sections, with the Front-Cover texts - being "A GNU Manual", and with the Back-Cover Texts as in (a) - below. A copy of the license is included in the section entitled - "GNU Free Documentation License' in the Texinfo manual. - - (a) The FSF's Back-Cover Text is: "You have the freedom to copy - and modify this GNU manual. Buying copies from the FSF supports - it in developing GNU and promoting software freedom." - -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; } - span.sansserif { font-family:sans-serif; font-weight:normal; } ---></style> -</head> -<body> -<h1 class="settitle">GNU Info 4.12</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 <samp><span class="command">infokey</span></samp></a> -<li><a href="#infokey-source-format">12.2 <samp><span class="command">infokey</span></samp> source format</a> -</li></ul> -<li><a name="toc_Index" href="#Index">Appendix A 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> - -</div> - -<h2 class="unnumbered">GNU Info</h2> - -<p>If you do not know how to use Info, but have a working Info reader, -you should read the Info manual before this one (see <a href="info.html#Top">Getting Started</a>), as it includes more background information and -a thorough tutorial. This documentation describes the standalone Info -reader that is part of the Texinfo distribution, not the Info reader -that is part of GNU Emacs. - -<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="#Index">Index</a>: Global index with 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> - -</div> - -<h2 class="chapter">1 What is Info?</h2> - -<p>The <dfn>Info</dfn> program is a standalone program, part of the Texinfo -distribution, which is used to view Info files on an ASCII terminal. -<dfn>Info files</dfn> are typically the result of processing Texinfo files -with the program <code>makeinfo</code> (also in the Texinfo distribution) - - <p>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. - - <p>GNU Emacs also provides an Info reader (just type <kbd>M-x info</kbd> in -Emacs). Emacs Info and standalone Info have nearly identical user -interfaces, although customization and other details are different -(this manual explains the standalone Info reader). The Emacs Info -reader supports the X Window System and other such bitmapped -interfaces, not just plain ASCII, so if you want the prettiest -display for Info files, you should try it. You can use Emacs Info -without using Emacs for anything else. (Type <kbd>C-x C-c</kbd> to exit; -this also works in the standalone Info reader.) - -<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> - -</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="g_t_002d_002dapropos"></a><dt><code>--apropos=</code><var>string</var><dt><code>-k </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. (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 -‘<samp><span class="samp">--restore</span></samp>’ 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 <samp><span class="file">./</span></samp> or -<samp><span class="file">../</span></samp>, 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 <samp><span class="file">./</span></samp> or <samp><span class="file">../</span></samp> -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 <samp><span class="file">./</span></samp> and <samp><span class="file">../</span></samp> 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 <samp><span class="file">.z</span></samp>, <samp><span class="file">.gz</span></samp>, <samp><span class="file">.bz2</span></samp>, <samp><span class="file">.Z</span></samp>, or -<samp><span class="file">.Y</span></samp> 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 ‘<samp><span class="samp">no -entries found</span></samp>’ 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 ‘<samp><span class="samp">--dribble</span></samp>’ -option above). When the keystrokes in the files are all read, Info -reverts its input to the usual interactive operation. - - <p><a name="g_t_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-g_t_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="g_t_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 ‘<samp><span class="samp">Emacs</span></samp>’ in the node ‘<samp><span class="samp">(dir)Top</span></samp>’, -and then selects the menu item ‘<samp><span class="samp">Buffers</span></samp>’ in the node -‘<samp><span class="samp">(emacs)Top</span></samp>’. -</dl> - - <p>To avoid searching the <samp><span class="file">dir</span></samp> files and just show some arbitrary -file, use ‘<samp><span class="samp">-f</span></samp>’ and the filename, as in ‘<samp><span class="samp">info -f ./foo.info</span></samp>’. - - <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 -‘<samp><span class="samp">info emacs --show-options</span></samp>’ does what you'd expect. - - <p>Finally, Info defines many default key bindings and variables. -See <a href="#Custom-Key-Bindings">Custom Key Bindings</a>, for information on how to customize these -settings. - -<!-- 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> - -</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</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> - -</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 ‘<samp><span class="samp">--vi-keys</span></samp>’ -operation is in effect (see <a href="#g_t_002d_002dvi_002dkeys">–vi-keys</a>). These key bindings are -designated with “vi-like operation”. See <a href="#Custom-Key-Bindings">Custom Key Bindings</a>, -for information on arbitrarily customizing key bindings and variable -settings. - - <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, -‘<samp><span class="samp">z</span></samp>’ under ‘<samp><span class="samp">--vi-keys</span></samp>’, 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, -‘<samp><span class="samp">w</span></samp>’ under ‘<samp><span class="samp">--vi-keys</span></samp>’, 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, ‘<samp><span class="samp">w</span></samp>’ under -‘<samp><span class="samp">--vi-keys</span></samp>’, 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 ‘<samp><span class="samp">d</span></samp>’ and ‘<samp><span class="samp">u</span></samp>’ -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 ‘<samp><span class="samp">u</span></samp>’ and ‘<samp><span class="samp">d</span></samp>’ -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="#scroll_002dbehavior">scroll-behavior</a>). - - <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 ‘<samp><span class="samp">BackSpace</span></samp>’, 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, ‘<samp><span class="samp">C-l</span></samp>’ 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 ‘<samp><span class="samp">\</span></samp>’ 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 ‘<samp><span class="samp">$</span></samp>’ 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 -‘<samp><span class="samp">$</span></samp>’ 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> - -</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 ‘<samp><span class="samp">n</span></samp>’, ‘<samp><span class="samp">p</span></samp>’, ‘<samp><span class="samp">u</span></samp>’, and -‘<samp><span class="samp">l</span></samp>’. Note that the commands to select nodes are mapped differently -when ‘<samp><span class="samp">--vi-keys</span></samp>’ 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 ‘<samp><span class="samp">l</span></samp>’ 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 ‘<samp><span class="samp">l</span></samp>’ 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-g_t_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 ‘<samp><span class="samp">t</span></samp>’ and ‘<samp><span class="samp">d</span></samp>’. - - <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 ‘<samp><span class="samp">Top</span></samp>’ 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 ‘<samp><span class="samp">(dir)</span></samp>’). -</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-g_t_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 ‘<samp><span class="samp">Top</span></samp>’, 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-g_t_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-g_t_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 ‘<samp><span class="samp">Next</span></samp>’ pointer, that node is selected. -Otherwise, if this node has a menu, the first menu item is selected. If -there is no ‘<samp><span class="samp">Next</span></samp>’ and no menu, the same process is tried with the -‘<samp><span class="samp">Up</span></samp>’ node of this node. - - <br><dt><[> (<code>global-prev-node</code>)<dd><a name="index-g_t_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 ‘<samp><span class="samp">Prev</span></samp>’ pointer, that node is selected. -Otherwise, if the node has an ‘<samp><span class="samp">Up</span></samp>’ 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="#scroll_002dbehavior">scroll-behavior</a>). - - <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 ‘<samp><span class="samp">Buffers</span></samp>’ in the Info file <samp><span class="file">emacs</span></samp>. - - <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 -‘<samp><span class="samp">--show-options</span></samp>’ command-line option (see <a href="#g_t_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 -‘<samp><span class="samp">I</span></samp>’. 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 ‘<samp><span class="samp">I</span></samp>’ -doesn't display the right node, go to the ‘<samp><span class="samp">(dir)</span></samp>’ node (using the -‘<samp><span class="samp">d</span></samp>’ command) and invoke ‘<samp><span class="samp">I</span></samp>’ 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 ‘<samp><span class="samp">(dir)</span></samp>’ (if the ‘<samp><span class="samp">(dir)</span></samp>’ node cannot be found, Info -uses ‘<samp><span class="samp">Top</span></samp>’). 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 -‘<samp><span class="samp">(dir)</span></samp>’ 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 ‘<samp><span class="samp">Reporting Bugs</span></samp>’ 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 ‘<samp><span class="samp">C-x C-b</span></samp>’ followed by ‘<samp><span class="samp">m</span></samp>’, 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> - -</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-g_t_002f-175"></a><a name="index-search-176"></a><a name="index-regular-expression-search-177"></a>Read a string in the echo area and search for it, either as a regular -expression (by default) or a literal 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 backwards. - - <br><dt><?> (<code>search-backward</code>, vi-like operation)<dd><a name="index-g_t_003f_002c-vi_002dlike-operation-178"></a><a name="index-search_002dbackward-179"></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><R> (<code>toggle-regexp</code>)<dd><a name="index-R-180"></a><a name="index-toggle_002dregexp-181"></a>Toggle between using regular expressions and literal strings for -searching. Info uses so-called `extended' regular expression syntax, -similar to Emacs (see <a href="emacs.html#Regexps">Using Regular Expressions</a>). - - <br><dt><S> (<code>search-case-sensitively</code><dd><a name="index-S-182"></a><a name="index-search_002dcase_002dsensitively-183"></a><a name="index-search_002c-case_002dsensitive-184"></a><a name="index-case_002dsensitive-search-185"></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-186"></a><a name="index-n_002c-vi_002dlike-operation-187"></a><a name="index-search_002dnext-188"></a><a name="index-repeated-search-189"></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-190"></a><a name="index-n_002c-vi_002dlike-operation-191"></a><a name="index-search_002dprevious-192"></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-193"></a><a name="index-isearch_002dforward-194"></a><a name="index-incremental-search-195"></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-196"></a><a name="index-isearch_002dbackward-197"></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-198"></a><a name="index-index_002dsearch-199"></a><a name="index-index_002c-searching-200"></a><a name="index-searching_002c-in-the-indices-201"></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-g_t_002c-202"></a><a name="index-next_002dindex_002dmatch-203"></a>Move to the node containing the next matching index item from the last -‘<samp><span class="samp">i</span></samp>’ command. - - <br><dt><kbd>M-x index-apropos</kbd><dd><a name="index-index_002dapropos-204"></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 ‘<samp><span class="samp">s</span></samp>’ or ‘<samp><span class="samp">/</span></samp>’ -(<code>search</code>). The ‘<samp><span class="samp">s</span></samp>’ 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 ‘<samp><span class="samp">s</span></samp>’ commands show you the default search -string within ‘<samp><span class="samp">[</span></samp>’ and ‘<samp><span class="samp">]</span></samp>’; pressing <RET> instead of -typing a new string will use the default search string. Under -‘<samp><span class="samp">--vi-keys</span></samp>’ (see <a href="#g_t_002d_002dvi_002dkeys">–vi-keys</a>), using the ‘<samp><span class="samp">n</span></samp>’ or ‘<samp><span class="samp">N</span></samp>’ -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-205"></a><a name="index-case_002dsensitivity_002c-and-search-206"></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 -‘<samp><span class="samp">S</span></samp>’ command (<code>search-case-sensitively</code>). The ‘<samp><span class="samp">n</span></samp>’ and -‘<samp><span class="samp">N</span></samp>’ commands operate case-sensitively if the last search command -was ‘<samp><span class="samp">S</span></samp>’. - - <p>The most efficient means of finding something quickly in a manual is -the ‘<samp><span class="samp">i</span></samp>’ 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 ‘<samp><span class="samp">,</span></samp>’ -(<code>next-index-match</code>) to find more matches. A good Info manual -has all of its important concepts indexed, so the ‘<samp><span class="samp">i</span></samp>’ 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="#g_t_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> - -</div> - -<h2 class="chapter">7 Selecting Cross References</h2> - -<p>We have already discussed the ‘<samp><span class="samp">Next</span></samp>’, ‘<samp><span class="samp">Prev</span></samp>’, and ‘<samp><span class="samp">Up</span></samp>’ -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> - -</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 ‘<samp><span class="samp">:</span></samp>’; 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 ‘<samp><span class="samp">.</span></samp>’ which ends the name of the target. The ‘<samp><span class="samp">.</span></samp>’ 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 ‘<samp><span class="samp">*</span></samp>’ 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 ‘<samp><span class="samp">Next</span></samp>’, ‘<samp><span class="samp">Prev</span></samp>’, and ‘<samp><span class="samp">Up</span></samp>’ 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</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> - -</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-g_t1-_0040dots_007b_007d-9_002c-in-Info-windows-207"></a><a name="index-M_002d1-_0040dots_007b_007d-M_002d9_002c-vi_002dlike-operation-208"></a><a name="index-g_t1-_0040dots_007b_007d-9_002c-in-Info-windows-209"></a><a name="index-M_002d1-_0040dots_007b_007d-M_002d9_002c-vi_002dlike-operation-210"></a><a name="index-menu_002ddigit-211"></a>Within an Info window, pressing a single digit, (such as ‘<samp><span class="samp">1</span></samp>’), -selects that menu item, and places its node in the current window. -For convenience, there is one exception; pressing ‘<samp><span class="samp">0</span></samp>’ selects the -<em>last</em> item in the node's menu. When ‘<samp><span class="samp">--vi-keys</span></samp>’ is in -effect, digits set the numeric argument, so these commands are remapped -to their ‘<samp><span class="samp">M-</span></samp>’ 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-g_t0_002c-in-Info-windows-212"></a><a name="index-M_002d0_002c-vi_002dlike-operation-213"></a><a name="index-last_002dmenu_002ditem-214"></a>Select the last item in the current node's menu. - - <br><dt><m> (<code>menu-item</code>)<dd><a name="index-m-215"></a><a name="index-menu_002ditem-216"></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-217"></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-218"></a><a name="index-r-219"></a><a name="index-M_002df_002c-vi_002dlike-operation-220"></a><a name="index-C_002dx-r_002c-vi_002dlike-operation-221"></a><a name="index-xref_002ditem-222"></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-223"></a><a name="index-move_002dto_002dnext_002dxref-224"></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-225"></a><a name="index-move_002dto_002dprev_002dxref-226"></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-227"></a><a name="index-BackTab_002c-in-Info-windows-228"></a>On DOS/Windows only, the <kbd>Shift-<TAB></kbd> key is an alias for -<kbd>M-<TAB></kbd>. This key is sometimes called ‘<samp><span class="samp">BackTab</span></samp>’. - - <br><dt><RET> (<code>select-reference-this-line</code>)<dt><M-g>, vi-like operation<dd><a name="index-RET_002c-in-Info-windows-229"></a><a name="index-M_002dg_002c-vi_002dlike-operation-230"></a><a name="index-select_002dreference_002dthis_002dline-231"></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> - -</div> - -<h2 class="chapter">8 Manipulating Multiple Windows</h2> - -<p><a name="index-windows_002c-manipulating-232"></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> - -</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 <samp><span class="file">dir</span></samp>, showing the node ‘<samp><span class="samp">Top</span></samp>’. - -<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 ‘<samp><span class="samp">z</span></samp>’'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 -‘<samp><span class="samp">$</span></samp>’ 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 -(‘<samp><span class="samp">*</span></samp>’). 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> - -</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-233"></a><a name="index-C_002dx-o-234"></a><a name="index-next_002dwindow-235"></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, ‘<samp><span class="samp">C-x o</span></samp>’ 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, ‘<samp><span class="samp">C-x o</span></samp>’ moves over -that many windows. A negative argument causes ‘<samp><span class="samp">C-x o</span></samp>’ to select -the previous window on the screen. - - <br><dt><kbd>M-x prev-window</kbd><dd><a name="index-prev_002dwindow-236"></a>Select the previous window on the screen. This is identical to -‘<samp><span class="samp">C-x o</span></samp>’ with a negative argument. - - <br><dt><kbd>C-x <2></kbd> (<code>split-window</code>)<dd><a name="index-windows_002c-creating-237"></a><a name="index-C_002dx-2-238"></a><a name="index-split_002dwindow-239"></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 (see <a href="#Variables">automatic-tiling</a>). - - <br><dt><kbd>C-x <0></kbd> (<code>delete-window</code>)<dd><a name="index-windows_002c-deleting-240"></a><a name="index-C_002dx-0-241"></a><a name="index-delete_002dwindow-242"></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-243"></a><a name="index-keep_002done_002dwindow-244"></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-245"></a><a name="index-scroll_002dother_002dwindow-246"></a>Scroll the other window, in the same fashion that ‘<samp><span class="samp">C-v</span></samp>’ 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-247"></a><a name="index-grow_002dwindow-248"></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-249"></a><a name="index-C_002dx-t-250"></a><a name="index-tile_002dwindows-251"></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> - -</div> - -<h3 class="section">8.3 The Echo Area</h3> - -<p><a name="index-echo-area-252"></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-253"></a><a name="index-RIGHT_002c-in-the-echo-area-254"></a><a name="index-M_002dh_002c-in-the-echo-area_002c-vi_002dlike-operation-255"></a><a name="index-echo_002darea_002dforward-256"></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-257"></a><a name="index-C_002db_002c-in-the-echo-area-258"></a><a name="index-M_002dl_002c-in-the-echo-area_002c-vi_002dlike-operation-259"></a><a name="index-echo_002darea_002dbackward-260"></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-261"></a><a name="index-M_002d0_002c-in-the-echo-area_002c-vi_002dlike-operation-262"></a><a name="index-echo_002darea_002dbeg_002dof_002dline-263"></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-264"></a><a name="index-M_002d_0024_002c-vi_002dlike-operation-265"></a><a name="index-echo_002darea_002dend_002dof_002dline-266"></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-267"></a><a name="index-M_002dw_002c-in-the-echo-area_002c-vi_002dlike-operation-268"></a><a name="index-echo_002darea_002dforward_002dword-269"></a>Move forward a word. - - <p><a name="index-C_002dRIGHT_002c-in-the-echo-area-270"></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-271"></a><a name="index-echo_002darea_002dbackward_002dword-272"></a>Move backward a word. - - <p><a name="index-C_002dLEFT_002c-in-the-echo-area-273"></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-274"></a><a name="index-M_002dx_002c-in-the-echo-area_002c-vi_002dlike-operation-275"></a><a name="index-echo_002darea_002ddelete-276"></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-277"></a><a name="index-echo_002darea_002drubout-278"></a>Delete the character behind the cursor. - - <p>On some keyboards, this key is designated <BS>, for -‘<samp><span class="samp">BackSpace</span></samp>’. 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-279"></a><a name="index-C_002du_002c-in-the-echo-area_002c-vi_002dlike-operation-280"></a><a name="index-echo_002darea_002dabort-281"></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-282"></a><a name="index-echo_002darea_002dnewline-283"></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-284"></a><a name="index-C_002dv_002c-in-the-echo-area_002c-vi_002dlike-operation-285"></a><a name="index-echo_002darea_002dquoted_002dinsert-286"></a>Insert the next character verbatim. This is how you can insert control -characters into a search string, for example, or the ‘<samp><span class="samp">?</span></samp>’ 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-287"></a><a name="index-echo_002darea_002dinsert-288"></a>Insert the character. Characters that have their 8th bit set, and not -bound to ‘<samp><span class="samp">M-</span></samp>’ 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-289"></a><a name="index-Shift_002dTAB_002c-in-the-echo-area-290"></a><a name="index-echo_002darea_002dtab_002dinsert-291"></a>Insert a TAB character. - - <p><a name="index-Shift_002dTAB_002c-in-the-echo-area-292"></a><a name="index-BackTab_002c-in-the-echo-area-293"></a>On DOS/Windows only, the <kbd>Shift-<TAB></kbd> key is an alias for -<kbd>M-<TAB></kbd>. This key is sometimes called ‘<samp><span class="samp">BackTab</span></samp>’. - - <br><dt><C-t> (<code>echo-area-transpose-chars</code>)<dd><a name="index-C_002dt_002c-in-the-echo-area-294"></a><a name="index-echo_002darea_002dtranspose_002dchars-295"></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</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-296"></a><a name="index-M_002dX_002c-in-the-echo-area_002c-vi_002dlike-operation-297"></a><a name="index-echo_002darea_002dkill_002dword-298"></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-299"></a><a name="index-echo_002darea_002dbackward_002dkill_002dword-300"></a>Kill the word preceding the cursor. - - <p><a name="index-M_002dBS_002c-in-the-echo-area-301"></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-302"></a><a name="index-echo_002darea_002dkill_002dline-303"></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-304"></a><a name="index-echo_002darea_002dbackward_002dkill_002dline-305"></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-306"></a><a name="index-echo_002darea_002dyank-307"></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-308"></a><a name="index-echo_002darea_002dyank_002dpop-309"></a>Yank back a previous kill, removing the last yanked text first. -</dl> - - <p><a name="index-completion-310"></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-311"></a><a name="index-SPC_002c-in-the-echo-area-312"></a><a name="index-echo_002darea_002dcomplete-313"></a>Insert as much of a completion as is possible. - - <br><dt><?> (<code>echo-area-possible-completions</code>)<dd><a name="index-g_t_003f_002c-in-the-echo-area-314"></a><a name="index-echo_002darea_002dpossible_002dcompletions-315"></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 ‘<samp><span class="samp">f</span></samp>’, followed by ‘<samp><span class="samp">?</span></samp>’, Info will pop up a -window showing a node called ‘<samp><span class="samp">*Completions*</span></samp>’ 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 ‘<samp><span class="samp">f</span></samp>’. Pressing <SPC> -or <TAB> would result in ‘<samp><span class="samp">fo</span></samp>’ appearing in the echo area, since -all of the choices which begin with ‘<samp><span class="samp">f</span></samp>’ continue with ‘<samp><span class="samp">o</span></samp>’. -Now, typing ‘<samp><span class="samp">l</span></samp>’ followed by ‘<samp><span class="samp">TAB</span></samp>’ results in ‘<samp><span class="samp">foliate</span></samp>’ -appearing in the echo area, since that is the only choice which begins -with ‘<samp><span class="samp">fol</span></samp>’. - - <br><dt><ESC C-v> (<code>echo-area-scroll-completions-window</code>)<dd><a name="index-ESC-C_002dv_002c-in-the-echo-area-316"></a><a name="index-echo_002darea_002dscroll_002dcompletions_002dwindow-317"></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> - -</div> - -<h2 class="chapter">9 Printing Nodes</h2> - -<p><a name="index-printing-318"></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-319"></a><a name="index-INFO_005fPRINT_005fCOMMAND_002c-environment-variable-320"></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, <samp><span class="file">PRN</span></samp>). - - <p><a name="index-printing-nodes-to-the-local-printer-321"></a><a name="index-local-printer-device-322"></a>The value of <code>INFO_PRINT_COMMAND</code> may begin with the ‘<samp><span class="samp">></span></samp>’ -character, as in ‘<samp><span class="samp">>/dev/printer</span></samp>’, 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> - -</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-323"></a><a name="index-commands_002c-describing-324"></a><a name="index-describe_002dcommand-325"></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-326"></a><a name="index-describe_002dkey-327"></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-328"></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-329"></a><a name="index-g_t_003f_002c-in-Info-windows-330"></a><a name="index-F1-331"></a><a name="index-h_002c-vi_002dlike-operation-332"></a><a name="index-get_002dhelp_002dwindow-333"></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-334"></a><a name="index-M_002dh_002c-vi_002dlike-operation-335"></a><a name="index-get_002dinfo_002dhelp_002dnode-336"></a>Try hard to visit the node <code>(info)Help</code>. The Info file -<samp><span class="file">info.texi</span></samp> 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-337"></a><a name="index-C_002du-338"></a><a name="index-universal_002dargument-339"></a>Start (or multiply by 4) the current numeric argument. ‘<samp><span class="samp">C-u</span></samp>’ is -a good way to give a small numeric argument to cursor movement or -scrolling commands; ‘<samp><span class="samp">C-u C-v</span></samp>’ scrolls the screen 4 lines, while -‘<samp><span class="samp">C-u C-u C-n</span></samp>’ moves the cursor down 16 lines. ‘<samp><span class="samp">C-u</span></samp>’ 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-340"></a><a name="index-g_t0-_0040dots_007b_007d-9_002c-vi_002dlike-operation-341"></a><a name="index-add_002ddigit_002dto_002dnumeric_002darg-342"></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 ‘<samp><span class="samp">C-l</span></samp>’ 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-343"></a><a name="index-g_t_002d-344"></a><a name="index-negative-arguments-345"></a><a name="index-arguments_002c-negative-346"></a><a name="index-numeric-arguments_002c-negative-347"></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 ‘<samp><span class="samp">-</span></samp>’ character itself; use <kbd>M--</kbd> instead, -if you need to specify negative arguments in the echo area. -</dl> - - <p>‘<samp><span class="samp">C-g</span></samp>’ 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-348"></a><a name="index-cancelling-the-current-operation-349"></a><a name="index-C_002dg_002c-in-Info-windows-350"></a><a name="index-C_002du-cancels-typeahead_002c-vi_002dlike-operation-351"></a><a name="index-abort_002dkey-352"></a>Cancel current operation. -</dl> - - <p>The ‘<samp><span class="samp">q</span></samp>’ command of Info simply quits running Info. Under -‘<samp><span class="samp">--vi-keys</span></samp>’ (see <a href="#g_t_002d_002dvi_002dkeys">–vi-keys</a>), you can also exit with ‘<samp><span class="samp">:q</span></samp>’ -or ‘<samp><span class="samp">ZZ</span></samp>’. - - <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-353"></a><a name="index-q-354"></a><a name="index-C_002dx-C_002dc-355"></a><a name="index-ZZ_002c-vi_002dlike-operation-356"></a><a name="index-quit-357"></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-358"></a><a name="index-screen_002c-changing-the-height-of-359"></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-360"></a><a name="index-show_002dfootnotes-361"></a><a name="index-footnotes_002c-displaying-362"></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> - -</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-363"></a><a name="index-set_002dvariable-364"></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-365"></a><a name="index-describe_002dvariable-366"></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-367"></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 ‘<samp><span class="samp">*Footnotes*</span></samp>’. If a node is -selected which contains no footnotes, and a ‘<samp><span class="samp">*Footnotes*</span></samp>’ window -is on the screen, the ‘<samp><span class="samp">*Footnotes*</span></samp>’ 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-368"></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 -‘<samp><span class="samp">C-x 2</span></samp>’ 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 ‘<samp><span class="samp">*Completions*</span></samp>’ and ‘<samp><span class="samp">*Footnotes*</span></samp>’ are <em>not</em> -resized through automatic tiling; they remain their original size. - - <p><a name="cursor_002dmovement_002dscrolls"></a><br><dt><code>cursor-movement-scrolls</code><dd>Normally, cursor movement commands (see <a href="#Cursor-Commands">Cursor Commands</a>) stop when -top or bottom of a node is reached. When this variable is set to -<code>On</code>, cursor movement commands act as scrolling ones and their -behavior is controlled by the <code>scroll-behavior</code> variable (see below). - - <br><dt><code>errors-ring-bell</code><dd><a name="index-errors_002dring_002dbell-369"></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-370"></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-371"></a><a name="index-ISO_002dLatin-372"></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. - - <p><a name="scroll_002dbehavior"></a><br><dt><code>scroll-behavior</code><dt><code>scroll-behaviour</code><dd><a name="index-scroll_002dbehavior-373"></a><a name="index-scroll_002dbehaviour-374"></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 -‘<samp><span class="samp">Next</span></samp>’ node, or failing that, the ‘<samp><span class="samp">Next</span></samp>’ of the ‘<samp><span class="samp">Up</span></samp>’. -This behavior is identical to using the ‘<samp><span class="samp">]</span></samp>’ -(<code>global-next-node</code>) and ‘<samp><span class="samp">[</span></samp>’ (<code>global-prev-node</code>) -commands. - - <br><dt><code>scroll-last-node</code><dd><a name="index-scroll_002dlast_002dnode-375"></a>Control what happens when a scrolling command is issued at the end of -the last node. Possible values are: - - <dl> -<dt><code>Stop</code><dd>Do not scroll. Display the ‘<samp><span class="samp">No more nodes within this document.</span></samp>’ -message. This is the default. - - <br><dt><code>Scroll</code><dd>Scroll as usual. Since the last node is usually an index, this means -that the very first node from the menu will be selected. - - <br><dt><code>Top</code><dd>Go to the top node of this document. -</dl> - - <p>This variable is in effect only if <code>scroll-behaviour</code> is set to -<code>Continuous</code>. - - <p>Notice that the default behavior has changed in version 4.12. Previous -versions behaved as if <code>scroll-last-node=Scroll</code> was set. This -behavior was counter-intuitive, therefore since version 4.12 the -default is to stop at the last node. - - <br><dt><code>Next Only</code><dd>Only try to get the ‘<samp><span class="samp">Next</span></samp>’ 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> - - <p>This variable normally affects only scrolling commands. -See <a href="#cursor_002dmovement_002dscrolls">cursor-movement-scrolls</a>, for information on how to widen its -scope. - - <p>The two names, <code>scroll-behavior</code> and <code>scroll-behaviour</code>, are -a historical accident. They are merely synonyms. - - <br><dt><code>scroll-step</code><dd><a name="index-scroll_002dstep-376"></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-377"></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-378"></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="#Index">Index</a>, -Previous: <a rel="previous" accesskey="p" href="#Variables">Variables</a>, -Up: <a rel="up" accesskey="u" href="#Top">Top</a> - -</div> - -<h2 class="chapter">12 Customizing Key Bindings and Variables</h2> - -<p><a name="index-default-key-bindings_002c-overriding-379"></a><a name="index-overriding-default-key-bindings-380"></a><a name="index-customizing-key-bindings-381"></a><a name="index-key-bindings_002c-customizing-382"></a><a name="index-infokey-383"></a><a name="index-g_t_002einfo-384"></a><a name="index-g_t_002einfokey-385"></a><a name="index-g_t_005finfo-file-_0028MS_002dDOS_0029-386"></a> -GNU Info provides a way to define arbitrary key-to-command bindings -and variable settings, overriding the defaults described in this -document. (The <samp><span class="option">--vi-keys</span></samp> option rebinds many keys at once; -see <a href="#g_t_002d_002dvi_002dkeys">–vi-keys</a>.) - - <p>On startup, GNU Info looks for a configuration file in the invoker's -HOME directory called <samp><span class="file">.info</span></samp><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 <samp><span class="file">.info</span></samp> 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> - -</div> - -<h3 class="section">12.1 Invoking <samp><span class="command">infokey</span></samp></h3> - -<p><a name="index-invoking-infokey-387"></a><a name="index-infokey_002c-invoking-388"></a><a name="index-g_t_005finfokey-file-_0028MS_002dDOS_0029-389"></a> -<samp><span class="command">infokey</span></samp> compiles a source file -(<samp><span class="file">$HOME/.infokey</span></samp><a rel="footnote" href="#fn-8" name="fnd-8"><sup>8</sup></a> by default) containing Info customizations -into a binary format (<samp><span class="file">$HOME/.info</span></samp> 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 <samp><span class="option">--help</span></samp> and <samp><span class="option">--version</span></samp>, the only -option is <samp><span class="option">--output </span><var>file</var></samp>. This tells <samp><span class="command">infokey</span></samp> to -write the binary data to <var>file</var> instead of <samp><span class="file">$HOME/.info</span></samp>. - -<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> - -</div> - -<h3 class="section">12.2 <samp><span class="command">infokey</span></samp> source format</h3> - -<p><a name="index-infokey-source-format-390"></a><a name="index-g_t_002einfokey-source-format-391"></a><a name="index-format-of-_002einfokey-source-392"></a> -The format of the source file read by <samp><span class="command">infokey</span></samp> is most easily -illustrated by example. For instance, here is a sample <samp><span class="file">.infokey</span></samp> -source file suitable for aficionados of <samp><span class="command">vi</span></samp> or <samp><span class="command">less</span></samp>: - -<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 <samp><span class="file">.info</span></samp> file take precedence over GNU -Info's default key bindings, whether or not ‘<samp><span class="samp">--vi-keys</span></samp>’ is used. A -default key binding may be disabled by overriding it in the <samp><span class="file">.info</span></samp> -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 <samp><span class="file">.info</span></samp> 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="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> - -</div> - -<h2 class="appendix">Appendix A Index</h2> - -<ul class="index-cp" compact> -<li><a href="#index-g_t_0027_002c-vi_002dlike-operation-137"><code>', vi-like operation</code></a>: <a href="#Node-Commands">Node Commands</a></li> -<li><a href="#index-g_t_002c-202"><code>,</code></a>: <a href="#Searching-Commands">Searching Commands</a></li> -<li><a href="#index-g_t_002d-344"><code>-</code></a>: <a href="#Miscellaneous-Commands">Miscellaneous Commands</a></li> -<li><a href="#index-g_t_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-g_t_002einfo-384">.info</a>: <a href="#Custom-Key-Bindings">Custom Key Bindings</a></li> -<li><a href="#index-g_t_002einfokey-385">.infokey</a>: <a href="#Custom-Key-Bindings">Custom Key Bindings</a></li> -<li><a href="#index-g_t_002einfokey-source-format-391">.infokey source format</a>: <a href="#infokey-source-format">infokey source format</a></li> -<li><a href="#index-g_t_002f-175"><code>/</code></a>: <a href="#Searching-Commands">Searching Commands</a></li> -<li><a href="#index-g_t0-_0040dots_007b_007d-9_002c-vi_002dlike-operation-341"><code>0 ... 9, vi-like operation</code></a>: <a href="#Miscellaneous-Commands">Miscellaneous Commands</a></li> -<li><a href="#index-g_t0_002c-in-Info-windows-212"><code>0, in Info windows</code></a>: <a href="#Selecting-Xrefs">Selecting Xrefs</a></li> -<li><a href="#index-g_t1-_0040dots_007b_007d-9_002c-in-Info-windows-207">1 <small class="dots">...</small> 9, in Info windows</a>: <a href="#Selecting-Xrefs">Selecting Xrefs</a></li> -<li><a href="#index-g_t_003c-145"><code><</code></a>: <a href="#Node-Commands">Node Commands</a></li> -<li><a href="#index-g_t_003e-148"><code>></code></a>: <a href="#Node-Commands">Node Commands</a></li> -<li><a href="#index-g_t_003f_002c-in-Info-windows-330"><code>?, in Info windows</code></a>: <a href="#Miscellaneous-Commands">Miscellaneous Commands</a></li> -<li><a href="#index-g_t_003f_002c-in-the-echo-area-314"><code>?, in the echo area</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> -<li><a href="#index-g_t_003f_002c-vi_002dlike-operation-178"><code>?, vi-like operation</code></a>: <a href="#Searching-Commands">Searching Commands</a></li> -<li><a href="#index-g_t_005b-153"><code>[</code></a>: <a href="#Node-Commands">Node Commands</a></li> -<li><a href="#index-g_t_005d-151"><code>]</code></a>: <a href="#Node-Commands">Node Commands</a></li> -<li><a href="#index-g_t_005finfo-file-_0028MS_002dDOS_0029-386">_info file (MS-DOS)</a>: <a href="#Custom-Key-Bindings">Custom Key Bindings</a></li> -<li><a href="#index-g_t_005finfokey-file-_0028MS_002dDOS_0029-389">_infokey file (MS-DOS)</a>: <a href="#Invoking-infokey">Invoking infokey</a></li> -<li><a href="#index-abort_002dkey-352"><code>abort-key</code></a>: <a href="#Miscellaneous-Commands">Miscellaneous Commands</a></li> -<li><a href="#index-add_002ddigit_002dto_002dnumeric_002darg-342"><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-346">arguments, negative</a>: <a href="#Miscellaneous-Commands">Miscellaneous Commands</a></li> -<li><a href="#index-automatic_002dfootnotes-367"><code>automatic-footnotes</code></a>: <a href="#Variables">Variables</a></li> -<li><a href="#index-automatic_002dtiling-368"><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-228"><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-293"><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-261"><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-258"><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-274"><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-264"><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-253"><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-350"><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-279"><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-329"><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-302"><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-273"><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-284"><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-196"><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-270"><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-193"><code>C-s</code></a>: <a href="#Searching-Commands">Searching Commands</a></li> -<li><a href="#index-C_002dt_002c-in-the-echo-area-294"><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-338"><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-351"><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-280"><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-285"><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-241"><code>C-x 0</code></a>: <a href="#Basic-Windows">Basic Windows</a></li> -<li><a href="#index-C_002dx-1-243"><code>C-x 1</code></a>: <a href="#Basic-Windows">Basic Windows</a></li> -<li><a href="#index-C_002dx-2-238"><code>C-x 2</code></a>: <a href="#Basic-Windows">Basic Windows</a></li> -<li><a href="#index-C_002dx-_005e-247"><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-355"><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-304"><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-190"><code>C-x N</code></a>: <a href="#Searching-Commands">Searching Commands</a></li> -<li><a href="#index-C_002dx-n-186"><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-234"><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-221"><code>C-x r, vi-like operation</code></a>: <a href="#Selecting-Xrefs">Selecting Xrefs</a></li> -<li><a href="#index-C_002dx-t-250"><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-306"><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-349">cancelling the current operation</a>: <a href="#Miscellaneous-Commands">Miscellaneous Commands</a></li> -<li><a href="#index-cancelling-typeahead-348">cancelling typeahead</a>: <a href="#Miscellaneous-Commands">Miscellaneous Commands</a></li> -<li><a href="#index-case_002dsensitive-search-185">case-sensitive search</a>: <a href="#Searching-Commands">Searching Commands</a></li> -<li><a href="#index-case_002dsensitivity_002c-and-search-206">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-324">commands, describing</a>: <a href="#Miscellaneous-Commands">Miscellaneous Commands</a></li> -<li><a href="#index-completion-310">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-381">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-379">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-277"><code>DEL, in the echo area</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> -<li><a href="#index-delete_002dwindow-242"><code>delete-window</code></a>: <a href="#Basic-Windows">Basic Windows</a></li> -<li><a href="#index-describe_002dcommand-325"><code>describe-command</code></a>: <a href="#Miscellaneous-Commands">Miscellaneous Commands</a></li> -<li><a href="#index-describe_002dkey-327"><code>describe-key</code></a>: <a href="#Miscellaneous-Commands">Miscellaneous Commands</a></li> -<li><a href="#index-describe_002dvariable-366"><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-252">echo area</a>: <a href="#The-Echo-Area">The Echo Area</a></li> -<li><a href="#index-echo_002darea_002dabort-281"><code>echo-area-abort</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> -<li><a href="#index-echo_002darea_002dbackward-260"><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-305"><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-300"><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-272"><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-263"><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-313"><code>echo-area-complete</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> -<li><a href="#index-echo_002darea_002ddelete-276"><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-266"><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-256"><code>echo-area-forward</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> -<li><a href="#index-echo_002darea_002dforward_002dword-269"><code>echo-area-forward-word</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> -<li><a href="#index-echo_002darea_002dinsert-288"><code>echo-area-insert</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> -<li><a href="#index-echo_002darea_002dkill_002dline-303"><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-298"><code>echo-area-kill-word</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> -<li><a href="#index-echo_002darea_002dnewline-283"><code>echo-area-newline</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> -<li><a href="#index-echo_002darea_002dpossible_002dcompletions-315"><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-286"><code>echo-area-quoted-insert</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> -<li><a href="#index-echo_002darea_002drubout-278"><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-317"><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-291"><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-295"><code>echo-area-transpose-chars</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> -<li><a href="#index-echo_002darea_002dyank-307"><code>echo-area-yank</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> -<li><a href="#index-echo_002darea_002dyank_002dpop-309"><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-369"><code>errors-ring-bell</code></a>: <a href="#Variables">Variables</a></li> -<li><a href="#index-ESC-C_002df-360"><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-245"><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-316"><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-218"><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-331"><code>F1</code></a>: <a href="#Miscellaneous-Commands">Miscellaneous Commands</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-217"><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-362">footnotes, displaying</a>: <a href="#Miscellaneous-Commands">Miscellaneous Commands</a></li> -<li><a href="#index-format-of-_002einfokey-source-392">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-323">functions, describing</a>: <a href="#Miscellaneous-Commands">Miscellaneous 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-155"><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-370"><code>gc-compressed-files</code></a>: <a href="#Variables">Variables</a></li> -<li><a href="#index-get_002dhelp_002dwindow-333"><code>get-help-window</code></a>: <a href="#Miscellaneous-Commands">Miscellaneous Commands</a></li> -<li><a href="#index-get_002dinfo_002dhelp_002dnode-336"><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-248"><code>grow-window</code></a>: <a href="#Basic-Windows">Basic Windows</a></li> -<li><a href="#index-h-334"><code>h</code></a>: <a href="#Miscellaneous-Commands">Miscellaneous Commands</a></li> -<li><a href="#index-h_002c-vi_002dlike-operation-332"><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-198"><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-195">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-200">index, searching</a>: <a href="#Searching-Commands">Searching Commands</a></li> -<li><a href="#index-index_002dapropos-204"><code>index-apropos</code></a>: <a href="#Searching-Commands">Searching Commands</a></li> -<li><a href="#index-index_002dsearch-199"><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-320">INFO_PRINT_COMMAND, environment variable</a>: <a href="#Printing-Nodes">Printing Nodes</a></li> -<li><a href="#index-infokey-383">infokey</a>: <a href="#Custom-Key-Bindings">Custom Key Bindings</a></li> -<li><a href="#index-infokey-source-format-390">infokey source format</a>: <a href="#infokey-source-format">infokey source format</a></li> -<li><a href="#index-infokey_002c-invoking-388">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-387">invoking infokey</a>: <a href="#Invoking-infokey">Invoking infokey</a></li> -<li><a href="#index-isearch_002dbackward-197"><code>isearch-backward</code></a>: <a href="#Searching-Commands">Searching Commands</a></li> -<li><a href="#index-isearch_002dforward-194"><code>isearch-forward</code></a>: <a href="#Searching-Commands">Searching Commands</a></li> -<li><a href="#index-ISO-Latin-characters-371">ISO Latin characters</a>: <a href="#Variables">Variables</a></li> -<li><a href="#index-ISO_002dLatin-372"><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-244"><code>keep-one-window</code></a>: <a href="#Basic-Windows">Basic Windows</a></li> -<li><a href="#index-key-bindings_002c-customizing-382">key bindings, customizing</a>: <a href="#Custom-Key-Bindings">Custom Key Bindings</a></li> -<li><a href="#index-keys_002c-describing-326">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-214"><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-257"><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-322">local printer device</a>: <a href="#Printing-Nodes">Printing Nodes</a></li> -<li><a href="#index-m-215"><code>m</code></a>: <a href="#Selecting-Xrefs">Selecting Xrefs</a></li> -<li><a href="#index-M_002d_0024_002c-vi_002dlike-operation-265"><code>M-$, vi-like operation</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> -<li><a href="#index-M_002d_002d-343"><code>M--</code></a>: <a href="#Miscellaneous-Commands">Miscellaneous Commands</a></li> -<li><a href="#index-M_002d0-_0040dots_007b_007d-M_002d9-340"><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-262"><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-213"><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-208">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-271"><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-301"><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-296"><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-299"><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-267"><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-220"><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-230"><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-255"><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-335"><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-259"><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-225"><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-289"><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-268"><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-297"><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-275"><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-308"><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-211"><code>menu-digit</code></a>: <a href="#Selecting-Xrefs">Selecting Xrefs</a></li> -<li><a href="#index-menu_002ditem-216"><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-224"><code>move-to-next-xref</code></a>: <a href="#Selecting-Xrefs">Selecting Xrefs</a></li> -<li><a href="#index-move_002dto_002dprev_002dxref-226"><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-187"><code>n, vi-like operation</code></a>: <a href="#Searching-Commands">Searching Commands</a></li> -<li><a href="#index-negative-arguments-345">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-203"><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-235"><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-337">numeric arguments</a>: <a href="#Miscellaneous-Commands">Miscellaneous Commands</a></li> -<li><a href="#index-numeric-arguments_002c-negative-347">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-380">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-236"><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-319"><code>print-node</code></a>: <a href="#Printing-Nodes">Printing Nodes</a></li> -<li><a href="#index-printing-318">printing</a>: <a href="#Printing-Nodes">Printing Nodes</a></li> -<li><a href="#index-printing-characters_002c-in-the-echo-area-287"><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-321">printing nodes to the local printer</a>: <a href="#Printing-Nodes">Printing Nodes</a></li> -<li><a href="#index-q-354"><code>q</code></a>: <a href="#Miscellaneous-Commands">Miscellaneous Commands</a></li> -<li><a href="#index-quit-357"><code>quit</code></a>: <a href="#Miscellaneous-Commands">Miscellaneous Commands</a></li> -<li><a href="#index-quitting-353">quitting</a>: <a href="#Miscellaneous-Commands">Miscellaneous Commands</a></li> -<li><a href="#index-r-219"><code>r</code></a>: <a href="#Selecting-Xrefs">Selecting Xrefs</a></li> -<li><a href="#index-R-180"><code>R</code></a>: <a href="#Searching-Commands">Searching Commands</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-regular-expression-search-177">regular expression search</a>: <a href="#Searching-Commands">Searching 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-189">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-229"><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-282"><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-254"><code>RIGHT, in the echo area</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> -<li><a href="#index-S-182"><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-359">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-373"><code>scroll-behavior</code></a>: <a href="#Variables">Variables</a></li> -<li><a href="#index-scroll_002dbehaviour-374"><code>scroll-behaviour</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_002dlast_002dnode-375"><code>scroll-last-node</code></a>: <a href="#Variables">Variables</a></li> -<li><a href="#index-scroll_002dother_002dwindow-246"><code>scroll-other-window</code></a>: <a href="#Basic-Windows">Basic Windows</a></li> -<li><a href="#index-scroll_002dstep-376"><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-205">search, and case-sensitivity</a>: <a href="#Searching-Commands">Searching Commands</a></li> -<li><a href="#index-search_002c-case_002dsensitive-184">search, case-sensitive</a>: <a href="#Searching-Commands">Searching Commands</a></li> -<li><a href="#index-search_002dbackward-179"><code>search-backward</code></a>: <a href="#Searching-Commands">Searching Commands</a></li> -<li><a href="#index-search_002dcase_002dsensitively-183"><code>search-case-sensitively</code></a>: <a href="#Searching-Commands">Searching Commands</a></li> -<li><a href="#index-search_002dnext-188"><code>search-next</code></a>: <a href="#Searching-Commands">Searching Commands</a></li> -<li><a href="#index-search_002dprevious-192"><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-201">searching, in the indices</a>: <a href="#Searching-Commands">Searching Commands</a></li> -<li><a href="#index-select_002dreference_002dthis_002dline-231"><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-358"><code>set-screen-height</code></a>: <a href="#Miscellaneous-Commands">Miscellaneous Commands</a></li> -<li><a href="#index-set_002dvariable-364"><code>set-variable</code></a>: <a href="#Variables">Variables</a></li> -<li><a href="#index-Shift_002dTAB_002c-in-Info-windows-227"><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-290"><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-361"><code>show-footnotes</code></a>: <a href="#Miscellaneous-Commands">Miscellaneous Commands</a></li> -<li><a href="#index-show_002dindex_002dmatch-377"><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-312"><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-239"><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-223"><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-311"><code>TAB, in the echo area</code></a>: <a href="#The-Echo-Area">The Echo Area</a></li> -<li><a href="#index-tile_002dwindows-251"><code>tile-windows</code></a>: <a href="#Basic-Windows">Basic Windows</a></li> -<li><a href="#index-tiling-249">tiling</a>: <a href="#Basic-Windows">Basic Windows</a></li> -<li><a href="#index-toggle_002dregexp-181"><code>toggle-regexp</code></a>: <a href="#Searching-Commands">Searching Commands</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-339"><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-365">variables, describing</a>: <a href="#Variables">Variables</a></li> -<li><a href="#index-variables_002c-setting-363">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-378"><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-328"><code>where-is</code></a>: <a href="#Miscellaneous-Commands">Miscellaneous Commands</a></li> -<li><a href="#index-windows_002c-creating-237">windows, creating</a>: <a href="#Basic-Windows">Basic Windows</a></li> -<li><a href="#index-windows_002c-deleting-240">windows, deleting</a>: <a href="#Basic-Windows">Basic Windows</a></li> -<li><a href="#index-windows_002c-manipulating-232">windows, manipulating</a>: <a href="#Window-Commands">Window Commands</a></li> -<li><a href="#index-windows_002c-selecting-233">windows, selecting</a>: <a href="#Basic-Windows">Basic Windows</a></li> -<li><a href="#index-xref_002ditem-222"><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-356"><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> -<samp><span class="file">.info</span></samp>, <samp><span class="file">-info</span></samp>, <samp><span class="file">/index</span></samp>, and <samp><span class="file">.inf</span></samp>.</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 <samp><span class="file">.z</span></samp> and <samp><span class="file">.gz</span></samp>, 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 <samp><span class="file">bison</span></samp>, -file names like <samp><span class="file">bison.igz</span></samp> and <samp><span class="file">bison.inz</span></samp> 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</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 -<samp><span class="file">_info</span></samp> instead. If the <samp><span class="env">HOME</span></samp> 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 <samp><span class="file">_infokey</span></samp> in -the MS-DOS version, and is looked for in the current directory if -<samp><span class="env">HOME</span></samp> is undefined.</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 differdeleted file mode 100644 index bfeb98aaff3..00000000000 --- a/Master/texmf/doc/texinfo/info-stnd.pdf +++ /dev/null diff --git a/Master/texmf/doc/texinfo/info.html b/Master/texmf/doc/texinfo/info.html deleted file mode 100644 index e8379e0a216..00000000000 --- a/Master/texmf/doc/texinfo/info.html +++ /dev/null @@ -1,1619 +0,0 @@ -<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.12"> -<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, 2005, 2006, 2007, 2008 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.2 or any later version published by the Free Software - Foundation; with no Invariant Sections, with the Front-Cover texts - being "A GNU Manual," and with the Back-Cover Texts as in (a) - below. A copy of the license is included in the section entitled - "GNU Free Documentation License" 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. Buying copies from GNU - Press supports the FSF in developing GNU and promoting software - freedom." - - 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; } - span.sansserif { font-family:sans-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><a href="#Help_002dQ">1.9 Quitting Info</a> -</li></ul> -<li><a name="toc_Advanced" href="#Advanced">2 Advanced Info Commands</a> -<ul> -<li><a href="#Search-Text">2.1 <kbd>s</kbd> searches Info documents</a> -<li><a href="#Search-Index">2.2 <kbd>i</kbd> searches the indices for specific subjects</a> -<li><a href="#Go-to-node">2.3 <kbd>g</kbd> goes to a node by name</a> -<li><a href="#Choose-menu-subtopic">2.4 <kbd>1</kbd>–<kbd>9</kbd> choose a menu subtopic by its number</a> -<li><a href="#Create-Info-buffer">2.5 <kbd>M-n</kbd> creates a new independent Info buffer in Emacs</a> -<li><a href="#Emacs-Info-Variables">2.6 Emacs Info-mode Variables</a> -</li></ul> -<li><a name="toc_Expert-Info" href="#Expert-Info">3 Info for Experts</a> -<ul> -<li><a href="#Add">3.1 Adding a new node to Info</a> -<li><a href="#Menus">3.2 How to Create Menus</a> -<li><a href="#Cross_002drefs">3.3 Creating Cross References</a> -<ul> -<li><a href="#Help_002dCross">3.3.1 The node reached by the cross reference in Info</a> -</li></ul> -<li><a href="#Tags">3.4 Tags Tables for Info Files</a> -<li><a href="#Checking">3.5 Checking an Info File</a> -</li></ul> -<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> - -</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. - - <p>There are two primary Info readers: <code>info</code>, a stand-alone program -designed just to read Info files, and the <code>info</code> package in GNU -Emacs, a general-purpose editor. At present, only the Emacs reader -supports using a mouse. - -<ul class="menu"> -<li><a accesskey="1" href="#Getting-Started">Getting Started</a>: Getting started using an Info reader. -<li><a accesskey="2" href="#Advanced">Advanced</a>: Advanced Info commands. -<li><a accesskey="3" href="#Expert-Info">Expert Info</a>: Info commands for experts. -<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="#Advanced">Advanced</a>, -Previous: <a rel="previous" accesskey="p" href="#Top">Top</a>, -Up: <a rel="up" accesskey="u" href="#Top">Top</a> - -</div> - -<!-- node-name, next, previous, up --> -<h2 class="chapter">1 Getting Started</h2> - -<p>This first part of this Info manual describes how to get around inside -of Info. The second part of the manual describes various advanced -Info commands. The third part briefly explains how to generate Info -files from Texinfo files, and describes how to write an Info file -by hand. - - <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 editor. - </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-Small-Screen"></a> -<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> - -</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 the entire text you are looking at fits on the screen, the text -‘<samp><span class="samp">All</span></samp>’ will be displayed at the bottom of the screen. In the -stand-alone Info reader, it is displayed at the bottom right corner of -the screen; in Emacs, it is displayed on the modeline. If you see the -text ‘<samp><span class="samp">Top</span></samp>’ 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 ‘<samp><span class="samp">Backspace</span></samp>’ or ‘<samp><span class="samp">DEL</span></samp>’ (on some keyboards, this key -might be labeled ‘<samp><span class="samp">Delete</span></samp>’). - -<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> - -</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 -<samp><span class="command">info</span></samp>. - - <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 ‘<samp><span class="samp">Help</span></samp>’ in the file <samp><span class="file">info</span></samp>. - - <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 ‘<samp><span class="samp">Next</span></samp>’ node after this one is the -node called ‘<samp><span class="samp">Help-P</span></samp>’. 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 displayed with a special typeface, -and remains at the top of the window all the time even if you scroll -through the node. - - <p>Besides a ‘<samp><span class="samp">Next</span></samp>’, a node can have a ‘<samp><span class="samp">Previous</span></samp>’ link, or an -‘<samp><span class="samp">Up</span></samp>’ link, 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 ‘<samp><span class="samp">Next</span></samp>’ node, named ‘<samp><span class="samp">Help-P</span></samp>’. - -<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">‘<samp><span class="samp">>></span></samp>’ 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 left - mouse button on the ‘<samp><span class="samp">Next</span></samp>’ link to do the same “the mouse way”. -</pre> - <div class="node"> -<p><hr> -<a name="Help-P"></a> -<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> - -</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 ‘<samp><span class="samp">Help-P</span></samp>’. The ‘<samp><span class="samp">Previous</span></samp>’ node, as you see, -is ‘<samp><span class="samp">Help</span></samp>’, 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, ‘<samp><span class="samp">Help-^L</span></samp>’. - -<pre class="format">>> But do not type <kbd>n</kbd> yet. First, try the <kbd>p</kbd> command, or - (in Emacs) click on the ‘<samp><span class="samp">Prev</span></samp>’ link. That takes you to - the ‘<samp><span class="samp">Previous</span></samp>’ node. Then use <kbd>n</kbd> to return here. -</pre> - <p>If you read this in Emacs, you will see an ‘<samp><span class="samp">Info</span></samp>’ item in the -menu bar, close to its right edge. Clicking the mouse on the -‘<samp><span class="samp">Info</span></samp>’ menu-bar item opens a menu of commands which include -‘<samp><span class="samp">Next</span></samp>’ and ‘<samp><span class="samp">Previous</span></samp>’ (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 (in Emacs) click the middle mouse button on - the ‘<samp><span class="samp">Next</span></samp>’ link, to get to the node ‘<samp><span class="samp">Help-^L</span></samp>’ and learn more. -</pre> - <div class="node"> -<p><hr> -<a name="Help-%5eL"></a> -<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> - -</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 -‘<samp><span class="samp">Help-^L</span></samp>’, and the header line tells you that <kbd>p</kbd> would get -you back to ‘<samp><span class="samp">Help-P</span></samp>’. 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 text ‘<samp><span class="samp">Top</span></samp>’ rather than ‘<samp><span class="samp">All</span></samp>’ near the bottom 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 ‘<samp><span class="samp">Next</span></samp>’, ‘<samp><span class="samp">Prev</span></samp>’, and ‘<samp><span class="samp">Up</span></samp>’ 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 ‘<samp><span class="samp">PageUp</span></samp>’ -and ‘<samp><span class="samp">PageDown</span></samp>’ (or maybe ‘<samp><span class="samp">Prior</span></samp>’ and ‘<samp><span class="samp">Next</span></samp>’). 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><a name="index-g_t_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 -<kbd>?</kbd>, which displays a brief list of commands. When you are -finished looking at the list, make it go away by typing <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>; that's 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 ‘<samp><span class="samp">Next</span></samp>’ link, - to visit the next node. -</pre> - <div class="node"> -<p><hr> -<a name="Help-Inv"></a> -<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> - -</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 ‘<samp><span class="samp">invisibility</span></samp>’ -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 ‘<samp><span class="samp">display</span></samp>’ property. Only the -invisibility property is affected by Visible mode. When, in this -tutorial, we refer to the ‘<samp><span class="samp">Emacs</span></samp>’ 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-%5d"></a> -<a name="Help_002d_005d"></a> -Up: <a rel="up" accesskey="u" href="#Help_002dInv">Help-Inv</a> - -</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-M"></a> -<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> - -</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 ‘<samp><span class="samp">* Menu:</span></samp>’<!-- /@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 ‘<samp><span class="samp">*</span></samp>’ -identifies one subtopic. The line usually contains a brief name for -the subtopic (followed by a ‘<samp><span class="samp">:</span></samp>’, 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 ‘<samp><span class="samp">*</span></samp>’ 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 ‘<samp><span class="samp">Node -about FOO</span></samp>’. 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 ‘<samp><span class="samp">* Menu:</span></samp>’<!-- /@w -->. Also, -in a real menu item, the ‘<samp><span class="samp">*</span></samp>’ would appear at the very start of -the line. This is why the “normally hidden” text in Emacs, namely -‘<samp><span class="samp">: Node about FOO.</span></samp>’, 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 ‘<samp><span class="samp">Foo</span></samp>’. (The ‘<samp><span class="samp">::</span></samp>’ 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 ‘<samp><span class="samp">Menu item: </span></samp>’. -You must then type the name of the subtopic you want, and end it with -a <RET>. - - <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 ‘<samp><span class="samp">R</span></samp>’. You could type another <kbd>R</kbd> - to replace it. But you do not have to, since ‘<samp><span class="samp">BA</span></samp>’ is a valid - abbreviation. -</pre> - <pre class="format">>> Now you are ready to go. Type a <RET>. -</pre> - <p>After visiting ‘<samp><span class="samp">Help-FOO</span></samp>’, 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 in the -stand-alone reader, 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 ‘<samp><span class="samp">Alt</span></samp>’.) In Emacs Info, type -<kbd>S-<TAB></kbd> to move to a previous subtopic line (press and hold -the <Shift> key and then press <TAB>). - - <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 ‘<samp><span class="samp">*</span></samp>’ and the colon ‘<samp><span class="samp">:</span></samp>’ 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-FOO"></a> -<a name="Help_002dFOO"></a> -Up: <a rel="up" accesskey="u" href="#Help_002dM">Help-M</a> - -</div> - -<h4 class="subsection">1.6.1 The <kbd>u</kbd> command</h4> - -<p>Congratulations! This is the node ‘<samp><span class="samp">Help-FOO</span></samp>’. It has an ‘<samp><span class="samp">Up</span></samp>’ -pointer ‘<samp><span class="samp">Help-M</span></samp>’, 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 ‘<samp><span class="samp">Up</span></samp>’ nodes that lead back to the menu. Menus move Down in the -tree, and ‘<samp><span class="samp">Up</span></samp>’ moves Up. ‘<samp><span class="samp">Previous</span></samp>’, 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 ‘<samp><span class="samp">Help-M</span></samp>’ by typing the command -<kbd>u</kbd> for “Up”. This puts you at the menu subtopic line pointing -to the subnode that the <kbd>u</kbd> command brought you from. (Some Info -readers may put you at the <em>front</em> of the node instead—to get -back to where you were reading, you have to type some <SPC>s.) - - <p>Another way to go Up is to click <kbd>Mouse-2</kbd> on the ‘<samp><span class="samp">Up</span></samp>’ -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 ‘<samp><span class="samp">Help-M</span></samp>’. -</pre> - <div class="node"> -<p><hr> -<a name="Help-Xref"></a> -<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> - -</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 ‘<samp><span class="samp">Cross</span></samp>’ and which -points to the node named ‘<samp><span class="samp">Help-Cross</span></samp>’. (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> You can follow a cross reference by moving the cursor to it and -press <RET>, just as in a menu. In Emacs, you can also click -<kbd>Mouse-1</kbd> on a cross reference to follow it; 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. - - <p>Another way to follow a cross reference is to type <kbd>f</kbd> and then -specify the name of the cross reference (in this case, ‘<samp><span class="samp">Cross</span></samp>’) -as an argument. For this command, 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 ‘<samp><span class="samp">f</span></samp>’ gives up. -</pre> - <p>The <TAB>, <kbd>M-<TAB></kbd> and <kbd>S-<TAB></kbd> keys, -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</a>. (After following this link, type -<kbd>l</kbd> to get back to this node.) Here the name ‘<samp><span class="samp">texinfo</span></samp>’ -between parentheses refers to the file name. This file name appears -in cross references and node names if it differs from the current -file, so you can always know that you are going to be switching to -another manual and which one. - - <p>However, Emacs normally hides some other text in cross-references. -If you put your mouse over the cross reference, then the information -appearing in a separate box (tool tip) or in the echo area will show -the full cross-reference including the file name and the node name of -the cross reference. If you have a mouse, just leave it over the -cross reference See <a href="texinfo.html#Top">Overview of Texinfo</a>, and watch what happens. If you -always like to have that information visible without having to move -your mouse over the cross reference, use <kbd>M-x visible-mode</kbd>, or -set <code>Info-hide-note-references</code> to a value other than <code>t</code> -(see <a href="#Emacs-Info-Variables">Emacs Info Variables</a>). - -<pre class="format">>> Now type <kbd>n</kbd> to learn more commands. -</pre> - <div class="node"> -<p><hr> -<a name="Help-Int"></a> -<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> - -</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 and the name of the index node; 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="#Search-Index">Search Index</a>, for a full explanation. - - <p><a name="index-l-_0040r_007b_0028Info-mode_0029_007d-37"></a><a name="index-Info_002dhistory_002dback-38"></a><a name="index-going-back-in-Info-history-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. - -<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 ‘<samp><span class="samp">Previous</span></samp>’ node (from this node, the -‘<samp><span class="samp">Prev</span></samp>’ link leads to ‘<samp><span class="samp">Help-Xref</span></samp>’). - - <p><a name="index-r-_0040r_007b_0028Info-mode_0029_007d-40"></a><a name="index-Info_002dhistory_002dforward-41"></a><a name="index-going-forward-in-Info-history-42"></a> You can use the <kbd>r</kbd> command (<code>Info-history-forward</code> in Emacs) -to revisit nodes in the history list in the forward direction, so that -<kbd>r</kbd> will return you to the node you came from by typing <kbd>l</kbd>. - - <p><a name="index-L-_0040r_007b_0028Info-mode_0029_007d-43"></a><a name="index-Info_002dhistory-44"></a><a name="index-history-list-of-visited-nodes-45"></a> The <kbd>L</kbd> command (<code>Info-history</code> in Emacs) creates a virtual -node that contains a list of all nodes you visited. You can select -a previously visited node from this menu to revisit it. - - <p><a name="index-d-_0040r_007b_0028Info-mode_0029_007d-46"></a><a name="index-Info_002ddirectory-47"></a><a name="index-go-to-Directory-node-48"></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-49"></a><a name="index-Info_002dtop_002dnode-50"></a><a name="index-go-to-Top-node-51"></a> The <kbd>t</kbd> command moves to the ‘<samp><span class="samp">Top</span></samp>’ 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>. - -<pre class="format">>> Now type <kbd>n</kbd> to see the last node of the course. -</pre> - <p>See <a href="#Advanced">Advanced</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="Help-Q"></a> -<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> - -</div> - -<!-- node-name, next, previous, up --> -<h3 class="section">1.9 Quitting Info</h3> - -<p><a name="index-q-_0040r_007b_0028Info-mode_0029_007d-52"></a><a name="index-Info_002dexit-53"></a><a name="index-quitting-Info-mode-54"></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="#Advanced">Advanced</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="Advanced"></a> -Next: <a rel="next" accesskey="n" href="#Expert-Info">Expert Info</a>, -Previous: <a rel="previous" accesskey="p" href="#Getting-Started">Getting Started</a>, -Up: <a rel="up" accesskey="u" href="#Top">Top</a> - -</div> - -<h2 class="chapter">2 Advanced Info Commands</h2> - -<p>This chapter describes various advanced Info commands. (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</a>.) - - <p><a name="index-C_002dq-_0040r_007b_0028Info-mode_0029_007d-55"></a> One advanced command useful with most of the others described here -is <kbd>C-q</kbd>, which “quotes” the next character so that it is -entered literally (see <a href="emacs.html#Inserting-Text">Inserting Text</a>). For example, pressing <kbd>?</kbd> ordinarily brings up a list -of completion possibilities. If you want to (for example) search for -an actual ‘<samp><span class="samp">?</span></samp>’ character, the simplest way is to insert it using -<kbd>C-q ?</kbd>. This works the same in Emacs and stand-alone Info. - -<ul class="menu"> -<li><a accesskey="1" href="#Search-Text">Search Text</a>: How to search Info documents. -<li><a accesskey="2" href="#Search-Index">Search Index</a>: How to search the indices for specific subjects. -<li><a accesskey="3" href="#Go-to-node">Go to node</a>: How to go to a node by name. -<li><a accesskey="4" href="#Choose-menu-subtopic">Choose menu subtopic</a>: How to choose a menu subtopic by its number. -<li><a accesskey="5" href="#Create-Info-buffer">Create Info buffer</a>: How to create a new Info buffer in Emacs. -<li><a accesskey="6" href="#Emacs-Info-Variables">Emacs Info Variables</a>: Variables modifying the behavior of Emacs Info. -</ul> - -<div class="node"> -<p><hr> -<a name="Search-Text"></a> -Next: <a rel="next" accesskey="n" href="#Search-Index">Search Index</a>, -Up: <a rel="up" accesskey="u" href="#Advanced">Advanced</a> - -</div> - -<!-- node-name, next, previous, up --> -<h3 class="section">2.1 <kbd>s</kbd> searches Info documents</h3> - -<p><a name="index-searching-Info-documents-56"></a><a name="index-Info-document-as-a-reference-57"></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 text or its indices. - - <p><a name="index-s-_0040r_007b_0028Info-mode_0029_007d-58"></a><a name="index-Info_002dsearch-59"></a> The <kbd>s</kbd> command allows you to search a whole Info 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 the file, which has no necessary relationship to the -order that they may be in the tree structure of menus and ‘<samp><span class="samp">next</span></samp>’ -pointers. But normally the two orders are not very different. In any -case, you can always look at the mode line 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-60"></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>. - - <p><a name="index-C_002ds-_0040r_007b_0028Info-mode_0029_007d-61"></a><a name="index-C_002dr-_0040r_007b_0028Info-mode_0029_007d-62"></a><a name="index-isearch-63"></a> Instead of using <kbd>s</kbd> in Emacs Info and in the stand-alone Info, -you can use an incremental search started with <kbd>C-s</kbd> or <kbd>C-r</kbd>. -It can search through multiple Info nodes. See <a href="emacs.html#Incremental-Search">Incremental Search</a>. In Emacs, you can disable this behavior -by setting the variable <code>Info-isearch-search</code> to <code>nil</code> -(see <a href="#Emacs-Info-Variables">Emacs Info Variables</a>). - -<div class="node"> -<p><hr> -<a name="Search-Index"></a> -Next: <a rel="next" accesskey="n" href="#Go-to-node">Go to node</a>, -Previous: <a rel="previous" accesskey="p" href="#Search-Text">Search Text</a>, -Up: <a rel="up" accesskey="u" href="#Advanced">Advanced</a> - -</div> - -<!-- node-name, next, previous, up --> -<h3 class="section">2.2 <kbd>i</kbd> searches the indices for specific subjects</h3> - -<p><a name="index-searching-Info-indices-64"></a><a name="index-i-_0040r_007b_0028Info-mode_0029_007d-65"></a><a name="index-Info_002dindex-66"></a> Since most topics in the manual should be indexed, you should try -the index search first before the text search. 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 and subsequent <kbd>,</kbd> commands find 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 Info 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-l</kbd> key does, type -<kbd>iC-l<RET></kbd> literally. - - <p><a name="index-info_002dapropos-67"></a><a name="index-index_002dapropos-68"></a>If you aren't sure which manual documents the topic you are looking -for, try the <kbd>M-x info-apropos</kbd> command in Emacs, or the <kbd>M-x -index-apropos</kbd> command in the stand-alone reader. It prompts for -a string and then looks up that string in all the indices of all the -Info documents installed on your system. - -<div class="node"> -<p><hr> -<a name="Go-to-node"></a> -Next: <a rel="next" accesskey="n" href="#Choose-menu-subtopic">Choose menu subtopic</a>, -Previous: <a rel="previous" accesskey="p" href="#Search-Index">Search Index</a>, -Up: <a rel="up" accesskey="u" href="#Advanced">Advanced</a> - -</div> - -<!-- node-name, next, previous, up --> -<h3 class="section">2.3 <kbd>g</kbd> goes to a node by name</h3> - -<p><a name="index-g-_0040r_007b_0028Info-mode_0029_007d-69"></a><a name="index-Info_002dgoto_002dnode-70"></a><a name="index-go-to-a-node-by-name-71"></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 ‘<samp><span class="samp">Top</span></samp>’ in this file. (This is equivalent to <kbd>t</kbd>, see -<a href="#Help_002dInt">Help-Int</a>.) <kbd>gGo to node<RET></kbd> would come back here. - - <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-72"></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 ‘<samp><span class="samp">Top</span></samp>’ in the Info file <samp><span class="file">dir</span></samp>. Likewise, -<kbd>g(emacs)Top<RET></kbd> goes to the top node of the Emacs manual. - - <p>The node name ‘<samp><span class="samp">*</span></samp>’ 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>. - -<div class="node"> -<p><hr> -<a name="Choose-menu-subtopic"></a> -Next: <a rel="next" accesskey="n" href="#Create-Info-buffer">Create Info buffer</a>, -Previous: <a rel="previous" accesskey="p" href="#Go-to-node">Go to node</a>, -Up: <a rel="up" accesskey="u" href="#Advanced">Advanced</a> - -</div> - -<!-- node-name, next, previous, up --> -<h3 class="section">2.4 <kbd>1</kbd>–<kbd>9</kbd> choose a menu subtopic by its number</h3> - -<p><a name="index-g_t1-_0040r_007bthrough_007d-9-_0040r_007b_0028Info-mode_0029_007d-73"></a><a name="index-Info_002dnth_002dmenu_002ditem-74"></a><a name="index-select-_0040var_007bn_007d_0027th-menu-item-75"></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. - - <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 ‘<samp><span class="samp">*</span></samp>’ 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. - -<div class="node"> -<p><hr> -<a name="Create-Info-buffer"></a> -Next: <a rel="next" accesskey="n" href="#Emacs-Info-Variables">Emacs Info Variables</a>, -Previous: <a rel="previous" accesskey="p" href="#Choose-menu-subtopic">Choose menu subtopic</a>, -Up: <a rel="up" accesskey="u" href="#Advanced">Advanced</a> - -</div> - -<!-- node-name, next, previous, up --> -<h3 class="section">2.5 <kbd>M-n</kbd> creates a new independent Info buffer in Emacs</h3> - -<p><a name="index-M_002dn-_0040r_007b_0028Info-mode_0029_007d-76"></a><a name="index-clone_002dbuffer-77"></a><a name="index-multiple-Info-buffers-78"></a> If you are reading Info in Emacs, you can select a new independent -Info buffer in a new Emacs 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. - - <p>Another way to produce new Info buffers in Emacs is to use a numeric -prefix argument for the <kbd>C-h i</kbd> command (<code>info</code>) which -switches to the Info buffer with that number. Thus, <kbd>C-u 2 C-h i</kbd> -switches to the buffer ‘<samp><span class="samp">*info*<2></span></samp>’, creating it if necessary. - -<div class="node"> -<p><hr> -<a name="Emacs-Info-Variables"></a> -Previous: <a rel="previous" accesskey="p" href="#Create-Info-buffer">Create Info buffer</a>, -Up: <a rel="up" accesskey="u" href="#Advanced">Advanced</a> - -</div> - -<!-- node-name, next, previous, up --> -<h3 class="section">2.6 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 init file. See <a href="emacs.html#Examining">Examining and Setting Variables</a>. The stand-alone Info reader program has its own set of -variables, described in <a href="info-stnd.html#Variables">Manipulating Variables</a>. - - <dl> -<dt><code>Info-directory-list</code><a name="index-Info_002ddirectory_002dlist-79"></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 <samp><span class="env">INFOPATH</span></samp> to -initialize it, or <code>Info-default-directory-list</code> if there is no -<samp><span class="env">INFOPATH</span></samp> 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 <samp><span class="env">INFOPATH</span></samp> -environment variable, since that applies to both programs. - - <br><dt><code>Info-additional-directory-list</code><a name="index-Info_002dadditional_002ddirectory_002dlist-80"></a><dd>A list of additional directories to search for Info documentation files. -These directories are not searched for merging the <samp><span class="file">dir</span></samp> file. - - <br><dt><code>Info-mode-hook</code><a name="index-Info_002dmode_002dhook-81"></a><dd>Hooks run when <code>Info-mode</code> is called. By default, it contains -the hook <code>turn-on-font-lock</code> which enables highlighting of Info -files. You can change how the highlighting looks by customizing the -faces <code>info-node</code>, <code>info-xref</code>, <code>info-xref-visited</code>, -<code>info-header-xref</code>, <code>info-header-node</code>, <code>info-menu-header</code>, -<code>info-menu-star</code>, and <code>info-title-</code><var>n</var> (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-fontify-maximum-menu-size</code><a name="index-Info_002dfontify_002dmaximum_002dmenu_002dsize-82"></a><dd>Maximum size of menu to fontify if <code>font-lock-mode</code> is non-<code>nil</code>. - - <br><dt><code>Info-fontify-visited-nodes</code><a name="index-Info_002dfontify_002dvisited_002dnodes-83"></a><dd>If non-<code>nil</code>, menu items and cross-references pointing to visited -nodes are displayed in the <code>info-xref-visited</code> face. - - <br><dt><code>Info-use-header-line</code><a name="index-Info_002duse_002dheader_002dline-84"></a><dd>If non-<code>nil</code>, Emacs puts in the Info buffer a header line showing -the ‘<samp><span class="samp">Next</span></samp>’, ‘<samp><span class="samp">Prev</span></samp>’, and ‘<samp><span class="samp">Up</span></samp>’ 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-85"></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-86"></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-isearch-search</code><a name="index-Info_002disearch_002dsearch-87"></a><dd>If non-<code>nil</code>, isearch in Info searches through multiple nodes. - - <br><dt><code>Info-enable-active-nodes</code><a name="index-Info_002denable_002dactive_002dnodes-88"></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 ‘<samp><span class="samp">DEL</span></samp>’ character) and an ‘<samp><span class="samp">execute: </span></samp>’ tag, like -this: - - <pre class="example"> ^_execute: (message "This is an active node!") -</pre> - </dl> - -<div class="node"> -<p><hr> -<a name="Expert-Info"></a> -Next: <a rel="next" accesskey="n" href="#Index">Index</a>, -Previous: <a rel="previous" accesskey="p" href="#Advanced">Advanced</a>, -Up: <a rel="up" accesskey="u" href="#Top">Top</a> - -</div> - -<h2 class="chapter">3 Info for Experts</h2> - -<p>This chapter explains how to write an Info file by hand. 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. - - <p>The <code>makeinfo</code> command 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</a>, for how to write a Texinfo file. - - <p>See <a href="texinfo.html#Creating-an-Info-File">Creating an Info File</a>, for how to create an Info file from a Texinfo file. - - <p>See <a href="texinfo.html#Installing-an-Info-File">Installing an Info File</a>, for how to install an Info file after you -have created one. - - <p>However, if you want to edit an Info file manually and install it manually, -here is how. - -<ul class="menu"> -<li><a accesskey="1" href="#Add">Add</a>: Describes how to add new nodes to the hierarchy. - Also tells what nodes look like. -<li><a accesskey="2" href="#Menus">Menus</a>: How to add to or create menus in Info nodes. -<li><a accesskey="3" href="#Cross_002drefs">Cross-refs</a>: How to add cross-references to Info nodes. -<li><a accesskey="4" href="#Tags">Tags</a>: How to make tags tables for Info files. -<li><a accesskey="5" href="#Checking">Checking</a>: Checking an Info File. -</ul> - -<div class="node"> -<p><hr> -<a name="Add"></a> -Next: <a rel="next" accesskey="n" href="#Menus">Menus</a>, -Up: <a rel="up" accesskey="u" href="#Expert-Info">Expert Info</a> - -</div> - -<!-- node-name, next, previous, up --> -<h3 class="section">3.1 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><a name="index-node-delimiters-89"></a> The new node can live in an existing documentation file, or in a new -one. It must have a ‘<samp><span class="samp">^_</span></samp>’ character before it (invisible to the -user; this node has one but you cannot see it), and it ends with either -a ‘<samp><span class="samp">^_</span></samp>’, a ‘<samp><span class="samp">^L</span></samp>’ (“formfeed”), or the end of file.<a rel="footnote" href="#fn-2" name="fnd-2"><sup>2</sup></a> - - <p>The ‘<samp><span class="samp">^_</span></samp>’ starting a node must be followed by a newline or a -‘<samp><span class="samp">^L</span></samp>’ 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 ‘<samp><span class="samp">Next</span></samp>’, ‘<samp><span class="samp">Previous</span></samp>’, and ‘<samp><span class="samp">Up</span></samp>’ -nodes (if there are any). As you can see, this node's ‘<samp><span class="samp">Up</span></samp>’ node -is the node ‘<samp><span class="samp">Expert Info</span></samp>’. The ‘<samp><span class="samp">Next</span></samp>’ node is ‘<samp><span class="samp">Menus</span></samp>’. - - <p><a name="index-node-header-line-format-90"></a><a name="index-format-of-node-headers-91"></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-92"></a><a name="index-Directory-node-93"></a> A node name has two forms. A node in the current file is named by -what appears after the ‘<samp><span class="samp">Node: </span></samp>’ in that node's first line. For -example, this node's name is ‘<samp><span class="samp">Add</span></samp>’. A node in another file is -named by ‘<samp><span class="samp">(</span><var>filename</var><span class="samp">)</span><var>node-within-file</var></samp>’, as in -‘<samp><span class="samp">(info)Add</span></samp>’ for this node. If the file name starts with ‘<samp><span class="samp">./</span></samp>’, -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 ‘<samp><span class="samp">(</span><var>filename</var><span class="samp">)Top</span></samp>’ can be abbreviated to just -‘<samp><span class="samp">(</span><var>filename</var><span class="samp">)</span></samp>’. By convention, the name ‘<samp><span class="samp">Top</span></samp>’ is used -for the “highest” node in any single file—the node whose ‘<samp><span class="samp">Up</span></samp>’ -points out of the file. The ‘<samp><span class="samp">Directory</span></samp>’ node is <samp><span class="file">(dir)</span></samp>, it -points to a file <samp><span class="file">dir</span></samp> which holds a large menu listing all the -Info documents installed on your site. The ‘<samp><span class="samp">Top</span></samp>’ node of a -document file listed in the ‘<samp><span class="samp">Directory</span></samp>’ should have an ‘<samp><span class="samp">Up: -(dir)</span></samp>’ in it. - - <p><a name="index-unstructured-documents-94"></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 ‘<samp><span class="samp">Node:</span></samp>’ 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 ‘<samp><span class="samp">Next</span></samp>’, ‘<samp><span class="samp">Previous</span></samp>’ and -‘<samp><span class="samp">Up</span></samp>’ names may contain them. In this node, since the ‘<samp><span class="samp">Up</span></samp>’ -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> - -</div> - -<!-- node-name, next, previous, up --> -<h3 class="section">3.2 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-95"></a> A menu begins with a line starting with ‘<samp><span class="samp">* Menu:</span></samp>’<!-- /@w -->. The -rest of the line is a comment. After the starting line, every line -that begins with a ‘<samp><span class="samp">* </span></samp>’ 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 -‘<samp><span class="samp">Next</span></samp>’, ‘<samp><span class="samp">Previous</span></samp>’ and ‘<samp><span class="samp">Up</span></samp>’, 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 ‘<samp><span class="samp">* </span><var>name</var><span class="samp">::</span></samp>’ 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 ‘<samp><span class="samp">Up:</span></samp>’ pointing at -the superior. It is often useful to arrange all or most of the subnodes -in a sequence of ‘<samp><span class="samp">Next</span></samp>’ and ‘<samp><span class="samp">Previous</span></samp>’ 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 ‘<samp><span class="samp">(dir)Top</span></samp>’—that -is, node ‘<samp><span class="samp">Top</span></samp>’ in file <samp><span class="file">.../info/dir</span></samp>. 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 <samp><span class="file">info</span></samp>. 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 ‘<samp><span class="samp">Top</span></samp>’; the other contains the node ‘<samp><span class="samp">Help</span></samp>’ which the -<kbd>h</kbd> command goes to. In fact, since there is no garbage -collector on the node graph, 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-refs"></a> -<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> - -</div> - -<!-- node-name, next, previous, up --> -<h3 class="section">3.3 Creating Cross References</h3> - -<p><a name="index-cross-reference-format-96"></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 ‘<samp><span class="samp">*note</span></samp>’ instead of ‘<samp><span class="samp">*</span></samp>’. -It <em>cannot</em> be terminated by a ‘<samp><span class="samp">)</span></samp>’, because ‘<samp><span class="samp">)</span></samp>’'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-Cross"></a> -<a name="Help_002dCross"></a> -Up: <a rel="up" accesskey="u" href="#Cross_002drefs">Cross-refs</a> - -</div> - -<h4 class="subsection">3.3.1 The node reached by the cross reference in Info</h4> - -<p>This is the node reached by the cross reference named ‘<samp><span class="samp">Cross</span></samp>’. - - <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 ‘<samp><span class="samp">Next</span></samp>’, ‘<samp><span class="samp">Previous</span></samp>’ or -‘<samp><span class="samp">Up</span></samp>’ 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="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> - -</div> - -<!-- node-name, next, previous, up --> -<h3 class="section">3.4 Tags Tables for Info Files</h3> - -<p><a name="index-tags-tables-in-Info-files-97"></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-98"></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-99"></a><a name="index-update-Info-tags-table-100"></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 ‘<samp><span class="samp">DEL</span></samp>’ character, and the character position in the file of the -beginning of the node. - -<div class="node"> -<p><hr> -<a name="Checking"></a> -Previous: <a rel="previous" accesskey="p" href="#Tags">Tags</a>, -Up: <a rel="up" accesskey="u" href="#Expert-Info">Expert Info</a> - -</div> - -<h3 class="section">3.5 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 ‘<samp><span class="samp">Next</span></samp>’, ‘<samp><span class="samp">Previous</span></samp>’, and -‘<samp><span class="samp">Up</span></samp>’ is checked, as is every menu item and every cross reference. In -addition, any ‘<samp><span class="samp">Next</span></samp>’ which does not have a ‘<samp><span class="samp">Previous</span></samp>’ 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-101"></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="Index"></a> -Previous: <a rel="previous" accesskey="p" href="#Expert-Info">Expert Info</a>, -Up: <a rel="up" accesskey="u" href="#Top">Top</a> - -</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-g_t1-_0040r_007bthrough_007d-9-_0040r_007b_0028Info-mode_0029_007d-73"><code>1 </code><span class="roman">through</span><code> 9 </code><span class="roman">(Info mode)</span></a>: <a href="#Choose-menu-subtopic">Choose menu subtopic</a></li> -<li><a href="#index-g_t_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-C_002dq-_0040r_007b_0028Info-mode_0029_007d-55"><code>C-q </code><span class="roman">(Info mode)</span></a>: <a href="#Advanced">Advanced</a></li> -<li><a href="#index-C_002dr-_0040r_007b_0028Info-mode_0029_007d-62"><code>C-r </code><span class="roman">(Info mode)</span></a>: <a href="#Search-Text">Search Text</a></li> -<li><a href="#index-C_002ds-_0040r_007b_0028Info-mode_0029_007d-61"><code>C-s </code><span class="roman">(Info mode)</span></a>: <a href="#Search-Text">Search Text</a></li> -<li><a href="#index-clone_002dbuffer-77"><code>clone-buffer</code></a>: <a href="#Create-Info-buffer">Create Info buffer</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-96">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-46"><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-93">Directory node</a>: <a href="#Add">Add</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-91">format of node headers</a>: <a href="#Add">Add</a></li> -<li><a href="#index-g-_0040r_007b_0028Info-mode_0029_007d-69"><code>g </code><span class="roman">(Info mode)</span></a>: <a href="#Go-to-node">Go to node</a></li> -<li><a href="#index-go-to-a-node-by-name-71">go to a node by name</a>: <a href="#Go-to-node">Go to node</a></li> -<li><a href="#index-go-to-another-Info-file-72">go to another Info file</a>: <a href="#Go-to-node">Go to node</a></li> -<li><a href="#index-go-to-Directory-node-48">go to Directory node</a>: <a href="#Help_002dInt">Help-Int</a></li> -<li><a href="#index-go-to-Top-node-51">go to Top node</a>: <a href="#Help_002dInt">Help-Int</a></li> -<li><a href="#index-going-back-in-Info-history-39">going back in Info history</a>: <a href="#Help_002dInt">Help-Int</a></li> -<li><a href="#index-going-forward-in-Info-history-42">going forward in Info history</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-history-list-of-visited-nodes-45">history list of visited nodes</a>: <a href="#Help_002dInt">Help-Int</a></li> -<li><a href="#index-i-_0040r_007b_0028Info-mode_0029_007d-65"><code>i </code><span class="roman">(Info mode)</span></a>: <a href="#Search-Index">Search Index</a></li> -<li><a href="#index-index_002dapropos-68"><code>index-apropos</code></a>: <a href="#Search-Index">Search Index</a></li> -<li><a href="#index-Info-document-as-a-reference-57">Info document as a reference</a>: <a href="#Search-Text">Search Text</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-80"><code>Info-additional-directory-list</code></a>: <a href="#Emacs-Info-Variables">Emacs Info Variables</a></li> -<li><a href="#index-info_002dapropos-67"><code>info-apropos</code></a>: <a href="#Search-Index">Search Index</a></li> -<li><a href="#index-Info_002ddirectory-47"><code>Info-directory</code></a>: <a href="#Help_002dInt">Help-Int</a></li> -<li><a href="#index-Info_002ddirectory_002dlist-79"><code>Info-directory-list</code></a>: <a href="#Emacs-Info-Variables">Emacs Info Variables</a></li> -<li><a href="#index-Info_002denable_002dactive_002dnodes-88"><code>Info-enable-active-nodes</code></a>: <a href="#Emacs-Info-Variables">Emacs Info Variables</a></li> -<li><a href="#index-Info_002dexit-53"><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_002dmaximum_002dmenu_002dsize-82"><code>Info-fontify-maximum-menu-size</code></a>: <a href="#Emacs-Info-Variables">Emacs Info Variables</a></li> -<li><a href="#index-Info_002dfontify_002dvisited_002dnodes-83"><code>Info-fontify-visited-nodes</code></a>: <a href="#Emacs-Info-Variables">Emacs Info Variables</a></li> -<li><a href="#index-Info_002dgoto_002dnode-70"><code>Info-goto-node</code></a>: <a href="#Go-to-node">Go to node</a></li> -<li><a href="#index-Info_002dhide_002dnote_002dreferences-85"><code>Info-hide-note-references</code></a>: <a href="#Emacs-Info-Variables">Emacs Info Variables</a></li> -<li><a href="#index-Info_002dhistory-44"><code>Info-history</code></a>: <a href="#Help_002dInt">Help-Int</a></li> -<li><a href="#index-Info_002dhistory_002dback-38"><code>Info-history-back</code></a>: <a href="#Help_002dInt">Help-Int</a></li> -<li><a href="#index-Info_002dhistory_002dforward-41"><code>Info-history-forward</code></a>: <a href="#Help_002dInt">Help-Int</a></li> -<li><a href="#index-Info_002dindex-66"><code>Info-index</code></a>: <a href="#Search-Index">Search Index</a></li> -<li><a href="#index-Info_002disearch_002dsearch-87"><code>Info-isearch-search</code></a>: <a href="#Emacs-Info-Variables">Emacs Info Variables</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_002dmode_002dhook-81"><code>Info-mode-hook</code></a>: <a href="#Emacs-Info-Variables">Emacs Info Variables</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-74"><code>Info-nth-menu-item</code></a>: <a href="#Choose-menu-subtopic">Choose menu subtopic</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-86"><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-59"><code>Info-search</code></a>: <a href="#Search-Text">Search Text</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-98"><code>Info-tagify</code></a>: <a href="#Tags">Tags</a></li> -<li><a href="#index-Info_002dtop_002dnode-50"><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-84"><code>Info-use-header-line</code></a>: <a href="#Emacs-Info-Variables">Emacs Info Variables</a></li> -<li><a href="#index-Info_002dvalidate-101"><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-isearch-63"><code>isearch</code></a>: <a href="#Search-Text">Search Text</a></li> -<li><a href="#index-L-_0040r_007b_0028Info-mode_0029_007d-43"><code>L </code><span class="roman">(Info mode)</span></a>: <a href="#Help_002dInt">Help-Int</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-76"><code>M-n </code><span class="roman">(Info mode)</span></a>: <a href="#Create-Info-buffer">Create Info buffer</a></li> -<li><a href="#index-M_002ds-_0040r_007b_0028Info-mode_0029_007d-60"><code>M-s </code><span class="roman">(Info mode)</span></a>: <a href="#Search-Text">Search Text</a></li> -<li><a href="#index-menu-and-menu-entry-format-95">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-78">multiple Info buffers</a>: <a href="#Create-Info-buffer">Create Info buffer</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-89">node delimiters</a>: <a href="#Add">Add</a></li> -<li><a href="#index-node-header-line-format-90">node header line format</a>: <a href="#Add">Add</a></li> -<li><a href="#index-node-name-format-92">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-52"><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-54">quitting Info mode</a>: <a href="#Help_002dQ">Help-Q</a></li> -<li><a href="#index-r-_0040r_007b_0028Info-mode_0029_007d-40"><code>r </code><span class="roman">(Info mode)</span></a>: <a href="#Help_002dInt">Help-Int</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-58"><code>s </code><span class="roman">(Info mode)</span></a>: <a href="#Search-Text">Search Text</a></li> -<li><a href="#index-searching-Info-documents-56">searching Info documents</a>: <a href="#Search-Text">Search Text</a></li> -<li><a href="#index-searching-Info-indices-64">searching Info indices</a>: <a href="#Search-Index">Search Index</a></li> -<li><a href="#index-select-_0040var_007bn_007d_0027th-menu-item-75">select <var>n</var>'th menu item</a>: <a href="#Choose-menu-subtopic">Choose menu subtopic</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-99">stale tags tables</a>: <a href="#Tags">Tags</a></li> -<li><a href="#index-t-_0040r_007b_0028Info-mode_0029_007d-49"><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-97">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-94">unstructured documents</a>: <a href="#Add">Add</a></li> -<li><a href="#index-update-Info-tags-table-100">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 ‘<samp><span class="samp">Backspace</span></samp>’ or ‘<samp><span class="samp"><-</span></samp>’ or -‘<samp><span class="samp">DEL</span></samp>’, or sometimes ‘<samp><span class="samp">Delete</span></samp>’.</p> - - <p class="footnote"><small>[<a name="fn-2" href="#fnd-2">2</a>]</small> If -you put in a ‘<samp><span class="samp">^L</span></samp>’ to end a new node, be sure that there is a -‘<samp><span class="samp">^_</span></samp>’ after it to start the next one, since ‘<samp><span class="samp">^L</span></samp>’ 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 ‘<samp><span class="samp">^L</span></samp>’ <em>right after</em> the -‘<samp><span class="samp">^_</span></samp>’.</p> - - <hr></div> - -</body></html> - diff --git a/Master/texmf/doc/texinfo/info.pdf b/Master/texmf/doc/texinfo/info.pdf Binary files differdeleted file mode 100644 index ddd4636cbf6..00000000000 --- a/Master/texmf/doc/texinfo/info.pdf +++ /dev/null diff --git a/Master/texmf/doc/texinfo/texinfo.html b/Master/texmf/doc/texinfo/texinfo.html deleted file mode 100644 index 77b1530b044..00000000000 --- a/Master/texmf/doc/texinfo/texinfo.html +++ /dev/null @@ -1,21165 +0,0 @@ -<html lang="en"> -<head> -<title>GNU Texinfo 4.12</title> -<meta http-equiv="Content-Type" content="text/html"> -<meta name="description" content="GNU Texinfo 4.12"> -<meta name="generator" content="makeinfo 4.12"> -<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.12, 9 April 2008), -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, 2005, 2006, 2007, 2008 -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.2 or any later version published by the Free Software - Foundation; with no Invariant Sections, with the Front-Cover Texts - being "A GNU Manual", and with the Back-Cover Texts as in (a) - below. A copy of the license is included in the section entitled - "GNU Free Documentation License." - - (a) The FSF's Back-Cover Text is: "You are free to copy and modify - this GNU Manual. Buying copies from GNU Press supports the FSF in - developing GNU and promoting software freedom." - --> -<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; } - span.sansserif { font-family:sans-serif; font-weight:normal; } ---></style> -</head> -<body> -<h1 class="settitle">GNU Texinfo 4.12</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_GNU-Free-Documentation-License">Appendix G GNU Free Documentation License</a></li> -<li><a href="#toc_Command-and-Variable-Index">Command and Variable Index</a></li> -<li><a href="#toc_General-Index">General 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="#abbr">9.1.14 <code>@abbr</code>{<var>abbreviation</var>[, <var>meaning</var>]}</a> -<li><a href="#acronym">9.1.15 <code>@acronym</code>{<var>acronym</var>[, <var>meaning</var>]}</a> -<li><a href="#indicateurl">9.1.16 <code>@indicateurl</code>{<var>uniform-resource-locator</var>}</a> -<li><a href="#email">9.1.17 <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-Quote-Characters">14.2 Inserting Quote Characters</a> -<li><a href="#Inserting-Space">14.3 Inserting Space</a> -<ul> -<li><a href="#Not-Ending-a-Sentence">14.3.1 Not Ending a Sentence</a> -<li><a href="#Ending-a-Sentence">14.3.2 Ending a Sentence</a> -<li><a href="#Multiple-Spaces">14.3.3 Multiple Spaces</a> -<li><a href="#frenchspacing">14.3.4 <code>@frenchspacing</code> <var>val</var>: Control sentence spacing</a> -<li><a href="#dmn">14.3.5 <code>@dmn</code>{<var>dimension</var>}: Format a Dimension</a> -</li></ul> -<li><a href="#Inserting-Accents">14.4 Inserting Accents</a> -<li><a href="#Inserting-Quotation-Marks">14.5 Inserting Quotation Marks</a> -<li><a href="#Dots-Bullets">14.6 Inserting Ellipsis and Bullets</a> -<ul> -<li><a href="#dots">14.6.1 <code>@dots</code>{} (<small class="dots">...</small>) and <code>@enddots</code>{} (<small class="enddots">...</small>)</a> -<li><a href="#bullet">14.6.2 <code>@bullet</code>{} (•)</a> -</li></ul> -<li><a href="#TeX-and-copyright">14.7 Inserting TeX and Legal Symbols: ©, ®</a> -<ul> -<li><a href="#tex">14.7.1 <code>@TeX</code>{} (TeX) and <code>@LaTeX</code>{} (LaTeX)</a> -<li><a href="#copyright-symbol">14.7.2 <code>@copyright{}</code> (©)</a> -<li><a href="#registered-symbol">14.7.3 <code>@registeredsymbol{}</code> (®)</a> -</li></ul> -<li><a href="#euro">14.8 <code>@euro</code>{} (€): Euro Currency Symbol</a> -<li><a href="#pounds">14.9 <code>@pounds</code>{} (£): Pounds Sterling</a> -<li><a href="#textdegree">14.10 <code>@textdegree</code>{} (°): Degrees Symbol</a> -<li><a href="#minus">14.11 <code>@minus</code>{} (−): Inserting a Minus Sign</a> -<li><a href="#geq-leq">14.12 <code>@geq{}</code> (≥) and <code>@leq{}</code> (≤): Inserting relations</a> -<li><a href="#math">14.13 <code>@math</code>: Inserting Mathematical Expressions</a> -<li><a href="#Click-Sequences">14.14 Click Sequences</a> -<li><a href="#Glyphs">14.15 Glyphs for Examples</a> -<ul> -<li><a href="#Glyphs-Summary">14.15.1 Glyphs Summary</a> -<li><a href="#result">14.15.2 <code>@result{}</code> (⇒): Indicating Evaluation</a> -<li><a href="#expansion">14.15.3 <code>@expansion{}</code> (==>): Indicating an Expansion</a> -<li><a href="#Print-Glyph">14.15.4 <code>@print{}</code> (-|): Indicating Printed Output</a> -<li><a href="#Error-Glyph">14.15.5 <code>@error{}</code> (error-->): Indicating an Error Message</a> -<li><a href="#Equivalence">14.15.6 <code>@equiv{}</code> (==): Indicating Equivalence</a> -<li><a href="#Point-Glyph">14.15.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="#allowcodebreaks">15.4 <code>@allowcodebreaks</code>: Control Line Breaks in <code>@code</code></a> -<li><a href="#w">15.5 <code>@w</code>{<var>text</var>}: Prevent Line Breaks</a> -<li><a href="#tie">15.6 <code>@tie{}</code>: Inserting an Unbreakable Space</a> -<li><a href="#sp">15.7 <code>@sp</code> <var>n</var>: Insert Blank Lines</a> -<li><a href="#page">15.8 <code>@page</code>: Start a New Page</a> -<li><a href="#group">15.9 <code>@group</code>: Prevent Page Breaks</a> -<li><a href="#need">15.10 <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>ll</var><code>[_</code><var>cc</var><code>]</code>: 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 and Caveats</a> -<li><a href="#alias">19.4 ‘<samp><span class="samp">@alias </span><var>new</var><span class="samp">=</span><var>existing</var></samp>’</a> -<li><a href="#definfoenclose">19.5 ‘<samp><span class="samp">definfoenclose</span></samp>’: 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 <samp><span class="file">dir</span></samp></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 <samp><span class="command">install-info</span></samp></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_GNU-Free-Documentation-License" href="#GNU-Free-Documentation-License">Appendix G GNU Free Documentation License</a> -<li><a name="toc_Command-and-Variable-Index" href="#Command-and-Variable-Index">Command and Variable Index</a> -<li><a name="toc_General-Index" href="#General-Index">General 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> - -</div> - -<h2 class="unnumbered">Texinfo</h2> - -<p>This manual is for GNU Texinfo (version 4.12, 9 April 2008), -a documentation system that can produce both online information and a -printed manual from a single source. - - <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="#GNU-Free-Documentation-License">GNU Free Documentation License</a>: Copying this manual. -<li><a href="#Command-and-Variable-Index">Command and Variable Index</a>: A menu containing commands and variables. -<li><a href="#General-Index">General 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="#abbr">abbr</a>: Indicating abbreviations. -<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-Quote-Characters">Inserting Quote Characters</a>: Inserting left and right quotes, in code. -<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="#Inserting-Quotation-Marks">Inserting Quotation Marks</a>: How to insert quotation marks. -<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="#euro">euro</a>: How to insert the Euro currency symbol. -<li><a href="#pounds">pounds</a>: How to insert the pounds currency symbol. -<li><a href="#textdegree">textdegree</a>: How to insert the degrees symbol. -<li><a href="#minus">minus</a>: How to insert a minus sign. -<li><a href="#geq-leq">geq leq</a>: How to insert greater/less-than-or-equal signs. -<li><a href="#math">math</a>: How to format a mathematical expression. -<li><a href="#Click-Sequences">Click Sequences</a>: Inserting GUI usage sequences. -<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="#frenchspacing">frenchspacing</a>: Specifying end-of-sentence spacing. -<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="#g_t_002d-and-hyphenation">- and hyphenation</a>: Helping TeX with hyphenation points. -<li><a href="#allowcodebreaks">allowcodebreaks</a>: Controlling line breaks within @code text. -<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>GNU Free Documentation License - -<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. - - </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> - -</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 <samp><span class="file">texinfo.tex</span></samp>. -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> - -</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> - -</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 <samp><span class="command">configure</span></samp>. -<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 -‘<samp><span class="samp">diff -c<!-- /@w --></span></samp>’ (see <a href="diff.html#Top">Overview</a>) and include <samp><span class="file">ChangeLog</span></samp> entries (see <a href="emacs.html#Change-Log">Change Log</a>), and follow the existing coding style. - -<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> - -</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 ASCII file containing text -interspersed with <dfn>@-commands</dfn> (words preceded by an ‘<samp><span class="samp">@</span></samp>’) -that tell the typesetting and formatting programs what to do. You can -edit a Texinfo file with any text editor, but it is especially -convenient to use GNU Emacs since that editor has a special mode, -called Texinfo mode, that provides various Texinfo-related features. -(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> - -</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 <samp><span class="command">makeinfo</span></samp>.) 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</a>), -and the standalone <samp><span class="command">info</span></samp> program (see <a href="info-stnd.html#Top">Info Standalone</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 <samp><span class="command">makeinfo --no-headers</span></samp>.) This is almost the -same as Info output, except the navigational control characters are -omitted. Also, standard output is used by default. - - <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 <samp><span class="command">makeinfo --html</span></samp>.) 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; <samp><span class="command">makeinfo</span></samp> 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 <samp><span class="command">texi2dvi</span></samp>.) 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</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 <samp><span class="command">texi2dvi --pdf</span></samp> or <samp><span class="command">texi2pdf</span></samp>.) This -format was developed by Adobe Systems for portable document -interchange, based on their previous PostScript language. It can -represent the exact appearance of a document, including fonts and -graphics, and supporting arbitrary scaling. It is intended to be -platform-independent and easily viewable, among other design goals; -<a href="http://tug.org/TUGboat/Articles/tb22-3/tb72beebe-pdf.pdf">http://tug.org/TUGboat/Articles/tb22-3/tb72beebe-pdf.pdf</a> has -some background. Texinfo uses the <samp><span class="command">pdftex</span></samp> 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 <samp><span class="command">makeinfo --xml</span></samp>.) 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 <samp><span class="command">makeinfo</span></samp> 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 <samp><span class="file">texinfo.dtd</span></samp> included in -the Texinfo source distribution. - - <br><dt>Docbook<dd><a name="index-Docbook-output-32"></a>(Generated via <samp><span class="command">makeinfo --docbook</span></samp>.) 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 <samp><span class="command">help2man</span></samp> to be useful; it generates a -traditional man page from the ‘<samp><span class="samp">--help</span></samp>’ 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> - -</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</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</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 <samp><span class="file">dir</span></samp> file in the <samp><span class="file">info</span></samp> 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 <samp><span class="command">info</span></samp> program itself does not follow URIs 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> - -</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 <samp><span class="file">texinfo.tex</span></samp> that contains information (definitions or -<dfn>macros</dfn>) that TeX uses when it typesets a Texinfo file. -(<samp><span class="file">texinfo.tex</span></samp> tells TeX how to convert the Texinfo @-commands -to TeX commands, which TeX can then process to create the typeset -document.) <samp><span class="file">texinfo.tex</span></samp> contains the specifications for printing -a document. You can get the latest version of <samp><span class="file">texinfo.tex</span></samp> from -the Texinfo home page, <a href="http://www.gnu.org/software/texinfo/">http://www.gnu.org/software/texinfo/</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 <samp><span class="file">texinfo.tex</span></samp>, 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</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> - -</div> - -<h3 class="section">1.6 @-commands</h3> - -<p><a name="index-g_t_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 ‘<samp><span class="samp">@</span></samp>’; 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 an ellipsis <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> - -</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 ASCII characters except ‘<samp><span class="samp">@</span></samp>’, ‘<samp><span class="samp">{</span></samp>’ and -‘<samp><span class="samp">}</span></samp>’ can appear in a Texinfo file and stand for themselves. -‘<samp><span class="samp">@</span></samp>’ is the escape character which introduces commands, while -‘<samp><span class="samp">{</span></samp>’ and ‘<samp><span class="samp">}</span></samp>’ are used to surround arguments to certain -commands. To put one of these special characters into the document, put -an ‘<samp><span class="samp">@</span></samp>’ character in front of it, like this: ‘<samp><span class="samp">@@</span></samp>’, -‘<samp><span class="samp">@{</span></samp>’, and ‘<samp><span class="samp">@}</span></samp>’. - - <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>Texinfo supports the usual quotation marks used in English, and -quotation marks used in other languages, please see <a href="#Inserting-Quotation-Marks">Inserting Quotation Marks</a>. - - <li><a name="index-Multiple-dashes-in-source-57"></a><a name="index-Dashes-in-source-58"></a><a name="index-Hyphens-in-source_002c-two-or-three-in-a-row-59"></a><a name="index-Em-dash_002c-producing-60"></a><a name="index-En-dash_002c-producing-61"></a>Use three hyphens in a row, ‘<samp><span class="samp">---</span></samp>’, to produce a long dash—like -this (called an <dfn>em dash</dfn>), used for punctuation in sentences. -Use two hyphens, ‘<samp><span class="samp">--</span></samp>’, to produce a medium dash (called an -<dfn>en dash</dfn>), used primarily for numeric ranges, as in “June -25–26”. Use a single hyphen, ‘<samp><span class="samp">-</span></samp>’, to produce a standard hyphen -used in compound words. For display on the screen, Info reduces three -hyphens to two and two hyphens to one (not transitively!). Of course, -any number of hyphens in the source remain as they are in literal -contexts, such as <code>@code</code> and <code>@example</code>. - - <li><a name="index-Tabs_003b-don_0027t-use_0021-62"></a><strong>Caution:</strong> Last, do not use tab characters in a Texinfo file -(except in verbatim modes)! TeX uses variable-width fonts, which -means that it is impractical at best to define a tab to work in all -circumstances. Consequently, TeX treats tabs like single spaces, -and that is not what they look like in the source. Furthermore, -<code>makeinfo</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 in GNU Emacs inserts -multiple spaces when you press the <TAB> key. 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> - -</div> - -<h3 class="section">1.8 Comments</h3> - -<p><a name="index-Comments-63"></a><a name="index-comment-64"></a><a name="index-c-_0040r_007b_0028comment_0029_007d-65"></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-66"></a><a name="index-Unprocessed-text-67"></a><a name="index-ignore-68"></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> - -</div> - -<h3 class="section">1.9 What a Texinfo File Must Have</h3> - -<p><a name="index-Minimal-Texinfo-file-_0028requirements_0029-69"></a><a name="index-Must-have-in-Texinfo-file-70"></a><a name="index-Required-in-Texinfo-file-71"></a><a name="index-Texinfo-file-minimum-72"></a> -By convention, the name of a Texinfo file ends with (in order of -preference) one of the extensions <samp><span class="file">.texinfo</span></samp>, <samp><span class="file">.texi</span></samp>, -<samp><span class="file">.txi</span></samp>, or <samp><span class="file">.tex</span></samp>. 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-g_t_005cinput-_0040r_007b_0028raw-_0040TeX_007b_007d-startup_0029_007d-73"></a>Here's an explanation: - - <ul> -<li>The ‘<samp><span class="samp">\input texinfo</span></samp>’ line tells TeX to use the -<samp><span class="file">texinfo.tex</span></samp> file, which tells TeX how to translate the Texinfo -@-commands into TeX typesetting commands. (Note the use of the -backslash, ‘<samp><span class="samp">\</span></samp>’; 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 ‘<samp><span class="samp"><head></span></samp>’ 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, ‘<samp><span class="samp">-*-texinfo-*-</span></samp>’ 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> - -</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 may contain commands for printing indices, and -closes with 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> - -</div> - -<h3 class="section">1.11 A Short Sample Texinfo File</h3> - -<p><a name="index-Sample-Texinfo-file_002c-with-comments-74"></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 -‘<samp><span class="samp">\input texinfo</span></samp>’ through to ‘<samp><span class="samp">@end titlepage</span></samp>’, 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{} 2005 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 repeat the short description from the -beginning of the ‘<samp><span class="samp">@copying</span></samp>’ text, but there's no need to repeat -the copyright information, so we don't use ‘<samp><span class="samp">@insertcopying</span></samp>’ here. -The ‘<samp><span class="samp">@top</span></samp>’ command itself helps <samp><span class="command">makeinfo</span></samp> determine the -relationships between nodes. - -<pre class="example"> @ifnottex - @node Top - @top Short Sample - - This is a short sample Texinfo file. - @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> - -</div> - -<h3 class="section">1.12 History</h3> - -<p><a name="index-Stallman_002c-Richard-M_002e-75"></a><a name="index-Chassell_002c-Robert-J_002e-76"></a><a name="index-Fox_002c-Brian-77"></a><a name="index-Berry_002c-Karl-78"></a>Richard M. Stallman invented the Texinfo format, wrote the initial -processors, and created Edition 1.0 of this manual. Robert J. -Chassell greatly revised and extended the manual, starting with -Edition 1.1. Brian Fox was responsible for the standalone Texinfo -distribution until version 3.8, and wrote the standalone -<samp><span class="command">makeinfo</span></samp> and <samp><span class="command">info</span></samp> 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-79"></a><a name="index-Zuhn_002c-David-D_002e-80"></a><a name="index-Weisshaus_002c-Melissa-81"></a><a name="index-Zaretskii_002c-Eli-82"></a><a name="index-Schwab_002c-Andreas-83"></a><a name="index-Weinberg_002c-Zack-84"></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, -tirelessly recorded and reported mistakes and obscurities. Zack -Weinberg did the impossible by implementing the macro syntax in -<samp><span class="file">texinfo.tex</span></samp>. 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 <samp><span class="file">ChangeLog</span></samp> file. Our mistakes are our own. - - <p><a name="index-Scribe-85"></a><a name="index-Reid_002c-Brian-86"></a><a name="index-History-of-Texinfo-87"></a><a name="index-Texinfo-history-88"></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 strove to describe document contents rather than -formatting, an idea wholeheartedly adopted by Texinfo. - - <p><a name="index-Bolio-89"></a><a name="index-Bo_0040TeX_007b_007d-90"></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> - -</div> - -<h2 class="chapter">2 Using Texinfo Mode</h2> - -<p><a name="index-Texinfo-mode-91"></a><a name="index-Mode_002c-using-Texinfo-92"></a><a name="index-GNU-Emacs-93"></a><a name="index-Emacs-94"></a> -You may edit a Texinfo file with any text editor you choose. A Texinfo -file is no different from any other ASCII file. However, GNU Emacs -comes with a special mode, called Texinfo mode, that provides Emacs -commands and tools to help ease your work. - - <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> - -</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> - -</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 n p</kbd> (<code>narrow-to-page</code>) command. (See <a href="emacs.html#Pages">Pages</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 -<samp><span class="file">.texinfo</span></samp>, <samp><span class="file">.texi</span></samp>, <samp><span class="file">.txi</span></samp>, or <samp><span class="file">.tex</span></samp>. 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 <samp><span class="file">.texinfo</span></samp>, <samp><span class="file">.texi</span></samp> or <samp><span class="file">.txi</span></samp> -extension. Also, Emacs switches to Texinfo mode -when you visit a -file that has ‘<samp><span class="samp">-*-texinfo-*-</span></samp>’ 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> - -</div> - -<!-- node-name, next, previous, up --> -<h3 class="section">2.3 Inserting Frequently Used Commands</h3> - -<p><a name="index-Inserting-frequently-used-commands-95"></a><a name="index-Frequently-used-commands_002c-inserting-96"></a><a name="index-Commands_002c-inserting-them-97"></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-98"></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-99"></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-100"></a>Insert <code>@end</code> and attempt to insert the correct following word, -such as ‘<samp><span class="samp">example</span></samp>’ or ‘<samp><span class="samp">table</span></samp>’. (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-101"></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-102"></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-103"></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-104"></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-105"></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-106"></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-107"></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-108"></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-109"></a>Insert <code>{}</code> and put the cursor between the braces. - - <br><dt><kbd>C-c }</kbd><dt><kbd>C-c ]</kbd><dt><kbd>M-x up-list</kbd><dd><a name="index-up_002dlist-110"></a>Move from between a pair of braces forward past the closing brace. -Typing <kbd>C-c ]</kbd> is easier than typing <kbd>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—‘<samp><span class="samp">1</span></samp>’ for one word, ‘<samp><span class="samp">2</span></samp>’ 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 <samp><span class="file">texinfo.el</span></samp>. - - <p><a name="index-texinfo_002dstart_002dmenu_002ddescription-111"></a><a name="index-Menu-description_002c-start-112"></a><a name="index-Description-for-menu_002c-start-113"></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> - -</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-114"></a><a name="index-Section-structure-of-a-file_002c-showing-it-115"></a><a name="index-Structure-of-a-file_002c-showing-it-116"></a><a name="index-Outline-of-file-structure_002c-showing-it-117"></a><a name="index-Contents_002dlike-outline-of-file-structure-118"></a><a name="index-File-section-structure_002c-showing-it-119"></a><a name="index-Texinfo-file-section-structure_002c-showing-it-120"></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 ‘<samp><span class="samp">*Occur*</span></samp>’ 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-121"></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-122"></a>Go to the line in the Texinfo file corresponding to the line under the -cursor in the <samp><span class="file">*Occur*</span></samp> 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</a>, for more -information about the narrowing commands.) - - <p><a name="index-page_002ddelimiter-123"></a><a name="index-Page-delimiter-in-Texinfo-mode-124"></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 n p</kbd> (<code>narrow-to-page</code>) command to narrow to a chapter. -See <a href="emacs.html#Pages">Pages</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> - -</div> - -<!-- node-name, next, previous, up --> -<h3 class="section">2.5 Updating Nodes and Menus</h3> - -<p><a name="index-Updating-nodes-and-menus-125"></a><a name="index-Create-nodes_002c-menus-automatically-126"></a><a name="index-Insert-nodes_002c-menus-automatically-127"></a><a name="index-Automatically-insert-nodes_002c-menus-128"></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> - -</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-129"></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-130"></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-131"></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-132"></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-133"></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 can be 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</a>) or with the <kbd>M-x set-variable</kbd> -command (see <a href="emacs.html#Examining">Examining and Setting Variables</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> - -</div> - -<h4 class="subsection">2.5.2 Updating Requirements</h4> - -<p><a name="index-Updating-requirements-134"></a><a name="index-Requirements-for-updating-commands-135"></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 ‘<samp><span class="samp">top</span></samp>’ or ‘<samp><span class="samp">Top</span></samp>’ -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> - -</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-136"></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-137"></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-138"></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-139"></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> - -</div> - -<!-- node-name, next, previous, up --> -<h3 class="section">2.6 Formatting for Info</h3> - -<p><a name="index-Formatting-for-Info-140"></a><a name="index-Running-an-Info-formatter-141"></a><a name="index-Info-formatting-142"></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-143"></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-144"></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> - -</div> - -<!-- node-name, next, previous, up --> -<h3 class="section">2.7 Printing</h3> - -<p><a name="index-Formatting-for-printing-145"></a><a name="index-Printing-a-region-or-buffer-146"></a><a name="index-Region-formatting-and-printing-147"></a><a name="index-Buffer-formatting-and-printing-148"></a><a name="index-Part-of-file-formatting-and-printing-149"></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-150"></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-151"></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-152"></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 ‘<samp><span class="samp">\input texinfo</span></samp>’ 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> - -</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> ‘<samp><span class="samp">@code</span></samp>’. - C-c C-c d <span class="roman">Insert</span> ‘<samp><span class="samp">@dfn</span></samp>’. - C-c C-c e <span class="roman">Insert</span> ‘<samp><span class="samp">@end</span></samp>’. - C-c C-c i <span class="roman">Insert</span> ‘<samp><span class="samp">@item</span></samp>’. - C-c C-c n <span class="roman">Insert</span> ‘<samp><span class="samp">@node</span></samp>’. - C-c C-c s <span class="roman">Insert</span> ‘<samp><span class="samp">@samp</span></samp>’. - C-c C-c v <span class="roman">Insert</span> ‘<samp><span class="samp">@var</span></samp>’. - C-c { <span class="roman">Insert braces.</span> - 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> - -</div> - -<h2 class="chapter">3 Beginning a Texinfo File</h2> - -<p><a name="index-Beginning-a-Texinfo-file-153"></a><a name="index-Texinfo-file-beginning-154"></a><a name="index-File-beginning-155"></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-156"></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> - -</div> - -<h3 class="section">3.1 Sample Texinfo File Beginning</h3> - -<p><a name="index-Example-beginning-of-Texinfo-file-157"></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> - - This manual is for <var>program</var>, version <var>version</var>. - @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> - -</div> - -<h3 class="section">3.2 Texinfo File Header</h3> - -<p><a name="index-Header-for-Texinfo-files-158"></a><a name="index-Texinfo-file-header-159"></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> - -</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-160"></a><a name="index-Beginning-line-of-a-Texinfo-file-161"></a><a name="index-Header-of-a-Texinfo-file-162"></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 ‘<samp><span class="samp">\input texinfo</span></samp>’ command -tells TeX to load the macros needed for processing a Texinfo file. -These are in a file called <samp><span class="file">texinfo.tex</span></samp>, which should have been -installed on your system along with either the TeX or Texinfo -software. TeX uses the backslash, ‘<samp><span class="samp">\</span></samp>’, to mark the beginning of -a command, exactly as Texinfo uses ‘<samp><span class="samp">@</span></samp>’. The <samp><span class="file">texinfo.tex</span></samp> -file causes the switch from ‘<samp><span class="samp">\</span></samp>’ to ‘<samp><span class="samp">@</span></samp>’; before the switch -occurs, TeX requires ‘<samp><span class="samp">\</span></samp>’, which is why it appears at the -beginning of the file. - - <li>When the file is edited in GNU Emacs, the ‘<samp><span class="samp">-*-texinfo-*-</span></samp>’ 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> - -</div> - -<h4 class="subsection">3.2.2 Start of Header</h4> - -<p><a name="index-Start-of-header-line-163"></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, ‘<samp><span class="samp">%**</span></samp>’, is to ensure that no other -comment is accidentally taken for a start-of-header line. You can -change it if you wish by setting the <code>tex-start-of-header</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> - -</div> - -<h4 class="subsection">3.2.3 <code>@setfilename</code>: Set the output file name</h4> - -<p><a name="index-setfilename-164"></a><a name="index-Texinfo-requires-_0040code_007b_0040_0040setfilename_007d-165"></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-166"></a><a name="index-g_t_0040samp_007b_005cinput_007d-source-line-ignored-167"></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 ‘<samp><span class="samp">.texi</span></samp>’) entirely from the input file -name, or, preferably, replace it with the ‘<samp><span class="samp">.info</span></samp>’ extension. - - <p><a name="index-Length-of-file-names-168"></a><a name="index-File-name-collision-169"></a><a name="index-Info-file-name_002c-choosing-170"></a>Although an explicit ‘<samp><span class="samp">.info</span></samp>’ extension is preferable, some -operating systems cannot handle long file names. You can run into a -problem even when the file name you specify is itself short enough. -This occurs because the Info formatters split a long Info file into -short indirect subfiles, and name them by appending ‘<samp><span class="samp">-1</span></samp>’, -‘<samp><span class="samp">-2</span></samp>’, <small class="dots">...</small>, ‘<samp><span class="samp">-10</span></samp>’, ‘<samp><span class="samp">-11</span></samp>’, and so on, to the original -file name. (See <a href="#Tag-and-Split-Files">Tag and Split Files</a>.) The subfile name -<samp><span class="file">texinfo.info-10</span></samp>, for example, is too long for old systems with a -14-character limit on filenames; so the Info file name for this document -is <samp><span class="file">texinfo</span></samp> rather than <samp><span class="file">texinfo.info</span></samp>. 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 <samp><span class="file">texin-10</span></samp>, <samp><span class="file">gcc.i12</span></samp>, etc. - - <p>When producing HTML output, <code>makeinfo</code> will replace any extension -with ‘<samp><span class="samp">html</span></samp>’, or add ‘<samp><span class="samp">.html</span></samp>’ if the given name has no -extension. - - <p><a name="index-texinfo_002ecnf-171"></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 <samp><span class="file">texinfo.cnf</span></samp> 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> - -</div> - -<h4 class="subsection">3.2.4 <code>@settitle</code>: Set the document title</h4> - -<p><a name="index-settitle-172"></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-g_t_003ctitle_003e-HTML-tag-173"></a>In the HTML file produced by <samp><span class="command">makeinfo</span></samp>, <var>title</var> serves as -the document ‘<samp><span class="samp"><title></span></samp>’. It also becomes the default document -description in the ‘<samp><span class="samp"><head></span></samp>’ 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> - -</div> - -<h4 class="subsection">3.2.5 End of Header</h4> - -<p><a name="index-End-of-header-line-174"></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> - -</div> - -<h3 class="section">3.3 Document Permissions</h3> - -<p><a name="index-Document-Permissions-175"></a><a name="index-Copying-Permissions-176"></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> - -</div> - -<h4 class="subsection">3.3.1 <code>@copying</code>: Declare Copying Permissions</h4> - -<p><a name="index-copying-177"></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-178"></a>The <code>@copyright{}</code> command generates a ‘<samp><span class="samp">c</span></samp>’ inside a circle -in output formats that support this (print and HTML). In the other -formats (Info and plain text), it generates ‘<samp><span class="samp">(C)</span></samp>’. 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-179"></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-180"></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-181"></a><a name="index-Holder-of-copyright-for-FSF-works-182"></a><a name="index-Owner-of-copyright-for-FSF-works-183"></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. If you do use several lines, do not indent any of them -(or anything else in the <code>@copying</code> block) in the source file. - - <p>See <a href="maintain.html#Copyright-Notices">Copyright Notices</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> - -</div> - -<h4 class="subsection">3.3.2 <code>@insertcopying</code>: Include Permissions Text</h4> - -<p><a name="index-insertcopying-184"></a><a name="index-Copying-text_002c-including-185"></a><a name="index-Permissions-text_002c-including-186"></a><a name="index-Including-permissions-text-187"></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>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>), but this does not matter for legal purposes, -because the text is present. - - <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). - - <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-%26-Copyright-Page"></a> -<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> - -</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-188"></a><a name="index-Copyright-page_002c-for-plain-text-189"></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>; <samp><span class="command">makeinfo</span></samp> -includes this when writing plain text (‘<samp><span class="samp">--no-headers</span></samp>’), 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> - -</div> - -<h4 class="subsection">3.4.1 <code>@titlepage</code></h4> - -<p><a name="index-Title-page-190"></a><a name="index-titlepage-191"></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-192"></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-193"></a><a name="index-Bastard-title-page-194"></a><a name="index-Title-page_002c-bastard-195"></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> - -</div> - -<h4 class="subsection">3.4.2 <code>@titlefont</code>, <code>@center</code>, and <code>@sp</code></h4> - -<p><a name="index-titlefont-196"></a><a name="index-center-197"></a><a name="index-sp-_0040r_007b_0028titlepage-line-spacing_0029_007d-198"></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> - -</div> - -<h4 class="subsection">3.4.3 <code>@title</code>, <code>@subtitle</code>, and <code>@author</code></h4> - -<p><a name="index-title-199"></a><a name="index-subtitle-200"></a><a name="index-author-201"></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> - -</div> - -<h4 class="subsection">3.4.4 Copyright Page</h4> - -<p><a name="index-Copyright-page-202"></a><a name="index-Printed-permissions-203"></a><a name="index-Permissions_002c-printed-204"></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-205"></a><a name="index-filll-_0040r_007b_0040TeX_007b_007d-dimension_007d-206"></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 incantation 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 ‘<samp><span class="samp">0pt -plus 1filll</span></samp>’ 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 ‘<samp><span class="samp">l</span></samp>’s in the word -‘<samp><span class="samp">filll</span></samp>’; 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> - -</div> - -<h4 class="subsection">3.4.5 Heading Generation</h4> - -<p><a name="index-end-titlepage-207"></a><a name="index-Headings_002c-page_002c-begin-to-appear-208"></a><a name="index-Titlepage-end-starts-headings-209"></a><a name="index-End-titlepage-starts-headings-210"></a> -Like all <code>@end</code> commands (see <a href="#Quotations-and-Examples">Quotations and Examples</a>), the <code>@end titlepage</code> command -must be written at the beginning of a line by itself, with only one -space between the <code>@end</code> and the <code>titlepage</code>. 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> - -</div> - -<h4 class="subsection">3.4.6 The <code>@headings</code> Command</h4> - -<p><a name="index-headings-211"></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 predefined 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><dd>Turn on page headings appropriate for double-sided printing. - - <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 ‘<samp><span class="samp">@setchapternewpage -on</span></samp>’, <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> - -</div> - -<h3 class="section">3.5 Generating a Table of Contents</h3> - -<p><a name="index-Table-of-contents-212"></a><a name="index-Contents_002c-Table-of-213"></a><a name="index-Short-table-of-contents-214"></a><a name="index-contents-215"></a><a name="index-summarycontents-216"></a><a name="index-shortcontents-217"></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-218"></a><a name="index-setshortcontentsaftertitlepage-219"></a><a name="index-Contents_002c-after-title-page-220"></a><a name="index-Table-of-contents_002c-after-title-page-221"></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 <samp><span class="command">texi2dvi</span></samp> (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> - -</div> - -<h3 class="section">3.6 The `Top' Node and Master Menu</h3> - -<p><a name="index-Top-node-222"></a><a name="index-Node_002c-_0060Top_0027-223"></a> -The `Top' node is the node in which a reader enters an Info manual. -As such, it should begin with a brief description of the manual -(including the version number), 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-224"></a>It is conventional and desirable 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 ifnottex</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> - -</div> - -<h4 class="subsection">3.6.1 Top Node Example</h4> - -<p><a name="index-Top-node-example-225"></a> -Here is an example of a Top node. - -<pre class="example"> @ifnottex - @node Top - @top Sample Title - - @insertcopying - @end ifnottex - - 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> - -</div> - -<h4 class="subsection">3.6.2 Parts of a Master Menu</h4> - -<p><a name="index-Master-menu-226"></a><a name="index-Menu_002c-master-227"></a><a name="index-Parts-of-a-master-menu-228"></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><a name="index-detailmenu-229"></a><a name="index-Detailed-menu-230"></a>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:: - * General 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> - -</div> - -<h3 class="section">3.7 Global Document Commands</h3> - -<p><a name="index-Global-Document-Commands-231"></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> - -</div> - -<h4 class="subsection">3.7.1 <code>@documentdescription</code>: Summary Text</h4> - -<p><a name="index-Document-description-232"></a><a name="index-Description-of-document-233"></a><a name="index-Summary-of-document-234"></a><a name="index-Abstract-of-document-235"></a><a name="index-g_t_003cmeta_003e-HTML-tag_002c-and-document-description-236"></a><a name="index-documentdescription-237"></a> -When producing HTML output for a document, <samp><span class="command">makeinfo</span></samp> writes a -‘<samp><span class="samp"><meta></span></samp>’ element in the ‘<samp><span class="samp"><head></span></samp>’ 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 ‘<samp><span class="samp"><head></span></samp>’ 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> - -</div> - -<h4 class="subsection">3.7.2 <code>@setchapternewpage</code>:</h4> - -<p><a name="index-Starting-chapters-238"></a><a name="index-Pages_002c-starting-odd-239"></a><a name="index-setchapternewpage-240"></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 -<samp><span class="option">--texinfo</span></samp> option to <samp><span class="command">texi2dvi</span></samp> 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> - -</div> - -<h4 class="subsection">3.7.3 <code>@paragraphindent</code>: Paragraph Indenting</h4> - -<p><a name="index-Indenting-paragraphs_002c-control-of-241"></a><a name="index-Paragraph-indentation-control-242"></a><a name="index-paragraphindent-243"></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 ‘<samp><span class="samp">asis</span></samp>’ 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> - -</div> - -<h4 class="subsection">3.7.4 <code>@firstparagraphindent</code>: Indenting After Headings</h4> - -<p><a name="index-First-paragraph_002c-suppressing-indentation-of-244"></a><a name="index-Suppressing-first-paragraph-indentation-245"></a><a name="index-Preventing-first-paragraph-indentation-246"></a><a name="index-Indenting_002c-suppressing-of-first-paragraph-247"></a><a name="index-Headings_002c-indentation-after-248"></a><a name="index-firstparagraphindent-249"></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 <samp><span class="command">makeinfo</span></samp> 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> - -</div> - -<h4 class="subsection">3.7.5 <code>@exampleindent</code>: Environment Indenting</h4> - -<p><a name="index-Indenting-environments-250"></a><a name="index-Environment-indentation-251"></a><a name="index-Example-indentation-252"></a><a name="index-exampleindent-253"></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 ‘<samp><span class="samp">asis</span></samp>’ or a number: - -<pre class="example"> @exampleindent <var>indent</var> -</pre> - <p><code>@exampleindent</code> is ignored for HTML output. Otherwise, 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 spaces in Info, and 0.4<span class="dmn">in</span> -in TeX, which is somewhat less. (The reduction is to help TeX -fit more characters onto physical lines.) - - <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> - -</div> - -<h3 class="section">3.8 Software Copying Permissions</h3> - -<p><a name="index-Software-copying-permissions-254"></a><a name="index-Copying-software-255"></a><a name="index-Distribution-256"></a><a name="index-License-agreement-257"></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-258"></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> - -</div> - -<h2 class="chapter">4 Ending a Texinfo File</h2> - -<p><a name="index-Ending-a-Texinfo-file-259"></a><a name="index-Texinfo-file-ending-260"></a><a name="index-File-ending-261"></a><a name="index-bye-262"></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-%26-Menus"></a> -<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> - -</div> - -<h3 class="section">4.1 Printing Indices and Menus</h3> - -<p><a name="index-Printing-an-index-263"></a><a name="index-Indices_002c-printing-and-menus-264"></a><a name="index-Generating-menus-with-indices-265"></a><a name="index-Menus-generated-with-indices-266"></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-267"></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; <samp><span class="command">makeinfo</span></samp> 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> - -</div> - -<h3 class="section">4.2 <code>@bye</code> File Ending</h3> - -<p><a name="index-bye-268"></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> - -</div> - -<h2 class="chapter">5 Chapter Structuring</h2> - -<p><a name="index-Chapter-structuring-269"></a><a name="index-Structuring-of-chapters-270"></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> - -</div> - -<h3 class="section">5.1 Tree Structure of Sections</h3> - -<p><a name="index-Tree-structuring-271"></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> - -</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> - -</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 ‘<samp><span class="samp">@node Top</span></samp>’ 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> - -</div> - -<!-- node-name, next, previous, up --> -<h3 class="section">5.4 <code>@chapter</code></h3> - -<p><a name="index-chapter-272"></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-273"></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-%26-appendix"></a> -<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> - -</div> - -<h3 class="section">5.5 <code>@unnumbered</code> and <code>@appendix</code></h3> - -<p><a name="index-unnumbered-274"></a><a name="index-appendix-275"></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 (`A', `B', <small class="dots">...</small>) instead of by number. - - <p>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-%26-chapheading"></a> -<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> - -</div> - -<h3 class="section">5.6 <code>@majorheading</code>, <code>@chapheading</code></h3> - -<p><a name="index-majorheading-276"></a><a name="index-chapheading-277"></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> - -</div> - -<h3 class="section">5.7 <code>@section</code></h3> - -<p><a name="index-section-278"></a> -A <code>@section</code> command identifies a section within a chapter unit, -whether created with <code>@chapter</code>, <code>@unnumbered</code>, or -<code>@appendix</code>, following the numbering scheme of the chapter-level -command. Thus, within a <code>@chapter</code> chapter numbered `1', the -section is numbered like `1.2'; within an <code>@appendix</code> -“chapter” labeled `A', the section is numbered like `A.2'; within an -<code>@unnumbered</code> chapter, the section gets no number. - - <p>For example, 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. The output is underlined with ‘<samp><span class="samp">=</span></samp>’ in Info. - - <p>Thus, - -<pre class="example"> @section This is a section -</pre> - <p class="noindent">might produce the following in Info: - -<pre class="example"> 5.7 This is a section - ===================== -</pre> - <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> - -</div> - -<h3 class="section">5.8 <code>@unnumberedsec</code>, <code>@appendixsec</code>, <code>@heading</code></h3> - -<p><a name="index-unnumberedsec-279"></a><a name="index-appendixsec-280"></a><a name="index-heading-281"></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, as described -in the previous section. - - <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-282"></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> - - <p><code>@unnumberedsec</code> and <code>@appendixsec</code> do not need to be used -in ordinary circumstances, because <code>@section</code> may also be used -within <code>@unnumbered</code> and <code>@appendix</code> chapters; again, see -the previous section. - -<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> - -</div> - -<h3 class="section">5.9 The <code>@subsection</code> Command</h3> - -<p><a name="index-subsection-283"></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 ‘<samp><span class="samp">-</span></samp>’. For example, - -<pre class="example"> @subsection This is a subsection -</pre> - <p class="noindent">produces - -<pre class="example"> 1.2.3 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> - -</div> - -<h3 class="section">5.10 The <code>@subsection</code>-like Commands</h3> - -<p><a name="index-Subsection_002dlike-commands-284"></a><a name="index-unnumberedsubsec-285"></a><a name="index-appendixsubsec-286"></a><a name="index-subheading-287"></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. - - <p><code>@unnumberedsubsec</code> and <code>@appendixsubsec</code> do not need to -be used in ordinary circumstances, because <code>@subsection</code> may -also be used within sections of <code>@unnumbered</code> and -<code>@appendix</code> chapters (see <a href="#section"><code>section</code></a>). - -<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> - -</div> - -<h3 class="section">5.11 The `subsub' Commands</h3> - -<p><a name="index-Subsub-commands-288"></a><a name="index-subsubsection-289"></a><a name="index-unnumberedsubsubsec-290"></a><a name="index-appendixsubsubsec-291"></a><a name="index-subsubheading-292"></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><code>@unnumberedsubsubsec</code> and <code>@appendixsubsubsec</code> do not -need to be used in ordinary circumstances, because -<code>@subsubsection</code> may also be used within subsections of -<code>@unnumbered</code> and <code>@appendix</code> chapters -(see <a href="#section"><code>section</code></a>). - - <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"> 1.2.3.4 This is a subsubsection - ............................... -</pre> - <div class="node"> -<p><hr> -<a name="Raise%2flower-sections"></a> -<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> - -</div> - -<h3 class="section">5.12 <code>@raisesections</code> and <code>@lowersections</code></h3> - -<p><a name="index-raisesections-293"></a><a name="index-lowersections-294"></a><a name="index-Raising-and-lowering-sections-295"></a><a name="index-Lowering-and-raising-sections-296"></a><a name="index-Sections_002c-raising-and-lowering-297"></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-298"></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 <samp><span class="command">makeinfo</span></samp> for implicitly determining node -pointers. Since <samp><span class="command">makeinfo</span></samp> 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 -<samp><span class="command">makeinfo</span></samp>'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> - -</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> - -</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> - -</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> - -</div> - -<h3 class="section">6.3 The <code>@node</code> Command</h3> - -<p><a name="index-Node_002c-defined-299"></a><a name="index-node-300"></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 specify 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 (for details of node names, see <a href="#Node-Line-Requirements">Node Line Requirements</a>). 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><a name="index-accesskey_0040r_007b_002c-in-HTML-output_007d-301"></a>Whether the node pointers are specified implicitly or explicitly, the -HTML output from <samp><span class="command">makeinfo</span></samp> for each node includes links to -the `Next', `Previous', and `Up' nodes. The HTML also uses the -<code>accesskey</code> attribute with the values ‘<samp><span class="samp">n</span></samp>’, ‘<samp><span class="samp">p</span></samp>’, and -‘<samp><span class="samp">u</span></samp>’ respectively. This allows people using web browsers to -follow the nagivation using (typically) <kbd>M-</kbd><var>letter</var>, e.g., -<kbd>M-n</kbd> for the `Next' node, from anywhere within the node. - - <p>You may insert spaces before each name on the <code>@node</code> line 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>.) - - <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> - -</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 (for details of node names, -see <a href="#Node-Line-Requirements">Node Line Requirements</a>). 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 the present 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 <samp><span class="file">dir</span></samp> 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 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> - -</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-g_t_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 -‘<samp><span class="samp">@node</span></samp>’ 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>The <var>node-name</var> argument must be present, but the others are -optional. If you wish to specify some but not others, just insert -commas as needed, as in: ‘<samp><span class="samp">@node mynode,,,uppernode</span></samp>’. However, -we recommend leaving off all the pointers and letting <code>makeinfo</code> -determine them, as described above. - - <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> - -</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> - -</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-g_t_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 ‘<samp><span class="samp">@</span></samp>’, such as <code>@</code> and -<code>{</code>, and accent commands such as ‘<samp><span class="samp">@'</span></samp>’. (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 ‘<samp><span class="samp">@node</span></samp>’ 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, ‘<samp><span class="samp">foo bar</span></samp>’. 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> - -</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-g_t_0028dir_0029-as-Up-node-of-Top-node-325"></a>The Top node (which must be named ‘<samp><span class="samp">top</span></samp>’ or ‘<samp><span class="samp">Top</span></samp>’) 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 ‘<samp><span class="samp">(dir)</span></samp>’ as the parent of the Top node; this is -short for ‘<samp><span class="samp">(dir)top</span></samp>’, and specifies the Top node in the <samp><span class="file">dir</span></samp> -file, which contains the main menu for the Info system as a whole. - - <li><a name="index-Prev-node-of-Top-node-326"></a>The `Prev' node of the Top node should also be your ‘<samp><span class="samp">(dir)</span></samp>’ file. - - <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 <samp><span class="file">info</span></samp> directory. - - <p>It is usually best to leave the pointers off entirely and let the -tools implicitly define them, with this simple result: - -<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> - -</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> - -</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. We -highly recommend using it. - - <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><a name="index-Detail-menu-332"></a><a name="index-detailmenu-333"></a>If you use a detailed menu in your master menu (see <a href="#Master-Menu-Parts">Master Menu Parts</a>), mark it with the <code>@detailmenu @dots{} @end -detailmenu</code> environment, or <samp><span class="command">makeinfo</span></samp> will get confused, -typically about the last and/or first node in the document. - - <p>This implicit node pointer creation 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 all 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> - -</div> - -<h3 class="section">6.5 <code>@anchor</code>: Defining Arbitrary Cross-reference Targets</h3> - -<p><a name="index-anchor-334"></a><a name="index-Anchors-335"></a><a name="index-Cross_002dreference-targets_002c-arbitrary-336"></a><a name="index-Targets-for-cross_002dreferences_002c-arbitrary-337"></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. -Whitespace (including newlines) is 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</a>.) - - <p>Also like node names, anchor names cannot include some characters -(see <a href="#Node-Line-Requirements">Node Line Requirements</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> - -</div> - -<h2 class="chapter">7 Menus</h2> - -<p><a name="index-Menus-338"></a><a name="index-menu-339"></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 text 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> - -</div> - -<h3 class="section">7.1 Menu Location</h3> - -<p><a name="index-Menu-location-340"></a><a name="index-Location-of-menus-341"></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-342"></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-343"></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 -<samp><span class="command">makeinfo</span></samp> 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 ‘<samp><span class="samp">@heading</span></samp>’ 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 this also does not work with -<samp><span class="command">makeinfo</span></samp>'s implicit pointer creation, and it also makes the -XML output incorrect, since it does not reflect the true document -structure. So, regrettably, 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> - -</div> - -<h3 class="section">7.2 Writing a Menu</h3> - -<p><a name="index-Writing-a-menu-344"></a><a name="index-Menu-writing-345"></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 ‘<samp><span class="samp">* </span></samp>’<!-- /@w --> is a <dfn>menu -entry</dfn>. (Note the space after the asterisk.) A line that does not -start with an ‘<samp><span class="samp">* </span></samp>’<!-- /@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 ‘<samp><span class="samp">Larger Units of Text</span></samp>’ is a -menu comment line; the two lines starting with ‘<samp><span class="samp">* </span></samp>’<!-- /@w --> are menu -<a name="index-Spaces_002c-in-menus-346"></a>entries. Space characters in a menu are preserved as-is; this allows -you to format the menu as you wish. - - <p><a name="index-accesskey_0040r_007b_002c-in-HTML-output_007d-347"></a>In the HTML output from <samp><span class="command">makeinfo</span></samp>, the <code>accesskey</code> -attribute is used with the values ‘<samp><span class="samp">1</span></samp>’<small class="dots">...</small>‘<samp><span class="samp">9</span></samp>’ for the -first nine entries. This allows people using web browsers to follow -the first menu entries using (typically) <kbd>M-</kbd><var>digit</var>, e.g., -<kbd>M-1</kbd> for the first entry. - -<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> - -</div> - -<h3 class="section">7.3 The Parts of a Menu</h3> - -<p><a name="index-Parts-of-a-menu-348"></a><a name="index-Menu-parts-349"></a><a name="index-g_t_0040code_007b_0040_0040menu_007d-parts-350"></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> - -</div> - -<!-- node-name, next, previous, up --> -<h3 class="section">7.4 Less Cluttered Menu Entry</h3> - -<p><a name="index-Two-part-menu-entry-351"></a><a name="index-Double_002dcolon-menu-entries-352"></a><a name="index-Menu-entries-with-two-colons-353"></a><a name="index-Less-cluttered-menu-entry-354"></a><a name="index-Uncluttered-menu-entry-355"></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> - -</div> - -<!-- node-name, next, previous, up --> -<h3 class="section">7.5 A Menu Example</h3> - -<p><a name="index-Menu-example-356"></a><a name="index-Example-menu-357"></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. ‘<samp><span class="samp">Files</span></samp>’ is both a menu -entry name and the name of the node referred to by that name. -‘<samp><span class="samp">Multiples</span></samp>’ is the menu entry name; it refers to the node named -‘<samp><span class="samp">Buffers</span></samp>’. The line ‘<samp><span class="samp">Larger Units of Text</span></samp>’ is a comment; it -appears in the menu, but is not an entry. - - <p>Since no file name is specified with either ‘<samp><span class="samp">Files</span></samp>’ or -‘<samp><span class="samp">Buffers</span></samp>’, 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> - -</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-358"></a><a name="index-Nodes-in-other-Info-files-359"></a><a name="index-Other-Info-files_0027-nodes-360"></a><a name="index-Going-to-other-Info-files_0027-nodes-361"></a><a name="index-Info_003b-other-files_0027-nodes-362"></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 ‘<samp><span class="samp">Outlining</span></samp>’ and -‘<samp><span class="samp">Rebinding</span></samp>’ 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 <samp><span class="file">dir</span></samp> 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 <samp><span class="file">dir</span></samp> 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> - -</div> - -<h2 class="chapter">8 Cross References</h2> - -<p><a name="index-Making-cross-references-363"></a><a name="index-Cross-references-364"></a><a name="index-References-365"></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> - -</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 ‘<samp><span class="samp">f</span></samp>’ 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> - -</div> - -<!-- node-name, next, previous, up --> -<h3 class="section">8.2 Different Cross Reference Commands</h3> - -<p><a name="index-Different-cross-reference-commands-366"></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 ‘<samp><span class="samp">*Note </span><var>name</var><span class="samp">: </span><var>node</var><span class="samp">.</span></samp>’. - - <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. (‘<samp><span class="samp">p</span></samp>’ 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> - -</div> - -<!-- node-name, next, previous, up --> -<h3 class="section">8.3 Parts of a Cross Reference</h3> - -<p><a name="index-Cross-reference-parts-367"></a><a name="index-Parts-of-a-cross-reference-368"></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 or the topic description. If you -include this argument, it becomes the first part of the cross reference. -It is usually omitted; then the topic description (third argument) is -used if it was specified; if that was omitted as well, the node name -is used. - - <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 ‘<samp><span class="samp">.info</span></samp>’ -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> - -</div> - -<!-- node-name, next, previous, up --> -<h3 class="section">8.4 <code>@xref</code></h3> - -<p><a name="index-xref-369"></a><a name="index-Cross-references-using-_0040code_007b_0040_0040xref_007d-370"></a><a name="index-References-using-_0040code_007b_0040_0040xref_007d-371"></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 ‘<samp><span class="samp">f</span></samp>’ 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> - -</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> - -</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> - -</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> - -</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> - -</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> - -</div> - -<h3 class="section">8.5 Naming a `Top' Node</h3> - -<p><a name="index-Naming-a-_0060Top_0027-Node-in-references-372"></a><a name="index-g_t_0040samp_007b_0040r_007bTop_007d_007d-node-naming-for-references-373"></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, ‘<samp><span class="samp">Top</span></samp>’ is the name of the first node, and -‘<samp><span class="samp">Overview</span></samp>’ 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> - -</div> - -<h3 class="section">8.6 <code>@ref</code></h3> - -<p><a name="index-Cross-references-using-_0040code_007b_0040_0040ref_007d-374"></a><a name="index-References-using-_0040code_007b_0040_0040ref_007d-375"></a><a name="index-ref-376"></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-377"></a> -<pre class="example"> For more information, @pxref{This}, and @ref{That}. -</pre> - <p class="noindent">produces in Info: - -<pre class="example"> For more information, *note This::, and *note That::. -</pre> - <p class="noindent">and in printed output: - - <blockquote> -For more information, see Section 1.1 [This], page 1, -and Section 1.2 [That], page 2. -</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-378"></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, “note” being a verb: - -<pre class="example"> Sea surges are described in *note Hurricanes::. -</pre> - <p>You should write a period or comma immediately after an <code>@ref</code> -command with two or more arguments. If there is no such following -punctuation, <samp><span class="command">makeinfo</span></samp> will generate a (grammatically -incorrect) period in the Info output; otherwise, the cross-reference -would fail completely, due to the current syntax of Info format. - - <p>In general, it is best to use <code>@ref</code> only when you need some -word other than “see” to precede the reference. When “see” (or -“See”) is ok, <code>@xref</code> and <code>@pxref</code> are preferable. - -<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> - -</div> - -<h3 class="section">8.7 <code>@pxref</code></h3> - -<p><a name="index-Cross-references-using-_0040code_007b_0040_0040pxref_007d-379"></a><a name="index-References-using-_0040code_007b_0040_0040pxref_007d-380"></a><a name="index-pxref-381"></a> -The parenthetical reference command, <code>@pxref</code>, is nearly the -same as <code>@xref</code>, but it is best used at the end of a sentence or -before a closing parenthesis. 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, if necessary. - </ol> - - <p><code>@pxref</code> is designed so that the output looks right and works -right at the end of a sentence or parenthetical phrase, 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-382"></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>). - - <p>In past versions of Texinfo, it was not allowed to write punctuation -after a <code>@pxref</code>, so it could be used <em>only</em> before a right -parenthesis. This is no longer the case, so now it can be used (for -example) at the end of a sentence, where a lowercase “see” works -best. For instance: - -<pre class="example"> ... For more information, @pxref{More}. -</pre> - <p class="noindent">which outputs (in Info): - -<pre class="example"> ... For more information, *note More::. -</pre> - <p class="noindent">This works fine. <code>@pxref</code> should only be followed by a comma, -period, or right parenthesis; in other cases, <samp><span class="command">makeinfo</span></samp> has -to insert a period to make the cross-reference work correctly in Info, -and that period looks wrong. - - <p>As a matter of general style, <code>@pxref</code> is best used at the ends -of sentences. Although it technically works 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> - -</div> - -<h3 class="section">8.8 <code>@inforef</code></h3> - -<p><a name="index-Cross-references-using-_0040code_007b_0040_0040inforef_007d-383"></a><a name="index-References-using-_0040code_007b_0040_0040inforef_007d-384"></a><a name="index-inforef-385"></a> -<code>@inforef</code> is used for making cross references to Info -documents—even from a printed manual. This might be because you -want to refer to conditional <code>@ifinfo</code> text -(see <a href="#Conditionals">Conditionals</a>), or because printed output is not available -(perhaps because there is no Texinfo source), among other -possibilities. - - <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 -‘<samp><span class="samp">}</span></samp>’, 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">For example, - -<pre class="example"> @inforef{Advanced, Advanced Info commands, info}, - for more information. -</pre> - <p class="noindent">produces (in Info): - -<pre class="example"> *Note Advanced Info commands: (info)Advanced, - for more information. -</pre> - <p class="noindent">and (in the printed output): - - <blockquote> -See Info file <samp><span class="file">info</span></samp>, node ‘<samp><span class="samp">Advanced</span></samp>’, for more information. -</blockquote> - - <p>(This particular example is not realistic, since the Info manual is -written in Texinfo, so all formats are available.) - - <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> - -</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-386"></a><a name="index-Uniform-resource-locator_002c-referring-to-387"></a><a name="index-URL_002c-referring-to-388"></a> -<a name="index-g_t_0040code_007bhref_007d_002c-producing-HTML-389"></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 -meaning. - - <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-390"></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 ‘<samp><span class="samp">/</span></samp>’ 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} program ... -</pre> - <p class="noindent">produces: -<pre class="display"> The <a href="/man.cgi/1/ls">ls</a> program <small class="dots">...</small> -</pre> - <p class="noindent">but with HTML: -<pre class="example"> The <a href="/man.cgi/1/ls">ls</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-g_t_003cURL_003a-convention_002c-not-used-391"></a>You can use this form in the input file if you wish. We feel it's not -necessary to include the ‘<samp><span class="samp"><URL:</span></samp>’ and ‘<samp><span class="samp">></span></samp>’ in the output, -since any software that tries to detect url's in text already has to -detect them without the ‘<samp><span class="samp"><URL:</span></samp>’ 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> - -</div> - -<h2 class="chapter">9 Marking Words and Phrases</h2> - -<p><a name="index-Paragraph_002c-marking-text-within-392"></a><a name="index-Marking-words-and-phrases-393"></a><a name="index-Words-and-phrases_002c-marking-them-394"></a><a name="index-Marking-text-within-a-paragraph-395"></a><a name="index-Text_002c-marking-up-396"></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> - -</div> - -<h3 class="section">9.1 Indicating Definitions, Commands, etc.</h3> - -<p><a name="index-Highlighting-text-397"></a><a name="index-Indicating-commands_002c-definitions_002c-etc_002e-398"></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>: Indicating a literal sequence of characters. -<li><a accesskey="6" href="#verb">verb</a>: Indicating 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="#abbr">abbr</a>: Indicating abbreviations. -<li><a href="#acronym">acronym</a>: Indicating acronyms. -<li><a href="#indicateurl">indicateurl</a>: Indicating an example URL. -<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> - -</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. -See <a href="#code"><code>@code</code></a>. - - <br><dt><code>@kbd{</code><var>keyboard-characters</var><code>}</code><dd>Indicate keyboard input. -See <a href="#kbd"><code>@kbd</code></a>. - - <br><dt><code>@key{</code><var>key-name</var><code>}</code><dd>Indicate the conventional name for a key on a keyboard. -See <a href="#key"><code>@key</code></a>. - - <br><dt><code>@samp{</code><var>text</var><code>}</code><dd>Indicate text that is a literal example of a sequence of characters. -See <a href="#samp"><code>@samp</code></a>. - - <br><dt><code>@verb{</code><var>text</var><code>}</code><dd>Write a verbatim sequence of characters. -See <a href="#verb"><code>@verb</code></a>. - - <br><dt><code>@var{</code><var>metasyntactic-variable</var><code>}</code><dd>Indicate a metasyntactic variable. -See <a href="#var"><code>@var</code></a>. - - <br><dt><code>@env{</code><var>environment-variable</var><code>}</code><dd>Indicate an environment variable. -See <a href="#env"><code>@env</code></a>. - - <br><dt><code>@file{</code><var>file-name</var><code>}</code><dd>Indicate the name of a file. -See <a href="#file"><code>@file</code></a>. - - <br><dt><code>@command{</code><var>command-name</var><code>}</code><dd>Indicate the name of a command. -See <a href="#command"><code>@command</code></a>. - - <br><dt><code>@option{</code><var>option</var><code>}</code><dd>Indicate a command-line option. -See <a href="#option"><code>@option</code></a>. - - <br><dt><code>@dfn{</code><var>term</var><code>}</code><dd>Indicate the introductory or defining use of a term. -See <a href="#dfn"><code>@dfn</code></a>. - - <br><dt><code>@cite{</code><var>reference</var><code>}</code><dd>Indicate the name of a book. -See <a href="#cite"><code>@cite</code></a>. - - <br><dt><code>@abbr{</code><var>abbreviation</var><code>}</code><dd>Indicate an abbreviation. - - <br><dt><code>@acronym{</code><var>acronym</var><code>}</code><dd>Indicate an acronym. -See <a href="#acronym"><code>@acronym</code></a>. - - <br><dt><code>@indicateurl{</code><var>uniform-resource-locator</var><code>}</code><dd>Indicate an example (that is, nonfunctional) uniform resource locator. -See <a href="#indicateurl"><code>@indicateurl</code></a>. (Use <code>@url</code> -(see <a href="#uref"><code>@url</code></a>) for live url's.) - - <br><dt><code>@email{</code><var>email-address</var><code>[, </code><var>displayed-text</var><code>]}</code><dd>Indicate an electronic mail address. -See <a href="#email"><code>@email</code></a>. - - </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> - -</div> - -<h4 class="subsection">9.1.2 <code>@code</code>{<var>sample-code</var>}</h4> - -<p><a name="index-code-399"></a> -<a name="index-Syntactic-tokens_002c-indicating-400"></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-401"></a><a name="index-Keywords_002c-indicating-402"></a><a name="index-Reserved-words_002c-indicating-403"></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 ‘<samp><span class="samp">@code{@@code}</span></samp>’ and -‘<samp><span class="samp">@code{@@samp}</span></samp>’ in the Texinfo source, respectively. - - <p><a name="index-Case_002c-not-altering-in-_0040code_007b_0040_0040code_007d-404"></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. -For example, - -<pre class="example"> The function returns @code{nil}. -</pre> - <p class="noindent">produces this: - - <blockquote> -The function returns <code>nil</code>. -</blockquote> - - <p>Here are some cases for which it is preferable <em>not</em> to use <code>@code</code>: - - <ul> -<li>For shell command names such as <samp><span class="command">ls</span></samp> (use <code>@command</code>). - - <li>For shell options such as ‘<samp><span class="samp">-c</span></samp>’ 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 <samp><span class="env">TEXINPUTS</span></samp> (use <code>@env</code>). - - <li>For a string of characters shorter than a syntactic token. For example, -if you are writing about ‘<samp><span class="samp">goto-ch</span></samp>’, 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. - - <p>Ordinarily, TeX will consider breaking lines at ‘<samp><span class="samp">-</span></samp>’ and -‘<samp><span class="samp">_</span></samp>’ characters within <code>@code</code> and related commands. This -can be controlled with <code>@allowcodebreaks</code> -(see <a href="#allowcodebreaks"><code>@allowcodebreaks</code></a>). - -<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> - -</div> - -<h4 class="subsection">9.1.3 <code>@kbd</code>{<var>keyboard-characters</var>}</h4> - -<p><a name="index-kbd-405"></a><a name="index-Keyboard-input-406"></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-407"></a><a name="index-Slanted-typewriter-font_002c-for-_0040code_007b_0040_0040kbd_007d-408"></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-409"></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-410"></a><a name="index-example_0040r_007b_002c-value-for-_0040code_007b_0040_0040kbdinputstyle_007d_007d-411"></a><a name="index-code_0040r_007b_002c-value-for-_0040code_007b_0040_0040kbdinputstyle_007d_007d-412"></a> - <dl> -<dt>‘<samp><span class="samp">code</span></samp>’<dd>Always use the same font for <code>@kbd</code> as <code>@code</code>. -<br><dt>‘<samp><span class="samp">example</span></samp>’<dd>Use the distinguishing font for <code>@kbd</code> only in <code>@example</code> -and similar environments. -<br><dt>‘<samp><span class="samp">distinct</span></samp>’<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 ‘<samp><span class="samp">r</span></samp>’ 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> - -</div> - -<h4 class="subsection">9.1.4 <code>@key</code>{<var>key-name</var>}</h4> - -<p><a name="index-key-413"></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> and <kbd>M-<TAB></kbd> you -would type: - -<pre class="example"> @kbd{C-x @key{ESC}} - @kbd{M-@key{TAB}} -</pre> - <p>Here is a list of the recommended names for keys: -<a name="index-Recommended-names-for-keys-414"></a><a name="index-Keys_002c-recommended-names-415"></a><a name="index-Names-recommended-for-keys-416"></a><a name="index-Abbreviations-for-keys-417"></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>DELETE</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-418"></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 ‘<samp><span class="samp">@kbd{Meta-a}</span></samp>’ to produce <kbd>Meta-a</kbd> and -‘<samp><span class="samp">@key{META}</span></samp>’ to produce <META>. - - <p>As a convention in GNU manuals, <code>@key</code> should not be used in -index entries. - -<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> - -</div> - -<h4 class="subsection">9.1.5 <code>@samp</code>{<var>text</var>}</h4> - -<p><a name="index-samp-419"></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 ‘<samp><span class="samp">foo</span></samp>’ at the end of the line, use the regexp -‘<samp><span class="samp">foo$</span></samp>’. -</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 ‘<samp><span class="samp">a</span></samp>’, ‘<samp><span class="samp">e</span></samp>’, -‘<samp><span class="samp">i</span></samp>’, ‘<samp><span class="samp">o</span></samp>’, ‘<samp><span class="samp">u</span></samp>’, and sometimes -‘<samp><span class="samp">y</span></samp>’. -</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> - -</div> - -<h4 class="subsection">9.1.6 <code>@verb</code>{<char><var>text</var><char>}</h4> - -<p><a name="index-verb-420"></a><a name="index-Verbatim-in_002dline-text-421"></a> -<a name="index-Delimiter-character_002c-for-verbatim-422"></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. In particular, it does not work to use <code>@verb</code> in -anything related to cross-referencing, such as section titles or -figure captions. - -<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> - -</div> - -<h4 class="subsection">9.1.7 <code>@var</code>{<var>metasyntactic-variable</var>}</h4> - -<p><a name="index-var-423"></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 ‘<samp><span class="samp">rm </span><var>filename</var></samp>’. -</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 <samp><span class="file">texinfo.tex</span></samp> 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> - -</div> - -<h4 class="subsection">9.1.8 <code>@env</code>{<var>environment-variable</var>}</h4> - -<p><a name="index-env-424"></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 <samp><span class="env">PATH</span></samp> 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> - -</div> - -<h4 class="subsection">9.1.9 <code>@file</code>{<var>file-name</var>}</h4> - -<p><a name="index-file-425"></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 <samp><span class="file">.el</span></samp> files are in -the <samp><span class="file">/usr/local/emacs/lisp</span></samp> 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> - -</div> - -<h4 class="subsection">9.1.10 <code>@command</code>{<var>command-name</var>}</h4> - -<p><a name="index-command-426"></a><a name="index-Command-names_002c-indicating-427"></a><a name="index-Program-names_002c-indicating-428"></a> -Use the <code>@command</code> command to indicate command names, such as -<samp><span class="command">ls</span></samp> or <samp><span class="command">cc</span></samp>. - - <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 <samp><span class="command">ls</span></samp> 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 ‘<samp><span class="samp">ls -l</span></samp>’, -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> - -</div> - -<h4 class="subsection">9.1.11 <code>@option</code>{<var>option-name</var>}</h4> - -<p><a name="index-option-429"></a> -Use the <code>@option</code> command to indicate a command-line option; for -example, <samp><span class="option">-l</span></samp> or <samp><span class="option">--version</span></samp> or -<samp><span class="option">--output=</span><var>filename</var></samp>. - - <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 <samp><span class="option">-l</span></samp> 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> - -</div> - -<!-- node-name, next, previous, up --> -<h4 class="subsection">9.1.12 <code>@dfn</code>{<var>term</var>}</h4> - -<p><a name="index-dfn-430"></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="#abbr">abbr</a>, -Previous: <a rel="previous" accesskey="p" href="#dfn">dfn</a>, -Up: <a rel="up" accesskey="u" href="#Indicating">Indicating</a> - -</div> - -<h4 class="subsection">9.1.13 <code>@cite</code>{<var>reference</var>}</h4> - -<p><a name="index-cite-431"></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="abbr"></a> -Next: <a rel="next" accesskey="n" href="#acronym">acronym</a>, -Previous: <a rel="previous" accesskey="p" href="#cite">cite</a>, -Up: <a rel="up" accesskey="u" href="#Indicating">Indicating</a> - -</div> - -<h4 class="subsection">9.1.14 <code>@abbr</code>{<var>abbreviation</var>[, <var>meaning</var>]}</h4> - -<p><a name="index-abbr-432"></a> -<a name="index-Abbreviations_002c-tagging-433"></a>You can use the <code>@abbr</code> command for general abbreviations. The -abbreviation is given as the single argument in braces, as in -‘<samp><span class="samp">@abbr{Comput.}</span></samp>’. As a matter of style, or for particular -abbreviations, you may prefer to omit periods, as in -‘<samp><span class="samp">@abbr{Mr} Stallman</span></samp>’. - - <p><code>@abbr</code> accepts an optional second argument, intended to be used -for the meaning of the abbreviation. - - <p>If the abbreviation ends with a lowercase letter and a period, and is -not at the end of a sentence, and has no second argument, remember to -use the <code>@.</code> command (see <a href="#Not-Ending-a-Sentence">Not Ending a Sentence</a>) to get the correct spacing. However, you do not have to -use <code>@.</code> within the abbreviation itself; Texinfo automatically -assumes periods within the abbreviation do not end a sentence. - - <p><a name="index-g_t_003cabbr_003e-tag-434"></a>In TeX and in the Info output, the first argument is printed as-is; -if the second argument is present, it is printed in parentheses after -the abbreviation. In HTML and XML, the <code><abbr></code> tag is -used; in Docbook, the <code><abbrev></code> tag is used. For instance: - -<pre class="example"> @abbr{Comput. J., Computer Journal} -</pre> - <p class="noindent">produces: - -<pre class="display"> <abbr title="Computer Journal">Comput. J.</abbr> (Computer Journal) -</pre> - <p>For abbreviations consisting of all capital letters, you may prefer to -use the <code>@acronym</code> command instead. See the next section for -more on the usage of these two commands. - -<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="#abbr">abbr</a>, -Up: <a rel="up" accesskey="u" href="#Indicating">Indicating</a> - -</div> - -<h4 class="subsection">9.1.15 <code>@acronym</code>{<var>acronym</var>[, <var>meaning</var>]}</h4> - -<p><a name="index-acronym-435"></a> -<a name="index-NASA_002c-as-acronym-436"></a><a name="index-Acronyms_002c-tagging-437"></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 ‘<samp><span class="samp">@acronym{NASA}</span></samp>’. As -a matter of style, or for particular acronyms, you may prefer to -use periods, as in ‘<samp><span class="samp">@acronym{N.A.S.A.}</span></samp>’. - - <p><code>@acronym</code> accepts an optional second argument, intended to be -used for the meaning of the acronym. - - <p>If the acronym is at the end of a sentence, and if there is no second -argument, remember to use the <code>@.</code> or similar command -(see <a href="#Ending-a-Sentence">Ending a Sentence</a>) to get the correct spacing. - - <p><a name="index-g_t_003cacronym_003e-tag-438"></a>In TeX, the acronym is printed in slightly smaller font. In the -Info output, the argument is printed as-is. In either format, if the -second argument is present, it is printed in parentheses after the -acronym. In HTML, Docbook, and XML, the <code><acronym></code> tag is -used. - - <p>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>). - - <p><code>@abbr</code> and <code>@acronym</code> are closely related commands: they -both signal to the reader that a shortened form is being used, and -possibly give a meaning. When choosing whether to use these two -commands, please bear the following in mind. - - <ul> -<li>In standard English usage, acronyms are a subset of abbreviations: -they include pronounceable words like `<acronym>NATO</acronym>', `radar', and -`snafu', and some sources also include syllable acronyms like -`Usenet', hybrids like `<acronym>SIGGRAPH</acronym>', and unpronounceable -initialisms like `<acronym>FBI</acronym>'. - - <li>In Texinfo, an acronym (but not an abbreviation) should consist only -of capital letters and periods, no lowercase. - - <li>In TeX, an acronym (but not an abbreviation) is printed in a -slightly smaller font. - - <li>Some browsers place a dotted bottom border under abbreviations but not -acronyms. - - <li>It's not essential to use these commands for all abbreviations. Text -is perfectly readable without them. - - </ul> - -<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> - -</div> - -<h4 class="subsection">9.1.16 <code>@indicateurl</code>{<var>uniform-resource-locator</var>}</h4> - -<p><a name="index-indicateurl-439"></a><a name="index-Uniform-resource-locator_002c-indicating-440"></a><a name="index-URL_002c-indicating-441"></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> - -</div> - -<h4 class="subsection">9.1.17 <code>@email</code>{<var>email-address</var>[, <var>displayed-text</var>]}</h4> - -<p><a name="index-email-442"></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-443"></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 ‘<samp><span class="samp">mailto</span></samp>’ 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> - -</div> - -<h3 class="section">9.2 Emphasizing Text</h3> - -<p><a name="index-Emphasizing-text-444"></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-%26-strong"></a> -<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> - -</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-445"></a><a name="index-emph-446"></a><a name="index-strong-447"></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>: ‘<samp><span class="samp">rm * .[^.]*</span></samp>’ -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 -(‘<samp><span class="samp">_</span></samp>’), and <code>@strong</code> puts asterisks around the text. - - <blockquote> -<b>Caution:</b> Do not use <code>@strong</code> with the word ‘<samp><span class="samp">Note</span></samp>’; 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>—‘<samp><span class="samp">Note</span></samp>’ 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> - -</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-448"></a><a name="index-sc-_0040r_007b_0028small-caps-font_0029_007d-449"></a> -Use the ‘<samp><span class="samp">@sc</span></samp>’ 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 -acronyms (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-g_t_003csmall_003e-tag-450"></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>, -<samp><span class="command">makeinfo</span></samp> 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> - -</div> - -<h4 class="subsection">9.2.3 Fonts for Printing, Not Info</h4> - -<p><a name="index-Fonts-for-printing_002c-not-Info-451"></a> -<a name="index-fonttextsize-452"></a><a name="index-Font-size_002c-reducing-453"></a><a name="index-Reducing-font-size-454"></a><a name="index-Smaller-fonts-455"></a>Texinfo provides one command to change the size of the main body font -in the TeX output for a document: <code>@fonttextsize</code>. It has no -effect at all in other output. It takes a single argument on the -remainder of the line, which must be either ‘<samp><span class="samp">10</span></samp>’ or ‘<samp><span class="samp">11</span></samp>’. -For example: - -<pre class="example"> @fonttextsize 10 -</pre> - <p><a name="index-Printing-cost_002c-reducing-456"></a>The effect is to reduce the body font to a 10<span class="dmn">pt</span> size (the -default is 11<span class="dmn">pt</span>). Fonts for other elements, such as sections -and chapters, are reduced accordingly. This should only be used in -conjunction with <code>@smallbook</code> (see <a href="#smallbook">Printing “Small” Books</a>) or similar, since 10<span class="dmn">pt</span> fonts on standard paper -(8.5x11 or A4) are too small. One reason to use this command is to -save pages, and hence printing cost, for physical books. - - <p>Texinfo does not at present have commands to switch the font family -to use, or more general size-changing commands. - - <p><a name="index-Styles_002c-font-457"></a>Texinfo also provides a number of font commands that specify font changes -in the printed manual and (where possible) in the HTML output, but -have no effect in the Info file. All the commands apply to an -argument that follows, surrounded by braces. - - <dl> -<dt><code>@b</code><dd><a name="index-b-_0040r_007b_0028bold-font_0029_007d-458"></a><a name="index-Bold-font-459"></a>selects <b>bold</b> face; - - <br><dt><code>@i</code><dd><a name="index-i-_0040r_007b_0028italic-font_0029_007d-460"></a><a name="index-Italic-font-461"></a>selects an <i>italic</i> font; - - <br><dt><code>@r</code><dd><a name="index-r-_0040r_007b_0028roman-font_0029_007d-462"></a><a name="index-Roman-font-463"></a><a name="index-Default-font-464"></a>selects a <span class="roman">roman</span> font, which is the usual font in which text is -printed. It may or may not be seriffed. - - <br><dt><code>@sansserif</code><dd><a name="index-sansserif-_0040r_007b_0028sans-serif-font_0029_007d-465"></a><a name="index-Sans-serif-font-466"></a>selects a <span class="sansserif">sans serif</span> font; - - <br><dt><code>@slanted</code><dd><a name="index-slanted-_0040r_007b_0028slanted-font_0029_007d-467"></a><a name="index-Slanted-font-468"></a><a name="index-Oblique-font-469"></a>selects a <i>slanted</i> font; - - <br><dt><code>@t</code><dd><a name="index-t-_0040r_007b_0028typewriter-font_0029_007d-470"></a><a name="index-Monospace-font-471"></a><a name="index-Fixed_002dwidth-font-472"></a><a name="index-Typewriter-font-473"></a>selects the <tt>fixed-width</tt>, typewriter-style font used by <code>@code</code>; - - </dl> - - <p>(The commands with longer names were invented much later than the -others, at which time it did not seem desirable to use very short -names for such an infrequently needed feature.) - - <p><a name="index-g_t_003clineannotation_003e-Docbook-tag-474"></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 font commands. Some of -them are only useful when documenting functionality of specific font -effects, such as in TeX and related packages. - -<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> - -</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 in the output. - - <p><a name="index-end-475"></a>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, and with only one space between the <code>@end</code> and the -<code>example</code>. - -<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> - -</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> - -</div> - -<h3 class="section">10.2 <code>@quotation</code>: Block quotations</h3> - -<p><a name="index-Quotations-476"></a><a name="index-quotation-477"></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>and the first lines of paragraphs are indented no more than other lines. - - </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 -‘<samp><span class="samp">:</span></samp>’. 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-g_t_003cnote_003e-Docbook-tag-478"></a><a name="index-g_t_003cblockquote_003e-HTML-tag-479"></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> - -</div> - -<h3 class="section">10.3 <code>@example</code>: Example Text</h3> - -<p><a name="index-Examples_002c-formatting-them-480"></a><a name="index-Formatting-examples-481"></a><a name="index-example-482"></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> - -</div> - -<h3 class="section">10.4 <code>@verbatim</code>: Literal Text</h3> - -<p><a name="index-verbatim-483"></a><a name="index-Verbatim-environment-484"></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 files in a Texinfo manual. - - <p>In general, the output will be just the same as the input. No -character substitutions are made, e.g., all spaces and blank lines are -significant, including tabs. In the printed manual, the text is -typeset in a fixed-width font, and not indented or filled. - - <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">This 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><a name="index-Verbatim_002c-small-485"></a><a name="index-Small-verbatim-486"></a>You can get a “small” verbatim by enclosing the <code>@verbatim</code> in -an <code>@smallformat</code> environment, as shown here: - -<!-- more cheating ... --> -<pre class="smallexample"><br><tt>@smallformat</tt><br> -<br><tt>@verbatim</tt><br> -<br><tt>... still verbatim, but in a smaller font ...</tt><br> -<br><tt>@end verbatim</tt><br> -<br><tt>@end smallformat</tt><br> -</pre> - <p>Finally, a word of warning: 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> - -</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-487"></a><a name="index-Including-a-file-verbatim-488"></a><a name="index-verbatiminclude-489"></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 include files in other directories within a distribution, -for instance: - -<pre class="example"> @verbatiminclude @value{top_srcdir}/NEWS -</pre> - <p class="noindent">(You still have to get <code>top_srcdir</code> defined in the -first place.) - - <p>For a method on printing the file contents in a smaller font size, see -the end of the previous section on <code>@verbatim</code>. - -<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> - -</div> - -<h3 class="section">10.6 <code>@lisp</code>: Marking a Lisp Example</h3> - -<p><a name="index-lisp-490"></a><a name="index-Lisp-example-491"></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> - -</div> - -<h3 class="section">10.7 <code>@small...</code> Block Commands</h3> - -<p><a name="index-Small-examples-492"></a><a name="index-Examples-in-smaller-fonts-493"></a><a name="index-Lisp-examples-in-smaller-fonts-494"></a><a name="index-smalldisplay-495"></a><a name="index-smallexample-496"></a><a name="index-smallformat-497"></a><a name="index-smalllisp-498"></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> - -</div> - -<h3 class="section">10.8 <code>@display</code> and <code>@smalldisplay</code></h3> - -<p><a name="index-Display-formatting-499"></a><a name="index-display-500"></a> -The <code>@display</code> command begins a kind of example, where each line -of input produces a line of output, and the output is indented. It is -thus like the <code>@example</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-501"></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>. - - <p>The <code>@table</code> command (see <a href="#table">table</a>) does not work inside -<code>@display</code>. Since <code>@display</code> is line-oriented, it doesn't -make sense to use them together. If you want to indent a table, try -<code>@quotation</code> (see <a href="#quotation">quotation</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> - -</div> - -<h3 class="section">10.9 <code>@format</code> and <code>@smallformat</code></h3> - -<p><a name="index-format-502"></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-503"></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> - -</div> - -<h3 class="section">10.10 <code>@exdent</code>: Undoing a Line's Indentation</h3> - -<p><a name="index-Indentation-undoing-504"></a><a name="index-exdent-505"></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 example -</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-%26-flushright"></a> -<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> - -</div> - -<h3 class="section">10.11 <code>@flushleft</code> and <code>@flushright</code></h3> - -<p><a name="index-flushleft-506"></a><a name="index-flushright-507"></a><a name="index-Ragged-right-508"></a><a name="index-Ragged-left-509"></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> - -</div> - -<h3 class="section">10.12 <code>@noindent</code>: Omitting Indentation</h3> - -<p><a name="index-Omitting-indentation-510"></a><a name="index-Suppressing-indentation-511"></a><a name="index-Indentation_002c-omitting-512"></a><a name="index-noindent-513"></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> - -</div> - -<h3 class="section">10.13 <code>@indent</code>: Forcing Indentation</h3> - -<p><a name="index-Forcing-indentation-514"></a><a name="index-Inserting-indentation-515"></a><a name="index-Indentation_002c-forcing-516"></a><a name="index-indent-517"></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> - -</div> - -<h3 class="section">10.14 <code>@cartouche</code>: Rounded Rectangles Around Examples</h3> - -<p><a name="index-cartouche-518"></a><a name="index-Box-with-rounded-corners-519"></a><a name="index-Rounded-rectangles_002c-around-examples-520"></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 <samp><span class="command">makeinfo</span></samp> 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> - -</div> - -<h2 class="chapter">11 Lists and Tables</h2> - -<p><a name="index-Making-lists-and-tables-521"></a><a name="index-Lists-and-tables_002c-making-522"></a><a name="index-Tables-and-lists_002c-making-523"></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> - -</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-524"></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> - -</div> - -<h3 class="section">11.2 <code>@itemize</code>: Making an Itemized List</h3> - -<p><a name="index-Itemization-525"></a><a name="index-itemize-526"></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-g_t_0040code_007b_0040_0040w_007d_002c-for-blank-items-527"></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 -‘<samp><span class="samp">{}</span></samp>’.) 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-528"></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 ‘<samp><span class="samp">*</span></samp>’ 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> - -</div> - -<h3 class="section">11.3 <code>@enumerate</code>: Making a Numbered or Lettered List</h3> - -<p><a name="index-Enumeration-529"></a><a name="index-enumerate-530"></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 ‘<samp><span class="samp">1</span></samp>’. With a numeric argument, such as -‘<samp><span class="samp">3</span></samp>’, the command starts the list with that number. With an upper -or lower case letter, such as ‘<samp><span class="samp">a</span></samp>’ or ‘<samp><span class="samp">A</span></samp>’, 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-column-Tables"></a> -<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> - -</div> - -<h3 class="section">11.4 Making a Two-column Table</h3> - -<p><a name="index-Tables_002c-making-two_002dcolumn-531"></a><a name="index-table-532"></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> - -</div> - -<h4 class="subsection">11.4.1 Using the <code>@table</code> Command</h4> - -<p><a name="index-Definition-lists_002c-typesetting-533"></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-534"></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-535"></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>‘<samp><span class="samp">foo</span></samp>’<dd>This is the text for -‘<samp><span class="samp">foo</span></samp>’. -<br><dt>‘<samp><span class="samp">bar</span></samp>’<dd>Text for ‘<samp><span class="samp">bar</span></samp>’. -</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> - -</div> - -<h4 class="subsection">11.4.2 <code>@ftable</code> and <code>@vtable</code></h4> - -<p><a name="index-Tables-with-indexes-536"></a><a name="index-Indexing-table-entries-automatically-537"></a><a name="index-ftable-538"></a><a name="index-vtable-539"></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> - -</div> - -<h4 class="subsection">11.4.3 <code>@itemx</code></h4> - -<p><a name="index-Two-named-items-for-_0040code_007b_0040_0040table_007d-540"></a><a name="index-itemx-541"></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-column-Tables"></a> -<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> - -</div> - -<h3 class="section">11.5 <code>@multitable</code>: Multi-column Tables</h3> - -<p><a name="index-Tables_002c-making-multi_002dcolumn-542"></a><a name="index-multitable-543"></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> - -</div> - -<h4 class="subsection">11.5.1 Multitable Column Widths</h4> - -<p><a name="index-Multitable-column-widths-544"></a><a name="index-Column-widths_002c-defining-for-multitables-545"></a><a name="index-Widths_002c-defining-multitable-column-546"></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-547"></a><a name="index-Line-length_002c-column-widths-as-fraction-of-548"></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-549"></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> - -</div> - -<h4 class="subsection">11.5.2 Multitable Rows</h4> - -<p><a name="index-Multitable-rows-550"></a><a name="index-Rows_002c-of-a-multitable-551"></a> -<a name="index-item-552"></a><a name="index-tab-553"></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-554"></a><a name="index-Heading-row_002c-in-table-555"></a><a name="index-g_t_003cthead_003e-HTML-tag-556"></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. In -Info, the heading row is followed by a separator line made of dashes -(‘<samp><span class="samp">-</span></samp>’ characters). - - <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</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> - -</div> - -<h2 class="chapter">12 Special Displays</h2> - -<p><a name="index-Special-displays-557"></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> - -</div> - -<h3 class="section">12.1 Floats</h3> - -<p><a name="index-Floats_002c-in-general-558"></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-559"></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> - -</div> - -<h4 class="subsection">12.1.1 <code>@float</code> [<var>type</var>][,<var>label</var>]: Floating Material</h4> - -<p><a name="index-float-560"></a><a name="index-Float-environment-561"></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>@listoffloats</code> output (see <a href="#listoffloats">listoffloats</a>). Cross-references -to <var>label</var> are allowed. - - <p><a name="index-Floats_002c-making-unnumbered-562"></a><a name="index-Unnumbered-float_002c-creating-563"></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-564"></a><a name="index-Numbering-of-floats-565"></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> - -</div> - -<h4 class="subsection">12.1.2 <code>@caption</code> & <code>@shortcaption</code></h4> - -<p><a name="index-caption-566"></a><a name="index-shortcaption-567"></a><a name="index-Captions_002c-for-floats-568"></a><a name="index-Short-captions_002c-for-lists-of-floats-569"></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. For -example: - -<pre class="example"> @float - ... as above ... - @shortcaption{Text for list of floats.} - @end float -</pre> - <p>The text for <code>@caption</code> and <code>@shortcaption</code> may not -contain comments (<code>@c</code>), verbatim text (<code>@verb</code>), -environments such as <code>@example</code>, or other complex constructs. - -<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> - -</div> - -<h4 class="subsection">12.1.3 <code>@listoffloats</code>: Tables of Contents for Floats</h4> - -<p><a name="index-listoffloats-570"></a><a name="index-List-of-floats-571"></a><a name="index-Floats_002c-list-of-572"></a><a name="index-Table-of-contents_002c-for-floats-573"></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> - -</div> - -<h3 class="section">12.2 Inserting Images</h3> - -<p><a name="index-Images_002c-inserting-574"></a><a name="index-Pictures_002c-inserting-575"></a><a name="index-image-576"></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> - -</div> - -<h4 class="subsection">12.2.1 Image Syntax</h4> - -<p>Here is the 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-577"></a><a name="index-Image-formats-578"></a>The <var>filename</var> argument is mandatory, and must not have an -extension, because the different processors support different formats: - - <ul> -<li><a name="index-eps-image-format-579"></a>TeX reads the file <samp><var>filename</var><span class="file">.eps</span></samp> (Encapsulated PostScript -format). -<li><a name="index-pdftex_0040r_007b_002c-and-images_007d-580"></a><a name="index-png-image-format-581"></a><a name="index-jpeg-image-format-582"></a><a name="index-pdf-image-inclusions-583"></a>pdfTeX reads <samp><var>filename</var><span class="file">.png</span></samp>, <samp><var>filename</var><span class="file">.jpg</span></samp>, -<samp><var>filename</var><span class="file">.jpeg</span></samp>, or <samp><var>filename</var><span class="file">.pdf</span></samp> (in that -order). It also tries uppercase versions of the extensions. The PDF -format cannot support EPS images, so they must be converted first. -<li><code>makeinfo</code> includes <samp><var>filename</var><span class="file">.txt</span></samp> 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-584"></a> - <pre class="example"> @image{foo,,,,.xpm} -</pre> - <p class="noindent">will cause <code>makeinfo</code> to look for <samp><span class="file">foo.xpm</span></samp> before any others. - - </ul> - - <p>The <var>width</var> and <var>height</var> arguments are described in the next -section. - - <p>For TeX output, if an image is the only thing in a paragraph it -will ordinarily be displayed on a line by itself, respecting the -current environment indentation, but without the normal paragraph -indentation. If you want it centered, use <code>@center</code> -(see <a href="#titlefont-center-sp"><code>@titlefont @center @sp</code></a>). - - <p><a name="index-Alt-attribute-for-images-585"></a><a name="index-Images_002c-alternate-text-for-586"></a><a name="index-g_t_002d-_0028in-image-alt-string_0029-587"></a>For HTML output, <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. The <var>alttext</var> is -taken as Texinfo text, so special characters such as ‘<samp><span class="samp">"</span></samp>’ and -‘<samp><span class="samp"><</span></samp>’ and ‘<samp><span class="samp">&</span></samp>’ are escaped in the HTML and XML output; also, -you can get an empty <code>alt</code> string with <code>@-</code> (a command -that produces no output; see <a href="#g_t_002d-and-hyphenation">- and hyphenation</a>). - - <p>For Info output, the <code>alt</code> string is also processed as Texinfo -text and output. In this case, ‘<samp><span class="samp">\</span></samp>’ is escaped as ‘<samp><span class="samp">\\</span></samp>’ and -‘<samp><span class="samp">"</span></samp>’ as ‘<samp><span class="samp">\"</span></samp>’; no other escapes are done. - - <p><a name="index-PNG-image-format-588"></a><a name="index-JPEG-image-format-589"></a>If you do not supply the optional <var>extension</var> (fifth) argument, -<code>makeinfo</code> first tries <samp><var>filename</var><span class="file">.png</span></samp>; if that does -not exist, it tries <samp><var>filename</var><span class="file">.jpg</span></samp>. If that does not exist -either, it complains. - - <p>In Info output, <code>makeinfo</code> writes a reference to the binary image -file (trying <var>filename</var> suffixed with <samp><var>extension</var></samp>, -<samp><var>.extension</var></samp>, <samp><span class="file">.png</span></samp>, or <samp><span class="file">.jpg</span></samp>, in that order) -if one exists. It also literally includes the <samp><span class="file">.txt</span></samp> 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><a name="index-g_t_0040samp_007b_005e_0040_0040_005eH_007d-for-images-in-Info-590"></a>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 ‘<samp><span class="samp">^@</span></samp>’ and ‘<samp><span class="samp">^H</span></samp>’ 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> - -</div> - -<h4 class="subsection">12.2.2 Image Scaling</h4> - -<p><a name="index-Images_002c-scaling-591"></a><a name="index-Scaling-images-592"></a><a name="index-Width-of-images-593"></a><a name="index-Height-of-images-594"></a><a name="index-Aspect-ratio-of-images-595"></a><a name="index-Distorting-images-596"></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-597"></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-598"></a>point (72.27pt = 1in) -<br><dt>pc<dd><a name="index-Picas-599"></a>pica (1pc = 12pt) -<br><dt>bp<dd><a name="index-Big-points-600"></a>big point (72bp = 1in) -<br><dt>in<dd><a name="index-Inches-601"></a>inch -<br><dt>cm<dd><a name="index-Centimeters-602"></a>centimeter (2.54cm = 1in) -<br><dt>mm<dd><a name="index-Millimeters-603"></a>millimeter (10mm = 1cm) -<br><dt>dd<dd><a name="index-Did_0040_005eot-points-604"></a>didôt point (1157dd = 1238pt) -<br><dt>cc<dd><a name="index-Ciceros-605"></a>cicero (1cc = 12dd) -<br><dt>sp<dd><a name="index-Scaled-points-606"></a>scaled point (65536sp = 1pt) -</dl> - - <p><a name="index-ridt_002eeps-607"></a>For example, the following will scale a file <samp><span class="file">ridt.eps</span></samp> to one -inch vertically, with the width scaled proportionately: - -<pre class="example"> @image{ridt,,1in} -</pre> - <p><a name="index-epsf_002etex-608"></a>For <code>@image</code> to work with TeX, the file <samp><span class="file">epsf.tex</span></samp> must be -installed somewhere that TeX can find it. (The standard location is -<samp><var>texmf</var><span class="file">/tex/generic/dvips/epsf.tex</span></samp>, 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> - -</div> - -<h3 class="section">12.3 Footnotes</h3> - -<p><a name="index-Footnotes-609"></a><a name="index-footnote-610"></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> - -</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, ‘<samp><span class="samp">.};</span></samp>’ is the sequence. This is normal (the -first ends the footnote and the second belongs to the sentence being -footnoted), so don't worry that it looks odd. - - <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: ‘<samp><span class="samp">(1)</span></samp>’. 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> - -</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-g_t_0040samp_007b_0040r_007bEnd_007d_007d-node-footnote-style-611"></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 -‘<samp><span class="samp">Footnotes</span></samp>’ within it. Each footnote begins with an -‘<samp><span class="samp">(</span><var>n</var><span class="samp">)</span></samp>’ 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-g_t_0040samp_007b_0040r_007bSeparate_007d_007d-footnote-style-612"></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 ‘<samp><span class="samp">(</span><var>n</var><span class="samp">)</span></samp>’ 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 ‘<samp><span class="samp">-Footnotes</span></samp>’<!-- /@w --> to the name of the node -that contains the footnotes. (Consequently, the footnotes' -node for the <samp><span class="file">Footnotes</span></samp> node is -<samp><span class="file">Footnotes-Footnotes</span></samp><!-- /@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 ‘<samp><span class="samp">end</span></samp>’ -style, as it is simpler for readers to follow. - - <p><a name="index-footnotestyle-613"></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 ‘<samp><span class="samp">end</span></samp>’ for the end node style or -‘<samp><span class="samp">separate</span></samp>’ 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> - -</div> - -<h2 class="chapter">13 Indices</h2> - -<p><a name="index-Indices-614"></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> - -</div> - -<h3 class="section">13.1 Making Index Entries</h3> - -<p><a name="index-Index-entries_002c-making-615"></a><a name="index-Entries_002c-making-index-616"></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> - -</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>‘<samp><span class="samp">cp</span></samp>’<dd><a name="index-g_t_0040code_007bcp_007d-_0028concept_0029-index-617"></a>(<code>@cindex</code>) concept index, for general concepts. -<br><dt>‘<samp><span class="samp">fn</span></samp>’<dd><a name="index-g_t_0040code_007bfn_007d-_0028function_0029-index-618"></a>(<code>@findex</code>) function index, for function and function-like -names (such as entry points of libraries). -<br><dt>‘<samp><span class="samp">ky</span></samp>’<dd><a name="index-g_t_0040code_007bky_007d-_0028keystroke_0029-index-619"></a>(<code>@kindex</code>) keystroke index, for keyboard commands. -<br><dt>‘<samp><span class="samp">pg</span></samp>’<dd><a name="index-g_t_0040code_007bpg_007d-_0028program_0029-index-620"></a>(<code>@pindex</code>) program index, for names of programs. -<br><dt>‘<samp><span class="samp">tp</span></samp>’<dd><a name="index-g_t_0040code_007btp_007d-_0028data-type_0029-index-621"></a>(<code>@tindex</code>) data type index, for type names (such as structures -defined in header files). -<br><dt>‘<samp><span class="samp">vr</span></samp>’<dd><a name="index-g_t_0040code_007bvr_007d-_0028variable_0029-index-622"></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> - -</div> - -<h3 class="section">13.3 Defining the Entries of an Index</h3> - -<p><a name="index-Defining-indexing-entries-623"></a><a name="index-Index-entries-624"></a><a name="index-Entries-for-an-index-625"></a><a name="index-Specifying-index-entries-626"></a><a name="index-Creating-index-entries-627"></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-628"></a><a name="index-Index-entry-writing-629"></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-630"></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> - -</div> - -<h3 class="section">13.4 Combining Indices</h3> - -<p><a name="index-Combining-indices-631"></a><a name="index-Indices_002c-combining-them-632"></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> - -</div> - -<h4 class="subsection">13.4.1 <code>@syncodeindex</code></h4> - -<p><a name="index-syncodeindex-633"></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-634"></a><a name="index-Two-letter-names-for-indices-635"></a><a name="index-Indices_002c-two-letter-names-636"></a><a name="index-Names-for-indices-637"></a>For this purpose, the indices are given two-letter names: - - <dl> -<dt>‘<samp><span class="samp">cp</span></samp>’<dd>concept index -<br><dt>‘<samp><span class="samp">fn</span></samp>’<dd>function index -<br><dt>‘<samp><span class="samp">vr</span></samp>’<dd>variable index -<br><dt>‘<samp><span class="samp">ky</span></samp>’<dd>key index -<br><dt>‘<samp><span class="samp">pg</span></samp>’<dd>program index -<br><dt>‘<samp><span class="samp">tp</span></samp>’<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-638"></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> - -</div> - -<h4 class="subsection">13.4.2 <code>@synindex</code></h4> - -<p><a name="index-synindex-639"></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> - -</div> - -<h3 class="section">13.5 Defining New Indices</h3> - -<p><a name="index-Defining-new-indices-640"></a><a name="index-Indices_002c-defining-new-641"></a><a name="index-New-index-defining-642"></a><a name="index-defindex-643"></a><a name="index-defcodeindex-644"></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 ‘<samp><span class="samp">au</span></samp>’. -For example: - -<pre class="example"> @defindex au -</pre> - <p>This defines a new index, called the ‘<samp><span class="samp">au</span></samp>’ 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 ‘<samp><span class="samp">au</span></samp>’ index entries. - -<pre class="example"> @section Cognitive Semantics - @cindex kinesthetic image schemas - @auindex Johnson, Mark - @auindex Lakoff, George -</pre> - <p class="noindent">(Evidently, ‘<samp><span class="samp">au</span></samp>’ serves here as an abbreviation for “author”.) - - <p>In general, Texinfo constructs the new indexing command by -concatenating the name of the index with ‘<samp><span class="samp">index</span></samp>’; thus, defining -an ‘<samp><span class="samp">xy</span></samp>’ 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> - -</div> - -<h2 class="chapter">14 Special Insertions</h2> - -<p><a name="index-Inserting-special-characters-and-symbols-645"></a><a name="index-Special-insertions-646"></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-Quote-Characters">Inserting Quote Characters</a>: Inserting left and right quotes, in code. -<li><a accesskey="3" href="#Inserting-Space">Inserting Space</a>: How to insert the right amount of space - within a sentence. -<li><a accesskey="4" href="#Inserting-Accents">Inserting Accents</a>: How to insert accents and special characters. -<li><a accesskey="5" href="#Inserting-Quotation-Marks">Inserting Quotation Marks</a>: How to insert quotation marks. -<li><a accesskey="6" href="#Dots-Bullets">Dots Bullets</a>: How to insert dots and bullets. -<li><a accesskey="7" href="#TeX-and-copyright">TeX and copyright</a>: How to insert the TeX logo - and the copyright symbol. -<li><a accesskey="8" href="#euro">euro</a>: How to insert the Euro currency symbol. -<li><a accesskey="9" href="#pounds">pounds</a>: How to insert the pounds currency symbol. -<li><a href="#textdegree">textdegree</a>: How to insert the degrees symbol. -<li><a href="#minus">minus</a>: How to insert a minus sign. -<li><a href="#geq-leq">geq leq</a>: How to insert greater/less-than-or-equal signs. -<li><a href="#math">math</a>: How to format a mathematical expression. -<li><a href="#Click-Sequences">Click Sequences</a>: Inserting GUI usage sequences. -<li><a 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-Quote-Characters">Inserting Quote Characters</a>, -Up: <a rel="up" accesskey="u" href="#Insertions">Insertions</a> - -</div> - -<h3 class="section">14.1 Inserting @ and {} and ,</h3> - -<p><a name="index-Special-characters_002c-inserting-647"></a><a name="index-Commands-to-insert-special-characters-648"></a> -‘<samp><span class="samp">@</span></samp>’ and curly braces are special characters in Texinfo. To insert -these characters so they appear in text, you must put an ‘<samp><span class="samp">@</span></samp>’ 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> - -</div> - -<h4 class="subsection">14.1.1 Inserting `@' with <code>@@</code></h4> - -<p><a name="index-g_t_0040_0040-_0040r_007b_0028literal-_0040samp_007b_0040_0040_007d_0029_007d-649"></a><a name="index-Inserting-_0040_0040-_0040r_007b_0028literal-_0040samp_007b_0040_0040_007d_0029_007d-650"></a> -<code>@@</code> stands for a single ‘<samp><span class="samp">@</span></samp>’ 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> - -</div> - -<h4 class="subsection">14.1.2 Inserting `{' and `}' with <code>@{</code> and <code>@}</code></h4> - -<p><a name="index-Braces_002c-inserting-651"></a><a name="index-g_t_0040_007b-_0040r_007b_0028literal-_0040samp_007b_0040_007b_007d_0029_007d-652"></a><a name="index-g_t_0040_007d-_0040r_007b_0028literal-_0040samp_007b_0040_007d_007d_0029_007d-653"></a> -<code>@{</code> stands for a single ‘<samp><span class="samp">{</span></samp>’ in either printed or Info -output. - - <p><code>@}</code> stands for a single ‘<samp><span class="samp">}</span></samp>’ in either printed or Info -output. - - <p>Do not put braces after either an <code>@{</code> or an <code>@}</code> -command. - -<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> - -</div> - -<h4 class="subsection">14.1.3 Inserting `,' with <code>@comma{}</code></h4> - -<p><a name="index-Commas_002c-inserting-654"></a><a name="index-comma-655"></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 character would confuse Texinfo's parsing for these -commands, you must use the command ‘<samp><span class="samp">@comma{}</span></samp>’ instead if you want -to pass an actual comma. 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 nearly anywhere, there is no need for it -anywhere except in this unusual case. - -<div class="node"> -<p><hr> -<a name="Inserting-Quote-Characters"></a> -Next: <a rel="next" accesskey="n" href="#Inserting-Space">Inserting Space</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> - -</div> - -<h3 class="section">14.2 Inserting Quote Characters</h3> - -<p><a name="index-Inserting-quote-characters-656"></a><a name="index-Quote-characters_002c-inserting-657"></a> -As explained in the early section on general Texinfo input conventions -(see <a href="#Conventions">Conventions</a>), Texinfo source files use the ASCII character -<code>`</code> (96 decimal) to produce a left quote (`), and ASCII <code>'</code> -(39 decimal) to produce a right quote ('). Doubling these input -characters (<code>``</code> and <code>''</code>) produces double quotes (“ and -”). These are the conventions used by TeX. - - <p>This works all right for text. However, in examples of computer code, -readers are especially likely to cut and paste the text -verbatim—and, unfortunately, some document viewers will mangle these -characters. (The free PDF reader <samp><span class="command">xpdf</span></samp> works fine, but other -PDF readers, both free and nonfree, have problems.) - - <p>If this is a concern for your document, Texinfo provides two special -settings via <code>@set</code>: - - <dl> -<dt><code>@set txicodequoteundirected</code><dd>causes the output for the <code>'</code> character to be the undirected -single quote, like this: - - <p><code>'</code>. - - <br><dt><code>@set txicodequotebacktick</code><dd>Cause the output for the <code>`</code> character to be the standalone grave -accent, like this: - - <p><code>`</code>. - - </dl> - - <p><code>xyza`'bc</code> - - <p>If you want these settings for only part of the document, -<code>@clear</code> will restore the normal behavior, as in -<code>@clear txicodequoteundirected</code>. - - <p>These settings affect <code>@code</code>, <code>@example</code>, and -<code>@verbatim</code>; they do not affect <code>@samp</code>. (See <a href="#Useful-Highlighting">Useful Highlighting</a>.) - -<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="#Inserting-Quote-Characters">Inserting Quote Characters</a>, -Up: <a rel="up" accesskey="u" href="#Insertions">Insertions</a> - -</div> - -<h3 class="section">14.3 Inserting Space</h3> - -<p><a name="index-Inserting-space-658"></a><a name="index-Spacing_002c-inserting-659"></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="#frenchspacing">frenchspacing</a>: Specifying end-of-sentence spacing. -<li><a accesskey="5" 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> - -</div> - -<h4 class="subsection">14.3.1 Not Ending a Sentence</h4> - -<p><a name="index-Not-ending-a-sentence-660"></a><a name="index-Sentence-non_002dending-punctuation-661"></a><a name="index-Periods_002c-inserting-662"></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-g_t_003ccolon_003e-_0040r_007b_0028suppress-end_002dof_002dsentence-space_0029_007d-663"></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"> foo vs.@: bar - foo vs. bar -</pre> - <p class="noindent">produces - - <blockquote> -foo vs. bar <br> -foo vs. bar -</blockquote> - -<p class="noindent"><code>@:</code> has no effect on the Info and HTML output. In Docbook and -XML, the previous punctuation character (.?!:) is output as an entity -instead of as the normal character: ‘<samp><span class="samp">&period; &quest; &excl; -&colon;</span></samp>’. 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> - -</div> - -<h4 class="subsection">14.3.2 Ending a Sentence</h4> - -<p><a name="index-Ending-a-Sentence-664"></a><a name="index-Sentence-ending-punctuation-665"></a> -<a name="index-g_t_002e--_0040r_007b_0028end-of-sentence_0029_007d-666"></a><a name="index-g_t_0021-_0040r_007b_0028end-of-sentence_0029_007d-667"></a><a name="index-g_t_003f-_0040r_007b_0028end-of-sentence_0029_007d-668"></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 -‘<samp><span class="samp">.</span></samp>’; 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</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="#frenchspacing">frenchspacing</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> - -</div> - -<h4 class="subsection">14.3.3 Multiple Spaces</h4> - -<p><a name="index-Multiple-spaces-669"></a><a name="index-Whitespace_002c-inserting-670"></a><a name="index-Space_002c-inserting-horizontal-671"></a><a name="index-g_t_003cspace_003e-672"></a><a name="index-g_t_003ctab_003e-673"></a><a name="index-g_t_003cnewline_003e-674"></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 ‘<samp><span class="samp">@</span></samp>’ character followed by a -space, i.e., ‘<samp><span class="samp">@ </span></samp>’, and <kbd>TAB</kbd> and <kbd>NL</kbd> represent the tab -character and end-of-line, i.e., when ‘<samp><span class="samp">@</span></samp>’ 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="frenchspacing"></a> -Next: <a rel="next" accesskey="n" href="#dmn">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> - -</div> - -<h4 class="subsection">14.3.4 <code>@frenchspacing</code> <var>val</var>: Control sentence spacing</h4> - -<p><a name="index-frenchspacing-675"></a><a name="index-French-spacing-676"></a><a name="index-Sentences_002c-spacing-after-677"></a><a name="index-Space_002c-after-sentences-678"></a> -In American typography, it is traditional and correct to put extra -space at the end of a sentence, after a semi-colon, and so on. This -is the default in Texinfo. In French typography (and many others), -this extra space is wrong; all spaces are uniform. - - <p>Therefore Texinfo provides the <code>@frenchspacing</code> command to -control the spacing after punctuation. It reads the rest of the line -as its argument, which must be the single word ‘<samp><span class="samp">on</span></samp>’ or ‘<samp><span class="samp">off</span></samp>’ -(always these words, regardless of the language) of the document. -Here is an example: - -<pre class="example"> @frenchspacing on - This is text. Two sentences. Three sentences. French spacing. - - @frenchspacing off - This is text. Two sentences. Three sentences. Non-French spacing. -</pre> - <p class="noindent">produces (there will be no difference in Info): - - <p>This is text. Two sentences. Three sentences. French spacing. - - <p>This is text. Two sentences. Three sentences. Non-French spacing. - - <p><code>@frenchspacing</code> mainly affects the printed output, including -the output after <code>@.</code>, <code>@!</code>, and <code>@?</code> (see <a href="#Ending-a-Sentence">Ending a Sentence</a>). - - <p>In Info, usually space characters in the input are written unaltered -to the output, and <code>@frenchspacing</code> does not change this. It -does change the one case where <samp><span class="command">makeinfo</span></samp> outputs a space on -its own: when a sentence ends at a newline in the source. Here's an -example: - -<pre class="example"> Some sentence. - Next sentence. -</pre> - <p class="noindent">produces in Info output, with <code>@frenchspacing off</code> -(the default), two spaces between the sentences: - -<pre class="example"> Some sentence. Next sentence. -</pre> - <p class="noindent">With <code>@frenchspacing on</code>, <samp><span class="command">makeinfo</span></samp> outputs -only a single space: - -<pre class="example"> Some sentence. Next sentence. -</pre> - <p><code>@frenchspacing</code> has no effect on the HTML or Docbook output; -for XML, it outputs a transliteration of itself (see <a href="#Output-Formats">Output Formats</a>). - -<div class="node"> -<p><hr> -<a name="dmn"></a> -Previous: <a rel="previous" accesskey="p" href="#frenchspacing">frenchspacing</a>, -Up: <a rel="up" accesskey="u" href="#Inserting-Space">Inserting Space</a> - -</div> - -<h4 class="subsection">14.3.5 <code>@dmn</code>{<var>dimension</var>}: Format a Dimension</h4> - -<p><a name="index-Thin-space-between-number_002c-dimension-679"></a><a name="index-Dimension-formatting-680"></a><a name="index-Format-a-dimension-681"></a><a name="index-dmn-682"></a> -At times, you may want to write ‘<samp><span class="samp">12pt</span></samp>’ or -‘<samp><span class="samp">8.5in</span></samp>’ 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 ‘<samp><span class="samp">8.27 in.@:</span></samp>’<!-- /@w --> -or ‘<samp><span class="samp">8.27 inches</span></samp>’<!-- /@w --> to ‘<samp><span class="samp">8.27@dmn{in}</span></samp>’ 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 ‘<samp><span class="samp">@:</span></samp>’ 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="#Inserting-Quotation-Marks">Inserting Quotation Marks</a>, -Previous: <a rel="previous" accesskey="p" href="#Inserting-Space">Inserting Space</a>, -Up: <a rel="up" accesskey="u" href="#Insertions">Insertions</a> - -</div> - -<h3 class="section">14.4 Inserting Accents</h3> - -<p><a name="index-Inserting-accents-683"></a><a name="index-Accents_002c-inserting-684"></a><a name="index-Floating-accents_002c-inserting-685"></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><a name="index-documentencoding-686"></a>To get the true accented characters output in Info, and not just the -ASCII transliterations, it is necessary to specify -<code>@documentencoding</code> with an encoding which supports the required -characters (see <a href="#documentencoding"><code>@documentencoding</code></a>). - - <p><a name="index-g_t_0022-_0040r_007b_0028umlaut-accent_0029_007d-687"></a><a name="index-Umlaut-accent-688"></a><a name="index-g_t_0027-_0040r_007b_0028umlaut-accent_0029_007d-689"></a><a name="index-Acute-accent-690"></a><a name="index-g_t_003d-_0040r_007b_0028macron-accent_0029_007d-691"></a><a name="index-Macron-accent-692"></a><a name="index-g_t_005e-_0040r_007b_0028circumflex-accent_0029_007d-693"></a><a name="index-Circumflex-accent-694"></a><a name="index-g_t_0060-_0040r_007b_0028grave-accent_0029_007d-695"></a><a name="index-Grave-accent-696"></a><a name="index-g_t_007e-_0040r_007b_0028tilde-accent_0029_007d-697"></a><a name="index-Tilde-accent-698"></a><a name="index-g_t_002c-_0040r_007b_0028cedilla-accent_0029_007d-699"></a><a name="index-Cedilla-accent-700"></a><a name="index-dotaccent-701"></a><a name="index-Dot-accent-702"></a><a name="index-H-_0040r_007b_0028Hungarian-umlaut-accent_0029_007d-703"></a><a name="index-Hungarian-umlaut-accent-704"></a><a name="index-ringaccent-705"></a><a name="index-Ring-accent-706"></a><a name="index-tieaccent-707"></a><a name="index-Tie_002dafter-accent-708"></a><a name="index-u-_0040r_007b_0028breve-accent_0029_007d-709"></a><a name="index-Breve-accent-710"></a><a name="index-ubaraccent-711"></a><a name="index-Underbar-accent-712"></a><a name="index-udotaccent-713"></a><a name="index-Underdot-accent-714"></a><a name="index-v-_0040r_007b_0028check-accent_0029_007d-715"></a><a name="index-Hacek-accent-716"></a><a name="index-Check-accent-717"></a><a name="index-Caron-accent-718"></a> - <p><table summary=""><tr align="left"><th valign="top">Command </th><th valign="top">Output </th><th valign="top">What -<br></th></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-719"></a><a name="index-g_t_0040questiondown_007b_007d-720"></a><a name="index-exclamdown-721"></a><a name="index-g_t_0040exclamdown_007b_007d-722"></a><a name="index-aa-723"></a><a name="index-g_t_0040aa_007b_007d-724"></a><a name="index-AA-725"></a><a name="index-g_t_0040AA_007b_007d-726"></a><a name="index-ae-727"></a><a name="index-g_t_0040ae_007b_007d-728"></a><a name="index-AE-729"></a><a name="index-g_t_0040AE_007b_007d-730"></a><a name="index-dotless-731"></a><a name="index-g_t_0040dotless_007bi_007d-_0028dotless-i_0029-732"></a><a name="index-g_t_0040dotless_007bj_007d-_0028dotless-j_0029-733"></a><a name="index-Dotless-i_002c-j-734"></a><a name="index-l-735"></a><a name="index-g_t_0040l_007b_007d-736"></a><a name="index-L-737"></a><a name="index-g_t_0040L_007b_007d-738"></a><a name="index-o-739"></a><a name="index-g_t_0040o_007b_007d-740"></a><a name="index-O-741"></a><a name="index-g_t_0040O_007b_007d-742"></a><a name="index-oe-743"></a><a name="index-g_t_0040oe_007b_007d-744"></a><a name="index-OE-745"></a><a name="index-g_t_0040OE_007b_007d-746"></a><a name="index-Romance-ordinals-747"></a><a name="index-Ordinals_002c-Romance-748"></a><a name="index-Feminine-ordinal-749"></a><a name="index-ordf-750"></a><a name="index-g_t_0040ordf_007b_007d-751"></a><a name="index-Masculine-ordinal-752"></a><a name="index-ordm-753"></a><a name="index-g_t_0040ordm_007b_007d-754"></a><a name="index-ss-755"></a><a name="index-g_t_0040ss_007b_007d-756"></a><a name="index-Es_002dzet-757"></a><a name="index-Sharp-S-758"></a><a name="index-German-S-759"></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="Inserting-Quotation-Marks"></a> -Next: <a rel="next" accesskey="n" href="#Dots-Bullets">Dots Bullets</a>, -Previous: <a rel="previous" accesskey="p" href="#Inserting-Accents">Inserting Accents</a>, -Up: <a rel="up" accesskey="u" href="#Insertions">Insertions</a> - -</div> - -<h3 class="section">14.5 Inserting Quotation Marks</h3> - -<p><a name="index-Inserting-quotation-marks-760"></a><a name="index-Quotation-marks_002c-inserting-761"></a> -<a name="index-Quotation-characters-_0028_0060_0027_0029_002c-in-source-762"></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 ASCII -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-763"></a><a name="index-Grave-accent_002c-vs_002e-left-quote-764"></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. - - <p>Texinfo supports several other quotation marks used in languages other -than English. Below is a table with the commands Texinfo provides for -inserting quotation marks. - - <p><a name="index-documentencoding-765"></a><a name="index-UTF_002d8-766"></a><a name="index-ISO-8859_002d15-767"></a><a name="index-Latin-9-768"></a><a name="index-ISO-8859_002d1-769"></a><a name="index-Latin-1-770"></a>In order to get the symbols for the quotation marks in encoded Info -output, it is necessary to specify <code>@documentencoding UTF-8</code>. -(See <a href="#documentencoding"><code>@documentencoding</code></a>.) Double -guillemets are also present in ISO 8859-1 (aka Latin 1) and ISO -8859-15 (aka Latin 9). - - <p><a name="index-European-Computer-Modern-fonts-771"></a><a name="index-EC-fonts-772"></a>The standard TeX fonts support the usual quotation marks used in -English (the ones produced with single and doubled ASCII -single-quotes). For the other quotation marks, TeX uses European -Computer Modern (EC) fonts (<samp><span class="file">ecrm1000</span></samp> and other variants). -These fonts are freely available, of course; you can download them -from <a href="http://www.ctan.org/tex-archive/fonts/ec">http://www.ctan.org/tex-archive/fonts/ec</a>, among other -places. - - <p><a name="index-CM_002dSuper-fonts-773"></a>The free EC fonts are bitmap fonts created with Metafont. Especially -for on-line viewing, Type 1 (vector) versions of the fonts are -preferable; these are available in the CM-Super font package -(<a href="http://www.ctan.org/tex-archive/fonts/ps-type1/cm-super">http://www.ctan.org/tex-archive/fonts/ps-type1/cm-super</a>). - - <p>Both distributions include installation instructions. - - <p><a name="index-Single-quotation-marks-774"></a><a name="index-Double-quotation-marks-775"></a><a name="index-Left-quotation-marks-776"></a><a name="index-Right-quotation-marks-777"></a><a name="index-quotedblleft-778"></a><a name="index-g_t_0060_0060-779"></a><a name="index-quoteleft-780"></a><a name="index-g_t_0060-781"></a><a name="index-quotedblright-782"></a><a name="index-g_t_0027_0027-783"></a><a name="index-quoteright-784"></a><a name="index-g_t_0027-785"></a><a name="index-Double-low_002d9-quotation-mark-786"></a><a name="index-Single-low_002d9-quotation-mark-787"></a><a name="index-quotedblbase-788"></a><a name="index-g_t_0040quotedblbase_007b_007d-_0028double-low_002d9-quotation-mark_0029-789"></a><a name="index-quotesinglbase-790"></a><a name="index-g_t_0040quotesinglbase_007b_007d-_0028single-low_002d9-quotation-mark_0029-791"></a><a name="index-Angle-quotation-marks-792"></a><a name="index-Guillemets-793"></a><a name="index-Guillemots-794"></a><a name="index-French-quotation-marks-795"></a><a name="index-Quotation-marks_002c-French-796"></a><a name="index-German-quotation-marks-797"></a><a name="index-Quotation-marks_002c-German-798"></a><a name="index-Double-guillemets-799"></a><a name="index-Single-guillemets-800"></a><a name="index-Double-angle-quotation-marks-801"></a><a name="index-Single-angle-quotation-marks-802"></a><a name="index-Left_002dpointing-angle-quotation-marks-803"></a><a name="index-Right_002dpointing-angle-quotation-marks-804"></a><a name="index-Double-left_002dpointing-angle-quotation-mark-805"></a><a name="index-Double-right_002dpointing-angle-quotation-mark-806"></a><a name="index-Single-left_002dpointing-angle-quotation-mark-807"></a><a name="index-Single-right_002dpointing-angle-quotation-mark-808"></a><a name="index-guillemetleft-809"></a><a name="index-guillemotleft-810"></a><a name="index-g_t_0040guillemetleft_007b_007d-811"></a><a name="index-guillemetright-812"></a><a name="index-guillemotright-813"></a><a name="index-g_t_0040guillemetright_007b_007d-814"></a><a name="index-guilsinglleft-815"></a><a name="index-g_t_0040guilsinglleft_007b_007d-816"></a><a name="index-guilsinglright-817"></a><a name="index-g_t_0040guilsinglright_007b_007d-818"></a> - <p><table summary=""><tr align="left"><th valign="top">Command </th><th valign="top">Glyph </th><th valign="top">Unicode name (point) -<br></th></tr><tr align="left"><td valign="top"><tt>@quotedblleft{} ``</tt> </td><td valign="top">“ </td><td valign="top">Left double quotation mark (U+201C) -<br></td></tr><tr align="left"><td valign="top"><tt>@quotedblright{} ''</tt> </td><td valign="top">” </td><td valign="top">Right double quotation mark (U+201D) -<br></td></tr><tr align="left"><td valign="top"><tt>@quoteleft{} `</tt> </td><td valign="top">‘ </td><td valign="top">Left single quotation mark (U+2018) -<br></td></tr><tr align="left"><td valign="top"><tt>@quoteright{} '</tt> </td><td valign="top">’ </td><td valign="top">Right single quotation mark (U+2019) -<br></td></tr><tr align="left"><td valign="top"><tt>@quotedblbase{}</tt> </td><td valign="top">„ </td><td valign="top">Double low-9 quotation mark (U+201E) -<br></td></tr><tr align="left"><td valign="top"><tt>@quotesinglbase{}</tt> </td><td valign="top">‚ </td><td valign="top">Single low-9 quotation mark (U+201A) -<br></td></tr><tr align="left"><td valign="top"><tt>@guillemetleft{}</tt> </td><td valign="top">« </td><td valign="top">Left-pointing double angle quotation mark (U+00AB) -<br></td></tr><tr align="left"><td valign="top"><tt>@guillemetright{}</tt> </td><td valign="top">» </td><td valign="top">Right-pointing double angle quotation mark (U+00BB) -<br></td></tr><tr align="left"><td valign="top"><tt>@guilsinglleft{}</tt> </td><td valign="top">‹ </td><td valign="top">Single left-pointing angle quotation mark (U+2039) -<br></td></tr><tr align="left"><td valign="top"><tt>@guilsinglright{}</tt> </td><td valign="top">› </td><td valign="top">Single right-pointing angle quotation mark (U+203A) - <br></td></tr></table> - - <p>For the double angle quotation marks, Adobe and LaTeX glyph names -are also supported: <code>@guillemotleft</code> and -<code>@guillemotright</code>. These names are actually incorrect; a -“guillemot” is a bird species (a type of auk). - - <p>Traditions for quotation mark usage vary to a great extent between -languages (<a href="http://en.wikipedia.org/wiki/Quotation_mark%2C_non-English_usage#Overview">http://en.wikipedia.org/wiki/Quotation_mark%2C_non-English_usage#Overview</a>). -Texinfo does not provide commands for typesetting quotation marks -according to the numerous traditions. Therefore, you have to choose -the commands appropriate for the language of your manual. Sometimes -aliases (see <a href="#alias"><code>@alias</code></a>) can simplify the usage and -make the source code more readable. For example, in German, -<code>@quotedblbase</code> is used for the left double quote, and the right -double quote is actually <code>@quotedblleft</code>, which is -counter-intuitive. Thus, in this case the following aliases would be -convenient: - -<pre class="example"> @alias lgqq = quotedblbase - @alias rgqq = quotedblleft -</pre> - <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-Quotation-Marks">Inserting Quotation Marks</a>, -Up: <a rel="up" accesskey="u" href="#Insertions">Insertions</a> - -</div> - -<h3 class="section">14.6 Inserting Ellipsis and Bullets</h3> - -<p><a name="index-Dots_002c-inserting-819"></a><a name="index-Bullets_002c-inserting-820"></a><a name="index-Ellipsis_002c-inserting-821"></a><a name="index-Inserting-ellipsis-822"></a><a name="index-Inserting-dots-823"></a><a name="index-Special-typesetting-commands-824"></a><a name="index-Typesetting-commands-for-dots_002c-etc_002e-825"></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, ‘<samp><span class="samp">{}</span></samp>’, 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> - -</div> - -<h4 class="subsection">14.6.1 <code>@dots</code>{} (<small class="dots">...</small>) and <code>@enddots</code>{} (<small class="enddots">...</small>)</h4> - -<p><a name="index-dots-826"></a><a name="index-enddots-827"></a><a name="index-Inserting-dots-828"></a><a name="index-Dots_002c-inserting-829"></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> - -</div> - -<h4 class="subsection">14.6.2 <code>@bullet</code>{} (•)</h4> - -<p><a name="index-bullet-830"></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="#euro">euro</a>, -Previous: <a rel="previous" accesskey="p" href="#Dots-Bullets">Dots Bullets</a>, -Up: <a rel="up" accesskey="u" href="#Insertions">Insertions</a> - -</div> - -<h3 class="section">14.7 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, ‘<samp><span class="samp">{}</span></samp>’, 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> - -</div> - -<h4 class="subsection">14.7.1 <code>@TeX</code>{} (TeX) and <code>@LaTeX</code>{} (LaTeX)</h4> - -<p><a name="index-TeX-831"></a><a name="index-LaTeX-832"></a><a name="index-Logos_002c-_0040TeX_007b_007d-833"></a><a name="index-g_t_0040TeX_007b_007d-logo-834"></a><a name="index-g_t_0040LaTeX_007b_007d-logo-835"></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 ‘<samp><span class="samp">TeX</span></samp>’. - - <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 -‘<samp><span class="samp">LaTeX</span></samp>’. (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> - -</div> - -<h4 class="subsection">14.7.2 <code>@copyright{}</code> (©)</h4> - -<p><a name="index-copyright-836"></a><a name="index-Copyright-symbol-837"></a> -Use the <code>@copyright{}</code> command to generate the copyright -symbol, `©'. Where possible, this is a ‘<samp><span class="samp">c</span></samp>’ -inside a circle; in Info, this is ‘<samp><span class="samp">(C)</span></samp>’. - -<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> - -</div> - -<h4 class="subsection">14.7.3 <code>@registeredsymbol{}</code> (®)</h4> - -<p><a name="index-registeredsymbol-838"></a><a name="index-Registered-symbol-839"></a> -Use the <code>@registeredsymbol{}</code> command to generate the -registered symbol, `®'. Where possible, this is an -‘<samp><span class="samp">R</span></samp>’ inside a circle; in Info, this is ‘<samp><span class="samp">(R)</span></samp>’. - -<div class="node"> -<p><hr> -<a name="euro"></a> -Next: <a rel="next" accesskey="n" href="#pounds">pounds</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> - -</div> - -<h3 class="section">14.8 <code>@euro</code>{} (€): Euro Currency Symbol</h3> - -<p><a name="index-euro-840"></a><a name="index-Euro-symbol-841"></a> -Use the <code>@euro{}</code> command to generate `€'. Where -possible, this is the symbol for the Euro currency, invented as part -of the European economic unification. In plain Info, it is the word -‘<samp><span class="samp">Euro </span></samp>’. A trailing space is included in the text -transliteration since typically no space is desired after the symbol, -so it would be inappropriate to have a space in the source document. - - <p>Texinfo cannot magically synthesize support for the Euro symbol where -the underlying system (fonts, software, whatever) does not support -it. Therefore, in many cases it is preferable to use the word -“Euro”. (In banking circles, the abbreviation for the Euro is EUR.) - - <p><a name="index-ISO-8859_002d15-842"></a><a name="index-Latin-9-843"></a>In order to get the Euro symbol in encoded Info output, for example, -it is necessary to specify <code>@documentencoding ISO-8859-15</code>. -(See <a href="#documentencoding"><code>@documentencoding</code></a>.) The Euro symbol -is in ISO 8859-15 (aka Latin 9), and is <em>not</em> in the more -widely-used and supported ISO 8859-1 (Latin 1). - - <p><a name="index-feymr10-844"></a><a name="index-Euro-font-845"></a>The Euro symbol does not exist in the standard TeX fonts (which -were designed before the Euro was legislated into existence). -Therefore, TeX uses an additional font, named <code>feymr10</code> (along -with other variables). It is freely available, of course; you can -download it from <a href="http://www.ctan.org/tex-archive/fonts/eurosym">http://www.ctan.org/tex-archive/fonts/eurosym</a>, -among other places. The distribution includes installation -instructions. - -<div class="node"> -<p><hr> -<a name="pounds"></a> -Next: <a rel="next" accesskey="n" href="#textdegree">textdegree</a>, -Previous: <a rel="previous" accesskey="p" href="#euro">euro</a>, -Up: <a rel="up" accesskey="u" href="#Insertions">Insertions</a> - -</div> - -<h3 class="section">14.9 <code>@pounds</code>{} (£): Pounds Sterling</h3> - -<p><a name="index-pounds-846"></a><a name="index-Pounds-symbol-847"></a> -Use the <code>@pounds{}</code> command to generate `£'. Where -possible, this is the symbol for the currency pounds sterling. In -Info, it is a ‘<samp><span class="samp">#</span></samp>’. - -<div class="node"> -<p><hr> -<a name="textdegree"></a> -Next: <a rel="next" accesskey="n" href="#minus">minus</a>, -Previous: <a rel="previous" accesskey="p" href="#pounds">pounds</a>, -Up: <a rel="up" accesskey="u" href="#Insertions">Insertions</a> - -</div> - -<h3 class="section">14.10 <code>@textdegree</code>{} (°): Degrees Symbol</h3> - -<p><a name="index-textdegree-848"></a><a name="index-Degree-symbol-849"></a> -Use the <code>@textdegree{}</code> command to generate `°'. -Where possible, this is the normal symbol for degrees. In plain text -and Info output, it is an ‘<samp><span class="samp">o</span></samp>’. - -<div class="node"> -<p><hr> -<a name="minus"></a> -Next: <a rel="next" accesskey="n" href="#geq-leq">geq leq</a>, -Previous: <a rel="previous" accesskey="p" href="#textdegree">textdegree</a>, -Up: <a rel="up" accesskey="u" href="#Insertions">Insertions</a> - -</div> - -<h3 class="section">14.11 <code>@minus</code>{} (−): Inserting a Minus Sign</h3> - -<p><a name="index-minus-850"></a><a name="index-Minus-sign-851"></a> -<a name="index-Em-dash_002c-compared-to-minus-sign-852"></a><a name="index-Hyphen_002c-compared-to-minus-853"></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"> ‘<samp><span class="samp">−</span></samp>’ is a minus sign generated with ‘<samp><span class="samp">@minus{}</span></samp>’, - - `-' is a hyphen generated with the character ‘<samp><span class="samp">-</span></samp>’, - - `—' 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="geq-leq"></a> -Next: <a rel="next" accesskey="n" href="#math">math</a>, -Previous: <a rel="previous" accesskey="p" href="#minus">minus</a>, -Up: <a rel="up" accesskey="u" href="#Insertions">Insertions</a> - -</div> - -<h3 class="section">14.12 <code>@geq{}</code> (≥) and <code>@leq{}</code> (≤): Inserting relations</h3> - -<p><a name="index-geq-854"></a><a name="index-leq-855"></a> -Use the <code>@geq{}</code> and <code>@geq{}</code> commands to generate -greater-than-or-equal and less-than-equal-signs, `≥' and -`≤'. In plain text and Info output, these are the ASCII -sequences ‘<samp><span class="samp">>=</span></samp>’ and ‘<samp><span class="samp"><=</span></samp>’. - -<div class="node"> -<p><hr> -<a name="math"></a> -Next: <a rel="next" accesskey="n" href="#Click-Sequences">Click Sequences</a>, -Previous: <a rel="previous" accesskey="p" href="#geq-leq">geq leq</a>, -Up: <a rel="up" accesskey="u" href="#Insertions">Insertions</a> - -</div> - -<h3 class="section">14.13 <code>@math</code>: Inserting Mathematical Expressions</h3> - -<p><a name="index-math-856"></a><a name="index-Mathematical-expressions-857"></a><a name="index-Formulas_002c-mathematical-858"></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>The <code>@math</code> command has no special effect on the Info and HTML -output. <samp><span class="command">makeinfo</span></samp> expands any <code>@</code>-commands as usual, -but it does not try to produce good mathematical formatting in any -way. - - <p>However, as far as the TeX output is concerned, plain TeX -mathematical commands are allowed in <code>@math</code>, starting with -‘<samp><span class="samp">\</span></samp>’, and the plain TeX math characters like ‘<samp><span class="samp">^</span></samp>’ and -‘<samp><span class="samp">_</span></samp>’ are also recognized. In essence, <code>@math</code> drops you -into plain TeX math mode. - - <p>This allows you to conveniently write superscripts and subscripts (as -in the above example), and also to use all the plain TeX math -control sequences for symbols, functions, and so on, and thus get -proper formatting in the TeX output, at least. - - <p>It's best to use ‘<samp><span class="samp">\</span></samp>’ instead of ‘<samp><span class="samp">@</span></samp>’ for any such -mathematical commands; otherwise, <samp><span class="command">makeinfo</span></samp> will complain. -On the other hand, input with matching (but unescaped) braces, such as -‘<samp><span class="samp">k_{75}</span></samp>’, is allowed inside <code>@math</code>, although -<samp><span class="command">makeinfo</span></samp> would complain about the bare braces in regular -input. - - <p>Here's an example: - -<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-g_t_005c-_0040r_007b_0028literal-_005c-in-_0040code_007b_0040_0040math_007d_0029_007d-859"></a>Since ‘<samp><span class="samp">\</span></samp>’ 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'd get the literal ‘<samp><span class="samp">\\</span></samp>’ in Info). <code>@\</code> is not -defined outside of <code>@math</code>, since a ‘<samp><span class="samp">\</span></samp>’ ordinarily produces a -literal ‘<samp><span class="samp">\</span></samp>’. - - <p><a name="index-Displayed-equations-860"></a><a name="index-Equations_002c-displayed-861"></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="Click-Sequences"></a> -Next: <a rel="next" accesskey="n" href="#Glyphs">Glyphs</a>, -Previous: <a rel="previous" accesskey="p" href="#math">math</a>, -Up: <a rel="up" accesskey="u" href="#Insertions">Insertions</a> - -</div> - -<h3 class="section">14.14 Click Sequences</h3> - -<p><a name="index-Click-sequences-862"></a><a name="index-Sequence-of-clicks-863"></a><a name="index-GUI-click-sequence-864"></a> -<a name="index-clicksequence-865"></a>When documenting graphical interfaces, it is necessary to describe -sequences such as `Click on ‘<samp><span class="samp">File</span></samp>’, then choose ‘<samp><span class="samp">Open</span></samp>’, then -<small class="dots">...</small>'. Texinfo offers commands <code>@clicksequence</code> and -<code>click</code> to represent this, typically used like this: - -<pre class="example"> ... @clicksequence{File @click{} Open} ... -</pre> - <p class="noindent">which produces: - -<pre class="display"> <small class="dots">...</small> File → Open <small class="dots">...</small> -</pre> - <p><a name="index-click-866"></a><a name="index-arrow-867"></a>The <code>@click</code> command produces a simple right arrow (‘<samp><span class="samp">-></span></samp>’ in -Info) by default; this glyph is also available independently via the -command <code>@arrow{}</code>. - - <p><a name="index-clickstyle-868"></a>You can change the glyph produced by <code>@click</code> with the command -<code>@clickstyle</code>, which takes a command name as its single argument -on the rest of the line, much like <code>@itemize</code> and friends -(see <a href="#itemize"><code>@itemize</code></a>). The command should produce a -glyph, and the usual empty braces ‘<samp><span class="samp">{}</span></samp>’ are omitted. Here's an -example: - -<pre class="example"> @clickstyle @result - ... @clicksequence{File @click{} Open} ... -</pre> - <p class="noindent">now produces: - -<pre class="display"> <small class="dots">...</small> File ⇒ Open <small class="dots">...</small> -</pre> - <div class="node"> -<p><hr> -<a name="Glyphs"></a> -Previous: <a rel="previous" accesskey="p" href="#Click-Sequences">Click Sequences</a>, -Up: <a rel="up" accesskey="u" href="#Insertions">Insertions</a> - -</div> - -<h3 class="section">14.15 Glyphs for Examples</h3> - -<p><a name="index-Glyphs-869"></a><a name="index-Examples_002c-glyphs-for-870"></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 ‘<samp><span class="samp">⇒</span></samp>’ or -‘<samp><span class="samp">==></span></samp>’. 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> - -</div> - -<h4 class="subsection">14.15.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> - -</div> - -<h4 class="subsection">14.15.2 <code>@result{}</code> (⇒): Indicating Evaluation</h4> - -<p><a name="index-Result-of-an-expression-871"></a><a name="index-Indicating-evaluation-872"></a><a name="index-Evaluation-glyph-873"></a><a name="index-Value-of-an-expression_002c-indicating-874"></a><a name="index-result-875"></a> -Use the <code>@result{}</code> command to indicate the result of -evaluating an expression. - - <p>The <code>@result{}</code> command is displayed as ‘<samp><span class="samp">⇒</span></samp>’ 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> - -</div> - -<h4 class="subsection">14.15.3 <code>@expansion{}</code> (==>): Indicating an Expansion</h4> - -<p><a name="index-Expansion_002c-indicating-876"></a><a name="index-Macro-expansion_002c-indicating-877"></a><a name="index-expansion-878"></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 ‘<samp><span class="samp">==></span></samp>’ -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> - -</div> - -<h4 class="subsection">14.15.4 <code>@print{}</code> (-|): Indicating Printed Output</h4> - -<p><a name="index-Printed-output_002c-indicating-879"></a><a name="index-print-880"></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 ‘<samp><span class="samp">-|</span></samp>’ 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 -‘<samp><span class="samp">-|</span></samp>’, 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> - -</div> - -<h4 class="subsection">14.15.5 <code>@error{}</code> (error-->): Indicating an Error Message</h4> - -<p><a name="index-Error-message_002c-indicating-881"></a><a name="index-error-882"></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 ‘<samp><span class="samp">error--></span></samp>’ 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>‘<samp><span class="samp">error--></span></samp>’ 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> - -</div> - -<h4 class="subsection">14.15.6 <code>@equiv{}</code> (==): Indicating Equivalence</h4> - -<p><a name="index-Equivalence_002c-indicating-883"></a><a name="index-equiv-884"></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 ‘<samp><span class="samp">==</span></samp>’ 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> - -</div> - -<h4 class="subsection">14.15.7 <code>@point{}</code> (-!-): Indicating Point in a Buffer</h4> - -<p><a name="index-Point_002c-indicating-in-a-buffer-885"></a><a name="index-point-886"></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 ‘<samp><span class="samp">@point{}</span></samp>’ 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 ‘<samp><span class="samp">-!-</span></samp>’ in Info -and HTML and as a small five pointed star in the printed -output. - - <p>The following example shows the contents of buffer <samp><span class="file">foo</span></samp> 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> - -</div> - -<h2 class="chapter">15 Forcing and Preventing Breaks</h2> - -<p><a name="index-Forcing-line-and-page-breaks-887"></a><a name="index-Making-line-and-page-breaks-888"></a><a name="index-Preventing-line-and-page-breaks-889"></a> -<a name="index-Line-breaks-890"></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-891"></a><a name="index-Page-breaks-892"></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="#g_t_002d-and-hyphenation">- and hyphenation</a>: Helping TeX with hyphenation points. -<li><a accesskey="4" href="#allowcodebreaks">allowcodebreaks</a>: Controlling line breaks within @code text. -<li><a accesskey="5" href="#w">w</a>: Preventing unwanted line breaks in text. -<li><a accesskey="6" href="#tie">tie</a>: Inserting an unbreakable but varying space. -<li><a accesskey="7" href="#sp">sp</a>: Inserting blank lines. -<li><a accesskey="8" href="#page">page</a>: Forcing the start of a new page. -<li><a accesskey="9" href="#group">group</a>: Preventing unwanted page breaks. -<li><a 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> - -</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="#g_t_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> - -</div> - -<h3 class="section">15.2 <code>@*</code> and <code>@/</code>: Generate and Allow Line Breaks</h3> - -<p><a name="index-g_t_002a-_0040r_007b_0028force-line-break_0029_007d-893"></a><a name="index-g_t_002f-_0040r_007b_0028allow-line-break_0029_007d-894"></a><a name="index-Line-breaks-895"></a><a name="index-Breaks-in-a-line-896"></a><a name="index-Force-line-break-897"></a><a name="index-Allow-line-break-898"></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="--and-hyphenation"></a> -<a name="g_t_002d-and-hyphenation"></a> -Next: <a rel="next" accesskey="n" href="#allowcodebreaks">allowcodebreaks</a>, -Previous: <a rel="previous" accesskey="p" href="#Line-Breaks">Line Breaks</a>, -Up: <a rel="up" accesskey="u" href="#Breaks">Breaks</a> - -</div> - -<h3 class="section">15.3 <code>@-</code> and <code>@hyphenation</code>: Helping TeX Hyphenate</h3> - -<p><a name="index-g_t_002d-_0040r_007b_0028discretionary-hyphen_0029_007d-899"></a><a name="index-hyphenation-900"></a><a name="index-Hyphenation_002c-helping-_0040TeX_007b_007d-do-901"></a><a name="index-Fine_002dtuning_002c-and-hyphenation-902"></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 ‘<samp><span class="samp">-</span></samp>’ 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, such as plurals. -</dl> - - <p>Info, HTML, and other non-TeX output is not hyphenated, so none of -these commands have any effect there. - -<div class="node"> -<p><hr> -<a name="allowcodebreaks"></a> -Next: <a rel="next" accesskey="n" href="#w">w</a>, -Previous: <a rel="previous" accesskey="p" href="#g_t_002d-and-hyphenation">- and hyphenation</a>, -Up: <a rel="up" accesskey="u" href="#Breaks">Breaks</a> - -</div> - -<h3 class="section">15.4 <code>@allowcodebreaks</code>: Control Line Breaks in <code>@code</code></h3> - -<p><a name="index-allowcodebreaks-903"></a><a name="index-Breaks_002c-within-_0040code_007b_0040_0040code_007d-904"></a><a name="index-g_t_002d_002c-breakpoint-within-_0040code_007b_0040_0040code_007d-905"></a><a name="index-Hyphen_002c-breakpoint-within-_0040code_007b_0040_0040code_007d-906"></a><a name="index-Dash_002c-breakpoint-within-_0040code_007b_0040_0040code_007d-907"></a><a name="index-g_t_005f_002c-breakpoint-within-_0040code_007b_0040_0040code_007d-908"></a><a name="index-Underscore_002c-breakpoint-within-_0040code_007b_0040_0040code_007d-909"></a> -Ordinarily, TeX will consider breaking lines at ‘<samp><span class="samp">-</span></samp>’ and -‘<samp><span class="samp">_</span></samp>’ characters within <code>@code</code> and related commands -(see <a href="#code"><code>@code</code></a>), more or less as if they were “empty” -hyphenation points. - - <p>This is necessary as many manuals, especially for Lisp-family -languages, must document very long identifiers. On the other hand, -other manuals don't have this problems, and you may not wish to allow -a line break at the underscore in, for example, <code>SIZE_MAX</code>, or -even worse, after any of the four underscores in <code>__typeof__</code>. - - <p>So Texinfo provides this command: - -<pre class="example"> @allowcodebreaks false -</pre> - <p class="noindent">to prevent TeX from breaking at ‘<samp><span class="samp">-</span></samp>’ or ‘<samp><span class="samp">_</span></samp>’ within -<code>@code</code>. You can go back to allowing such breaks with -<code>@allowcodebreaks true</code>. Write these commands on lines by -themselves. - - <p>These commands can be given anywhere in the document. For example, -you may have just one problematic paragraph where you need to turn off -the breaks, but want them in general, or vice versa. - - <p>This command has no effect in Info, HTML, and other non-TeX output. - -<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="#allowcodebreaks">allowcodebreaks</a>, -Up: <a rel="up" accesskey="u" href="#Breaks">Breaks</a> - -</div> - -<h3 class="section">15.5 <code>@w</code>{<var>text</var>}: Prevent Line Breaks</h3> - -<p><a name="index-w-_0040r_007b_0028prevent-line-break_0029_007d-910"></a><a name="index-Line-breaks_002c-preventing-911"></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 <samp><span class="command">makeinfo</span></samp>. - - <p><a name="index-Non_002dbreakable-space_002c-fixed-912"></a><a name="index-Unbreakable-space_002c-fixed-913"></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 manual indenting. 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-914"></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. <samp><span class="command">makeinfo</span></samp> does not ever hyphenate -words. - - <p><a name="index-Keyword-expansion_002c-preventing-915"></a><a name="index-Version-control-keywords_002c-preventing-expansion-of-916"></a><a name="index-g_t_0024Id-expansion_002c-preventing-917"></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> - -</div> - -<h3 class="section">15.6 <code>@tie{}</code>: Inserting an Unbreakable Space</h3> - -<p><a name="index-tie-_0040r_007b_0028unbreakable-interword-space_0029_007d-918"></a><a name="index-Tied-space-919"></a><a name="index-Non_002dbreakable-space_002c-variable-920"></a><a name="index-Unbreakable-space_002c-variable-921"></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. 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 ‘<samp><span class="samp">\hbox</span></samp>’). - - </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> - -</div> - -<h3 class="section">15.7 <code>@sp</code> <var>n</var>: Insert Blank Lines</h3> - -<p><a name="index-sp-_0040r_007b_0028line-spacing_0029_007d-922"></a><a name="index-Space_002c-inserting-vertical-923"></a><a name="index-Blank-lines-924"></a><a name="index-Line-spacing-925"></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> - -</div> - -<h3 class="section">15.8 <code>@page</code>: Start a New Page</h3> - -<p><a name="index-Page-breaks-926"></a><a name="index-page-927"></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> - -</div> - -<!-- node-name, next, previous, up --> -<h3 class="section">15.9 <code>@group</code>: Prevent Page Breaks</h3> - -<p><a name="index-Group-_0028hold-text-together-vertically_0029-928"></a><a name="index-Holding-text-together-vertically-929"></a><a name="index-Vertically-holding-text-together-930"></a><a name="index-group-931"></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> - -</div> - -<!-- node-name, next, previous, up --> -<h3 class="section">15.10 <code>@need </code><var>mils</var>: Prevent Page Breaks</h3> - -<p><a name="index-Need-space-at-page-bottom-932"></a><a name="index-need-933"></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> - -</div> - -<h2 class="chapter">16 Definition Commands</h2> - -<p><a name="index-Definition-commands-934"></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> - -</div> - -<h3 class="section">16.1 The Template for a Definition</h3> - -<p><a name="index-Definition-template-935"></a><a name="index-Template-for-a-definition-936"></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-937"></a></var><br> -<blockquote><p>This command 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. This may also be necessary if the text -contains commands, for example, ‘<samp><span class="samp">{declaraci@'on}</span></samp>’ if you are -writing in Spanish. - - <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-938"></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> - -</div> - -<h3 class="section">16.2 Definition Command Continuation Lines</h3> - -<p><a name="index-Continuation-lines-in-definition-commands-939"></a><a name="index-Definition-command-headings_002c-continuing-940"></a><a name="index-g_t_0040samp_007b_0040_0040_007d-as-continuation-in-definition-commands-941"></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 ‘<samp><span class="samp">@</span></samp>’ 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-942"></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-943"></a><a name="index-Collapsing-whitespace-around-continuations-944"></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, ‘<samp><span class="samp">@</span></samp>’ 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> - -</div> - -<h3 class="section">16.3 Optional and Repeated Arguments</h3> - -<p><a name="index-Optional-and-repeated-arguments-945"></a><a name="index-Repeated-and-optional-arguments-946"></a><a name="index-Arguments_002c-repeated-and-optional-947"></a><a name="index-Syntax_002c-optional-_0026-repeated-arguments-948"></a><a name="index-Meta_002dsyntactic-chars-for-arguments-949"></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>‘<samp><span class="samp">...</span></samp>’ 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-950"></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 -‘<samp><span class="samp">foobar</span></samp>’. - -<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> - -</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-951"></a><a name="index-Grouping-two-definitions-together-952"></a><a name="index-Definitions-grouped-together-953"></a><a name="index-deffnx-954"></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-955"></a></var><br> -— Interactive Command: <b>isearch-backward</b><var><a name="index-isearch_002dbackward-956"></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> - -</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> - -</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-957"></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 ‘<samp><span class="samp">@var{nchars}</span></samp>’ in this way. - - <p>In the unusual case when an argument name contains ‘<samp><span class="samp">--</span></samp>’, 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-958"></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 ‘<samp><span class="samp">@deffn Function ...</span></samp>’. -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-959"></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 ‘<samp><span class="samp">@deffn Macro ...</span></samp>’ and -works like <code>@defun</code>. - - <p><a name="index-defspec-960"></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</a>.) -<code>@defspec</code> is equivalent to ‘<samp><span class="samp">@deffn {Special Form} -...</span></samp>’ 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> - -</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-961"></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-962"></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 ‘<samp><span class="samp">@defvr Variable -...</span></samp>’. - - <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-963"></a><br><dt><code>@defopt </code><var>name</var><dd><a name="index-User-options_002c-marking-964"></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</a>). <code>@defopt</code> is equivalent to ‘<samp><span class="samp">@defvr {User -Option} ...</span></samp>’ 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> - -</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-965"></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) write everything -as straight text, and it will be printed in slanted type; (b) 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) 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-966"></a>The <code>@deftypefun</code> command is the specialized definition command -for functions in typed languages. The command is equivalent to -‘<samp><span class="samp">@deftypefn Function ...</span></samp>’. 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> - -</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-967"></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-968"></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 ‘<samp><span class="samp">@deftypevr Variable ...</span></samp>’. 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> - -</div> - -<h4 class="subsection">16.5.5 Data Types</h4> - -<p>Here is the command for data types: - - -<a name="index-deftp-969"></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> - -</div> - -<h4 class="subsection">16.5.6 Object-Oriented Programming</h4> - -<p><a name="index-Object_002doriented-programming-970"></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-Oriented-Variables"></a> -<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> - -</div> - -<h5 class="subsubsection">16.5.6.1 Object-Oriented Variables</h5> - -<p><a name="index-Variables_002c-object_002doriented-971"></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-972"></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-973"></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-974"></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-975"></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-976"></a>The <code>@defivar</code> command is the definition command for instance -variables in object-oriented programming. <code>@defivar</code> is -equivalent to ‘<samp><span class="samp">@defcv {Instance Variable} ...</span></samp>’. 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-977"></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-978"></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-979"></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-Oriented-Methods"></a> -<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> - -</div> - -<h5 class="subsubsection">16.5.6.2 Object-Oriented Methods</h5> - -<p><a name="index-Methods_002c-object_002doriented-980"></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-981"></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-982"></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-983"></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 ‘<samp><span class="samp">@defop Method ...</span></samp>’. -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-984"></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> - -</div> - -<h3 class="section">16.6 Conventions for Writing Definitions</h3> - -<p><a name="index-Definition-conventions-985"></a><a name="index-Conventions-for-writing-definitions-986"></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> - -</div> - -<h3 class="section">16.7 A Sample Function Definition</h3> - -<p><a name="index-Function-definitions-987"></a><a name="index-Command-definitions-988"></a><a name="index-Macro-definitions-989"></a><a name="index-Sample-function-definition-990"></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</a>. - - <blockquote> - -<div class="defun"> -— Function: <b>apply</b><var> function &rest arguments<a name="index-apply-991"></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> - -</div> - -<h2 class="chapter">17 Conditionally Visible Text</h2> - -<p><a name="index-Conditionally-visible-text-992"></a><a name="index-Text_002c-conditionally-visible-993"></a><a name="index-Visibility-of-conditional-text-994"></a><a name="index-If-text-conditionally-visible-995"></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> - -</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-996"></a><code>@ifinfo</code> begins segments of text that should be ignored by -TeX when it typesets the printed manual, and by <samp><span class="command">makeinfo</span></samp> -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-997"></a><a name="index-ifhtml-998"></a><a name="index-ifplaintext-999"></a><a name="index-iftex-1000"></a><a name="index-ifxml-1001"></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> - -</div> - -<h3 class="section">17.2 Conditional Not Commands</h3> - -<p><a name="index-ifnotdocbook-1002"></a><a name="index-ifnothtml-1003"></a><a name="index-ifnotinfo-1004"></a><a name="index-ifnotplaintext-1005"></a><a name="index-ifnottex-1006"></a><a name="index-ifnotxml-1007"></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> - -</div> - -<h3 class="section">17.3 Raw Formatter Commands</h3> - -<p><a name="index-Raw-formatter-commands-1008"></a><a name="index-g_t_0040TeX_007b_007d-commands_002c-using-ordinary-1009"></a><a name="index-Ordinary-_0040TeX_007b_007d-commands_002c-using-1010"></a><a name="index-Commands-using-raw-_0040TeX_007b_007d-1011"></a><a name="index-Docbook_002c-including-raw-1012"></a><a name="index-HTML_002c-including-raw-1013"></a><a name="index-XML_002c-including-raw-1014"></a><a name="index-Plain-_0040TeX_007b_007d-1015"></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 ‘<samp><span class="samp">\</span></samp>’ used by TeX with an -‘<samp><span class="samp">@</span></samp>’. 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-1016"></a>You can enter plain TeX completely, and use ‘<samp><span class="samp">\</span></samp>’ 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-g_t_005cgdef-_0040r_007bwithin-_0040code_007b_0040_0040tex_007d_007d-1017"></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-1018"></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-1019"></a><a name="index-html-1020"></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-1021"></a><a name="index-xml-1022"></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-1023"></a><a name="index-docbook-1024"></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> - -</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 specified. - - <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> - -</div> - -<h4 class="subsection">17.4.1 <code>@set</code> and <code>@value</code></h4> - -<p><a name="index-set-1025"></a><a name="index-value-1026"></a><a name="index-clear-1027"></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 ‘<samp><span class="samp">-</span></samp>’ or -‘<samp><span class="samp">_</span></samp>’—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> - -</div> - -<h4 class="subsection">17.4.2 <code>@ifset</code> and <code>@ifclear</code></h4> - -<p><a name="index-ifset-1028"></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-1029"></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-1030"></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> - -</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</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> - -</div> - -<h3 class="section">17.5 Conditional Nesting</h3> - -<p><a name="index-Conditionals_002c-nested-1031"></a><a name="index-Nesting-conditionals-1032"></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> - -</div> - -<h2 class="chapter">18 Internationalization</h2> - -<p><a name="index-Internationalization-1033"></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> - -</div> - -<h3 class="section">18.1 <code>@documentlanguage </code><var>ll</var><code>[_</code><var>cc</var><code>]</code>: Set the Document Language</h3> - -<p><a name="index-documentlanguage-1034"></a><a name="index-Language_002c-declaring-1035"></a><a name="index-Locale_002c-declaring-1036"></a><a name="index-Document-language_002c-declaring-1037"></a> -The <code>@documentlanguage</code> command declares the current document -locale. Write it on a line by itself, near the beginning of the -file, but after <code>@setfilename</code> -(see <a href="#setfilename"><code>@setfilename</code></a>). - - <p>Include a two-letter ISO 639-2 language code (<var>ll</var>) following -the command name, optionally followed by a two-letter ISO 3166 -two-letter country code (<var>cc</var>). 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_US</code> for US English. - - <p>As with GNU Gettext (see <a href="gettext.html#Top">Top</a>), if the country -code is omitted, the main dialect is assumed where possible. For -example, <code>de</code> is equivalent to <code>de_DE</code> (German as spoken in -Germany). - - <p><a name="index-Document-strings_002c-translation-of-1038"></a>For Info and other online output, this command changes the translation -of various <dfn>document strings</dfn> such as “see” in cross-references -(see <a href="#Cross-References">Cross References</a>), “Function' in defuns (see <a href="#Definition-Commands">Definition Commands</a>), and so on. Some strings, such as “Node:”, “Next:”, -“Menu:”, etc., are keywords in Info output, so are not translated -there; they are translated in other output formats. - - <p><a name="index-g_t_0040file_007btxi_002d_0040var_007bcc_007d_002etex_007d-1039"></a>For TeX, this command causes a file <samp><span class="file">txi-</span><var>locale</var><span class="file">.tex</span></samp> to -be read (if it exists). If <code>@setdocumentlanguage</code> argument -contains the optional ‘<samp><span class="samp">_</span><var>cc</var></samp>’ suffix, this is tried first. -For example, with <code>@setdocumentlanguage de_DE</code>, TeX first -looks for <samp><span class="file">txi-de_DE.tex</span></samp>, then <samp><span class="file">txi-de.tex</span></samp>. - - <p>Such a <samp><span class="file">txi-*</span></samp> file is intended to redefine the various English -words used in TeX output, such as `Chapter', `See', and so on. We -are aware that individual words like these cannot always be translated -in isolation, and that a very different strategy would be required for -ideographic (among other) scripts. Help in improving Texinfo's -language support is welcome. - - <p><a name="index-Hyphenation-patterns_002c-language_002ddependent-1040"></a>It would also be desirable for this command to also change TeX's -ideas of the current hyphenation patterns (via the TeX primitive -<code>\language</code>), but this is unfortunately not currently -implemented. - - <p>In September 2006, the W3C Internationalization Activity released a -new recommendation for specifying tags identifying language: -<pre class="example"> <a href="http://www.rfc-editor.org/rfc/bcp/bcp47.txt">http://www.rfc-editor.org/rfc/bcp/bcp47.txt</a> -</pre> - <p>When Gettext supports this new scheme, Texinfo will too. - - <p><a name="index-ISO-639_002d2-language-codes-1041"></a><a name="index-ISO-3166-country-codes-1042"></a><a name="index-Language-codes-1043"></a><a name="index-Country-codes-1044"></a>Since the lists of language codes and country codes are quite dynamic, -we don't attempt to list them here. The valid language codes are on -the official home page for ISO 639, -<a href="http://www.loc.gov/standards/iso639-2/">http://www.loc.gov/standards/iso639-2/</a>. The country codes and -the official web site for ISO 3166 can be found via -<a href="http://en.wikipedia.org/wiki/ISO_3166">http://en.wikipedia.org/wiki/ISO_3166</a>. - -<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> - -</div> - -<h3 class="section">18.2 <code>@documentencoding </code><var>enc</var>: Set Input Encoding</h3> - -<p><a name="index-documentencoding-1045"></a><a name="index-Encoding_002c-declaring-1046"></a><a name="index-Input-encoding_002c-declaring-1047"></a><a name="index-Character-set_002c-declaring-1048"></a><a name="index-Document-input-encoding-1049"></a> -The <code>@documentencoding</code> command declares the input document -encoding. Write it on a line by itself, with a valid encoding -specification following, near the beginning of the file but after -<code>@setfilename</code> (see <a href="#setfilename"><code>@setfilename</code></a>). - - <p>At present, Texinfo supports only these encodings: - - <dl> -<dt><code>US-ASCII</code><dd>This has no particular effect, but it's included for completeness. - - <dt><code>UTF-8</code><dd>The vast global character encoding, expressed in 8-bit bytes. -The Texinfo processors have no deep knowledge of Unicode; for the most -part, they just pass along the input they are given to the output. - - <dt><code>ISO-8859-1</code><dt><code>ISO-8859-15</code><br><dt><code>ISO-8859-2</code><dd>These specify the standard encodings for Western European (the first -two) and Eastern European languages (the third), respectively. ISO -8859-15 replaces some little-used characters from 8859-1 (e.g., -precomposed fractions) with more commonly needed ones, such as the -Euro symbol (€). - - <p>A full description of the encodings is beyond our scope here; -one useful reference is <a href="http://czyborra.com/charsets/iso8859.html">http://czyborra.com/charsets/iso8859.html</a>. - - <br><dt><code>koi8-r</code><dd>This is the commonly used encoding for the Russian language. - - <br><dt><code>koi8-u</code><dd>This is the commonly used encoding for the Ukrainian language. - - </dl> - - <p>Specifying an encoding <var>enc</var> has the following effects: - - <p><a name="index-g_t_002d_002denable_002dencoding-1050"></a><a name="index-Local-Variables_003a-section_002c-for-encoding-1051"></a><a name="index-Info-output_002c-and-encoding-1052"></a>In Info output, unless the option <samp><span class="option">--disable-encoding</span></samp> is given -to <samp><span class="command">makeinfo</span></samp>, a so-called `Local Variables' section -(see <a href="emacs.html#File-Variables">File Variables</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>Also, in Info and plain text output (barring -<samp><span class="option">--disable-encoding</span></samp>), accent constructs and special -characters, such as <code>@'e</code>, are output as the actual 8-bit -character in the given encoding. - - <p><a name="index-HTML-output_002c-and-encodings-1053"></a><a name="index-g_t_0040code_007bhttp_002dequiv_007d_002c-and-charset-specification-1054"></a><a name="index-g_t_0040code_007b_003cmeta_003e_007d-HTML-tag_002c-and-charset-specification-1055"></a>In HTML output, a ‘<samp><span class="samp"><meta></span></samp>’ tag is output, in the ‘<samp><span class="samp"><head></span></samp>’ -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, if supported by the system. - -<pre class="example"> <meta http-equiv="Content-Type" content="text/html; - charset=<var>enc</var>"> -</pre> - <p>In split HTML output, if <samp><span class="option">--transliterate-file-names</span></samp> is -given (see <a href="#HTML-Xref-8_002dbit-Character-Expansion">HTML Xref 8-bit Character Expansion</a>), the names of HTML -files are formed by transliteration of the corresponding node names, -using the specified encoding. - - <p>In XML and Docbook output, the given document encoding is written in -the output file as usual with those formats. - - <p>In TeX output, the characters which are supported in the standard -Computer Modern fonts are output accordingly. (For example, this -means using constructed accents rather than precomposed glyphs.) -Using a missing character generates a warning message, as does -specifying an unimplemented encoding. - -<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> - -</div> - -<h2 class="chapter">19 Defining New Texinfo Commands</h2> - -<p><a name="index-Macros-1056"></a><a name="index-Defining-new-Texinfo-commands-1057"></a><a name="index-New-Texinfo-commands_002c-defining-1058"></a><a name="index-Texinfo-commands_002c-defining-new-1059"></a><a name="index-User_002ddefined-Texinfo-commands-1060"></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>‘<samp><span class="samp">@alias</span></samp>’ is a convenient way to define a new name for an existing -command. - - <li>‘<samp><span class="samp">@definfoenclose</span></samp>’ 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> - -</div> - -<h3 class="section">19.1 Defining Macros</h3> - -<p><a name="index-Defining-macros-1061"></a><a name="index-Macro-definitions-1062"></a> -<a name="index-macro-1063"></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-1064"></a><a name="index-Names-of-macros_002c-valid-characters-of-1065"></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, -<samp><span class="command">makeinfo</span></samp> will accept anything except ‘<samp><span class="samp">{}_^=</span></samp>’; -‘<samp><span class="samp">_</span></samp>’ and ‘<samp><span class="samp">^</span></samp>’ 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 (‘<samp><span class="samp">@macro foo {}</span></samp>’) or with no braces at all (‘<samp><span class="samp">@macro -foo</span></samp>’). - - <p><a name="index-Body-of-a-macro-1066"></a><a name="index-Mutually-recursive-macros-1067"></a><a name="index-Recursion_002c-mutual-1068"></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-1069"></a>In the macro body, instances of a parameter name surrounded by -backslashes, as in ‘<samp><span class="samp">\</span><var>param1</var><span class="samp">\</span></samp>’ 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-1070"></a>To get a single ‘<samp><span class="samp">\</span></samp>’ in the macro expansion, use ‘<samp><span class="samp">\\</span></samp>’. Any -other use of ‘<samp><span class="samp">\</span></samp>’ in the body yields a warning. - - <p><a name="index-Spaces-in-macros-1071"></a><a name="index-Whitespace-in-macros-1072"></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-1073"></a><a name="index-rmacro-1074"></a>To allow a macro to be used recursively, that is, in an argument to a -call to itself, you must define it with ‘<samp><span class="samp">@rmacro</span></samp>’, 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 ‘<samp><span class="samp">@macro</span></samp>’ instead of -‘<samp><span class="samp">@rmacro</span></samp>’, an error message is given. - - <p><a name="index-unmacro-1075"></a><a name="index-Macros_002c-undefining-1076"></a><a name="index-Undefining-macros-1077"></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> - -</div> - -<h3 class="section">19.2 Invoking Macros</h3> - -<p><a name="index-Invoking-macros-1078"></a><a name="index-Expanding-macros-1079"></a><a name="index-Running-macros-1080"></a><a name="index-Macro-invocation-1081"></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-1082"></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-1083"></a>Passing strings containing commas as macro arguments requires special -care, since they should be properly <dfn>quoted</dfn> to prevent -<samp><span class="command">makeinfo</span></samp> from confusing them with argument separators. To -manually quote a comma, prepend it with a backslash character, like -this: <code>\,</code>. Alternatively, use the <code>@comma</code> command -(see <a href="#Inserting-a-Comma">Inserting a Comma</a>). However, to facilitate use of macros, -<samp><span class="command">makeinfo</span></samp> implements a set of rules called <dfn>automatic -quoting</dfn>: - - <ol type=1 start=1> -<li>If a macro takes only one argument, all commas in its invocation -are quoted by default. For example: - - <pre class="example"> @macro FIXME{text} - @strong{FIXME: \text\} - @end macro - - @FIXME{A nice feature, though it can be dangerous.} -</pre> - <p class="noindent">will produce the following output - - <pre class="example"> <strong>FIXME: A nice feature, though it can be dangerous.</strong> -</pre> - <p>And indeed, it can. Namely, <samp><span class="command">makeinfo</span></samp> -does not control number of arguments passed to one-argument -macros, so be careful when you invoke them. - - <li>If a macro invocation includes another command (including a -recursive invocation of itself), any commas in the nested command -invocation(s) are quoted by default. For example, in - - <pre class="example"> @say{@strong{Yes, I do}, person one} -</pre> - <p>the comma after ‘<samp><span class="samp">Yes</span></samp>’ is implicitly quoted. Here's another -example, with a recursive macro: - - <pre class="example"> @rmacro cat{a,b} - \a\\b\ - @end rmacro - - @cat{@cat{foo, bar}, baz} -</pre> - <p class="noindent">will produce the string ‘<samp><span class="samp">foobarbaz</span></samp>’. - - <li>Otherwise, a comma should be explicitly quoted, as above, to be -treated as a part of an argument. - </ol> - - <p><a name="index-Braces_002c-in-macro-arguments-1084"></a>Other characters that need to be quoted in macro arguments are -curly braces and backslash. For example - -<pre class="example"> @<var>macname</var> {\\\{\}\,} -</pre> - <p class="noindent">will pass the (almost certainly error-producing) argument -‘<samp><span class="samp">\{},</span></samp>’ 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> - -</div> - -<h3 class="section">19.3 Macro Details and Caveats</h3> - -<p><a name="index-Macro-details-1085"></a><a name="index-Details-of-macro-usage-1086"></a><a name="index-Caveats-for-macro-usage-1087"></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 -<samp><span class="command">makeinfo</span></samp> by invoking <samp><span class="command">texi2dvi</span></samp> with the ‘<samp><span class="samp">-E</span></samp>’ -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 unpredictable. - - <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>Commas in macro arguments, even if escaped by a backslash, don't -always work. - - <li>Macro arguments cannot cross lines. - - <li>It is (usually) best to avoid comments inside macro definitions, but -see the next item. - - <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. In general, -the interaction of newlines in the macro definitions and invocations -depends on the precise commands and context. You may be able to work -around some problems with judicious use of <code>@c</code>. Suppose you -define a macro that is always intended to be used on a line by itself: - - <pre class="example"> @macro linemac - @cindex whatever - @c - @end macro - ... - foo - @linemac - bar -</pre> - <p>Without the <code>@c</code>, there will be an unwanted blank line between -the ‘<samp><span class="samp">@cindex whatever</span></samp>’ and the ‘<samp><span class="samp">bar</span></samp>’ (one newline comes -from the macro definition, one from after the invocation), causing a -paragraph break. - - <p>On the other hand, you wouldn't want the <code>@c</code> if the macro was -sometimes invoked in the middle of a line (the text after the -invocation would be treated as a comment). - - <li>In general, you can't arbitrarily substitute a macro call for Texinfo -command arguments, even when the text is the same. It might work with -some commands, it fails with others. Best not to do it at all. For -instance, this fails: - - <pre class="example"> @macro offmacro - off - @end macro - @headings @offmacro -</pre> - <p class="noindent">You would expect this to be equivalent to <code>@headings off</code>, but -for TeXnical reasons, it fails with a mysterious error message -(<code>Paragraph ended before @headings was complete</code>). - - <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 <samp><span class="command">makeinfo</span></samp> 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> - -</div> - -<h3 class="section">19.4 ‘<samp><span class="samp">@alias </span><var>new</var><span class="samp">=</span><var>existing</var></samp>’</h3> - -<p><a name="index-Aliases_002c-command-1088"></a><a name="index-Command-aliases-1089"></a><a name="index-alias-1090"></a> -The ‘<samp><span class="samp">@alias</span></samp>’ 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 ‘<samp><span class="samp">@alias</span></samp>’ 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> - -</div> - -<h3 class="section">19.5 ‘<samp><span class="samp">definfoenclose</span></samp>’: Customized Highlighting</h3> - -<p><a name="index-Highlighting_002c-customized-1091"></a><a name="index-Customized-highlighting-1092"></a><a name="index-definfoenclose-1093"></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 -<samp><span class="file">texinfo.tex</span></samp>, <samp><span class="file">texinfo.cnf</span></samp>, or within an ‘<samp><span class="samp">@iftex</span></samp>’ 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 predefined 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-1094"></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 ‘<samp><span class="samp">@ifinfo</span></samp>’, but -the raw TeX commands do need to be in ‘<samp><span class="samp">@iftex</span></samp>’. - - <p><a name="index-headword-1095"></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>‘<samp><span class="samp">@definfoenclose</span></samp>’ 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> - -</div> - -<h2 class="chapter">20 Formatting and Printing Hardcopy</h2> - -<p><a name="index-Format-and-print-hardcopy-1096"></a><a name="index-Printing-hardcopy-1097"></a><a name="index-Hardcopy_002c-printing-it-1098"></a><a name="index-Making-a-printed-manual-1099"></a><a name="index-Sorting-indices-1100"></a><a name="index-Indices_002c-sorting-1101"></a><a name="index-g_t_0040TeX_007b_007d-index-sorting-1102"></a><a name="index-texindex-1103"></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> - -</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%2ftexindex"></a> -<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> - -</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-1104"></a><a name="index-Formatting-with-_0040code_007btex_007d-and-_0040code_007btexindex_007d-1105"></a><a name="index-DVI-file-1106"></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-1107"></a>The <code>tex</code> formatting command itself does not sort the indices; it -writes an output file of unsorted index data. To generate a printed -index after running the <samp><span class="command">tex</span></samp> command, you first need a sorted -index to work from. The <samp><span class="command">texindex</span></samp> command sorts indices. -(The source file <samp><span class="file">texindex.c</span></samp> comes as part of the standard -Texinfo distribution, among other places.) (<samp><span class="command">texi2dvi</span></samp> runs -<samp><span class="command">tex</span></samp> and <samp><span class="command">texindex</span></samp> as necessary.) - - <p><a name="index-Names-of-index-files-1108"></a><a name="index-Index-file-names-1109"></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 ‘<samp><span class="samp">.tex</span></samp>’ (or similar, see <a href="web2c.html#tex-invocation">tex invocation</a>) extension removed, followed by the two letter names of indices. -For example, the raw index output files for the input file -<samp><span class="file">foo.texinfo</span></samp> would be <samp><span class="file">foo.cp</span></samp>, <samp><span class="file">foo.vr</span></samp>, <samp><span class="file">foo.fn</span></samp>, -<samp><span class="file">foo.tp</span></samp>, <samp><span class="file">foo.pg</span></samp> and <samp><span class="file">foo.ky</span></samp>. Those are exactly the -arguments to give to <code>texindex</code>. - - <p><a name="index-Wildcards-1110"></a><a name="index-Globbing-1111"></a>Instead of specifying all the unsorted index file names explicitly, you -can use ‘<samp><span class="samp">??</span></samp>’ 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 ‘<samp><span class="samp">texindex foo.??</span></samp>’ -even if there are similarly named files with two letter extensions -that are not index files, such as ‘<samp><span class="samp">foo.el</span></samp>’. 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 ‘<samp><span class="samp">s</span></samp>’ 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-1112"></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-1113"></a><a name="index-novalidate-1114"></a><a name="index-Pointer-validation_002c-suppressing-1115"></a><a name="index-Chapters_002c-formatting-one-at-a-time-1116"></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> - -</div> - -<h3 class="section">20.3 Format with <code>texi2dvi</code></h3> - -<p><a name="index-texi2dvi-_0040r_007b_0028shell-script_0029_007d-1117"></a> -The <code>texi2dvi</code> command automatically runs both TeX and -<samp><span class="command">texindex</span></samp> 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 <samp><span class="file">foo.texi</span></samp>, do this (where -‘<samp><span class="samp">prompt$ </span></samp>’ 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 (‘<samp><span class="samp">.texi</span></samp>’, ‘<samp><span class="samp">.texinfo</span></samp>’, etc.). Under -MS-DOS and perhaps in other circumstances, you may need to run ‘<samp><span class="samp">sh -texi2dvi foo.texi</span></samp>’ instead of relying on the operating system to invoke -the shell on the ‘<samp><span class="samp">texi2dvi</span></samp>’ script. - - <p><a name="index-g_t_002d_002dcommand-_0040r_007b_0028_0040command_007btexi2dvi_007d_0029_007d-1118"></a>One useful option to <code>texi2dvi</code> is ‘<samp><span class="samp">--command=</span><var>cmd</var></samp>’. -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 <samp><span class="file">texinfo.cnf</span></samp>; -see <a href="#Preparing-for-TeX">Preparing for TeX</a>). - - <p><a name="index-g_t_002d_002dpdf-_0040r_007b_0028_0040command_007btexi2dvi_007d_0029_007d-1119"></a>With the <samp><span class="option">--pdf</span></samp> option, <samp><span class="command">texi2dvi</span></samp> produces PDF output -instead of DVI (see <a href="#PDF-Output">PDF Output</a>), by running <samp><span class="command">pdftex</span></samp> -instead of <samp><span class="command">tex</span></samp>. Alternatively, the command -<samp><span class="command">texi2pdf</span></samp> is an abbreviation for running ‘<samp><span class="samp">texi2dvi ---pdf</span></samp>’. The command <samp><span class="command">pdftexi2dvi</span></samp> is also supported as a -convenience to AUC-TeX users, since the latter merely prepends -‘<samp><span class="samp">pdf</span></samp>’ to DVI producing tools to have PDF producing tools. - - <p><a name="index-g_t_0040LaTeX_007b_007d_002c-processing-with-_0040command_007btexi2dvi_007d-1120"></a><samp><span class="command">texi2dvi</span></samp> can also be used to process LaTeX files; simply -run ‘<samp><span class="samp">texi2dvi filename.ext</span></samp>’. - - <p><a name="index-g_t_002d_002dlanguage-_0040r_007b_0028_0040command_007btexi2dvi_007d_0029_007d-1121"></a>Normally <samp><span class="command">texi2dvi</span></samp> is able to guess the input file language -by its contents and file name suffix. If, however, it fails to do so -you can specify the input language using -<samp><span class="option">--language=</span><var>lang</var></samp> command line option, where <var>lang</var> -is either ‘<samp><span class="samp">latex</span></samp>’ or ‘<samp><span class="samp">texinfo</span></samp>’. - - <p><samp><span class="command">texi2dvi</span></samp> will use <samp><span class="command">etex</span></samp> (or <samp><span class="command">pdfetex</span></samp>) if -they are available; these extended versions of TeX are not -required, and the DVI (or PDF) output is identical, but they simplify -the TeX programming in some cases, and provide additional tracing -information when debugging <samp><span class="file">texinfo.tex</span></samp>. - - <p><a name="index-g_t_002d_002dtranslate_002dfile-_0040r_007b_0028_0040command_007btexi2dvi_007d_0029_007d-1122"></a>Several options are provided for handling documents, written in -character sets other than ASCII. The -<samp><span class="option">--translate-file=</span><var>file</var></samp> option instructs -<samp><span class="command">texi2dv</span></samp> to translate input into internal TeX character -set using <dfn>translation file</dfn> <var>file</var> (see <a href="web2c.html#TCX-files">TCX files</a>). - - <p><a name="index-g_t_002d_002drecode-_0040r_007b_0028_0040command_007btexi2dvi_007d_0029_007d-1123"></a>The options <samp><span class="option">--recode</span></samp> and <samp><span class="option">--recode-from=</span><var>enc</var></samp> -allow conversion of an input document before running TeX. The -<samp><span class="option">--recode</span></samp> option recodes the document from encoding specified -by ‘<samp><span class="samp">@documentencoding</span></samp>’ command -(see <a href="#documentencoding"><code>documentencoding</code></a>) to plain 7-bit -‘<samp><span class="samp">texinfo</span></samp>’ encoding. - - <p><a name="index-g_t_002d_002drecode_002dfrom-_0040r_007b_0028_0040command_007btexi2dvi_007d_0029_007d-1124"></a>The option <samp><span class="option">--recode-from=</span><var>enc</var></samp> recodes the document from -<var>enc</var> encoding to the encoding specified by -‘<samp><span class="samp">@documentencoding</span></samp>’. This is useful, for example, if the -document is written in ‘<samp><span class="samp">UTF-8</span></samp>’ encoding and an equivalent 8-bit -encoding is supported by <samp><span class="command">makeinfo</span></samp>. - - <p>Both <samp><span class="option">--recode</span></samp> and <samp><span class="option">--recode-from=</span><var>enc</var></samp> use -<samp><span class="command">recode</span></samp> utility to perform the conversion. If -<samp><span class="command">recode</span></samp> fails to process the file, <samp><span class="command">texi2dvi</span></samp> prints -a warning and continues using unmodified input file. - - <p>For a list of other options, run ‘<samp><span class="samp">texi2dvi --help</span></samp>’. - -<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> - -</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-1125"></a> -The precise command to print a DVI file depends on your system -installation. Two common ones are ‘<samp><span class="samp">dvips foo.dvi -o</span></samp>’ and ‘<samp><span class="samp">lpr --d foo.dvi</span></samp>’. - - <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-1126"></a><a name="index-Printing-DVI-files_002c-on-MS_002dDOS_002fMS_002dWindows-1127"></a><a name="index-lpr_0040r_007b_002dd_002c-replacements-on-MS_002dDOS_002fMS_002dWindows_007d-1128"></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 -‘<samp><span class="samp">-d</span></samp>’ 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</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 ‘<samp><span class="samp">PRN</span></samp>’. -</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> - -</div> - -<h3 class="section">20.5 From an Emacs Shell</h3> - -<p><a name="index-Print_002c-format-from-Emacs-shell-1129"></a><a name="index-Format_002c-print-from-Emacs-shell-1130"></a><a name="index-Shell_002c-format_002c-print-from-1131"></a><a name="index-Emacs-shell_002c-format_002c-print-from-1132"></a><a name="index-GNU-Emacs-shell_002c-format_002c-print-from-1133"></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> - -</div> - -<h3 class="section">20.6 Formatting and Printing in Texinfo Mode</h3> - -<p><a name="index-Region-printing-in-Texinfo-mode-1134"></a><a name="index-Format-and-print-in-Texinfo-mode-1135"></a><a name="index-Print-and-format-in-Texinfo-mode-1136"></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 <samp><span class="file">.log</span></samp> 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 <samp><span class="file">*tex-shell*</span></samp>. 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 ‘<samp><span class="samp">*tex-shell*</span></samp>’ buffer, -and you can switch to and from and use the ‘<samp><span class="samp">*tex-shell*</span></samp>’ 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</a>), or with your <samp><span class="file">.emacs</span></samp> -initialization file (see <a href="emacs.html#Init-File">Init File</a>). - - <p><a name="index-Customize-Emacs-package-_0028_0040t_007bDevelopment_002fDocs_002fTexinfo_007d_0029-1137"></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</a>, for more details about this. The Texinfo variables can -be found in the ‘<samp><span class="samp">Development/Docs/Texinfo</span></samp>’ group, once you invoke -the <kbd>M-x customize</kbd> command. - -<div class="node"> -<p><hr> -<a name="Compile-Command"></a> -<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> - -</div> - -<h3 class="section">20.7 Using the Local Variables List</h3> - -<p><a name="index-Local-variables-1138"></a><a name="index-Compile-command-for-formatting-1139"></a><a name="index-Format-with-the-compile-command-1140"></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 -<samp><span class="file">*compilation*</span></samp> buffer in which Emacs runs the compile command. -For example, at the end of the <samp><span class="file">gdb.texinfo</span></samp> 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</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> - -</div> - -<h3 class="section">20.8 TeX Formatting Requirements Summary</h3> - -<p><a name="index-Requirements-for-formatting-1141"></a><a name="index-Minimal-requirements-for-formatting-1142"></a><a name="index-Formatting-requirements-1143"></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> - -</div> - -<h3 class="section">20.9 Preparing for TeX</h3> - -<p><a name="index-Preparing-for-_0040TeX_007b_007d-1144"></a><a name="index-g_t_0040TeX_007b_007d-input-initialization-1145"></a><a name="index-g_t_0040b_007b_002eprofile_007d-initialization-file-1146"></a><a name="index-g_t_0040b_007b_002ecshrc_007d-initialization-file-1147"></a><a name="index-Initialization-file-for-_0040TeX_007b_007d-input-1148"></a> -TeX needs to know where to find the <samp><span class="file">texinfo.tex</span></samp> file that the -‘<samp><span class="samp">\input texinfo</span></samp>’ command on the first line reads. The -<samp><span class="file">texinfo.tex</span></samp> 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-1149"></a> -Usually, the installer has put the <samp><span class="file">texinfo.tex</span></samp> 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 <samp><span class="file">texinfo.tex</span></samp> 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-1150"></a>Also, you should install <samp><span class="file">epsf.tex</span></samp>, 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-European-Computer-Modern-fonts_002c-installing-1151"></a><a name="index-EC-fonts_002c-installing-1152"></a><a name="index-CM_002dSuper-fonts_002c-installing-1153"></a>To be able to use quotation marks other than those used in English -you'll need to install European Computer Modern fonts and optionally -CM-Super fonts, unless they are already installed (see <a href="#Inserting-Quotation-Marks">Inserting Quotation Marks</a>). - - <p><a name="index-feymr10_0040r_007b_002c-installing_007d-1154"></a><a name="index-Euro-font_002c-installing-1155"></a>If you intend to use the <code>@euro</code> command, you should install the -Euro font, if it is not already installed. See <a href="#euro">euro</a>. - - <p><a name="index-texinfo_002ecnf-_0040r_007binstallation_007d-1156"></a><a name="index-Customizing-of-_0040TeX_007b_007d-for-Texinfo-1157"></a><a name="index-Site_002dwide-Texinfo-configuration-file-1158"></a>Optionally, you may create an additional <samp><span class="file">texinfo.cnf</span></samp>, 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 <samp><span class="file">texinfo.cnf</span></samp> contains the line ‘<samp><span class="samp">@afourpaper</span></samp>’ -(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 -<samp><span class="file">texinfo.cnf</span></samp>, you do not need to create it. - - <p><a name="index-Environment-variable-_0040code_007bTEXINPUTS_007d-1159"></a><a name="index-TEXINPUTS-1160"></a>If neither of the above locations for these system files suffice for -you, you can specify the directories explicitly. For -<samp><span class="file">texinfo.tex</span></samp>, you can do this by writing the complete path for the -file after the <code>\input</code> command. Another way, that works for both -<samp><span class="file">texinfo.tex</span></samp> and <samp><span class="file">texinfo.cnf</span></samp> (and any other file TeX -might read), is to set the <code>TEXINPUTS</code> environment variable in your -<samp><span class="file">.cshrc</span></samp> or <samp><span class="file">.profile</span></samp> file. - - <p>Which you use of <samp><span class="file">.cshrc</span></samp> or <samp><span class="file">.profile</span></samp> 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 <samp><span class="file">.cshrc</span></samp> file for -initialization information, and the former read <samp><span class="file">.profile</span></samp>. - - <p>In a <samp><span class="file">.cshrc</span></samp> file, you could use the following <code>csh</code> command -sequence: - -<pre class="example"> setenv TEXINPUTS .:/home/me/mylib: -</pre> - <p>In a <samp><span class="file">.profile</span></samp> 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 -<samp><span class="file">autoexec.bat</span></samp> file, or in the Windows Registry. - -<p class="noindent">These settings would cause TeX to look for <samp><span class="file">\input</span></samp> file first -in the current directory, indicated by the ‘<samp><span class="samp">.</span></samp>’, then in a -hypothetical user ‘<samp><span class="samp">me</span></samp>’'s <samp><span class="file">mylib</span></samp> directory, and finally in -the system directories. (A leading, trailing, or doubled ‘<samp><span class="samp">:</span></samp>’ -indicates searching the system directories at that point.) - - <p><a name="index-Dumping-a-_002efmt-file-1161"></a><a name="index-Format-file_002c-dumping-1162"></a>Finally, you may wish to dump a <samp><span class="file">.fmt</span></samp> file (see <a href="web2c.html#Memory-dumps">Memory dumps</a>) so that TeX can load Texinfo faster. (The -disadvantage is that then updating <samp><span class="file">texinfo.tex</span></samp> requires -redumping.) You can do this by running this command, assuming -<samp><span class="file">epsf.tex</span></samp> is findable by TeX: - -<pre class="example"> initex texinfo @dump -</pre> - <p class="noindent">(<code>dump</code> is a TeX primitive.) Then, move <samp><span class="file">texinfo.fmt</span></samp> to -wherever your <code>.fmt</code> files are found; typically, this will be in the -subdirectory <samp><span class="file">web2c</span></samp> 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> - -</div> - -<h3 class="section">20.10 Overfull “hboxes”</h3> - -<p><a name="index-Overfull-_0040samp_007bhboxes_007d-1163"></a><a name="index-g_t_0040samp_007bhboxes_007d_002c-overfull-1164"></a><a name="index-Final-output-1165"></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-1166"></a>(In TeX, lines are in “horizontal boxes”, hence the term, “hbox”. -‘<samp><span class="samp">@hbox</span></samp>’ 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-g_t_005cemergencystretch-1167"></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 ‘<samp><span class="samp">.15\hsize</span></samp>’. <code>\hsize</code> is the TeX dimension -containing the current line width. - - <p><a name="index-Black-rectangle-in-hardcopy-1168"></a><a name="index-Rectangle_002c-black-in-hardcopy-1169"></a><a name="index-Box_002c-ugly-black-in-hardcopy-1170"></a><a name="index-Ugly-black-rectangles-in-hardcopy-1171"></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-1172"></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> - -</div> - -<h3 class="section">20.11 Printing “Small” Books</h3> - -<p><a name="index-smallbook-1173"></a><a name="index-Small-book-size-1174"></a><a name="index-Book_002c-printing-small-1175"></a><a name="index-Page-sizes-for-books-1176"></a><a name="index-Size-of-printed-book-1177"></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> - -</div> - -<h3 class="section">20.12 Printing on A4 Paper</h3> - -<p><a name="index-A4-paper_002c-printing-on-1178"></a><a name="index-A5-paper_002c-printing-on-1179"></a><a name="index-Paper-size_002c-A4-1180"></a><a name="index-European-A4-paper-1181"></a><a name="index-afourpaper-1182"></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-1183"></a><a name="index-afourwide-1184"></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> - -</div> - -<h3 class="section">20.13 <code>@pagesizes</code> [<var>width</var>][, <var>height</var>]: Custom Page Sizes</h3> - -<p><a name="index-pagesizes-1185"></a><a name="index-Custom-page-sizes-1186"></a><a name="index-Page-sizes_002c-customized-1187"></a><a name="index-Text-width-and-height-1188"></a><a name="index-Width-of-text-area-1189"></a><a name="index-Height-of-text-area-1190"></a><a name="index-Depth-of-text-area-1191"></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-1192"></a><a name="index-Legal-paper_002c-printing-on-1193"></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-1194"></a>To make more elaborate changes, such as changing any of the page -margins, you must define a new command in <samp><span class="file">texinfo.tex</span></samp> (or -<samp><span class="file">texinfo.cnf</span></samp>, 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> - -</div> - -<h3 class="section">20.14 Cropmarks and Magnification</h3> - -<p><a name="index-cropmarks-1195"></a><a name="index-Cropmarks-for-printing-1196"></a><a name="index-Printing-cropmarks-1197"></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 -<samp><span class="file">texinfo.tex</span></samp>. - - <p><a name="index-g_t_005cmag-_0040r_007b_0028raw-_0040TeX_007b_007d-magnification_0029_007d-1198"></a><a name="index-Magnified-printing-1199"></a><a name="index-Larger-or-smaller-pages-1200"></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 ‘<samp><span class="samp">=</span></samp>’ 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> - -</div> - -<h3 class="section">20.15 PDF Output</h3> - -<p><a name="index-PDF-output-1201"></a> -<a name="index-pdftex-1202"></a>The simplest way to generate PDF output from Texinfo source is to run -the convenience script <samp><span class="command">texi2pdf</span></samp> (or <samp><span class="command">pdftexi2dvi</span></samp>); -this simply executes the <samp><span class="command">texi2dvi</span></samp> script with the -<samp><span class="option">--pdf</span></samp> option (see <a href="#Format-with-texi2dvi">Format with texi2dvi</a>). If for some -reason you want to process the document by hand, simply run the -<samp><span class="command">pdftex</span></samp> program instead of plain <samp><span class="command">tex</span></samp>. That is, run -‘<samp><span class="samp">pdftex foo.texi</span></samp>’ instead of ‘<samp><span class="samp">tex foo.texi</span></samp>’. - - <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. Related links: - - <ul> -<li>GNU GV, a <a href="http://www.foolabs.com/xpdf/">Ghostscript-based PDF reader</a>. (It can also preview PostScript documents.) - - <li>A freely available standalone <a href="http://www.foolabs.com/xpdf/">PDF reader</a> for the X window system. - - <li><a href="http://partners.adobe.com/asn/acrobat/sdk/public/docs/">PDF definition</a>. - - </ul> - - <p>At present, Texinfo does not provide -‘<samp><span class="samp">@ifpdf</span></samp>’ or ‘<samp><span class="samp">@pdf</span></samp>’ commands as for the other output -formats, since PDF documents contain many internal links that would be -hard or impossible to get right at the Texinfo source level. - - <p>PDF files require special software to be displayed, unlike the plain -ASCII formats (Info, HTML) that Texinfo supports. They also tend to -be much larger than the DVI files output by TeX by default. -Nevertheless, a PDF file does define an actual typeset document in a -self-contained file, so it has its place. - -<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> - -</div> - -<h3 class="section">20.16 How to Obtain TeX</h3> - -<p><a name="index-Obtaining-_0040TeX_007b_007d-1203"></a><a name="index-g_t_0040TeX_007b_007d_002c-how-to-obtain-1204"></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. - 51 Franklin St, Fifth Floor - Boston, MA 02110-1301 - 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> - -</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> - -</div> - -<h3 class="section">21.1 Creating an Info File</h3> - -<p><a name="index-Creating-an-Info-file-1205"></a><a name="index-Info_002c-creating-an-online-file-1206"></a><a name="index-Formatting-a-file-for-Info-1207"></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> - -</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> - -</div> - -<h4 class="subsection">21.1.2 Running <code>makeinfo</code> from a Shell</h4> - -<p><a name="index-makeinfo-1208"></a> -To create an Info file from a Texinfo file, invoke <samp><span class="command">makeinfo</span></samp> -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><samp><span class="command">makeinfo</span></samp> 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> - -</div> - -<h4 class="subsection">21.1.3 Options for <code>makeinfo</code></h4> - -<p><a name="index-g_t_0040code_007bmakeinfo_007d-options-1209"></a><a name="index-Options-for-_0040code_007bmakeinfo_007d-1210"></a> -The <samp><span class="command">makeinfo</span></samp> program accepts many options. Perhaps the most -commonly needed are those that change the output format. By default, -<samp><span class="command">makeinfo</span></samp> outputs Info files. - - <p>Each command line option is a word preceded by ‘<samp><span class="samp">--</span></samp>’ or a letter -preceded by ‘<samp><span class="samp">-</span></samp>’. 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 <samp><span class="file">bison.texinfo</span></samp> 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-g_t_002dD-_0040var_007bvar_007d-1211"></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-g_t_002d_002dcommands_002din_002dnode_002dnames-1212"></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 -‘<samp><span class="samp">--no-validate</span></samp>’ 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-g_t_002d_002dcss_002dinclude-1213"></a>Include the contents of <var>file</var>, which should contain cascading -style sheets specifications, in the ‘<samp><span class="samp"><style></span></samp>’ block of the HTML -output. See <a href="#HTML-CSS">HTML CSS</a>. If <var>file</var> is ‘<samp><span class="samp">-</span></samp>’, read standard -input. - - <br><dt><code>--css-ref=</code><var>url</var><dd><a name="index-g_t_002d_002dcss_002dref-1214"></a>In HTML mode, add a ‘<samp><span class="samp"><link></span></samp>’ tag to the HTML output which -references a cascading style sheet at <var>url</var>. This allows using -standalone style sheets. - - <br><dt><code>--disable-encoding</code><dt><code>--enable-encoding</code><dd><a name="index-g_t_002d_002ddisable_002dencoding-1215"></a><a name="index-g_t_002d_002denable_002dencoding-1216"></a>By default, or with <samp><span class="option">--enable-encoding</span></samp>, output accented and -special characters in Info or plain text output based on -‘<samp><span class="samp">@documentencoding</span></samp>’. With <samp><span class="option">--disable-encoding</span></samp>, 7-bit -ASCII transliterations are output. -See <a href="#documentencoding"><code>documentencoding</code></a>, and <a href="#Inserting-Accents">Inserting Accents</a>. - - <br><dt><code>--docbook</code><dd><a name="index-g_t_002d_002ddocbook-1217"></a>Generate Docbook output rather than Info. - - <br><dt><code>--document-language=</code><var>lang</var><dd><a name="index-g_t_002d_002ddocument_002dlanguage-1218"></a><a name="index-LANG-1219"></a>Use <var>lang</var> to translate Texinfo keywords which end up in the -output document. The default is the locale specified by the -<code>@documentlanguage</code> command if there is one -(see <a href="#documentlanguage">documentlanguage</a>). - - <br><dt><code>--error-limit=</code><var>limit</var><dt><code>-e </code><var>limit</var><dd><a name="index-g_t_002d_002derror_002dlimit_003d_0040var_007blimit_007d-1220"></a><a name="index-g_t_002de-_0040var_007blimit_007d-1221"></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-g_t_002d_002dfill_002dcolumn_003d_0040var_007bwidth_007d-1222"></a><a name="index-g_t_002df-_0040var_007bwidth_007d-1223"></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 ‘<samp><span class="samp">--html</span></samp>’. - - <br><dt><code>--footnote-style=</code><var>style</var><dt><code>-s </code><var>style</var><dd><a name="index-g_t_002d_002dfootnote_002dstyle_003d_0040var_007bstyle_007d-1224"></a><a name="index-g_t_002ds-_0040var_007bstyle_007d-1225"></a>Set the footnote style to <var>style</var>, either ‘<samp><span class="samp">end</span></samp>’ for the end -node style (the default) or ‘<samp><span class="samp">separate</span></samp>’ 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 ‘<samp><span class="samp">separate</span></samp>’, <code>makeinfo</code> makes a new node -containing the footnotes found in the current node. When the footnote -style is ‘<samp><span class="samp">end</span></samp>’, <code>makeinfo</code> places the footnote references at -the end of the current node. Ignored with ‘<samp><span class="samp">--html</span></samp>’. - - <br><dt><code>--force</code><dt><code>-F</code><dd><a name="index-g_t_002d_002dforce-1226"></a><a name="index-g_t_002dF-1227"></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-g_t_002d_002dhelp-1228"></a><a name="index-g_t_002dh-1229"></a>Print a usage message listing all available options, then exit successfully. - - <br><dt><code>--html</code><dd><a name="index-g_t_002d_002dhtml-1230"></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-g_t_002dI-_0040var_007bdir_007d-1231"></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 <samp><span class="file">.</span></samp> is appended. Note that -<var>dir</var> can actually be a list of several directories separated by the -usual path separator character (‘<samp><span class="samp">:</span></samp>’ on Unix, ‘<samp><span class="samp">;</span></samp>’ on -MS-DOS/MS-Windows). - - <br><dt><code>--ifdocbook</code><dd><a name="index-g_t_002d_002difdocbook-1232"></a><dt><code>--ifhtml</code><dd><a name="index-g_t_002d_002difhtml-1233"></a><dt><code>--ifinfo</code><dd><a name="index-g_t_002d_002difinfo-1234"></a><dt><code>--ifplaintext</code><dd><a name="index-g_t_002d_002difplaintext-1235"></a><dt><code>--iftex</code><dd><a name="index-g_t_002d_002diftex-1236"></a><dt><code>--ifxml</code><dd><a name="index-g_t_002d_002difxml-1237"></a>For the specified format, process ‘<samp><span class="samp">@if</span><var>format</var></samp>’ and -‘<samp><span class="samp">@</span><var>format</var></samp>’ commands even if not generating the given output -format. For instance, if <samp><span class="option">--iftex</span></samp> is specified, then -‘<samp><span class="samp">@iftex</span></samp>’ and ‘<samp><span class="samp">@tex</span></samp>’ blocks will be read. - - <br><dt><code>--macro-expand=</code><var>file</var><dt><code>-E </code><var>file</var><dd><a name="index-g_t_002d_002dmacro_002dexpand_003d_0040var_007bfile_007d-1238"></a><a name="index-g_t_002dE-_0040var_007bfile_007d-1239"></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 -<samp><span class="command">texi2dvi</span></samp>. - - <br><dt><code>--no-headers</code><br><dt><code>--plaintext</code><dd><a name="index-g_t_002d_002dno_002dheaders-1240"></a><a name="index-g_t_002d_002dplaintext-1241"></a><a name="index-Plain-text-output-1242"></a><a name="index-ASCII-text-output-1243"></a><a name="index-Generating-plain-text-files-1244"></a><a name="index-g_t_0040file_007bINSTALL_007d-file_002c-generating-1245"></a><a name="index-Node-separators_002c-omitting-1246"></a><a name="index-Menus_002c-omitting-1247"></a>Do not include menus or node separator lines in the output, and -implicitly <samp><span class="option">--enable-encoding</span></samp> (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 -<samp><span class="file">INSTALL</span></samp> file). - - <p><a name="index-Navigation-links_002c-omitting-1248"></a>For HTML output, likewise omit menus. And if ‘<samp><span class="samp">--no-split</span></samp>’ 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 <samp><span class="option">-o</span></samp>. - - <br><dt><code>--no-ifdocbook</code><dd><a name="index-g_t_002d_002dno_002difdocbook-1249"></a><dt><code>--no-ifhtml</code><dd><a name="index-g_t_002d_002dno_002difhtml-1250"></a><dt><code>--no-ifinfo</code><dd><a name="index-g_t_002d_002dno_002difinfo-1251"></a><dt><code>--no-ifplaintext</code><dd><a name="index-g_t_002d_002dno_002difplaintext-1252"></a><dt><code>--no-iftex</code><dd><a name="index-g_t_002d_002dno_002diftex-1253"></a><dt><code>--no-ifxml</code><dd><a name="index-g_t_002d_002dno_002difxml-1254"></a>Do not process ‘<samp><span class="samp">@if</span><var>format</var></samp>’ and ‘<samp><span class="samp">@</span><var>format</var></samp>’ -commands, and do process ‘<samp><span class="samp">@ifnot</span><var>format</var></samp>’, even if -generating the given format. For instance, if <samp><span class="option">--no-ifhtml</span></samp> is -specified, then ‘<samp><span class="samp">@ifhtml</span></samp>’ and ‘<samp><span class="samp">@html</span></samp>’ blocks will not be -read, and ‘<samp><span class="samp">@ifnothtml</span></samp>’ blocks will be. - - <br><dt><code>--no-number-footnotes</code><dd><a name="index-g_t_002d_002dno_002dnumber_002dfootnotes-1255"></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>--no-number-sections</code><dd><a name="index-g_t_002d_002dno_002dnumber_002dsections-1256"></a>Do not output chapter, section, and appendix numbers. -You need to specify this if your manual is not hierarchically-structured. - - <br><dt><code>--no-split</code><dd><a name="index-g_t_002d_002dno_002dsplit-1257"></a><a name="index-Splitting-of-output-files-1258"></a><a name="index-Output-file-splitting-1259"></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-g_t_002d_002dno_002dpointer_002dvalidate-1260"></a><a name="index-g_t_002d_002dno_002dvalidate-1261"></a><a name="index-Pointer-validation_002c-suppressing-1262"></a>Suppress the pointer-validation phase of <code>makeinfo</code>—a dangerous -thing to do. 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-g_t_002d_002dno_002dwarn-1263"></a>Suppress warning messages (but <em>not</em> error messages). - - <br><dt><code>--number-sections</code><dd><a name="index-g_t_002d_002dnumber_002dsections-1264"></a>Output chapter, section, and appendix numbers as in printed manuals. -This is the default. It works only with hierarchically-structured -manuals. - - <br><dt><code>--output=</code><var>file</var><dt><code>-o </code><var>file</var><dd><a name="index-g_t_002d_002doutput_003d_0040var_007bfile_007d-1265"></a><a name="index-g_t_002do-_0040var_007bfile_007d-1266"></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 ‘<samp><span class="samp">-</span></samp>’, output -goes to standard output and ‘<samp><span class="samp">--no-split</span></samp>’ 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-g_t_002dP-_0040var_007bdir_007d-1267"></a>Prepend <var>dir</var> to the directory search list for <code>@include</code>. -If <var>dir</var> is not given, the current directory <samp><span class="file">.</span></samp> is prepended. -See ‘<samp><span class="samp">-I</span></samp>’ for more details. - - <br><dt><code>--paragraph-indent=</code><var>indent</var><dt><code>-p </code><var>indent</var><dd><a name="index-g_t_002d_002dparagraph_002dindent_003d_0040var_007bindent_007d-1268"></a><a name="index-g_t_002dp-_0040var_007bindent_007d-1269"></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>‘<samp><span class="samp">asis</span></samp>’<dd>Preserve any existing indentation at the starts of paragraphs. - - <br><dt>‘<samp><span class="samp">0</span></samp>’ or ‘<samp><span class="samp">none</span></samp>’<dd>Delete any existing indentation. - - <br><dt><var>num</var><dd>Indent each paragraph by <var>num</var> spaces. -</dl> - - <br><dt><code>--split-size=</code><var>num</var><dd><a name="index-g_t_002d_002dsplit_002dsize_003d_0040var_007bnum_007d-1270"></a>Keep Info files to at most <var>num</var> characters; default is 300,000. - - <br><dt><code>--transliterate-file-names</code><dd><a name="index-g_t_002d_002dtransliterate_002dfile_002dnames-1271"></a>Enable transliteration of 8-bit characters in node names for the -purpose of file name creation. See <a href="#HTML-Xref-8_002dbit-Character-Expansion">HTML Xref 8-bit Character Expansion</a>. - - <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-g_t_002d_002dverbose-1272"></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-g_t_002d_002dversion-1273"></a><a name="index-g_t_002dV-1274"></a>Print the version number, then exit successfully. - - <br><dt><code>--xml</code><dd><a name="index-g_t_002d_002dxml-1275"></a>Generate XML output rather than Info. - - </dl> - - <p><a name="index-TEXINFO_005fOUTPUT_005fFORMAT-1276"></a><a name="index-Environment-variable-_0040code_007bTEXINFO_005fOUTPUT_005fFORMAT_007d-1277"></a><samp><span class="command">makeinfo</span></samp> also reads the environment variable -<samp><span class="env">TEXINFO_OUTPUT_FORMAT</span></samp> 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> - -</div> - -<h4 class="subsection">21.1.4 Pointer Validation</h4> - -<p><a name="index-Pointer-validation-with-_0040code_007bmakeinfo_007d-1278"></a><a name="index-Validation-of-pointers-1279"></a> -If you do not suppress pointer validation with the ‘<samp><span class="samp">--no-validate</span></samp>’ -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 -<samp><span class="file">(dir)</span></samp>, 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-g_t_0040_0040_002dcommands-in-_0040_0040node_002c-limited-support-1280"></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. (Your best bet -is to avoid using @-commands in node names.) 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 ‘<samp><span class="samp">--commands-in-node-names</span></samp>’ 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-g_t_0040_0040value-in-_0040_0040node-lines-1281"></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 -‘<samp><span class="samp">--commands-in-node-names</span></samp>’ option. - - <p>‘<samp><span class="samp">--commands-in-node-names</span></samp>’ has no effect if the ‘<samp><span class="samp">--no-validate</span></samp>’ -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> - -</div> - -<h4 class="subsection">21.1.5 Running <code>makeinfo</code> Within Emacs</h4> - -<p><a name="index-Running-_0040code_007bmakeinfo_007d-in-Emacs-1282"></a><a name="index-g_t_0040code_007bmakeinfo_007d-inside-Emacs-1283"></a><a name="index-Shell_002c-running-_0040code_007bmakeinfo_007d-in-1284"></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-1285"></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-1286"></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-1287"></a><a name="index-Parsing-errors-1288"></a><a name="index-next_002derror-1289"></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</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-1290"></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-1291"></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 <samp><span class="file">.emacs</span></samp> initialization file. - - <p>For example, you could write the following in your <samp><span class="file">.emacs</span></samp> 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</a>,<br> -<a href="emacs.html#Examining">Examining and Setting Variables</a>,<br> -<a href="emacs.html#Init-File">Init File</a>, and<br> -<a href="#makeinfo-options">Options for <code>makeinfo</code></a>. - -<div class="node"> -<p><hr> -<a name="texinfo-format-commands"></a> -<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> - -</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 ‘<samp><span class="samp">*Info Region*</span></samp>’. - - <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-1292"></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-1293"></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> - -</div> - -<!-- node-name, next, previous, up --> -<h4 class="subsection">21.1.7 Batch Formatting</h4> - -<p><a name="index-Batch-formatting-for-Info-1294"></a><a name="index-Info-batch-formatting-1295"></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</a>.) - - <p>Here is a shell command to format all the files that end in -<samp><span class="file">.texinfo</span></samp> 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> - -</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-1296"></a><a name="index-Tag-table_002c-making-automatically-1297"></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-1298"></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 ‘<samp><span class="samp">-1</span></samp>’<!-- /@w -->, -‘<samp><span class="samp">-2</span></samp>’<!-- /@w -->, ‘<samp><span class="samp">-3</span></samp>’<!-- /@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 <samp><span class="file">test-texinfo</span></samp> 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 <samp><span class="file">test-texinfo</span></samp> had far more nodes than are shown here.) Each of -the split-off, indirect files, <samp><span class="file">test-texinfo-1</span></samp>, -<samp><span class="file">test-texinfo-2</span></samp>, and <samp><span class="file">test-texinfo-3</span></samp>, is listed in this file -after the line that says ‘<samp><span class="samp">Indirect:</span></samp>’. The tag table is listed after -the line that says ‘<samp><span class="samp">Tag table:</span></samp>’. - - <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> - -</div> - -<h3 class="section">21.2 Installing an Info File</h3> - -<p><a name="index-Installing-an-Info-file-1299"></a><a name="index-Info-file-installation-1300"></a><a name="index-g_t_0040file_007bdir_007d-directory-for-Info-installation-1301"></a> -Info files are usually kept in the <samp><span class="file">info</span></samp> 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> - -</div> - -<h4 class="subsection">21.2.1 The Directory File <samp><span class="file">dir</span></samp></h4> - -<p>For Info to work, the <samp><span class="file">info</span></samp> directory must contain a file that -serves as a top level directory for the Info system. By convention, -this file is called <samp><span class="file">dir</span></samp>. (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 <samp><span class="file">info</span></samp> directory.) - - <p>The <samp><span class="file">dir</span></samp> 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 ‘<samp><span class="samp">Info</span></samp>’ entry points to the `Top' node of the -<samp><span class="file">info</span></samp> file and the ‘<samp><span class="samp">Emacs</span></samp>’ entry points to the `Top' node -of the <samp><span class="file">emacs</span></samp> 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 <samp><span class="file">dir</span></samp> 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 <samp><span class="file">dir</span></samp>. - -<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> - -</div> - -<h4 class="subsection">21.2.2 Listing a New Info File</h4> - -<p><a name="index-Adding-a-new-Info-file-1302"></a><a name="index-Listing-a-new-Info-file-1303"></a><a name="index-New-Info-file_002c-listing-it-in-_0040file_007bdir_007d-file-1304"></a><a name="index-Info-file_002c-listing-a-new-1305"></a><a name="index-g_t_0040file_007bdir_007d-file-listing-1306"></a> -To add a new Info file to your system, you must write a menu entry to -add to the menu in the <samp><span class="file">dir</span></samp> file in the <samp><span class="file">info</span></samp> 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 <samp><span class="file">.info</span></samp> extension. Thus, the -Info file for GDB might be called either <samp><span class="file">gdb</span></samp> or <samp><span class="file">gdb.info</span></samp>. -The Info reader programs automatically try the file name both with and -without <samp><span class="file">.info</span></samp><a rel="footnote" href="#fn-10" name="fnd-10"><sup>10</sup></a>; so it is better to avoid -clutter and not to write ‘<samp><span class="samp">.info</span></samp>’ explicitly in the menu entry. For -example, the GDB menu entry should use just ‘<samp><span class="samp">gdb</span></samp>’ for the file -name, not ‘<samp><span class="samp">gdb.info</span></samp>’. - -<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> - -</div> - -<h4 class="subsection">21.2.3 Info Files in Other Directories</h4> - -<p><a name="index-Installing-Info-in-another-directory-1307"></a><a name="index-Info-installed-in-another-directory-1308"></a><a name="index-Another-Info-directory-1309"></a><a name="index-g_t_0040file_007bdir_007d-files-and-Info-directories-1310"></a> -If an Info file is not in the <samp><span class="file">info</span></samp> directory, there are three -ways to specify its location: - - <ol type=1 start=1> -<li>Write the pathname in the <samp><span class="file">dir</span></samp> file as the second part of the menu. - - <li>If you are using Emacs, list the name of the file in a second <samp><span class="file">dir</span></samp> -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 <samp><span class="file">dir</span></samp> files (the files -must be named <samp><span class="file">dir</span></samp>). Emacs merges the files named <samp><span class="file">dir</span></samp> 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 <samp><span class="file">.profile</span></samp> or <samp><span class="file">.cshrc</span></samp> 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 <samp><span class="file">/home/bob/info</span></samp> -directory, you could add an entry like this to the menu in the -standard <samp><span class="file">dir</span></samp> 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 <samp><span class="file">info-test</span></samp> file is -written as the second part of the menu entry. - - <p>Alternatively, you could write the following in your <samp><span class="file">.emacs</span></samp> file: - - <p><a name="index-Info_002ddirectory_002dlist-1311"></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 <samp><span class="file">dir</span></samp> file with the <samp><span class="file">dir</span></samp> -file in <samp><span class="file">/home/bob/info</span></samp>. Thus, Info will list the -<samp><span class="file">/home/bob/info/info-test</span></samp> file as a menu entry in the -<samp><span class="file">/home/bob/info/dir</span></samp> 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 <samp><span class="file">dir</span></samp> file. - - <p><a name="index-INFOPATH-1312"></a><a name="index-Environment-variable-_0040code_007bINFOPATH_007d-1313"></a>Finally, you can tell Info where to look by setting the <code>INFOPATH</code> -environment variable in your shell startup file, such as <samp><span class="file">.cshrc</span></samp>, -<samp><span class="file">.profile</span></samp> or <samp><span class="file">autoexec.bat</span></samp>. 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 -<samp><span class="file">.profile</span></samp> initialization file; but if you use <code>csh</code> or -<code>tcsh</code>, you set the variable in the <samp><span class="file">.cshrc</span></samp> initialization -file. On MS-DOS/MS-Windows systems, you must set <code>INFOPATH</code> in -your <samp><span class="file">autoexec.bat</span></samp> file or in the Registry. Each type of shell -uses a different syntax. - - <ul> -<li>In a <samp><span class="file">.cshrc</span></samp> 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 <samp><span class="file">.profile</span></samp> 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-1314"></a>In a <samp><span class="file">autoexec.bat</span></samp> 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 ‘<samp><span class="samp">.</span></samp>’ 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 <samp><span class="file">dir</span></samp> in any directory listed in the -<samp><span class="env">INFOPATH</span></samp> variable into a single menu presented to you in the node -called ‘<samp><span class="samp">(dir)Top</span></samp>’. - - <p><a name="index-Colon_002c-last-in-_0040env_007bINFOPATH_007d-1315"></a>However you set <samp><span class="env">INFOPATH</span></samp>, 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 <samp><span class="file">/local/info</span></samp> first, then the standard directories. -Leading or doubled colons are not treated specially. - - <p><a name="index-g_t_0040file_007bdir_007d-file_002c-creating-your-own-1316"></a>When you create your own <samp><span class="file">dir</span></samp> file for use with -<code>Info-directory-list</code> or <samp><span class="env">INFOPATH</span></samp>, it's easiest to start by -copying an existing <samp><span class="file">dir</span></samp> file and replace all the text after the -‘<samp><span class="samp">* Menu:</span></samp>’ 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> - -</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 <samp><span class="file">dir</span></samp>. -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-1317"></a><a name="index-direntry-1318"></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><code>install-info</code> will automatically reformat the description of the -menu entries it is adding. As a matter of convention, the description -of the main entry (above, ‘<samp><span class="samp">The GNU documentation format</span></samp>’) should -start at column 32, starting at zero (as in -<code>what-cursor-position</code> in Emacs). This will make it align with -most others. Description for individual utilities best start in -column 48, where possible. For more information about formatting see -the ‘<samp><span class="samp">--calign</span></samp>’, ‘<samp><span class="samp">--align</span></samp>’, and ‘<samp><span class="samp">--max-width</span></samp>’ options in -<a href="#Invoking-install_002dinfo">Invoking install-info</a>. - - <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-1319"></a><a name="index-Dir-categories_002c-choosing-1320"></a><a name="index-Categories_002c-choosing-1321"></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 <samp><span class="file">util/dir-example</span></samp> 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-1322"></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 <samp><span class="command">man</span></samp> system. - -<div class="node"> -<p><hr> -<a name="Invoking-install-info"></a> -<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> - -</div> - -<h4 class="subsection">21.2.5 Invoking <samp><span class="command">install-info</span></samp></h4> - -<p><a name="index-install_002dinfo-1323"></a> -<code>install-info</code> inserts menu entries from an Info file into the -top-level <samp><span class="file">dir</span></samp> file in the Info system (see the previous sections -for an explanation of how the <samp><span class="file">dir</span></samp> file works). <code>install-info</code> -also removes menu entries from the <samp><span class="file">dir</span></samp> file. It's most often -run as part of software installation, or when constructing a <samp><span class="file">dir</span></samp> 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 <samp><span class="file">dir</span></samp> file per invocation. - - <p><a name="index-g_t_0040file_007bdir_007d_002c-created-by-_0040code_007binstall_002dinfo_007d-1324"></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-1325"></a><a name="index-Dir-files_002c-compressed-1326"></a>If any input file is compressed with <code>gzip</code> (see <a href="gzip.html#Invoking-gzip">Invoking 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 <samp><var>dir-file</var><span class="file">.gz</span></samp>. - - <p>Options: - - <dl> -<dt><code>--add-once</code><dd>Specifies that the entry or entries will only be put into a single section. - - <br><dt><code>--align=</code><var>column</var><dd><a name="index-g_t_002d_002dalign_003d_0040var_007bcolumn_007d-1327"></a>Specifies the column that the second and subsequent lines of menu entry's -description will be formatted to begin at. The default for this option is -‘<samp><span class="samp">35</span></samp>’. It is used in conjunction with the ‘<samp><span class="samp">--max-width</span></samp>’ option. -<var>column</var> starts counting at 1. - - <br><dt><code>--append-new-sections</code><dd>Instead of alphabetizing new sections, place them at the end of the DIR file. - - <br><dt><code>--calign=</code><var>column</var><dd><a name="index-g_t_002d_002dcalign_003d_0040var_007bcolumn_007d-1328"></a>Specifies the column that the first line of menu entry's description will -be formatted to begin at. The default for this option is ‘<samp><span class="samp">33</span></samp>’. It is -used in conjunction with the ‘<samp><span class="samp">--max-width</span></samp>’ option. -When the name of the menu entry exceeds this column, entry's description -will start on the following line. -<var>column</var> starts counting at 1. - - <br><dt><code>--debug</code><dd><a name="index-g_t_002d_002ddebug-1329"></a>Report what is being done. - - <br><dt><code>--delete</code><dd><a name="index-g_t_002d_002ddelete-1330"></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 ‘<samp><span class="samp">.info</span></samp>’ in either one). Don't insert any new entries. -Any empty sections that result from the removal are also removed. - - <br><dt><code>--description=</code><var>text</var><dd><a name="index-g_t_002d_002ddescription_003d_0040var_007btext_007d-1331"></a>Specify the explanatory portion of the menu entry. If you don't specify -a description (either via ‘<samp><span class="samp">--entry</span></samp>’, ‘<samp><span class="samp">--item</span></samp>’ or this option), -the description is taken from the Info file itself. - - <br><dt><code>--dir-file=</code><var>name</var><dd><a name="index-g_t_002d_002ddir_002dfile_003d_0040var_007bname_007d-1332"></a>Specify file name of the Info directory file. This is equivalent to -using the <var>dir-file</var> argument. - - <br><dt><code>--dry-run</code><dd><a name="index-g_t_002d_002ddry_002drun-1333"></a>Same as ‘<samp><span class="samp">--test</span></samp>’. - - <br><dt><code>--entry=</code><var>text</var><dd><a name="index-g_t_002d_002dentry_003d_0040var_007btext_007d-1334"></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><dd><a name="index-g_t_002d_002dhelp-1335"></a>Display a usage message with basic usage and all available options, -then exit successfully. - - <br><dt><code>--info-file=</code><var>file</var><dd><a name="index-g_t_002d_002dinfo_002dfile_003d_0040var_007bfile_007d-1336"></a>Specify Info file to install in the directory. This is -equivalent to using the <var>info-file</var> argument. - - <br><dt><code>--info-dir=</code><var>dir</var><dd><a name="index-g_t_002d_002dinfo_002ddir_003d_0040var_007bdir_007d-1337"></a>Specify the directory where the directory file <samp><span class="file">dir</span></samp> resides. -Equivalent to ‘<samp><span class="samp">--dir-file=</span><var>dir</var><span class="samp">/dir</span></samp>’. - - <br><dt><code>--infodir=</code><var>dir</var><dd><a name="index-g_t_002d_002dinfodir_003d_0040var_007bdir_007d-1338"></a>Same as ‘<samp><span class="samp">--info-dir</span></samp>’. - - <br><dt><code>--item=</code><var>text</var><dd><a name="index-g_t_002d_002ditem_003d_0040var_007btext_007d-1339"></a>Same as ‘<samp><span class="samp">--entry=</span><var>text</var></samp>’. An Info directory entry is actually -a menu item. - - <br><dt><code>--keep-old</code><dd><a name="index-g_t_002d_002dkeep_002dold-1340"></a>Do not replace pre-existing menu entries. When ‘<samp><span class="samp">--remove</span></samp>’ is specified, -this option means that empty sections are not removed. - - <br><dt><code>--max-width=</code><var>column</var><dd><a name="index-g_t_002d_002dmax_002dwidth_003d_0040var_007bcolumn_007d-1341"></a>Specifies the column that the menu entry's description will be word-wrapped -at. <var>column</var> starts counting at 1. - - <br><dt><code>--maxwidth=</code><var>column</var><dd><a name="index-g_t_002d_002dmaxwidth_003d_0040var_007bcolumn_007d-1342"></a>Same as ‘<samp><span class="samp">--max-width</span></samp>’. - - <br><dt><code>--menuentry=</code><var>text</var><dd><a name="index-g_t_002d_002dmenuentry_003d_0040var_007btext_007d-1343"></a>Same as ‘<samp><span class="samp">--name</span></samp>’. - - <br><dt><code>--name=</code><var>text</var><dd><a name="index-g_t_002d_002dname_003d_0040var_007btext_007d-1344"></a>Specify the name portion of the menu entry. If the <var>text</var> does not start -with an asterisk ‘<samp><span class="samp">*</span></samp>’, it is presumed to be the text after the ‘<samp><span class="samp">*</span></samp>’ -and before the parentheses that specify the Info file. Otherwise <var>text</var> -is taken verbatim, and is meant to include the text up to and including the -first dot ‘<samp><span class="samp">.</span></samp>’. If you don't specify the name (either via ‘<samp><span class="samp">--entry</span></samp>’, -‘<samp><span class="samp">--item</span></samp>’ or this option), it is taken from the Info file itself. If -the Info does not contain the name, the basename of the Info file is used. - - <br><dt><code>--no-indent</code><dd><a name="index-g_t_002d_002dno_002dindent-1345"></a>Suppress formatting of new entries into the <samp><span class="file">dir</span></samp> file. - - <br><dt><code>--quiet</code><dd><a name="index-g_t_002d_002dquiet-1346"></a><dt><code>--silent</code><dd><a name="index-g_t_002d_002dsilent-1347"></a>Suppress warnings, etc., for silent operation. - - <br><dt><code>--remove</code><dd><a name="index-g_t_002d_002dremove-1348"></a>Same as ‘<samp><span class="samp">--delete</span></samp>’. - - <br><dt><code>--remove-exactly</code><dd><a name="index-g_t_002d_002dremove_002dexactly-1349"></a>Also like ‘<samp><span class="samp">--delete</span></samp>’, but only entries if the Info file name -matches exactly; <code>.info</code> and/or <code>.gz</code> suffixes are -<em>not</em> ignored. - - <br><dt><code>--section=</code><var>sec</var><dd><a name="index-g_t_002d_002dsection_003d_0040var_007bsec_007d-1350"></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. If the Info file doesn't specify -a section, the menu entries are put into the Miscellaneous section. - - <br><dt><code>--section </code><var>regex</var> <var>sec</var><dd><a name="index-g_t_002d_002dsection-_0040var_007bregex_007d-_0040var_007bsec_007d-1351"></a>Same as ‘<samp><span class="samp">--regex=</span><var>regex</var><span class="samp"> --section=</span><var>sec</var><span class="samp"> --add-once</span></samp>’. - - <p><code>install-info</code> tries to detect when this alternate syntax is used, -but does not always guess correctly! Here is the heuristic that -<code>install-info</code> uses: - <ol type=1 start=1> -<li>If the second argument to <code>--section</code> starts with a hyphen, the original syntax is presumed. -<li>If the second argument to <code>--section</code> is a file that can be opened, the original syntax is presumed -<li>Otherwise the alternate syntax is used. - </ol> - - <p>When heuristic fails because your section title starts with a hyphen, or it -happens to be a filename that can be opened, the syntax should be changed -to ‘<samp><span class="samp">--regex=</span><var>regex</var><span class="samp"> --section=</span><var>sec</var><span class="samp"> --add-once</span></samp>’. - - <br><dt><code>--regex=</code><var>regex</var><dd><a name="index-g_t_002d_002dregex_003d_0040var_007bregex_007d-1352"></a>Put this file's entries into any section that matches <var>regex</var>. If -more than one section matches, all of the entries are added in each of the -sections. Specify <var>regex</var> using basic regular expression syntax, more -or less as used with <samp><span class="command">grep</span></samp>, for example. - - <br><dt><code>--test</code><dd><a name="index-g_t_002d_002dtest-1353"></a>Suppress updating of the directory file. - - <br><dt><code>--version</code><dd><a name="index-g_t_002d_002dversion-1354"></a><a name="index-Version-number_002c-for-install_002dinfo-1355"></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> - -</div> - -<h2 class="chapter">22 Generating HTML</h2> - -<p><a name="index-HTML-output-1356"></a> -<samp><span class="command">makeinfo</span></samp> generates Info output by default, but given the -<samp><span class="option">--html</span></samp> option, it will generate HTML, for web browsers and -other programs. This chapter gives some details on such HTML output. - - <p><samp><span class="command">makeinfo</span></samp> 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> - -</div> - -<h3 class="section">22.1 HTML Translation</h3> - -<p><samp><span class="command">makeinfo</span></samp> 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 ‘<samp><span class="samp"><</span></samp>’, -‘<samp><span class="samp">></span></samp>’ and ‘<samp><span class="samp">&</span></samp>’ characters which have special significance in -HTML). See <a href="#Conditional-Commands">Conditional Commands</a>. - - <p><a name="index-g_t_002d_002dfootnote_002dstyle_0040r_007b_002c-ignored-in-HTML-output_007d-1357"></a>The <samp><span class="option">--footnote-style</span></samp> 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-1358"></a>By default, a navigation bar is inserted at the start of each node, -analogous to Info output. The ‘<samp><span class="samp">--no-headers</span></samp>’ option suppresses -this if used with ‘<samp><span class="samp">--no-split</span></samp>’. 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 1.0 feature. - - <p><a name="index-HTML-output_002c-browser-compatibility-of-1359"></a>The HTML generated is mostly standard (i.e., HTML 2.0, RFC-1866). -One exception is that HTML 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 4 ‘<samp><span class="samp">lang</span></samp>’ -attribute on the ‘<samp><span class="samp"><html></span></samp>’ 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> - -</div> - -<h3 class="section">22.2 HTML Splitting</h3> - -<p><a name="index-Split-HTML-output-1360"></a><a name="index-HTML-output_002c-split-1361"></a> -When splitting output (which is the default), <samp><span class="command">makeinfo</span></samp> -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 ‘<samp><span class="samp">-</span></samp>’'s, so it can work as a filename. In the unusual case of -two different nodes having the same name after this treatment, they -are written consecutively to the same file, with HTML anchors so each -can be referred to separately. If <samp><span class="command">makeinfo</span></samp> 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><samp><span class="command">makeinfo</span></samp> 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 ‘<samp><span class="samp">gcc</span></samp>’. - - <li>If that directory cannot be created for any reason, then -<samp><span class="command">makeinfo</span></samp> tries appending ‘<samp><span class="samp">.html</span></samp>’ to the directory name. -For example, output for <code>@setfilename texinfo</code> would be written -to ‘<samp><span class="samp">texinfo.html</span></samp>’. - - <li>If the ‘<samp><var>name</var><span class="samp">.html</span></samp>’ 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 ‘<samp><span class="samp">index.html</span></samp>’. - - <p>Monolithic output (<code>--no-split</code>) is named according to -<code>@setfilename</code> (with any ‘<samp><span class="samp">.info</span></samp>’ extension is replaced with -‘<samp><span class="samp">.html</span></samp>’) 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> - -</div> - -<h3 class="section">22.3 HTML CSS</h3> - -<p><a name="index-HTML_002c-and-CSS-1362"></a><a name="index-CSS_002c-and-HTML-output-1363"></a><a name="index-Cascading-Style-Sheets_002c-and-HTML-output-1364"></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, <samp><span class="command">makeinfo</span></samp> 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 ‘<samp><span class="samp"><pre></span></samp>’ command uses a monospaced font. - - <p>You can influence the CSS in the HTML output with two -<samp><span class="command">makeinfo</span></samp> options: <samp><span class="option">--css-include=</span><var>file</var></samp> and -<samp><span class="option">--css-ref=</span><var>url</var></samp>. - - <p>The option <samp><span class="option">--css-ref=</span><var>url</var></samp> adds to each output HTML file -a ‘<samp><span class="samp"><link></span></samp>’ tag referencing a CSS at the given <var>url</var>. This -allows using external style sheets. - - <p>The option <samp><span class="option">--css-include=</span><var>file</var></samp> 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-g_t_0040_0040import-specifications_002c-in-CSS-files-1365"></a>The CSS file may begin with so-called ‘<samp><span class="samp">@import</span></samp>’ 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 <samp><span class="command">makeinfo</span></samp> handles them. - - <p><a name="index-Comments_002c-in-CSS-files-1366"></a>There can be more than one ‘<samp><span class="samp">@import</span></samp>’, but they have to come -first in the file, with only whitespace and comments interspersed, no -normal definitions. (Technical exception: an ‘<samp><span class="samp">@charset</span></samp>’ -directive may precede the ‘<samp><span class="samp">@import</span></samp>’'s. This does not alter -<samp><span class="command">makeinfo</span></samp>'s behavior, it just copies the ‘<samp><span class="samp">@charset</span></samp>’ if -present.) Comments in CSS files are delimited by ‘<samp><span class="samp">/* ... */</span></samp>’, as -in C. An ‘<samp><span class="samp">@import</span></samp>’ 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 <samp><span class="command">makeinfo</span></samp> is concerned, the crucial characters are -the ‘<samp><span class="samp">@</span></samp>’ at the beginning and the semicolon terminating the -directive. When reading the CSS file, it simply copies any such -‘<samp><span class="samp">@</span></samp>’-directive into the output, as follows: - - <ul> -<li>If <var>file</var> contains only normal CSS declarations, it is -included after <samp><span class="command">makeinfo</span></samp>'s default CSS, thus overriding it. - - <li>If <var>file</var> begins with ‘<samp><span class="samp">@import</span></samp>’ specifications (see -below), then the ‘<samp><span class="samp">import</span></samp>’'s are included first (they have to come -first, according to the standard), and then <samp><span class="command">makeinfo</span></samp>'s -default CSS is included. If you need to override <samp><span class="command">makeinfo</span></samp>'s -defaults from an ‘<samp><span class="samp">@import</span></samp>’, you can do so with the ‘<samp><span class="samp">! -important</span></samp>’ CSS construct, as in: - <pre class="example"> pre.smallexample { font-size: inherit ! important } -</pre> - <li>If <var>file</var> contains both ‘<samp><span class="samp">@import</span></samp>’ and inline CSS -specifications, the ‘<samp><span class="samp">@import</span></samp>’'s are included first, then -<samp><span class="command">makeinfo</span></samp>'s defaults, and lastly the inline CSS from -<var>file</var>. - - <li>Any @-directive other than ‘<samp><span class="samp">@import</span></samp>’ and ‘<samp><span class="samp">@charset</span></samp>’ -is treated as a CSS declaration, meaning <samp><span class="command">makeinfo</span></samp> includes -its default CSS and then the rest of the file. - - </ul> - - <p>If the CSS file is malformed or erroneous, <samp><span class="command">makeinfo</span></samp>'s output -is unspecified. <samp><span class="command">makeinfo</span></samp> does not try to interpret the -meaning of the CSS file in any way; it just looks for the special -‘<samp><span class="samp">@</span></samp>’ and ‘<samp><span class="samp">;</span></samp>’ 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> - -</div> - -<h3 class="section">22.4 HTML Cross-references</h3> - -<p><a name="index-HTML-cross_002dreferences-1367"></a><a name="index-Cross_002dreferences_002c-in-HTML-output-1368"></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 -<samp><span class="command">texi2html</span></samp>, 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-1369"></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> - -</div> - -<h4 class="subsection">22.4.1 HTML Cross-reference Link Basics</h4> - -<p><a name="index-HTML-cross_002dreference-link-basics-1370"></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 ‘<samp><span class="samp">localhost</span></samp>’, or, according to the rules for -HTML links, the ‘<samp><span class="samp">http://localhost/</span></samp>’ 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 a given -<var>manual</var> is either available as a monolithic file -<samp><var>manual</var><span class="file">.html</span></samp>, or a split subdirectory -<samp><var>manual</var><span class="file">/*.html</span></samp>. Here are the cases: - - <ul> -<li>If the present manual is split, and the referent manual is also split, -the directory is ‘<samp><span class="samp">../</span><var>referent/</var></samp>’ 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 ‘<samp><span class="samp">../</span></samp>’ and the file is <samp><var>referent</var><span class="file">.html</span></samp>. - - <li>If the present manual is mono, and the referent manual is split, the -directory is <samp><var>referent</var><span class="file">/</span></samp> 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 <samp><span class="file">./</span></samp> (or just the empty string), and the file is -<samp><var>referent</var><span class="file">.html</span></samp>. - - </ul> - - <p>One exception: the algorithm for node name expansion prefixes the -string ‘<samp><span class="samp">g_t</span></samp>’ when the node name begins with a non-letter. This -kludge (due to XHTML rules) is not necessary for filenames, and is -therefore omitted. - - <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 ‘<samp><span class="samp">foo</span></samp>’ 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; <samp><span class="command">makeinfo</span></samp> defaults to split, with the -<samp><span class="option">--no-split</span></samp> option overriding this. - - <p>Whether the referent manual is split or mono is another bit of the -external information. For now, <samp><span class="command">makeinfo</span></samp> 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> - -</div> - -<h4 class="subsection">22.4.2 HTML Cross-reference Node Name Expansion</h4> - -<p><a name="index-HTML-cross_002dreference-node-name-expansion-1371"></a><a name="index-node-name-expansion_002c-in-HTML-cross_002dreferences-1372"></a><a name="index-expansion_002c-of-node-names-in-HTML-cross_002dreferences-1373"></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 XHTML identifiers and -filenames. The restrictions are similar for each: plain ASCII -letters, numbers, and the ‘<samp><span class="samp">-</span></samp>’ and ‘<samp><span class="samp">_</span></samp>’ characters are all -that can be used. (Although HTML anchors can contain most characters, -XHTML is more restrictive.) - - <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 -<samp><span class="command">makeinfo</span></samp> 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 <samp><span class="file">index.html</span></samp>, to match web server software. -However, the HTML <em>target</em> is ‘<samp><span class="samp">Top</span></samp>’. 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) are not modified. All other -characters are changed as specified below. - - <li>The standard ASCII numbers (0-9) are not modified except when a number -is the first character of the node name. In that case, see below. - - <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 ‘<samp><span class="samp">-</span></samp>’ character. - - <li>Other ASCII 7-bit characters are transformed into ‘<samp><span class="samp">_00</span><var>xx</var></samp>’, -where <var>xx</var> is the ASCII character code in (lowercase) hexadecimal. -This includes ‘<samp><span class="samp">_</span></samp>’, which is mapped to ‘<samp><span class="samp">_005f</span></samp>’. - - <li>If the node name does not begin with a letter, the literal string -‘<samp><span class="samp">g_t</span></samp>’ is prefixed to the result. (Due to the rules above, that -string can never occur otherwise; it is an arbitrary choice, standing -for “GNU Texinfo”.) This is necessary because XHTML requires that -identifiers begin with a letter. - - </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>‘<samp><span class="samp">_</span></samp>’ ⇒ ‘<samp><span class="samp">_005f</span></samp>’ -<li>‘<samp><span class="samp">-</span></samp>’ ⇒ ‘<samp><span class="samp">_002d</span></samp>’ -<li>‘<samp><span class="samp">A node</span></samp>’ ⇒ ‘<samp><span class="samp">A-node</span></samp>’ -</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 -<samp><span class="file">index.html</span></samp>. Thus, on a case-folding system, Top and a node -named `Index' will both be written to <samp><span class="file">index.html</span></samp>. - - <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> - -</div> - -<h4 class="subsection">22.4.3 HTML Cross-reference Command Expansion</h4> - -<p><a name="index-HTML-cross_002dreference-command-expansion-1374"></a> -In standard Texinfo, node names may not contain @-commands. -<samp><span class="command">makeinfo</span></samp> has an option <samp><span class="option">--commands-in-node-names</span></samp> -which partially supports it (see <a href="#Invoking-makeinfo">Invoking makeinfo</a>), but it is not -robust and not recommended. - - <p>Thus, <samp><span class="command">makeinfo</span></samp> 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 @slanted @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 ‘<samp><span class="samp">-</span></samp>’, 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%">‘<samp><span class="samp">!</span></samp>’ -<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%">‘<samp><span class="samp">.</span></samp>’ -<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%">‘<samp><span class="samp">?</span></samp>’ -<br></td></tr><tr align="left"><td valign="top" width="30%"><code>@@</code> </td><td valign="top" width="50%">‘<samp><span class="samp">@</span></samp>’ -<br></td></tr><tr align="left"><td valign="top" width="30%"><code>@{</code> </td><td valign="top" width="50%">‘<samp><span class="samp">{</span></samp>’ -<br></td></tr><tr align="left"><td valign="top" width="30%"><code>@}</code> </td><td valign="top" width="50%">‘<samp><span class="samp">}</span></samp>’ -<br></td></tr><tr align="left"><td valign="top" width="30%"><code>@LaTeX</code> </td><td valign="top" width="50%">‘<samp><span class="samp">LaTeX</span></samp>’ -<br></td></tr><tr align="left"><td valign="top" width="30%"><code>@TeX</code> </td><td valign="top" width="50%">‘<samp><span class="samp">TeX</span></samp>’ -<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%">‘<samp><span class="samp">,</span></samp>’ -<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%">‘<samp><span class="samp">...</span></samp>’ -<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%">‘<samp><span class="samp">error--></span></samp>’ -<br></td></tr><tr align="left"><td valign="top" width="30%"><code>@euro</code> </td><td valign="top" width="50%">U+20AC -<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+2605 -<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%">U+22A3 -<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> or <code>@abbr</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-bit-Character-Expansion"></a> -<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> - -</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-1375"></a><a name="index-g_t8_002dbit-characters_002c-in-HTML-cross_002dreferences-1376"></a><a name="index-Expansion-of-8_002dbit-characters-in-HTML-cross_002dreferences-1377"></a><a name="index-Transliteration-of-8_002dbit-characters-in-HTML-cross_002dreferences-1378"></a> -Usually, characters other than plain 7-bit ASCII are transformed into -the corresponding Unicode code point(s) in Normalization Form C, which -uses precomposed characters where available. (This is the -normalization form recommended by the W3C and other bodies.) This -holds when that code point is 0xffff or less, as it almost always is. - - <p>These will then be further transformed by the rules above into the -string ‘<samp><span class="samp">_</span><var>xxxx</var></samp>’, 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) <code>@enddots</code> expands to three periods which in -turn expands to three ‘<samp><span class="samp">_002e</span></samp>’'s; 2) <code>@u{B}</code> is a `B' -with a breve accent, which does not exist as a pre-accented Unicode -character, therefore expands to ‘<samp><span class="samp">B_0306</span></samp>’ (B with combining -breve). - - <p>When the Unicode code point is above 0xffff, the transformation is -‘<samp><span class="samp">__</span><var>xxxxxx</var></samp>’, that is, two leading underscores followed by -six hex digits. Since Unicode has declared that their highest code -point is 0x10ffff, this is sufficient. (We felt it was better to -define this extra escape than to always use six hex digits, since the -first two would nearly always be zeros.) - - <p>This method works fine if the node name consists mostly of ASCII -characters and contains only few 8-bit ones. If the document is -written in a language whose script is not based on the Latin alphabet -(such as, e.g. Ukrainian), it will create file names consisting -entirely of ‘<samp><span class="samp">_</span><var>xxxx</var></samp>’ notations, which is inconvenient. - - <p>To handle such cases, <samp><span class="command">makeinfo</span></samp> offers -<samp><span class="option">--transliterate-file-names</span></samp> command line option. This option -enables <dfn>transliteration</dfn> of node names into ASCII characters for -the purposes of file name creation and referencing. The -transliteration is based on phonetic principle, which makes the -produced file names easily readable. - - <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> - -</div> - -<h4 class="subsection">22.4.5 HTML Cross-reference Mismatch</h4> - -<p><a name="index-HTML-cross_002dreference-mismatch-1379"></a><a name="index-Mismatched-HTML-cross_002dreference-source-and-target-1380"></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 -<samp><span class="file">manual/</span></samp> subdirectory full of HTML files which redirect back to -the monolithic <samp><span class="file">manual.html</span></samp>. 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 -<samp><span class="file">manual.html</span></samp> to the different <samp><span class="file">manual/node.html</span></samp> 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 <samp><span class="file">manual.html</span></samp>: - -<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> - -</div> - -<h2 class="appendix">Appendix A @-Command List</h2> - -<p><a name="index-Alphabetical-_0040_0040_002dcommand-list-1381"></a><a name="index-List-of--_0040_0040_002dcommands-1382"></a><a name="index-g_t_0040_0040_002dcommand-list-1383"></a><a name="index-Reference-to-_0040_0040_002dcommands-1384"></a> -Here is an alphabetical list of the @-commands in Texinfo. Square -brackets, <tt>[</tt> <!-- /@w --><tt>]</tt>, indicate optional arguments; an ellipsis, -‘<samp><span class="samp">...</span></samp>’, 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="#g_t_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>Tell TeX to refrain from inserting extra whitespace after an -immediately preceding period, question mark, exclamation mark, or -colon, as TeX normally would. 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, ‘<samp><span class="samp">@</span></samp>’. -See <a href="#Atsign-Braces-Comma">Inserting @ and {} and ,</a>. - - <br><dt><code>@\</code><dd>Stands for a backslash (‘<samp><span class="samp">\</span></samp>’) 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, ‘<samp><span class="samp">{</span></samp>’. -See <a href="#Atsign-Braces-Comma">Inserting @ and {} and ,</a>. - - <br><dt><code>@}</code><dd>Stands for a right-hand brace, ‘<samp><span class="samp">}</span></samp>’.<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>@abbr{</code><var>abbreviation</var><code>}</code><dd>Tag <var>abbreviation</var> as an abbreviation, such as `Comput.'. -See <a href="#abbr"><code>abbr</code></a>. - - <br><dt><code>@acronym{</code><var>acronym</var><code>}</code><dd>Tag <var>acronym</var> as an acronym, 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 ‘<samp><span class="samp">@</span><var>new</var></samp>’ an alias for the existing command -‘<samp><span class="samp">@</span><var>existing</var></samp>’. 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>@arrow{}</code><dd>Produce a normal right arrow glyph: ‘<samp><span class="samp">→</span></samp>’. Used by default -for <code>@click</code>. See <a href="#Click-Sequences">Click Sequences</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">Two-column Tables</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>@click{}</code><dd>Represent a single “click” in a GUI. Used within -<code>@clicksequence</code>. See <a href="#Click-Sequences">Click Sequences</a>. - - <br><dt><code>@clicksequence{</code><var>action</var><code> @click{} </code><var>action</var><code>}</code><dd>Represent a sequence of clicks in a GUI. See <a href="#Click-Sequences">Click Sequences</a>. - - <br><dt><code>@clickstyle @</code><var>cmd</var><dd>Execute @<var>cmd</var> for each <code>@click</code>; the default is -<code>@arrow</code>. The usual following empty braces on @<var>cmd</var> are -omitted. See <a href="#Click-Sequences">Click Sequences</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 <samp><span class="command">ls</span></samp>. -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 ‘<samp><span class="samp">@defcv -{Instance Variable} ...</span></samp>’. 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 -‘<samp><span class="samp">@deffn Macro ...</span></samp>’. 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 ‘<samp><span class="samp">@defop Method ...</span></samp>’. 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 -‘<samp><span class="samp">@defvr {User Option} ...</span></samp>’. 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 -‘<samp><span class="samp">@deffn {Special Form} ...</span></samp>’. 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 ‘<samp><span class="samp">int</span></samp>’ or -‘<samp><span class="samp">float</span></samp>’), 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 ‘<samp><span class="samp">@deftypefn Function ...</span></samp>’. -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 ‘<samp><span class="samp">@deftypevr Variable ...</span></samp>’. 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 -‘<samp><span class="samp">@deffn Function ...</span></samp>’. 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 -‘<samp><span class="samp">@defvr Variable ...</span></samp>’. 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: ‘<samp><span class="samp">...</span></samp>’. -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 ‘<samp><span class="samp">@end example</span></samp>’. 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 <samp><span class="env">PATH</span></samp>. -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: ‘<samp><span class="samp">==</span></samp>’. See <a href="#Equivalence">Equivalence</a>. - - <br><dt><code>@euro{}</code><dd>Generate the Euro currency sign. -See <a href="#euro"><code>@euro{}</code></a>. - - <br><dt><code>@error{}</code><dd>Indicate to the reader with a glyph that the following text is -an error message: ‘<samp><span class="samp">error--></span></samp>’. 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: ‘<samp><span class="samp">==></span></samp>’. -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 ‘<samp><span class="samp">end</span></samp>’ for the end -node style or ‘<samp><span class="samp">separate</span></samp>’ 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>@geq{}</code><dd>Generate a greater-than-or-equal sign, `≥'. See <a href="#geq-leq">geq leq</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="#g_t_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 -‘<samp><var>filename</var><span class="samp">.</span><var>ext</var></samp>’ 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 -<samp><span class="file">texinfo</span></samp> 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>@leq{}</code><dd>Generate a less-than-or-equal sign, `≤'. See <a href="#geq-leq">geq leq</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 <samp><span class="option">-l</span></samp> or <samp><span class="option">--help</span></samp>. -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: ‘<samp><span class="samp">-!-</span></samp>’. 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: -‘<samp><span class="samp">-|</span></samp>’. 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: ‘<samp><span class="samp">⇒</span></samp>’. 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>@sansserif{</code><var>text</var><code>}</code><dd>Print <var>text</var> in a <span class="sansserif">sans serif</span> font if possible. No -effect in Info. See <a href="#Fonts">Fonts</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 ‘<samp><span class="samp">@end titlepage</span></samp>’ 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 ‘<samp><span class="samp">@end titlepage</span></samp>’ -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 ‘<samp><span class="samp"><head></span></samp>’. -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>@slanted{</code><var>text</var><code>}</code><dd>Print <var>text</var> in a <i>slanted</i> font if possible. No effect -in Info. See <a href="#Fonts">Fonts</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>@thischapternum</code><dt><code>@thisfile</code><dt><code>@thispage</code><dt><code>@thistitle</code><dd>Only allowed in a heading or footing. Stands for, respectively, the -number and name of the current chapter (in the format `Chapter 1: -Title'), the current chapter name only, the current chapter number -only, the filename, the current page number, and the title of the -document, respectively. 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 ‘<samp><span class="samp">0pt plus -1filll</span></samp>’. (Note spelling of ‘<samp><span class="samp">filll</span></samp>’.) <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> - -</div> - -<h3 class="section">A.1 @-Command Syntax</h3> - -<p><a name="index-g_t_0040_0040_002dcommand-syntax-1385"></a><a name="index-Syntax_002c-of-_0040_0040_002dcommands-1386"></a><a name="index-Command-syntax-1387"></a> -The character ‘<samp><span class="samp">@</span></samp>’ is used to start special Texinfo commands. -(It has the same meaning that ‘<samp><span class="samp">\</span></samp>’ 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. The -non-alphabetic commands include <code>@@</code>, <code>@{</code>, <code>@}</code>, -<code>@.</code>, <code>@</code><kbd>SPACE</kbd>, most of the accent commands, and -many more. - - <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> ⇒ ‘<samp><span class="samp">...</span></samp>’, <code>@equiv{}</code> -⇒ ‘<samp><span class="samp">==</span></samp>’, <code>@TeX{}</code> ⇒ `TeX', -and <code>@bullet{}</code> ⇒ ‘<samp><span class="samp">•</span></samp>’. - - <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: ‘<samp><span class="samp">In -Texinfo, @@-commands are @dfn{mark-up} commands.</span></samp>’ - - <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-1388"></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> - -</div> - -<h2 class="appendix">Appendix B Tips and Hints</h2> - -<p>Here are some tips for writing Texinfo documentation: - - <p><a name="index-Tips-1389"></a><a name="index-Usage-tips-1390"></a><a name="index-Hints-1391"></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—‘<samp><span class="samp">Lazy dog</span></samp>’, and ‘<samp><span class="samp">Dog, lazy</span></samp>’—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 ‘<samp><span class="samp">x</span></samp>’ or -‘<samp><span class="samp">i</span></samp>’ in upper case. - - <li>Capitalize “Info”; it is a name. - - <li>Write TeX using the <code>@TeX{}</code> command. Note the uppercase -‘<samp><span class="samp">T</span></samp>’ and ‘<samp><span class="samp">X</span></samp>’. 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 ‘<samp><span class="samp">---</span></samp>’</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 ‘<samp><span class="samp">s</span></samp>’ immediately after an -‘<samp><span class="samp">@code</span></samp>’. 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, ‘<samp><span class="samp">---</span></samp>’, 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, ‘<samp><span class="samp">au</span></samp>’ is an abbreviation for ``author''. -</pre> - <p class="noindent">since ‘<samp><span class="samp">au</span></samp>’ does <em>not</em> serve as an abbreviation for -‘<samp><span class="samp">author.</span></samp>’ (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 ‘<samp><span class="samp">X</span></samp>’ 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> - -</div> - -<h2 class="appendix">Appendix C Sample Texinfo Files</h2> - -<p><a name="index-Sample-Texinfo-files-1392"></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> - -</div> - -<h3 class="section">C.1 Short Sample</h3> - -<p><a name="index-Sample-Texinfo-file_002c-no-comments-1393"></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 <samp><span class="command">makeinfo</span></samp> 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 © 2005 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> - -</div> - -<h3 class="section">C.2 GNU Sample Texts</h3> - -<p><a name="index-GNU-sample-texts-1394"></a><a name="index-Sample-texts_002c-GNU-1395"></a><a name="index-Full-texts_002c-GNU-1396"></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-g_t_0024Id-1397"></a><a name="index-CVS-_0024Id-1398"></a><a name="index-RCS-_0024Id-1399"></a><a name="index-Documentation-identification-1400"></a><a name="index-Identification-of-documentation-1401"></a>The ‘<samp><span class="samp">$Id:</span></samp>’ comment is for the CVS (see <a href="cvs.html#Top">Overview</a>) or RCS -(<a href="http://www.gnu.org/software/rcs">http://www.gnu.org/software/rcs</a>) version control systems, which -expand it into a string such as: - <pre class="example"> $Id: texinfo.txi,v 1.220 2008/04/09 17:07:31 karl Exp $ -</pre> - <p>(This is useful in all sources that use version control, not just manuals.) -You may wish to include the ‘<samp><span class="samp">$Id:</span></samp>’ 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-1402"></a><a name="index-UPDATED-_0040r_007bAutomake-variable_007d-1403"></a><a name="index-VERSION-_0040r_007bAutomake-variable_007d-1404"></a><a name="index-time_002dstamp_002eel-1405"></a>The <samp><span class="file">version.texi</span></samp> in the <code>@include</code> command is maintained -automatically by Automake (see <a href="automake.html#Top">Introduction</a>). It sets the ‘<samp><span class="samp">VERSION</span></samp>’ and ‘<samp><span class="samp">UPDATED</span></samp>’ 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</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</a>. - - <li><a name="index-GNU-Free-Documentation-License_002c-including-entire-1406"></a><a name="index-Free-Documentation-License_002c-including-entire-1407"></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 <samp><span class="file">fdl.texi</span></samp> 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 the FSF is not the copyright holder, then use the appropriate name. - - <li>If your manual is not published on paper by the FSF, then omit the -last sentence in the Back-Cover Text that talks about copies from GNU -Press. - - <li>If your manual has Invariant Sections (again, see the license itself -for details), then 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.220 2008/04/09 17:07:31 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{} 2007 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.2 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,'' -and with the Back-Cover Texts as in (a) below. A copy of the -license is included in the section entitled ``GNU Free Documentation -License.'' - -(a) The FSF's Back-Cover Text is: ``You have the freedom to -copy and modify this GNU manual. Buying copies from the FSF -supports it in developing GNU and promoting software freedom.'' -@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 - -This manual is for GNU Sample (version @value{VERSION}, @value{UPDATED}). -@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 GNU Free Documentation License -@appendix GNU Free Documentation License - -@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> - -</div> - -<h3 class="section">C.3 Verbatim Copying License</h3> - -<p><a name="index-Verbatim-copying-license-1408"></a><a name="index-License-for-verbatim-copying-1409"></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{} 2005 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-permissive-Copying-License"></a> -<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> - -</div> - -<h3 class="section">C.4 All-permissive Copying License</h3> - -<p><a name="index-All_002dpermissive-copying-license-1410"></a><a name="index-License-for-all_002dpermissive-copying-1411"></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 © 2005 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> - -</div> - -<h2 class="appendix">Appendix D Include Files</h2> - -<p><a name="index-Include-files-1412"></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> - -</div> - -<h3 class="section">D.1 How to Use Include Files</h3> - -<p><a name="index-include-1413"></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 ‘<samp><span class="samp">\input texinfo</span></samp>’; 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-multiple-files-update"></a> -<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> - -</div> - -<h3 class="section">D.2 <code>texinfo-multiple-files-update</code></h3> - -<p><a name="index-texinfo_002dmultiple_002dfiles_002dupdate-1414"></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> - -</div> - -<h3 class="section">D.3 Include Files Requirements</h3> - -<p><a name="index-Include-files-requirements-1415"></a><a name="index-Requirements-for-include-files-1416"></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> - -</div> - -<h3 class="section">D.4 Sample File with <code>@include</code></h3> - -<p><a name="index-Sample-_0040code_007b_0040_0040include_007d-file-1417"></a><a name="index-Include-file-sample-1418"></a><a name="index-g_t_0040code_007b_0040_0040include_007d-file-sample-1419"></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 <samp><span class="file">foo.texinfo</span></samp>, might look like this: - -<pre class="example"> @node First - @chapter First Chapter - - Contents of first chapter ... -</pre> - <p>The full contents of <samp><span class="file">concept-index.texinfo</span></samp> 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 <samp><span class="file">elisp.texi</span></samp>. 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> - -</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> - -</div> - -<h2 class="appendix">Appendix E Page Headings</h2> - -<p><a name="index-Headings-1420"></a><a name="index-Footings-1421"></a><a name="index-Page-numbering-1422"></a><a name="index-Page-headings-1423"></a><a name="index-Formatting-headings-and-footings-1424"></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> - -</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> - -</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> - -</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> - -</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 ‘<samp><span class="samp">@|</span></samp>’ 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: - - <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><a name="index-everyheading-1425"></a><a name="index-everyfooting-1426"></a>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. - - <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><a name="index-evenheading-1427"></a><a name="index-evenfooting-1428"></a><a name="index-oddheading-1429"></a><a name="index-oddfooting-1430"></a>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 ‘<samp><span class="samp">@this...</span></samp>’ series of @-commands to -provide the names of chapters -and sections and the page number. You can use the -‘<samp><span class="samp">@this...</span></samp>’ 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 ‘<samp><span class="samp">@this...</span></samp>’ commands: - - <dl> -<dt><code>@thispage</code><dd><a name="index-thispage-1431"></a>Expands to the current page number. - - <br><dt><code>@thissectionname</code><dd><a name="index-thissectionname-1432"></a>Expands to the name of the current section. - - <br><dt><code>@thissectionnum</code><dd><a name="index-thissectionnum-1433"></a>Expands to the number of the current section. - - <br><dt><code>@thissection</code><dd><a name="index-thissection-1434"></a>Expands to the number and name of the current section, in the format -`Section 1: Title'. - - <br><dt><code>@thischaptername</code><dd><a name="index-thischaptername-1435"></a>Expands to the name of the current chapter. - - <br><dt><code>@thischapternum</code><dd><a name="index-thischapternum-1436"></a>Expands to the number of the current chapter, or letter of the current -appendix. - - <br><dt><code>@thischapter</code><dd><a name="index-thischapter-1437"></a>Expands to the number and name of the current -chapter, in the format `Chapter 1: Title'. - - <br><dt><code>@thistitle</code><dd><a name="index-thistitle-1438"></a>Expands to the name of the document, as specified by the -<code>@settitle</code> command. - - <br><dt><code>@thisfile</code><dd><a name="index-thisfile-1439"></a>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-1440"></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. - - <p>If you have very short chapters and/or sections, several of them can -appear on a single page. You can specify which chapters and sections -you want <code>@thischapter</code>, <code>@thissection</code> and other such -macros to refer to on such pages as follows: - - <dl> -<dt><code>@everyheadingmarks </code><var>ref</var><dt><code>@everyfootingmarks </code><var>ref</var><dd><a name="index-everyheadingmarks-1441"></a><a name="index-everyfootingmarks-1442"></a>The <var>ref</var> argument can be either <code>top</code> (the <code>@this...</code> -commands will refer to the chapter/section at the top of a page) or -<code>bottom</code> (the commands will reflect the situation at the bottom -of a page). These ‘<samp><span class="samp">@every...</span></samp>’ commands specify what to do on -both even- and odd-numbered pages. - - <br><dt><code>@evenheadingmarks </code><var>ref</var><dt><code>@oddheadingmarks </code><var>ref</var><dt><code>@evenfootingmarks </code><var>ref</var><dt><code>@oddfootingmarks </code><var>ref</var><dd><a name="index-evenheadingmarks-1443"></a><a name="index-oddheadingmarks-1444"></a><a name="index-evenfootingmarks-1445"></a><a name="index-oddfootingmarks-1446"></a>These ‘<samp><span class="samp">@even...</span></samp>’ and ‘<samp><span class="samp">@odd...</span></samp>’ commands specify what to do -on only even- or odd-numbered pages, respectively. The <var>ref</var> -argument is the same as with the ‘<samp><span class="samp">@every...</span></samp>’ commands. -</dl> - - <p>Write these commands immediately after the <code>@...contents</code> -commands, or after the <code>@end titlepage</code> command if you don't -have a table of contents or if it is printed at the end of your -manual. - - <p>By default the <code>@this...</code> commands reflect the situation at the -bottom of a page both in headings and in footings. - -<div class="node"> -<p><hr> -<a name="Catching-Mistakes"></a> -Next: <a rel="next" accesskey="n" href="#GNU-Free-Documentation-License">GNU Free Documentation License</a>, -Previous: <a rel="previous" accesskey="p" href="#Headings">Headings</a>, -Up: <a rel="up" accesskey="u" href="#Top">Top</a> - -</div> - -<h2 class="appendix">Appendix F Formatting Mistakes</h2> - -<p><a name="index-Structure_002c-catching-mistakes-in-1447"></a><a name="index-Nodes_002c-catching-mistakes-1448"></a><a name="index-Catching-mistakes-1449"></a><a name="index-Correcting-mistakes-1450"></a><a name="index-Mistakes_002c-catching-1451"></a><a name="index-Problems_002c-catching-1452"></a><a name="index-Debugging-the-Texinfo-structure-1453"></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> - -</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> - -</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-1454"></a><a name="index-Debugging-with-Info-formatting-1455"></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 ‘<samp><span class="samp">*Info Region*</span></samp>’ 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 ‘<samp><span class="samp">Unbalanced parentheses</span></samp>’ -rather than ‘<samp><span class="samp">Unbalanced braces</span></samp>’. 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> - -</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-1456"></a><a name="index-Debugging-with-_0040TeX_007b_007d-formatting-1457"></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">‘<samp><span class="samp">@par</span></samp>’ is an internal TeX command of no relevance to Texinfo. -‘<samp><span class="samp">l.27</span></samp>’ means that TeX detected the problem on line 27 of the -Texinfo file. The ‘<samp><span class="samp">?</span></samp>’ 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 ‘<samp><span class="samp">?</span></samp>’ 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 ‘<samp><span class="samp">?</span></samp>’ 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 ‘<samp><span class="samp">?</span></samp>’ 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 ‘<samp><span class="samp">?</span></samp>’ 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 ‘<samp><span class="samp">*</span></samp>’ 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, ‘<samp><span class="samp">\</span></samp>’. TeX uses ‘<samp><span class="samp">\</span></samp>’ -instead of ‘<samp><span class="samp">@</span></samp>’; and in this circumstance, you are working -directly with TeX, not with Texinfo.) - -<div class="node"> -<p><hr> -<a name="Using-texinfo-show-structure"></a> -<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> - -</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-1458"></a><a name="index-texinfo_002dshow_002dstructure-1459"></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 ‘<samp><span class="samp">*Occur*</span></samp>’ 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 <samp><span class="file">texinfo.texi</span></samp> begin -with the <code>@section</code>, <code>@subheading</code>, and <code>@subsection</code> -commands respectively. If you move your cursor into the ‘<samp><span class="samp">*Occur*</span></samp>’ -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</a>, for more -information about <code>occur-mode-goto-occurrence</code>. - - <p>The first line in the ‘<samp><span class="samp">*Occur*</span></samp>’ 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</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</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 ‘<samp><span class="samp">*Occur*</span></samp>’ 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> - -</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-1460"></a><a name="index-occur-1461"></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</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 -‘<samp><span class="samp">@chapter</span></samp>’ in them, just type ‘<samp><span class="samp">@chapter</span></samp>’. This will -produce a list of the chapters. It will also list all the sentences -with ‘<samp><span class="samp">@chapter</span></samp>’ in the middle of the line. - - <p>If you want to see only those lines that start with the word -‘<samp><span class="samp">@chapter</span></samp>’, type ‘<samp><span class="samp">^@chapter</span></samp>’ 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 ‘<samp><span class="samp">$</span></samp>’; for example, -‘<samp><span class="samp">catching mistakes$</span></samp>’. 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</a>, -for more information. - -<div class="node"> -<p><hr> -<a name="Running-Info-Validate"></a> -<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> - -</div> - -<!-- node-name, next, previous, up --> -<h3 class="section">F.6 Finding Badly Referenced Nodes</h3> - -<p><a name="index-Info_002dvalidate-1462"></a><a name="index-Nodes_002c-checking-for-badly-referenced-1463"></a><a name="index-Checking-for-badly-referenced-nodes-1464"></a><a name="index-Looking-for-badly-referenced-nodes-1465"></a><a name="index-Finding-badly-referenced-nodes-1466"></a><a name="index-Badly-referenced-nodes-1467"></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-validate"></a> -<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> - -</div> - -<h4 class="subsection">F.6.1 Running <code>Info-validate</code></h4> - -<p><a name="index-Running-_0040code_007bInfo_002dvalidate_007d-1468"></a><a name="index-Info-validating-a-large-file-1469"></a><a name="index-Validating-a-large-file-1470"></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 ‘<samp><span class="samp">*problems in -info file*</span></samp>’. - - <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 ‘<samp><span class="samp">Overview</span></samp>’ 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 ‘<samp><span class="samp">Texinfo Mode</span></samp>’ 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> - -</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-1471"></a><a name="index-Unsplit-file-creation-1472"></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-1473"></a><a name="index-Tag-table_002c-making-manually-1474"></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> - -</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 ‘<samp><span class="samp">I</span></samp>’ 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 ‘<samp><span class="samp">I</span></samp>’ 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> - -</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-1475"></a><a name="index-Info-file_002c-splitting-manually-1476"></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 ‘<samp><span class="samp">I</span></samp>’ in ‘<samp><span class="samp">Info</span></samp>’ 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 ‘<samp><span class="samp">-</span></samp>’ 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="GNU-Free-Documentation-License"></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> - -</div> - -<h2 class="appendix">Appendix G GNU Free Documentation License</h2> - -<!-- The GNU Free Documentation License. --> -<div align="center">Version 1.2, November 2002</div> - -<!-- This file is intended to be included within another document, --> -<!-- hence no sectioning command or @node. --> -<pre class="display"> Copyright © 2000,2001,2002 Free Software Foundation, Inc. - 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, 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> - -<h3 class="heading">ADDENDUM: How to use this License for your documents</h3> - -<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<small class="dots">...</small>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="#General-Index">General Index</a>, -Previous: <a rel="previous" accesskey="p" href="#GNU-Free-Documentation-License">GNU Free Documentation License</a>, -Up: <a rel="up" accesskey="u" href="#Top">Top</a> - -</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 ‘<samp><span class="samp">@</span></samp>’. - - - -<ul class="index-fn" compact> -<li><a href="#index-g_t_0021-_0040r_007b_0028end-of-sentence_0029_007d-667"><code>! </code><span class="roman">(end of sentence)</span></a>: <a href="#Ending-a-Sentence">Ending a Sentence</a></li> -<li><a href="#index-g_t_0022-_0040r_007b_0028umlaut-accent_0029_007d-687"><code>" </code><span class="roman">(umlaut accent)</span></a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-g_t_0027-_0040r_007b_0028umlaut-accent_0029_007d-689"><code>' </code><span class="roman">(umlaut accent)</span></a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-g_t_002a-_0040r_007b_0028force-line-break_0029_007d-893"><code>* </code><span class="roman">(force line break)</span></a>: <a href="#Line-Breaks">Line Breaks</a></li> -<li><a href="#index-g_t_002c-_0040r_007b_0028cedilla-accent_0029_007d-699"><code>, </code><span class="roman">(cedilla accent)</span></a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-g_t_002d-_0040r_007b_0028discretionary-hyphen_0029_007d-899"><code>- </code><span class="roman">(discretionary hyphen)</span></a>: <a href="#g_t_002d-and-hyphenation">- and hyphenation</a></li> -<li><a href="#index-g_t_002d-_0028in-image-alt-string_0029-587"><code>- (in image alt string)</code></a>: <a href="#Image-Syntax">Image Syntax</a></li> -<li><a href="#index-g_t_002e--_0040r_007b_0028end-of-sentence_0029_007d-666"><code>. </code><span class="roman">(end of sentence)</span></a>: <a href="#Ending-a-Sentence">Ending a Sentence</a></li> -<li><a href="#index-g_t_002f-_0040r_007b_0028allow-line-break_0029_007d-894"><code>/ </code><span class="roman">(allow line break)</span></a>: <a href="#Line-Breaks">Line Breaks</a></li> -<li><a href="#index-g_t_003ccolon_003e-_0040r_007b_0028suppress-end_002dof_002dsentence-space_0029_007d-663"><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-g_t_003cnewline_003e-674"><code><newline></code></a>: <a href="#Multiple-Spaces">Multiple Spaces</a></li> -<li><a href="#index-g_t_003cspace_003e-672"><code><space></code></a>: <a href="#Multiple-Spaces">Multiple Spaces</a></li> -<li><a href="#index-g_t_003ctab_003e-673"><code><tab></code></a>: <a href="#Multiple-Spaces">Multiple Spaces</a></li> -<li><a href="#index-g_t_003d-_0040r_007b_0028macron-accent_0029_007d-691"><code>= </code><span class="roman">(macron accent)</span></a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-g_t_003f-_0040r_007b_0028end-of-sentence_0029_007d-668"><code>? </code><span class="roman">(end of sentence)</span></a>: <a href="#Ending-a-Sentence">Ending a Sentence</a></li> -<li><a href="#index-g_t_0040_0040-_0040r_007b_0028literal-_0040samp_007b_0040_0040_007d_0029_007d-649"><code>@ </code><span class="roman">(literal ‘</span><samp><span class="samp">@</span></samp><span class="roman">’)</span></a>: <a href="#Inserting-an-Atsign">Inserting an Atsign</a></li> -<li><a href="#index-g_t_005c-_0040r_007b_0028literal-_005c-in-_0040code_007b_0040_0040math_007d_0029_007d-859"><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-g_t_005cemergencystretch-1167"><code>\emergencystretch</code></a>: <a href="#Overfull-hboxes">Overfull hboxes</a></li> -<li><a href="#index-g_t_005cgdef-_0040r_007bwithin-_0040code_007b_0040_0040tex_007d_007d-1017"><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-g_t_005cinput-_0040r_007b_0028raw-_0040TeX_007b_007d-startup_0029_007d-73"><code>\input </code><span class="roman">(raw TeX startup)</span></a>: <a href="#Minimum">Minimum</a></li> -<li><a href="#index-g_t_005cmag-_0040r_007b_0028raw-_0040TeX_007b_007d-magnification_0029_007d-1198"><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-g_t_005e-_0040r_007b_0028circumflex-accent_0029_007d-693"><code>^ </code><span class="roman">(circumflex accent)</span></a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-g_t_0060-_0040r_007b_0028grave-accent_0029_007d-695"><code>` </code><span class="roman">(grave accent)</span></a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-AA-725"><code>AA</code></a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-aa-723"><code>aa</code></a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-abbr-432"><code>abbr</code></a>: <a href="#abbr">abbr</a></li> -<li><a href="#index-acronym-435"><code>acronym</code></a>: <a href="#acronym">acronym</a></li> -<li><a href="#index-AE-729"><code>AE</code></a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-ae-727"><code>ae</code></a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-afourlatex-1183"><code>afourlatex</code></a>: <a href="#A4-Paper">A4 Paper</a></li> -<li><a href="#index-afourpaper-1182"><code>afourpaper</code></a>: <a href="#A4-Paper">A4 Paper</a></li> -<li><a href="#index-afourwide-1184"><code>afourwide</code></a>: <a href="#A4-Paper">A4 Paper</a></li> -<li><a href="#index-alias-1090"><code>alias</code></a>: <a href="#alias">alias</a></li> -<li><a href="#index-allowcodebreaks-903"><code>allowcodebreaks</code></a>: <a href="#allowcodebreaks">allowcodebreaks</a></li> -<li><a href="#index-anchor-334"><code>anchor</code></a>: <a href="#anchor">anchor</a></li> -<li><a href="#index-appendix-275"><code>appendix</code></a>: <a href="#unnumbered-_0026-appendix">unnumbered & appendix</a></li> -<li><a href="#index-appendixsec-280"><code>appendixsec</code></a>: <a href="#unnumberedsec-appendixsec-heading">unnumberedsec appendixsec heading</a></li> -<li><a href="#index-appendixsection-282"><code>appendixsection</code></a>: <a href="#unnumberedsec-appendixsec-heading">unnumberedsec appendixsec heading</a></li> -<li><a href="#index-appendixsubsec-286"><code>appendixsubsec</code></a>: <a href="#unnumberedsubsec-appendixsubsec-subheading">unnumberedsubsec appendixsubsec subheading</a></li> -<li><a href="#index-appendixsubsubsec-291"><code>appendixsubsubsec</code></a>: <a href="#subsubsection">subsubsection</a></li> -<li><a href="#index-apply-991"><code>apply</code></a>: <a href="#Sample-Function-Definition">Sample Function Definition</a></li> -<li><a href="#index-arrow-867"><code>arrow</code></a>: <a href="#Click-Sequences">Click Sequences</a></li> -<li><a href="#index-asis-534"><code>asis</code></a>: <a href="#table">table</a></li> -<li><a href="#index-author-201"><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-458"><code>b </code><span class="roman">(bold font)</span></a>: <a href="#Fonts">Fonts</a></li> -<li><a href="#index-bullet-830"><code>bullet</code></a>: <a href="#bullet">bullet</a></li> -<li><a href="#index-bye-268"><code>bye</code></a>: <a href="#File-End">File End</a></li> -<li><a href="#index-bye-262"><code>bye</code></a>: <a href="#Ending-a-File">Ending a File</a></li> -<li><a href="#index-c-_0040r_007b_0028comment_0029_007d-65"><code>c </code><span class="roman">(comment)</span></a>: <a href="#Comments">Comments</a></li> -<li><a href="#index-caption-566"><code>caption</code></a>: <a href="#caption-shortcaption">caption shortcaption</a></li> -<li><a href="#index-cartouche-518"><code>cartouche</code></a>: <a href="#cartouche">cartouche</a></li> -<li><a href="#index-center-197"><code>center</code></a>: <a href="#titlefont-center-sp">titlefont center sp</a></li> -<li><a href="#index-centerchap-273"><code>centerchap</code></a>: <a href="#chapter">chapter</a></li> -<li><a href="#index-chapheading-277"><code>chapheading</code></a>: <a href="#majorheading-_0026-chapheading">majorheading & chapheading</a></li> -<li><a href="#index-chapter-272"><code>chapter</code></a>: <a href="#chapter">chapter</a></li> -<li><a href="#index-cite-431"><code>cite</code></a>: <a href="#cite">cite</a></li> -<li><a href="#index-clear-1027"><code>clear</code></a>: <a href="#set-value">set value</a></li> -<li><a href="#index-click-866"><code>click</code></a>: <a href="#Click-Sequences">Click Sequences</a></li> -<li><a href="#index-clicksequence-865"><code>clicksequence</code></a>: <a href="#Click-Sequences">Click Sequences</a></li> -<li><a href="#index-clickstyle-868"><code>clickstyle</code></a>: <a href="#Click-Sequences">Click Sequences</a></li> -<li><a href="#index-code-399"><code>code</code></a>: <a href="#code">code</a></li> -<li><a href="#index-columnfractions-547"><code>columnfractions</code></a>: <a href="#Multitable-Column-Widths">Multitable Column Widths</a></li> -<li><a href="#index-comma-655"><code>comma</code></a>: <a href="#Inserting-a-Comma">Inserting a Comma</a></li> -<li><a href="#index-command-426"><code>command</code></a>: <a href="#command">command</a></li> -<li><a href="#index-comment-64"><code>comment</code></a>: <a href="#Comments">Comments</a></li> -<li><a href="#index-contents-215"><code>contents</code></a>: <a href="#Contents">Contents</a></li> -<li><a href="#index-copying-177"><code>copying</code></a>: <a href="#copying">copying</a></li> -<li><a href="#index-copyright-836"><code>copyright</code></a>: <a href="#copyright-symbol">copyright symbol</a></li> -<li><a href="#index-copyright-178"><code>copyright</code></a>: <a href="#copying">copying</a></li> -<li><a href="#index-cropmarks-1195"><code>cropmarks</code></a>: <a href="#Cropmarks-and-Magnification">Cropmarks and Magnification</a></li> -<li><a href="#index-defcodeindex-644"><code>defcodeindex</code></a>: <a href="#New-Indices">New Indices</a></li> -<li><a href="#index-defcv-972"><code>defcv</code></a>: <a href="#Object_002dOriented-Variables">Object-Oriented Variables</a></li> -<li><a href="#index-deffn-957"><code>deffn</code></a>: <a href="#Functions-Commands">Functions Commands</a></li> -<li><a href="#index-deffnx-954"><code>deffnx</code></a>: <a href="#deffnx">deffnx</a></li> -<li><a href="#index-defindex-643"><code>defindex</code></a>: <a href="#New-Indices">New Indices</a></li> -<li><a href="#index-definfoenclose-1093"><code>definfoenclose</code></a>: <a href="#definfoenclose">definfoenclose</a></li> -<li><a href="#index-defivar-976"><code>defivar</code></a>: <a href="#Object_002dOriented-Variables">Object-Oriented Variables</a></li> -<li><a href="#index-defmac-959"><code>defmac</code></a>: <a href="#Functions-Commands">Functions Commands</a></li> -<li><a href="#index-defmethod-983"><code>defmethod</code></a>: <a href="#Object_002dOriented-Methods">Object-Oriented Methods</a></li> -<li><a href="#index-defop-981"><code>defop</code></a>: <a href="#Object_002dOriented-Methods">Object-Oriented Methods</a></li> -<li><a href="#index-defopt-963"><code>defopt</code></a>: <a href="#Variables-Commands">Variables Commands</a></li> -<li><a href="#index-defspec-960"><code>defspec</code></a>: <a href="#Functions-Commands">Functions Commands</a></li> -<li><a href="#index-deftp-969"><code>deftp</code></a>: <a href="#Data-Types">Data Types</a></li> -<li><a href="#index-deftypecv-974"><code>deftypecv</code></a>: <a href="#Object_002dOriented-Variables">Object-Oriented Variables</a></li> -<li><a href="#index-deftypefn-965"><code>deftypefn</code></a>: <a href="#Typed-Functions">Typed Functions</a></li> -<li><a href="#index-deftypefun-966"><code>deftypefun</code></a>: <a href="#Typed-Functions">Typed Functions</a></li> -<li><a href="#index-deftypeivar-978"><code>deftypeivar</code></a>: <a href="#Object_002dOriented-Variables">Object-Oriented Variables</a></li> -<li><a href="#index-deftypeop-982"><code>deftypeop</code></a>: <a href="#Object_002dOriented-Methods">Object-Oriented Methods</a></li> -<li><a href="#index-deftypevar-968"><code>deftypevar</code></a>: <a href="#Typed-Variables">Typed Variables</a></li> -<li><a href="#index-deftypevr-967"><code>deftypevr</code></a>: <a href="#Typed-Variables">Typed Variables</a></li> -<li><a href="#index-defun-958"><code>defun</code></a>: <a href="#Functions-Commands">Functions Commands</a></li> -<li><a href="#index-defvar-962"><code>defvar</code></a>: <a href="#Variables-Commands">Variables Commands</a></li> -<li><a href="#index-defvr-961"><code>defvr</code></a>: <a href="#Variables-Commands">Variables Commands</a></li> -<li><a href="#index-detailmenu-333"><code>detailmenu</code></a>: <a href="#makeinfo-Pointer-Creation">makeinfo Pointer Creation</a></li> -<li><a href="#index-detailmenu-229"><code>detailmenu</code></a>: <a href="#Master-Menu-Parts">Master Menu Parts</a></li> -<li><a href="#index-dfn-430"><code>dfn</code></a>: <a href="#dfn">dfn</a></li> -<li><a href="#index-dircategory-1317"><code>dircategory</code></a>: <a href="#Installing-Dir-Entries">Installing Dir Entries</a></li> -<li><a href="#index-direntry-1318"><code>direntry</code></a>: <a href="#Installing-Dir-Entries">Installing Dir Entries</a></li> -<li><a href="#index-display-500"><code>display</code></a>: <a href="#display">display</a></li> -<li><a href="#index-dmn-682"><code>dmn</code></a>: <a href="#dmn">dmn</a></li> -<li><a href="#index-docbook-1024"><code>docbook</code></a>: <a href="#Raw-Formatter-Commands">Raw Formatter Commands</a></li> -<li><a href="#index-documentdescription-237"><code>documentdescription</code></a>: <a href="#documentdescription">documentdescription</a></li> -<li><a href="#index-documentencoding-1045"><code>documentencoding</code></a>: <a href="#documentencoding">documentencoding</a></li> -<li><a href="#index-documentencoding-765"><code>documentencoding</code></a>: <a href="#Inserting-Quotation-Marks">Inserting Quotation Marks</a></li> -<li><a href="#index-documentencoding-686"><code>documentencoding</code></a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-documentlanguage-1034"><code>documentlanguage</code></a>: <a href="#documentlanguage">documentlanguage</a></li> -<li><a href="#index-dotaccent-701"><code>dotaccent</code></a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-dotless-731"><code>dotless</code></a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-dots-826"><code>dots</code></a>: <a href="#dots">dots</a></li> -<li><a href="#index-email-442"><code>email</code></a>: <a href="#email">email</a></li> -<li><a href="#index-emph-446"><code>emph</code></a>: <a href="#emph-_0026-strong">emph & strong</a></li> -<li><a href="#index-end-524"><code>end</code></a>: <a href="#Introducing-Lists">Introducing Lists</a></li> -<li><a href="#index-end-475"><code>end</code></a>: <a href="#Quotations-and-Examples">Quotations and Examples</a></li> -<li><a href="#index-end-titlepage-207"><code>end titlepage</code></a>: <a href="#end-titlepage">end titlepage</a></li> -<li><a href="#index-enddots-827"><code>enddots</code></a>: <a href="#dots">dots</a></li> -<li><a href="#index-enumerate-530"><code>enumerate</code></a>: <a href="#enumerate">enumerate</a></li> -<li><a href="#index-env-424"><code>env</code></a>: <a href="#env">env</a></li> -<li><a href="#index-equiv-884"><code>equiv</code></a>: <a href="#Equivalence">Equivalence</a></li> -<li><a href="#index-error-882"><code>error</code></a>: <a href="#Error-Glyph">Error Glyph</a></li> -<li><a href="#index-euro-840"><code>euro</code></a>: <a href="#euro">euro</a></li> -<li><a href="#index-evenfooting-1428"><code>evenfooting</code></a>: <a href="#Custom-Headings">Custom Headings</a></li> -<li><a href="#index-evenfootingmarks-1445"><code>evenfootingmarks</code></a>: <a href="#Custom-Headings">Custom Headings</a></li> -<li><a href="#index-evenheading-1427"><code>evenheading</code></a>: <a href="#Custom-Headings">Custom Headings</a></li> -<li><a href="#index-evenheadingmarks-1443"><code>evenheadingmarks</code></a>: <a href="#Custom-Headings">Custom Headings</a></li> -<li><a href="#index-everyfooting-1426"><code>everyfooting</code></a>: <a href="#Custom-Headings">Custom Headings</a></li> -<li><a href="#index-everyfootingmarks-1442"><code>everyfootingmarks</code></a>: <a href="#Custom-Headings">Custom Headings</a></li> -<li><a href="#index-everyheading-1425"><code>everyheading</code></a>: <a href="#Custom-Headings">Custom Headings</a></li> -<li><a href="#index-everyheadingmarks-1441"><code>everyheadingmarks</code></a>: <a href="#Custom-Headings">Custom Headings</a></li> -<li><a href="#index-example-482"><code>example</code></a>: <a href="#example">example</a></li> -<li><a href="#index-exampleindent-253"><code>exampleindent</code></a>: <a href="#exampleindent">exampleindent</a></li> -<li><a href="#index-exclamdown-721"><code>exclamdown</code></a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-exdent-505"><code>exdent</code></a>: <a href="#exdent">exdent</a></li> -<li><a href="#index-expansion-878"><code>expansion</code></a>: <a href="#expansion">expansion</a></li> -<li><a href="#index-file-425"><code>file</code></a>: <a href="#file">file</a></li> -<li><a href="#index-filll-_0040r_007b_0040TeX_007b_007d-dimension_007d-206"><code>filll </code><span class="roman">TeX dimension</span></a>: <a href="#Copyright">Copyright</a></li> -<li><a href="#index-finalout-1172"><code>finalout</code></a>: <a href="#Overfull-hboxes">Overfull hboxes</a></li> -<li><a href="#index-firstparagraphindent-249"><code>firstparagraphindent</code></a>: <a href="#firstparagraphindent">firstparagraphindent</a></li> -<li><a href="#index-float-560"><code>float</code></a>: <a href="#float">float</a></li> -<li><a href="#index-flushleft-506"><code>flushleft</code></a>: <a href="#flushleft-_0026-flushright">flushleft & flushright</a></li> -<li><a href="#index-flushright-507"><code>flushright</code></a>: <a href="#flushleft-_0026-flushright">flushleft & flushright</a></li> -<li><a href="#index-fn_002dname-942"><code>fn-name</code></a>: <a href="#Def-Cmd-Continuation-Lines">Def Cmd Continuation Lines</a></li> -<li><a href="#index-fonttextsize-452"><code>fonttextsize</code></a>: <a href="#Fonts">Fonts</a></li> -<li><a href="#index-foobar-950"><code>foobar</code></a>: <a href="#Optional-Arguments">Optional Arguments</a></li> -<li><a href="#index-footnote-610"><code>footnote</code></a>: <a href="#Footnotes">Footnotes</a></li> -<li><a href="#index-footnotestyle-613"><code>footnotestyle</code></a>: <a href="#Footnote-Styles">Footnote Styles</a></li> -<li><a href="#index-format-502"><code>format</code></a>: <a href="#format">format</a></li> -<li><a href="#index-forward_002dword-937"><code>forward-word</code></a>: <a href="#Def-Cmd-Template">Def Cmd Template</a></li> -<li><a href="#index-frenchspacing-675"><code>frenchspacing</code></a>: <a href="#frenchspacing">frenchspacing</a></li> -<li><a href="#index-ftable-538"><code>ftable</code></a>: <a href="#ftable-vtable">ftable vtable</a></li> -<li><a href="#index-geq-854"><code>geq</code></a>: <a href="#geq-leq">geq leq</a></li> -<li><a href="#index-group-931"><code>group</code></a>: <a href="#group">group</a></li> -<li><a href="#index-guillemetleft-809"><code>guillemetleft</code></a>: <a href="#Inserting-Quotation-Marks">Inserting Quotation Marks</a></li> -<li><a href="#index-guillemetright-812"><code>guillemetright</code></a>: <a href="#Inserting-Quotation-Marks">Inserting Quotation Marks</a></li> -<li><a href="#index-guillemotleft-810"><code>guillemotleft</code></a>: <a href="#Inserting-Quotation-Marks">Inserting Quotation Marks</a></li> -<li><a href="#index-guillemotright-813"><code>guillemotright</code></a>: <a href="#Inserting-Quotation-Marks">Inserting Quotation Marks</a></li> -<li><a href="#index-guilsinglleft-815"><code>guilsinglleft</code></a>: <a href="#Inserting-Quotation-Marks">Inserting Quotation Marks</a></li> -<li><a href="#index-guilsinglright-817"><code>guilsinglright</code></a>: <a href="#Inserting-Quotation-Marks">Inserting Quotation Marks</a></li> -<li><a href="#index-H-_0040r_007b_0028Hungarian-umlaut-accent_0029_007d-703"><code>H </code><span class="roman">(Hungarian umlaut accent)</span></a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-hbox-1166"><code>hbox</code></a>: <a href="#Overfull-hboxes">Overfull hboxes</a></li> -<li><a href="#index-heading-281"><code>heading</code></a>: <a href="#unnumberedsec-appendixsec-heading">unnumberedsec appendixsec heading</a></li> -<li><a href="#index-headings-211"><code>headings</code></a>: <a href="#headings-on-off">headings on off</a></li> -<li><a href="#index-headitem-554"><code>headitem</code></a>: <a href="#Multitable-Rows">Multitable Rows</a></li> -<li><a href="#index-headword-1095"><code>headword</code></a>: <a href="#definfoenclose">definfoenclose</a></li> -<li><a href="#index-html-1020"><code>html</code></a>: <a href="#Raw-Formatter-Commands">Raw Formatter Commands</a></li> -<li><a href="#index-hyphenation-900"><code>hyphenation</code></a>: <a href="#g_t_002d-and-hyphenation">- and hyphenation</a></li> -<li><a href="#index-i-_0040r_007b_0028italic-font_0029_007d-460"><code>i </code><span class="roman">(italic font)</span></a>: <a href="#Fonts">Fonts</a></li> -<li><a href="#index-ifclear-1030"><code>ifclear</code></a>: <a href="#ifset-ifclear">ifset ifclear</a></li> -<li><a href="#index-ifdocbook-1023"><code>ifdocbook</code></a>: <a href="#Raw-Formatter-Commands">Raw Formatter Commands</a></li> -<li><a href="#index-ifdocbook-997"><code>ifdocbook</code></a>: <a href="#Conditional-Commands">Conditional Commands</a></li> -<li><a href="#index-ifhtml-1019"><code>ifhtml</code></a>: <a href="#Raw-Formatter-Commands">Raw Formatter Commands</a></li> -<li><a href="#index-ifhtml-998"><code>ifhtml</code></a>: <a href="#Conditional-Commands">Conditional Commands</a></li> -<li><a href="#index-ifinfo-996"><code>ifinfo</code></a>: <a href="#Conditional-Commands">Conditional Commands</a></li> -<li><a href="#index-ifnotdocbook-1002"><code>ifnotdocbook</code></a>: <a href="#Conditional-Not-Commands">Conditional Not Commands</a></li> -<li><a href="#index-ifnothtml-1003"><code>ifnothtml</code></a>: <a href="#Conditional-Not-Commands">Conditional Not Commands</a></li> -<li><a href="#index-ifnotinfo-1004"><code>ifnotinfo</code></a>: <a href="#Conditional-Not-Commands">Conditional Not Commands</a></li> -<li><a href="#index-ifnotplaintext-1005"><code>ifnotplaintext</code></a>: <a href="#Conditional-Not-Commands">Conditional Not Commands</a></li> -<li><a href="#index-ifnottex-1006"><code>ifnottex</code></a>: <a href="#Conditional-Not-Commands">Conditional Not Commands</a></li> -<li><a href="#index-ifnotxml-1007"><code>ifnotxml</code></a>: <a href="#Conditional-Not-Commands">Conditional Not Commands</a></li> -<li><a href="#index-ifplaintext-999"><code>ifplaintext</code></a>: <a href="#Conditional-Commands">Conditional Commands</a></li> -<li><a href="#index-ifset-1028"><code>ifset</code></a>: <a href="#ifset-ifclear">ifset ifclear</a></li> -<li><a href="#index-iftex-1000"><code>iftex</code></a>: <a href="#Conditional-Commands">Conditional Commands</a></li> -<li><a href="#index-ifxml-1021"><code>ifxml</code></a>: <a href="#Raw-Formatter-Commands">Raw Formatter Commands</a></li> -<li><a href="#index-ifxml-1001"><code>ifxml</code></a>: <a href="#Conditional-Commands">Conditional Commands</a></li> -<li><a href="#index-ignore-68"><code>ignore</code></a>: <a href="#Comments">Comments</a></li> -<li><a href="#index-image-576"><code>image</code></a>: <a href="#Images">Images</a></li> -<li><a href="#index-include-1413"><code>include</code></a>: <a href="#Using-Include-Files">Using Include Files</a></li> -<li><a href="#index-indent-517"><code>indent</code></a>: <a href="#indent">indent</a></li> -<li><a href="#index-indicateurl-439"><code>indicateurl</code></a>: <a href="#indicateurl">indicateurl</a></li> -<li><a href="#index-Info_002dvalidate-1462"><code>Info-validate</code></a>: <a href="#Running-Info_002dValidate">Running Info-Validate</a></li> -<li><a href="#index-inforef-385"><code>inforef</code></a>: <a href="#inforef">inforef</a></li> -<li><a href="#index-insertcopying-184"><code>insertcopying</code></a>: <a href="#insertcopying">insertcopying</a></li> -<li><a href="#index-isearch_002dbackward-956"><code>isearch-backward</code></a>: <a href="#deffnx">deffnx</a></li> -<li><a href="#index-isearch_002dforward-955"><code>isearch-forward</code></a>: <a href="#deffnx">deffnx</a></li> -<li><a href="#index-item-552"><code>item</code></a>: <a href="#Multitable-Rows">Multitable Rows</a></li> -<li><a href="#index-item-535"><code>item</code></a>: <a href="#table">table</a></li> -<li><a href="#index-item-528"><code>item</code></a>: <a href="#itemize">itemize</a></li> -<li><a href="#index-itemize-526"><code>itemize</code></a>: <a href="#itemize">itemize</a></li> -<li><a href="#index-itemx-541"><code>itemx</code></a>: <a href="#itemx">itemx</a></li> -<li><a href="#index-kbd-405"><code>kbd</code></a>: <a href="#kbd">kbd</a></li> -<li><a href="#index-kbdinputstyle-409"><code>kbdinputstyle</code></a>: <a href="#kbd">kbd</a></li> -<li><a href="#index-key-413"><code>key</code></a>: <a href="#key">key</a></li> -<li><a href="#index-L-737"><code>L</code></a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-l-735"><code>l</code></a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-LaTeX-832"><code>LaTeX</code></a>: <a href="#tex">tex</a></li> -<li><a href="#index-leq-855"><code>leq</code></a>: <a href="#geq-leq">geq leq</a></li> -<li><a href="#index-lisp-490"><code>lisp</code></a>: <a href="#lisp">lisp</a></li> -<li><a href="#index-listoffloats-570"><code>listoffloats</code></a>: <a href="#listoffloats">listoffloats</a></li> -<li><a href="#index-lowersections-294"><code>lowersections</code></a>: <a href="#Raise_002flower-sections">Raise/lower sections</a></li> -<li><a href="#index-macro-1063"><code>macro</code></a>: <a href="#Defining-Macros">Defining Macros</a></li> -<li><a href="#index-majorheading-276"><code>majorheading</code></a>: <a href="#majorheading-_0026-chapheading">majorheading & chapheading</a></li> -<li><a href="#index-makeinfo_002dbuffer-1286"><code>makeinfo-buffer</code></a>: <a href="#makeinfo-in-Emacs">makeinfo in Emacs</a></li> -<li><a href="#index-makeinfo_002dkill_002djob-1290"><code>makeinfo-kill-job</code></a>: <a href="#makeinfo-in-Emacs">makeinfo in Emacs</a></li> -<li><a href="#index-makeinfo_002drecenter_002doutput_002dbuffer-1291"><code>makeinfo-recenter-output-buffer</code></a>: <a href="#makeinfo-in-Emacs">makeinfo in Emacs</a></li> -<li><a href="#index-makeinfo_002dregion-1285"><code>makeinfo-region</code></a>: <a href="#makeinfo-in-Emacs">makeinfo in Emacs</a></li> -<li><a href="#index-math-856"><code>math</code></a>: <a href="#math">math</a></li> -<li><a href="#index-menu-339"><code>menu</code></a>: <a href="#Menus">Menus</a></li> -<li><a href="#index-minus-850"><code>minus</code></a>: <a href="#minus">minus</a></li> -<li><a href="#index-multitable-543"><code>multitable</code></a>: <a href="#Multi_002dcolumn-Tables">Multi-column Tables</a></li> -<li><a href="#index-need-933"><code>need</code></a>: <a href="#need">need</a></li> -<li><a href="#index-next_002derror-1289"><code>next-error</code></a>: <a href="#makeinfo-in-Emacs">makeinfo in Emacs</a></li> -<li><a href="#index-node-300"><code>node</code></a>: <a href="#node">node</a></li> -<li><a href="#index-noindent-513"><code>noindent</code></a>: <a href="#noindent">noindent</a></li> -<li><a href="#index-novalidate-1114"><code>novalidate</code></a>: <a href="#Format-with-tex_002ftexindex">Format with tex/texindex</a></li> -<li><a href="#index-O-741"><code>O</code></a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-o-739"><code>o</code></a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-occur-1461"><code>occur</code></a>: <a href="#Using-occur">Using occur</a></li> -<li><a href="#index-occur_002dmode_002dgoto_002doccurrence-122"><code>occur-mode-goto-occurrence</code></a>: <a href="#Showing-the-Structure">Showing the Structure</a></li> -<li><a href="#index-oddfooting-1430"><code>oddfooting</code></a>: <a href="#Custom-Headings">Custom Headings</a></li> -<li><a href="#index-oddfootingmarks-1446"><code>oddfootingmarks</code></a>: <a href="#Custom-Headings">Custom Headings</a></li> -<li><a href="#index-oddheading-1429"><code>oddheading</code></a>: <a href="#Custom-Headings">Custom Headings</a></li> -<li><a href="#index-oddheadingmarks-1444"><code>oddheadingmarks</code></a>: <a href="#Custom-Headings">Custom Headings</a></li> -<li><a href="#index-OE-745"><code>OE</code></a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-oe-743"><code>oe</code></a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-option-429"><code>option</code></a>: <a href="#option">option</a></li> -<li><a href="#index-ordf-750"><code>ordf</code></a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-ordm-753"><code>ordm</code></a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-page-927"><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-192"><code>page</code><span class="roman">, within </span><code>@titlepage</code></a>: <a href="#titlepage">titlepage</a></li> -<li><a href="#index-pagesizes-1185"><code>pagesizes</code></a>: <a href="#pagesizes">pagesizes</a></li> -<li><a href="#index-paragraphindent-243"><code>paragraphindent</code></a>: <a href="#paragraphindent">paragraphindent</a></li> -<li><a href="#index-phoo-1094"><code>phoo</code></a>: <a href="#definfoenclose">definfoenclose</a></li> -<li><a href="#index-point-886"><code>point</code></a>: <a href="#Point-Glyph">Point Glyph</a></li> -<li><a href="#index-pounds-846"><code>pounds</code></a>: <a href="#pounds">pounds</a></li> -<li><a href="#index-print-880"><code>print</code></a>: <a href="#Print-Glyph">Print Glyph</a></li> -<li><a href="#index-printindex-267"><code>printindex</code></a>: <a href="#Printing-Indices-_0026-Menus">Printing Indices & Menus</a></li> -<li><a href="#index-pxref-381"><code>pxref</code></a>: <a href="#pxref">pxref</a></li> -<li><a href="#index-questiondown-719"><code>questiondown</code></a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-quotation-477"><code>quotation</code></a>: <a href="#quotation">quotation</a></li> -<li><a href="#index-quotedblbase-788"><code>quotedblbase</code></a>: <a href="#Inserting-Quotation-Marks">Inserting Quotation Marks</a></li> -<li><a href="#index-quotedblleft-778"><code>quotedblleft</code></a>: <a href="#Inserting-Quotation-Marks">Inserting Quotation Marks</a></li> -<li><a href="#index-quotedblright-782"><code>quotedblright</code></a>: <a href="#Inserting-Quotation-Marks">Inserting Quotation Marks</a></li> -<li><a href="#index-quoteleft-780"><code>quoteleft</code></a>: <a href="#Inserting-Quotation-Marks">Inserting Quotation Marks</a></li> -<li><a href="#index-quoteright-784"><code>quoteright</code></a>: <a href="#Inserting-Quotation-Marks">Inserting Quotation Marks</a></li> -<li><a href="#index-quotesinglbase-790"><code>quotesinglbase</code></a>: <a href="#Inserting-Quotation-Marks">Inserting Quotation Marks</a></li> -<li><a href="#index-r-_0040r_007b_0028roman-font_0029_007d-462"><code>r </code><span class="roman">(roman font)</span></a>: <a href="#Fonts">Fonts</a></li> -<li><a href="#index-raisesections-293"><code>raisesections</code></a>: <a href="#Raise_002flower-sections">Raise/lower sections</a></li> -<li><a href="#index-ref-376"><code>ref</code></a>: <a href="#ref">ref</a></li> -<li><a href="#index-registeredsymbol-838"><code>registeredsymbol</code></a>: <a href="#registered-symbol">registered symbol</a></li> -<li><a href="#index-result-875"><code>result</code></a>: <a href="#result">result</a></li> -<li><a href="#index-ringaccent-705"><code>ringaccent</code></a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-rmacro-1074"><code>rmacro</code></a>: <a href="#Defining-Macros">Defining Macros</a></li> -<li><a href="#index-samp-419"><code>samp</code></a>: <a href="#samp">samp</a></li> -<li><a href="#index-sansserif-_0040r_007b_0028sans-serif-font_0029_007d-465"><code>sansserif </code><span class="roman">(sans serif font)</span></a>: <a href="#Fonts">Fonts</a></li> -<li><a href="#index-sc-_0040r_007b_0028small-caps-font_0029_007d-449"><code>sc </code><span class="roman">(small caps font)</span></a>: <a href="#Smallcaps">Smallcaps</a></li> -<li><a href="#index-section-278"><code>section</code></a>: <a href="#section">section</a></li> -<li><a href="#index-set-1025"><code>set</code></a>: <a href="#set-value">set value</a></li> -<li><a href="#index-setchapternewpage-240"><code>setchapternewpage</code></a>: <a href="#setchapternewpage">setchapternewpage</a></li> -<li><a href="#index-setcontentsaftertitlepage-218"><code>setcontentsaftertitlepage</code></a>: <a href="#Contents">Contents</a></li> -<li><a href="#index-setfilename-164"><code>setfilename</code></a>: <a href="#setfilename">setfilename</a></li> -<li><a href="#index-setshortcontentsaftertitlepage-219"><code>setshortcontentsaftertitlepage</code></a>: <a href="#Contents">Contents</a></li> -<li><a href="#index-settitle-172"><code>settitle</code></a>: <a href="#settitle">settitle</a></li> -<li><a href="#index-shortcaption-567"><code>shortcaption</code></a>: <a href="#caption-shortcaption">caption shortcaption</a></li> -<li><a href="#index-shortcontents-217"><code>shortcontents</code></a>: <a href="#Contents">Contents</a></li> -<li><a href="#index-shorttitlepage-193"><code>shorttitlepage</code></a>: <a href="#titlepage">titlepage</a></li> -<li><a href="#index-slanted-_0040r_007b_0028slanted-font_0029_007d-467"><code>slanted </code><span class="roman">(slanted font)</span></a>: <a href="#Fonts">Fonts</a></li> -<li><a href="#index-smallbook-1173"><code>smallbook</code></a>: <a href="#smallbook">smallbook</a></li> -<li><a href="#index-smalldisplay-501"><code>smalldisplay</code></a>: <a href="#display">display</a></li> -<li><a href="#index-smalldisplay-495"><code>smalldisplay</code></a>: <a href="#small">small</a></li> -<li><a href="#index-smallexample-496"><code>smallexample</code></a>: <a href="#small">small</a></li> -<li><a href="#index-smallformat-503"><code>smallformat</code></a>: <a href="#format">format</a></li> -<li><a href="#index-smallformat-497"><code>smallformat</code></a>: <a href="#small">small</a></li> -<li><a href="#index-smalllisp-498"><code>smalllisp</code></a>: <a href="#small">small</a></li> -<li><a href="#index-sp-_0040r_007b_0028line-spacing_0029_007d-922"><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-198"><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-755"><code>ss</code></a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-strong-447"><code>strong</code></a>: <a href="#emph-_0026-strong">emph & strong</a></li> -<li><a href="#index-subheading-287"><code>subheading</code></a>: <a href="#unnumberedsubsec-appendixsubsec-subheading">unnumberedsubsec appendixsubsec subheading</a></li> -<li><a href="#index-subsection-283"><code>subsection</code></a>: <a href="#subsection">subsection</a></li> -<li><a href="#index-subsubheading-292"><code>subsubheading</code></a>: <a href="#subsubsection">subsubsection</a></li> -<li><a href="#index-subsubsection-289"><code>subsubsection</code></a>: <a href="#subsubsection">subsubsection</a></li> -<li><a href="#index-subtitle-200"><code>subtitle</code></a>: <a href="#title-subtitle-author">title subtitle author</a></li> -<li><a href="#index-summarycontents-216"><code>summarycontents</code></a>: <a href="#Contents">Contents</a></li> -<li><a href="#index-syncodeindex-633"><code>syncodeindex</code></a>: <a href="#syncodeindex">syncodeindex</a></li> -<li><a href="#index-synindex-639"><code>synindex</code></a>: <a href="#synindex">synindex</a></li> -<li><a href="#index-t-_0040r_007b_0028typewriter-font_0029_007d-470"><code>t </code><span class="roman">(typewriter font)</span></a>: <a href="#Fonts">Fonts</a></li> -<li><a href="#index-tab-553"><code>tab</code></a>: <a href="#Multitable-Rows">Multitable Rows</a></li> -<li><a href="#index-table-532"><code>table</code></a>: <a href="#Two_002dcolumn-Tables">Two-column Tables</a></li> -<li><a href="#index-tex-1016"><code>tex</code></a>: <a href="#Raw-Formatter-Commands">Raw Formatter Commands</a></li> -<li><a href="#index-TeX-831"><code>TeX</code></a>: <a href="#tex">tex</a></li> -<li><a href="#index-texinfo_002dall_002dmenus_002dupdate-133"><code>texinfo-all-menus-update</code></a>: <a href="#Updating-Commands">Updating Commands</a></li> -<li><a href="#index-texinfo_002devery_002dnode_002dupdate-132"><code>texinfo-every-node-update</code></a>: <a href="#Updating-Commands">Updating Commands</a></li> -<li><a href="#index-texinfo_002dformat_002dbuffer-1293"><code>texinfo-format-buffer</code></a>: <a href="#texinfo_002dformat-commands">texinfo-format commands</a></li> -<li><a href="#index-texinfo_002dformat_002dbuffer-144"><code>texinfo-format-buffer</code></a>: <a href="#Info-Formatting">Info Formatting</a></li> -<li><a href="#index-texinfo_002dformat_002dregion-1292"><code>texinfo-format-region</code></a>: <a href="#texinfo_002dformat-commands">texinfo-format commands</a></li> -<li><a href="#index-texinfo_002dformat_002dregion-143"><code>texinfo-format-region</code></a>: <a href="#Info-Formatting">Info Formatting</a></li> -<li><a href="#index-texinfo_002dindent_002dmenu_002ddescription-138"><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-98"><code>texinfo-insert-@code</code></a>: <a href="#Inserting">Inserting</a></li> -<li><a href="#index-texinfo_002dinsert_002d_0040_0040dfn-99"><code>texinfo-insert-@dfn</code></a>: <a href="#Inserting">Inserting</a></li> -<li><a href="#index-texinfo_002dinsert_002d_0040_0040end-100"><code>texinfo-insert-@end</code></a>: <a href="#Inserting">Inserting</a></li> -<li><a href="#index-texinfo_002dinsert_002d_0040_0040example-108"><code>texinfo-insert-@example</code></a>: <a href="#Inserting">Inserting</a></li> -<li><a href="#index-texinfo_002dinsert_002d_0040_0040item-101"><code>texinfo-insert-@item</code></a>: <a href="#Inserting">Inserting</a></li> -<li><a href="#index-texinfo_002dinsert_002d_0040_0040kbd-102"><code>texinfo-insert-@kbd</code></a>: <a href="#Inserting">Inserting</a></li> -<li><a href="#index-texinfo_002dinsert_002d_0040_0040node-103"><code>texinfo-insert-@node</code></a>: <a href="#Inserting">Inserting</a></li> -<li><a href="#index-texinfo_002dinsert_002d_0040_0040noindent-104"><code>texinfo-insert-@noindent</code></a>: <a href="#Inserting">Inserting</a></li> -<li><a href="#index-texinfo_002dinsert_002d_0040_0040samp-105"><code>texinfo-insert-@samp</code></a>: <a href="#Inserting">Inserting</a></li> -<li><a href="#index-texinfo_002dinsert_002d_0040_0040table-106"><code>texinfo-insert-@table</code></a>: <a href="#Inserting">Inserting</a></li> -<li><a href="#index-texinfo_002dinsert_002d_0040_0040var-107"><code>texinfo-insert-@var</code></a>: <a href="#Inserting">Inserting</a></li> -<li><a href="#index-texinfo_002dinsert_002dbraces-109"><code>texinfo-insert-braces</code></a>: <a href="#Inserting">Inserting</a></li> -<li><a href="#index-texinfo_002dinsert_002dnode_002dlines-136"><code>texinfo-insert-node-lines</code></a>: <a href="#Other-Updating-Commands">Other Updating Commands</a></li> -<li><a href="#index-texinfo_002dmake_002dmenu-131"><code>texinfo-make-menu</code></a>: <a href="#Updating-Commands">Updating Commands</a></li> -<li><a href="#index-texinfo_002dmaster_002dmenu-129"><code>texinfo-master-menu</code></a>: <a href="#Updating-Commands">Updating Commands</a></li> -<li><a href="#index-texinfo_002dmultiple_002dfiles_002dupdate-1414"><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-137"><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-139"><code>texinfo-sequential-node-update</code></a>: <a href="#Other-Updating-Commands">Other Updating Commands</a></li> -<li><a href="#index-texinfo_002dshow_002dstructure-1459"><code>texinfo-show-structure</code></a>: <a href="#Using-texinfo_002dshow_002dstructure">Using texinfo-show-structure</a></li> -<li><a href="#index-texinfo_002dshow_002dstructure-121"><code>texinfo-show-structure</code></a>: <a href="#Showing-the-Structure">Showing the Structure</a></li> -<li><a href="#index-texinfo_002dstart_002dmenu_002ddescription-111"><code>texinfo-start-menu-description</code></a>: <a href="#Inserting">Inserting</a></li> -<li><a href="#index-texinfo_002dtex_002dbuffer-150"><code>texinfo-tex-buffer</code></a>: <a href="#Printing">Printing</a></li> -<li><a href="#index-texinfo_002dtex_002dprint-152"><code>texinfo-tex-print</code></a>: <a href="#Printing">Printing</a></li> -<li><a href="#index-texinfo_002dtex_002dregion-151"><code>texinfo-tex-region</code></a>: <a href="#Printing">Printing</a></li> -<li><a href="#index-texinfo_002dupdate_002dnode-130"><code>texinfo-update-node</code></a>: <a href="#Updating-Commands">Updating Commands</a></li> -<li><a href="#index-textdegree-848"><code>textdegree</code></a>: <a href="#textdegree">textdegree</a></li> -<li><a href="#index-thischapter-1437"><code>thischapter</code></a>: <a href="#Custom-Headings">Custom Headings</a></li> -<li><a href="#index-thischaptername-1435"><code>thischaptername</code></a>: <a href="#Custom-Headings">Custom Headings</a></li> -<li><a href="#index-thischapternum-1436"><code>thischapternum</code></a>: <a href="#Custom-Headings">Custom Headings</a></li> -<li><a href="#index-thisfile-1439"><code>thisfile</code></a>: <a href="#Custom-Headings">Custom Headings</a></li> -<li><a href="#index-thispage-1431"><code>thispage</code></a>: <a href="#Custom-Headings">Custom Headings</a></li> -<li><a href="#index-thissection-1434"><code>thissection</code></a>: <a href="#Custom-Headings">Custom Headings</a></li> -<li><a href="#index-thissectionname-1432"><code>thissectionname</code></a>: <a href="#Custom-Headings">Custom Headings</a></li> -<li><a href="#index-thissectionnum-1433"><code>thissectionnum</code></a>: <a href="#Custom-Headings">Custom Headings</a></li> -<li><a href="#index-thistitle-1438"><code>thistitle</code></a>: <a href="#Custom-Headings">Custom Headings</a></li> -<li><a href="#index-tie-_0040r_007b_0028unbreakable-interword-space_0029_007d-918"><code>tie </code><span class="roman">(unbreakable interword space)</span></a>: <a href="#tie">tie</a></li> -<li><a href="#index-tieaccent-707"><code>tieaccent</code></a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-title-199"><code>title</code></a>: <a href="#title-subtitle-author">title subtitle author</a></li> -<li><a href="#index-titlefont-196"><code>titlefont</code></a>: <a href="#titlefont-center-sp">titlefont center sp</a></li> -<li><a href="#index-titlepage-191"><code>titlepage</code></a>: <a href="#titlepage">titlepage</a></li> -<li><a href="#index-today-1440"><code>today</code></a>: <a href="#Custom-Headings">Custom Headings</a></li> -<li><a href="#index-top-224"><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-709"><code>u </code><span class="roman">(breve accent)</span></a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-ubaraccent-711"><code>ubaraccent</code></a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-udotaccent-713"><code>udotaccent</code></a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-unmacro-1075"><code>unmacro</code></a>: <a href="#Defining-Macros">Defining Macros</a></li> -<li><a href="#index-unnumbered-274"><code>unnumbered</code></a>: <a href="#unnumbered-_0026-appendix">unnumbered & appendix</a></li> -<li><a href="#index-unnumberedsec-279"><code>unnumberedsec</code></a>: <a href="#unnumberedsec-appendixsec-heading">unnumberedsec appendixsec heading</a></li> -<li><a href="#index-unnumberedsubsec-285"><code>unnumberedsubsec</code></a>: <a href="#unnumberedsubsec-appendixsubsec-subheading">unnumberedsubsec appendixsubsec subheading</a></li> -<li><a href="#index-unnumberedsubsubsec-290"><code>unnumberedsubsubsec</code></a>: <a href="#subsubsection">subsubsection</a></li> -<li><a href="#index-up_002dlist-110"><code>up-list</code></a>: <a href="#Inserting">Inserting</a></li> -<li><a href="#index-uref-386"><code>uref</code></a>: <a href="#uref">uref</a></li> -<li><a href="#index-v-_0040r_007b_0028check-accent_0029_007d-715"><code>v </code><span class="roman">(check accent)</span></a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-value-1026"><code>value</code></a>: <a href="#set-value">set value</a></li> -<li><a href="#index-var-423"><code>var</code></a>: <a href="#var">var</a></li> -<li><a href="#index-verb-420"><code>verb</code></a>: <a href="#verb">verb</a></li> -<li><a href="#index-verbatim-483"><code>verbatim</code></a>: <a href="#verbatim">verbatim</a></li> -<li><a href="#index-verbatiminclude-489"><code>verbatiminclude</code></a>: <a href="#verbatiminclude">verbatiminclude</a></li> -<li><a href="#index-vskip-_0040r_007b_0040TeX_007b_007d-vertical-skip_007d-205"><code>vskip </code><span class="roman">TeX vertical skip</span></a>: <a href="#Copyright">Copyright</a></li> -<li><a href="#index-vtable-539"><code>vtable</code></a>: <a href="#ftable-vtable">ftable vtable</a></li> -<li><a href="#index-w-_0040r_007b_0028prevent-line-break_0029_007d-910"><code>w </code><span class="roman">(prevent line break)</span></a>: <a href="#w">w</a></li> -<li><a href="#index-xml-1022"><code>xml</code></a>: <a href="#Raw-Formatter-Commands">Raw Formatter Commands</a></li> -<li><a href="#index-xref-369"><code>xref</code></a>: <a href="#xref">xref</a></li> -<li><a href="#index-g_t_0040_007b-_0040r_007b_0028literal-_0040samp_007b_0040_007b_007d_0029_007d-652"><code>{ </code><span class="roman">(literal ‘</span><samp><span class="samp">{</span></samp><span class="roman">’)</span></a>: <a href="#Inserting-Braces">Inserting Braces</a></li> -<li><a href="#index-g_t_0040_007d-_0040r_007b_0028literal-_0040samp_007b_0040_007d_007d_0029_007d-653"><code>} </code><span class="roman">(literal ‘</span><samp><span class="samp">}</span></samp><span class="roman">’)</span></a>: <a href="#Inserting-Braces">Inserting Braces</a></li> -<li><a href="#index-g_t_007e-_0040r_007b_0028tilde-accent_0029_007d-697"><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="General-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> - -</div> - -<h2 class="unnumbered">General Index</h2> - - - -<ul class="index-cp" compact> -<li><a href="#index-g_t_0040exclamdown_007b_007d-722">¡</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-g_t_0060_0060-779">“</a>: <a href="#Inserting-Quotation-Marks">Inserting Quotation Marks</a></li> -<li><a href="#index-g_t_0040quotedblbase_007b_007d-_0028double-low_002d9-quotation-mark_0029-789">„ (double low-9 quotation mark)</a>: <a href="#Inserting-Quotation-Marks">Inserting Quotation Marks</a></li> -<li><a href="#index-g_t_0024Id-1397">$Id</a>: <a href="#GNU-Sample-Texts">GNU Sample Texts</a></li> -<li><a href="#index-g_t_0024Id-expansion_002c-preventing-917">$Id expansion, preventing</a>: <a href="#w">w</a></li> -<li><a href="#index-g_t_0027-785">'</a>: <a href="#Inserting-Quotation-Marks">Inserting Quotation Marks</a></li> -<li><a href="#index-g_t_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-g_t_0040quotesinglbase_007b_007d-_0028single-low_002d9-quotation-mark_0029-791">‚ (single low-9 quotation mark)</a>: <a href="#Inserting-Quotation-Marks">Inserting Quotation Marks</a></li> -<li><a href="#index-g_t_002d_002c-breakpoint-within-_0040code_007b_0040_0040code_007d-905">-, breakpoint within <code>@code</code></a>: <a href="#allowcodebreaks">allowcodebreaks</a></li> -<li><a href="#index-g_t_002d_002dalign_003d_0040var_007bcolumn_007d-1327"><code>--align=</code><var>column</var></a>: <a href="#Invoking-install_002dinfo">Invoking install-info</a></li> -<li><a href="#index-g_t_002d_002dcalign_003d_0040var_007bcolumn_007d-1328"><code>--calign=</code><var>column</var></a>: <a href="#Invoking-install_002dinfo">Invoking install-info</a></li> -<li><a href="#index-g_t_002d_002dcommand-_0040r_007b_0028_0040command_007btexi2dvi_007d_0029_007d-1118"><code>--command </code><span class="roman">(</span><samp><span class="command">texi2dvi</span></samp><span class="roman">)</span></a>: <a href="#Format-with-texi2dvi">Format with texi2dvi</a></li> -<li><a href="#index-g_t_002d_002dcommands_002din_002dnode_002dnames-1212"><code>--commands-in-node-names</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> -<li><a href="#index-g_t_002d_002dcss_002dinclude-1213"><code>--css-include</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> -<li><a href="#index-g_t_002d_002dcss_002dref-1214"><code>--css-ref</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> -<li><a href="#index-g_t_002d_002ddebug-1329"><code>--debug</code></a>: <a href="#Invoking-install_002dinfo">Invoking install-info</a></li> -<li><a href="#index-g_t_002d_002ddelete-1330"><code>--delete</code></a>: <a href="#Invoking-install_002dinfo">Invoking install-info</a></li> -<li><a href="#index-g_t_002d_002ddescription_003d_0040var_007btext_007d-1331"><code>--description=</code><var>text</var></a>: <a href="#Invoking-install_002dinfo">Invoking install-info</a></li> -<li><a href="#index-g_t_002d_002ddir_002dfile_003d_0040var_007bname_007d-1332"><code>--dir-file=</code><var>name</var></a>: <a href="#Invoking-install_002dinfo">Invoking install-info</a></li> -<li><a href="#index-g_t_002d_002ddisable_002dencoding-1215"><code>--disable-encoding</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> -<li><a href="#index-g_t_002d_002ddocbook-1217"><code>--docbook</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> -<li><a href="#index-g_t_002d_002ddocument_002dlanguage-1218"><code>--document-language</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> -<li><a href="#index-g_t_002d_002ddry_002drun-1333"><code>--dry-run</code></a>: <a href="#Invoking-install_002dinfo">Invoking install-info</a></li> -<li><a href="#index-g_t_002d_002denable_002dencoding-1216"><code>--enable-encoding</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> -<li><a href="#index-g_t_002d_002denable_002dencoding-1050"><code>--enable-encoding</code></a>: <a href="#documentencoding">documentencoding</a></li> -<li><a href="#index-g_t_002d_002dentry_003d_0040var_007btext_007d-1334"><code>--entry=</code><var>text</var></a>: <a href="#Invoking-install_002dinfo">Invoking install-info</a></li> -<li><a href="#index-g_t_002d_002derror_002dlimit_003d_0040var_007blimit_007d-1220"><code>--error-limit=</code><var>limit</var></a>: <a href="#makeinfo-options">makeinfo options</a></li> -<li><a href="#index-g_t_002d_002dfill_002dcolumn_003d_0040var_007bwidth_007d-1222"><code>--fill-column=</code><var>width</var></a>: <a href="#makeinfo-options">makeinfo options</a></li> -<li><a href="#index-g_t_002d_002dfootnote_002dstyle_0040r_007b_002c-ignored-in-HTML-output_007d-1357"><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-g_t_002d_002dfootnote_002dstyle_003d_0040var_007bstyle_007d-1224"><code>--footnote-style=</code><var>style</var></a>: <a href="#makeinfo-options">makeinfo options</a></li> -<li><a href="#index-g_t_002d_002dforce-1226"><code>--force</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> -<li><a href="#index-g_t_002d_002dhelp-1335"><code>--help</code></a>: <a href="#Invoking-install_002dinfo">Invoking install-info</a></li> -<li><a href="#index-g_t_002d_002dhelp-1228"><code>--help</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> -<li><a href="#index-g_t_002d_002dhtml-1230"><code>--html</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> -<li><a href="#index-g_t_002d_002difdocbook-1232"><code>--ifdocbook</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> -<li><a href="#index-g_t_002d_002difhtml-1233"><code>--ifhtml</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> -<li><a href="#index-g_t_002d_002difinfo-1234"><code>--ifinfo</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> -<li><a href="#index-g_t_002d_002difplaintext-1235"><code>--ifplaintext</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> -<li><a href="#index-g_t_002d_002diftex-1236"><code>--iftex</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> -<li><a href="#index-g_t_002d_002difxml-1237"><code>--ifxml</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> -<li><a href="#index-g_t_002d_002dinfo_002ddir_003d_0040var_007bdir_007d-1337"><code>--info-dir=</code><var>dir</var></a>: <a href="#Invoking-install_002dinfo">Invoking install-info</a></li> -<li><a href="#index-g_t_002d_002dinfo_002dfile_003d_0040var_007bfile_007d-1336"><code>--info-file=</code><var>file</var></a>: <a href="#Invoking-install_002dinfo">Invoking install-info</a></li> -<li><a href="#index-g_t_002d_002dinfodir_003d_0040var_007bdir_007d-1338"><code>--infodir=</code><var>dir</var></a>: <a href="#Invoking-install_002dinfo">Invoking install-info</a></li> -<li><a href="#index-g_t_002d_002ditem_003d_0040var_007btext_007d-1339"><code>--item=</code><var>text</var></a>: <a href="#Invoking-install_002dinfo">Invoking install-info</a></li> -<li><a href="#index-g_t_002d_002dkeep_002dold-1340"><code>--keep-old</code></a>: <a href="#Invoking-install_002dinfo">Invoking install-info</a></li> -<li><a href="#index-g_t_002d_002dlanguage-_0040r_007b_0028_0040command_007btexi2dvi_007d_0029_007d-1121"><code>--language </code><span class="roman">(</span><samp><span class="command">texi2dvi</span></samp><span class="roman">)</span></a>: <a href="#Format-with-texi2dvi">Format with texi2dvi</a></li> -<li><a href="#index-g_t_002d_002dmacro_002dexpand_003d_0040var_007bfile_007d-1238"><code>--macro-expand=</code><var>file</var></a>: <a href="#makeinfo-options">makeinfo options</a></li> -<li><a href="#index-g_t_002d_002dmax_002dwidth_003d_0040var_007bcolumn_007d-1341"><code>--max-width=</code><var>column</var></a>: <a href="#Invoking-install_002dinfo">Invoking install-info</a></li> -<li><a href="#index-g_t_002d_002dmaxwidth_003d_0040var_007bcolumn_007d-1342"><code>--maxwidth=</code><var>column</var></a>: <a href="#Invoking-install_002dinfo">Invoking install-info</a></li> -<li><a href="#index-g_t_002d_002dmenuentry_003d_0040var_007btext_007d-1343"><code>--menuentry=</code><var>text</var></a>: <a href="#Invoking-install_002dinfo">Invoking install-info</a></li> -<li><a href="#index-g_t_002d_002dname_003d_0040var_007btext_007d-1344"><code>--name=</code><var>text</var></a>: <a href="#Invoking-install_002dinfo">Invoking install-info</a></li> -<li><a href="#index-g_t_002d_002dno_002dheaders-1240"><code>--no-headers</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> -<li><a href="#index-g_t_002d_002dno_002difdocbook-1249"><code>--no-ifdocbook</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> -<li><a href="#index-g_t_002d_002dno_002difhtml-1250"><code>--no-ifhtml</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> -<li><a href="#index-g_t_002d_002dno_002difinfo-1251"><code>--no-ifinfo</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> -<li><a href="#index-g_t_002d_002dno_002difplaintext-1252"><code>--no-ifplaintext</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> -<li><a href="#index-g_t_002d_002dno_002diftex-1253"><code>--no-iftex</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> -<li><a href="#index-g_t_002d_002dno_002difxml-1254"><code>--no-ifxml</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> -<li><a href="#index-g_t_002d_002dno_002dindent-1345"><code>--no-indent</code></a>: <a href="#Invoking-install_002dinfo">Invoking install-info</a></li> -<li><a href="#index-g_t_002d_002dno_002dnumber_002dfootnotes-1255"><code>--no-number-footnotes</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> -<li><a href="#index-g_t_002d_002dno_002dnumber_002dsections-1256"><code>--no-number-sections</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> -<li><a href="#index-g_t_002d_002dno_002dpointer_002dvalidate-1260"><code>--no-pointer-validate</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> -<li><a href="#index-g_t_002d_002dno_002dsplit-1257"><code>--no-split</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> -<li><a href="#index-g_t_002d_002dno_002dvalidate-1261"><code>--no-validate</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> -<li><a href="#index-g_t_002d_002dno_002dwarn-1263"><code>--no-warn</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> -<li><a href="#index-g_t_002d_002dnumber_002dsections-1264"><code>--number-sections</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> -<li><a href="#index-g_t_002d_002doutput_003d_0040var_007bfile_007d-1265"><code>--output=</code><var>file</var></a>: <a href="#makeinfo-options">makeinfo options</a></li> -<li><a href="#index-g_t_002d_002dparagraph_002dindent_003d_0040var_007bindent_007d-1268"><code>--paragraph-indent=</code><var>indent</var></a>: <a href="#makeinfo-options">makeinfo options</a></li> -<li><a href="#index-g_t_002d_002dpdf-_0040r_007b_0028_0040command_007btexi2dvi_007d_0029_007d-1119"><code>--pdf </code><span class="roman">(</span><samp><span class="command">texi2dvi</span></samp><span class="roman">)</span></a>: <a href="#Format-with-texi2dvi">Format with texi2dvi</a></li> -<li><a href="#index-g_t_002d_002dplaintext-1241"><code>--plaintext</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> -<li><a href="#index-g_t_002d_002dquiet-1346"><code>--quiet</code></a>: <a href="#Invoking-install_002dinfo">Invoking install-info</a></li> -<li><a href="#index-g_t_002d_002drecode-_0040r_007b_0028_0040command_007btexi2dvi_007d_0029_007d-1123"><code>--recode </code><span class="roman">(</span><samp><span class="command">texi2dvi</span></samp><span class="roman">)</span></a>: <a href="#Format-with-texi2dvi">Format with texi2dvi</a></li> -<li><a href="#index-g_t_002d_002drecode_002dfrom-_0040r_007b_0028_0040command_007btexi2dvi_007d_0029_007d-1124"><code>--recode-from </code><span class="roman">(</span><samp><span class="command">texi2dvi</span></samp><span class="roman">)</span></a>: <a href="#Format-with-texi2dvi">Format with texi2dvi</a></li> -<li><a href="#index-g_t_002d_002dregex_003d_0040var_007bregex_007d-1352"><code>--regex=</code><var>regex</var></a>: <a href="#Invoking-install_002dinfo">Invoking install-info</a></li> -<li><a href="#index-g_t_002d_002dremove-1348"><code>--remove</code></a>: <a href="#Invoking-install_002dinfo">Invoking install-info</a></li> -<li><a href="#index-g_t_002d_002dremove_002dexactly-1349"><code>--remove-exactly</code></a>: <a href="#Invoking-install_002dinfo">Invoking install-info</a></li> -<li><a href="#index-g_t_002d_002dsection-_0040var_007bregex_007d-_0040var_007bsec_007d-1351"><code>--section </code><var>regex</var> <var>sec</var></a>: <a href="#Invoking-install_002dinfo">Invoking install-info</a></li> -<li><a href="#index-g_t_002d_002dsection_003d_0040var_007bsec_007d-1350"><code>--section=</code><var>sec</var></a>: <a href="#Invoking-install_002dinfo">Invoking install-info</a></li> -<li><a href="#index-g_t_002d_002dsilent-1347"><code>--silent</code></a>: <a href="#Invoking-install_002dinfo">Invoking install-info</a></li> -<li><a href="#index-g_t_002d_002dsplit_002dsize_003d_0040var_007bnum_007d-1270"><code>--split-size=</code><var>num</var></a>: <a href="#makeinfo-options">makeinfo options</a></li> -<li><a href="#index-g_t_002d_002dtest-1353"><code>--test</code></a>: <a href="#Invoking-install_002dinfo">Invoking install-info</a></li> -<li><a href="#index-g_t_002d_002dtranslate_002dfile-_0040r_007b_0028_0040command_007btexi2dvi_007d_0029_007d-1122"><code>--translate-file </code><span class="roman">(</span><samp><span class="command">texi2dvi</span></samp><span class="roman">)</span></a>: <a href="#Format-with-texi2dvi">Format with texi2dvi</a></li> -<li><a href="#index-g_t_002d_002dtransliterate_002dfile_002dnames-1271"><code>--transliterate-file-names</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> -<li><a href="#index-g_t_002d_002dverbose-1272"><code>--verbose</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> -<li><a href="#index-g_t_002d_002dversion-1354"><code>--version</code></a>: <a href="#Invoking-install_002dinfo">Invoking install-info</a></li> -<li><a href="#index-g_t_002d_002dversion-1273"><code>--version</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> -<li><a href="#index-g_t_002d_002dxml-1275"><code>--xml</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> -<li><a href="#index-g_t_002dD-_0040var_007bvar_007d-1211"><code>-D </code><var>var</var></a>: <a href="#makeinfo-options">makeinfo options</a></li> -<li><a href="#index-g_t_002dE-_0040var_007bfile_007d-1239"><code>-E </code><var>file</var></a>: <a href="#makeinfo-options">makeinfo options</a></li> -<li><a href="#index-g_t_002de-_0040var_007blimit_007d-1221"><code>-e </code><var>limit</var></a>: <a href="#makeinfo-options">makeinfo options</a></li> -<li><a href="#index-g_t_002dF-1227"><code>-F</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> -<li><a href="#index-g_t_002df-_0040var_007bwidth_007d-1223"><code>-f </code><var>width</var></a>: <a href="#makeinfo-options">makeinfo options</a></li> -<li><a href="#index-g_t_002dh-1229"><code>-h</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> -<li><a href="#index-g_t_002dI-_0040var_007bdir_007d-1231"><code>-I </code><var>dir</var></a>: <a href="#makeinfo-options">makeinfo options</a></li> -<li><a href="#index-g_t_002do-_0040var_007bfile_007d-1266"><code>-o </code><var>file</var></a>: <a href="#makeinfo-options">makeinfo options</a></li> -<li><a href="#index-g_t_002dP-_0040var_007bdir_007d-1267"><code>-P </code><var>dir</var></a>: <a href="#makeinfo-options">makeinfo options</a></li> -<li><a href="#index-g_t_002dp-_0040var_007bindent_007d-1269"><code>-p </code><var>indent</var></a>: <a href="#makeinfo-options">makeinfo options</a></li> -<li><a href="#index-g_t_002ds-_0040var_007bstyle_007d-1225"><code>-s </code><var>style</var></a>: <a href="#makeinfo-options">makeinfo options</a></li> -<li><a href="#index-g_t_002dV-1274"><code>-V</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> -<li><a href="#index-g_t_0040b_007b_002ecshrc_007d-initialization-file-1147"><b>.cshrc</b> initialization file</a>: <a href="#Preparing-for-TeX">Preparing for TeX</a></li> -<li><a href="#index-g_t_0040b_007b_002eprofile_007d-initialization-file-1146"><b>.profile</b> initialization file</a>: <a href="#Preparing-for-TeX">Preparing for TeX</a></li> -<li><a href="#index-g_t_0040L_007b_007d-738">/L</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-g_t_0040l_007b_007d-736">/l</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-g_t_0040O_007b_007d-742">Ø</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-g_t_0040o_007b_007d-740">ø</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-g_t8_002dbit-characters_002c-in-HTML-cross_002dreferences-1376">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-g_t_0040guilsinglleft_007b_007d-816">‹</a>: <a href="#Inserting-Quotation-Marks">Inserting Quotation Marks</a></li> -<li><a href="#index-g_t_0040guillemetleft_007b_007d-811">«</a>: <a href="#Inserting-Quotation-Marks">Inserting Quotation Marks</a></li> -<li><a href="#index-g_t_003cabbr_003e-tag-434"><abbr> tag</a>: <a href="#abbr">abbr</a></li> -<li><a href="#index-g_t_003cacronym_003e-tag-438"><acronym> tag</a>: <a href="#acronym">acronym</a></li> -<li><a href="#index-g_t_003cblockquote_003e-HTML-tag-479"><blockquote> HTML tag</a>: <a href="#quotation">quotation</a></li> -<li><a href="#index-g_t_003clineannotation_003e-Docbook-tag-474"><lineannotation> Docbook tag</a>: <a href="#Fonts">Fonts</a></li> -<li><a href="#index-g_t_0040code_007b_003cmeta_003e_007d-HTML-tag_002c-and-charset-specification-1055"><code><meta></code> HTML tag, and charset specification</a>: <a href="#documentencoding">documentencoding</a></li> -<li><a href="#index-g_t_003cmeta_003e-HTML-tag_002c-and-document-description-236"><meta> HTML tag, and document description</a>: <a href="#documentdescription">documentdescription</a></li> -<li><a href="#index-g_t_003cnote_003e-Docbook-tag-478"><note> Docbook tag</a>: <a href="#quotation">quotation</a></li> -<li><a href="#index-g_t_003csmall_003e-tag-450"><small> tag</a>: <a href="#Smallcaps">Smallcaps</a></li> -<li><a href="#index-g_t_003cthead_003e-HTML-tag-556"><thead> HTML tag</a>: <a href="#Multitable-Rows">Multitable Rows</a></li> -<li><a href="#index-g_t_003ctitle_003e-HTML-tag-173"><title> HTML tag</a>: <a href="#settitle">settitle</a></li> -<li><a href="#index-g_t_003cURL_003a-convention_002c-not-used-391"><URL: convention, not used</a>: <a href="#uref">uref</a></li> -<li><a href="#index-g_t_0040guilsinglright_007b_007d-818">›</a>: <a href="#Inserting-Quotation-Marks">Inserting Quotation Marks</a></li> -<li><a href="#index-g_t_0040guillemetright_007b_007d-814">»</a>: <a href="#Inserting-Quotation-Marks">Inserting Quotation Marks</a></li> -<li><a href="#index-g_t_0040questiondown_007b_007d-720">¿</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-g_t_0040samp_007b_0040_0040_007d-as-continuation-in-definition-commands-941">‘<samp><span class="samp">@</span></samp>’ as continuation in definition commands</a>: <a href="#Def-Cmd-Continuation-Lines">Def Cmd Continuation Lines</a></li> -<li><a href="#index-g_t_0040_0040_002dcommand-list-1383">@-command list</a>: <a href="#Command-List">Command List</a></li> -<li><a href="#index-g_t_0040_0040_002dcommand-syntax-1385">@-command syntax</a>: <a href="#Command-Syntax">Command Syntax</a></li> -<li><a href="#index-g_t_0040_0040_002dcommands-46">@-commands</a>: <a href="#Formatting-Commands">Formatting Commands</a></li> -<li><a href="#index-g_t_0040_0040_002dcommands-in-_0040_0040node_002c-limited-support-1280">@-commands in @node, limited support</a>: <a href="#Pointer-Validation">Pointer Validation</a></li> -<li><a href="#index-g_t_0040_0040_002dcommands-in-nodename-310">@-commands in nodename</a>: <a href="#Node-Line-Requirements">Node Line Requirements</a></li> -<li><a href="#index-g_t_0040_0040import-specifications_002c-in-CSS-files-1365">@import specifications, in CSS files</a>: <a href="#HTML-CSS">HTML CSS</a></li> -<li><a href="#index-g_t_0040code_007b_0040_0040include_007d-file-sample-1419"><code>@include</code> file sample</a>: <a href="#Sample-Include-File">Sample Include File</a></li> -<li><a href="#index-g_t_0040code_007b_0040_0040menu_007d-parts-350"><code>@menu</code> parts</a>: <a href="#Menu-Parts">Menu Parts</a></li> -<li><a href="#index-g_t_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-g_t_0040_0040value-in-_0040_0040node-lines-1281">@value in @node lines</a>: <a href="#Pointer-Validation">Pointer Validation</a></li> -<li><a href="#index-g_t_0040code_007b_0040_0040w_007d_002c-for-blank-items-527"><code>@w</code>, for blank items</a>: <a href="#itemize">itemize</a></li> -<li><a href="#index-g_t_0040samp_007b_005cinput_007d-source-line-ignored-167">‘<samp><span class="samp">\input</span></samp>’ source line ignored</a>: <a href="#setfilename">setfilename</a></li> -<li><a href="#index-g_t_0040samp_007b_005e_0040_0040_005eH_007d-for-images-in-Info-590">‘<samp><span class="samp">^@^H</span></samp>’ for images in Info</a>: <a href="#Image-Syntax">Image Syntax</a></li> -<li><a href="#index-g_t_005f_002c-breakpoint-within-_0040code_007b_0040_0040code_007d-908">_, breakpoint within <code>@code</code></a>: <a href="#allowcodebreaks">allowcodebreaks</a></li> -<li><a href="#index-g_t_0060-781">`</a>: <a href="#Inserting-Quotation-Marks">Inserting Quotation Marks</a></li> -<li><a href="#index-g_t_0040ordf_007b_007d-751">ª</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-A4-paper_002c-printing-on-1178">A4 paper, printing on</a>: <a href="#A4-Paper">A4 Paper</a></li> -<li><a href="#index-A5-paper_002c-printing-on-1179">A5 paper, printing on</a>: <a href="#A4-Paper">A4 Paper</a></li> -<li><a href="#index-g_t_0040AA_007b_007d-726">Å</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-g_t_0040aa_007b_007d-724">å</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-Abbreviations-for-keys-417">Abbreviations for keys</a>: <a href="#key">key</a></li> -<li><a href="#index-Abbreviations_002c-tagging-433">Abbreviations, tagging</a>: <a href="#abbr">abbr</a></li> -<li><a href="#index-Abstract-of-document-235">Abstract of document</a>: <a href="#documentdescription">documentdescription</a></li> -<li><a href="#index-Accents_002c-inserting-684">Accents, inserting</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-accesskey_0040r_007b_002c-in-HTML-output_007d-347"><code>accesskey</code><span class="roman">, in HTML output</span></a>: <a href="#Writing-a-Menu">Writing a Menu</a></li> -<li><a href="#index-accesskey_0040r_007b_002c-in-HTML-output_007d-301"><code>accesskey</code><span class="roman">, in HTML output</span></a>: <a href="#node">node</a></li> -<li><a href="#index-Acronyms_002c-tagging-437">Acronyms, tagging</a>: <a href="#acronym">acronym</a></li> -<li><a href="#index-Acute-accent-690">Acute accent</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-Adding-a-new-Info-file-1302">Adding a new Info file</a>: <a href="#New-Info-File">New Info File</a></li> -<li><a href="#index-g_t_0040AE_007b_007d-730">Æ</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-g_t_0040ae_007b_007d-728">æ</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-Aliases_002c-command-1088">Aliases, command</a>: <a href="#alias">alias</a></li> -<li><a href="#index-All_002dpermissive-copying-license-1410">All-permissive copying license</a>: <a href="#All_002dpermissive-Copying-License">All-permissive Copying License</a></li> -<li><a href="#index-Allow-line-break-898">Allow line break</a>: <a href="#Line-Breaks">Line Breaks</a></li> -<li><a href="#index-Alphabetical-_0040_0040_002dcommand-list-1381">Alphabetical @-command list</a>: <a href="#Command-List">Command List</a></li> -<li><a href="#index-Alt-attribute-for-images-585">Alt attribute for images</a>: <a href="#Image-Syntax">Image Syntax</a></li> -<li><a href="#index-Anchors-335">Anchors</a>: <a href="#anchor">anchor</a></li> -<li><a href="#index-Angle-quotation-marks-792">Angle quotation marks</a>: <a href="#Inserting-Quotation-Marks">Inserting Quotation Marks</a></li> -<li><a href="#index-Another-Info-directory-1309">Another Info directory</a>: <a href="#Other-Info-Directories">Other Info Directories</a></li> -<li><a href="#index-Arguments_002c-repeated-and-optional-947">Arguments, repeated and optional</a>: <a href="#Optional-Arguments">Optional Arguments</a></li> -<li><a href="#index-ASCII-text-output-1243">ASCII text output</a>: <a href="#makeinfo-options">makeinfo options</a></li> -<li><a href="#index-Aspect-ratio-of-images-595">Aspect ratio of images</a>: <a href="#Image-Scaling">Image Scaling</a></li> -<li><a href="#index-autoexec_002ebat-1314"><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-1402"><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-128">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-1113">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-1192">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-1070">Backslash in macros</a>: <a href="#Defining-Macros">Defining Macros</a></li> -<li><a href="#index-Backslash_002c-and-macros-1082">Backslash, and macros</a>: <a href="#Invoking-Macros">Invoking Macros</a></li> -<li><a href="#index-Badly-referenced-nodes-1467">Badly referenced nodes</a>: <a href="#Running-Info_002dValidate">Running Info-Validate</a></li> -<li><a href="#index-Bastard-title-page-194">Bastard title page</a>: <a href="#titlepage">titlepage</a></li> -<li><a href="#index-Batch-formatting-for-Info-1294">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-153">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-161">Beginning line of a Texinfo file</a>: <a href="#First-Line">First Line</a></li> -<li><a href="#index-Berry_002c-Karl-78">Berry, Karl</a>: <a href="#History">History</a></li> -<li><a href="#index-Big-points-600">Big points</a>: <a href="#Image-Scaling">Image Scaling</a></li> -<li><a href="#index-Black-rectangle-in-hardcopy-1168">Black rectangle in hardcopy</a>: <a href="#Overfull-hboxes">Overfull hboxes</a></li> -<li><a href="#index-Blank-lines-924">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-1066">Body of a macro</a>: <a href="#Defining-Macros">Defining Macros</a></li> -<li><a href="#index-Bold-font-459">Bold font</a>: <a href="#Fonts">Fonts</a></li> -<li><a href="#index-Bolio-89">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-1175">Book, printing small</a>: <a href="#smallbook">smallbook</a></li> -<li><a href="#index-border_002dpattern-973"><code>border-pattern</code></a>: <a href="#Object_002dOriented-Variables">Object-Oriented Variables</a></li> -<li><a href="#index-border_002dpattern-of-Window-979"><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-90">BoTeX</a>: <a href="#History">History</a></li> -<li><a href="#index-Box-with-rounded-corners-519">Box with rounded corners</a>: <a href="#cartouche">cartouche</a></li> -<li><a href="#index-Box_002c-ugly-black-in-hardcopy-1170">Box, ugly black in hardcopy</a>: <a href="#Overfull-hboxes">Overfull hboxes</a></li> -<li><a href="#index-Braces-and-argument-syntax-1388">Braces and argument syntax</a>: <a href="#Command-Syntax">Command Syntax</a></li> -<li><a href="#index-Braces_002c-in-macro-arguments-1084">Braces, in macro arguments</a>: <a href="#Invoking-Macros">Invoking Macros</a></li> -<li><a href="#index-Braces_002c-inserting-651">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-896">Breaks in a line</a>: <a href="#Line-Breaks">Line Breaks</a></li> -<li><a href="#index-Breaks_002c-within-_0040code_007b_0040_0040code_007d-904">Breaks, within <code>@code</code></a>: <a href="#allowcodebreaks">allowcodebreaks</a></li> -<li><a href="#index-Breve-accent-710">Breve accent</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-Buffer-formatting-and-printing-148">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-820">Bullets, inserting</a>: <a href="#Dots-Bullets">Dots Bullets</a></li> -<li><a href="#index-Captions_002c-for-floats-568">Captions, for floats</a>: <a href="#caption-shortcaption">caption shortcaption</a></li> -<li><a href="#index-Caron-accent-718">Caron accent</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-Cascading-Style-Sheets_002c-and-HTML-output-1364">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-404">Case, not altering in <code>@code</code></a>: <a href="#code">code</a></li> -<li><a href="#index-Catching-errors-with-Info-formatting-1454">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-1456">Catching errors with TeX formatting</a>: <a href="#Debugging-with-TeX">Debugging with TeX</a></li> -<li><a href="#index-Catching-mistakes-1449">Catching mistakes</a>: <a href="#Catching-Mistakes">Catching Mistakes</a></li> -<li><a href="#index-Categories_002c-choosing-1321">Categories, choosing</a>: <a href="#Installing-Dir-Entries">Installing Dir Entries</a></li> -<li><a href="#index-Caveats-for-macro-usage-1087">Caveats for macro usage</a>: <a href="#Macro-Details">Macro Details</a></li> -<li><a href="#index-Cedilla-accent-700">Cedilla accent</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-Centimeters-602">Centimeters</a>: <a href="#Image-Scaling">Image Scaling</a></li> -<li><a href="#index-Chapter-structuring-269">Chapter structuring</a>: <a href="#Structuring">Structuring</a></li> -<li><a href="#index-Chapters_002c-formatting-one-at-a-time-1116">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-1048">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-76">Chassell, Robert J.</a>: <a href="#History">History</a></li> -<li><a href="#index-Check-accent-717">Check accent</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-Checking-for-badly-referenced-nodes-1464">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-605">Ciceros</a>: <a href="#Image-Scaling">Image Scaling</a></li> -<li><a href="#index-Circumflex-accent-694">Circumflex accent</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-Click-sequences-862">Click sequences</a>: <a href="#Click-Sequences">Click Sequences</a></li> -<li><a href="#index-CM_002dSuper-fonts-773">CM-Super fonts</a>: <a href="#Inserting-Quotation-Marks">Inserting Quotation Marks</a></li> -<li><a href="#index-CM_002dSuper-fonts_002c-installing-1153">CM-Super fonts, installing</a>: <a href="#Preparing-for-TeX">Preparing for TeX</a></li> -<li><a href="#index-code_0040r_007b_002c-value-for-_0040code_007b_0040_0040kbdinputstyle_007d_007d-412"><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-944">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-1315">Colon, last in <samp><span class="env">INFOPATH</span></samp></a>: <a href="#Other-Info-Directories">Other Info Directories</a></li> -<li><a href="#index-Column-widths_002c-defining-for-multitables-545">Column widths, defining for multitables</a>: <a href="#Multitable-Column-Widths">Multitable Column Widths</a></li> -<li><a href="#index-Combining-indices-631">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-1083">Comma, in macro arguments</a>: <a href="#Invoking-Macros">Invoking Macros</a></li> -<li><a href="#index-Command-aliases-1089">Command aliases</a>: <a href="#alias">alias</a></li> -<li><a href="#index-Command-definitions-988">Command definitions</a>: <a href="#Sample-Function-Definition">Sample Function Definition</a></li> -<li><a href="#index-Command-names_002c-indicating-427">Command names, indicating</a>: <a href="#command">command</a></li> -<li><a href="#index-Command-syntax-1387">Command syntax</a>: <a href="#Command-Syntax">Command Syntax</a></li> -<li><a href="#index-Commands-to-insert-special-characters-648">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-1011">Commands using raw TeX</a>: <a href="#Raw-Formatter-Commands">Raw Formatter Commands</a></li> -<li><a href="#index-Commands_002c-inserting-them-97">Commands, inserting them</a>: <a href="#Inserting">Inserting</a></li> -<li><a href="#index-Commas_002c-inserting-654">Commas, inserting</a>: <a href="#Inserting-a-Comma">Inserting a Comma</a></li> -<li><a href="#index-Comments-63">Comments</a>: <a href="#Comments">Comments</a></li> -<li><a href="#index-Comments_002c-in-CSS-files-1366">Comments, in CSS files</a>: <a href="#HTML-CSS">HTML CSS</a></li> -<li><a href="#index-Compile-command-for-formatting-1139">Compile command for formatting</a>: <a href="#Compile_002dCommand">Compile-Command</a></li> -<li><a href="#index-Compressed-files_002c-reading-1325">Compressed files, reading</a>: <a href="#Invoking-install_002dinfo">Invoking install-info</a></li> -<li><a href="#index-Conditionally-visible-text-992">Conditionally visible text</a>: <a href="#Conditionals">Conditionals</a></li> -<li><a href="#index-Conditionals_002c-nested-1031">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-220">Contents, after title page</a>: <a href="#Contents">Contents</a></li> -<li><a href="#index-Contents_002c-Table-of-213">Contents, Table of</a>: <a href="#Contents">Contents</a></li> -<li><a href="#index-Contents_002dlike-outline-of-file-structure-118">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-939">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-986">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-176">Copying Permissions</a>: <a href="#Document-Permissions">Document Permissions</a></li> -<li><a href="#index-Copying-software-255">Copying software</a>: <a href="#Software-Copying-Permissions">Software Copying Permissions</a></li> -<li><a href="#index-Copying-text_002c-including-185">Copying text, including</a>: <a href="#insertcopying">insertcopying</a></li> -<li><a href="#index-Copyright-holder-for-FSF-works-181">Copyright holder for FSF works</a>: <a href="#copying">copying</a></li> -<li><a href="#index-Copyright-page-202">Copyright page</a>: <a href="#Copyright">Copyright</a></li> -<li><a href="#index-Copyright-page_002c-for-plain-text-189">Copyright page, for plain text</a>: <a href="#Titlepage-_0026-Copyright-Page">Titlepage & Copyright Page</a></li> -<li><a href="#index-Copyright-symbol-837">Copyright symbol</a>: <a href="#copyright-symbol">copyright symbol</a></li> -<li><a href="#index-Copyright-word_002c-always-in-English-179">Copyright word, always in English</a>: <a href="#copying">copying</a></li> -<li><a href="#index-Correcting-mistakes-1450">Correcting mistakes</a>: <a href="#Catching-Mistakes">Catching Mistakes</a></li> -<li><a href="#index-Country-codes-1044">Country codes</a>: <a href="#documentlanguage">documentlanguage</a></li> -<li><a href="#index-g_t_0040code_007bcp_007d-_0028concept_0029-index-617"><code>cp</code> (concept) index</a>: <a href="#Predefined-Indices">Predefined Indices</a></li> -<li><a href="#index-Create-nodes_002c-menus-automatically-126">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-1205">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-1471">Creating an unsplit file</a>: <a href="#Unsplit">Unsplit</a></li> -<li><a href="#index-Creating-index-entries-627">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-1196">Cropmarks for printing</a>: <a href="#Cropmarks-and-Magnification">Cropmarks and Magnification</a></li> -<li><a href="#index-Cross-reference-parts-367">Cross reference parts</a>: <a href="#Cross-Reference-Parts">Cross Reference Parts</a></li> -<li><a href="#index-Cross-references-364">Cross references</a>: <a href="#Cross-References">Cross References</a></li> -<li><a href="#index-Cross-references-using-_0040code_007b_0040_0040inforef_007d-383">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-379">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-374">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-370">Cross references using <code>@xref</code></a>: <a href="#xref">xref</a></li> -<li><a href="#index-Cross_002dreference-targets_002c-arbitrary-336">Cross-reference targets, arbitrary</a>: <a href="#anchor">anchor</a></li> -<li><a href="#index-Cross_002dreferences_002c-in-HTML-output-1368">Cross-references, in HTML output</a>: <a href="#HTML-Xref">HTML Xref</a></li> -<li><a href="#index-CSS_002c-and-HTML-output-1363">CSS, and HTML output</a>: <a href="#HTML-CSS">HTML CSS</a></li> -<li><a href="#index-Custom-page-sizes-1186">Custom page sizes</a>: <a href="#pagesizes">pagesizes</a></li> -<li><a href="#index-Customize-Emacs-package-_0028_0040t_007bDevelopment_002fDocs_002fTexinfo_007d_0029-1137">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-1092">Customized highlighting</a>: <a href="#definfoenclose">definfoenclose</a></li> -<li><a href="#index-Customizing-of-_0040TeX_007b_007d-for-Texinfo-1157">Customizing of TeX for Texinfo</a>: <a href="#Preparing-for-TeX">Preparing for TeX</a></li> -<li><a href="#index-CVS-_0024Id-1398">CVS $Id</a>: <a href="#GNU-Sample-Texts">GNU Sample Texts</a></li> -<li><a href="#index-Dash_002c-breakpoint-within-_0040code_007b_0040_0040code_007d-907">Dash, breakpoint within <code>@code</code></a>: <a href="#allowcodebreaks">allowcodebreaks</a></li> -<li><a href="#index-Dashes-in-source-58">Dashes in source</a>: <a href="#Conventions">Conventions</a></li> -<li><a href="#index-Debugging-the-Texinfo-structure-1453">Debugging the Texinfo structure</a>: <a href="#Catching-Mistakes">Catching Mistakes</a></li> -<li><a href="#index-Debugging-with-Info-formatting-1455">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-1457">Debugging with TeX formatting</a>: <a href="#Debugging-with-TeX">Debugging with TeX</a></li> -<li><a href="#index-Default-font-464">Default font</a>: <a href="#Fonts">Fonts</a></li> -<li><a href="#index-Defining-indexing-entries-623">Defining indexing entries</a>: <a href="#Indexing-Commands">Indexing Commands</a></li> -<li><a href="#index-Defining-macros-1061">Defining macros</a>: <a href="#Defining-Macros">Defining Macros</a></li> -<li><a href="#index-Defining-new-indices-640">Defining new indices</a>: <a href="#New-Indices">New Indices</a></li> -<li><a href="#index-Defining-new-Texinfo-commands-1057">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-940">Definition command headings, continuing</a>: <a href="#Def-Cmd-Continuation-Lines">Def Cmd Continuation Lines</a></li> -<li><a href="#index-Definition-commands-934">Definition commands</a>: <a href="#Definition-Commands">Definition Commands</a></li> -<li><a href="#index-Definition-conventions-985">Definition conventions</a>: <a href="#Def-Cmd-Conventions">Def Cmd Conventions</a></li> -<li><a href="#index-Definition-lists_002c-typesetting-533">Definition lists, typesetting</a>: <a href="#table">table</a></li> -<li><a href="#index-Definition-template-935">Definition template</a>: <a href="#Def-Cmd-Template">Def Cmd Template</a></li> -<li><a href="#index-Definitions-grouped-together-953">Definitions grouped together</a>: <a href="#deffnx">deffnx</a></li> -<li><a href="#index-Degree-symbol-849">Degree symbol</a>: <a href="#textdegree">textdegree</a></li> -<li><a href="#index-Delimiter-character_002c-for-verbatim-422">Delimiter character, for verbatim</a>: <a href="#verb">verb</a></li> -<li><a href="#index-Depth-of-text-area-1191">Depth of text area</a>: <a href="#pagesizes">pagesizes</a></li> -<li><a href="#index-Description-for-menu_002c-start-113">Description for menu, start</a>: <a href="#Inserting">Inserting</a></li> -<li><a href="#index-Description-of-document-233">Description of document</a>: <a href="#documentdescription">documentdescription</a></li> -<li><a href="#index-Detail-menu-332">Detail menu</a>: <a href="#makeinfo-Pointer-Creation">makeinfo Pointer Creation</a></li> -<li><a href="#index-Detailed-menu-230">Detailed menu</a>: <a href="#Master-Menu-Parts">Master Menu Parts</a></li> -<li><a href="#index-Details-of-macro-usage-1086">Details of macro usage</a>: <a href="#Macro-Details">Macro Details</a></li> -<li><a href="#index-Did_0040_005eot-points-604">Didôt points</a>: <a href="#Image-Scaling">Image Scaling</a></li> -<li><a href="#index-Different-cross-reference-commands-366">Different cross reference commands</a>: <a href="#Cross-Reference-Commands">Cross Reference Commands</a></li> -<li><a href="#index-Dimension-formatting-680">Dimension formatting</a>: <a href="#dmn">dmn</a></li> -<li><a href="#index-Dimensions-and-image-sizes-597">Dimensions and image sizes</a>: <a href="#Image-Scaling">Image Scaling</a></li> -<li><a href="#index-Dir-categories_002c-choosing-1320">Dir categories, choosing</a>: <a href="#Installing-Dir-Entries">Installing Dir Entries</a></li> -<li><a href="#index-g_t_0040file_007bdir_007d-directory-for-Info-installation-1301"><samp><span class="file">dir</span></samp> directory for Info installation</a>: <a href="#Installing-an-Info-File">Installing an Info File</a></li> -<li><a href="#index-g_t_0040file_007bdir_007d-file-listing-1306"><samp><span class="file">dir</span></samp> file listing</a>: <a href="#New-Info-File">New Info File</a></li> -<li><a href="#index-g_t_0040file_007bdir_007d-file_002c-creating-your-own-1316"><samp><span class="file">dir</span></samp> file, creating your own</a>: <a href="#Other-Info-Directories">Other Info Directories</a></li> -<li><a href="#index-g_t_0040file_007bdir_007d-files-and-Info-directories-1310"><samp><span class="file">dir</span></samp> files and Info directories</a>: <a href="#Other-Info-Directories">Other Info Directories</a></li> -<li><a href="#index-Dir-files_002c-compressed-1326">Dir files, compressed</a>: <a href="#Invoking-install_002dinfo">Invoking install-info</a></li> -<li><a href="#index-g_t_0040file_007bdir_007d_002c-created-by-_0040code_007binstall_002dinfo_007d-1324"><samp><span class="file">dir</span></samp>, created by <code>install-info</code></a>: <a href="#Invoking-install_002dinfo">Invoking install-info</a></li> -<li><a href="#index-Display-formatting-499">Display formatting</a>: <a href="#display">display</a></li> -<li><a href="#index-Displayed-equations-860">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-410"><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-596">Distorting images</a>: <a href="#Image-Scaling">Image Scaling</a></li> -<li><a href="#index-Distribution-256">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-1012">Docbook, including raw</a>: <a href="#Raw-Formatter-Commands">Raw Formatter Commands</a></li> -<li><a href="#index-Document-description-232">Document description</a>: <a href="#documentdescription">documentdescription</a></li> -<li><a href="#index-Document-input-encoding-1049">Document input encoding</a>: <a href="#documentencoding">documentencoding</a></li> -<li><a href="#index-Document-language_002c-declaring-1037">Document language, declaring</a>: <a href="#documentlanguage">documentlanguage</a></li> -<li><a href="#index-Document-Permissions-175">Document Permissions</a>: <a href="#Document-Permissions">Document Permissions</a></li> -<li><a href="#index-Document-strings_002c-translation-of-1038">Document strings, translation of</a>: <a href="#documentlanguage">documentlanguage</a></li> -<li><a href="#index-Documentation-identification-1400">Documentation identification</a>: <a href="#GNU-Sample-Texts">GNU Sample Texts</a></li> -<li><a href="#index-Dot-accent-702">Dot accent</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-Dotless-i_002c-j-734">Dotless i, j</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-Dots_002c-inserting-829">Dots, inserting</a>: <a href="#dots">dots</a></li> -<li><a href="#index-Dots_002c-inserting-819">Dots, inserting</a>: <a href="#Dots-Bullets">Dots Bullets</a></li> -<li><a href="#index-Double-angle-quotation-marks-801">Double angle quotation marks</a>: <a href="#Inserting-Quotation-Marks">Inserting Quotation Marks</a></li> -<li><a href="#index-Double-guillemets-799">Double guillemets</a>: <a href="#Inserting-Quotation-Marks">Inserting Quotation Marks</a></li> -<li><a href="#index-Double-left_002dpointing-angle-quotation-mark-805">Double left-pointing angle quotation mark</a>: <a href="#Inserting-Quotation-Marks">Inserting Quotation Marks</a></li> -<li><a href="#index-Double-low_002d9-quotation-mark-786">Double low-9 quotation mark</a>: <a href="#Inserting-Quotation-Marks">Inserting Quotation Marks</a></li> -<li><a href="#index-Double-quotation-marks-775">Double quotation marks</a>: <a href="#Inserting-Quotation-Marks">Inserting Quotation Marks</a></li> -<li><a href="#index-Double-right_002dpointing-angle-quotation-mark-806">Double right-pointing angle quotation mark</a>: <a href="#Inserting-Quotation-Marks">Inserting Quotation Marks</a></li> -<li><a href="#index-Double_002dcolon-menu-entries-352">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-1369">Dumas, Patrice</a>: <a href="#HTML-Xref">HTML Xref</a></li> -<li><a href="#index-Dumping-a-_002efmt-file-1161">Dumping a .fmt file</a>: <a href="#Preparing-for-TeX">Preparing for TeX</a></li> -<li><a href="#index-DVI-file-1106">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-EC-fonts-772">EC fonts</a>: <a href="#Inserting-Quotation-Marks">Inserting Quotation Marks</a></li> -<li><a href="#index-EC-fonts_002c-installing-1152">EC fonts, installing</a>: <a href="#Preparing-for-TeX">Preparing for TeX</a></li> -<li><a href="#index-Ellipsis_002c-inserting-821">Ellipsis, inserting</a>: <a href="#Dots-Bullets">Dots Bullets</a></li> -<li><a href="#index-Em-dash_002c-compared-to-minus-sign-852">Em dash, compared to minus sign</a>: <a href="#minus">minus</a></li> -<li><a href="#index-Em-dash_002c-producing-60">Em dash, producing</a>: <a href="#Conventions">Conventions</a></li> -<li><a href="#index-Emacs-94">Emacs</a>: <a href="#Texinfo-Mode">Texinfo Mode</a></li> -<li><a href="#index-Emacs-shell_002c-format_002c-print-from-1132">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-444">Emphasizing text</a>: <a href="#Emphasis">Emphasis</a></li> -<li><a href="#index-Emphasizing-text_002c-font-for-445">Emphasizing text, font for</a>: <a href="#emph-_0026-strong">emph & strong</a></li> -<li><a href="#index-En-dash_002c-producing-61">En dash, producing</a>: <a href="#Conventions">Conventions</a></li> -<li><a href="#index-Encoding_002c-declaring-1046">Encoding, declaring</a>: <a href="#documentencoding">documentencoding</a></li> -<li><a href="#index-g_t_0040samp_007b_0040r_007bEnd_007d_007d-node-footnote-style-611">‘<samp><span class="samp">End</span></samp>’ node footnote style</a>: <a href="#Footnote-Styles">Footnote Styles</a></li> -<li><a href="#index-End-of-header-line-174">End of header line</a>: <a href="#End-of-Header">End of Header</a></li> -<li><a href="#index-End-titlepage-starts-headings-210">End titlepage starts headings</a>: <a href="#end-titlepage">end titlepage</a></li> -<li><a href="#index-Ending-a-Sentence-664">Ending a Sentence</a>: <a href="#Ending-a-Sentence">Ending a Sentence</a></li> -<li><a href="#index-Ending-a-Texinfo-file-259">Ending a Texinfo file</a>: <a href="#Ending-a-File">Ending a File</a></li> -<li><a href="#index-Entries-for-an-index-625">Entries for an index</a>: <a href="#Indexing-Commands">Indexing Commands</a></li> -<li><a href="#index-Entries_002c-making-index-616">Entries, making index</a>: <a href="#Index-Entries">Index Entries</a></li> -<li><a href="#index-Enumeration-529">Enumeration</a>: <a href="#enumerate">enumerate</a></li> -<li><a href="#index-Environment-indentation-251">Environment indentation</a>: <a href="#exampleindent">exampleindent</a></li> -<li><a href="#index-Environment-variable-_0040code_007bINFOPATH_007d-1313">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-1277">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-1159">Environment variable <code>TEXINPUTS</code></a>: <a href="#Preparing-for-TeX">Preparing for TeX</a></li> -<li><a href="#index-eps-image-format-579"><code>eps image format</code></a>: <a href="#Image-Syntax">Image Syntax</a></li> -<li><a href="#index-epsf_002etex-608"><code>epsf.tex</code></a>: <a href="#Image-Scaling">Image Scaling</a></li> -<li><a href="#index-epsf_002etex_0040r_007b_002c-installing_007d-1150"><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-861">Equations, displayed</a>: <a href="#math">math</a></li> -<li><a href="#index-Equivalence_002c-indicating-883">Equivalence, indicating</a>: <a href="#Equivalence">Equivalence</a></li> -<li><a href="#index-Error-message_002c-indicating-881">Error message, indicating</a>: <a href="#Error-Glyph">Error Glyph</a></li> -<li><a href="#index-Errors_002c-parsing-1287">Errors, parsing</a>: <a href="#makeinfo-in-Emacs">makeinfo in Emacs</a></li> -<li><a href="#index-Es_002dzet-757">Es-zet</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-Euro-font-845">Euro font</a>: <a href="#euro">euro</a></li> -<li><a href="#index-Euro-font_002c-installing-1155">Euro font, installing</a>: <a href="#Preparing-for-TeX">Preparing for TeX</a></li> -<li><a href="#index-Euro-symbol-841">Euro symbol</a>: <a href="#euro">euro</a></li> -<li><a href="#index-European-A4-paper-1181">European A4 paper</a>: <a href="#A4-Paper">A4 Paper</a></li> -<li><a href="#index-European-Computer-Modern-fonts-771">European Computer Modern fonts</a>: <a href="#Inserting-Quotation-Marks">Inserting Quotation Marks</a></li> -<li><a href="#index-European-Computer-Modern-fonts_002c-installing-1151">European Computer Modern fonts, installing</a>: <a href="#Preparing-for-TeX">Preparing for TeX</a></li> -<li><a href="#index-Evaluation-glyph-873">Evaluation glyph</a>: <a href="#result">result</a></li> -<li><a href="#index-Example-beginning-of-Texinfo-file-157">Example beginning of Texinfo file</a>: <a href="#Sample-Beginning">Sample Beginning</a></li> -<li><a href="#index-Example-indentation-252">Example indentation</a>: <a href="#exampleindent">exampleindent</a></li> -<li><a href="#index-Example-menu-357">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-411"><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-493">Examples in smaller fonts</a>: <a href="#small">small</a></li> -<li><a href="#index-Examples_002c-formatting-them-480">Examples, formatting them</a>: <a href="#example">example</a></li> -<li><a href="#index-Examples_002c-glyphs-for-870">Examples, glyphs for</a>: <a href="#Glyphs">Glyphs</a></li> -<li><a href="#index-Expanding-macros-1079">Expanding macros</a>: <a href="#Invoking-Macros">Invoking Macros</a></li> -<li><a href="#index-Expansion-of-8_002dbit-characters-in-HTML-cross_002dreferences-1377">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-876">Expansion, indicating</a>: <a href="#expansion">expansion</a></li> -<li><a href="#index-expansion_002c-of-node-names-in-HTML-cross_002dreferences-1373">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-401">Expressions in a program, indicating</a>: <a href="#code">code</a></li> -<li><a href="#index-Feminine-ordinal-749">Feminine ordinal</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-feymr10-844"><code>feymr10</code></a>: <a href="#euro">euro</a></li> -<li><a href="#index-feymr10_0040r_007b_002c-installing_007d-1154"><code>feymr10</code><span class="roman">, installing</span></a>: <a href="#Preparing-for-TeX">Preparing for TeX</a></li> -<li><a href="#index-File-beginning-155">File beginning</a>: <a href="#Beginning-a-File">Beginning a File</a></li> -<li><a href="#index-File-ending-261">File ending</a>: <a href="#Ending-a-File">Ending a File</a></li> -<li><a href="#index-File-name-collision-169">File name collision</a>: <a href="#setfilename">setfilename</a></li> -<li><a href="#index-File-section-structure_002c-showing-it-119">File section structure, showing it</a>: <a href="#Showing-the-Structure">Showing the Structure</a></li> -<li><a href="#index-Final-output-1165">Final output</a>: <a href="#Overfull-hboxes">Overfull hboxes</a></li> -<li><a href="#index-Finding-badly-referenced-nodes-1466">Finding badly referenced nodes</a>: <a href="#Running-Info_002dValidate">Running Info-Validate</a></li> -<li><a href="#index-Fine_002dtuning_002c-and-hyphenation-902">Fine-tuning, and hyphenation</a>: <a href="#g_t_002d-and-hyphenation">- and hyphenation</a></li> -<li><a href="#index-First-line-of-a-Texinfo-file-160">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-244">First paragraph, suppressing indentation of</a>: <a href="#firstparagraphindent">firstparagraphindent</a></li> -<li><a href="#index-Fixed_002dwidth-font-472">Fixed-width font</a>: <a href="#Fonts">Fonts</a></li> -<li><a href="#index-Float-environment-561">Float environment</a>: <a href="#float">float</a></li> -<li><a href="#index-Floating-accents_002c-inserting-685">Floating accents, inserting</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-Floating_002c-not-yet-implemented-559">Floating, not yet implemented</a>: <a href="#Floats">Floats</a></li> -<li><a href="#index-Floats_002c-in-general-558">Floats, in general</a>: <a href="#Floats">Floats</a></li> -<li><a href="#index-Floats_002c-list-of-572">Floats, list of</a>: <a href="#listoffloats">listoffloats</a></li> -<li><a href="#index-Floats_002c-making-unnumbered-562">Floats, making unnumbered</a>: <a href="#float">float</a></li> -<li><a href="#index-Floats_002c-numbering-of-564">Floats, numbering of</a>: <a href="#float">float</a></li> -<li><a href="#index-Flooding-382">Flooding</a>: <a href="#pxref">pxref</a></li> -<li><a href="#index-g_t_0040code_007bfn_007d-_0028function_0029-index-618"><code>fn</code> (function) index</a>: <a href="#Predefined-Indices">Predefined Indices</a></li> -<li><a href="#index-Font-size_002c-reducing-453">Font size, reducing</a>: <a href="#Fonts">Fonts</a></li> -<li><a href="#index-Fonts-for-indices-638">Fonts for indices</a>: <a href="#syncodeindex">syncodeindex</a></li> -<li><a href="#index-Fonts-for-printing_002c-not-Info-451">Fonts for printing, not Info</a>: <a href="#Fonts">Fonts</a></li> -<li><a href="#index-Footings-1421">Footings</a>: <a href="#Headings">Headings</a></li> -<li><a href="#index-Footnotes-609">Footnotes</a>: <a href="#Footnotes">Footnotes</a></li> -<li><a href="#index-Force-line-break-897">Force line break</a>: <a href="#Line-Breaks">Line Breaks</a></li> -<li><a href="#index-Forcing-indentation-514">Forcing indentation</a>: <a href="#indent">indent</a></li> -<li><a href="#index-Forcing-line-and-page-breaks-887">Forcing line and page breaks</a>: <a href="#Breaks">Breaks</a></li> -<li><a href="#index-Format-a-dimension-681">Format a dimension</a>: <a href="#dmn">dmn</a></li> -<li><a href="#index-Format-and-print-hardcopy-1096">Format and print hardcopy</a>: <a href="#Hardcopy">Hardcopy</a></li> -<li><a href="#index-Format-and-print-in-Texinfo-mode-1135">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-1162">Format file, dumping</a>: <a href="#Preparing-for-TeX">Preparing for TeX</a></li> -<li><a href="#index-Format-with-the-compile-command-1140">Format with the compile command</a>: <a href="#Compile_002dCommand">Compile-Command</a></li> -<li><a href="#index-Format_002c-print-from-Emacs-shell-1130">Format, print from Emacs shell</a>: <a href="#Within-Emacs">Within Emacs</a></li> -<li><a href="#index-Formats-for-images-577">Formats for images</a>: <a href="#Image-Syntax">Image Syntax</a></li> -<li><a href="#index-Formatting-a-file-for-Info-1207">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-481">Formatting examples</a>: <a href="#example">example</a></li> -<li><a href="#index-Formatting-for-Info-140">Formatting for Info</a>: <a href="#Info-Formatting">Info Formatting</a></li> -<li><a href="#index-Formatting-for-printing-145">Formatting for printing</a>: <a href="#Printing">Printing</a></li> -<li><a href="#index-Formatting-headings-and-footings-1424">Formatting headings and footings</a>: <a href="#Headings">Headings</a></li> -<li><a href="#index-Formatting-requirements-1143">Formatting requirements</a>: <a href="#Requirements-Summary">Requirements Summary</a></li> -<li><a href="#index-Formatting-with-_0040code_007btex_007d-and-_0040code_007btexindex_007d-1105">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-858">Formulas, mathematical</a>: <a href="#math">math</a></li> -<li><a href="#index-Fox_002c-Brian-77">Fox, Brian</a>: <a href="#History">History</a></li> -<li><a href="#index-Free-Documentation-License_002c-including-entire-1407">Free Documentation License, including entire</a>: <a href="#GNU-Sample-Texts">GNU Sample Texts</a></li> -<li><a href="#index-Free-Software-Directory-1319">Free Software Directory</a>: <a href="#Installing-Dir-Entries">Installing Dir Entries</a></li> -<li><a href="#index-French-quotation-marks-795">French quotation marks</a>: <a href="#Inserting-Quotation-Marks">Inserting Quotation Marks</a></li> -<li><a href="#index-French-spacing-676">French spacing</a>: <a href="#frenchspacing">frenchspacing</a></li> -<li><a href="#index-Frequently-used-commands_002c-inserting-96">Frequently used commands, inserting</a>: <a href="#Inserting">Inserting</a></li> -<li><a href="#index-Frontmatter_002c-text-in-156">Frontmatter, text in</a>: <a href="#Beginning-a-File">Beginning a File</a></li> -<li><a href="#index-Full-texts_002c-GNU-1396">Full texts, GNU</a>: <a href="#GNU-Sample-Texts">GNU Sample Texts</a></li> -<li><a href="#index-Function-definitions-987">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-265">Generating menus with indices</a>: <a href="#Printing-Indices-_0026-Menus">Printing Indices & Menus</a></li> -<li><a href="#index-Generating-plain-text-files-1244">Generating plain text files</a>: <a href="#makeinfo-options">makeinfo options</a></li> -<li><a href="#index-German-quotation-marks-797">German quotation marks</a>: <a href="#Inserting-Quotation-Marks">Inserting Quotation Marks</a></li> -<li><a href="#index-German-S-759">German S</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-Global-Document-Commands-231">Global Document Commands</a>: <a href="#Global-Document-Commands">Global Document Commands</a></li> -<li><a href="#index-Globbing-1111">Globbing</a>: <a href="#Format-with-tex_002ftexindex">Format with tex/texindex</a></li> -<li><a href="#index-Glyphs-869">Glyphs</a>: <a href="#Glyphs">Glyphs</a></li> -<li><a href="#index-GNU-Emacs-93">GNU Emacs</a>: <a href="#Texinfo-Mode">Texinfo Mode</a></li> -<li><a href="#index-GNU-Emacs-shell_002c-format_002c-print-from-1133">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-1406">GNU Free Documentation License, including entire</a>: <a href="#GNU-Sample-Texts">GNU Sample Texts</a></li> -<li><a href="#index-GNU-sample-texts-1394">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-361">Going to other Info files' nodes</a>: <a href="#Other-Info-Files">Other Info Files</a></li> -<li><a href="#index-Grave-accent-696">Grave accent</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-Grave-accent_002c-vs_002e-left-quote-764">Grave accent, vs. left quote</a>: <a href="#Inserting-Quotation-Marks">Inserting Quotation Marks</a></li> -<li><a href="#index-Group-_0028hold-text-together-vertically_0029-928">Group (hold text together vertically)</a>: <a href="#group">group</a></li> -<li><a href="#index-Grouping-two-definitions-together-952">Grouping two definitions together</a>: <a href="#deffnx">deffnx</a></li> -<li><a href="#index-GUI-click-sequence-864">GUI click sequence</a>: <a href="#Click-Sequences">Click Sequences</a></li> -<li><a href="#index-Guillemets-793">Guillemets</a>: <a href="#Inserting-Quotation-Marks">Inserting Quotation Marks</a></li> -<li><a href="#index-Guillemots-794">Guillemots</a>: <a href="#Inserting-Quotation-Marks">Inserting Quotation Marks</a></li> -<li><a href="#index-Hacek-accent-716">Hacek accent</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-Hardcopy_002c-printing-it-1098">Hardcopy, printing it</a>: <a href="#Hardcopy">Hardcopy</a></li> -<li><a href="#index-g_t_0040samp_007bhboxes_007d_002c-overfull-1164">‘<samp><span class="samp">hboxes</span></samp>’, overfull</a>: <a href="#Overfull-hboxes">Overfull hboxes</a></li> -<li><a href="#index-Header-for-Texinfo-files-158">Header for Texinfo files</a>: <a href="#Texinfo-File-Header">Texinfo File Header</a></li> -<li><a href="#index-Header-of-a-Texinfo-file-162">Header of a Texinfo file</a>: <a href="#First-Line">First Line</a></li> -<li><a href="#index-Heading-row_002c-in-table-555">Heading row, in table</a>: <a href="#Multitable-Rows">Multitable Rows</a></li> -<li><a href="#index-Headings-1420">Headings</a>: <a href="#Headings">Headings</a></li> -<li><a href="#index-Headings_002c-indentation-after-248">Headings, indentation after</a>: <a href="#firstparagraphindent">firstparagraphindent</a></li> -<li><a href="#index-Headings_002c-page_002c-begin-to-appear-208">Headings, page, begin to appear</a>: <a href="#end-titlepage">end titlepage</a></li> -<li><a href="#index-Height-of-images-594">Height of images</a>: <a href="#Image-Scaling">Image Scaling</a></li> -<li><a href="#index-Height-of-text-area-1190">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-343">Hierarchical documents, and menus</a>: <a href="#Menu-Location">Menu Location</a></li> -<li><a href="#index-Highlighting-text-397">Highlighting text</a>: <a href="#Indicating">Indicating</a></li> -<li><a href="#index-Highlighting_002c-customized-1091">Highlighting, customized</a>: <a href="#definfoenclose">definfoenclose</a></li> -<li><a href="#index-Hints-1391">Hints</a>: <a href="#Tips">Tips</a></li> -<li><a href="#index-History-of-Texinfo-87">History of Texinfo</a>: <a href="#History">History</a></li> -<li><a href="#index-Holder-of-copyright-for-FSF-works-182">Holder of copyright for FSF works</a>: <a href="#copying">copying</a></li> -<li><a href="#index-Holding-text-together-vertically-929">Holding text together vertically</a>: <a href="#group">group</a></li> -<li><a href="#index-g_t_0040code_007bhref_007d_002c-producing-HTML-389"><code>href</code>, producing HTML</a>: <a href="#uref">uref</a></li> -<li><a href="#index-HTML-cross_002dreference-8_002dbit-character-expansion-1375">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-1374">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-1370">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-1379">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-1371">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-1367">HTML cross-references</a>: <a href="#HTML-Xref">HTML Xref</a></li> -<li><a href="#index-HTML-output-1356">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-1053">HTML output, and encodings</a>: <a href="#documentencoding">documentencoding</a></li> -<li><a href="#index-HTML-output_002c-browser-compatibility-of-1359">HTML output, browser compatibility of</a>: <a href="#HTML-Translation">HTML Translation</a></li> -<li><a href="#index-HTML-output_002c-split-1361">HTML output, split</a>: <a href="#HTML-Splitting">HTML Splitting</a></li> -<li><a href="#index-HTML_002c-and-CSS-1362">HTML, and CSS</a>: <a href="#HTML-CSS">HTML CSS</a></li> -<li><a href="#index-HTML_002c-including-raw-1013">HTML, including raw</a>: <a href="#Raw-Formatter-Commands">Raw Formatter Commands</a></li> -<li><a href="#index-g_t_0040code_007bhttp_002dequiv_007d_002c-and-charset-specification-1054"><code>http-equiv</code>, and charset specification</a>: <a href="#documentencoding">documentencoding</a></li> -<li><a href="#index-Hungarian-umlaut-accent-704">Hungarian umlaut accent</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-Hurricanes-377">Hurricanes</a>: <a href="#ref">ref</a></li> -<li><a href="#index-Hyphen_002c-breakpoint-within-_0040code_007b_0040_0040code_007d-906">Hyphen, breakpoint within <code>@code</code></a>: <a href="#allowcodebreaks">allowcodebreaks</a></li> -<li><a href="#index-Hyphen_002c-compared-to-minus-853">Hyphen, compared to minus</a>: <a href="#minus">minus</a></li> -<li><a href="#index-Hyphenation-patterns_002c-language_002ddependent-1040">Hyphenation patterns, language-dependent</a>: <a href="#documentlanguage">documentlanguage</a></li> -<li><a href="#index-Hyphenation_002c-helping-_0040TeX_007b_007d-do-901">Hyphenation, helping TeX do</a>: <a href="#g_t_002d-and-hyphenation">- and hyphenation</a></li> -<li><a href="#index-Hyphenation_002c-preventing-914">Hyphenation, preventing</a>: <a href="#w">w</a></li> -<li><a href="#index-Hyphens-in-source_002c-two-or-three-in-a-row-59">Hyphens in source, two or three in a row</a>: <a href="#Conventions">Conventions</a></li> -<li><a href="#index-g_t_0040dotless_007bi_007d-_0028dotless-i_0029-732">i (dotless i)</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-Identification-of-documentation-1401">Identification of documentation</a>: <a href="#GNU-Sample-Texts">GNU Sample Texts</a></li> -<li><a href="#index-If-text-conditionally-visible-995">If text conditionally visible</a>: <a href="#Conditionals">Conditionals</a></li> -<li><a href="#index-Ignored-before-_0040code_007b_0040_0040setfilename_007d-166">Ignored before <code>@setfilename</code></a>: <a href="#setfilename">setfilename</a></li> -<li><a href="#index-Ignored-text-66">Ignored text</a>: <a href="#Comments">Comments</a></li> -<li><a href="#index-Image-formats-578">Image formats</a>: <a href="#Image-Syntax">Image Syntax</a></li> -<li><a href="#index-Images_002c-alternate-text-for-586">Images, alternate text for</a>: <a href="#Image-Syntax">Image Syntax</a></li> -<li><a href="#index-Images_002c-inserting-574">Images, inserting</a>: <a href="#Images">Images</a></li> -<li><a href="#index-Images_002c-scaling-591">Images, scaling</a>: <a href="#Image-Scaling">Image Scaling</a></li> -<li><a href="#index-Inches-601">Inches</a>: <a href="#Image-Scaling">Image Scaling</a></li> -<li><a href="#index-Include-file-sample-1418">Include file sample</a>: <a href="#Sample-Include-File">Sample Include File</a></li> -<li><a href="#index-Include-files-1412">Include files</a>: <a href="#Include-Files">Include Files</a></li> -<li><a href="#index-Include-files-requirements-1415">Include files requirements</a>: <a href="#Include-Files-Requirements">Include Files Requirements</a></li> -<li><a href="#index-Include-files_002c-and-section-levels-298">Include files, and section levels</a>: <a href="#Raise_002flower-sections">Raise/lower sections</a></li> -<li><a href="#index-Including-a-file-verbatim-488">Including a file verbatim</a>: <a href="#verbatiminclude">verbatiminclude</a></li> -<li><a href="#index-Including-permissions-text-187">Including permissions text</a>: <a href="#insertcopying">insertcopying</a></li> -<li><a href="#index-Indentation-undoing-504">Indentation undoing</a>: <a href="#exdent">exdent</a></li> -<li><a href="#index-Indentation_002c-forcing-516">Indentation, forcing</a>: <a href="#indent">indent</a></li> -<li><a href="#index-Indentation_002c-omitting-512">Indentation, omitting</a>: <a href="#noindent">noindent</a></li> -<li><a href="#index-Indenting-environments-250">Indenting environments</a>: <a href="#exampleindent">exampleindent</a></li> -<li><a href="#index-Indenting-paragraphs_002c-control-of-241">Indenting paragraphs, control of</a>: <a href="#paragraphindent">paragraphindent</a></li> -<li><a href="#index-Indenting_002c-suppressing-of-first-paragraph-247">Indenting, suppressing of first paragraph</a>: <a href="#firstparagraphindent">firstparagraphindent</a></li> -<li><a href="#index-Index-entries-624">Index entries</a>: <a href="#Indexing-Commands">Indexing Commands</a></li> -<li><a href="#index-Index-entries_002c-making-615">Index entries, making</a>: <a href="#Index-Entries">Index Entries</a></li> -<li><a href="#index-Index-entry-writing-629">Index entry writing</a>: <a href="#Indexing-Commands">Indexing Commands</a></li> -<li><a href="#index-Index-file-names-1109">Index file names</a>: <a href="#Format-with-tex_002ftexindex">Format with tex/texindex</a></li> -<li><a href="#index-Index-font-types-630">Index font types</a>: <a href="#Indexing-Commands">Indexing Commands</a></li> -<li><a href="#index-Indexing-table-entries-automatically-537">Indexing table entries automatically</a>: <a href="#ftable-vtable">ftable vtable</a></li> -<li><a href="#index-Indicating-commands_002c-definitions_002c-etc_002e-398">Indicating commands, definitions, etc.</a>: <a href="#Indicating">Indicating</a></li> -<li><a href="#index-Indicating-evaluation-872">Indicating evaluation</a>: <a href="#result">result</a></li> -<li><a href="#index-Indices-614">Indices</a>: <a href="#Indices">Indices</a></li> -<li><a href="#index-Indices_002c-combining-them-632">Indices, combining them</a>: <a href="#Combining-Indices">Combining Indices</a></li> -<li><a href="#index-Indices_002c-defining-new-641">Indices, defining new</a>: <a href="#New-Indices">New Indices</a></li> -<li><a href="#index-Indices_002c-printing-and-menus-264">Indices, printing and menus</a>: <a href="#Printing-Indices-_0026-Menus">Printing Indices & Menus</a></li> -<li><a href="#index-Indices_002c-sorting-1101">Indices, sorting</a>: <a href="#Hardcopy">Hardcopy</a></li> -<li><a href="#index-Indices_002c-two-letter-names-636">Indices, two letter names</a>: <a href="#syncodeindex">syncodeindex</a></li> -<li><a href="#index-Indirect-subfiles-1298">Indirect subfiles</a>: <a href="#Tag-and-Split-Files">Tag and Split Files</a></li> -<li><a href="#index-Info-batch-formatting-1295">Info batch formatting</a>: <a href="#Batch-Formatting">Batch Formatting</a></li> -<li><a href="#index-Info-file-installation-1300">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-170">Info file name, choosing</a>: <a href="#setfilename">setfilename</a></li> -<li><a href="#index-Info-file_002c-listing-a-new-1305">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-1476">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-342">Info format, and menus</a>: <a href="#Menu-Location">Menu Location</a></li> -<li><a href="#index-Info-formatting-142">Info formatting</a>: <a href="#Info-Formatting">Info Formatting</a></li> -<li><a href="#index-Info-installed-in-another-directory-1308">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-1052">Info output, and encoding</a>: <a href="#documentencoding">documentencoding</a></li> -<li><a href="#index-Info-validating-a-large-file-1469">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-1206">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-1311"><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-362">Info; other files' nodes</a>: <a href="#Other-Info-Files">Other Info Files</a></li> -<li><a href="#index-INFOPATH-1312"><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-1148">Initialization file for TeX input</a>: <a href="#Preparing-for-TeX">Preparing for TeX</a></li> -<li><a href="#index-Input-encoding_002c-declaring-1047">Input encoding, declaring</a>: <a href="#documentencoding">documentencoding</a></li> -<li><a href="#index-Insert-nodes_002c-menus-automatically-127">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-650">Inserting @ <span class="roman">(literal ‘</span><samp><span class="samp">@</span></samp><span class="roman">’)</span></a>: <a href="#Inserting-an-Atsign">Inserting an Atsign</a></li> -<li><a href="#index-Inserting-accents-683">Inserting accents</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-Inserting-dots-828">Inserting dots</a>: <a href="#dots">dots</a></li> -<li><a href="#index-Inserting-dots-823">Inserting dots</a>: <a href="#Dots-Bullets">Dots Bullets</a></li> -<li><a href="#index-Inserting-ellipsis-822">Inserting ellipsis</a>: <a href="#Dots-Bullets">Dots Bullets</a></li> -<li><a href="#index-Inserting-frequently-used-commands-95">Inserting frequently used commands</a>: <a href="#Inserting">Inserting</a></li> -<li><a href="#index-Inserting-indentation-515">Inserting indentation</a>: <a href="#indent">indent</a></li> -<li><a href="#index-Inserting-quotation-marks-760">Inserting quotation marks</a>: <a href="#Inserting-Quotation-Marks">Inserting Quotation Marks</a></li> -<li><a href="#index-Inserting-quote-characters-656">Inserting quote characters</a>: <a href="#Inserting-Quote-Characters">Inserting Quote Characters</a></li> -<li><a href="#index-Inserting-space-658">Inserting space</a>: <a href="#Inserting-Space">Inserting Space</a></li> -<li><a href="#index-Inserting-special-characters-and-symbols-645">Inserting special characters and symbols</a>: <a href="#Insertions">Insertions</a></li> -<li><a href="#index-g_t_0040file_007bINSTALL_007d-file_002c-generating-1245"><samp><span class="file">INSTALL</span></samp> file, generating</a>: <a href="#makeinfo-options">makeinfo options</a></li> -<li><a href="#index-install_002dinfo-1323"><code>install-info</code></a>: <a href="#Invoking-install_002dinfo">Invoking install-info</a></li> -<li><a href="#index-Installing-an-Info-file-1299">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-1307">Installing Info in another directory</a>: <a href="#Other-Info-Directories">Other Info Directories</a></li> -<li><a href="#index-Internationalization-1033">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-258">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-1078">Invoking macros</a>: <a href="#Invoking-Macros">Invoking Macros</a></li> -<li><a href="#index-Invoking-nodes_002c-including-in-dir-file-1322">Invoking nodes, including in dir file</a>: <a href="#Installing-Dir-Entries">Installing Dir Entries</a></li> -<li><a href="#index-ISO-3166-country-codes-1042">ISO 3166 country codes</a>: <a href="#documentlanguage">documentlanguage</a></li> -<li><a href="#index-ISO-639_002d2-language-codes-1041">ISO 639-2 language codes</a>: <a href="#documentlanguage">documentlanguage</a></li> -<li><a href="#index-ISO-8859_002d1-769">ISO 8859-1</a>: <a href="#Inserting-Quotation-Marks">Inserting Quotation Marks</a></li> -<li><a href="#index-ISO-8859_002d15-842">ISO 8859-15</a>: <a href="#euro">euro</a></li> -<li><a href="#index-ISO-8859_002d15-767">ISO 8859-15</a>: <a href="#Inserting-Quotation-Marks">Inserting Quotation Marks</a></li> -<li><a href="#index-Italic-font-461">Italic font</a>: <a href="#Fonts">Fonts</a></li> -<li><a href="#index-Itemization-525">Itemization</a>: <a href="#itemize">itemize</a></li> -<li><a href="#index-g_t_0040dotless_007bj_007d-_0028dotless-j_0029-733">j (dotless j)</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-JPEG-image-format-589">JPEG image format</a>: <a href="#Image-Syntax">Image Syntax</a></li> -<li><a href="#index-jpeg-image-format-582"><code>jpeg image format</code></a>: <a href="#Image-Syntax">Image Syntax</a></li> -<li><a href="#index-Keyboard-input-406">Keyboard input</a>: <a href="#kbd">kbd</a></li> -<li><a href="#index-Keys_002c-recommended-names-415">Keys, recommended names</a>: <a href="#key">key</a></li> -<li><a href="#index-Keyword-expansion_002c-preventing-915">Keyword expansion, preventing</a>: <a href="#w">w</a></li> -<li><a href="#index-Keywords_002c-indicating-402">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-g_t_0040code_007bky_007d-_0028keystroke_0029-index-619"><code>ky</code> (keystroke) index</a>: <a href="#Predefined-Indices">Predefined Indices</a></li> -<li><a href="#index-LANG-1219"><code>LANG</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> -<li><a href="#index-Language-codes-1043">Language codes</a>: <a href="#documentlanguage">documentlanguage</a></li> -<li><a href="#index-Language_002c-declaring-1035">Language, declaring</a>: <a href="#documentlanguage">documentlanguage</a></li> -<li><a href="#index-Larger-or-smaller-pages-1200">Larger or smaller pages</a>: <a href="#Cropmarks-and-Magnification">Cropmarks and Magnification</a></li> -<li><a href="#index-g_t_0040LaTeX_007b_007d-logo-835">LaTeX logo</a>: <a href="#tex">tex</a></li> -<li><a href="#index-g_t_0040LaTeX_007b_007d_002c-processing-with-_0040command_007btexi2dvi_007d-1120">LaTeX, processing with <samp><span class="command">texi2dvi</span></samp></a>: <a href="#Format-with-texi2dvi">Format with texi2dvi</a></li> -<li><a href="#index-Latin-1-770">Latin 1</a>: <a href="#Inserting-Quotation-Marks">Inserting Quotation Marks</a></li> -<li><a href="#index-Latin-9-843">Latin 9</a>: <a href="#euro">euro</a></li> -<li><a href="#index-Latin-9-768">Latin 9</a>: <a href="#Inserting-Quotation-Marks">Inserting Quotation Marks</a></li> -<li><a href="#index-Left-quotation-marks-776">Left quotation marks</a>: <a href="#Inserting-Quotation-Marks">Inserting Quotation Marks</a></li> -<li><a href="#index-Left_002dpointing-angle-quotation-marks-803">Left-pointing angle quotation marks</a>: <a href="#Inserting-Quotation-Marks">Inserting Quotation Marks</a></li> -<li><a href="#index-Legal-paper_002c-printing-on-1193">Legal paper, printing on</a>: <a href="#pagesizes">pagesizes</a></li> -<li><a href="#index-Length-of-file-names-168">Length of file names</a>: <a href="#setfilename">setfilename</a></li> -<li><a href="#index-Less-cluttered-menu-entry-354">Less cluttered menu entry</a>: <a href="#Less-Cluttered-Menu-Entry">Less Cluttered Menu Entry</a></li> -<li><a href="#index-License-agreement-257">License agreement</a>: <a href="#Software-Copying-Permissions">Software Copying Permissions</a></li> -<li><a href="#index-License-for-all_002dpermissive-copying-1411">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-1409">License for verbatim copying</a>: <a href="#Verbatim-Copying-License">Verbatim Copying License</a></li> -<li><a href="#index-Line-breaks-895">Line breaks</a>: <a href="#Line-Breaks">Line Breaks</a></li> -<li><a href="#index-Line-breaks-890">Line breaks</a>: <a href="#Breaks">Breaks</a></li> -<li><a href="#index-Line-breaks_002c-preventing-911">Line breaks, preventing</a>: <a href="#w">w</a></li> -<li><a href="#index-Line-length_002c-column-widths-as-fraction-of-548">Line length, column widths as fraction of</a>: <a href="#Multitable-Column-Widths">Multitable Column Widths</a></li> -<li><a href="#index-Line-spacing-925">Line spacing</a>: <a href="#sp">sp</a></li> -<li><a href="#index-Lisp-example-491">Lisp example</a>: <a href="#lisp">lisp</a></li> -<li><a href="#index-Lisp-examples-in-smaller-fonts-494">Lisp examples in smaller fonts</a>: <a href="#small">small</a></li> -<li><a href="#index-List-of--_0040_0040_002dcommands-1382">List of @-commands</a>: <a href="#Command-List">Command List</a></li> -<li><a href="#index-List-of-floats-571">List of floats</a>: <a href="#listoffloats">listoffloats</a></li> -<li><a href="#index-Listing-a-new-Info-file-1303">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-522">Lists and tables, making</a>: <a href="#Lists-and-Tables">Lists and Tables</a></li> -<li><a href="#index-Local-variables-1138">Local variables</a>: <a href="#Compile_002dCommand">Compile-Command</a></li> -<li><a href="#index-Local-Variables_003a-section_002c-for-encoding-1051">Local Variables: section, for encoding</a>: <a href="#documentencoding">documentencoding</a></li> -<li><a href="#index-Locale_002c-declaring-1036">Locale, declaring</a>: <a href="#documentlanguage">documentlanguage</a></li> -<li><a href="#index-Location-of-menus-341">Location of menus</a>: <a href="#Menu-Location">Menu Location</a></li> -<li><a href="#index-Logos_002c-_0040TeX_007b_007d-833">Logos, TeX</a>: <a href="#tex">tex</a></li> -<li><a href="#index-Looking-for-badly-referenced-nodes-1465">Looking for badly referenced nodes</a>: <a href="#Running-Info_002dValidate">Running Info-Validate</a></li> -<li><a href="#index-Lowering-and-raising-sections-296">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-1125"><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-1128"><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-1062">Macro definitions</a>: <a href="#Defining-Macros">Defining Macros</a></li> -<li><a href="#index-Macro-definitions-989">Macro definitions</a>: <a href="#Sample-Function-Definition">Sample Function Definition</a></li> -<li><a href="#index-Macro-details-1085">Macro details</a>: <a href="#Macro-Details">Macro Details</a></li> -<li><a href="#index-Macro-expansion_002c-indicating-877">Macro expansion, indicating</a>: <a href="#expansion">expansion</a></li> -<li><a href="#index-Macro-invocation-1081">Macro invocation</a>: <a href="#Invoking-Macros">Invoking Macros</a></li> -<li><a href="#index-Macro-names_002c-valid-characters-in-1064">Macro names, valid characters in</a>: <a href="#Defining-Macros">Defining Macros</a></li> -<li><a href="#index-Macron-accent-692">Macron accent</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-Macros-1056">Macros</a>: <a href="#Defining-New-Texinfo-Commands">Defining New Texinfo Commands</a></li> -<li><a href="#index-Macros-in-definition-commands-938">Macros in definition commands</a>: <a href="#Def-Cmd-Template">Def Cmd Template</a></li> -<li><a href="#index-Macros_002c-undefining-1076">Macros, undefining</a>: <a href="#Defining-Macros">Defining Macros</a></li> -<li><a href="#index-Magnified-printing-1199">Magnified printing</a>: <a href="#Cropmarks-and-Magnification">Cropmarks and Magnification</a></li> -<li><a href="#index-Mailto-link-443">Mailto link</a>: <a href="#email">email</a></li> -<li><a href="#index-makeinfo-1208"><code>makeinfo</code></a>: <a href="#Invoking-makeinfo">Invoking makeinfo</a></li> -<li><a href="#index-g_t_0040code_007bmakeinfo_007d-inside-Emacs-1283"><code>makeinfo</code> inside Emacs</a>: <a href="#makeinfo-in-Emacs">makeinfo in Emacs</a></li> -<li><a href="#index-g_t_0040code_007bmakeinfo_007d-options-1209"><code>makeinfo</code> options</a>: <a href="#makeinfo-options">makeinfo options</a></li> -<li><a href="#index-Making-a-printed-manual-1099">Making a printed manual</a>: <a href="#Hardcopy">Hardcopy</a></li> -<li><a href="#index-Making-a-tag-table-automatically-1296">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-1473">Making a tag table manually</a>: <a href="#Unsplit">Unsplit</a></li> -<li><a href="#index-Making-cross-references-363">Making cross references</a>: <a href="#Cross-References">Cross References</a></li> -<li><a href="#index-Making-line-and-page-breaks-888">Making line and page breaks</a>: <a href="#Breaks">Breaks</a></li> -<li><a href="#index-Making-lists-and-tables-521">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-390">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-1194">Margins on page, not controllable</a>: <a href="#pagesizes">pagesizes</a></li> -<li><a href="#index-Marking-text-within-a-paragraph-395">Marking text within a paragraph</a>: <a href="#Marking-Text">Marking Text</a></li> -<li><a href="#index-Marking-words-and-phrases-393">Marking words and phrases</a>: <a href="#Marking-Text">Marking Text</a></li> -<li><a href="#index-Masculine-ordinal-752">Masculine ordinal</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-Master-menu-226">Master menu</a>: <a href="#Master-Menu-Parts">Master Menu Parts</a></li> -<li><a href="#index-Mathematical-expressions-1018">Mathematical expressions</a>: <a href="#Raw-Formatter-Commands">Raw Formatter Commands</a></li> -<li><a href="#index-Mathematical-expressions-857">Mathematical expressions</a>: <a href="#math">math</a></li> -<li><a href="#index-Menu-description_002c-start-112">Menu description, start</a>: <a href="#Inserting">Inserting</a></li> -<li><a href="#index-Menu-entries-with-two-colons-353">Menu entries with two colons</a>: <a href="#Less-Cluttered-Menu-Entry">Less Cluttered Menu Entry</a></li> -<li><a href="#index-Menu-example-356">Menu example</a>: <a href="#Menu-Example">Menu Example</a></li> -<li><a href="#index-Menu-location-340">Menu location</a>: <a href="#Menu-Location">Menu Location</a></li> -<li><a href="#index-Menu-parts-349">Menu parts</a>: <a href="#Menu-Parts">Menu Parts</a></li> -<li><a href="#index-Menu-writing-345">Menu writing</a>: <a href="#Writing-a-Menu">Writing a Menu</a></li> -<li><a href="#index-Menu_002c-master-227">Menu, master</a>: <a href="#Master-Menu-Parts">Master Menu Parts</a></li> -<li><a href="#index-Menus-338">Menus</a>: <a href="#Menus">Menus</a></li> -<li><a href="#index-Menus-generated-with-indices-266">Menus generated with indices</a>: <a href="#Printing-Indices-_0026-Menus">Printing Indices & Menus</a></li> -<li><a href="#index-Menus_002c-omitting-1247">Menus, omitting</a>: <a href="#makeinfo-options">makeinfo options</a></li> -<li><a href="#index-META-key-418">META key</a>: <a href="#key">key</a></li> -<li><a href="#index-Meta_002dsyntactic-chars-for-arguments-949">Meta-syntactic chars for arguments</a>: <a href="#Optional-Arguments">Optional Arguments</a></li> -<li><a href="#index-Methods_002c-object_002doriented-980">Methods, object-oriented</a>: <a href="#Object_002dOriented-Methods">Object-Oriented Methods</a></li> -<li><a href="#index-Millimeters-603">Millimeters</a>: <a href="#Image-Scaling">Image Scaling</a></li> -<li><a href="#index-Minimal-requirements-for-formatting-1142">Minimal requirements for formatting</a>: <a href="#Requirements-Summary">Requirements Summary</a></li> -<li><a href="#index-Minimal-Texinfo-file-_0028requirements_0029-69">Minimal Texinfo file (requirements)</a>: <a href="#Minimum">Minimum</a></li> -<li><a href="#index-Minus-sign-851">Minus sign</a>: <a href="#minus">minus</a></li> -<li><a href="#index-Mismatched-HTML-cross_002dreference-source-and-target-1380">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-1451">Mistakes, catching</a>: <a href="#Catching-Mistakes">Catching Mistakes</a></li> -<li><a href="#index-Mode_002c-using-Texinfo-92">Mode, using Texinfo</a>: <a href="#Texinfo-Mode">Texinfo Mode</a></li> -<li><a href="#index-Monospace-font-471">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-57">Multiple dashes in source</a>: <a href="#Conventions">Conventions</a></li> -<li><a href="#index-Multiple-spaces-669">Multiple spaces</a>: <a href="#Multiple-Spaces">Multiple Spaces</a></li> -<li><a href="#index-Multitable-column-widths-544">Multitable column widths</a>: <a href="#Multitable-Column-Widths">Multitable Column Widths</a></li> -<li><a href="#index-Multitable-rows-550">Multitable rows</a>: <a href="#Multitable-Rows">Multitable Rows</a></li> -<li><a href="#index-Must-have-in-Texinfo-file-70">Must have in Texinfo file</a>: <a href="#Minimum">Minimum</a></li> -<li><a href="#index-Mutually-recursive-macros-1067">Mutually recursive macros</a>: <a href="#Defining-Macros">Defining Macros</a></li> -<li><a href="#index-Names-for-indices-637">Names for indices</a>: <a href="#syncodeindex">syncodeindex</a></li> -<li><a href="#index-Names-of-index-files-1108">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-1065">Names of macros, valid characters of</a>: <a href="#Defining-Macros">Defining Macros</a></li> -<li><a href="#index-Names-recommended-for-keys-416">Names recommended for keys</a>: <a href="#key">key</a></li> -<li><a href="#index-Naming-a-_0060Top_0027-Node-in-references-372">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-436">NASA, as acronym</a>: <a href="#acronym">acronym</a></li> -<li><a href="#index-Navigation-bar_002c-in-HTML-output-1358">Navigation bar, in HTML output</a>: <a href="#HTML-Translation">HTML Translation</a></li> -<li><a href="#index-Navigation-links_002c-omitting-1248">Navigation links, omitting</a>: <a href="#makeinfo-options">makeinfo options</a></li> -<li><a href="#index-Need-space-at-page-bottom-932">Need space at page bottom</a>: <a href="#need">need</a></li> -<li><a href="#index-Nesting-conditionals-1032">Nesting conditionals</a>: <a href="#Conditional-Nesting">Conditional Nesting</a></li> -<li><a href="#index-New-index-defining-642">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-1304">New Info file, listing it in <samp><span class="file">dir</span></samp> file</a>: <a href="#New-Info-File">New Info File</a></li> -<li><a href="#index-New-Texinfo-commands_002c-defining-1058">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-1372">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-1246">Node separators, omitting</a>: <a href="#makeinfo-options">makeinfo options</a></li> -<li><a href="#index-Node_002c-_0060Top_0027-223">Node, `Top'</a>: <a href="#The-Top-Node">The Top Node</a></li> -<li><a href="#index-Node_002c-defined-299">Node, defined</a>: <a href="#node">node</a></li> -<li><a href="#index-Nodes-in-other-Info-files-359">Nodes in other Info files</a>: <a href="#Other-Info-Files">Other Info Files</a></li> -<li><a href="#index-Nodes_002c-catching-mistakes-1448">Nodes, catching mistakes</a>: <a href="#Catching-Mistakes">Catching Mistakes</a></li> -<li><a href="#index-Nodes_002c-checking-for-badly-referenced-1463">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-912">Non-breakable space, fixed</a>: <a href="#w">w</a></li> -<li><a href="#index-Non_002dbreakable-space_002c-variable-920">Non-breakable space, variable</a>: <a href="#tie">tie</a></li> -<li><a href="#index-Not-ending-a-sentence-660">Not ending a sentence</a>: <a href="#Not-Ending-a-Sentence">Not Ending a Sentence</a></li> -<li><a href="#index-Numbering-of-floats-565">Numbering of floats</a>: <a href="#float">float</a></li> -<li><a href="#index-g_t_0040ordm_007b_007d-754">º</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-970">Object-oriented programming</a>: <a href="#Abstract-Objects">Abstract Objects</a></li> -<li><a href="#index-Oblique-font-469">Oblique font</a>: <a href="#Fonts">Fonts</a></li> -<li><a href="#index-Obtaining-_0040TeX_007b_007d-1203">Obtaining TeX</a>: <a href="#Obtaining-TeX">Obtaining TeX</a></li> -<li><a href="#index-Occurrences_002c-listing-with-_0040code_007b_0040_0040occur_007d-1460">Occurrences, listing with <code>@occur</code></a>: <a href="#Using-occur">Using occur</a></li> -<li><a href="#index-g_t_0040OE_007b_007d-746">Œ</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-g_t_0040oe_007b_007d-744">œ</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-Omitting-indentation-510">Omitting indentation</a>: <a href="#noindent">noindent</a></li> -<li><a href="#index-Optional-and-repeated-arguments-945">Optional and repeated arguments</a>: <a href="#Optional-Arguments">Optional Arguments</a></li> -<li><a href="#index-Options-for-_0040code_007bmakeinfo_007d-1210">Options for <code>makeinfo</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> -<li><a href="#index-Ordinals_002c-Romance-748">Ordinals, Romance</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-Ordinary-_0040TeX_007b_007d-commands_002c-using-1010">Ordinary TeX commands, using</a>: <a href="#Raw-Formatter-Commands">Raw Formatter Commands</a></li> -<li><a href="#index-Other-Info-files_0027-nodes-360">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-117">Outline of file structure, showing it</a>: <a href="#Showing-the-Structure">Showing the Structure</a></li> -<li><a href="#index-Output-file-splitting-1259">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-1163">Overfull ‘<samp><span class="samp">hboxes</span></samp>’</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-183">Owner of copyright for FSF works</a>: <a href="#copying">copying</a></li> -<li><a href="#index-Page-breaks-926">Page breaks</a>: <a href="#page">page</a></li> -<li><a href="#index-Page-breaks-892">Page breaks</a>: <a href="#Breaks">Breaks</a></li> -<li><a href="#index-Page-delimiter-in-Texinfo-mode-124">Page delimiter in Texinfo mode</a>: <a href="#Showing-the-Structure">Showing the Structure</a></li> -<li><a href="#index-Page-headings-1423">Page headings</a>: <a href="#Headings">Headings</a></li> -<li><a href="#index-Page-numbering-1422">Page numbering</a>: <a href="#Headings">Headings</a></li> -<li><a href="#index-Page-sizes-for-books-1176">Page sizes for books</a>: <a href="#smallbook">smallbook</a></li> -<li><a href="#index-Page-sizes_002c-customized-1187">Page sizes, customized</a>: <a href="#pagesizes">pagesizes</a></li> -<li><a href="#index-page_002ddelimiter-123"><code>page-delimiter</code></a>: <a href="#Showing-the-Structure">Showing the Structure</a></li> -<li><a href="#index-Pages_002c-starting-odd-239">Pages, starting odd</a>: <a href="#setchapternewpage">setchapternewpage</a></li> -<li><a href="#index-Paper-size_002c-A4-1180">Paper size, A4</a>: <a href="#A4-Paper">A4 Paper</a></li> -<li><a href="#index-Paragraph-indentation-control-242">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-392">Paragraph, marking text within</a>: <a href="#Marking-Text">Marking Text</a></li> -<li><a href="#index-Parameters-to-macros-1069">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-1288">Parsing errors</a>: <a href="#makeinfo-in-Emacs">makeinfo in Emacs</a></li> -<li><a href="#index-Part-of-file-formatting-and-printing-149">Part of file formatting and printing</a>: <a href="#Printing">Printing</a></li> -<li><a href="#index-Parts-of-a-cross-reference-368">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-228">Parts of a master menu</a>: <a href="#Master-Menu-Parts">Master Menu Parts</a></li> -<li><a href="#index-Parts-of-a-menu-348">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-image-inclusions-583"><code>pdf image inclusions</code></a>: <a href="#Image-Syntax">Image Syntax</a></li> -<li><a href="#index-PDF-output-1201">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-pdftex-1202"><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-580"><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-662">Periods, inserting</a>: <a href="#Not-Ending-a-Sentence">Not Ending a Sentence</a></li> -<li><a href="#index-Permissions-text_002c-including-186">Permissions text, including</a>: <a href="#insertcopying">insertcopying</a></li> -<li><a href="#index-Permissions_002c-printed-204">Permissions, printed</a>: <a href="#Copyright">Copyright</a></li> -<li><a href="#index-g_t_0040code_007bpg_007d-_0028program_0029-index-620"><code>pg</code> (program) index</a>: <a href="#Predefined-Indices">Predefined Indices</a></li> -<li><a href="#index-Picas-599">Picas</a>: <a href="#Image-Scaling">Image Scaling</a></li> -<li><a href="#index-Pictures_002c-inserting-575">Pictures, inserting</a>: <a href="#Images">Images</a></li> -<li><a href="#index-Pinard_002c-Fran_0040_002c_007bc_007dois-79">Pinard, François</a>: <a href="#History">History</a></li> -<li><a href="#index-Plain-_0040TeX_007b_007d-1015">Plain TeX</a>: <a href="#Raw-Formatter-Commands">Raw Formatter Commands</a></li> -<li><a href="#index-Plain-text-output-1242">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-588">PNG image format</a>: <a href="#Image-Syntax">Image Syntax</a></li> -<li><a href="#index-png-image-format-581"><code>png image format</code></a>: <a href="#Image-Syntax">Image Syntax</a></li> -<li><a href="#index-Point_002c-indicating-in-a-buffer-885">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-1278">Pointer validation with <code>makeinfo</code></a>: <a href="#Pointer-Validation">Pointer Validation</a></li> -<li><a href="#index-Pointer-validation_002c-suppressing-1262">Pointer validation, suppressing</a>: <a href="#makeinfo-options">makeinfo options</a></li> -<li><a href="#index-Pointer-validation_002c-suppressing-1115">Pointer validation, suppressing</a>: <a href="#Format-with-tex_002ftexindex">Format with tex/texindex</a></li> -<li><a href="#index-Points-_0028dimension_0029-598">Points (dimension)</a>: <a href="#Image-Scaling">Image Scaling</a></li> -<li><a href="#index-Pounds-symbol-847">Pounds symbol</a>: <a href="#pounds">pounds</a></li> -<li><a href="#index-Predefined-names-for-indices-634">Predefined names for indices</a>: <a href="#syncodeindex">syncodeindex</a></li> -<li><a href="#index-Preparing-for-_0040TeX_007b_007d-1144">Preparing for TeX</a>: <a href="#Preparing-for-TeX">Preparing for TeX</a></li> -<li><a href="#index-Prev-node-of-Top-node-326">Prev node of Top node</a>: <a href="#First-Node">First Node</a></li> -<li><a href="#index-Preventing-first-paragraph-indentation-246">Preventing first paragraph indentation</a>: <a href="#firstparagraphindent">firstparagraphindent</a></li> -<li><a href="#index-Preventing-line-and-page-breaks-889">Preventing line and page breaks</a>: <a href="#Breaks">Breaks</a></li> -<li><a href="#index-Print-and-format-in-Texinfo-mode-1136">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-1129">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-879">Printed output, indicating</a>: <a href="#Print-Glyph">Print Glyph</a></li> -<li><a href="#index-Printed-permissions-203">Printed permissions</a>: <a href="#Copyright">Copyright</a></li> -<li><a href="#index-Printing-a-region-or-buffer-146">Printing a region or buffer</a>: <a href="#Printing">Printing</a></li> -<li><a href="#index-Printing-an-index-263">Printing an index</a>: <a href="#Printing-Indices-_0026-Menus">Printing Indices & Menus</a></li> -<li><a href="#index-Printing-cost_002c-reducing-456">Printing cost, reducing</a>: <a href="#Fonts">Fonts</a></li> -<li><a href="#index-Printing-cropmarks-1197">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-1127">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-1097">Printing hardcopy</a>: <a href="#Hardcopy">Hardcopy</a></li> -<li><a href="#index-Problems_002c-catching-1452">Problems, catching</a>: <a href="#Catching-Mistakes">Catching Mistakes</a></li> -<li><a href="#index-Program-names_002c-indicating-428">Program names, indicating</a>: <a href="#command">command</a></li> -<li><a href="#index-Prototype-row_002c-column-widths-defined-by-549">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-762">Quotation characters (`'), in source</a>: <a href="#Inserting-Quotation-Marks">Inserting Quotation Marks</a></li> -<li><a href="#index-Quotation-marks_002c-French-796">Quotation marks, French</a>: <a href="#Inserting-Quotation-Marks">Inserting Quotation Marks</a></li> -<li><a href="#index-Quotation-marks_002c-German-798">Quotation marks, German</a>: <a href="#Inserting-Quotation-Marks">Inserting Quotation Marks</a></li> -<li><a href="#index-Quotation-marks_002c-inserting-761">Quotation marks, inserting</a>: <a href="#Inserting-Quotation-Marks">Inserting Quotation Marks</a></li> -<li><a href="#index-Quotations-476">Quotations</a>: <a href="#quotation">quotation</a></li> -<li><a href="#index-Quote-characters_002c-inserting-657">Quote characters, inserting</a>: <a href="#Inserting-Quote-Characters">Inserting Quote Characters</a></li> -<li><a href="#index-Ragged-left-509">Ragged left</a>: <a href="#flushleft-_0026-flushright">flushleft & flushright</a></li> -<li><a href="#index-Ragged-right-508">Ragged right</a>: <a href="#flushleft-_0026-flushright">flushleft & flushright</a></li> -<li><a href="#index-Raising-and-lowering-sections-295">Raising and lowering sections</a>: <a href="#Raise_002flower-sections">Raise/lower sections</a></li> -<li><a href="#index-Raw-formatter-commands-1008">Raw formatter commands</a>: <a href="#Raw-Formatter-Commands">Raw Formatter Commands</a></li> -<li><a href="#index-RCS-_0024Id-1399">RCS $Id</a>: <a href="#GNU-Sample-Texts">GNU Sample Texts</a></li> -<li><a href="#index-Recommended-names-for-keys-414">Recommended names for keys</a>: <a href="#key">key</a></li> -<li><a href="#index-Rectangle_002c-black-in-hardcopy-1169">Rectangle, black in hardcopy</a>: <a href="#Overfull-hboxes">Overfull hboxes</a></li> -<li><a href="#index-Recursion_002c-mutual-1068">Recursion, mutual</a>: <a href="#Defining-Macros">Defining Macros</a></li> -<li><a href="#index-Recursive-macro-invocations-1073">Recursive macro invocations</a>: <a href="#Defining-Macros">Defining Macros</a></li> -<li><a href="#index-Reducing-font-size-454">Reducing font size</a>: <a href="#Fonts">Fonts</a></li> -<li><a href="#index-Reference-to-_0040_0040_002dcommands-1384">Reference to @-commands</a>: <a href="#Command-List">Command List</a></li> -<li><a href="#index-References-365">References</a>: <a href="#Cross-References">Cross References</a></li> -<li><a href="#index-References-using-_0040code_007b_0040_0040inforef_007d-384">References using <code>@inforef</code></a>: <a href="#inforef">inforef</a></li> -<li><a href="#index-References-using-_0040code_007b_0040_0040pxref_007d-380">References using <code>@pxref</code></a>: <a href="#pxref">pxref</a></li> -<li><a href="#index-References-using-_0040code_007b_0040_0040ref_007d-375">References using <code>@ref</code></a>: <a href="#ref">ref</a></li> -<li><a href="#index-References-using-_0040code_007b_0040_0040xref_007d-371">References using <code>@xref</code></a>: <a href="#xref">xref</a></li> -<li><a href="#index-Referring-to-other-Info-files-358">Referring to other Info files</a>: <a href="#Other-Info-Files">Other Info Files</a></li> -<li><a href="#index-Region-formatting-and-printing-147">Region formatting and printing</a>: <a href="#Printing">Printing</a></li> -<li><a href="#index-Region-printing-in-Texinfo-mode-1134">Region printing in Texinfo mode</a>: <a href="#Texinfo-Mode-Printing">Texinfo Mode Printing</a></li> -<li><a href="#index-Registered-symbol-839">Registered symbol</a>: <a href="#registered-symbol">registered symbol</a></li> -<li><a href="#index-Reid_002c-Brian-86">Reid, Brian</a>: <a href="#History">History</a></li> -<li><a href="#index-Repeated-and-optional-arguments-946">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-71">Required in Texinfo file</a>: <a href="#Minimum">Minimum</a></li> -<li><a href="#index-Requirements-for-formatting-1141">Requirements for formatting</a>: <a href="#Requirements-Summary">Requirements Summary</a></li> -<li><a href="#index-Requirements-for-include-files-1416">Requirements for include files</a>: <a href="#Include-Files-Requirements">Include Files Requirements</a></li> -<li><a href="#index-Requirements-for-updating-commands-135">Requirements for updating commands</a>: <a href="#Updating-Requirements">Updating Requirements</a></li> -<li><a href="#index-Reserved-words_002c-indicating-403">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-871">Result of an expression</a>: <a href="#result">result</a></li> -<li><a href="#index-ridt_002eeps-607"><code>ridt.eps</code></a>: <a href="#Image-Scaling">Image Scaling</a></li> -<li><a href="#index-Right-quotation-marks-777">Right quotation marks</a>: <a href="#Inserting-Quotation-Marks">Inserting Quotation Marks</a></li> -<li><a href="#index-Right_002dpointing-angle-quotation-marks-804">Right-pointing angle quotation marks</a>: <a href="#Inserting-Quotation-Marks">Inserting Quotation Marks</a></li> -<li><a href="#index-Ring-accent-706">Ring accent</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-Roman-font-463">Roman font</a>: <a href="#Fonts">Fonts</a></li> -<li><a href="#index-Romance-ordinals-747">Romance ordinals</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-Rounded-rectangles_002c-around-examples-520">Rounded rectangles, around examples</a>: <a href="#cartouche">cartouche</a></li> -<li><a href="#index-Rows_002c-of-a-multitable-551">Rows, of a multitable</a>: <a href="#Multitable-Rows">Multitable Rows</a></li> -<li><a href="#index-Running-an-Info-formatter-141">Running an Info formatter</a>: <a href="#Info-Formatting">Info Formatting</a></li> -<li><a href="#index-Running-_0040code_007bInfo_002dvalidate_007d-1468">Running <code>Info-validate</code></a>: <a href="#Using-Info_002dvalidate">Using Info-validate</a></li> -<li><a href="#index-Running-macros-1080">Running macros</a>: <a href="#Invoking-Macros">Invoking Macros</a></li> -<li><a href="#index-Running-_0040code_007bmakeinfo_007d-in-Emacs-1282">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-1417">Sample <code>@include</code> file</a>: <a href="#Sample-Include-File">Sample Include File</a></li> -<li><a href="#index-Sample-function-definition-990">Sample function definition</a>: <a href="#Sample-Function-Definition">Sample Function Definition</a></li> -<li><a href="#index-Sample-Texinfo-file_002c-no-comments-1393">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-74">Sample Texinfo file, with comments</a>: <a href="#Short-Sample">Short Sample</a></li> -<li><a href="#index-Sample-Texinfo-files-1392">Sample Texinfo files</a>: <a href="#Sample-Texinfo-Files">Sample Texinfo Files</a></li> -<li><a href="#index-Sample-texts_002c-GNU-1395">Sample texts, GNU</a>: <a href="#GNU-Sample-Texts">GNU Sample Texts</a></li> -<li><a href="#index-Sans-serif-font-466">Sans serif font</a>: <a href="#Fonts">Fonts</a></li> -<li><a href="#index-Scaled-points-606">Scaled points</a>: <a href="#Image-Scaling">Image Scaling</a></li> -<li><a href="#index-Scaling-images-592">Scaling images</a>: <a href="#Image-Scaling">Image Scaling</a></li> -<li><a href="#index-Schwab_002c-Andreas-83">Schwab, Andreas</a>: <a href="#History">History</a></li> -<li><a href="#index-Scribe-85">Scribe</a>: <a href="#History">History</a></li> -<li><a href="#index-Sea-surges-378">Sea surges</a>: <a href="#ref">ref</a></li> -<li><a href="#index-Section-structure-of-a-file_002c-showing-it-115">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-297">Sections, raising and lowering</a>: <a href="#Raise_002flower-sections">Raise/lower sections</a></li> -<li><a href="#index-Sentence-ending-punctuation-665">Sentence ending punctuation</a>: <a href="#Ending-a-Sentence">Ending a Sentence</a></li> -<li><a href="#index-Sentence-non_002dending-punctuation-661">Sentence non-ending punctuation</a>: <a href="#Not-Ending-a-Sentence">Not Ending a Sentence</a></li> -<li><a href="#index-Sentences_002c-spacing-after-677">Sentences, spacing after</a>: <a href="#frenchspacing">frenchspacing</a></li> -<li><a href="#index-g_t_0040samp_007b_0040r_007bSeparate_007d_007d-footnote-style-612">‘<samp><span class="samp">Separate</span></samp>’ footnote style</a>: <a href="#Footnote-Styles">Footnote Styles</a></li> -<li><a href="#index-Sequence-of-clicks-863">Sequence of clicks</a>: <a href="#Click-Sequences">Click Sequences</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-758">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-1104">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-1126">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-1131">Shell, format, print from</a>: <a href="#Within-Emacs">Within Emacs</a></li> -<li><a href="#index-Shell_002c-running-_0040code_007bmakeinfo_007d-in-1284">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-569">Short captions, for lists of floats</a>: <a href="#caption-shortcaption">caption shortcaption</a></li> -<li><a href="#index-Short-table-of-contents-214">Short table of contents</a>: <a href="#Contents">Contents</a></li> -<li><a href="#index-Showing-the-section-structure-of-a-file-114">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-1458">Showing the structure of a file</a>: <a href="#Using-texinfo_002dshow_002dstructure">Using texinfo-show-structure</a></li> -<li><a href="#index-Shrubbery-1029">Shrubbery</a>: <a href="#ifset-ifclear">ifset ifclear</a></li> -<li><a href="#index-Single-angle-quotation-marks-802">Single angle quotation marks</a>: <a href="#Inserting-Quotation-Marks">Inserting Quotation Marks</a></li> -<li><a href="#index-Single-guillemets-800">Single guillemets</a>: <a href="#Inserting-Quotation-Marks">Inserting Quotation Marks</a></li> -<li><a href="#index-Single-left_002dpointing-angle-quotation-mark-807">Single left-pointing angle quotation mark</a>: <a href="#Inserting-Quotation-Marks">Inserting Quotation Marks</a></li> -<li><a href="#index-Single-low_002d9-quotation-mark-787">Single low-9 quotation mark</a>: <a href="#Inserting-Quotation-Marks">Inserting Quotation Marks</a></li> -<li><a href="#index-Single-quotation-marks-774">Single quotation marks</a>: <a href="#Inserting-Quotation-Marks">Inserting Quotation Marks</a></li> -<li><a href="#index-Single-right_002dpointing-angle-quotation-mark-808">Single right-pointing angle quotation mark</a>: <a href="#Inserting-Quotation-Marks">Inserting Quotation Marks</a></li> -<li><a href="#index-Site_002dwide-Texinfo-configuration-file-1158">Site-wide Texinfo configuration file</a>: <a href="#Preparing-for-TeX">Preparing for TeX</a></li> -<li><a href="#index-Size-of-printed-book-1177">Size of printed book</a>: <a href="#smallbook">smallbook</a></li> -<li><a href="#index-Slanted-font-468">Slanted font</a>: <a href="#Fonts">Fonts</a></li> -<li><a href="#index-Slanted-typewriter-font_002c-for-_0040code_007b_0040_0040kbd_007d-408">Slanted typewriter font, for <code>@kbd</code></a>: <a href="#kbd">kbd</a></li> -<li><a href="#index-Small-book-size-1174">Small book size</a>: <a href="#smallbook">smallbook</a></li> -<li><a href="#index-Small-caps-font-448">Small caps font</a>: <a href="#Smallcaps">Smallcaps</a></li> -<li><a href="#index-Small-examples-492">Small examples</a>: <a href="#small">small</a></li> -<li><a href="#index-Small-verbatim-486">Small verbatim</a>: <a href="#verbatim">verbatim</a></li> -<li><a href="#index-Smaller-fonts-455">Smaller fonts</a>: <a href="#Fonts">Fonts</a></li> -<li><a href="#index-Software-copying-permissions-254">Software copying permissions</a>: <a href="#Software-Copying-Permissions">Software Copying Permissions</a></li> -<li><a href="#index-Sorting-indices-1100">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-after-sentences-678">Space, after sentences</a>: <a href="#frenchspacing">frenchspacing</a></li> -<li><a href="#index-Space_002c-inserting-horizontal-671">Space, inserting horizontal</a>: <a href="#Multiple-Spaces">Multiple Spaces</a></li> -<li><a href="#index-Space_002c-inserting-vertical-923">Space, inserting vertical</a>: <a href="#sp">sp</a></li> -<li><a href="#index-Spaces-in-macros-1071">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-346">Spaces, in menus</a>: <a href="#Writing-a-Menu">Writing a Menu</a></li> -<li><a href="#index-Spacing_002c-inserting-659">Spacing, inserting</a>: <a href="#Inserting-Space">Inserting Space</a></li> -<li><a href="#index-Special-characters_002c-inserting-647">Special characters, inserting</a>: <a href="#Atsign-Braces-Comma">Atsign Braces Comma</a></li> -<li><a href="#index-Special-displays-557">Special displays</a>: <a href="#Special-Displays">Special Displays</a></li> -<li><a href="#index-Special-insertions-646">Special insertions</a>: <a href="#Insertions">Insertions</a></li> -<li><a href="#index-Special-typesetting-commands-824">Special typesetting commands</a>: <a href="#Dots-Bullets">Dots Bullets</a></li> -<li><a href="#index-Specifying-index-entries-626">Specifying index entries</a>: <a href="#Indexing-Commands">Indexing Commands</a></li> -<li><a href="#index-Split-HTML-output-1360">Split HTML output</a>: <a href="#HTML-Splitting">HTML Splitting</a></li> -<li><a href="#index-Splitting-an-Info-file-manually-1475">Splitting an Info file manually</a>: <a href="#Splitting">Splitting</a></li> -<li><a href="#index-Splitting-of-output-files-1258">Splitting of output files</a>: <a href="#makeinfo-options">makeinfo options</a></li> -<li><a href="#index-g_t_0040ss_007b_007d-756">ß</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-Stallman_002c-Richard-M_002e-75">Stallman, Richard M.</a>: <a href="#History">History</a></li> -<li><a href="#index-Start-of-header-line-163">Start of header line</a>: <a href="#Start-of-Header">Start of Header</a></li> -<li><a href="#index-Starting-chapters-238">Starting chapters</a>: <a href="#setchapternewpage">setchapternewpage</a></li> -<li><a href="#index-Structure-of-a-file_002c-showing-it-116">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-1447">Structure, catching mistakes in</a>: <a href="#Catching-Mistakes">Catching Mistakes</a></li> -<li><a href="#index-Structuring-of-chapters-270">Structuring of chapters</a>: <a href="#Structuring">Structuring</a></li> -<li><a href="#index-Styles_002c-font-457">Styles, font</a>: <a href="#Fonts">Fonts</a></li> -<li><a href="#index-Subsection_002dlike-commands-284">Subsection-like commands</a>: <a href="#unnumberedsubsec-appendixsubsec-subheading">unnumberedsubsec appendixsubsec subheading</a></li> -<li><a href="#index-Subsub-commands-288">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-234">Summary of document</a>: <a href="#documentdescription">documentdescription</a></li> -<li><a href="#index-Suppressing-first-paragraph-indentation-245">Suppressing first paragraph indentation</a>: <a href="#firstparagraphindent">firstparagraphindent</a></li> -<li><a href="#index-Suppressing-indentation-511">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-400">Syntactic tokens, indicating</a>: <a href="#code">code</a></li> -<li><a href="#index-Syntax_002c-of-_0040_0040_002dcommands-1386">Syntax, of @-commands</a>: <a href="#Command-Syntax">Command Syntax</a></li> -<li><a href="#index-Syntax_002c-optional-_0026-repeated-arguments-948">Syntax, optional & repeated arguments</a>: <a href="#Optional-Arguments">Optional Arguments</a></li> -<li><a href="#index-Table-of-contents-212">Table of contents</a>: <a href="#Contents">Contents</a></li> -<li><a href="#index-Table-of-contents_002c-after-title-page-221">Table of contents, after title page</a>: <a href="#Contents">Contents</a></li> -<li><a href="#index-Table-of-contents_002c-for-floats-573">Table of contents, for floats</a>: <a href="#listoffloats">listoffloats</a></li> -<li><a href="#index-Tables-and-lists_002c-making-523">Tables and lists, making</a>: <a href="#Lists-and-Tables">Lists and Tables</a></li> -<li><a href="#index-Tables-with-indexes-536">Tables with indexes</a>: <a href="#ftable-vtable">ftable vtable</a></li> -<li><a href="#index-Tables_002c-making-multi_002dcolumn-542">Tables, making multi-column</a>: <a href="#Multi_002dcolumn-Tables">Multi-column Tables</a></li> -<li><a href="#index-Tables_002c-making-two_002dcolumn-531">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-62">Tabs; don't use!</a>: <a href="#Conventions">Conventions</a></li> -<li><a href="#index-Tag-table_002c-making-automatically-1297">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-1474">Tag table, making manually</a>: <a href="#Unsplit">Unsplit</a></li> -<li><a href="#index-Targets-for-cross_002dreferences_002c-arbitrary-337">Targets for cross-references, arbitrary</a>: <a href="#anchor">anchor</a></li> -<li><a href="#index-Template-for-a-definition-936">Template for a definition</a>: <a href="#Def-Cmd-Template">Def Cmd Template</a></li> -<li><a href="#index-g_t_0040TeX_007b_007d-commands_002c-using-ordinary-1009">TeX commands, using ordinary</a>: <a href="#Raw-Formatter-Commands">Raw Formatter Commands</a></li> -<li><a href="#index-g_t_0040TeX_007b_007d-index-sorting-1102">TeX index sorting</a>: <a href="#Hardcopy">Hardcopy</a></li> -<li><a href="#index-g_t_0040TeX_007b_007d-input-initialization-1145">TeX input initialization</a>: <a href="#Preparing-for-TeX">Preparing for TeX</a></li> -<li><a href="#index-g_t_0040TeX_007b_007d-logo-834">TeX logo</a>: <a href="#tex">tex</a></li> -<li><a href="#index-g_t_0040TeX_007b_007d_002c-how-to-obtain-1204">TeX, how to obtain</a>: <a href="#Obtaining-TeX">Obtaining TeX</a></li> -<li><a href="#index-texi2dvi-1112"><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-1117"><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-1477"><code>texi2roff</code><span class="roman">, unsupported software</span></a>: <a href="#Footnotes">Footnotes</a></li> -<li><a href="#index-texindex-1107"><code>texindex</code></a>: <a href="#Format-with-tex_002ftexindex">Format with tex/texindex</a></li> -<li><a href="#index-texindex-1103"><code>texindex</code></a>: <a href="#Hardcopy">Hardcopy</a></li> -<li><a href="#index-Texinfo-commands_002c-defining-new-1059">Texinfo commands, defining new</a>: <a href="#Defining-New-Texinfo-Commands">Defining New Texinfo Commands</a></li> -<li><a href="#index-Texinfo-file-beginning-154">Texinfo file beginning</a>: <a href="#Beginning-a-File">Beginning a File</a></li> -<li><a href="#index-Texinfo-file-ending-260">Texinfo file ending</a>: <a href="#Ending-a-File">Ending a File</a></li> -<li><a href="#index-Texinfo-file-header-159">Texinfo file header</a>: <a href="#Texinfo-File-Header">Texinfo File Header</a></li> -<li><a href="#index-Texinfo-file-minimum-72">Texinfo file minimum</a>: <a href="#Minimum">Minimum</a></li> -<li><a href="#index-Texinfo-file-section-structure_002c-showing-it-120">Texinfo file section structure, showing it</a>: <a href="#Showing-the-Structure">Showing the Structure</a></li> -<li><a href="#index-Texinfo-history-88">Texinfo history</a>: <a href="#History">History</a></li> -<li><a href="#index-Texinfo-mode-91">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-165">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-171"><code>texinfo.cnf</code></a>: <a href="#setfilename">setfilename</a></li> -<li><a href="#index-texinfo_002ecnf-_0040r_007binstallation_007d-1156"><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-1149"><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-1276"><code>TEXINFO_OUTPUT_FORMAT</code></a>: <a href="#makeinfo-options">makeinfo options</a></li> -<li><a href="#index-TEXINPUTS-1160"><code>TEXINPUTS</code></a>: <a href="#Preparing-for-TeX">Preparing for TeX</a></li> -<li><a href="#index-Text-width-and-height-1188">Text width and height</a>: <a href="#pagesizes">pagesizes</a></li> -<li><a href="#index-Text_002c-conditionally-visible-993">Text, conditionally visible</a>: <a href="#Conditionals">Conditionals</a></li> -<li><a href="#index-Text_002c-marking-up-396">Text, marking up</a>: <a href="#Marking-Text">Marking Text</a></li> -<li><a href="#index-Thin-space-between-number_002c-dimension-679">Thin space between number, dimension</a>: <a href="#dmn">dmn</a></li> -<li><a href="#index-Tie_002dafter-accent-708">Tie-after accent</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-Tied-space-919">Tied space</a>: <a href="#tie">tie</a></li> -<li><a href="#index-Tilde-accent-698">Tilde accent</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-time_002dstamp_002eel-1405"><code>time-stamp.el</code></a>: <a href="#GNU-Sample-Texts">GNU Sample Texts</a></li> -<li><a href="#index-Tips-1389">Tips</a>: <a href="#Tips">Tips</a></li> -<li><a href="#index-Title-page-190">Title page</a>: <a href="#titlepage">titlepage</a></li> -<li><a href="#index-Title-page_002c-bastard-195">Title page, bastard</a>: <a href="#titlepage">titlepage</a></li> -<li><a href="#index-Title-page_002c-for-plain-text-188">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-209">Titlepage end starts headings</a>: <a href="#end-titlepage">end titlepage</a></li> -<li><a href="#index-Top-node-222">Top node</a>: <a href="#The-Top-Node">The Top Node</a></li> -<li><a href="#index-Top-node-example-225">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-g_t_0040samp_007b_0040r_007bTop_007d_007d-node-naming-for-references-373">‘<samp><span class="samp">Top</span></samp>’ node naming for references</a>: <a href="#Top-Node-Naming">Top Node Naming</a></li> -<li><a href="#index-g_t_0040code_007btp_007d-_0028data-type_0029-index-621"><code>tp</code> (data type) index</a>: <a href="#Predefined-Indices">Predefined Indices</a></li> -<li><a href="#index-Transliteration-of-8_002dbit-characters-in-HTML-cross_002dreferences-1378">Transliteration 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-Tree-structuring-271">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-951">Two `First' Lines for <code>@deffn</code></a>: <a href="#deffnx">deffnx</a></li> -<li><a href="#index-Two-letter-names-for-indices-635">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-540">Two named items for <code>@table</code></a>: <a href="#itemx">itemx</a></li> -<li><a href="#index-Two-part-menu-entry-351">Two part menu entry</a>: <a href="#Less-Cluttered-Menu-Entry">Less Cluttered Menu Entry</a></li> -<li><a href="#index-g_t_0040file_007btxi_002d_0040var_007bcc_007d_002etex_007d-1039"><samp><span class="file">txi-</span><var>cc</var><span class="file">.tex</span></samp></a>: <a href="#documentlanguage">documentlanguage</a></li> -<li><a href="#index-Typesetting-commands-for-dots_002c-etc_002e-825">Typesetting commands for dots, etc.</a>: <a href="#Dots-Bullets">Dots Bullets</a></li> -<li><a href="#index-Typewriter-font-473">Typewriter font</a>: <a href="#Fonts">Fonts</a></li> -<li><a href="#index-Ugly-black-rectangles-in-hardcopy-1171">Ugly black rectangles in hardcopy</a>: <a href="#Overfull-hboxes">Overfull hboxes</a></li> -<li><a href="#index-Umlaut-accent-688">Umlaut accent</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-Unbreakable-space_002c-fixed-913">Unbreakable space, fixed</a>: <a href="#w">w</a></li> -<li><a href="#index-Unbreakable-space_002c-variable-921">Unbreakable space, variable</a>: <a href="#tie">tie</a></li> -<li><a href="#index-Uncluttered-menu-entry-355">Uncluttered menu entry</a>: <a href="#Less-Cluttered-Menu-Entry">Less Cluttered Menu Entry</a></li> -<li><a href="#index-Undefining-macros-1077">Undefining macros</a>: <a href="#Defining-Macros">Defining Macros</a></li> -<li><a href="#index-Underbar-accent-712">Underbar accent</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-Underdot-accent-714">Underdot accent</a>: <a href="#Inserting-Accents">Inserting Accents</a></li> -<li><a href="#index-Underscore_002c-breakpoint-within-_0040code_007b_0040_0040code_007d-909">Underscore, breakpoint within <code>@code</code></a>: <a href="#allowcodebreaks">allowcodebreaks</a></li> -<li><a href="#index-Unicode-quotation-characters-763">Unicode quotation characters</a>: <a href="#Inserting-Quotation-Marks">Inserting Quotation Marks</a></li> -<li><a href="#index-Uniform-resource-locator_002c-indicating-440">Uniform resource locator, indicating</a>: <a href="#indicateurl">indicateurl</a></li> -<li><a href="#index-Uniform-resource-locator_002c-referring-to-387">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-563">Unnumbered float, creating</a>: <a href="#float">float</a></li> -<li><a href="#index-Unprocessed-text-67">Unprocessed text</a>: <a href="#Comments">Comments</a></li> -<li><a href="#index-Unsplit-file-creation-1472">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-1403"><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-125">Updating nodes and menus</a>: <a href="#Updating-Nodes-and-Menus">Updating Nodes and Menus</a></li> -<li><a href="#index-Updating-requirements-134">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-441">URL, indicating</a>: <a href="#indicateurl">indicateurl</a></li> -<li><a href="#index-URL_002c-referring-to-388">URL, referring to</a>: <a href="#uref">uref</a></li> -<li><a href="#index-Usage-tips-1390">Usage tips</a>: <a href="#Tips">Tips</a></li> -<li><a href="#index-User-input-407">User input</a>: <a href="#kbd">kbd</a></li> -<li><a href="#index-User-options_002c-marking-964">User options, marking</a>: <a href="#Variables-Commands">Variables Commands</a></li> -<li><a href="#index-User_002ddefined-Texinfo-commands-1060">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-UTF_002d8-766">UTF-8</a>: <a href="#Inserting-Quotation-Marks">Inserting Quotation Marks</a></li> -<li><a href="#index-Validating-a-large-file-1470">Validating a large file</a>: <a href="#Using-Info_002dvalidate">Using Info-validate</a></li> -<li><a href="#index-Validation-of-pointers-1279">Validation of pointers</a>: <a href="#Pointer-Validation">Pointer Validation</a></li> -<li><a href="#index-Value-of-an-expression_002c-indicating-874">Value of an expression, indicating</a>: <a href="#result">result</a></li> -<li><a href="#index-Variables_002c-object_002doriented-971">Variables, object-oriented</a>: <a href="#Object_002dOriented-Variables">Object-Oriented Variables</a></li> -<li><a href="#index-Verbatim-copying-license-1408">Verbatim copying license</a>: <a href="#Verbatim-Copying-License">Verbatim Copying License</a></li> -<li><a href="#index-Verbatim-environment-484">Verbatim environment</a>: <a href="#verbatim">verbatim</a></li> -<li><a href="#index-Verbatim-in_002dline-text-421">Verbatim in-line text</a>: <a href="#verb">verb</a></li> -<li><a href="#index-Verbatim_002c-include-file-487">Verbatim, include file</a>: <a href="#verbatiminclude">verbatiminclude</a></li> -<li><a href="#index-Verbatim_002c-small-485">Verbatim, small</a>: <a href="#verbatim">verbatim</a></li> -<li><a href="#index-VERSION-_0040r_007bAutomake-variable_007d-1404"><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-916">Version control keywords, preventing expansion of</a>: <a href="#w">w</a></li> -<li><a href="#index-Version-number_002c-for-install_002dinfo-1355">Version number, for install-info</a>: <a href="#Invoking-install_002dinfo">Invoking install-info</a></li> -<li><a href="#index-Vertically-holding-text-together-930">Vertically holding text together</a>: <a href="#group">group</a></li> -<li><a href="#index-Visibility-of-conditional-text-994">Visibility of conditional text</a>: <a href="#Conditionals">Conditionals</a></li> -<li><a href="#index-g_t_0040code_007bvr_007d-_0028variable_0029-index-622"><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-84">Weinberg, Zack</a>: <a href="#History">History</a></li> -<li><a href="#index-Weisshaus_002c-Melissa-81">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-891">White space, excessive</a>: <a href="#Breaks">Breaks</a></li> -<li><a href="#index-Whitespace-in-macros-1072">Whitespace in macros</a>: <a href="#Defining-Macros">Defining Macros</a></li> -<li><a href="#index-Whitespace_002c-collapsed-around-continuations-943">Whitespace, collapsed around continuations</a>: <a href="#Def-Cmd-Continuation-Lines">Def Cmd Continuation Lines</a></li> -<li><a href="#index-Whitespace_002c-inserting-670">Whitespace, inserting</a>: <a href="#Multiple-Spaces">Multiple Spaces</a></li> -<li><a href="#index-Width-of-images-593">Width of images</a>: <a href="#Image-Scaling">Image Scaling</a></li> -<li><a href="#index-Width-of-text-area-1189">Width of text area</a>: <a href="#pagesizes">pagesizes</a></li> -<li><a href="#index-Widths_002c-defining-multitable-column-546">Widths, defining multitable column</a>: <a href="#Multitable-Column-Widths">Multitable Column Widths</a></li> -<li><a href="#index-Wildcards-1110">Wildcards</a>: <a href="#Format-with-tex_002ftexindex">Format with tex/texindex</a></li> -<li><a href="#index-Words-and-phrases_002c-marking-them-394">Words and phrases, marking them</a>: <a href="#Marking-Text">Marking Text</a></li> -<li><a href="#index-Writing-a-menu-344">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-628">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-1014">XML, including raw</a>: <a href="#Raw-Formatter-Commands">Raw Formatter Commands</a></li> -<li><a href="#index-XPM-image-format-584"><code>XPM image format</code></a>: <a href="#Image-Syntax">Image Syntax</a></li> -<li><a href="#index-Years_002c-in-copyright-line-180">Years, in copyright line</a>: <a href="#copying">copying</a></li> -<li><a href="#index-Zaretskii_002c-Eli-82">Zaretskii, Eli</a>: <a href="#History">History</a></li> -<li><a href="#index-Zuhn_002c-David-D_002e-80">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 ‘<samp><span class="samp">X</span></samp>’ is actually the Greek letter “chi” rather than -the English letter “ex”. Pronounce TeX as if the ‘<samp><span class="samp">X</span></samp>’ were the -last sound in the name `Bach'; but pronounce Texinfo as if the ‘<samp><span class="samp">x</span></samp>’ -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-1477"></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 ‘<samp><span class="samp">;</span></samp>’ character, instead of ‘<samp><span class="samp">:</span></samp>’, 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 <samp><span class="file">.inf</span></samp> extension as well.</p> - - <p class="footnote"><small>[<a name="fn-11" href="#fnd-11">11</a>]</small> Note the -use of ‘<samp><span class="samp">;</span></samp>’ 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> - - <hr></div> - -</body></html> - diff --git a/Master/texmf/doc/texinfo/texinfo.pdf b/Master/texmf/doc/texinfo/texinfo.pdf Binary files differdeleted file mode 100644 index 3a104cd1615..00000000000 --- a/Master/texmf/doc/texinfo/texinfo.pdf +++ /dev/null |